From 75391adb299d4efaac87a0b3e3f8dbdfd122b3e8 Mon Sep 17 00:00:00 2001 From: Christopher Chedeau Date: Mon, 9 Nov 2026 19:57:12 -0800 Subject: [PATCH 1/4] feat(DropdownMenu): a finger or a pen opens the menu as it presses Under a finger or a pen, a DropdownMenu or MoreMenu trigger opens its menu as it is pressed, instead of after a 500 ms hold (spec:AST-094 FR29, FR43). Inside a scroll view it opens once the 150 ms content-touch delay passes with no scroll, so a scroll that starts on the trigger still scrolls. The finger that opened the menu picks a row only after moving 10 px. presentation="popover" keeps the previous behavior. useMenuPress with no longPressDelayMs follows the same rules, and longPressDelayMs: 500 keeps the previous hold. --- .changeset/menu-press-public-default.md | 7 + .changeset/menu-press-uimenu.md | 7 + .../DropdownMenu/DropdownMenu.spec.md | 71 ++- packages/core/api-report.md | 2 +- .../core/src/Breadcrumbs/BreadcrumbItem.tsx | 4 +- packages/core/src/ContextMenu/ContextMenu.tsx | 4 +- .../src/DropdownMenu/DropdownMenu.doc.mjs | 4 +- .../src/DropdownMenu/DropdownMenu.test.tsx | 228 +++++++++- .../core/src/DropdownMenu/DropdownMenu.tsx | 21 +- .../src/DropdownMenu/DropdownMenuSubMenu.tsx | 4 +- .../MenuBottomSheetActionList.tsx | 4 +- ...MenuTouchPress.interaction.browser.spec.ts | 396 ++++++++++++++++ .../__tests__/MenuPress.a11y.chromium.spec.ts | 36 ++ packages/core/src/MoreMenu/MoreMenu.doc.mjs | 4 +- packages/core/src/MoreMenu/MoreMenu.tsx | 6 +- packages/core/src/NavMenu/NavHeadingMenu.tsx | 4 +- packages/core/src/Selector/Selector.tsx | 4 +- packages/core/src/SideNav/SideNavHeading.tsx | 4 +- packages/core/src/TabList/TabMenu.tsx | 4 +- packages/core/src/TopNav/TopNavHeading.tsx | 4 +- packages/core/src/TopNav/TopNavMenu.tsx | 4 +- packages/core/src/hooks/menuPressGesture.ts | 26 +- .../core/src/hooks/menuPressValues.test.ts | 13 +- packages/core/src/hooks/menuPressValues.ts | 18 +- packages/core/src/hooks/menuScrollView.ts | 22 + packages/core/src/hooks/menuTriggerPress.ts | 226 +++++++++ packages/core/src/hooks/useMenuPress.doc.mjs | 26 +- packages/core/src/hooks/useMenuPress.test.tsx | 427 +++++++++++++++++- packages/core/src/hooks/useMenuPress.ts | 355 ++++++++------- packages/core/src/motion/MEASUREMENTS.md | 8 +- packages/core/src/motion/uikit/gestures.ts | 21 +- 31 files changed, 1661 insertions(+), 303 deletions(-) create mode 100644 .changeset/menu-press-public-default.md create mode 100644 .changeset/menu-press-uimenu.md create mode 100644 packages/core/src/DropdownMenu/__tests__/DropdownMenuTouchPress.interaction.browser.spec.ts create mode 100644 packages/core/src/hooks/menuScrollView.ts create mode 100644 packages/core/src/hooks/menuTriggerPress.ts diff --git a/.changeset/menu-press-public-default.md b/.changeset/menu-press-public-default.md new file mode 100644 index 0000000000000..050b2f23dca26 --- /dev/null +++ b/.changeset/menu-press-public-default.md @@ -0,0 +1,7 @@ +--- +'@astryxdesign/core': patch +--- + +[feature] `useMenuPress` with no `longPressDelayMs` now follows DropdownMenu's finger rules on every device (`spec:AST-094` FR25, FR29, FR43): a finger or a pen opens the menu as it presses (inside a scroll view, once the 150 ms content-touch delay has passed), and the finger that opened it picks a row only after moving 10 px. To keep the previous behavior, a 500 ms hold and a pick at the opening finger's lift, pass `longPressDelayMs: 500`. + +@vjeux diff --git a/.changeset/menu-press-uimenu.md b/.changeset/menu-press-uimenu.md new file mode 100644 index 0000000000000..adf1c6b6cd86f --- /dev/null +++ b/.changeset/menu-press-uimenu.md @@ -0,0 +1,7 @@ +--- +'@astryxdesign/core': patch +--- + +[feature] Under a finger or a pen, on every device, a DropdownMenu or MoreMenu trigger now opens its menu as it is pressed, instead of after a 500 ms hold (`spec:AST-094` FR29, FR43). Inside a scroll view it opens once the 150 ms content-touch delay has passed with no scroll, so a scroll that starts on it still scrolls. To keep the previous behavior, a tap that opens at the lift and a 500 ms hold, pass `presentation="popover"`. A mouse is unchanged. + +@vjeux diff --git a/docs/specs/components/DropdownMenu/DropdownMenu.spec.md b/docs/specs/components/DropdownMenu/DropdownMenu.spec.md index d93a49e5e7977..ab1b071fb336a 100644 --- a/docs/specs/components/DropdownMenu/DropdownMenu.spec.md +++ b/docs/specs/components/DropdownMenu/DropdownMenu.spec.md @@ -16,6 +16,7 @@ verified_by: packages/core/src/DropdownMenu/DropdownMenuSubMenu.test.tsx, 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/__tests__/MenuHeaderFooter.a11y.chromium.spec.ts, packages/core/src/DropdownMenu/__tests__/SubMenuHeaderFooter.a11y.chromium.spec.ts, packages/core/src/ContextMenu/ContextMenu.test.tsx, @@ -39,15 +40,15 @@ system_specs: [spec:AST-020/FR15, spec:AST-094, spec:AST-102] ## 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 after a 500 ms hold or at a tap's click, 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. Finger press-open (FR8), 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 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`. | This table is a review projection; the body below is authoritative. @@ -131,7 +132,7 @@ component-local concepts; each keeps its released default. | FR5 | Both menu surfaces carry `data-astryx-menu-press` and follow `module:DropdownMenu/useMenuPress` FR1–FR7, FR10, and FR11: the row under the release acts, the highlight follows a held pointer, a mouse released outside closes and a finger leaves the menu open, the browser's stray click never acts, and the Pointer menu surface declares `touch-action` by overflow. The grow, collapse, and pan dismissal under a finger are FR21. | `module:DropdownMenu/useMenuPress`; `spec:AST-094` FR26–FR28 | | FR6 | When the pointer menu closes, focus returns to the Trigger button with a visible ring only when the menu was driven by keyboard, and after a pointer pick the returned focus opens no trigger tooltip (`component:Tooltip` FR4); a press outside that landed on a focusable control keeps focus there. | `architecture:interaction-modality` INV1; DEC-1 | | FR7 | `menuMaxHeight` replaces the 300px term of the menu's and its popover viewport's block-size cap while the viewport gutters still bound both; the touch sheet ignores it. | DEC-2 | -| FR8 | The Trigger button opens the pointer menu on a mouse press-down, with a settle rule on the opening release, and pressing the trigger of an open menu closes it without reopening in the same gesture; a mouse click and the keyboard open as before. The mouse press-open is shipped behavior, not a requirement until `module:DropdownMenu/useMenuPress` DEC-4 is ruled. Under a finger the trigger MUST open the menu as `spec:AST-094` FR29 states: as the finger presses in a fixed bar, after the 150 ms content-touch delay or at a tap's lift inside a scroll view; `presentation="popover"` keeps the tap open. Implementation gap: a held finger opens it after a 500 ms hold, and a tap opens it at its click. | `module:DropdownMenu/useMenuPress` FR8, FR9; `spec:AST-094` FR29 | +| FR8 | The Trigger button opens the pointer menu on a mouse press-down, with a settle rule on the opening release, and pressing the trigger of an open menu closes it without reopening in the same gesture; a mouse click and the keyboard open as before. The mouse press-open is shipped behavior, not a requirement until `module:DropdownMenu/useMenuPress` DEC-4 is ruled. Under a finger the trigger MUST open the menu as `spec:AST-094` FR29 states: as the finger presses in a fixed bar, after the 150 ms content-touch delay or at a tap's lift inside a scroll view; `presentation="popover"` keeps the tap open. | `module:DropdownMenu/useMenuPress` FR8, FR9; `spec:AST-094` FR29 | | FR9 | With `renderTrigger`, the rendered control carries `aria-haspopup`, `aria-expanded`, `aria-controls` and the `id` the menu's `aria-labelledby` points at, and receives the same press-model, keyboard-open and toggle-click handlers as the Button path; the menu is named by that control. A disabled custom trigger never opens the menu or the sheet. `button` and `renderTrigger` are mutually exclusive: both given, `renderTrigger` wins and a dev warning fires, in both presentations. A drilled-in Back row (FR11) returns to the menu by that same name: the caller's `aria-label` when given, else the control's accessible name, read as the menu opens. | DEC-3 | | FR10 | An action row with `href` renders as one anchor carrying `role="menuitem"` (the pointer menu) or the touch sheet's link row, routed through `LinkProvider`; a plain click runs `onClick`, then closes the menu (`hasCloseOnSelect`), then lets the browser navigate; a modified click does not run `onClick`, closes the menu, and is left to the browser; in the pointer menu a middle click closes the menu (`hasCloseOnSelect`), then runs the caller's `onAuxClick`, while the touch sheet leaves a middle click to the browser and stays open; a right click is left to the context menu; Enter and Space activate through a synthesized click that carries the key's modifiers. A disabled link row has no `href`; a blocked destination renders inertly. | Current behavior; `family:navigation-destinations` | | FR11 | When a compact touch display opened the pointer menu (the query the root presentation uses for its bottom sheet, sampled once as it opens), an `adaptive` sub-menu row drills in: its rows and a leading Back row named "Back to " replace the menu's rows in the same Pointer menu surface, no flyout opens, the drilled list is a `menu` named by the row's label, and Back, Escape and ArrowLeft return to the row with focus on it; a pick inside closes the whole menu, and closing the menu resets the drilled view. Roving focus and typeahead scope to the shown rows; sibling rows and dividers need no knowledge of it. `presentation="flyout"` keeps the flyout; `"drill-in"` drills in on any pointer. | DEC-4; `spec:AST-094` FR34 | @@ -344,35 +345,33 @@ than adding a DropdownMenu-owned heading target. ## Verification map -| Contract | Verification | Representative states | Mutation or failure expectation | Audit section | -| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------- | -| FR1, FR4 | `DropdownMenu.test.tsx` rendering cases ("renders menu with role=\"menu\"", "renders data-driven actions in a bottom sheet when requested", "uses the BottomSheet for adaptive presentation on compact touch", "uses the shared menu BottomSheet frame", "keeps adaptive presentation anchored without compact touch") and section, divider, and compound cases | Root pointer, root touch, adaptive | A missing surface, sheet frame, or menu role fails. Evidence gap: no test asserts the `dropdown-menu` target on the Touch menu surface or `list-item` on touch rows. | `audit:DropdownMenu/anatomy` | -| FR2 | `DropdownMenu.test.tsx` theming-slot cases ("exposes a themeable slot on the section heading", "exposes a themeable slot on the menu divider"); `DropdownMenuSubMenu.test.tsx` "exposes a themeable slot on the submenu indicator icon"; `themingTargets.test.ts` | Heading, divider, submenu indicator | A missing heading, divider, or indicator target fails; a rendered class absent from the documented targets fails. Evidence gap: no test asserts `dropdown-menu`, `dropdown-menu-item`, or `dropdown-menu-radio` placement. | `audit:DropdownMenu/theming` | -| FR3 | `DropdownMenu.test.tsx` button customization, icon-only, and hasChevron cases | Button variants and sizes; icon-only; no chevron | A Button prop that stops reaching the trigger fails. Evidence gap: the delegated Trigger Button gaps are asserted by `component:Button`'s own records, and no test here asserts the BottomSheet, List, Indicator, or Icon delegation beyond rendering. | `audit:DropdownMenu/theming` | -| FR5 | `DropdownMenu.test.tsx` press-model cases ("a finger that lands on one row and lifts on another acts on the second, once", "a mouse released outside closes the menu; a finger released outside leaves it open", "marks the menu as carrying the press model and owns touch scrolling"); `MenuPress.a11y.chromium.spec.ts`; the module record's own map | Finger and mouse release; scrolling menu | A row that acts on press-down, a mouse release outside that keeps the menu, or a missing press marker fails. | `audit:DropdownMenu/behavior` | -| FR6 | `DropdownMenu.test.tsx` focus-return cases ("restores focus to the trigger after keyboard dismissal", "returns focus to the trigger after pointer dismissal without a focus ring", "leaves focus on the control a press outside landed on") and the "focus return after a pointer pick" and "a trigger the caller renders" cases | Keyboard and pointer close; Button and custom trigger | A lost focus return, a ring after a pointer close, no ring after a keyboard close, or focus pulled off a control pressed outside fails. | `audit:DropdownMenu/accessibility` | -| FR7 | `DropdownMenu.test.tsx` menuMaxHeight cases | A cap above 300px; viewport bound | A menu clipped to 300px under a raised cap, or one that escapes the viewport, fails. Evidence gap: no test asserts that the touch sheet ignores the cap. | `audit:DropdownMenu/layout` | -| FR8 | `DropdownMenu.test.tsx` press-model trigger cases ("a mouse press on the trigger opens the menu and a drag-release acts on the row under it", "the opening release before the settle time acts on nothing and the menu stays", "pressing the trigger of an open menu closes it and does not reopen it in the same gesture", "a held touch on the trigger opens with the finger down and a slide picks", "a tap on the trigger still opens through its click") | Mouse press-open; held finger; tap | A mouse that opens only on click, an opening release that acts early, or a re-open in the closing gesture fails. The held-touch case asserts the current 500 ms hold, the FR8 gap pending conformance. | `audit:DropdownMenu/behavior` | -| FR8 | `DropdownMenuOpeningRelease.interaction.browser.spec.ts` (Chromium, WebKit): an opening release off the trigger, under a trigger that moved away, or on the trigger after a show that waited leaves the menu open; a settled release outside closes it | Mouse release off the trigger | An opening release before the settle time that the browser's light dismiss closes fails | `audit:DropdownMenu/behavior` | -| FR9, AR1 | `DropdownMenu.test.tsx` custom trigger cases; `DropdownMenuSubMenu.test.tsx` "a menu hung off a custom trigger" cases | Custom trigger open, keyboard, mouse, disabled; both props given; Back row names | A custom trigger that does not open, toggle, or name the menu, a disabled one that opens, a missing warning, or a wrong Back row name fails. | `audit:DropdownMenu/accessibility` | -| FR10, AR2, ORD1 | `DropdownMenu.test.tsx` "DropdownMenuItem href" and "link rows — the browser's own clicks" cases | Plain, modified, middle, and right click; Enter; bottom sheet; disabled; blocked | A row that is not an anchor, a modified click that runs `onClick`, a middle click that does not close, a disabled row with an address, or a live blocked destination fails. Evidence gap: no test asserts the order of `onClick`, close, and navigation. | `audit:DropdownMenu/behavior` | -| FR11, AR3 | `DropdownMenuSubMenu.test.tsx` "drill-in on a phone" cases; `DropdownMenuDrillIn.a11y.chromium.spec.ts` | Phone and laptop; forced presentations; theme breakpoint; reset on close | A flyout on a phone, a drill-in on a laptop by default, a wrong name, a Back that loses focus, or a drilled view that survives a close fails. | `audit:DropdownMenu/accessibility` | -| FR12, AR4 | `DropdownMenu.test.tsx` keyboard cases ("ArrowDown on the last row wraps to the first, ArrowUp on the first to the last", "ArrowUp on the trigger opens with the last row highlighted", "PageDown moves to the last row and PageUp back to the first", "the opening key's auto-repeat does not act on the highlighted row"), open-focus cases, typeahead cases, and "has aria-haspopup and aria-expanded attributes" | Wrap, Page keys, open keys, auto-repeat, typeahead | A missing wrap, a Page key that does not move, an ArrowUp open on the first row, an auto-repeat that acts, or a missing typeahead match fails. Evidence gap: no test asserts PageDown past the visible rows, typeahead ignoring chords or composition, or `aria-controls` on the Button trigger. | `audit:DropdownMenu/accessibility` | -| FR13 | `DropdownMenuSubMenu.test.tsx` safe-triangle cases | Diagonal path, pause inside, leaving both | A flyout that closes inside the triangle or stays open after leaving it fails. | `audit:DropdownMenu/behavior` | -| FR14 | `DropdownMenu.test.tsx` section cases | Titled and untitled sections | A missing group role or title fails. | `audit:DropdownMenu/accessibility` | -| 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` | -| 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` | -| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and targets | Missing, extra, prefixed, stale, or alias-backed mappings fail repository validation. | `audit:DropdownMenu/theming` | +| Contract | Verification | Representative states | Mutation or failure expectation | Audit section | +| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------- | +| FR1, FR4 | `DropdownMenu.test.tsx` rendering cases ("renders menu with role=\"menu\"", "renders data-driven actions in a bottom sheet when requested", "uses the BottomSheet for adaptive presentation on compact touch", "uses the shared menu BottomSheet frame", "keeps adaptive presentation anchored without compact touch") and section, divider, and compound cases | Root pointer, root touch, adaptive | A missing surface, sheet frame, or menu role fails. Evidence gap: no test asserts the `dropdown-menu` target on the Touch menu surface or `list-item` on touch rows. | `audit:DropdownMenu/anatomy` | +| FR2 | `DropdownMenu.test.tsx` theming-slot cases ("exposes a themeable slot on the section heading", "exposes a themeable slot on the menu divider"); `DropdownMenuSubMenu.test.tsx` "exposes a themeable slot on the submenu indicator icon"; `themingTargets.test.ts` | Heading, divider, submenu indicator | A missing heading, divider, or indicator target fails; a rendered class absent from the documented targets fails. Evidence gap: no test asserts `dropdown-menu`, `dropdown-menu-item`, or `dropdown-menu-radio` placement. | `audit:DropdownMenu/theming` | +| FR3 | `DropdownMenu.test.tsx` button customization, icon-only, and hasChevron cases | Button variants and sizes; icon-only; no chevron | A Button prop that stops reaching the trigger fails. Evidence gap: the delegated Trigger Button gaps are asserted by `component:Button`'s own records, and no test here asserts the BottomSheet, List, Indicator, or Icon delegation beyond rendering. | `audit:DropdownMenu/theming` | +| FR5 | `DropdownMenu.test.tsx` press-model cases ("a finger that lands on one row and lifts on another acts on the second, once", "a mouse released outside closes the menu; a finger released outside leaves it open", "marks the menu as carrying the press model and owns touch scrolling"); `MenuPress.a11y.chromium.spec.ts`; the module record's own map | Finger and mouse release; scrolling menu | A row that acts on press-down, a mouse release outside that keeps the menu, or a missing press marker fails. | `audit:DropdownMenu/behavior` | +| FR6 | `DropdownMenu.test.tsx` focus-return cases ("restores focus to the trigger after keyboard dismissal", "returns focus to the trigger after pointer dismissal without a focus ring", "leaves focus on the control a press outside landed on") and the "focus return after a pointer pick" and "a trigger the caller renders" cases | Keyboard and pointer close; Button and custom trigger | A lost focus return, a ring after a pointer close, no ring after a keyboard close, or focus pulled off a control pressed outside fails. | `audit:DropdownMenu/accessibility` | +| FR7 | `DropdownMenu.test.tsx` menuMaxHeight cases | A cap above 300px; viewport bound | A menu clipped to 300px under a raised cap, or one that escapes the viewport, fails. Evidence gap: no test asserts that the touch sheet ignores the cap. | `audit:DropdownMenu/layout` | +| FR8 | `DropdownMenu.test.tsx` press-model trigger cases ("a mouse press on the trigger opens the menu and a drag-release acts on the row under it", "the opening release before the settle time acts on nothing and the menu stays", "pressing the trigger of an open menu closes it and does not reopen it in the same gesture", "under a coarse pointer a finger opens the menu as it presses the trigger (no scroll view), and a slide picks", "a tap on the trigger opens the menu on the press, and its click does not close it") | Mouse press-open; held finger; tap | A mouse that opens only on click, an opening release that acts early, or a re-open in the closing gesture fails. A finger press that waits for a hold, or a tap whose click toggles the menu its press opened, fails. | `audit:DropdownMenu/behavior` | +| FR8 | `DropdownMenuOpeningRelease.interaction.browser.spec.ts` (Chromium, WebKit): an opening release off the trigger, under a trigger that moved away, or on the trigger after a show that waited leaves the menu open; a settled release outside closes it | Mouse release off the trigger | An opening release before the settle time that the browser's light dismiss closes fails | `audit:DropdownMenu/behavior` | +| FR9, AR1 | `DropdownMenu.test.tsx` custom trigger cases; `DropdownMenuSubMenu.test.tsx` "a menu hung off a custom trigger" cases | Custom trigger open, keyboard, mouse, disabled; both props given; Back row names | A custom trigger that does not open, toggle, or name the menu, a disabled one that opens, a missing warning, or a wrong Back row name fails. | `audit:DropdownMenu/accessibility` | +| FR10, AR2, ORD1 | `DropdownMenu.test.tsx` "DropdownMenuItem href" and "link rows — the browser's own clicks" cases | Plain, modified, middle, and right click; Enter; bottom sheet; disabled; blocked | A row that is not an anchor, a modified click that runs `onClick`, a middle click that does not close, a disabled row with an address, or a live blocked destination fails. Evidence gap: no test asserts the order of `onClick`, close, and navigation. | `audit:DropdownMenu/behavior` | +| FR11, AR3 | `DropdownMenuSubMenu.test.tsx` "drill-in on a phone" cases; `DropdownMenuDrillIn.a11y.chromium.spec.ts` | Phone and laptop; forced presentations; theme breakpoint; reset on close | A flyout on a phone, a drill-in on a laptop by default, a wrong name, a Back that loses focus, or a drilled view that survives a close fails. | `audit:DropdownMenu/accessibility` | +| FR12, AR4 | `DropdownMenu.test.tsx` keyboard cases ("ArrowDown on the last row wraps to the first, ArrowUp on the first to the last", "ArrowUp on the trigger opens with the last row highlighted", "PageDown moves to the last row and PageUp back to the first", "the opening key's auto-repeat does not act on the highlighted row"), open-focus cases, typeahead cases, and "has aria-haspopup and aria-expanded attributes" | Wrap, Page keys, open keys, auto-repeat, typeahead | A missing wrap, a Page key that does not move, an ArrowUp open on the first row, an auto-repeat that acts, or a missing typeahead match fails. Evidence gap: no test asserts PageDown past the visible rows, typeahead ignoring chords or composition, or `aria-controls` on the Button trigger. | `audit:DropdownMenu/accessibility` | +| FR13 | `DropdownMenuSubMenu.test.tsx` safe-triangle cases | Diagonal path, pause inside, leaving both | A flyout that closes inside the triangle or stays open after leaving it fails. | `audit:DropdownMenu/behavior` | +| FR14 | `DropdownMenu.test.tsx` section cases | Titled and untitled sections | A missing group role or title fails. | `audit:DropdownMenu/accessibility` | +| 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` | +| 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` | +| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and targets | Missing, extra, prefixed, stale, or alias-backed mappings fail repository validation. | `audit:DropdownMenu/theming` | ## Current-state impact -- **Finger press-open (FR8).** A held finger opens the menu after a 500 ms - hold, and a tap at its click, instead of as `spec:AST-094` FR29 states. - **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 diff --git a/packages/core/api-report.md b/packages/core/api-report.md index 7fe253d6ab808..72aa27ef8ffae 100644 --- a/packages/core/api-report.md +++ b/packages/core/api-report.md @@ -6085,7 +6085,7 @@ interface UseMenuPressOptions hitTest?: (x: number, y: number) => Element | null isEnabled?: boolean = true itemSelector: string - longPressDelayMs?: number = 500 + longPressDelayMs?: number menuRef: RefObject onActivate?: (row: HTMLElement, release: PointerEvent) => void onDismiss?: () => void diff --git a/packages/core/src/Breadcrumbs/BreadcrumbItem.tsx b/packages/core/src/Breadcrumbs/BreadcrumbItem.tsx index a2d1f85b7f9ab..8291507c51ff9 100644 --- a/packages/core/src/Breadcrumbs/BreadcrumbItem.tsx +++ b/packages/core/src/Breadcrumbs/BreadcrumbItem.tsx @@ -52,7 +52,7 @@ import {focusOutlineProps} from '../utils/focusOutline.stylex'; import {Icon} from '../Icon'; import {usePopover} from '../Popover/usePopover'; import {useListFocus} from '../hooks/useListFocus'; -import {useMenuPress} from '../hooks/useMenuPress'; +import {useMenuSurfacePress} from '../hooks/useMenuPress'; import {pressOnItemsOnly} from '../hooks/menuPressOnItems'; import {menuTouchActionStyles} from '../DropdownMenu/menuTouchAction.stylex'; import {useMenuOverflow} from '../DropdownMenu/useMenuOverflow'; @@ -585,7 +585,7 @@ function BreadcrumbMenuTrigger({ // A press that slides across the menu's items acts on the item it lifts on, // the highlight following the pointer, as DropdownMenu's does // (`family:action-groups` FR1-FR3, FR5); a mouse released outside closes it. - const menuPress = useMenuPress({ + const menuPress = useMenuSurfacePress({ menuRef: listRef, itemSelector: MENU_ITEM_SELECTOR, onDismiss: closeMenu, diff --git a/packages/core/src/ContextMenu/ContextMenu.tsx b/packages/core/src/ContextMenu/ContextMenu.tsx index 5f6c2ef64a906..2da3a4496c68b 100644 --- a/packages/core/src/ContextMenu/ContextMenu.tsx +++ b/packages/core/src/ContextMenu/ContextMenu.tsx @@ -78,7 +78,7 @@ import { import {useMenuOverflow} from '../DropdownMenu/useMenuOverflow'; import {useMenuDrillIn} from '../DropdownMenu/useMenuDrillIn'; import {useInternalListFocus} from '../hooks/useListFocus'; -import {useMenuPress} from '../hooks/useMenuPress'; +import {useMenuSurfacePress} from '../hooks/useMenuPress'; import {useTypeahead} from '../hooks/useTypeahead'; import {useLongPress} from '../hooks/useLongPress'; import {layerAnimations} from '../Layer/layerAnimations.stylex'; @@ -768,7 +768,7 @@ export function ContextMenu({ // The press model: the row under a release acts, the highlight follows a // held pointer, a mouse released outside dismisses and a finger leaves the // menu open. - const menuPress = useMenuPress({ + const menuPress = useMenuSurfacePress({ menuRef: listRef, itemSelector: MENU_ITEM_SELECTOR, onDismiss: closeMenu, diff --git a/packages/core/src/DropdownMenu/DropdownMenu.doc.mjs b/packages/core/src/DropdownMenu/DropdownMenu.doc.mjs index 43a75cb0e587a..0eb3e1264dbd1 100644 --- a/packages/core/src/DropdownMenu/DropdownMenu.doc.mjs +++ b/packages/core/src/DropdownMenu/DropdownMenu.doc.mjs @@ -187,7 +187,7 @@ export const docs = { name: 'renderTrigger', type: '(props: DropdownMenuTriggerProps) => ReactNode', description: - 'Render the control the menu hangs off — an IconButton, a chip, an avatar, a list row — instead of the built-in Button. Spread the given props onto it: they carry the press model (a mouse opens on press-down, a held finger opens with the finger down), the keyboard opens, the toggle click, and `aria-haspopup`/`aria-expanded`/`aria-controls`/`id`; the menu is then named by that control through `aria-labelledby`. Mutually exclusive with `button`.', + 'Render the control the menu hangs off — an IconButton, a chip, an avatar, a list row — instead of the built-in Button. Spread the given props onto it: they carry the press model (a mouse opens on press-down, a finger or a pen opens as it presses), the keyboard opens, the toggle click, and `aria-haspopup`/`aria-expanded`/`aria-controls`/`id`; the menu is then named by that control through `aria-labelledby`. Mutually exclusive with `button`.', }, { @@ -201,7 +201,7 @@ export const docs = { name: 'presentation', type: "'popover' | 'bottom-sheet' | 'adaptive'", description: - "Presentation surface for data-driven items. 'popover' stays anchored, 'bottom-sheet' always renders the actions in a modal BottomSheet, and 'adaptive' uses a BottomSheet on compact coarse-pointer layouts while remaining anchored elsewhere. Compound children currently support popover only. Omitted, the menu is anchored, and under a finger, on every device, the finger that opened it picks a row only after moving 10 px. Pass 'popover' to keep the pointer behavior on every device, the settle rule included.", + "Presentation surface for data-driven items. 'popover' stays anchored, 'bottom-sheet' always renders the actions in a modal BottomSheet, and 'adaptive' uses a BottomSheet on compact coarse-pointer layouts while remaining anchored elsewhere. Compound children currently support popover only. Omitted, the menu is anchored, and under a finger or a pen, on every device, its trigger opens as it is pressed (inside a scroll view, after the 150 ms content-touch delay), and the opening finger picks after moving 10 px. Pass 'popover' to keep the pointer behavior on every device, a 500 ms hold included.", }, { name: 'isMenuOpen', diff --git a/packages/core/src/DropdownMenu/DropdownMenu.test.tsx b/packages/core/src/DropdownMenu/DropdownMenu.test.tsx index 121de94761d4f..cdd5d45a07a6b 100644 --- a/packages/core/src/DropdownMenu/DropdownMenu.test.tsx +++ b/packages/core/src/DropdownMenu/DropdownMenu.test.tsx @@ -3379,27 +3379,30 @@ describe('DropdownMenu press model', () => { expect(HTMLElement.prototype.showPopover).toHaveBeenCalledTimes(1); }); - it('a held touch on the trigger opens with the finger down, and a slide past the handoff picks (spec:AST-094 FR29, FR43)', () => { + it('under a coarse pointer a finger opens the menu as it presses the trigger (no scroll view), and a slide picks', () => { + stubCoarsePointer(); vi.useFakeTimers(); try { const onPick = vi.fn(); const trigger = renderMenu(onPick); + // A trigger in no scroll view opens on the press. fireEvent.pointerDown(trigger, {...touch, clientX: 0, clientY: 0}); - expect(trigger).toHaveAttribute('aria-expanded', 'false'); - act(() => { - vi.advanceTimersByTime(500); - }); expect(trigger).toHaveAttribute('aria-expanded', 'true'); - // The handoff counts from the first position the open menu sees. + // UIMenu's handoff: the finger picks once it travels from the first + // sample the menu saw. fireEvent.pointerMove(item('Delete'), {...touch, clientX: 0, clientY: 3}); - const past = { + expect(item('Delete')).not.toHaveFocus(); + fireEvent.pointerMove(item('Delete'), { ...touch, clientX: 0, clientY: 3 + UIKIT_GESTURES.menuPress.handoff.value, - }; - fireEvent.pointerMove(item('Delete'), past); + }); expect(item('Delete')).toHaveFocus(); - fireEvent.pointerUp(item('Delete'), past); + fireEvent.pointerUp(item('Delete'), { + ...touch, + clientX: 0, + clientY: 3 + UIKIT_GESTURES.menuPress.handoff.value, + }); expect(onPick).toHaveBeenCalledWith('Delete'); // The click the browser aims at the trigger for this gesture is spent. fireEvent.click(trigger, {detail: 1}); @@ -3478,7 +3481,7 @@ describe('DropdownMenu press model', () => { }); it('presentation="popover" pins the settle rule under a finger: once the opening press has settled, a still lift picks the row under it', () => { - // spec:AST-094 FR25: a moved touch default comes back through + // A moved touch default comes back through // `presentation`, never through a public threshold. stubCoarsePointer(); vi.useFakeTimers(); @@ -3504,6 +3507,37 @@ describe('DropdownMenu press model', () => { } }); + it('presentation="popover" pins the released trigger under a finger: it opens at 500 ms, not on the press', () => { + // A moved touch default comes back through + // `presentation`, never through a public threshold. + stubCoarsePointer(); + vi.useFakeTimers(); + try { + const onPick = vi.fn<(label: string) => void>(); + render( + + onPick('Edit')} /> + onPick('Delete')} /> + , + ); + const trigger = screen.getByRole('button', {name: /Pinned/}); + fireEvent.pointerDown(trigger, {...touch, clientX: 0, clientY: 0}); + // Not on the press, as the touch modes would open it. + expect(trigger).toHaveAttribute('aria-expanded', 'false'); + act(() => { + vi.advanceTimersByTime(MENU_PRESS_LONG_PRESS_MS - 1); + }); + expect(trigger).toHaveAttribute('aria-expanded', 'false'); + act(() => { + vi.advanceTimersByTime(1); + }); + expect(MENU_PRESS_LONG_PRESS_MS).toBe(500); + expect(trigger).toHaveAttribute('aria-expanded', 'true'); + } finally { + vi.useRealTimers(); + } + }); + it('a menu a held finger opens keeps its trigger as the invoker until the finger lifts', () => { // A release on the trigger is outside the `popover="auto"` menu, so the // browser's light dismiss would close it; holding the invoker through @@ -3630,13 +3664,183 @@ describe('DropdownMenu press model', () => { }); }); - it('a tap on the trigger still opens through its click', () => { + it('a tap on the trigger opens the menu on the press, and its click does not close it', () => { const trigger = renderMenu(); fireEvent.pointerDown(trigger, touch); + expect(trigger).toHaveAttribute('aria-expanded', 'true'); fireEvent.pointerUp(trigger, touch); fireEvent.click(trigger, {detail: 1}); expect(trigger).toHaveAttribute('aria-expanded', 'true'); }); + + // A finger follows the menus' finger rules on every device: a touchscreen + // laptop (a fine primary pointer) as on a phone. Each gesture is still read + // as a finger or a mouse. `presentation="popover"` keeps the released + // finger behavior. + describe('a finger follows the same rules on every device; each gesture is still a finger or a mouse', () => { + function stubFinePointer() { + vi.stubGlobal( + 'matchMedia', + vi.fn().mockImplementation((query: string) => ({ + matches: false, + media: query, + onchange: null, + addEventListener: vi.fn(), + removeEventListener: vi.fn(), + addListener: vi.fn(), + removeListener: vi.fn(), + dispatchEvent: vi.fn(), + })), + ); + expect(window.matchMedia(TOUCH_QUERY).matches).toBe(false); + } + const touchmoveIsPrevented = () => { + const event = new Event('touchmove', {bubbles: true, cancelable: true}); + document.body.dispatchEvent(event); + return event.defaultPrevented; + }; + + it('fine primary pointer: a finger opens the menu as it presses the trigger, as on a phone (spec:AST-094 FR29, FR43)', () => { + stubFinePointer(); + const trigger = renderMenu(); + fireEvent.pointerDown(trigger, {...touch, clientX: 0, clientY: 0}); + expect(trigger).toHaveAttribute('aria-expanded', 'true'); + fireEvent.pointerUp(trigger, {...touch, clientX: 0, clientY: 0}); + // The tap's own click comes after the lift; it must not toggle. + fireEvent.click(trigger, {detail: 1}); + expect(trigger).toHaveAttribute('aria-expanded', 'true'); + }); + + it('fine primary pointer: a pen opens the menu as it presses the trigger, as a finger does (spec:AST-094 FR29, FR43; spec:AST-017 FR59)', () => { + stubFinePointer(); + const trigger = renderMenu(); + const pen = {pointerType: 'pen', pointerId: 7, clientX: 0, clientY: 0}; + fireEvent.pointerDown(trigger, pen); + expect(trigger).toHaveAttribute('aria-expanded', 'true'); + fireEvent.pointerUp(trigger, pen); + // The pen's own click comes after the lift; it must not toggle. + fireEvent.click(trigger, {detail: 1}); + expect(trigger).toHaveAttribute('aria-expanded', 'true'); + }); + + it('fine primary pointer, presentation="popover": a finger keeps the released behavior, its press opening nothing and its tap opening the menu through the click (spec:AST-094 FR25)', () => { + stubFinePointer(); + render( + + + + , + ); + const trigger = screen.getByRole('button', {name: /Pinned/}); + fireEvent.pointerDown(trigger, {...touch, clientX: 0, clientY: 0}); + expect(trigger).toHaveAttribute('aria-expanded', 'false'); + fireEvent.pointerUp(trigger, {...touch, clientX: 0, clientY: 0}); + fireEvent.click(trigger, {detail: 1}); + expect(trigger).toHaveAttribute('aria-expanded', 'true'); + }); + + it('fine primary pointer: the finger that opened the menu picks only once it travels the handoff, as on a phone (spec:AST-094 FR29, FR43)', () => { + stubFinePointer(); + const onPick = vi.fn<(label: string) => void>(); + const trigger = renderMenu(onPick); + fireEvent.pointerDown(trigger, {...touch, clientX: 0, clientY: 0}); + expect(trigger).toHaveAttribute('aria-expanded', 'true'); + // The finger's later touchmoves are the menu's, not a scroll. + expect(touchmoveIsPrevented()).toBe(true); + // A finger that barely moved lights nothing, however long it rests. + fireEvent.pointerMove(item('Delete'), {...touch, clientX: 0, clientY: 3}); + expect(item('Delete')).not.toHaveFocus(); + // UIMenu's handoff: the finger picks once it travels from the first + // sample the menu saw. + const handoff = 3 + UIKIT_GESTURES.menuPress.handoff.value; + fireEvent.pointerMove(item('Delete'), { + ...touch, + clientX: 0, + clientY: handoff, + }); + expect(item('Delete')).toHaveFocus(); + fireEvent.pointerUp(item('Delete'), { + ...touch, + clientX: 0, + clientY: handoff, + }); + expect(onPick).toHaveBeenCalledWith('Delete'); + expect(touchmoveIsPrevented()).toBe(false); + }); + + it('fine primary pointer: a finger that lifts outside the menu leaves it open; a mouse released outside closes it', async () => { + stubFinePointer(); + const user = userEvent.setup(); + const trigger = renderMenu(); + await user.click(trigger); + fireEvent.pointerDown(item('Edit'), touch); + fireEvent.pointerUp(document.body, touch); + expect(trigger).toHaveAttribute('aria-expanded', 'true'); + fireEvent.pointerDown(item('Edit'), mouse); + fireEvent.pointerUp(document.body, mouse); + expect(trigger).toHaveAttribute('aria-expanded', 'false'); + }); + + function renderCountingMenu() { + const onOpenChange = vi.fn<(isOpen: boolean) => void>(); + const onPick = vi.fn<(label: string) => void>(); + render( + + onPick('Edit')} /> + onPick('Delete')} /> + , + ); + return { + trigger: screen.getByRole('button', {name: /Actions/}), + onOpenChange, + onPick, + }; + } + + it('coarse primary pointer: a finger opens the menu once, as it presses, and it closes once at a pick (module AR5)', () => { + stubCoarsePointer(); + const {trigger, onOpenChange, onPick} = renderCountingMenu(); + fireEvent.pointerDown(trigger, {...touch, clientX: 0, clientY: 0}); + fireEvent.pointerUp(trigger, {...touch, clientX: 0, clientY: 0}); + // The tap's own click comes after the lift; it must not toggle. + fireEvent.click(trigger, {detail: 1}); + expect(trigger).toHaveAttribute('aria-expanded', 'true'); + expect(onOpenChange.mock.calls).toEqual([[true]]); + fireEvent.pointerDown(item('Delete'), touch); + fireEvent.pointerUp(item('Delete'), touch); + expect(onPick).toHaveBeenCalledWith('Delete'); + expect(onOpenChange.mock.calls).toEqual([[true], [false]]); + }); + + it('fine primary pointer: a finger opens the menu once, as it presses, and it closes once at a pick, as on a phone (module AR5, spec:AST-094 FR43)', () => { + stubFinePointer(); + const {trigger, onOpenChange, onPick} = renderCountingMenu(); + fireEvent.pointerDown(trigger, {...touch, clientX: 0, clientY: 0}); + expect(trigger).toHaveAttribute('aria-expanded', 'true'); + fireEvent.pointerUp(trigger, {...touch, clientX: 0, clientY: 0}); + // The tap's own click comes after the lift; it must not toggle. + fireEvent.click(trigger, {detail: 1}); + expect(trigger).toHaveAttribute('aria-expanded', 'true'); + expect(onOpenChange.mock.calls).toEqual([[true]]); + fireEvent.pointerDown(item('Delete'), touch); + fireEvent.pointerUp(item('Delete'), touch); + expect(onPick).toHaveBeenCalledWith('Delete'); + expect(onOpenChange.mock.calls).toEqual([[true], [false]]); + }); + + it('coarse primary pointer: a mouse keeps the mouse path: it opens on its press, and a press in the menu released outside closes it', () => { + stubCoarsePointer(); + const trigger = renderMenu(); + fireEvent.pointerDown(trigger, mouse); + expect(trigger).toHaveAttribute('aria-expanded', 'true'); + fireEvent.pointerUp(trigger, mouse); + fireEvent.click(trigger, {detail: 1}); + expect(trigger).toHaveAttribute('aria-expanded', 'true'); + fireEvent.pointerDown(item('Edit'), mouse); + fireEvent.pointerUp(document.body, mouse); + expect(trigger).toHaveAttribute('aria-expanded', 'false'); + }); + }); }); describe('DropdownMenu trigger handler composition', () => { diff --git a/packages/core/src/DropdownMenu/DropdownMenu.tsx b/packages/core/src/DropdownMenu/DropdownMenu.tsx index 78a85aeddaf35..0504ff2776a74 100644 --- a/packages/core/src/DropdownMenu/DropdownMenu.tsx +++ b/packages/core/src/DropdownMenu/DropdownMenu.tsx @@ -79,6 +79,7 @@ import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect'; import {useMergedRefs} from '../hooks/useMergedRefs'; import {useInternalListFocus} from '../hooks/useListFocus'; import {useDropdownMenuPress} from '../hooks/useMenuPress'; +import {isInScrollView} from '../hooks/menuScrollView'; import type {MenuPressPointerType} from '../hooks/menuPressGesture'; import {useTypeahead} from '../hooks/useTypeahead'; import {useFocusReturnVisibility} from '../hooks/useFocusReturnVisibility'; @@ -468,10 +469,11 @@ interface DropdownMenuDataProps extends DropdownMenuBaseProps { * Surface used to present the actions. Pass a value selected by product * policy (for example, a compact-touch media query) when the presentation * should adapt. Bottom-sheet presentation is intended for short action sets. - * Omitted, the menu is the anchored popover. Under a finger, on every - * device, the finger that opened it picks as UIMenu's does, once it has - * moved. `'popover'` pins the anchored popover with the pointer behavior on - * every device (the opening press follows the settle rule). + * Omitted, the menu is the anchored popover. On every device, a finger or + * a pen opens it as it presses the trigger, as UIMenu's pull-down button + * does. The finger that opened it picks once it has moved. `'popover'` + * pins the anchored popover with the pointer behavior on every device. A + * finger held for 500 ms opens it, and the settle rule decides its release. */ presentation?: DropdownMenuPresentation; items: DropdownMenuOption[]; @@ -480,9 +482,11 @@ interface DropdownMenuDataProps extends DropdownMenuBaseProps { interface DropdownMenuCompoundProps extends DropdownMenuBaseProps { /** - * `'popover'` pins the pointer behavior on every device (the opening press - * follows the settle rule). Omitted, on every device, the finger - * that opened the menu picks as UIMenu's does, once it has moved. + * `'popover'` pins the pointer behavior on every device. A finger held for + * 500 ms opens the menu, and the settle rule decides its release. Omitted, + * on every device, a finger or a pen opens the menu as it presses, as + * UIMenu's pull-down button does. The finger that opened it picks once it + * has moved. */ presentation?: 'popover'; items?: undefined; @@ -1478,9 +1482,8 @@ function DropdownMenuPopover({ itemSelector: MENU_ITEM_SELECTOR, onTriggerPress: handleTriggerPress, onDismiss: closeMenu, - // Under a finger, on every device, the opening finger picks as UIMenu's - // does. `presentation="popover"` pins the pointer model. touchModel: pressTouchModel, + isInScrollView, }); cancelMenuPressRef.current = menuPress.cancel; diff --git a/packages/core/src/DropdownMenu/DropdownMenuSubMenu.tsx b/packages/core/src/DropdownMenu/DropdownMenuSubMenu.tsx index 1069c1c748dca..9dc854b75590b 100644 --- a/packages/core/src/DropdownMenu/DropdownMenuSubMenu.tsx +++ b/packages/core/src/DropdownMenu/DropdownMenuSubMenu.tsx @@ -73,7 +73,7 @@ import {useMenuHover} from '../hooks/useMenuHover'; import { isMenuPressActivation, MENU_PRESS_SURFACE_ATTR, - useMenuPress, + useMenuSurfacePress, } from '../hooks/useMenuPress'; import {useTypeahead} from '../hooks/useTypeahead'; import {useMenuOverflow} from './useMenuOverflow'; @@ -1061,7 +1061,7 @@ export function DropdownMenuSubMenu( // The press model for this flyout: the row under a release acts, the // highlight follows a held pointer. A mouse released outside every level // dismisses the whole menu; a finger leaves it open. - const menuPress = useMenuPress({ + const menuPress = useMenuSurfacePress({ menuRef, itemSelector: MENU_ITEM_SELECTOR, onDismiss: nestedMenuContext.closeMenu, diff --git a/packages/core/src/DropdownMenu/MenuBottomSheetActionList.tsx b/packages/core/src/DropdownMenu/MenuBottomSheetActionList.tsx index f903644e7aa72..00e1463af62be 100644 --- a/packages/core/src/DropdownMenu/MenuBottomSheetActionList.tsx +++ b/packages/core/src/DropdownMenu/MenuBottomSheetActionList.tsx @@ -16,7 +16,7 @@ import {Heading} from '../Heading/Heading'; import {Icon, renderIconSlot} from '../Icon/Icon'; import {List} from '../List/List'; import {ListItem} from '../List/ListItem'; -import {useMenuPress} from '../hooks/useMenuPress'; +import {useMenuSurfacePress} from '../hooks/useMenuPress'; import {useMergedRefs} from '../hooks/useMergedRefs'; import {colorVars, spacingVars} from '../theme/tokens.stylex'; import {rtlStyles} from '../utils/rtlStyles'; @@ -74,7 +74,7 @@ export function MenuBottomSheetActionList({ // The press model: the row under a finger's RELEASE acts, and the // highlight (focus) follows the finger across the rows. The sheet is modal, // so a release outside it is the scrim's, not a dismissal of ours. - const menuPress = useMenuPress({ + const menuPress = useMenuSurfacePress({ menuRef: listRef, itemSelector: SHEET_ROW_SELECTOR, }); diff --git a/packages/core/src/DropdownMenu/__tests__/DropdownMenuTouchPress.interaction.browser.spec.ts b/packages/core/src/DropdownMenu/__tests__/DropdownMenuTouchPress.interaction.browser.spec.ts new file mode 100644 index 0000000000000..61150bce57b2b --- /dev/null +++ b/packages/core/src/DropdownMenu/__tests__/DropdownMenuTouchPress.interaction.browser.spec.ts @@ -0,0 +1,396 @@ +// Copyright (c) Meta Platforms, Inc. and affiliates. + +/** + * @file DropdownMenuTouchPress.interaction.browser.spec.ts + * @input The built Default DropdownMenu story, real touch input (Chromium + * CDP / WebKit's input command), the interaction harness, and UIMenu's + * values from the UIKit constants table + * @output Interaction proofs for a finger on DropdownMenu's trigger, one + * touch model on every engine. The menu opens as the finger presses a + * trigger in no scroll view, and the lift picks nothing. A tap opens it as + * it presses, and its lift leaves it open. In scrolling page content, a + * held finger opens it once the 150 ms content-touch delay passes. A scroll + * that starts on the trigger takes the touch. A press that slides onto a + * row, past the 10 pt handoff, picks that row once. A tap and a pick each + * open and close the menu once. A storyboard shows the press, hold, slide + * and lift. + * @position Evidence for the finger's press model in DropdownMenu (and + * MoreMenu, which renders it); the machine itself is unit-tested in + * menuPressGesture.test.ts and useMenuPress.test.tsx + */ + +import { + expect, + test, + type Locator, + type Page, +} from '@astryxdesign/a11y-spec/playwright'; +import { + drag, + frames, + installLongTaskLog, + openStory, + Storyboard, + tap, + touchDriver, + waitForRest, + withStorybook, + type TouchDriver, +} from '@astryxdesign/interaction-harness'; +import {scroll} from '../../motion/uikit/scroll'; + +/** The element's rendered box; a missing one fails the spec. */ +async function boxOf(locator: Locator): Promise<{ + x: number; + y: number; + width: number; + height: number; +}> { + const box = await locator.boundingBox(); + if (box == null) { + throw new Error('the element has no rendered box'); + } + return box; +} + +const storybook = withStorybook(test); + +interface Box { + x: number; + y: number; + width: number; + height: number; +} + +interface OpenStory { + driver: TouchDriver; + trigger: Locator; + popover: Locator; + center: {x: number; y: number}; + triggerBox: Box; +} + +/** Page-side log of the gesture and the menu: performance.now() times. */ +async function installMenuLog(page: Page) { + await page.evaluate(() => { + const log = { + down: [] as number[], + up: [] as number[], + cancel: [] as number[], + opened: [] as number[], + closed: [] as number[], + shown: [] as number[], + picked: [] as string[], + }; + (window as unknown as {__menuLog: typeof log}).__menuLog = log; + document.addEventListener( + 'pointerdown', + () => log.down.push(performance.now()), + true, + ); + document.addEventListener( + 'pointerup', + () => log.up.push(performance.now()), + true, + ); + document.addEventListener( + 'pointercancel', + () => log.cancel.push(performance.now()), + true, + ); + // The moment the menu shows: `beforetoggle` fires inside showPopover, + // while `toggle` follows in a task. + document.addEventListener( + 'beforetoggle', + event => { + if (event.newState === 'open') { + log.shown.push(performance.now()); + } + }, + true, + ); + document.addEventListener( + 'toggle', + event => { + // A popover hidden from assistive technology (a close's exit copy) + // is no menu a screen reader hears (module AR5). + if ( + event.target instanceof Element && + event.target.getAttribute('aria-hidden') === 'true' + ) { + return; + } + const state = event.newState; + (state === 'open' ? log.opened : log.closed).push(performance.now()); + }, + true, + ); + // The story reports a pick by logging "