@assistant-ui/react-generative-ui 0.0.24 → 0.1.0

package/src/vocabulary/dispatch.ts

@@ -1,83 +0,0 @@
-import { hasFieldReference, resolveFieldReferences } from "../fieldReferences";
-import type { Action } from "../ir";
-import type { GenerativeUIDispatch } from "../types";
-import type { A2uiBinding } from "../a2ui/BindingContext";
-import { equalData } from "../a2ui/dataModel";
-import { CHECKBOX_GROUP_ATTR, FIELD_NAME_ATTR } from "../constants";
-import {
-  collectFormValues,
-  type FormControlElementLike,
-} from "./collectFormValues";
-
-export const actionAttr = (a: Action | undefined): string | undefined =>
-  a ? JSON.stringify(a) : undefined;
-
-const fieldValues = (
-  source: Element,
-  bindings?: ReadonlyMap<string, A2uiBinding>,
-): Record<string, unknown> => {
-  const scope = source.closest('form[data-aui], [data-aui="root"]');
-  if (!scope) return {};
-  const root = scope.closest('[data-aui="root"]');
-  const controls = Array.from(
-    scope.querySelectorAll<
-      HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement
-    >("input, select, textarea"),
-  ).filter((control) => control.closest('[data-aui="root"]') === root);
-  const values = collectFormValues(
-    controls as ArrayLike<FormControlElementLike>,
-  );
-  if (!bindings) return values;
-  const groups = new Map<string, Map<Element, FormControlElementLike[]>>();
-  for (const control of controls) {
-    const name = control.getAttribute(FIELD_NAME_ATTR) ?? control.name;
-    if (!bindings.has(name)) continue;
-    const field =
-      groups.get(name) ?? new Map<Element, FormControlElementLike[]>();
-    groups.set(name, field);
-    const group =
-      control.type === "radio" || control.hasAttribute(CHECKBOX_GROUP_ATTR)
-        ? (control.closest("fieldset") ?? control)
-        : control;
-    const elements = field.get(group) ?? [];
-    elements.push(control);
-    field.set(group, elements);
-  }
-  for (const [name, field] of groups) {
-    const candidates = [...field.values()]
-      .map((elements) => collectFormValues(elements)[name])
-      .filter((value) => value !== undefined);
-    if (candidates.length > 0)
-      values[name] =
-        candidates.find(
-          (value) => !equalData(value, bindings.get(name)!.value),
-        ) ?? candidates[0];
-  }
-  return values;
-};
-
-/**
- * Fires `$action` through `$dispatch` when both are present, merging a runtime value into the payload under the reserved `$input` key (not `value`) so the user's input never clobbers a model-supplied `value` field. Each `{ "$field": name }` inside `$action` first resolves to the current value of the control with that `name` in the vocabulary form or generative UI root nearest to `source`, collected the way a `Form` collects it; a reference whose control is missing or holds no value resolves to its `fallback`, or is dropped without one. No-op when no registry is wired. The returned promise from an async handler is caught and re-thrown on a microtask so rejections surface rather than going unhandled.
- */
-export const fire = (
-  $action: Action | undefined,
-  $dispatch: GenerativeUIDispatch | undefined,
-  input?: unknown,
-  source?: Element,
-  bindings?: ReadonlyMap<string, A2uiBinding>,
-) => {
-  if (!$action || !$dispatch) return;
-  const action =
-    source && hasFieldReference($action)
-      ? (resolveFieldReferences(
-          $action,
-          fieldValues(source, bindings),
-        ) as Action)
-      : $action;
-  const payload = input === undefined ? action : { ...action, $input: input };
-  void Promise.resolve($dispatch(payload)).catch((error) => {
-    queueMicrotask(() => {
-      throw error;
-    });
-  });
-};

package/src/vocabulary/fact.test.tsx

@@ -1,94 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { renderToStaticMarkup } from "react-dom/server";
-import { renderGenerativeUI } from "../renderGenerativeUI";
-import { factVocabulary } from "./fact";
-
-const render = (node: unknown) =>
-  renderToStaticMarkup(<>{renderGenerativeUI(node, factVocabulary)}</>);
-
-describe("factVocabulary", () => {
-  it("Fact renders a label/value pair inside a dl", () => {
-    expect(render({ $type: "Fact", label: "Status", value: "open" })).toBe(
-      '<dl data-aui="fact"><dt data-aui="fact-label">Status</dt><dd data-aui="fact-value">open</dd></dl>',
-    );
-  });
-
-  it("Fact ignores malformed text properties", () => {
-    expect(
-      render({
-        $type: "Fact",
-        label: { unexpected: true },
-        value: { unexpected: true },
-      }),
-    ).toBe(
-      '<dl data-aui="fact"><dt data-aui="fact-label"></dt><dd data-aui="fact-value"></dd></dl>',
-    );
-  });
-
-  it("Fact renders a good or bad delta with an arrow", () => {
-    expect(
-      render({
-        $type: "Fact",
-        label: "Revenue",
-        value: "$12.4k",
-        delta: "+8%",
-      }),
-    ).toContain(
-      '<span data-aui="fact-delta" data-aui-trend="up" data-aui-tone="good">↑ 8%</span>',
-    );
-    expect(
-      render({
-        $type: "Fact",
-        label: "Cost",
-        value: "$12.4k",
-        delta: "-8%",
-        upIsGood: false,
-      }),
-    ).toContain(
-      '<span data-aui="fact-delta" data-aui-trend="down" data-aui-tone="good">↓ 8%</span>',
-    );
-  });
-
-  it("Fact reads a typographic minus as a downward delta", () => {
-    expect(
-      render({
-        $type: "Fact",
-        label: "Latency",
-        value: "120 ms",
-        delta: "\u22123%",
-      }),
-    ).toContain('data-aui-trend="down" data-aui-tone="bad">↓ 3%</span>');
-  });
-
-  it("Fact infers a zero delta as flat", () => {
-    expect(
-      render({
-        $type: "Fact",
-        label: "Revenue",
-        value: "$12.4k",
-        delta: "+0.0%",
-      }),
-    ).toContain('data-aui-trend="flat" data-aui-tone="neutral">→ +0.0%</span>');
-  });
-
-  it("Fact lets trend override the delta sign and renders flat deltas neutrally", () => {
-    expect(
-      render({
-        $type: "Fact",
-        label: "Revenue",
-        value: "$12.4k",
-        delta: "-8%",
-        trend: "up",
-      }),
-    ).toContain('data-aui-trend="up" data-aui-tone="good">↑ -8%</span>');
-    expect(
-      render({
-        $type: "Fact",
-        label: "Revenue",
-        value: "$12.4k",
-        delta: "0%",
-        trend: "flat",
-      }),
-    ).toContain('data-aui-trend="flat" data-aui-tone="neutral">→ 0%</span>');
-  });
-});

package/src/vocabulary/fact.tsx

@@ -1,54 +0,0 @@
-import { z } from "zod";
-import type { GenerativeUILibrary } from "../types";
-import { factTrend, formatFactDelta } from "./formatValue";
-import { toTextContent } from "./toTextContent";
-
-const factTone = (
-  trend: "up" | "down" | "flat",
-  upIsGood: unknown,
-): "good" | "bad" | "neutral" => {
-  if (trend === "flat") return "neutral";
-  const positive = upIsGood !== false;
-  const isGood = trend === "up" ? positive : !positive;
-  return isGood ? "good" : "bad";
-};
-
-export const factVocabulary = {
-  Fact: {
-    description:
-      "A label/value pair, rendered as a key followed by its value. Use for compact metadata.",
-    properties: z.object({
-      label: z.string().describe("The fact label (key)."),
-      value: z.string().describe("The fact value."),
-      delta: z.string().optional().describe("Change from before."),
-      trend: z
-        .enum(["up", "down", "flat"])
-        .optional()
-        .describe("Change direction."),
-      upIsGood: z.boolean().optional().describe("Whether up is good."),
-    }),
-    render: ({ label, value, delta, trend, upIsGood, children }) => {
-      const direction = factTrend(delta, trend);
-      const tone = factTone(direction, upIsGood);
-
-      return (
-        <dl data-aui="fact">
-          <dt data-aui="fact-label">{toTextContent(label)}</dt>
-          <dd data-aui="fact-value">
-            {toTextContent(value)}
-            {typeof delta === "string" ? (
-              <span
-                data-aui="fact-delta"
-                data-aui-trend={direction}
-                data-aui-tone={tone}
-              >
-                {formatFactDelta(delta, direction)}
-              </span>
-            ) : null}
-            {children}
-          </dd>
-        </dl>
-      );
-    },
-  },
-} satisfies GenerativeUILibrary;

package/src/vocabulary/form.test.tsx

@@ -1,113 +0,0 @@
-import { describe, it, expect, vi } from "vitest";
-import type { ReactElement } from "react";
-import { renderToStaticMarkup } from "react-dom/server";
-import { renderGenerativeUI } from "../renderGenerativeUI";
-import { createActionRegistry } from "../actionRegistry";
-import { formVocabulary } from "./form";
-import type { FormControlElementLike } from "./collectFormValues";
-
-const render = (node: unknown) =>
-  renderToStaticMarkup(<>{renderGenerativeUI(node, formVocabulary)}</>);
-
-const el = (
-  partial: Partial<FormControlElementLike>,
-): FormControlElementLike => ({
-  name: "",
-  type: "text",
-  value: "",
-  disabled: false,
-  hasAttribute: () => false,
-  ...partial,
-});
-
-const fakeSubmitEvent = (elements: FormControlElementLike[]) => ({
-  preventDefault: vi.fn(),
-  currentTarget: { elements },
-});
-
-describe("formVocabulary", () => {
-  it("Form renders a form element with children and a gap hook", () => {
-    const html = render({
-      $type: "Form",
-      gap: 2,
-      children: { $type: "Fact", label: "a", value: "b" } as never,
-    });
-    expect(html).toContain('<form data-aui="form" data-aui-gap="2">');
-  });
-
-  it("Form without gap or $action renders bare", () => {
-    expect(render({ $type: "Form" })).toBe('<form data-aui="form"></form>');
-  });
-
-  it("Form onSubmit prevents default and dispatches collected values keyed by name", () => {
-    const handler = vi.fn();
-    const registry = createActionRegistry({ save: handler });
-    const out = formVocabulary.Form.render({
-      $status: "done",
-      $action: { type: "save" },
-      $dispatch: registry.dispatch,
-    }) as ReactElement;
-    const onSubmit = (out.props as { onSubmit: (e: unknown) => void }).onSubmit;
-    const event = fakeSubmitEvent([
-      el({ name: "email", type: "email", value: "a@example.com" }),
-      el({ name: "agree", type: "checkbox", checked: true }),
-      el({ name: "size", type: "radio", value: "sm", checked: false }),
-      el({ name: "size", type: "radio", value: "lg", checked: true }),
-      el({ name: "", type: "text", value: "ignored" }),
-      el({ name: "off", type: "text", value: "ignored", disabled: true }),
-    ]);
-    onSubmit(event);
-    expect(event.preventDefault).toHaveBeenCalled();
-    expect(handler).toHaveBeenCalledWith({
-      payload: {
-        type: "save",
-        $input: { email: "a@example.com", agree: true, size: "lg" },
-      },
-    });
-  });
-
-  it("Form onSubmit collects repeated non-radio names into an array", () => {
-    const handler = vi.fn();
-    const registry = createActionRegistry({ save: handler });
-    const out = formVocabulary.Form.render({
-      $status: "done",
-      $action: { type: "save" },
-      $dispatch: registry.dispatch,
-    }) as ReactElement;
-    const onSubmit = (out.props as { onSubmit: (e: unknown) => void }).onSubmit;
-    onSubmit(
-      fakeSubmitEvent([
-        el({ name: "tag", type: "text", value: "a" }),
-        el({ name: "tag", type: "text", value: "b" }),
-      ]),
-    );
-    expect(handler).toHaveBeenCalledWith({
-      payload: { type: "save", $input: { tag: ["a", "b"] } },
-    });
-  });
-
-  it("Form onSubmit is silent (but still prevents default) when no $action is wired", () => {
-    const out = formVocabulary.Form.render({
-      $status: "done",
-    }) as ReactElement;
-    const onSubmit = (out.props as { onSubmit: (e: unknown) => void }).onSubmit;
-    const event = fakeSubmitEvent([
-      el({ name: "x", type: "text", value: "y" }),
-    ]);
-    expect(() => onSubmit(event)).not.toThrow();
-    expect(event.preventDefault).toHaveBeenCalled();
-  });
-
-  it("Form onSubmit is silent (but still prevents default) when $action is present but no $dispatch is wired", () => {
-    const out = formVocabulary.Form.render({
-      $status: "done",
-      $action: { type: "save" },
-    }) as ReactElement;
-    const onSubmit = (out.props as { onSubmit: (e: unknown) => void }).onSubmit;
-    const event = fakeSubmitEvent([
-      el({ name: "x", type: "text", value: "y" }),
-    ]);
-    expect(() => onSubmit(event)).not.toThrow();
-    expect(event.preventDefault).toHaveBeenCalled();
-  });
-});

package/src/vocabulary/form.tsx

@@ -1,39 +0,0 @@
-import { z } from "zod";
-import type { GenerativeUILibrary } from "../types";
-import { actionAttr, fire } from "./dispatch";
-import { collectFormValuesFromEvent } from "./collectFormValues";
-
-export const formVocabulary = {
-  Form: {
-    description:
-      "Wraps named child controls (Select/Input/Checkbox/RadioGroup/CheckboxGroup/DatePicker with a `name`). Carries `$action`; on submit it fires with every named control's value, keyed by `name`.",
-    properties: z.object({
-      gap: z
-        .number()
-        .min(0)
-        .max(8)
-        .optional()
-        .describe(
-          "Gap between children in 4px units. 0 to 8 is the supported range.",
-        ),
-    }),
-    render: ({ gap, $action, $dispatch, children }) => (
-      <form
-        data-aui="form"
-        data-aui-gap={gap}
-        data-aui-action={actionAttr($action)}
-        onSubmit={(event) => {
-          event.preventDefault();
-          fire(
-            $action,
-            $dispatch,
-            collectFormValuesFromEvent(event),
-            event.currentTarget,
-          );
-        }}
-      >
-        {children}
-      </form>
-    ),
-  },
-} satisfies GenerativeUILibrary;

package/src/vocabulary/formatValue.test.ts

@@ -1,72 +0,0 @@
-import { afterEach, describe, expect, it, vi } from "vitest";
-import { factTrend, formatValue } from "./formatValue";
-
-afterEach(() => {
-  vi.restoreAllMocks();
-});
-
-describe("formatValue", () => {
-  it.each(["0", "0%", "+0.0%", "−0", "$0"])(
-    "infers %s as a flat fact delta",
-    (delta) => {
-      expect(factTrend(delta, undefined)).toBe("flat");
-    },
-  );
-
-  it("formats numbers, currency, percentages, and dates", () => {
-    expect(formatValue(1234.567, { kind: "number", decimals: 2 })).toBe(
-      "1,234.57",
-    );
-    expect(
-      formatValue(1234.5, { kind: "currency", currency: "USD", decimals: 2 }),
-    ).toBe("$1,234.50");
-    expect(formatValue(0.1234, { kind: "percent", decimals: 1 })).toBe("12.3%");
-    expect(formatValue("2024-01-02", { kind: "date" })).toBe("Jan 2, 2024");
-    expect(formatValue(0, { kind: "date" })).toBe(
-      new Intl.DateTimeFormat("en-US", { dateStyle: "medium" }).format(0),
-    );
-  });
-
-  it("keeps a date-only value on its calendar day west of UTC", () => {
-    const DateTimeFormat = Intl.DateTimeFormat;
-    vi.spyOn(Intl, "DateTimeFormat").mockImplementation(
-      function (locales, options) {
-        return new DateTimeFormat(locales, {
-          timeZone: "America/Los_Angeles",
-          ...options,
-        });
-      },
-    );
-
-    expect(formatValue("2026-09-26", { kind: "date" })).toBe("Sep 26, 2026");
-  });
-
-  it("keeps impossible ISO calendar dates as raw text", () => {
-    expect(formatValue("2024-02-30", { kind: "date" })).toBe("2024-02-30");
-    expect(formatValue("2023-02-29", { kind: "date" })).toBe("2023-02-29");
-    expect(formatValue("2024-04-31", { kind: "date" })).toBe("2024-04-31");
-    expect(formatValue("2024-02-29", { kind: "date" })).toBe("Feb 29, 2024");
-  });
-
-  it("clamps decimal precision", () => {
-    expect(formatValue(1.234, { kind: "number", decimals: -2 })).toBe("1");
-    expect(formatValue(1.234, { kind: "number", decimals: 30 })).toBe(
-      new Intl.NumberFormat("en-US", {
-        minimumFractionDigits: 20,
-        maximumFractionDigits: 20,
-      }).format(1.234),
-    );
-  });
-
-  it("keeps wrong-typed values and invalid formats as raw text", () => {
-    expect(formatValue("1234", { kind: "number" })).toBe("1234");
-    expect(formatValue("0.2", { kind: "percent" })).toBe("0.2");
-    expect(formatValue("not a date", { kind: "date" })).toBe("not a date");
-    expect(() =>
-      formatValue(12, { kind: "currency", currency: "not-a-currency" }),
-    ).not.toThrow();
-    expect(
-      formatValue(12, { kind: "currency", currency: "not-a-currency" }),
-    ).toBe("12");
-  });
-});

package/src/vocabulary/formatValue.ts

@@ -1,127 +0,0 @@
-type TableFormat = {
-  kind: "number" | "currency" | "percent" | "date";
-  currency?: string;
-  decimals?: number;
-};
-
-const DATE_ONLY_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
-
-const ISO_DATE_PATTERN =
-  /^\d{4}-\d{2}-\d{2}(?:T\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:?\d{2})?)?$/;
-
-type FactTrend = "up" | "down" | "flat";
-
-const toRawText = (value: unknown): string =>
-  typeof value === "string" ||
-  typeof value === "number" ||
-  typeof value === "boolean"
-    ? String(value)
-    : "";
-
-const isTableFormat = (format: unknown): format is TableFormat =>
-  format !== null &&
-  typeof format === "object" &&
-  "kind" in format &&
-  (format.kind === "number" ||
-    format.kind === "currency" ||
-    format.kind === "percent" ||
-    format.kind === "date");
-
-const fractionDigits = (decimals: unknown): number | undefined => {
-  if (typeof decimals !== "number" || !Number.isFinite(decimals)) {
-    return undefined;
-  }
-  return Math.min(20, Math.max(0, Math.trunc(decimals)));
-};
-
-const isCalendarDate = (value: string): boolean => {
-  const [year, month, day] = value.slice(0, 10).split("-").map(Number);
-  if (year === undefined || month === undefined || day === undefined) {
-    return false;
-  }
-  const daysInMonth =
-    month === 2
-      ? year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0)
-        ? 29
-        : 28
-      : [4, 6, 9, 11].includes(month)
-        ? 30
-        : 31;
-  return month >= 1 && month <= 12 && day >= 1 && day <= daysInMonth;
-};
-
-const dateFromValue = (value: unknown): Date | undefined => {
-  if (typeof value === "number") {
-    const date = new Date(value);
-    return Number.isNaN(date.getTime()) ? undefined : date;
-  }
-  if (typeof value !== "string" || !ISO_DATE_PATTERN.test(value)) {
-    return undefined;
-  }
-  if (!isCalendarDate(value)) return undefined;
-  const date = new Date(value);
-  return Number.isNaN(date.getTime()) ? undefined : date;
-};
-
-export const factTrend = (delta: unknown, trend: unknown): FactTrend => {
-  if (trend === "down" || trend === "flat" || trend === "up") return trend;
-  if (typeof delta === "string" && /\d/.test(delta) && !/[1-9]/.test(delta)) {
-    return "flat";
-  }
-  return typeof delta === "string" && /^[-\u2212]/.test(delta) ? "down" : "up";
-};
-
-export const formatFactDelta = (delta: string, trend: FactTrend): string => {
-  const arrow = trend === "up" ? "↑" : trend === "down" ? "↓" : "→";
-  const text =
-    trend === "up"
-      ? delta.replace(/^\+/, "")
-      : trend === "down"
-        ? delta.replace(/^[-\u2212]/, "")
-        : delta;
-  return `${arrow} ${text}`;
-};
-
-export const isNumericTableFormat = (format: unknown): boolean =>
-  isTableFormat(format) && format.kind !== "date";
-
-export const formatValue = (value: unknown, format: unknown): string => {
-  const raw = toRawText(value);
-  try {
-    if (!isTableFormat(format)) return raw;
-
-    if (format.kind === "date") {
-      const date = dateFromValue(value);
-      return date === undefined
-        ? raw
-        : new Intl.DateTimeFormat("en-US", {
-            dateStyle: "medium",
-            ...(typeof value === "string" && DATE_ONLY_PATTERN.test(value)
-              ? { timeZone: "UTC" }
-              : {}),
-          }).format(date);
-    }
-
-    if (typeof value !== "number") return raw;
-
-    const decimals = fractionDigits(format.decimals);
-    const digitOptions =
-      decimals === undefined
-        ? {}
-        : { minimumFractionDigits: decimals, maximumFractionDigits: decimals };
-    if (format.kind === "currency") {
-      if (typeof format.currency !== "string") return raw;
-      return new Intl.NumberFormat("en-US", {
-        ...digitOptions,
-        style: "currency",
-        currency: format.currency,
-      }).format(value);
-    }
-    return new Intl.NumberFormat("en-US", {
-      ...digitOptions,
-      ...(format.kind === "percent" ? { style: "percent" } : {}),
-    }).format(value);
-  } catch {
-    return raw;
-  }
-};

package/src/vocabulary/icon.test.tsx

@@ -1,64 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { renderToStaticMarkup } from "react-dom/server";
-import { renderGenerativeUI } from "../renderGenerativeUI";
-import { buildPresentParameters } from "../buildPresentParameters";
-import { iconVocabulary } from "./icon";
-import { ICON_NAMES } from "../ir";
-
-const render = (node: unknown) =>
-  renderToStaticMarkup(<>{renderGenerativeUI(node, iconVocabulary)}</>);
-
-describe("iconVocabulary", () => {
-  it("a known name renders an svg with the data-aui hooks and default size", () => {
-    const html = render({ $type: "Icon", name: "check" });
-    expect(html).toContain('data-aui="icon"');
-    expect(html).toContain('data-aui-name="check"');
-    expect(html).toContain('viewBox="0 0 24 24"');
-    expect(html).toContain('width="16"');
-    expect(html).toContain('height="16"');
-    expect(html).toContain('aria-hidden="true"');
-  });
-
-  it("every built-in name renders without throwing and without a data-aui-size attribute when size is omitted", () => {
-    for (const name of ICON_NAMES) {
-      const html = render({ $type: "Icon", name });
-      expect(html, name).toContain("<svg");
-      expect(html, name).not.toContain("data-aui-size=");
-    }
-  });
-
-  it("maps size tokens to pixel dimensions", () => {
-    expect(render({ $type: "Icon", name: "star", size: "sm" })).toContain(
-      'width="14"',
-    );
-    expect(render({ $type: "Icon", name: "star", size: "md" })).toContain(
-      'width="16"',
-    );
-    expect(render({ $type: "Icon", name: "star", size: "lg" })).toContain(
-      'width="20"',
-    );
-  });
-
-  it("emits the size token as a data-aui-size hook when given", () => {
-    expect(render({ $type: "Icon", name: "bell", size: "lg" })).toContain(
-      'data-aui-size="lg"',
-    );
-  });
-
-  it("an unknown name renders nothing rather than throwing", () => {
-    expect(() =>
-      render({ $type: "Icon", name: "not-a-real-icon" }),
-    ).not.toThrow();
-    expect(render({ $type: "Icon", name: "not-a-real-icon" })).toBe("");
-  });
-
-  it("exposes the closed name enum in buildPresentParameters", () => {
-    const schema = buildPresentParameters(iconVocabulary) as Record<
-      string,
-      unknown
-    >;
-    const properties = schema["properties"] as Record<string, unknown>;
-    const nameProp = properties["name"] as { enum?: unknown[] };
-    expect(nameProp.enum).toEqual([...ICON_NAMES]);
-  });
-});