@signalcore/ui 0.1.0 → 1.0.0-beta.1

package/src/surface/Surface.tsx

@@ -0,0 +1,605 @@
+import { ArrowUpIcon, CheckIcon, PencilSimpleIcon } from "@phosphor-icons/react";
+import { Component, useEffect, useRef, useState, type ComponentType, type ReactNode } from "react";
+
+import { Automation } from "../automation/Automation";
+import type {
+  AutomationBlock,
+  Block,
+  ButtonBlock,
+  ChoiceBlock,
+  FieldsBlock,
+  ImageBlock,
+  ListBlock,
+  Surface as Shown,
+  TableBlock,
+} from "../blocks";
+import { classes } from "../classes";
+import { Button } from "../kit/Button";
+import { formatSize } from "../about";
+import { baseName } from "../files";
+import { Card } from "../kit/Card";
+import { Chart } from "../kit/Chart";
+import { KitProvider, useKit, useParts } from "../kit/context";
+import { FileMark } from "../kit/FileMark";
+import { List, Row } from "../kit/List";
+import { Mark } from "../kit/Mark";
+import type { KitLocale, KitMessages } from "../kit/messages";
+import type { FileHost } from "../kit/uploads";
+import { AudioPlayer } from "../kit/AudioPlayer";
+import { Note } from "../kit/Note";
+import { Stat } from "../kit/Stat";
+import type { Attachment, FileBlock } from "../types";
+import { FormView } from "./Form";
+import { Markdown } from "./Markdown";
+import {
+  ScopeContext,
+  useScope,
+  useSurfaceParts,
+  type Scope,
+  type SurfaceClassNames,
+  type SurfaceComponents,
+} from "./scope";
+import { answeredIn, chosen, FIELD_KINDS, picked, pressed, type SurfaceAction } from "./values";
+
+export interface SurfaceProps {
+  surface: Shown;
+  onAction: (action: SurfaceAction) => void;
+  /** False draws the inputs disabled: a surface already answered, or one from an older turn. */
+  active?: boolean | undefined;
+  /** What the person already did on it: the option picked, the button pressed, the form sent. */
+  answered?: SurfaceAction | undefined;
+  components?: SurfaceComponents | undefined;
+  classNames?: SurfaceClassNames;
+  /** The words its controls say, in the host's language; English by default. */
+  messages?: Partial<KitMessages> | undefined;
+  /** The language of its calendar, days, times and numbers; English by default. */
+  locale?: KitLocale | undefined;
+  /**
+   * Where its file fields' files go (uploaded as they are picked) and how the ones sent are found
+   * and opened: the conversation's. None: a file field takes no files.
+   */
+  files?: FileHost | undefined;
+}
+
+const BLOCKS: ReadonlySet<string> = new Set([
+  "card",
+  "stack",
+  "divider",
+  "text",
+  "fields",
+  "table",
+  "list",
+  "stat",
+  "chart",
+  "note",
+  "image",
+  "automation",
+  "file",
+  "button",
+  "choice",
+  "form",
+]);
+
+/** Whether every block down the tree, and every field of its forms, is one this renderer draws. */
+export function known(blocks: Block[]): boolean {
+  return blocks.every((block) => {
+    if (!BLOCKS.has(block.type)) return false;
+    if (block.type === "form") return block.fields.every((field) => FIELD_KINDS.has(field.kind));
+    return "children" in block ? known(block.children) : true;
+  });
+}
+
+/**
+ * Whether a screen draws its own edge: one that is a single card (or an automation, a card of
+ * its own) needs no panel around it where it is shown.
+ */
+export function framesItself(surface: Shown): boolean {
+  const [only, ...more] = surface.blocks;
+  return more.length === 0 && (only?.type === "card" || only?.type === "automation");
+}
+
+/**
+ * What the agent showed, drawn block by block with the kit's primitives (a `card` is a `Card`, a
+ * `list` a `List` of `Row`s, a form's fields its controls); a block or a field kind the API has
+ * grown since this renderer was written leaves the whole surface to its text twin, so nothing
+ * is half-drawn. Each block's action comes back through `onAction`; the host wraps it with the
+ * surface's id.
+ */
+export function Surface({
+  surface,
+  onAction,
+  active = true,
+  answered,
+  components,
+  classNames,
+  messages,
+  locale,
+  files,
+}: SurfaceProps) {
+  const scope: Scope = { active, answered, onAction, components, classNames, files };
+  return (
+    <KitProvider classNames={classNames} messages={messages} locale={locale}>
+      <ScopeContext value={scope}>
+        <div className={`sc ${classes(classNames, "sc-surface")}`}>
+          <Whole twin={<p className={classes(classNames, "sc-surface__text")}>{surface.text}</p>}>
+            {known(surface.blocks)
+              ? surface.blocks.map((block, index) => <Draw key={index} block={block} />)
+              : null}
+          </Whole>
+        </div>
+      </ScopeContext>
+    </KitProvider>
+  );
+}
+
+/**
+ * The surface drawn whole or not at all: what it can't draw (blocks it doesn't know, or one that
+ * fails as it draws) leaves its text twin in its place, never a broken page.
+ */
+class Whole extends Component<{ twin: ReactNode; children: ReactNode }, { failed: boolean }> {
+  override state = { failed: false };
+
+  static getDerivedStateFromError(): { failed: boolean } {
+    return { failed: true };
+  }
+
+  override render() {
+    return this.state.failed || this.props.children === null
+      ? this.props.twin
+      : this.props.children;
+  }
+}
+
+/** One block: the host's own component for its type when it gave one, else the kit's. */
+function Draw({ block }: { block: Block }) {
+  const { active, onAction, components } = useScope();
+  const part = useSurfaceParts();
+  const children =
+    "children" in block
+      ? block.children.map((child, index) => <Draw key={index} block={child} />)
+      : undefined;
+  const Own = components?.[block.type];
+  if (Own) {
+    // Found by the block's own type, so its fields are the right props; the union is too wide
+    // for the compiler to see that pairing.
+    const Host = Own as ComponentType<Record<string, unknown>>;
+    return <Host {...block} active={active} onAction={onAction} children={children} />;
+  }
+  switch (block.type) {
+    case "card":
+      return (
+        <Card title={block.title} subtitle={block.subtitle} image={block.image}>
+          {children}
+        </Card>
+      );
+    case "stack":
+      return (
+        <div
+          part="stack"
+          className={part(
+            "sc-surface__stack",
+            ...(block.direction === "row" ? (["sc-surface__stack--row"] as const) : []),
+          )}
+        >
+          {children}
+        </div>
+      );
+    case "divider":
+      return <hr part="divider" className={part("sc-surface__divider")} />;
+    case "text":
+      return (
+        <div part="text" className={part("sc-surface__text")}>
+          <Markdown text={block.text} />
+        </div>
+      );
+    case "fields":
+      return <Fields block={block} />;
+    case "table":
+      return <Table block={block} />;
+    case "list":
+      return <Listing block={block} />;
+    case "stat":
+      return <Stat label={block.label} value={block.value} hint={block.hint} tone={block.tone} />;
+    case "chart":
+      return <Chart kind={block.kind} points={block.points} />;
+    case "note":
+      return (
+        <Note tone={block.tone}>
+          <Markdown text={block.text} />
+        </Note>
+      );
+    case "image":
+      return <Picture block={block} />;
+    case "automation":
+      return <AutomationShown block={block} />;
+    case "file":
+      return <FileShown block={block} />;
+    case "button":
+      return <Pressable block={block} />;
+    case "choice":
+      return <Choice block={block} />;
+    case "form":
+      return <FormView block={block} />;
+  }
+}
+
+/**
+ * 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
+ * host's viewer (`files.open`), whatever its kind. A picture, a video or a sound plays where it
+ * is instead, when the host can play it (`files.play`). Until the API has put it in the
+ * conversation it is only named, quietly.
+ */
+function FileShown({ block }: { block: FileBlock }) {
+  const { files } = useScope();
+  const { code } = useKit();
+  const { file } = block;
+  const name = file?.name ?? baseName(block.path);
+  const title = block.title ?? name;
+  const open = file !== null ? files?.open : undefined;
+  const played = file !== null ? playedAs(file.media_type) : null;
+  const src = usePlayed(file, played !== null ? files?.play : undefined);
+  if (file !== null && played !== null && src !== null) {
+    return (
+      <Played
+        kind={played}
+        src={src.url}
+        name={name}
+        caption={block.title}
+        onOpen={open ? () => open(file) : undefined}
+        onLost={src.again}
+      />
+    );
+  }
+  return (
+    <List>
+      <Row
+        mark={<FileMark name={name} type={file?.media_type} />}
+        title={title}
+        subtitle={title === name ? undefined : name}
+        meta={file === null ? undefined : formatSize(file.size, code)}
+        quiet={file === null}
+        onPress={open && file !== null ? () => open(file) : undefined}
+      />
+    </List>
+  );
+}
+
+type PlayedKind = "image" | "video" | "audio";
+
+/** How a file plays in the page: a picture, a video, a sound; null for any other kind. */
+export function playedAs(mediaType: string): PlayedKind | null {
+  const family = mediaType.split("/")[0];
+  return family === "image" || family === "video" || family === "audio" ? family : null;
+}
+
+/**
+ * Where `file` plays from, asked of the host once (`play`): null until it answers, and when it
+ * can't. `again` asks for a new address, for a player whose address ran out.
+ */
+export function usePlayed(
+  file: Attachment | null,
+  play: ((file: Attachment) => Promise<string>) | undefined,
+): { url: string; again: () => void } | null {
+  const [url, setUrl] = useState<string | null>(null);
+  const [asked, setAsked] = useState(0);
+  // The file and the host's way to play it as they are now: a block drawn again carries the
+  // same file anew, and the host its functions; what is asked for changes with the file's id.
+  const latest = useRef({ file, play });
+  latest.current = { file, play };
+  const id = file?.id;
+  const playable = play !== undefined;
+  useEffect(() => {
+    const { file: now, play: player } = latest.current;
+    if (now === null || player === undefined) return;
+    let current = true;
+    player(now).then(
+      (address) => current && setUrl(address),
+      () => current && setUrl(null),
+    );
+    return () => {
+      current = false;
+    };
+  }, [id, playable, asked]);
+  return url === null ? null : { url, again: () => setAsked((times) => times + 1) };
+}
+
+/**
+ * A picture, a video or a sound the agent put in front of the person, where it is: the
+ * browser's own player, streaming from the address it plays from; a picture pressed opens whole
+ * in the host's viewer. A player whose address ran out asks for a new one, once.
+ */
+function Played({
+  kind,
+  src,
+  name,
+  caption,
+  onOpen,
+  onLost,
+}: {
+  kind: PlayedKind;
+  src: string;
+  name: string;
+  caption: string | undefined;
+  onOpen: (() => void) | undefined;
+  onLost: () => void;
+}) {
+  const part = useSurfaceParts();
+  const lost = useRef(false);
+  const once = () => {
+    if (lost.current) return;
+    lost.current = true;
+    onLost();
+  };
+  return (
+    <figure part="media" className={part("sc-surface__media")} data-kind={kind}>
+      {kind === "image" ? (
+        onOpen ? (
+          <button type="button" onClick={onOpen} aria-label={name}>
+            <img src={src} alt={name} loading="lazy" onError={once} />
+          </button>
+        ) : (
+          <img src={src} alt={name} loading="lazy" onError={once} />
+        )
+      ) : kind === "video" ? (
+        <video src={src} controls playsInline preload="metadata" aria-label={name} onError={once} />
+      ) : (
+        <AudioPlayer src={src} label={name} onError={once} />
+      )}
+      {caption !== undefined && <figcaption>{caption}</figcaption>}
+    </figure>
+  );
+}
+
+/** Labels and their values, a row each. */
+function Fields({ block }: { block: FieldsBlock }) {
+  const part = useSurfaceParts();
+  return (
+    <dl part="fields" className={part("sc-surface__fields")}>
+      {block.items.map((item, index) => (
+        <div key={index}>
+          <dt>{item.label}</dt>
+          <dd>{item.value}</dd>
+        </div>
+      ))}
+    </dl>
+  );
+}
+
+/** Rows under named columns, scrolling across inside their own box when they are wide. */
+function Table({ block }: { block: TableBlock }) {
+  const part = useSurfaceParts();
+  return (
+    <div part="table" className={part("sc-surface__table")}>
+      <table>
+        <thead>
+          <tr>
+            {block.columns.map((column, index) => (
+              <th key={index} scope="col">
+                {column}
+              </th>
+            ))}
+          </tr>
+        </thead>
+        <tbody>
+          {block.rows.map((row, index) => (
+            <tr key={index}>
+              {block.columns.map((_, at) => (
+                <td key={at}>{row[at] ?? ""}</td>
+              ))}
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </div>
+  );
+}
+
+/** A list block as the kit's `List`: a `Row` each; with an action, rows to pick, the picked checked. */
+function Listing({ block }: { block: ListBlock }) {
+  const { active, answered, onAction } = useScope();
+  const { action } = block;
+  const pick = action !== undefined && answered?.name === action ? answered.data.item : undefined;
+  return (
+    <List>
+      {block.items.map((entry) => (
+        <Row
+          key={entry.id}
+          mark={
+            entry.image !== undefined && https(entry.image) ? (
+              <Mark src={entry.image} photo size={40} />
+            ) : undefined
+          }
+          title={entry.title}
+          subtitle={entry.subtitle}
+          meta={entry.meta}
+          pressed={entry.id === pick}
+          disabled={!active}
+          onPress={
+            action === undefined ? undefined : () => onAction(chosen({ ...block, action }, entry))
+          }
+        />
+      ))}
+    </List>
+  );
+}
+
+/** A picture from an https address, never sending the page's address along, with its caption. */
+function Picture({ block }: { block: ImageBlock }) {
+  const part = useSurfaceParts();
+  if (!https(block.url)) return null;
+  return (
+    <figure part="image" className={part("sc-surface__image")}>
+      <img src={block.url} alt={block.alt} loading="lazy" referrerPolicy="no-referrer" />
+      {block.caption !== undefined && <figcaption>{block.caption}</figcaption>}
+    </figure>
+  );
+}
+
+/**
+ * An automation, read only: the agent's page is where it is switched and its runs opened. One
+ * that is not there (removed, renamed since) says so quietly.
+ */
+function AutomationShown({ block }: { block: AutomationBlock }) {
+  const part = useParts();
+  const { messages } = useKit();
+  // `null`: it is gone; missing: not filled in by the API, which a newer server always does.
+  if (block.view == null) {
+    return (
+      <p className={part("sc-automation", "sc-automation--gone")}>{messages.automation.gone}</p>
+    );
+  }
+  return <Automation automation={block.view} runs={block.view.runs} />;
+}
+
+/**
+ * A button that sends its action, marked once it was the one pressed; or a link that opens its
+ * page apart (it stays usable on an older turn: it changes nothing here).
+ */
+function Pressable({ block }: { block: ButtonBlock }) {
+  const { active, answered, onAction } = useScope();
+  const { action, url, tone, label } = block;
+  if (url !== undefined) {
+    return https(url) ? (
+      <Button tone={tone} href={url}>
+        {label}
+      </Button>
+    ) : null;
+  }
+  if (action === undefined) return null;
+  const done = answered?.name === action && answered.label === label;
+  return (
+    <Button
+      tone={tone}
+      icon={done ? CheckIcon : undefined}
+      pressed={done}
+      disabled={!active}
+      onClick={() => onAction(pressed({ ...block, action }))}
+    >
+      {label}
+    </Button>
+  );
+}
+
+/** A few options to pick one of at once; the one picked keeps a ring and a check. */
+function Choice({ block }: { block: ChoiceBlock }) {
+  const { active, answered, onAction } = useScope();
+  const part = useSurfaceParts();
+  const mine = answered?.name === block.action ? answered.data : undefined;
+  const chosenId = mine?.option;
+  const listed =
+    block.other === true ||
+    block.options.length > SHORT_CHOICE ||
+    block.options.some((option) => option.hint !== undefined || option.label.length > SHORT_LABEL);
+  return (
+    <div
+      role="group"
+      part="choice"
+      className={part(
+        "sc-surface__choice",
+        ...(listed ? (["sc-surface__choice--list"] as const) : []),
+      )}
+    >
+      {block.options.map((option) => (
+        <button
+          key={option.id}
+          type="button"
+          disabled={!active}
+          aria-pressed={option.id === chosenId || undefined}
+          onClick={() => onAction(picked(block, option))}
+          part="option"
+          className={part("sc-surface__option")}
+        >
+          <span>
+            {option.label}
+            {option.hint !== undefined && <small>{option.hint}</small>}
+          </span>
+          {option.id === chosenId && <CheckIcon aria-hidden weight="bold" />}
+        </button>
+      ))}
+      {block.other === true && (
+        <Other
+          active={active}
+          said={typeof mine?.text === "string" ? mine.text : undefined}
+          onSay={(text) => onAction(answeredIn(block, text))}
+        />
+      )}
+    </div>
+  );
+}
+
+/** Pills fit options this few and this short; more, longer or with a hint, they go one a row. */
+const SHORT_CHOICE = 4;
+const SHORT_LABEL = 28;
+
+/**
+ * A choice's last row, to answer in one's own words: pressed, it turns into a box with its send
+ * (Enter sends, Escape folds it back). Once said, the words stand in it, chosen.
+ */
+function Other({
+  active,
+  said,
+  onSay,
+}: {
+  active: boolean;
+  said: string | undefined;
+  onSay: (text: string) => void;
+}) {
+  const part = useSurfaceParts();
+  const { messages } = useKit();
+  const [writing, setWriting] = useState(false);
+  const [text, setText] = useState("");
+  if (said !== undefined || !writing) {
+    return (
+      <button
+        type="button"
+        disabled={!active}
+        aria-pressed={said !== undefined || undefined}
+        onClick={() => setWriting(true)}
+        part="option other"
+        className={part("sc-surface__option", "sc-surface__option--other")}
+      >
+        {said === undefined && <PencilSimpleIcon aria-hidden />}
+        <span>{said ?? messages.other}</span>
+        {said !== undefined && <CheckIcon aria-hidden weight="bold" />}
+      </button>
+    );
+  }
+  const send = () => {
+    const words = text.trim();
+    if (words !== "") onSay(words);
+  };
+  return (
+    <form
+      part="other"
+      className={part("sc-surface__other")}
+      onSubmit={(event) => {
+        event.preventDefault();
+        send();
+      }}
+    >
+      <input
+        // A person who pressed to write wants to write.
+        autoFocus
+        value={text}
+        aria-label={messages.other}
+        placeholder={messages.otherPlaceholder}
+        onChange={(event) => setText(event.target.value)}
+        onKeyDown={(event) => {
+          if (event.key === "Escape") {
+            event.stopPropagation();
+            setWriting(false);
+          }
+        }}
+      />
+      <button type="submit" aria-label={messages.send} disabled={text.trim() === ""}>
+        <ArrowUpIcon aria-hidden weight="bold" />
+      </button>
+    </form>
+  );
+}
+
+/** Only an https address is loaded or opened: never a script, never a local file. */
+function https(url: string): boolean {
+  return /^https:\/\//i.test(url);
+}

package/src/surface/scope.ts

@@ -0,0 +1,82 @@
+import { createContext, useContext, type ComponentType, type ReactNode } from "react";
+
+import type { Block } from "../blocks";
+import { classes } from "../classes";
+import type { KitPart } from "../kit/context";
+import type { FileHost } from "../kit/uploads";
+import type { SurfaceAction } from "./values";
+
+/**
+ * The surface's own parts, by the class each carries: the blocks that are not a kit primitive,
+ * and the form's layout. `classNames` takes these and the kit's (`KitPart`) under the same keys.
+ */
+export type SurfacePart =
+  | "sc-surface"
+  | "sc-surface__stack"
+  | "sc-surface__stack--row"
+  | "sc-surface__divider"
+  | "sc-surface__text"
+  | "sc-surface__fields"
+  | "sc-surface__table"
+  | "sc-surface__image"
+  | "sc-surface__media"
+  | "sc-surface__choice"
+  | "sc-surface__choice--list"
+  | "sc-surface__option"
+  | "sc-surface__option--other"
+  | "sc-surface__other"
+  | "sc-surface__form"
+  | "sc-surface__submit"
+  | "sc-surface__foot"
+  | "sc-surface__sent";
+
+export type SurfaceClassNames = Partial<Record<SurfacePart | KitPart, string>> | undefined;
+
+/**
+ * What a host's component for a block type receives: the block itself, whether the surface still
+ * takes input, and `onAction` to send what the person did; a container's `children` come drawn.
+ */
+export type BlockProps<Type extends Block["type"]> = Omit<
+  Extract<Block, { type: Type }>,
+  "children"
+> &
+  (Extract<Block, { type: Type }> extends { children: Block[] }
+    ? { children: ReactNode }
+    : unknown) & {
+    active: boolean;
+    onAction: (action: SurfaceAction) => void;
+  };
+
+/** 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 every block of one surface shares: whether it takes input, what was done on it. */
+export interface Scope {
+  active: boolean;
+  /** What the person already did on the surface. */
+  answered: SurfaceAction | undefined;
+  onAction: (action: SurfaceAction) => void;
+  components: SurfaceComponents | undefined;
+  classNames: SurfaceClassNames;
+  /** Where its file fields' files go and are found; none: they take none. */
+  files: FileHost | undefined;
+}
+
+export const ScopeContext = createContext<Scope>({
+  active: false,
+  answered: undefined,
+  onAction: () => undefined,
+  components: undefined,
+  classNames: undefined,
+  files: undefined,
+});
+
+export function useScope(): Scope {
+  return useContext(ScopeContext);
+}
+
+/** The classes of the surface's own parts, with the host's own under each. */
+export function useSurfaceParts(): (...parts: SurfacePart[]) => string {
+  const { classNames } = useScope();
+  return (...parts) => classes(classNames, ...parts);
+}