Chat: Update chat docs for single channel changes

content/chat/connect.textile

@@ -144,15 +144,15 @@ If a client briefly loses connection to Ably, for example when driving through a
 During periods of discontinuity greater than 2 minutes then you will need to take steps to recover any missed messages, such as by calling "history":/docs/chat/rooms/history.
 
 blang[javascript,swift,kotlin].
-  Each feature of the Chat SDK provides an @onDiscontinuity()@ handler to assist with this. These methods enable you to register a listener that will be notified when discontinuity occurs in that feature so that you can handle it, as needed.
+  The Chat SDK provides an @onDiscontinuity()@ handler exposed via the Room object to assist with this. This method enables you to register a listener that will be notified when discontinuity occurs in the room so that you can handle it, as needed.
 
 blang[react].
   Any hooks that take an optional listener to monitor their events, such as typing indicator events in the @useTyping@ hook, can also register a listener to be notified of, and handle, periods of discontinuity.
 
 For example, for messages:
 
 ```[javascript]
-const { off } = room.messages.onDiscontinuity((reason?: ErrorInfo) => {
+const { off } = room.onDiscontinuity((reason?: ErrorInfo) => {
   // Recover from the discontinuity
 });
 ```
@@ -173,7 +173,7 @@ const MyComponent = () => {
 ```
 
 ```[swift]
-let subscription = room.messages.onDiscontinuity()
+let subscription = room.onDiscontinuity()
 for await error in subscription {
   print("Recovering from the error: \(error)")
 }
@@ -207,10 +207,4 @@ blang[react,swift].
 blang[react].
 
 blang[javascript,swift,kotlin].
-  The following discontinuity handlers are available:
-
-  * <span lang="javascript">"Messages":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Messages.html#onDiscontinuity</span><span lang="swift">"Messages":https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/messages</span>
-  * <span lang="javascript">"Presence":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Presence.html#onDiscontinuity</span><span lang="swift">"Presence":https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/presence</span>
-  * <span lang="javascript">"Occupancy":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Occupancy.html#onDiscontinuity</span><span lang="swift">"Occupancy":https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/occupancy</span>
-  * <span lang="javascript">"Typing indicators":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Typing.html#onDiscontinuity</span><span lang="swift">"Typing indicators":https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/typing</span>
-  * <span lang="javascript">"Room reactions":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.RoomReactions.html#onDiscontinuity</span><span lang="swift">"Room reactions":https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/roomreactions</span>
+  The discontinuity handler is accessible via the <span lang="javascript">"Room":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Room.html#onDiscontinuity</span><span lang="swift">"Room":https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/room</span> object.

content/chat/rooms/index.textile

@@ -11,31 +11,35 @@ languages:
 
 Rooms are used to organize and logically separate your users and chat messages into 'rooms'. They are the entry object into using chat and provide access to all other chat features, such as messages, online status and typing indicators. A room can represent a 1:1 chat between an agent and a customer, a private message between two users in a chat application, a large group conversation, or the chat section of a livestream with thousands of users.
 
-You also control which features are enabled in a room when you create one. For instance, you might only want to utilize typing indicators in direct messages between users.
+h2(#channel-relationship). Channel <> Room relationship
+
+It is important to note that each room is backed by a single Ably Pub/Sub channel. You may need to be aware of this when using some integrations with Ably, such as the "Pulsar":https://ably.com/docs/integrations/streaming/pulsar#creating-pulsar-rule connectors, or if you are operating in an environment where a Chat SDK is not available.
+The channel name is the same as the room ID with an appended suffix of @::$chat@ (e.g @some-room-id::$chat@). In most cases, you will not need to worry about this, as the Chat SDK handles the channel creation and management for you and capabilities can be configured at the room level.
+
 
 h2(#create). Create or retrieve a room
 
-Users send messages to a room and subscribe to the room in order to receive messages. Other features, such as indicating which users are online, or which users are typing are configured as part of a room's options.
+Users send messages to a room and subscribe to the room in order to receive messages.
 
 blang[javascript,swift,kotlin].
   A @room@ is created, or an existing one is retrieved from the @rooms@ collection using the <span lang="javascript">"@rooms.get()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Rooms.html#get</span><span lang="swift">"@rooms.get()@":https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/rooms/get%28roomid%3Aoptions%3A%29</span><span lang="kotlin">"@rooms.get()@":https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat-android/com.ably.chat/-rooms/get.html</span> method:
 
 blang[react].
   The "@ChatRoomProvider@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/functions/chat-react.ChatRoomProvider.html provides access to a specific chat room to all child components in the component tree.
 
-  Pass in the ID of the room to use, and select which which additional chat features you want enabled for that room. This is configured by passing a "@RoomOptions@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.RoomOptions.html object to the provider.
+  Pass in the ID of the room to use. If you need to provide further feature configuration, such as enabling occupancy messages, you can pass in an optional "@RoomOptions@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.RoomOptions.html object to the provider.
 
   <aside data-type='note'>
   <p>All components that utilize chat feature hooks must be children of a @ChatRoomProvider@. This includes @useRoom@, "@useMessages@":/docs/chat/rooms/messages, "@useOccupancy@":/docs/chat/rooms/occupancy, "@usePresence@":/docs/chat/rooms/presence, "@usePresenceListener@":/docs/chat/rooms/presence, "@useRoomReactions@":/docs/chat/rooms/reactions and "@useTyping@":/docs/chat/rooms/typing.</p>
   </aside>
 
 ```[javascript]
-const room = await chatClient.rooms.get('basketball-stream', AllFeaturesEnabled);
+const room = await chatClient.rooms.get('basketball-stream', {occupancy: {enableEvents: true}});
 ```
 
 ```[react]
 import * as Ably from 'ably';
-import { ChatClientProvider, ChatRoomProvider, LogLevel, AllFeaturesEnabled } from '@ably/chat';
+import { ChatClientProvider, ChatRoomProvider, LogLevel } from '@ably/chat';
 
 const realtimeClient = new Ably.Realtime({ key: '{{API_KEY}}', clientId: 'clientId' });
 const chatClient = new ChatClient(realtimeClient);
@@ -45,7 +49,7 @@ const App = () => {
     <ChatClientProvider client={chatClient}>
       <ChatRoomProvider
         id="my-room-id"
-        options={AllFeaturesEnabled}
+        options={{occupancy: {enableEvents: true}}}
       >
         <RestOfYourApp />
       </ChatRoomProvider>
@@ -55,7 +59,7 @@ const App = () => {
 ```
 
 ```[swift]
-let room = try await chatClient.rooms.get(roomID: "basketball-stream", options: RoomOptions())
+let room = try await chatClient.rooms.get(roomID: "basketball-stream", options: .init(occupancy: .init(enableEvents: true)))
 ```
 
 ```[kotlin]
@@ -70,12 +74,9 @@ blang[react].
   </aside>
 
 blang[javascript,swift,kotlin].
-  When you create or retrieve a room using @rooms.get()@, you need to choose which additional chat features you want enabled for that room. This is configured by passing a <span lang="javascript">"@RoomOptions@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.RoomOptions.html</span><span lang="swift">"@RoomOptions@":https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/roomoptions</span><span lang="kotlin">"@RoomOptions@":https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat-android/com.ably.chat/-room-options/index.html</span> object as the second argument. In addition to setting which features are enabled, @RoomOptions@ also configures the properties of the associated features, such as the timeout period for typing indicators.
+  When you create or retrieve a room using @rooms.get()@, you can provide custom configuration for some features for that room by passing a <span lang="javascript">"@RoomOptions@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.RoomOptions.html</span><span lang="swift">"@RoomOptions@":https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/roomoptions</span><span lang="kotlin">"@RoomOptions@":https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat-android/com.ably.chat/-room-options/index.html</span> object as the second argument. If you do not provide a @RoomOptions@ object, the default settings will be used.
 
   ```[javascript]
-  const presence = {enter: false};
-  const reactions = {};
-  const occupancy = {};
   const typing = {timeoutMs: 5000};
   const room = await chatClient.rooms.get('basketball-stream', {presence, reactions, typing, occupancy});
   ```
@@ -95,31 +96,17 @@ blang[javascript,swift,kotlin].
   val room = chatClient.rooms.get(roomId = "basketball-stream", options = options)
   ```
 
-blang[javascript].
-  You can also use the @AllFeaturesEnabled@ property for each @RoomOption@ to configure whether preconfigured example settings should be used:
-
-  ```[javascript]
-  const room = await chatClient.rooms.get('basketball-stream', {presence: AllFeaturesEnabled.presence});
-  ```
-
-  Or configure each feature using your own values:
-
-  ```[javascript]
-  const room = await chatClient.rooms.get('basketball-stream', {typing: {timeoutMs: 5000}});
-  ```
-
 blang[react,swift,kotlin].
 
-Enable each feature using its associated option. The details of the options available to each feature are documented on their respective pages:
+The details of the options available to each feature are documented on their respective pages:
 
-blang[javascript].
+blang[javascript,swift].
   | Feature | @RoomOption@ | Default settings |
-  | "Presence":/docs/chat/rooms/presence | @presence@ | @AllFeaturesEnabled.presence@ |
-  | "Occupancy":/docs/chat/rooms/occupancy | @occupancy@ | @AllFeaturesEnabled.occupancy@ |
-  | "Typing indicators":/docs/chat/rooms/typing | @typing@ | @AllFeaturesEnabled.typing@ |
-  | "Room reactions":/docs/chat/rooms/reactions | @reactions@ | @AllFeaturesEnabled.reactions@ |
+  | "Presence":/docs/chat/rooms/presence | @presence.enableEvents@ | @true@ |
+  | "Occupancy":/docs/chat/rooms/occupancy | @occupancy.enableEvents@ | @false@ |
+  | "Typing indicators":/docs/chat/rooms/typing | @typing.heartbeatThrottleMs@ | @10000@ |
 
-blang[swift,kotlin].
+blang[kotlin].
   | Feature | @RoomOption@ | Default settings |
   | "Presence":/docs/chat/rooms/presence | @presence@ | @PresenceOptions()@ |
   | "Occupancy":/docs/chat/rooms/occupancy | @occupancy@ | @OccupancyOptions()@ |
@@ -130,7 +117,7 @@ h3(#release). Release a room
 
 Releasing a room allows the underlying resources to be garbage collected or released.
 
-Releasing a room may be optional for many applications. If you have multiple transient rooms, such as in the case of a 1:1 support chat, then it is may be more beneficial.
+Releasing a room may be optional for many applications. If you have multiple transient rooms, such as in the case of a 1:1 support chat, then it may be more beneficial.
 
 blang[javascript,swift,kotlin].
   Once <span lang="javascript">"@rooms.release()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Rooms.html#release</span><span lang="swift">"@rooms.release()@":https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/rooms/release%28roomid%3A%29</span><span lang="kotlin">"@rooms.release()@":https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat-android/com.ably.chat/-rooms/release.html</span> has been called, the room will be unusable and a new instance will need to be created using "@rooms.get()@":#create if you want to reuse it.

content/chat/rooms/occupancy.textile

@@ -12,7 +12,7 @@ languages:
 Occupancy enables you to view the number of users currently online in a room. This feature can be used to display user counts to highlight popular, or trending chat rooms.
 
 <aside data-type='note'>
-<p>Occupancy needs to be "enabled":/docs/chat/rooms#create when creating or retrieving a room.</p>
+<p>Occupancy generates messages on any client entering/leaving a room, and so increases the number of billable messages sent in a room - as such, it is disabled by default and needs to be "enabled":/docs/chat/rooms#create when creating or retrieving a room.</p>
 </aside>
 
 h2(#subscribe). Subscribe to room occupancy

content/chat/rooms/presence.textile

@@ -11,10 +11,6 @@ languages:
 
 Subscribe to the online status of room members using the presence feature. Presence enables you to show which members are currently online, indicate when a user goes offline, and have users optionally set additional information about their profile, or their current status within the application.
 
-<aside data-type='note'>
-<p>Presence needs to be "enabled":/docs/chat/rooms#create when creating or retrieving a room.</p>
-</aside>
-
 h2(#subscribe). Subscribe to presence
 
 blang[javascript,swift,kotlin].
@@ -297,16 +293,10 @@ h2(#options). Presence options
 
 The following options can be set when "creating a room":/docs/chat/rooms#create that are specific to presence:
 
-blang[javascript].
-
-  |_. Property |_. Description |_. Default |
-  | enter | Set whether the client has permissions to enter the presence set. Calling @presence.enter()@ is still required. | true |
-  | subscribe | Set whether the client has permissions to subscribe to the presence set. Calling @presence.subscribe()@ is still required. | true |
-
-blang[react].
+blang[javascript,react].
 
   |_. Property |_. Description |_. Default |
-  | subscribe | Set whether the client has permissions to subscribe to the presence set. Calling @presence.subscribe()@ is still required. | true |
+  | enableEvents | Set whether the client has permissions to subscribe to the presence set. Calling @presence.subscribe()@ is still required. | true |
 
 h2(#retrieve). Retrieve the presence set
 

content/chat/rooms/reactions.textile

@@ -13,10 +13,6 @@ Users can send reactions to the entire chat room to show their sentiment as to w
 
 Room reactions are ephemeral and not stored or aggregated by Ably. The intention being that they show the overall sentiment of a room at a point in time.
 
-<aside data-type='note'>
-<p>Room reactions need to be "enabled":/docs/chat/rooms#create when creating or retrieving a room.</p>
-</aside>
-
 h2(#subscribe). Subscribe to room reactions
 
 blang[javascript,swift,kotlin].

content/chat/rooms/typing.textile

@@ -11,10 +11,6 @@ languages:
 
 Typing indicators enable you to display which users are currently writing a message in a room. This feature can be used to display a message such as __Sandi is typing...__, or when a certain threshold is reached you could instead display __Multiple people are typing...__ or _12 people are typing..._. Typing events are emitted whenever a user starts or stops typing.
 
-<aside data-type='note'>
-<p>Typing indicators need to be "enabled":/docs/chat/rooms#create when creating or retrieving a room.</p>
-</aside>
-
 h2(#subscribe). Subscribe to typing events
 
 blang[javascript,swift,kotlin].

content/chat/setup.textile

@@ -20,7 +20,7 @@ h2(#authentication). Authentication
 An API key is required to authenticate with Ably. API keys are used either to authenticate directly with Ably using basic authentication, or to generate tokens for untrusted clients using "token authentication":/docs/auth/token.
 
 <aside data-type='important'>
-<p>The examples use basic authentication to demonstrate features for convenience. In your own applications, basic authentication should never be used on the client-side as it exposes your Ably API key. Instead use token authentication.</p>
+<p>The examples use basic authentication to demonstrate features for convenience. In your own applications, basic authentication should never be used on the client-side as it exposes your Ably API key. Instead, use token authentication.</p>
 </aside>
 
 "Sign up":https://ably.com/sign-up to Ably to create an API key in the dashboard or use the "Control API":/docs/account/control-api to create an API key programmatically.
@@ -32,12 +32,12 @@ API keys and tokens have a set of "capabilities":/docs/auth/capabilities assigne
 | Message history | Subscribe, History |
 | Online status | Subscribe, Presence |
 | Room occupancy | Subscribe, Channel Metadata |
-| Typing indicators | Publish, Subscribe, Presence |
+| Typing indicators | Publish, Subscribe |
 | Room reactions | Publish, Subscribe |
 
 When setting the capabilities for Chat, you need to apply them to either a wildcard resource, or a wildcard resource prefixed with the chat namespace, for example:
 
-* @[chat]*@ and @*@, or
+* @[chat]*@ or
 * @[*]*@
 
 h2(#install). Install
@@ -53,6 +53,12 @@ blang[javascript,react].
   npm install @ably/chat
   ```
 
+  Currently, React is also required as a peer dependency. This will be removed in a future release.
+
+  ```[sh]
+  npm install react
+  ```
+
   Import the SDKs into your project:
 
   ```[javascript]