@assistant-ui/react-generative-ui 0.0.21 → 0.0.23

package/src/a2ui/dataModel.ts

@@ -0,0 +1,69 @@
+import { setAtPointer } from "./reducer";
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+export const equalData = (left: unknown, right: unknown): boolean => {
+  if (Object.is(left, right)) return true;
+  if (Array.isArray(left) && Array.isArray(right)) {
+    return (
+      left.length === right.length &&
+      left.every((value, index) => equalData(value, right[index]))
+    );
+  }
+  if (!isRecord(left) || !isRecord(right)) return false;
+  const keys = Object.keys(left);
+  return (
+    keys.length === Object.keys(right).length &&
+    keys.every(
+      (key) => Object.hasOwn(right, key) && equalData(left[key], right[key]),
+    )
+  );
+};
+
+export const decodePointer = (path: string): string[] => {
+  if (path === "" || path === "/") return [];
+  return (path.startsWith("/") ? path.slice(1) : path)
+    .split("/")
+    .map((segment) => segment.replaceAll("~1", "/").replaceAll("~0", "~"));
+};
+
+export const resolvePointer = (source: unknown, path: string): unknown => {
+  let current = source;
+  for (const segment of decodePointer(path)) {
+    if (Array.isArray(current)) {
+      if (!/^(0|[1-9]\d*)$/.test(segment)) return undefined;
+      current = current[Number(segment)];
+      continue;
+    }
+    if (!isRecord(current) || !Object.hasOwn(current, segment)) {
+      return undefined;
+    }
+    current = current[segment];
+  }
+  return current;
+};
+
+export const reconcileDataModel = (
+  previous: unknown,
+  incoming: unknown,
+  local: unknown,
+  editedPaths: ReadonlySet<string>,
+) => {
+  let value = incoming;
+  const retained = new Set<string>();
+  for (const path of editedPaths) {
+    if (
+      equalData(resolvePointer(previous, path), resolvePointer(incoming, path))
+    ) {
+      value = setAtPointer(
+        value,
+        path,
+        resolvePointer(local, path),
+        false,
+      ).value;
+      retained.add(path);
+    }
+  }
+  return { incoming, value, editedPaths: retained };
+};

package/src/a2ui/reducer.test.ts

@@ -100,6 +100,41 @@ describe("applyA2uiOperations", () => {
     expect(result.state.get("properties")?.catalogId).toBe("basic");
   });
 
+  it("applies v0.9.1 operations the way v0.9 does", () => {
+    const result = applyA2uiOperations(new Map(), [
+      {
+        version: "v0.9.1",
+        createSurface: { surfaceId: "main", catalogId: "basic" },
+      },
+      {
+        version: "v0.9.1",
+        updateComponents: {
+          surfaceId: "main",
+          components: [{ id: "root", component: "Text", text: "hello" }],
+        },
+      },
+      {
+        version: "v0.9.1",
+        updateDataModel: {
+          surfaceId: "main",
+          path: "/profile/name",
+          value: "Ada",
+        },
+      },
+    ]);
+
+    expect(result.warnings).toEqual([]);
+    expect(result.state.get("main")).toMatchObject({
+      catalogId: "basic",
+      dataModel: { profile: { name: "Ada" } },
+    });
+    expect(result.state.get("main")?.components.get("root")).toEqual({
+      id: "root",
+      component: "Text",
+      text: "hello",
+    });
+  });
+
   it.each(["10001", "4294967294"])(
     "rejects array pointer index %s beyond the auto-vivification limit",
     (index) => {

package/src/a2ui/reducer.ts

@@ -3,6 +3,7 @@ import {
   type A2uiOperationResult,
   type A2uiState,
   type A2uiSurfaceState,
+  type A2uiVersion,
 } from "./types";
 
 const OPERATION_KEYS = new Set([
@@ -12,14 +13,14 @@ const OPERATION_KEYS = new Set([
   "deleteSurface",
 ]);
 // This defensive ceiling is well above the renderer's displayed-item limit.
-const MAX_AUTO_VIVIFY_ARRAY_INDEX = 10_000;
+export const MAX_AUTO_VIVIFY_ARRAY_INDEX = 10_000;
 const INVALID_POINTER = Symbol("invalidPointer");
 
 const isRecord = (value: unknown): value is Record<string, unknown> =>
   typeof value === "object" && value !== null && !Array.isArray(value);
 
-const isVersion = (value: unknown): value is "v0.9" | "v1.0" =>
-  value === "v0.9" || value === "v1.0";
+const isVersion = (value: unknown): value is A2uiVersion =>
+  value === "v0.9" || value === "v0.9.1" || value === "v1.0";
 
 const surfaceIdOf = (payload: Record<string, unknown>): string | undefined => {
   const surfaceId = payload["surfaceId"];
@@ -117,7 +118,7 @@ const decodePointer = (path: string): string[] | undefined => {
 const isArrayIndex = (segment: string): boolean =>
   segment === "0" || /^[1-9]\d*$/.test(segment);
 
-const setAtPointer = (
+export const setAtPointer = (
   model: unknown,
   path: string,
   value: unknown,

package/src/a2ui/types.ts

@@ -1,6 +1,6 @@
 export const A2UI_SURFACE_ID = Symbol("a2uiSurfaceId");
 
-export type A2uiVersion = "v0.9" | "v1.0";
+export type A2uiVersion = "v0.9" | "v0.9.1" | "v1.0";
 
 export interface A2uiTemplateChildren {
   readonly template: {
@@ -12,7 +12,10 @@ export interface A2uiTemplateChildren {
 export interface ComponentNode extends Record<string, unknown> {
   readonly id: string;
   readonly component: string;
-  readonly children?: readonly string[] | A2uiTemplateChildren;
+  readonly children?:
+    | readonly string[]
+    | { readonly componentId: string; readonly path: string }
+    | A2uiTemplateChildren;
 }
 
 export interface A2uiCreateSurfaceV09Payload {
@@ -53,6 +56,10 @@ export type A2uiCreateSurfaceOperation =
       readonly version: "v0.9";
       readonly createSurface: A2uiCreateSurfaceV09Payload;
     }
+  | {
+      readonly version: "v0.9.1";
+      readonly createSurface: A2uiCreateSurfaceV09Payload;
+    }
   | {
       readonly version: "v1.0";
       readonly createSurface: A2uiCreateSurfaceV10Payload;

package/src/a2ui/valueFunctions.test.ts

@@ -0,0 +1,271 @@
+import { describe, expect, it } from "vitest";
+import {
+  ExpressionSyntaxError,
+  evaluateA2uiValueFunction,
+  parseExpressionTemplate,
+  type ExpressionPart,
+} from "./valueFunctions";
+
+const joinLiterals = (parts: ExpressionPart[]) =>
+  parts.reduce<ExpressionPart[]>((joined, part) => {
+    const last = joined.at(-1);
+    if (typeof part === "string" && typeof last === "string") {
+      joined[joined.length - 1] = last + part;
+    } else {
+      joined.push(part);
+    }
+    return joined;
+  }, []);
+
+// The parse_expression_template cases of a2ui-project/a2ui conformance/core/expressions.yaml.
+const PARSE_CASES: [string, ExpressionPart[]][] = [
+  ["hello world", ["hello world"]],
+  ["", []],
+  ["${user}", [{ path: "user" }]],
+  ["value is ${/user/name}", ["value is ", { path: "/user/name" }]],
+  ["${my-path.with_underscores}", [{ path: "my-path.with_underscores" }]],
+  ["a ${x} b ${y} c", ["a ", { path: "x" }, " b ", { path: "y" }, " c"]],
+  ["${x}${y}", [{ path: "x" }, { path: "y" }]],
+  ["${'hello world'}", ["hello world"]],
+  ['${"hello world"}', ["hello world"]],
+  ["${'line\\nbreak'}", ["line\nbreak"]],
+  ["${'it\\'s'}", ["it's"]],
+  ["${42}", [42]],
+  ["${1.5}", [1.5]],
+  ["${007}", [7]],
+  ["${true} ${false}", [true, " ", false]],
+  ["${trueish}", [{ path: "trueish" }]],
+  ["${now()}", [{ call: "now", args: {} }]],
+  [
+    "sum is ${add(a: 10, b: 20)}",
+    ["sum is ", { call: "add", args: { a: 10, b: 20 } }],
+  ],
+  [
+    "${format(value: /amount, suffix: ' USD', fallback: zero())}",
+    [
+      {
+        call: "format",
+        args: {
+          value: { path: "/amount" },
+          suffix: " USD",
+          fallback: { call: "zero", args: {} },
+        },
+      },
+    ],
+  ],
+  [
+    "${outer(a: inner(b: 1))}",
+    [{ call: "outer", args: { a: { call: "inner", args: { b: 1 } } } }],
+  ],
+  ["${${'hello'}}", ["hello"]],
+  ["${   /user/name   }", [{ path: "/user/name" }]],
+  ["\\${not_interpolated}", ["${not_interpolated}"]],
+  ["before \\${x} after", ["before ${x} after"]],
+  ["\\${literal} ${real}", ["${literal} ", { path: "real" }]],
+  ["${1.}", [1]],
+];
+
+const MALFORMED_TEMPLATES = [
+  "hello ${world",
+  "${add(a: 1, b: 2}",
+  "${add(a 1)}",
+  "${true false}",
+  "${1.2.3}",
+];
+
+describe("parseExpressionTemplate", () => {
+  it.each(PARSE_CASES)("parses %j", (template, expected) => {
+    expect(joinLiterals(parseExpressionTemplate(template))).toEqual(expected);
+  });
+
+  it.each(MALFORMED_TEMPLATES)("rejects %j", (template) => {
+    expect(() => parseExpressionTemplate(template)).toThrow(
+      ExpressionSyntaxError,
+    );
+  });
+
+  it("rejects templates past the length and nesting caps", () => {
+    expect(() => parseExpressionTemplate("x".repeat(10_001))).toThrow(
+      ExpressionSyntaxError,
+    );
+    expect(() =>
+      parseExpressionTemplate(`${"${".repeat(40)}1${"}".repeat(40)}`),
+    ).toThrow(ExpressionSyntaxError);
+  });
+
+  it("accepts an empty interpolation, a trailing argument comma, and any whitespace", () => {
+    expect(joinLiterals(parseExpressionTemplate("a${}b"))).toEqual(["ab"]);
+    expect(parseExpressionTemplate("${add(a: 1, )}")).toEqual([
+      { call: "add", args: { a: 1 } },
+    ]);
+    expect(parseExpressionTemplate("${ /x }")).toEqual([{ path: "/x" }]);
+    expect(() => parseExpressionTemplate("${add(a: 1 x)}")).toThrow(
+      ExpressionSyntaxError,
+    );
+  });
+});
+
+const evaluate = (
+  name: string,
+  args: Record<string, unknown>,
+  data: Record<string, unknown> = {},
+) => {
+  const warnings: string[] = [];
+  const value = evaluateA2uiValueFunction(name, args, {
+    resolve: (part) =>
+      typeof part === "object" && part !== null && "path" in part
+        ? data[part.path]
+        : undefined,
+    warn: (message) => warnings.push(message),
+    templates: new Map(),
+  });
+  return { value, warnings };
+};
+
+const dateName = (
+  date: Date,
+  options: Intl.DateTimeFormatOptions,
+  type: Intl.DateTimeFormatPartTypes,
+) =>
+  new Intl.DateTimeFormat(undefined, options)
+    .formatToParts(date)
+    .find((part) => part.type === type)!.value;
+
+describe("evaluateA2uiValueFunction", () => {
+  it("interpolates formatString paths and coerces values to text", () => {
+    expect(
+      evaluate(
+        "formatString",
+        { value: "Hi ${/name}, ${count} new ${/flag} ${/missing}|${/tags}" },
+        { "/name": "Ada", count: 3, "/flag": true, "/tags": ["a", "b"] },
+      ),
+    ).toEqual({ value: 'Hi Ada, 3 new true |["a","b"]', warnings: [] });
+  });
+
+  it("warns and skips a malformed formatString template", () => {
+    expect(evaluate("formatString", { value: "Hi ${name" })).toEqual({
+      value: undefined,
+      warnings: [
+        "A2UI formatString template is malformed: an interpolation is not closed.",
+      ],
+    });
+  });
+
+  it("formats numbers and currencies with the requested decimals and grouping", () => {
+    const number = (options: Intl.NumberFormatOptions, value: number) =>
+      new Intl.NumberFormat(undefined, options).format(value);
+
+    expect(evaluate("formatNumber", { value: 1234.5, decimals: 2 })).toEqual({
+      value: number(
+        { minimumFractionDigits: 2, maximumFractionDigits: 2 },
+        1234.5,
+      ),
+      warnings: [],
+    });
+    expect(
+      evaluate("formatNumber", { value: "1500", grouping: false }).value,
+    ).toBe(number({ useGrouping: false }, 1500));
+    expect(
+      evaluate("formatCurrency", { value: 12.5, currency: "USD" }).value,
+    ).toBe(number({ style: "currency", currency: "USD" }, 12.5));
+  });
+
+  it("formats a missing amount as empty text and warns on invalid arguments", () => {
+    expect(evaluate("formatNumber", { value: undefined })).toEqual({
+      value: "",
+      warnings: [],
+    });
+    expect(evaluate("formatNumber", { value: "abc" })).toEqual({
+      value: undefined,
+      warnings: ['A2UI function "formatNumber" received invalid arguments.'],
+    });
+    expect(
+      evaluate("formatNumber", { value: 1, decimals: 1.5 }).warnings,
+    ).toEqual(['A2UI function "formatNumber" received invalid arguments.']);
+    expect(evaluate("formatCurrency", { value: 1 }).warnings).toEqual([
+      'A2UI function "formatCurrency" received invalid arguments.',
+    ]);
+    expect(
+      evaluate("formatCurrency", { value: 1, currency: "not a code" }).warnings,
+    ).toEqual(['A2UI function "formatCurrency" received invalid arguments.']);
+  });
+
+  it("formats dates with TR35 patterns, quoted literals, and padded fields", () => {
+    const value = "2026-01-16T14:05:09";
+    const date = new Date(value);
+    const pm = dateName(date, { hour: "numeric", hour12: true }, "dayPeriod");
+    const format = (pattern: string) =>
+      evaluate("formatDate", { value, format: pattern }).value;
+
+    expect(format("h:mm a")).toBe(`2:05 ${pm}`);
+    expect(format("HH:mm:ss")).toBe("14:05:09");
+    expect(format("yy/M/d, yyyy-MM-dd")).toBe("26/1/16, 2026-01-16");
+    expect(format("EEEE, MMM d 'at' h:mm a")).toBe(
+      `${dateName(date, { weekday: "long" }, "weekday")}, ${dateName(date, { month: "short" }, "month")} 16 at 2:05 ${pm}`,
+    );
+    expect(format("MMMM d, E")).toBe(
+      `${dateName(date, { month: "long" }, "month")} 16, ${dateName(date, { weekday: "short" }, "weekday")}`,
+    );
+    expect(format("h 'o''clock'")).toBe("2 o'clock");
+  });
+
+  it("reads a date-only value as a local calendar date and rejects one out of range", () => {
+    expect(
+      evaluate("formatDate", {
+        value: "2026-01-16",
+        format: "yyyy-MM-dd HH:mm",
+      }).value,
+    ).toBe("2026-01-16 00:00");
+    expect(
+      evaluate("formatDate", { value: "2026-02-30", format: "d" }).warnings,
+    ).toEqual(['A2UI function "formatDate" received invalid arguments.']);
+  });
+
+  it("falls back to an ISO date for an unsupported pattern and warns on an invalid date", () => {
+    const value = "2026-01-16T14:05:09";
+    expect(evaluate("formatDate", { value, format: "YYYY" })).toEqual({
+      value: new Date(value).toISOString(),
+      warnings: [
+        'A2UI function "formatDate" does not support the pattern "YYYY", so it returned an ISO date.',
+      ],
+    });
+    expect(
+      evaluate("formatDate", { value: "not a date", format: "d" }).warnings,
+    ).toEqual(['A2UI function "formatDate" received invalid arguments.']);
+    expect(evaluate("formatDate", { value: undefined, format: "d" })).toEqual({
+      value: "",
+      warnings: [],
+    });
+  });
+
+  it("selects a plural category and falls back to other", () => {
+    const category = new Intl.PluralRules().select(1);
+    expect(
+      evaluate("pluralize", {
+        value: 1,
+        [category]: "1 review",
+        other: "reviews",
+      }).value,
+    ).toBe("1 review");
+    expect(evaluate("pluralize", { value: 2, other: "reviews" }).value).toBe(
+      "reviews",
+    );
+  });
+
+  it("evaluates boolean functions by truthiness", () => {
+    expect(evaluate("and", { values: [true, 1] }).value).toBe(true);
+    expect(evaluate("and", { values: [true, ""] }).value).toBe(false);
+    expect(evaluate("or", { values: [false, "x"] }).value).toBe(true);
+    expect(evaluate("not", { value: 0 }).value).toBe(true);
+    expect(evaluate("not", { value: undefined }).value).toBe(true);
+  });
+
+  it("warns instead of evaluating a function it does not support", () => {
+    expect(evaluate("customValue", {})).toEqual({
+      value: undefined,
+      warnings: [
+        'A2UI function "customValue" is not supported and was skipped.',
+      ],
+    });
+  });
+});