@assistant-ui/react-generative-ui 0.0.6 → 0.0.7

package/src/vocabulary/index.ts

@@ -0,0 +1,27 @@
+import type { GenerativeUILibrary } from "../types";
+import { alertVocabulary } from "./alert";
+import { dataVocabulary } from "./data";
+import { factVocabulary } from "./fact";
+import { interactiveVocabulary } from "./interactive";
+import { layoutVocabulary } from "./layout";
+import { mediaVocabulary } from "./media";
+import { textVocabulary } from "./text";
+
+/**
+ * The closed generative-ui vocabulary the factory ships: a fixed set of
+ * intrinsic components the model may render, each a zod `properties` schema
+ * plus an unstyled structural `render` (semantic HTML with a `data-aui`
+ * attribute naming the component, plus `data-aui-<prop>` hooks, for the host
+ * to style). Users opt in by passing it to
+ * `new JSONGenerativeUI({ library: defaultGenerativeUILibrary })`, and override
+ * or extend entries with their own `defineGenerativeComponents`.
+ */
+export const defaultGenerativeUILibrary: GenerativeUILibrary = {
+  ...textVocabulary,
+  ...mediaVocabulary,
+  ...factVocabulary,
+  ...interactiveVocabulary,
+  ...layoutVocabulary,
+  ...dataVocabulary,
+  ...alertVocabulary,
+};

package/src/vocabulary/interactive.dispatch.test.tsx

@@ -0,0 +1,110 @@
+import { describe, it, expect, vi } from "vitest";
+import { isValidElement, type ReactNode } from "react";
+import { interactiveVocabulary } from "./interactive";
+import { createActionRegistry } from "../actionRegistry";
+
+/** The props shape `Button.render` receives when the renderer injects `$action`
+ * and `$dispatch`. Used to call `render` directly so the test can invoke
+ * `onClick` without a DOM. */
+type ButtonRenderProps = {
+  label: string;
+  $status: "done";
+  $action?: { type: string; [k: string]: unknown };
+  $dispatch?: (a: unknown) => unknown;
+};
+
+describe("interactiveVocabulary $action dispatch", () => {
+  it("Button render attaches an onClick that fires $dispatch with the $action payload", () => {
+    const handler = vi.fn();
+    const registry = createActionRegistry({ purchase: handler });
+    const out = interactiveVocabulary.Button.render({
+      label: "Buy",
+      $status: "done",
+      $action: { type: "purchase", itemId: "sku-1" },
+      $dispatch: registry.dispatch,
+    } as ButtonRenderProps) as ReactNode;
+    expect(isValidElement(out)).toBe(true);
+    const onClick = (out as { props: { onClick: () => void } }).props.onClick;
+    expect(typeof onClick).toBe("function");
+    onClick();
+    expect(handler).toHaveBeenCalledWith({
+      payload: { type: "purchase", itemId: "sku-1" },
+    });
+  });
+
+  it("Button onClick is a no-op when no $dispatch is wired (read-only render)", () => {
+    const out = interactiveVocabulary.Button.render({
+      label: "Buy",
+      $status: "done",
+      $action: { type: "purchase", itemId: "sku-1" },
+    } as ButtonRenderProps) as ReactNode;
+    const onClick = (out as { props: { onClick: () => void } }).props.onClick;
+    expect(typeof onClick).toBe("function");
+    expect(() => onClick()).not.toThrow();
+  });
+
+  it("Button onClick is a no-op when $action is absent", () => {
+    const handler = vi.fn();
+    const registry = createActionRegistry({ purchase: handler });
+    const out = interactiveVocabulary.Button.render({
+      label: "Go",
+      $status: "done",
+      $dispatch: registry.dispatch,
+    } as ButtonRenderProps) as ReactNode;
+    (out as { props: { onClick: () => void } }).props.onClick();
+    expect(handler).not.toHaveBeenCalled();
+  });
+
+  it("Select onChange merges the selected value into $input and preserves a model-supplied $action.value", () => {
+    const handler = vi.fn();
+    const registry = createActionRegistry({ pick: handler });
+    const out = interactiveVocabulary.Select.render({
+      options: [{ label: "A", value: "a" }],
+      $status: "done",
+      $action: { type: "pick", value: "model-supplied" },
+      $dispatch: registry.dispatch,
+    }) as ReactNode;
+    const onChange = (
+      out as {
+        props: { onChange: (e: { currentTarget: { value: string } }) => void };
+      }
+    ).props.onChange;
+    onChange({ currentTarget: { value: "user-picked" } });
+    expect(handler).toHaveBeenCalledWith({
+      payload: {
+        type: "pick",
+        value: "model-supplied",
+        $input: "user-picked",
+      },
+    });
+  });
+
+  it("Input onKeyDown (Enter) merges the entered value into $input", () => {
+    const handler = vi.fn();
+    const registry = createActionRegistry({ submit: handler });
+    const out = interactiveVocabulary.Input.render({
+      $status: "done",
+      $action: { type: "submit" },
+      $dispatch: registry.dispatch,
+    }) as ReactNode;
+    const onKeyDown = (
+      out as {
+        props: {
+          onKeyDown: (e: {
+            key: string;
+            nativeEvent: { isComposing: boolean };
+            currentTarget: { value: string };
+          }) => void;
+        };
+      }
+    ).props.onKeyDown;
+    onKeyDown({
+      key: "Enter",
+      nativeEvent: { isComposing: false },
+      currentTarget: { value: "typed text" },
+    });
+    expect(handler).toHaveBeenCalledWith({
+      payload: { type: "submit", $input: "typed text" },
+    });
+  });
+});

package/src/vocabulary/interactive.test.tsx

@@ -0,0 +1,108 @@
+import { describe, it, expect } from "vitest";
+import { renderToStaticMarkup } from "react-dom/server";
+import { renderGenerativeUI } from "../renderGenerativeUI";
+import { interactiveVocabulary } from "./interactive";
+
+const render = (node: unknown) =>
+  renderToStaticMarkup(<>{renderGenerativeUI(node, interactiveVocabulary)}</>);
+
+describe("interactiveVocabulary", () => {
+  it("Button renders a button with style/block hooks and the label", () => {
+    expect(
+      render({
+        $type: "Button",
+        label: "Go",
+        buttonStyle: "primary",
+        block: true,
+      }),
+    ).toBe(
+      '<button data-aui="button" data-aui-style="primary" data-aui-block="true">Go</button>',
+    );
+  });
+
+  it("Button omits data-aui-block when block is false or omitted", () => {
+    expect(render({ $type: "Button", label: "Go", block: false })).toBe(
+      '<button data-aui="button">Go</button>',
+    );
+  });
+
+  it("Select renders an aria-label when label is provided", () => {
+    const html = render({
+      $type: "Select",
+      label: "Choose",
+      options: [{ label: "A", value: "a" }],
+    });
+    expect(html).toContain('aria-label="Choose"');
+  });
+
+  it("Select keys options by index so duplicate values do not collide", () => {
+    const html = render({
+      $type: "Select",
+      options: [
+        { label: "A", value: "x" },
+        { label: "B", value: "x" },
+      ],
+    });
+    expect(html).toContain('<option value="x">A</option>');
+    expect(html).toContain('<option value="x">B</option>');
+  });
+
+  it("Button stashes $action on a data-aui-action attribute", () => {
+    const html = render({
+      $type: "Button",
+      label: "Buy",
+      $action: { type: "purchase", itemId: "sku-1" },
+    });
+    expect(html).toContain('data-aui-action="');
+    expect(html).toContain("&quot;type&quot;:&quot;purchase&quot;");
+    expect(html).toContain("&quot;itemId&quot;:&quot;sku-1&quot;");
+  });
+
+  it("Button without $action omits the data-aui-action attribute", () => {
+    expect(render({ $type: "Button", label: "Go" })).toBe(
+      '<button data-aui="button">Go</button>',
+    );
+  });
+
+  it("Select renders options with values and a placeholder", () => {
+    const html = render({
+      $type: "Select",
+      placeholder: "Pick one",
+      options: [
+        { label: "A", value: "a" },
+        { label: "B", value: "b" },
+      ],
+    });
+    expect(html).toContain('data-aui="select"');
+    expect(html).toContain(
+      'value="" disabled="" selected="">Pick one</option>',
+    );
+    expect(html).toContain('<option value="a">A</option>');
+    expect(html).toContain('<option value="b">B</option>');
+  });
+
+  it("Input renders a single-line input by default", () => {
+    expect(render({ $type: "Input", placeholder: "type here" })).toBe(
+      '<input data-aui="input" placeholder="type here"/>',
+    );
+  });
+
+  it("Input multiline renders a textarea with the multiline hook", () => {
+    const html = render({ $type: "Input", multiline: true });
+    expect(html).toContain("data-aui-multiline");
+    expect(html).toContain("<textarea");
+  });
+
+  it("DatePicker renders a date input with min/max", () => {
+    const html = render({
+      $type: "DatePicker",
+      value: "2026-01-01",
+      min: "2025-01-01",
+      max: "2027-01-01",
+    });
+    expect(html).toContain('type="date"');
+    expect(html).toContain('value="2026-01-01"');
+    expect(html).toContain('min="2025-01-01"');
+    expect(html).toContain('max="2027-01-01"');
+  });
+});

package/src/vocabulary/interactive.tsx

@@ -0,0 +1,165 @@
+import { z } from "zod";
+import type { Action } from "../ir";
+import { BUTTON_STYLES } from "../ir";
+import type { GenerativeUIDispatch, GenerativeUILibrary } from "../types";
+
+const optionSchema = z.object({
+  label: z.string(),
+  value: z.string(),
+});
+
+const actionAttr = (a: Action | undefined): string | undefined =>
+  a ? JSON.stringify(a) : undefined;
+
+/** 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. */
+const fire = (
+  $action: Action | undefined,
+  $dispatch: GenerativeUIDispatch | undefined,
+  input?: unknown,
+) => {
+  if (!$action || !$dispatch) return;
+  const payload = input === undefined ? $action : { ...$action, $input: input };
+  void Promise.resolve($dispatch(payload)).catch((error) => {
+    queueMicrotask(() => {
+      throw error;
+    });
+  });
+};
+
+export const interactiveVocabulary = {
+  Button: {
+    description:
+      "A clickable button. Carries `$action` describing the side effect or resume value.",
+    properties: z.object({
+      label: z.string().describe("Button label."),
+      buttonStyle: z.enum(BUTTON_STYLES).optional().describe("Visual style."),
+      block: z
+        .boolean()
+        .optional()
+        .describe("Whether the button spans the full width."),
+    }),
+    render: ({ label, buttonStyle, block, $action, $dispatch, children }) => (
+      <button
+        data-aui="button"
+        data-aui-style={buttonStyle}
+        data-aui-block={block || undefined}
+        data-aui-action={actionAttr($action)}
+        onClick={() => fire($action, $dispatch)}
+      >
+        {label}
+        {children}
+      </button>
+    ),
+  },
+  Select: {
+    description:
+      "A dropdown selector. Carries `$action` describing the on-select behavior.",
+    properties: z.object({
+      options: z.array(optionSchema).describe("Selectable options."),
+      placeholder: z
+        .string()
+        .optional()
+        .describe("Placeholder shown when nothing is selected."),
+      label: z
+        .string()
+        .optional()
+        .describe("Accessible label for the control."),
+    }),
+    render: ({ options, placeholder, label, $action, $dispatch, children }) => (
+      <select
+        data-aui="select"
+        data-aui-action={actionAttr($action)}
+        aria-label={label}
+        defaultValue=""
+        onChange={(e) => fire($action, $dispatch, e.currentTarget.value)}
+      >
+        {placeholder ? (
+          <option value="" disabled>
+            {placeholder}
+          </option>
+        ) : null}
+        {options.map((o: { label: string; value: string }, i: number) => (
+          <option key={i} value={o.value}>
+            {o.label}
+          </option>
+        ))}
+        {children}
+      </select>
+    ),
+  },
+  Input: {
+    description:
+      "A text input. Carries `$action` describing the on-submit behavior.",
+    properties: z.object({
+      placeholder: z.string().optional().describe("Placeholder text."),
+      multiline: z
+        .boolean()
+        .optional()
+        .describe("Render a textarea instead of a single-line input."),
+      label: z
+        .string()
+        .optional()
+        .describe("Accessible label for the control."),
+    }),
+    render: ({ placeholder, multiline, label, $action, $dispatch }) => {
+      const submit = (v: string) => fire($action, $dispatch, v);
+      return multiline ? (
+        <textarea
+          data-aui="input"
+          data-aui-multiline
+          data-aui-action={actionAttr($action)}
+          aria-label={label}
+          placeholder={placeholder}
+          onKeyDown={(e) => {
+            if (
+              e.key === "Enter" &&
+              (e.ctrlKey || e.metaKey) &&
+              !e.nativeEvent.isComposing
+            )
+              submit(e.currentTarget.value);
+          }}
+        />
+      ) : (
+        <input
+          data-aui="input"
+          data-aui-action={actionAttr($action)}
+          aria-label={label}
+          placeholder={placeholder}
+          onKeyDown={(e) => {
+            if (e.key === "Enter" && !e.nativeEvent.isComposing)
+              submit(e.currentTarget.value);
+          }}
+        />
+      );
+    },
+  },
+  DatePicker: {
+    description:
+      "A date input. Carries `$action` describing the on-select behavior.",
+    properties: z.object({
+      value: z.string().optional().describe("Initial date (YYYY-MM-DD)."),
+      min: z.string().optional().describe("Minimum date (YYYY-MM-DD)."),
+      max: z.string().optional().describe("Maximum date (YYYY-MM-DD)."),
+      label: z
+        .string()
+        .optional()
+        .describe("Accessible label for the control."),
+    }),
+    render: ({ value, min, max, label, $action, $dispatch }) => (
+      <input
+        type="date"
+        data-aui="datepicker"
+        data-aui-action={actionAttr($action)}
+        aria-label={label}
+        defaultValue={value}
+        min={min}
+        max={max}
+        onChange={(e) => fire($action, $dispatch, e.currentTarget.value)}
+      />
+    ),
+  },
+} satisfies GenerativeUILibrary;

package/src/vocabulary/layout.test.tsx

@@ -0,0 +1,61 @@
+import { describe, it, expect } from "vitest";
+import { renderToStaticMarkup } from "react-dom/server";
+import { renderGenerativeUI } from "../renderGenerativeUI";
+import { layoutVocabulary } from "./layout";
+
+const render = (node: unknown) =>
+  renderToStaticMarkup(<>{renderGenerativeUI(node, layoutVocabulary)}</>);
+
+describe("layoutVocabulary", () => {
+  it("Card renders a section with optional title and padding/background hooks", () => {
+    expect(
+      render({
+        $type: "Card",
+        title: "T",
+        padding: 2,
+        background: "muted",
+      }),
+    ).toBe(
+      '<section data-aui="card" data-aui-padding="2" data-aui-background="muted"><header data-aui="card-title">T</header></section>',
+    );
+  });
+
+  it("Card without a title omits the header", () => {
+    expect(render({ $type: "Card" })).toBe(
+      '<section data-aui="card"></section>',
+    );
+  });
+
+  it("Col renders a div with gap/align hooks and nested children", () => {
+    expect(
+      render({
+        $type: "Col",
+        gap: 2,
+        align: "center",
+        children: { $type: "Text", value: "x" } as never,
+      }),
+    ).toContain('data-aui="col"');
+  });
+
+  it("Row renders a div with gap/align/justify hooks", () => {
+    const html = render({
+      $type: "Row",
+      gap: 4,
+      align: "start",
+      justify: "between",
+    });
+    expect(html).toBe(
+      '<div data-aui="row" data-aui-gap="4" data-aui-align="start" data-aui-justify="between"></div>',
+    );
+  });
+
+  it("Spacer renders an empty div", () => {
+    expect(render({ $type: "Spacer" })).toBe('<div data-aui="spacer"></div>');
+  });
+
+  it("Badge renders a span with the value and variant hook", () => {
+    expect(render({ $type: "Badge", value: "new", variant: "success" })).toBe(
+      '<span data-aui="badge" data-aui-variant="success">new</span>',
+    );
+  });
+});

package/src/vocabulary/layout.tsx

@@ -0,0 +1,76 @@
+import { z } from "zod";
+import type { GenerativeUILibrary } from "../types";
+import { ALIGNS, JUSTIFIES } from "../ir";
+
+export const layoutVocabulary = {
+  Card: {
+    description:
+      "A bordered container grouping related content. Optionally titled.",
+    properties: z.object({
+      title: z.string().optional().describe("Optional card title."),
+      padding: z
+        .number()
+        .optional()
+        .describe("Padding in 4px units (e.g. 2 = 8px)."),
+      background: z.string().optional().describe("Background token or color."),
+    }),
+    render: ({ title, padding, background, children }) => (
+      <section
+        data-aui="card"
+        data-aui-padding={padding}
+        data-aui-background={background}
+      >
+        {title ? <header data-aui="card-title">{title}</header> : null}
+        {children}
+      </section>
+    ),
+  },
+  Col: {
+    description: "A vertical stack; children laid out top to bottom.",
+    properties: z.object({
+      gap: z.number().optional().describe("Gap between children in 4px units."),
+      align: z.enum(ALIGNS).optional().describe("Cross-axis alignment."),
+    }),
+    render: ({ gap, align, children }) => (
+      <div data-aui="col" data-aui-gap={gap} data-aui-align={align}>
+        {children}
+      </div>
+    ),
+  },
+  Row: {
+    description: "A horizontal row; children laid out left to right.",
+    properties: z.object({
+      gap: z.number().optional().describe("Gap between children in 4px units."),
+      align: z.enum(ALIGNS).optional().describe("Cross-axis alignment."),
+      justify: z.enum(JUSTIFIES).optional().describe("Main-axis distribution."),
+    }),
+    render: ({ gap, align, justify, children }) => (
+      <div
+        data-aui="row"
+        data-aui-gap={gap}
+        data-aui-align={align}
+        data-aui-justify={justify}
+      >
+        {children}
+      </div>
+    ),
+  },
+  Spacer: {
+    description: "Empty space that pushes neighbors apart.",
+    properties: z.object({}),
+    render: () => <div data-aui="spacer" />,
+  },
+  Badge: {
+    description: "A small labeled tag, e.g. for status or category.",
+    properties: z.object({
+      value: z.string().describe("Badge text."),
+      variant: z.string().optional().describe("Visual variant token."),
+    }),
+    render: ({ value, variant, children }) => (
+      <span data-aui="badge" data-aui-variant={variant}>
+        {value}
+        {children}
+      </span>
+    ),
+  },
+} satisfies GenerativeUILibrary;

package/src/vocabulary/media.test.tsx

@@ -0,0 +1,53 @@
+import { describe, it, expect } from "vitest";
+import { renderToStaticMarkup } from "react-dom/server";
+import { renderGenerativeUI } from "../renderGenerativeUI";
+import { mediaVocabulary } from "./media";
+
+const render = (node: unknown) =>
+  renderToStaticMarkup(<>{renderGenerativeUI(node, mediaVocabulary)}</>);
+
+describe("mediaVocabulary", () => {
+  it("Image renders an img with src, alt, and size hook", () => {
+    const html = render({
+      $type: "Image",
+      src: "/a.png",
+      alt: "alt",
+      size: "md",
+    });
+    expect(html).toContain(
+      '<img data-aui="image" data-aui-size="md" src="/a.png" alt="alt"/>',
+    );
+  });
+
+  it("Image renders a numeric size as px", () => {
+    const html = render({
+      $type: "Image",
+      src: "/a.png",
+      alt: "alt",
+      size: 128,
+    });
+    expect(html).toContain(
+      '<img data-aui="image" data-aui-size="128px" src="/a.png" alt="alt"/>',
+    );
+  });
+
+  it("Image `alt` is required by the schema (not optional)", () => {
+    const schema = mediaVocabulary.Image.properties as unknown as {
+      safeParse: (v: unknown) => { success: boolean };
+    };
+    expect(schema.safeParse({ src: "/a.png" }).success).toBe(false);
+    expect(schema.safeParse({ src: "/a.png", alt: "x" }).success).toBe(true);
+  });
+
+  it("Divider omits data-aui-flush when flush is false", () => {
+    expect(render({ $type: "Divider", flush: false })).toBe(
+      '<hr data-aui="divider"/>',
+    );
+  });
+
+  it("Divider renders an hr with a flush hook", () => {
+    expect(render({ $type: "Divider", flush: true })).toBe(
+      '<hr data-aui="divider" data-aui-flush="true"/>',
+    );
+  });
+});

package/src/vocabulary/media.tsx

@@ -0,0 +1,37 @@
+import { z } from "zod";
+import type { GenerativeUILibrary } from "../types";
+import { IMAGE_SIZE_TOKENS } from "../ir";
+
+export const mediaVocabulary = {
+  Image: {
+    description: "An image. Provide `src` and `alt` for accessibility.",
+    properties: z.object({
+      src: z.string().describe("Image URL."),
+      alt: z.string().describe("Alt text for accessibility."),
+      size: z
+        .union([z.enum(IMAGE_SIZE_TOKENS), z.number()])
+        .optional()
+        .describe("Size token or pixel value."),
+    }),
+    render: ({ src, alt, size }) => (
+      <img
+        data-aui="image"
+        data-aui-size={typeof size === "number" ? `${size}px` : size}
+        src={src}
+        alt={alt}
+      />
+    ),
+  },
+  Divider: {
+    description: "A horizontal rule between sections.",
+    properties: z.object({
+      flush: z
+        .boolean()
+        .optional()
+        .describe("Whether the divider spans the full width with no inset."),
+    }),
+    render: ({ flush }) => (
+      <hr data-aui="divider" data-aui-flush={flush || undefined} />
+    ),
+  },
+} satisfies GenerativeUILibrary;