@agent-native/core 0.117.2 → 0.118.1

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/editor/SharedRichEditor.tsx

@@ -14,7 +14,12 @@ import {
   type SharedEditorFeatures,
 } from "./extensions.js";
 import type { ImageUploadFn } from "./ImageExtension.js";
-import { SlashCommandMenu, type SlashCommandItem } from "./SlashCommandMenu.js";
+import {
+  DEFAULT_SLASH_COMMANDS,
+  filterSlashCommandItems,
+  SlashCommandMenu,
+  type SlashCommandItem,
+} from "./SlashCommandMenu.js";
 import {
   useCollabReconcile,
   getEditorMarkdown,
@@ -200,6 +205,12 @@ export function SharedRichEditor({
 
   const collab = !!ydoc;
 
+  const effectiveSlashItems = useMemo(
+    () =>
+      filterSlashCommandItems(slashItems ?? DEFAULT_SLASH_COMMANDS, features),
+    [features, slashItems],
+  );
+
   // The collab hook needs the editor, but useEditor's `onUpdate` needs the
   // hook's guards. Break the cycle with a ref: `onUpdate` reads the guards
   // through `guardsRef`, which is populated right after the hook runs below.
@@ -313,7 +324,7 @@ export function SharedRichEditor({
         <BubbleToolbar editor={editor} buildItems={buildBubbleItems} />
       ) : null}
       {editable ? (
-        <SlashCommandMenu editor={editor} items={slashItems} />
+        <SlashCommandMenu editor={editor} items={effectiveSlashItems} />
       ) : null}
       <EditorContent editor={editor} />
     </div>

package/corpus/toolkit/src/editor/SlashCommandMenu.tsx

@@ -22,9 +22,26 @@ export interface SlashCommandItem {
   searchText?: string;
   /** Short text glyph shown in the menu (T, H1, tbl, …). */
   icon: string;
+  /** Hide this command when the shared editor feature is disabled. */
+  requires?: "tables" | "tasks" | "codeBlock";
   action: (editor: Editor) => void;
 }
 
+export interface SlashCommandFeatureFlags {
+  tables?: boolean;
+  tasks?: boolean;
+  codeBlock?: boolean;
+}
+
+export function filterSlashCommandItems(
+  items: readonly SlashCommandItem[],
+  features?: SlashCommandFeatureFlags,
+): SlashCommandItem[] {
+  return items.filter(
+    (item) => !item.requires || features?.[item.requires] !== false,
+  );
+}
+
 /**
  * The default block commands — Plan's current set. Apps pass their own `items`
  * (typically `[...DEFAULT_SLASH_COMMANDS, ...extra]`) to extend it.
@@ -73,6 +90,7 @@ export const DEFAULT_SLASH_COMMANDS: SlashCommandItem[] = [
     title: "To-do list",
     description: "Checklist items",
     icon: "[]",
+    requires: "tasks",
     action: (editor) => editor.chain().focus().toggleTaskList().run(),
   },
   {
@@ -85,6 +103,7 @@ export const DEFAULT_SLASH_COMMANDS: SlashCommandItem[] = [
     title: "Code block",
     description: "Code snippet",
     icon: "<>",
+    requires: "codeBlock",
     action: (editor) => editor.chain().focus().toggleCodeBlock().run(),
   },
   {
@@ -97,6 +116,7 @@ export const DEFAULT_SLASH_COMMANDS: SlashCommandItem[] = [
     title: "Table",
     description: "Three by three table",
     icon: "tbl",
+    requires: "tables",
     action: (editor) =>
       editor
         .chain()

package/corpus/toolkit/src/editor/index.ts

@@ -25,8 +25,10 @@ export {
   SlashCommandMenu,
   DEFAULT_SLASH_COMMANDS,
   createImageSlashCommand,
+  filterSlashCommandItems,
   type SlashCommandItem,
   type SlashCommandMenuProps,
+  type SlashCommandFeatureFlags,
 } from "./SlashCommandMenu.js";
 export {
   SharedImage,