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

package/src/vocabulary/alert.test.tsx

@@ -1,5 +1,9 @@
-import { describe, it, expect } from "vitest";
+// @vitest-environment jsdom
+
+import { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
 import { renderToStaticMarkup } from "react-dom/server";
+import { afterEach, describe, expect, it, vi } from "vitest";
 import { renderGenerativeUI } from "../renderGenerativeUI";
 import { alertVocabulary } from "./alert";
 import { defaultGenerativeUILibrary } from "./index";
@@ -7,6 +11,99 @@ import { defaultGenerativeUILibrary } from "./index";
 const render = (node: unknown) =>
   renderToStaticMarkup(<>{renderGenerativeUI(node, alertVocabulary)}</>);
 
+(
+  globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }
+).IS_REACT_ACT_ENVIRONMENT = true;
+
+let root: Root | undefined;
+
+afterEach(async () => {
+  await act(async () => root?.unmount());
+  root = undefined;
+  document.body.innerHTML = "";
+});
+
+const carousel = {
+  $type: "Carousel",
+  children: [
+    { $type: "Card", title: "One" },
+    { $type: "Card", title: "Two" },
+    { $type: "Card", title: "Three" },
+  ],
+};
+
+const mountCarousel = async (node: unknown = carousel) => {
+  const container = document.createElement("div");
+  document.body.append(container);
+  root = createRoot(container);
+  await act(async () => {
+    root!.render(renderGenerativeUI(node, defaultGenerativeUILibrary));
+  });
+  const track = container.querySelector<HTMLDivElement>(
+    '[data-aui="carousel"]',
+  );
+  if (!track) throw new Error("Carousel track was not rendered.");
+  return { container, track };
+};
+
+const setCarouselLayout = (
+  track: HTMLDivElement,
+  {
+    scrollWidth,
+    clientWidth,
+    scrollLeft,
+  }: { scrollWidth: number; clientWidth: number; scrollLeft: number },
+) => {
+  const rtl = track.style.direction === "rtl";
+  const rect = (left: number, width: number) =>
+    ({
+      left,
+      right: left + width,
+      width,
+      top: 0,
+      bottom: 100,
+      height: 100,
+      x: left,
+      y: 0,
+      toJSON: () => ({}),
+    }) as DOMRect;
+  const trackLeft = 140;
+  Object.defineProperties(track, {
+    scrollWidth: { configurable: true, value: scrollWidth },
+    clientWidth: { configurable: true, value: clientWidth },
+    scrollLeft: { configurable: true, value: scrollLeft, writable: true },
+    getBoundingClientRect: {
+      configurable: true,
+      value: () => rect(trackLeft, clientWidth),
+    },
+  });
+  track
+    .querySelectorAll<HTMLElement>(':scope > [data-aui="carousel-slide"]')
+    .forEach((slide, index) => {
+      Object.defineProperty(slide, "getBoundingClientRect", {
+        configurable: true,
+        value: () => {
+          const offset = index * 200 - Math.abs(track.scrollLeft);
+          return rtl
+            ? rect(trackLeft + clientWidth - offset - 188, 188)
+            : rect(trackLeft + offset, 188);
+        },
+      });
+    });
+  const scrollBy = vi.fn();
+  Object.defineProperty(track, "scrollBy", {
+    configurable: true,
+    value: scrollBy,
+  });
+  return scrollBy;
+};
+
+const measure = async () => {
+  await act(async () => {
+    window.dispatchEvent(new Event("resize"));
+  });
+};
+
 describe("alertVocabulary", () => {
   it("Alert renders with title/description/tone, defaulting tone to info", () => {
     expect(
@@ -69,15 +166,18 @@ describe("alertVocabulary", () => {
   });
 
   it("Carousel without a label renders role=group, no aria-label, and no double-name landmark", () => {
-    expect(render({ $type: "Carousel" })).toBe(
-      '<div data-aui="carousel" role="group" aria-roledescription="carousel" tabindex="0"></div>',
-    );
+    const html = render({ $type: "Carousel" });
+    expect(html).toContain('data-aui="carousel"');
+    expect(html).toContain('role="group"');
+    expect(html).toContain('aria-roledescription="carousel"');
+    expect(html).toContain('tabindex="0"');
+    expect(html).not.toContain("aria-label");
   });
 
   it("Carousel with a label renders role=region and the given aria-label", () => {
-    expect(render({ $type: "Carousel", label: "Featured" })).toBe(
-      '<div data-aui="carousel" role="region" aria-roledescription="carousel" aria-label="Featured" tabindex="0"></div>',
-    );
+    const html = render({ $type: "Carousel", label: "Featured" });
+    expect(html).toContain('role="region"');
+    expect(html).toContain('aria-label="Featured"');
   });
 
   it("Carousel container carries region semantics and an optional label", () => {
@@ -143,4 +243,185 @@ describe("alertVocabulary", () => {
     expect(html).toContain('aria-label="10 of 10"');
     expect(html).not.toContain("11 of 10");
   });
+
+  it("Carousel server markup keeps the track inside an always-present frame", () => {
+    const html = renderToStaticMarkup(
+      <>{renderGenerativeUI(carousel, defaultGenerativeUILibrary)}</>,
+    );
+    expect(html).toMatch(
+      /<div data-aui="carousel-frame"><div id="[^"]+" data-aui="carousel"/,
+    );
+  });
+
+  it("Carousel does not render controls when its slides fit", async () => {
+    const { container, track } = await mountCarousel();
+    setCarouselLayout(track, {
+      scrollWidth: 300,
+      clientWidth: 300,
+      scrollLeft: 0,
+    });
+    await measure();
+    expect(
+      container.querySelector('[data-aui="carousel-controls"]'),
+    ).toBeNull();
+  });
+
+  it("Carousel renders overflow controls with Previous disabled at the start", async () => {
+    const { container, track } = await mountCarousel();
+    setCarouselLayout(track, {
+      scrollWidth: 600,
+      clientWidth: 300,
+      scrollLeft: 0,
+    });
+    await measure();
+
+    const previous = container.querySelector<HTMLButtonElement>(
+      '[data-aui="carousel-prev"]',
+    );
+    const next = container.querySelector<HTMLButtonElement>(
+      '[data-aui="carousel-next"]',
+    );
+    expect(previous).not.toBeNull();
+    expect(next).not.toBeNull();
+    expect(previous!.disabled).toBe(true);
+    expect(next!.disabled).toBe(false);
+    expect(previous!.getAttribute("aria-controls")).toBe(track.id);
+    expect(next!.getAttribute("aria-controls")).toBe(track.id);
+  });
+
+  it("Carousel remeasures streamed slides and observes each slide", async () => {
+    const originalResizeObserver = globalThis.ResizeObserver;
+    class TestResizeObserver {
+      static instances: TestResizeObserver[] = [];
+      readonly observed = new Set<Element>();
+
+      constructor() {
+        TestResizeObserver.instances.push(this);
+      }
+
+      observe(element: Element) {
+        this.observed.add(element);
+      }
+
+      disconnect() {}
+    }
+    globalThis.ResizeObserver =
+      TestResizeObserver as unknown as typeof ResizeObserver;
+
+    try {
+      const { container, track } = await mountCarousel({
+        $type: "Carousel",
+        children: [{ $type: "Card", title: "One" }],
+      });
+      setCarouselLayout(track, {
+        scrollWidth: 600,
+        clientWidth: 300,
+        scrollLeft: 0,
+      });
+      await act(async () => {
+        root!.render(
+          renderGenerativeUI(
+            {
+              $type: "Carousel",
+              children: [
+                { $type: "Card", title: "One" },
+                { $type: "Card", title: "Two" },
+                { $type: "Card", title: "Three" },
+              ],
+            },
+            defaultGenerativeUILibrary,
+          ),
+        );
+      });
+
+      expect(
+        container.querySelector('[data-aui="carousel-controls"]'),
+      ).not.toBeNull();
+      const observer = TestResizeObserver.instances.at(-1);
+      expect([...observer!.observed]).toEqual([
+        track,
+        ...track.querySelectorAll('[data-aui="carousel-slide"]'),
+      ]);
+    } finally {
+      globalThis.ResizeObserver = originalResizeObserver;
+    }
+  });
+
+  it("Carousel moves to the next slide start", async () => {
+    const { container, track } = await mountCarousel();
+    const scrollBy = setCarouselLayout(track, {
+      scrollWidth: 600,
+      clientWidth: 300,
+      scrollLeft: 0,
+    });
+    await measure();
+
+    const next = container.querySelector<HTMLButtonElement>(
+      '[data-aui="carousel-next"]',
+    );
+    await act(async () => next!.click());
+    expect(scrollBy).toHaveBeenCalledWith({ left: 200 });
+  });
+
+  it("Carousel moves back one slide from the middle", async () => {
+    const { container, track } = await mountCarousel();
+    const scrollBy = setCarouselLayout(track, {
+      scrollWidth: 600,
+      clientWidth: 300,
+      scrollLeft: 200,
+    });
+    await measure();
+
+    const previous = container.querySelector<HTMLButtonElement>(
+      '[data-aui="carousel-prev"]',
+    );
+    expect(previous!.disabled).toBe(false);
+    await act(async () => previous!.click());
+    expect(scrollBy).toHaveBeenCalledWith({ left: -200 });
+  });
+
+  it("Carousel pages toward the inline end in right-to-left layouts", async () => {
+    const { container, track } = await mountCarousel();
+    track.style.direction = "rtl";
+    const scrollBy = setCarouselLayout(track, {
+      scrollWidth: 600,
+      clientWidth: 300,
+      scrollLeft: 0,
+    });
+    await measure();
+
+    const next = container.querySelector<HTMLButtonElement>(
+      '[data-aui="carousel-next"]',
+    );
+    await act(async () => next!.click());
+    expect(scrollBy).toHaveBeenCalledWith({ left: -200 });
+
+    track.scrollLeft = -300;
+    await act(async () => {
+      track.dispatchEvent(new Event("scroll"));
+    });
+    expect(next!.disabled).toBe(true);
+  });
+
+  it("Carousel disables Next at the scroll end", async () => {
+    const { container, track } = await mountCarousel();
+    setCarouselLayout(track, {
+      scrollWidth: 600,
+      clientWidth: 300,
+      scrollLeft: 300,
+    });
+    await measure();
+
+    const next = container.querySelector<HTMLButtonElement>(
+      '[data-aui="carousel-next"]',
+    );
+    expect(next!.disabled).toBe(true);
+  });
+
+  it("Carousel server markup does not contain controls", () => {
+    const html = renderToStaticMarkup(
+      <>{renderGenerativeUI(carousel, defaultGenerativeUILibrary)}</>,
+    );
+    expect(html).not.toContain('data-aui="carousel-controls"');
+  });
 });

package/src/vocabulary/alert.tsx

@@ -1,4 +1,4 @@
-import { Children } from "react";
+import * as React from "react";
 import { z } from "zod";
 import type { GenerativeUILibrary } from "../types";
 import { ALERT_TONES } from "../ir";
@@ -6,6 +6,172 @@ import { toTextContent } from "./toTextContent";
 
 const MAX_CARDS = 10;
 
+type CarouselRenderProps = {
+  label?: string;
+  children?: React.ReactNode;
+};
+
+type CarouselMeasurement = {
+  overflows: boolean;
+  atStart: boolean;
+  atEnd: boolean;
+};
+
+function CarouselRender({ label, children }: CarouselRenderProps) {
+  const carouselId = React.useId();
+  const carouselRef = React.useRef<HTMLDivElement>(null);
+  const [measurement, setMeasurement] = React.useState<
+    CarouselMeasurement | undefined
+  >(undefined);
+  const cards = React.Children.toArray(children).slice(0, MAX_CARDS);
+  const n = cards.length;
+
+  React.useEffect(() => {
+    const carousel = carouselRef.current;
+    if (!carousel) return;
+
+    const measure = () => {
+      const maxScrollLeft = Math.max(
+        carousel.scrollWidth - carousel.clientWidth,
+        0,
+      );
+      const position = Math.abs(carousel.scrollLeft);
+      const next = {
+        overflows: maxScrollLeft > 0,
+        atStart: position <= 1,
+        atEnd: position >= maxScrollLeft - 1,
+      };
+      setMeasurement((current) =>
+        current?.overflows === next.overflows &&
+        current.atStart === next.atStart &&
+        current.atEnd === next.atEnd
+          ? current
+          : next,
+      );
+    };
+
+    measure();
+    carousel.addEventListener("scroll", measure, { passive: true });
+    window.addEventListener("resize", measure);
+    const resizeObserver =
+      typeof ResizeObserver === "undefined"
+        ? undefined
+        : new ResizeObserver(measure);
+    resizeObserver?.observe(carousel);
+    carousel
+      .querySelectorAll(':scope > [data-aui="carousel-slide"]')
+      .forEach((slide) => resizeObserver?.observe(slide));
+
+    return () => {
+      carousel.removeEventListener("scroll", measure);
+      window.removeEventListener("resize", measure);
+      resizeObserver?.disconnect();
+    };
+  }, [n]);
+
+  const move = (direction: "previous" | "next") => {
+    const carousel = carouselRef.current;
+    if (!carousel) return;
+
+    const rtl = getComputedStyle(carousel).direction === "rtl";
+    const startOf = (element: Element) => {
+      const rect = element.getBoundingClientRect();
+      return rtl ? -rect.right : rect.left;
+    };
+    const edge = startOf(carousel);
+    const starts = Array.from(
+      carousel.querySelectorAll(':scope > [data-aui="carousel-slide"]'),
+      startOf,
+    );
+    let current = 0;
+    starts.forEach((start, index) => {
+      if (
+        Math.abs(start - edge) < Math.abs((starts[current] ?? start) - edge)
+      ) {
+        current = index;
+      }
+    });
+    const origin = starts[current];
+    const target = starts[current + (direction === "next" ? 1 : -1)];
+    if (origin === undefined || target === undefined) return;
+    carousel.scrollBy({ left: rtl ? origin - target : target - origin });
+  };
+
+  return (
+    <div data-aui="carousel-frame">
+      <div
+        ref={carouselRef}
+        id={carouselId}
+        data-aui="carousel"
+        role={label ? "region" : "group"}
+        aria-roledescription="carousel"
+        aria-label={label}
+        tabIndex={0}
+      >
+        {cards.map((card, i) => (
+          <div
+            key={i}
+            data-aui="carousel-slide"
+            role="group"
+            aria-roledescription="slide"
+            aria-label={`${i + 1} of ${n}`}
+          >
+            {card}
+          </div>
+        ))}
+      </div>
+      {measurement?.overflows ? (
+        <div data-aui="carousel-controls">
+          <button
+            type="button"
+            data-aui="carousel-prev"
+            aria-label="Previous slide"
+            aria-controls={carouselId}
+            disabled={measurement.atStart}
+            onClick={() => move("previous")}
+          >
+            <svg
+              aria-hidden="true"
+              viewBox="0 0 24 24"
+              width="16"
+              height="16"
+              fill="none"
+              stroke="currentColor"
+              strokeWidth="2"
+              strokeLinecap="round"
+              strokeLinejoin="round"
+            >
+              <path d="M9 5l7 7-7 7" transform="translate(24 0) scale(-1 1)" />
+            </svg>
+          </button>
+          <button
+            type="button"
+            data-aui="carousel-next"
+            aria-label="Next slide"
+            aria-controls={carouselId}
+            disabled={measurement.atEnd}
+            onClick={() => move("next")}
+          >
+            <svg
+              aria-hidden="true"
+              viewBox="0 0 24 24"
+              width="16"
+              height="16"
+              fill="none"
+              stroke="currentColor"
+              strokeWidth="2"
+              strokeLinecap="round"
+              strokeLinejoin="round"
+            >
+              <path d="M9 5l7 7-7 7" />
+            </svg>
+          </button>
+        </div>
+      ) : null}
+    </div>
+  );
+}
+
 export const alertVocabulary = {
   Alert: {
     description:
@@ -46,30 +212,6 @@ export const alertVocabulary = {
         .optional()
         .describe("Accessible label for the carousel."),
     }),
-    render: ({ label, children }) => {
-      const cards = Children.toArray(children).slice(0, MAX_CARDS);
-      const n = cards.length;
-      return (
-        <div
-          data-aui="carousel"
-          role={label ? "region" : "group"}
-          aria-roledescription="carousel"
-          aria-label={label}
-          tabIndex={0}
-        >
-          {cards.map((card, i) => (
-            <div
-              key={i}
-              data-aui="carousel-slide"
-              role="group"
-              aria-roledescription="slide"
-              aria-label={`${i + 1} of ${n}`}
-            >
-              {card}
-            </div>
-          ))}
-        </div>
-      );
-    },
+    render: CarouselRender,
   },
 } satisfies GenerativeUILibrary;

package/src/vocabulary/collectFormValues.test.ts

@@ -5,7 +5,7 @@ import {
   collectFormValues,
   type FormControlElementLike,
 } from "./collectFormValues";
-import { GENERATED_NAME_ATTR } from "../constants";
+import { CHECKBOX_GROUP_ATTR, GENERATED_NAME_ATTR } from "../constants";
 
 const el = (
   partial: Partial<FormControlElementLike>,
@@ -51,6 +51,27 @@ describe("collectFormValues", () => {
     expect(values.size).toBeUndefined();
   });
 
+  it("resolves a checkbox group to its checked values in document order", () => {
+    const option = (value: string, checked: boolean) =>
+      el({
+        name: "toppings",
+        type: "checkbox",
+        value,
+        checked,
+        hasAttribute: (name) => name === CHECKBOX_GROUP_ATTR,
+      });
+    expect(
+      collectFormValues([
+        option("basil", true),
+        option("olives", false),
+        option("onion", true),
+      ]),
+    ).toEqual({ toppings: ["basil", "onion"] });
+    expect(collectFormValues([option("basil", false)])).toEqual({
+      toppings: [],
+    });
+  });
+
   it("resolves select/input/textarea/date controls to their string value", () => {
     expect(
       collectFormValues([
@@ -67,6 +88,12 @@ describe("collectFormValues", () => {
     });
   });
 
+  it("resolves a range input to its numeric value", () => {
+    expect(
+      collectFormValues([el({ name: "volume", type: "range", value: "7" })]),
+    ).toEqual({ volume: 7 });
+  });
+
   it("collects repeated non-radio names into an array in document order", () => {
     expect(
       collectFormValues([

package/src/vocabulary/collectFormValues.ts

@@ -1,5 +1,9 @@
 import type { FormEvent } from "react";
-import { GENERATED_NAME_ATTR } from "../constants";
+import {
+  CHECKBOX_GROUP_ATTR,
+  FIELD_NAME_ATTR,
+  GENERATED_NAME_ATTR,
+} from "../constants";
 
 /**
  * The subset of `HTMLInputElement`/`HTMLSelectElement`/`HTMLTextAreaElement` that {@link collectFormValues} reads. A structural type rather than the DOM interfaces themselves, so a plain object can stand in for a form control in tests.
@@ -11,11 +15,12 @@ export type FormControlElementLike = {
   readonly checked?: boolean;
   readonly disabled: boolean;
   readonly hasAttribute: (name: string) => boolean;
+  readonly getAttribute?: ((name: string) => string | null) | undefined;
   readonly matches?: ((selector: string) => boolean) | undefined;
 };
 
 /**
- * Collects a submitted form's named control values into a plain object, keyed by `name`, in document order. Reads each control's live DOM state rather than `FormData`, so a checkbox resolves to its `checked` boolean instead of an on/off string. A radio group resolves to its checked option's `value`, or `undefined` if none is checked. Any other repeated `name` resolves to an array of its controls' values, in document order. Controls without a `name`, that carry `data-aui-generated-name`, or that are effectively disabled, including through an ancestor disabled fieldset outside its first legend, are skipped entirely.
+ * Collects a submitted form's named control values into a plain object, keyed by `name`, in document order. Reads each control's live DOM state rather than `FormData`, so a checkbox resolves to its `checked` boolean instead of an on/off string. A radio group resolves to its checked option's `value`, or `undefined` if none is checked. A checkbox group resolves to its checked options' values in document order, or an empty array if none is checked. Any other repeated `name` resolves to an array of its controls' values, in document order. Controls without a `name`, that carry `data-aui-generated-name`, or that are effectively disabled, including through an ancestor disabled fieldset outside its first legend, are skipped entirely.
  */
 export function collectFormValues(
   elements: ArrayLike<FormControlElementLike>,
@@ -23,7 +28,8 @@ export function collectFormValues(
   const values: Record<string, unknown> = Object.create(null);
 
   for (const element of Array.from(elements)) {
-    const { name, disabled } = element;
+    const { disabled } = element;
+    const name = element.getAttribute?.(FIELD_NAME_ATTR) ?? element.name;
     if (
       !name ||
       disabled ||
@@ -38,8 +44,22 @@ export function collectFormValues(
       continue;
     }
 
-    const value: string | boolean =
-      element.type === "checkbox" ? (element.checked ?? false) : element.value;
+    if (
+      element.type === "checkbox" &&
+      element.hasAttribute(CHECKBOX_GROUP_ATTR)
+    ) {
+      const existing = values[name];
+      const checked = Array.isArray(existing) ? existing : [];
+      values[name] = element.checked ? [...checked, element.value] : checked;
+      continue;
+    }
+
+    const value: string | number | boolean =
+      element.type === "checkbox"
+        ? (element.checked ?? false)
+        : element.type === "range"
+          ? Number(element.value)
+          : element.value;
 
     if (Object.hasOwn(values, name)) {
       const existing = values[name];