Carry the menu popup contract onto the composer quick pills

The 插件 / 设计百宝箱 pills open the standalone `role="menu"` popovers in
ChatComposer, but they arrived without the contract of the ComposerPlusMenu rows
they replaced: no `aria-haspopup` / `aria-expanded`, no Escape handler, and no
focus return. Keyboard and screen-reader users could not tell a popup was open,
and Escape pressed while focus sat in the plugin search did nothing.

The pills live in ChatPane while the popovers live in ChatComposer, so the state
is plumbed both ways rather than duplicated:

- `onStandalonePanelChange` reports which popover is open, and each pill carries
  `aria-haspopup="menu"` plus its own `aria-expanded` — the same pair
  `ComposerPlusMenu` already puts on its trigger. No `aria-controls`: that
  surface does not use one, and this is not the place to invent a second
  convention.
- `openDesignToolbox` / `openPluginsPanel` take the opening pill as the
  return-focus target. Both popovers move focus inside themselves, so a
  dismissal has to hand it back, and the pill is the control the user came from.
- Escape closes through a document-level handler, mirroring ComposerPlusMenu's.

`dismissStandalonePanels` is deliberately only wired to the dismissal paths
(Escape, backdrop). Picking a plugin or an action keeps the plain setters,
because those hand focus to the composer input and pulling it back to the pill
would fight that.

No interaction changes: hover-open, the shared close timer, pill-to-popup
pointer travel and every selection path behave exactly as before.

Red first: `tests/components/ChatPane.quick-pill-popup-contract.test.tsx` runs
both pills through advertise / expand / Escape-from-inside / backdrop-dismiss and
asserts focus lands back on the pill. All six cases failed before this change.

Author: lefarcen

apps/web/src/components/ChatComposer.tsx

@@ -273,6 +273,10 @@ interface Props {
   // ChatPane → ProjectView → App. Omitted → the add rows are hidden.
   onBrowsePlugins?: () => void;
   onOpenConnectors?: () => void;
+  /** Reports which standalone quick-pill popover is open (null when none), so
+   *  the host that renders the pills can carry `aria-expanded` on them. The
+   *  popovers live here but their triggers do not. */
+  onStandalonePanelChange?: (panel: ComposerStandalonePanel) => void;
   // Optional pet wiring. The composer no longer renders a visible pet
   // entry, but existing manual `/pet` commands still route here.
   petConfig?: AppConfig['pet'];
@@ -347,6 +351,9 @@ export interface ChatComposerDraftOptions {
   sessionMode?: ChatSessionMode;
 }
 
+/** Which of the two standalone quick-pill popovers is open, if either. */
+export type ComposerStandalonePanel = 'plugins' | 'toolbox' | null;
+
 export interface ChatComposerHandle {
   setDraft: (text: string, options?: ChatComposerDraftOptions) => void;
   restoreDraft: (draft: {
@@ -377,11 +384,13 @@ export interface ChatComposerHandle {
    */
   applyDesignToolboxSkill: (skillId: string) => void;
   /** Open the standalone toolbox popover (the 设计百宝箱 quick pill above the
-   *  composer input; the "+" menu no longer carries a toolbox row). */
-  openDesignToolbox: () => void;
+   *  composer input; the "+" menu no longer carries a toolbox row). `opener` is
+   *  the control focus returns to when the popover is dismissed. */
+  openDesignToolbox: (opener?: HTMLElement | null) => void;
   /** Open the standalone plugins popover (the 插件 quick pill above the
-   *  composer input; the "+" menu no longer carries a plugins row). */
-  openPluginsPanel: () => void;
+   *  composer input; the "+" menu no longer carries a plugins row). `opener` is
+   *  the control focus returns to when the popover is dismissed. */
+  openPluginsPanel: (opener?: HTMLElement | null) => void;
   /** Schedule closing whichever standalone popover is open (hover-leave from
    *  a quick pill); re-opening or hovering the popup cancels it. */
   scheduleComposerPanelClose: () => void;
@@ -447,6 +456,7 @@ export const ChatComposer = forwardRef<ChatComposerHandle, Props>(
       onStop,
       onOpenMcpSettings,
       onBrowsePlugins,
+      onStandalonePanelChange,
       onOpenConnectors,
       petConfig,
       onAdoptPet,
@@ -557,6 +567,43 @@ export const ChatComposer = forwardRef<ChatComposerHandle, Props>(
     useEffect(() => () => {
       if (panelCloseTimerRef.current) clearTimeout(panelCloseTimerRef.current);
     }, []);
+    // The quick pill a standalone popover was opened from. Both popovers move
+    // focus inside themselves (the plugins pane autofocuses its search box), so
+    // a dismissal has to hand focus back — the pill lives in the host above the
+    // composer and is the only control still mounted afterwards.
+    const panelOpenerRef = useRef<HTMLElement | null>(null);
+    /** Close whichever standalone popover is open BECAUSE THE USER DISMISSED IT
+     *  (Escape, backdrop) and return focus to the pill that opened it. Paths
+     *  where the user picked something keep the plain setters: the composer
+     *  takes focus there, and pulling it back to the pill would fight that. */
+    function dismissStandalonePanels() {
+      cancelComposerPanelClose();
+      setPluginsPanelOpen(false);
+      setDesignToolboxOpen(false);
+      const opener = panelOpenerRef.current;
+      panelOpenerRef.current = null;
+      opener?.focus();
+    }
+    const openStandalonePanel: ComposerStandalonePanel = designToolboxOpen
+      ? 'toolbox'
+      : pluginsPanelOpen
+        ? 'plugins'
+        : null;
+    useEffect(() => {
+      onStandalonePanelChange?.(openStandalonePanel);
+    }, [onStandalonePanelChange, openStandalonePanel]);
+    // Escape closes the popover, matching ComposerPlusMenu's own document-level
+    // handler. Without it, Escape pressed while focus sat in the plugin search
+    // did nothing at all.
+    useEffect(() => {
+      if (openStandalonePanel == null) return;
+      function onKey(event: KeyboardEvent) {
+        if (event.key !== 'Escape') return;
+        dismissStandalonePanels();
+      }
+      document.addEventListener('keydown', onKey);
+      return () => document.removeEventListener('keydown', onKey);
+    }, [openStandalonePanel]);
     // External "+"-menu open request (next-step quick pills) — nonce-keyed so
     // every pill click re-opens even after the menu was dismissed.
     const [plusMenuOpenRequest, setPlusMenuOpenRequest] = useState<
@@ -1157,17 +1204,19 @@ export const ChatComposer = forwardRef<ChatComposerHandle, Props>(
           pendingEntryFromRef.current = 'next_step';
           applyDesignToolboxSkillByIdRef.current(skillId);
         },
-        openDesignToolbox: () => {
+        openDesignToolbox: (opener?: HTMLElement | null) => {
           cancelComposerPanelClose();
           setComposerEngaged(true);
+          panelOpenerRef.current = opener ?? null;
           // The two popovers share one anchor spot — opening one closes the
           // other so hover-switching between the pills swaps panels.
           setPluginsPanelOpen(false);
           setDesignToolboxOpen(true);
         },
-        openPluginsPanel: () => {
+        openPluginsPanel: (opener?: HTMLElement | null) => {
           cancelComposerPanelClose();
           setComposerEngaged(true);
+          panelOpenerRef.current = opener ?? null;
           setDesignToolboxOpen(false);
           setPluginsPanelOpen(true);
         },
@@ -2761,7 +2810,7 @@ export const ChatComposer = forwardRef<ChatComposerHandle, Props>(
             <div
               className="composer-toolbox-standalone-backdrop"
               aria-hidden="true"
-              onClick={() => setDesignToolboxOpen(false)}
+              onClick={dismissStandalonePanels}
             />
             <div
               className="plus-menu__popup composer-toolbox-standalone-popup"
@@ -2820,7 +2869,7 @@ export const ChatComposer = forwardRef<ChatComposerHandle, Props>(
             <div
               className="composer-toolbox-standalone-backdrop"
               aria-hidden="true"
-              onClick={() => setPluginsPanelOpen(false)}
+              onClick={dismissStandalonePanels}
             />
             <div
               className="plus-menu__popup composer-toolbox-standalone-popup composer-plugins-standalone-popup"

apps/web/src/components/ChatPane.tsx

@@ -88,6 +88,7 @@ import {
   type ChatComposerHandle,
   type ChatSendOutcome,
   type ChatSendMeta,
+  type ComposerStandalonePanel,
 } from './ChatComposer';
 import type { PlaceholderScenario } from './home-hero/placeholderScenarios';
 import { listDesignArtifactCandidates } from './design-files/designArtifacts';
@@ -966,6 +967,14 @@ export function ChatPane({
   const chatLogScrollIdleTimerRef = useRef<number | null>(null);
   const historyWrapRef = useRef<HTMLDivElement | null>(null);
   const composerRef = useRef<ChatComposerHandle | null>(null);
+  // The 插件 / 设计百宝箱 quick pills. The popovers they open live inside
+  // ChatComposer, so the pills need both a way to report their expanded state
+  // and a stable identity for the popover to return focus to.
+  const quickPillRefs = {
+    plugins: useRef<HTMLButtonElement | null>(null),
+    toolbox: useRef<HTMLButtonElement | null>(null),
+  };
+  const [openComposerPanel, setOpenComposerPanel] = useState<ComposerStandalonePanel>(null);
   const composerSlotRef = useRef<HTMLDivElement | null>(null);
   const composerLayerRef = useRef<HTMLDivElement | null>(null);
   const pinnedTodoRef = useRef<HTMLDivElement | null>(null);
@@ -1079,8 +1088,11 @@ export function ChatPane({
       clearTimeout(pillHoverTimerRef.current);
       pillHoverTimerRef.current = null;
     }
-    if (which === 'toolbox') composerRef.current?.openDesignToolbox();
-    else composerRef.current?.openPluginsPanel();
+    // Hand the pill down as the popover's return-focus target: it opens a
+    // surface that takes focus, and it is the control the user came from.
+    const opener = quickPillRefs[which].current;
+    if (which === 'toolbox') composerRef.current?.openDesignToolbox(opener);
+    else composerRef.current?.openPluginsPanel(opener);
   }, []);
   const handleQuickPillHoverEnter = useCallback((which: 'plugins' | 'toolbox') => {
     if (pillHoverTimerRef.current) clearTimeout(pillHoverTimerRef.current);
@@ -2152,9 +2164,12 @@ export function ChatPane({
           data-testid="composer-quick-pills"
         >
           <button
+            ref={quickPillRefs.plugins}
             type="button"
             className={nextStepStyles.quickPill}
             data-testid="next-step-quick-pill-plugins"
+            aria-haspopup="menu"
+            aria-expanded={openComposerPanel === 'plugins'}
             onClick={() => handleNextStepOpenComposerPanel('plugins')}
             onMouseEnter={() => handleQuickPillHoverEnter('plugins')}
             onMouseLeave={handleQuickPillHoverLeave}
@@ -2163,9 +2178,12 @@ export function ChatPane({
             <span>{t('entry.navPlugins')}</span>
           </button>
           <button
+            ref={quickPillRefs.toolbox}
             type="button"
             className={nextStepStyles.quickPill}
             data-testid="next-step-quick-pill-toolbox"
+            aria-haspopup="menu"
+            aria-expanded={openComposerPanel === 'toolbox'}
             onClick={() => handleNextStepOpenComposerPanel('toolbox')}
             onMouseEnter={() => handleQuickPillHoverEnter('toolbox')}
             onMouseLeave={handleQuickPillHoverLeave}
@@ -2231,6 +2249,7 @@ export function ChatPane({
       onOpenSettings={onOpenSettings}
       onOpenMcpSettings={onOpenMcpSettings}
       onBrowsePlugins={onBrowsePlugins}
+      onStandalonePanelChange={setOpenComposerPanel}
       onOpenConnectors={onOpenConnectors}
       petConfig={petConfig}
       onAdoptPet={onAdoptPet}

apps/web/tests/components/ChatPane.quick-pill-popup-contract.test.tsx

@@ -0,0 +1,113 @@
+// @vitest-environment jsdom
+//
+// The 插件 / 设计百宝箱 quick pills above the composer input open the standalone
+// `role="menu"` popovers in ChatComposer. They replaced rows that used to live
+// in ComposerPlusMenu, but arrived without that surface's keyboard/AT contract:
+// no `aria-haspopup` / `aria-expanded` on the pill, no Escape handler, and no
+// focus return — so Escape pressed inside the plugin search did nothing and
+// keyboard users could not tell the popup was open.
+//
+// This pins the contract ComposerPlusMenu already ships (`aria-haspopup="menu"`
+// plus `aria-expanded`, Escape closes) and the focus return the pills need on
+// top of it: the popovers move focus inside themselves, so closing has to hand
+// it back to the pill that opened them.
+
+// jsdom has no HTMLElement.scrollTo; ChatPane's log calls it on mount.
+if (typeof HTMLElement.prototype.scrollTo !== 'function') {
+  HTMLElement.prototype.scrollTo = function () {};
+}
+
+import { act, cleanup, fireEvent, render, screen } from '@testing-library/react';
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { ChatPane } from '../../src/components/ChatPane';
+
+function renderChatPane() {
+  return render(
+    <ChatPane
+      messages={[]}
+      streaming={false}
+      error={null}
+      projectId="project-1"
+      projectFiles={[]}
+      onEnsureProject={async () => 'project-1'}
+      onSend={() => {}}
+      onStop={() => {}}
+      conversations={[]}
+      activeConversationId={null}
+      onSelectConversation={() => {}}
+      onDeleteConversation={() => {}}
+    />,
+  );
+}
+
+function pill(which: 'plugins' | 'toolbox'): HTMLElement {
+  return screen.getByTestId(`next-step-quick-pill-${which}`);
+}
+
+function standalonePopup(): HTMLElement | null {
+  return document.querySelector<HTMLElement>('.composer-toolbox-standalone-popup');
+}
+
+afterEach(() => {
+  cleanup();
+});
+
+describe.each([
+  { which: 'plugins' as const, label: '插件' },
+  { which: 'toolbox' as const, label: '设计百宝箱' },
+])('composer quick pill popup contract — $label', ({ which }) => {
+  it('advertises the menu it owns and flips expanded as it opens', () => {
+    renderChatPane();
+    const trigger = pill(which);
+
+    expect(trigger.getAttribute('aria-haspopup')).toBe('menu');
+    expect(trigger.getAttribute('aria-expanded')).toBe('false');
+
+    act(() => {
+      fireEvent.click(trigger);
+    });
+
+    expect(standalonePopup()).not.toBeNull();
+    expect(pill(which).getAttribute('aria-expanded')).toBe('true');
+  });
+
+  it('closes on Escape from inside the menu and returns focus to the pill', () => {
+    renderChatPane();
+    const trigger = pill(which);
+
+    act(() => {
+      fireEvent.click(trigger);
+    });
+    const popup = standalonePopup();
+    expect(popup).not.toBeNull();
+
+    // Focus starts inside the popover (the plugin pane autofocuses its search
+    // box), which is exactly why the close path has to restore it.
+    act(() => {
+      popup!.focus();
+      fireEvent.keyDown(document, { key: 'Escape' });
+    });
+
+    expect(standalonePopup()).toBeNull();
+    expect(pill(which).getAttribute('aria-expanded')).toBe('false');
+    expect(document.activeElement).toBe(pill(which));
+  });
+
+  it('returns focus to the pill when the backdrop dismisses the menu', () => {
+    renderChatPane();
+
+    act(() => {
+      fireEvent.click(pill(which));
+    });
+    const backdrop = document.querySelector<HTMLElement>('.composer-toolbox-standalone-backdrop');
+    expect(backdrop).not.toBeNull();
+
+    act(() => {
+      fireEvent.click(backdrop!);
+    });
+
+    expect(standalonePopup()).toBeNull();
+    expect(document.activeElement).toBe(pill(which));
+  });
+});