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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@signalcore/ui",
-  "version": "1.0.0-beta.2",
+  "version": "1.0.0-beta.4",
   "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

@@ -1,4 +1,5 @@
 import {
+  ArrowsOutSimpleIcon,
   ArrowUpIcon,
   CaretRightIcon,
   CheckIcon,
@@ -7,6 +8,7 @@ import {
   MicrophoneIcon,
   PaperclipIcon,
   ShieldWarningIcon,
+  SidebarSimpleIcon,
   StopIcon,
   UploadSimpleIcon,
   WarningCircleIcon,
@@ -40,13 +42,18 @@ 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";
 import { stepGlyph } from "./stepGlyphs";
 import { Markdown } from "./surface/Markdown";
-import type { SurfaceComponents, SurfacePart } from "./surface/scope";
+import { Placed, type PlacedPart } from "./surface/Placed";
+import { placeOf, type SurfacePlaces } from "./surface/places";
+import type { HostBlocks, SurfaceComponents, SurfacePart } from "./surface/scope";
 import { framesItself, Surface, usePlayed } from "./surface/Surface";
 import type { SurfaceAction } from "./surface/values";
 import type {
@@ -122,6 +129,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.
@@ -129,6 +142,13 @@ export interface ChatMessages {
   confirming: string;
   /** The line across the log where the agent handed the conversation to a person. */
   handedOff: string;
+  /**
+   * The line where the agent put what it showed in a panel or a modal, which opens it again:
+   * the agent's name and the surface's title ("Ray opened your week").
+   */
+  opened: (name: string, title: string) => string;
+  /** The button that closes a panel or a modal. */
+  closePlaced: string;
   /**
    * The line across the log where who answers the conversation changed (`handovers`), before
    * why: to whom (`holder`), and who changed it (`by`).
@@ -194,8 +214,14 @@ 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",
+  opened: (name, title) => `${name} opened ${title}`,
+  closePlaced: "Close",
   handover: (holder, by, name) => {
     const automation = by.kind === "automation" ? ` by “${by.title}”` : "";
     switch (holder) {
@@ -234,6 +260,7 @@ export type ChatPart =
   | "sc-chat"
   | "sc-chat--builder"
   | "sc-chat--console"
+  | "sc-chat--placed"
   | "sc-chat__log"
   | "sc-chat__log--channel"
   | "sc-chat__message"
@@ -256,10 +283,15 @@ 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"
   | "sc-chat__handoff"
+  | "sc-chat__placed"
+  | "sc-chat__placed--open"
   | "sc-chat__handover"
   | "sc-chat__decision"
   | "sc-chat__message--heard"
@@ -284,7 +316,7 @@ export type ChatPart =
   | "sc-chat__stop";
 
 type ClassNames =
-  Partial<Record<ChatPart | SurfacePart | KitPart | BrowserPart, string>> | undefined;
+  Partial<Record<ChatPart | SurfacePart | KitPart | BrowserPart | PlacedPart, string>> | undefined;
 
 /**
  * How the chat looks. `agent` is an agent's conversation. `builder` is the builder's, v2's: the
@@ -328,6 +360,13 @@ export interface AgentChatProps {
   classNames?: ClassNames;
   /** The host's own drawing of a block type, for every surface the agent shows. */
   components?: SurfaceComponents | undefined;
+  /** The host's own blocks, by the name each was declared with (`PUT /v1/blocks/{name}`). */
+  blocks?: HostBlocks | undefined;
+  /**
+   * Where the agent may put what it shows besides the conversation: a panel beside it, a modal
+   * over the page (both by default). One the host doesn't allow shows in the conversation.
+   */
+  surfaces?: SurfacePlaces | undefined;
   /** The language of the surfaces' calendars, days, times and numbers; English by default. */
   locale?: KitLocale | undefined;
   /** An error's code, from the socket or `load` for a history that could not be read; the host words it. */
@@ -399,6 +438,86 @@ export interface AgentChatProps {
   onTool?: ToolHandler | undefined;
 }
 
+/** Where nothing is put apart: a conversation on a channel. */
+const NO_PLACES: SurfacePlaces = {};
+
+/**
+ * What the person can still do on the conversation's surfaces: what they did on each, by its id
+ * (each draws its answer), and whether one takes input. A surface takes input while the turn
+ * waits on it or, once nothing runs or waits, when the agent showed it since the person last
+ * spoke; older ones are read, not used. On a channel the person answered there: here it reads.
+ */
+export function surfacesOf(
+  live: Pick<LiveConversation, "messages" | "pending" | "awaiting">,
+  onChannel: boolean,
+): {
+  answers: ReadonlyMap<string, Action>;
+  /** Whether a reply at `index` of the messages is since the person last spoke, all settled. */
+  current: (index: number) => boolean;
+  /** Whether the surface `id`, of the reply at `index`, takes input. */
+  takes: (id: string, index: number) => boolean;
+} {
+  const { messages, pending, awaiting } = live;
+  const idle = !onChannel && !pending && awaiting === null;
+  const lastSaid = messages.findLastIndex((message) => message.role === "user");
+  const answers = new Map<string, Action>();
+  for (const message of messages) {
+    if (message.action) answers.set(message.action.surface, message.action);
+  }
+  const current = (index: number) => idle && index > lastSaid;
+  return {
+    answers,
+    current,
+    takes: (id, index) => (!onChannel && id === awaiting) || current(index),
+  };
+}
+
+/** A step that drew a surface, by its id: the surface, and the index of its reply. */
+function placedStep(
+  messages: readonly Message[],
+  id: string,
+): { step: Step; surface: Shown; index: number } | null {
+  for (const [index, message] of messages.entries()) {
+    const step = message.steps.find((each) => each.id === id);
+    if (step?.surface) return { step, surface: step.surface, index };
+  }
+  return null;
+}
+
+/**
+ * The surface open in a panel or a modal, by its step's id: each one the agent puts apart opens
+ * as it comes, and a conversation that opens waiting on one opens it; one read with the history
+ * waits for its line. Closing it, or opening another, is the person's.
+ */
+function useOpenedPlace(
+  live: Pick<LiveConversation, "messages" | "loading" | "awaiting">,
+  places: SurfacePlaces | undefined,
+): [string | null, (id: string | null) => void] {
+  const [opened, setOpened] = useState<string | null>(null);
+  const ids = live.messages
+    .flatMap((message) => message.steps)
+    .filter((step) => step.surface && placeOf(step.surface, places) !== "chat")
+    .map((step) => step.id);
+  const seen = useRef<Set<string> | null>(null);
+  const key = ids.join(" ");
+  const { loading, awaiting } = live;
+  useEffect(() => {
+    if (loading) return;
+    const known = seen.current;
+    const placed = key === "" ? [] : key.split(" ");
+    if (known === null) {
+      seen.current = new Set(placed);
+      if (awaiting !== null && placed.includes(awaiting)) setOpened(awaiting);
+      return;
+    }
+    const fresh = placed.filter((id) => !known.has(id));
+    for (const id of fresh) known.add(id);
+    const newest = fresh.at(-1);
+    if (newest !== undefined) setOpened(newest);
+  }, [key, loading, awaiting]);
+  return [opened, setOpened];
+}
+
 /** How close to the foot, in pixels, still counts as being at it (v2's). */
 const NEAR_FOOT = 80;
 
@@ -433,6 +552,8 @@ function Chat({
   messages,
   classNames,
   components,
+  blocks,
+  surfaces,
   locale,
   onError,
   actions,
@@ -460,6 +581,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.
@@ -474,6 +596,11 @@ function Chat({
   const { pending } = live;
   // A conversation on a channel: its messages say who said them.
   const onChannel = live.messages.some((message) => message.author != null);
+  // What the agent put in a panel or a modal, where the host allows it (on a channel, nothing:
+  // it went there in the conversation); the one open now.
+  const places = onChannel ? NO_PLACES : surfaces;
+  const [opened, setOpened] = useOpenedPlace(live, places);
+  const open = opened === null ? null : placedStep(live.messages, opened);
 
   // The builder stops on Esc from anywhere on the page, as v2's did; an agent's chat, from inside it.
   const stop = useRef(live.stop);
@@ -493,6 +620,8 @@ function Chat({
 
   const looks: ChatPart[] = builder ? ["sc-chat--builder"] : [];
   if (look === "console") looks.push("sc-chat--console");
+  // A panel open makes room for itself at the chat's right.
+  if (open !== null && placeOf(open.surface, places) === "panel") looks.push("sc-chat--placed");
   const stepsShown = steps === "shown";
 
   return (
@@ -554,6 +683,10 @@ function Chat({
           words={words}
           classNames={classNames}
           components={components}
+          blocks={blocks}
+          places={places}
+          opened={opened}
+          onOpen={setOpened}
           locale={locale}
           following={following}
           took={took}
@@ -565,6 +698,35 @@ function Chat({
           steps={stepsShown}
         />
       )}
+      {open !== null && (
+        <Placed
+          key={open.step.id}
+          where={placeOf(open.surface, places) === "modal" ? "modal" : "panel"}
+          title={open.surface.title ?? ""}
+          closeLabel={words.closePlaced}
+          onClose={() => {
+            setOpened(null);
+          }}
+          classNames={classNames}
+        >
+          <Surface
+            surface={open.surface}
+            active={surfacesOf(live, onChannel).takes(open.step.id, open.index)}
+            answered={surfacesOf(live, onChannel).answers.get(open.step.id)}
+            components={components}
+            blocks={blocks}
+            classNames={classNames}
+            messages={words.kit}
+            locale={locale}
+            files={files}
+            onAction={(action) => {
+              live.act({ surface: open.step.id, ...action });
+              // A modal is for now: once used, the conversation goes on under it.
+              if (placeOf(open.surface, places) === "modal") setOpened(null);
+            }}
+          />
+        </Placed>
+      )}
       {/* The browser the agent drives, over the composer while the conversation has one. */}
       <BrowserView live={live} name={name} messages={words.browser} classNames={classNames} />
       {live.pending && (
@@ -748,8 +910,17 @@ function Log({
   handovers,
   who,
   steps,
+  blocks,
+  places,
+  opened,
+  onOpen,
 }: PartProps & {
   components: SurfaceComponents | undefined;
+  blocks: HostBlocks | undefined;
+  places: SurfacePlaces | undefined;
+  /** The surface open in a panel or a modal, and the way to open one from its line. */
+  opened: string | null;
+  onOpen: (id: string) => void;
   locale: KitLocale | undefined;
   following: RefObject<boolean>;
   took: number | null;
@@ -811,16 +982,7 @@ function Log({
     };
   }, [following]);
 
-  // A surface takes input while the turn waits on it or, once nothing runs or waits, when the
-  // agent showed it since the person last spoke; older ones are read, not used. On a channel the
-  // person answered it there: here it only reads.
-  const idle = !onChannel && !pending && awaiting === null;
-  const lastSaid = messages.findLastIndex((message) => message.role === "user");
-  // What the person did on each surface, by the surface's id: a surface draws its answer.
-  const answers = new Map<string, Action>();
-  for (const message of messages) {
-    if (message.action) answers.set(message.action.surface, message.action);
-  }
+  const { answers, current } = surfacesOf(live, onChannel);
   // Drawn, who answers says where the agent handed it over; otherwise its `escalate` step does.
   const handed = handovers === undefined ? handoffs(messages) : NO_HANDOFFS;
   const placed = handoversAt(messages, handovers ?? []);
@@ -877,14 +1039,19 @@ function Log({
                   message={message}
                   from={carried.current?.id === message.id ? carried.current.from : undefined}
                   awaiting={onChannel ? null : awaiting}
-                  current={idle && index > lastSaid}
+                  current={current(index)}
                   answers={answers}
                   name={name}
                   words={words}
                   classNames={classNames}
                   components={components}
+                  blocks={blocks}
+                  places={places}
+                  opened={opened}
+                  onOpen={onOpen}
                   locale={locale}
                   onAction={live.act}
+                  onActAll={live.actAll}
                   builder={builder}
                   files={files}
                   who={who}
@@ -1234,8 +1401,19 @@ function Reply({
   who,
   steps,
   onChannel,
+  onActAll,
+  blocks,
+  places,
+  opened,
+  onOpen,
 }: DrawProps & {
+  blocks: HostBlocks | undefined;
+  places: SurfacePlaces | undefined;
+  opened: string | null;
+  onOpen: (id: string) => void;
   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 +1429,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)
@@ -1310,35 +1493,71 @@ function Reply({
           ))}
         </ol>
       )}
-      {message.steps.map(
-        (step) =>
-          step.surface && (
-            <div
+      {message.steps.map((step) => {
+        if (!step.surface) return null;
+        const place = placeOf(step.surface, places);
+        if (place !== "chat") {
+          const Glyph = place === "panel" ? SidebarSimpleIcon : ArrowsOutSimpleIcon;
+          return (
+            <button
               key={step.id}
-              part="surface"
+              type="button"
+              part="placed"
+              aria-expanded={opened === step.id}
+              onClick={() => {
+                onOpen(step.id);
+              }}
               className={classes(
                 classNames,
-                "sc-chat__screen",
-                ...(framesItself(step.surface) ? (["sc-chat__screen--bare"] as const) : []),
+                "sc-chat__placed",
+                ...(opened === step.id ? (["sc-chat__placed--open"] as const) : []),
               )}
             >
-              <Surface
-                surface={step.surface}
-                active={step.id === awaiting || current}
-                answered={answers.get(step.id)}
-                components={components}
-                classNames={classNames}
-                messages={words.kit}
-                locale={locale}
-                files={files}
-                onAction={(action) => onAction({ surface: step.id, ...action })}
-              />
-            </div>
-          ),
+              <Glyph aria-hidden />
+              <span>{words.opened(name, step.surface.title ?? "")}</span>
+            </button>
+          );
+        }
+        return (
+          <div
+            key={step.id}
+            part="surface"
+            className={classes(
+              classNames,
+              "sc-chat__screen",
+              ...(framesItself(step.surface) ? (["sc-chat__screen--bare"] as const) : []),
+            )}
+          >
+            <Surface
+              surface={step.surface}
+              active={step.id === awaiting || current}
+              answered={answers.get(step.id)}
+              components={components}
+              blocks={blocks}
+              classNames={classNames}
+              messages={words.kit}
+              locale={locale}
+              files={files}
+              onAction={(action) => onAction({ surface: step.id, ...action })}
+            />
+          </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 +1802,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