@assistant-ui/react 0.12.17 → 0.12.20

package/src/primitives/{chainOfThought/index.ts → chainOfThought.ts}

@@ -1,14 +1,14 @@
 export {
   ChainOfThoughtPrimitiveRoot as Root,
   type ChainOfThoughtPrimitiveRoot as RootPrimitive,
-} from "./ChainOfThoughtRoot";
+} from "./chainOfThought/ChainOfThoughtRoot";
 
 export {
   ChainOfThoughtPrimitiveAccordionTrigger as AccordionTrigger,
   type ChainOfThoughtPrimitiveAccordionTrigger as AccordionTriggerPrimitive,
-} from "./ChainOfThoughtAccordionTrigger";
+} from "./chainOfThought/ChainOfThoughtAccordionTrigger";
 
 export {
   ChainOfThoughtPrimitiveParts as Parts,
   type ChainOfThoughtPrimitiveParts as PartsPrimitive,
-} from "./ChainOfThoughtParts";
+} from "./chainOfThought/ChainOfThoughtParts";

package/src/primitives/composer/ComposerDictate.ts

@@ -1,28 +1,16 @@
 "use client";
 
-import { useCallback } from "react";
-import { useAui, useAuiState } from "@assistant-ui/store";
 import type {
   ActionButtonElement,
   ActionButtonProps,
 } from "../../utils/createActionButton";
 import { createActionButton } from "../../utils/createActionButton";
+import { useComposerDictate as useComposerDictateBehavior } from "@assistant-ui/core/react";
 
 const useComposerDictate = () => {
-  const aui = useAui();
-  const disabled = useAuiState(
-    (s) =>
-      s.composer.dictation != null ||
-      !s.thread.capabilities.dictation ||
-      !s.composer.isEditing,
-  );
-
-  const callback = useCallback(() => {
-    aui.composer().startDictation();
-  }, [aui]);
-
+  const { disabled, startDictation } = useComposerDictateBehavior();
   if (disabled) return null;
-  return callback;
+  return startDictation;
 };
 
 export namespace ComposerPrimitiveDictate {

package/src/primitives/composer/ComposerInput.tsx

@@ -18,6 +18,10 @@ import { useEscapeKeydown } from "@radix-ui/react-use-escape-keydown";
 import { useOnScrollToBottom } from "../../utils/hooks/useOnScrollToBottom";
 import { useAuiState, useAui } from "@assistant-ui/store";
 import { flushResourcesSync } from "@assistant-ui/tap";
+import {
+  useMentionContextOptional,
+  useMentionInternalContext,
+} from "./mention/ComposerMentionContext";
 
 export namespace ComposerPrimitiveInput {
   export type Element = HTMLTextAreaElement;
@@ -118,6 +122,7 @@ export const ComposerPrimitiveInput = forwardRef<
       onChange,
       onKeyDown,
       onPaste,
+      onSelect,
       submitOnEnter,
       submitMode,
       cancelOnEscape = true,
@@ -130,6 +135,8 @@ export const ComposerPrimitiveInput = forwardRef<
     forwardedRef,
   ) => {
     const aui = useAui();
+    const mentionContext = useMentionContextOptional();
+    const mentionInternalContext = useMentionInternalContext();
 
     const effectiveSubmitMode =
       submitMode ?? (submitOnEnter === false ? "none" : "enter");
@@ -149,11 +156,17 @@ export const ComposerPrimitiveInput = forwardRef<
     const ref = useComposedRefs(forwardedRef, textareaRef);
 
     useEscapeKeydown((e) => {
-      if (!cancelOnEscape) return;
-
       // Only handle ESC if it originated from within this input
       if (!textareaRef.current?.contains(e.target as Node)) return;
 
+      // Let mention popover handle Escape first
+      if (mentionContext?.open) {
+        mentionContext.handleKeyDown(e);
+        return;
+      }
+
+      if (!cancelOnEscape) return;
+
       const composer = aui.composer();
       if (composer.getState().canCancel) {
         composer.cancel();
@@ -167,9 +180,31 @@ export const ComposerPrimitiveInput = forwardRef<
       // ignore IME composition events
       if (e.nativeEvent.isComposing) return;
 
-      if (e.key === "Enter" && !e.shiftKey) {
-        const isRunning = aui.thread().getState().isRunning;
-        if (isRunning) return;
+      // Let the mention popover handle keyboard events first
+      if (mentionContext?.handleKeyDown(e)) return;
+
+      if (e.key === "Enter") {
+        const threadState = aui.thread().getState();
+        const hasQueue = threadState.capabilities.queue;
+
+        // Steer hotkey: Cmd/Ctrl+Shift+Enter (respects submitMode="none" and isEmpty)
+        if (
+          e.shiftKey &&
+          (e.ctrlKey || e.metaKey) &&
+          hasQueue &&
+          effectiveSubmitMode !== "none" &&
+          !aui.composer().getState().isEmpty
+        ) {
+          e.preventDefault();
+          aui.composer().send({ steer: true });
+          return;
+        }
+
+        // Regular newline: Shift+Enter
+        if (e.shiftKey) return;
+
+        // Block submission when running unless queue is supported
+        if (threadState.isRunning && !hasQueue) return;
 
         let shouldSubmit = false;
         if (effectiveSubmitMode === "ctrlEnter") {
@@ -254,8 +289,17 @@ export const ComposerPrimitiveInput = forwardRef<
           flushResourcesSync(() => {
             aui.composer().setText(e.target.value);
           });
+          mentionInternalContext?.setCursorPosition(
+            e.target.selectionStart ?? e.target.value.length,
+          );
         })}
         onKeyDown={composeEventHandlers(onKeyDown, handleKeyPress)}
+        onSelect={composeEventHandlers(onSelect, (e) => {
+          const target = e.target as HTMLTextAreaElement;
+          mentionInternalContext?.setCursorPosition(
+            target.selectionStart ?? target.value.length,
+          );
+        })}
         onPaste={composeEventHandlers(onPaste, handlePaste)}
       />
     );

package/src/primitives/composer/ComposerQueue.tsx

@@ -0,0 +1,3 @@
+"use client";
+
+export { ComposerPrimitiveQueue } from "@assistant-ui/core/react";

package/src/primitives/composer/ComposerSend.ts

@@ -1,5 +1,6 @@
 "use client";
 
+import { useCallback } from "react";
 import {
   ActionButtonElement,
   ActionButtonProps,
@@ -9,8 +10,9 @@ import { useComposerSend as useComposerSendBehavior } from "@assistant-ui/core/r
 
 export const useComposerSend = () => {
   const { disabled, send } = useComposerSendBehavior();
+  const callback = useCallback(() => send(), [send]);
   if (disabled) return null;
-  return send;
+  return callback;
 };
 
 export namespace ComposerPrimitiveSend {

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

@@ -0,0 +1,55 @@
+"use client";
+
+import { Primitive } from "@radix-ui/react-primitive";
+import {
+  type ComponentRef,
+  type ComponentPropsWithoutRef,
+  forwardRef,
+  useCallback,
+} from "react";
+import { composeEventHandlers } from "@radix-ui/primitive";
+import { useMentionContext } from "./ComposerMentionContext";
+
+// =============================================================================
+// MentionBack — Button to navigate back from items to categories
+// =============================================================================
+
+export namespace ComposerPrimitiveMentionBack {
+  export type Element = ComponentRef<typeof Primitive.button>;
+  export type Props = ComponentPropsWithoutRef<typeof Primitive.button>;
+}
+
+/**
+ * A button that navigates back from category items to the category list.
+ * Only renders when a category is active (drill-down view).
+ *
+ * @example
+ * ```tsx
+ * <ComposerPrimitive.MentionBack>
+ *   &larr; Back
+ * </ComposerPrimitive.MentionBack>
+ * ```
+ */
+export const ComposerPrimitiveMentionBack = forwardRef<
+  ComposerPrimitiveMentionBack.Element,
+  ComposerPrimitiveMentionBack.Props
+>(({ onClick, ...props }, forwardedRef) => {
+  const { activeCategoryId, isSearchMode, goBack } = useMentionContext();
+
+  const handleClick = useCallback(() => {
+    goBack();
+  }, [goBack]);
+
+  if (!activeCategoryId || isSearchMode) return null;
+
+  return (
+    <Primitive.button
+      type="button"
+      {...props}
+      ref={forwardedRef}
+      onClick={composeEventHandlers(onClick, handleClick)}
+    />
+  );
+});
+
+ComposerPrimitiveMentionBack.displayName = "ComposerPrimitive.MentionBack";

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

@@ -0,0 +1,104 @@
+"use client";
+
+import { Primitive } from "@radix-ui/react-primitive";
+import {
+  type ComponentRef,
+  type ComponentPropsWithoutRef,
+  type ReactNode,
+  forwardRef,
+  useCallback,
+} from "react";
+import { composeEventHandlers } from "@radix-ui/primitive";
+import { useMentionContext } from "./ComposerMentionContext";
+import type { Unstable_MentionCategory } from "@assistant-ui/core";
+
+// =============================================================================
+// MentionCategories — Renders the list of categories
+// =============================================================================
+
+export namespace ComposerPrimitiveMentionCategories {
+  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;
+  };
+}
+
+export const ComposerPrimitiveMentionCategories = forwardRef<
+  ComposerPrimitiveMentionCategories.Element,
+  ComposerPrimitiveMentionCategories.Props
+>(({ children, ...props }, forwardedRef) => {
+  const { categories, activeCategoryId, isSearchMode } = useMentionContext();
+
+  if (activeCategoryId || isSearchMode) return null;
+
+  return (
+    <Primitive.div role="group" {...props} ref={forwardedRef}>
+      {children(categories)}
+    </Primitive.div>
+  );
+});
+
+ComposerPrimitiveMentionCategories.displayName =
+  "ComposerPrimitive.MentionCategories";
+
+// =============================================================================
+// MentionCategoryItem — A single category row (clickable to drill-down)
+// =============================================================================
+
+export namespace ComposerPrimitiveMentionCategoryItem {
+  export type Element = ComponentRef<typeof Primitive.button>;
+  export type Props = ComponentPropsWithoutRef<typeof Primitive.button> & {
+    categoryId: string;
+  };
+}
+
+/**
+ * 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
+>(({ categoryId, onClick, ...props }, forwardedRef) => {
+  const {
+    selectCategory,
+    categories,
+    highlightedIndex,
+    activeCategoryId,
+    isSearchMode,
+  } = useMentionContext();
+
+  const handleClick = useCallback(() => {
+    selectCategory(categoryId);
+  }, [selectCategory, categoryId]);
+
+  // Derive highlighted state from context — no manual wiring needed
+  const isHighlighted =
+    !activeCategoryId &&
+    !isSearchMode &&
+    categories.findIndex((c) => c.id === categoryId) === highlightedIndex;
+
+  return (
+    <Primitive.button
+      type="button"
+      role="option"
+      aria-selected={isHighlighted}
+      data-highlighted={isHighlighted ? "" : undefined}
+      {...props}
+      ref={forwardedRef}
+      onClick={composeEventHandlers(onClick, handleClick)}
+    />
+  );
+});
+
+ComposerPrimitiveMentionCategoryItem.displayName =
+  "ComposerPrimitive.MentionCategoryItem";

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

@@ -0,0 +1,141 @@
+"use client";
+
+import {
+  createContext,
+  useContext,
+  useState,
+  useCallback,
+  useMemo,
+  useEffect,
+  type ReactNode,
+  type FC,
+} from "react";
+import { useResource } from "@assistant-ui/tap/react";
+import { useAui, useAuiState } from "@assistant-ui/store";
+import type {
+  Unstable_MentionAdapter,
+  Unstable_DirectiveFormatter,
+} from "@assistant-ui/core";
+import { unstable_defaultDirectiveFormatter } from "@assistant-ui/core";
+import {
+  MentionResource,
+  type MentionResourceOutput,
+  type SelectItemOverride,
+} from "./MentionResource";
+
+// =============================================================================
+// Context — public (popover components read state + actions from here)
+// =============================================================================
+
+const MentionContext = createContext<MentionResourceOutput | null>(null);
+
+export const useMentionContext = () => {
+  const ctx = useContext(MentionContext);
+  if (!ctx)
+    throw new Error(
+      "useMentionContext must be used within ComposerPrimitive.MentionRoot",
+    );
+  return ctx;
+};
+
+export const useMentionContextOptional = () => {
+  return useContext(MentionContext);
+};
+
+// =============================================================================
+// Internal context — ComposerInput → MentionRoot communication
+// =============================================================================
+
+type MentionInternalContextValue = {
+  setCursorPosition(pos: number): void;
+  registerSelectItemOverride(fn: SelectItemOverride): () => void;
+};
+
+const MentionInternalContext =
+  createContext<MentionInternalContextValue | null>(null);
+
+export const useMentionInternalContext = () => {
+  return useContext(MentionInternalContext);
+};
+
+// =============================================================================
+// Provider Component
+// =============================================================================
+
+export namespace ComposerPrimitiveMentionRoot {
+  export type Props = {
+    children: ReactNode;
+    adapter?: Unstable_MentionAdapter | undefined;
+    /** Character(s) that trigger the mention popover. @default "@" */
+    trigger?: string | undefined;
+    /** Custom formatter for serializing/parsing mention directives. */
+    formatter?: Unstable_DirectiveFormatter | undefined;
+  };
+}
+
+export const ComposerPrimitiveMentionRoot: FC<
+  ComposerPrimitiveMentionRoot.Props
+> = ({
+  children,
+  adapter: adapterProp,
+  trigger: triggerChar = "@",
+  formatter: formatterProp,
+}) => {
+  const aui = useAui();
+  const text = useAuiState((s) => s.composer.text);
+  const formatter = formatterProp ?? unstable_defaultDirectiveFormatter;
+
+  // ---------------------------------------------------------------------------
+  // Runtime adapter (subscribe to state changes instead of useAuiState to avoid
+  // infinite loop — getModelContext() returns a new object on every call)
+  // ---------------------------------------------------------------------------
+
+  const getRuntimeAdapter = useCallback(() => {
+    try {
+      const runtime = aui.composer().__internal_getRuntime?.();
+      return (runtime as any)?._core?.getState()?.getMentionAdapter?.();
+    } catch {
+      return undefined;
+    }
+  }, [aui]);
+  const [runtimeAdapter, setRuntimeAdapter] = useState(getRuntimeAdapter);
+  useEffect(() => {
+    return aui.subscribe(() => {
+      setRuntimeAdapter((prev: unknown) => {
+        const next = getRuntimeAdapter();
+        return prev === next ? prev : next;
+      });
+    });
+  }, [aui, getRuntimeAdapter]);
+  const adapter = adapterProp ?? runtimeAdapter;
+
+  // ---------------------------------------------------------------------------
+  // Mention resource (all state + logic managed via tap primitives)
+  // ---------------------------------------------------------------------------
+
+  const mention = useResource(
+    MentionResource({ adapter, text, triggerChar, formatter, aui }),
+  );
+
+  // ---------------------------------------------------------------------------
+  // Internal context (stable — methods come from tapEffectEvent)
+  // ---------------------------------------------------------------------------
+
+  const internalContextValue = useMemo<MentionInternalContextValue>(
+    () => ({
+      setCursorPosition: mention.setCursorPosition,
+      registerSelectItemOverride: mention.registerSelectItemOverride,
+    }),
+    [mention.setCursorPosition, mention.registerSelectItemOverride],
+  );
+
+  return (
+    <MentionContext.Provider value={mention}>
+      <MentionInternalContext.Provider value={internalContextValue}>
+        {children}
+      </MentionInternalContext.Provider>
+    </MentionContext.Provider>
+  );
+};
+
+ComposerPrimitiveMentionRoot.displayName = "ComposerPrimitive.MentionRoot";

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

@@ -0,0 +1,104 @@
+"use client";
+
+import { Primitive } from "@radix-ui/react-primitive";
+import {
+  type ComponentRef,
+  type ComponentPropsWithoutRef,
+  type ReactNode,
+  forwardRef,
+  useCallback,
+} from "react";
+import { composeEventHandlers } from "@radix-ui/primitive";
+import { useMentionContext } from "./ComposerMentionContext";
+import type { Unstable_MentionItem } from "@assistant-ui/core";
+
+// =============================================================================
+// MentionItems — Renders the list of items within a category
+// =============================================================================
+
+export namespace ComposerPrimitiveMentionItems {
+  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;
+  };
+}
+
+export const ComposerPrimitiveMentionItems = forwardRef<
+  ComposerPrimitiveMentionItems.Element,
+  ComposerPrimitiveMentionItems.Props
+>(({ children, ...props }, forwardedRef) => {
+  const { items, activeCategoryId, isSearchMode } = useMentionContext();
+
+  if (!activeCategoryId && !isSearchMode) return null;
+
+  return (
+    <Primitive.div role="group" {...props} ref={forwardedRef}>
+      {children(items)}
+    </Primitive.div>
+  );
+});
+
+ComposerPrimitiveMentionItems.displayName = "ComposerPrimitive.MentionItems";
+
+// =============================================================================
+// MentionItem — A single selectable mention item
+// =============================================================================
+
+export namespace ComposerPrimitiveMentionItem {
+  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. */
+    index?: number | undefined;
+  };
+}
+
+/**
+ * A button that inserts the mention item into the composer.
+ * Automatically receives `data-highlighted` when keyboard-navigated.
+ */
+export const ComposerPrimitiveMentionItem = forwardRef<
+  ComposerPrimitiveMentionItem.Element,
+  ComposerPrimitiveMentionItem.Props
+>(({ item, index: indexProp, onClick, ...props }, forwardedRef) => {
+  const {
+    selectItem,
+    items,
+    highlightedIndex,
+    activeCategoryId,
+    isSearchMode,
+  } = useMentionContext();
+
+  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) &&
+    itemIndex === highlightedIndex;
+
+  return (
+    <Primitive.button
+      type="button"
+      role="option"
+      aria-selected={isHighlighted}
+      data-highlighted={isHighlighted ? "" : undefined}
+      {...props}
+      ref={forwardedRef}
+      onClick={composeEventHandlers(onClick, handleClick)}
+    />
+  );
+});
+
+ComposerPrimitiveMentionItem.displayName = "ComposerPrimitive.MentionItem";

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