@tribe-nest/forge 3.29.0 → 3.34.0

package/src/ui/media/CallStage.tsx

@@ -0,0 +1,633 @@
+import { useCallback, useEffect, useMemo, useRef, type CSSProperties, type ReactNode } from "react";
+import {
+  AlertTriangle,
+  Loader2,
+  Mic,
+  MicOff,
+  MonitorUp,
+  MonitorX,
+  PhoneOff,
+  RefreshCw,
+  Video,
+  VideoOff,
+} from "lucide-react";
+
+import {
+  useActiveSpeakers,
+  useGrants,
+  useLocalMedia,
+  useLocalPublications,
+  useMediaRoom,
+  useParticipants,
+  useRecording,
+  useRemoteTrack,
+  useRoomState,
+  useVisibleProducers,
+  type LocalSource,
+} from "@tribe-nest/media-client/react";
+
+import { useForgeT, type ForgeT } from "../../i18n";
+import { useThemeTokens, type ResolvedThemeTokens } from "../theme/ForgeThemeProvider";
+import { CallHelpHint } from "./CallHelpHint";
+import {
+  callHeadCount,
+  callStatus,
+  callTiles,
+  canPublishSource,
+  remoteAudioProducerIds,
+  type CallStatus,
+  type CallTile,
+} from "./callState";
+
+/**
+ * The call, as a screen. One implementation, both surfaces.
+ *
+ * Everything above this file was reachable only from a test: the room, the
+ * hooks and `BookingCallProvider` all existed and nothing rendered a call, so
+ * no human could join one. This is the part that makes it reachable, and it is
+ * built ONCE here because there are two rendering surfaces (admin, and code
+ * websites through Forge) and a second implementation would mean every fix to
+ * the ordering rules had to be made twice. The second copy is always the one
+ * that drifts.
+ *
+ * ## Where the colours come from
+ *
+ * `useThemeTokens()`, which on a code website is the creator's own
+ * `themeSettings` fed through `<ForgeThemeProvider>`, and in admin is the
+ * dashboard's own tokens fed through the same provider. Not one colour is
+ * written down in this file. A call screen with a hard-coded palette is a call
+ * screen that looks like somebody else's product on every site that installs
+ * it.
+ *
+ * ## Where the words come from
+ *
+ * `useForgeT()`, like every other Forge component, with keys under
+ * `forge.call_stage.*`. `callStatus` returns KEYS for the same reason it is
+ * pure: it has no locale. The one thing rendered verbatim is the server's own
+ * sentence (a refusal, a close reason), because a friendlier translation of a
+ * refusal is a lie about why you were refused. Admin renders this same
+ * component inside `<ForgeI18nProvider>` with the dashboard's locale; outside
+ * any provider the hook answers in English, so a site that has not mounted one
+ * still gets a working call.
+ *
+ * ## What it does NOT decide
+ *
+ * Whether a control may be used. `useGrants()` says what the node minted this
+ * token for, and it is read here so a button that would be refused is not
+ * offered; the node checks the same thing on the publish itself and its answer
+ * is the only one that counts. Hiding a control is courtesy, never enforcement.
+ *
+ * ## Mount it behind a Join control
+ *
+ * The provider connects on mount and closes on unmount. Rendering the whole
+ * thing inside a list of sessions would open a media connection for every row.
+ */
+
+export type CallStageProps = {
+  /**
+   * Called once the local participant has left. The host is expected to unmount
+   * the provider: this component closes the room, but a provider left mounted
+   * would reconnect on the next render.
+   */
+  onLeave?: () => void;
+  /** Whose call this is. Rendered above the grid. */
+  title?: ReactNode;
+  /** Ratio for each tile. Defaults to 16 / 9. */
+  aspectRatio?: number;
+};
+
+export function CallStage({ onLeave, title, aspectRatio = 16 / 9 }: CallStageProps) {
+  const tokens = useThemeTokens();
+  const t = useForgeT();
+  const { connectionState, error, recovering, retry } = useMediaRoom();
+  const state = useRoomState();
+  const peers = useParticipants();
+  const activeSpeakers = useActiveSpeakers();
+  const recording = useRecording();
+  /**
+   * The barrier, applied. NOT `state.producers`.
+   *
+   * The reducer keeps every producer the node has ever announced so a subscribe
+   * rule that narrows and later widens is reversible, which means the raw list
+   * can hold people this seat has been barred from seeing. On a sealed room
+   * their presence is most of what the barrier was hiding, and a tile carries
+   * their identity.
+   */
+  const producers = useVisibleProducers();
+
+  const status = useMemo(
+    () => callStatus({ connectionState, error, recovering, phase: state.phase, closedReason: state.closedReason }),
+    [connectionState, error, recovering, state.phase, state.closedReason],
+  );
+
+  // Memoised on the room's own snapshots, every one of which is a stable
+  // reference while nothing changed. Rebuilding these per render is what turns
+  // a call screen into a component that re-renders per FRAME.
+  const tiles = useMemo(
+    () => callTiles({ identity: state.identity, peers, producers, activeSpeakers }),
+    [state.identity, peers, producers, activeSpeakers],
+  );
+  const audioProducerIds = useMemo(
+    () => remoteAudioProducerIds({ identity: state.identity, producers }),
+    [state.identity, producers],
+  );
+
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        gap: "0.75rem",
+        padding: "1rem",
+        borderRadius: tokens.cornerRadius,
+        border: `1px solid ${tokens.border}`,
+        backgroundColor: tokens.background,
+        color: tokens.text,
+        fontFamily: tokens.fontFamily,
+      }}
+    >
+      <div
+        style={{
+          display: "flex",
+          alignItems: "center",
+          justifyContent: "space-between",
+          gap: "0.75rem",
+          flexWrap: "wrap",
+        }}
+      >
+        {title ? <div style={{ fontWeight: 600, fontFamily: tokens.headingFontFamily }}>{title}</div> : <span />}
+        <div style={{ display: "flex", alignItems: "center", gap: "0.75rem" }}>
+          {recording && <RecordingIndicator tokens={tokens} t={t} />}
+          <ConnectionStatus status={status} tokens={tokens} t={t} onRetry={retry} />
+        </div>
+      </div>
+
+      <div style={{ display: "flex", alignItems: "center", gap: "0.375rem", fontSize: "0.75rem", color: tokens.muted }}>
+        <span>{t("forge.call_stage.head_count", { count: callHeadCount(tiles) })}</span>
+        <CallHelpHint label={t("forge.call_stage.help_hear_not_see_label")}>
+          {t("forge.call_stage.help_hear_not_see")}
+        </CallHelpHint>
+      </div>
+
+      <div
+        style={{
+          display: "grid",
+          gridTemplateColumns: "repeat(auto-fit, minmax(12rem, 1fr))",
+          gap: "0.75rem",
+        }}
+      >
+        <LocalPreview tokens={tokens} aspectRatio={aspectRatio} t={t} />
+        {tiles.map((tile) => (
+          <ParticipantTile key={tile.key} tile={tile} tokens={tokens} aspectRatio={aspectRatio} t={t} />
+        ))}
+      </div>
+
+      {audioProducerIds.map((producerId) => (
+        <RemoteAudio key={producerId} producerId={producerId} />
+      ))}
+
+      <CallControls tokens={tokens} t={t} connected={connectionState === "connected"} onLeave={onLeave} />
+    </div>
+  );
+}
+
+/**
+ * The connection, said plainly.
+ *
+ * Four different words for four different situations, because "connecting",
+ * "reconnecting" and "we were refused" call for three different responses and a
+ * single spinner tells you which of them you are in exactly never.
+ */
+function ConnectionStatus({
+  status,
+  tokens,
+  t,
+  onRetry,
+}: {
+  status: CallStatus;
+  tokens: ResolvedThemeTokens;
+  t: ForgeT;
+  onRetry: () => void;
+}) {
+  const busy = status.tone === "connecting" || status.tone === "reconnecting";
+  const alarming = status.tone === "failed";
+  // Our own copy is translated; the server's sentence is shown as it came.
+  const detail = status.detailKey ? t(status.detailKey) : status.detailText;
+
+  return (
+    <div
+      role="status"
+      aria-live="polite"
+      style={{
+        display: "flex",
+        alignItems: "center",
+        gap: "0.5rem",
+        fontSize: "0.8125rem",
+        color: alarming ? tokens.text : tokens.muted,
+      }}
+    >
+      {busy && <Loader2 width={14} height={14} aria-hidden="true" />}
+      {alarming && <AlertTriangle width={14} height={14} aria-hidden="true" color={tokens.secondary} />}
+      {status.tone === "live" && (
+        <span
+          aria-hidden="true"
+          style={{ width: 8, height: 8, borderRadius: 9999, backgroundColor: tokens.primary, display: "inline-block" }}
+        />
+      )}
+      <span style={{ fontWeight: alarming ? 600 : 400 }}>{t(status.headlineKey)}</span>
+      {detail && <span style={{ color: tokens.muted }}>{detail}</span>}
+      {status.canRetry && (
+        <button
+          type="button"
+          onClick={onRetry}
+          style={{
+            display: "inline-flex",
+            alignItems: "center",
+            gap: "0.25rem",
+            border: `1px solid ${tokens.border}`,
+            borderRadius: tokens.cornerRadius,
+            backgroundColor: "transparent",
+            color: tokens.text,
+            padding: "0.125rem 0.5rem",
+            cursor: "pointer",
+            font: "inherit",
+            fontSize: "0.75rem",
+          }}
+        >
+          <RefreshCw width={12} height={12} aria-hidden="true" />
+          {t("forge.call_stage.retry")}
+        </button>
+      )}
+    </div>
+  );
+}
+
+/** Somebody is recording. A consent signal, so it is content and always shown. */
+function RecordingIndicator({ tokens, t }: { tokens: ResolvedThemeTokens; t: ForgeT }) {
+  return (
+    <span
+      style={{
+        display: "inline-flex",
+        alignItems: "center",
+        gap: "0.375rem",
+        fontSize: "0.75rem",
+        fontWeight: 600,
+        color: tokens.text,
+        border: `1px solid ${tokens.border}`,
+        borderRadius: tokens.cornerRadius,
+        padding: "0.125rem 0.5rem",
+      }}
+    >
+      <span
+        aria-hidden="true"
+        style={{ width: 8, height: 8, borderRadius: 9999, backgroundColor: tokens.secondary, display: "inline-block" }}
+      />
+      {t("forge.call_stage.recording")}
+    </span>
+  );
+}
+
+const tileFrame = (tokens: ResolvedThemeTokens, aspectRatio: number, speaking: boolean): CSSProperties => ({
+  position: "relative",
+  overflow: "hidden",
+  aspectRatio: String(aspectRatio),
+  borderRadius: tokens.cornerRadius,
+  backgroundColor: tokens.surface,
+  // The active speaker is shown by the FRAME rather than by re-ordering the
+  // grid: a grid that reshuffles itself every time somebody says "mm" is
+  // unusable, and the person you were looking at moves out from under the eye.
+  border: `2px solid ${speaking ? tokens.primary : tokens.border}`,
+  display: "flex",
+  alignItems: "center",
+  justifyContent: "center",
+});
+
+const tileName = (tokens: ResolvedThemeTokens): CSSProperties => ({
+  position: "absolute",
+  left: "0.5rem",
+  bottom: "0.5rem",
+  maxWidth: "calc(100% - 1rem)",
+  overflow: "hidden",
+  textOverflow: "ellipsis",
+  whiteSpace: "nowrap",
+  fontSize: "0.75rem",
+  padding: "0.125rem 0.375rem",
+  borderRadius: tokens.cornerRadius,
+  backgroundColor: tokens.background,
+  color: tokens.text,
+});
+
+/**
+ * One participant.
+ *
+ * A tile with no video renders the NAME, at size, and keeps its place in the
+ * grid. That is the whole point: somebody with the camera off has not left, and
+ * a grid that drops them re-flows under everyone else's eyes the moment one
+ * person turns a camera off.
+ */
+function ParticipantTile({
+  tile,
+  tokens,
+  aspectRatio,
+  t,
+}: {
+  tile: CallTile;
+  tokens: ResolvedThemeTokens;
+  aspectRatio: number;
+  t: ForgeT;
+}) {
+  // `useRemoteTrack` takes a producer id unconditionally so the hook order is
+  // the same for a tile with video and a tile without. An id that matches
+  // nothing simply returns no track, which is the state we want anyway.
+  const { track, attach } = useRemoteTrack(tile.videoProducerId ?? "");
+  const showVideo = !!tile.videoProducerId && !!track && !tile.videoPaused;
+
+  return (
+    <div
+      style={tileFrame(tokens, aspectRatio, tile.isSpeaking)}
+      data-testid={`tile-${tile.identity}`}
+      // The active set as an attribute as well as a border: a site restyling
+      // the grid needs the fact, and a colour is not something a test can
+      // assert without pinning a palette this component deliberately has none of.
+      data-speaking={tile.isSpeaking ? "true" : "false"}
+    >
+      {showVideo ? (
+        <video ref={attach} autoPlay playsInline muted style={{ width: "100%", height: "100%", objectFit: "cover" }} />
+      ) : (
+        <span
+          style={{
+            fontSize: "0.9375rem",
+            fontWeight: 600,
+            color: tokens.text,
+            padding: "0 0.75rem",
+            textAlign: "center",
+          }}
+        >
+          {tile.name}
+        </span>
+      )}
+      <span style={tileName(tokens)}>
+        {tile.name}
+        {!tile.hasAudio && <span style={{ color: tokens.muted }}> {t("forge.call_stage.listening")}</span>}
+      </span>
+    </div>
+  );
+}
+
+/**
+ * Remote audio, attached and never drawn.
+ *
+ * Audio has to live on an element or the call is silent. It is deliberately NOT
+ * attached to the participant's `<video>`: a tile whose camera is off has no
+ * video element, and hanging the audio off one would mute whoever turned their
+ * camera off.
+ */
+function RemoteAudio({ producerId }: { producerId: string }) {
+  const { attach } = useRemoteTrack(producerId);
+  return <audio ref={attach} autoPlay style={{ display: "none" }} />;
+}
+
+/** This viewer, as they are being sent. Muted, or it is a feedback loop. */
+function LocalPreview({ tokens, aspectRatio, t }: { tokens: ResolvedThemeTokens; aspectRatio: number; t: ForgeT }) {
+  const state = useRoomState();
+  const publications = useLocalPublications();
+  const videoRef = useRef<HTMLVideoElement | null>(null);
+
+  const camera = useMemo(() => publications.find((p) => p.source === "camera"), [publications]);
+  // A paused camera is still captured and still a publication, but nothing is
+  // being sent, so the preview shows the name the others are seeing.
+  const track = camera && !camera.paused ? camera.track : undefined;
+
+  useEffect(() => {
+    const element = videoRef.current;
+    if (!element) return;
+    // Rebuilt only when the TRACK changes. Doing this in a ref callback would
+    // build a new `MediaStream` on every render, which is the per-frame churn
+    // this component exists to avoid.
+    element.srcObject = track ? new MediaStream([track]) : null;
+    return () => {
+      element.srcObject = null;
+    };
+  }, [track]);
+
+  const name = state.identity ? t("forge.call_stage.you") : t("forge.call_stage.you_not_connected");
+
+  return (
+    <div style={tileFrame(tokens, aspectRatio, false)} data-testid="tile-local">
+      {track ? (
+        <video
+          ref={videoRef}
+          autoPlay
+          playsInline
+          muted
+          style={{ width: "100%", height: "100%", objectFit: "cover" }}
+        />
+      ) : (
+        <span style={{ fontSize: "0.9375rem", fontWeight: 600, color: tokens.text }}>{name}</span>
+      )}
+      <span style={tileName(tokens)}>{name}</span>
+    </div>
+  );
+}
+
+/** One sentence per source a drop took away, keyed by the SDK's word for it. */
+const LOST_SOURCE_KEYS: Record<LocalSource, string> = {
+  microphone: "forge.call_stage.lost_microphone",
+  camera: "forge.call_stage.lost_camera",
+  screen: "forge.call_stage.lost_screen",
+};
+
+const controlButton = (tokens: ResolvedThemeTokens, active: boolean, busy = false): CSSProperties => ({
+  display: "inline-flex",
+  alignItems: "center",
+  gap: "0.375rem",
+  padding: "0.5rem 0.75rem",
+  borderRadius: tokens.cornerRadius,
+  border: `1px solid ${active ? tokens.primary : tokens.border}`,
+  backgroundColor: active ? tokens.primary : "transparent",
+  color: active ? tokens.textPrimary : tokens.text,
+  cursor: busy ? "progress" : "pointer",
+  opacity: busy ? 0.6 : 1,
+  font: "inherit",
+  fontSize: "0.8125rem",
+});
+
+/**
+ * Microphone, camera, screen and leave.
+ *
+ * Each toggle is drawn only when the token was minted with the grant for it, so
+ * a listen-only seat is not offered a microphone it would be refused. That is a
+ * rendering decision; the node refuses the publish itself either way.
+ *
+ * ## Mute is a pause, not a republish
+ *
+ * The first press on Unmute or Start camera captures and publishes. Every press
+ * after that PAUSES or RESUMES the publication the room already holds, through
+ * `setPaused`. A toggle built as unpublish-then-publish starts every unmute
+ * with `getUserMedia`, and Safari puts a permission prompt in front of every
+ * call to it, so a person on an iPad was asked whether the site may use the
+ * microphone each time they spoke. Pausing keeps the capture open (the
+ * browser's device indicator stays on, which the camera hint says) and the way
+ * back asks nobody anything. Screen share is the exception: stopping it ends
+ * the capture, because sharing again has to go through the picker anyway.
+ *
+ * ## Why every toggle is disabled while it is working
+ *
+ * Each of these is a read-then-write: it reads whether the source is live and
+ * publishes, pauses or resumes accordingly. The flag it reads does not move
+ * until the publish has resolved, and a publish starts with a permission
+ * prompt that can sit on screen for seconds - so a button that looks untouched
+ * is a button a person presses again, and two presses used to mean two
+ * producers from one identity and everyone else hearing them doubled.
+ * `useLocalMedia` holds the real lock (a synchronous ref, since both clicks
+ * land before React re-renders anything); this is the part that says so on
+ * screen, because a control that silently ignores you is only marginally
+ * better than one that misbehaves.
+ */
+function CallControls({
+  tokens,
+  t,
+  connected,
+  onLeave,
+}: {
+  tokens: ResolvedThemeTokens;
+  t: ForgeT;
+  connected: boolean;
+  onLeave?: () => void;
+}) {
+  const grants = useGrants();
+  const { room } = useMediaRoom();
+  const media = useLocalMedia();
+
+  // What the person is actually SENDING, which is what the button says.
+  const microphoneLive = media.isMicrophoneEnabled && !media.paused.microphone;
+  const cameraLive = media.isCameraEnabled && !media.paused.camera;
+
+  // Plain handlers, deliberately not `useCallback`. `useLocalMedia()` returns a
+  // fresh object every render, so memoising on it would rebuild the callback
+  // every render anyway while looking as though it did not.
+  const toggleMicrophone = () => {
+    if (!media.isMicrophoneEnabled) {
+      void media.publishMicrophone();
+      return;
+    }
+    void media.setPaused("microphone", microphoneLive);
+  };
+  const toggleCamera = () => {
+    if (!media.isCameraEnabled) {
+      void media.publishCamera();
+      return;
+    }
+    void media.setPaused("camera", cameraLive);
+  };
+  const toggleScreen = () => {
+    void (media.screenSharing ? media.unpublish("screen") : media.publishScreen());
+  };
+
+  const leave = useCallback(() => {
+    // Closed here AND unmounted by the host. Closing alone would leave a
+    // provider mounted that reconnects on its next render; unmounting alone
+    // relies on a cleanup running before the person walks away from the laptop.
+    void room?.close().catch(() => undefined);
+    onLeave?.();
+  }, [room, onLeave]);
+
+  return (
+    <div style={{ display: "flex", flexWrap: "wrap", alignItems: "center", gap: "0.5rem" }}>
+      {canPublishSource(grants, "microphone") && (
+        <button
+          type="button"
+          onClick={toggleMicrophone}
+          disabled={media.pending.microphone}
+          aria-busy={media.pending.microphone}
+          style={controlButton(tokens, microphoneLive, media.pending.microphone)}
+        >
+          {microphoneLive ? (
+            <Mic width={16} height={16} aria-hidden="true" />
+          ) : (
+            <MicOff width={16} height={16} aria-hidden="true" />
+          )}
+          {microphoneLive ? t("forge.call_stage.mute") : t("forge.call_stage.unmute")}
+        </button>
+      )}
+
+      {canPublishSource(grants, "camera") && (
+        <span style={{ display: "inline-flex", alignItems: "center", gap: "0.25rem" }}>
+          <button
+            type="button"
+            onClick={toggleCamera}
+            disabled={media.pending.camera}
+            aria-busy={media.pending.camera}
+            style={controlButton(tokens, cameraLive, media.pending.camera)}
+          >
+            {cameraLive ? (
+              <Video width={16} height={16} aria-hidden="true" />
+            ) : (
+              <VideoOff width={16} height={16} aria-hidden="true" />
+            )}
+            {cameraLive ? t("forge.call_stage.camera_stop") : t("forge.call_stage.camera_start")}
+          </button>
+          <CallHelpHint label={t("forge.call_stage.help_camera_stop_label")}>
+            {t("forge.call_stage.help_camera_stop")}
+          </CallHelpHint>
+        </span>
+      )}
+
+      {canPublishSource(grants, "screen") && (
+        <span style={{ display: "inline-flex", alignItems: "center", gap: "0.25rem" }}>
+          <button
+            type="button"
+            onClick={toggleScreen}
+            disabled={media.pending.screen}
+            aria-busy={media.pending.screen}
+            style={controlButton(tokens, media.screenSharing, media.pending.screen)}
+          >
+            {media.screenSharing ? (
+              <MonitorX width={16} height={16} aria-hidden="true" />
+            ) : (
+              <MonitorUp width={16} height={16} aria-hidden="true" />
+            )}
+            {media.screenSharing ? t("forge.call_stage.screen_stop") : t("forge.call_stage.screen_start")}
+          </button>
+          <CallHelpHint label={t("forge.call_stage.help_screen_label")}>
+            {t("forge.call_stage.help_screen")}
+          </CallHelpHint>
+        </span>
+      )}
+
+      <button
+        type="button"
+        onClick={leave}
+        style={{ ...controlButton(tokens, false), marginLeft: "auto", borderColor: tokens.secondary }}
+      >
+        <PhoneOff width={16} height={16} aria-hidden="true" />
+        {t("forge.call_stage.leave")}
+      </button>
+
+      {/* A denied permission prompt is something the person has to be told
+          about without asking, so it stays visible rather than going behind
+          the `?`. */}
+      {media.error && (
+        <span role="alert" style={{ width: "100%", fontSize: "0.8125rem", color: tokens.text }}>
+          {media.error.message}
+        </span>
+      )}
+
+      {/* State the person has to act on, so it is content and stays visible: a
+          drop stopped their capture (the light went out, on purpose), the room
+          is back, and nothing will turn the microphone on again but them. Shown
+          once the room is back rather than during the drop, when the status
+          line above is already saying "reconnecting". An alert rather than a
+          status: somebody who misses it is talking to nobody. */}
+      {connected && media.lostSources.length > 0 && (
+        <span role="alert" style={{ width: "100%", fontSize: "0.8125rem", color: tokens.text }}>
+          {media.lostSources.map((source) => (
+            <span key={source} style={{ display: "block" }}>
+              {t(LOST_SOURCE_KEYS[source])}
+            </span>
+          ))}
+        </span>
+      )}
+    </div>
+  );
+}