@assistant-ui/react 0.12.22 → 0.12.24

package/src/legacy-runtime/runtime-cores/assistant-transport/useToolInvocations.test.ts

@@ -19,7 +19,13 @@ const createState = (
 const createAssistantMessage = (
   argsText: string,
   args: Record<string, unknown>,
-  options?: { result?: ReadonlyJSONValue; isError?: boolean },
+  options?: {
+    result?: ReadonlyJSONValue;
+    isError?: boolean;
+    toolCallId?: string;
+    toolName?: string;
+    nestedMessages?: ThreadAssistantMessage[];
+  },
 ): ThreadAssistantMessage => ({
   id: "m-1",
   role: "assistant",
@@ -35,12 +41,13 @@ const createAssistantMessage = (
   content: [
     {
       type: "tool-call",
-      toolCallId: "tool-1",
-      toolName: "weatherSearch",
+      toolCallId: options?.toolCallId ?? "tool-1",
+      toolName: options?.toolName ?? "weatherSearch",
       args: args as ReadonlyJSONObject,
       argsText,
       ...(options?.result !== undefined && { result: options.result }),
       ...(options?.isError !== undefined && { isError: options.isError }),
+      ...(options?.nestedMessages && { messages: options.nestedMessages }),
     },
   ],
 });
@@ -228,6 +235,182 @@ describe("useToolInvocations", () => {
     expect(Object.keys(statuses)).not.toContain("tool-1:rewrite:0");
   });
 
+  it("does not execute tool calls loaded asynchronously with existing results", async () => {
+    const execute = vi.fn(async () => ({ forecast: "ok" }));
+    const getTools = () => ({
+      weatherSearch: {
+        parameters: { type: "object", properties: {} },
+        execute,
+      } satisfies Tool,
+    });
+    const onResult = vi.fn();
+    const setToolStatuses = vi.fn();
+
+    const { rerender } = renderHook(
+      ({ state }: { state: AssistantTransportState }) =>
+        useToolInvocations({
+          state,
+          getTools,
+          onResult,
+          setToolStatuses,
+        }),
+      {
+        initialProps: {
+          state: createState([]),
+        },
+      },
+    );
+
+    act(() => {
+      rerender({
+        state: createState([
+          createAssistantMessage(
+            '{"query":"London"}',
+            { query: "London" },
+            { result: { source: "history" } },
+          ),
+        ]),
+      });
+    });
+
+    await waitFor(() => {
+      expect(execute).not.toHaveBeenCalled();
+      expect(onResult).not.toHaveBeenCalled();
+    });
+  });
+
+  it("does not re-execute asynchronously loaded resolved tool calls after reset", async () => {
+    const execute = vi.fn(async () => ({ forecast: "ok" }));
+    const getTools = () => ({
+      weatherSearch: {
+        parameters: { type: "object", properties: {} },
+        execute,
+      } satisfies Tool,
+    });
+    const onResult = vi.fn();
+    const setToolStatuses = vi.fn();
+
+    const { result, rerender } = renderHook(
+      ({ state }: { state: AssistantTransportState }) =>
+        useToolInvocations({
+          state,
+          getTools,
+          onResult,
+          setToolStatuses,
+        }),
+      {
+        initialProps: {
+          state: createState([]),
+        },
+      },
+    );
+
+    act(() => {
+      rerender({
+        state: createState([
+          createAssistantMessage('{"query":"London"}', { query: "London" }),
+        ]),
+      });
+    });
+
+    await waitFor(() => {
+      expect(execute).toHaveBeenCalledTimes(1);
+    });
+
+    act(() => {
+      result.current.reset();
+    });
+
+    await act(async () => {
+      await Promise.resolve();
+    });
+
+    act(() => {
+      rerender({
+        state: createState([]),
+      });
+    });
+
+    act(() => {
+      rerender({
+        state: createState([
+          createAssistantMessage(
+            '{"query":"London"}',
+            { query: "London" },
+            { result: { source: "history" } },
+          ),
+        ]),
+      });
+    });
+
+    await waitFor(() => {
+      expect(execute).toHaveBeenCalledTimes(1);
+      expect(onResult).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  it("still processes nested unresolved tool calls when the parent tool call is already resolved", async () => {
+    const executeParent = vi.fn(async () => ({ scope: "parent" }));
+    const executeChild = vi.fn(async () => ({ scope: "child" }));
+    const getTools = () => ({
+      resolvedOnly: {
+        parameters: { type: "object", properties: {} },
+        execute: executeParent,
+      } satisfies Tool,
+      childTool: {
+        parameters: { type: "object", properties: {} },
+        execute: executeChild,
+      } satisfies Tool,
+    });
+    const onResult = vi.fn();
+    const setToolStatuses = vi.fn();
+
+    const nestedMessage = createAssistantMessage(
+      '{"query":"nested"}',
+      { query: "nested" },
+      {
+        toolCallId: "tool-child",
+        toolName: "childTool",
+      },
+    );
+
+    const { rerender } = renderHook(
+      ({ state }: { state: AssistantTransportState }) =>
+        useToolInvocations({
+          state,
+          getTools,
+          onResult,
+          setToolStatuses,
+        }),
+      {
+        initialProps: {
+          state: createState([]),
+        },
+      },
+    );
+
+    act(() => {
+      rerender({
+        state: createState([
+          createAssistantMessage(
+            '{"query":"parent"}',
+            { query: "parent" },
+            {
+              result: { source: "history" },
+              toolName: "resolvedOnly",
+              nestedMessages: [nestedMessage],
+            },
+          ),
+        ]),
+      });
+    });
+
+    await waitFor(() => {
+      expect(executeParent).not.toHaveBeenCalled();
+      expect(executeChild).toHaveBeenCalledTimes(1);
+    });
+  });
+
   it("does not close args stream early for non-executable tool snapshots", () => {
     const getTools = () => ({
       weatherSearch: {

package/src/primitives/composer/ComposerInput.tsx

@@ -22,10 +22,7 @@ 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";
+import { useComposerInputPluginRegistryOptional } from "./ComposerInputPluginContext";
 
 export namespace ComposerPrimitiveInput {
   export type Element = HTMLTextAreaElement;
@@ -144,8 +141,7 @@ export const ComposerPrimitiveInput = forwardRef<
     forwardedRef,
   ) => {
     const aui = useAui();
-    const mentionContext = useMentionContextOptional();
-    const mentionInternalContext = useMentionInternalContext();
+    const pluginRegistry = useComposerInputPluginRegistryOptional();
 
     const effectiveSubmitMode =
       submitMode ?? (submitOnEnter === false ? "none" : "enter");
@@ -166,10 +162,11 @@ export const ComposerPrimitiveInput = forwardRef<
       // 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;
+      // Let registered plugins (mention, slash command, etc.) handle Escape first
+      if (pluginRegistry) {
+        for (const plugin of pluginRegistry.getPlugins()) {
+          if (plugin.handleKeyDown(e)) return;
+        }
       }
 
       if (!cancelOnEscape) return;
@@ -187,8 +184,12 @@ export const ComposerPrimitiveInput = forwardRef<
       // ignore IME composition events
       if (e.nativeEvent.isComposing) return;
 
-      // Let the mention popover handle keyboard events first
-      if (mentionContext?.handleKeyDown(e)) return;
+      // Let registered plugins (mention, slash command, etc.) handle keyboard events first
+      if (pluginRegistry) {
+        for (const plugin of pluginRegistry.getPlugins()) {
+          if (plugin.handleKeyDown(e)) return;
+        }
+      }
 
       if (e.key === "Enter") {
         const threadState = aui.thread().getState();
@@ -297,9 +298,12 @@ export const ComposerPrimitiveInput = forwardRef<
           flushResourcesSync(() => {
             aui.composer().setText(e.target.value);
           });
-          mentionInternalContext?.setCursorPosition(
-            e.target.selectionStart ?? e.target.value.length,
-          );
+          const pos = e.target.selectionStart ?? e.target.value.length;
+          if (pluginRegistry) {
+            for (const plugin of pluginRegistry.getPlugins()) {
+              plugin.setCursorPosition(pos);
+            }
+          }
         },
       ),
       onKeyDown: composeEventHandlers(onKeyDown, handleKeyPress),
@@ -307,9 +311,12 @@ export const ComposerPrimitiveInput = forwardRef<
         onSelect,
         (e: React.SyntheticEvent<HTMLTextAreaElement>) => {
           const target = e.target as HTMLTextAreaElement;
-          mentionInternalContext?.setCursorPosition(
-            target.selectionStart ?? target.value.length,
-          );
+          const pos = target.selectionStart ?? target.value.length;
+          if (pluginRegistry) {
+            for (const plugin of pluginRegistry.getPlugins()) {
+              plugin.setCursorPosition(pos);
+            }
+          }
         },
       ),
       onPaste: composeEventHandlers(onPaste, handlePaste),

package/src/primitives/composer/ComposerInputPluginContext.tsx

@@ -0,0 +1,100 @@
+"use client";
+
+import {
+  createContext,
+  useContext,
+  useRef,
+  useCallback,
+  useMemo,
+  type ReactNode,
+  type FC,
+} from "react";
+
+// =============================================================================
+// Plugin interface — any trigger system (mention, slash command, emoji, etc.)
+// registers one of these with the input.
+// =============================================================================
+
+/**
+ * A plugin that intercepts keyboard events and cursor changes in the composer
+ * input. Used by trigger roots (MentionRoot, SlashCommandRoot, etc.) to handle
+ * popover navigation without ComposerInput knowing about specific triggers.
+ */
+export type ComposerInputPlugin = {
+  /** Handle a key event. Return true if consumed (stops propagation to other plugins and default behavior). */
+  handleKeyDown(e: {
+    readonly key: string;
+    readonly shiftKey: boolean;
+    readonly ctrlKey?: boolean;
+    readonly metaKey?: boolean;
+    readonly nativeEvent?: { isComposing?: boolean };
+    preventDefault(): void;
+  }): boolean;
+
+  /** Called on every cursor position change (selection change / text change). */
+  setCursorPosition(pos: number): void;
+};
+
+// =============================================================================
+// Registry — mutable, ref-based. No re-renders on register/unregister because
+// plugins are read imperatively at event time.
+// =============================================================================
+
+export type ComposerInputPluginRegistry = {
+  register(plugin: ComposerInputPlugin): () => void;
+  getPlugins(): readonly ComposerInputPlugin[];
+};
+
+const ComposerInputPluginRegistryContext =
+  createContext<ComposerInputPluginRegistry | null>(null);
+
+export const useComposerInputPluginRegistry =
+  (): ComposerInputPluginRegistry => {
+    const ctx = useContext(ComposerInputPluginRegistryContext);
+    if (!ctx)
+      throw new Error(
+        "useComposerInputPluginRegistry must be used within a ComposerInputPluginProvider",
+      );
+    return ctx;
+  };
+
+export const useComposerInputPluginRegistryOptional =
+  (): ComposerInputPluginRegistry | null => {
+    return useContext(ComposerInputPluginRegistryContext);
+  };
+
+// =============================================================================
+// Provider
+// =============================================================================
+
+export const ComposerInputPluginProvider: FC<{ children: ReactNode }> = ({
+  children,
+}) => {
+  const pluginsRef = useRef<Set<ComposerInputPlugin>>(new Set());
+  const snapshotRef = useRef<readonly ComposerInputPlugin[]>([]);
+
+  const register = useCallback((plugin: ComposerInputPlugin) => {
+    pluginsRef.current.add(plugin);
+    snapshotRef.current = Array.from(pluginsRef.current);
+    return () => {
+      pluginsRef.current.delete(plugin);
+      snapshotRef.current = Array.from(pluginsRef.current);
+    };
+  }, []);
+
+  const getPlugins = useCallback(
+    (): readonly ComposerInputPlugin[] => snapshotRef.current,
+    [],
+  );
+
+  const registry = useMemo<ComposerInputPluginRegistry>(
+    () => ({ register, getPlugins }),
+    [register, getPlugins],
+  );
+
+  return (
+    <ComposerInputPluginRegistryContext.Provider value={registry}>
+      {children}
+    </ComposerInputPluginRegistryContext.Provider>
+  );
+};

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

@@ -10,21 +10,25 @@ import {
   type ReactNode,
   type FC,
 } from "react";
-import { useResource } from "@assistant-ui/tap/react";
-import { useAui, useAuiState } from "@assistant-ui/store";
+import { useAui } 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";
+import { ComposerPrimitiveTriggerPopoverRoot } from "../trigger/TriggerPopoverContext";
+import type {
+  TriggerPopoverResourceOutput,
+  SelectItemOverride,
+  OnSelectBehavior,
+} from "../trigger/TriggerPopoverResource";
+
+type MentionResourceOutput = TriggerPopoverResourceOutput & {
+  readonly formatter: Unstable_DirectiveFormatter;
+};
 
 // =============================================================================
-// Context — public (popover components read state + actions from here)
+// Context — public (provides formatter on top of TriggerPopoverContext)
 // =============================================================================
 
 const MentionContext = createContext<MentionResourceOutput | null>(null);
@@ -43,11 +47,10 @@ export const useMentionContextOptional = () => {
 };
 
 // =============================================================================
-// Internal context — ComposerInput → MentionRoot communication
+// Internal context — only registerSelectItemOverride for Lexical integration
 // =============================================================================
 
 type MentionInternalContextValue = {
-  setCursorPosition(pos: number): void;
   registerSelectItemOverride(fn: SelectItemOverride): () => void;
 };
 
@@ -59,7 +62,7 @@ export const useMentionInternalContext = () => {
 };
 
 // =============================================================================
-// Provider Component
+// Provider Component — delegates to TriggerPopoverRoot internally
 // =============================================================================
 
 export namespace ComposerPrimitiveMentionRoot {
@@ -82,7 +85,6 @@ export const ComposerPrimitiveMentionRoot: FC<
   formatter: formatterProp,
 }) => {
   const aui = useAui();
-  const text = useAuiState((s) => s.composer.text);
   const formatter = formatterProp ?? unstable_defaultDirectiveFormatter;
 
   // ---------------------------------------------------------------------------
@@ -110,32 +112,64 @@ export const ComposerPrimitiveMentionRoot: FC<
   const adapter = adapterProp ?? runtimeAdapter;
 
   // ---------------------------------------------------------------------------
-  // Mention resource (all state + logic managed via tap primitives)
+  // onSelect behavior for mentions: insert directive text
   // ---------------------------------------------------------------------------
 
-  const mention = useResource(
-    MentionResource({ adapter, text, triggerChar, formatter, aui }),
+  const onSelect = useMemo<OnSelectBehavior>(
+    () => ({ type: "insertDirective", formatter }),
+    [formatter],
   );
 
   // ---------------------------------------------------------------------------
-  // Internal context (stable — methods come from tapEffectEvent)
+  // MentionContext — provides formatter + delegates state to TriggerPopoverContext
+  // We use useAuiState to read trigger popover state via the inner context.
+  // For backward compat, MentionContext wraps TriggerPopoverContext output.
   // ---------------------------------------------------------------------------
 
+  return (
+    <ComposerPrimitiveTriggerPopoverRoot
+      adapter={adapter}
+      trigger={triggerChar}
+      onSelect={onSelect}
+    >
+      <MentionContextBridge formatter={formatter}>
+        {children}
+      </MentionContextBridge>
+    </ComposerPrimitiveTriggerPopoverRoot>
+  );
+};
+
+ComposerPrimitiveMentionRoot.displayName = "ComposerPrimitive.MentionRoot";
+
+// =============================================================================
+// Bridge — reads TriggerPopoverContext, wraps it as MentionContext
+// =============================================================================
+
+import { useTriggerPopoverContext } from "../trigger/TriggerPopoverContext";
+
+const MentionContextBridge: FC<{
+  formatter: Unstable_DirectiveFormatter;
+  children: ReactNode;
+}> = ({ formatter, children }) => {
+  const triggerCtx = useTriggerPopoverContext();
+
+  const mentionValue = useMemo<MentionResourceOutput>(
+    () => ({ ...triggerCtx, formatter }),
+    [triggerCtx, formatter],
+  );
+
   const internalContextValue = useMemo<MentionInternalContextValue>(
     () => ({
-      setCursorPosition: mention.setCursorPosition,
-      registerSelectItemOverride: mention.registerSelectItemOverride,
+      registerSelectItemOverride: triggerCtx.registerSelectItemOverride,
     }),
-    [mention.setCursorPosition, mention.registerSelectItemOverride],
+    [triggerCtx.registerSelectItemOverride],
   );
 
   return (
-    <MentionContext.Provider value={mention}>
+    <MentionContext.Provider value={mentionValue}>
       <MentionInternalContext.Provider value={internalContextValue}>
         {children}
       </MentionInternalContext.Provider>
     </MentionContext.Provider>
   );
 };
-
-ComposerPrimitiveMentionRoot.displayName = "ComposerPrimitive.MentionRoot";

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

@@ -4,13 +4,16 @@ export {
   useMentionContextOptional,
   useMentionInternalContext,
 } from "./ComposerMentionContext";
-export { ComposerPrimitiveMentionPopover } from "./ComposerMentionPopover";
+
+// UI primitives — re-exported from the shared trigger popover implementation.
+// MentionRoot internally renders TriggerPopoverRoot, so these work within it.
+export { ComposerPrimitiveTriggerPopoverPopover as ComposerPrimitiveMentionPopover } from "../trigger/TriggerPopoverPopover";
 export {
-  ComposerPrimitiveMentionCategories,
-  ComposerPrimitiveMentionCategoryItem,
-} from "./ComposerMentionCategories";
+  ComposerPrimitiveTriggerPopoverCategories as ComposerPrimitiveMentionCategories,
+  ComposerPrimitiveTriggerPopoverCategoryItem as ComposerPrimitiveMentionCategoryItem,
+} from "../trigger/TriggerPopoverCategories";
 export {
-  ComposerPrimitiveMentionItems,
-  ComposerPrimitiveMentionItem,
-} from "./ComposerMentionItems";
-export { ComposerPrimitiveMentionBack } from "./ComposerMentionBack";
+  ComposerPrimitiveTriggerPopoverItems as ComposerPrimitiveMentionItems,
+  ComposerPrimitiveTriggerPopoverItem as ComposerPrimitiveMentionItem,
+} from "../trigger/TriggerPopoverItems";
+export { ComposerPrimitiveTriggerPopoverBack as ComposerPrimitiveMentionBack } from "../trigger/TriggerPopoverBack";

package/src/primitives/composer/slash-command/ComposerSlashCommandRoot.tsx

@@ -0,0 +1,76 @@
+"use client";
+
+import { type ReactNode, type FC, useCallback, useMemo } from "react";
+import type {
+  Unstable_SlashCommandAdapter,
+  Unstable_SlashCommandItem,
+} from "@assistant-ui/core";
+import { ComposerPrimitiveTriggerPopoverRoot } from "../trigger/TriggerPopoverContext";
+import type { OnSelectBehavior } from "../trigger/TriggerPopoverResource";
+
+// =============================================================================
+// SlashCommandRoot — convenience wrapper around TriggerPopoverRoot
+// =============================================================================
+
+export namespace ComposerPrimitiveSlashCommandRoot {
+  export type Props = {
+    children: ReactNode;
+    /** The adapter providing slash command categories and items. */
+    adapter: Unstable_SlashCommandAdapter;
+    /** Character(s) that trigger the popover. @default "/" */
+    trigger?: string | undefined;
+    /** Callback when a slash command is selected. */
+    onSelect?: ((item: Unstable_SlashCommandItem) => void) | undefined;
+  };
+}
+
+/**
+ * Convenience wrapper around `TriggerPopoverRoot` pre-configured for `/` slash commands.
+ * When a user selects a command, the `/command` text is removed from the composer
+ * and the item's `execute` callback (if any) and `onSelect` prop are called.
+ *
+ * @example
+ * ```tsx
+ * <ComposerPrimitive.Unstable_SlashCommandRoot adapter={slashAdapter}>
+ *   <ComposerPrimitive.Input />
+ *   <ComposerPrimitive.Unstable_TriggerPopoverPopover>
+ *     <ComposerPrimitive.Unstable_TriggerPopoverItems>
+ *       {(items) => items.map(item => (
+ *         <ComposerPrimitive.Unstable_TriggerPopoverItem key={item.id} item={item}>
+ *           {item.label}
+ *         </ComposerPrimitive.Unstable_TriggerPopoverItem>
+ *       ))}
+ *     </ComposerPrimitive.Unstable_TriggerPopoverItems>
+ *   </ComposerPrimitive.Unstable_TriggerPopoverPopover>
+ * </ComposerPrimitive.Unstable_SlashCommandRoot>
+ * ```
+ */
+export const ComposerPrimitiveSlashCommandRoot: FC<
+  ComposerPrimitiveSlashCommandRoot.Props
+> = ({ children, adapter, trigger = "/", onSelect: onSelectProp }) => {
+  const handler = useCallback(
+    (item: Unstable_SlashCommandItem) => {
+      item.execute?.();
+      onSelectProp?.(item);
+    },
+    [onSelectProp],
+  );
+
+  const onSelect = useMemo<OnSelectBehavior>(
+    () => ({ type: "action", handler }),
+    [handler],
+  );
+
+  return (
+    <ComposerPrimitiveTriggerPopoverRoot
+      adapter={adapter}
+      trigger={trigger}
+      onSelect={onSelect}
+    >
+      {children}
+    </ComposerPrimitiveTriggerPopoverRoot>
+  );
+};
+
+ComposerPrimitiveSlashCommandRoot.displayName =
+  "ComposerPrimitive.SlashCommandRoot";

package/src/primitives/composer/slash-command/index.ts

@@ -0,0 +1 @@
+export { ComposerPrimitiveSlashCommandRoot } from "./ComposerSlashCommandRoot";

package/src/primitives/composer/trigger/TriggerPopoverBack.tsx

@@ -0,0 +1,40 @@
+"use client";
+
+import { Primitive } from "../../../utils/Primitive";
+import {
+  type ComponentRef,
+  type ComponentPropsWithoutRef,
+  forwardRef,
+} from "react";
+import { composeEventHandlers } from "@radix-ui/primitive";
+import { useTriggerPopoverContext } from "./TriggerPopoverContext";
+
+export namespace ComposerPrimitiveTriggerPopoverBack {
+  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).
+ */
+export const ComposerPrimitiveTriggerPopoverBack = forwardRef<
+  ComposerPrimitiveTriggerPopoverBack.Element,
+  ComposerPrimitiveTriggerPopoverBack.Props
+>(({ onClick, ...props }, forwardedRef) => {
+  const { activeCategoryId, isSearchMode, goBack } = useTriggerPopoverContext();
+
+  if (!activeCategoryId || isSearchMode) return null;
+
+  return (
+    <Primitive.button
+      type="button"
+      {...props}
+      ref={forwardedRef}
+      onClick={composeEventHandlers(onClick, goBack)}
+    />
+  );
+});
+
+ComposerPrimitiveTriggerPopoverBack.displayName =
+  "ComposerPrimitive.TriggerPopoverBack";