@assistant-ui/react 0.12.17 → 0.12.20

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

@@ -0,0 +1,25 @@
+export { ComposerPrimitiveRoot as Root } from "./composer/ComposerRoot";
+export { ComposerPrimitiveInput as Input } from "./composer/ComposerInput";
+export { ComposerPrimitiveSend as Send } from "./composer/ComposerSend";
+export { ComposerPrimitiveCancel as Cancel } from "./composer/ComposerCancel";
+export { ComposerPrimitiveAddAttachment as AddAttachment } from "./composer/ComposerAddAttachment";
+export { ComposerPrimitiveAttachments as Attachments } from "./composer/ComposerAttachments";
+export { ComposerPrimitiveAttachmentByIndex as AttachmentByIndex } from "./composer/ComposerAttachments";
+export { ComposerPrimitiveAttachmentDropzone as AttachmentDropzone } from "./composer/ComposerAttachmentDropzone";
+export { ComposerPrimitiveDictate as Dictate } from "./composer/ComposerDictate";
+export { ComposerPrimitiveStopDictation as StopDictation } from "./composer/ComposerStopDictation";
+export { ComposerPrimitiveDictationTranscript as DictationTranscript } from "./composer/ComposerDictationTranscript";
+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/error/ErrorMessage.tsx

@@ -2,7 +2,7 @@
 
 import { Primitive } from "@radix-ui/react-primitive";
 import { type ComponentRef, forwardRef, ComponentPropsWithoutRef } from "react";
-import { useAuiState } from "@assistant-ui/store";
+import { useMessageError } from "@assistant-ui/core/react";
 
 export namespace ErrorPrimitiveMessage {
   export type Element = ComponentRef<typeof Primitive.span>;
@@ -13,12 +13,7 @@ export const ErrorPrimitiveMessage = forwardRef<
   ErrorPrimitiveMessage.Element,
   ErrorPrimitiveMessage.Props
 >(({ children, ...props }, forwardRef) => {
-  const error = useAuiState((s) => {
-    return s.message.status?.type === "incomplete" &&
-      s.message.status.reason === "error"
-      ? s.message.status.error
-      : undefined;
-  });
+  const error = useMessageError();
 
   if (error === undefined) return null;
 

package/src/primitives/error.ts

@@ -0,0 +1,2 @@
+export { ErrorPrimitiveRoot as Root } from "./error/ErrorRoot";
+export { ErrorPrimitiveMessage as Message } from "./error/ErrorMessage";

package/src/primitives/message/MessageError.ts

@@ -1,15 +1,11 @@
 "use client";
 
 import { FC, PropsWithChildren } from "react";
-import { useAuiState } from "@assistant-ui/store";
+import { useMessageError } from "@assistant-ui/core/react";
 
 export const MessagePrimitiveError: FC<PropsWithChildren> = ({ children }) => {
-  const hasError = useAuiState(
-    (s) =>
-      s.message.status?.type === "incomplete" &&
-      s.message.status.reason === "error",
-  );
-  return hasError ? children : null;
+  const error = useMessageError();
+  return error !== undefined ? children : null;
 };
 
 MessagePrimitiveError.displayName = "MessagePrimitive.Error";

package/src/primitives/message/MessageParts.tsx

@@ -31,10 +31,16 @@ export namespace MessagePrimitiveParts {
 /**
  * Renders the parts of a message with web-specific default components.
  */
-export const MessagePrimitiveParts: FC<MessagePrimitiveParts.Props> = ({
-  components,
-  ...rest
-}) => {
+export const MessagePrimitiveParts: FC<MessagePrimitiveParts.Props> = (
+  props,
+) => {
+  if ("children" in props) {
+    return (
+      <MessagePrimitivePartsBase>{props.children}</MessagePrimitivePartsBase>
+    );
+  }
+
+  const { components, ...rest } = props;
   const merged = components
     ? {
         Text: components.Text ?? webDefaultComponents.Text,
@@ -58,6 +64,7 @@ export const MessagePrimitiveParts: FC<MessagePrimitiveParts.Props> = ({
                 messagePartsDefaultComponents.ReasoningGroup,
             }),
         Empty: components.Empty,
+        Quote: components.Quote,
       }
     : webDefaultComponents;
 

package/src/primitives/message/MessagePartsGrouped.tsx

@@ -8,10 +8,8 @@ import {
   useMemo,
 } from "react";
 import { useAuiState, useAui } from "@assistant-ui/store";
-import {
-  PartByIndexProvider,
-  TextMessagePartProvider,
-} from "../../context/providers";
+import { PartByIndexProvider } from "../../context/providers/PartByIndexProvider";
+import { TextMessagePartProvider } from "../../context/providers/TextMessagePartProvider";
 import { MessagePartPrimitiveText } from "../messagePart/MessagePartText";
 import { MessagePartPrimitiveImage } from "../messagePart/MessagePartImage";
 import type {
@@ -26,7 +24,7 @@ import type {
   ToolCallMessagePartProps,
   FileMessagePartComponent,
   ReasoningMessagePartComponent,
-} from "../../types";
+} from "@assistant-ui/core/react";
 import { MessagePartPrimitiveInProgress } from "../messagePart/MessagePartInProgress";
 import type { MessagePartStatus } from "@assistant-ui/core";
 

package/src/primitives/message.ts

@@ -0,0 +1,13 @@
+export { MessagePrimitiveRoot as Root } from "./message/MessageRoot";
+export { MessagePrimitiveParts as Parts } from "./message/MessageParts";
+export { MessagePrimitivePartByIndex as PartByIndex } from "./message/MessageParts";
+export { MessagePrimitiveParts as Content } from "./message/MessageParts";
+export { MessagePrimitiveIf as If } from "./message/MessageIf";
+export { MessagePrimitiveAttachments as Attachments } from "./message/MessageAttachments";
+export { MessagePrimitiveAttachmentByIndex as AttachmentByIndex } from "./message/MessageAttachments";
+export { MessagePrimitiveQuote as Quote } from "@assistant-ui/core/react";
+export { MessagePrimitiveError as Error } from "./message/MessageError";
+export {
+  MessagePrimitiveUnstable_PartsGrouped as Unstable_PartsGrouped,
+  MessagePrimitiveUnstable_PartsGroupedByParentId as Unstable_PartsGroupedByParentId,
+} from "./message/MessagePartsGrouped";

package/src/primitives/messagePart.ts

@@ -0,0 +1,4 @@
+export { MessagePartPrimitiveText as Text } from "./messagePart/MessagePartText";
+export { MessagePartPrimitiveImage as Image } from "./messagePart/MessagePartImage";
+export { MessagePartPrimitiveInProgress as InProgress } from "./messagePart/MessagePartInProgress";
+export { PartPrimitiveMessages as Messages } from "@assistant-ui/core/react";

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,
+);