@superxd-studio/adptr 0.5.0

package/source/reusable/generative/copy.ts

@@ -0,0 +1,47 @@
+export const generativeCopy = {
+  stepReady: "Ready",
+  stepLoading: "Loading",
+  stepReview: "Review",
+  stepFailed: "Not applied",
+  stepUncertain: "Unconfirmed",
+  stepResult: "Result",
+  stepPast: "Previous state",
+  loading: "Preparing your response",
+  streaming: "The response is arriving. Actions will be available when it’s complete.",
+  empty: "There’s nothing to show yet.",
+  invalid: "We couldn’t display this response.",
+  invalidNote: "Your work is still here. Try requesting the response again.",
+  retry: "Try again",
+  back: "Back",
+  confirm: "Confirm action",
+  working: "Applying",
+  checking: "Checking",
+  review: "Review before continuing",
+  input: "Your details",
+  noHandler: "This action isn’t available here.",
+  failed: "The action wasn’t applied.",
+  failedNote: "Your details are saved here. You can try again.",
+  uncertain: "We haven’t received confirmation.",
+  uncertainNote: "Check the result before trying again. Your details are kept here.",
+  check: "Check status",
+  noReceipt: "There’s no confirmation yet. Check again or retry this same request.",
+  complete: "Action complete",
+  dismissed: "Dismissed",
+  fieldRequired: "Enter a value to continue.",
+  email: "Enter an email address like name@company.com.",
+  date: "Enter a valid date.",
+  imageMissing: "Image unavailable",
+  data: "View data",
+  point: "Point",
+  series: "Value",
+  mediaSelected: "Track selected",
+  quoted: "Quoted amount",
+  validation: "Check the highlighted fields.",
+  updated: "A new response is available. Finish or dismiss this action before opening it.",
+  next: "Open new response",
+  quoteUnavailable: "We couldn’t confirm the amount. Try again before continuing.",
+  actionInvalid: "We couldn’t prepare this action.",
+  actionInvalidNote:
+    "Your details are still here. Check the entries, shorten long text and try again.",
+} as const;
+export type GenerativeCopy = { [K in keyof typeof generativeCopy]: string };

package/source/reusable/generative/data.tsx

@@ -0,0 +1,126 @@
+import { useState } from "react";
+import { defaultGenerativeUILibrary } from "@assistant-ui/react-generative-ui";
+import { Button } from "../../components/button.js";
+import { generativeCopy as copy } from "./copy.js";
+import type { GenerativeChartProps, GenerativeTableProps } from "./schema.js";
+
+export function GenerativeTable({ label, columns, rows, sortable = false }: GenerativeTableProps) {
+  const [sort, setSort] = useState<{ index: number; direction: 1 | -1 }>();
+  const ordered = sort
+    ? [...rows].sort((a, b) => {
+        const left = a[sort.index],
+          right = b[sort.index];
+        return (
+          sort.direction *
+          (typeof left === "number" && typeof right === "number"
+            ? left - right
+            : String(left).localeCompare(String(right), "en", { numeric: true }))
+        );
+      })
+    : rows;
+  return (
+    <div
+      className="min-w-0 overflow-x-auto rounded-control border border-line-subtle"
+      tabIndex={0}
+      role="region"
+      aria-label={label}
+    >
+      <table className="w-full type-body text-fg numeric">
+        <caption className="sr-only">{label}</caption>
+        <thead className="bg-surface-muted">
+          <tr>
+            {columns.map((column, index) => (
+              <th
+                key={index}
+                scope="col"
+                aria-sort={
+                  sort?.index === index
+                    ? sort.direction === 1
+                      ? "ascending"
+                      : "descending"
+                    : undefined
+                }
+                className="px-4 py-2 text-left type-label"
+                style={{ textAlign: column.align === "end" ? "right" : "left" }}
+              >
+                {sortable ? (
+                  <Button
+                    size="sm"
+                    variant="ghost"
+                    className="-mx-2"
+                    onPress={() =>
+                      setSort({
+                        index,
+                        direction: sort?.index === index && sort.direction === 1 ? -1 : 1,
+                      })
+                    }
+                  >
+                    {column.label}
+                    {sort?.index === index ? (
+                      <span aria-hidden>{sort.direction === 1 ? "↑" : "↓"}</span>
+                    ) : null}
+                  </Button>
+                ) : (
+                  column.label
+                )}
+              </th>
+            ))}
+          </tr>
+        </thead>
+        <tbody>
+          {ordered.map((row, index) => (
+            <tr key={index} className="border-t border-line-subtle">
+              {row.map((cell, c) => (
+                <td
+                  key={c}
+                  className="px-4 py-3"
+                  style={{ textAlign: columns[c]?.align === "end" ? "right" : "left" }}
+                >
+                  {String(cell)}
+                </td>
+              ))}
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </div>
+  );
+}
+/** Upstream chart geometry, host tokens, and the same values in a keyboard-accessible table. */
+export function GenerativeChart(props: GenerativeChartProps) {
+  const [showData, setShowData] = useState(false);
+  const series = props.series?.length
+    ? props.series
+    : [{ label: copy.series, data: props.data ?? [] }];
+  return (
+    <figure className="generative-chart flex min-w-0 flex-col gap-4" aria-label={props.label}>
+      {series.every((s) => s.data.length === 0) ? (
+        <p className="type-body text-fg-subtle">{copy.empty}</p>
+      ) : (
+        defaultGenerativeUILibrary.Chart?.render({ ...props, $status: "done" })
+      )}
+      <Button
+        size="sm"
+        variant="ghost"
+        className="self-start"
+        aria-expanded={showData}
+        onPress={() => setShowData((v) => !v)}
+      >
+        {copy.data}
+      </Button>
+      {showData ? (
+        <GenerativeTable
+          label={props.label}
+          columns={[
+            { label: copy.point },
+            ...series.map((s) => ({ label: s.label, align: "end" as const })),
+          ]}
+          rows={(series[0]?.data ?? []).map((p, i) => [
+            p.label,
+            ...series.map((s) => s.data[i]?.value ?? 0),
+          ])}
+        />
+      ) : null}
+    </figure>
+  );
+}

package/source/reusable/generative/index.tsx

@@ -0,0 +1,517 @@
+import { CanvasSequence, useCanvasObserver } from "../../components/canvas/index.js";
+import {
+  useEffect,
+  useLayoutEffect,
+  useCallback,
+  useId,
+  useMemo,
+  useRef,
+  useState,
+  useSyncExternalStore,
+  type ReactNode,
+} from "react";
+import { renderGenerativeUI } from "@assistant-ui/react-generative-ui";
+import { Button } from "../../components/button.js";
+import { Callout } from "../../components/callout.js";
+import { Spinner } from "../../components/spinner.js";
+import { generativeCopy as defaultCopy, type GenerativeCopy } from "./copy.js";
+import { parseStructuredSpec, type StructuredSpec } from "./schema.js";
+import {
+  createSuperxdGenerativeLibrary,
+  GenerativeRuntimeContext,
+  type GenerativeLibraryOptions,
+} from "./vocabulary.js";
+import {
+  createGenerativeActionController,
+  type GenerativeActions,
+  type GenerativeActionController,
+  type GenerativeRequest,
+  type GenerativeActionSnapshot,
+} from "./actions.js";
+import { ResponseTimeline } from "./timeline.js";
+export { createSuperxdGenerativeLibrary, GenerativeForm } from "./vocabulary.js";
+export type {
+  GenerativeLibraryOptions,
+  GenerativeFormProps,
+  GenerativeFactResolver,
+} from "./vocabulary.js";
+export { GenerativeChart, GenerativeTable } from "./data.js";
+export { parseStructuredSpec, chartSchema, tableSchema, nodeSchemas } from "./schema.js";
+export type {
+  StructuredSpec,
+  StructuredAction,
+  GenerativeChartProps,
+  GenerativeTableProps,
+} from "./schema.js";
+export { createGenerativeActionController } from "./actions.js";
+export type {
+  GenerativeActionController,
+  GenerativeActions,
+  GenerativeActionHandler,
+  GenerativeActionSnapshot,
+  GenerativeStage,
+  GenerativeRequest,
+  GenerativeReceipt,
+} from "./actions.js";
+export { generativeCopy } from "./copy.js";
+export type { GenerativeCopy } from "./copy.js";
+
+export interface StructuredResponseProps extends GenerativeLibraryOptions {
+  /** Stable identity of this response. A different response owns a different action session. */
+  responseId: string;
+  spec: unknown;
+  status?: "loading" | "streaming" | "done" | "error";
+  /** Host-authored allowlist; an omitted handler renders its action unavailable. Keep stable for this response. */
+  actions?: GenerativeActions;
+  controller?: GenerativeActionController;
+  onRetry?: () => void;
+  /** Host-owned destination shown only after a matching successful receipt. Return null for the default receipt. */
+  renderResult?: (request: GenerativeRequest) => ReactNode;
+  /** Keep action steps on the canvas; earlier steps become read-only previews. Off by default. */
+  retainSteps?: boolean;
+  copy?: GenerativeCopy;
+  className?: string;
+}
+const noActions: GenerativeActions = {};
+export function StructuredResponse(props: StructuredResponseProps) {
+  return (
+    <CanvasSequence key={props.responseId}>
+      <ResponseSession key={props.responseId} {...props} />
+    </CanvasSequence>
+  );
+}
+function ResponseSession(props: StructuredResponseProps) {
+  const [owned] = useState(() => createGenerativeActionController(props.actions ?? noActions));
+  const controller = props.controller ?? owned;
+  const snapshot = useSyncExternalStore(
+    controller.subscribe,
+    controller.getSnapshot,
+    controller.getSnapshot,
+  );
+  const capture = useResponseObservation(props, controller);
+  const lease = useRef(0);
+  useEffect(() => {
+    const state = lease;
+    const current = ++state.current;
+    return () => {
+      queueMicrotask(() => {
+        if (state.current === current && !props.controller) owned.dispose();
+      });
+    };
+  }, [props.controller, owned]);
+  return props.retainSteps ? (
+    <ResponseTimeline
+      controller={controller}
+      spec={props.spec}
+      status={props.status ?? "done"}
+      actions={props.actions ?? noActions}
+      copy={props.copy ?? defaultCopy}
+    >
+      {(step, onRequest) => (
+        <ResponseView
+          {...props}
+          spec={step.spec}
+          status={step.status}
+          controller={controller}
+          snapshot={step.snapshot}
+          actionOnly={step.snapshot.stage !== "ready"}
+          onRequest={onRequest}
+          inputSnapshot={step.input}
+        />
+      )}
+    </ResponseTimeline>
+  ) : (
+    <ResponseView {...props} controller={controller} snapshot={snapshot} onRequest={capture} />
+  );
+}
+/** Record from the same controller used by the demo, including fast loading transitions. */
+function useResponseObservation(
+  props: StructuredResponseProps,
+  controller: GenerativeActionController,
+) {
+  const observe = useCanvasObserver();
+  const source = useId();
+  const latest = useRef(props);
+  const input = useRef<Readonly<Record<string, string | boolean>>>(undefined);
+  const seen = useRef<GenerativeActionSnapshot | null>(null);
+  useLayoutEffect(() => {
+    latest.current = props;
+  }, [props]);
+  const record = useCallback(
+    (snapshot: GenerativeActionSnapshot, force = false) => {
+      if (!observe || (!force && seen.current === snapshot)) return;
+      if (seen.current?.stage === "complete" || seen.current?.stage === "dismissed") return;
+      if (snapshot.stage === "ready" && snapshot.request) return;
+      seen.current = snapshot;
+      const config = latest.current;
+      const copy = config.copy ?? defaultCopy;
+      const status = config.status ?? "done";
+      let contentState: string = status;
+      if (status === "done") {
+        if (config.spec == null) contentState = "empty";
+        else {
+          try {
+            parseStructuredSpec(config.spec);
+          } catch {
+            contentState = "invalid";
+          }
+        }
+      }
+      const inspecting =
+        snapshot.request && config.actions?.[snapshot.request.action.type]?.kind === "inspect";
+      const labels = {
+        ready:
+          contentState === "empty"
+            ? copy.empty
+            : contentState === "invalid" || status === "error"
+              ? copy.invalid
+              : status === "done"
+                ? copy.stepReady
+                : copy.stepLoading,
+        confirm: copy.stepReview,
+        submitting: inspecting ? copy.stepLoading : copy.working,
+        checking: copy.checking,
+        failed: copy.stepFailed,
+        uncertain: copy.stepUncertain,
+        complete: copy.stepResult,
+        dismissed: copy.dismissed,
+      };
+      const result =
+        snapshot.stage === "complete" && snapshot.request
+          ? config.renderResult?.(snapshot.request)
+          : null;
+      observe(
+        {
+          phase: `generative-${snapshot.stage}-${contentState}`,
+          label: labels[snapshot.stage],
+          className: "max-w-2xl",
+          yieldToChild: Boolean(result),
+          terminal: snapshot.stage === "dismissed" || (snapshot.stage === "complete" && !result),
+          node: (
+            <ResponseView
+              key={JSON.stringify(input.current)}
+              {...config}
+              controller={controller}
+              snapshot={snapshot}
+              retainSteps
+              actionOnly={snapshot.stage !== "ready"}
+              inputSnapshot={input.current}
+            />
+          ),
+        },
+        source,
+      );
+    },
+    [observe, source, controller],
+  );
+  useEffect(() => {
+    if (!observe) return;
+    record(controller.getSnapshot(), true);
+    return controller.subscribe(() => record(controller.getSnapshot()));
+  }, [observe, record, controller, props.spec, props.status]);
+  return (action: unknown) => {
+    if (!observe || !action || typeof action !== "object") return;
+    const values = (action as { $input?: unknown }).$input;
+    if (values && typeof values === "object" && !Array.isArray(values)) {
+      input.current = Object.fromEntries(
+        Object.entries(values).filter(
+          (entry): entry is [string, string | boolean] =>
+            typeof entry[1] === "string" || typeof entry[1] === "boolean",
+        ),
+      );
+      record(controller.getSnapshot(), true);
+    }
+  };
+}
+
+function ResponseView({
+  spec,
+  status = "done",
+  actions = noActions,
+  controller,
+  snapshot,
+  actionOnly = false,
+  retainSteps = false,
+  inputSnapshot,
+  onRequest,
+  onRetry,
+  renderResult,
+  resolveImage,
+  resolveFact,
+  copy = defaultCopy,
+  className,
+}: StructuredResponseProps & {
+  controller: GenerativeActionController;
+  snapshot: GenerativeActionSnapshot;
+  actionOnly?: boolean;
+  inputSnapshot?: Readonly<Record<string, string | boolean>>;
+  onRequest?: (input: unknown) => void;
+}) {
+  const library = useMemo(
+    () => createSuperxdGenerativeLibrary({ resolveImage, resolveFact }),
+    [resolveImage, resolveFact],
+  );
+  let parsed: StructuredSpec | undefined;
+  try {
+    if (spec != null) parsed = parseStructuredSpec(spec);
+  } catch {
+    /* Never display raw exceptions or partially validated actions. */
+  }
+  const [frozen, setFrozen] = useState<StructuredSpec>();
+  const busy = ["confirm", "submitting", "failed", "uncertain", "checking"].includes(
+    snapshot.stage,
+  );
+  const display = busy ? (frozen ?? parsed) : parsed;
+  const heading = useId();
+  const panel = useRef<HTMLDivElement>(null);
+  const [origin, setOrigin] = useState<HTMLElement | null>(null);
+  const [requestError, setRequestError] = useState(false);
+  const result =
+    snapshot.stage === "complete" && snapshot.request ? renderResult?.(snapshot.request) : null;
+  const hasResult = result != null && result !== false;
+  const inspecting = snapshot.request && actions[snapshot.request.action.type]?.kind === "inspect";
+  const previous = useRef(snapshot.stage);
+  useEffect(() => {
+    if (
+      previous.current !== snapshot.stage &&
+      previous.current === "ready" &&
+      snapshot.stage !== "ready" &&
+      origin
+    )
+      panel.current?.focus({ preventScroll: true });
+    if (previous.current !== snapshot.stage && hasResult && origin) panel.current?.focus();
+    if (previous.current !== snapshot.stage && snapshot.stage === "ready")
+      origin?.focus({ preventScroll: true });
+    previous.current = snapshot.stage;
+  }, [snapshot.stage, origin, hasResult]);
+  const request = (input: unknown) => {
+    onRequest?.(input);
+    setOrigin(document.activeElement as HTMLElement);
+    setFrozen(parsed);
+    setRequestError(!controller.request(input));
+  };
+  const updated = busy && frozen !== undefined && JSON.stringify(parsed) !== JSON.stringify(frozen);
+  const action = snapshot.request?.action;
+  const details = action
+    ? Object.entries(action).flatMap(([name, value]) =>
+        name === "type"
+          ? []
+          : ["$input", "$bindings"].includes(name) &&
+              value &&
+              typeof value === "object" &&
+              !Array.isArray(value)
+            ? Object.entries(value)
+            : [[name, value]],
+      )
+    : [];
+  return (
+    <section
+      aria-labelledby={heading}
+      className={`wrap-anywhere ${className ?? ""}`}
+      data-structured-response
+    >
+      <h2 id={heading} className="sr-only">
+        {copy.input}
+      </h2>
+      <div className="mx-auto flex w-full max-w-2xl min-w-0 flex-col gap-4">
+        {updated ? <Callout>{copy.updated}</Callout> : null}
+        {requestError ? (
+          <Callout tone="error" live="assertive" title={copy.actionInvalid}>
+            {copy.actionInvalidNote}
+          </Callout>
+        ) : null}
+        {actionOnly ? null : busy || status === "done" ? (
+          display ? (
+            <GenerativeRuntimeContext.Provider
+              value={{
+                blocked: snapshot.stage !== "ready",
+                available: new Set(Object.keys(actions)),
+                captureInput: onRequest,
+                initialValues: inputSnapshot,
+              }}
+            >
+              <div
+                className={
+                  display.$type === "Form"
+                    ? "min-w-0 rounded-surface border border-line-subtle bg-surface p-5 shadow-control sm:p-6"
+                    : "min-w-0"
+                }
+                hidden={snapshot.stage !== "ready"}
+                data-generative-content
+              >
+                {renderGenerativeUI(display, library, { status: "done", dispatch: request })}
+              </div>
+            </GenerativeRuntimeContext.Provider>
+          ) : (
+            <Callout
+              tone={spec == null ? "neutral" : "error"}
+              title={spec == null ? copy.empty : copy.invalid}
+              actions={onRetry ? <Button onPress={onRetry}>{copy.retry}</Button> : undefined}
+            >
+              {spec == null ? undefined : copy.invalidNote}
+            </Callout>
+          )
+        ) : status === "error" ? (
+          <Callout
+            tone="error"
+            title={copy.invalid}
+            actions={onRetry ? <Button onPress={onRetry}>{copy.retry}</Button> : undefined}
+          >
+            {copy.invalidNote}
+          </Callout>
+        ) : (
+          <div
+            role="status"
+            className="flex flex-col gap-4 rounded-surface border border-line-subtle bg-surface p-6"
+          >
+            <div className="flex items-center gap-3 type-body text-fg">
+              <Spinner />
+              {copy.loading}
+            </div>
+            {status === "streaming" ? (
+              <p className="type-body text-fg-subtle">{copy.streaming}</p>
+            ) : null}
+            <div aria-hidden className="flex flex-col gap-3">
+              <span className="h-control-md w-full rounded-control bg-surface-subtle" />
+              <span className="h-4 w-2/3 rounded-cell bg-surface-subtle" />
+              <span className="h-4 w-1/2 rounded-cell bg-surface-subtle" />
+            </div>
+          </div>
+        )}
+        {snapshot.stage !== "ready" ? (
+          <div
+            ref={panel}
+            tabIndex={-1}
+            className="rounded-surface border border-line-subtle bg-surface p-5 outline-none focus-visible:focus-ring sm:p-6"
+            data-generative-action
+          >
+            {hasResult ? (
+              <div className="flex flex-col gap-5" data-generative-result>
+                {!retainSteps ? (
+                  <Button
+                    size="sm"
+                    variant="ghost"
+                    className="self-start"
+                    onPress={() => controller.reset()}
+                  >
+                    {copy.back}
+                  </Button>
+                ) : null}
+                {result}
+              </div>
+            ) : inspecting && ["submitting", "checking"].includes(snapshot.stage) ? (
+              <div role="status" className="flex items-center gap-3 type-body text-fg">
+                <Spinner />
+                {snapshot.stage === "checking" ? copy.checking : copy.loading}
+              </div>
+            ) : ["confirm", "submitting", "checking"].includes(snapshot.stage) ? (
+              <div className="flex flex-col gap-4">
+                <p className="font-mono type-caption text-fg-subtle">{copy.review}</p>
+                <h3 className="type-heading text-fg-emphasis">{snapshot.label}</h3>
+                <p className="type-body text-fg">{snapshot.description}</p>
+                {details.length ? (
+                  <dl className="flex flex-col gap-3 border-y border-line-subtle py-4">
+                    {details.map(([name, value], index) => (
+                      <div key={index} className="flex flex-col gap-1">
+                        <dt className="font-mono type-caption text-fg-subtle">
+                          {String(name)
+                            .replace(/^\$/, "")
+                            .replace(/([A-Z])/g, " $1")
+                            .replace(/^./, (letter) => letter.toUpperCase())}
+                        </dt>
+                        <dd className="type-body wrap-anywhere whitespace-pre-wrap text-fg-emphasis">
+                          {value && typeof value === "object"
+                            ? JSON.stringify(value, null, 2)
+                            : String(value)}
+                        </dd>
+                      </div>
+                    ))}
+                  </dl>
+                ) : null}
+                <div className="flex flex-wrap gap-3">
+                  <Button
+                    variant="primary"
+                    isDisabled={snapshot.stage !== "confirm"}
+                    aria-busy={snapshot.stage !== "confirm"}
+                    aria-label={
+                      snapshot.stage === "checking"
+                        ? copy.checking
+                        : snapshot.stage === "submitting"
+                          ? copy.working
+                          : copy.confirm
+                    }
+                    onPress={() => controller.confirm()}
+                  >
+                    {snapshot.stage !== "confirm" ? <Spinner /> : null}
+                    {snapshot.stage === "checking"
+                      ? copy.checking
+                      : snapshot.stage === "submitting"
+                        ? copy.working
+                        : copy.confirm}
+                  </Button>
+                  <Button
+                    variant="ghost"
+                    isDisabled={snapshot.stage !== "confirm"}
+                    onPress={() => controller.back()}
+                  >
+                    {copy.back}
+                  </Button>
+                </div>
+                {snapshot.stage !== "confirm" ? (
+                  <p role="status" className="sr-only">
+                    {snapshot.stage === "checking" ? copy.checking : copy.working}
+                  </p>
+                ) : null}
+              </div>
+            ) : snapshot.stage === "failed" ? (
+              <Callout
+                tone="error"
+                title={copy.failed}
+                live="polite"
+                actions={
+                  <>
+                    <Button onPress={() => controller.retry()}>{copy.retry}</Button>
+                    <Button variant="ghost" onPress={() => controller.back()}>
+                      {copy.back}
+                    </Button>
+                  </>
+                }
+              >
+                {snapshot.message ?? copy.failedNote}
+              </Callout>
+            ) : snapshot.stage === "uncertain" ? (
+              <Callout
+                tone="attention"
+                title={copy.uncertain}
+                live="polite"
+                actions={
+                  <>
+                    {snapshot.request && actions[snapshot.request.action.type]?.lookup ? (
+                      <Button onPress={() => controller.check()}>{copy.check}</Button>
+                    ) : null}
+                    <Button onPress={() => controller.retry()}>{copy.retry}</Button>
+                  </>
+                }
+              >
+                {snapshot.noReceipt ? copy.noReceipt : copy.uncertainNote}
+              </Callout>
+            ) : (
+              <Callout
+                tone={snapshot.stage === "complete" ? "success" : "neutral"}
+                title={snapshot.stage === "complete" ? copy.complete : copy.dismissed}
+                live="polite"
+                actions={
+                  retainSteps ? undefined : (
+                    <Button onPress={() => controller.reset()}>{copy.back}</Button>
+                  )
+                }
+              >
+                {snapshot.message}
+              </Callout>
+            )}
+          </div>
+        ) : null}
+      </div>
+    </section>
+  );
+}