@assistant-ui/react 0.12.23 → 0.12.24

package/src/primitives/composer/ComposerInput.tsx

@@ -22,10 +22,7 @@ import { useEscapeKeydown } from "@radix-ui/react-use-escape-keydown";
 import { useOnScrollToBottom } from "../../utils/hooks/useOnScrollToBottom";
 import { useAuiState, useAui } from "@assistant-ui/store";
 import { flushResourcesSync } from "@assistant-ui/tap";
-import {
-  useMentionContextOptional,
-  useMentionInternalContext,
-} from "./mention/ComposerMentionContext";
+import { useComposerInputPluginRegistryOptional } from "./ComposerInputPluginContext";
 
 export namespace ComposerPrimitiveInput {
   export type Element = HTMLTextAreaElement;
@@ -144,8 +141,7 @@ export const ComposerPrimitiveInput = forwardRef<
     forwardedRef,
   ) => {
     const aui = useAui();
-    const mentionContext = useMentionContextOptional();
-    const mentionInternalContext = useMentionInternalContext();
+    const pluginRegistry = useComposerInputPluginRegistryOptional();
 
     const effectiveSubmitMode =
       submitMode ?? (submitOnEnter === false ? "none" : "enter");
@@ -166,10 +162,11 @@ export const ComposerPrimitiveInput = forwardRef<
       // Only handle ESC if it originated from within this input
       if (!textareaRef.current?.contains(e.target as Node)) return;
 
-      // Let mention popover handle Escape first
-      if (mentionContext?.open) {
-        mentionContext.handleKeyDown(e);
-        return;
+      // Let registered plugins (mention, slash command, etc.) handle Escape first
+      if (pluginRegistry) {
+        for (const plugin of pluginRegistry.getPlugins()) {
+          if (plugin.handleKeyDown(e)) return;
+        }
       }
 
       if (!cancelOnEscape) return;
@@ -187,8 +184,12 @@ export const ComposerPrimitiveInput = forwardRef<
       // ignore IME composition events
       if (e.nativeEvent.isComposing) return;
 
-      // Let the mention popover handle keyboard events first
-      if (mentionContext?.handleKeyDown(e)) return;
+      // Let registered plugins (mention, slash command, etc.) handle keyboard events first
+      if (pluginRegistry) {
+        for (const plugin of pluginRegistry.getPlugins()) {
+          if (plugin.handleKeyDown(e)) return;
+        }
+      }
 
       if (e.key === "Enter") {
         const threadState = aui.thread().getState();
@@ -297,9 +298,12 @@ export const ComposerPrimitiveInput = forwardRef<
           flushResourcesSync(() => {
             aui.composer().setText(e.target.value);
           });
-          mentionInternalContext?.setCursorPosition(
-            e.target.selectionStart ?? e.target.value.length,
-          );
+          const pos = e.target.selectionStart ?? e.target.value.length;
+          if (pluginRegistry) {
+            for (const plugin of pluginRegistry.getPlugins()) {
+              plugin.setCursorPosition(pos);
+            }
+          }
         },
       ),
       onKeyDown: composeEventHandlers(onKeyDown, handleKeyPress),
@@ -307,9 +311,12 @@ export const ComposerPrimitiveInput = forwardRef<
         onSelect,
         (e: React.SyntheticEvent<HTMLTextAreaElement>) => {
           const target = e.target as HTMLTextAreaElement;
-          mentionInternalContext?.setCursorPosition(
-            target.selectionStart ?? target.value.length,
-          );
+          const pos = target.selectionStart ?? target.value.length;
+          if (pluginRegistry) {
+            for (const plugin of pluginRegistry.getPlugins()) {
+              plugin.setCursorPosition(pos);
+            }
+          }
         },
       ),
       onPaste: composeEventHandlers(onPaste, handlePaste),

package/src/primitives/composer/ComposerInputPluginContext.tsx

@@ -0,0 +1,100 @@
+"use client";
+
+import {
+  createContext,
+  useContext,
+  useRef,
+  useCallback,
+  useMemo,
+  type ReactNode,
+  type FC,
+} from "react";
+
+// =============================================================================
+// Plugin interface — any trigger system (mention, slash command, emoji, etc.)
+// registers one of these with the input.
+// =============================================================================
+
+/**
+ * A plugin that intercepts keyboard events and cursor changes in the composer
+ * input. Used by trigger roots (MentionRoot, SlashCommandRoot, etc.) to handle
+ * popover navigation without ComposerInput knowing about specific triggers.
+ */
+export type ComposerInputPlugin = {
+  /** Handle a key event. Return true if consumed (stops propagation to other plugins and default behavior). */
+  handleKeyDown(e: {
+    readonly key: string;
+    readonly shiftKey: boolean;
+    readonly ctrlKey?: boolean;
+    readonly metaKey?: boolean;
+    readonly nativeEvent?: { isComposing?: boolean };
+    preventDefault(): void;
+  }): boolean;
+
+  /** Called on every cursor position change (selection change / text change). */
+  setCursorPosition(pos: number): void;
+};
+
+// =============================================================================
+// Registry — mutable, ref-based. No re-renders on register/unregister because
+// plugins are read imperatively at event time.
+// =============================================================================
+
+export type ComposerInputPluginRegistry = {
+  register(plugin: ComposerInputPlugin): () => void;
+  getPlugins(): readonly ComposerInputPlugin[];
+};
+
+const ComposerInputPluginRegistryContext =
+  createContext<ComposerInputPluginRegistry | null>(null);
+
+export const useComposerInputPluginRegistry =
+  (): ComposerInputPluginRegistry => {
+    const ctx = useContext(ComposerInputPluginRegistryContext);
+    if (!ctx)
+      throw new Error(
+        "useComposerInputPluginRegistry must be used within a ComposerInputPluginProvider",
+      );
+    return ctx;
+  };
+
+export const useComposerInputPluginRegistryOptional =
+  (): ComposerInputPluginRegistry | null => {
+    return useContext(ComposerInputPluginRegistryContext);
+  };
+
+// =============================================================================
+// Provider
+// =============================================================================
+
+export const ComposerInputPluginProvider: FC<{ children: ReactNode }> = ({
+  children,
+}) => {
+  const pluginsRef = useRef<Set<ComposerInputPlugin>>(new Set());
+  const snapshotRef = useRef<readonly ComposerInputPlugin[]>([]);
+
+  const register = useCallback((plugin: ComposerInputPlugin) => {
+    pluginsRef.current.add(plugin);
+    snapshotRef.current = Array.from(pluginsRef.current);
+    return () => {
+      pluginsRef.current.delete(plugin);
+      snapshotRef.current = Array.from(pluginsRef.current);
+    };
+  }, []);
+
+  const getPlugins = useCallback(
+    (): readonly ComposerInputPlugin[] => snapshotRef.current,
+    [],
+  );
+
+  const registry = useMemo<ComposerInputPluginRegistry>(
+    () => ({ register, getPlugins }),
+    [register, getPlugins],
+  );
+
+  return (
+    <ComposerInputPluginRegistryContext.Provider value={registry}>
+      {children}
+    </ComposerInputPluginRegistryContext.Provider>
+  );
+};

package/src/primitives/composer/mention/ComposerMentionContext.tsx

@@ -10,21 +10,25 @@ import {
   type ReactNode,
   type FC,
 } from "react";
-import { useResource } from "@assistant-ui/tap/react";
-import { useAui, useAuiState } from "@assistant-ui/store";
+import { useAui } from "@assistant-ui/store";
 import type {
   Unstable_MentionAdapter,
   Unstable_DirectiveFormatter,
 } from "@assistant-ui/core";
 import { unstable_defaultDirectiveFormatter } from "@assistant-ui/core";
-import {
-  MentionResource,
-  type MentionResourceOutput,
-  type SelectItemOverride,
-} from "./MentionResource";
+import { ComposerPrimitiveTriggerPopoverRoot } from "../trigger/TriggerPopoverContext";
+import type {
+  TriggerPopoverResourceOutput,
+  SelectItemOverride,
+  OnSelectBehavior,
+} from "../trigger/TriggerPopoverResource";
+
+type MentionResourceOutput = TriggerPopoverResourceOutput & {
+  readonly formatter: Unstable_DirectiveFormatter;
+};
 
 // =============================================================================
-// Context — public (popover components read state + actions from here)
+// Context — public (provides formatter on top of TriggerPopoverContext)
 // =============================================================================
 
 const MentionContext = createContext<MentionResourceOutput | null>(null);
@@ -43,11 +47,10 @@ export const useMentionContextOptional = () => {
 };
 
 // =============================================================================
-// Internal context — ComposerInput → MentionRoot communication
+// Internal context — only registerSelectItemOverride for Lexical integration
 // =============================================================================
 
 type MentionInternalContextValue = {
-  setCursorPosition(pos: number): void;
   registerSelectItemOverride(fn: SelectItemOverride): () => void;
 };
 
@@ -59,7 +62,7 @@ export const useMentionInternalContext = () => {
 };
 
 // =============================================================================
-// Provider Component
+// Provider Component — delegates to TriggerPopoverRoot internally
 // =============================================================================
 
 export namespace ComposerPrimitiveMentionRoot {
@@ -82,7 +85,6 @@ export const ComposerPrimitiveMentionRoot: FC<
   formatter: formatterProp,
 }) => {
   const aui = useAui();
-  const text = useAuiState((s) => s.composer.text);
   const formatter = formatterProp ?? unstable_defaultDirectiveFormatter;
 
   // ---------------------------------------------------------------------------
@@ -110,32 +112,64 @@ export const ComposerPrimitiveMentionRoot: FC<
   const adapter = adapterProp ?? runtimeAdapter;
 
   // ---------------------------------------------------------------------------
-  // Mention resource (all state + logic managed via tap primitives)
+  // onSelect behavior for mentions: insert directive text
   // ---------------------------------------------------------------------------
 
-  const mention = useResource(
-    MentionResource({ adapter, text, triggerChar, formatter, aui }),
+  const onSelect = useMemo<OnSelectBehavior>(
+    () => ({ type: "insertDirective", formatter }),
+    [formatter],
   );
 
   // ---------------------------------------------------------------------------
-  // Internal context (stable — methods come from tapEffectEvent)
+  // MentionContext — provides formatter + delegates state to TriggerPopoverContext
+  // We use useAuiState to read trigger popover state via the inner context.
+  // For backward compat, MentionContext wraps TriggerPopoverContext output.
   // ---------------------------------------------------------------------------
 
+  return (
+    <ComposerPrimitiveTriggerPopoverRoot
+      adapter={adapter}
+      trigger={triggerChar}
+      onSelect={onSelect}
+    >
+      <MentionContextBridge formatter={formatter}>
+        {children}
+      </MentionContextBridge>
+    </ComposerPrimitiveTriggerPopoverRoot>
+  );
+};
+
+ComposerPrimitiveMentionRoot.displayName = "ComposerPrimitive.MentionRoot";
+
+// =============================================================================
+// Bridge — reads TriggerPopoverContext, wraps it as MentionContext
+// =============================================================================
+
+import { useTriggerPopoverContext } from "../trigger/TriggerPopoverContext";
+
+const MentionContextBridge: FC<{
+  formatter: Unstable_DirectiveFormatter;
+  children: ReactNode;
+}> = ({ formatter, children }) => {
+  const triggerCtx = useTriggerPopoverContext();
+
+  const mentionValue = useMemo<MentionResourceOutput>(
+    () => ({ ...triggerCtx, formatter }),
+    [triggerCtx, formatter],
+  );
+
   const internalContextValue = useMemo<MentionInternalContextValue>(
     () => ({
-      setCursorPosition: mention.setCursorPosition,
-      registerSelectItemOverride: mention.registerSelectItemOverride,
+      registerSelectItemOverride: triggerCtx.registerSelectItemOverride,
     }),
-    [mention.setCursorPosition, mention.registerSelectItemOverride],
+    [triggerCtx.registerSelectItemOverride],
   );
 
   return (
-    <MentionContext.Provider value={mention}>
+    <MentionContext.Provider value={mentionValue}>
       <MentionInternalContext.Provider value={internalContextValue}>
         {children}
       </MentionInternalContext.Provider>
     </MentionContext.Provider>
   );
 };
-
-ComposerPrimitiveMentionRoot.displayName = "ComposerPrimitive.MentionRoot";

package/src/primitives/composer/mention/index.ts

@@ -4,13 +4,16 @@ export {
   useMentionContextOptional,
   useMentionInternalContext,
 } from "./ComposerMentionContext";
-export { ComposerPrimitiveMentionPopover } from "./ComposerMentionPopover";
+
+// UI primitives — re-exported from the shared trigger popover implementation.
+// MentionRoot internally renders TriggerPopoverRoot, so these work within it.
+export { ComposerPrimitiveTriggerPopoverPopover as ComposerPrimitiveMentionPopover } from "../trigger/TriggerPopoverPopover";
 export {
-  ComposerPrimitiveMentionCategories,
-  ComposerPrimitiveMentionCategoryItem,
-} from "./ComposerMentionCategories";
+  ComposerPrimitiveTriggerPopoverCategories as ComposerPrimitiveMentionCategories,
+  ComposerPrimitiveTriggerPopoverCategoryItem as ComposerPrimitiveMentionCategoryItem,
+} from "../trigger/TriggerPopoverCategories";
 export {
-  ComposerPrimitiveMentionItems,
-  ComposerPrimitiveMentionItem,
-} from "./ComposerMentionItems";
-export { ComposerPrimitiveMentionBack } from "./ComposerMentionBack";
+  ComposerPrimitiveTriggerPopoverItems as ComposerPrimitiveMentionItems,
+  ComposerPrimitiveTriggerPopoverItem as ComposerPrimitiveMentionItem,
+} from "../trigger/TriggerPopoverItems";
+export { ComposerPrimitiveTriggerPopoverBack as ComposerPrimitiveMentionBack } from "../trigger/TriggerPopoverBack";

package/src/primitives/composer/slash-command/ComposerSlashCommandRoot.tsx

@@ -0,0 +1,76 @@
+"use client";
+
+import { type ReactNode, type FC, useCallback, useMemo } from "react";
+import type {
+  Unstable_SlashCommandAdapter,
+  Unstable_SlashCommandItem,
+} from "@assistant-ui/core";
+import { ComposerPrimitiveTriggerPopoverRoot } from "../trigger/TriggerPopoverContext";
+import type { OnSelectBehavior } from "../trigger/TriggerPopoverResource";
+
+// =============================================================================
+// SlashCommandRoot — convenience wrapper around TriggerPopoverRoot
+// =============================================================================
+
+export namespace ComposerPrimitiveSlashCommandRoot {
+  export type Props = {
+    children: ReactNode;
+    /** The adapter providing slash command categories and items. */
+    adapter: Unstable_SlashCommandAdapter;
+    /** Character(s) that trigger the popover. @default "/" */
+    trigger?: string | undefined;
+    /** Callback when a slash command is selected. */
+    onSelect?: ((item: Unstable_SlashCommandItem) => void) | undefined;
+  };
+}
+
+/**
+ * Convenience wrapper around `TriggerPopoverRoot` pre-configured for `/` slash commands.
+ * When a user selects a command, the `/command` text is removed from the composer
+ * and the item's `execute` callback (if any) and `onSelect` prop are called.
+ *
+ * @example
+ * ```tsx
+ * <ComposerPrimitive.Unstable_SlashCommandRoot adapter={slashAdapter}>
+ *   <ComposerPrimitive.Input />
+ *   <ComposerPrimitive.Unstable_TriggerPopoverPopover>
+ *     <ComposerPrimitive.Unstable_TriggerPopoverItems>
+ *       {(items) => items.map(item => (
+ *         <ComposerPrimitive.Unstable_TriggerPopoverItem key={item.id} item={item}>
+ *           {item.label}
+ *         </ComposerPrimitive.Unstable_TriggerPopoverItem>
+ *       ))}
+ *     </ComposerPrimitive.Unstable_TriggerPopoverItems>
+ *   </ComposerPrimitive.Unstable_TriggerPopoverPopover>
+ * </ComposerPrimitive.Unstable_SlashCommandRoot>
+ * ```
+ */
+export const ComposerPrimitiveSlashCommandRoot: FC<
+  ComposerPrimitiveSlashCommandRoot.Props
+> = ({ children, adapter, trigger = "/", onSelect: onSelectProp }) => {
+  const handler = useCallback(
+    (item: Unstable_SlashCommandItem) => {
+      item.execute?.();
+      onSelectProp?.(item);
+    },
+    [onSelectProp],
+  );
+
+  const onSelect = useMemo<OnSelectBehavior>(
+    () => ({ type: "action", handler }),
+    [handler],
+  );
+
+  return (
+    <ComposerPrimitiveTriggerPopoverRoot
+      adapter={adapter}
+      trigger={trigger}
+      onSelect={onSelect}
+    >
+      {children}
+    </ComposerPrimitiveTriggerPopoverRoot>
+  );
+};
+
+ComposerPrimitiveSlashCommandRoot.displayName =
+  "ComposerPrimitive.SlashCommandRoot";

package/src/primitives/composer/slash-command/index.ts

@@ -0,0 +1 @@
+export { ComposerPrimitiveSlashCommandRoot } from "./ComposerSlashCommandRoot";

package/src/primitives/composer/trigger/TriggerPopoverBack.tsx

@@ -0,0 +1,40 @@
+"use client";
+
+import { Primitive } from "../../../utils/Primitive";
+import {
+  type ComponentRef,
+  type ComponentPropsWithoutRef,
+  forwardRef,
+} from "react";
+import { composeEventHandlers } from "@radix-ui/primitive";
+import { useTriggerPopoverContext } from "./TriggerPopoverContext";
+
+export namespace ComposerPrimitiveTriggerPopoverBack {
+  export type Element = ComponentRef<typeof Primitive.button>;
+  export type Props = ComponentPropsWithoutRef<typeof Primitive.button>;
+}
+
+/**
+ * A button that navigates back from category items to the category list.
+ * Only renders when a category is active (drill-down view).
+ */
+export const ComposerPrimitiveTriggerPopoverBack = forwardRef<
+  ComposerPrimitiveTriggerPopoverBack.Element,
+  ComposerPrimitiveTriggerPopoverBack.Props
+>(({ onClick, ...props }, forwardedRef) => {
+  const { activeCategoryId, isSearchMode, goBack } = useTriggerPopoverContext();
+
+  if (!activeCategoryId || isSearchMode) return null;
+
+  return (
+    <Primitive.button
+      type="button"
+      {...props}
+      ref={forwardedRef}
+      onClick={composeEventHandlers(onClick, goBack)}
+    />
+  );
+});
+
+ComposerPrimitiveTriggerPopoverBack.displayName =
+  "ComposerPrimitive.TriggerPopoverBack";

package/src/primitives/composer/{mention/ComposerMentionCategories.tsx → trigger/TriggerPopoverCategories.tsx}

@@ -9,52 +9,56 @@ import {
   useCallback,
 } from "react";
 import { composeEventHandlers } from "@radix-ui/primitive";
-import { useMentionContext } from "./ComposerMentionContext";
-import type { Unstable_MentionCategory } from "@assistant-ui/core";
+import { useTriggerPopoverContext } from "./TriggerPopoverContext";
+import type { Unstable_TriggerCategory } from "@assistant-ui/core";
 
 // =============================================================================
-// MentionCategories — Renders the list of categories
+// TriggerPopoverCategories — Renders the list of categories
 // =============================================================================
 
-export namespace ComposerPrimitiveMentionCategories {
+export namespace ComposerPrimitiveTriggerPopoverCategories {
   export type Element = ComponentRef<typeof Primitive.div>;
   export type Props = Omit<
     ComponentPropsWithoutRef<typeof Primitive.div>,
     "children"
   > & {
-    /**
-     * Render function that receives the filtered categories and returns
-     * the UI. A render-function pattern is used here (instead of a
-     * `components` prop) to give consumers full control over list layout,
-     * ordering, grouping, and empty states.
-     */
-    children: (categories: readonly Unstable_MentionCategory[]) => ReactNode;
+    children: (categories: readonly Unstable_TriggerCategory[]) => ReactNode;
   };
 }
 
-export const ComposerPrimitiveMentionCategories = forwardRef<
-  ComposerPrimitiveMentionCategories.Element,
-  ComposerPrimitiveMentionCategories.Props
->(({ children, ...props }, forwardedRef) => {
-  const { categories, activeCategoryId, isSearchMode } = useMentionContext();
+/**
+ * Renders the top-level category list via a render function.
+ * Only renders when no category is active and search mode is off.
+ */
+export const ComposerPrimitiveTriggerPopoverCategories = forwardRef<
+  ComposerPrimitiveTriggerPopoverCategories.Element,
+  ComposerPrimitiveTriggerPopoverCategories.Props
+>(({ children, "aria-label": ariaLabel, ...props }, forwardedRef) => {
+  const { categories, activeCategoryId, isSearchMode } =
+    useTriggerPopoverContext();
 
   if (activeCategoryId || isSearchMode) return null;
 
   return (
-    <Primitive.div role="group" {...props} ref={forwardedRef}>
+    <Primitive.div
+      role="group"
+      aria-label={ariaLabel ?? "Categories"}
+      {...props}
+      ref={forwardedRef}
+    >
       {children(categories)}
     </Primitive.div>
   );
 });
 
-ComposerPrimitiveMentionCategories.displayName =
-  "ComposerPrimitive.MentionCategories";
+ComposerPrimitiveTriggerPopoverCategories.displayName =
+  "ComposerPrimitive.TriggerPopoverCategories";
 
 // =============================================================================
-// MentionCategoryItem — A single category row (clickable to drill-down)
+// TriggerPopoverCategoryItem — A single category row
 // =============================================================================
 
-export namespace ComposerPrimitiveMentionCategoryItem {
+export namespace ComposerPrimitiveTriggerPopoverCategoryItem {
   export type Element = ComponentRef<typeof Primitive.button>;
   export type Props = ComponentPropsWithoutRef<typeof Primitive.button> & {
     categoryId: string;
@@ -65,9 +69,9 @@ export namespace ComposerPrimitiveMentionCategoryItem {
  * A button that selects a category and triggers drill-down navigation.
  * Automatically receives `data-highlighted` when keyboard-navigated.
  */
-export const ComposerPrimitiveMentionCategoryItem = forwardRef<
-  ComposerPrimitiveMentionCategoryItem.Element,
-  ComposerPrimitiveMentionCategoryItem.Props
+export const ComposerPrimitiveTriggerPopoverCategoryItem = forwardRef<
+  ComposerPrimitiveTriggerPopoverCategoryItem.Element,
+  ComposerPrimitiveTriggerPopoverCategoryItem.Props
 >(({ categoryId, onClick, ...props }, forwardedRef) => {
   const {
     selectCategory,
@@ -75,13 +79,13 @@ export const ComposerPrimitiveMentionCategoryItem = forwardRef<
     highlightedIndex,
     activeCategoryId,
     isSearchMode,
-  } = useMentionContext();
+    popoverId,
+  } = useTriggerPopoverContext();
 
   const handleClick = useCallback(() => {
     selectCategory(categoryId);
   }, [selectCategory, categoryId]);
 
-  // Derive highlighted state from context — no manual wiring needed
   const isHighlighted =
     !activeCategoryId &&
     !isSearchMode &&
@@ -91,6 +95,7 @@ export const ComposerPrimitiveMentionCategoryItem = forwardRef<
     <Primitive.button
       type="button"
       role="option"
+      id={`${popoverId}-option-${categoryId}`}
       aria-selected={isHighlighted}
       data-highlighted={isHighlighted ? "" : undefined}
       {...props}
@@ -100,5 +105,5 @@ export const ComposerPrimitiveMentionCategoryItem = forwardRef<
   );
 });
 
-ComposerPrimitiveMentionCategoryItem.displayName =
-  "ComposerPrimitive.MentionCategoryItem";
+ComposerPrimitiveTriggerPopoverCategoryItem.displayName =
+  "ComposerPrimitive.TriggerPopoverCategoryItem";