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

package/package.json

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

@@ -1,4 +1,5 @@
 import {
+  ArrowsOutSimpleIcon,
   ArrowUpIcon,
   CaretRightIcon,
   CheckIcon,
@@ -7,6 +8,7 @@ import {
   MicrophoneIcon,
   PaperclipIcon,
   ShieldWarningIcon,
+  SidebarSimpleIcon,
   StopIcon,
   UploadSimpleIcon,
   WarningCircleIcon,
@@ -49,7 +51,9 @@ 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 {
@@ -138,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`).
@@ -209,6 +220,8 @@ export const CHAT_MESSAGES: ChatMessages = {
   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) {
@@ -247,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"
@@ -276,6 +290,8 @@ export type ChatPart =
   | "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"
@@ -300,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
@@ -344,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. */
@@ -415,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;
 
@@ -449,6 +552,8 @@ function Chat({
   messages,
   classNames,
   components,
+  blocks,
+  surfaces,
   locale,
   onError,
   actions,
@@ -491,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);
@@ -510,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 (
@@ -571,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}
@@ -582,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 && (
@@ -765,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;
@@ -828,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 ?? []);
@@ -894,12 +1039,16 @@ 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}
@@ -1253,7 +1402,15 @@ function Reply({
   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;
@@ -1336,32 +1493,56 @@ 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()}

package/src/AgentSpace.tsx

@@ -17,7 +17,8 @@ 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,
@@ -150,6 +151,17 @@ export interface AgentSpaceProps {
     | 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. */
@@ -200,6 +212,8 @@ export function AgentSpace({
   messages,
   classNames,
   components,
+  blocks,
+  surfaces,
   locale,
   suggestions,
   onTool,
@@ -418,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/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/blocks.ts

@@ -124,6 +124,88 @@ export interface ConnectBlock {
   connection: ConnectView | null;
 }
 
+// --- Time and work ------------------------------------------------------------------------
+
+/**
+ * One thing on a calendar: its title at its time ("YYYY-MM-DDTHH:MM" in the person's time; a day
+ * alone, "YYYY-MM-DD", is all of it), until `end`, with a line of detail and a page to open.
+ */
+export interface CalendarEvent {
+  id: string;
+  title: string;
+  start: string;
+  end?: string;
+  detail?: string;
+  /** https only. */
+  url?: string;
+}
+
+/**
+ * A day's events, or a week's from `start` ("YYYY-MM-DD"), in their order. With `action`,
+ * pressing one sends it with `{event: id}`; one with `url` opens its page instead.
+ */
+export interface CalendarBlock {
+  type: "calendar";
+  span: "day" | "week";
+  start: string;
+  events: CalendarEvent[];
+  action?: string;
+}
+
+/** One thing on a timeline: when, what, a line about it, where it stands in a word, its mark. */
+export interface TimelineItem {
+  id?: string;
+  at: string;
+  title: string;
+  text?: string;
+  status?: string;
+  tone?: Tone;
+}
+
+/** Dated things, one under another, the newest first. */
+export interface TimelineBlock {
+  type: "timeline";
+  items: TimelineItem[];
+}
+
+export interface BoardCard {
+  id: string;
+  title: string;
+  subtitle?: string;
+  /** At its foot: a price, a day, who. */
+  meta?: string;
+}
+
+export interface BoardColumn {
+  id: string;
+  title: string;
+  cards: BoardCard[];
+}
+
+/**
+ * Cards in columns, a column per stage. With `action`, the person moves a card to another column,
+ * which sends `action` with `{card, column}`.
+ */
+export interface BoardBlock {
+  type: "board";
+  columns: BoardColumn[];
+  action?: string;
+}
+
+// --- The host's own -----------------------------------------------------------------------
+
+/**
+ * One of the host's own blocks, by the name it declared (`PUT /v1/blocks/{name}`): its `props`,
+ * checked by the API against the schema the host declared, and `text`, the same in words, which a
+ * page that doesn't draw it shows instead.
+ */
+export interface HostBlock {
+  type: "host";
+  name: string;
+  props: Record<string, unknown>;
+  text: string;
+}
+
 // --- Action -------------------------------------------------------------------------------
 
 /** One thing the person can do: pressing it sends `action`, or, with `url`, opens that page. */
@@ -265,10 +347,26 @@ export type Block =
   | ConnectBlock
   | ButtonBlock
   | ChoiceBlock
-  | FormBlock;
+  | FormBlock
+  | CalendarBlock
+  | TimelineBlock
+  | BoardBlock
+  | HostBlock;
 
-/** What the agent shows: blocks, and the words a channel without a screen gets instead. */
+/**
+ * Where a surface shows in a page: in the conversation, in a panel beside it, or in a modal over
+ * it. A page that doesn't allow the place shows it in the conversation.
+ */
+export type Place = "chat" | "panel" | "modal";
+
+/**
+ * What the agent shows: blocks, and the words a channel without a screen gets instead; where it
+ * shows and, in a panel or a modal, its title, which the conversation's line to open it says.
+ */
 export interface Surface {
   blocks: Block[];
   text: string;
+  /** None: the conversation. */
+  where?: Place;
+  title?: string;
 }