@assistant-ui/react 0.12.22 → 0.12.24

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";

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";