diff --git a/.changeset/menu-touch-grow.md b/.changeset/menu-touch-grow.md
new file mode 100644
index 0000000000000..7ebc16e1d2283
--- /dev/null
+++ b/.changeset/menu-touch-grow.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[feature] Under a finger or a pen, a DropdownMenu or MoreMenu now grows out of its trigger as it opens and shrinks back into it as it closes, on a Popover's path and timing (`spec:AST-094` FR31). A tap's open grows as a hold's does. Under Reduce Motion on a phone or tablet (a coarse primary pointer), the menu fades in at its size and out where it stands. A mouse, the keyboard and `presentation="popover"` keep the layer's own entrance.
+
+@vjeux
diff --git a/apps/sandbox/scripts/next-export-routes.json b/apps/sandbox/scripts/next-export-routes.json
index 1478ce270b345..5e26b13dd89b9 100644
--- a/apps/sandbox/scripts/next-export-routes.json
+++ b/apps/sandbox/scripts/next-export-routes.json
@@ -28,6 +28,7 @@
"/pages/markdown-perf/",
"/pages/media-mode/",
"/pages/mega-menu/",
+ "/pages/menu-grow-cases/",
"/pages/menu-press-cases/",
"/pages/minute-wheel-loop/",
"/pages/mobile-keyboard-fields/",
diff --git a/apps/sandbox/src/app/(raw)/pages/menu-grow-cases/page.tsx b/apps/sandbox/src/app/(raw)/pages/menu-grow-cases/page.tsx
new file mode 100644
index 0000000000000..332741b48f11a
--- /dev/null
+++ b/apps/sandbox/src/app/(raw)/pages/menu-grow-cases/page.tsx
@@ -0,0 +1,204 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file page.tsx
+ * @input None
+ * @output A bare page of large DropdownMenus and a Popover, spread down a
+ * page that scrolls with the document
+ * @position A raw page, with no sandbox chrome, for checking on a phone how
+ * menus grow out of their trigger and shrink back. It has a tall menu that
+ * scrolls, a wide one and a filter menu with many rows. It also has nested
+ * sub-menus, menus at each edge, one that flips above, and a Popover.
+ */
+
+import {Button} from '@astryxdesign/core/Button';
+import {
+ DropdownMenu,
+ type DropdownMenuOption,
+} from '@astryxdesign/core/DropdownMenu';
+import {HStack, VStack} from '@astryxdesign/core/Layout';
+import {Popover} from '@astryxdesign/core/Popover';
+import {Heading, Text} from '@astryxdesign/core/Text';
+
+const SHORT: DropdownMenuOption[] = [
+ {label: 'Edit'},
+ {label: 'Duplicate'},
+ {label: 'Share'},
+ {label: 'Delete', variant: 'destructive'},
+];
+
+const TALL: DropdownMenuOption[] = Array.from({length: 40}, (_, index) => ({
+ label: `Project ${index + 1}`,
+}));
+
+const WIDE: DropdownMenuOption[] = [
+ {
+ label: 'Export the whole workspace as a spreadsheet',
+ description: 'Every table, with its filters and hidden columns',
+ },
+ {
+ label: 'Copy a link that opens this exact view',
+ description: 'Sorting, grouping and the scroll position travel with it',
+ },
+ {
+ label: 'Send a weekly summary to the team channel',
+ description: 'Every Monday morning, in the channel time zone',
+ },
+];
+
+function section(title: string, labels: string[]): DropdownMenuOption {
+ return {type: 'section', title, items: labels.map(label => ({label}))};
+}
+
+const FILTERS: DropdownMenuOption[] = [
+ section('Status', ['Open', 'In progress', 'In review', 'Blocked', 'Done']),
+ {type: 'divider'},
+ section('Priority', ['Urgent', 'High', 'Medium', 'Low']),
+ {type: 'divider'},
+ section('Owner', [
+ 'Anyone',
+ 'Me',
+ 'My team',
+ 'Unassigned',
+ 'Recently active',
+ 'Former members',
+ ]),
+ {type: 'divider'},
+ section('Labels', [
+ 'Bug',
+ 'Feature',
+ 'Design',
+ 'Docs',
+ 'Performance',
+ 'Accessibility',
+ 'Security',
+ 'Mobile',
+ ]),
+];
+
+const NESTED: DropdownMenuOption[] = [
+ {label: 'New file'},
+ {
+ label: 'Move to',
+ items: [
+ {label: 'Inbox'},
+ {
+ label: 'Projects',
+ items: [
+ {label: 'Website'},
+ {label: 'Mobile app'},
+ {
+ label: 'Archive',
+ items: [{label: '2024'}, {label: '2025'}, {label: '2026'}],
+ },
+ ],
+ },
+ {label: 'Shared with me'},
+ ],
+ },
+ {
+ label: 'Share',
+ items: [{label: 'Copy link'}, {label: 'Email'}, {label: 'Message'}],
+ },
+ {label: 'Delete', variant: 'destructive'},
+];
+
+const FILLER = Array.from({length: 12}, (_, index) => `Row ${index + 1}`);
+
+function Filler() {
+ return (
+
+ {FILLER.map(row => (
+
+ {row}
+
+ ))}
+
+ );
+}
+
+function Case({title, children}: {title: string; children: React.ReactNode}) {
+ return (
+
+ {title}
+ {children}
+
+ );
+}
+
+export default function MenuGrowCasesPage() {
+ return (
+
+
+
+
+
+
+ Menu grow cases
+
+ Tap or hold each trigger: the menu grows out of it and shrinks back
+ into it. The Popover below grows the same way.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Filter
+ {['Open', 'In progress', 'In review', 'Done'].map(label => (
+ {label}
+ ))}
+
+ }>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ );
+}
diff --git a/apps/sandbox/src/app/sandboxPages.ts b/apps/sandbox/src/app/sandboxPages.ts
index 7220c0b5f87d1..15319d2b6952c 100644
--- a/apps/sandbox/src/app/sandboxPages.ts
+++ b/apps/sandbox/src/app/sandboxPages.ts
@@ -123,6 +123,12 @@ export const categories: SandboxCategory[] = [
description:
'A pushed NavigationStack screen with a Done row or a strip at its edge, and a RefreshControl list, on a page that scrolls with the document, to check taps and pulls on a phone',
},
+ {
+ name: 'Menu Grow Cases',
+ href: '/pages/menu-grow-cases/',
+ description:
+ 'Large DropdownMenus and a Popover that grow out of their trigger: tall, wide, many rows, nested, at the edges and flipped, on a page that scrolls with the document',
+ },
{
name: 'List Reorder Cases',
href: '/pages/list-reorder-cases/',
diff --git a/docs/architecture/layer-runtime.md b/docs/architecture/layer-runtime.md
index a20ae477cc1fd..fd7e75bb24441 100644
--- a/docs/architecture/layer-runtime.md
+++ b/docs/architecture/layer-runtime.md
@@ -881,7 +881,8 @@ it on the surface inside the layer and run no layout while it plays.
its one touch module. `Layer/layerKeyboardClearance.ts` holds the clearance
and the cap's arithmetic. `Layer/settledBox.ts` reads a layer's box without
its entrance transform, for the fallback order, the keyboard's cap and the
- exit copy.
+ exit copy. The touch grow reads its source the same way, without the press
+ transform (INV22).
- `Layer/preserveAnimations.ts` owns carrying the CSS animations and
transitions of a layer and its content across the re-placement's display
reset.
diff --git a/docs/specs/AST-094-touch-presentations/spec.md b/docs/specs/AST-094-touch-presentations/spec.md
index f4de42ca5c505..076a6612e2c0f 100644
--- a/docs/specs/AST-094-touch-presentations/spec.md
+++ b/docs/specs/AST-094-touch-presentations/spec.md
@@ -675,7 +675,11 @@ under a finger, and a mouse follows `module:DropdownMenu/useMenuPress` FR3 and
shrink plays on the theme's exit duration and easing (FR7). The shrink plays in full after the surface has
closed. This is its exit under FR7 (`family:overlay-dismissal` AV6); under
reduced motion FR8 applies. A menu or popover presented as a bottom sheet
- follows the sheet instead.
+ follows the sheet instead. Tap-opened layers (Popover, DropdownMenu,
+ MoreMenu) grow on Popover's surface motion. A menu opened without an
+ accepted press uses the layer's own entrance. That covers a keyboard or
+ programmatic open and a press the menu's press model ignores, such as a
+ second finger.
- **FR32 — A pan outside dismisses.** Under a finger, an open anchored menu MUST close as a touch outside it
begins to pan, and at the lift of a tap or hold outside it. A Popover's
dismissal is unchanged. A pinch stays available over it: its surface
diff --git a/docs/specs/components/DropdownMenu/DropdownMenu.spec.md b/docs/specs/components/DropdownMenu/DropdownMenu.spec.md
index 6c3299b78e878..ca88b134078cb 100644
--- a/docs/specs/components/DropdownMenu/DropdownMenu.spec.md
+++ b/docs/specs/components/DropdownMenu/DropdownMenu.spec.md
@@ -17,6 +17,8 @@ verified_by:
packages/core/src/DropdownMenu/__tests__/DropdownMenuDrillIn.a11y.chromium.spec.ts,
packages/core/src/DropdownMenu/__tests__/MenuPress.a11y.chromium.spec.ts,
packages/core/src/DropdownMenu/__tests__/DropdownMenuTouchPress.interaction.browser.spec.ts,
+ packages/core/src/DropdownMenu/DropdownMenuTouchGrow.test.tsx,
+ packages/core/src/DropdownMenu/__tests__/DropdownMenuTouchGrow.interaction.browser.spec.ts,
packages/core/src/DropdownMenu/__tests__/MenuHeaderFooter.a11y.chromium.spec.ts,
packages/core/src/DropdownMenu/__tests__/SubMenuHeaderFooter.a11y.chromium.spec.ts,
packages/core/src/ContextMenu/ContextMenu.test.tsx,
@@ -40,15 +42,15 @@ system_specs: [spec:AST-020/FR15, spec:AST-094, spec:AST-102, spec:AST-116]
## Contract at a glance
-| Area | Contract |
-| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract | None changes. DropdownMenu takes a `button` (Button props) or `renderTrigger`, data-driven `items` or compound children, `presentation`, `isMenuOpen` and `onOpenChange`, placement and alignment, `menuMaxHeight`, `header`, and `footer`. |
-| Behavior | A Menu Button trigger opens an anchored pointer menu or a bottom-sheet action list. Rows act on the release under the shared press model; sub-menus fly out beside their row or drill in on a compact touch display; a header or footer makes the pointer popover a modal dialog around the menu. |
-| End-user impact | People pick actions by mouse, finger, or keyboard; keyboard users get a focus return with a ring and pointer users without one; on a phone sub-menus replace the rows instead of flying off-screen. Under a finger the menu opens as the finger presses, or after the content-touch delay inside a scroll view; it does not grow from its trigger, and a pan outside does not close it. |
-| Builder impact | Builders choose the trigger, the rows, and the regions; rows stay menu items and every non-item control goes in `header` or `footer`. |
-| Compatibility/readiness | Records shipped behavior; no API change; a disabled row gains `tabindex="-1"`; the released behavior under a finger moves as `spec:AST-094` FR25 lists, with `presentation="popover"` keeping it. Touch grow and pan dismissal (FR21), the still mouse (FR22), and Trigger Button gaps are in Current-state impact. |
-| Review checks | Reject a control placed among the rows, a lost trigger ARIA wiring, a drilled-in view that leaves the menu box, a header or footer without the dialog, a lost focus-return modality, or a target moved off its painted element. |
-| Governing rules | `spec:AST-020` FR15; `spec:AST-094` FR26–FR35; `module:DropdownMenu/useMenuPress`; `architecture:interaction-modality` INV1; `architecture:component-theming-surface`; `architecture:layer-runtime`; `family:overlay-dismissal`; `family:navigation-destinations`. |
+| Area | Contract |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract | None changes. DropdownMenu takes a `button` (Button props) or `renderTrigger`, data-driven `items` or compound children, `presentation`, `isMenuOpen` and `onOpenChange`, placement and alignment, `menuMaxHeight`, `header`, and `footer`. |
+| Behavior | A Menu Button trigger opens an anchored pointer menu or a bottom-sheet action list. Rows act on the release under the shared press model; sub-menus fly out beside their row or drill in on a compact touch display; a header or footer makes the pointer popover a modal dialog around the menu. |
+| End-user impact | People pick actions by mouse, finger, or keyboard; keyboard users get a focus return with a ring and pointer users without one; on a phone sub-menus replace the rows instead of flying off-screen. Under a finger the menu opens as the finger presses, or after the content-touch delay inside a scroll view; it grows out of its trigger and shrinks back into it, and a pan outside does not close it. |
+| Builder impact | Builders choose the trigger, the rows, and the regions; rows stay menu items and every non-item control goes in `header` or `footer`. |
+| Compatibility/readiness | Records shipped behavior; no API change; a disabled row gains `tabindex="-1"`; the released behavior under a finger moves as `spec:AST-094` FR25 lists, with `presentation="popover"` keeping it. Pan dismissal (FR21), the still mouse (FR22), and Trigger Button gaps are in Current-state impact. |
+| Review checks | Reject a control placed among the rows, a lost trigger ARIA wiring, a drilled-in view that leaves the menu box, a header or footer without the dialog, a lost focus-return modality, or a target moved off its painted element. |
+| Governing rules | `spec:AST-020` FR15; `spec:AST-094` FR26–FR35; `module:DropdownMenu/useMenuPress`; `architecture:interaction-modality` INV1; `architecture:component-theming-surface`; `architecture:layer-runtime`; `family:overlay-dismissal`; `family:navigation-destinations`. |
This table is a review projection; the body below is authoritative.
@@ -144,7 +146,7 @@ component-local concepts; each keeps its released default.
| FR16 | Checkbox rows follow `component:DropdownMenuCheckboxItem`. | Current source |
| FR17 | A disabled menu row MUST be reached by the keyboard and stay inert (DEC-11): in DropdownMenu, its sub-menus, MoreMenu, ContextMenu and NavHeadingMenu, ArrowDown, ArrowUp, Home, End and type-ahead visit a disabled row as they visit any other row, the row takes focus and exposes `aria-disabled="true"`, and Enter, Space or a click on it does nothing and leaves the menu open. Opening a menu from the keyboard still lands on an enabled row: the first, or the last after ArrowUp on the trigger (FR12, AR4). | DEC-11; WAI-ARIA Menu pattern |
| FR20 | With `header` or `footer` on a sub-menu (`DropdownMenuSubMenu`), its surface is a modal dialog named by its row (AR7), holding the header, the sub-menu's `role="menu"` (rows only), then the footer. It sits in a host `DropdownMenu` renders beside its menu, never inside a menu; under a root with no such host (`ContextMenu`) the sub-menu shows its rows alone. On a fine pointer the dialog is the flyout; on a compact touch display, the drilled-in view, which replaces the root's menu and regions until popped. A region keeps its own keys and presses. The rows are one Tab stop: Tab and Shift+Tab walk the header's controls, the rows, then the footer's, and wrap; from a deeper flyout, that flyout closes and the walk goes on from the rows. An open lands as for any sub-menu (FR11, FR12), not on a region. Escape in the dialog, outside an IME composition and unless a control there handled it, returns focus to the row and leaves the root open. A pointer leaving the flyout keeps it open until focus leaves, and it closes with the flyout holding its row. Without either prop nothing changes. | Current behavior; FR15; AR5 |
-| FR21 | Under a finger, in the touch modes (`presentation` not pinned to `'popover'`), the pointer menu MUST grow out of the Trigger button on the theme's entrance duration and easing tokens and collapse back into it on the theme's exit duration and easing (`spec:AST-094` FR7, FR31, FR45), and MUST close as a pan that starts outside it begins (FR32); a pinned `'popover'` keeps the layer's own entrance. A pan dismissal is the menu's own close: focus that was in the menu returns to the Trigger button, whose `aria-expanded` turns false. A mouse keeps the layer's own entrance and exit. Implementation gap: the menu keeps the layer's own entrance and exit under a finger too, and has no pan-outside dismissal of its own. | `spec:AST-094` FR31, FR32; `family:overlay-dismissal` AV6 |
+| FR21 | Under a finger, in the touch modes (`presentation` not pinned to `'popover'`), the pointer menu MUST grow out of the Trigger button on the theme's entrance duration and easing tokens and collapse back into it on the theme's exit duration and easing (`spec:AST-094` FR7, FR31, FR45), and MUST close as a pan that starts outside it begins (FR32); a pinned `'popover'` keeps the layer's own entrance. A pan dismissal is the menu's own close: focus that was in the menu returns to the Trigger button, whose `aria-expanded` turns false. A finger's or a pen's open grows the menu, a tap's open at its lift included, and the grow follows the popover's path. A mouse and the keyboard keep the layer's own entrance and exit. Under Reduce Motion, where the primary pointer is coarse, the menu fades in at its size and fades out where it stands (`design:reduced-motion` DR2). Under a coarse primary pointer, taps stay held from the open until the menu is visible. Implementation gap: the menu has no pan-outside dismissal of its own. | `spec:AST-094` FR31, FR32; `family:overlay-dismissal` AV6 |
| FR22 | Under a finger, in the touch modes, where the primary pointer is coarse (a phone or a tablet), a tap or a drag that lands while the pointer menu enters MUST reach nothing: it closes nothing, scrolls nothing, moves no focus and clicks nothing (`spec:AST-094` FR35). The finger that opened the menu still picks the row it lifts on (FR8). Keys and assistive technology stay live. A mouse, a pinned `'popover'` and a finger where the primary pointer is fine (a touchscreen laptop) hold nothing, as for `component:Drawer`. Implementation gap: after a finger, a still mouse's first press lands on the entering menu's shield unless the mouse rests where the page last heard it when the shield came up (`spec:AST-094` FR35). | `spec:AST-094` FR35; `architecture:layer-runtime` |
| FR23 | Tab or Shift+Tab on a row at any level of a menu without `header` or `footer`, its own rows or an open sub-menu flyout's at any depth, closes every open level and the menu, calls `onOpenChange(false)` once, and leaves focus to move on from the trigger in page order (WAI-ARIA Menu Button). A level with a header or footer keeps FR15's and FR20's Tab cycle within it. | WAI-ARIA Menu Button pattern; current tests |
@@ -365,7 +367,7 @@ than adding a DropdownMenu-owned heading target.
| FR15, AR5 | `DropdownMenu.test.tsx` header and footer cases, including the hidden-control, open-sub-menu, and header radio-group cases; `MenuHeaderFooter.a11y.chromium.spec.ts` | Regions present and absent; hidden controls; open flyout; custom trigger; bottom sheet | A region inside the menu, a missing or unnamed dialog, a wrong `aria-haspopup`, a Tab that leaves the popover, a hidden control taken as a stop, or a region whose keys the menu takes fails. | `audit:DropdownMenu/accessibility` |
| FR17, AR6 | DropdownMenu, MoreMenu, ContextMenu and NavHeadingMenu keyboard tests, plus a real-browser keyboard check of focus order and blocked activation and a real-browser accessibility-tree check that a focused disabled row is announced as disabled (`spec:AST-085` Platform support); disabled-row cases | Disabled rows | A disabled row that runs a caller handler, closes the menu, is skipped by the arrow keys or type-ahead, or is not announced as disabled fails. | `audit:DropdownMenu/accessibility` |
| FR20, AR7 | `DropdownMenuSubMenu.test.tsx` header and footer cases, including "on a phone"; `SubMenuHeaderFooter.a11y.chromium.spec.ts`; `ContextMenu.test.tsx` "shows a sub-menu with a header or footer as its rows alone, and says why in development" | Fine pointer and phone; Escape paths; nested flyouts; pointer leaving | A region inside a menu, an unnamed dialog, a Tab walk that does not wrap, an Escape that closes the root, or a flyout that closes while focus is inside fails. | `audit:DropdownMenu/accessibility` |
-| FR21 | Evidence gap: no test, matching the FR21 gap | — | — | `audit:DropdownMenu/behavior` |
+| FR21 | `DropdownMenuTouchGrow.test.tsx` (which opens grow); `DropdownMenuTouchGrow.interaction.browser.spec.ts` (Chromium, WebKit): the first tap after load, a tap in scrolling content and a held finger grow the menu out of its trigger, on the popover's path and timing. Evidence gap: pan dismissal, matching the FR21 gap | — | — | `audit:DropdownMenu/behavior` |
| FR22 | `DropdownMenu.test.tsx` "DropdownMenu entrance under a finger" cases; `useMenuPress.test.tsx` "an input hold over the menu" cases; `DropdownMenuEntranceHold.interaction.browser.spec.ts` | A tap outside and a finger's slide while the menu enters; a mouse click | A tap during the entrance that closes the menu, clicks the page or moves focus, a slide that picks nothing, or a held mouse fails. | `audit:DropdownMenu/behavior` |
| FR23 | `DropdownMenu.test.tsx` Tab cases; `DropdownMenuSubMenu.test.tsx` "Tab from a flyout leaves the whole menu" suite | top level, one and two levels down, Shift+Tab | A Tab that leaves any level open, a second `onOpenChange(false)`, or a prevented Tab fails. | `audit:DropdownMenu/accessibility` |
| PR1 | Evidence gap: no test asserts the listener and observer bounds | — | — | `audit:DropdownMenu/behavior` |
@@ -373,10 +375,8 @@ than adding a DropdownMenu-owned heading target.
## Current-state impact
-- **Touch grow and pan dismissal (FR21).** Under a finger the menu appears and
- leaves with the layer's own entrance and exit instead of growing out of and
- back into the Trigger button, and a pan that starts outside does not close
- it, against `spec:AST-094` FR31 and FR32.
+- **Pan dismissal (FR21).** Under a finger a pan that starts outside the menu
+ does not close it, against `spec:AST-094` FR32.
- **Still mouse after a finger (FR22).** Known gap: after a finger, a still
mouse's first press does nothing unless the mouse rests where the page last
heard it when the entering menu's shield came up.
diff --git a/docs/specs/components/DropdownMenu/modules/useMenuPress.spec.md b/docs/specs/components/DropdownMenu/modules/useMenuPress.spec.md
index c9e008b8f2218..4a35b3b0296b4 100644
--- a/docs/specs/components/DropdownMenu/modules/useMenuPress.spec.md
+++ b/docs/specs/components/DropdownMenu/modules/useMenuPress.spec.md
@@ -154,6 +154,10 @@ Consumer migration instructions belong in consumer docs and release notes.
| `data-astryx-menu-press` | present or absent | the root carries this model; a host controller of its own stands aside | present on every mounted root | `module:DropdownMenu/useMenuPress` | stable |
| activation click | `click` with `detail: 0`, the release's button and modifiers | how the model acts on a row, marked for the synchronous extent by `isMenuPressActivation()`; `detail === 0` alone therefore no longer means "keyboard" on a menu row | — | `module:DropdownMenu/useMenuPress` | stable |
+`useMenuPressInternal` (not exported from any entry) also reports the accepted
+press's pointer type, which DropdownMenu reads to choose its grow; the public
+hook does not expose it.
+
## Behavioral contract
| ID | Invariant | Basis | Verification state |
@@ -206,6 +210,10 @@ Consumer migration instructions belong in consumer docs and release notes.
- **PR3 — Autoscroll.** One interval while a tracked pointer rests in an
edge zone of an overflowing menu; it stops when the pointer leaves the zone,
the scroller reaches its edge, or the gesture ends.
+- **PR4 — The press model is the menus' own.** It builds on the layer
+ runtime's gesture counter and input hold. No engine that
+ `architecture:react-component-runtime` INV19 names models a menu's press,
+ where the row under the release acts, so none fits.
## Accessibility contract
diff --git a/docs/specs/components/Popover/Popover.spec.md b/docs/specs/components/Popover/Popover.spec.md
index 1d1260b889431..15c5f5ef3273f 100644
--- a/docs/specs/components/Popover/Popover.spec.md
+++ b/docs/specs/components/Popover/Popover.spec.md
@@ -104,6 +104,13 @@ rung, so a caller whose content owns its own edges can ask for a flush surface.
`width`, else the trigger's minimum width), conditional internal scrolling,
and the measurement lifecycle needed to support them.
- The current fallback close control appended by the hook.
+- The touch presentation's surface motion (`usePopoverSurfaceMotion`,
+ `popoverSurfaceMotion.ts`). DropdownMenu plays it too, with options Popover
+ does not pass: `holdUntilFirstFrame`, which holds taps from the open until
+ the grow's first frame, and a `present` call's `isTouch`, which decides the
+ touch presentation from the open's own input. The grow holds taps only
+ under a coarse primary pointer. It measures its source without the press
+ transform (`architecture:layer-runtime` INV22).
**Does not own / non-goals**
diff --git a/packages/core/src/DropdownMenu/DropdownMenu.test.tsx b/packages/core/src/DropdownMenu/DropdownMenu.test.tsx
index 373d3b748b337..b5174c568bc27 100644
--- a/packages/core/src/DropdownMenu/DropdownMenu.test.tsx
+++ b/packages/core/src/DropdownMenu/DropdownMenu.test.tsx
@@ -17,6 +17,7 @@ import {
beforeAll,
beforeEach,
afterEach,
+ onTestFinished,
} from 'vitest';
import {readFileSync} from 'node:fs';
import {render, screen, fireEvent, waitFor, act} from '@testing-library/react';
@@ -39,11 +40,15 @@ import {spacingVars} from '../theme/tokens.stylex';
import {COMPACT_TOUCH_PRESENTATION_QUERY} from '../hooks/useAdaptivePresentation';
import {MENU_PRESS_LONG_PRESS_MS} from '../hooks/useMenuPress';
import {MENU_PRESS_SETTLE_MS} from '../hooks/menuPressGesture';
-import {isInHeldLayer} from '../Layer/inputHold';
+import {holdInput, isInHeldLayer} from '../Layer/inputHold';
import {runPopoverOperation} from '../Layer/popoverOperations';
import {TOUCH_QUERY} from '../utils/touchPresentation';
import {UIKIT_GESTURES} from '../motion/uikit/gestures';
+// Spied, so a case about the press model alone can stub the presentation's
+// input hold: jsdom never ends a presentation.
+vi.mock('../Layer/inputHold', {spy: true});
+
// Mock showPopover and hidePopover methods since they're not implemented in jsdom
beforeEach(() => {
__resetInteractionModalityForTest();
@@ -3680,6 +3685,10 @@ describe('DropdownMenu press model', () => {
it('under a coarse pointer a finger opens the menu as it presses the trigger (no scroll view), and a slide picks', () => {
stubCoarsePointer();
+ // The press model alone: jsdom never ends the grow, so its input hold
+ // would hold this gesture to its end.
+ vi.mocked(holdInput).mockImplementation(() => () => {});
+ onTestFinished(() => vi.mocked(holdInput).mockRestore());
vi.useFakeTimers();
try {
const onPick = vi.fn();
@@ -4116,6 +4125,10 @@ describe('DropdownMenu press model', () => {
it('coarse primary pointer: a finger opens the menu once, as it presses, and it closes once at a pick (module AR5)', () => {
stubCoarsePointer();
+ // The press model alone: jsdom never ends the grow, so its input hold
+ // would hold this gesture to its end.
+ vi.mocked(holdInput).mockImplementation(() => () => {});
+ onTestFinished(() => vi.mocked(holdInput).mockRestore());
const {trigger, onOpenChange, onPick} = renderCountingMenu();
fireEvent.pointerDown(trigger, {...touch, clientX: 0, clientY: 0});
fireEvent.pointerUp(trigger, {...touch, clientX: 0, clientY: 0});
diff --git a/packages/core/src/DropdownMenu/DropdownMenu.tsx b/packages/core/src/DropdownMenu/DropdownMenu.tsx
index 3cbc2a8154e24..614252d22956b 100644
--- a/packages/core/src/DropdownMenu/DropdownMenu.tsx
+++ b/packages/core/src/DropdownMenu/DropdownMenu.tsx
@@ -50,6 +50,7 @@ import {readAccessibleName} from '../utils/accessibleName';
import * as stylex from '@stylexjs/stylex';
import {usePopoverInternal} from '../Popover/usePopover';
import {holdEntranceInput} from '../Layer/holdEntranceInput';
+import {usePopoverSurfaceMotion} from '../Popover/usePopoverSurfaceMotion';
import {
claimPress,
currentGesture,
@@ -80,7 +81,10 @@ import {
import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';
import {useMergedRefs} from '../hooks/useMergedRefs';
import {useInternalListFocus} from '../hooks/useListFocus';
-import {MENU_PRESS_LONG_PRESS_MS, useMenuPress} from '../hooks/useMenuPress';
+import {
+ MENU_PRESS_LONG_PRESS_MS,
+ useMenuPressInternal,
+} from '../hooks/useMenuPress';
import type {MenuPressPointerType} from '../hooks/menuPressGesture';
import {useTypeahead} from '../hooks/useTypeahead';
import {useFocusReturnVisibility} from '../hooks/useFocusReturnVisibility';
@@ -129,6 +133,9 @@ import english from '../i18n/generated-english/DropdownMenu/DropdownMenu.generat
registerEnglishFallback(english);
+/** Taps stay held from the open until the touch grow shows. */
+const MENU_SURFACE_MOTION = {holdUntilFirstFrame: true};
+
// The menu's own lower cap on the placement axis; the viewport cap underneath
// it is the layer runtime's (spec:AST-059 FR3).
const MENU_BLOCK_CAP = '300px';
@@ -1043,6 +1050,20 @@ function DropdownMenuPopover({
}
}, []);
+ // The touch presentation's grow out of the trigger and shrink back into
+ // it, on Popover's own surface motion (Popover/usePopoverSurfaceMotion.ts).
+ const surfaceMotion = usePopoverSurfaceMotion(MENU_SURFACE_MOTION);
+ // The gesture of a finger's or a pen's open, a tap's open at its lift
+ // included, until the layer shows. A show in another gesture, such as a
+ // later open from code, plays the layer's own entrance.
+ const touchOpenRef = useRef<{
+ gesture: number;
+ waitsForShow?: boolean;
+ } | null>(null);
+ // Runs as the menu opens, before it paints; set once `usePopoverInternal`
+ // has returned the surface it presents.
+ const presentSurfaceRef = useRef<() => void>(() => {});
+
// Focus lands somewhere stated when the menu closes. A press outside that
// landed on a focusable control has already moved focus there; leave it.
// Otherwise — a row acted, Escape, a press on nothing — focus returns to
@@ -1050,6 +1071,7 @@ function DropdownMenuPopover({
// keyboard (the modality tracker decides; the suppressed style hides the
// pointer case, which Safari would otherwise paint after a touch pick).
const handleLayerHide = useCallback(() => {
+ touchOpenRef.current = null;
releaseEntranceRef.current?.();
releaseEntranceRef.current = null;
// Whatever closed the menu — light dismiss, the dismissal stack, Escape
@@ -1108,6 +1130,7 @@ function DropdownMenuPopover({
openModalityRef.current = 'keyboard';
shouldFocusOnOpenRef.current = false;
focusLastOnOpenRef.current = false;
+ touchOpenRef.current = null;
}, []);
// Synchronizes the dialog's name from the custom trigger's DOM, an external
@@ -1123,6 +1146,8 @@ function DropdownMenuPopover({
const handleLayerShow = useCallback(() => {
acceptedOpenRef.current = true;
holdOpeningPressRef.current();
+ presentSurfaceRef.current();
+ touchOpenRef.current = null;
holdEntranceRef.current();
resetFocusReturn();
if (renderTrigger != null) {
@@ -1154,6 +1179,7 @@ function DropdownMenuPopover({
restoreFocusTo,
onHide: handleLayerHide,
onShow: handleLayerShow,
+ onCloseStart: surfaceMotion.closeStart,
hasLightDismiss: true,
// The menu, not the layer, owns what a touch outside that pans does.
ownsOutsidePan: true,
@@ -1175,6 +1201,22 @@ function DropdownMenuPopover({
xstyle: layerAnimations[placement],
onOpenPendingChange: handleOpenPendingChange,
});
+ // The layer's show handler calls this as the menu opens. It reads the
+ // surface and the trigger when it runs.
+ useCommittedRefInto(presentSurfaceRef, () => {
+ const surface = popover.contentRef.current;
+ // A finger's or a pen's open grows the menu. Under Reduce Motion the
+ // animator decides: a fade at full size on a coarse pointer, at once
+ // elsewhere.
+ surfaceMotion.present(
+ surface,
+ buttonRef.current,
+ null,
+ pressTouchModel === 'uikit' &&
+ (touchOpenRef.current?.waitsForShow === true ||
+ touchOpenRef.current?.gesture === currentGesture()),
+ );
+ });
const closeMenu = useCallback(() => {
if (openPendingRef.current) {
@@ -1240,6 +1282,9 @@ function DropdownMenuPopover({
pendingControlledOpenRef.current = false;
if (!popover.isOpen) {
shouldFocusOnOpenRef.current = !isMountedOpenRef.current;
+ // A trigger's open has already shown the menu, so this show is an
+ // open from code, with no accepted press.
+ touchOpenRef.current = null;
popover.show();
}
} else {
@@ -1422,6 +1467,9 @@ function DropdownMenuPopover({
modality: 'keyboard' | 'pointer' = 'keyboard',
notifyClick = false,
): 'open' | 'pending' | 'refused' => {
+ if (modality === 'keyboard') {
+ touchOpenRef.current = null;
+ }
// An unavailable trigger never opens the menu. Button keeps an
// aria-disabled trigger focusable for its tooltip and swallows only
// Enter and Space, so the arrow keys, a press and a click would still
@@ -1429,6 +1477,7 @@ function DropdownMenuPopover({
if (
buttonRef.current?.matches(':disabled, [aria-disabled="true"]') === true
) {
+ touchOpenRef.current = null;
disarmOpen();
return 'refused';
}
@@ -1444,6 +1493,11 @@ function DropdownMenuPopover({
// The layer can accept the open and hold it until the trigger is a
// valid anchor. The armed focus and click then wait for that open.
if (openPendingRef.current) {
+ // A finger's open still grows when it shows, also after a key press
+ // has started another gesture.
+ if (touchOpenRef.current?.gesture === currentGesture()) {
+ touchOpenRef.current = {...touchOpenRef.current, waitsForShow: true};
+ }
return 'pending';
}
disarmOpen();
@@ -1507,6 +1561,8 @@ function DropdownMenuPopover({
focusForLastInput(buttonRef.current, {preventScroll: true});
}
openingPressRef.current = {gesture: currentGesture()};
+ touchOpenRef.current =
+ pointerType !== 'mouse' ? {gesture: currentGesture()} : null;
const didOpen = openAndFocus('pointer', true) === 'open';
// A mouse can release away from the trigger, or the trigger can move
// away under it. So the layer claims a mouse's press, and that release
@@ -1534,7 +1590,7 @@ function DropdownMenuPopover({
// The press model: the row under a release acts, the highlight follows a
// held pointer. A mouse released outside the menu dismisses it; a finger
// released outside leaves it open, so the hook never calls onDismiss then.
- const menuPress = useMenuPress({
+ const {press: menuPress, triggerClickPointerType} = useMenuPressInternal({
menuRef: listRef,
triggerRef: buttonRef,
itemSelector: MENU_ITEM_SELECTOR,
@@ -1559,22 +1615,34 @@ function DropdownMenuPopover({
// activation): treat it as keyboard so those users still land on the
// first item. Real pointer clicks report detail >= 1.
const modality = e.detail === 0 ? 'keyboard' : 'pointer';
+ const pressPointerType = triggerClickPointerType();
+ // Only a click that opens the menu marks a finger's or a pen's open.
+ const openFromClick = () => {
+ touchOpenRef.current =
+ modality === 'pointer' &&
+ pressPointerType != null &&
+ pressPointerType !== 'mouse'
+ ? {gesture: currentGesture()}
+ : null;
+ openAndFocus(modality, true);
+ };
if (isControlled) {
if (controlledIsOpen) {
onClick?.();
onOpenChange?.(false);
} else {
- openAndFocus(modality, true);
+ openFromClick();
}
} else if (popover.isOpen) {
onClick?.();
popover.hide();
} else {
- openAndFocus(modality, true);
+ openFromClick();
}
},
[
menuPress,
+ triggerClickPointerType,
onClick,
isControlled,
onOpenChange,
diff --git a/packages/core/src/DropdownMenu/DropdownMenuTouchGrow.test.tsx b/packages/core/src/DropdownMenu/DropdownMenuTouchGrow.test.tsx
new file mode 100644
index 0000000000000..5fb5440225fbc
--- /dev/null
+++ b/packages/core/src/DropdownMenu/DropdownMenuTouchGrow.test.tsx
@@ -0,0 +1,512 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file DropdownMenuTouchGrow.test.tsx
+ * @input DropdownMenu, with the grow replaced by a recorder
+ * @output Which opens grow the menu out of its trigger. A finger's or a
+ * pen's open grows it, a tap's open at its lift included, and under Reduce
+ * Motion its open and close still play the surface motion. A mouse's open,
+ * the keyboard's and a menu pinned to the pointer presentation do not.
+ * @position Unit coverage of DropdownMenu's touch grow decision
+ * (Popover/usePopoverSurfaceMotion.ts). The browser spec
+ * covers the frames.
+ */
+
+import {act, fireEvent, render, screen} from '@testing-library/react';
+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';
+import {__resetMenuPressForTest} from '../hooks/useMenuPress';
+import type * as InputHold from '../Layer/inputHold';
+import type * as PopoverSurfaceMotion from '../Popover/popoverSurfaceMotion';
+import {scroll} from '../motion/uikit/scroll';
+import {DropdownMenu, type DropdownMenuOption} from './DropdownMenu';
+import {reducedMotionMarkProps} from '../privateAttributes/reducedMotion.stylex';
+import {TOUCH_QUERY} from '../utils/touchQueries';
+
+const motion = vi.hoisted(() => ({
+ enter: vi.fn(),
+ exit: vi.fn(),
+ reset: vi.fn(),
+ dispose: vi.fn(),
+}));
+vi.mock('../Popover/popoverSurfaceMotion', async importOriginal => ({
+ ...(await importOriginal()),
+ createPopoverSurfaceMotion: vi.fn(() => motion),
+}));
+const entranceHold = vi.hoisted(() => vi.fn(() => null));
+vi.mock('../Layer/holdEntranceInput', () => ({
+ holdEntranceInput: entranceHold,
+}));
+// Counts the input holds that are up. jsdom hit-tests nothing, so no shield
+// is drawn.
+const inputHolds = vi.hoisted(() => ({up: 0}));
+vi.mock('../Layer/inputHold', async importOriginal => ({
+ ...(await importOriginal()),
+ holdInput: (_layer: Element, {until}: InputHold.InputHoldOptions) => {
+ inputHolds.up += 1;
+ let isUp = true;
+ const end = () => {
+ if (isUp) {
+ isUp = false;
+ inputHolds.up -= 1;
+ }
+ };
+ const settles = 'finished' in until ? until.finished : until;
+ void Promise.resolve(settles).then(end, end);
+ return end;
+ },
+}));
+
+const ITEMS: DropdownMenuOption[] = [{label: 'Edit'}, {label: 'Duplicate'}];
+
+// The trigger's layout box, which a press scales to 0.98 about its centre, as
+// Button's press does. Its box read carries that scale unless an override
+// takes the transform off.
+const TRIGGER_BOX = {left: 141, top: 160, width: 120, height: 44};
+function pressScale(trigger: HTMLElement) {
+ trigger.style.transform = 'scale(0.98)';
+ trigger.getBoundingClientRect = function (this: HTMLElement) {
+ const scale =
+ this.style.getPropertyValue('transform') === 'none' ? 1 : 0.98;
+ const width = TRIGGER_BOX.width * scale;
+ const height = TRIGGER_BOX.height * scale;
+ const left = TRIGGER_BOX.left + (TRIGGER_BOX.width - width) / 2;
+ const top = TRIGGER_BOX.top + (TRIGGER_BOX.height - height) / 2;
+ return {
+ left,
+ top,
+ width,
+ height,
+ x: left,
+ y: top,
+ right: left + width,
+ bottom: top + height,
+ toJSON: () => ({}),
+ };
+ };
+}
+
+// A scroll view as the press model's scroll probe reads one.
+function ScrollView({children}: {children: React.ReactNode}) {
+ return (
+