@assistant-ui/react-generative-ui 0.0.20 → 0.0.22

package/src/vocabulary/dispatch.ts

@@ -1,19 +1,80 @@
+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. 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.
+ * 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 payload = input === undefined ? $action : { ...$action, $input: input };
+  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

@@ -24,4 +24,71 @@ describe("factVocabulary", () => {
       '<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,7 +1,18 @@
 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:
@@ -9,15 +20,35 @@ export const factVocabulary = {
     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, children }) => (
-      <dl data-aui="fact">
-        <dt data-aui="fact-label">{toTextContent(label)}</dt>
-        <dd data-aui="fact-value">
-          {toTextContent(value)}
-          {children}
-        </dd>
-      </dl>
-    ),
+    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.tsx

@@ -6,7 +6,7 @@ import { collectFormValuesFromEvent } from "./collectFormValues";
 export const formVocabulary = {
   Form: {
     description:
-      "Wraps named child controls (Select/Input/Checkbox/RadioGroup/DatePicker with a `name`). Carries `$action`; on submit it fires with every named control's value, keyed by `name`.",
+      "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()
@@ -24,7 +24,12 @@ export const formVocabulary = {
         data-aui-action={actionAttr($action)}
         onSubmit={(event) => {
           event.preventDefault();
-          fire($action, $dispatch, collectFormValuesFromEvent(event));
+          fire(
+            $action,
+            $dispatch,
+            collectFormValuesFromEvent(event),
+            event.currentTarget,
+          );
         }}
       >
         {children}

package/src/vocabulary/formatValue.test.ts

@@ -0,0 +1,72 @@
+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

@@ -0,0 +1,127 @@
+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/index.test.ts

@@ -14,7 +14,9 @@ const EXPECTED_KEYS = [
   "Input",
   "DatePicker",
   "Checkbox",
+  "Slider",
   "RadioGroup",
+  "CheckboxGroup",
   "Form",
   "Card",
   "Col",