@agent-native/core 0.117.1 → 0.118.0

package/corpus/toolkit/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/corpus/toolkit/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/corpus/toolkit/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/corpus/toolkit/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;
+}

package/corpus/toolkit/src/design-system/types.ts

@@ -0,0 +1,363 @@
+import type {
+  ComponentType,
+  CSSProperties,
+  KeyboardEvent as ReactKeyboardEvent,
+  MouseEvent as ReactMouseEvent,
+  ReactElement,
+  ReactNode,
+  Ref,
+  RefObject,
+} from "react";
+
+export const DESIGN_SYSTEM_CONTRACT_VERSION = 1 as const;
+
+export type DesignSystemIntent = "primary" | "neutral" | "danger";
+export type DesignSystemEmphasis = "solid" | "outline" | "ghost";
+export type DesignSystemSize = "compact" | "default" | "large";
+export type DesignSystemTone =
+  | "neutral"
+  | "info"
+  | "success"
+  | "warning"
+  | "danger";
+export type DesignSystemPlacement = "top" | "right" | "bottom" | "left";
+export type DesignSystemAlign = "start" | "center" | "end";
+export type DesignSystemKey = string | number;
+export type DesignSystemPressEvent =
+  | ReactMouseEvent<HTMLElement>
+  | ReactKeyboardEvent<HTMLElement>;
+
+/**
+ * Styling hooks are optional interoperability affordances. Adapters must not
+ * rely on either hook being present, and Toolkit views must not pass
+ * framework-specific utility classes through this contract.
+ */
+export interface DesignSystemStyleProps {
+  className?: string;
+  style?: CSSProperties;
+}
+
+export interface DesignSystemAccessibleProps {
+  id?: string;
+  title?: string;
+  "aria-label"?: string;
+  "aria-labelledby"?: string;
+  "aria-describedby"?: string;
+  "aria-controls"?: string;
+  "aria-expanded"?: boolean;
+  "aria-haspopup"?: boolean | "dialog" | "grid" | "listbox" | "menu" | "tree";
+  "aria-pressed"?: boolean | "mixed";
+}
+
+export interface DesignSystemOverlayProps extends DesignSystemStyleProps {
+  portalContainer?: Element | null;
+  placement?: DesignSystemPlacement;
+  align?: DesignSystemAlign;
+  collisionPadding?: number;
+}
+
+export interface ActionButtonProps
+  extends DesignSystemStyleProps, DesignSystemAccessibleProps {
+  children?: ReactNode;
+  intent?: DesignSystemIntent;
+  emphasis?: DesignSystemEmphasis;
+  size?: DesignSystemSize;
+  pending?: boolean;
+  disabled?: boolean;
+  type?: "button" | "submit" | "reset";
+  leadingIcon?: ReactNode;
+  trailingIcon?: ReactNode;
+  onPress?: (event?: DesignSystemPressEvent) => void;
+  elementRef?: Ref<HTMLButtonElement>;
+}
+
+export interface IconButtonProps
+  extends DesignSystemStyleProps, DesignSystemAccessibleProps {
+  label: string;
+  icon: ReactNode;
+  intent?: DesignSystemIntent;
+  emphasis?: DesignSystemEmphasis;
+  size?: DesignSystemSize;
+  pending?: boolean;
+  disabled?: boolean;
+  type?: "button" | "submit" | "reset";
+  onPress?: (event?: DesignSystemPressEvent) => void;
+  elementRef?: Ref<HTMLButtonElement>;
+}
+
+export type DesignSystemTextInputType =
+  | "text"
+  | "email"
+  | "password"
+  | "search"
+  | "tel"
+  | "url";
+
+export interface TextFieldProps
+  extends DesignSystemStyleProps, DesignSystemAccessibleProps {
+  value: string;
+  onChange: (value: string) => void;
+  label?: ReactNode;
+  description?: ReactNode;
+  errorMessage?: ReactNode;
+  placeholder?: string;
+  /** Optional native datalist id for editable fields with suggestions. */
+  list?: string;
+  name?: string;
+  type?: DesignSystemTextInputType;
+  inputMode?:
+    | "none"
+    | "text"
+    | "tel"
+    | "url"
+    | "email"
+    | "numeric"
+    | "decimal"
+    | "search";
+  autoComplete?: string;
+  autoFocus?: boolean;
+  required?: boolean;
+  readOnly?: boolean;
+  disabled?: boolean;
+  invalid?: boolean;
+  leadingContent?: ReactNode;
+  trailingContent?: ReactNode;
+  onBlur?: () => void;
+  onFocus?: () => void;
+  onKeyDown?: (event: ReactKeyboardEvent<HTMLElement>) => void;
+  inputRef?: Ref<HTMLInputElement>;
+}
+
+export interface TextAreaProps
+  extends DesignSystemStyleProps, DesignSystemAccessibleProps {
+  value: string;
+  onChange: (value: string) => void;
+  label?: ReactNode;
+  description?: ReactNode;
+  errorMessage?: ReactNode;
+  placeholder?: string;
+  name?: string;
+  rows?: number;
+  maxLength?: number;
+  autoFocus?: boolean;
+  required?: boolean;
+  readOnly?: boolean;
+  disabled?: boolean;
+  invalid?: boolean;
+  onBlur?: () => void;
+  onFocus?: () => void;
+  onKeyDown?: (event: ReactKeyboardEvent<HTMLElement>) => void;
+  textAreaRef?: Ref<HTMLTextAreaElement>;
+}
+
+export interface SpinnerProps
+  extends DesignSystemStyleProps, DesignSystemAccessibleProps {
+  label?: string;
+  size?: DesignSystemSize;
+}
+
+export interface SkeletonProps
+  extends DesignSystemStyleProps, DesignSystemAccessibleProps {
+  width?: string | number;
+  height?: string | number;
+  shape?: "line" | "rectangle" | "circle";
+}
+
+export interface StatusProps
+  extends DesignSystemStyleProps, DesignSystemAccessibleProps {
+  children: ReactNode;
+  tone?: DesignSystemTone;
+  icon?: ReactNode;
+  size?: DesignSystemSize;
+}
+
+export interface SurfaceProps
+  extends DesignSystemStyleProps, DesignSystemAccessibleProps {
+  children: ReactNode;
+  as?: "div" | "section" | "article" | "aside";
+  elevation?: "none" | "low" | "medium";
+  padding?: "none" | "compact" | "default" | "spacious";
+  interactive?: boolean;
+  onPress?: (event?: DesignSystemPressEvent) => void;
+}
+
+export interface AvatarProps
+  extends DesignSystemStyleProps, DesignSystemAccessibleProps {
+  name: string;
+  src?: string | null;
+  fallback?: ReactNode;
+  size?: DesignSystemSize;
+  status?: "online" | "offline" | "busy" | "away";
+  imageRef?: Ref<HTMLImageElement>;
+}
+
+export interface TooltipProps extends DesignSystemOverlayProps {
+  trigger: ReactElement;
+  content: ReactNode;
+  open?: boolean;
+  defaultOpen?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  delayMs?: number;
+  disabled?: boolean;
+}
+
+export interface MenuItem {
+  id: DesignSystemKey;
+  label: ReactNode;
+  description?: ReactNode;
+  icon?: ReactNode;
+  shortcut?: ReactNode;
+  disabled?: boolean;
+  intent?: Extract<DesignSystemIntent, "neutral" | "danger">;
+  selected?: boolean;
+  children?: readonly MenuItem[];
+}
+
+export interface MenuSection {
+  id: DesignSystemKey;
+  label?: ReactNode;
+  items: readonly MenuItem[];
+}
+
+export interface MenuProps extends DesignSystemOverlayProps {
+  trigger: ReactElement;
+  items?: readonly MenuItem[];
+  sections?: readonly MenuSection[];
+  open?: boolean;
+  defaultOpen?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  onAction: (id: DesignSystemKey) => void;
+  closeOnAction?: boolean;
+}
+
+export interface PopoverProps extends DesignSystemOverlayProps {
+  trigger: ReactElement;
+  children: ReactNode;
+  open?: boolean;
+  defaultOpen?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  modal?: boolean;
+  dismissible?: boolean;
+  initialFocusRef?: RefObject<HTMLElement | null>;
+  restoreFocusRef?: RefObject<HTMLElement | null>;
+}
+
+export interface DialogProps extends DesignSystemOverlayProps {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  title: ReactNode;
+  children: ReactNode;
+  description?: ReactNode;
+  footer?: ReactNode;
+  trigger?: ReactElement;
+  size?: "small" | "medium" | "large" | "fullscreen";
+  dismissible?: boolean;
+  closeLabel?: string;
+  initialFocusRef?: RefObject<HTMLElement | null>;
+  restoreFocusRef?: RefObject<HTMLElement | null>;
+}
+
+export interface PickerOption<Value extends DesignSystemKey = string> {
+  value: Value;
+  label: ReactNode;
+  textValue?: string;
+  description?: ReactNode;
+  icon?: ReactNode;
+  disabled?: boolean;
+  keywords?: readonly string[];
+}
+
+export interface PickerProps<Value extends DesignSystemKey = string>
+  extends DesignSystemOverlayProps, DesignSystemAccessibleProps {
+  mode: "select" | "combobox";
+  options: readonly PickerOption<Value>[];
+  value: Value | null;
+  onChange: (value: Value | null) => void;
+  label?: ReactNode;
+  description?: ReactNode;
+  errorMessage?: ReactNode;
+  placeholder?: string;
+  searchValue?: string;
+  onSearchChange?: (value: string) => void;
+  open?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  emptyContent?: ReactNode;
+  loadingContent?: ReactNode;
+  loading?: boolean;
+  required?: boolean;
+  disabled?: boolean;
+  invalid?: boolean;
+  pickerRef?: Ref<HTMLElement>;
+}
+
+export interface CheckboxProps
+  extends DesignSystemStyleProps, DesignSystemAccessibleProps {
+  checked: boolean;
+  onChange: (checked: boolean) => void;
+  label?: ReactNode;
+  description?: ReactNode;
+  indeterminate?: boolean;
+  required?: boolean;
+  disabled?: boolean;
+  invalid?: boolean;
+  inputRef?: Ref<HTMLButtonElement>;
+}
+
+export interface SwitchProps
+  extends DesignSystemStyleProps, DesignSystemAccessibleProps {
+  checked: boolean;
+  onChange: (checked: boolean) => void;
+  label?: ReactNode;
+  description?: ReactNode;
+  disabled?: boolean;
+  inputRef?: Ref<HTMLButtonElement>;
+}
+
+export interface TabItem<Value extends DesignSystemKey = string> {
+  value: Value;
+  label: ReactNode;
+  content: ReactNode;
+  disabled?: boolean;
+  icon?: ReactNode;
+}
+
+export interface TabsProps<Value extends DesignSystemKey = string>
+  extends DesignSystemStyleProps, DesignSystemAccessibleProps {
+  items: readonly TabItem<Value>[];
+  value: Value;
+  onChange: (value: Value) => void;
+  orientation?: "horizontal" | "vertical";
+  activationMode?: "automatic" | "manual";
+}
+
+export interface PickerComponent {
+  <Value extends DesignSystemKey = string>(
+    props: PickerProps<Value>,
+  ): ReactNode;
+}
+
+export interface TabsComponent {
+  <Value extends DesignSystemKey = string>(props: TabsProps<Value>): ReactNode;
+}
+
+export interface DesignSystemComponents {
+  ActionButton: ComponentType<ActionButtonProps>;
+  IconButton: ComponentType<IconButtonProps>;
+  TextField: ComponentType<TextFieldProps>;
+  TextArea: ComponentType<TextAreaProps>;
+  Spinner: ComponentType<SpinnerProps>;
+  Skeleton: ComponentType<SkeletonProps>;
+  Status: ComponentType<StatusProps>;
+  Surface: ComponentType<SurfaceProps>;
+  Avatar: ComponentType<AvatarProps>;
+  Tooltip: ComponentType<TooltipProps>;
+  Menu: ComponentType<MenuProps>;
+  Popover: ComponentType<PopoverProps>;
+  Dialog: ComponentType<DialogProps>;
+  Picker: PickerComponent;
+  Checkbox: ComponentType<CheckboxProps>;
+  Switch: ComponentType<SwitchProps>;
+  Tabs: TabsComponent;
+}
+
+export type DesignSystemComponentName = keyof DesignSystemComponents;

package/corpus/toolkit/src/provider.tsx

@@ -1,20 +1,33 @@
 import {
   createContext,
   useContext,
+  useEffect,
   useMemo,
+  type ElementType,
   type ReactNode,
   type ComponentType,
 } from "react";
 
+import {
+  DesignSystemContext,
+  LegacyButtonRenderContext,
+  type DesignSystemContextValue,
+} from "./design-system/context.js";
+import type { DesignSystemDefinition } from "./design-system/definition.js";
+import type {
+  ActionButtonProps,
+  DesignSystemComponents,
+} from "./design-system/types.js";
 import type { ButtonProps } from "./ui/button.js";
 
 export interface ToolkitComponents {
   Button?: ComponentType<ButtonProps>;
 }
 
-interface ToolkitProviderProps {
+export interface ToolkitProviderProps {
   children: ReactNode;
   components?: ToolkitComponents;
+  designSystem?: DesignSystemDefinition;
 }
 
 const ToolkitComponentsContext = createContext<ToolkitComponents>({});
@@ -22,17 +35,97 @@ const ToolkitComponentsContext = createContext<ToolkitComponents>({});
 export function ToolkitProvider({
   children,
   components,
+  designSystem,
 }: ToolkitProviderProps) {
   const parent = useContext(ToolkitComponentsContext);
-  const value = useMemo(
+  const parentDesignSystem = useContext(DesignSystemContext);
+  const value = useMemo<ToolkitComponents>(
     () => ({ ...parent, ...components }),
     [parent, components],
   );
+  const mergedDefinition = useMemo<DesignSystemDefinition | undefined>(() => {
+    if (!designSystem) return parentDesignSystem.definition;
+    return {
+      ...parentDesignSystem.definition,
+      ...designSystem,
+      components: {
+        ...parentDesignSystem.definition?.components,
+        ...designSystem.components,
+      },
+    };
+  }, [designSystem, parentDesignSystem.definition]);
+  const legacyActionButton = useMemo<
+    DesignSystemComponents["ActionButton"] | undefined
+  >(() => {
+    if (!value.Button) return parentDesignSystem.legacyActionButton;
+    const LegacyButton = value.Button as ElementType<
+      ButtonProps & { ref?: ActionButtonProps["elementRef"] }
+    >;
+    return function LegacyActionButton({
+      children,
+      intent,
+      emphasis,
+      size,
+      pending,
+      leadingIcon,
+      trailingIcon,
+      onPress,
+      elementRef,
+      ...props
+    }: ActionButtonProps) {
+      const variant =
+        emphasis === "ghost"
+          ? "ghost"
+          : emphasis === "outline"
+            ? "outline"
+            : intent === "danger"
+              ? "destructive"
+              : intent === "primary"
+                ? "default"
+                : "secondary";
+      const legacySize =
+        size === "compact" ? "sm" : size === "large" ? "lg" : "default";
+      return (
+        <LegacyButtonRenderContext.Provider value={true}>
+          <LegacyButton
+            {...props}
+            ref={elementRef}
+            variant={variant}
+            size={legacySize}
+            disabled={props.disabled || pending}
+            aria-busy={pending || undefined}
+            onClick={(event) => onPress?.(event)}
+          >
+            {leadingIcon}
+            {children}
+            {trailingIcon}
+          </LegacyButton>
+        </LegacyButtonRenderContext.Provider>
+      );
+    };
+  }, [parentDesignSystem.legacyActionButton, value.Button]);
+  const designSystemValue = useMemo<DesignSystemContextValue>(
+    () => ({ definition: mergedDefinition, legacyActionButton }),
+    [legacyActionButton, mergedDefinition],
+  );
+
+  useEffect(() => {
+    if (!mergedDefinition?.components?.ActionButton || !value.Button) return;
+    const isDevelopment =
+      (import.meta as ImportMeta & { env?: { DEV?: boolean } }).env?.DEV ??
+      true;
+    if (!isDevelopment) return;
+    console.warn(
+      "[agent-native] ToolkitProvider received both designSystem.components.ActionButton and legacy components.Button. ActionButton takes precedence.",
+    );
+  }, [mergedDefinition?.components?.ActionButton, value.Button]);
 
   return (
-    <ToolkitComponentsContext.Provider value={value}>
-      {children}
-    </ToolkitComponentsContext.Provider>
+    <DesignSystemContext.Provider value={designSystemValue}>
+      <ToolkitComponentsContext.Provider value={value}>
+        {children}
+      </ToolkitComponentsContext.Provider>
+    </DesignSystemContext.Provider>
   );
 }