@assistant-ui/react 0.14.0 → 0.14.3

package/src/primitives/composer/ComposerInput.tsx

@@ -23,6 +23,7 @@ import { useOnScrollToBottom } from "../../utils/hooks/useOnScrollToBottom";
 import { useAuiState, useAui } from "@assistant-ui/store";
 import { flushResourcesSync } from "@assistant-ui/tap";
 import { useComposerInputPluginRegistryOptional } from "./ComposerInputPluginContext";
+import { useTriggerPopoverActiveAriaOptional } from "./trigger/TriggerPopoverRootContext";
 
 export namespace ComposerPrimitiveInput {
   export type Element = HTMLTextAreaElement;
@@ -100,6 +101,12 @@ export namespace ComposerPrimitiveInput {
  * keyboard shortcuts, file paste support, and intelligent focus management.
  * It integrates with the composer context to manage message state and submission.
  *
+ * When rendered inside `Unstable_TriggerPopoverRoot` and a popover is open, the
+ * underlying `<textarea>` automatically receives `aria-controls`,
+ * `aria-expanded`, `aria-haspopup`, and `aria-activedescendant` for the
+ * combobox relationship. These computed attributes override user-provided
+ * values for those four ARIA props while the popover is open.
+ *
  * @example
  * ```tsx
  * // Ctrl/Cmd+Enter to submit (plain Enter inserts newline)
@@ -142,6 +149,7 @@ export const ComposerPrimitiveInput = forwardRef<
   ) => {
     const aui = useAui();
     const pluginRegistry = useComposerInputPluginRegistryOptional();
+    const activeAria = useTriggerPopoverActiveAriaOptional();
 
     const effectiveSubmitMode =
       submitMode ?? (submitOnEnter === false ? "none" : "enter");
@@ -197,13 +205,13 @@ export const ComposerPrimitiveInput = forwardRef<
         const threadState = aui.thread().getState();
         const hasQueue = threadState.capabilities.queue;
 
-        // Steer hotkey: Cmd/Ctrl+Shift+Enter (respects submitMode="none" and isEmpty)
+        // Steer hotkey: Cmd/Ctrl+Shift+Enter (respects submitMode="none" and canSend)
         if (
           e.shiftKey &&
           (e.ctrlKey || e.metaKey) &&
           hasQueue &&
           effectiveSubmitMode !== "none" &&
-          !aui.composer().getState().isEmpty
+          aui.composer().getState().canSend
         ) {
           e.preventDefault();
           aui.composer().send({ steer: true });
@@ -287,10 +295,20 @@ export const ComposerPrimitiveInput = forwardRef<
       return aui.on("threadListItem.switchedTo", focus);
     }, [unstable_focusOnThreadSwitched, focus, aui]);
 
+    const ariaComboboxProps = activeAria
+      ? {
+          "aria-controls": activeAria.popoverId,
+          "aria-expanded": true as const,
+          "aria-haspopup": "listbox" as const,
+          "aria-activedescendant": activeAria.highlightedItemId,
+        }
+      : {};
+
     const inputProps = {
       name: "input" as const,
       value,
       ...rest,
+      ...ariaComboboxProps,
       ref: ref as React.ForwardedRef<HTMLTextAreaElement>,
       disabled: isDisabled,
       onChange: composeEventHandlers(

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

@@ -23,7 +23,10 @@ import {
   type TriggerPopoverResourceOutput,
 } from "./TriggerPopoverResource";
 import type { TriggerBehavior } from "./triggerSelectionResource";
-import { useTriggerPopoverRootContext } from "./TriggerPopoverRootContext";
+import {
+  useTriggerPopoverAriaPublish,
+  useTriggerPopoverRootContext,
+} from "./TriggerPopoverRootContext";
 
 const TriggerPopoverScopeContext =
   createContext<TriggerPopoverResourceOutput | null>(null);
@@ -179,6 +182,23 @@ export const ComposerPrimitiveTriggerPopover = forwardRef<
 
     const open = behavior !== null && resource.open;
 
+    const aria = useTriggerPopoverAriaPublish();
+
+    useEffect(() => {
+      if (!open) return undefined;
+      return () => {
+        aria.setActiveAria(char, null);
+      };
+    }, [aria, char, open]);
+
+    useEffect(() => {
+      if (!open) return;
+      aria.setActiveAria(char, {
+        popoverId,
+        highlightedItemId: resource.highlightedItemId,
+      });
+    }, [aria, char, popoverId, open, resource.highlightedItemId]);
+
     return (
       <TriggerBehaviorRegistrationContext.Provider value={registration}>
         <TriggerPopoverScopeContext.Provider value={resource}>

package/src/primitives/composer/trigger/TriggerPopoverRootContext.test.tsx

@@ -0,0 +1,152 @@
+/**
+ * @vitest-environment jsdom
+ */
+import { act, type FC } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import {
+  ComposerPrimitiveTriggerPopoverRoot,
+  type TriggerPopoverActiveAria,
+  useTriggerPopoverActiveAriaOptional,
+  useTriggerPopoverAriaPublish,
+} from "./TriggerPopoverRootContext";
+
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+
+type PublishHandle = ReturnType<typeof useTriggerPopoverAriaPublish>;
+
+describe("TriggerPopoverRootContext active ARIA", () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(() => {
+    container = document.createElement("div");
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(async () => {
+    await act(async () => {
+      root.unmount();
+    });
+    container.remove();
+  });
+
+  const renderWithRoot = async () => {
+    const publishRef = { current: null as PublishHandle | null };
+    const ariaRef = { current: null as TriggerPopoverActiveAria | null };
+
+    const Probe: FC = () => {
+      publishRef.current = useTriggerPopoverAriaPublish();
+      ariaRef.current = useTriggerPopoverActiveAriaOptional();
+      return null;
+    };
+
+    await act(async () => {
+      root.render(
+        <ComposerPrimitiveTriggerPopoverRoot>
+          <Probe />
+        </ComposerPrimitiveTriggerPopoverRoot>,
+      );
+    });
+
+    return {
+      publish: () => publishRef.current as PublishHandle,
+      aria: () => ariaRef.current,
+    };
+  };
+
+  it("returns null initially inside a root", async () => {
+    const { aria } = await renderWithRoot();
+    expect(aria()).toBeNull();
+  });
+
+  it("publishes a descriptor and surfaces it via the hook", async () => {
+    const { publish, aria } = await renderWithRoot();
+
+    await act(async () => {
+      publish().setActiveAria("@", {
+        popoverId: "popover-mention",
+        highlightedItemId: "popover-mention-option-a",
+      });
+    });
+
+    expect(aria()).toEqual({
+      popoverId: "popover-mention",
+      highlightedItemId: "popover-mention-option-a",
+    });
+  });
+
+  it("clears the descriptor when the owning char releases it", async () => {
+    const { publish, aria } = await renderWithRoot();
+
+    await act(async () => {
+      publish().setActiveAria("@", {
+        popoverId: "popover-mention",
+        highlightedItemId: undefined,
+      });
+    });
+    expect(aria()).not.toBeNull();
+
+    await act(async () => {
+      publish().setActiveAria("@", null);
+    });
+    expect(aria()).toBeNull();
+  });
+
+  it("ignores a clear call from a non-owning char", async () => {
+    const { publish, aria } = await renderWithRoot();
+
+    await act(async () => {
+      publish().setActiveAria("@", {
+        popoverId: "popover-mention",
+        highlightedItemId: undefined,
+      });
+    });
+
+    await act(async () => {
+      publish().setActiveAria("/", null);
+    });
+
+    expect(aria()).toEqual({
+      popoverId: "popover-mention",
+      highlightedItemId: undefined,
+    });
+  });
+
+  it("replaces the descriptor when a different char takes over", async () => {
+    const { publish, aria } = await renderWithRoot();
+
+    await act(async () => {
+      publish().setActiveAria("@", {
+        popoverId: "popover-mention",
+        highlightedItemId: "popover-mention-option-a",
+      });
+    });
+    await act(async () => {
+      publish().setActiveAria("/", {
+        popoverId: "popover-slash",
+        highlightedItemId: "popover-slash-option-x",
+      });
+    });
+
+    expect(aria()).toEqual({
+      popoverId: "popover-slash",
+      highlightedItemId: "popover-slash-option-x",
+    });
+  });
+
+  it("returns null when the consumer is rendered outside a root", async () => {
+    const ariaRef = { current: null as TriggerPopoverActiveAria | null };
+    const Solo: FC = () => {
+      ariaRef.current = useTriggerPopoverActiveAriaOptional();
+      return null;
+    };
+
+    await act(async () => {
+      root.render(<Solo />);
+    });
+
+    expect(ariaRef.current).toBeNull();
+  });
+});

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

@@ -29,17 +29,43 @@ export type TriggerPopoverLifecycleListener = {
   removed(char: string): void;
 };
 
+/**
+ * ARIA descriptor of the popover that is currently open. Consumed by the
+ * focused element (typically the composer textarea) so it can advertise the
+ * combobox relationship per the WAI-ARIA editable combobox pattern.
+ */
+export type TriggerPopoverActiveAria = {
+  popoverId: string;
+  highlightedItemId: string | undefined;
+};
+
 export type TriggerPopoverRootContextValue = {
   register(trigger: RegisteredTrigger): () => void;
   getTriggers(): ReadonlyMap<string, RegisteredTrigger>;
   subscribe(listener: () => void): () => void;
   /** Subscribe to per-trigger add/remove events. */
   subscribeLifecycle(listener: TriggerPopoverLifecycleListener): () => void;
+  /** ARIA descriptor of the open popover, or null if none is open. */
+  getActiveAria(): TriggerPopoverActiveAria | null;
+  /** Subscribe to changes in the active ARIA descriptor. */
+  subscribeAria(listener: () => void): () => void;
+};
+
+/**
+ * Write-side of the ARIA descriptor, scoped to `TriggerPopover` children of a
+ * `TriggerPopoverRoot`. Intentionally not exposed on the public root context
+ * value: external consumers can read ARIA state but cannot publish or clear it.
+ */
+type TriggerPopoverAriaPublish = {
+  setActiveAria(char: string, aria: TriggerPopoverActiveAria | null): void;
 };
 
 const TriggerPopoverRootContext =
   createContext<TriggerPopoverRootContextValue | null>(null);
 
+const TriggerPopoverAriaPublishContext =
+  createContext<TriggerPopoverAriaPublish | null>(null);
+
 export const useTriggerPopoverRootContext = () => {
   const ctx = useContext(TriggerPopoverRootContext);
   if (!ctx)
@@ -52,6 +78,19 @@ export const useTriggerPopoverRootContext = () => {
 export const useTriggerPopoverRootContextOptional = () =>
   useContext(TriggerPopoverRootContext);
 
+/**
+ * Internal hook used by `TriggerPopover` children to publish their open and
+ * highlight state. Not exported from the trigger module.
+ */
+export const useTriggerPopoverAriaPublish = (): TriggerPopoverAriaPublish => {
+  const ctx = useContext(TriggerPopoverAriaPublishContext);
+  if (!ctx)
+    throw new Error(
+      "useTriggerPopoverAriaPublish must be used within ComposerPrimitive.TriggerPopoverRoot",
+    );
+  return ctx;
+};
+
 /**
  * Live map of registered triggers, re-rendering on change. Prefer
  * `subscribeLifecycle` for incremental add/remove handling.
@@ -75,24 +114,57 @@ export const useTriggerPopoverTriggersOptional = () => {
   );
 };
 
+const getNullAria = () => null;
+
+/**
+ * Returns the ARIA descriptor of the currently open trigger popover, or
+ * `null` if none is open or the consumer is rendered outside a
+ * `TriggerPopoverRoot`.
+ */
+export const useTriggerPopoverActiveAriaOptional =
+  (): TriggerPopoverActiveAria | null => {
+    const ctx = useTriggerPopoverRootContextOptional();
+    return useSyncExternalStore(
+      ctx ? ctx.subscribeAria : noopSubscribe,
+      ctx ? ctx.getActiveAria : getNullAria,
+      ctx ? ctx.getActiveAria : getNullAria,
+    );
+  };
+
 export namespace ComposerPrimitiveTriggerPopoverRoot {
   export type Props = {
     children: ReactNode;
   };
 }
 
+/**
+ * Local helper for the simple "notify-all listeners" subscribable pattern.
+ * Used twice in this file (trigger registry, active ARIA); kept inline to
+ * avoid pulling a single-use abstraction into the wider tree.
+ */
+function useSimpleSubscribable() {
+  const listenersRef = useRef<Set<() => void>>(new Set());
+  const notify = useCallback(() => {
+    for (const listener of listenersRef.current) listener();
+  }, []);
+  const subscribe = useCallback((listener: () => void) => {
+    listenersRef.current.add(listener);
+    return () => {
+      listenersRef.current.delete(listener);
+    };
+  }, []);
+  return { notify, subscribe };
+}
+
 const TriggerPopoverRootInner: FC<
   ComposerPrimitiveTriggerPopoverRoot.Props
 > = ({ children }) => {
   const triggersRef = useRef<ReadonlyMap<string, RegisteredTrigger>>(new Map());
-  const listenersRef = useRef<Set<() => void>>(new Set());
   const lifecycleListenersRef = useRef<Set<TriggerPopoverLifecycleListener>>(
     new Set(),
   );
 
-  const notify = useCallback(() => {
-    for (const listener of listenersRef.current) listener();
-  }, []);
+  const { notify, subscribe } = useSimpleSubscribable();
 
   const register = useCallback<TriggerPopoverRootContextValue["register"]>(
     (trigger) => {
@@ -137,16 +209,6 @@ const TriggerPopoverRootInner: FC<
     TriggerPopoverRootContextValue["getTriggers"]
   >(() => triggersRef.current, []);
 
-  const subscribe = useCallback<TriggerPopoverRootContextValue["subscribe"]>(
-    (listener) => {
-      listenersRef.current.add(listener);
-      return () => {
-        listenersRef.current.delete(listener);
-      };
-    },
-    [],
-  );
-
   const subscribeLifecycle = useCallback<
     TriggerPopoverRootContextValue["subscribeLifecycle"]
   >((listener) => {
@@ -156,14 +218,69 @@ const TriggerPopoverRootInner: FC<
     };
   }, []);
 
+  const activeAriaRef = useRef<TriggerPopoverActiveAria | null>(null);
+  const activeAriaCharRef = useRef<string | null>(null);
+  const { notify: notifyAria, subscribe: subscribeAria } =
+    useSimpleSubscribable();
+
+  const setActiveAria = useCallback<TriggerPopoverAriaPublish["setActiveAria"]>(
+    (char, aria) => {
+      if (aria === null) {
+        if (activeAriaCharRef.current !== char) return;
+        activeAriaRef.current = null;
+        activeAriaCharRef.current = null;
+        notifyAria();
+        return;
+      }
+      const prev = activeAriaRef.current;
+      if (
+        activeAriaCharRef.current === char &&
+        prev !== null &&
+        prev.popoverId === aria.popoverId &&
+        prev.highlightedItemId === aria.highlightedItemId
+      ) {
+        return;
+      }
+      activeAriaRef.current = aria;
+      activeAriaCharRef.current = char;
+      notifyAria();
+    },
+    [notifyAria],
+  );
+
+  const getActiveAria = useCallback<
+    TriggerPopoverRootContextValue["getActiveAria"]
+  >(() => activeAriaRef.current, []);
+
   const value = useMemo<TriggerPopoverRootContextValue>(
-    () => ({ register, getTriggers, subscribe, subscribeLifecycle }),
-    [register, getTriggers, subscribe, subscribeLifecycle],
+    () => ({
+      register,
+      getTriggers,
+      subscribe,
+      subscribeLifecycle,
+      getActiveAria,
+      subscribeAria,
+    }),
+    [
+      register,
+      getTriggers,
+      subscribe,
+      subscribeLifecycle,
+      getActiveAria,
+      subscribeAria,
+    ],
+  );
+
+  const ariaPublishValue = useMemo<TriggerPopoverAriaPublish>(
+    () => ({ setActiveAria }),
+    [setActiveAria],
   );
 
   return (
     <TriggerPopoverRootContext.Provider value={value}>
-      {children}
+      <TriggerPopoverAriaPublishContext.Provider value={ariaPublishValue}>
+        {children}
+      </TriggerPopoverAriaPublishContext.Provider>
     </TriggerPopoverRootContext.Provider>
   );
 };

package/src/primitives/composer/trigger/triggerKeyboardResource.test.ts

@@ -0,0 +1,236 @@
+import { describe, it, expect, vi } from "vitest";
+import { createResourceRoot } from "@assistant-ui/tap";
+import type {
+  Unstable_TriggerCategory,
+  Unstable_TriggerItem,
+} from "@assistant-ui/core";
+import { TriggerKeyboardResource } from "./triggerKeyboardResource";
+
+const item = (id: string): Unstable_TriggerItem => ({
+  id,
+  type: "command",
+  label: id,
+});
+
+const category = (id: string): Unstable_TriggerCategory => ({
+  id,
+  label: id,
+});
+
+const makeKeyEvent = (key: string, shiftKey = false) => ({
+  key,
+  shiftKey,
+  preventDefault: vi.fn(),
+});
+
+const tick = () => new Promise<void>((resolve) => setTimeout(resolve, 0));
+
+const render = (
+  overrides: Partial<Parameters<typeof TriggerKeyboardResource>[0]> = {},
+) => {
+  const props = {
+    navigableList: [item("a"), item("b"), item("c")],
+    isSearchMode: false,
+    activeCategoryId: null as string | null,
+    query: "",
+    popoverId: "popover",
+    open: true,
+    selectItem: vi.fn(),
+    selectCategory: vi.fn(),
+    goBack: vi.fn(),
+    close: vi.fn(),
+    ...overrides,
+  };
+  const root = createResourceRoot();
+  const sub = root.render(TriggerKeyboardResource(props));
+  return { sub, props };
+};
+
+describe("TriggerKeyboardResource", () => {
+  it("selects highlighted item on Tab", () => {
+    const { sub, props } = render();
+    const e = makeKeyEvent("Tab");
+
+    const consumed = sub.getValue().handleKeyDown(e);
+
+    expect(consumed).toBe(true);
+    expect(e.preventDefault).toHaveBeenCalled();
+    expect(props.selectItem).toHaveBeenCalledWith(props.navigableList[0]);
+    expect(props.selectCategory).not.toHaveBeenCalled();
+  });
+
+  it("selects category on Tab when entry is a category", () => {
+    const { sub, props } = render({
+      navigableList: [category("cat-1"), item("b")],
+    });
+
+    const consumed = sub.getValue().handleKeyDown(makeKeyEvent("Tab"));
+
+    expect(consumed).toBe(true);
+    expect(props.selectCategory).toHaveBeenCalledWith("cat-1");
+    expect(props.selectItem).not.toHaveBeenCalled();
+  });
+
+  it("lets Shift+Tab pass through for native focus traversal", () => {
+    const { sub, props } = render();
+    const e = makeKeyEvent("Tab", true);
+
+    const consumed = sub.getValue().handleKeyDown(e);
+
+    expect(consumed).toBe(false);
+    expect(e.preventDefault).not.toHaveBeenCalled();
+    expect(props.selectItem).not.toHaveBeenCalled();
+  });
+
+  it("swallows Tab when the navigable list is empty", () => {
+    const { sub, props } = render({ navigableList: [] });
+    const e = makeKeyEvent("Tab");
+
+    const consumed = sub.getValue().handleKeyDown(e);
+
+    expect(consumed).toBe(true);
+    expect(e.preventDefault).toHaveBeenCalled();
+    expect(props.selectItem).not.toHaveBeenCalled();
+    expect(props.selectCategory).not.toHaveBeenCalled();
+  });
+
+  it("does nothing when the popover is closed", () => {
+    const { sub, props } = render({ open: false });
+    const e = makeKeyEvent("Tab");
+
+    const consumed = sub.getValue().handleKeyDown(e);
+
+    expect(consumed).toBe(false);
+    expect(e.preventDefault).not.toHaveBeenCalled();
+    expect(props.selectItem).not.toHaveBeenCalled();
+  });
+
+  it("moves the highlight forward on ArrowDown", async () => {
+    const { sub } = render();
+
+    const consumed = sub.getValue().handleKeyDown(makeKeyEvent("ArrowDown"));
+    await tick();
+
+    expect(consumed).toBe(true);
+    expect(sub.getValue().highlightedIndex).toBe(1);
+  });
+
+  it("wraps the highlight to the top on ArrowDown past the last entry", async () => {
+    const { sub } = render();
+    const handle = sub.getValue().handleKeyDown;
+
+    handle(makeKeyEvent("ArrowDown"));
+    handle(makeKeyEvent("ArrowDown"));
+    handle(makeKeyEvent("ArrowDown"));
+    await tick();
+
+    expect(sub.getValue().highlightedIndex).toBe(0);
+  });
+
+  it("moves the highlight backward on ArrowUp", async () => {
+    const { sub } = render();
+    const handle = sub.getValue().handleKeyDown;
+
+    handle(makeKeyEvent("ArrowDown"));
+    await tick();
+    handle(makeKeyEvent("ArrowUp"));
+    await tick();
+
+    expect(sub.getValue().highlightedIndex).toBe(0);
+  });
+
+  it("wraps the highlight to the bottom on ArrowUp from the first entry", async () => {
+    const { sub } = render();
+
+    sub.getValue().handleKeyDown(makeKeyEvent("ArrowUp"));
+    await tick();
+
+    expect(sub.getValue().highlightedIndex).toBe(2);
+  });
+
+  it("keeps the highlight at 0 on ArrowDown when navigableList is empty", async () => {
+    const { sub } = render({ navigableList: [] });
+    const e = makeKeyEvent("ArrowDown");
+
+    const consumed = sub.getValue().handleKeyDown(e);
+    await tick();
+
+    expect(consumed).toBe(true);
+    expect(e.preventDefault).toHaveBeenCalled();
+    expect(sub.getValue().highlightedIndex).toBe(0);
+  });
+
+  it("selects the highlighted item on Enter", () => {
+    const { sub, props } = render();
+    const e = makeKeyEvent("Enter");
+
+    const consumed = sub.getValue().handleKeyDown(e);
+
+    expect(consumed).toBe(true);
+    expect(e.preventDefault).toHaveBeenCalled();
+    expect(props.selectItem).toHaveBeenCalledWith(props.navigableList[0]);
+  });
+
+  it("lets Shift+Enter pass through for newline insertion", () => {
+    const { sub, props } = render();
+    const e = makeKeyEvent("Enter", true);
+
+    const consumed = sub.getValue().handleKeyDown(e);
+
+    expect(consumed).toBe(false);
+    expect(e.preventDefault).not.toHaveBeenCalled();
+    expect(props.selectItem).not.toHaveBeenCalled();
+  });
+
+  it("closes the popover on Escape", () => {
+    const { sub, props } = render();
+    const e = makeKeyEvent("Escape");
+
+    const consumed = sub.getValue().handleKeyDown(e);
+
+    expect(consumed).toBe(true);
+    expect(e.preventDefault).toHaveBeenCalled();
+    expect(props.close).toHaveBeenCalled();
+  });
+
+  it("drills back on Backspace when a category is active and the query is empty", () => {
+    const { sub, props } = render({
+      activeCategoryId: "cat-1",
+      query: "",
+    });
+    const e = makeKeyEvent("Backspace");
+
+    const consumed = sub.getValue().handleKeyDown(e);
+
+    expect(consumed).toBe(true);
+    expect(e.preventDefault).toHaveBeenCalled();
+    expect(props.goBack).toHaveBeenCalled();
+  });
+
+  it("lets Backspace pass through when the query is non-empty", () => {
+    const { sub, props } = render({
+      activeCategoryId: "cat-1",
+      query: "foo",
+    });
+    const e = makeKeyEvent("Backspace");
+
+    const consumed = sub.getValue().handleKeyDown(e);
+
+    expect(consumed).toBe(false);
+    expect(e.preventDefault).not.toHaveBeenCalled();
+    expect(props.goBack).not.toHaveBeenCalled();
+  });
+
+  it("lets Backspace pass through when no category is active", () => {
+    const { sub, props } = render({
+      activeCategoryId: null,
+      query: "",
+    });
+    const e = makeKeyEvent("Backspace");
+
+    const consumed = sub.getValue().handleKeyDown(e);
+
+    expect(consumed).toBe(false);
+    expect(props.goBack).not.toHaveBeenCalled();
+  });
+});