@agent-native/toolkit 0.9.1 → 0.10.0

package/src/conformance/types.ts

@@ -0,0 +1,45 @@
+import type { DesignSystemComponents } from "../design-system/types.js";
+
+export type DesignSystemConformanceCategory =
+  | "contract"
+  | "leaf"
+  | "behavior"
+  | "overlay-interoperability";
+
+export interface DesignSystemConformanceCheckResult {
+  id: string;
+  category: DesignSystemConformanceCategory;
+  components: readonly (keyof DesignSystemComponents)[];
+  passed: boolean;
+  message?: string;
+}
+
+export interface DesignSystemConformanceReport {
+  contractVersion: number;
+  adapterName: string;
+  passed: boolean;
+  results: readonly DesignSystemConformanceCheckResult[];
+}
+
+export interface RunDesignSystemConformanceOptions {
+  adapterName?: string;
+  components: DesignSystemComponents;
+  contractVersion: number;
+  document?: Document;
+}
+
+export class DesignSystemConformanceError extends Error {
+  readonly report: DesignSystemConformanceReport;
+
+  constructor(report: DesignSystemConformanceReport) {
+    const failures = report.results
+      .filter((result) => !result.passed)
+      .map((result) => `${result.id}: ${result.message ?? "failed"}`)
+      .join("\n");
+    super(
+      `Design system conformance failed for ${report.adapterName}:\n${failures}`,
+    );
+    this.name = "DesignSystemConformanceError";
+    this.report = report;
+  }
+}

package/src/conformance/version.ts

@@ -0,0 +1,22 @@
+import { DESIGN_SYSTEM_CONTRACT_VERSION } from "../design-system/types.js";
+
+export const DESIGN_SYSTEM_CONTRACT_EVOLUTION_POLICY = {
+  minor: "New components and optional props are backward-compatible.",
+  major:
+    "Required props, removed components or props, and behavioral contract changes require a new contract major.",
+} as const;
+
+export function assertDesignSystemContractVersion(
+  adapterContractVersion: number,
+): void {
+  if (!Number.isInteger(adapterContractVersion) || adapterContractVersion < 1) {
+    throw new TypeError(
+      "Design system contractVersion must be a positive integer.",
+    );
+  }
+  if (adapterContractVersion !== DESIGN_SYSTEM_CONTRACT_VERSION) {
+    throw new RangeError(
+      `Design system contract major ${adapterContractVersion} is incompatible with Toolkit contract major ${DESIGN_SYSTEM_CONTRACT_VERSION}.`,
+    );
+  }
+}

package/src/design-system/components.tsx

@@ -0,0 +1,146 @@
+import type { ComponentType } from "react";
+
+import { useDesignSystemComponent } from "./context.js";
+import { defaultDesignSystemComponents } from "./default-adapter.js";
+import { DesignSystemErrorBoundary } from "./error-boundary.js";
+import type {
+  ActionButtonProps,
+  AvatarProps,
+  CheckboxProps,
+  DesignSystemComponentName,
+  DesignSystemComponents,
+  DesignSystemKey,
+  DialogProps,
+  IconButtonProps,
+  MenuProps,
+  PickerProps,
+  PopoverProps,
+  SkeletonProps,
+  SpinnerProps,
+  StatusProps,
+  SurfaceProps,
+  SwitchProps,
+  TabsProps,
+  TextAreaProps,
+  TextFieldProps,
+  TooltipProps,
+} from "./types.js";
+
+function createComponent<Props extends object>(
+  name: DesignSystemComponentName,
+  DefaultComponent: ComponentType<Props>,
+) {
+  function DesignSystemComponent(props: Props) {
+    const CustomComponent = useDesignSystemComponent(name) as
+      | ComponentType<Props>
+      | undefined;
+    const fallback = <DefaultComponent {...props} />;
+    if (
+      !CustomComponent ||
+      CustomComponent === DefaultComponent ||
+      CustomComponent === DesignSystemComponent
+    ) {
+      return fallback;
+    }
+    return (
+      <DesignSystemErrorBoundary component={name} fallback={fallback}>
+        <CustomComponent {...props} />
+      </DesignSystemErrorBoundary>
+    );
+  }
+  DesignSystemComponent.displayName = `DesignSystem.${name}`;
+  return DesignSystemComponent;
+}
+
+export const ActionButton = createComponent<ActionButtonProps>(
+  "ActionButton",
+  defaultDesignSystemComponents.ActionButton,
+);
+export const IconButton = createComponent<IconButtonProps>(
+  "IconButton",
+  defaultDesignSystemComponents.IconButton,
+);
+export const TextField = createComponent<TextFieldProps>(
+  "TextField",
+  defaultDesignSystemComponents.TextField,
+);
+export const TextArea = createComponent<TextAreaProps>(
+  "TextArea",
+  defaultDesignSystemComponents.TextArea,
+);
+export const Spinner = createComponent<SpinnerProps>(
+  "Spinner",
+  defaultDesignSystemComponents.Spinner,
+);
+export const Skeleton = createComponent<SkeletonProps>(
+  "Skeleton",
+  defaultDesignSystemComponents.Skeleton,
+);
+export const Status = createComponent<StatusProps>(
+  "Status",
+  defaultDesignSystemComponents.Status,
+);
+export const Surface = createComponent<SurfaceProps>(
+  "Surface",
+  defaultDesignSystemComponents.Surface,
+);
+export const Avatar = createComponent<AvatarProps>(
+  "Avatar",
+  defaultDesignSystemComponents.Avatar,
+);
+export const Tooltip = createComponent<TooltipProps>(
+  "Tooltip",
+  defaultDesignSystemComponents.Tooltip,
+);
+export const Menu = createComponent<MenuProps>(
+  "Menu",
+  defaultDesignSystemComponents.Menu,
+);
+export const Popover = createComponent<PopoverProps>(
+  "Popover",
+  defaultDesignSystemComponents.Popover,
+);
+export const Dialog = createComponent<DialogProps>(
+  "Dialog",
+  defaultDesignSystemComponents.Dialog,
+);
+export const Checkbox = createComponent<CheckboxProps>(
+  "Checkbox",
+  defaultDesignSystemComponents.Checkbox,
+);
+export const Switch = createComponent<SwitchProps>(
+  "Switch",
+  defaultDesignSystemComponents.Switch,
+);
+
+export function Picker<Value extends DesignSystemKey = string>(
+  props: PickerProps<Value>,
+) {
+  const CustomComponent = useDesignSystemComponent("Picker") as
+    | DesignSystemComponents["Picker"]
+    | undefined;
+  const DefaultComponent = defaultDesignSystemComponents.Picker;
+  const fallback = <DefaultComponent {...props} />;
+  if (!CustomComponent || CustomComponent === DefaultComponent) return fallback;
+  return (
+    <DesignSystemErrorBoundary component="Picker" fallback={fallback}>
+      <CustomComponent {...props} />
+    </DesignSystemErrorBoundary>
+  );
+}
+
+export function Tabs<Value extends DesignSystemKey = string>(
+  props: TabsProps<Value>,
+) {
+  const CustomComponent = useDesignSystemComponent("Tabs") as
+    | DesignSystemComponents["Tabs"]
+    | undefined;
+  const DefaultComponent = defaultDesignSystemComponents.Tabs;
+  const fallback = <DefaultComponent {...props} />;
+  if (!CustomComponent || CustomComponent === DefaultComponent) return fallback;
+  return (
+    <DesignSystemErrorBoundary component="Tabs" fallback={fallback}>
+      <CustomComponent {...props} />
+    </DesignSystemErrorBoundary>
+  );
+}

package/src/design-system/context.tsx

@@ -0,0 +1,31 @@
+import { createContext, useContext } from "react";
+
+import type { DesignSystemDefinition } from "./definition.js";
+import type {
+  DesignSystemComponentName,
+  DesignSystemComponents,
+} from "./types.js";
+
+export interface DesignSystemContextValue {
+  definition?: DesignSystemDefinition;
+  legacyActionButton?: DesignSystemComponents["ActionButton"];
+}
+
+export const DesignSystemContext = createContext<DesignSystemContextValue>({});
+export const LegacyButtonRenderContext = createContext(false);
+
+export function useDesignSystem(): DesignSystemDefinition | undefined {
+  return useContext(DesignSystemContext).definition;
+}
+
+export function useDesignSystemComponent<
+  Name extends DesignSystemComponentName,
+>(name: Name): DesignSystemComponents[Name] | undefined {
+  const context = useContext(DesignSystemContext);
+  const component = context.definition?.components?.[name];
+  if (component) return component as DesignSystemComponents[Name];
+  if (name === "ActionButton" && context.legacyActionButton) {
+    return context.legacyActionButton as DesignSystemComponents[Name];
+  }
+  return undefined;
+}

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

@@ -0,0 +1,143 @@
+// @vitest-environment happy-dom
+
+import {
+  Children,
+  isValidElement,
+  type ReactElement,
+  type ReactNode,
+} from "react";
+import { describe, expect, it, vi } from "vitest";
+
+import { defaultDesignSystemComponents } from "./default-adapter.js";
+
+type TestElement = ReactElement<Record<string, unknown>>;
+
+function findElement(
+  node: ReactNode,
+  predicate: (element: TestElement) => boolean,
+): TestElement | undefined {
+  if (Array.isArray(node)) {
+    for (const child of node) {
+      const match = findElement(child, predicate);
+      if (match) return match;
+    }
+    return undefined;
+  }
+  if (!isValidElement(node)) return undefined;
+  const element = node as TestElement;
+  if (predicate(element)) return element;
+  for (const child of Children.toArray(element.props.children as ReactNode)) {
+    const match = findElement(child, predicate);
+    if (match) return match;
+  }
+  return undefined;
+}
+
+function renderComponent(
+  component: unknown,
+  props: Record<string, unknown>,
+): TestElement {
+  return (component as (props: Record<string, unknown>) => ReactNode)(
+    props,
+  ) as TestElement;
+}
+
+describe("default design system adapter", () => {
+  it("maps visual size and shape props to default styles", () => {
+    const iconButton = renderComponent(
+      defaultDesignSystemComponents.IconButton,
+      {
+        label: "More",
+        icon: <span />,
+        size: "large",
+      },
+    );
+    const spinner = renderComponent(defaultDesignSystemComponents.Spinner, {
+      size: "compact",
+    });
+    const skeleton = renderComponent(defaultDesignSystemComponents.Skeleton, {
+      shape: "circle",
+    });
+    const avatar = renderComponent(defaultDesignSystemComponents.Avatar, {
+      name: "Ada Lovelace",
+      size: "compact",
+      status: "online",
+    });
+
+    expect(iconButton.props.className).toContain("h-12");
+    expect(spinner.props.className).toContain("size-3");
+    expect(skeleton.props.className).toContain("rounded-full");
+    expect(
+      findElement(avatar, (element) => element.props.role === "img")?.props
+        .className,
+    ).toContain("bg-green-500");
+  });
+
+  it("prevents outside dismissal when a dialog is not dismissible", () => {
+    const dialog = renderComponent(defaultDesignSystemComponents.Dialog, {
+      open: true,
+      onOpenChange: vi.fn(),
+      title: "Confirm",
+      children: <p>Confirm this action</p>,
+      dismissible: false,
+    });
+    const content = findElement(
+      dialog,
+      (element) => typeof element.props.onInteractOutside === "function",
+    );
+    const preventDefault = vi.fn();
+
+    (
+      content?.props.onInteractOutside as
+        | ((event: { preventDefault: () => void }) => void)
+        | undefined
+    )?.({ preventDefault });
+
+    expect(preventDefault).toHaveBeenCalledOnce();
+  });
+
+  it("honors menu selection state and closeOnAction", () => {
+    const onAction = vi.fn();
+    const menu = renderComponent(defaultDesignSystemComponents.Menu, {
+      trigger: <button type="button">Open</button>,
+      items: [{ id: "selected", label: "Selected", selected: true }],
+      onAction,
+      closeOnAction: false,
+    });
+    const content = (menu.props.children as TestElement[])[1];
+    const items = content.props.children as TestElement;
+    const renderedItems = (
+      items.type as (props: Record<string, unknown>) => ReactNode
+    )(items.props);
+    const item = findElement(
+      renderedItems,
+      (element) => element.props.checked === true,
+    );
+    const preventDefault = vi.fn();
+
+    (
+      item?.props.onSelect as
+        | ((event: { preventDefault: () => void }) => void)
+        | undefined
+    )?.({ preventDefault });
+
+    expect(item?.props.checked).toBe(true);
+    expect(preventDefault).toHaveBeenCalledOnce();
+    expect(onAction).toHaveBeenCalledWith("selected");
+  });
+
+  it("maps checkbox invalid state to aria-invalid", () => {
+    const checkbox = renderComponent(defaultDesignSystemComponents.Checkbox, {
+      checked: false,
+      onChange: vi.fn(),
+      invalid: true,
+    });
+    const input = findElement(
+      checkbox,
+      (element) => element.props["aria-invalid"] === true,
+    );
+
+    expect(input?.props["aria-invalid"]).toBe(true);
+    expect(input?.props.invalid).toBeUndefined();
+  });
+});