cortena-ui 1.1.0 → 1.2.0

package/src/a2ui/renderer.tsx

@@ -0,0 +1,438 @@
+"use client";
+
+/**
+ * The A2UI React renderer.
+ *
+ * Takes A2UI messages, folds them onto surfaces, walks the component tree and
+ * draws each node through the catalogue. Nothing an agent sends reaches the DOM
+ * as markup: a node is a catalogue name plus properties that must pass the
+ * entry's zod schema, and anything else becomes an inline error card.
+ *
+ * ## Why this is written rather than adopted
+ *
+ * `@a2ui/react` 0.11.0 (Google, Apache-2.0, published 2026-09-01) is a real,
+ * maintained v0.9 renderer and it does let a host supply a catalogue. It was
+ * evaluated for DESIGN-33 and not adopted, for three reasons:
+ *
+ * 1. **zod major.** `@a2ui/web_core`'s generic binder reads zod 3 internals —
+ *    `schema._def.typeName`, `_def.shape()`, `_def.innerType` — to decide how to
+ *    bind each property. cortena-ui's zod peer is `^3.25 || ^4`, and zod 4 has
+ *    no `_def.typeName` and exposes `shape` as a property, so a catalogue
+ *    authored with the consumer's zod 4 fails inside the binder. Adopting would
+ *    pin the whole package's schema layer to zod 3 while `form.tsx` and
+ *    `@hookform/resolvers` follow the consumer's.
+ * 2. **Dialect.** Cortena already speaks A2UI v0.8: core bundles the Lit
+ *    renderer at `src/canvas-host/a2ui/` and the `canvas` tool pushes
+ *    `beginRendering` / `surfaceUpdate` / `dataModelUpdate` as JSONL.
+ *    `@a2ui/react` splits v0_8 and v0_9 into separate entry points with separate
+ *    catalogues, so neither one reads both. Every payload written for the
+ *    native nodes would have to be rewritten before it rendered on the web.
+ * 3. **Weight and surface.** It brings `@a2ui/web_core` (3.8 MB unpacked),
+ *    markdown-it, `@preact/signals-core` and date-fns into a package whose build
+ *    externalises everything and whose markdown already goes through
+ *    react-markdown with a sanitize schema. And the API this task needs —
+ *    `resolveDataSource` for server tables, `onAction` for the AG-UI round trip —
+ *    has no counterpart there, so it would be wrapped either way.
+ *
+ * What we keep is the part that matters for interop: the **wire format** is
+ * A2UI's, the action we emit is shaped like A2UI's client-to-server `action`
+ * (`{ name, surfaceId, sourceComponentId, context }`), and the catalogue is a
+ * schema-per-component registry. Swapping the engine later is mechanical.
+ */
+
+import * as React from "react";
+import type { DataSource } from "@/components/data-table";
+import { cn } from "@/lib/cn";
+import {
+  A2UI_DEFAULT_SURFACE_ID,
+  foldMessages,
+  isDataBinding,
+  readAction,
+  readChildren,
+  readComponent,
+  resolvePointer,
+  resolveValue,
+  setAtPointer,
+  type A2UIAction,
+  type A2UIComponentSpec,
+  type A2UIMessageInput,
+  type A2UISurface,
+} from "./message";
+import { defaultCatalogue, type A2UICatalogue } from "./catalogue";
+import { A2UIErrorCard, type A2UINodeInfo, type A2UIResolvedAction, type A2UIRow } from "./views";
+
+export interface A2UIRendererProps {
+  /**
+   * The payload. One message, the list an AG-UI `CUSTOM` event carries, or the
+   * JSONL text `canvas.a2ui.pushJSONL` sends. Later messages fold onto earlier
+   * ones, so a push stream can be accumulated by the host and handed here whole.
+   */
+  message: A2UIMessageInput;
+  /** The component vocabulary. Defaults to the whole cortena-ui catalogue. */
+  catalogue?: A2UICatalogue;
+  /** Receives every user event, shaped like A2UI's client-to-server action. */
+  onAction?: (action: A2UIAction) => void;
+  /**
+   * Resolves a `{ kind: "server", sourceId }` table handle into a real data
+   * source. Without it, a server table renders an error card rather than an
+   * empty one, because a silently empty table reads as "no results".
+   */
+  resolveDataSource?: (sourceId: string) => DataSource<A2UIRow> | undefined;
+  /** Render only this surface. Default: every surface, in arrival order. */
+  surfaceId?: string;
+  /** Debounce before a continuous input becomes an action. @default 300 */
+  debounceMs?: number;
+  className?: string;
+}
+
+/** Depth limit; a tree deeper than this is a malformed payload, not a design. */
+const MAX_DEPTH = 32;
+
+interface NodeContext {
+  surface: A2UISurface;
+  catalogue: A2UICatalogue;
+  model: Record<string, unknown>;
+  setModel: (updater: (model: Record<string, unknown>) => Record<string, unknown>) => void;
+  onAction: ((action: A2UIAction) => void) | undefined;
+  resolveDataSource: (sourceId: string) => DataSource<A2UIRow> | undefined;
+  debounceMs: number;
+}
+
+/**
+ * A2UIRenderer — draws A2UI messages through cortena-ui.
+ *
+ * ```tsx
+ * <A2UIRenderer
+ *   message={customEvent.value}
+ *   catalogue={defaultCatalogue}
+ *   onAction={(action) => agent.send(action)}
+ *   resolveDataSource={(id) => sources[id]}
+ * />
+ * ```
+ */
+export function A2UIRenderer({
+  message,
+  catalogue = defaultCatalogue,
+  onAction,
+  resolveDataSource,
+  surfaceId,
+  debounceMs = 300,
+  className,
+}: A2UIRendererProps) {
+  const fold = React.useMemo(() => foldMessages(message), [message]);
+
+  // Local data model per surface, seeded from the folded one. Inputs write here
+  // so a bound value updates as the user types; a new payload replaces it,
+  // because the agent is then the authority on what the surface shows.
+  const [models, setModels] = React.useState<Record<string, Record<string, unknown>>>(() =>
+    seedModels(fold.surfaces),
+  );
+  const seenFold = React.useRef(fold);
+  if (seenFold.current !== fold) {
+    seenFold.current = fold;
+    setModels(seedModels(fold.surfaces));
+  }
+
+  const resolve = React.useCallback(
+    (sourceId: string) => resolveDataSource?.(sourceId),
+    [resolveDataSource],
+  );
+
+  const surfaces = surfaceId
+    ? fold.surfaces.filter((surface) => surface.id === surfaceId)
+    : fold.surfaces;
+
+  const missingSurface = Boolean(surfaceId) && surfaces.length === 0 && fold.surfaces.length > 0;
+
+  return (
+    <div data-slot="a2ui-renderer" className={cn("flex min-w-0 flex-col gap-3", className)}>
+      {fold.errors.length > 0 ? (
+        <A2UIErrorCard
+          title="Malformed A2UI payload"
+          detail={fold.errors.slice(0, 5).join(" ")}
+        />
+      ) : null}
+      {missingSurface ? (
+        <A2UIErrorCard
+          title="Unknown surface"
+          detail={`No surface "${surfaceId}" in this payload.`}
+        />
+      ) : null}
+      {surfaces.map((surface) => (
+        <A2UISurfaceView
+          key={surface.id}
+          surface={surface}
+          catalogue={catalogue}
+          model={models[surface.id] ?? surface.dataModel}
+          setModel={(updater) =>
+            setModels((current) => ({
+              ...current,
+              [surface.id]: updater(current[surface.id] ?? surface.dataModel),
+            }))
+          }
+          onAction={onAction}
+          resolveDataSource={resolve}
+          debounceMs={debounceMs}
+        />
+      ))}
+    </div>
+  );
+}
+
+function seedModels(surfaces: readonly A2UISurface[]): Record<string, Record<string, unknown>> {
+  const models: Record<string, Record<string, unknown>> = {};
+  for (const surface of surfaces) {
+    models[surface.id] = surface.dataModel;
+  }
+  return models;
+}
+
+function A2UISurfaceView({
+  surface,
+  catalogue,
+  model,
+  setModel,
+  onAction,
+  resolveDataSource,
+  debounceMs,
+}: {
+  surface: A2UISurface;
+  catalogue: A2UICatalogue;
+  model: Record<string, unknown>;
+  setModel: (updater: (model: Record<string, unknown>) => Record<string, unknown>) => void;
+  onAction: ((action: A2UIAction) => void) | undefined;
+  resolveDataSource: (sourceId: string) => DataSource<A2UIRow> | undefined;
+  debounceMs: number;
+}) {
+  const context: NodeContext = {
+    surface,
+    catalogue,
+    model,
+    setModel,
+    onAction,
+    resolveDataSource,
+    debounceMs,
+  };
+
+  if (!surface.root) {
+    return (
+      <div data-slot="a2ui-surface" data-surface-id={surface.id}>
+        <A2UIErrorCard
+          title="Empty A2UI surface"
+          detail={`Surface "${surface.id}" has no root component. Send updateComponents with a component whose id is "root", or name one in createSurface.`}
+        />
+      </div>
+    );
+  }
+
+  return (
+    <div data-slot="a2ui-surface" data-surface-id={surface.id} className="flex min-w-0 flex-col">
+      <A2UINode context={context} id={surface.root} contextPath="/" ancestors={[]} depth={0} />
+    </div>
+  );
+}
+
+function A2UINode({
+  context,
+  id,
+  contextPath,
+  ancestors,
+  depth,
+}: {
+  context: NodeContext;
+  id: string;
+  contextPath: string;
+  ancestors: readonly string[];
+  depth: number;
+}) {
+  const spec = context.surface.components.get(id);
+
+  if (!spec) {
+    return <A2UIErrorCard title="Unknown component id" detail={`No component "${id}" in this surface.`} />;
+  }
+  if (ancestors.includes(id)) {
+    return (
+      <A2UIErrorCard
+        title="Circular component reference"
+        detail={`"${id}" is already an ancestor of itself: ${[...ancestors, id].join(" → ")}.`}
+        componentId={id}
+      />
+    );
+  }
+  if (depth > MAX_DEPTH) {
+    return (
+      <A2UIErrorCard
+        title="Component tree too deep"
+        detail={`More than ${MAX_DEPTH} levels below the root.`}
+        componentId={id}
+      />
+    );
+  }
+
+  const declaration = readComponent(spec);
+  if (!declaration) {
+    return (
+      <A2UIErrorCard
+        title="Component has no type"
+        detail="Expected `component` to be a catalogue name, or an object keyed by one."
+        componentId={id}
+      />
+    );
+  }
+
+  const entry = context.catalogue[declaration.name];
+  if (!entry) {
+    return (
+      <A2UIErrorCard
+        title={`Unknown component "${declaration.name}"`}
+        detail={`The catalogue has: ${Object.keys(context.catalogue).sort().join(", ")}.`}
+        componentId={id}
+      />
+    );
+  }
+
+  // Resolve bindings first, then normalise actions, then validate. A view
+  // therefore only ever sees values that passed the entry's schema.
+  const raw = declaration.properties;
+  const bindings: Record<string, string> = {};
+  const resolved: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(raw)) {
+    if (key === "children") {
+      continue;
+    }
+    if (isDataBinding(value)) {
+      bindings[key] = resolvePointer(value.path, contextPath);
+    }
+    const next = resolveValue(value, context.model, contextPath);
+    resolved[key] = key.startsWith("on") ? readAction(next) : next;
+  }
+
+  const parsed = entry.props.safeParse(resolved);
+  if (!parsed.success) {
+    const issues = parsed.error.issues
+      .slice(0, 4)
+      .map((issue) => `${issue.path.join(".") || "(root)"}: ${issue.message}`)
+      .join("; ");
+    return (
+      <A2UIErrorCard
+        title={`Invalid props for ${declaration.name}`}
+        detail={issues}
+        componentId={id}
+      />
+    );
+  }
+
+  const node: A2UINodeInfo = {
+    surfaceId: context.surface.id,
+    componentId: id,
+    dataContextPath: contextPath,
+  };
+
+  const children =
+    entry.children === "many"
+      ? renderChildren(context, spec, raw, contextPath, [...ancestors, id], depth)
+      : [];
+
+  const emit = (
+    action: A2UIResolvedAction | undefined,
+    fallbackName: string,
+    payload?: Record<string, unknown>,
+  ) => {
+    context.onAction?.({
+      surfaceId: context.surface.id,
+      componentId: id,
+      name: action?.name ?? fallbackName,
+      payload: { ...(action?.context ?? {}), ...(payload ?? {}) },
+    });
+  };
+
+  const writeBack = (property: string, value: unknown) => {
+    const pointer = bindings[property];
+    if (!pointer) {
+      return;
+    }
+    context.setModel((model) => setAtPointer(model, pointer, value));
+  };
+
+  const View = entry.view as React.FC<{
+    props: unknown;
+    node: A2UINodeInfo;
+    children: React.ReactNode[];
+    dataModel: Record<string, unknown>;
+    emit: typeof emit;
+    writeBack: typeof writeBack;
+    resolveDataSource: (sourceId: string) => DataSource<A2UIRow> | undefined;
+    debounceMs: number;
+  }>;
+
+  return (
+    <View
+      props={parsed.data}
+      node={node}
+      dataModel={context.model}
+      emit={emit}
+      writeBack={writeBack}
+      resolveDataSource={context.resolveDataSource}
+      debounceMs={context.debounceMs}
+    >
+      {children}
+    </View>
+  );
+}
+
+/**
+ * Render a component's children.
+ *
+ * An explicit list renders each id once. A template renders the referenced
+ * component once per item in a bound array, each with its own data context, so
+ * an agent describes a row of a table or a list item once instead of repeating
+ * it per item.
+ */
+function renderChildren(
+  context: NodeContext,
+  spec: A2UIComponentSpec,
+  properties: Record<string, unknown>,
+  contextPath: string,
+  ancestors: readonly string[],
+  depth: number,
+): React.ReactNode[] {
+  const children = readChildren(spec, properties);
+  if (children.kind === "none") {
+    return [];
+  }
+  if (children.kind === "list") {
+    return children.ids.map((childId) => (
+      <A2UINode
+        key={childId}
+        context={context}
+        id={childId}
+        contextPath={contextPath}
+        ancestors={ancestors}
+        depth={depth + 1}
+      />
+    ));
+  }
+  const pointer = resolvePointer(children.path, contextPath);
+  const items = resolveValue({ path: children.path }, context.model, contextPath);
+  if (!Array.isArray(items)) {
+    return [
+      <A2UIErrorCard
+        key="template-error"
+        title="Template list is not an array"
+        detail={`"${pointer}" does not resolve to an array in the data model.`}
+      />,
+    ];
+  }
+  return items.map((_item, index) => (
+    <A2UINode
+      key={`${children.componentId}:${index}`}
+      context={context}
+      id={children.componentId}
+      contextPath={`${pointer === "/" ? "" : pointer}/${index}`}
+      ancestors={ancestors}
+      depth={depth + 1}
+    />
+  ));
+}
+
+export { A2UI_DEFAULT_SURFACE_ID };