@naviedu/room-platform-react 0.0.1 → 0.0.4

package/README.md

@@ -0,0 +1,258 @@
+# @naviedu/room-platform-react
+
+Embeddable React UI and runtime for NaviEdu Room Platform rooms. The package
+owns the default room experience, LiveKit connection, media controls, speaker
+requests, private rooms, responsive layout, and optional chat and whiteboard
+surfaces.
+
+## Requirements
+
+- React 18 or 19
+- A Room Platform launch ticket issued by the host backend
+- A public Room Platform API base URL
+- A browser running in a secure context when camera, microphone, or screen
+  sharing is required
+
+The launch ticket is short-lived and must be obtained server-side. Do not put
+backend credentials or long-lived signing secrets in the browser bundle.
+
+## Installation
+
+```bash
+npm install @naviedu/room-platform-react
+```
+
+`react` and `react-dom` are peer dependencies. Room Platform's published
+runtime dependencies are installed automatically with the package.
+
+## Basic usage
+
+Import the package stylesheet once, then render `RoomPlatformRoom` with the
+launch ticket returned by your backend:
+
+```tsx
+'use client'
+
+import { type RoomLaunchTicketRenewalReason, RoomPlatformRoom } from '@naviedu/room-platform-react'
+import '@naviedu/room-platform-react/styles.css'
+
+type RoomTicketResponse = { launchToken: string }
+
+export function Room({ launchToken }: { launchToken: string }) {
+    async function renewLaunchTicket(_reason: RoomLaunchTicketRenewalReason): Promise<RoomTicketResponse> {
+        const response = await fetch('/api/room-platform/launch-ticket', {
+            method: 'POST',
+            credentials: 'include',
+        })
+
+        if (!response.ok) throw new Error('Unable to renew the Room Platform launch ticket')
+
+        return (await response.json()) as RoomTicketResponse
+    }
+
+    return (
+        <RoomPlatformRoom
+            apiBaseUrl="https://api.example.com/room-platform"
+            launchToken={launchToken}
+            onLaunchTicketRequired={renewLaunchTicket}
+            onExit={() => window.history.back()}
+        />
+    )
+}
+```
+
+`apiBaseUrl` is the URL prefix before `/rooms`. The package calls these routes
+relative to it:
+
+- `POST /rooms/exchange`
+- `GET /rooms/:roomId/control-state`
+- `POST /rooms/:roomId/actions`
+
+For example, with `apiBaseUrl="https://api.example.com/room-platform"`, the
+exchange request is sent to
+`https://api.example.com/room-platform/rooms/exchange`.
+
+The package renders a full viewport room (`100dvh`). Mount it in a page or
+layout that allows the room to occupy the viewport.
+
+## `RoomPlatformRoom` props
+
+| Prop                     | Required | Description                                                                          |
+| ------------------------ | -------- | ------------------------------------------------------------------------------------ |
+| `apiBaseUrl`             | Yes      | Room Platform API prefix. Do not append `/rooms`.                                    |
+| `launchToken`            | Yes      | Initial server-issued launch ticket.                                                 |
+| `onLaunchTicketRequired` | Yes      | Returns `{ launchToken }` when the current ticket or access session must be renewed. |
+| `extensions`             | No       | Host-provided top-bar, workspace, sidebar, monitor, and participant extensions.      |
+| `integrations`           | No       | Chat and whiteboard configuration.                                                   |
+| `isPracticeMode`         | No       | Enables practice-room presentation behavior.                                         |
+| `showLocalPreview`       | No       | Shows the local preview in the sidebar. Defaults to `true`.                          |
+| `primaryCameraSelector`  | No       | Selects the primary camera track when the default selection is not suitable.         |
+| `onError`                | No       | Receives connection, media, and action errors.                                       |
+| `onLifecycleEvent`       | No       | Receives exchange, renewal, and reconnect lifecycle events.                          |
+| `onExit`                 | No       | Called when the user chooses to leave the room.                                      |
+| `children`               | No       | Replaces the default workspace while keeping the provider and room runtime.          |
+
+### Error and lifecycle callbacks
+
+```tsx
+<RoomPlatformRoom
+    // ...required props
+    onError={({ error, recoverable, scope }) => {
+        console.error(`[room-platform:${scope}]`, error)
+        if (!recoverable) {
+            // Show the host application's unavailable-room state.
+        }
+    }}
+    onLifecycleEvent={(event) => {
+        // Send telemetry to the host backend if needed.
+        console.info('Room Platform lifecycle:', event)
+    }}
+/>
+```
+
+Lifecycle events are `exchange.succeeded`, `exchange.failed`,
+`renewal.succeeded`, `renewal.failed`, `reconnect.succeeded`, and
+`reconnect.failed`.
+
+## Chat and whiteboard integrations
+
+Integrations are optional. The host supplies already-authorized configuration;
+the room package does not issue chat or whiteboard credentials.
+
+```tsx
+<RoomPlatformRoom
+    // ...required props
+    integrations={{
+        chat: {
+            endpoint: 'https://api.example.com/chat',
+            realtimeEndpoint: 'wss://realtime.example.com/chat',
+            token: chatToken,
+            tokenExpiresAt: chatTokenExpiresAt,
+            refreshToken: refreshChatToken,
+            refreshTokenExpiresAt: refreshChatTokenExpiresAt,
+            rooms: chatRooms,
+            currentRoomId: roomId,
+        },
+        whiteboard: {
+            joinState: whiteboardJoinState,
+            runtime: {
+                realtimeEndpoint: whiteboardRealtimeEndpoint,
+                recoveryPort: whiteboardRecoveryPort,
+            },
+        },
+    }}
+/>
+```
+
+When chat is configured, the default sidebar includes the chat tab and unread
+badge. When whiteboard access is available, a shared screen can display the
+whiteboard surface. Omit either integration when the host does not use it.
+
+## Extensions
+
+Extensions keep host-specific UI outside the shared room implementation. Every
+extension receives `RoomPlatformExtensionProps`:
+
+```tsx
+import type { RoomPlatformExtensionProps } from '@naviedu/room-platform-react'
+
+function HostToolbar({ actions, capabilities, connectionStatus, roomId }: RoomPlatformExtensionProps) {
+    const canModerate = capabilities.includes('room:moderate')
+
+    return (
+        <div>
+            <span>{connectionStatus}</span>
+            <span>{roomId}</span>
+            {canModerate ? (
+                <button type="button" onClick={() => void actions.perform('speak.request')}>
+                    Request to speak
+                </button>
+            ) : null}
+        </div>
+    )
+}
+
+;<RoomPlatformRoom
+    // ...required props
+    extensions={{
+        topBarTrailing: HostToolbar,
+        sidebarTabs: [{ id: 'materials', title: 'Materials', component: HostMaterialsTab }],
+        mainWorkspace: {
+            placement: 'alongside-stage',
+            component: HostWorkspace,
+        },
+    }}
+/>
+```
+
+Available extension slots are:
+
+- `topBarLeading` and `topBarTrailing`
+- `mainWorkspace` with `overlay` or `alongside-stage` placement
+- `sidebarTabs`
+- `participantTab` in `default` or `replace` mode
+- `monitor` with a host-provided participant roster and eligibility flag
+
+`actions.perform` sends a Room Platform action and accepts an optional string
+payload. Check `actions.hasCapability(...)` before rendering privileged
+controls, and use `actions.isPending(...)` to disable controls during an
+in-flight action.
+
+## Advanced composition
+
+Use `RoomPlatformProvider` and `useRoomPlatform` when the host needs to render
+a custom room surface instead of `RoomPlatformRoom`'s default workspace:
+
+```tsx
+import { RoomPlatformProvider, type RoomPlatformProviderProps, useRoomPlatform } from '@naviedu/room-platform-react'
+
+function CustomRoomSurface() {
+    const { localMedia, setLocalMediaEnabled, status } = useRoomPlatform()
+
+    return (
+        <button
+            type="button"
+            disabled={status !== 'connected'}
+            onClick={() => void setLocalMediaEnabled('camera', !localMedia.camera)}
+        >
+            {localMedia.camera ? 'Turn camera off' : 'Turn camera on'}
+        </button>
+    )
+}
+
+export function CustomRoom(props: {
+    apiBaseUrl: string
+    launchToken: string
+    onLaunchTicketRequired: RoomPlatformProviderProps['onLaunchTicketRequired']
+}) {
+    return (
+        <RoomPlatformProvider {...props}>
+            <CustomRoomSurface />
+        </RoomPlatformProvider>
+    )
+}
+```
+
+Use `RoomPlatformRoom` unless a custom surface is required. It composes the
+provider, LiveKit media runtime, private-room runtime, default stage, controls,
+and sidebar for you.
+
+## Publishing and local verification
+
+From the repository root:
+
+```bash
+yarn nx run @naviedu/room-platform-react:build
+```
+
+The publishable package is written to
+`dist/libs/features/room-platform-react`. Inspect it before publishing:
+
+```bash
+cd dist/libs/features/room-platform-react
+npm pack --dry-run
+npm publish --access public
+```
+
+The package embeds the required shared UI source during bundling, so consumers
+do not need private workspace aliases such as `@navi/ui` or `@navi/utils`.