@tribe-nest/forge 3.54.0 → 3.58.0

package/src/ui/media/CallStage.tsx

@@ -17,6 +17,7 @@ import {
 
 import { useForgeT, type ForgeT } from "../../i18n";
 import { useThemeTokens } from "../theme/ForgeThemeProvider";
+import type { CallStageBreakouts } from "./callBreakouts";
 import type { CallStageChat } from "./callChat";
 import {
   callHeadCount,
@@ -24,10 +25,11 @@ import {
   callTiles,
   remoteAudioProducerIds,
   stageNotice,
+  type BreakoutMove,
   type CallTile,
 } from "./callState";
 import { useFlyingReactions, useRaisedHands } from "./hooks/useCallSignals";
-import { CallSidePanel, type SidePanelTab } from "./panels/CallSidePanel";
+import { CallSidePanel, showsRoomsTab, type SidePanelTab } from "./panels/CallSidePanel";
 import { resolveLayout, GALLERY_PAGE_SIZE, pickDominant, type StageLayout, type ViewChoice } from "./stage/callLayout";
 import { diffPeers, unreadCount } from "./stage/callSignals";
 import { createCallSounds } from "./stage/callSounds";
@@ -96,6 +98,12 @@ export type CallStageProps = {
    * how. Absent means no chat tab or button is drawn.
    */
   chat?: CallStageChat;
+  /**
+   * The breakout-rooms adapter, injected like `chat`. Absent means no rooms
+   * tab, no Rooms button and no Return to main: the stage draws exactly what
+   * it drew before rooms existed.
+   */
+  breakouts?: CallStageBreakouts;
   /** Rendering hint for host courtesies (lower-hand). The server enforces
    * every real host action itself. */
   isHost?: boolean;
@@ -161,6 +169,7 @@ export function CallStage({
   aspectRatio = 16 / 9,
   recordingControl,
   chat,
+  breakouts,
   isHost = false,
   mediaDefaults,
   cameraSimulcast = false,
@@ -168,7 +177,7 @@ export function CallStage({
   const themeTokens = useThemeTokens();
   const tokens = useMemo(() => stageTokens(themeTokens), [themeTokens]);
   const t = useForgeT();
-  const { connectionState, error, recovering, retry } = useMediaRoom();
+  const { connectionState, error, recovering, retry, room } = useMediaRoom();
   const state = useRoomState();
   const peers = useParticipants();
   const activeSpeakers = useActiveSpeakers();
@@ -185,9 +194,23 @@ export function CallStage({
 
   const [ui, dispatch] = useReducer(uiReducer, initialUi);
 
+  /**
+   * A breakout move in flight, from either side.
+   *
+   * The node's `moveRequested` lands in `state.moving` (the host sent us
+   * somewhere); a Join or Return the person pressed themselves goes through
+   * `room.moveTo()`, which the SDK reports exactly like a server drain, so the
+   * stage remembers the destination itself in `localMoving` until the room is
+   * back. Both read the same way everywhere below.
+   */
+  const [localMoving, setLocalMoving] = useState<BreakoutMove | null>(null);
+  const [movePending, setMovePending] = useState(false);
+  const [moveError, setMoveError] = useState<string | null>(null);
+  const moving: BreakoutMove | null = state.moving ?? localMoving;
+
   const status = useMemo(
-    () => callStatus({ connectionState, error, recovering, phase: state.phase, closedReason: state.closedReason }),
-    [connectionState, error, recovering, state.phase, state.closedReason],
+    () => callStatus({ connectionState, error, recovering, phase: state.phase, closedReason: state.closedReason, moving }),
+    [connectionState, error, recovering, state.phase, state.closedReason, moving],
   );
 
   // Everyone by name, INCLUDING self as "You" - the peer list is other people
@@ -211,11 +234,54 @@ export function CallStage({
   const remoteCount = useMemo(() => new Set(tiles.map((tile) => tile.identity)).size, [tiles]);
   const everSawPeersRef = useRef(false);
   if (remoteCount > 0) everSawPeersRef.current = true;
+  const breakoutsActive = breakouts?.active ?? false;
   const notice = useMemo(
-    () => stageNotice({ status, remoteCount, everSawPeers: everSawPeersRef.current }),
-    [status, remoteCount],
+    () => stageNotice({ status, remoteCount, everSawPeers: everSawPeersRef.current, moving, breakoutsActive }),
+    [status, remoteCount, moving, breakoutsActive],
+  );
+
+  /**
+   * The self-move: write the assignment, then leave and reconnect. The backend
+   * mints the next ticket for the room the assignment names, so the reconnect
+   * IS the move; captures survive it the way they survive a drain.
+   */
+  const selfMove = useCallback(
+    async (roomPublicId: string | null) => {
+      if (!breakouts || !room) return;
+      setMoveError(null);
+      setMovePending(true);
+      try {
+        await breakouts.moveSelf(roomPublicId);
+        const name = roomPublicId ? (breakouts.rooms.find((r) => r.publicId === roomPublicId)?.name ?? roomPublicId) : null;
+        setLocalMoving({ room: roomPublicId ?? "main", name });
+        await room.moveTo();
+      } catch (cause) {
+        setLocalMoving(null);
+        setMoveError(cause instanceof Error && cause.message ? cause.message : t("forge.call_stage.breakouts.error"));
+      } finally {
+        setMovePending(false);
+      }
+    },
+    [breakouts, room, t],
   );
 
+  // The room is back (or gone): the local destination has been reached or is
+  // moot, and the assignment view is re-read so the panel shows where everyone
+  // landed. Every RETURN to connected refreshes, not only after our own move:
+  // the host may have reassigned us while we were away.
+  const previousConnectionRef = useRef(connectionState);
+  const refreshRef = useRef(breakouts?.refresh);
+  refreshRef.current = breakouts?.refresh;
+  useEffect(() => {
+    const previous = previousConnectionRef.current;
+    previousConnectionRef.current = connectionState;
+    if (connectionState === "connected" && previous !== "connected") {
+      setLocalMoving(null);
+      if (previous !== "idle" && previous !== "connecting") refreshRef.current?.();
+    }
+    if (connectionState === "closed") setLocalMoving(null);
+  }, [connectionState]);
+
   // Dominant speaker with a hold, so the rail and speaker view do not flap.
   const [dominant, setDominant] = useState<{ identity: string | null; since: number }>({ identity: null, since: 0 });
   useEffect(() => {
@@ -308,6 +374,23 @@ export function CallStage({
 
   const togglePanel = (tab: SidePanelTab) => dispatch({ type: "panel", panel: ui.panel === tab ? null : tab });
 
+  // A tab whose content went away (chat never injected, rooms closed under an
+  // attendee) falls back to People rather than drawing an empty rail.
+  const roomsTab = showsRoomsTab(breakouts);
+  const panelTab: SidePanelTab | null =
+    ui.panel === "chat" && !chat ? "people" : ui.panel === "rooms" && !roomsTab ? "people" : ui.panel;
+
+  // An attendee's rooms list is read on demand: once when the tab opens and
+  // then every few seconds while it stays open. The host's adapter polls on
+  // its own, so this only fires for a seat whose adapter does not.
+  const attendeeRoomsOpen = panelTab === "rooms" && !!breakouts && !breakouts.canManage;
+  useEffect(() => {
+    if (!attendeeRoomsOpen) return undefined;
+    refreshRef.current?.();
+    const timer = setInterval(() => refreshRef.current?.(), 5000);
+    return () => clearInterval(timer);
+  }, [attendeeRoomsOpen]);
+
   const showSelfView =
     !ui.selfHidden && layout.mode !== "duo" && connectionState === "connected" && (!notice || notice.kind === "waiting" || notice.kind === "everyone_left");
 
@@ -410,7 +493,7 @@ export function CallStage({
           {ui.panel && narrow && (
             <div data-testid="call-panel-overlay" style={{ position: "absolute", inset: 0, zIndex: 30, display: "flex" }}>
               <CallSidePanel
-                tab={chat ? ui.panel : "people"}
+                tab={panelTab ?? "people"}
                 onTab={(tab) => dispatch({ type: "panel", panel: tab })}
                 onClose={() => dispatch({ type: "panel", panel: null })}
                 tokens={tokens}
@@ -423,6 +506,10 @@ export function CallStage({
                 onLowerHand={hands.lowerHandOf}
                 onLowerAll={hands.lowerAll}
                 unread={chatUnread}
+                breakouts={breakouts}
+                onSelfMove={(id) => void selfMove(id)}
+                movePending={movePending}
+                moveError={moveError}
                 fill
               />
             </div>
@@ -431,7 +518,7 @@ export function CallStage({
 
         {ui.panel && !narrow && (
           <CallSidePanel
-            tab={chat ? ui.panel : "people"}
+            tab={panelTab ?? "people"}
             onTab={(tab) => dispatch({ type: "panel", panel: tab })}
             onClose={() => dispatch({ type: "panel", panel: null })}
             tokens={tokens}
@@ -444,6 +531,10 @@ export function CallStage({
             onLowerHand={hands.lowerHandOf}
             onLowerAll={hands.lowerAll}
             unread={chatUnread}
+            breakouts={breakouts}
+            onSelfMove={(id) => void selfMove(id)}
+            movePending={movePending}
+            moveError={moveError}
           />
         )}
       </div>
@@ -466,8 +557,14 @@ export function CallStage({
         chatUnread={chatUnread}
         onToggleChat={() => togglePanel("chat")}
         onTogglePeople={() => togglePanel("people")}
-        chatOpen={ui.panel === "chat"}
-        peopleOpen={ui.panel === "people"}
+        chatOpen={panelTab === "chat"}
+        peopleOpen={panelTab === "people"}
+        roomsAvailable={roomsTab}
+        roomsOpen={panelTab === "rooms"}
+        onToggleRooms={() => togglePanel("rooms")}
+        inBreakout={!!breakouts?.current}
+        onReturnToMain={() => void selfMove(null)}
+        movePending={movePending}
         onGesture={unlockSounds}
       />
 

package/src/ui/media/_tests/CallBreakoutsPanel.spec.tsx

@@ -0,0 +1,271 @@
+// @vitest-environment jsdom
+import { cleanup, fireEvent, render, waitFor } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { translateForge, type ForgeT } from "../../../i18n";
+import type { CallStageBreakouts } from "../callBreakouts";
+import { CallSidePanel, showsRoomsTab } from "../panels/CallSidePanel";
+import type { StageTokens } from "../stage/stageTheme";
+
+/**
+ * The rooms rail, rendered against a fake adapter.
+ *
+ * Three things are worth being sure about here, and none of them is "did it
+ * render": that a call WITHOUT rooms draws exactly the two tabs it always drew,
+ * that the host's controls reach the adapter with the right arguments (an
+ * assignment sent to the wrong room is silent), and that closing every room
+ * takes a second press.
+ */
+
+afterEach(cleanup);
+
+const tokens: StageTokens = {
+  stageBg: "#0c0d10",
+  stageSurface: "#17181d",
+  stageChrome: "#1e2026",
+  stageText: "#f4f5f7",
+  stageMuted: "#9aa0ab",
+  stageBorder: "#2c2f37",
+  accent: "#0b6",
+  accentText: "#fff",
+  danger: "#c00",
+  cornerRadius: 8,
+};
+
+const t: ForgeT = (key, vars) => translateForge("en", key, vars);
+
+const adapter = (over: Partial<CallStageBreakouts> = {}): CallStageBreakouts => ({
+  ready: true,
+  canManage: false,
+  active: false,
+  current: null,
+  main: { participantCount: 0, participants: [] },
+  rooms: [],
+  pending: false,
+  create: vi.fn(async () => undefined),
+  assign: vi.fn(async () => undefined),
+  moveSelf: vi.fn(async () => undefined),
+  closeAll: vi.fn(async () => undefined),
+  refresh: vi.fn(),
+  ...over,
+});
+
+const ROOMS = [
+  {
+    publicId: "room-1",
+    name: "Room 1",
+    position: 1,
+    participantCount: 1,
+    participants: [{ identity: "anna", name: "Anna" }],
+    assigned: [
+      { identity: "anna", name: "Anna" },
+      { identity: "ben", name: "Ben" },
+    ],
+  },
+  { publicId: "room-2", name: "Room 2", position: 2, participantCount: 0, participants: [], assigned: [] },
+];
+
+const mount = (
+  props: { breakouts?: CallStageBreakouts; tab?: "chat" | "people" | "rooms"; onSelfMove?: (id: string | null) => void } = {},
+) => {
+  const onTab = vi.fn();
+  const utils = render(
+    <CallSidePanel
+      tab={props.tab ?? "rooms"}
+      onTab={onTab}
+      onClose={() => undefined}
+      tokens={tokens}
+      t={t}
+      tiles={[]}
+      hands={[]}
+      isHost={!!props.breakouts?.canManage}
+      myIdentity="host-1"
+      onLowerHand={() => undefined}
+      onLowerAll={() => undefined}
+      unread={0}
+      breakouts={props.breakouts}
+      onSelfMove={props.onSelfMove ?? (() => undefined)}
+      movePending={false}
+      moveError={null}
+    />,
+  );
+  return { ...utils, onTab };
+};
+
+describe("the rooms tab exists only when there is something behind it", () => {
+  it("draws no rooms tab and no rooms panel when the page injected no adapter", () => {
+    const { queryByText, queryByTestId, getByTestId } = mount({ breakouts: undefined, tab: "rooms" });
+    expect(showsRoomsTab(undefined)).toBe(false);
+    expect(queryByText("Rooms")).toBeNull();
+    expect(queryByTestId("call-breakouts-panel")).toBeNull();
+    // A rooms tab asked for with nothing behind it falls back to the roster.
+    expect(getByTestId("call-participants-panel")).toBeTruthy();
+  });
+
+  it("hides the tab from an attendee while no room is open, and shows it once one is", () => {
+    expect(showsRoomsTab(adapter({ canManage: false, active: false }))).toBe(false);
+    expect(showsRoomsTab(adapter({ canManage: false, active: true }))).toBe(true);
+    // The host always has it: that is where rooms get created.
+    expect(showsRoomsTab(adapter({ canManage: true, active: false }))).toBe(true);
+  });
+});
+
+describe("the host's view", () => {
+  it("offers the create form while no room is open and sends count and assignment", async () => {
+    const breakouts = adapter({ canManage: true });
+    const { getByLabelText, getByText, queryByTestId } = mount({ breakouts });
+
+    expect(queryByTestId("breakouts-close-all")).toBeNull();
+    fireEvent.change(getByLabelText("Number of rooms"), { target: { value: "3" } });
+    fireEvent.change(getByLabelText("Assign people"), { target: { value: "manual" } });
+    fireEvent.click(getByText("Create rooms"));
+
+    await waitFor(() => expect(breakouts.create).toHaveBeenCalledWith({ count: 3, assign: "manual" }));
+  });
+
+  it("refuses a count outside 1..20 without asking the server", () => {
+    const breakouts = adapter({ canManage: true });
+    const { getByLabelText, getByText } = mount({ breakouts });
+    fireEvent.change(getByLabelText("Number of rooms"), { target: { value: "21" } });
+    expect((getByText("Create rooms") as HTMLButtonElement).disabled).toBe(true);
+    fireEvent.change(getByLabelText("Number of rooms"), { target: { value: "0" } });
+    expect((getByText("Create rooms") as HTMLButtonElement).disabled).toBe(true);
+    expect(breakouts.create).not.toHaveBeenCalled();
+  });
+
+  it("lists the main room and every room with live counts, arrivals and the people on their way", () => {
+    const breakouts = adapter({
+      canManage: true,
+      active: true,
+      main: { participantCount: 2, participants: [{ identity: "host-1", name: "Host" }, { identity: "carla", name: "Carla" }] },
+      rooms: ROOMS,
+    });
+    const { getByTestId } = mount({ breakouts });
+
+    const main = getByTestId("breakouts-room-main");
+    expect(main.textContent).toContain("Main room");
+    expect(main.textContent).toContain("2 in this room");
+    expect(main.textContent).toContain("Host (you)");
+    expect(main.textContent).toContain("Carla");
+
+    const room1 = getByTestId("breakouts-room-room-1");
+    expect(room1.textContent).toContain("Room 1");
+    expect(room1.textContent).toContain("1 in this room");
+    expect(room1.textContent).toContain("Anna");
+    // Assigned, not yet arrived: listed where they are GOING, and said so.
+    expect(room1.textContent).toContain("Ben (on the way)");
+
+    expect(getByTestId("breakouts-room-room-2").textContent).toContain("Nobody here yet");
+  });
+
+  it("assigns a person through the select beside their name, and never offers one for the host themselves", async () => {
+    const breakouts = adapter({
+      canManage: true,
+      active: true,
+      main: { participantCount: 2, participants: [{ identity: "host-1", name: "Host" }, { identity: "carla", name: "Carla" }] },
+      rooms: ROOMS,
+    });
+    const { getByLabelText, queryByLabelText } = mount({ breakouts });
+
+    fireEvent.change(getByLabelText("Move Carla to a room"), { target: { value: "room-2" } });
+    await waitFor(() => expect(breakouts.assign).toHaveBeenCalledWith("carla", "room-2"));
+
+    // Back to main is `null`, not the empty string the option carries.
+    fireEvent.change(getByLabelText("Move Anna to a room"), { target: { value: "" } });
+    await waitFor(() => expect(breakouts.assign).toHaveBeenCalledWith("anna", null));
+
+    // The host moves themselves with Join, never by reassigning their own row.
+    expect(queryByLabelText("Move Host to a room")).toBeNull();
+  });
+
+  it("joins a room through the stage's self-move, and marks the room the host is in", () => {
+    const onSelfMove = vi.fn();
+    const breakouts = adapter({ canManage: true, active: true, current: { publicId: "room-1", name: "Room 1" }, rooms: ROOMS });
+    const { getByTestId, queryByTestId } = mount({ breakouts, onSelfMove });
+
+    // In Room 1: no Join for it, a marker instead; Join for the other room and
+    // Return to main for the main room.
+    expect(queryByTestId("breakouts-join-room-1")).toBeNull();
+    expect(getByTestId("breakouts-room-room-1").textContent).toContain("You are here");
+
+    fireEvent.click(getByTestId("breakouts-join-room-2"));
+    expect(onSelfMove).toHaveBeenCalledWith("room-2");
+    fireEvent.click(getByTestId("breakouts-join-main"));
+    expect(onSelfMove).toHaveBeenCalledWith(null);
+    // The panel does not touch the adapter for a self-move; the stage does.
+    expect(breakouts.moveSelf).not.toHaveBeenCalled();
+  });
+
+  it("closes every room only after the warning has been confirmed", async () => {
+    const breakouts = adapter({ canManage: true, active: true, rooms: ROOMS });
+    const { getByTestId, getByText, queryByTestId, queryByText } = mount({ breakouts });
+
+    // The warning is not on screen until the control is pressed.
+    expect(queryByText(/Everyone comes back to the main room/)).toBeNull();
+    fireEvent.click(getByTestId("breakouts-close-all"));
+    expect(breakouts.closeAll).not.toHaveBeenCalled();
+    // Visible as content: a warning about what a control is about to do is
+    // never a `?` hint.
+    expect(getByText(/Everyone comes back to the main room/)).toBeTruthy();
+
+    fireEvent.click(getByText("Keep them open"));
+    expect(breakouts.closeAll).not.toHaveBeenCalled();
+    expect(queryByTestId("breakouts-close-confirm")).toBeNull();
+
+    fireEvent.click(getByTestId("breakouts-close-all"));
+    fireEvent.click(getByTestId("breakouts-close-confirm"));
+    await waitFor(() => expect(breakouts.closeAll).toHaveBeenCalledTimes(1));
+  });
+
+  it("shows the server's own sentence when an action is refused", async () => {
+    const breakouts = adapter({
+      canManage: true,
+      create: vi.fn(async () => {
+        throw new Error("Rooms are already open.");
+      }),
+    });
+    const { getByText, getByTestId } = mount({ breakouts });
+    fireEvent.click(getByText("Create rooms"));
+    await waitFor(() => expect(getByTestId("breakouts-error").textContent).toBe("Rooms are already open."));
+  });
+
+  it("keeps the explanation behind a `?` with a name that says what it explains", async () => {
+    const { getByLabelText, queryByText } = mount({ breakouts: adapter({ canManage: true }) });
+    expect(queryByText(/Each room is a separate call/)).toBeNull();
+    fireEvent.click(getByLabelText("What happens when I create rooms?"));
+    await waitFor(() => expect(queryByText(/Each room is a separate call/)).toBeTruthy());
+  });
+});
+
+describe("the attendee's view", () => {
+  it("says where you are, lists the rooms, and offers no host control", () => {
+    const breakouts = adapter({ canManage: false, active: true, current: { publicId: "room-2", name: "Room 2" }, rooms: ROOMS });
+    const { getByTestId, queryByTestId, queryByLabelText, queryByText } = mount({ breakouts });
+
+    expect(getByTestId("breakouts-where").textContent).toBe("You are in Room 2");
+    expect(queryByText("Room 1")).toBeTruthy();
+    expect(queryByText("Main room")).toBeTruthy();
+    expect(queryByTestId("breakouts-close-all")).toBeNull();
+    expect(queryByTestId("breakouts-create")).toBeNull();
+    expect(queryByLabelText(/Move .* to a room/)).toBeNull();
+  });
+
+  it("offers Return to main room only while in a breakout, and routes it through the stage", () => {
+    const onSelfMove = vi.fn();
+    const inRoom = adapter({ canManage: false, active: true, current: { publicId: "room-2", name: "Room 2" }, rooms: ROOMS });
+    const { getByTestId, unmount } = mount({ breakouts: inRoom, onSelfMove });
+    fireEvent.click(getByTestId("breakouts-return-main"));
+    expect(onSelfMove).toHaveBeenCalledWith(null);
+    unmount();
+
+    const inMain = adapter({ canManage: false, active: true, current: null, rooms: ROOMS });
+    const { queryByTestId, getByTestId: get } = mount({ breakouts: inMain });
+    expect(queryByTestId("breakouts-return-main")).toBeNull();
+    expect(get("breakouts-where").textContent).toBe("You are in the main room");
+  });
+
+  it("says it is loading before the first describe has landed", () => {
+    const { getByText } = mount({ breakouts: adapter({ ready: false, active: true }) });
+    expect(getByText("Loading rooms…")).toBeTruthy();
+  });
+});