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

package/src/surface/Placed.tsx

@@ -0,0 +1,98 @@
+import { XIcon } from "@phosphor-icons/react";
+import { useEffect, useRef, type KeyboardEvent, type ReactNode } from "react";
+
+import { classes } from "../classes";
+import { Button } from "../kit/Button";
+
+/** The parts of a surface shown apart from the conversation, by the class each carries. */
+export type PlacedPart =
+  | "sc-placed"
+  | "sc-placed--panel"
+  | "sc-placed--modal"
+  | "sc-placed__head"
+  | "sc-placed__title"
+  | "sc-placed__body";
+
+/**
+ * A surface the agent put apart from the conversation, tied to it all the same: in a `panel` that
+ * stands beside the conversation (over it where there is no room), or in a `modal` over the page,
+ * whose backdrop, Escape or cross close it. Its title heads it; closed, the conversation's line
+ * opens it again.
+ */
+export function Placed({
+  where,
+  title,
+  closeLabel,
+  onClose,
+  classNames,
+  children,
+}: {
+  where: "panel" | "modal";
+  title: string;
+  closeLabel: string;
+  onClose: () => void;
+  classNames: Partial<Record<PlacedPart, string>> | undefined;
+  children: ReactNode;
+}) {
+  const dialog = useRef<HTMLDialogElement>(null);
+  useEffect(() => {
+    const opened = dialog.current;
+    if (opened === null) return undefined;
+    // jsdom has no top layer: a dialog there is only shown.
+    if (typeof opened.showModal === "function") opened.showModal();
+    else opened.setAttribute("open", "");
+    return () => {
+      if (typeof opened.close === "function") opened.close();
+    };
+  }, []);
+  const head = (
+    <header className={classes(classNames, "sc-placed__head")}>
+      <h2 className={classes(classNames, "sc-placed__title")}>{title}</h2>
+      <Button
+        tone="ghost"
+        size="sm"
+        icon={XIcon}
+        aria-label={closeLabel}
+        title={closeLabel}
+        onClick={onClose}
+      />
+    </header>
+  );
+  // Escape closes this, not the reply the conversation is writing.
+  const onKeyDown = (event: KeyboardEvent) => {
+    if (event.key !== "Escape") return;
+    event.stopPropagation();
+    if (where === "panel") onClose();
+  };
+  const body = <div className={classes(classNames, "sc-placed__body")}>{children}</div>;
+  if (where === "panel") {
+    return (
+      <aside
+        part="placed panel"
+        aria-label={title}
+        onKeyDown={onKeyDown}
+        className={classes(classNames, "sc-placed", "sc-placed--panel")}
+      >
+        {head}
+        {body}
+      </aside>
+    );
+  }
+  return (
+    <dialog
+      ref={dialog}
+      part="placed modal"
+      aria-label={title}
+      onKeyDown={onKeyDown}
+      onClose={onClose}
+      // A press on the backdrop (the dialog itself, outside its box) closes it.
+      onClick={(event) => {
+        if (event.target === event.currentTarget) onClose();
+      }}
+      className={`sc ${classes(classNames, "sc-placed", "sc-placed--modal")}`}
+    >
+      {head}
+      {body}
+    </dialog>
+  );
+}

package/src/surface/Surface.tsx

@@ -5,10 +5,13 @@ import { Automation } from "../automation/Automation";
 import type {
   AutomationBlock,
   Block,
+  BoardBlock,
   ButtonBlock,
+  CalendarBlock,
   ChoiceBlock,
   ConnectBlock,
   FieldsBlock,
+  HostBlock,
   ImageBlock,
   ListBlock,
   Surface as Shown,
@@ -18,6 +21,8 @@ import { classes } from "../classes";
 import { Button } from "../kit/Button";
 import { formatSize } from "../about";
 import { baseName } from "../files";
+import { Agenda } from "../kit/Agenda";
+import { Kanban } from "../kit/Kanban";
 import { Card } from "../kit/Card";
 import { Chart } from "../kit/Chart";
 import { KitProvider, useKit, useParts } from "../kit/context";
@@ -29,6 +34,7 @@ import type { FileHost } from "../kit/uploads";
 import { AudioPlayer } from "../kit/AudioPlayer";
 import { Note } from "../kit/Note";
 import { Stat } from "../kit/Stat";
+import { Timeline } from "../kit/Timeline";
 import type { Attachment, FileBlock } from "../types";
 import { FormView } from "./Form";
 import { Markdown } from "./Markdown";
@@ -36,6 +42,8 @@ import {
   ScopeContext,
   useScope,
   useSurfaceParts,
+  type HostBlockProps,
+  type HostBlocks,
   type Scope,
   type SurfaceClassNames,
   type SurfaceComponents,
@@ -50,6 +58,8 @@ export interface SurfaceProps {
   /** What the person already did on it: the option picked, the button pressed, the form sent. */
   answered?: SurfaceAction | undefined;
   components?: SurfaceComponents | undefined;
+  /** The host's own blocks, by the name each was declared with. */
+  blocks?: HostBlocks | undefined;
   classNames?: SurfaceClassNames;
   /** The words its controls say, in the host's language; English by default. */
   messages?: Partial<KitMessages> | undefined;
@@ -80,6 +90,10 @@ const BLOCKS: ReadonlySet<string> = new Set([
   "button",
   "choice",
   "form",
+  "calendar",
+  "timeline",
+  "board",
+  "host",
 ]);
 
 /** Whether every block down the tree, and every field of its forms, is one this renderer draws. */
@@ -116,12 +130,13 @@ export function Surface({
   active = true,
   answered,
   components,
+  blocks,
   classNames,
   messages,
   locale,
   files,
 }: SurfaceProps) {
-  const scope: Scope = { active, answered, onAction, components, classNames, files };
+  const scope: Scope = { active, answered, onAction, components, blocks, classNames, files };
   return (
     <KitProvider classNames={classNames} messages={messages} locale={locale}>
       <ScopeContext value={scope}>
@@ -227,9 +242,85 @@ function Draw({ block }: { block: Block }) {
       return <Choice block={block} />;
     case "form":
       return <FormView block={block} />;
+    case "calendar":
+      return <CalendarShown block={block} />;
+    case "timeline":
+      return <Timeline items={block.items} />;
+    case "board":
+      return <BoardShown block={block} />;
+    case "host":
+      return <Hosted block={block} />;
   }
 }
 
+/** A calendar; with its action, pressing an event sends it (`{event}`). */
+function CalendarShown({ block }: { block: CalendarBlock }) {
+  const { active, onAction } = useScope();
+  const { action } = block;
+  return (
+    <Agenda
+      span={block.span}
+      start={block.start}
+      events={block.events}
+      disabled={!active}
+      onEvent={
+        action === undefined
+          ? undefined
+          : (event) => {
+              onAction({ name: action, data: { event: event.id }, label: event.title });
+            }
+      }
+    />
+  );
+}
+
+/** A board; with its action, a card moved to another column sends it (`{card, column}`). */
+function BoardShown({ block }: { block: BoardBlock }) {
+  const { active, onAction } = useScope();
+  const { messages } = useKit();
+  const { action } = block;
+  return (
+    <Kanban
+      columns={block.columns}
+      disabled={!active}
+      onMove={
+        action === undefined
+          ? undefined
+          : (card, column) => {
+              onAction({
+                name: action,
+                data: { card: card.id, column: column.id },
+                label: messages.board.moved(card.title, column.title),
+              });
+            }
+      }
+    />
+  );
+}
+
+/**
+ * One of the host's own blocks, drawn by the component it registered under the block's name; a
+ * name it gave none for, or a component that fails as it draws, leaves the block's words in a
+ * quiet card in its place, and the rest of the surface draws.
+ */
+function Hosted({ block }: { block: HostBlock }) {
+  const { blocks, active, onAction } = useScope();
+  const part = useSurfaceParts();
+  const twin = (
+    <div part="host" className={part("sc-surface__host")} data-block={block.name}>
+      <Markdown text={block.text} />
+    </div>
+  );
+  // Registered under this name, for these props: the API checked them against its schema.
+  const Own = blocks?.[block.name] as ComponentType<HostBlockProps> | undefined;
+  if (Own === undefined) return twin;
+  return (
+    <Whole twin={twin}>
+      <Own props={block.props} text={block.text} active={active} onAction={onAction} />
+    </Whole>
+  );
+}
+
 /**
  * A file the agent put in front of the person, compact: its kind's mark, its title (its name
  * under it when the title is another), its size at the right; pressed, it opens whole in the

package/src/surface/places.ts

@@ -0,0 +1,19 @@
+import type { Place, Surface } from "../blocks";
+
+/**
+ * Where a host lets the agent put what it shows besides the conversation: a panel beside it, a
+ * modal over the page. A place it doesn't allow shows in the conversation.
+ */
+export interface SurfacePlaces {
+  panel?: boolean | undefined;
+  modal?: boolean | undefined;
+}
+
+/** Both, unless the host says otherwise. */
+export const EVERY_PLACE: SurfacePlaces = { panel: true, modal: true };
+
+/** Where a surface shows in this page: the place the agent chose when the host allows it. */
+export function placeOf(surface: Surface, places: SurfacePlaces = EVERY_PLACE): Place {
+  const where = surface.where ?? "chat";
+  return where !== "chat" && places[where] === true ? where : "chat";
+}

package/src/surface/scope.ts

@@ -30,7 +30,8 @@ export type SurfacePart =
   | "sc-surface__foot"
   | "sc-surface__sent"
   | "sc-surface__connect"
-  | "sc-surface__connect--done";
+  | "sc-surface__connect--done"
+  | "sc-surface__host";
 
 export type SurfaceClassNames = Partial<Record<SurfacePart | KitPart, string>> | undefined;
 
@@ -52,6 +53,25 @@ export type BlockProps<Type extends Block["type"]> = Omit<
 /** The host's own drawing of a block type, in place of the package's: `{ table: TheirTable }`. */
 export type SurfaceComponents = { [Type in Block["type"]]?: ComponentType<BlockProps<Type>> };
 
+/**
+ * What a host's own block receives (`HostBlocks`): its `props`, as the API checked them against
+ * the schema the host declared; `text`, the same in words; whether the surface still takes
+ * input, and `onAction` to send what the person did with it, as any block does.
+ */
+export interface HostBlockProps<Props = Record<string, unknown>> {
+  props: Props;
+  text: string;
+  active: boolean;
+  onAction: (action: SurfaceAction) => void;
+}
+
+/**
+ * The host's own blocks, by the name it declared each with (`PUT /v1/blocks/{name}`):
+ * `{ "demoprep.deal-card": DealCard }`. A block of a name it doesn't give shows its words.
+ */
+// `never`: a component typed for its own props (`HostBlockProps<Deal>`) takes its place.
+export type HostBlocks = Readonly<Record<string, ComponentType<HostBlockProps<never>>>>;
+
 /** What every block of one surface shares: whether it takes input, what was done on it. */
 export interface Scope {
   active: boolean;
@@ -59,6 +79,8 @@ export interface Scope {
   answered: SurfaceAction | undefined;
   onAction: (action: SurfaceAction) => void;
   components: SurfaceComponents | undefined;
+  /** The host's own blocks, by name. */
+  blocks: HostBlocks | undefined;
   classNames: SurfaceClassNames;
   /** Where its file fields' files go and are found; none: they take none. */
   files: FileHost | undefined;
@@ -69,6 +91,7 @@ export const ScopeContext = createContext<Scope>({
   answered: undefined,
   onAction: () => undefined,
   components: undefined,
+  blocks: undefined,
   classNames: undefined,
   files: undefined,
 });

package/src/types.ts

@@ -90,6 +90,12 @@ export interface Conversation {
    * host's app (`host_person`, its `contact` then) or the widget's visitor.
    */
   person?: ConversationPerson | null | undefined;
+  /**
+   * For the person it is with: how many of the business's messages came since they last read it,
+   * and whether it waits on them (a question, their yes); left out by an older API.
+   */
+  unread?: number | undefined;
+  waiting_on_person?: boolean | undefined;
 }
 
 /** Who a person's token or a publishable key started a conversation for. */
@@ -237,6 +243,8 @@ export interface Request {
   input: Record<string, unknown>;
   /** The person's when left out (an API from before it). */
   decides?: Decides | undefined;
+  /** The JSON Schema of its input, which an edit given with the yes must fit. */
+  schema?: Record<string, unknown> | null | undefined;
 }
 
 /** An action a reply called: what, how it went, and what it drew. */
@@ -306,6 +314,9 @@ export interface Message {
   heard?: string | null | undefined;
   /** On a channel, a person's message: what was decided of it; null otherwise. */
   decision?: Decision | null | undefined;
+  /** The agent's words first, without a turn of the person's, and the run whose code sent them. */
+  proactive?: boolean | undefined;
+  run_id?: string | null | undefined;
   created_at: string;
 }
 
@@ -485,6 +496,19 @@ export interface FileBlock {
   file: Attachment | null;
 }
 
+/**
+ * An agent's view rendered for one contact (`GET /views/{name}/render`): its blocks as the kit
+ * draws them, filled from the rows when it was read, and `text`, the same in words.
+ */
+export interface ViewRendered {
+  name: string;
+  title: string;
+  contact_id: string;
+  blocks: Surface["blocks"];
+  text: string;
+  rendered_at: string;
+}
+
 /** Who holds the conversation's browser: the agent drives it, or the person does. */
 export type BrowserControl = "agent" | "person";
 

package/src/useConversation.ts

@@ -444,6 +444,8 @@ export interface LiveConversation {
   say: (text: string, files?: readonly string[]) => boolean;
   /** What the person did on a surface; false when the socket is closed. */
   act: (action: Action) => boolean;
+  /** Several things done at once (a yes or no on each call a reply waits on), sent together. */
+  actAll: (actions: readonly Action[]) => boolean;
   /** Stops the reply on its way; false when the socket is closed. */
   stop: () => boolean;
   /** The conversation's browser while it is open: where it is, who holds it. */
@@ -605,6 +607,13 @@ export function useConversation(
     return true;
   };
 
+  const actAll = (actions: readonly Action[]): boolean => {
+    const sent = actions.map((one) => ({ type: "action" as const, ...one }));
+    if (!live.send({ type: "actions", actions: sent })) return false;
+    for (const action of actions) dispatch({ type: "acted", action });
+    return true;
+  };
+
   return {
     messages: state.messages,
     draft: state.draft,
@@ -615,6 +624,7 @@ export function useConversation(
     error: state.error,
     say,
     act,
+    actAll,
     stop: () => live.send({ type: "stop" }),
     browser: state.browser,
     watchScreen: screen.watch,

package/src/widget/element.tsx

@@ -5,8 +5,11 @@ import { createRoot, type Root } from "react-dom/client";
 
 import type { ChatSteps } from "../AgentChat";
 import { AgentSpace, SPACE_MESSAGES } from "../AgentSpace";
+import { useUnread } from "../Threads";
 import { createClient } from "../client";
 import type { Credentials } from "../credentials";
+import type { SurfacePlaces } from "../surface/places";
+import type { HostBlocks } from "../surface/scope";
 import { SPACE_MESSAGES_ES } from "../es";
 import { es } from "../locale";
 import styles from "../styles.css?inline";
@@ -31,6 +34,7 @@ const ATTRIBUTES = [
   "unstyled",
   "shadow",
   "contained",
+  "surfaces",
 ] as const;
 
 type Attribute = (typeof ATTRIBUTES)[number];
@@ -58,12 +62,19 @@ export interface WidgetSettings {
   steps: ChatSteps | undefined;
   /** Floating within the element's own box (`contained`), not at the page's corner: a preview. */
   contained: boolean;
+  /**
+   * Where the agent may put what it shows besides the conversation (`surfaces`: `"panel modal"`,
+   * either, or `""` for neither); both unless the page says.
+   */
+  surfaces: SurfacePlaces | undefined;
 }
 
 /** The launcher's words, by language. */
-const LAUNCHER: Readonly<Record<Language, { open: string; close: string; chat: string }>> = {
-  en: { open: "Open the chat", close: "Close the chat", chat: "Chat" },
-  es: { open: "Abrir el chat", close: "Cerrar el chat", chat: "Chat" },
+const LAUNCHER: Readonly<
+  Record<Language, { open: string; close: string; chat: string; news: string }>
+> = {
+  en: { open: "Open the chat", close: "Close the chat", chat: "Chat", news: "something new" },
+  es: { open: "Abrir el chat", close: "Cerrar el chat", chat: "Chat", news: "hay novedades" },
 };
 
 /**
@@ -106,9 +117,17 @@ export function settingsOf(element: Element): WidgetSettings | null {
     header: on(element, "header"),
     steps: steps === "shown" || steps === "hidden" ? steps : undefined,
     contained: on(element, "contained"),
+    surfaces: placesOf(element.getAttribute("surfaces")),
   };
 }
 
+/** The places a `surfaces` attribute names (`"panel modal"`); none given: the default, both. */
+export function placesOf(named: string | null): SurfacePlaces | undefined {
+  if (named === null) return undefined;
+  const places = new Set(named.trim().toLowerCase().split(/\s+/));
+  return { panel: places.has("panel"), modal: places.has("modal") };
+}
+
 /**
  * A look as the widget's own stylesheet: its tokens on the host (`:host` in its shadow root, the
  * element itself when drawn into the page), where the page's own rules for the element still
@@ -239,6 +258,8 @@ function stylePage() {
 export interface WidgetProps {
   settings: WidgetSettings & { agent: string };
   look?: WidgetLook | null | undefined;
+  /** The page's own blocks, by name (the element's `blocks`). */
+  blocks?: HostBlocks | undefined;
 }
 
 /**
@@ -246,14 +267,19 @@ export interface WidgetProps {
  * page's corner (the left one if its look says so), or (`inline`) in the page's flow at the
  * element's size. The conversation it opens is kept in the page's storage for the next visit.
  */
-export function Widget({ settings, look = null }: WidgetProps) {
-  const { baseUrl, agent, credential, language, mode, steps, contained } = settings;
+export function Widget({ settings, look = null, blocks }: WidgetProps) {
+  const { baseUrl, agent, credential, language, mode, steps, contained, surfaces } = settings;
   const signedAs = credential.token ?? credential.publishableKey ?? "cookie";
   // One client while the page says the same; a new token (the host's, renewed) makes another.
   const client = useMemo(() => createClient({ baseUrl, ...credential }), [baseUrl, signedAs]);
   const [open, setOpen] = useState(false);
   const words = LAUNCHER[language];
   const floating = mode === "floating";
+  // While closed, a dot on the launcher says something waits (an unread message, a question), for
+  // someone who talked before: nobody new is asked after until they open it.
+  const returning = keptConversation(agent) !== undefined;
+  const news = useUnread(client, agent, floating && !open && returning && client.who === "person");
+  const waits = news.unread > 0 || news.waiting;
   const header = settings.header || look?.header === true;
 
   const space = (
@@ -269,6 +295,8 @@ export function Widget({ settings, look = null }: WidgetProps) {
         layout={floating ? "compact" : "full"}
         header={header}
         steps={steps}
+        surfaces={surfaces}
+        blocks={blocks}
         messages={language === "es" ? SPACE_MESSAGES_ES : SPACE_MESSAGES}
         locale={language === "es" ? es : undefined}
         onClose={
@@ -295,7 +323,7 @@ export function Widget({ settings, look = null }: WidgetProps) {
       <button
         type="button"
         part="launcher"
-        aria-label={open ? words.close : words.open}
+        aria-label={open ? words.close : waits ? `${words.open}: ${words.news}` : words.open}
         aria-expanded={open}
         onClick={() => {
           setOpen(!open);
@@ -307,6 +335,7 @@ export function Widget({ settings, look = null }: WidgetProps) {
         ) : (
           <ChatCircleDotsIcon aria-hidden weight="fill" />
         )}
+        {!open && waits && <span aria-hidden className="sc-widget__dot" />}
       </button>
     </div>
   );
@@ -337,6 +366,8 @@ export class SignalCoreChat extends HTMLElement {
   #lookSheet: HTMLStyleElement | null = null;
   /** The look set on the element, over its channel's. */
   #look: WidgetLook | null = null;
+  /** The page's own blocks, by name. */
+  #blocks: HostBlocks | undefined = undefined;
   /** The web channel its publishable key belongs to, as read for that key (null while read). */
   #channel: { key: string; config: WidgetConfig | null } | null = null;
   /** The page's type and ink as last given to the widget. */
@@ -363,6 +394,20 @@ export class SignalCoreChat extends HTMLElement {
     this.#draw();
   }
 
+  /**
+   * The page's own blocks, by the name each was declared with (`PUT /v1/blocks/{name}`), set as
+   * a property: `chat.blocks = { "demoprep.deal-card": DealCard }`, React components the
+   * widget's React draws. One it doesn't give shows its words.
+   */
+  get blocks(): HostBlocks | undefined {
+    return this.#blocks;
+  }
+
+  set blocks(value: HostBlocks | undefined) {
+    this.#blocks = value;
+    this.#draw();
+  }
+
   connectedCallback() {
     this.#mount ??= this.#build();
     this.#root = createRoot(this.#mount);
@@ -521,7 +566,9 @@ export class SignalCoreChat extends HTMLElement {
     }
     const agent = settings?.agent ?? config?.agent_id ?? null;
     this.#root.render(
-      settings && agent && <Widget settings={{ ...settings, agent }} look={this.#worn} />,
+      settings && agent && (
+        <Widget settings={{ ...settings, agent }} look={this.#worn} blocks={this.#blocks} />
+      ),
     );
   }
 }

package/src/widget/widget.css

@@ -104,6 +104,19 @@ signalcore-chat[shadow="none"][mode="inline"] {
   height: 46%;
 }
 
+/* While the chat is closed and something waits in it (an unread message, a question): a dot at
+   the launcher's corner, ringed in the page's surface so it reads on the accent. */
+.sc-widget__dot {
+  position: absolute;
+  top: 6%;
+  right: 6%;
+  width: 22%;
+  height: 22%;
+  border: 2px solid var(--_surface);
+  border-radius: var(--_radius-full);
+  background: var(--_danger);
+}
+
 .sc-widget--floating > .sc-widget__panel {
   position: fixed;
   right: var(--_offset);