@agent-native/toolkit 0.0.0-beta-20260819143124

package/src/design-system/definition.ts

@@ -0,0 +1,14 @@
+import type { DesignSystemTheme } from "./theme.js";
+import type { DesignSystemComponents } from "./types.js";
+
+export interface DesignSystemDefinition {
+  name?: string;
+  components?: Partial<DesignSystemComponents>;
+  theme?: DesignSystemTheme;
+}
+
+export function defineDesignSystem<
+  const Definition extends DesignSystemDefinition,
+>(definition: Definition): Definition {
+  return definition;
+}

package/src/design-system/design-system.spec.tsx

@@ -0,0 +1,356 @@
+// @vitest-environment happy-dom
+
+import { act, forwardRef, type ComponentProps } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { ToolkitProvider } from "../provider.js";
+import { Button } from "../ui/button.js";
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from "../ui/dropdown-menu.js";
+import { Popover, PopoverContent, PopoverTrigger } from "../ui/popover.js";
+import { ActionButton, IconButton } from "./components.js";
+import { defaultDesignSystemComponents } from "./default-adapter.js";
+import { defineDesignSystem } from "./definition.js";
+import { defineTheme } from "./theme.js";
+import { DESIGN_SYSTEM_CONTRACT_VERSION } from "./types.js";
+
+describe("design-system contract", () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(() => {
+    vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", true);
+    container = document.createElement("div");
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(() => {
+    act(() => root.unmount());
+    container.remove();
+    vi.restoreAllMocks();
+    vi.unstubAllGlobals();
+  });
+
+  it("locks the seventeen semantic component names", () => {
+    expect(DESIGN_SYSTEM_CONTRACT_VERSION).toBe(1);
+    expect(Object.keys(defaultDesignSystemComponents).sort()).toEqual(
+      [
+        "ActionButton",
+        "Avatar",
+        "Checkbox",
+        "Dialog",
+        "IconButton",
+        "Menu",
+        "Picker",
+        "Popover",
+        "Skeleton",
+        "Spinner",
+        "Status",
+        "Surface",
+        "Switch",
+        "Tabs",
+        "TextArea",
+        "TextField",
+        "Tooltip",
+      ].sort(),
+    );
+  });
+
+  it("preserves typed design-system and theme definitions", () => {
+    const theme = defineTheme({
+      colors: {
+        light: { primary: "oklch(55% 0.2 260)" },
+      },
+      radius: "0.75rem",
+    });
+    const definition = defineDesignSystem({
+      name: "Acme",
+      theme,
+      components: {},
+    });
+
+    expect(definition).toEqual({ name: "Acme", theme, components: {} });
+  });
+
+  it("prefers ActionButton over the legacy Button override", () => {
+    const warning = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const LegacyButton = () => <button data-adapter="legacy" />;
+    const CustomActionButton = () => <button data-adapter="semantic" />;
+
+    act(() => {
+      root.render(
+        <ToolkitProvider
+          components={{ Button: LegacyButton }}
+          designSystem={{
+            components: { ActionButton: CustomActionButton },
+          }}
+        >
+          <Button>Save</Button>
+        </ToolkitProvider>,
+      );
+    });
+
+    expect(container.querySelector("[data-adapter=semantic]")).not.toBeNull();
+    expect(container.querySelector("[data-adapter=legacy]")).toBeNull();
+    expect(warning).toHaveBeenCalledOnce();
+  });
+
+  it("warns when nested providers combine the effective ActionButton APIs", () => {
+    const warning = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const LegacyButton = () => <button data-adapter="legacy" />;
+    const CustomActionButton = () => <button data-adapter="semantic" />;
+
+    act(() => {
+      root.render(
+        <ToolkitProvider
+          designSystem={{
+            components: { ActionButton: CustomActionButton },
+          }}
+        >
+          <ToolkitProvider components={{ Button: LegacyButton }}>
+            <Button>Save</Button>
+          </ToolkitProvider>
+        </ToolkitProvider>,
+      );
+    });
+
+    expect(container.querySelector("[data-adapter=semantic]")).not.toBeNull();
+    expect(warning).toHaveBeenCalledOnce();
+  });
+
+  it("forwards semantic intent independently from the legacy visual variant", () => {
+    const received = vi.fn();
+    const CustomActionButton = (props: ComponentProps<typeof ActionButton>) => {
+      received(props.intent, props.emphasis);
+      return <button>{props.children}</button>;
+    };
+
+    act(() => {
+      root.render(
+        <ToolkitProvider
+          designSystem={{ components: { ActionButton: CustomActionButton } }}
+        >
+          <Button variant="ghost" intent="danger" emphasis="outline">
+            Remove
+          </Button>
+        </ToolkitProvider>,
+      );
+    });
+
+    expect(received).toHaveBeenCalledWith("danger", "outline");
+  });
+
+  it("uses legacy Button as the lowest-precedence ActionButton adapter", () => {
+    const LegacyButton = (props: ComponentProps<"button">) => (
+      <button {...props} data-adapter="legacy" />
+    );
+
+    act(() => {
+      root.render(
+        <ToolkitProvider components={{ Button: LegacyButton }}>
+          <ActionButton>Save</ActionButton>
+        </ToolkitProvider>,
+      );
+    });
+
+    expect(container.querySelector("[data-adapter=legacy]")?.textContent).toBe(
+      "Save",
+    );
+  });
+
+  it.each(["pointer", "Enter", "Space", "ArrowDown"])(
+    "preserves Radix menu trigger behavior through a legacy Button override with %s activation",
+    async (activation) => {
+      const onOpenChange = vi.fn();
+      let buttonRef: HTMLButtonElement | null = null;
+      const LegacyButton = forwardRef<
+        HTMLButtonElement,
+        ComponentProps<typeof Button>
+      >(
+        (
+          {
+            asChild: _asChild,
+            emphasis: _emphasis,
+            intent: _intent,
+            size: _size,
+            variant: _variant,
+            ...props
+          },
+          ref,
+        ) => <button {...props} ref={ref} data-adapter="legacy" />,
+      );
+
+      await act(async () => {
+        root.render(
+          <ToolkitProvider
+            components={{ Button: LegacyButton }}
+            designSystem={{}}
+          >
+            <DropdownMenu onOpenChange={onOpenChange}>
+              <DropdownMenuTrigger asChild>
+                <Button
+                  ref={(node) => {
+                    buttonRef = node;
+                  }}
+                >
+                  Open menu
+                </Button>
+              </DropdownMenuTrigger>
+              <DropdownMenuContent>
+                <DropdownMenuItem>First item</DropdownMenuItem>
+              </DropdownMenuContent>
+            </DropdownMenu>
+          </ToolkitProvider>,
+        );
+      });
+
+      const trigger = container.querySelector<HTMLButtonElement>("button");
+      expect(trigger).not.toBeNull();
+      expect(buttonRef).toBe(trigger);
+      expect(trigger?.getAttribute("aria-haspopup")).toBe("menu");
+      expect(trigger?.getAttribute("aria-expanded")).toBe("false");
+      expect(trigger?.dataset.state).toBe("closed");
+
+      await act(async () => {
+        trigger?.focus();
+        if (activation === "pointer") {
+          trigger?.dispatchEvent(
+            new PointerEvent("pointerdown", {
+              bubbles: true,
+              button: 0,
+              pointerType: "mouse",
+            }),
+          );
+        } else {
+          const key = activation === "Space" ? " " : activation;
+          trigger?.dispatchEvent(
+            new KeyboardEvent("keydown", { bubbles: true, key }),
+          );
+        }
+        await Promise.resolve();
+      });
+
+      expect(onOpenChange).toHaveBeenCalledTimes(1);
+      expect(onOpenChange).toHaveBeenLastCalledWith(true);
+      expect(trigger?.getAttribute("aria-expanded")).toBe("true");
+      expect(trigger?.dataset.state).toBe("open");
+      expect(document.querySelector("[role=menu]")).not.toBeNull();
+
+      await act(async () => {
+        document.activeElement?.dispatchEvent(
+          new KeyboardEvent("keydown", { bubbles: true, key: "Escape" }),
+        );
+        await Promise.resolve();
+      });
+
+      expect(onOpenChange).toHaveBeenCalledTimes(2);
+      expect(onOpenChange).toHaveBeenLastCalledWith(false);
+      expect(trigger?.getAttribute("aria-expanded")).toBe("false");
+      expect(trigger?.dataset.state).toBe("closed");
+    },
+  );
+
+  it("forwards a native ref passed to ActionButton to the real DOM button node", () => {
+    let node: HTMLButtonElement | null = null;
+
+    act(() => {
+      root.render(
+        <ActionButton
+          ref={(el) => {
+            node = el;
+          }}
+        >
+          Save
+        </ActionButton>,
+      );
+    });
+
+    const button = container.querySelector("button");
+    expect(button).not.toBeNull();
+    expect(node).toBe(button);
+  });
+
+  it("resolves a Radix asChild Popover trigger's ref to the real IconButton DOM node", async () => {
+    // Radix positions a popover by measuring the DOM node its `asChild`
+    // Slot clones a ref onto. If that ref is dropped, Radix has nothing to
+    // measure and falls back to an unpositioned, off-screen placement.
+    let node: HTMLButtonElement | null = null;
+
+    await act(async () => {
+      root.render(
+        <Popover>
+          <PopoverTrigger asChild>
+            <IconButton
+              label="Manage"
+              icon={<span />}
+              ref={(el) => {
+                node = el;
+              }}
+            />
+          </PopoverTrigger>
+          <PopoverContent>Content</PopoverContent>
+        </Popover>,
+      );
+    });
+
+    const button = container.querySelector("button");
+    expect(button).not.toBeNull();
+    expect(node).toBe(button);
+  });
+
+  it.each([
+    ["IconButton", <IconButton label="Manage" icon={<span />} />],
+    ["ActionButton", <ActionButton>Manage</ActionButton>],
+  ])(
+    "opens a Radix asChild Popover trigger built on %s when clicked",
+    async (_name, trigger) => {
+      // Radix passes its toggle handler down as `onClick`. An adapter that
+      // spreads props and then sets its own `onClick` silently drops it, so
+      // the trigger renders correctly and never opens.
+      await act(async () => {
+        root.render(
+          <Popover>
+            <PopoverTrigger asChild>{trigger}</PopoverTrigger>
+            <PopoverContent>Content</PopoverContent>
+          </Popover>,
+        );
+      });
+
+      const button = container.querySelector("button");
+      await act(async () => {
+        button?.click();
+      });
+      expect(button?.dataset.state).toBe("open");
+    },
+  );
+
+  it("isolates a broken customer component and renders the default control", () => {
+    vi.spyOn(console, "error").mockImplementation(() => {});
+    const BrokenActionButton = () => {
+      throw new Error("broken adapter");
+    };
+
+    act(() => {
+      root.render(
+        <ToolkitProvider
+          designSystem={{
+            components: { ActionButton: BrokenActionButton },
+          }}
+        >
+          <ActionButton>Fallback action</ActionButton>
+        </ToolkitProvider>,
+      );
+    });
+
+    expect(container.querySelector("button")?.textContent).toBe(
+      "Fallback action",
+    );
+    expect(console.error).toHaveBeenCalled();
+  });
+});

package/src/design-system/error-boundary.tsx

@@ -0,0 +1,37 @@
+import { Component, type ErrorInfo, type ReactNode } from "react";
+
+import type { DesignSystemComponentName } from "./types.js";
+
+interface DesignSystemErrorBoundaryProps {
+  component: DesignSystemComponentName | string;
+  fallback: ReactNode;
+  children: ReactNode;
+}
+
+interface DesignSystemErrorBoundaryState {
+  failed: boolean;
+}
+
+export class DesignSystemErrorBoundary extends Component<
+  DesignSystemErrorBoundaryProps,
+  DesignSystemErrorBoundaryState
+> {
+  state: DesignSystemErrorBoundaryState = { failed: false };
+
+  static getDerivedStateFromError(): DesignSystemErrorBoundaryState {
+    return { failed: true };
+  }
+
+  componentDidCatch(error: unknown, info: ErrorInfo) {
+    console.error(
+      `[agent-native] Custom design-system component ${this.props.component} failed; rendering the default adapter for this control.`,
+      error,
+      info,
+    );
+  }
+
+  render() {
+    if (this.state.failed) return this.props.fallback;
+    return this.props.children;
+  }
+}

package/src/design-system/index.ts

@@ -0,0 +1,7 @@
+export * from "./components.js";
+export * from "./context.js";
+export * from "./default-adapter.js";
+export * from "./definition.js";
+export * from "./error-boundary.js";
+export * from "./theme.js";
+export * from "./types.js";

package/src/design-system/theme.spec.ts

@@ -0,0 +1,61 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  normalizeDesignSystemColor,
+  normalizeDesignSystemTheme,
+  renderDesignSystemThemeCss,
+} from "./theme.js";
+
+describe("design system themes", () => {
+  it.each([
+    ["#ff0000", "0 100% 50%"],
+    ["rgb(0 128 255)", "209.882 100% 50%"],
+    ["oklch(62% 0.2 250)", "204.933 99.979% 45.91%"],
+    ["rebeccapurple", "270 50% 40%"],
+    ["rgb(255 0 0 / 50%)", "0 100% 50% / 0.5"],
+  ])("normalizes %s to an HSL triplet", (input, output) => {
+    expect(normalizeDesignSystemColor(input)).toBe(output);
+  });
+
+  it("falls back to light colors token by token without deriving dark colors", () => {
+    const normalized = normalizeDesignSystemTheme({
+      colors: {
+        light: { background: "white", foreground: "black" },
+        dark: { background: "#101010" },
+      },
+    });
+
+    expect(normalized.dark["--background"]).toBe("0 0% 6.275%");
+    expect(normalized.dark["--foreground"]).toBe(
+      normalized.light["--foreground"],
+    );
+  });
+
+  it("renders static light and dark token blocks", () => {
+    const css = renderDesignSystemThemeCss({
+      colors: { light: { primary: "oklch(60% 0.2 250)" } },
+      radius: "0.75rem",
+    });
+
+    expect(css).toContain(":root:root {");
+    expect(css).toContain(":root.dark {");
+    expect(css).toContain("--primary:");
+    expect(css.match(/--radius: 0.75rem/g)).toHaveLength(2);
+  });
+
+  it.each(["oklch(62% 0.2 250)", "oklch(70% 0.4 30)", "oklch(60% 0.3 120)"])(
+    "maps vivid %s into the sRGB gamut before HSL conversion",
+    (input) => {
+      const [, saturation] = normalizeDesignSystemColor(input).split(" ");
+      expect(Number.parseFloat(saturation)).toBeLessThanOrEqual(100);
+    },
+  );
+
+  it("identifies the invalid semantic token", () => {
+    expect(() =>
+      normalizeDesignSystemTheme({
+        colors: { light: { primary: "definitely-not-a-color" } },
+      }),
+    ).toThrow('Invalid design system color for "primary"');
+  });
+});

package/src/design-system/theme.ts

@@ -0,0 +1,145 @@
+import { clampChroma, converter, parse } from "culori";
+
+export const DESIGN_SYSTEM_COLOR_TOKENS = [
+  "background",
+  "foreground",
+  "border",
+  "input",
+  "ring",
+  "primary",
+  "primary-foreground",
+  "secondary",
+  "secondary-foreground",
+  "destructive",
+  "destructive-foreground",
+  "muted",
+  "muted-foreground",
+  "accent",
+  "accent-foreground",
+  "popover",
+  "popover-foreground",
+  "card",
+  "card-foreground",
+  "sidebar-background",
+  "sidebar-foreground",
+  "sidebar-primary",
+  "sidebar-primary-foreground",
+  "sidebar-accent",
+  "sidebar-accent-foreground",
+  "sidebar-border",
+  "sidebar-ring",
+] as const;
+
+export type DesignSystemColorToken =
+  (typeof DESIGN_SYSTEM_COLOR_TOKENS)[number];
+export type DesignSystemColorPalette = Partial<
+  Record<DesignSystemColorToken, string>
+>;
+
+export interface DesignSystemTheme {
+  colors: {
+    light: DesignSystemColorPalette;
+    /** Dark mode falls back token-by-token to the light palette. */
+    dark?: DesignSystemColorPalette;
+  };
+  radius?: string;
+  typography?: {
+    fontFamily?: string;
+    monoFontFamily?: string;
+    baseFontSize?: string;
+  };
+  elevation?: {
+    low?: string;
+    medium?: string;
+    high?: string;
+  };
+}
+
+export interface NormalizedDesignSystemTheme {
+  light: Record<string, string>;
+  dark: Record<string, string>;
+}
+
+const toHsl = converter("hsl");
+
+function round(value: number): string {
+  return Number(value.toFixed(3)).toString();
+}
+
+export function normalizeDesignSystemColor(value: string): string {
+  const parsed = parse(value);
+  const color = parsed ? toHsl(clampChroma(parsed, "oklch")) : undefined;
+  if (!color) {
+    throw new Error(`Unsupported design system color: ${value}`);
+  }
+
+  const hue = color.h ?? 0;
+  const base = `${round(hue)} ${round(color.s * 100)}% ${round(color.l * 100)}%`;
+  return color.alpha !== undefined && color.alpha < 1
+    ? `${base} / ${round(color.alpha)}`
+    : base;
+}
+
+function normalizePalette(
+  palette: DesignSystemColorPalette,
+): Record<string, string> {
+  return Object.fromEntries(
+    DESIGN_SYSTEM_COLOR_TOKENS.flatMap((token) => {
+      const value = palette[token];
+      if (value === undefined) return [];
+      try {
+        return [[`--${token}`, normalizeDesignSystemColor(value)]];
+      } catch (error) {
+        throw new Error(
+          `Invalid design system color for "${token}": ${value}`,
+          { cause: error },
+        );
+      }
+    }),
+  );
+}
+
+export function normalizeDesignSystemTheme(
+  theme: DesignSystemTheme,
+): NormalizedDesignSystemTheme {
+  const light = normalizePalette(theme.colors.light);
+  const dark = {
+    ...light,
+    ...normalizePalette(theme.colors.dark ?? {}),
+  };
+
+  const shared: Record<string, string | undefined> = {
+    "--radius": theme.radius,
+    "--font-family": theme.typography?.fontFamily,
+    "--font-mono": theme.typography?.monoFontFamily,
+    "--base-font-size": theme.typography?.baseFontSize,
+    "--shadow-low": theme.elevation?.low,
+    "--shadow-medium": theme.elevation?.medium,
+    "--shadow-high": theme.elevation?.high,
+  };
+  for (const [name, value] of Object.entries(shared)) {
+    if (value !== undefined) {
+      light[name] = value;
+      dark[name] = value;
+    }
+  }
+
+  return { light, dark };
+}
+
+function renderDeclarations(values: Record<string, string>): string {
+  return Object.entries(values)
+    .map(([name, value]) => `  ${name}: ${value};`)
+    .join("\n");
+}
+
+export function renderDesignSystemThemeCss(theme: DesignSystemTheme): string {
+  const normalized = normalizeDesignSystemTheme(theme);
+  return `:root:root {\n${renderDeclarations(normalized.light)}\n}\n\n:root.dark {\n${renderDeclarations(normalized.dark)}\n}\n`;
+}
+
+export function defineTheme<const Theme extends DesignSystemTheme>(
+  theme: Theme,
+): Theme {
+  return theme;
+}