@tribe-nest/forge 3.29.0 → 3.31.0

package/src/ui/media/CallHelpHint.tsx

@@ -0,0 +1,87 @@
+import { useId, useState, type ReactNode } from "react";
+import { HelpCircle } from "lucide-react";
+
+import { useThemeTokens } from "../theme/ForgeThemeProvider";
+
+/**
+ * The `?` that carries an explanation, instead of a paragraph that always shows.
+ *
+ * House design law: if a piece of text exists to EXPLAIN something, it goes
+ * behind a `?`. A call screen is the worst possible place to break that rule,
+ * because it is looked at while something is happening and every sentence that
+ * is not about right now is a sentence in the way.
+ *
+ * ## What is NOT help, and stays visible on this surface
+ *
+ * - the connection state, and what went wrong when it went wrong
+ * - a denied camera or microphone permission
+ * - the recording indicator, which is a consent signal
+ *
+ * ## Why Forge grows its own rather than importing `HelpHint`
+ *
+ * `@tribe-nest/frontend-shared` is not a dependency of this package and cannot
+ * become one: Forge publishes raw source and a creator site installs only
+ * Forge's declared dependencies, so an import of it would resolve here (npm
+ * workspaces symlink everything) and fail on every real site. See
+ * `_tests/publishedResolvability.spec.ts`. This is a disclosure built from a
+ * button and a span, which needs nothing.
+ */
+export type CallHelpHintProps = {
+  /** Accessible name. Say what it explains ("What does sharing send?"), never "help". */
+  label: string;
+  children: ReactNode;
+};
+
+export function CallHelpHint({ label, children }: CallHelpHintProps) {
+  const tokens = useThemeTokens();
+  const [open, setOpen] = useState(false);
+  const panelId = useId();
+
+  return (
+    <span style={{ position: "relative", display: "inline-flex", verticalAlign: "middle" }}>
+      <button
+        type="button"
+        aria-label={label}
+        aria-expanded={open}
+        aria-controls={panelId}
+        onClick={() => setOpen((was) => !was)}
+        style={{
+          display: "inline-flex",
+          alignItems: "center",
+          justifyContent: "center",
+          background: "transparent",
+          border: "none",
+          padding: 0,
+          cursor: "pointer",
+          color: tokens.muted,
+        }}
+      >
+        <HelpCircle width={14} height={14} aria-hidden="true" />
+      </button>
+      {open && (
+        <span
+          id={panelId}
+          role="note"
+          style={{
+            position: "absolute",
+            bottom: "calc(100% + 6px)",
+            left: 0,
+            zIndex: 20,
+            width: "16rem",
+            padding: "0.5rem 0.625rem",
+            borderRadius: tokens.cornerRadius,
+            border: `1px solid ${tokens.border}`,
+            backgroundColor: tokens.surface,
+            color: tokens.text,
+            fontSize: "0.75rem",
+            lineHeight: 1.5,
+            textAlign: "left",
+            fontWeight: 400,
+          }}
+        >
+          {children}
+        </span>
+      )}
+    </span>
+  );
+}

package/src/ui/media/CallStage.tsx

@@ -0,0 +1,542 @@
+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,
+} from "@tribe-nest/media-client/react";
+
+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.
+ *
+ * ## 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 { 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} />}
+          <ConnectionStatus status={status} tokens={tokens} onRetry={retry} />
+        </div>
+      </div>
+
+      <div style={{ display: "flex", alignItems: "center", gap: "0.375rem", fontSize: "0.75rem", color: tokens.muted }}>
+        <span>
+          In this call: {callHeadCount(tiles)}
+        </span>
+        <CallHelpHint label="Why can I hear someone but not see them?">
+          A tile with a name and no picture means that person has their camera off, or the call is busy enough that only
+          the people currently speaking are sent in full. Both are normal, and their audio is unaffected.
+        </CallHelpHint>
+      </div>
+
+      <div
+        style={{
+          display: "grid",
+          gridTemplateColumns: "repeat(auto-fit, minmax(12rem, 1fr))",
+          gap: "0.75rem",
+        }}
+      >
+        <LocalPreview tokens={tokens} aspectRatio={aspectRatio} />
+        {tiles.map((tile) => (
+          <ParticipantTile key={tile.key} tile={tile} tokens={tokens} aspectRatio={aspectRatio} />
+        ))}
+      </div>
+
+      {audioProducerIds.map((producerId) => (
+        <RemoteAudio key={producerId} producerId={producerId} />
+      ))}
+
+      <CallControls tokens={tokens} 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,
+  onRetry,
+}: {
+  status: CallStatus;
+  tokens: ResolvedThemeTokens;
+  onRetry: () => void;
+}) {
+  const busy = status.tone === "connecting" || status.tone === "reconnecting";
+  const alarming = status.tone === "failed";
+
+  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 }}>{status.headline}</span>
+      {status.detail && <span style={{ color: tokens.muted }}>{status.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" />
+          Try again
+        </button>
+      )}
+    </div>
+  );
+}
+
+/** Somebody is recording. A consent signal, so it is content and always shown. */
+function RecordingIndicator({ tokens }: { tokens: ResolvedThemeTokens }) {
+  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" }}
+      />
+      This call is being recorded
+    </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,
+}: {
+  tile: CallTile;
+  tokens: ResolvedThemeTokens;
+  aspectRatio: number;
+}) {
+  // `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 }}> (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 }: { tokens: ResolvedThemeTokens; aspectRatio: number }) {
+  const state = useRoomState();
+  const publications = useLocalPublications();
+  const videoRef = useRef<HTMLVideoElement | null>(null);
+
+  const camera = useMemo(() => publications.find((p) => p.source === "camera"), [publications]);
+  const track = camera?.track;
+
+  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 ? "You" : "You (not connected yet)";
+
+  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>
+  );
+}
+
+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.
+ *
+ * ## 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 or unpublishes 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, onLeave }: { tokens: ResolvedThemeTokens; onLeave?: () => void }) {
+  const grants = useGrants();
+  const { room } = useMediaRoom();
+  const media = useLocalMedia();
+
+  // 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 = () => {
+    void (media.isMicrophoneEnabled ? media.unpublish("microphone") : media.publishMicrophone());
+  };
+  const toggleCamera = () => {
+    void (media.isCameraEnabled ? media.unpublish("camera") : media.publishCamera());
+  };
+  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, media.isMicrophoneEnabled, media.pending.microphone)}
+        >
+          {media.isMicrophoneEnabled ? (
+            <Mic width={16} height={16} aria-hidden="true" />
+          ) : (
+            <MicOff width={16} height={16} aria-hidden="true" />
+          )}
+          {media.isMicrophoneEnabled ? "Mute" : "Unmute"}
+        </button>
+      )}
+
+      {canPublishSource(grants, "camera") && (
+        <button
+          type="button"
+          onClick={toggleCamera}
+          disabled={media.pending.camera}
+          aria-busy={media.pending.camera}
+          style={controlButton(tokens, media.isCameraEnabled, media.pending.camera)}
+        >
+          {media.isCameraEnabled ? (
+            <Video width={16} height={16} aria-hidden="true" />
+          ) : (
+            <VideoOff width={16} height={16} aria-hidden="true" />
+          )}
+          {media.isCameraEnabled ? "Stop camera" : "Start camera"}
+        </button>
+      )}
+
+      {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 ? "Stop sharing" : "Share screen"}
+          </button>
+          <CallHelpHint label="What does sharing my screen send?">
+            Whatever you pick in the browser prompt, live, to everyone in the call. Your camera keeps running alongside
+            it rather than being replaced, so people can still see you while you present.
+          </CallHelpHint>
+        </span>
+      )}
+
+      <button
+        type="button"
+        onClick={leave}
+        style={{ ...controlButton(tokens, false), marginLeft: "auto", borderColor: tokens.secondary }}
+      >
+        <PhoneOff width={16} height={16} aria-hidden="true" />
+        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>
+      )}
+    </div>
+  );
+}