@assistant-ui/react 0.12.19 → 0.12.21

package/src/client/SingleThreadList.ts

@@ -0,0 +1,95 @@
+import { resource, tapMemo } from "@assistant-ui/tap";
+import {
+  type ClientElement,
+  type ClientOutput,
+  tapClientResource,
+} from "@assistant-ui/store";
+
+const THREAD_ID = "default";
+
+const SingleThreadListItem = resource((): ClientOutput<"threadListItem"> => {
+  return {
+    getState: () => ({
+      id: THREAD_ID,
+      remoteId: undefined,
+      externalId: undefined,
+      title: undefined,
+      status: "regular",
+    }),
+    switchTo: () => {},
+    rename: () => {},
+    archive: () => {},
+    unarchive: () => {},
+    delete: () => {},
+    generateTitle: () => {},
+    initialize: async () => ({ remoteId: THREAD_ID, externalId: undefined }),
+    detach: () => {},
+  };
+});
+
+type SingleThreadListProps = {
+  thread: ClientElement<"thread">;
+};
+
+/**
+ * A minimal threads scope that wraps a single thread.
+ * Automatically provided by ExternalThread when no threads scope exists.
+ * Mounts the provided thread resource element.
+ */
+export const SingleThreadList = resource(
+  ({ thread }: SingleThreadListProps): ClientOutput<"threads"> => {
+    const itemClient = tapClientResource(SingleThreadListItem());
+    const threadClient = tapClientResource(thread);
+
+    const state = tapMemo(
+      () => ({
+        mainThreadId: THREAD_ID,
+        newThreadId: null,
+        isLoading: false,
+        threadIds: [THREAD_ID],
+        archivedThreadIds: [],
+        threadItems: [itemClient.state],
+        main: threadClient.state,
+      }),
+      [itemClient.state, threadClient.state],
+    );
+
+    return {
+      getState: () => state,
+      switchToThread: () => {
+        throw new Error("SingleThreadList does not support switchToThread");
+      },
+      switchToNewThread: () => {
+        throw new Error("SingleThreadList does not support switchToNewThread");
+      },
+      item: (selector) => {
+        if (
+          selector !== "main" &&
+          !(
+            typeof selector === "object" &&
+            "id" in selector &&
+            selector.id === THREAD_ID
+          ) &&
+          !(
+            typeof selector === "object" &&
+            "index" in selector &&
+            selector.index === 0
+          )
+        ) {
+          throw new Error(
+            `SingleThreadList: unknown item selector ${JSON.stringify(selector)}`,
+          );
+        }
+        return itemClient.methods;
+      },
+      thread: (selector) => {
+        if (selector !== "main" && selector !== THREAD_ID) {
+          throw new Error(
+            `SingleThreadList: unknown thread selector ${JSON.stringify(selector)}`,
+          );
+        }
+        return threadClient.methods;
+      },
+    };
+  },
+);

package/src/index.ts

@@ -199,6 +199,13 @@ export {
   type ToolDefinition,
   Tools,
   DataRenderers,
+  Interactables,
+  useInteractable,
+  type UseInteractableConfig,
+  type UseInteractableMetadata,
+  makeInteractable,
+  type InteractableConfig,
+  type AssistantInteractable,
 } from "@assistant-ui/core/react";
 
 // Core pass-through (unchanged)
@@ -216,6 +223,11 @@ export type { Tool } from "assistant-stream";
 export { tool } from "@assistant-ui/core";
 
 export { Suggestions, type SuggestionConfig } from "@assistant-ui/core/store";
+export type {
+  QueueItemState,
+  QueueItemMethods,
+} from "@assistant-ui/core/store";
+export type { ComposerSendOptions } from "@assistant-ui/core/store";
 
 // React-only (stays)
 export { makeAssistantVisible } from "./model-context/makeAssistantVisible";
@@ -250,6 +262,7 @@ export * as AttachmentPrimitive from "./primitives/attachment";
 export * as BranchPickerPrimitive from "./primitives/branchPicker";
 export * as ChainOfThoughtPrimitive from "./primitives/chainOfThought";
 export * as ComposerPrimitive from "./primitives/composer";
+export * as QueueItemPrimitive from "./primitives/queueItem";
 export * as MessagePartPrimitive from "./primitives/messagePart";
 export * as ErrorPrimitive from "./primitives/error";
 export * as MessagePrimitive from "./primitives/message";
@@ -348,16 +361,29 @@ export {
   ExternalThread,
   type ExternalThreadProps,
   type ExternalThreadMessage,
+  type ExternalThreadQueueAdapter,
 } from "./client/ExternalThread";
 export {
   InMemoryThreadList,
   type InMemoryThreadListProps,
 } from "./client/InMemoryThreadList";
+export { SingleThreadList } from "./client/SingleThreadList";
 
 // ============================================================================
 // internal & augmentations
 // ============================================================================
 export * as INTERNAL from "./internal";
+
+// Unstable - mention
+export {
+  unstable_useToolMentionAdapter,
+  type Unstable_ToolMentionAdapterOptions,
+} from "./unstable/useToolMentionAdapter";
+export {
+  useMentionContext as unstable_useMentionContext,
+  useMentionContextOptional as unstable_useMentionContextOptional,
+  useMentionInternalContext as unstable_useMentionInternalContext,
+} from "./primitives/composer/mention";
 export type { ToolExecutionStatus } from "./internal";
 
 export type { Assistant } from "./augmentations";

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