@agent-native/toolkit 0.0.0-beta-20260819143124

package/src/data-grid/index.ts

@@ -0,0 +1,15 @@
+export {
+  DataGrid,
+  clampDataGridColumnWidth,
+  dataGridColumnTemplate,
+  type DataGridActiveCell,
+  type DataGridCellContext,
+  type DataGridColumn,
+  type DataGridCommitContext,
+  type DataGridDirection,
+  type DataGridEditorContext,
+  type DataGridProps,
+  type DataGridRowContext,
+  type DataGridSelectionMode,
+  type DataGridSlotContext,
+} from "./DataGrid.js";

package/src/design-system/components.tsx

@@ -0,0 +1,196 @@
+import { forwardRef, type ComponentType, type Ref } 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;
+}
+
+function mergeElementRefs<Element>(
+  refs: readonly (Ref<Element> | undefined)[],
+): Ref<Element> {
+  return (node: Element | null) => {
+    for (const ref of refs) {
+      if (typeof ref === "function") ref(node);
+      else if (ref) (ref as { current: Element | null }).current = node;
+    }
+  };
+}
+
+/**
+ * Like `createComponent`, but also wraps in `forwardRef` and merges the
+ * forwarded ref into `elementRef` before rendering. Radix `asChild`/`Slot`
+ * triggers attach a native `ref` directly to their JSX child to measure it
+ * for popper positioning; without this, that ref is silently dropped by the
+ * plain function component `createComponent` returns, and Radix falls back
+ * to an unmeasured, off-screen position. Scoped to ActionButton/IconButton
+ * because those are the only semantic contracts that declare `elementRef`.
+ */
+function createRefForwardingComponent<
+  Props extends { elementRef?: Ref<Element> },
+  Element,
+>(name: DesignSystemComponentName, DefaultComponent: ComponentType<Props>) {
+  const DesignSystemComponent = forwardRef<Element, Props>((props, ref) => {
+    const CustomComponent = useDesignSystemComponent(name) as
+      | ComponentType<Props>
+      | undefined;
+    const mergedProps = {
+      ...props,
+      elementRef: mergeElementRefs([ref, props.elementRef]),
+    } as Props;
+    const fallback = <DefaultComponent {...mergedProps} />;
+    if (
+      !CustomComponent ||
+      CustomComponent === DefaultComponent ||
+      (CustomComponent as unknown) === DesignSystemComponent
+    ) {
+      return fallback;
+    }
+    return (
+      <DesignSystemErrorBoundary component={name} fallback={fallback}>
+        <CustomComponent {...mergedProps} />
+      </DesignSystemErrorBoundary>
+    );
+  });
+  DesignSystemComponent.displayName = `DesignSystem.${name}`;
+  return DesignSystemComponent;
+}
+
+export const ActionButton = createRefForwardingComponent<
+  ActionButtonProps,
+  HTMLButtonElement
+>("ActionButton", defaultDesignSystemComponents.ActionButton);
+export const IconButton = createRefForwardingComponent<
+  IconButtonProps,
+  HTMLButtonElement
+>("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,158 @@
+// @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("preserves native click handlers for composed ActionButtons", () => {
+    const onPress = vi.fn();
+    const onClick = vi.fn();
+    const button = renderComponent(defaultDesignSystemComponents.ActionButton, {
+      children: "Share",
+      onPress,
+      onClick,
+    });
+
+    (button.props.onClick as ((event: unknown) => void) | undefined)?.({});
+
+    expect(onPress).toHaveBeenCalledOnce();
+    expect(onClick).toHaveBeenCalledOnce();
+  });
+
+  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();
+  });
+});