@agent-native/toolkit 0.9.0 → 0.10.0

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,183 @@
+// @vitest-environment happy-dom
+
+import { act, 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 { ActionButton } 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("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;
+}