feat(DropdownMenu): anchorRef places the menu against an element other than its trigger

A menu that lines up with a box wider than its control, a toolbar or a
search row, could not: the layer anchored to the trigger, and renderTrigger's
one ref was the anchor, the focus target and the press target at once.

DropdownMenu now takes `anchorRef`, Popover's name and a ref object's shape:
the popover menu is placed against that element, with placement and
alignment read against it, and takes its width by default. The trigger
keeps focus and focus return, the press model, the keyboard opens and the
menu's name; only the layer's anchor moves, so a press elsewhere in the
anchor still dismisses the menu. The bottom sheet ignores it.

The draft DropdownMenu record proposes the Menu anchor concept, FR15 and
DEC-8 for the owner. Docs, a story (a search row whose Filter menu lines up
with the row), unit cases for the Button and a custom trigger, and a
real-Chromium spec for placement, width, dismissal, toggle, keys, focus
return and the press model.

Author: vjeux

.changeset/dropdown-menu-anchor-ref.md

@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[feat] `DropdownMenu` takes `anchorRef`, Popover's prop for an external anchor: the popover menu is placed against that element, with `placement` and `alignment` read against it, and takes its width by default, instead of the trigger's. A menu can now line up with a toolbar or a search row wider than its control, while the trigger keeps focus and focus return, the press model, the keyboard opens and the menu's name. The bottom-sheet presentation ignores it.
+
+@vjeux

apps/storybook/stories/DropdownMenu.stories.tsx

@@ -4,7 +4,8 @@ import type {Meta, StoryObj} from '@storybook/react';
 import * as stylex from '@stylexjs/stylex';
 import {Badge} from '@astryxdesign/core/Badge';
 import {IconButton} from '@astryxdesign/core/IconButton';
-import {useState} from 'react';
+import {TextInput} from '@astryxdesign/core/TextInput';
+import {useRef, useState} from 'react';
 import {
   DropdownMenu,
   DropdownMenuItem,
@@ -96,6 +97,25 @@ const readinessStyles = stylex.create({
   },
 });
 
+const anchorStoryStyles = stylex.create({
+  // A search row: a field and its Filter trigger. The menu lines up with the
+  // row, not with the trigger.
+  row: {
+    display: 'flex',
+    alignItems: 'center',
+    gap: spacingVars['--spacing-2'],
+    inlineSize: 360,
+    paddingBlockStart: spacingVars['--spacing-2'],
+    paddingBlockEnd: spacingVars['--spacing-2'],
+    paddingInlineStart: spacingVars['--spacing-2'],
+    paddingInlineEnd: spacingVars['--spacing-2'],
+  },
+  field: {
+    flexGrow: 1,
+    minInlineSize: 0,
+  },
+});
+
 const PROJECT_ACTIONS = [
   {
     label: 'Edit project',
@@ -1341,6 +1361,51 @@ export const CustomTrigger: Story = {
   },
 };
 
+export const AnchorRef: Story = {
+  name: 'Anchored to a row (anchorRef)',
+  render: function AnchorRefStory() {
+    const rowRef = useRef<HTMLDivElement>(null);
+    const [query, setQuery] = useState('');
+    const [showing, setShowing] = useState('Everything');
+    return (
+      <div>
+        <div
+          ref={rowRef}
+          data-testid="search-row"
+          {...stylex.props(anchorStoryStyles.row)}>
+          <div {...stylex.props(anchorStoryStyles.field)}>
+            <TextInput
+              label="Search"
+              isLabelHidden
+              placeholder="Search"
+              value={query}
+              onChange={setQuery}
+            />
+          </div>
+          <DropdownMenu
+            anchorRef={rowRef}
+            alignment="end"
+            button={{label: 'Filter'}}
+            items={['Everything', 'Mine', 'Shared with me'].map(label => ({
+              label,
+              onClick: () => setShowing(label),
+            }))}
+          />
+        </div>
+        <p data-testid="showing">Showing: {showing}</p>
+      </div>
+    );
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "A menu that lines up with a box wider than its trigger: `anchorRef` names the search row, so the menu sits under the row with its inline end on the row's and takes the row's width. The Filter button keeps focus, the press model, the keyboard opens and the menu's name.",
+      },
+    },
+  },
+};
+
 export const LinkRows: Story = {
   name: 'Rows that navigate (href)',
   render: () => (

packages/core/src/DropdownMenu/DropdownMenu.doc.mjs

@@ -219,7 +219,13 @@ export const docs = {
       name: 'menuWidth',
       type: 'number | string',
       description:
-        'Minimum width for the popover presentation. Length values may grow for content; intrinsic and CSS-wide keywords select the preferred inline size. Every form is capped to the available viewport space. Defaults to matching the trigger width up to that cap.',
+        "Minimum width for the popover presentation. Length values may grow for content; intrinsic and CSS-wide keywords select the preferred inline size. Every form is capped to the available viewport space. Defaults to matching the anchor width up to that cap: the trigger's, or the anchorRef element's.",
+    },
+    {
+      name: 'anchorRef',
+      type: 'React.RefObject<HTMLElement | null>',
+      description:
+        "External ref to use as the menu's anchor, as on Popover. The popover presentation is placed against this element, with placement and alignment read against it, and takes its width by default, instead of the trigger's: a menu that lines up with a toolbar or a search row wider than its control. The trigger keeps focus and focus return, the press model, the keyboard opens and the menu's name. Ignored by bottom-sheet presentation.",
     },
     {
       name: 'menuMaxHeight',

packages/core/src/DropdownMenu/DropdownMenu.spec.md

@@ -85,13 +85,14 @@ Consumer migration instructions belong in consumer docs and release notes.
 ## Public concepts
 
 Consumer props, item shapes, subcomponents, and presentation policy remain
-documented in `DropdownMenu.doc.mjs` and the subcomponent docs. Two component-local concepts are added, by DEC-2 and DEC-3; each keeps its
+documented in `DropdownMenu.doc.mjs` and the subcomponent docs. Three component-local concepts are added, by DEC-2, DEC-3 and proposed DEC-8; each keeps its
 released default.
 
 | Concept         | Closed values or states                                  | Meaning                                                                                                                                                               | Availability by variant/orientation/state | Default  | Owner                    | Stability | Invalid-value behavior                              |
 | --------------- | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | -------- | ------------------------ | --------- | --------------------------------------------------- |
 | Menu height cap | `menuMaxHeight`: a number of pixels                      | Lifts the 300px cap for a menu that must fit its rows; the viewport still bounds it.                                                                                  | Pointer presentation                      | `300px`  | `component:DropdownMenu` | stable    | Ignored by the touch sheet.                         |
 | Trigger source  | `button` (Button props) or `renderTrigger` (render prop) | Which control the menu hangs off. `trigger` receives `DropdownMenuTriggerProps` — the press model, keyboard opens, toggle click and ARIA wiring — and names the menu. | Both presentations                        | `button` | `component:DropdownMenu` | stable    | Both given: `trigger` wins and a dev warning fires. |
+| Menu anchor     | `anchorRef`: a ref to an element                         | The element the pointer menu is placed against and takes its default width from, instead of the trigger; the trigger keeps focus, the press model and the name.       | Pointer presentation                      | Trigger  | `component:DropdownMenu` | proposed  | Ignored by the touch sheet.                         |
 
 ## Behavioral and layout contract
 
@@ -114,6 +115,7 @@ released default.
 | FR12                  | In the pointer menu ArrowDown on the last enabled row wraps to the first and ArrowUp on the first to the last; PageDown and PageUp move to the last and first fully visible enabled row and, pressed there again, one viewport further without wrapping; ArrowUp on the trigger opens with the last enabled row highlighted; the key that opened the menu and its auto-repeats do not activate; typeahead matches the row's label element alone and ignores Control/Command chords and input-method composition.                                                                                                                                                                                                              | Proposed in this change; `DropdownMenu.test.tsx` keyboard suite, `useListFocus.test.tsx`, `useTypeahead.test.tsx`                                                             | Proposed; verified in jsdom, pending owner review                                 |
 | FR13                  | On a mouse, a nested flyout stays open while the pointer is inside the triangle from where it left its row to the flyout's near edge — including while the pointer is paused there — and closes after the existing delay once the pointer has left both the row and that triangle. The row's click toggle and its guard window are unchanged.                                                                                                                                                                                                                                                                                                                                                                                 | Proposed in this change; `DropdownMenuSubMenu.test.tsx` safe-triangle suite, `useMenuHover.test.tsx`                                                                          | Proposed; verified in jsdom, pending owner review                                 |
 | FR14                  | A compound `DropdownMenuGroup` is one `role="group"` named by its heading through `aria-labelledby`; the heading carries `dropdown-menu-section-heading`, is plain text rather than a menu item, and is skipped by roving focus and typeahead. An untitled group is an unnamed `role="group"`.                                                                                                                                                                                                                                                                                                                                                                                                                                | DEC-1, docs, and tests                                                                                                                                                        | Proposed; awaiting owner approval                                                 |
+| FR15                  | With `anchorRef`, the pointer menu MUST be placed against the referenced element, with `placement` and `alignment` read against it and its default minimum width that element's width, still capped by the viewport, while the Trigger button keeps focus and focus return (FR6), the press model (FR8), the keyboard opens and the menu's name (FR9); a press on that element outside the trigger is a press outside the menu and dismisses it. Without it the trigger is the anchor. The touch sheet ignores it.                                                                                                                                                                                                            | Proposed DEC-8; `component:Popover` `anchorRef`                                                                                                                               | Proposed; verified in jsdom and Chromium, pending owner review                    |
 
 ### Allowed variation
 
@@ -276,6 +278,7 @@ than adding a DropdownMenu-owned heading target.
 | FR8, AR2            | `DropdownMenu.test.tsx` "DropdownMenuItem href" suite (pointer menu and bottom sheet)                                                                                        | Plain click, ⌘-click, Enter with modifiers, disabled link row                                              | A row rendering an inner anchor, running `onClick` on a modified click, or a synthesized click dropping the modifiers fails.                                  | `audit:DropdownMenu/behavior` |
 | FR12, AR3           | `DropdownMenuSubMenu.test.tsx` "drill-in on a phone" suite; `__tests__/DropdownMenuDrillIn.a11y.chromium.spec.ts` (real Chromium, coarse pointer)                            | Drill in, Back, Escape, ArrowLeft, nested level, scoped typeahead, forced presentations, close resets      | A flyout opening on a coarse pointer, a missing Back row, sibling rows staying in the order, or focus not returning to the row fails.                         | `audit:DropdownMenu/behavior` |
 | FR10                | `DropdownMenuSubMenu.test.tsx` safe-triangle suite; `useMenuHover.test.tsx` `isPointInSafeTriangle` and click-guard suites                                                   | diagonal path toward the flyout, a pause inside it, path away, click-opened and hover-opened guard windows | A flyout that closes while the pointer is inside the triangle or paused in it, one that never closes after leaving it, or a changed guard-window rule, fails. | `audit:DropdownMenu/behavior` |
+| FR15                | `DropdownMenu.test.tsx` anchorRef suite; `__tests__/DropdownMenuAnchorRef.a11y.chromium.spec.ts` (real Chromium)                                                             | Button and custom trigger; place, width, toggle, field press, keys, Escape, press-drag; sheet              | A menu placed against its trigger, an anchored trigger, a lost toggle, key or focus return, or a press in the anchor that leaves the menu open, fails.        | `audit:DropdownMenu/behavior` |
 
 ## Decision log
 
@@ -440,3 +443,24 @@ The value is a number of pixels. Rejected: an arbitrary CSS length (`50vh`,
 `calc(...)`), which is product-shaped tuning on a shared component that
 `spec:AST-002` does not admit, and which lets a caller write a cap the
 viewport term cannot reason about.
+
+### DEC-8 (proposed) — A menu may anchor to an element other than its trigger
+
+**Reference:** `component:DropdownMenu/DEC-8`
+
+**Decider:** proposed by `vjeux`, 2026-10-11; pending owner review
+
+Where a menu sits is a positioning fact; which control opens it is an
+interaction fact. A menu that lines up with a box wider than its control, a
+toolbar or a search row, needs the first without moving the second: the
+trigger keeps focus and focus return, the press model, the keyboard opens and
+the menu's name (DEC-3), and only placement, alignment and the default width
+read the anchor. Popover already names an external anchor `anchorRef`, and
+TopNav's mega menu anchors its panel to the nav while its button keeps the
+toggle, so the prop takes Popover's name and a ref object's shape. A press on
+the anchor outside the trigger stays outside the menu and dismisses it.
+
+Rejected: a second ref in `DropdownMenuTriggerProps`, since the anchor is
+usually an ancestor the render prop does not render; an offset from the
+trigger, which breaks when the row resizes; and hosting the menu's rows in a
+Popover, which loses the menu's press model and keyboard opens.

packages/core/src/DropdownMenu/DropdownMenu.test.tsx

@@ -13,7 +13,7 @@ import {describe, it, expect, vi, beforeEach} from 'vitest';
 import {readFileSync} from 'node:fs';
 import {render, screen, fireEvent, waitFor, act} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
-import {useState} from 'react';
+import {useRef, useState} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {DropdownMenu} from './DropdownMenu';
 import {DropdownMenuItem} from './DropdownMenuItem';
@@ -23,6 +23,7 @@ import {Divider} from '../Divider';
 import {rtlStyles} from '../utils';
 import {__resetInteractionModalityForTest} from '../utils/interactionModality';
 import {focusOutlineStyles} from '../utils/focusOutline.stylex';
+import {readAnchorNames} from '../Layer/anchorName';
 
 // Mock showPopover and hidePopover methods since they're not implemented in jsdom
 beforeEach(() => {
@@ -2987,6 +2988,130 @@ describe('DropdownMenu menuMaxHeight', () => {
   });
 });
 
+describe('DropdownMenu anchorRef', () => {
+  const ITEMS = [{label: 'Mine'}, {label: 'Everyone'}];
+
+  function positionAnchorOf(menu: HTMLElement): string | undefined {
+    const layer = menu.closest('[popover]');
+    return /position-anchor:\s*([^;]+)/.exec(
+      layer?.getAttribute('style') ?? '',
+    )?.[1];
+  }
+
+  it('places the menu against the anchorRef element while the trigger keeps its wiring', async () => {
+    const user = userEvent.setup();
+    const errors = vi.spyOn(console, 'error').mockImplementation(() => {});
+    try {
+      function SearchRow() {
+        const rowRef = useRef<HTMLDivElement>(null);
+        return (
+          <div ref={rowRef} data-testid="row">
+            <input aria-label="Search" />
+            <DropdownMenu
+              anchorRef={rowRef}
+              alignment="end"
+              button={{label: 'Filter'}}
+              items={ITEMS}
+            />
+          </div>
+        );
+      }
+      render(<SearchRow />);
+      const row = screen.getByTestId('row');
+      const trigger = screen.getByRole('button', {name: 'Filter'});
+      const menu = screen.getByRole('menu', {hidden: true});
+      // The row carries the menu's anchor name; the trigger carries none.
+      const [anchorName] = readAnchorNames(row);
+      expect(anchorName).toMatch(/^--astryx-layer-/);
+      expect(positionAnchorOf(menu)).toBe(anchorName);
+      expect(readAnchorNames(trigger)).toEqual([]);
+      // The trigger keeps the menu-button wiring.
+      expect(trigger).toHaveAttribute('aria-haspopup', 'menu');
+      expect(trigger).toHaveAttribute('aria-controls', menu.id);
+
+      await user.click(trigger);
+      await waitFor(() =>
+        expect(trigger).toHaveAttribute('aria-expanded', 'true'),
+      );
+      await user.keyboard('{Escape}');
+      await waitFor(() =>
+        expect(trigger).toHaveAttribute('aria-expanded', 'false'),
+      );
+      // The anchor stays on the row through the open and the close.
+      expect(readAnchorNames(row)).toEqual([anchorName]);
+      expect(readAnchorNames(trigger)).toEqual([]);
+      // The prop never reaches the DOM.
+      expect(menu).not.toHaveAttribute('anchorref');
+      expect(errors).not.toHaveBeenCalled();
+    } finally {
+      errors.mockRestore();
+    }
+  });
+
+  it('leaves a renderTrigger control its focus, keys and name, and the anchor to anchorRef', async () => {
+    const user = userEvent.setup();
+    function Toolbar() {
+      const barRef = useRef<HTMLDivElement>(null);
+      return (
+        <div ref={barRef} data-testid="bar">
+          <DropdownMenu
+            anchorRef={barRef}
+            renderTrigger={props => (
+              <button type="button" {...props}>
+                Owner
+              </button>
+            )}>
+            <DropdownMenuItem label="Mine" onClick={() => {}} />
+          </DropdownMenu>
+        </div>
+      );
+    }
+    render(<Toolbar />);
+    const bar = screen.getByTestId('bar');
+    const trigger = screen.getByRole('button', {name: 'Owner'});
+    const menu = screen.getByRole('menu', {hidden: true});
+    expect(positionAnchorOf(menu)).toBe(readAnchorNames(bar)[0]);
+    expect(readAnchorNames(trigger)).toEqual([]);
+    // The menu is still named by its control.
+    expect(menu).toHaveAttribute('aria-labelledby', trigger.id);
+    trigger.focus();
+    await user.keyboard('{ArrowDown}');
+    await waitFor(() =>
+      expect(
+        screen.getByRole('menuitem', {name: 'Mine', hidden: true}),
+      ).toHaveFocus(),
+    );
+  });
+
+  it('without anchorRef the trigger stays the anchor', () => {
+    render(<DropdownMenu button={{label: 'Filter'}} items={ITEMS} />);
+    const trigger = screen.getByRole('button', {name: 'Filter'});
+    const menu = screen.getByRole('menu', {hidden: true});
+    const names = readAnchorNames(trigger);
+    expect(names).toHaveLength(1);
+    expect(positionAnchorOf(menu)).toBe(names[0]);
+  });
+
+  it('the bottom sheet ignores anchorRef', () => {
+    function SheetRow() {
+      const rowRef = useRef<HTMLDivElement>(null);
+      return (
+        <div ref={rowRef} data-testid="row">
+          <DropdownMenu
+            anchorRef={rowRef}
+            presentation="bottom-sheet"
+            button={{label: 'Filter'}}
+            items={ITEMS}
+          />
+        </div>
+      );
+    }
+    render(<SheetRow />);
+    expect(readAnchorNames(screen.getByTestId('row'))).toEqual([]);
+    expect(document.querySelector('[anchorref]')).toBeNull();
+  });
+});
+
 describe('DropdownMenu focus return after a pointer pick', () => {
   function renderMenu(onPick: (label: string) => void = () => {}) {
     render(