@signalcore/ui 0.1.0 → 1.0.0-beta.1

package/src/Modes.tsx

@@ -0,0 +1,112 @@
+import { ChatCircleTextIcon, WaveformIcon, type Icon } from "@phosphor-icons/react";
+import { useEffect, useRef, type KeyboardEvent } from "react";
+
+import { classes } from "./classes";
+
+/** How the person talks to the agent in its space: writing, or on a call. */
+export type SpaceMode = "text" | "voice";
+
+/** The modes' words: the group's name for screen readers, and each mode's. */
+export interface ModeMessages {
+  label: string;
+  text: string;
+  voice: string;
+}
+
+/** The modes' parts, by the class each carries. */
+export type ModePart =
+  "sc-space__modes" | "sc-space__mode" | "sc-space__mode--text" | "sc-space__mode--voice";
+
+const MODES: readonly { mode: SpaceMode; glyph: Icon }[] = [
+  { mode: "text", glyph: ChatCircleTextIcon },
+  { mode: "voice", glyph: WaveformIcon },
+];
+
+/** Where an arrow key moves among the modes, by how many; Home and End go to either end. */
+const STEPS: Readonly<Record<string, number>> = {
+  ArrowRight: 1,
+  ArrowDown: 1,
+  ArrowLeft: -1,
+  ArrowUp: -1,
+};
+
+/**
+ * The two ways to talk, side by side in one small segmented control: a radio group, the mode on
+ * reachable by Tab and the arrows moving to the other and choosing it (Home and End too), each
+ * named by its glyph and its word. `focus` takes the keyboard as it is drawn, for a control drawn
+ * anew after a switch made from it (the chat's and the call's are two).
+ */
+export function Modes({
+  mode,
+  onChange,
+  words,
+  classNames,
+  focus = false,
+}: {
+  mode: SpaceMode;
+  onChange: (mode: SpaceMode) => void;
+  words: ModeMessages;
+  classNames?: Partial<Record<ModePart, string>> | undefined;
+  focus?: boolean | undefined;
+}) {
+  const buttons = useRef<(HTMLButtonElement | null)[]>([]);
+  const on = MODES.findIndex((each) => each.mode === mode);
+
+  useEffect(() => {
+    if (focus) buttons.current[on]?.focus();
+    // Only as it is drawn: a mode chosen later keeps the focus where the keys put it.
+  }, []);
+
+  const onKeyDown = (event: KeyboardEvent<HTMLButtonElement>, index: number) => {
+    const step = STEPS[event.key];
+    const to =
+      event.key === "Home"
+        ? 0
+        : event.key === "End"
+          ? MODES.length - 1
+          : step === undefined
+            ? null
+            : (index + step + MODES.length) % MODES.length;
+    if (to === null) return;
+    event.preventDefault();
+    buttons.current[to]?.focus();
+    const next = MODES[to];
+    if (next && next.mode !== mode) onChange(next.mode);
+  };
+
+  return (
+    <div
+      role="radiogroup"
+      aria-label={words.label}
+      part="modes"
+      className={classes(classNames, "sc-space__modes")}
+    >
+      {MODES.map(({ mode: each, glyph: Glyph }, index) => {
+        const chosen = index === on;
+        return (
+          <button
+            key={each}
+            ref={(button) => {
+              buttons.current[index] = button;
+            }}
+            type="button"
+            role="radio"
+            aria-checked={chosen}
+            tabIndex={chosen ? 0 : -1}
+            onClick={() => {
+              if (!chosen) onChange(each);
+            }}
+            onKeyDown={(event) => {
+              onKeyDown(event, index);
+            }}
+            part={chosen ? `mode mode-${each} mode-selected` : `mode mode-${each}`}
+            className={classes(classNames, "sc-space__mode", `sc-space__mode--${each}`)}
+          >
+            <Glyph aria-hidden weight={chosen ? "fill" : "regular"} />
+            <span>{words[each]}</span>
+          </button>
+        );
+      })}
+    </div>
+  );
+}

package/src/VoiceCall.tsx

@@ -0,0 +1,411 @@
+import {
+  MicrophoneIcon,
+  MicrophoneSlashIcon,
+  PhoneDisconnectIcon,
+  SpeakerHighIcon,
+} from "@phosphor-icons/react";
+import { useEffect, useRef, useState, type ReactNode, type RefObject } from "react";
+
+import {
+  durationOf,
+  keyBelongsElsewhere,
+  lookOf,
+  orbOf,
+  type CallEndedBy,
+  type CallLook,
+  type CallProblem,
+  type CallState,
+} from "./call";
+import { classes } from "./classes";
+import { Button } from "./kit/Button";
+import { KitProvider, type KitClassNames, type KitPart } from "./kit/context";
+import type { AgentTint } from "./tint";
+import { useCall, type CallJoin } from "./useCall";
+import { Orb } from "./voice/Orb";
+import type { OrbStyle } from "./voice/orbs";
+
+/** How big the orb is drawn: large, in the middle, with room for it to grow when the voice is loud. */
+const ORB_SIZE = 280;
+
+/** The orb's level where nobody it follows is speaking. */
+const SILENT = (): number => 0;
+
+/** The words a call says; a host gives its own, in its language. */
+export interface VoiceCallMessages {
+  /** The call's name, for those who can't see it. */
+  call: (name: string) => string;
+  /** What the call is doing, in a word or two. */
+  states: Readonly<Record<Exclude<CallLook, "problem">, string>>;
+  /** Under the state while the call connects. */
+  calling: (name: string) => string;
+  /** Why the call ended, before how long it lasted. */
+  ended: Readonly<Record<CallEndedBy, (name: string) => string>>;
+  /** Why the call never began, and what the person can do about it. */
+  problems: Readonly<Record<CallProblem, { title: (name: string) => string; help: string }>>;
+  mute: string;
+  hangUp: string;
+  /** Under the controls, where there is a keyboard. */
+  keys: string;
+  /** Under the controls while the microphone is off. */
+  muted: string;
+  /** The browser held the agent's voice until a press: the button that lets it play. */
+  hear: (name: string) => string;
+}
+
+export const VOICE_CALL_MESSAGES: VoiceCallMessages = {
+  call: (name) => `Call with ${name}`,
+  states: {
+    connecting: "Connecting…",
+    listening: "Listening",
+    thinking: "Thinking",
+    speaking: "Speaking",
+    reconnecting: "Reconnecting…",
+    ended: "Call ended",
+  },
+  calling: (name) => `Calling ${name}`,
+  ended: {
+    person: () => "You hung up",
+    agent: (name) => `${name} hung up`,
+    limit: () => "It reached its longest time",
+    dropped: () => "The line dropped",
+  },
+  problems: {
+    denied: {
+      title: () => "The microphone isn't allowed",
+      help: "Allow the microphone for this page (the icon beside the address) and call again.",
+    },
+    nomic: {
+      title: () => "No microphone",
+      help: "Plug one in, or pick another in your system's sound settings, and call again.",
+    },
+    inuse: {
+      title: () => "The microphone is busy",
+      help: "Another app is using it. Close it and call again.",
+    },
+    unsupported: {
+      title: () => "This browser can't call",
+      help: "Open this page over https in a recent Chrome, Edge, Safari or Firefox.",
+    },
+    off: {
+      title: () => "Calls aren't set up",
+      help: "Calls are turned on where your agents work. Ask whoever set it up.",
+    },
+    builder: {
+      title: (name) => `${name} doesn't take calls`,
+      help: "A squad's builder only writes. Call one of the squad's agents.",
+    },
+    refused: {
+      title: (name) => `${name} can't take this call`,
+      help: "Try again in a moment.",
+    },
+    failed: {
+      title: (name) => `Couldn't call ${name}`,
+      help: "Check your connection and try again.",
+    },
+    unanswered: {
+      title: (name) => `${name} isn't answering`,
+      help: "Calls aren't being taken right now. Try again in a moment.",
+    },
+  },
+  mute: "Mute",
+  hangUp: "Hang up",
+  keys: "Space mutes and unmutes",
+  muted: "Your microphone is off",
+  hear: (name) => `Hear ${name}`,
+};
+
+/** The call's parts, by the class each carries; `classNames` adds a host's own under the same keys. */
+export type VoiceCallPart =
+  | "sc-call"
+  | `sc-call--${CallLook}`
+  | `sc-call--${AgentTint}`
+  | "sc-call--on"
+  | "sc-call--muted"
+  | "sc-call__stage"
+  | "sc-call__orb"
+  | "sc-call__state"
+  | "sc-call__line"
+  | "sc-call__sound"
+  | "sc-call__controls"
+  | "sc-call__control"
+  | "sc-call__mute"
+  | "sc-call__hangup"
+  | "sc-call__hint"
+  | "sc-call__captions"
+  | "sc-call__after";
+
+export interface VoiceCallProps {
+  /**
+   * Where to join: LiveKit's address and a token for the call's room (our API's
+   * `client.conversations.call(agentId)` answers both, `client.agents.call(id)` for the owner's
+   * test). Called once, when the call starts, after the microphone is open.
+   */
+  connect: () => Promise<CallJoin>;
+  /** The agent's name, for the words that say it. */
+  name: string;
+  /**
+   * The agent's own tint (`agentTint(id)`), worn by the call's chrome: the orb's shader paints its
+   * own colours, and the still orb that stands in where there is no WebGL wears it.
+   */
+  tint?: AgentTint | undefined;
+  /** How the orb is drawn: `"wave"` (the default) or `"fluid-dots"`. */
+  orb?: OrbStyle | undefined;
+  /** The orb's diameter in pixels: 280 by default, less for a call in a small panel. */
+  orbSize?: number | undefined;
+  /**
+   * Why the call ended as the API keeps it, once the host has read it (`endedByReason` of its
+   * conversation's call): what the end says when the agent's side closed the room (its goodbye,
+   * or its longest time), which the room doesn't tell. Until then the end says how long it was.
+   */
+  endedBy?: CallEndedBy | null | undefined;
+  messages?: Partial<VoiceCallMessages> | undefined;
+  /** The host's classes for the call's parts and the kit's (the orb's `sc-orb…`, the buttons'). */
+  classNames?: Partial<Record<VoiceCallPart | KitPart, string>> | undefined;
+  /**
+   * The call is over, once: it ended (`answered`: the agent took it; `problem` null), or it
+   * couldn't begin (`problem`: why, which the call shows until the host takes it away).
+   */
+  onEnd?: ((answered: boolean, problem: CallProblem | null) => void) | undefined;
+  /** The agent took the call: its time counts from now. Once. */
+  onAnswer?: (() => void) | undefined;
+  /** What the host offers once the call is over, in place of the controls: call again, write. */
+  after?: ReactNode;
+  /** What is being said, drawn by the host under the orb while the call is on (`sc-call__captions`). */
+  captions?: ReactNode;
+}
+
+/**
+ * A voice call with an agent, the one a customer has on the phone: the call starts when it
+ * mounts and ends when it unmounts. The orb, large in the middle, rests while the line is found,
+ * moves with whoever speaks (the agent's voice while it speaks, the person's while it listens),
+ * calms while the agent thinks, and fades once the call is over; under it what the call
+ * is doing in a word, its time, and the two controls a phone has, mute and hang up. A microphone
+ * that can't be used, or a call that can't be made (the API's refusal among them), says why in
+ * words and what to do; an end says who ended it (the room's own word, or the API's: `endedBy`)
+ * and how long it lasted.
+ *
+ * Space mutes and unmutes from anywhere that isn't a field or a control of the page's own.
+ * Escape never hangs up: it is the key that closes things, pressed by reflex, and a call ended
+ * by accident can't be taken back, so ending one is the red button's alone. The orb stands
+ * still under reduced motion, one frame per state: the words say the rest.
+ */
+export function VoiceCall(props: VoiceCallProps) {
+  return (
+    <KitProvider classNames={props.classNames as KitClassNames}>
+      <Call {...props} />
+    </KitProvider>
+  );
+}
+
+function Call({
+  connect,
+  name,
+  tint = "sky",
+  orb: style,
+  orbSize = ORB_SIZE,
+  endedBy,
+  messages,
+  classNames,
+  onEnd,
+  onAnswer,
+  after,
+  captions,
+}: VoiceCallProps) {
+  const words = { ...VOICE_CALL_MESSAGES, ...messages };
+  const root = useRef<HTMLElement>(null);
+  const sink = useRef<HTMLDivElement>(null);
+  const call = useCall(connect, { sink });
+  const { state } = call;
+  const look = lookOf(state);
+  const orb = orbOf(look);
+  const over = state.stage === "over";
+  const seconds = useSeconds(state);
+
+  useSpace(root, !over, () => {
+    call.mute();
+  });
+  // The call takes the keyboard as it opens, so Space is its from the start; and again once over,
+  // when the control that had it is gone, so the host's offers are the next stop.
+  useEffect(() => {
+    root.current?.focus({ preventScroll: true });
+  }, [over]);
+  // The host's ears as it last gave them.
+  const told = useRef({ onEnd, onAnswer });
+  useEffect(() => {
+    told.current = { onEnd, onAnswer };
+  });
+  const answered = state.answeredAt !== null;
+  useEffect(() => {
+    if (answered) told.current.onAnswer?.();
+  }, [answered]);
+  useEffect(() => {
+    if (over) told.current.onEnd?.(answered, state.problem);
+  }, [over]);
+
+  const { headline, line } = wordsOf(state, look, seconds, words, name, endedBy ?? null);
+  const modifiers: VoiceCallPart[] = [`sc-call--${look}`, `sc-call--${tint}`];
+  if (!over) modifiers.push("sc-call--on");
+  if (state.muted && !over) modifiers.push("sc-call--muted");
+
+  return (
+    <section
+      ref={root}
+      tabIndex={-1}
+      aria-label={words.call(name)}
+      part="call"
+      className={`sc ${classes(classNames, "sc-call", ...modifiers)}`}
+    >
+      <div className={classes(classNames, "sc-call__stage")}>
+        <Orb
+          state={orb.state}
+          level={orb.follows === null ? SILENT : call.meter[orb.follows]}
+          size={orbSize}
+          style={style}
+          label={headline}
+          className={classes(classNames, "sc-call__orb")}
+        />
+        <p role="status" part="call-state" className={classes(classNames, "sc-call__state")}>
+          <span key={headline}>{headline}</span>
+        </p>
+        <p part="call-line" className={classes(classNames, "sc-call__line")}>
+          {line}
+        </p>
+      </div>
+      {captions !== undefined && !over && (
+        <div part="captions" className={classes(classNames, "sc-call__captions")}>
+          {captions}
+        </div>
+      )}
+      {state.silenced && !over && (
+        <Button
+          size="sm"
+          icon={SpeakerHighIcon}
+          onClick={call.hear}
+          className={classes(classNames, "sc-call__sound")}
+        >
+          {words.hear(name)}
+        </Button>
+      )}
+      {over ? (
+        after !== undefined && (
+          <div part="call-after" className={classes(classNames, "sc-call__after")}>
+            {after}
+          </div>
+        )
+      ) : (
+        <>
+          <div part="call-controls" className={classes(classNames, "sc-call__controls")}>
+            <div className={classes(classNames, "sc-call__control")}>
+              <Button
+                icon={state.muted ? MicrophoneSlashIcon : MicrophoneIcon}
+                aria-label={words.mute}
+                aria-pressed={state.muted}
+                disabled={state.stage === "opening"}
+                onClick={() => {
+                  call.mute();
+                }}
+                part="mute"
+                className={classes(classNames, "sc-call__mute")}
+              />
+              <span aria-hidden>{words.mute}</span>
+            </div>
+            <div className={classes(classNames, "sc-call__control")}>
+              <Button
+                tone="danger"
+                icon={PhoneDisconnectIcon}
+                aria-label={words.hangUp}
+                onClick={call.hangUp}
+                part="hang-up"
+                className={classes(classNames, "sc-call__hangup")}
+              />
+              <span aria-hidden>{words.hangUp}</span>
+            </div>
+          </div>
+          <p
+            data-keys={state.muted ? undefined : ""}
+            className={classes(classNames, "sc-call__hint")}
+          >
+            {state.muted ? words.muted : words.keys}
+          </p>
+        </>
+      )}
+      {/* The agent's voice plays from here. */}
+      <div ref={sink} hidden />
+    </section>
+  );
+}
+
+/**
+ * What the call says: what it is doing (or why it couldn't begin), and under it who is being
+ * called, the time, how it ended (as the room knows it, else as the API said: `endedBy`) and how
+ * long it lasted, or what to do.
+ */
+function wordsOf(
+  state: CallState,
+  look: CallLook,
+  seconds: number,
+  words: VoiceCallMessages,
+  name: string,
+  endedBy: CallEndedBy | null,
+): { headline: string; line: string } {
+  if (look === "problem" && state.problem !== null) {
+    const problem = words.problems[state.problem];
+    return { headline: problem.title(name), line: problem.help };
+  }
+  const headline = look === "problem" ? "" : words.states[look];
+  if (state.end !== null) {
+    const by = state.end.by ?? endedBy;
+    const lasted = durationOf(state.end.seconds);
+    // Why it ended says it ended; how long it lasted, under it.
+    return { headline: by === null ? headline : words.ended[by](name), line: lasted };
+  }
+  return {
+    headline,
+    line: state.answeredAt === null ? words.calling(name) : durationOf(seconds),
+  };
+}
+
+/** The call's time in whole seconds: counting while it is on, held once it is over. */
+function useSeconds(state: CallState): number {
+  const [now, setNow] = useState(() => Date.now());
+  const counting = state.answeredAt !== null && state.stage !== "over";
+  useEffect(() => {
+    if (!counting) return undefined;
+    const tick = setInterval(() => {
+      setNow(Date.now());
+    }, 500);
+    return () => {
+      clearInterval(tick);
+    };
+  }, [counting]);
+  if (state.end !== null) return state.end.seconds;
+  if (state.answeredAt === null) return 0;
+  return Math.max(0, Math.floor((now - state.answeredAt) / 1000));
+}
+
+/**
+ * Space mutes and unmutes while `active`, wherever it doesn't belong to something else (a field,
+ * a control of the page's own). Taken whole, down and up: the page doesn't scroll, and a control
+ * of the call that has the focus is not pressed by it.
+ */
+function useSpace(root: RefObject<HTMLElement | null>, active: boolean, toggle: () => void) {
+  const latest = useRef(toggle);
+  useEffect(() => {
+    latest.current = toggle;
+  });
+  useEffect(() => {
+    if (!active) return undefined;
+    const onKey = (event: KeyboardEvent) => {
+      if (event.key !== " " || event.ctrlKey || event.metaKey || event.altKey) return;
+      if (event.defaultPrevented || keyBelongsElsewhere(event.target, root.current)) return;
+      event.preventDefault();
+      if (event.type === "keydown" && !event.repeat) latest.current();
+    };
+    window.addEventListener("keydown", onKey);
+    window.addEventListener("keyup", onKey);
+    return () => {
+      window.removeEventListener("keydown", onKey);
+      window.removeEventListener("keyup", onKey);
+    };
+  }, [active, root]);
+}