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

package/src/AgentSpace.tsx

@@ -17,8 +17,16 @@ import { Button } from "./kit/Button";
 import { KitProvider, type KitPart } from "./kit/context";
 import type { KitLocale } from "./kit/messages";
 import { Modes, type ModeMessages, type ModePart, type SpaceMode } from "./Modes";
-import type { SurfaceComponents, SurfacePart } from "./surface/scope";
+import type { SurfacePlaces } from "./surface/places";
+import type { HostBlocks, 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 +58,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 +73,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 +97,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,13 +137,31 @@ export interface AgentSpaceProps {
   classNames?:
     | Partial<
         Record<
-          SpacePart | ChatPart | SurfacePart | KitPart | BrowserPart | VoiceCallPart | TaskPart,
+          | SpacePart
+          | ChatPart
+          | SurfacePart
+          | KitPart
+          | BrowserPart
+          | VoiceCallPart
+          | TaskPart
+          | ThreadPart,
           string
         >
       >
     | undefined;
   /** 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}`):
+   * `{ "demoprep.deal-card": DealCard }`. One it doesn't give shows its words.
+   */
+  blocks?: HostBlocks | undefined;
+  /**
+   * Where the agent may put what it shows besides the conversation: `panel`, beside it (over it
+   * in a narrow space), and `modal`, over the page; both by default. A place left out shows in
+   * the conversation: `{ panel: true, modal: false }`.
+   */
+  surfaces?: SurfacePlaces | undefined;
   /** The language of the surfaces' calendars, days, times and numbers; English by default. */
   locale?: KitLocale | undefined;
   /** A few things the person might say first, offered while nothing has been said. */
@@ -147,6 +179,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;
 }
 
 /**
@@ -174,6 +212,8 @@ export function AgentSpace({
   messages,
   classNames,
   components,
+  blocks,
+  surfaces,
   locale,
   suggestions,
   onTool,
@@ -181,10 +221,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 +293,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 +387,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}
@@ -342,6 +432,8 @@ export function AgentSpace({
           messages={words.chat}
           classNames={classNames}
           components={components}
+          blocks={blocks}
+          surfaces={surfaces}
           locale={locale}
           suggestions={suggestions}
           steps={steps}

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} />;
+}

package/src/View.tsx

@@ -0,0 +1,117 @@
+import { useEffect, useRef, useState } from "react";
+
+import { classes } from "./classes";
+import { ApiError, type Client } from "./client";
+import type { KitLocale, KitMessages } from "./kit/messages";
+import type { HostBlocks, SurfaceClassNames, SurfaceComponents } from "./surface/scope";
+import { Surface } from "./surface/Surface";
+import type { SurfaceAction } from "./surface/values";
+import type { ViewRendered } from "./types";
+
+/** How often a view is read again while it is shown: the figures move as the rows do. */
+export const VIEW_POLL_MS = 30_000;
+
+/** A view as it was last read: the view once it came, why it failed, or that it isn't there. */
+export interface ViewRead {
+  view: ViewRendered | null;
+  problem: unknown;
+  /** No such view, or not one for this person (404). */
+  gone: boolean;
+}
+
+/**
+ * An agent's view (`name`), rendered for the person the page speaks for (their token: their
+ * own) or, for the business, for the contact it names: read when shown and again every
+ * `VIEW_POLL_MS`, what was read staying while the next read is on its way.
+ */
+export function useView(client: Client, name: string, contact?: string): ViewRead {
+  const key = `${name}\n${contact ?? ""}`;
+  const [read, setRead] = useState<ViewRead & { key: string }>({
+    key,
+    view: null,
+    problem: null,
+    gone: false,
+  });
+  const latest = useRef({ client, name, contact });
+  useEffect(() => {
+    latest.current = { client, name, contact };
+  });
+  useEffect(() => {
+    let stopped = false;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const load = async () => {
+      const now = latest.current;
+      try {
+        const view = await now.client.views.render(now.name, now.contact);
+        if (stopped) return;
+        setRead({ key, view, problem: null, gone: false });
+      } catch (error) {
+        if (stopped) return;
+        const gone = error instanceof ApiError && error.status === 404;
+        setRead((last) => ({ ...last, key, problem: gone ? null : error, gone }));
+      }
+      if (!stopped) timer = setTimeout(() => void load(), VIEW_POLL_MS);
+    };
+    void load();
+    return () => {
+      stopped = true;
+      clearTimeout(timer);
+    };
+  }, [client, key]);
+  // Another view's read is not this one's: until its own comes, nothing is shown.
+  return read.key === key ? read : { view: null, problem: null, gone: false };
+}
+
+export interface ViewProps {
+  client: Client;
+  /** The view's name, as its agent or the business wrote it (`proxima_reunion`). */
+  name: string;
+  /** For the business: the contact it is rendered for (their id). A person's token: their own. */
+  contact?: string | undefined;
+  /** The host's own blocks, by the name each was declared with. */
+  blocks?: HostBlocks | undefined;
+  /** The host's own drawing of a block type. */
+  components?: SurfaceComponents | undefined;
+  classNames?: SurfaceClassNames;
+  /** The words of its blocks, in the host's language; English by default. */
+  messages?: Partial<KitMessages> | undefined;
+  /** The language of its days, times and numbers; English by default. */
+  locale?: KitLocale | undefined;
+  /** What the person does on a host's block that sends something; without it, they only read. */
+  onAction?: ((action: SurfaceAction) => void) | undefined;
+}
+
+/**
+ * An agent's view where the host's page puts it (a rep's next meeting on its home, their week
+ * beside a record), drawn with the kit's blocks in the host's style, live: read again every half
+ * minute, so it shows what the rows hold now, never a copy. While it is first read, an empty
+ * box holds its place; a view that isn't there (or isn't the person's) draws nothing.
+ */
+export function View({
+  client,
+  name,
+  contact,
+  blocks,
+  components,
+  classNames,
+  messages,
+  locale,
+  onAction,
+}: ViewProps) {
+  const { view } = useView(client, name, contact);
+  if (view === null) {
+    return <div aria-busy="true" className={`sc ${classes(classNames, "sc-surface")}`} />;
+  }
+  return (
+    <Surface
+      surface={{ blocks: view.blocks, text: view.text }}
+      active={onAction !== undefined}
+      onAction={onAction ?? (() => undefined)}
+      blocks={blocks}
+      components={components}
+      classNames={classNames}
+      messages={messages}
+      locale={locale}
+    />
+  );
+}

package/src/automation/marks.tsx

@@ -1,4 +1,5 @@
 import {
+  ArrowBendDownRightIcon,
   BellIcon,
   BrainIcon,
   ChatCircleIcon,
@@ -8,7 +9,9 @@ import {
   FileTextIcon,
   FlaskIcon,
   GlobeIcon,
+  HandTapIcon,
   LightningIcon,
+  PlugsConnectedIcon,
   SparkleIcon,
   TableIcon,
   WebhooksLogoIcon,
@@ -52,6 +55,8 @@ const KINDS: Readonly<Record<Exclude<Trigger["kind"], "event">, Icon>> = {
   schedule: ClockIcon,
   webhook: WebhooksLogoIcon,
   platform: ChatCircleIcon,
+  manual: HandTapIcon,
+  after: ArrowBendDownRightIcon,
 };
 
 /** What starts an automation, as a mark: a clock, a webhook, a message, the app whose event it
@@ -79,6 +84,8 @@ const BY: Readonly<Record<Exclude<RunBy, "event">, Icon>> = {
   platform: ChatCircleIcon,
   agent: ChatCircleIcon,
   test: FlaskIcon,
+  api: PlugsConnectedIcon,
+  after: ArrowBendDownRightIcon,
 };
 
 export function ByMark({

package/src/automation/messages.ts

@@ -68,6 +68,10 @@ export interface AutomationMessages {
   event: (app: string | null, event: string | null) => string;
   /** One of the platform's events: a contact's message stored on a channel. */
   platform: string;
+  /** Only started by hand: the agent, the business's app, a button. */
+  manual: string;
+  /** When another of the agent's automations ends well, by its name. */
+  after: (automation: string | null) => string;
   /** When it runs next, after when it runs: the day, and the time when the line doesn't say it. */
   next: (day: DayRef, time: string | null) => string;
   /** How it stands, on its pill. */
@@ -127,6 +131,8 @@ export const AUTOMATION_MESSAGES: AutomationMessages = {
   custom: "On a schedule of its own",
   webhook: "When another system calls it",
   platform: "When a message arrives",
+  manual: "When someone starts it",
+  after: (automation) => (automation ? `After “${automation}”` : "After another automation"),
   event: (app, event) =>
     event ? `When ${event} in ${app ?? "an app"}` : `On an event in ${app ?? "an app"}`,
   next: (day, time) => {
@@ -177,6 +183,8 @@ export const AUTOMATION_MESSAGES: AutomationMessages = {
       platform: "a message",
       agent: "you asked in the chat",
       test: "test",
+      api: "your app",
+      after: "after another",
     })[by],
   statuses: {
     running: "Running",

package/src/automation/when.ts

@@ -35,6 +35,10 @@ export function whenOf(trigger: Trigger, words: AutomationMessages, code: string
       return { text: words.webhook, timed: false };
     case "platform":
       return { text: words.platform, timed: false };
+    case "manual":
+      return { text: words.manual, timed: false };
+    case "after":
+      return { text: words.after(trigger.after ?? null), timed: false };
     case "event":
       return {
         text: words.event(trigger.app_title ?? trigger.app, trigger.event_title),