@assistant-ui/react 0.12.22 → 0.12.24

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,

package/src/primitives/composer/{mention/detectMentionTrigger.test.ts → trigger/detectTrigger.test.ts}

@@ -1,28 +1,28 @@
 import { describe, it, expect } from "vitest";
-import { detectMentionTrigger } from "./detectMentionTrigger";
+import { detectTrigger } from "./detectTrigger";
 
-describe("detectMentionTrigger", () => {
+describe("detectTrigger", () => {
   it("detects @query at cursor position", () => {
-    expect(detectMentionTrigger("hello @wea", "@", 10)).toEqual({
+    expect(detectTrigger("hello @wea", "@", 10)).toEqual({
       query: "wea",
       offset: 6,
     });
   });
 
   it("returns null when cursor is before the trigger", () => {
-    expect(detectMentionTrigger("hello @weather", "@", 5)).toBeNull();
+    expect(detectTrigger("hello @weather", "@", 5)).toBeNull();
   });
 
   it("returns null when no trigger character", () => {
-    expect(detectMentionTrigger("hello world", "@", 11)).toBeNull();
+    expect(detectTrigger("hello world", "@", 11)).toBeNull();
   });
 
   it("requires whitespace or start before trigger", () => {
-    expect(detectMentionTrigger("email@test", "@", 10)).toBeNull();
+    expect(detectTrigger("email@test", "@", 10)).toBeNull();
   });
 
   it("trigger at start of text", () => {
-    expect(detectMentionTrigger("@foo", "@", 4)).toEqual({
+    expect(detectTrigger("@foo", "@", 4)).toEqual({
       query: "foo",
       offset: 0,
     });
@@ -30,19 +30,19 @@ describe("detectMentionTrigger", () => {
 
   it("stops at whitespace in query", () => {
     // "@foo bar" — space terminates the mention
-    expect(detectMentionTrigger("@foo bar", "@", 8)).toBeNull();
+    expect(detectTrigger("@foo bar", "@", 8)).toBeNull();
   });
 
   it("stops at newline", () => {
-    expect(detectMentionTrigger("@foo\nbar", "@", 8)).toBeNull();
+    expect(detectTrigger("@foo\nbar", "@", 8)).toBeNull();
   });
 
   it("stops at tab", () => {
-    expect(detectMentionTrigger("@foo\tbar", "@", 8)).toBeNull();
+    expect(detectTrigger("@foo\tbar", "@", 8)).toBeNull();
   });
 
   it("treats tab before trigger as valid boundary", () => {
-    expect(detectMentionTrigger("hello\t@foo", "@", 10)).toEqual({
+    expect(detectTrigger("hello\t@foo", "@", 10)).toEqual({
       query: "foo",
       offset: 6,
     });
@@ -51,7 +51,7 @@ describe("detectMentionTrigger", () => {
   it("finds trigger closest to cursor, not earlier ones", () => {
     // Text has two @: "hello @old text @new"
     // Cursor at end → should find @new
-    expect(detectMentionTrigger("hello @old text @new", "@", 20)).toEqual({
+    expect(detectTrigger("hello @old text @new", "@", 20)).toEqual({
       query: "new",
       offset: 16,
     });
@@ -59,18 +59,18 @@ describe("detectMentionTrigger", () => {
 
   it("ignores trigger after cursor", () => {
     // Cursor at position 5, trigger at position 10
-    expect(detectMentionTrigger("hello text @foo", "@", 5)).toBeNull();
+    expect(detectTrigger("hello text @foo", "@", 5)).toBeNull();
   });
 
   it("works with multi-char trigger", () => {
-    expect(detectMentionTrigger("hello @@foo", "@@", 11)).toEqual({
+    expect(detectTrigger("hello @@foo", "@@", 11)).toEqual({
       query: "foo",
       offset: 6,
     });
   });
 
   it("empty query when cursor is right after trigger", () => {
-    expect(detectMentionTrigger("hello @", "@", 7)).toEqual({
+    expect(detectTrigger("hello @", "@", 7)).toEqual({
       query: "",
       offset: 6,
     });

package/src/primitives/composer/{mention/detectMentionTrigger.ts → trigger/detectTrigger.ts}

@@ -1,11 +1,11 @@
 const WHITESPACE_RE = /\s/;
 
 /**
- * Detect a mention trigger in text relative to the cursor position.
+ * Detect a trigger character in text relative to the cursor position.
  *
- * @internal Exported for testing and for the MentionResource.
+ * @internal Exported for testing and for trigger resources.
  */
-export function detectMentionTrigger(
+export function detectTrigger(
   text: string,
   triggerChar: string,
   cursorPosition: number,

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

@@ -0,0 +1,16 @@
+export {
+  ComposerPrimitiveTriggerPopoverRoot,
+  useTriggerPopoverContext,
+  useTriggerPopoverContextOptional,
+} from "./TriggerPopoverContext";
+export { ComposerPrimitiveTriggerPopoverPopover } from "./TriggerPopoverPopover";
+export {
+  ComposerPrimitiveTriggerPopoverCategories,
+  ComposerPrimitiveTriggerPopoverCategoryItem,
+} from "./TriggerPopoverCategories";
+export {
+  ComposerPrimitiveTriggerPopoverItems,
+  ComposerPrimitiveTriggerPopoverItem,
+} from "./TriggerPopoverItems";
+export { ComposerPrimitiveTriggerPopoverBack } from "./TriggerPopoverBack";
+export type { OnSelectBehavior } from "./TriggerPopoverResource";

package/src/primitives/composer.ts

@@ -23,3 +23,19 @@ export { ComposerPrimitiveMentionItem as Unstable_MentionItem } from "./composer
 export { ComposerPrimitiveMentionBack as Unstable_MentionBack } from "./composer/mention";
 export { useMentionContext as unstable_useMentionContext } from "./composer/mention";
 export { useMentionContextOptional as unstable_useMentionContextOptional } from "./composer/mention";
+
+// --- Generic Trigger Popover primitives (unstable) ---
+export { ComposerPrimitiveTriggerPopoverRoot as Unstable_TriggerPopoverRoot } from "./composer/trigger";
+export { ComposerPrimitiveTriggerPopoverPopover as Unstable_TriggerPopoverPopover } from "./composer/trigger";
+export { ComposerPrimitiveTriggerPopoverCategories as Unstable_TriggerPopoverCategories } from "./composer/trigger";
+export { ComposerPrimitiveTriggerPopoverCategoryItem as Unstable_TriggerPopoverCategoryItem } from "./composer/trigger";
+export { ComposerPrimitiveTriggerPopoverItems as Unstable_TriggerPopoverItems } from "./composer/trigger";
+export { ComposerPrimitiveTriggerPopoverItem as Unstable_TriggerPopoverItem } from "./composer/trigger";
+export { ComposerPrimitiveTriggerPopoverBack as Unstable_TriggerPopoverBack } from "./composer/trigger";
+export { useTriggerPopoverContext as unstable_useTriggerPopoverContext } from "./composer/trigger";
+export { useTriggerPopoverContextOptional as unstable_useTriggerPopoverContextOptional } from "./composer/trigger";
+
+// --- Slash Command primitives (unstable) ---
+// SlashCommandRoot is the only slash-specific primitive; UI primitives
+// (Popover, Items, Categories, Back) are the shared TriggerPopover* set above.
+export { ComposerPrimitiveSlashCommandRoot as Unstable_SlashCommandRoot } from "./composer/slash-command";

package/src/primitives/message/MessageRoot.tsx

@@ -79,9 +79,20 @@ export namespace MessagePrimitiveRoot {
   export type Element = ComponentRef<typeof Primitive.div>;
   /**
    * Props for the MessagePrimitive.Root component.
-   * Accepts all standard div element props.
+   * Accepts all standard div element props plus optional viewport slack tuning.
    */
-  export type Props = ComponentPropsWithoutRef<typeof Primitive.div>;
+  export type Props = ComponentPropsWithoutRef<typeof Primitive.div> & {
+    /**
+     * Threshold at which the user message height clamps to the offset.
+     * @default "10em"
+     */
+    fillClampThreshold?: string | undefined;
+    /**
+     * Offset used when clamping large user messages.
+     * @default "6em"
+     */
+    fillClampOffset?: string | undefined;
+  };
 }
 
 /**
@@ -108,7 +119,7 @@ export namespace MessagePrimitiveRoot {
 export const MessagePrimitiveRoot = forwardRef<
   MessagePrimitiveRoot.Element,
   MessagePrimitiveRoot.Props
->((props, forwardRef) => {
+>(({ fillClampThreshold, fillClampOffset, ...props }, forwardRef) => {
   const isHoveringRef = useIsHoveringRef();
   const anchorUserMessageRef = useMessageViewportRef();
   const ref = useComposedRefs<HTMLDivElement>(
@@ -119,7 +130,10 @@ export const MessagePrimitiveRoot = forwardRef<
   const messageId = useAuiState((s) => s.message.id);
 
   return (
-    <ThreadPrimitiveViewportSlack>
+    <ThreadPrimitiveViewportSlack
+      fillClampThreshold={fillClampThreshold}
+      fillClampOffset={fillClampOffset}
+    >
       <Primitive.div {...props} ref={ref} data-message-id={messageId} />
     </ThreadPrimitiveViewportSlack>
   );

package/src/primitives/thread/ThreadViewportSlack.tsx

@@ -36,9 +36,9 @@ const parseCssLength = (value: string, element: HTMLElement): number => {
 
 export type ThreadViewportSlackProps = {
   /** Threshold at which the user message height clamps to the offset */
-  fillClampThreshold?: string;
+  fillClampThreshold?: string | undefined;
   /** Offset used when clamping large user messages */
-  fillClampOffset?: string;
+  fillClampOffset?: string | undefined;
   children: ReactNode;
 };
 

package/src/tests/BaseComposerRuntimeCore.test.ts

@@ -6,12 +6,14 @@ import type {
   AppendMessage,
   CreateAttachment,
   PendingAttachment,
+  SendOptions,
 } from "@assistant-ui/core";
 
 class TestComposerCore extends BaseComposerRuntimeCore {
   private _attachmentAdapter: AttachmentAdapter | undefined;
   private _dictationAdapter: DictationAdapter | undefined;
   public sentMessages: Array<Omit<AppendMessage, "parentId" | "sourceId">> = [];
+  public sentOptions: Array<SendOptions | undefined> = [];
   public cancelCalled = false;
 
   protected getAttachmentAdapter() {
@@ -33,8 +35,12 @@ class TestComposerCore extends BaseComposerRuntimeCore {
     return false;
   }
 
-  protected handleSend(message: Omit<AppendMessage, "parentId" | "sourceId">) {
+  protected handleSend(
+    message: Omit<AppendMessage, "parentId" | "sourceId">,
+    options?: SendOptions,
+  ) {
     this.sentMessages.push(message);
+    this.sentOptions.push(options);
   }
 
   protected handleCancel() {
@@ -421,4 +427,30 @@ describe("BaseComposerRuntimeCore", () => {
       expect(adapter.send).toHaveBeenCalledTimes(1);
     });
   });
+
+  describe("send options", () => {
+    it("send() passes undefined options by default", async () => {
+      composer.setText("hello");
+      await composer.send();
+
+      expect(composer.sentOptions).toHaveLength(1);
+      expect(composer.sentOptions[0]).toBeUndefined();
+    });
+
+    it("send({ startRun: true }) forwards options to handleSend", async () => {
+      composer.setText("hello");
+      await composer.send({ startRun: true });
+
+      expect(composer.sentOptions).toHaveLength(1);
+      expect(composer.sentOptions[0]).toEqual({ startRun: true });
+    });
+
+    it("send({ startRun: false }) forwards options to handleSend", async () => {
+      composer.setText("hello");
+      await composer.send({ startRun: false });
+
+      expect(composer.sentOptions).toHaveLength(1);
+      expect(composer.sentOptions[0]).toEqual({ startRun: false });
+    });
+  });
 });