@assistant-ui/react 0.12.25 → 0.12.27

package/src/primitives/composer/ComposerAttachmentDropzone.test.tsx

@@ -0,0 +1,125 @@
+/**
+ * @vitest-environment jsdom
+ */
+import { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { ComposerPrimitiveAttachmentDropzone } from "./ComposerAttachmentDropzone";
+
+const addAttachment = vi.fn<(file: File) => Promise<void>>();
+
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+
+vi.mock("@assistant-ui/store", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("@assistant-ui/store")>();
+  return {
+    ...actual,
+    useAui: () => ({
+      composer: () => ({
+        addAttachment,
+      }),
+    }),
+  };
+});
+
+const createDropEvent = (files: File[]) => {
+  const event = new Event("drop", { bubbles: true, cancelable: true });
+  Object.defineProperty(event, "dataTransfer", {
+    value: { files },
+    configurable: true,
+  });
+  return event;
+};
+
+describe("ComposerPrimitiveAttachmentDropzone", () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(async () => {
+    addAttachment.mockReset();
+    container = document.createElement("div");
+    document.body.appendChild(container);
+    root = createRoot(container);
+
+    await act(async () => {
+      root.render(
+        <ComposerPrimitiveAttachmentDropzone data-testid="dropzone">
+          <div>dropzone</div>
+        </ComposerPrimitiveAttachmentDropzone>,
+      );
+    });
+  });
+
+  afterEach(async () => {
+    await act(async () => {
+      root.unmount();
+    });
+    container.remove();
+    vi.restoreAllMocks();
+  });
+
+  it("starts all dropped attachments before awaiting completion", async () => {
+    const resolvers: Array<() => void> = [];
+    addAttachment.mockImplementation(
+      () =>
+        new Promise<void>((resolve) => {
+          resolvers.push(resolve);
+        }),
+    );
+
+    const dropzone = container.querySelector("[data-testid='dropzone']");
+    expect(dropzone).not.toBeNull();
+
+    const files = [
+      new File(["a"], "first.txt", { type: "text/plain" }),
+      new File(["b"], "second.txt", { type: "text/plain" }),
+      new File(["c"], "third.txt", { type: "text/plain" }),
+    ];
+
+    await act(async () => {
+      dropzone!.dispatchEvent(createDropEvent(files));
+      await Promise.resolve();
+    });
+
+    expect(addAttachment).toHaveBeenCalledTimes(3);
+    expect(addAttachment.mock.calls.map(([file]) => file.name)).toEqual([
+      "first.txt",
+      "second.txt",
+      "third.txt",
+    ]);
+
+    for (const resolve of resolvers) resolve();
+
+    await act(async () => {
+      await Promise.resolve();
+    });
+  });
+
+  it("continues processing other files when one attachment fails", async () => {
+    const error = new Error("upload failed");
+    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+
+    addAttachment
+      .mockRejectedValueOnce(error)
+      .mockResolvedValueOnce(undefined)
+      .mockResolvedValueOnce(undefined);
+
+    const dropzone = container.querySelector("[data-testid='dropzone']");
+    expect(dropzone).not.toBeNull();
+
+    const files = [
+      new File(["a"], "first.txt", { type: "text/plain" }),
+      new File(["b"], "second.txt", { type: "text/plain" }),
+      new File(["c"], "third.txt", { type: "text/plain" }),
+    ];
+
+    await act(async () => {
+      dropzone!.dispatchEvent(createDropEvent(files));
+      await Promise.resolve();
+      await Promise.resolve();
+    });
+
+    expect(addAttachment).toHaveBeenCalledTimes(3);
+    expect(errorSpy).toHaveBeenCalledWith("Failed to add attachment:", error);
+  });
+});

package/src/primitives/composer/ComposerAttachmentDropzone.tsx

@@ -11,7 +11,7 @@ import {
 
 import { composeEventHandlers } from "@radix-ui/primitive";
 import { Slot } from "radix-ui";
-import React from "react";
+import type React from "react";
 import { useAui } from "@assistant-ui/store";
 
 export namespace ComposerPrimitiveAttachmentDropzone {
@@ -66,13 +66,16 @@ export const ComposerPrimitiveAttachmentDropzone = forwardRef<
       if (disabled) return;
       e.preventDefault();
       setIsDragging(false);
-      for (const file of e.dataTransfer.files) {
-        try {
-          await aui.composer().addAttachment(file);
-        } catch (error) {
-          console.error("Failed to add attachment:", error);
-        }
-      }
+      const files = Array.from(e.dataTransfer.files);
+      await Promise.all(
+        files.map(async (file) => {
+          try {
+            await aui.composer().addAttachment(file);
+          } catch (error) {
+            console.error("Failed to add attachment:", error);
+          }
+        }),
+      );
     },
     [disabled, aui],
   );

package/src/primitives/composer/ComposerCancel.ts

@@ -1,8 +1,8 @@
 "use client";
 
 import {
-  ActionButtonElement,
-  ActionButtonProps,
+  type ActionButtonElement,
+  type ActionButtonProps,
   createActionButton,
 } from "../../utils/createActionButton";
 import { useComposerCancel as useComposerCancelBehavior } from "@assistant-ui/core/react";

package/src/primitives/composer/ComposerDictationTranscript.tsx

@@ -1,7 +1,11 @@
 "use client";
 
 import { Primitive } from "../../utils/Primitive";
-import { type ComponentRef, forwardRef, ComponentPropsWithoutRef } from "react";
+import {
+  type ComponentRef,
+  forwardRef,
+  type ComponentPropsWithoutRef,
+} from "react";
 import { useAuiState } from "@assistant-ui/store";
 
 export namespace ComposerPrimitiveDictationTranscript {

package/src/primitives/composer/ComposerInput.tsx

@@ -4,7 +4,7 @@ import { composeEventHandlers } from "@radix-ui/primitive";
 import { useComposedRefs } from "@radix-ui/react-compose-refs";
 import { Slot } from "radix-ui";
 import {
-  ClipboardEvent,
+  type ClipboardEvent,
   type KeyboardEvent,
   type ReactElement,
   type ReactNode,
@@ -157,6 +157,8 @@ export const ComposerPrimitiveInput = forwardRef<
       ) || disabledProp;
     const textareaRef = useRef<HTMLTextAreaElement>(null);
     const ref = useComposedRefs(forwardedRef, textareaRef);
+    // suppress text/cursor broadcasts during IME composition
+    const compositionRef = useRef(false);
 
     useEscapeKeydown((e) => {
       // Only handle ESC if it originated from within this input
@@ -295,6 +297,10 @@ export const ComposerPrimitiveInput = forwardRef<
         onChange,
         (e: React.ChangeEvent<HTMLTextAreaElement>) => {
           if (!aui.composer().getState().isEditing) return;
+          const isComposing =
+            (e.nativeEvent as { isComposing?: boolean }).isComposing === true ||
+            compositionRef.current;
+          if (isComposing) return;
           flushResourcesSync(() => {
             aui.composer().setText(e.target.value);
           });
@@ -307,9 +313,35 @@ export const ComposerPrimitiveInput = forwardRef<
         },
       ),
       onKeyDown: composeEventHandlers(onKeyDown, handleKeyPress),
+      onCompositionStart: composeEventHandlers(
+        (rest as { onCompositionStart?: React.CompositionEventHandler })
+          .onCompositionStart,
+        () => {
+          compositionRef.current = true;
+        },
+      ),
+      onCompositionEnd: composeEventHandlers(
+        (rest as { onCompositionEnd?: React.CompositionEventHandler })
+          .onCompositionEnd,
+        (e: React.CompositionEvent<HTMLTextAreaElement>) => {
+          compositionRef.current = false;
+          if (!aui.composer().getState().isEditing) return;
+          const target = e.target as HTMLTextAreaElement;
+          flushResourcesSync(() => {
+            aui.composer().setText(target.value);
+          });
+          const pos = target.selectionStart ?? target.value.length;
+          if (pluginRegistry) {
+            for (const plugin of pluginRegistry.getPlugins()) {
+              plugin.setCursorPosition(pos);
+            }
+          }
+        },
+      ),
       onSelect: composeEventHandlers(
         onSelect,
         (e: React.SyntheticEvent<HTMLTextAreaElement>) => {
+          if (compositionRef.current) return;
           const target = e.target as HTMLTextAreaElement;
           const pos = target.selectionStart ?? target.value.length;
           if (pluginRegistry) {

package/src/primitives/composer/ComposerInputPluginContext.tsx

@@ -10,15 +10,10 @@ import {
   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.
+ * input. Used by trigger popover declarations 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). */
@@ -35,13 +30,21 @@ export type ComposerInputPlugin = {
   setCursorPosition(pos: number): void;
 };
 
-// =============================================================================
-// Registry — mutable, ref-based. No re-renders on register/unregister because
-// plugins are read imperatively at event time.
-// =============================================================================
+/** Options for registering a plugin. */
+export type ComposerInputPluginRegisterOptions = {
+  /**
+   * Relative priority. Plugins with higher priority receive events first.
+   * @default 0
+   */
+  priority?: number;
+};
 
+// Ref-based registry: plugins are read imperatively at event time, so register/unregister does not trigger re-renders.
 export type ComposerInputPluginRegistry = {
-  register(plugin: ComposerInputPlugin): () => void;
+  register(
+    plugin: ComposerInputPlugin,
+    opts?: ComposerInputPluginRegisterOptions,
+  ): () => void;
   getPlugins(): readonly ComposerInputPlugin[];
 };
 
@@ -63,25 +66,35 @@ export const useComposerInputPluginRegistryOptional =
     return useContext(ComposerInputPluginRegistryContext);
   };
 
-// =============================================================================
-// Provider
-// =============================================================================
-
 export const ComposerInputPluginProvider: FC<{ children: ReactNode }> = ({
   children,
 }) => {
-  const pluginsRef = useRef<Set<ComposerInputPlugin>>(new Set());
+  const pluginsRef = useRef<Map<ComposerInputPlugin, number>>(new Map());
   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 refreshSnapshot = useCallback(() => {
+    const entries = Array.from(pluginsRef.current.entries());
+    // Sort by priority descending; stable insertion order for equal priorities.
+    entries.sort((a, b) => b[1] - a[1]);
+    snapshotRef.current = entries.map(([plugin]) => plugin);
   }, []);
 
+  const register = useCallback(
+    (
+      plugin: ComposerInputPlugin,
+      opts?: ComposerInputPluginRegisterOptions,
+    ) => {
+      const priority = opts?.priority ?? 0;
+      pluginsRef.current.set(plugin, priority);
+      refreshSnapshot();
+      return () => {
+        pluginsRef.current.delete(plugin);
+        refreshSnapshot();
+      };
+    },
+    [refreshSnapshot],
+  );
+
   const getPlugins = useCallback(
     (): readonly ComposerInputPlugin[] => snapshotRef.current,
     [],

package/src/primitives/composer/ComposerRoot.tsx

@@ -6,7 +6,7 @@ import {
   type ComponentRef,
   type FormEvent,
   forwardRef,
-  ComponentPropsWithoutRef,
+  type ComponentPropsWithoutRef,
 } from "react";
 import { useComposerSend } from "./ComposerSend";
 

package/src/primitives/composer/ComposerSend.ts

@@ -2,8 +2,8 @@
 
 import { useCallback } from "react";
 import {
-  ActionButtonElement,
-  ActionButtonProps,
+  type ActionButtonElement,
+  type ActionButtonProps,
   createActionButton,
 } from "../../utils/createActionButton";
 import { useComposerSend as useComposerSendBehavior } from "@assistant-ui/core/react";

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

@@ -0,0 +1,207 @@
+"use client";
+
+import { useAui, useAuiState } from "@assistant-ui/store";
+import { useResource } from "@assistant-ui/tap/react";
+import type { Unstable_TriggerAdapter } from "@assistant-ui/core";
+import {
+  createContext,
+  forwardRef,
+  useCallback,
+  useContext,
+  useEffect,
+  useId,
+  useMemo,
+  useRef,
+  useState,
+  type ComponentPropsWithoutRef,
+  type ComponentRef,
+} from "react";
+import { Primitive } from "../../../utils/Primitive";
+import { useComposerInputPluginRegistryOptional } from "../ComposerInputPluginContext";
+import {
+  TriggerPopoverResource,
+  type TriggerPopoverResourceOutput,
+} from "./TriggerPopoverResource";
+import type { TriggerBehavior } from "./triggerSelectionResource";
+import { useTriggerPopoverRootContext } from "./TriggerPopoverRootContext";
+
+const TriggerPopoverScopeContext =
+  createContext<TriggerPopoverResourceOutput | null>(null);
+
+export const useTriggerPopoverScopeContext = () => {
+  const ctx = useContext(TriggerPopoverScopeContext);
+  if (!ctx)
+    throw new Error(
+      "useTriggerPopoverScopeContext must be used within ComposerPrimitive.TriggerPopover",
+    );
+  return ctx;
+};
+
+export const useTriggerPopoverScopeContextOptional = () =>
+  useContext(TriggerPopoverScopeContext);
+
+/** Registration API exposed to behavior sub-primitives. */
+export type TriggerBehaviorRegistration = {
+  register(behavior: TriggerBehavior): () => void;
+};
+
+const TriggerBehaviorRegistrationContext =
+  createContext<TriggerBehaviorRegistration | null>(null);
+
+/** Obtain the registration handle from the parent `<TriggerPopover>`. */
+export const useTriggerBehaviorRegistration = () => {
+  const ctx = useContext(TriggerBehaviorRegistrationContext);
+  if (!ctx)
+    throw new Error(
+      "TriggerPopover.Directive / TriggerPopover.Action must be rendered inside ComposerPrimitive.TriggerPopover",
+    );
+  return ctx;
+};
+
+export namespace ComposerPrimitiveTriggerPopover {
+  export type Element = ComponentRef<typeof Primitive.div>;
+  export type Props = Omit<
+    ComponentPropsWithoutRef<typeof Primitive.div>,
+    "onSelect"
+  > & {
+    /** The character(s) that activate this trigger (e.g. `"@"`, `"/"`). Also serves as the trigger identity within the root. */
+    readonly char: string;
+    /** Adapter providing categories and items. */
+    readonly adapter?: Unstable_TriggerAdapter | undefined;
+  };
+}
+
+/**
+ * Declares a trigger and renders its popover container. The popover only
+ * renders its DOM (and children) when the trigger character is active in the
+ * composer input and a behavior sub-primitive has been registered.
+ *
+ * A behavior is contributed by rendering exactly one of
+ * `<TriggerPopover.Directive>` or `<TriggerPopover.Action>` as a child. Without
+ * a behavior the trigger stays closed.
+ *
+ * Must be placed inside `ComposerPrimitive.Unstable_TriggerPopoverRoot`.
+ *
+ * @example
+ * ```tsx
+ * <ComposerPrimitive.Unstable_TriggerPopover
+ *   char="@"
+ *   adapter={mentionAdapter}
+ * >
+ *   <ComposerPrimitive.Unstable_TriggerPopover.Directive formatter={formatter} />
+ *   <ComposerPrimitive.Unstable_TriggerPopoverCategories>
+ *     {(cats) => cats.map(...)}
+ *   </ComposerPrimitive.Unstable_TriggerPopoverCategories>
+ *   <ComposerPrimitive.Unstable_TriggerPopoverItems>
+ *     {(items) => items.map(...)}
+ *   </ComposerPrimitive.Unstable_TriggerPopoverItems>
+ * </ComposerPrimitive.Unstable_TriggerPopover>
+ * ```
+ */
+export const ComposerPrimitiveTriggerPopover = forwardRef<
+  ComposerPrimitiveTriggerPopover.Element,
+  ComposerPrimitiveTriggerPopover.Props
+>(
+  (
+    { char, adapter, "aria-label": ariaLabel, children, ...props },
+    forwardedRef,
+  ) => {
+    const aui = useAui();
+    const text = useAuiState((s) => s.composer.text);
+    const popoverId = useId();
+
+    // Track in state (for resource reactivity) + ref (dev warning on duplicate registrations).
+    const behaviorRef = useRef<TriggerBehavior | null>(null);
+    const [behavior, setBehavior] = useState<TriggerBehavior | null>(null);
+    const registrationCountRef = useRef(0);
+
+    const register = useCallback<TriggerBehaviorRegistration["register"]>(
+      (next) => {
+        registrationCountRef.current += 1;
+        if (
+          process.env.NODE_ENV !== "production" &&
+          registrationCountRef.current > 1
+        ) {
+          console.warn(
+            `[assistant-ui] TriggerPopover "${char}" received more than one behavior child. Exactly one <TriggerPopover.Directive> or <TriggerPopover.Action> is allowed per TriggerPopover; the last registration wins.`,
+          );
+        }
+        behaviorRef.current = next;
+        setBehavior(next);
+        return () => {
+          registrationCountRef.current = Math.max(
+            0,
+            registrationCountRef.current - 1,
+          );
+          if (behaviorRef.current === next) {
+            behaviorRef.current = null;
+            setBehavior(null);
+          }
+        };
+      },
+      [char],
+    );
+
+    const registration = useMemo<TriggerBehaviorRegistration>(
+      () => ({ register }),
+      [register],
+    );
+
+    const resource = useResource(
+      TriggerPopoverResource({
+        adapter,
+        text,
+        triggerChar: char,
+        behavior: behavior ?? undefined,
+        aui,
+        popoverId,
+      }),
+    );
+
+    // Wrapper changes per render, but tap-stable methods inside don't.
+    const resourceRef = useRef(resource);
+    resourceRef.current = resource;
+
+    const root = useTriggerPopoverRootContext();
+    useEffect(() => {
+      return root.register({
+        char,
+        ...(behavior ? { behavior } : {}),
+        resource: resourceRef.current,
+      });
+    }, [root, char, behavior]);
+
+    const pluginRegistry = useComposerInputPluginRegistryOptional();
+    useEffect(() => {
+      if (!pluginRegistry) return undefined;
+      return pluginRegistry.register(resourceRef.current);
+    }, [pluginRegistry]);
+
+    const open = behavior !== null && resource.open;
+
+    return (
+      <TriggerBehaviorRegistrationContext.Provider value={registration}>
+        <TriggerPopoverScopeContext.Provider value={resource}>
+          {open ? (
+            <Primitive.div
+              role="listbox"
+              id={popoverId}
+              aria-label={ariaLabel ?? "Suggestions"}
+              aria-activedescendant={resource.highlightedItemId}
+              data-state="open"
+              {...props}
+              ref={forwardedRef}
+            >
+              {children}
+            </Primitive.div>
+          ) : (
+            children
+          )}
+        </TriggerPopoverScopeContext.Provider>
+      </TriggerBehaviorRegistrationContext.Provider>
+    );
+  },
+);
+
+ComposerPrimitiveTriggerPopover.displayName =
+  "ComposerPrimitive.TriggerPopover";

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

@@ -0,0 +1,61 @@
+"use client";
+
+import type {
+  Unstable_DirectiveFormatter,
+  Unstable_TriggerItem,
+} from "@assistant-ui/core";
+import { unstable_defaultDirectiveFormatter } from "@assistant-ui/core";
+import { useEffect, useRef, type FC } from "react";
+import { useTriggerBehaviorRegistration } from "./TriggerPopover";
+import type { TriggerBehavior } from "./triggerSelectionResource";
+
+export namespace ComposerPrimitiveTriggerPopoverAction {
+  export type Props = {
+    /** Defaults to `unstable_defaultDirectiveFormatter`. */
+    readonly formatter?: Unstable_DirectiveFormatter | undefined;
+    /** Fires the moment an item is selected; runs regardless of `removeOnExecute`. */
+    readonly onExecute: (item: Unstable_TriggerItem) => void;
+    /** When true, strips the trigger text after executing. Defaults to `false` (keeps audit-trail chip). */
+    readonly removeOnExecute?: boolean | undefined;
+  };
+}
+
+/**
+ * Configures a `<TriggerPopover>` to fire a handler when an item is selected,
+ * optionally leaving a directive chip behind as an audit trail. Render exactly
+ * one behavior sub-primitive per `<TriggerPopover>`.
+ *
+ * Exposed as `ComposerPrimitive.Unstable_TriggerPopover.Action`.
+ *
+ * @example
+ * ```tsx
+ * <ComposerPrimitive.Unstable_TriggerPopover char="/" adapter={slashAdapter}>
+ *   <ComposerPrimitive.Unstable_TriggerPopover.Action
+ *     onExecute={(item) => commandHandlers[item.id]?.()}
+ *     removeOnExecute={false}
+ *   />
+ * </ComposerPrimitive.Unstable_TriggerPopover>
+ * ```
+ */
+export const ComposerPrimitiveTriggerPopoverAction: FC<
+  ComposerPrimitiveTriggerPopoverAction.Props
+> = ({ formatter, onExecute, removeOnExecute }) => {
+  const { register } = useTriggerBehaviorRegistration();
+  const onExecuteRef = useRef(onExecute);
+  onExecuteRef.current = onExecute;
+
+  useEffect(() => {
+    const behavior: TriggerBehavior = {
+      kind: "action",
+      formatter: formatter ?? unstable_defaultDirectiveFormatter,
+      onExecute: (item) => onExecuteRef.current(item),
+      ...(removeOnExecute !== undefined ? { removeOnExecute } : {}),
+    };
+    return register(behavior);
+  }, [register, formatter, removeOnExecute]);
+
+  return null;
+};
+
+ComposerPrimitiveTriggerPopoverAction.displayName =
+  "ComposerPrimitive.TriggerPopoverAction";

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

@@ -7,7 +7,7 @@ import {
   forwardRef,
 } from "react";
 import { composeEventHandlers } from "@radix-ui/primitive";
-import { useTriggerPopoverContext } from "./TriggerPopoverContext";
+import { useTriggerPopoverScopeContext } from "./TriggerPopover";
 
 export namespace ComposerPrimitiveTriggerPopoverBack {
   export type Element = ComponentRef<typeof Primitive.button>;
@@ -22,9 +22,10 @@ export const ComposerPrimitiveTriggerPopoverBack = forwardRef<
   ComposerPrimitiveTriggerPopoverBack.Element,
   ComposerPrimitiveTriggerPopoverBack.Props
 >(({ onClick, ...props }, forwardedRef) => {
-  const { activeCategoryId, isSearchMode, goBack } = useTriggerPopoverContext();
+  const { activeCategoryId, isSearchMode, goBack, open } =
+    useTriggerPopoverScopeContext();
 
-  if (!activeCategoryId || isSearchMode) return null;
+  if (!open || !activeCategoryId || isSearchMode) return null;
 
   return (
     <Primitive.button