@signalcore/ui 1.0.0-beta.2 → 1.0.0-beta.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@signalcore/ui",
-  "version": "1.0.0-beta.2",
+  "version": "1.0.0-beta.3",
   "description": "SignalCore's components for the people an agent serves: the chat, the call, the agent's space, and the <signalcore-chat> widget.",
   "keywords": [
     "signalcore",

package/src/AgentAbout.tsx

@@ -155,6 +155,8 @@ export const ABOUT_MESSAGES: AboutMessages = {
     webhook: "When called",
     event: "On an event",
     platform: "On a message",
+    manual: "When started",
+    after: "After another",
   },
   topics: {
     apps: "Apps",
@@ -946,6 +948,8 @@ const KIND_ICONS: Readonly<Record<AutomationKind, Icon>> = {
   webhook: "code",
   event: "bell",
   platform: "message",
+  manual: "hand",
+  after: "check",
 };
 
 /** An app's mark: the host's logo when it draws one, else the provider's, bare. */

package/src/AgentChat.tsx

@@ -40,7 +40,10 @@ import { useConversationFiles } from "./conversationFiles";
 import { FILES_PER_MESSAGE } from "./frames";
 import { actionMark } from "./marks";
 import { AudioPlayer } from "./kit/AudioPlayer";
+import { Button } from "./kit/Button";
 import { KitProvider, type KitPart } from "./kit/context";
+import { Field } from "./kit/Field";
+import { Checkbox, NumberInput, TextArea, TextInput } from "./kit/Inputs";
 import { carriesFiles, FileChips, UploadChips, useUploads, type Uploads } from "./kit/FileField";
 import { KIT_MESSAGES, type KitLocale, type KitMessages } from "./kit/messages";
 import type { FileHost } from "./kit/uploads";
@@ -122,6 +125,12 @@ export interface ChatMessages {
   inputs: Readonly<Record<string, string>>;
   allow: string;
   decline: string;
+  /** What heads the card of several actions that wait for the person's leave, by how many. */
+  approvals: (count: number) => string;
+  /** The card's one button, as many as are ticked: every one, some, or none (all declined). */
+  approveAll: string;
+  approveSome: (count: number) => string;
+  declineAll: string;
   /**
    * On a person's page, in place of the approval card: what the agent asked to do waits for the
    * business's yes (`decides: "business"`), which its people give from their app.
@@ -194,6 +203,10 @@ export const CHAT_MESSAGES: ChatMessages = {
   inputs: {},
   allow: "Allow",
   decline: "Decline",
+  approvals: (count) => `${count} actions need your approval`,
+  approveAll: "Approve all",
+  approveSome: (count) => `Approve ${count}`,
+  declineAll: "Decline all",
   confirming: "Waiting for the business to confirm",
   handedOff: "Handed to a person",
   handover: (holder, by, name) => {
@@ -256,6 +269,9 @@ export type ChatPart =
   | "sc-chat__step--failed"
   | "sc-chat__output"
   | "sc-chat__request"
+  | "sc-chat__requests"
+  | "sc-chat__ask"
+  | "sc-chat__ask-fields"
   | "sc-chat__confirming"
   | "sc-chat__screen"
   | "sc-chat__screen--bare"
@@ -460,6 +476,7 @@ function Chat({
     onTool: onTool ?? (() => Promise.reject(new Error(words.noTool))),
   });
   const files = useConversationFiles(client, conversationId, live.messages, onOpenFile);
+  useReadAsShown(client, conversationId, live.messages.at(-1)?.id);
   // What the person attaches to their next message: picked, dropped on the chat, or pasted.
   const uploads = useUploads(attachments ? files : undefined, { max: FILES_PER_MESSAGE });
   // Files go with what is said, once the turn waits on nothing; to the host's `write`, at once.
@@ -885,6 +902,7 @@ function Log({
                   components={components}
                   locale={locale}
                   onAction={live.act}
+                  onActAll={live.actAll}
                   builder={builder}
                   files={files}
                   who={who}
@@ -1234,8 +1252,11 @@ function Reply({
   who,
   steps,
   onChannel,
+  onActAll,
 }: DrawProps & {
   message: Message;
+  /** Several things done at once: a yes or no on each call it waits on, from one card. */
+  onActAll: (actions: readonly Action[]) => void;
   /** It was streaming: its words go on revealing from here. None: they show whole. */
   from: number | undefined;
   awaiting: string | null;
@@ -1251,6 +1272,11 @@ function Reply({
   onChannel: boolean;
 }) {
   const text = useReveal(message.text, from ?? message.text.length);
+  // The calls it waits on the leave of whoever this page speaks for: two or more, in one card.
+  const asked = message.steps.filter(
+    (step): step is Step & { request: Request } =>
+      step.request !== null && !(step.request.decides === "business" && who === "person"),
+  );
   // On a channel, what the person there has got so far; elsewhere, the words as they come.
   const { shown: said, typing } = onChannel
     ? channelParts(message, text)
@@ -1336,9 +1362,21 @@ function Reply({
             </div>
           ),
       )}
+      {asked.length > 1 && (
+        <Approvals
+          key={asked.map((step) => step.id).join()}
+          steps={asked}
+          name={name}
+          words={words}
+          classNames={classNames}
+          onActAll={onActAll}
+        />
+      )}
       {message.steps.map((step) => {
         const { request } = step;
-        if (request === null) return null;
+        if (request === null || (asked.length > 1 && asked.some((one) => one.id === step.id))) {
+          return null;
+        }
         if (request.decides === "business" && who === "person") {
           return (
             <p
@@ -1583,6 +1621,170 @@ function Approval({
   );
 }
 
+/**
+ * Several actions a reply waits on the person's leave for, in one card: a box to tick for each
+ * (all ticked to begin with), what each would take under it, editable while ticked, and one
+ * button that sends a yes for each ticked (with what was changed) and a no for the rest, at once.
+ */
+function Approvals({
+  steps,
+  name,
+  words,
+  classNames,
+  onActAll,
+}: {
+  steps: readonly (Step & { request: Request })[];
+  name: string;
+  words: ChatMessages;
+  classNames: ClassNames;
+  onActAll: (actions: readonly Action[]) => void;
+}) {
+  const [chosen, setChosen] = useState<ReadonlySet<string>>(
+    () => new Set(steps.map((step) => step.id)),
+  );
+  const [edits, setEdits] = useState<Readonly<Record<string, Record<string, unknown>>>>({});
+  const [sent, setSent] = useState(false);
+  const inputOf = (step: Step & { request: Request }) => ({
+    ...step.request.input,
+    ...edits[step.id],
+  });
+  const send = () => {
+    setSent(true);
+    onActAll(
+      steps.map((step) =>
+        chosen.has(step.id)
+          ? {
+              surface: step.id,
+              name: "approve",
+              data: step.id in edits ? { input: inputOf(step) } : {},
+              label: words.allow,
+            }
+          : { surface: step.id, name: "decline", data: {}, label: words.decline },
+      ),
+    );
+  };
+  const label =
+    chosen.size === steps.length
+      ? words.approveAll
+      : chosen.size === 0
+        ? words.declineAll
+        : words.approveSome(chosen.size);
+  return (
+    <div part="approval" className={classes(classNames, "sc-chat__request", "sc-chat__requests")}>
+      <header>
+        <ShieldWarningIcon aria-hidden />
+        {words.approvals(steps.length)}
+      </header>
+      <ul>
+        {steps.map((step) => {
+          const ticked = chosen.has(step.id);
+          return (
+            <li key={step.id} className={classes(classNames, "sc-chat__ask")}>
+              <Checkbox
+                value={ticked}
+                disabled={sent}
+                onChange={(on) => {
+                  setChosen((last) => {
+                    const next = new Set(last);
+                    if (on) next.add(step.id);
+                    else next.delete(step.id);
+                    return next;
+                  });
+                }}
+              >
+                {words.request(name, step.request.action)}
+              </Checkbox>
+              {ticked && (
+                <div className={classes(classNames, "sc-chat__ask-fields")}>
+                  {Object.entries(inputOf(step)).map(([field, value]) => (
+                    <InputValue
+                      key={field}
+                      label={words.inputs[field] ?? field}
+                      value={value}
+                      disabled={sent}
+                      onChange={(changed) => {
+                        setEdits((last) => ({
+                          ...last,
+                          [step.id]: { ...last[step.id], [field]: changed },
+                        }));
+                      }}
+                    />
+                  ))}
+                </div>
+              )}
+            </li>
+          );
+        })}
+      </ul>
+      <footer>
+        <Button tone="primary" disabled={sent} onClick={send}>
+          {label}
+        </Button>
+      </footer>
+    </div>
+  );
+}
+
+/**
+ * One field of an action's input, editable as what it holds: words, a number, a yes or no;
+ * anything else (a list, an object) shown as it is.
+ */
+function InputValue({
+  label,
+  value,
+  disabled,
+  onChange,
+}: {
+  label: string;
+  value: unknown;
+  disabled: boolean;
+  onChange: (value: unknown) => void;
+}) {
+  if (typeof value === "boolean") {
+    return (
+      <Checkbox value={value} disabled={disabled} onChange={onChange}>
+        {label}
+      </Checkbox>
+    );
+  }
+  return (
+    <Field label={label}>
+      {(ids) =>
+        typeof value === "number" ? (
+          <NumberInput {...ids} value={value} disabled={disabled} onChange={onChange} />
+        ) : typeof value === "string" ? (
+          value.length > 80 || value.includes("\n") ? (
+            <TextArea {...ids} value={value} disabled={disabled} onChange={onChange} />
+          ) : (
+            <TextInput {...ids} value={value} disabled={disabled} onChange={onChange} />
+          )
+        ) : (
+          <TextInput {...ids} value={JSON.stringify(value)} disabled onChange={() => undefined} />
+        )
+      }
+    </Field>
+  );
+}
+
+/**
+ * On a person's page, what came is read as the chat shows it: each newest message while the page
+ * is in sight, and once it comes back into sight. Their threads' `unread` follows.
+ */
+function useReadAsShown(client: Client, conversationId: string, newest: string | undefined) {
+  useEffect(() => {
+    if (client.who !== "person" || newest === undefined) return undefined;
+    const read = () => {
+      if (document.visibilityState === "hidden") return;
+      client.conversations.read(conversationId).catch(() => undefined);
+    };
+    read();
+    document.addEventListener("visibilitychange", read);
+    return () => {
+      document.removeEventListener("visibilitychange", read);
+    };
+  }, [client, conversationId, newest]);
+}
+
 /**
  * Where the person writes: a box that grows a few lines with the text. Enter sends, Shift+Enter
  * breaks the line; nothing goes while a reply is on its way or the socket is closed, but the

package/src/AgentSpace.tsx

@@ -19,6 +19,13 @@ import type { KitLocale } from "./kit/messages";
 import { Modes, type ModeMessages, type ModePart, type SpaceMode } from "./Modes";
 import type { SurfaceComponents, SurfacePart } from "./surface/scope";
 import { agentTint, type AgentTint } from "./tint";
+import {
+  THREAD_MESSAGES,
+  Threads,
+  useUnread,
+  type ThreadMessages,
+  type ThreadPart,
+} from "./Threads";
 import { useAgentFace } from "./useAgentFace";
 import { useConversation, type LiveConversation, type ToolHandler } from "./useConversation";
 import type { VoiceCallMessages, VoiceCallPart } from "./VoiceCall";
@@ -50,6 +57,8 @@ export interface SpaceMessages {
   voice: Partial<VoiceCallMessages>;
   /** What the person's tasks say (`AgentTasks`'s words). */
   tasks: TaskMessages;
+  /** What the person's threads say (`Threads`'s words). */
+  threads: ThreadMessages;
 }
 
 export const SPACE_MESSAGES: SpaceMessages = {
@@ -63,6 +72,7 @@ export const SPACE_MESSAGES: SpaceMessages = {
   chat: {},
   voice: {},
   tasks: TASK_MESSAGES,
+  threads: THREAD_MESSAGES,
 };
 
 /** The space's parts, by the class each carries; `classNames` adds a host's own under the same keys. */
@@ -86,6 +96,9 @@ export type SpacePart =
   | "sc-space__caption--agent"
   | "sc-space__status"
   | "sc-space__tasks"
+  | "sc-space__bar"
+  | "sc-space__threads"
+  | "sc-space__dot"
   | ModePart;
 
 /**
@@ -123,7 +136,14 @@ export interface AgentSpaceProps {
   classNames?:
     | Partial<
         Record<
-          SpacePart | ChatPart | SurfacePart | KitPart | BrowserPart | VoiceCallPart | TaskPart,
+          | SpacePart
+          | ChatPart
+          | SurfacePart
+          | KitPart
+          | BrowserPart
+          | VoiceCallPart
+          | TaskPart
+          | ThreadPart,
           string
         >
       >
@@ -147,6 +167,12 @@ export interface AgentSpaceProps {
    * while there are any, which opens them. On by default; the business's own space never has it.
    */
   tasks?: boolean | undefined;
+  /**
+   * Whether a person sees their threads with the agent (`Threads`): a line over the chat, a dot on
+   * it while another waits on them, which lists them by title with what is unread, to go to one
+   * or start another. On by default; the business's own space never has it.
+   */
+  threads?: boolean | undefined;
 }
 
 /**
@@ -181,10 +207,13 @@ export function AgentSpace({
   orb,
   onClose,
   tasks: showsTasks = true,
+  threads: showsThreads = true,
 }: AgentSpaceProps) {
   const words = { ...SPACE_MESSAGES, ...messages };
   const theirs = useTasks(client, agentId, showsTasks && client.who === "person");
   const [listing, setListing] = useState(false);
+  const threads = useUnread(client, agentId, showsThreads && client.who === "person");
+  const [browsing, setBrowsing] = useState(false);
   const { face, loading } = useAgentFace(client, agentId);
   const opened = useOpened(client, agentId, conversationId, onConversation);
   const [mode, setMode] = useState<SpaceMode>("text");
@@ -250,6 +279,30 @@ export function AgentSpace({
         </p>
       );
     }
+    if (browsing && threads.threads !== null) {
+      const went = (next: string) => {
+        opened.go(next);
+        setBrowsing(false);
+        void threads.refresh();
+      };
+      return (
+        <Threads
+          threads={threads.threads}
+          current={id}
+          onSelect={went}
+          onNew={() => {
+            void client.conversations.start(agentId).then((started) => {
+              went(started.id);
+            });
+          }}
+          onBack={() => {
+            setBrowsing(false);
+          }}
+          messages={words.threads}
+          classNames={classNames}
+        />
+      );
+    }
     if (listing && theirs.tasks !== null) {
       return (
         <AgentTasks
@@ -320,20 +373,43 @@ export function AgentSpace({
       );
     }
     const count = theirs.tasks?.length ?? 0;
+    // Another thread with something for them: the line to the threads carries a dot.
+    const news = (threads.threads ?? []).some(
+      (thread) =>
+        thread.id !== id && ((thread.unread ?? 0) > 0 || thread.waiting_on_person === true),
+    );
     return (
       <>
-        {count > 0 && (
-          <button
-            type="button"
-            part="tasks-open"
-            className={classes(classNames, "sc-space__tasks")}
-            onClick={() => {
-              setListing(true);
-              void theirs.refresh();
-            }}
-          >
-            {words.tasks.open(count)}
-          </button>
+        {(threads.threads !== null || count > 0) && (
+          <div className={classes(classNames, "sc-space__bar")}>
+            {threads.threads !== null && (
+              <button
+                type="button"
+                part="threads-open"
+                className={classes(classNames, "sc-space__threads")}
+                onClick={() => {
+                  setBrowsing(true);
+                  void threads.refresh();
+                }}
+              >
+                {words.threads.open}
+                {news && <span aria-hidden className={classes(classNames, "sc-space__dot")} />}
+              </button>
+            )}
+            {count > 0 && (
+              <button
+                type="button"
+                part="tasks-open"
+                className={classes(classNames, "sc-space__tasks")}
+                onClick={() => {
+                  setListing(true);
+                  void theirs.refresh();
+                }}
+              >
+                {words.tasks.open(count)}
+              </button>
+            )}
+          </div>
         )}
         <AgentChat
           client={client}

package/src/Threads.tsx

@@ -0,0 +1,218 @@
+import { ArrowLeftIcon, PlusIcon } from "@phosphor-icons/react";
+import { useCallback, useEffect, useRef, useState } from "react";
+
+import { AgentChat, type AgentChatProps } from "./AgentChat";
+import { classes } from "./classes";
+import type { Client } from "./client";
+import { Button } from "./kit/Button";
+import type { Conversation as Thread } from "./types";
+
+/** What the person's threads say; a host gives its own, in its language. */
+export interface ThreadMessages {
+  /** Over the chat, to open the list; and the list's title. */
+  open: string;
+  title: string;
+  back: string;
+  /** Starts another conversation with the agent. */
+  new: string;
+  /** A thread nothing names yet. */
+  untitled: string;
+  /** Beside a thread: how many of the agent's messages are unread; that it waits on them. */
+  unread: (count: number) => string;
+  waiting: string;
+  empty: string;
+}
+
+export const THREAD_MESSAGES: ThreadMessages = {
+  open: "Conversations",
+  title: "Your conversations",
+  back: "Back to the conversation",
+  new: "New conversation",
+  untitled: "New conversation",
+  unread: (count) => (count === 1 ? "1 unread message" : `${count} unread messages`),
+  waiting: "Waiting for you",
+  empty: "Nothing here yet.",
+};
+
+export type ThreadPart =
+  | "sc-threads"
+  | "sc-threads__head"
+  | "sc-threads__title"
+  | "sc-threads__list"
+  | "sc-threads__item"
+  | "sc-threads__item--current"
+  | "sc-threads__name"
+  | "sc-threads__badge"
+  | "sc-threads__dot"
+  | "sc-threads__empty";
+
+/** How often the person's threads are read again, for what is unread. */
+export const THREADS_POLL_MS = 20_000;
+
+/** The person's threads with an agent, and what of them waits on the person. */
+export interface Unread {
+  /** Newest first; null until read, and whenever they can't be. */
+  threads: Thread[] | null;
+  /** Every unread message of the agent's, across the threads. */
+  unread: number;
+  /** Whether a thread waits on the person (a question, their yes). */
+  waiting: boolean;
+  refresh: () => Promise<void>;
+}
+
+/**
+ * The threads the person the client speaks for has with the agent, read now, again every
+ * `THREADS_POLL_MS`, when the page comes back into sight, and on `refresh`: what draws a dot on
+ * a launcher, a count beside a tab. `enabled` off reads nothing.
+ */
+export function useUnread(client: Client, agentId: string, enabled = true): Unread {
+  const [threads, setThreads] = useState<Thread[] | null>(null);
+  const live = useRef(true);
+  const refresh = useCallback(async () => {
+    try {
+      const read = await client.conversations.list(agentId);
+      if (live.current) setThreads(read);
+    } catch {
+      if (live.current) setThreads(null);
+    }
+  }, [client, agentId]);
+  useEffect(() => {
+    live.current = true;
+    if (!enabled) return undefined;
+    void refresh();
+    const timer = setInterval(() => void refresh(), THREADS_POLL_MS);
+    const shown = () => {
+      if (document.visibilityState === "visible") void refresh();
+    };
+    document.addEventListener("visibilitychange", shown);
+    return () => {
+      live.current = false;
+      clearInterval(timer);
+      document.removeEventListener("visibilitychange", shown);
+    };
+  }, [enabled, refresh]);
+  const read = enabled ? threads : null;
+  return {
+    threads: read,
+    unread: (read ?? []).reduce((sum, thread) => sum + (thread.unread ?? 0), 0),
+    waiting: (read ?? []).some((thread) => thread.waiting_on_person === true),
+    refresh,
+  };
+}
+
+export interface ThreadsProps {
+  /** The threads, newest first (`useUnread`'s). */
+  threads: readonly Thread[];
+  /** The one open now, marked. */
+  current?: string | null | undefined;
+  onSelect: (id: string) => void;
+  /** Starts another; without it, no button for it. */
+  onNew?: (() => void) | undefined;
+  /** The way back to the open conversation; without it, none. */
+  onBack?: (() => void) | undefined;
+  messages?: Partial<ThreadMessages> | undefined;
+  classNames?: Partial<Record<ThreadPart, string>> | undefined;
+}
+
+/**
+ * The person's threads with the agent: each by its title, how many of the agent's messages in
+ * it are unread, a dot when it waits on them; the open one marked; another to start.
+ */
+export function Threads({
+  threads,
+  current = null,
+  onSelect,
+  onNew,
+  onBack,
+  messages,
+  classNames,
+}: ThreadsProps) {
+  const words = { ...THREAD_MESSAGES, ...messages };
+  return (
+    <section aria-label={words.title} part="threads" className={classes(classNames, "sc-threads")}>
+      <header className={classes(classNames, "sc-threads__head")}>
+        {onBack && (
+          <Button
+            tone="ghost"
+            size="sm"
+            icon={ArrowLeftIcon}
+            aria-label={words.back}
+            title={words.back}
+            onClick={onBack}
+          />
+        )}
+        <h3 className={classes(classNames, "sc-threads__title")}>{words.title}</h3>
+        {onNew && (
+          <Button tone="ghost" size="sm" icon={PlusIcon} onClick={onNew}>
+            {words.new}
+          </Button>
+        )}
+      </header>
+      {threads.length === 0 ? (
+        <p className={classes(classNames, "sc-threads__empty")}>{words.empty}</p>
+      ) : (
+        <ul className={classes(classNames, "sc-threads__list")}>
+          {threads.map((thread) => {
+            const unread = thread.unread ?? 0;
+            const open = thread.id === current;
+            return (
+              <li key={thread.id}>
+                <button
+                  type="button"
+                  aria-current={open || undefined}
+                  className={classes(
+                    classNames,
+                    "sc-threads__item",
+                    ...(open ? (["sc-threads__item--current"] as const) : []),
+                  )}
+                  onClick={() => {
+                    onSelect(thread.id);
+                  }}
+                >
+                  <span className={classes(classNames, "sc-threads__name")}>
+                    {thread.title ?? words.untitled}
+                  </span>
+                  {unread > 0 ? (
+                    <span
+                      aria-label={words.unread(unread)}
+                      className={classes(classNames, "sc-threads__badge")}
+                    >
+                      {unread}
+                    </span>
+                  ) : (
+                    thread.waiting_on_person === true && (
+                      <span
+                        role="img"
+                        aria-label={words.waiting}
+                        className={classes(classNames, "sc-threads__dot")}
+                      />
+                    )
+                  )}
+                </button>
+              </li>
+            );
+          })}
+        </ul>
+      )}
+    </section>
+  );
+}
+
+/**
+ * A conversation between a person and one agent, as the API reads it (`types.ts`): one name for
+ * the shape and for the component that shows one.
+ */
+export type Conversation = Thread;
+
+export type ConversationProps = Omit<AgentChatProps, "conversationId"> & {
+  /** The conversation to show, by its id. */
+  id: string;
+};
+
+/**
+ * One conversation, for a host that lays out its own threads: the chat (`AgentChat`), which reads
+ * what comes as it shows it on a person's page, so their `unread` follows.
+ */
+export function Conversation({ id, ...chat }: ConversationProps) {
+  return <AgentChat conversationId={id} {...chat} />;
+}