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

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

@@ -496,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/widget/element.tsx

@@ -8,6 +8,8 @@ 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";
@@ -32,6 +34,7 @@ const ATTRIBUTES = [
   "unstyled",
   "shadow",
   "contained",
+  "surfaces",
 ] as const;
 
 type Attribute = (typeof ATTRIBUTES)[number];
@@ -59,6 +62,11 @@ 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. */
@@ -109,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
@@ -242,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;
 }
 
 /**
@@ -249,8 +267,8 @@ 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]);
@@ -277,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={
@@ -346,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. */
@@ -372,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);
@@ -530,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} />
+      ),
     );
   }
 }