FCE-2708 Adds docs for data channels

docs/explanation/data-channels.mdx

@@ -0,0 +1,190 @@
+---
+type: explanation
+sidebar_position: 7
+---
+
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+
+# Data Channels
+
+Data channels allow you to send and receive arbitrary binary data between peers in a room. This is useful for implementing features like text chat, file sharing, game state synchronization, or real-time cursor positions.
+
+## Prerequisites
+
+Before using data channels, you must be [connected to a room](./connecting). Data channels only work after you have successfully joined a room.
+
+## Channel Types
+
+The SDK provides two types of data channels, each optimized for different use cases:
+
+### Reliable Channel
+
+- **Ordered delivery**: Messages arrive in the order they were sent
+- **Guaranteed delivery**: All messages will be delivered, with automatic retransmission if needed
+- **Use cases**: Chat messages, file transfers, commands, or any data that must not be lost
+
+### Lossy Channel
+
+- **Unordered delivery**: Messages may arrive out of order
+- **No retransmission**: Messages may be dropped if the network is congested
+- **Lower latency**: Faster delivery since there's no waiting for retransmissions
+- **Use cases**: Real-time cursor positions, game state updates, live sensor data, or any data where the latest value matters more than every value
+
+## Broadcast Communication
+
+Data channels work in a **broadcast fashion** - when you publish data, it is sent to all other peers in the room. Additionally:
+
+- Messages sent on the **reliable channel** are only received by peers subscribed to the **reliable channel**
+- Messages sent on the **lossy channel** are only received by peers subscribed to the **lossy channel**
+
+This separation allows you to use both channels simultaneously for different purposes without interference.
+
+## Using Data Channels
+
+Use the [`useDataChannel`](../../api/web/functions/useDataChannel) hook to work with data channels. The typical flow is:
+
+1. Initialize the data channel after connecting to a room
+2. Subscribe to incoming messages
+3. Publish messages to other peers
+
+### Example: Simple Chat Messages
+
+<Tabs groupId="platform">
+  <TabItem value="web" label="React (Web)">
+
+```tsx
+import { useConnection, useDataChannel } from "@fishjam-cloud/react-client";
+import { useCallback, useEffect, useState } from "react";
+
+export function useChat() {
+  const { peerStatus } = useConnection();
+  const {
+    initializeDataChannel,
+    publishData,
+    subscribeData,
+    dataChannelReady,
+  } = useDataChannel();
+
+  const [messages, setMessages] = useState<string[]>([]);
+
+  // Step 1: Initialize data channel when connected
+  useEffect(() => {
+    if (peerStatus === "connected") {
+      initializeDataChannel();
+    }
+  }, [peerStatus, initializeDataChannel]);
+
+  // Step 2: Subscribe to incoming messages
+  useEffect(() => {
+    if (!dataChannelReady) return;
+
+    const unsubscribe = subscribeData(
+      (data: Uint8Array) => {
+        const message = new TextDecoder().decode(data);
+        setMessages((prev) => [...prev, message]);
+      },
+      { reliable: true },
+    );
+
+    return unsubscribe;
+  }, [subscribeData, dataChannelReady]);
+
+  // Step 3: Publish messages
+  const sendMessage = useCallback(
+    (text: string) => {
+      if (!dataChannelReady) return;
+
+      const encoded = new TextEncoder().encode(text);
+      publishData(encoded, { reliable: true });
+    },
+    [publishData, dataChannelReady],
+  );
+
+  return { messages, sendMessage, ready: dataChannelReady };
+}
+```
+
+  </TabItem>
+  <TabItem value="mobile" label="React Native (Mobile)" disabled>
+
+Mobile SDK support for data channels will be available in a future release.
+
+  </TabItem>
+</Tabs>
+
+### Example: Using the Lossy Channel
+
+For real-time data where low latency is more important than guaranteed delivery:
+
+<Tabs groupId="platform">
+  <TabItem value="web" label="React (Web)">
+
+```tsx
+import { useConnection, useDataChannel } from "@fishjam-cloud/react-client";
+import { useCallback, useEffect, useState } from "react";
+
+interface CursorPosition {
+  peerId: string;
+  x: number;
+  y: number;
+}
+
+export function useCursorSharing(peerId: string) {
+  const { peerStatus } = useConnection();
+  const {
+    initializeDataChannel,
+    publishData,
+    subscribeData,
+    dataChannelReady,
+  } = useDataChannel();
+
+  const [cursors, setCursors] = useState<Map<string, CursorPosition>>(
+    new Map(),
+  );
+
+  useEffect(() => {
+    if (peerStatus === "connected") {
+      initializeDataChannel();
+    }
+  }, [peerStatus, initializeDataChannel]);
+
+  useEffect(() => {
+    if (!dataChannelReady) return;
+
+    const unsubscribe = subscribeData(
+      (data: Uint8Array) => {
+        const position: CursorPosition = JSON.parse(
+          new TextDecoder().decode(data),
+        );
+        setCursors((prev) => new Map(prev).set(position.peerId, position));
+      },
+      { reliable: false }, // Lossy channel for low latency
+    );
+
+    return unsubscribe;
+  }, [subscribeData, dataChannelReady]);
+
+  const updateCursor = useCallback(
+    (x: number, y: number) => {
+      if (!dataChannelReady) return;
+
+      const encoded = new TextEncoder().encode(
+        JSON.stringify({ peerId, x, y }),
+      );
+      publishData(encoded, { reliable: false });
+    },
+    [publishData, dataChannelReady, peerId],
+  );
+
+  return { cursors, updateCursor, ready: dataChannelReady };
+}
+```
+
+  </TabItem>
+  <TabItem value="mobile" label="React Native (Mobile)" disabled>
+
+Mobile SDK support for data channels will be available in a future release.
+
+  </TabItem>
+</Tabs>

docs/how-to/client/connecting.mdx

@@ -168,5 +168,6 @@ Now that you're connected to a room, you can explore additional features:
 
 - [Start Streaming](./start-streaming) - Enable your camera and microphone
 - [List Other Peers](./list-other-peers) - Display video from other participants
+- [Data Channels](./data-channels) - Send and receive arbitrary data between peers (e.g., text chat)
 - [Picture in Picture](./picture-in-picture) - Allow users to watch video in a floating window (Mobile)
 - [Background Streaming](./background-streaming) - Keep calls active when the app is backgrounded (Mobile)