@assistant-ui/react 0.12.19 → 0.12.21

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

@@ -0,0 +1,52 @@
+"use client";
+
+import { Primitive } from "@radix-ui/react-primitive";
+import {
+  type ComponentRef,
+  type ComponentPropsWithoutRef,
+  forwardRef,
+} from "react";
+import { useMentionContext } from "./ComposerMentionContext";
+
+// =============================================================================
+// MentionPopover — Container that only renders when mention is active
+// =============================================================================
+
+export namespace ComposerPrimitiveMentionPopover {
+  export type Element = ComponentRef<typeof Primitive.div>;
+  export type Props = ComponentPropsWithoutRef<typeof Primitive.div>;
+}
+
+/**
+ * Renders a container for the mention picker popover.
+ * Only renders when a `@` trigger is detected in the composer text.
+ *
+ * @example
+ * ```tsx
+ * <ComposerPrimitive.MentionRoot adapter={mentionAdapter}>
+ *   <ComposerPrimitive.Input />
+ *   <ComposerPrimitive.MentionPopover>
+ *     <ComposerPrimitive.MentionCategories />
+ *   </ComposerPrimitive.MentionPopover>
+ * </ComposerPrimitive.MentionRoot>
+ * ```
+ */
+export const ComposerPrimitiveMentionPopover = forwardRef<
+  ComposerPrimitiveMentionPopover.Element,
+  ComposerPrimitiveMentionPopover.Props
+>((props, forwardedRef) => {
+  const { open } = useMentionContext();
+  if (!open) return null;
+
+  return (
+    <Primitive.div
+      role="listbox"
+      data-state="open"
+      {...props}
+      ref={forwardedRef}
+    />
+  );
+});
+
+ComposerPrimitiveMentionPopover.displayName =
+  "ComposerPrimitive.MentionPopover";

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

@@ -0,0 +1,328 @@
+import {
+  resource,
+  tapState,
+  tapMemo,
+  tapEffectEvent,
+  tapEffect,
+  tapRef,
+} from "@assistant-ui/tap";
+import type {
+  Unstable_MentionAdapter,
+  Unstable_MentionCategory,
+  Unstable_MentionItem,
+  Unstable_DirectiveFormatter,
+} from "@assistant-ui/core";
+import type { AssistantClient } from "@assistant-ui/store";
+import { detectMentionTrigger } from "./detectMentionTrigger";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export type MentionKeyEvent = {
+  readonly key: string;
+  readonly shiftKey: boolean;
+  preventDefault(): void;
+};
+
+export type SelectItemOverride = (item: Unstable_MentionItem) => boolean;
+
+export type MentionResourceOutput = {
+  // State
+  readonly open: boolean;
+  readonly query: string;
+  readonly activeCategoryId: string | null;
+  readonly categories: readonly Unstable_MentionCategory[];
+  readonly items: readonly Unstable_MentionItem[];
+  readonly highlightedIndex: number;
+  readonly isSearchMode: boolean;
+  readonly formatter: Unstable_DirectiveFormatter;
+
+  // Actions
+  selectCategory(categoryId: string): void;
+  goBack(): void;
+  selectItem(item: Unstable_MentionItem): void;
+  close(): void;
+  handleKeyDown(e: MentionKeyEvent): boolean;
+
+  // Internal (for ComposerInput integration)
+  setCursorPosition(pos: number): void;
+  registerSelectItemOverride(fn: SelectItemOverride): () => void;
+};
+
+// =============================================================================
+// Resource
+// =============================================================================
+
+export const MentionResource = resource(
+  ({
+    adapter,
+    text,
+    triggerChar,
+    formatter,
+    aui,
+  }: {
+    adapter: Unstable_MentionAdapter | undefined;
+    text: string;
+    triggerChar: string;
+    formatter: Unstable_DirectiveFormatter;
+    aui: AssistantClient;
+  }): MentionResourceOutput => {
+    // -------------------------------------------------------------------------
+    // Cursor tracking + trigger detection
+    // -------------------------------------------------------------------------
+
+    const [cursorPosition, setCursorPosition] = tapState(text.length);
+
+    const trigger = tapMemo(() => {
+      const pos = Math.min(cursorPosition, text.length);
+      return detectMentionTrigger(text, triggerChar, pos);
+    }, [cursorPosition, text, triggerChar]);
+
+    const open = trigger !== null && adapter !== undefined;
+    const query = trigger?.query ?? "";
+
+    // -------------------------------------------------------------------------
+    // Category navigation
+    // -------------------------------------------------------------------------
+
+    const [activeCategoryId, setActiveCategoryId] = tapState<string | null>(
+      null,
+    );
+
+    // Reset when popover closes
+    tapEffect(() => {
+      if (!open) setActiveCategoryId(null);
+    }, [open]);
+
+    const categories = tapMemo<readonly Unstable_MentionCategory[]>(() => {
+      if (!open || !adapter) return [];
+      return adapter.categories();
+    }, [open, adapter]);
+
+    const effectiveActiveCategoryId = open ? activeCategoryId : null;
+
+    // -------------------------------------------------------------------------
+    // Items + search
+    // -------------------------------------------------------------------------
+
+    const allItems = tapMemo<readonly Unstable_MentionItem[]>(() => {
+      if (!effectiveActiveCategoryId || !adapter) return [];
+      return adapter.categoryItems(effectiveActiveCategoryId);
+    }, [effectiveActiveCategoryId, adapter]);
+
+    const searchResults = tapMemo<
+      readonly Unstable_MentionItem[] | null
+    >(() => {
+      if (!open || !adapter || !query || effectiveActiveCategoryId) return null;
+      if (adapter.search) return adapter.search(query);
+
+      const cats = adapter.categories();
+      const all: Unstable_MentionItem[] = [];
+      const lower = query.toLowerCase();
+      for (const cat of cats) {
+        for (const item of adapter.categoryItems(cat.id)) {
+          if (
+            item.id.toLowerCase().includes(lower) ||
+            item.label.toLowerCase().includes(lower) ||
+            item.description?.toLowerCase().includes(lower)
+          ) {
+            all.push(item);
+          }
+        }
+      }
+      return all;
+    }, [open, adapter, query, effectiveActiveCategoryId]);
+
+    const isSearchMode = searchResults !== null;
+
+    // -------------------------------------------------------------------------
+    // Filtering
+    // -------------------------------------------------------------------------
+
+    const filteredCategories = tapMemo(() => {
+      if (isSearchMode) return [];
+      if (!query) return categories;
+      const lower = query.toLowerCase();
+      return categories.filter((cat) =>
+        cat.label.toLowerCase().includes(lower),
+      );
+    }, [categories, query, isSearchMode]);
+
+    const filteredItems = tapMemo(() => {
+      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),
+      );
+    }, [allItems, query, isSearchMode, searchResults]);
+
+    // -------------------------------------------------------------------------
+    // Keyboard navigation
+    // -------------------------------------------------------------------------
+
+    const [highlightedIndex, setHighlightedIndex] = tapState(0);
+
+    const navigableList = tapMemo(() => {
+      if (isSearchMode) return searchResults ?? [];
+      if (effectiveActiveCategoryId) return filteredItems;
+      return filteredCategories;
+    }, [
+      isSearchMode,
+      searchResults,
+      effectiveActiveCategoryId,
+      filteredItems,
+      filteredCategories,
+    ]);
+
+    // Reset highlight when list changes
+    // biome-ignore lint/correctness/useExhaustiveDependencies: intentional reset on list change
+    tapEffect(() => {
+      setHighlightedIndex(0);
+    }, [navigableList]);
+
+    // -------------------------------------------------------------------------
+    // Lexical select-item override
+    // -------------------------------------------------------------------------
+
+    const selectItemOverrideRef = tapRef<SelectItemOverride | null>(null);
+
+    const registerSelectItemOverride = tapEffectEvent(
+      (fn: SelectItemOverride) => {
+        selectItemOverrideRef.current = fn;
+        return () => {
+          if (selectItemOverrideRef.current === fn) {
+            selectItemOverrideRef.current = null;
+          }
+        };
+      },
+    );
+
+    // -------------------------------------------------------------------------
+    // Actions (stable via tapEffectEvent)
+    // -------------------------------------------------------------------------
+
+    const selectCategory = tapEffectEvent((categoryId: string) => {
+      setActiveCategoryId(categoryId);
+      setHighlightedIndex(0);
+    });
+
+    const goBack = tapEffectEvent(() => {
+      setActiveCategoryId(null);
+      setHighlightedIndex(0);
+    });
+
+    const selectItem = tapEffectEvent((item: Unstable_MentionItem) => {
+      if (!trigger) return;
+
+      // Try the Lexical override first
+      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}`);
+
+      aui.composer().setText(newText);
+      setActiveCategoryId(null);
+      setHighlightedIndex(0);
+    });
+
+    const close = tapEffectEvent(() => {
+      setActiveCategoryId(null);
+      setHighlightedIndex(0);
+      // Move cursor before the trigger so trigger detection deactivates
+      if (trigger) {
+        setCursorPosition(trigger.offset);
+      }
+    });
+
+    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);
+          }
+          return true;
+        }
+        case "Escape": {
+          e.preventDefault();
+          close();
+          return true;
+        }
+        case "Backspace": {
+          if (effectiveActiveCategoryId && query === "") {
+            e.preventDefault();
+            goBack();
+            return true;
+          }
+          return false;
+        }
+        default:
+          return false;
+      }
+    });
+
+    // -------------------------------------------------------------------------
+    // Output
+    // -------------------------------------------------------------------------
+
+    return {
+      open,
+      query,
+      activeCategoryId: effectiveActiveCategoryId,
+      categories: filteredCategories,
+      items: filteredItems,
+      highlightedIndex,
+      isSearchMode,
+      formatter,
+      selectCategory,
+      goBack,
+      selectItem,
+      close,
+      handleKeyDown,
+      setCursorPosition,
+      registerSelectItemOverride,
+    };
+  },
+);

package/src/primitives/composer/mention/detectMentionTrigger.test.ts

@@ -0,0 +1,78 @@
+import { describe, it, expect } from "vitest";
+import { detectMentionTrigger } from "./detectMentionTrigger";
+
+describe("detectMentionTrigger", () => {
+  it("detects @query at cursor position", () => {
+    expect(detectMentionTrigger("hello @wea", "@", 10)).toEqual({
+      query: "wea",
+      offset: 6,
+    });
+  });
+
+  it("returns null when cursor is before the trigger", () => {
+    expect(detectMentionTrigger("hello @weather", "@", 5)).toBeNull();
+  });
+
+  it("returns null when no trigger character", () => {
+    expect(detectMentionTrigger("hello world", "@", 11)).toBeNull();
+  });
+
+  it("requires whitespace or start before trigger", () => {
+    expect(detectMentionTrigger("email@test", "@", 10)).toBeNull();
+  });
+
+  it("trigger at start of text", () => {
+    expect(detectMentionTrigger("@foo", "@", 4)).toEqual({
+      query: "foo",
+      offset: 0,
+    });
+  });
+
+  it("stops at whitespace in query", () => {
+    // "@foo bar" — space terminates the mention
+    expect(detectMentionTrigger("@foo bar", "@", 8)).toBeNull();
+  });
+
+  it("stops at newline", () => {
+    expect(detectMentionTrigger("@foo\nbar", "@", 8)).toBeNull();
+  });
+
+  it("stops at tab", () => {
+    expect(detectMentionTrigger("@foo\tbar", "@", 8)).toBeNull();
+  });
+
+  it("treats tab before trigger as valid boundary", () => {
+    expect(detectMentionTrigger("hello\t@foo", "@", 10)).toEqual({
+      query: "foo",
+      offset: 6,
+    });
+  });
+
+  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({
+      query: "new",
+      offset: 16,
+    });
+  });
+
+  it("ignores trigger after cursor", () => {
+    // Cursor at position 5, trigger at position 10
+    expect(detectMentionTrigger("hello text @foo", "@", 5)).toBeNull();
+  });
+
+  it("works with multi-char trigger", () => {
+    expect(detectMentionTrigger("hello @@foo", "@@", 11)).toEqual({
+      query: "foo",
+      offset: 6,
+    });
+  });
+
+  it("empty query when cursor is right after trigger", () => {
+    expect(detectMentionTrigger("hello @", "@", 7)).toEqual({
+      query: "",
+      offset: 6,
+    });
+  });
+});

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

@@ -0,0 +1,37 @@
+const WHITESPACE_RE = /\s/;
+
+/**
+ * Detect a mention trigger in text relative to the cursor position.
+ *
+ * @internal Exported for testing and for the MentionResource.
+ */
+export function detectMentionTrigger(
+  text: string,
+  triggerChar: string,
+  cursorPosition: number,
+): {
+  query: string;
+  offset: number;
+} | null {
+  // Only consider text up to the cursor
+  const textUpToCursor = text.slice(0, cursorPosition);
+
+  // Search backwards from cursor for the trigger character.
+  // Stop at any whitespace during scan — trigger must be contiguous with cursor.
+  for (let i = textUpToCursor.length - 1; i >= 0; i--) {
+    const char = textUpToCursor[i]!;
+
+    if (WHITESPACE_RE.test(char)) return null;
+
+    if (textUpToCursor.startsWith(triggerChar, i)) {
+      // Trigger must be preceded by whitespace or be at start of text
+      if (i > 0 && !WHITESPACE_RE.test(textUpToCursor[i - 1]!)) continue;
+
+      const query = textUpToCursor.slice(i + triggerChar.length);
+
+      return { query, offset: i };
+    }
+  }
+
+  return null;
+}

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

@@ -0,0 +1,16 @@
+export {
+  ComposerPrimitiveMentionRoot,
+  useMentionContext,
+  useMentionContextOptional,
+  useMentionInternalContext,
+} from "./ComposerMentionContext";
+export { ComposerPrimitiveMentionPopover } from "./ComposerMentionPopover";
+export {
+  ComposerPrimitiveMentionCategories,
+  ComposerPrimitiveMentionCategoryItem,
+} from "./ComposerMentionCategories";
+export {
+  ComposerPrimitiveMentionItems,
+  ComposerPrimitiveMentionItem,
+} from "./ComposerMentionItems";
+export { ComposerPrimitiveMentionBack } from "./ComposerMentionBack";

package/src/primitives/composer.ts

@@ -13,3 +13,13 @@ export { ComposerPrimitiveIf as If } from "./composer/ComposerIf";
 export { ComposerPrimitiveQuote as Quote } from "./composer/ComposerQuote";
 export { ComposerPrimitiveQuoteText as QuoteText } from "./composer/ComposerQuote";
 export { ComposerPrimitiveQuoteDismiss as QuoteDismiss } from "./composer/ComposerQuote";
+export { ComposerPrimitiveQueue as Queue } from "./composer/ComposerQueue";
+export { ComposerPrimitiveMentionRoot as Unstable_MentionRoot } from "./composer/mention";
+export { ComposerPrimitiveMentionPopover as Unstable_MentionPopover } from "./composer/mention";
+export { ComposerPrimitiveMentionCategories as Unstable_MentionCategories } from "./composer/mention";
+export { ComposerPrimitiveMentionCategoryItem as Unstable_MentionCategoryItem } from "./composer/mention";
+export { ComposerPrimitiveMentionItems as Unstable_MentionItems } from "./composer/mention";
+export { ComposerPrimitiveMentionItem as Unstable_MentionItem } from "./composer/mention";
+export { ComposerPrimitiveMentionBack as Unstable_MentionBack } from "./composer/mention";
+export { useMentionContext as unstable_useMentionContext } from "./composer/mention";
+export { useMentionContextOptional as unstable_useMentionContextOptional } from "./composer/mention";

package/src/primitives/queueItem/QueueItemRemove.ts

@@ -0,0 +1,37 @@
+"use client";
+
+import {
+  ActionButtonElement,
+  ActionButtonProps,
+  createActionButton,
+} from "../../utils/createActionButton";
+import { useAui } from "@assistant-ui/store";
+import { useCallback } from "react";
+
+const useQueueItemRemove = () => {
+  const aui = useAui();
+
+  const callback = useCallback(() => {
+    aui.queueItem().remove();
+  }, [aui]);
+
+  return callback;
+};
+
+export namespace QueueItemPrimitiveRemove {
+  export type Element = ActionButtonElement;
+  export type Props = ActionButtonProps<typeof useQueueItemRemove>;
+}
+
+/**
+ * A button that removes this item from the queue.
+ *
+ * @example
+ * ```tsx
+ * <QueueItemPrimitive.Remove>×</QueueItemPrimitive.Remove>
+ * ```
+ */
+export const QueueItemPrimitiveRemove = createActionButton(
+  "QueueItemPrimitive.Remove",
+  useQueueItemRemove,
+);

package/src/primitives/queueItem/QueueItemSteer.ts

@@ -0,0 +1,37 @@
+"use client";
+
+import {
+  ActionButtonElement,
+  ActionButtonProps,
+  createActionButton,
+} from "../../utils/createActionButton";
+import { useAui } from "@assistant-ui/store";
+import { useCallback } from "react";
+
+const useQueueItemSteer = () => {
+  const aui = useAui();
+
+  const callback = useCallback(() => {
+    aui.queueItem().steer();
+  }, [aui]);
+
+  return callback;
+};
+
+export namespace QueueItemPrimitiveSteer {
+  export type Element = ActionButtonElement;
+  export type Props = ActionButtonProps<typeof useQueueItemSteer>;
+}
+
+/**
+ * A button that steers the current run to process this queue item immediately.
+ *
+ * @example
+ * ```tsx
+ * <QueueItemPrimitive.Steer>Run Now</QueueItemPrimitive.Steer>
+ * ```
+ */
+export const QueueItemPrimitiveSteer = createActionButton(
+  "QueueItemPrimitive.Steer",
+  useQueueItemSteer,
+);

package/src/primitives/queueItem/QueueItemText.tsx

@@ -0,0 +1,37 @@
+"use client";
+
+import { Primitive } from "@radix-ui/react-primitive";
+import {
+  type ComponentRef,
+  type ComponentPropsWithoutRef,
+  forwardRef,
+} from "react";
+import { useAuiState } from "@assistant-ui/store";
+
+export namespace QueueItemPrimitiveText {
+  export type Element = ComponentRef<typeof Primitive.span>;
+  export type Props = ComponentPropsWithoutRef<typeof Primitive.span>;
+}
+
+/**
+ * Renders the prompt text of a queue item.
+ *
+ * @example
+ * ```tsx
+ * <QueueItemPrimitive.Text />
+ * ```
+ */
+export const QueueItemPrimitiveText = forwardRef<
+  QueueItemPrimitiveText.Element,
+  QueueItemPrimitiveText.Props
+>((props, ref) => {
+  const prompt = useAuiState((s) => s.queueItem.prompt);
+
+  return (
+    <Primitive.span {...props} ref={ref}>
+      {props.children ?? prompt}
+    </Primitive.span>
+  );
+});
+
+QueueItemPrimitiveText.displayName = "QueueItemPrimitive.Text";

package/src/primitives/queueItem.ts

@@ -0,0 +1,3 @@
+export { QueueItemPrimitiveText as Text } from "./queueItem/QueueItemText";
+export { QueueItemPrimitiveSteer as Steer } from "./queueItem/QueueItemSteer";
+export { QueueItemPrimitiveRemove as Remove } from "./queueItem/QueueItemRemove";

package/src/tests/BaseComposerRuntimeCore.test.ts

@@ -204,7 +204,9 @@ describe("BaseComposerRuntimeCore", () => {
     };
     composer.setAttachmentAdapter(adapter);
 
-    await composer.addAttachment(new File(["data"], "test.txt"));
+    await composer.addAttachment(
+      new File(["data"], "test.txt", { type: "text/plain" }),
+    );
 
     expect(composer.attachments).toHaveLength(1);
     expect(composer.attachments[0]!.id).toBe("att-1");