@assistant-ui/react 0.12.23 → 0.12.25

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

@@ -0,0 +1,129 @@
+"use client";
+
+import {
+  createContext,
+  useContext,
+  useEffect,
+  useId,
+  type ReactNode,
+  type FC,
+} from "react";
+import { useResource } from "@assistant-ui/tap/react";
+import { useAui, useAuiState } from "@assistant-ui/store";
+import type { Unstable_TriggerAdapter } from "@assistant-ui/core";
+import {
+  TriggerPopoverResource,
+  type TriggerPopoverResourceOutput,
+  type OnSelectBehavior,
+} from "./TriggerPopoverResource";
+import {
+  useComposerInputPluginRegistryOptional,
+  ComposerInputPluginProvider,
+} from "../ComposerInputPluginContext";
+
+// =============================================================================
+// Context
+// =============================================================================
+
+const TriggerPopoverContext =
+  createContext<TriggerPopoverResourceOutput | null>(null);
+
+export const useTriggerPopoverContext = () => {
+  const ctx = useContext(TriggerPopoverContext);
+  if (!ctx)
+    throw new Error(
+      "useTriggerPopoverContext must be used within ComposerPrimitive.TriggerPopoverRoot",
+    );
+  return ctx;
+};
+
+export const useTriggerPopoverContextOptional = () => {
+  return useContext(TriggerPopoverContext);
+};
+
+// =============================================================================
+// Root Component
+// =============================================================================
+
+export namespace ComposerPrimitiveTriggerPopoverRoot {
+  export type Props = {
+    children: ReactNode;
+    /** The adapter providing categories and items. */
+    adapter: Unstable_TriggerAdapter;
+    /** Character(s) that trigger the popover. @default "@" */
+    trigger?: string | undefined;
+    /** What happens when an item is selected. */
+    onSelect: OnSelectBehavior;
+  };
+}
+
+const TriggerPopoverRootInner: FC<
+  ComposerPrimitiveTriggerPopoverRoot.Props
+> = ({ children, adapter, trigger: triggerChar = "@", onSelect }) => {
+  const aui = useAui();
+  const text = useAuiState((s) => s.composer.text);
+  const popoverId = useId();
+
+  const triggerPopover = useResource(
+    TriggerPopoverResource({
+      adapter,
+      text,
+      triggerChar,
+      onSelect,
+      aui,
+      popoverId,
+    }),
+  );
+
+  // Register as ComposerInput plugin
+  const pluginRegistry = useComposerInputPluginRegistryOptional();
+
+  useEffect(() => {
+    if (!pluginRegistry) return undefined;
+    return pluginRegistry.register(triggerPopover);
+  }, [pluginRegistry, triggerPopover]);
+
+  return (
+    <TriggerPopoverContext.Provider value={triggerPopover}>
+      {children}
+    </TriggerPopoverContext.Provider>
+  );
+};
+
+/**
+ * Provider that wraps the composer with trigger detection, keyboard navigation,
+ * and popover state. Supports any trigger character (`@`, `/`, `:`, etc.).
+ * Multiple trigger roots can coexist around the same input.
+ *
+ * @example
+ * ```tsx
+ * <ComposerPrimitive.Unstable_TriggerPopoverRoot
+ *   trigger="/"
+ *   adapter={slashAdapter}
+ *   onSelect={{ type: "action", handler: (item) => console.log(item) }}
+ * >
+ *   <ComposerPrimitive.Input />
+ *   <ComposerPrimitive.Unstable_TriggerPopoverPopover>
+ *     ...
+ *   </ComposerPrimitive.Unstable_TriggerPopoverPopover>
+ * </ComposerPrimitive.Unstable_TriggerPopoverRoot>
+ * ```
+ */
+export const ComposerPrimitiveTriggerPopoverRoot: FC<
+  ComposerPrimitiveTriggerPopoverRoot.Props
+> = (props) => {
+  const existingRegistry = useComposerInputPluginRegistryOptional();
+
+  if (existingRegistry) {
+    return <TriggerPopoverRootInner {...props} />;
+  }
+
+  return (
+    <ComposerInputPluginProvider>
+      <TriggerPopoverRootInner {...props} />
+    </ComposerInputPluginProvider>
+  );
+};
+
+ComposerPrimitiveTriggerPopoverRoot.displayName =
+  "ComposerPrimitive.TriggerPopoverRoot";

package/src/primitives/composer/{mention/ComposerMentionItems.tsx → trigger/TriggerPopoverItems.tsx}

@@ -9,66 +9,69 @@ import {
   useCallback,
 } from "react";
 import { composeEventHandlers } from "@radix-ui/primitive";
-import { useMentionContext } from "./ComposerMentionContext";
-import type { Unstable_MentionItem } from "@assistant-ui/core";
+import { useTriggerPopoverContext } from "./TriggerPopoverContext";
+import type { Unstable_TriggerItem } from "@assistant-ui/core";
 
 // =============================================================================
-// MentionItems — Renders the list of items within a category
+// TriggerPopoverItems — Renders the list of items within a category
 // =============================================================================
 
-export namespace ComposerPrimitiveMentionItems {
+export namespace ComposerPrimitiveTriggerPopoverItems {
   export type Element = ComponentRef<typeof Primitive.div>;
   export type Props = Omit<
     ComponentPropsWithoutRef<typeof Primitive.div>,
     "children"
   > & {
-    /**
-     * Render function that receives the filtered items 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: (items: readonly Unstable_MentionItem[]) => ReactNode;
+    children: (items: readonly Unstable_TriggerItem[]) => ReactNode;
   };
 }
 
-export const ComposerPrimitiveMentionItems = forwardRef<
-  ComposerPrimitiveMentionItems.Element,
-  ComposerPrimitiveMentionItems.Props
->(({ children, ...props }, forwardedRef) => {
-  const { items, activeCategoryId, isSearchMode } = useMentionContext();
+/**
+ * Renders the list of items within a category or search results via a render function.
+ * Only renders when a category is active or search mode is on.
+ */
+export const ComposerPrimitiveTriggerPopoverItems = forwardRef<
+  ComposerPrimitiveTriggerPopoverItems.Element,
+  ComposerPrimitiveTriggerPopoverItems.Props
+>(({ children, "aria-label": ariaLabel, ...props }, forwardedRef) => {
+  const { items, activeCategoryId, isSearchMode } = useTriggerPopoverContext();
 
   if (!activeCategoryId && !isSearchMode) return null;
 
   return (
-    <Primitive.div role="group" {...props} ref={forwardedRef}>
+    <Primitive.div
+      role="group"
+      aria-label={ariaLabel ?? "Items"}
+      {...props}
+      ref={forwardedRef}
+    >
       {children(items)}
     </Primitive.div>
   );
 });
 
-ComposerPrimitiveMentionItems.displayName = "ComposerPrimitive.MentionItems";
+ComposerPrimitiveTriggerPopoverItems.displayName =
+  "ComposerPrimitive.TriggerPopoverItems";
 
 // =============================================================================
-// MentionItem — A single selectable mention item
+// TriggerPopoverItem — A single selectable item
 // =============================================================================
 
-export namespace ComposerPrimitiveMentionItem {
+export namespace ComposerPrimitiveTriggerPopoverItem {
   export type Element = ComponentRef<typeof Primitive.button>;
   export type Props = ComponentPropsWithoutRef<typeof Primitive.button> & {
-    item: Unstable_MentionItem;
-    /** Position in the items list. Used for keyboard highlight matching. Falls back to findIndex by id. */
+    item: Unstable_TriggerItem;
     index?: number | undefined;
   };
 }
 
 /**
- * A button that inserts the mention item into the composer.
+ * A button that selects a trigger item.
  * Automatically receives `data-highlighted` when keyboard-navigated.
  */
-export const ComposerPrimitiveMentionItem = forwardRef<
-  ComposerPrimitiveMentionItem.Element,
-  ComposerPrimitiveMentionItem.Props
+export const ComposerPrimitiveTriggerPopoverItem = forwardRef<
+  ComposerPrimitiveTriggerPopoverItem.Element,
+  ComposerPrimitiveTriggerPopoverItem.Props
 >(({ item, index: indexProp, onClick, ...props }, forwardedRef) => {
   const {
     selectItem,
@@ -76,13 +79,13 @@ export const ComposerPrimitiveMentionItem = forwardRef<
     highlightedIndex,
     activeCategoryId,
     isSearchMode,
-  } = useMentionContext();
+    popoverId,
+  } = useTriggerPopoverContext();
 
   const handleClick = useCallback(() => {
     selectItem(item);
   }, [selectItem, item]);
 
-  // Use explicit index prop if provided, fall back to findIndex
   const itemIndex = indexProp ?? items.findIndex((i) => i.id === item.id);
   const isHighlighted =
     (isSearchMode || activeCategoryId !== null) &&
@@ -92,6 +95,7 @@ export const ComposerPrimitiveMentionItem = forwardRef<
     <Primitive.button
       type="button"
       role="option"
+      id={`${popoverId}-option-${item.id}`}
       aria-selected={isHighlighted}
       data-highlighted={isHighlighted ? "" : undefined}
       {...props}
@@ -101,4 +105,5 @@ export const ComposerPrimitiveMentionItem = forwardRef<
   );
 });
 
-ComposerPrimitiveMentionItem.displayName = "ComposerPrimitive.MentionItem";
+ComposerPrimitiveTriggerPopoverItem.displayName =
+  "ComposerPrimitive.TriggerPopoverItem";

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

@@ -0,0 +1,51 @@
+"use client";
+
+import { Primitive } from "../../../utils/Primitive";
+import {
+  type ComponentRef,
+  type ComponentPropsWithoutRef,
+  forwardRef,
+} from "react";
+import { useTriggerPopoverContext } from "./TriggerPopoverContext";
+
+export namespace ComposerPrimitiveTriggerPopoverPopover {
+  export type Element = ComponentRef<typeof Primitive.div>;
+  export type Props = ComponentPropsWithoutRef<typeof Primitive.div>;
+}
+
+/**
+ * Renders a container for the trigger popover.
+ * Only renders when a trigger character is detected in the composer text.
+ *
+ * @example
+ * ```tsx
+ * <ComposerPrimitive.Unstable_TriggerPopoverRoot trigger="/" adapter={adapter} onSelect={onSelect}>
+ *   <ComposerPrimitive.Input />
+ *   <ComposerPrimitive.Unstable_TriggerPopoverPopover>
+ *     <ComposerPrimitive.Unstable_TriggerPopoverCategories />
+ *   </ComposerPrimitive.Unstable_TriggerPopoverPopover>
+ * </ComposerPrimitive.Unstable_TriggerPopoverRoot>
+ * ```
+ */
+export const ComposerPrimitiveTriggerPopoverPopover = forwardRef<
+  ComposerPrimitiveTriggerPopoverPopover.Element,
+  ComposerPrimitiveTriggerPopoverPopover.Props
+>(({ "aria-label": ariaLabel, ...props }, forwardedRef) => {
+  const { open, popoverId, highlightedItemId } = useTriggerPopoverContext();
+  if (!open) return null;
+
+  return (
+    <Primitive.div
+      role="listbox"
+      id={popoverId}
+      aria-label={ariaLabel ?? "Suggestions"}
+      aria-activedescendant={highlightedItemId}
+      data-state="open"
+      {...props}
+      ref={forwardedRef}
+    />
+  );
+});
+
+ComposerPrimitiveTriggerPopoverPopover.displayName =
+  "ComposerPrimitive.TriggerPopoverPopover";

package/src/primitives/composer/{mention/MentionResource.ts → trigger/TriggerPopoverResource.ts}

@@ -7,43 +7,70 @@ import {
   tapRef,
 } from "@assistant-ui/tap";
 import type {
-  Unstable_MentionAdapter,
-  Unstable_MentionCategory,
-  Unstable_MentionItem,
+  Unstable_TriggerAdapter,
+  Unstable_TriggerCategory,
+  Unstable_TriggerItem,
   Unstable_DirectiveFormatter,
 } from "@assistant-ui/core";
 import type { AssistantClient } from "@assistant-ui/store";
-import { detectMentionTrigger } from "./detectMentionTrigger";
+import { detectTrigger } from "./detectTrigger";
+
+function isTriggerItem(
+  x: Unstable_TriggerItem | Unstable_TriggerCategory,
+): x is Unstable_TriggerItem {
+  return "type" in x;
+}
+
+function matchesQuery(item: Unstable_TriggerItem, lower: string): boolean {
+  return (
+    item.id.toLowerCase().includes(lower) ||
+    item.label.toLowerCase().includes(lower) ||
+    (item.description?.toLowerCase().includes(lower) ?? false)
+  );
+}
 
 // =============================================================================
 // Types
 // =============================================================================
 
-export type MentionKeyEvent = {
+export type TriggerPopoverKeyEvent = {
   readonly key: string;
   readonly shiftKey: boolean;
   preventDefault(): void;
 };
 
-export type SelectItemOverride = (item: Unstable_MentionItem) => boolean;
+export type SelectItemOverride = (item: Unstable_TriggerItem) => boolean;
 
-export type MentionResourceOutput = {
+export type OnSelectBehavior =
+  | {
+      type: "insertDirective";
+      formatter: Unstable_DirectiveFormatter;
+    }
+  | {
+      type: "action";
+      handler: (item: Unstable_TriggerItem) => void;
+    };
+
+export type TriggerPopoverResourceOutput = {
   // State
   readonly open: boolean;
   readonly query: string;
   readonly activeCategoryId: string | null;
-  readonly categories: readonly Unstable_MentionCategory[];
-  readonly items: readonly Unstable_MentionItem[];
+  readonly categories: readonly Unstable_TriggerCategory[];
+  readonly items: readonly Unstable_TriggerItem[];
   readonly highlightedIndex: number;
   readonly isSearchMode: boolean;
-  readonly formatter: Unstable_DirectiveFormatter;
+  /** Stable ID prefix for generating accessible element IDs. */
+  readonly popoverId: string;
+  /** ID of the currently highlighted item (for aria-activedescendant). */
+  readonly highlightedItemId: string | undefined;
 
   // Actions
   selectCategory(categoryId: string): void;
   goBack(): void;
-  selectItem(item: Unstable_MentionItem): void;
+  selectItem(item: Unstable_TriggerItem): void;
   close(): void;
-  handleKeyDown(e: MentionKeyEvent): boolean;
+  handleKeyDown(e: TriggerPopoverKeyEvent): boolean;
 
   // Internal (for ComposerInput integration)
   setCursorPosition(pos: number): void;
@@ -54,20 +81,23 @@ export type MentionResourceOutput = {
 // Resource
 // =============================================================================
 
-export const MentionResource = resource(
+export const TriggerPopoverResource = resource(
   ({
     adapter,
     text,
     triggerChar,
-    formatter,
+    onSelect,
     aui,
+    popoverId,
   }: {
-    adapter: Unstable_MentionAdapter | undefined;
+    adapter: Unstable_TriggerAdapter | undefined;
     text: string;
     triggerChar: string;
-    formatter: Unstable_DirectiveFormatter;
+    onSelect: OnSelectBehavior;
     aui: AssistantClient;
-  }): MentionResourceOutput => {
+    /** Stable ID for accessible element IDs (pass React's useId() from component layer). */
+    popoverId: string;
+  }): TriggerPopoverResourceOutput => {
     // -------------------------------------------------------------------------
     // Cursor tracking + trigger detection
     // -------------------------------------------------------------------------
@@ -76,7 +106,7 @@ export const MentionResource = resource(
 
     const trigger = tapMemo(() => {
       const pos = Math.min(cursorPosition, text.length);
-      return detectMentionTrigger(text, triggerChar, pos);
+      return detectTrigger(text, triggerChar, pos);
     }, [cursorPosition, text, triggerChar]);
 
     const open = trigger !== null && adapter !== undefined;
@@ -95,7 +125,7 @@ export const MentionResource = resource(
       if (!open) setActiveCategoryId(null);
     }, [open]);
 
-    const categories = tapMemo<readonly Unstable_MentionCategory[]>(() => {
+    const categories = tapMemo<readonly Unstable_TriggerCategory[]>(() => {
       if (!open || !adapter) return [];
       return adapter.categories();
     }, [open, adapter]);
@@ -106,33 +136,31 @@ export const MentionResource = resource(
     // Items + search
     // -------------------------------------------------------------------------
 
-    const allItems = tapMemo<readonly Unstable_MentionItem[]>(() => {
+    const allItems = tapMemo<readonly Unstable_TriggerItem[]>(() => {
       if (!effectiveActiveCategoryId || !adapter) return [];
       return adapter.categoryItems(effectiveActiveCategoryId);
     }, [effectiveActiveCategoryId, adapter]);
 
     const searchResults = tapMemo<
-      readonly Unstable_MentionItem[] | null
+      readonly Unstable_TriggerItem[] | null
     >(() => {
-      if (!open || !adapter || !query || effectiveActiveCategoryId) return null;
+      if (!open || !adapter || effectiveActiveCategoryId) return null;
+      // If categories exist and query is empty, show categories first (not search)
+      if (!query && categories.length > 0) return null;
       if (adapter.search) return adapter.search(query);
 
-      const cats = adapter.categories();
-      const all: Unstable_MentionItem[] = [];
+      // Fallback: search all categories manually (reuse already-computed list)
+      const all: Unstable_TriggerItem[] = [];
       const lower = query.toLowerCase();
-      for (const cat of cats) {
+      for (const cat of categories) {
         for (const item of adapter.categoryItems(cat.id)) {
-          if (
-            item.id.toLowerCase().includes(lower) ||
-            item.label.toLowerCase().includes(lower) ||
-            item.description?.toLowerCase().includes(lower)
-          ) {
+          if (matchesQuery(item, lower)) {
             all.push(item);
           }
         }
       }
       return all;
-    }, [open, adapter, query, effectiveActiveCategoryId]);
+    }, [open, adapter, query, effectiveActiveCategoryId, categories]);
 
     const isSearchMode = searchResults !== null;
 
@@ -153,12 +181,7 @@ export const MentionResource = resource(
       if (isSearchMode) return searchResults ?? [];
       if (!query) return allItems;
       const lower = query.toLowerCase();
-      return allItems.filter(
-        (item) =>
-          item.id.toLowerCase().includes(lower) ||
-          item.label.toLowerCase().includes(lower) ||
-          item.description?.toLowerCase().includes(lower),
-      );
+      return allItems.filter((item) => matchesQuery(item, lower));
     }, [allItems, query, isSearchMode, searchResults]);
 
     // -------------------------------------------------------------------------
@@ -186,7 +209,7 @@ export const MentionResource = resource(
     }, [navigableList]);
 
     // -------------------------------------------------------------------------
-    // Lexical select-item override
+    // Select-item override (for Lexical integration)
     // -------------------------------------------------------------------------
 
     const selectItemOverrideRef = tapRef<SelectItemOverride | null>(null);
@@ -216,27 +239,42 @@ export const MentionResource = resource(
       setHighlightedIndex(0);
     });
 
-    const selectItem = tapEffectEvent((item: Unstable_MentionItem) => {
+    const selectItem = tapEffectEvent((item: Unstable_TriggerItem) => {
       if (!trigger) return;
 
-      // Try the Lexical override first
+      // Try the override first (e.g. Lexical MentionPlugin)
       if (selectItemOverrideRef.current?.(item)) {
         setActiveCategoryId(null);
         setHighlightedIndex(0);
         return;
       }
 
-      // Default: text-based replacement (textarea path)
-      const currentText = aui.composer().getState().text;
-      const before = currentText.slice(0, trigger.offset);
-      const after = currentText.slice(
-        trigger.offset + triggerChar.length + trigger.query.length,
-      );
-      const directive = formatter.serialize(item);
-      const newText =
-        before + directive + (after.startsWith(" ") ? after : ` ${after}`);
+      // Behavior depends on the onSelect configuration
+      if (onSelect.type === "insertDirective") {
+        // Insert directive text (mention path)
+        const currentText = aui.composer().getState().text;
+        const before = currentText.slice(0, trigger.offset);
+        const after = currentText.slice(
+          trigger.offset + triggerChar.length + trigger.query.length,
+        );
+        const directive = onSelect.formatter.serialize(item);
+        const newText =
+          before + directive + (after.startsWith(" ") ? after : ` ${after}`);
+
+        aui.composer().setText(newText);
+      } else if (onSelect.type === "action") {
+        // Execute action + clear trigger text (slash command path)
+        const currentText = aui.composer().getState().text;
+        const before = currentText.slice(0, trigger.offset);
+        const after = currentText.slice(
+          trigger.offset + triggerChar.length + trigger.query.length,
+        );
+        const newText = before + after.trimStart();
+        aui.composer().setText(newText);
+
+        onSelect.handler(item);
+      }
 
-      aui.composer().setText(newText);
       setActiveCategoryId(null);
       setHighlightedIndex(0);
     });
@@ -250,63 +288,72 @@ export const MentionResource = resource(
       }
     });
 
-    const handleKeyDown = tapEffectEvent((e: MentionKeyEvent): boolean => {
-      if (!open) return false;
-
-      switch (e.key) {
-        case "ArrowDown": {
-          e.preventDefault();
-          setHighlightedIndex((prev) => {
-            const len = navigableList.length;
-            if (len === 0) return 0;
-            return prev < len - 1 ? prev + 1 : 0;
-          });
-          return true;
-        }
-        case "ArrowUp": {
-          e.preventDefault();
-          setHighlightedIndex((prev) => {
-            const len = navigableList.length;
-            if (len === 0) return 0;
-            return prev > 0 ? prev - 1 : len - 1;
-          });
-          return true;
-        }
-        case "Enter": {
-          if (e.shiftKey) return false;
-          e.preventDefault();
-          const item = navigableList[highlightedIndex];
-          if (!item) return true;
-
-          if (isSearchMode || effectiveActiveCategoryId) {
-            selectItem(item as Unstable_MentionItem);
-          } else {
-            selectCategory((item as Unstable_MentionCategory).id);
+    const handleKeyDown = tapEffectEvent(
+      (e: TriggerPopoverKeyEvent): boolean => {
+        if (!open) return false;
+
+        switch (e.key) {
+          case "ArrowDown": {
+            e.preventDefault();
+            setHighlightedIndex((prev) => {
+              const len = navigableList.length;
+              if (len === 0) return 0;
+              return prev < len - 1 ? prev + 1 : 0;
+            });
+            return true;
           }
-          return true;
-        }
-        case "Escape": {
-          e.preventDefault();
-          close();
-          return true;
-        }
-        case "Backspace": {
-          if (effectiveActiveCategoryId && query === "") {
+          case "ArrowUp": {
             e.preventDefault();
-            goBack();
+            setHighlightedIndex((prev) => {
+              const len = navigableList.length;
+              if (len === 0) return 0;
+              return prev > 0 ? prev - 1 : len - 1;
+            });
             return true;
           }
-          return false;
+          case "Enter": {
+            if (e.shiftKey) return false;
+            e.preventDefault();
+            const item = navigableList[highlightedIndex];
+            if (!item) return true;
+
+            if (isTriggerItem(item)) {
+              selectItem(item);
+            } else {
+              selectCategory(item.id);
+            }
+            return true;
+          }
+          case "Escape": {
+            e.preventDefault();
+            close();
+            return true;
+          }
+          case "Backspace": {
+            if (effectiveActiveCategoryId && query === "") {
+              e.preventDefault();
+              goBack();
+              return true;
+            }
+            return false;
+          }
+          default:
+            return false;
         }
-        default:
-          return false;
-      }
-    });
+      },
+    );
 
     // -------------------------------------------------------------------------
     // Output
     // -------------------------------------------------------------------------
 
+    // Compute highlighted item ID for aria-activedescendant
+    const highlightedEntry = navigableList[highlightedIndex];
+    const highlightedItemId =
+      open && highlightedEntry
+        ? `${popoverId}-option-${highlightedEntry.id}`
+        : undefined;
+
     return {
       open,
       query,
@@ -315,7 +362,8 @@ export const MentionResource = resource(
       items: filteredItems,
       highlightedIndex,
       isSearchMode,
-      formatter,
+      popoverId,
+      highlightedItemId,
       selectCategory,
       goBack,
       selectItem,