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

package/src/vocabulary/layout.tsx

@@ -1,34 +1,138 @@
+import type { CSSProperties, FormEvent } from "react";
 import { z } from "zod";
 import type { GenerativeUILibrary } from "../types";
 import { ALIGNS, JUSTIFIES } from "../ir";
+import { fire } from "./dispatch";
+import { collectFormValuesFromEvent } from "./collectFormValues";
+
+const toCssLength = (value: string | number): string =>
+  typeof value === "number" ? `${value}px` : value;
+
+const cardActionSchema = z.looseObject({
+  type: z
+    .string()
+    .describe("The action type, resolved by the host's action registry."),
+});
+
+const cardFooterButtonSchema = z.object({
+  label: z.string().describe("Footer button label."),
+  $action: cardActionSchema
+    .optional()
+    .describe("Action fired when the button is activated."),
+});
 
 export const layoutVocabulary = {
   Card: {
     description:
-      "A bordered container grouping related content. Optionally titled.",
+      "A bordered container grouping related content. Optionally titled. Set `asForm` to collect named child control values on submit, and `confirm`/`cancel` to add a footer with action buttons.",
     properties: z.object({
       title: z.string().optional().describe("Optional card title."),
       padding: z
         .number()
+        .min(0)
+        .max(8)
+        .optional()
+        .describe(
+          "Padding in 4px units (e.g. 2 = 8px). 0 to 8 is the supported range.",
+        ),
+      background: z
+        .string()
+        .optional()
+        .describe(
+          "Background color or gradient (any CSS background value). Setting this also switches the card's own text to white, since a custom background makes the card a tinted surface; children can still opt into a different color explicitly.",
+        ),
+      asForm: z
+        .boolean()
+        .optional()
+        .describe(
+          "Render as a form; submitting it fires `confirm.$action` with every named child control's value, keyed by `name`.",
+        ),
+      confirm: cardFooterButtonSchema
         .optional()
-        .describe("Padding in 4px units (e.g. 2 = 8px)."),
-      background: z.string().optional().describe("Background token or color."),
+        .describe("Confirm button shown in the footer."),
+      cancel: cardFooterButtonSchema
+        .optional()
+        .describe("Cancel button shown in the footer."),
     }),
-    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>
-    ),
+    render: ({
+      title,
+      padding,
+      background,
+      asForm,
+      confirm,
+      cancel,
+      $dispatch,
+      children,
+    }) => {
+      const Root = asForm ? "form" : "section";
+      const footer =
+        confirm || cancel ? (
+          <footer data-aui="card-footer">
+            {confirm ? (
+              <button
+                type={asForm ? "submit" : "button"}
+                data-aui="card-confirm"
+                onClick={
+                  asForm ? undefined : () => fire(confirm.$action, $dispatch)
+                }
+              >
+                {confirm.label}
+              </button>
+            ) : null}
+            {cancel ? (
+              <button
+                type="button"
+                data-aui="card-cancel"
+                onClick={() => fire(cancel.$action, $dispatch)}
+              >
+                {cancel.label}
+              </button>
+            ) : null}
+          </footer>
+        ) : null;
+
+      return (
+        <Root
+          data-aui="card"
+          data-aui-padding={padding}
+          data-aui-background={background}
+          style={
+            background !== undefined
+              ? { background, color: "white" }
+              : undefined
+          }
+          data-aui-asform={asForm || undefined}
+          onSubmit={
+            asForm
+              ? (event: FormEvent<HTMLFormElement>) => {
+                  event.preventDefault();
+                  fire(
+                    confirm?.$action,
+                    $dispatch,
+                    collectFormValuesFromEvent(event),
+                  );
+                }
+              : undefined
+          }
+        >
+          {title ? <header data-aui="card-title">{title}</header> : null}
+          {children}
+          {footer}
+        </Root>
+      );
+    },
   },
   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."),
+      gap: z
+        .number()
+        .min(0)
+        .max(8)
+        .optional()
+        .describe(
+          "Gap between children in 4px units. 0 to 8 is the supported range.",
+        ),
       align: z.enum(ALIGNS).optional().describe("Cross-axis alignment."),
     }),
     render: ({ gap, align, children }) => (
@@ -40,7 +144,14 @@ export const layoutVocabulary = {
   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."),
+      gap: z
+        .number()
+        .min(0)
+        .max(8)
+        .optional()
+        .describe(
+          "Gap between children in 4px units. 0 to 8 is the supported range.",
+        ),
       align: z.enum(ALIGNS).optional().describe("Cross-axis alignment."),
       justify: z.enum(JUSTIFIES).optional().describe("Main-axis distribution."),
     }),
@@ -73,4 +184,46 @@ export const layoutVocabulary = {
       </span>
     ),
   },
+  Box: {
+    description:
+      "A generic container for composition, e.g. a progress bar built from an outer track Box containing a partial-width fill Box. Size, radius, and background accept arbitrary values, so they render as inline styles rather than data-attribute hooks.",
+    properties: z.object({
+      width: z
+        .union([z.string(), z.number()])
+        .optional()
+        .describe("Width; a number is pixels."),
+      height: z
+        .union([z.string(), z.number()])
+        .optional()
+        .describe("Height; a number is pixels."),
+      radius: z
+        .union([z.literal("full"), z.number()])
+        .optional()
+        .describe(
+          'Corner radius; "full" is a pill/circle, a number is pixels.',
+        ),
+      background: z
+        .string()
+        .optional()
+        .describe("Background color or gradient (any CSS background value)."),
+    }),
+    render: ({ width, height, radius, background, children }) => {
+      const style: CSSProperties = {};
+      if (width !== undefined) style.width = toCssLength(width);
+      if (height !== undefined) style.height = toCssLength(height);
+      if (background !== undefined) style.background = background;
+      if (radius === "full") style.borderRadius = "9999px";
+      else if (typeof radius === "number") style.borderRadius = `${radius}px`;
+
+      return (
+        <div
+          data-aui="box"
+          data-aui-radius={radius === "full" ? "full" : undefined}
+          style={style}
+        >
+          {children}
+        </div>
+      );
+    },
+  },
 } satisfies GenerativeUILibrary;

package/src/vocabulary/list.test.tsx

@@ -0,0 +1,195 @@
+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 { listVocabulary } from "./list";
+
+const render = (node: unknown) =>
+  renderToStaticMarkup(<>{renderGenerativeUI(node, listVocabulary)}</>);
+
+describe("listVocabulary", () => {
+  it("ListView renders a ul wrapping its children", () => {
+    const html = render({
+      $type: "ListView",
+      children: [
+        { $type: "ListViewItem", children: "a" },
+        { $type: "ListViewItem", children: "b" },
+      ],
+    });
+    expect(html).toContain('<ul data-aui="listview">');
+    expect((html.match(/data-aui="listview-item"/g) ?? []).length).toBe(2);
+  });
+
+  it("ListViewItem without $action renders children directly with no trigger wrapper", () => {
+    expect(render({ $type: "ListViewItem", children: "row" })).toBe(
+      '<li data-aui="listview-item">row</li>',
+    );
+  });
+
+  it("ListViewItem with $action but no dispatch renders children directly (read-only)", () => {
+    expect(
+      render({
+        $type: "ListViewItem",
+        $action: { type: "open" },
+        children: "row",
+      }),
+    ).toBe('<li data-aui="listview-item">row</li>');
+  });
+
+  it("ListViewItem wraps children in a clickable trigger when $action and dispatch are both present", () => {
+    const registry = createActionRegistry({ open: vi.fn() });
+    const html = renderToStaticMarkup(
+      <>
+        {renderGenerativeUI(
+          { $type: "ListViewItem", $action: { type: "open" }, children: "row" },
+          listVocabulary,
+          { status: "done", dispatch: registry.dispatch },
+        )}
+      </>,
+    );
+    expect(html).toContain('data-aui="listview-item-trigger"');
+    expect(html).toContain('role="button"');
+    expect(html).toContain('tabindex="0"');
+  });
+});
+
+describe("listVocabulary $action dispatch", () => {
+  const rowOut = (dispatch: (a: unknown) => unknown) =>
+    listVocabulary.ListViewItem.render({
+      $status: "done",
+      $action: { type: "open" },
+      $dispatch: dispatch,
+      children: "row",
+    }) as ReactElement;
+
+  it("clicking the trigger fires $action with no $input", () => {
+    const handler = vi.fn();
+    const registry = createActionRegistry({ open: handler });
+    const trigger = rowOut(registry.dispatch).props.children as ReactElement;
+    const onClick = (trigger.props as { onClick: (e: unknown) => void })
+      .onClick;
+    onClick({ target: { closest: () => null } });
+    expect(handler).toHaveBeenCalledWith({ payload: { type: "open" } });
+  });
+
+  type KeyDownEvent = {
+    key: string;
+    target: { closest: (selector: string) => unknown };
+    preventDefault: () => void;
+  };
+
+  const getOnKeyDown = (dispatch: (a: unknown) => unknown) => {
+    const trigger = rowOut(dispatch).props.children as ReactElement;
+    return (trigger.props as { onKeyDown: (e: KeyDownEvent) => void })
+      .onKeyDown;
+  };
+
+  it("Enter and Space keydown both fire $action", () => {
+    const handler = vi.fn();
+    const registry = createActionRegistry({ open: handler });
+    const onKeyDown = getOnKeyDown(registry.dispatch);
+    onKeyDown({
+      key: "Enter",
+      target: { closest: () => null },
+      preventDefault: vi.fn(),
+    });
+    onKeyDown({
+      key: " ",
+      target: { closest: () => null },
+      preventDefault: vi.fn(),
+    });
+    expect(handler).toHaveBeenCalledTimes(2);
+  });
+
+  it("a keydown for any other key does not fire $action", () => {
+    const handler = vi.fn();
+    const registry = createActionRegistry({ open: handler });
+    const onKeyDown = getOnKeyDown(registry.dispatch);
+    onKeyDown({
+      key: "Tab",
+      target: { closest: () => null },
+      preventDefault: vi.fn(),
+    });
+    expect(handler).not.toHaveBeenCalled();
+  });
+
+  it("a click whose target sits inside a nested interactive element does not fire the row action", () => {
+    const handler = vi.fn();
+    const registry = createActionRegistry({ open: handler });
+    const trigger = rowOut(registry.dispatch).props.children as ReactElement;
+    const onClick = (trigger.props as { onClick: (e: unknown) => void })
+      .onClick;
+    const nestedButton = {
+      closest: (selector: string) =>
+        selector.includes("button") ? nestedButton : null,
+    };
+    onClick({ target: nestedButton });
+    expect(handler).not.toHaveBeenCalled();
+  });
+
+  it("a keydown Enter whose target sits inside a nested interactive element does not fire the row action", () => {
+    const handler = vi.fn();
+    const registry = createActionRegistry({ open: handler });
+    const onKeyDown = getOnKeyDown(registry.dispatch);
+    const nestedInput = {
+      closest: (selector: string) =>
+        selector.includes("input") ? nestedInput : null,
+    };
+    const preventDefault = vi.fn();
+    onKeyDown({ key: "Enter", target: nestedInput, preventDefault });
+    expect(handler).not.toHaveBeenCalled();
+    expect(preventDefault).not.toHaveBeenCalled();
+  });
+
+  it('a click whose target sits inside a nested role="button" element does not fire the row action', () => {
+    const handler = vi.fn();
+    const registry = createActionRegistry({ open: handler });
+    const trigger = rowOut(registry.dispatch).props.children as ReactElement;
+    const onClick = (trigger.props as { onClick: (e: unknown) => void })
+      .onClick;
+    const nestedRoleButton = {
+      closest: (selector: string) =>
+        selector.includes('[role="button"]') ? nestedRoleButton : null,
+    };
+    onClick({ target: nestedRoleButton });
+    expect(handler).not.toHaveBeenCalled();
+  });
+
+  it('a keydown Enter whose target sits inside a nested role="button" element (e.g. a nested ListViewItem trigger) does not fire the row action', () => {
+    const handler = vi.fn();
+    const registry = createActionRegistry({ open: handler });
+    const onKeyDown = getOnKeyDown(registry.dispatch);
+    const nestedRoleButton = {
+      closest: (selector: string) =>
+        selector.includes('[role="button"]') ? nestedRoleButton : null,
+    };
+    const preventDefault = vi.fn();
+    onKeyDown({ key: "Enter", target: nestedRoleButton, preventDefault });
+    expect(handler).not.toHaveBeenCalled();
+  });
+
+  it("Space on the trigger itself fires the row action and prevents default", () => {
+    const handler = vi.fn();
+    const registry = createActionRegistry({ open: handler });
+    const onKeyDown = getOnKeyDown(registry.dispatch);
+    const preventDefault = vi.fn();
+    onKeyDown({ key: " ", target: { closest: () => null }, preventDefault });
+    expect(handler).toHaveBeenCalledWith({ payload: { type: "open" } });
+    expect(preventDefault).toHaveBeenCalledTimes(1);
+  });
+
+  it("Enter on the trigger itself fires without calling preventDefault", () => {
+    const handler = vi.fn();
+    const registry = createActionRegistry({ open: handler });
+    const onKeyDown = getOnKeyDown(registry.dispatch);
+    const preventDefault = vi.fn();
+    onKeyDown({
+      key: "Enter",
+      target: { closest: () => null },
+      preventDefault,
+    });
+    expect(handler).toHaveBeenCalledWith({ payload: { type: "open" } });
+    expect(preventDefault).not.toHaveBeenCalled();
+  });
+});

package/src/vocabulary/list.tsx

@@ -0,0 +1,48 @@
+import { z } from "zod";
+import type { GenerativeUILibrary } from "../types";
+import { fire } from "./dispatch";
+
+const INTERACTIVE_DESCENDANT_SELECTOR =
+  'button, a, input, select, textarea, label, [role="button"], [role="link"], [role="checkbox"], [role="radio"], [role="switch"], [role="textbox"], [role="combobox"], [role="menuitem"]';
+
+export const listVocabulary = {
+  ListView: {
+    description:
+      "A vertical list container. Wrap `ListViewItem` children as rows.",
+    properties: z.object({}),
+    render: ({ children }) => <ul data-aui="listview">{children}</ul>,
+  },
+  ListViewItem: {
+    description:
+      "A row inside a ListView. Carries `$action` to make the whole row clickable and keyboard-activatable.",
+    properties: z.object({}),
+    render: ({ $action, $dispatch, children }) => {
+      if (!$action || !$dispatch) {
+        return <li data-aui="listview-item">{children}</li>;
+      }
+      return (
+        <li data-aui="listview-item">
+          <div
+            role="button"
+            tabIndex={0}
+            data-aui="listview-item-trigger"
+            onClick={(event) => {
+              const target = event.target as Element;
+              if (target.closest(INTERACTIVE_DESCENDANT_SELECTOR)) return;
+              fire($action, $dispatch);
+            }}
+            onKeyDown={(event) => {
+              if (event.key !== "Enter" && event.key !== " ") return;
+              const target = event.target as Element;
+              if (target.closest(INTERACTIVE_DESCENDANT_SELECTOR)) return;
+              if (event.key === " ") event.preventDefault();
+              fire($action, $dispatch);
+            }}
+          >
+            {children}
+          </div>
+        </li>
+      );
+    },
+  },
+} satisfies GenerativeUILibrary;

package/src/vocabulary/media.test.tsx

@@ -19,16 +19,27 @@ describe("mediaVocabulary", () => {
     );
   });
 
-  it("Image renders a numeric size as px", () => {
+  it("Image renders a numeric size as an inline max-width style, not a dead data-aui-size attribute", () => {
     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"/>',
-    );
+    expect(html).not.toContain("data-aui-size");
+    expect(html).toContain('style="max-width:128px"');
+  });
+
+  it("Image renders a numeric size on a round avatar as an inline width/height square", () => {
+    const html = render({
+      $type: "Image",
+      src: "/a.png",
+      alt: "avatar",
+      size: 64,
+      round: true,
+    });
+    expect(html).not.toContain("data-aui-size");
+    expect(html).toContain('style="width:64px;height:64px"');
   });
 
   it("Image `alt` is required by the schema (not optional)", () => {
@@ -39,6 +50,27 @@ describe("mediaVocabulary", () => {
     expect(schema.safeParse({ src: "/a.png", alt: "x" }).success).toBe(true);
   });
 
+  it("Image omits data-aui-round when round is not set", () => {
+    const html = render({ $type: "Image", src: "/a.png", alt: "alt" });
+    expect(html).not.toContain("data-aui-round");
+  });
+
+  it("Image renders data-aui-round when round is true", () => {
+    const html = render({
+      $type: "Image",
+      src: "/a.png",
+      alt: "avatar",
+      round: true,
+    });
+    expect(html).toContain('data-aui-round="true"');
+  });
+
+  it("Image with a missing alt still renders (defensive: schema validation is not runtime enforcement)", () => {
+    expect(() =>
+      render({ $type: "Image", src: "/a.png" } as never),
+    ).not.toThrow();
+  });
+
   it("Divider omits data-aui-flush when flush is false", () => {
     expect(render({ $type: "Divider", flush: false })).toBe(
       '<hr data-aui="divider"/>',

package/src/vocabulary/media.tsx

@@ -1,3 +1,4 @@
+import type { CSSProperties } from "react";
 import { z } from "zod";
 import type { GenerativeUILibrary } from "../types";
 import { IMAGE_SIZE_TOKENS } from "../ir";
@@ -12,15 +13,33 @@ export const mediaVocabulary = {
         .union([z.enum(IMAGE_SIZE_TOKENS), z.number()])
         .optional()
         .describe("Size token or pixel value."),
+      round: z
+        .boolean()
+        .optional()
+        .describe(
+          "Render as a circular avatar (fully rounded, cropped to a square).",
+        ),
     }),
-    render: ({ src, alt, size }) => (
-      <img
-        data-aui="image"
-        data-aui-size={typeof size === "number" ? `${size}px` : size}
-        src={src}
-        alt={alt}
-      />
-    ),
+    render: ({ src, alt, size, round }) => {
+      const numericSize = typeof size === "number" ? size : undefined;
+      const style: CSSProperties | undefined =
+        numericSize === undefined
+          ? undefined
+          : round
+            ? { width: `${numericSize}px`, height: `${numericSize}px` }
+            : { maxWidth: `${numericSize}px` };
+
+      return (
+        <img
+          data-aui="image"
+          data-aui-size={numericSize === undefined ? size : undefined}
+          data-aui-round={round || undefined}
+          src={src}
+          alt={alt}
+          style={style}
+        />
+      );
+    },
   },
   Divider: {
     description: "A horizontal rule between sections.",