chat kotlin jetpack compose doc

src/pages/docs/chat/getting-started/android.mdx

@@ -161,6 +161,19 @@ fun ConnectionStatusUi(connection: Connection) {
 ```
 </Code>
 
+<Aside data-type='note'>
+The `collectAsStatus()` extension function returns `State<com.ably.chat.ConnectionStatus>` from the Ably Chat SDK. 
+The `ConnectionStatus` enum includes follwong values:
+* `Initialized` → A temporary state for connection when the client is first initialized.
+* `Connecting` → The client is currently connecting to Ably.
+* `Connected` → The client is currently connected to Ably.
+* `Disconnected` → The client is currently disconnected from Ably, but keeps reconnecting to Ably.
+* `Suspended` → The client is in an extended state of disconnection, but attempts to reconnect every 2 mins (default).
+* `Failed` → The client is currently disconnected from Ably and will not attempt to reconnect. User intervention is required.
+* `Closing` → An explicit request by the developer to close the connection.
+* `Closed` → The connection has been explicitly closed by the client.
+</Aside>
+
 Update the `App` component to display the connection status using the new `ConnectionStatusUi` component:
 
 <Code>
@@ -237,6 +250,11 @@ The above code creates a room with the ID `my-first-room` and sets up a listener
 Monitoring the room status is useful for deciding when to show a loading spinner or other UI elements while waiting for the room to be created or joined.
 </Aside>
 
+<Aside data-type='note'>
+The `collectAsStatus()` extension function for rooms returns `State<com.ably.chat.RoomStatus>` from the Ably Chat SDK. The `RoomStatus` enum includes the following values throughout a room's lifecycle:
+The `RoomStatus` enum includes values such as `Initialized`, `Attaching`, `Attached`, `Detaching`, `Detached`, `Suspended`, `Failed`, `Releasing` and `Released`.
+</Aside>
+
 ## Step 4: Send a message <a id="step-4"/>
 
 Messages are how your clients interact with one another.
@@ -957,6 +975,34 @@ class MainActivity : ComponentActivity() {
 ```
 </Code>
 
+### Room lifecycle management
+
+When managing room lifecycles in your application, keep these best practices in mind:
+
+<Aside data-type='important'>
+**Keep released rooms in memory for status observation**
+
+When you call `chatClient.rooms.release(roomId)`, the room object remains valid and its status changes to `Released`. 
+But it's removed from internal `chatClient.rooms` map, so you have to maintain external map to check released rooms using `collectAsStatus`.
+The `collectAsStatus()` extension function continues to work on released rooms, allowing your UI to observe and display the `Released` state.
+This ensures your UI can properly display the room's `Released` state via `collectAsStatus()` and prevent users from attempting operations on closed rooms.
+</Aside>
+
+**Room state transitions**
+
+Understanding room state transitions helps you build robust chat applications:
+
+* `Initialized` → A temporary state for room when it is first initialized.
+* `Initialized` → `Attaching` → `Attached`: Normal room attachment flow using `room.attach`.
+* `Attached` → `Detaching` → `Detached`: Muting or pausing a room functionality using `room.detach`, so it won't receive any events.
+* `Detached` → `Attaching` → `Attached`: Resuming a muted room using `room.attach`, make sure to fetch missed messages using [history api](/docs/chat/rooms/history?lang=kotlin).
+* `Attached` → `Releasing` → `Released`: Room is detached removing all local resources using `rooms.release` and is garbage collected.
+* `Attached` → `Suspended`: Temporary underlying network disconnection, connection keeps reconnecting every 2 minutes (default is 2 mins).
+* `Suspended` → `Attached`: Automatic reconnection after network recovery, make sure to fetch missed messages using [history api](/docs/chat/rooms/history?lang=kotlin).
+* `Failed` → Represents underlying connection is in `Failed` state.
+
+Use these transitions to provide appropriate UI feedback, such as showing loading indicators during `Attaching` or `Detaching` states, or displaying "Connection lost" messages during `Suspended` state.
+
 ## Next steps <a id="next-steps"/>
 
 Continue to explore the documentation with Kotlin as the selected language: