@agent-native/toolkit 0.9.1 → 0.10.1

package/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/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/src/editor/SlashCommandMenu.spec.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  DEFAULT_SLASH_COMMANDS,
+  filterSlashCommandItems,
+} from "./SlashCommandMenu.js";
+
+describe("filterSlashCommandItems", () => {
+  it("hides commands whose editor extensions are disabled", () => {
+    const commands = filterSlashCommandItems(DEFAULT_SLASH_COMMANDS, {
+      codeBlock: false,
+      tables: false,
+      tasks: false,
+    });
+
+    expect(commands.map((command) => command.title)).not.toEqual(
+      expect.arrayContaining(["Code block", "Table", "To-do list"]),
+    );
+  });
+
+  it("keeps commands enabled when their feature is unspecified", () => {
+    const commands = filterSlashCommandItems(DEFAULT_SLASH_COMMANDS, {
+      tasks: false,
+    });
+
+    expect(commands.map((command) => command.title)).toEqual(
+      expect.arrayContaining(["Code block", "Table"]),
+    );
+    expect(commands.map((command) => command.title)).not.toContain(
+      "To-do list",
+    );
+  });
+});

package/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/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,

package/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>
   );
 }