@signalcore/ui 0.1.0 → 1.0.0-beta.1

package/src/call.ts

@@ -0,0 +1,300 @@
+/**
+ * A voice call with an agent, as the person on it sees it: where it stands, why it ended or
+ * never began, and how long it lasted. Pure, so it is tested without a room; `useCall` feeds it
+ * what LiveKit says.
+ */
+
+import { ApiError } from "./client";
+import type { CallReason } from "./types";
+import type { OrbState } from "./voice/orbs";
+
+/** What the agent is doing, as LiveKit's agents publish it (`lk.agent.state`). */
+export type AgentActivity = "initializing" | "idle" | "listening" | "thinking" | "speaking";
+
+/** Why a call that began is over. */
+export type CallEndedBy =
+  /** The person hung up. */
+  | "person"
+  /** The agent did: it said one of its goodbyes. */
+  | "agent"
+  /** It reached its longest time. */
+  | "limit"
+  /** The line went: the network, or the agent's side fell. */
+  | "dropped";
+
+/** Why a call never began. */
+export type CallProblem =
+  /** The person, or the browser, said no to the microphone. */
+  | "denied"
+  /** There is no microphone to use. */
+  | "nomic"
+  /** Another application holds the microphone. */
+  | "inuse"
+  /** This browser can't call: no microphone access at all (an old one, or a page not on https). */
+  | "unsupported"
+  /** Calls aren't set up where the agent works (the API refused with `no_calls`). */
+  | "off"
+  /** The agent takes no calls: a squad's builder (`builder`). */
+  | "builder"
+  /** The API wouldn't make the call, for any other reason it named. */
+  | "refused"
+  /** The call couldn't be made or joined. */
+  | "failed"
+  /** The room was there, but no agent came to it. */
+  | "unanswered";
+
+/** How a call ended: why, and how long it lasted from when the agent picked up. */
+export interface CallEnd {
+  /**
+   * Why, as far as the room knows: null when the agent's side closed it (its goodbye, or its
+   * longest time), which only the API says (`endedByReason`).
+   */
+  by: CallEndedBy | null;
+  seconds: number;
+}
+
+/** Where a call stands. */
+export interface CallState {
+  /** Opening the microphone and the room; ringing until the agent joins; on; over. */
+  stage: "opening" | "ringing" | "on" | "over";
+  /** When the agent joined, in ms; the call's time counts from it. */
+  answeredAt: number | null;
+  /** What the agent says it is doing; null while it says nothing. */
+  agent: AgentActivity | null;
+  /** Whether the agent's voice is coming, for an agent that doesn't say what it is doing. */
+  speaking: boolean;
+  /** The line is being found again; the call goes on once it is. */
+  reconnecting: boolean;
+  muted: boolean;
+  /** The browser holds the agent's voice until the person presses something. */
+  silenced: boolean;
+  end: CallEnd | null;
+  problem: CallProblem | null;
+}
+
+export const CALL_START: CallState = {
+  stage: "opening",
+  answeredAt: null,
+  agent: null,
+  speaking: false,
+  reconnecting: false,
+  muted: false,
+  silenced: false,
+  end: null,
+  problem: null,
+};
+
+/** What moves a call, from the room. */
+export type CallEvent =
+  | { type: "ringing" }
+  | { type: "answered"; at: number }
+  | { type: "agent"; activity: AgentActivity | null }
+  | { type: "speaking"; speaking: boolean }
+  | { type: "reconnecting"; reconnecting: boolean }
+  | { type: "muted"; muted: boolean }
+  | { type: "silenced"; silenced: boolean }
+  | { type: "ended"; by: CallEndedBy | null; at: number }
+  | { type: "failed"; problem: CallProblem };
+
+/**
+ * The call, one event at a time. Once over (ended, or never begun) nothing moves it again: the
+ * room's last words after a hang-up (its disconnect, a track going) are not news.
+ */
+export function callReducer(state: CallState, event: CallEvent): CallState {
+  if (state.stage === "over") return state;
+  switch (event.type) {
+    case "ringing":
+      return state.stage === "opening" ? { ...state, stage: "ringing" } : state;
+    case "answered":
+      return state.answeredAt === null ? { ...state, stage: "on", answeredAt: event.at } : state;
+    case "agent":
+      return { ...state, agent: event.activity };
+    case "speaking":
+      return { ...state, speaking: event.speaking };
+    case "reconnecting":
+      return { ...state, reconnecting: event.reconnecting };
+    case "muted":
+      return { ...state, muted: event.muted };
+    case "silenced":
+      return { ...state, silenced: event.silenced };
+    case "ended": {
+      const seconds = state.answeredAt === null ? 0 : secondsBetween(state.answeredAt, event.at);
+      return { ...state, stage: "over", reconnecting: false, end: { by: event.by, seconds } };
+    }
+    case "failed":
+      return { ...state, stage: "over", reconnecting: false, problem: event.problem };
+  }
+}
+
+const secondsBetween = (from: number, to: number): number =>
+  Math.max(0, Math.floor((to - from) / 1000));
+
+/** What the call shows, in one word: each has its words, its look and its orb. */
+export type CallLook =
+  "connecting" | "listening" | "thinking" | "speaking" | "reconnecting" | "ended" | "problem";
+
+/**
+ * What the call shows now. Before the agent picks up, and while it starts, it is connecting;
+ * then what the agent says it is doing (an agent that says nothing is speaking while its voice
+ * comes, listening otherwise).
+ */
+export function lookOf(state: CallState): CallLook {
+  if (state.problem !== null) return "problem";
+  if (state.end !== null) return "ended";
+  if (state.answeredAt === null || state.agent === "initializing") return "connecting";
+  if (state.reconnecting) return "reconnecting";
+  if (state.agent === "thinking" || state.agent === "speaking") return state.agent;
+  if (state.agent === null && state.speaking) return "speaking";
+  return "listening";
+}
+
+/**
+ * What the orb shows of a call: what the agent is doing once the call is on, moved by whoever is
+ * speaking (the agent's voice while it speaks, the person's microphone while it listens); at rest
+ * while the line is found (connecting, reconnecting) and once the call is over.
+ */
+export function orbOf(look: CallLook): { state: OrbState; follows: "agent" | "person" | null } {
+  switch (look) {
+    case "speaking":
+      return { state: look, follows: "agent" };
+    case "listening":
+      return { state: look, follows: "person" };
+    case "thinking":
+      return { state: look, follows: null };
+    default:
+      return { state: "idle", follows: null };
+  }
+}
+
+/** The agent's state as LiveKit's agents publish it, or null for anything else. */
+export function activityOf(value: string | undefined): AgentActivity | null {
+  switch (value) {
+    case "initializing":
+    case "idle":
+    case "listening":
+    case "thinking":
+    case "speaking":
+      return value;
+    default:
+      return null;
+  }
+}
+
+/**
+ * Why the room let the person go, as LiveKit says it (`DisconnectReason`'s names): they hung up;
+ * the room was closed under them, which is the agent's side ending the call (its goodbye, or its
+ * longest time: null, the API says which); anything else, the line went.
+ */
+export function endedBy(reason: string | undefined, hungUp: boolean): CallEndedBy | null {
+  if (hungUp || reason === "CLIENT_INITIATED") return "person";
+  if (reason === "ROOM_DELETED" || reason === "ROOM_CLOSED" || reason === "PARTICIPANT_REMOVED") {
+    return null;
+  }
+  return "dropped";
+}
+
+/**
+ * Why a call ended as the API keeps it (`CallGlance.reason`), as the call says it: the person hung
+ * up, the agent said goodbye, it reached its longest time; anything else (it failed, its end never
+ * came) is a line that dropped. Null while the API has no end for it yet.
+ */
+export function endedByReason(reason: CallReason | null | undefined): CallEndedBy | null {
+  switch (reason) {
+    case "caller":
+      return "person";
+    case "agent":
+      return "agent";
+    case "max_duration":
+      return "limit";
+    case null:
+    case undefined:
+      return null;
+    default:
+      return "dropped";
+  }
+}
+
+/**
+ * Why a call couldn't be made, from what asking for it threw: the API's refusal, by its code
+ * (calls not set up where the agent works, an agent that takes none, any other it named);
+ * anything else (no answer, or one that named nothing) is a call that failed.
+ */
+export function refusalOf(error: unknown): CallProblem {
+  if (!(error instanceof ApiError) || error.code === null) return "failed";
+  switch (error.code) {
+    case "no_calls":
+      return "off";
+    case "builder":
+      return "builder";
+    default:
+      return "refused";
+  }
+}
+
+/**
+ * Why the microphone couldn't be opened, from the browser's error (`DOMException` names, as
+ * LiveKit reads them too); one the browser doesn't name is a call that failed.
+ */
+export function callProblemOf(error: unknown): CallProblem {
+  const name = error instanceof Error || isNamed(error) ? error.name : "";
+  switch (name) {
+    case "NotAllowedError":
+    case "PermissionDeniedError":
+    case "SecurityError":
+      return "denied";
+    case "NotFoundError":
+    case "DevicesNotFoundError":
+    case "OverconstrainedError":
+      return "nomic";
+    case "NotReadableError":
+    case "TrackStartError":
+    case "AbortError":
+      return "inuse";
+    default:
+      return "failed";
+  }
+}
+
+const isNamed = (value: unknown): value is { name: string } =>
+  typeof value === "object" &&
+  value !== null &&
+  "name" in value &&
+  typeof (value as { name: unknown }).name === "string";
+
+/** A call's time as a phone shows it: 0:07, 12:34, 1:02:03. */
+export function durationOf(seconds: number): string {
+  const whole = Math.max(0, Math.floor(seconds));
+  const hours = Math.floor(whole / 3600);
+  const minutes = Math.floor((whole % 3600) / 60);
+  const rest = String(whole % 60).padStart(2, "0");
+  return hours > 0 ? `${hours}:${String(minutes).padStart(2, "0")}:${rest}` : `${minutes}:${rest}`;
+}
+
+/**
+ * A loudness read off a track (0 to 1, the root mean square of its spectrum as LiveKit measures
+ * it) as the orb shows it: speech sits low on that scale, so it is lifted and the floor of a quiet
+ * room cut away.
+ */
+export function loudness(volume: number): number {
+  const lifted = (volume - FLOOR) / (1 - FLOOR);
+  return Math.min(1, Math.max(0, Math.sqrt(Math.max(0, lifted)) * GAIN));
+}
+
+const FLOOR = 0.04;
+const GAIN = 1.25;
+
+/**
+ * Whether a key belongs to what it was pressed on, not to the call: a field being typed in, or a
+ * control of the page's own (outside the call) that Space presses. Elsewhere (the call itself,
+ * the page, a dialog it sits in) Space mutes and unmutes.
+ */
+export function keyBelongsElsewhere(target: EventTarget | null, call: Element | null): boolean {
+  if (!(target instanceof Element)) return false;
+  if (target.matches(EDITABLE)) return true;
+  if (call?.contains(target)) return false;
+  return target.matches(PRESSABLE);
+}
+
+const EDITABLE = 'input, textarea, select, [contenteditable]:not([contenteditable="false"])';
+const PRESSABLE =
+  'button, a[href], summary, [role="button"], [role="checkbox"], [role="switch"], [role="radio"], [role="tab"], [role="menuitem"], [role="option"], [role="slider"]';

package/src/channelParts.ts

@@ -0,0 +1,17 @@
+import type { Message } from "./types";
+
+/**
+ * What of an agent's reply on a channel shows now, as the person there gets it: the parts that
+ * went, and whether more are on their way (shown as the channel's "typing"). One that failed
+ * shows whole, so the business reads what didn't go. Anything that doesn't go out shows whole.
+ */
+export function channelParts(
+  message: Pick<Message, "delivery" | "pieces" | "sent_parts">,
+  text: string,
+): { shown: string[]; typing: boolean } {
+  if (message.delivery == null) return { shown: [text], typing: false };
+  const parts = message.pieces != null && message.pieces.length > 1 ? message.pieces : [text];
+  if (message.delivery === "failed") return { shown: parts, typing: false };
+  const sent = message.sent_parts ?? (message.delivery === "queued" ? 0 : parts.length);
+  return { shown: parts.slice(0, sent), typing: sent < parts.length };
+}

package/src/classes.ts

@@ -0,0 +1,10 @@
+/** The classes of a component's parts: each name, and what the host adds under it. */
+export function classes<Part extends string>(
+  classNames: Partial<Record<Part, string>> | undefined,
+  ...parts: Part[]
+): string {
+  return parts
+    .flatMap((part) => [part, classNames?.[part]])
+    .filter((name) => name !== undefined)
+    .join(" ");
+}