diff --git a/.changeset/contextmenu-outside-press-watch.md b/.changeset/contextmenu-outside-press-watch.md new file mode 100644 index 0000000000000..8540b95a11b32 --- /dev/null +++ b/.changeset/contextmenu-outside-press-watch.md @@ -0,0 +1,7 @@ +--- +'@astryxdesign/core': patch +--- + +[fix] ContextMenu closes on an outside press through the layer's outside-press watch. A mouse or pen press closes it at its `mousedown`, in the menu's own document, so a menu in an iframe or a Picture-in-Picture window no longer closes on a press in the page. + +@vjeux diff --git a/.changeset/contextmenu-touch-timeline.md b/.changeset/contextmenu-touch-timeline.md new file mode 100644 index 0000000000000..59b0d7495714d --- /dev/null +++ b/.changeset/contextmenu-touch-timeline.md @@ -0,0 +1,7 @@ +--- +'@astryxdesign/core': patch +--- + +[feat] ContextMenu opens from a held finger on iOS 26's measured timeline where the primary pointer is coarse. The hold keeps UIKit's measured moments. At 400 ms the press takes the finger: its lift no longer sends a click, and the page cannot scroll under it. The menu opens at 735 ms if the finger is still down, or as soon as it lifts after 400 ms. A finger that lifts before 400 ms, or drifts more than 11.5 px on either axis before the menu opens, gets no menu. The page stays free to scroll while the menu is up: a touch outside the menu closes it as it begins to pan, or at its lift. A touch open lights no row: the menu itself takes the focus, as in UIKit (keyboard and pointer opens still focus the first item). A second finger cancels the press before 400 ms; after it, the menu still opens. A fine pointer (a mouse) keeps the right-click menu, and a finger there keeps today's 500 ms long press. The touch code loads after the page first paints, so a page's first load does not carry it; a finger held before then starts the hold once it loads. Pass `presentation="popover"` to keep today's menu: the menu at the pointer, opened by a finger held for 500 ms. + +@vjeux diff --git a/.changeset/gesture-arena-late-input.md b/.changeset/gesture-arena-late-input.md new file mode 100644 index 0000000000000..44d2e3bc54473 --- /dev/null +++ b/.changeset/gesture-arena-late-input.md @@ -0,0 +1,7 @@ +--- +'@astryxdesign/core': patch +--- + +[fix] A touch gesture's deadline now runs after the input stamped before it. Behind a blocked page, a finger's or pen's deadline whose timer runs more than 17 ms late waits 50 ms for input still queued. Each input from before it that comes late keeps it waiting. A mouse's or trackpad's deadline does not wait. A deadline that falls among a coalesced move's samples runs between them. A List reorder hold or a Pager's catch whose finger drifted or lifted in time now ends as it should. + +@vjeux diff --git a/apps/storybook/stories/ContextMenu.stories.tsx b/apps/storybook/stories/ContextMenu.stories.tsx index 891b4ca1c4aa1..9e35541c56873 100644 --- a/apps/storybook/stories/ContextMenu.stories.tsx +++ b/apps/storybook/stories/ContextMenu.stories.tsx @@ -647,3 +647,72 @@ export const BottomSheetSubmenu: Story = { } }, }; + +const touchStyles = stylex.create({ + card: { + width: '200px', + height: '120px', + display: 'grid', + placeItems: 'center', + borderRadius: '12px', + backgroundColor: '#e5e7eb', + color: '#374151', + userSelect: 'none', + }, +}); + +export const TouchLongPress: Story = { + name: 'Touch / long press', + parameters: { + docs: { + description: { + story: + 'Where the primary pointer is coarse (a touch screen), hold a finger on the card. As on iOS, a haptic plays at 400 ms where the device can play one, and the menu opens at 735 ms, or as soon as the finger lifts after 400 ms. A finger that lifts before 400 ms, or drifts more than 11.5 px on either axis before the menu opens, gets no menu. While the menu is up, the page still scrolls: a touch outside the menu closes it as it begins to pan.', + }, + }, + }, + render: () => ( + {}}, + {label: 'Share', icon: ShareIcon, onClick: () => {}}, + {label: 'Save to Files', icon: ArrowDownTrayIcon, onClick: () => {}}, + {type: 'divider'}, + { + label: 'Delete', + icon: TrashIcon, + variant: 'destructive', + onClick: () => {}, + }, + ]}> +
Hold for actions
+
+ ), +}; + +export const TouchLongPressPopover: Story = { + name: 'Touch / long press, presentation="popover"', + parameters: { + docs: { + description: { + story: + 'With `presentation="popover"`, ContextMenu keeps today’s menu on every device: a finger held for 500 ms opens it at the finger, with no iOS timeline. A finger on a device whose primary pointer is fine (a mouse or a trackpad) gets the same long press.', + }, + }, + }, + render: () => ( + {}}, + {label: 'Share', icon: ShareIcon, onClick: () => {}}, + {label: 'Save to Files', icon: ArrowDownTrayIcon, onClick: () => {}}, + ]}> +
Hold for actions
+
+ ), +}; diff --git a/docs/architecture/layer-runtime.md b/docs/architecture/layer-runtime.md index ea81772eec66c..d55a1ac663323 100644 --- a/docs/architecture/layer-runtime.md +++ b/docs/architecture/layer-runtime.md @@ -381,14 +381,13 @@ Outside interaction is not coordinated by the shared stack. Current paths close their own layers independently: - auto popovers use native light dismiss; -- BaseTypeahead's list, DateInput's calendar, DateTimeInput's time list and - ChatComposerInput's trigger menu, manual popovers, use Layer's outside-press - watch, +- BaseTypeahead's list, DateInput's calendar, DateTimeInput's time list, + ChatComposerInput's trigger menu and ContextMenu's menu, manual popovers, + use Layer's outside-press watch, which closes on a press that starts and ends outside the field and the list - and forgets a cancelled press (a scroll); + and forgets a cancelled press (a scroll); ContextMenu's menu judges the + press types it names at their `mousedown` (`pressTypes`); - native dialogs handle backdrop clicks locally; -- ContextMenu uses a local outside `mousedown` listener, which skips the - compatibility mouse events of the finger press that opened the menu; - Tooltip and HoverCard use hover/focus loss plus a touch-only outside listener; - sheets own scrim and swipe behavior; and - dropdown submenus encode their root-close relationship locally through @@ -396,7 +395,7 @@ close their own layers independently: One fact joins these paths, for a modal host's backdrop press (`family:overlay-dismissal` FR11). The outside-press watch, the touch-only -outside listener, the text fields' blur closes, ContextMenu's `mousedown` close, +outside listener, the text fields' blur closes, and a held Tooltip's focus-out release each record their close in a per-document count. A Dialog or Drawer backdrop press that sees the count change, or an auto popover close, between its pointer-down and its click leaves @@ -835,6 +834,14 @@ it on the surface inside the layer and run no layout while it plays. - `Layer/useLayer.tsx` owns Popover API lifecycle, state reconciliation, anchor/fixed/custom rendering, trigger source, and current same-gesture memory. + It also owns two internal members of a context-mode layer, which + `useLayerInternal` returns and `useLayer`'s return type does not name. + With `lazyMount`, `prepare()` mounts the layer's content without showing it. + The popover stays closed, with no pixel and no accessibility node, and a + later `show()` only shows it. `releasePrepared()` unmounts that content + unless the layer has shown since. ContextMenu prepares its menu at a held + press's commit, so its first render does not fall inside the show at the + hold's display moment. - `Layer/layerHost.ts` owns safe inline versus nearest corrective portal placement. - `Layer/anchorName.ts` owns composition of anchor names on one trigger. - `Layer/layerTextReset.stylex.ts` owns the text baseline and @@ -893,8 +900,11 @@ it on the surface inside the layer and run no layout while it plays. touch-only outside listener for Tooltip/HoverCard. - `Layer/outsidePress.ts` owns the outside-press watch for a text field's manual layer, used by BaseTypeahead, DateInput, DateTimeInput and - ChatComposerInput's trigger menu, and the per-document count of outside - closes that a modal backdrop press reads (`family:overlay-dismissal` FR11). + ChatComposerInput's trigger menu, and for ContextMenu's menu, which judges + a mouse's or a pen's press as it goes down, and a touch's too under a fine + pointer or with `presentation="popover"` (`pressTypes`). It also owns the + per-document count of outside closes that a modal backdrop press reads + (`family:overlay-dismissal` FR11). - `DropdownMenuContext` and `DropdownMenuSubMenu` own the current local menu-cascade parent-close chain. - Dialog families own native modal/backdrop presentation and their local channel diff --git a/docs/specs/AST-094-touch-presentations/spec.md b/docs/specs/AST-094-touch-presentations/spec.md index a64ae86f50a86..2ed17b243b6f7 100644 --- a/docs/specs/AST-094-touch-presentations/spec.md +++ b/docs/specs/AST-094-touch-presentations/spec.md @@ -514,7 +514,16 @@ a measured, sourced difference exists. - **FR16 — Gestures keep the event clock.** Recognizers MUST read time from the input events' timestamps. Durations (a long press, the interval between taps) MUST be deadlines on that clock, so a blocked main thread delays the - report and never the moment reported. + report and never the moment reported. While the latest contact is a finger + or a pen, a deadline behind a blocked page waits for input still queued + before it. It waits 50 ms when its timer runs more than 17 ms late. While the + latest contact is a finger or a pen, every recognizer's late deadline waits + those 50 ms, even with nothing queued. Each finger's or pen's + input from before it that reaches the page more than 33 ms late keeps it + waiting 50 ms more. An input stamped at or past the deadline ends the wait. + A deadline that comes due during the wait runs as it ends. A deadline among + a coalesced move's samples runs between them: the samples stamped before it + come first. - **FR17 — Native readings.** A recognizer's thresholds MUST follow UIKit's measured values (FR1, FR2). A pan begins at 10 pt of travel on either axis (a screen-edge pan attached to an element within the band at 15 px, FR18), @@ -831,7 +840,10 @@ under a finger, and a mouse follows `module:DropdownMenu/useMenuPress` FR3 and component or module record sets on purpose, such as `component:Thumbnail` AR4's, is unaffected. Mobile size increases belong to theme adaptations (DEC-20). - **FR43 — Gestures work on the web.** Gestures attach for every pointer, a - mouse, a pen, and a finger, not only a coarse primary pointer. A part that + mouse, a pen, and a finger, not only a coarse primary pointer. A recognizer + that attaches while a finger is down on its element may begin that finger + from the finger's own touchstart, at attach time; the host still begins + fingers only from Touch Events. A part that follows a pointer's drag, such as a switch's or a slider's thumb, a sheet, a pager, a picker wheel or a row, follows a mouse, a pen, a trackpad and a finger alike, with the same rubber band past its ends, wherever its record @@ -895,7 +907,8 @@ under a finger, and a mouse follows `module:DropdownMenu/useMenuPress` FR3 and browser's own menu closed. A hold loses to a claim another recognizer made first. The headless context menu (`spec:AST-107` FR8) makes its request through it, and ContextMenu through that menu (`component:ContextMenu` - FR10). One module keeps these rules the same in every menu. The + FR10). FR10's implementation gap records that ContextMenu times its touch + model's hold itself. One module keeps these rules the same in every menu. The press model has a fine-pointer profile with no delay (FR11); and with a mouse, a trackpad, or a pen where the primary pointer is fine a reorder starts on a drag from its handle without a hold, while a pen where the @@ -1078,6 +1091,14 @@ under a finger, and a mouse follows `module:DropdownMenu/useMenuPress` FR3 and - FR6 gap: a resize during a settle drops its velocity when it leaves the row past its new last page, or when the settle began before the viewport had a width. The row lands on its target at once. +- FR16 gap: on a blocked main thread, a recognizer keeps its outcome, but it + reports it later. While the latest contact is a finger or a pen, a deadline + that runs late waits 50 ms or more for input still queued. So ContextMenu's + menu can show that much later. +- One wait: the arena holds a late deadline for input still queued, for every + recognizer (FR16). Each touch carries the samples of the input that moved it + at the times they came with (`inputSamples`). The host begins a late finger + at the time the page runs (`pageTime()`). - Consumer docs: none until a component ships its touch presentation; each component documents its own, including the `presentation` value that keeps the released surface (FR25). @@ -1133,7 +1154,7 @@ Motion that FR45 moves, by component. Each component's record carries its own li | FR11 theme | `generateThemeRules.test.ts` themed-`:active` cases; real-browser forced `:active` on the Themed press story | a theme `:active` on a base and on a variant with a trailing pseudo; fine pointer; coarse pointer with forced `:active` and with the press attribute | a bare theme `:active` rule a coarse pointer matches, or a coarse arm keyed on `:active`, fails | | FR13 | Resolver unit tests and a server-render test | coarse and fine pointer; narrow, wide and short; server render; hydrating render | a component that answers the conditions differently, or a touch presentation in the server or hydrating render, fails | | FR14 | Browser tests of a sheet over a scrolled list | scrolled and at its top | a midway handoff fails | -| FR15–FR17 | Recognizer unit tests on synthetic streams with explicit timestamps | exclusive, simultaneous, require-to-fail, nested; a watcher beside a claiming winner; a blocked main thread; a pan at 10 pt per axis | a wrong winner, a late deadline, or a translation that keeps the hysteresis, or a watcher failed or cancelled by a claiming winner fails | +| FR15–FR17 | Recognizer unit tests on synthetic streams with explicit timestamps | exclusive, simultaneous, require-to-fail, nested; a watcher beside a claiming winner; a blocked main thread; a deadline run late behind a block, with a drift that reaches the page after the next task; an on-time deadline while input from before it still comes late; a coalesced move whose samples straddle a deadline; a wait whose own timer runs late; a mouse's late deadline and a pen's; a pan at 10 pt per axis | a wrong winner, a late deadline, a deadline that runs before input queued before it, or a translation that keeps the hysteresis, or a watcher failed or cancelled by a claiming winner fails | | FR18–FR22 | Browser tests with real touch input (`spec:AST-013` FR10) | per-axis pans beside native scrolling, page zoom, cancelled touches, clicks after taps, keyboard activation, a modal scroll lock, a control that keeps its press through a drag; a still finger with sub-pixel jitter over a scroll view; a finger moved 9 px and 10 px straight, and (7, 7) and (8, 8) diagonally; a recognizer on an element whose author `touch-action` is narrower, including one without `pinch-zoom`; a screen-edge pan landing at 40 px and at 41 px from the edge, at 14 px and 15 px of travel, and a horizontal scroll that starts outside the band; a screen-edge pan on an element within the band, and on one that reaches beyond it; a sheet's pull from a list at its top, and from a list scrolled away from its top; a long press dragged past its tolerance after it began, which never scrolls the page | a ghost click, a scroll or zoom blocked other than by the author's `touch-action`, or a cancelled unowned touchmove outside FR19's five exceptions, a tap cancelled by sub-pixel movement or by under 10 px of travel, a scroll that does not take the touch at 10 px, or a derived `touch-action` wider than the author's, a screen-edge pan that claims outside its band or before 15 px on an element within the band, or has not claimed at 15 px, or an author scroll outside the band that is blocked, a band claim of `pan-x` on an element that reaches beyond the band, or a 15 px start there, or a scroll-edge pan that cancels a move a scroller could scroll, or begins before 10 pt, fails | | FR19 (DEC-30) | Gesture unit tests on synthetic streams; browser tests with real touch input in WebKit and Chromium | a tap that wobbles 2–4 px toward a scroll edge keeps every move, and a 5 px move is cancelled; a sideways move is never held; NavigationStack's content back swipe on a pushed screen; RefreshControl's pull at its top, whose touch path is not a scroll-edge pan (a guard) | a move under 5 px along the pan's axis cancelled, a move from 5 px left uncancelled while every scroller under the finger sits at its edge, a sideways move held, or a pan that begins before its hysteresis fails | | FR20 | Browser tests with real touch input in Chromium phone emulation (`spec:AST-013` FR10) | a horizontal drag under `pan-y`; a vertical drag under `pan-y` over a scroller with room; a vertical drag where no scroller has room | a horizontal drag under `pan-y` counted as the browser taking the touch, a vertical one over a scroller with room not counted, or a later uncancelable move counted, fails | @@ -1150,6 +1171,7 @@ Motion that FR45 moves, by component. Each component's record carries its own li | FR42 | Default-theme geometry tests under a coarse and a fine pointer, and hit-testing between adjacent targets | every component at phone width with a finger and with a mouse; a dense toolbar; a chip and its remove button; a Switch beside a label link | a default-theme box that grows under touch or at phone width other than with its text, or, where no component or module record sets the hit area, a touch target under 44 px where neighbors allow it or a hit area that overlaps a neighbor's target, fails | | FR43 | Browser tests with a mouse, a trackpad, a pen, a finger, and the keyboard, and resource counts | a pan by drag and by wheel; a slider's thumb under a wheel and a trackpad scroll; a ctrl-wheel pinch; a long press, a right click, and Shift+F10; a mouse press; a handle drag; a row swipe with a mouse and a trackpad; a component with no gesture | a gesture missing under a mouse or pen, a mouse-drag swipe action, a pen pinch, an edge pan under a mouse, a trackpad, or a pen, a press delay under a fine pointer, a wheel or trackpad scroll that changes a thumb's value or does not reach the scroll under it, an idle listener in a component with no gesture, or added stylesheet bytes, fails | | FR43 trackpad | Unit tests on timed wheel streams; WebKit browser tests with trackpad streams (Chromium's driver wheels read as a mouse wheel) | a form and a required sheet pulled 30 to 240 px by a finger and by a trackpad; mouse lines, notches, ticks and accelerated deltas over a sheet, a pager and a row; ten swipes each starting mid-momentum, ten whose momentum ends, and a slow drag with 150 ms pauses; a trackpad flick and a slow stopped drag on an info sheet; a fling, a slow 60 px swipe, a 42 px spike and back-to-back swipes on a pager; a row opened and swiped back within one gesture, and a long fast swipe; a pinch ending; a trackpad pan through a window blur and through a hidden page | a trackpad stretch that differs from a finger's for the same travel (120 px gives 54 px on the reference sheet), a mouse wheel that moves a sheet, a pager or a row, splitter counts other than ten, ten and one, momentum that moves a surface, a flick released with no velocity, a pager that travels past one page or pages on a spike, an info sheet a flick leaves open or a slow stopped drag closes, an open row that reveals its other side within one gesture, a trackpad pan a window blur or a hidden page leaves mid-gesture, or a pinch that ends after 100 ms fails | +| FR43 late begin | Gesture host unit tests on a finger that lands before its recognizer attaches | a finger begun at the attach from its own touchstart; its later drift past the press's limit; a touchstart the host already heard; one it heard but left untracked; the finger's own pointer handed over | a late finger whose hold counts from its touchstart rather than the attach, a late finger whose later moves or lift miss its recognizer, a touchstart begun twice, a heard but untracked finger left unbegun, or a late finger with no pointer fails | | FR44 | Unit tests of a pen press a window blur ends, on a Switch, a Slider and the host, under a coarse and a fine pointer | a pen press on a Switch and on a Slider, blur mid-press: nothing toggles or commits; a pen whose contact ends in `pointercancel` | with the host keeping no note of a blur-cancelled pen, the Switch toggles at the pen's click | | all | iOS simulator: the UIKit reference capture and the same gesture in Safari; real iOS Safari devices; Android Chrome in the Android emulator (DEC-27) | per component | an unmatched curve or timing is a parity defect | | all (DEC-31) | The evidence-carry check, before device or emulator evidence from an earlier head counts at a later head | a later head that only merges `main`; the pull request's own changes byte-identical or changed; a merge that changes a file the pull request changes, a direct import of those changes, a shared motion or layer module, or none of them; a generated file among the pull request's own files that CI proves regenerates identically, or does not prove; a commit, or an overlap with the pull request's own files, confined to test-only files as DEC-31 defines them, or knowledge records, or not | the evidence-carry check compares the PR's own diff between the two heads, and the merge's changed files against the files the PR changes, the changes' direct imports and the shared motion and layer modules (currently `motion/transientCopy`, `motion/inertClone`, `motion/animator`, `motion/carryAnimations`, `Layer/useLayer`, `hooks/usePager`); any overlap fails, except a generated file among the pull request's own files that CI proves regenerates identically at the new head; a changed own diff, or an overlap with the pull request's own files, confined to test-only files as DEC-31 defines them, knowledge records or `.changeset/` release notes, passes | diff --git a/docs/specs/components/ContextMenu/ContextMenu.spec.md b/docs/specs/components/ContextMenu/ContextMenu.spec.md index af08cfd78df09..f481957f3bb96 100644 --- a/docs/specs/components/ContextMenu/ContextMenu.spec.md +++ b/docs/specs/components/ContextMenu/ContextMenu.spec.md @@ -15,6 +15,7 @@ verified_by: packages/core/src/ContextMenu/ContextMenu.test.tsx, packages/core/src/ContextMenu/ContextMenu.triggerProps.test.tsx, packages/core/src/ContextMenu/ContextMenu.sheetLoading.test.tsx, + packages/core/src/ContextMenu/ContextMenu.touchLoadFailure.test.tsx, packages/core/src/theme/themingTargets.test.ts, scripts/check-knowledge.mjs, apps/storybook/rtl-audit/targets.json, @@ -35,17 +36,25 @@ system_specs: [spec:AST-094, spec:AST-107] # ContextMenu component contract + + +```json +{ + "paths": ["packages/core/src/motion/uikit/contextMenu.ts"] +} +``` + ## Contract at a glance -| Area | Contract | -| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Public contract | None changes. ContextMenu takes caller `children` as the Trigger area, data-driven `items` or compound `menuContent`, `label`, `presentation`, `isDisabled`, and `triggerAs`. | -| Behavior | Right-click, Shift+F10 or the Menu key, and a touch long press open a menu at the cursor (or the trigger's bottom-left from the keyboard), or a bottom sheet; rows follow DropdownMenu's rows and press model. | -| End-user impact | People reach a region's actions by mouse, keyboard, or a held finger; a sub-menu drills in on a phone. A touch-opened menu does not yet grow from the finger or lift its trigger, and a scroll that starts outside leaves it open; mouse and keyboard opens keep today's look. | -| Builder impact | Builders wrap any region, including an inline reference in prose (`triggerAs="span"`). | -| 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. The touch grow, pan dismissal, and trigger lift (FR5) are listed under Current-state impact. | -| Review checks | Reject a trigger that gains a role or `aria-haspopup`, a menu that bypasses the shared Escape stack, a `context-menu` target moved off the painted surface, or a second open-state owner. | -| Governing rules | `spec:AST-107` FR8; `spec:AST-094` FR26–FR35; `module:DropdownMenu/useMenuPress`; `family:overlay-dismissal`; `architecture:component-theming-surface`; `architecture:layer-runtime`. | +| Area | Contract | +| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Public contract | One default moves: under a coarse primary pointer, an omitted `presentation` means the touch model (`spec:AST-094` FR25), and `presentation="popover"` keeps the released surface. ContextMenu takes caller `children` as the Trigger area, data-driven `items` or compound `menuContent`, `label`, `presentation`, `isDisabled`, and `triggerAs`. | +| Behavior | Right-click, Shift+F10 or the Menu key, and a touch long press open a menu at the cursor (or the trigger's bottom-left from the keyboard), or a bottom sheet; rows follow DropdownMenu's rows and press model. | +| End-user impact | People reach a region's actions by mouse, keyboard, or a held finger; a sub-menu drills in on a phone. A touch-opened menu keeps the layer's own entrance and lifts no trigger (FR5's recorded gap); mouse and keyboard opens keep today's look. | +| Builder impact | Builders wrap any region, including an inline reference in prose (`triggerAs="span"`). | +| 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. The touch grow and trigger lift (FR5) are listed under Current-state impact. | +| Review checks | Reject a trigger that gains a role or `aria-haspopup`, a menu that bypasses the shared Escape stack, a `context-menu` target moved off the painted surface, or a second open-state owner. | +| Governing rules | `spec:AST-107` FR8; `spec:AST-094` FR26–FR35; `module:DropdownMenu/useMenuPress`; `family:overlay-dismissal`; `architecture:component-theming-surface`; `architecture:layer-runtime`. | This table is a review projection; the body below is authoritative. @@ -74,6 +83,10 @@ Consumer migration instructions belong in consumer docs and release notes. **Owns** - The Trigger area's context-menu invocation wiring (FR10). +- The touch hold under a coarse pointer (FR12). `ContextMenuPressRecognizer`, + in `contextMenuPress.ts`, times the commit, the display and the drift. + `ContextMenuTouchLayer.tsx` attaches it to the Trigger area and opens the + menu. - The alternative Pointer menu surface and Touch menu surface and their shared `context-menu` target. - Cursor-anchor placement across the two presentation paths, and open state @@ -101,19 +114,20 @@ Consumer props, content modes, and presentation policy remain documented in ## Behavioral and layout contract -| ID | Invariant | Basis | -| ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | -| FR1 | Every render contains a caller-provided Trigger area; with `isDisabled` no invocation opens a menu and the native context menu is left alone. Pointer presentation opens a Pointer menu surface at the current local cursor anchor; touch presentation opens a Touch sheet frame containing a Touch menu surface and, for data mode, a Touch action list and Touch action rows. | Current source, docs, and tests | -| FR2 | The `context-menu` target stays on the painted Pointer menu surface and alternative Touch menu surface, not on the Trigger area or cursor anchor. | `architecture:component-theming-surface`; current source | -| FR3 | Pointer action rows retain DropdownMenu ownership. The touch frame retains BottomSheet ownership, while data-driven touch lists and rows retain List ownership. | Current source and owner docs | -| FR4 | Compound `menuContent` remains a caller-supplied pointer-menu interior and may also render inside the touch frame; the data-driven touch path instead converts the same item data to List and ListItem presentation. | Current source and tests | -| FR5 | The Pointer menu surface carries `data-astryx-menu-press` and follows `module:DropdownMenu/useMenuPress` FR1–FR7: 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 stray click never acts, and `touch-action` follows overflow. The long press that opened the menu does not close it as it lifts; a tap outside closes it, and a mouse press outside closes it at the press. Under a finger the menu MUST close as a pan that starts outside it begins (`spec:AST-094` FR32), MUST hand the held finger that opened it to the menu as the opening press, and MUST treat a pen's press outside as FR32 does (FR33). The lift and the grow apply only to a menu opened by touch (a touch-initiated open on a coarse pointer); a menu opened by mouse or keyboard keeps its released appearance and motion, with no lift, no tint and no grow. A touch-opened menu MUST grow out of the finger's point and shrink back into it (`spec:AST-094` FR31) as its own surface, by transform and opacity only (`spec:AST-094` FR5), with no second element such as a glass surface growing behind it, and on a block trigger MUST lift the trigger above the page with the menu beside it (FR33; DD1, DEC-2). The long-press presentation is a gesture component, so the trigger's lift plays `springs.contextMenuLift`, the menu's grow `springs.contextMenuMorph`, and the trigger's return, part of the menu's exit, `springs.contextMenuDismiss` (`spec:AST-094` FR4, FR7, FR45). Implementation gap: it keeps the layer's own entrance and exit, a scroll that starts outside leaves it open, the opening finger is not handed to the menu so it cannot slide to a row, no trigger lift or page tint exists, and a pen press outside closes it at the press. Right-click, Shift+F10, long-press invocation, and keyboard navigation are as FR1 and FR8 state. | `module:DropdownMenu/useMenuPress`; `spec:AST-094` FR26–FR33 | -| FR6 | With `triggerAs="span"` the Trigger area is an inline element that owns a box, so the cursor anchor measures from the trigger's own rect on every invocation path. Right-click, Shift+F10, long-press, and `context-menu` target placement all use that box. | DEC-1 | -| FR7 | Sub-menu rows follow `component:DropdownMenu` FR11 inside the pointer menu: ContextMenu mounts the same drill-in view stack, named after its `label`, so a sub-menu drills in on a phone here too. A sub-menu with a header or footer shows its rows alone here (`component:DropdownMenu` FR20). | `component:DropdownMenu/DEC-4` | -| FR8 | In the pointer menu ArrowDown on the last row wraps to the first and ArrowUp on the first to the last; PageDown and PageUp page as in `component:DropdownMenu` FR12; a held key's auto-repeat does not activate; typeahead matches the row's label element alone. A disabled row is reached by these keys and by typeahead and stays inert, as `component:DropdownMenu` FR17 states. | Current source and tests | -| FR9 | While the Pointer menu surface is open, it participates in `family:overlay-dismissal` through the shared stack and provides descendant depth. One Escape press affects only the top-most present nested surface; ContextMenu closes only when it is that surface. | `family:overlay-dismissal` FR1–FR6; `ContextMenu.test.tsx` nested-layer case | -| FR10 | ContextMenu MUST be built on the public headless context menu (`spec:AST-107` FR8), with its invocation, open state, and cleanup the factory's and no behavior of its own beside the factory's. Implementation gap: no headless context menu ships; ContextMenu owns its invocation, open state, outside-press listener, and cleanup itself. | `spec:AST-107` FR8 | -| FR11 | Tab or Shift+Tab on a row of the pointer menu, its own or an open sub-menu flyout's at any depth, closes every open level and the menu and calls `onOpenChange(false)` once, as `component:DropdownMenu` FR23 states for its menu. | WAI-ARIA Menu Button pattern; current tests | +| ID | Invariant | Basis | +| ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| FR1 | Every render contains a caller-provided Trigger area; with `isDisabled` no invocation opens a menu and the native context menu is left alone. Pointer presentation opens a Pointer menu surface at the current local cursor anchor; touch presentation opens a Touch sheet frame containing a Touch menu surface and, for data mode, a Touch action list and Touch action rows. | Current source, docs, and tests | +| FR2 | The `context-menu` target stays on the painted Pointer menu surface and alternative Touch menu surface, not on the Trigger area or cursor anchor. | `architecture:component-theming-surface`; current source | +| FR3 | Pointer action rows retain DropdownMenu ownership. The touch frame retains BottomSheet ownership, while data-driven touch lists and rows retain List ownership. | Current source and owner docs | +| FR4 | Compound `menuContent` remains a caller-supplied pointer-menu interior and may also render inside the touch frame; the data-driven touch path instead converts the same item data to List and ListItem presentation. | Current source and tests | +| FR5 | The Pointer menu surface carries `data-astryx-menu-press` and follows `module:DropdownMenu/useMenuPress` FR1–FR7: 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 stray click never acts, and `touch-action` follows overflow. The long press that opened the menu does not close it as it lifts; a tap outside closes it, and a mouse press outside closes it at the press. Under a finger the menu MUST close as a pan that starts outside it begins (`spec:AST-094` FR32), MUST hand the held finger that opened it to the menu as the opening press, and MUST treat a pen's press outside as FR32 does (FR33). The lift and the grow apply only to a menu opened by touch (a touch-initiated open on a coarse pointer); a menu opened by mouse or keyboard keeps its released appearance and motion, with no lift, no tint and no grow. A touch-opened menu MUST grow out of the finger's point and shrink back into it (`spec:AST-094` FR31) as its own surface, by transform and opacity only (`spec:AST-094` FR5), with no second element such as a glass surface growing behind it, and on a block trigger MUST lift the trigger above the page with the menu beside it (FR33; DD1, DEC-2). The long-press presentation is a gesture component, so the trigger's lift plays `springs.contextMenuLift`, the menu's grow `springs.contextMenuMorph`, and the trigger's return, part of the menu's exit, `springs.contextMenuDismiss` (`spec:AST-094` FR4, FR7, FR45). Implementation gap: it keeps the layer's own entrance and exit, the opening finger is not handed to the menu so it cannot slide to a row, no trigger lift or page tint exists, and a pen press outside closes it at the press. Right-click, Shift+F10, long-press invocation, and keyboard navigation are as FR1 and FR8 state. | `module:DropdownMenu/useMenuPress`; `spec:AST-094` FR26–FR33 | +| FR6 | With `triggerAs="span"` the Trigger area is an inline element that owns a box, so the cursor anchor measures from the trigger's own rect on every invocation path. Right-click, Shift+F10, long-press, and `context-menu` target placement all use that box. | DEC-1 | +| FR7 | Sub-menu rows follow `component:DropdownMenu` FR11 inside the pointer menu: ContextMenu mounts the same drill-in view stack, named after its `label`, so a sub-menu drills in on a phone here too. A sub-menu with a header or footer shows its rows alone here (`component:DropdownMenu` FR20). | `component:DropdownMenu/DEC-4` | +| FR8 | In the pointer menu ArrowDown on the last row wraps to the first and ArrowUp on the first to the last; PageDown and PageUp page as in `component:DropdownMenu` FR12; a held key's auto-repeat does not activate; typeahead matches the row's label element alone. A disabled row is reached by these keys and by typeahead and stays inert, as `component:DropdownMenu` FR17 states. | Current source and tests | +| FR9 | While the Pointer menu surface is open, it participates in `family:overlay-dismissal` through the shared stack and provides descendant depth. One Escape press affects only the top-most present nested surface; ContextMenu closes only when it is that surface. | `family:overlay-dismissal` FR1–FR6; `ContextMenu.test.tsx` nested-layer case | +| FR10 | ContextMenu MUST be built on the public headless context menu (`spec:AST-107` FR8), with its invocation, open state, and cleanup the factory's and no behavior of its own beside the factory's. Implementation gap: no headless context menu ships. ContextMenu owns its invocation: its touch model's hold (the 400 ms commit, the 735 ms display and the drift rule, which `gestures/contextRequest.ts`'s plain long press does not time), its right click and its menu keys. It owns its open state and cleanup, and closes on an outside press through Layer's outside-press watch. | `spec:AST-107` FR8 | +| FR11 | Tab or Shift+Tab on a row of the pointer menu, its own or an open sub-menu flyout's at any depth, closes every open level and the menu and calls `onOpenChange(false)` once, as `component:DropdownMenu` FR23 states for its menu. | WAI-ARIA Menu Button pattern; current tests | +| FR12 | Under a finger, the hold commits at 400 ms and the menu displays at 735 ms, as UIKit's do. They are measured input, not motion, and stay internal (`spec:AST-094` FR4, FR45). A finger that lands before the touch layer has loaded starts the hold once it loads; a mouse or keyboard opens as today. The touch layer loads once per page, after the page's first paint, when the main thread is idle and at most 2 s after that paint. No input starts or hurries the load. If it fails to load, a finger gets today's 500 ms long press, and the next touch loads it again. | Measured: UIContextMenuInteraction on the iOS 26.2 simulator commits at 400 ms and displays its menu at 735 ms (`motion/uikit/contextMenu.ts`); `spec:AST-094` FR4, FR45 | ### Allowed variation @@ -144,15 +158,18 @@ Consumer props, content modes, and presentation policy remain documented in ### Performance and resources -- **PR1 — Bounded resources.** While open, ContextMenu adds a document (and - shadow-root) mousedown listener for outside dismissal and removes it on - close, and the - pointer menu observes its size and content to decide whether it scrolls. With - `presentation="adaptive"` it subscribes to the compact-touch query while - mounted. A menu never opened mounts no pointer menu surface, only its layer's +- **PR1 — Bounded resources.** While open, ContextMenu's outside-press watch + adds pointer listeners to the trigger's document (and shadow roots), plus a + mousedown listener where a mouse or a pen closes it at the press, and + removes them on close. The pointer menu observes its size and content to + decide whether it scrolls. Unless `presentation="popover"`, it subscribes to + the coarse-pointer query while mounted, and with `presentation="adaptive"` + also to the compact query. A menu never opened mounts no pointer menu surface, only its layer's inert marker: the surface mounts at the first open and stays mounted after it, so a page with many context menus (a table with one per cell) carries no - closed menu surfaces. The touch sheet's code (its frame and its data-driven + closed menu surfaces. A finger's hold mounts the surface, closed, at its + commit, so the menu at 735 ms only shows it; a hold that ends with no menu + unmounts it again. The touch sheet's code (its frame and its data-driven action list) loads after mount, and only while the menu resolves to the sheet presentation, so a pointer menu carries none of it. @@ -247,37 +264,42 @@ anchor is positioning infrastructure rather than consumer anatomy. ## Verification map -| Contract | Verification | Representative states | Mutation or failure expectation | Audit section | -| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | -| FR1, FR4 | `ContextMenu.test.tsx` rendering, invocation, bottom-sheet, adaptive, compound, and disabled cases ("renders menu with role=\"menu\"", "opens menu on right-click", "opens from a keyboard-invoked contextmenu (Shift+F10 / Menu key)", "opens on touch long-press", "opens the real menu content in a BottomSheet when requested", "uses the BottomSheet for adaptive presentation on compact touch", "renders menuContent as menu items", "does not open when isDisabled is true") | Right-click, keyboard, long press; pointer and sheet; data and compound; disabled | A missing invocation path, menu role, sheet, or compound interior, or a disabled trigger that opens, fails. Evidence gap: no test asserts that a disabled trigger leaves the native context menu alone. | `audit:ContextMenu/anatomy` | -| FR2 | `themingTargets.test.ts` | Rendered targets | A rendered class absent from the documented targets fails. Evidence gap: no test asserts `context-menu` on either painted surface or its absence from the trigger. | `audit:ContextMenu/theming` | -| FR3 | `ContextMenu.test.tsx` destructive-variant, section, divider, selectable, and alias cases | Shared rows through ContextMenu | A row that loses DropdownMenu's semantics or variant fails. Evidence gap: no test asserts the BottomSheet and List delegation beyond rendering. | `audit:ContextMenu/theming` | -| FR5 | `ContextMenu.test.tsx` "acts on the row under a finger release, once, and swallows the stray click" and outside-dismissal cases; `ContextMenuLongPress.a11y.chromium.spec.ts` | Finger release; long press lift; tap, mouse, pen, and scroll outside | A row acting on the press row, a stray click that acts, a long press that closes its own menu, or a tap or mouse press outside that leaves it open fails. Evidence gap: no test asserts the FR31 grow, the opening-finger handoff, or the FR33 lift; the scroll-outside and pen cases assert the current gaps. | `audit:ContextMenu/behavior` | -| FR5, DD1 touch scope | Browser tests on the touch story, the menu opened by a finger under a coarse pointer and by a mouse and by Shift+F10 under a fine pointer | Touch-opened, mouse-opened and keyboard-opened menus on a block trigger | A mouse- or keyboard-opened menu that lifts its trigger, tints the page or grows, or a touch-opened menu that blurs the page, grows a second surface, or animates anything but transform and opacity, fails. Evidence gap: the lift and the grow are unbuilt, so no test asserts either. | `audit:ContextMenu/behavior` | -| FR5 Reduce Motion | Browser tests on the touch story with reduced motion | A touch-opened menu opening and closing under Reduce Motion | A lift, grow or shrink that moves rather than playing an opacity-only cross-fade of 200 ms or less (`spec:AST-094` FR8) fails. Evidence gap: no test exists. | `audit:ContextMenu/behavior` | -| FR5 motion roles | Role registry tests over `spec:AST-094` FR4 | `springs.contextMenuLift`, `springs.contextMenuDismiss` and `springs.contextMenuMorph` at tempo 1 and `'standard'` | A lift, return or grow that plays a curve or a literal instead of its spring role, or a role off its FR4 table value, fails. | `audit:ContextMenu/behavior` | -| DEC-2 | Element-count browser test on the touch story (`spec:AST-017` FR60) | At rest and lifted, fine and coarse pointer | A lift element at rest, a copy of the trigger, or an open count beyond the layer, the shadow, the anchor and the placeholder fails. Evidence gap: the lift is unbuilt, so no test exists. | `audit:ContextMenu/anatomy` | -| FR6, AR1, ORD1 | `ContextMenu.test.tsx` "inline trigger (triggerAs)" and cursor-anchor cases; "does not put aria-haspopup on the role-less trigger wrapper (menus-15)"; `ContextMenu.triggerProps.test.tsx`; `ContextMenuCursorAnchor.a11y.browser.spec.ts` | `span` in a paragraph; default `div`; pointer and keyboard anchors | A block trigger in prose, a trigger with a role or `aria-haspopup`, or an anchor outside the trigger fails. | `audit:ContextMenu/behavior` | -| FR7 | `ContextMenu.test.tsx` "drills into nested data items inside the BottomSheet", "renders a submenu from a nested items array and keyboard-reaches an item after it", and "shows a sub-menu with a header or footer as its rows alone, and says why in development" | Sheet drill-in; pointer sub-menu; regions under ContextMenu | A missing sub-menu, an unreachable row after it, or a sub-menu dialog under ContextMenu fails. Evidence gap: no test here asserts the pointer drill-in on a phone. | `audit:ContextMenu/behavior` | -| FR8 | `ContextMenu.test.tsx` "wraps arrow navigation at the ends", typeahead cases, and disabled-row keyboard cases (`component:DropdownMenu` FR17) | Wrap; typeahead; disabled rows | A clamped arrow, a missing typeahead match, a disabled row the keys or typeahead skip, or a disabled row that acts or closes the menu fails. Evidence gap: no test asserts Page keys or auto-repeat. | `audit:ContextMenu/behavior` | -| FR9 | `ContextMenu.test.tsx` "lets a nested layer consume Escape before the context menu", "closes on Escape even when opened without auto-focus", and "ignores Escape during IME composition" | Nested layer; Escape; composition | A context menu that closes with its nested child, or on a composition Escape, fails. | `audit:ContextMenu/behavior` | -| FR10, PR1 | `ContextMenu.test.tsx` invocation and handler-composition cases ("composes the consumer context-menu handler with menu opening", "keeps component-owned opening when a consumer prevents default", "composes consumer touch handlers with long-press detection"); `ContextMenu.sheetLoading.test.tsx` (a pointer menu loads no sheet action list; a sheet menu opens, drills in and comes back) | Right click, long press, keyboard | A context request that does not open the menu, a dropped consumer handler, or a pointer menu that loads the sheet's action list fails. Evidence gap: no test asserts listener cleanup on unmount; nothing tests a headless factory, which does not ship (the FR10 gap). | `audit:ContextMenu/behavior` | -| FR11 | `ContextMenu.test.tsx` "Tab from a flyout leaves the whole menu" case | a sub-menu row | A Tab that leaves the menu or a flyout open, or a second `onOpenChange(false)`, fails. | `audit:ContextMenu/accessibility` | -| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and target | Missing, extra, prefixed, stale, or unclassified mappings fail repository validation. | `audit:ContextMenu/theming` | -| RTL relation | RTL audit curated D2 target (`apps/storybook/rtl-audit/targets.json`) on the `Presentation / BottomSheet submenu` story | BottomSheet opened into a submenu, LTR and RTL | The sheet header's back button not at the inline start of its heading in both directions fails D2. | `audit:ContextMenu/i18n-rtl` | +| Contract | Verification | Representative states | Mutation or failure expectation | Audit section | +| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | +| FR1, FR4 | `ContextMenu.test.tsx` rendering, invocation, bottom-sheet, adaptive, compound, and disabled cases ("renders menu with role=\"menu\"", "opens menu on right-click", "opens from a keyboard-invoked contextmenu (Shift+F10 / Menu key)", "opens for a finger still down at 735 ms (iOS 26.2), not a millisecond before", "opens the real menu content in a BottomSheet when requested", "uses the BottomSheet for adaptive presentation on compact touch", "renders menuContent as menu items", "does not open when isDisabled is true") | Right-click, keyboard, long press; pointer and sheet; data and compound; disabled | A missing invocation path, menu role, sheet, or compound interior, or a disabled trigger that opens, fails. Evidence gap: no test asserts that a disabled trigger leaves the native context menu alone. | `audit:ContextMenu/anatomy` | +| FR2 | `themingTargets.test.ts` | Rendered targets | A rendered class absent from the documented targets fails. Evidence gap: no test asserts `context-menu` on either painted surface or its absence from the trigger. | `audit:ContextMenu/theming` | +| FR3 | `ContextMenu.test.tsx` destructive-variant, section, divider, selectable, and alias cases | Shared rows through ContextMenu | A row that loses DropdownMenu's semantics or variant fails. Evidence gap: no test asserts the BottomSheet and List delegation beyond rendering. | `audit:ContextMenu/theming` | +| FR5 | `ContextMenu.test.tsx` "acts on the row under a finger release, once, and swallows the stray click" and outside-dismissal cases; `outsidePress.test.ts` pan cases; `ContextMenuLongPress.interaction.browser.spec.ts` "a new finger that pans outside the open menu closes it, and the page scrolls"; `ContextMenuLongPress.a11y.chromium.spec.ts` | Finger release; long press lift; tap, mouse, pen, and pan outside | A row acting on the press row, a stray click that acts, a long press that closes its own menu, a tap or mouse press outside that leaves it open, or a pan outside that leaves it open fails. Evidence gap: no test asserts the FR31 grow, the opening-finger handoff, or the FR33 lift. | `audit:ContextMenu/behavior` | +| FR5, DD1 touch scope | Browser tests on the touch story, the menu opened by a finger under a coarse pointer and by a mouse and by Shift+F10 under a fine pointer | Touch-opened, mouse-opened and keyboard-opened menus on a block trigger | A mouse- or keyboard-opened menu that lifts its trigger, tints the page or grows, or a touch-opened menu that blurs the page, grows a second surface, or animates anything but transform and opacity, fails. Evidence gap: the lift and the grow are unbuilt, so no test asserts either. | `audit:ContextMenu/behavior` | +| FR5 Reduce Motion | Browser tests on the touch story with reduced motion | A touch-opened menu opening and closing under Reduce Motion | A lift, grow or shrink that moves rather than playing an opacity-only cross-fade of 200 ms or less (`spec:AST-094` FR8) fails. Evidence gap: no test exists. | `audit:ContextMenu/behavior` | +| FR5 motion roles | Role registry tests over `spec:AST-094` FR4 | `springs.contextMenuLift`, `springs.contextMenuDismiss` and `springs.contextMenuMorph` at tempo 1 and `'standard'` | A lift, return or grow that plays a curve or a literal instead of its spring role, or a role off its FR4 table value, fails. | `audit:ContextMenu/behavior` | +| DEC-2 | Element-count browser test on the touch story (`spec:AST-017` FR60) | At rest and lifted, fine and coarse pointer | A lift element at rest, a copy of the trigger, or an open count beyond the layer, the shadow, the anchor and the placeholder fails. Evidence gap: the lift is unbuilt, so no test exists. | `audit:ContextMenu/anatomy` | +| FR6, AR1, ORD1 | `ContextMenu.test.tsx` "inline trigger (triggerAs)" and cursor-anchor cases; "does not put aria-haspopup on the role-less trigger wrapper (menus-15)"; `ContextMenu.triggerProps.test.tsx`; `ContextMenuCursorAnchor.a11y.browser.spec.ts` | `span` in a paragraph; default `div`; pointer and keyboard anchors | A block trigger in prose, a trigger with a role or `aria-haspopup`, or an anchor outside the trigger fails. | `audit:ContextMenu/behavior` | +| FR7 | `ContextMenu.test.tsx` "drills into nested data items inside the BottomSheet", "renders a submenu from a nested items array and keyboard-reaches an item after it", and "shows a sub-menu with a header or footer as its rows alone, and says why in development" | Sheet drill-in; pointer sub-menu; regions under ContextMenu | A missing sub-menu, an unreachable row after it, or a sub-menu dialog under ContextMenu fails. Evidence gap: no test here asserts the pointer drill-in on a phone. | `audit:ContextMenu/behavior` | +| FR8 | `ContextMenu.test.tsx` "wraps arrow navigation at the ends", typeahead cases, and disabled-row keyboard cases (`component:DropdownMenu` FR17) | Wrap; typeahead; disabled rows | A clamped arrow, a missing typeahead match, a disabled row the keys or typeahead skip, or a disabled row that acts or closes the menu fails. Evidence gap: no test asserts Page keys or auto-repeat. | `audit:ContextMenu/behavior` | +| FR9 | `ContextMenu.test.tsx` "lets a nested layer consume Escape before the context menu", "closes on Escape even when opened without auto-focus", and "ignores Escape during IME composition" | Nested layer; Escape; composition | A context menu that closes with its nested child, or on a composition Escape, fails. | `audit:ContextMenu/behavior` | +| FR10, PR1 | `ContextMenu.test.tsx` invocation and handler-composition cases ("composes the consumer context-menu handler with menu opening", "keeps component-owned opening when a consumer prevents default", "passes touch events through to the consumer’s own handlers", and the cases where a consumer `onTouchStart` or `onTouchEnd` runs beside the hold); `ContextMenu.sheetLoading.test.tsx` (a pointer menu loads no sheet action list; a sheet menu opens, drills in and comes back) | Right click, long press, keyboard | A context request that does not open the menu, a dropped consumer handler, or a pointer menu that loads the sheet's action list fails. Evidence gap: no test asserts listener cleanup on unmount; nothing tests a headless factory, which does not ship (the FR10 gap). | `audit:ContextMenu/behavior` | +| FR11 | `ContextMenu.test.tsx` "Tab from a flyout leaves the whole menu" case | a sub-menu row | A Tab that leaves the menu or a flyout open, or a second `onOpenChange(false)`, fails. | `audit:ContextMenu/accessibility` | +| FR12 | `ContextMenu.test.tsx` "opens for a finger still down at 735 ms (iOS 26.2), not a millisecond before" and "opens at the lift for a finger lifted after the commit (400 ms), as UIKit does", and the "before its touch layer loads" cases, and the second-document case that loads on the trigger's own window; `ContextMenu.touchLoadFailure.test.tsx` (after a failed load: one development warning, the 500 ms long press, the browser's own long-press menu, also for a finger held through that load, and a new load at the next touch); `contextMenuPress.test.ts`; `ContextMenuLongPress.interaction.browser.spec.ts` "a finger that lands before the touch layer loads starts the hold once it loads: the menu shows 735 ms after the load" and "a finger that drifts past the tolerance before the touch layer loads gets no menu once it loads" | A held finger: the commit and the menu's display; a finger down before the touch layer loads, held still or drifting; a failed load | A commit or a display off UIKit's moments fails. A hold that starts before the touch layer loads fails. A menu for a finger that drifted past the tolerance before the load fails. A failed load that leaves a finger without a menu, or never loads again, fails. | `audit:ContextMenu/behavior` | +| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and target | Missing, extra, prefixed, stale, or unclassified mappings fail repository validation. | `audit:ContextMenu/theming` | +| RTL relation | RTL audit curated D2 target (`apps/storybook/rtl-audit/targets.json`) on the `Presentation / BottomSheet submenu` story | BottomSheet opened into a submenu, LTR and RTL | The sheet header's back button not at the inline start of its heading in both directions fails D2. | `audit:ContextMenu/i18n-rtl` | ## Current-state impact - **No headless factory (FR10).** No headless context menu ships, so ContextMenu owns its invocation, open state, and outside-press listener itself, against `spec:AST-107` FR8. -- **Touch grow, pan dismissal, handoff, and lift (FR5).** A touch-opened - menu keeps the layer's own entrance and exit instead of growing from the - finger, a scroll that starts outside leaves it open, the held finger that - opened it cannot slide to a row, and a block trigger is not lifted over a - tinted page; a pen press outside closes it at the press. All are against - `spec:AST-094` FR31, FR32, and FR33. A menu opened by mouse or keyboard - already keeps its released appearance and motion. +- **Touch grow, handoff, and lift (FR5).** A touch-opened menu keeps the + layer's own entrance and exit instead of growing from the finger, the held + finger that opened it cannot slide to a row, and a block trigger is not + lifted over a tinted page; a pen press outside closes it at the press. All + are against `spec:AST-094` FR31, FR32, and FR33. A menu opened by mouse or + keyboard already keeps its released appearance and motion. +- **Touch-open focus indicator.** A touch open focuses the menu itself, and + the menu draws no focus outline in any color mode, forced colors included. + `architecture:interaction-modality` INV1 hides the focus indicator after + pointer input, and no record names an indicator for this menu under forced + colors. ## Decision log diff --git a/packages/core/src/ContextMenu/ContextMenu.doc.mjs b/packages/core/src/ContextMenu/ContextMenu.doc.mjs index f8ee2c5659074..4a5b1745c7bbe 100644 --- a/packages/core/src/ContextMenu/ContextMenu.doc.mjs +++ b/packages/core/src/ContextMenu/ContextMenu.doc.mjs @@ -132,8 +132,7 @@ export const docs = { name: 'presentation', type: "'popover' | 'bottom-sheet' | 'adaptive'", description: - 'Presentation policy. `popover` opens at the pointer position, `bottom-sheet` always uses an action sheet, and `adaptive` uses the BottomSheet on a compact touch screen: a coarse primary pointer, and a viewport narrower than the theme `md` breakpoint (768px by default) or shorter than 500px.', - default: "'popover'", + 'Presentation policy. Omitted, the menu opens at the pointer position, and under a finger a held finger opens it on iOS timing (the touch model). `popover` opens at the pointer position on every device, and a held finger opens it at 500 ms (the long press), as before; so does a finger where the primary pointer is fine. `bottom-sheet` always uses an action sheet, and `adaptive` uses the BottomSheet on a compact touch screen: a coarse primary pointer, and a viewport narrower than the theme `md` breakpoint (768px by default) or shorter than 500px.', }, { name: 'isDisabled', @@ -160,7 +159,7 @@ export const docs = { usage: { anatomy, description: - 'A right-click context menu that appears at the cursor position. Use to provide contextual actions for specific elements or regions without cluttering the UI with visible buttons.', + 'A right-click context menu that appears at the cursor position. Use to provide contextual actions for specific elements or regions without cluttering the UI with visible buttons. Under a finger, where the primary pointer is coarse, a held finger opens it with iOS timing: the menu opens at 735 ms, or as soon as the finger lifts after 400 ms.', bestPractices: [ { guidance: true, @@ -224,7 +223,7 @@ export const docs = { export const docsZh = { usage: { description: - '右键点击时在光标位置出现的上下文菜单。用于为特定元素或区域提供上下文操作,而不使 UI 杂乱。', + '右键点击时在光标位置出现的上下文菜单。用于为特定元素或区域提供上下文操作,而不使 UI 杂乱。在主指针为粗指针(触摸屏)时,按住手指即可打开,时序与 iOS 相同:735 毫秒时菜单打开;若手指在 400 毫秒后抬起,菜单在抬起时立即打开。', bestPractices: [ {guidance: true, description: '保持菜单项简洁和面向操作。'}, {guidance: true, description: '有很多项时使用分组和分隔线。'}, @@ -260,7 +259,7 @@ export const docsDense = { usage: { anatomy, description: - 'A right-click context menu that appears at the cursor position. Use to provide contextual actions for specific elements or regions.', + 'A right-click context menu that appears at the cursor position. Use to provide contextual actions for specific elements or regions. Under a finger (a coarse primary pointer): a held finger opens it at 735 ms, or on a lift after 400 ms.', bestPractices: [ {guidance: true, description: 'Keep items concise and action-oriented.'}, { diff --git a/packages/core/src/ContextMenu/ContextMenu.test.tsx b/packages/core/src/ContextMenu/ContextMenu.test.tsx index ab315cfd9611a..54581018d90a7 100644 --- a/packages/core/src/ContextMenu/ContextMenu.test.tsx +++ b/packages/core/src/ContextMenu/ContextMenu.test.tsx @@ -8,9 +8,17 @@ * SYNC: When ContextMenu.tsx changes, update tests to match new behavior */ -import {useRef, useState} from 'react'; +import {Suspense, startTransition, use, useRef, useState} from 'react'; import {createPortal} from 'react-dom'; -import {describe, it, expect, vi, beforeAll, beforeEach} from 'vitest'; +import { + describe, + it, + expect, + vi, + afterEach, + beforeAll, + beforeEach, +} from 'vitest'; import { render, screen, @@ -19,10 +27,16 @@ import { waitFor, cleanup, createEvent, + within, } from '@testing-library/react'; import userEvent from '@testing-library/user-event'; import {readFileSync} from 'node:fs'; import {ContextMenu} from './ContextMenu'; +import { + __loadContextMenuTouchLayerForTest, + __resetContextMenuTouchLayerForTest, + useContextMenuTouchLayer, +} from './contextMenuTouchLoader'; import {ContextMenuGroup} from './index'; import { ContextMenuItem, @@ -37,10 +51,16 @@ import {Divider} from '../Divider'; import {useLayerDismissal} from '../Layer/useLayerDismissal'; import {warmMenuBottomSheet} from '../DropdownMenu/__tests__/warmMenuBottomSheet'; import {COMPACT_TOUCH_PRESENTATION_QUERY} from '../hooks/useAdaptivePresentation'; +import {COMPACT_QUERY, TOUCH_QUERY} from '../utils/touchPresentation'; +import {HAPTIC_VIBRATION_PATTERNS} from '../motion/uikit'; +import {contextMenu} from '../motion/uikit/contextMenu'; // The touch sheet is loaded lazily; resolve its modules once up front, so // ContextMenu's own lazy sheet renders within the cases' waitFor. beforeAll(warmMenuBottomSheet, 20000); +// The touch layer loads after first paint. These cases hold a finger once the +// page has settled, so they load it up front; the before-load cases reset it. +beforeAll(__loadContextMenuTouchLayerForTest, 20000); function NestedDismissibleLayer({onDismiss}: {onDismiss: () => void}) { const [isOpen, setIsOpen] = useState(true); @@ -180,6 +200,17 @@ describe('ContextMenu', () => { ).toBeInTheDocument(); }); + it('suppresses native text selection on the long-press trigger', () => { + const source = readFileSync( + 'packages/core/src/ContextMenu/ContextMenu.tsx', + 'utf8', + ); + + expect(source).toMatch( + /trigger:[\s\S]*?WebkitTouchCallout: 'none',[\s\S]*?WebkitUserSelect: 'none',[\s\S]*?userSelect: 'none'/, + ); + }); + it('does not put aria-haspopup on the role-less trigger wrapper (menus-15)', () => { render( @@ -374,7 +405,11 @@ describe('ContextMenu', () => { vi.stubGlobal( 'matchMedia', vi.fn().mockImplementation((query: string) => ({ - matches: query === COMPACT_TOUCH_PRESENTATION_QUERY, + // A compact touch screen: a coarse primary pointer, a narrow viewport. + matches: + query === COMPACT_TOUCH_PRESENTATION_QUERY || + query === TOUCH_QUERY || + query === COMPACT_QUERY, media: query, onchange: null, addEventListener: vi.fn(), @@ -414,6 +449,8 @@ describe('ContextMenu', () => { it.each(['open', 'closed', 'nested'] as const)( 'judges presses once inside a %s shadow root', mode => { + // Under the touch model, so a touch on the host closes the menu. + stubPointer(true); const host = document.createElement('div'); document.body.append(host); let root = host.attachShadow({mode: mode === 'open' ? 'open' : 'closed'}); @@ -431,16 +468,33 @@ describe('ContextMenu', () => { , {container}, ); - fireEvent.contextMenu(container.querySelector('div div')!); + const trigger = container.querySelector('div div')!; + fireEvent.contextMenu(trigger); // At the document a press on the menu is retargeted to a shadow host. const item = container.querySelector('[role="menuitem"]')!; fireEvent.mouseDown(item, {composed: true}); expect(HTMLElement.prototype.hidePopover).not.toHaveBeenCalled(); - // A press on the host itself is outside the menu. + // A touch on the menu is inside too, through its lift. + const onItem = {pointerType: 'touch', pointerId: 1, composed: true}; + fireEvent.pointerDown(item, onItem); + fireEvent.pointerUp(item, onItem); + expect(HTMLElement.prototype.hidePopover).not.toHaveBeenCalled(); + // A mouse press on the host itself is outside the menu. Its + // pointerdown comes first, as a browser sends it. + fireEvent.pointerDown(host, {pointerType: 'mouse', pointerId: 3}); fireEvent.mouseDown(host); expect(HTMLElement.prototype.hidePopover).toHaveBeenCalled(); + // A touch on the host closes the menu at its lift. + vi.mocked(HTMLElement.prototype.hidePopover).mockClear(); + fireEvent.contextMenu(trigger); + const onHost = {pointerType: 'touch', pointerId: 2}; + fireEvent.pointerDown(host, onHost); + expect(HTMLElement.prototype.hidePopover).not.toHaveBeenCalled(); + fireEvent.pointerUp(host, onHost); + expect(HTMLElement.prototype.hidePopover).toHaveBeenCalled(); } finally { host.remove(); + vi.unstubAllGlobals(); } }, ); @@ -665,114 +719,861 @@ describe('ContextMenu', () => { expect(HTMLElement.prototype.showPopover).toHaveBeenCalledTimes(2); }); }); +}); - it('opens on touch long-press', () => { - vi.useFakeTimers(); - try { +/** + * A finger on the real gesture host: touch events with explicit contacts, + * stamped on the (faked) `performance.now()` clock the host reads. + */ +interface Contact { + id: number; + x: number; + y: number; +} + +function dispatchTouch( + type: 'touchstart' | 'touchmove' | 'touchend' | 'touchcancel', + target: EventTarget, + changed: Contact[], + all: Contact[], +): Event { + const event = new Event(type, {bubbles: true, cancelable: true}); + const toTouch = (contact: Contact) => ({ + identifier: contact.id, + clientX: contact.x, + clientY: contact.y, + target, + }); + Object.defineProperty(event, 'changedTouches', {value: changed.map(toTouch)}); + Object.defineProperty(event, 'touches', {value: all.map(toTouch)}); + Object.defineProperty(event, 'timeStamp', {value: performance.now()}); + target.dispatchEvent(event); + return event; +} + +function finger(target: EventTarget, id = 1, x = 20, y = 20) { + const contact = {id, x, y}; + return { + down: () => dispatchTouch('touchstart', target, [contact], [contact]), + moveTo: (nx: number, ny: number) => { + contact.x = nx; + contact.y = ny; + return dispatchTouch('touchmove', target, [contact], [contact]); + }, + up: () => dispatchTouch('touchend', target, [contact], []), + }; +} + +const advance = (ms: number) => + act(() => { + vi.advanceTimersByTime(ms); + }); + +/** The primary pointer answers `matches` to `(pointer: coarse)`. */ +function stubPointer(isCoarse: boolean) { + vi.stubGlobal( + 'matchMedia', + vi.fn().mockImplementation((query: string) => ({ + matches: isCoarse && query === '(pointer: coarse)', + media: query, + onchange: null, + addEventListener: vi.fn(), + removeEventListener: vi.fn(), + addListener: vi.fn(), + removeListener: vi.fn(), + dispatchEvent: vi.fn(), + })), + ); +} + +/** + * A finger on iOS in jsdom: a coarse pointer, on an engine that supports + * `-webkit-touch-callout` (WebKit on iOS). Undone by vi.unstubAllGlobals(). + */ +function stubIosTouch() { + vi.stubGlobal( + 'matchMedia', + vi.fn().mockImplementation((query: string) => ({ + matches: query === '(pointer: coarse)', + media: query, + onchange: null, + addEventListener: vi.fn(), + removeEventListener: vi.fn(), + addListener: vi.fn(), + removeListener: vi.fn(), + dispatchEvent: vi.fn(), + })), + ); + vi.stubGlobal('CSS', { + ...(globalThis as {CSS?: object}).CSS, + supports: (condition: string) => + condition.includes('-webkit-touch-callout'), + }); +} + +/** A finger on Android: a coarse pointer, no WebKit touch callout. */ +function stubAndroidTouch() { + stubPointer(true); +} + +// The gesture host lives as long as the document and remembers the latest +// event time. Each install of fake timers restarts `performance.now()` near 0. +// So every case moves the faked clock past the ones before it. +let clockEpoch = 0; + +// One touch model on every touch device (#8316): iOS and Android alike. +describe.each([ + ['iOS', stubIosTouch], + ['Android', stubAndroidTouch], +] as const)( + 'ContextMenu under a finger on %s: UIKit’s long-press timeline', + (_platform, stubTouch) => { + beforeEach(() => { + stubTouch(); + vi.useFakeTimers({ + toFake: [ + 'setTimeout', + 'clearTimeout', + 'setInterval', + 'clearInterval', + 'requestAnimationFrame', + 'cancelAnimationFrame', + 'performance', + 'Date', + ], + }); + clockEpoch += 100_000; + vi.advanceTimersByTime(clockEpoch); + }); + afterEach(() => { + vi.useRealTimers(); + vi.unstubAllGlobals(); + }); + + function renderMenu( + props: { + isDisabled?: boolean; + presentation?: 'popover' | 'bottom-sheet'; + triggerAs?: 'div' | 'span'; + onTouchStart?: (event: React.TouchEvent) => void; + onTouchEnd?: (event: React.TouchEvent) => void; + } = {}, + ) { render( - +
Long-press me
, ); - const trigger = screen.getByTestId('ctx'); - fireEvent.touchStart(trigger, { - touches: [{clientX: 20, clientY: 20}], + return screen.getByTestId('ctx'); + } + + it('opens for a finger still down at 735 ms (iOS 26.2), not a millisecond before', () => { + const trigger = renderMenu(); + const press = finger(trigger); + press.down(); + advance(contextMenu.press.menuDisplayMs - 1); + expect(HTMLElement.prototype.showPopover).not.toHaveBeenCalled(); + advance(1); + expect(HTMLElement.prototype.showPopover).toHaveBeenCalledTimes(1); + press.up(); + }); + + describe('before its touch layer loads', () => { + // The page's one load waits for a frame these cases never run, so each + // case loads the layer when it chooses. + beforeEach(() => { + __resetContextMenuTouchLayerForTest(); + vi.spyOn(window, 'requestAnimationFrame').mockImplementation(() => 0); + }); + afterEach(async () => { + vi.mocked(window.requestAnimationFrame).mockRestore(); + await __loadContextMenuTouchLayerForTest(); + }); + const loadLayer = async () => + act(async () => { + await __loadContextMenuTouchLayerForTest(); + }); + + it('starts the hold of a finger that landed before the load once the layer loads', async () => { + const trigger = renderMenu(); + const press = finger(trigger); + press.down(); + advance(1000); + expect(HTMLElement.prototype.showPopover).not.toHaveBeenCalled(); + await loadLayer(); + advance(contextMenu.press.menuDisplayMs - 1); + expect(HTMLElement.prototype.showPopover).not.toHaveBeenCalled(); + advance(1); + expect(HTMLElement.prototype.showPopover).toHaveBeenCalledTimes(1); + press.up(); + }); + + it('opens nothing for a finger lifted before the load', async () => { + const trigger = renderMenu(); + const press = finger(trigger); + press.down(); + advance(200); + press.up(); + await loadLayer(); + advance(contextMenu.press.menuDisplayMs * 2); + expect(HTMLElement.prototype.showPopover).not.toHaveBeenCalled(); + }); + + it('opens nothing for a finger that drifted past the tolerance before the load', async () => { + const trigger = renderMenu(); + const press = finger(trigger); + press.down(); + advance(100); + // Past the tolerance on one axis, then back to where it landed. + press.moveTo(20 + contextMenu.press.allowableMovement + 0.5, 20); + press.moveTo(20, 20); + advance(400); + await loadLayer(); + advance(contextMenu.press.menuDisplayMs * 2); + expect(HTMLElement.prototype.showPopover).not.toHaveBeenCalled(); + press.up(); }); - // Not open until the long-press threshold elapses. + + it('starts the hold of a finger that drifted within the tolerance before the load', async () => { + const trigger = renderMenu(); + const press = finger(trigger); + press.down(); + advance(100); + press.moveTo( + 20 + contextMenu.press.allowableMovement, + 20 - contextMenu.press.allowableMovement, + ); + advance(400); + await loadLayer(); + advance(contextMenu.press.menuDisplayMs); + expect(HTMLElement.prototype.showPopover).toHaveBeenCalledTimes(1); + press.up(); + }); + + it('opens nothing for a finger whose drift past the tolerance comes only as a pointer move', async () => { + // Before the layer loads, Chromium sends a small drift's pointermove + // but not its touchmove. + const trigger = renderMenu(); + const press = finger(trigger); + press.down(); + advance(100); + const primaryTouch = { + pointerType: 'touch', + pointerId: 1, + isPrimary: true, + clientY: 20, + }; + fireEvent.pointerMove(trigger, { + ...primaryTouch, + clientX: 20 + contextMenu.press.allowableMovement + 0.5, + }); + fireEvent.pointerMove(trigger, {...primaryTouch, clientX: 20}); + advance(400); + await loadLayer(); + advance(contextMenu.press.menuDisplayMs * 2); + expect(HTMLElement.prototype.showPopover).not.toHaveBeenCalled(); + press.up(); + }); + + it('starts the hold of a finger while a mouse or a second touch pointer moves far before the load', async () => { + const trigger = renderMenu(); + const press = finger(trigger); + press.down(); + advance(100); + fireEvent.pointerMove(trigger, { + pointerType: 'mouse', + pointerId: 2, + isPrimary: true, + clientX: 90, + clientY: 20, + }); + fireEvent.pointerMove(trigger, { + pointerType: 'touch', + pointerId: 3, + isPrimary: false, + clientX: 90, + clientY: 20, + }); + advance(400); + await loadLayer(); + advance(contextMenu.press.menuDisplayMs); + expect(HTMLElement.prototype.showPopover).toHaveBeenCalledTimes(1); + press.up(); + }); + + it('keeps the browser’s own long-press menu from opening it for a finger held through the load', async () => { + const trigger = renderMenu(); + const press = finger(trigger); + press.down(); + advance(500); + const opened = fireEvent( + trigger, + new MouseEvent('contextmenu', {bubbles: true, cancelable: true}), + ); + expect(opened).toBe(false); + expect(HTMLElement.prototype.showPopover).not.toHaveBeenCalled(); + await loadLayer(); + advance(contextMenu.press.menuDisplayMs); + expect(HTMLElement.prototype.showPopover).toHaveBeenCalledTimes(1); + press.up(); + }); + + it('opens at once for a right click or the menu key, with no finger down', () => { + const trigger = renderMenu(); + fireEvent.contextMenu(trigger, {clientX: 10, clientY: 10}); + expect(HTMLElement.prototype.showPopover).toHaveBeenCalledTimes(1); + }); + + it('schedules the load at the first ContextMenu under the touch model, for after a frame, and a finger does not start it', () => { + const trigger = renderMenu(); + expect(window.requestAnimationFrame).toHaveBeenCalledTimes(1); + const press = finger(trigger); + press.down(); + advance(1000); + press.up(); + expect(window.requestAnimationFrame).toHaveBeenCalledTimes(1); + }); + }); + + it('mounts the menu, closed, at the commit, and shows that element at 735 ms', () => { + const trigger = renderMenu(); + const press = finger(trigger); + press.down(); + advance(contextMenu.press.commitMs - 1); + expect(screen.queryByRole('menu', {hidden: true})).toBeNull(); + advance(1); + const menu = screen.getByRole('menu', {hidden: true}); expect(HTMLElement.prototype.showPopover).not.toHaveBeenCalled(); + advance(contextMenu.press.menuDisplayMs - contextMenu.press.commitMs); + expect(HTMLElement.prototype.showPopover).toHaveBeenCalledTimes(1); + expect(screen.getByRole('menu', {hidden: true})).toBe(menu); + press.up(); + }); + + it('mounts the menu at the commit from the committed render, when React drops a later render', async () => { + // A transition whose render suspends never commits. Its render asks for + // a bottom sheet, which mounts nothing at the commit. + const never = new Promise(() => {}); + function Suspends({isSuspended}: {isSuspended: boolean}) { + if (isSuspended) { + use(never); + } + return null; + } + let setIsSheet: (isSheet: boolean) => void = () => {}; + function App() { + const [isSheet, set] = useState(false); + setIsSheet = set; + return ( + + +
Long-press me
+
+ +
+ ); + } + render(); + await act(async () => { + startTransition(() => setIsSheet(true)); + }); + const press = finger(screen.getByTestId('ctx')); + press.down(); + advance(contextMenu.press.commitMs); + expect(screen.getByRole('menu', {hidden: true})).toBeTruthy(); + press.up(); + }); + + it('shows the menu mounted at the commit at the lift that comes before 735 ms', () => { + const trigger = renderMenu(); + const press = finger(trigger); + press.down(); + advance(529); + const menu = screen.getByRole('menu', {hidden: true}); act(() => { - vi.advanceTimersByTime(500); + press.up(); }); - expect(HTMLElement.prototype.showPopover).toHaveBeenCalled(); - } finally { - vi.useRealTimers(); - } - }); + expect(HTMLElement.prototype.showPopover).toHaveBeenCalledTimes(1); + expect(screen.getByRole('menu', {hidden: true})).toBe(menu); + }); - it('composes consumer touch handlers with long-press detection', () => { - vi.useFakeTimers(); - try { - const onTouchStart = vi.fn(); - render( - -
Long-press me
-
, - ); + it('mounts no menu for a press lifted before the commit', () => { + const trigger = renderMenu(); + const press = finger(trigger); + press.down(); + advance(250); + press.up(); + advance(1000); + expect(screen.queryByRole('menu', {hidden: true})).toBeNull(); + }); - fireEvent.touchStart(screen.getByTestId('ctx'), { - touches: [{clientX: 20, clientY: 20}], - }); - expect(onTouchStart).toHaveBeenCalledOnce(); + it.each([ + [ + 'a move past the tolerance', + (trigger: HTMLElement) => { + const moved = {id: 1, x: 20, y: 50}; + dispatchTouch('touchmove', trigger, [moved], [moved]); + }, + ], + [ + 'a touch the browser cancels', + (trigger: HTMLElement) => { + dispatchTouch('touchcancel', trigger, [{id: 1, x: 20, y: 20}], []); + }, + ], + ])( + 'unmounts the menu mounted at the commit after %s, before 735 ms', + (_, end) => { + const trigger = renderMenu(); + const press = finger(trigger); + press.down(); + advance(contextMenu.press.commitMs + 50); + expect(screen.getByRole('menu', {hidden: true})).toBeInTheDocument(); + act(() => { + end(trigger); + }); + advance(contextMenu.press.menuDisplayMs); + expect(screen.queryByRole('menu', {hidden: true})).toBeNull(); + expect(HTMLElement.prototype.showPopover).not.toHaveBeenCalled(); + }, + ); + + it('lights no row when a touch opens it: focus goes to the menu itself, not its first item', () => { + const trigger = renderMenu(); + const press = finger(trigger); + press.down(); + advance(contextMenu.press.menuDisplayMs); + // The focus moves on the next frame. + advance(20); + expect(screen.getByRole('menu', {hidden: true})).toHaveFocus(); + expect( + screen.getByRole('menuitem', {name: 'Item 1', hidden: true}), + ).not.toHaveFocus(); + press.up(); + }); + it('opens at the lift for a finger lifted after the commit (400 ms), as UIKit does', () => { + const trigger = renderMenu(); + const press = finger(trigger); + press.down(); + advance(529); + expect(HTMLElement.prototype.showPopover).not.toHaveBeenCalled(); + // A first open mounts the menu's layer, which shows it as it attaches. act(() => { - vi.advanceTimersByTime(500); + press.up(); }); - expect(HTMLElement.prototype.showPopover).toHaveBeenCalledOnce(); - } finally { - vi.useRealTimers(); - } - }); + expect(HTMLElement.prototype.showPopover).toHaveBeenCalledTimes(1); + }); - it('clears a pending long-press when a consumer prevents default on touch end', () => { - vi.useFakeTimers(); - try { - render( + it('opens nothing for a drag past the tolerance after the commit, before the menu', () => { + const trigger = renderMenu(); + const press = finger(trigger, 1, 20, 20); + press.down(); + advance(500); + press.moveTo(20, 50); + advance(500); + press.up(); + advance(100); + expect(HTMLElement.prototype.showPopover).not.toHaveBeenCalled(); + }); + + it('keeps the menu open as the finger lifts: the lift sends no click or compatibility mouse events', () => { + const trigger = renderMenu(); + const press = finger(trigger); + press.down(); + advance(contextMenu.press.menuDisplayMs); + const lift = press.up(); + // A cancelled touchend is the one signal that stops the browser's click + // and its compatibility mousedown, which would read as a press outside. + expect(lift.defaultPrevented).toBe(true); + expect(screen.getByRole('menu', {hidden: true})).toBeInTheDocument(); + expect(HTMLElement.prototype.hidePopover).not.toHaveBeenCalled(); + }); + + it('still opens at 735 ms beside a consumer onTouchStart, which runs (#7167)', () => { + const onTouchStart = vi.fn(); + const trigger = renderMenu({onTouchStart}); + const press = finger(trigger); + press.down(); + expect(onTouchStart).toHaveBeenCalledTimes(1); + advance(contextMenu.press.menuDisplayMs - 1); + expect(HTMLElement.prototype.showPopover).not.toHaveBeenCalled(); + advance(1); + expect(HTMLElement.prototype.showPopover).toHaveBeenCalledTimes(1); + press.up(); + }); + + it('opens nothing for an early lift whose consumer onTouchEnd prevents default (#7167)', () => { + const onTouchEnd = vi.fn((event: React.TouchEvent) => { + event.preventDefault(); + }); + const trigger = renderMenu({onTouchEnd}); + const press = finger(trigger); + press.down(); + advance(200); + press.up(); + expect(onTouchEnd).toHaveBeenCalledTimes(1); + advance(1000); + expect(HTMLElement.prototype.showPopover).not.toHaveBeenCalled(); + }); + + it('moves the recognizer to the new trigger when triggerAs swaps it: a hold on the new node opens the menu', () => { + const {rerender} = render( + +
Long-press me
+
, + ); + rerender( event.preventDefault()}> -
Long-press me
+ triggerAs="span"> + Long-press me
, ); + const press = finger(screen.getByTestId('ctx')); + press.down(); + advance(contextMenu.press.menuDisplayMs); + expect(HTMLElement.prototype.showPopover).toHaveBeenCalledTimes(1); + press.up(); + }); - const trigger = screen.getByTestId('ctx'); - fireEvent.touchStart(trigger, { - touches: [{clientX: 20, clientY: 20}], + it('opens nothing for a press lifted before the commit, and leaves its click alone', () => { + const trigger = renderMenu(); + const press = finger(trigger); + press.down(); + advance(250); + const lift = press.up(); + expect(lift.defaultPrevented).toBe(false); + advance(1000); + expect(HTMLElement.prototype.showPopover).not.toHaveBeenCalled(); + }); + + it('cancels when the finger drifts past the tolerance on one axis (11.5 px)', () => { + const trigger = renderMenu(); + const press = finger(trigger, 1, 20, 20); + press.down(); + advance(50); + press.moveTo(20, 31.6); + advance(1000); + expect(HTMLElement.prototype.showPopover).not.toHaveBeenCalled(); + press.up(); + }); + + it('still opens after a drift inside the tolerance', () => { + const trigger = renderMenu(); + const press = finger(trigger, 1, 20, 20); + press.down(); + advance(50); + press.moveTo(31, 31); // 15.6 px away, 11 px on each axis + advance(contextMenu.press.menuDisplayMs); + expect(HTMLElement.prototype.showPopover).toHaveBeenCalledTimes(1); + press.up(); + }); + + it('cancels when a second finger lands before the commit', () => { + const trigger = renderMenu(); + const first = {id: 1, x: 20, y: 20}; + const second = {id: 2, x: 60, y: 20}; + dispatchTouch('touchstart', trigger, [first], [first]); + advance(100); + dispatchTouch('touchstart', trigger, [second], [first, second]); + advance(1000); + expect(HTMLElement.prototype.showPopover).not.toHaveBeenCalled(); + dispatchTouch('touchend', trigger, [first, second], []); + }); + + it('lets the long press decide while a finger is down: the browser’s own long-press menu opens nothing', () => { + const trigger = renderMenu(); + const press = finger(trigger); + press.down(); + advance(380); + // Android Chrome fires contextmenu for a held finger on its own clock. + const native = new MouseEvent('contextmenu', { + bubbles: true, + cancelable: true, + clientX: 20, + clientY: 20, }); - fireEvent.touchEnd(trigger); + trigger.dispatchEvent(native); + expect(native.defaultPrevented).toBe(true); + expect(HTMLElement.prototype.showPopover).not.toHaveBeenCalled(); + advance(contextMenu.press.menuDisplayMs - 380); + expect(HTMLElement.prototype.showPopover).toHaveBeenCalledTimes(1); + press.up(); + }); + it('plays the click haptic at the commit where the platform vibrates, and none for an early lift', () => { + const vibrate = vi.fn(() => true); + Object.defineProperty(navigator, 'vibrate', { + value: vibrate, + configurable: true, + }); + try { + const trigger = renderMenu(); + const early = finger(trigger); + early.down(); + advance(250); + early.up(); + advance(500); + expect(vibrate).not.toHaveBeenCalled(); + + const held = finger(trigger); + held.down(); + advance(contextMenu.press.commitMs - 1); + expect(vibrate).not.toHaveBeenCalled(); + advance(1); + // At the commit, before the menu shows. + expect(vibrate).toHaveBeenCalledTimes(1); + expect(HTMLElement.prototype.showPopover).not.toHaveBeenCalled(); + expect(vibrate).toHaveBeenCalledWith([ + ...HAPTIC_VIBRATION_PATTERNS[contextMenu.commitHaptic].value, + ]); + held.up(); + } finally { + // jsdom has no vibration API of its own. + delete (navigator as {vibrate?: unknown}).vibrate; + } + }); + + it('leaves the page free to scroll while a menu a finger opened is up; a touch outside closes it as it begins to pan', () => { + const trigger = renderMenu(); + const press = finger(trigger); + press.down(); + advance(contextMenu.press.commitMs); + // Lifted after the commit: the menu opens at the lift. act(() => { - vi.advanceTimersByTime(500); + press.up(); + }); + expect(HTMLElement.prototype.showPopover).toHaveBeenCalledTimes(1); + expect(document.body.style.position).toBe(''); + const outside = {pointerType: 'touch', pointerId: 9, clientX: 200}; + act(() => { + fireEvent.pointerDown(document.body, {...outside, clientY: 200}); + fireEvent.pointerMove(document.body, {...outside, clientY: 195}); + }); + expect(HTMLElement.prototype.hidePopover).not.toHaveBeenCalled(); + act(() => { + fireEvent.pointerMove(document.body, {...outside, clientY: 180}); }); + expect(HTMLElement.prototype.hidePopover).toHaveBeenCalled(); + }); + + it('leaves the page alone for a menu a right-click opened', () => { + const trigger = renderMenu(); + fireEvent.contextMenu(trigger, {clientX: 20, clientY: 20}); + expect(HTMLElement.prototype.showPopover).toHaveBeenCalledTimes(1); + expect(document.body.style.position).toBe(''); + }); + + it('passes touch events through to the consumer’s own handlers', () => { + const onTouchStart = vi.fn(); + const onTouchEnd = vi.fn(); + const trigger = renderMenu({onTouchStart, onTouchEnd}); + const press = finger(trigger); + press.down(); + press.up(); + expect(onTouchStart).toHaveBeenCalledTimes(1); + expect(onTouchEnd).toHaveBeenCalledTimes(1); + }); + + it('keeps today’s menu with presentation="popover": a held finger opens it at 500 ms through today’s long press, with no growth and no scroll lock', () => { + const trigger = renderMenu({presentation: 'popover'}); + const shows = () => + vi.mocked(HTMLElement.prototype.showPopover).mock.calls.length; + expect(trigger).not.toHaveAttribute('data-astryx-pressable'); + const press = finger(trigger); + press.down(); + advance(499); + expect(shows()).toBe(0); + advance(1); + expect(shows()).toBe(1); + // Today’s menu: the first row takes the focus, nothing grows, the page + // is not locked. + expect(trigger.style.getPropertyValue('scale')).toBe(''); + expect(document.body.style.overflow).not.toBe('hidden'); + press.up(); + // The browser’s own long-press menu (Android Chrome) still opens it. + fireEvent.contextMenu(trigger, {clientX: 20, clientY: 20, detail: 1}); + expect(shows()).toBeGreaterThanOrEqual(1); + }); + + it('with presentation="popover", a drift past 10 px or a lift before 500 ms opens nothing (today’s long press)', () => { + const trigger = renderMenu({presentation: 'popover'}); + const shows = () => + vi.mocked(HTMLElement.prototype.showPopover).mock.calls.length; + let press = finger(trigger); + press.down(); + advance(300); + press.up(); + advance(400); + expect(shows()).toBe(0); + press = finger(trigger); + press.down(); + press.moveTo(31, 20); + advance(600); + expect(shows()).toBe(0); + press.up(); + }); + + it('opens nothing on touch when disabled', () => { + const trigger = renderMenu({isDisabled: true}); + const press = finger(trigger); + press.down(); + advance(1000); expect(HTMLElement.prototype.showPopover).not.toHaveBeenCalled(); - } finally { - vi.useRealTimers(); - } + press.up(); + }); + }, +); + +describe('ContextMenu under a fine pointer: the touch model costs nothing', () => { + beforeEach(() => { + stubPointer(false); + vi.useFakeTimers({ + toFake: [ + 'setTimeout', + 'clearTimeout', + 'setInterval', + 'clearInterval', + 'requestAnimationFrame', + 'cancelAnimationFrame', + 'performance', + 'Date', + ], + }); + clockEpoch += 100_000; + vi.advanceTimersByTime(clockEpoch); + }); + afterEach(() => { + vi.useRealTimers(); + vi.unstubAllGlobals(); }); - it('suppresses native text selection on the long-press trigger', () => { - const source = readFileSync( - 'packages/core/src/ContextMenu/ContextMenu.tsx', - 'utf8', + it('opens today’s menu for a finger held 500 ms (today’s long press), with no touch model: no growth, no scroll lock, the first row focused', () => { + // A fine pointer in this context, before any check. + expect(window.matchMedia('(pointer: coarse)').matches).toBe(false); + const onTouchStart = vi.fn(); + render( + +
Right-click me
+
, ); + const trigger = screen.getByTestId('ctx'); + expect(trigger).not.toHaveAttribute('data-astryx-pressable'); + const press = finger(trigger); + press.down(); + expect(onTouchStart).toHaveBeenCalledTimes(1); + advance(499); + expect(HTMLElement.prototype.showPopover).not.toHaveBeenCalled(); + advance(1); + expect(HTMLElement.prototype.showPopover).toHaveBeenCalledTimes(1); + expect(trigger.style.getPropertyValue('scale')).toBe(''); + expect(document.body.style.overflow).not.toBe('hidden'); + advance(20); + expect( + screen.getByRole('menuitem', {name: 'Item 1', hidden: true}), + ).toHaveFocus(); + press.up(); + }); - expect(source).toMatch( - /trigger:[\s\S]*?WebkitTouchCallout: 'none',[\s\S]*?WebkitUserSelect: 'none',[\s\S]*?userSelect: 'none'/, + it('does not hand the finger that opened the menu on to it: a slide onto a row and a lift pick nothing', () => { + const onClick = vi.fn(); + render( + +
Right-click me
+
, + ); + const trigger = screen.getByTestId('ctx'); + const press = finger(trigger); + press.down(); + advance(500); + expect(HTMLElement.prototype.showPopover).toHaveBeenCalledTimes(1); + const row = screen.getByRole('menuitem', {name: 'Item 1', hidden: true}); + const box = row.getBoundingClientRect(); + press.moveTo(box.left + 4, box.top + 4); + press.up(); + advance(50); + expect(onClick).not.toHaveBeenCalled(); + }); + + it('opens the cursor menu on a right-click, as before', () => { + render( + +
Right-click me
+
, ); + const trigger = screen.getByTestId('ctx'); + fireEvent.contextMenu(trigger, {clientX: 20, clientY: 20, detail: 1}); + expect(HTMLElement.prototype.showPopover).toHaveBeenCalledTimes(1); + advance(20); + expect( + screen.getByRole('menuitem', {name: 'Item 1', hidden: true}), + ).toHaveFocus(); }); +}); - it('cancels the long-press when the finger moves past the threshold', () => { - vi.useFakeTimers(); - try { - render( +describe('ContextMenu: the primary pointer alone picks a finger’s rules (spec:AST-094 FR13, FR33)', () => { + beforeEach(() => { + vi.useFakeTimers({ + toFake: [ + 'setTimeout', + 'clearTimeout', + 'setInterval', + 'clearInterval', + 'requestAnimationFrame', + 'cancelAnimationFrame', + 'performance', + 'Date', + ], + }); + clockEpoch += 100_000; + vi.advanceTimersByTime(clockEpoch); + }); + afterEach(() => { + vi.useRealTimers(); + vi.unstubAllGlobals(); + }); + + it('opens for the same held finger at 735 ms where the primary pointer is coarse, and at 500 ms where it is fine', () => { + const shows = () => + vi.mocked(HTMLElement.prototype.showPopover).mock.calls.length; + const renderTrigger = () => { + const view = render( -
Long-press me
+
Hold me
, ); - const trigger = screen.getByTestId('ctx'); - fireEvent.touchStart(trigger, {touches: [{clientX: 20, clientY: 20}]}); - // Move past MOVE_CANCEL_PX (10px) — treated as a scroll, not a press. - fireEvent.touchMove(trigger, {touches: [{clientX: 20, clientY: 40}]}); - act(() => { - vi.advanceTimersByTime(500); - }); - expect(HTMLElement.prototype.showPopover).not.toHaveBeenCalled(); - } finally { - vi.useRealTimers(); - } + return {trigger: screen.getByTestId('ctx'), unmount: view.unmount}; + }; + // Coarse: the touch model's timeline, no menu at 500 ms. + stubPointer(true); + const coarse = renderTrigger(); + let press = finger(coarse.trigger); + press.down(); + advance(600); + expect(shows()).toBe(0); + advance(contextMenu.press.menuDisplayMs - 600); + expect(shows()).toBe(1); + press.up(); + coarse.unmount(); + vi.mocked(HTMLElement.prototype.showPopover).mockClear(); + // Fine: today's long press, the same finger opens at 500 ms. + stubPointer(false); + const fine = renderTrigger(); + press = finger(fine.trigger); + press.down(); + advance(499); + expect(shows()).toBe(0); + advance(1); + expect(shows()).toBe(1); + press.up(); }); }); @@ -1629,6 +2430,16 @@ describe('ContextMenu inline trigger (triggerAs)', () => { describe('ContextMenu outside dismissal', () => { const finger = (pointerId: number) => ({pointerType: 'touch', pointerId}); + // Under the touch model, a coarse primary pointer. Undone at the end. + function underTouchModel(run: () => void) { + stubPointer(true); + try { + run(); + } finally { + vi.unstubAllGlobals(); + } + } + // Holds a finger on the trigger until the long-press opens the menu. Only // the long-press delay is faked. function longPress(trigger: HTMLElement, pointerId: number) { @@ -1721,7 +2532,25 @@ describe('ContextMenu outside dismissal', () => { expect(onOpenChange).not.toHaveBeenCalledWith(false); }); - it('a tap outside closes the menu through its compatibility mousedown; a scroll that starts outside leaves it open', () => { + it('under the touch model, a tap outside closes the menu at its lift, and a scroll that starts outside closes it as the browser takes the finger', () => { + underTouchModel(() => { + const onOpenChange = vi.fn<(isOpen: boolean) => void>(); + const {trigger, outside} = renderMenu(onOpenChange); + fireEvent.contextMenu(trigger, {clientX: 50, clientY: 15, detail: 1}); + // The browser takes this finger for a scroll: no compatibility events. + fireEvent.pointerDown(outside, finger(3)); + expect(onOpenChange).toHaveBeenLastCalledWith(true); + fireEvent.pointerCancel(outside, finger(3)); + expect(onOpenChange).toHaveBeenLastCalledWith(false); + fireEvent.contextMenu(trigger, {clientX: 50, clientY: 15, detail: 1}); + fireEvent.pointerDown(outside, finger(4)); + expect(onOpenChange).toHaveBeenLastCalledWith(true); + lift(outside, 4); + expect(onOpenChange).toHaveBeenLastCalledWith(false); + }); + }); + + it('outside the touch model, a tap outside closes the menu through its compatibility mousedown, and a scroll that starts outside leaves it open', () => { const onOpenChange = vi.fn<(isOpen: boolean) => void>(); const {trigger, outside} = renderMenu(onOpenChange); fireEvent.contextMenu(trigger, {clientX: 50, clientY: 15, detail: 1}); @@ -1734,6 +2563,37 @@ describe('ContextMenu outside dismissal', () => { expect(onOpenChange).toHaveBeenLastCalledWith(false); }); + it('with presentation="popover", a finger keeps the released outside dismissal: a scroll or a drag outside leaves the menu open', () => { + underTouchModel(() => { + const onOpenChange = vi.fn<(isOpen: boolean) => void>(); + render( + <> + +
Long-press me
+
+ + , + ); + const outside = screen.getByRole('button', {name: 'Outside'}); + fireEvent.contextMenu(screen.getByTestId('ctx'), { + clientX: 50, + clientY: 15, + detail: 1, + }); + fireEvent.pointerDown(outside, {...finger(3), clientX: 0, clientY: 0}); + fireEvent.pointerCancel(outside, finger(3)); + fireEvent.pointerDown(outside, {...finger(4), clientX: 0, clientY: 0}); + fireEvent.pointerMove(outside, {...finger(4), clientX: 0, clientY: 40}); + fireEvent.pointerUp(outside, finger(4)); + expect(onOpenChange).toHaveBeenLastCalledWith(true); + expect(onOpenChange).not.toHaveBeenCalledWith(false); + }); + }); + it('a mouse press or a pen press outside closes the menu at the press', () => { for (const pointerType of ['mouse', 'pen']) { const onOpenChange = vi.fn<(isOpen: boolean) => void>(); @@ -1746,7 +2606,7 @@ describe('ContextMenu outside dismissal', () => { } }); - it('presses that send no mousedown leave the menu open, as before: a cancelled pointerdown, a finger drag, a second finger', () => { + it('a mouse press that sends no mousedown leaves the menu open, as before', () => { const onOpenChange = vi.fn<(isOpen: boolean) => void>(); const {trigger, outside} = renderMenu(onOpenChange); fireEvent.contextMenu(trigger, {clientX: 50, clientY: 15, detail: 1}); @@ -1754,18 +2614,240 @@ describe('ContextMenu outside dismissal', () => { // resize handle): the browser sends no mousedown. fireEvent.pointerDown(outside, {pointerType: 'mouse', pointerId: 1}); fireEvent.pointerUp(outside, {pointerType: 'mouse', pointerId: 1}); - // A finger drag on a surface that does not pan (a Slider), lifted. - fireEvent.pointerDown(outside, finger(5)); - fireEvent.pointerMove(outside, finger(5)); - fireEvent.pointerUp(outside, finger(5)); - // A second finger's tap. - fireEvent.pointerDown(outside, finger(6)); - fireEvent.pointerDown(outside, finger(7)); - fireEvent.pointerUp(outside, finger(7)); - fireEvent.pointerCancel(outside, finger(6)); expect(onOpenChange).toHaveBeenLastCalledWith(true); expect(onOpenChange).not.toHaveBeenCalledWith(false); }); + + it('under the touch model, a finger outside closes the menu as it pans past the pan threshold, or at its lift; a second finger waits for the first one', () => { + underTouchModel(() => { + const onOpenChange = vi.fn<(isOpen: boolean) => void>(); + const {trigger, outside} = renderMenu(onOpenChange); + const open = () => + fireEvent.contextMenu(trigger, {clientX: 50, clientY: 15, detail: 1}); + // A drag on a surface that does not pan (a Slider): it closes the menu + // as it travels past the pan threshold, before the lift. + open(); + fireEvent.pointerDown(outside, {...finger(5), clientX: 0, clientY: 0}); + fireEvent.pointerMove(outside, {...finger(5), clientX: 8, clientY: 0}); + expect(onOpenChange).toHaveBeenLastCalledWith(true); + fireEvent.pointerMove(outside, {...finger(5), clientX: 30, clientY: 0}); + expect(onOpenChange).toHaveBeenLastCalledWith(false); + fireEvent.pointerUp(outside, finger(5)); + // A second finger's tap does not end the first finger's touch. + open(); + fireEvent.pointerDown(outside, finger(6)); + fireEvent.pointerDown(outside, finger(7)); + fireEvent.pointerUp(outside, finger(7)); + expect(onOpenChange).toHaveBeenLastCalledWith(true); + fireEvent.pointerUp(outside, finger(6)); + expect(onOpenChange).toHaveBeenLastCalledWith(false); + }); + }); + + it('under the touch model, a touch on the menu itself leaves it open', () => { + underTouchModel(() => { + const onOpenChange = vi.fn<(isOpen: boolean) => void>(); + const {trigger} = renderMenu(onOpenChange); + fireEvent.contextMenu(trigger, {clientX: 50, clientY: 15, detail: 1}); + const menu = screen.getByRole('menu', {hidden: true}); + fireEvent.pointerDown(menu, {...finger(8), clientX: 0, clientY: 0}); + fireEvent.pointerMove(menu, {...finger(8), clientX: 0, clientY: 40}); + fireEvent.pointerUp(menu, finger(8)); + expect(onOpenChange).not.toHaveBeenCalledWith(false); + }); + }); + + describe('in a second document', () => { + // An app can render a ContextMenu into a same-origin iframe or a Document + // Picture-in-Picture window through a portal. Every press for it then + // happens in that document. + let frame: HTMLIFrameElement; + let secondDocument: Document; + + beforeEach(() => { + frame = document.createElement('iframe'); + document.body.appendChild(frame); + secondDocument = frame.contentDocument!; + // The Popover API stand-in above, on the second window's own prototype. + const {prototype} = secondDocument.defaultView!.HTMLElement; + prototype.showPopover = HTMLElement.prototype.showPopover; + prototype.hidePopover = HTMLElement.prototype.hidePopover; + prototype.matches = HTMLElement.prototype.matches; + }); + + afterEach(() => { + // Unmount before the frame goes, or React removes nodes from a + // document that no longer exists. + cleanup(); + frame.remove(); + }); + + it('a mouse press outside the menu closes it in the document it renders in; a press in the page does not', () => { + const onOpenChange = vi.fn<(isOpen: boolean) => void>(); + render( + createPortal( + <> + +
Right-click me
+
+ + , + secondDocument.body, + ), + ); + const view = within(secondDocument.body); + fireEvent.contextMenu(view.getByTestId('ctx'), { + clientX: 50, + clientY: 15, + detail: 1, + }); + expect(onOpenChange).toHaveBeenLastCalledWith(true); + fireEvent.pointerDown(document.body, { + pointerType: 'mouse', + pointerId: 1, + }); + fireEvent.mouseDown(document.body); + expect(onOpenChange).not.toHaveBeenCalledWith(false); + const outside = view.getByRole('button', {name: 'Outside'}); + fireEvent.pointerDown(outside, {pointerType: 'mouse', pointerId: 1}); + fireEvent.mouseDown(outside); + expect(onOpenChange).toHaveBeenLastCalledWith(false); + }); + + it('times a finger on the second document’s own clock: a short tap opens no menu and keeps its click', () => { + vi.useFakeTimers({ + toFake: ['setTimeout', 'clearTimeout', 'performance', 'Date'], + }); + clockEpoch += 100_000; + vi.advanceTimersByTime(clockEpoch); + const view = secondDocument.defaultView as Window & typeof globalThis; + // The frame opened after the page, so its clock reads 5 s less. Its + // events come stamped on that clock. + const frameNow = vi + .spyOn(view.performance, 'now') + .mockImplementation(() => performance.now() - 5000); + const coarse = vi.fn().mockImplementation((query: string) => ({ + matches: query === '(pointer: coarse)', + media: query, + addEventListener: vi.fn(), + removeEventListener: vi.fn(), + })); + vi.stubGlobal('matchMedia', coarse); + Object.defineProperty(view, 'matchMedia', { + value: coarse, + configurable: true, + }); + try { + const onOpenChange = vi.fn<(isOpen: boolean) => void>(); + render( + createPortal( + +
Long-press me
+
, + secondDocument.body, + ), + ); + const trigger = within(secondDocument.body).getByTestId('ctx'); + const send = (type: 'touchstart' | 'touchend') => { + const event = new view.Event(type, {bubbles: true, cancelable: true}); + const contact = { + identifier: 1, + clientX: 20, + clientY: 20, + target: trigger, + }; + Object.defineProperty(event, 'changedTouches', {value: [contact]}); + Object.defineProperty(event, 'touches', { + value: type === 'touchstart' ? [contact] : [], + }); + Object.defineProperty(event, 'timeStamp', { + value: view.performance.now(), + }); + trigger.dispatchEvent(event); + return event; + }; + send('touchstart'); + act(() => { + vi.advanceTimersByTime(120); + }); + const lift = send('touchend'); + act(() => { + vi.advanceTimersByTime(1000); + }); + expect(onOpenChange).not.toHaveBeenCalledWith(true); + expect(lift.defaultPrevented).toBe(false); + } finally { + frameNow.mockRestore(); + vi.unstubAllGlobals(); + vi.useRealTimers(); + } + }); + + it('schedules the touch layer’s load on the trigger’s own window', async () => { + __resetContextMenuTouchLayerForTest(); + const view = secondDocument.defaultView as Window & typeof globalThis; + // The page paints no frame, as when its tab is hidden, while the + // second window paints. + const pageFrames = vi + .spyOn(window, 'requestAnimationFrame') + .mockImplementation(() => 0); + const frameFrames = vi.fn((callback: FrameRequestCallback) => { + callback(0); + return 1; + }); + Object.defineProperty(view, 'requestAnimationFrame', { + value: frameFrames, + configurable: true, + }); + const coarse = vi.fn().mockImplementation((query: string) => ({ + matches: query === '(pointer: coarse)', + media: query, + addEventListener: vi.fn(), + removeEventListener: vi.fn(), + })); + vi.stubGlobal('matchMedia', coarse); + Object.defineProperty(view, 'matchMedia', { + value: coarse, + configurable: true, + }); + // Reads the page's one touch layer, as every ContextMenu does. + function LayerProbe() { + const {layer} = useContextMenuTouchLayer(true); + return ( + + {layer == null ? 'waiting' : 'loaded'} + + ); + } + try { + render( + <> + + {createPortal( + +
Long-press me
+
, + secondDocument.body, + )} + , + ); + expect(frameFrames).toHaveBeenCalled(); + await vi.waitFor(() => { + expect(screen.getByTestId('probe')).toHaveTextContent('loaded'); + }); + } finally { + pageFrames.mockRestore(); + vi.unstubAllGlobals(); + await __loadContextMenuTouchLayerForTest(); + } + }); + }); }); describe('ContextMenu: Tab from a flyout leaves the whole menu (APG menu button)', () => { diff --git a/packages/core/src/ContextMenu/ContextMenu.touchLoadFailure.test.tsx b/packages/core/src/ContextMenu/ContextMenu.touchLoadFailure.test.tsx new file mode 100644 index 0000000000000..ca3e387418ce4 --- /dev/null +++ b/packages/core/src/ContextMenu/ContextMenu.touchLoadFailure.test.tsx @@ -0,0 +1,325 @@ +// Copyright (c) Meta Platforms, Inc. and affiliates. + +/** + * @file ContextMenu.touchLoadFailure.test.tsx + * @input Uses vitest, Testing Library and ContextMenu, with the touch layer's + * import failing until a case lets it load + * @output Checks a finger on a ContextMenu whose touch layer failed to load: + * one development warning, the 500 ms long press and the browser's own + * long-press menu open the menu, and the next touch loads the layer again + * @position Testing; the loaded touch layer is in ContextMenu.test.tsx + */ + +import { + act, + cleanup, + fireEvent, + render, + screen, + within, +} from '@testing-library/react'; +import {createPortal} from 'react-dom'; +import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest'; +import {contextMenu} from '../motion/uikit/contextMenu'; +import {__resetDevWarnings} from '../utils/devWarning'; +import {ContextMenu} from './ContextMenu'; +import {__resetContextMenuTouchLayerForTest} from './contextMenuTouchLoader'; + +/** The touch layer's import fails while `attempts` is at most `failUntil`. */ +const layerImport = vi.hoisted(() => ({ + attempts: 0, + failUntil: Number.POSITIVE_INFINITY, +})); + +vi.mock('./ContextMenuTouchLayer', async importOriginal => { + layerImport.attempts += 1; + if (layerImport.attempts <= layerImport.failUntil) { + throw new Error('Failed to fetch dynamically imported module'); + } + return importOriginal(); +}); + +interface Contact { + id: number; + x: number; + y: number; +} + +function dispatchTouch( + type: 'touchstart' | 'touchend', + target: EventTarget, + changed: Contact[], + all: Contact[], +): void { + const event = new Event(type, {bubbles: true, cancelable: true}); + const toTouch = (contact: Contact) => ({ + identifier: contact.id, + clientX: contact.x, + clientY: contact.y, + target, + }); + Object.defineProperty(event, 'changedTouches', {value: changed.map(toTouch)}); + Object.defineProperty(event, 'touches', {value: all.map(toTouch)}); + Object.defineProperty(event, 'timeStamp', {value: performance.now()}); + target.dispatchEvent(event); +} + +function finger(target: EventTarget) { + const contact = {id: 1, x: 20, y: 20}; + return { + down: () => dispatchTouch('touchstart', target, [contact], [contact]), + up: () => dispatchTouch('touchend', target, [contact], []), + }; +} + +const advance = (ms: number) => + act(() => { + vi.advanceTimersByTime(ms); + }); + +/** Runs the page's scheduled load, and what it starts, to its end. */ +async function settleLoad(): Promise { + await act(async () => { + await vi.advanceTimersByTimeAsync(100); + }); +} + +// The gesture host remembers the latest event time, and each install of fake +// timers restarts the faked clock. So every case moves it past the ones +// before it. +let clockEpoch = 0; + +describe('ContextMenu under a finger when its touch layer fails to load', () => { + let warn: ReturnType; + + beforeEach(() => { + vi.stubGlobal( + 'matchMedia', + vi.fn().mockImplementation((query: string) => ({ + matches: query === '(pointer: coarse)', + media: query, + onchange: null, + addEventListener: vi.fn(), + removeEventListener: vi.fn(), + addListener: vi.fn(), + removeListener: vi.fn(), + dispatchEvent: vi.fn(), + })), + ); + HTMLElement.prototype.showPopover = vi.fn(function (this: HTMLElement) { + this.setAttribute('popover-open', ''); + }); + HTMLElement.prototype.hidePopover = vi.fn(function (this: HTMLElement) { + this.removeAttribute('popover-open'); + }); + vi.useFakeTimers({ + toFake: [ + 'setTimeout', + 'clearTimeout', + 'requestAnimationFrame', + 'cancelAnimationFrame', + 'performance', + 'Date', + ], + }); + clockEpoch += 100_000; + vi.advanceTimersByTime(clockEpoch); + __resetContextMenuTouchLayerForTest(); + __resetDevWarnings(); + warn = vi.spyOn(console, 'warn').mockImplementation(() => {}); + }); + + afterEach(() => { + cleanup(); + warn.mockRestore(); + vi.useRealTimers(); + vi.unstubAllGlobals(); + }); + + function renderMenu(): HTMLElement { + render( + +
Long-press me
+
, + ); + return screen.getByTestId('ctx'); + } + + it('warns once in development, however many loads fail', async () => { + const trigger = renderMenu(); + await settleLoad(); + expect(warn).toHaveBeenCalledTimes(1); + expect(String(warn.mock.calls[0][0])).toContain('ContextMenu'); + const attempts = layerImport.attempts; + // The next touch asks again, and that load fails too. + const press = finger(trigger); + press.down(); + await settleLoad(); + press.up(); + expect(layerImport.attempts).toBe(attempts + 1); + expect(warn).toHaveBeenCalledTimes(1); + }); + + it('gives a held finger the 500 ms long press after a failed load', async () => { + const trigger = renderMenu(); + await settleLoad(); + const press = finger(trigger); + press.down(); + advance(499); + expect(HTMLElement.prototype.showPopover).not.toHaveBeenCalled(); + advance(1); + expect(HTMLElement.prototype.showPopover).toHaveBeenCalledTimes(1); + press.up(); + }); + + it('lets the browser’s own long-press menu open it after a failed load', async () => { + const trigger = renderMenu(); + await settleLoad(); + const press = finger(trigger); + press.down(); + advance(300); + fireEvent( + trigger, + new MouseEvent('contextmenu', { + bubbles: true, + cancelable: true, + clientX: 20, + clientY: 20, + }), + ); + expect(HTMLElement.prototype.showPopover).toHaveBeenCalledTimes(1); + press.up(); + }); + + it('lets the browser’s own long-press menu open it for a finger held through the failed load', async () => { + const trigger = renderMenu(); + // The finger lands while the load runs, and that load fails. + const press = finger(trigger); + press.down(); + await settleLoad(); + fireEvent( + trigger, + new MouseEvent('contextmenu', { + bubbles: true, + cancelable: true, + clientX: 20, + clientY: 20, + }), + ); + expect(HTMLElement.prototype.showPopover).toHaveBeenCalledTimes(1); + press.up(); + }); + + it('starts no load when a trigger mounts after a failed load, until a touch asks', async () => { + renderMenu(); + await settleLoad(); + const attempts = layerImport.attempts; + // A second menu mounts after the failure. Mounting is no intent. + render( + +
Long-press me too
+
, + ); + await settleLoad(); + expect(layerImport.attempts).toBe(attempts); + // A touch on it is the intent that asks again. + const press = finger(screen.getByTestId('ctx-2')); + press.down(); + await settleLoad(); + press.up(); + expect(layerImport.attempts).toBe(attempts + 1); + }); + + it('starts no load when a trigger mounts in another document after a failed load, until a touch asks', async () => { + renderMenu(); + await settleLoad(); + const attempts = layerImport.attempts; + const frame = document.createElement('iframe'); + document.body.appendChild(frame); + const otherDocument = frame.contentDocument!; + const view = otherDocument.defaultView as Window & typeof globalThis; + // The other window paints and idles at once, so a load it scheduled + // would start at once. + Object.defineProperty(view, 'requestAnimationFrame', { + value: (callback: FrameRequestCallback) => { + callback(0); + return 1; + }, + configurable: true, + }); + Object.defineProperty(view, 'setTimeout', { + value: (callback: () => void) => { + callback(); + return 1; + }, + configurable: true, + }); + Object.defineProperty(view, 'matchMedia', { + value: window.matchMedia, + configurable: true, + }); + try { + render( + createPortal( + +
Long-press me too
+
, + otherDocument.body, + ), + ); + await settleLoad(); + expect(layerImport.attempts).toBe(attempts); + // A touch on it is the intent that asks again. + const trigger = within(otherDocument.body).getByTestId('ctx-2'); + const send = (type: 'touchstart' | 'touchend') => { + const event = new view.Event(type, {bubbles: true, cancelable: true}); + const contact = { + identifier: 1, + clientX: 20, + clientY: 20, + target: trigger, + }; + Object.defineProperty(event, 'changedTouches', {value: [contact]}); + Object.defineProperty(event, 'touches', { + value: type === 'touchstart' ? [contact] : [], + }); + Object.defineProperty(event, 'timeStamp', {value: performance.now()}); + trigger.dispatchEvent(event); + }; + send('touchstart'); + await settleLoad(); + send('touchend'); + expect(layerImport.attempts).toBe(attempts + 1); + } finally { + // Unmount before the frame goes, or React removes nodes from a + // document that no longer exists. + cleanup(); + frame.remove(); + } + }); + + // Last: once the layer has loaded, the page keeps it. + it('loads the layer again at the next touch, and a later finger gets the hold', async () => { + const trigger = renderMenu(); + await settleLoad(); + // The next load succeeds. The module loads here first, outside the fake + // timers, so the trigger's new load ends inside this case. + layerImport.failUntil = layerImport.attempts; + await import('./ContextMenuTouchLayer'); + const first = finger(trigger); + first.down(); + await settleLoad(); + first.up(); + await act(async () => { + await vi.advanceTimersByTimeAsync(contextMenu.press.menuDisplayMs * 2); + }); + vi.mocked(HTMLElement.prototype.showPopover).mockClear(); + const second = finger(trigger); + second.down(); + advance(contextMenu.press.menuDisplayMs - 1); + expect(HTMLElement.prototype.showPopover).not.toHaveBeenCalled(); + advance(1); + expect(HTMLElement.prototype.showPopover).toHaveBeenCalledTimes(1); + second.up(); + }); +}); diff --git a/packages/core/src/ContextMenu/ContextMenu.tsx b/packages/core/src/ContextMenu/ContextMenu.tsx index ae68da4fc5f49..341b33b0df561 100644 --- a/packages/core/src/ContextMenu/ContextMenu.tsx +++ b/packages/core/src/ContextMenu/ContextMenu.tsx @@ -4,8 +4,9 @@ /** * @file ContextMenu.tsx * @input Uses React, StyleX, useLayer, shared layer dismissal, the lazily - * loaded menu sheet (DropdownMenu/lazyMenuBottomSheet), useListFocus, and the - * shared menu-presentation resolver + * loaded menu sheet (DropdownMenu/lazyMenuBottomSheet), useListFocus, the + * presentation resolver (usePresentation), useLongPress, and the touch layer + * (ContextMenuTouchLayer), which loads after first paint * @output Exports ContextMenu with cursor-popover and touch-sheet presentations * @position Core implementation; consumed by index.ts * @@ -28,7 +29,9 @@ * context menu that was never opened adds no popover element to the page (a * table with a menu on every cell would otherwise carry one per cell). Once * mounted it stays, so every later open and close, its exit animation - * included, runs as before. + * included, runs as before. A finger's hold mounts it, closed, at the + * commit, so the show at 735 ms only reveals it. A hold that ends with no + * menu unmounts it again. * The trigger wrapper is a `div` by default; `triggerAs` makes it an inline * `span`, so a reference inside prose can own a context menu without * breaking the text flow. @@ -36,6 +39,9 @@ * SYNC: When modified, update these files to stay in sync: * - /packages/core/src/ContextMenu/ContextMenu.doc.mjs * - /packages/core/src/ContextMenu/ContextMenu.test.tsx + * - /packages/core/src/ContextMenu/ContextMenuTouchLayer.tsx (the touch layer) + * - /packages/core/src/ContextMenu/contextMenuTouchLoader.ts (its load) + * - /packages/core/src/ContextMenu/contextMenuPress.ts (touch timeline) * - /packages/core/src/ContextMenu/index.ts * - /apps/storybook/stories/ContextMenu.stories.tsx * - /packages/cli/assets/templates/blocks/components/ContextMenu/ (showcase blocks) @@ -58,7 +64,7 @@ import {useLayerInternal} from '../Layer/useLayer'; import {LayerDepthProvider} from '../Layer/LayerDepthContext'; import {useLayerDismissal} from '../Layer/useLayerDismissal'; import {currentGesture} from '../Layer/gestureCounter'; -import {noteOutsideDismissal} from '../Layer/outsidePress'; +import {useOutsidePress} from '../Layer/outsidePress'; import { MenuBottomSheet, MenuBottomSheetActionList, @@ -80,10 +86,19 @@ import { } from '../DropdownMenu/menuItemRoles'; import {useMenuOverflow} from '../DropdownMenu/useMenuOverflow'; import {useMenuDrillIn} from '../DropdownMenu/useMenuDrillIn'; +import {useCommittedRefInto} from '../hooks/useCommittedRef'; import {useInternalListFocus} from '../hooks/useListFocus'; +import {useLongPress} from '../hooks/useLongPress'; import {useMenuPress} from '../hooks/useMenuPress'; import {useTypeahead} from '../hooks/useTypeahead'; -import {useLongPress} from '../hooks/useLongPress'; +import {shadowHostOf} from '../utils/flatTree'; +import {usePresentation} from '../utils/presentation'; +import {contextMenu} from '../motion/uikit/contextMenu'; +import type {ContextMenuTouchHandle, LateTouch} from './ContextMenuTouchLayer'; +import { + retryContextMenuTouchLayer, + useContextMenuTouchLayer, +} from './contextMenuTouchLoader'; import {layerAnimations} from '../Layer/layerAnimations.stylex'; import {layerViewportInset} from '../Layer/layerViewportInset.stylex'; import { @@ -106,10 +121,7 @@ import type { } from '../DropdownMenu/DropdownMenu'; import {useMergedRefs} from '../hooks/useMergedRefs'; -import { - useAdaptivePresentation, - type AdaptivePresentation, -} from '../hooks/useAdaptivePresentation'; +import type {AdaptivePresentation} from '../hooks/useAdaptivePresentation'; import { registerEnglishFallback, useComponentTranslator, @@ -119,11 +131,12 @@ import english from '../i18n/generated-english/ContextMenu/ContextMenu.generated registerEnglishFallback(english); const styles = stylex.create({ - // Trigger wrapper: suppress the iOS long-press callout/selection so the - // long-press opens our context menu instead of the native text/callout UI. - // `position: relative` establishes the containing block for the absolutely - // positioned cursor anchor below, so the anchor point tracks the trigger - // (and scrolls with it) instead of the page. + // Trigger wrapper. `position: relative` makes the containing block for the + // absolutely positioned cursor anchor below. So the anchor point follows + // the trigger, and scrolls with it, instead of the page. The iOS callout and + // text selection stay off. A long press or a right-click then opens this + // menu instead of selecting the trigger's text. The + // gesture host adds its own lock for a held press. trigger: { position: 'relative', WebkitTouchCallout: 'none', @@ -179,6 +192,10 @@ const styles = stylex.create({ transitionTimingFunction: easeVars['--ease-standard'], userSelect: 'none', WebkitTouchCallout: 'none', + // A touch open focuses the menu itself, so no row is lit. The menu is an + // internal focus target, not a control, so it shows no browser ring. + // Keyboard focus moves to an item instead. + outline: 'none', }, // Scroll ownership by the browser's own signal; see DropdownMenu. touchPinchZoom: { @@ -248,6 +265,27 @@ function keepAnchorInside(offset: number, size: number): number { return offset > size - 1 && offset <= size ? Math.max(size - 1, 0) : offset; } +/** + * Whether a move takes the finger of a kept touchstart past the press's drift + * tolerance on either axis, from where it landed. A touch move names its + * finger by `identifier`; the primary touch pointer's move names none. The + * touch layer judges later moves itself; this judges the moves before it + * loads. + */ +function driftsPastTolerance( + touchStart: TouchEvent, + to: {readonly clientX: number; readonly clientY: number}, + identifier?: number, +): boolean { + const {allowableMovement} = contextMenu.press; + return Array.from(touchStart.changedTouches).some( + landed => + (identifier === undefined || landed.identifier === identifier) && + (Math.abs(to.clientX - landed.clientX) > allowableMovement || + Math.abs(to.clientY - landed.clientY) > allowableMovement), + ); +} + // ============================================================================= // Types // ============================================================================= @@ -298,11 +336,13 @@ interface ContextMenuBaseProps extends BaseProps { onOpenChange?: (isOpen: boolean) => void; /** * Presentation policy for the menu. - * - `popover`: open beside the pointer position. + * - omitted: the menu at the pointer. Under a finger, a held finger opens it + * on iOS's timeline (the touch model). + * - `popover`: the menu at the pointer on every device, as before. A held + * finger opens it at 500 ms through today's long press. * - `bottom-sheet`: open as an action sheet. * - `adaptive`: use a BottomSheet on compact coarse-pointer viewports and * the cursor-positioned popover elsewhere. - * @default 'popover' */ presentation?: AdaptivePresentation; 'data-testid'?: string; @@ -356,7 +396,7 @@ export function ContextMenu({ label: labelFromProps, isDisabled = false, onOpenChange, - presentation = 'popover', + presentation, triggerAs = 'div', ref, className, @@ -368,14 +408,20 @@ export function ContextMenu({ onTouchMove: onTouchMoveProp, onTouchEnd: onTouchEndProp, onTouchCancel: onTouchCancelProp, + onPointerMove: onPointerMoveProp, + onPointerDown: onPointerDownProp, 'data-testid': testId, ...rest }: ContextMenuProps) { const t = useComponentTranslator(); const label = labelFromProps ?? t('@astryx.contextMenu.label'); const backLabel = t('@astryx.dropdownMenu.back'); - const resolvedPresentation = useAdaptivePresentation(presentation); - const usesBottomSheet = resolvedPresentation === 'bottom-sheet'; + // The surface, and whether the touch model applies: under a finger, unless + // the caller pins `presentation="popover"`. + const {surface, touchModes} = usePresentation(presentation, { + whenOmitted: 'touch', + }); + const usesBottomSheet = surface === 'bottom-sheet'; // Separate content props (union discriminant) from DOM pass-through attrs. // The union means exactly one of items/menuContent exists in rest; destructure // both so triggerProps contains only DOM-safe attributes. @@ -419,15 +465,35 @@ export function ContextMenu({ const [isOpen, setIsOpen] = useState(false); // An open from the trigger moves focus into the menu once it shows: a frame - // after the show, which for a first open comes as its layer attaches. - const focusOnShowRef = useRef(false); + // after the show, which for a first open comes as its layer attaches. A + // touch open focuses the menu itself; other opens focus its first row. + const focusOnShowRef = useRef<'first' | 'menu' | null>(null); const focusFirstRef = useRef<() => void>(() => {}); + const focusMenuRef = useRef<() => void>(() => {}); const [submenuPath, setSubmenuPath] = useState([]); const currentSubmenu = submenuPath.at(-1); const currentItems = currentSubmenu?.items ?? items; const currentTitle = currentSubmenu?.label ?? label; const sheetLabel = typeof currentTitle === 'string' ? currentTitle : label; + // The mounted touch layer, which says whether it times a finger. + const touchHandleRef = useRef(null); + // The touch layer loads after the page's first paint, and only while the + // touch model applies. + const {layer: TouchLayer, hasFailed: hasTouchLayerFailed} = + useContextMenuTouchLayer(touchModes && !isDisabled, triggerRef); + // A finger that lands before the touch layer has loaded, with its pointer. + // The layer begins it as it mounts, if the finger is still down. + const lateTouchRef = useRef(null); + // The latest touch pointer to go down on the trigger. Chromium sends a + // finger's pointerdown before its touchstart. + const touchPointerIdRef = useRef(null); + const takeLateTouch = useCallback(() => { + const late = lateTouchRef.current; + lateTouchRef.current = null; + return late; + }, []); + const updateOpenState = useCallback( (nextIsOpen: boolean) => { if (!nextIsOpen) { @@ -439,12 +505,17 @@ export function ContextMenu({ [onOpenChange], ); + const outsidePress = useOutsidePress(); + // Starts the outside-press watch as the menu shows. It is set below, where + // the menu's list and its close exist. + const watchOutsideRef = useRef<() => void>(() => {}); const layer = useLayerInternal({ mode: 'context', // Mounted at the first open and kept (see the file header). lazyMount: true, keepsMountAfterShow: true, onHide: useCallback(() => { + outsidePress.stop(); setIsOpen(false); onOpenChange?.(false); // Restore focus to the element that was focused before opening. @@ -453,13 +524,19 @@ export function ContextMenu({ if (toRestore && document.contains(toRestore)) { toRestore.focus(); } - }, [onOpenChange]), + }, [onOpenChange, outsidePress]), onShow: useCallback(() => { setIsOpen(true); onOpenChange?.(true); - if (focusOnShowRef.current) { - focusOnShowRef.current = false; - requestAnimationFrame(() => focusFirstRef.current()); + watchOutsideRef.current(); + const focusTarget = focusOnShowRef.current; + if (focusTarget != null) { + focusOnShowRef.current = null; + requestAnimationFrame(() => + focusTarget === 'menu' + ? focusMenuRef.current() + : focusFirstRef.current(), + ); } }, [onOpenChange]), lightDismiss: false, @@ -514,6 +591,11 @@ export function ContextMenu({ focusFollowsLastInput: true, }); focusFirstRef.current = focusFirst; + const focusMenu = useCallback( + () => listRef.current?.focus({preventScroll: true}), + [listRef], + ); + useCommittedRefInto(focusMenuRef, focusMenu); // Join the shared stack so an Escape press dismisses exactly one top-most // surface. BottomSheet owns its own dismissal path. @@ -537,44 +619,37 @@ export function ContextMenu({ ), }); - // Dismiss on any click outside the menu. We use popover="manual" (not - // "auto") because the native light-dismiss treats the mouseup from the - // opening right-click as a dismiss event. Handling it ourselves via - // mousedown avoids that race. A touch's compatibility mousedown for the - // press that opened the menu (sent mid-hold by iOS, or as a long press - // lifts by Chromium) belongs to that press's gesture, so it is not read as - // a press outside; any later press is a new gesture and closes as before. - useEffect(() => { - if (!isOpen || usesBottomSheet) { + // The menu is a manual popover: native light dismiss would read the mouseup + // of the opening right-click as a press outside. So one watch closes it. A + // mouse or a pen closes it at the press. Under the touch model, a touch + // closes it as it begins to pan, or at its lift, and the page stays free to + // scroll. Otherwise a touch closes it at its compatibility mousedown. The + // press that opened the menu keeps it open. + const watchOutside = useCallback(() => { + const trigger = triggerRef.current; + if (trigger == null) { return; } - // Inside a shadow root, even a closed or nested one, the document sees a - // press on the menu as a press on an outer shadow host, so the menu's own - // tree judges its presses first and the document skips those. - const tree = listRef.current?.getRootNode(); - const shadow = tree instanceof ShadowRoot ? tree : null; - const judged = new WeakSet(); - const handleClickOutside = (e: Event) => { - const menu = listRef.current; - if (judged.has(e)) { - return; - } - judged.add(e); - if (currentGesture() === openingGestureRef.current) { - return; - } - if (menu && !menu.contains(e.target as Node)) { - noteOutsideDismissal(menu.ownerDocument); - closeMenu(); - } - }; - document.addEventListener('mousedown', handleClickOutside); - shadow?.addEventListener('mousedown', handleClickOutside); - return () => { - document.removeEventListener('mousedown', handleClickOutside); - shadow?.removeEventListener('mousedown', handleClickOutside); - }; - }, [isOpen, closeMenu, listRef, usesBottomSheet]); + // The menu mounts after its first show, so each press reads it then. It + // renders in the trigger's own root, which may be another window's. + const root = trigger.getRootNode(); + outsidePress.start( + trigger, + path => listRef.current != null && path.includes(listRef.current), + () => { + if (currentGesture() !== openingGestureRef.current) { + closeMenu(); + } + }, + { + pointerTypes: touchModes ? ['touch'] : [], + closesOnPan: touchModes, + pressTypes: touchModes ? ['mouse', 'pen'] : ['mouse', 'pen', 'touch'], + root: shadowHostOf(root) != null ? root : null, + }, + ); + }, [closeMenu, listRef, outsidePress, touchModes]); + useCommittedRefInto(watchOutsideRef, watchOutside); const listKeyDown = useCallback( (e: React.KeyboardEvent) => { @@ -639,7 +714,15 @@ export function ContextMenu({ // what makes the menu context-relative: it scrolls with the content and the // browser auto-flips it against the viewport edges via CSS anchor positioning. const openAtLocalPoint = useCallback( - (localX: number, localY: number, focusEl: HTMLElement | null) => { + ( + localX: number, + localY: number, + focusEl: HTMLElement | null, + // A touch open focuses the menu itself: UIKit lights no row until the + // finger moves onto one. Pointer and keyboard opens focus the first + // item (APG menu pattern); arrow keys reach the items from the menu. + focusTarget: 'first' | 'menu' = 'first', + ) => { const rect = getAnchorBaseRect(); const x = rect ? keepAnchorInside(localX, rect.width) : localX; const y = rect ? keepAnchorInside(localY, rect.height) : localY; @@ -661,13 +744,38 @@ export function ContextMenu({ // A first open mounts the layer, and the show runs from the popover // element's callback ref as it attaches, in the same commit, before // the browser paints; a later one shows at once. - focusOnShowRef.current = true; + focusOnShowRef.current = focusTarget; layer.show(); } }, [getAnchorBaseRect, layer, updateOpenState, usesBottomSheet], ); + // The hold's commit: the menu shows at its moment or at the lift, so its + // layer mounts now, closed, and the show only reveals it. + const prepareMenu = useCallback(() => { + if (!usesBottomSheet) { + layer.prepare(); + } + }, [layer, usesBottomSheet]); + + // A client point in the cursor anchor's coordinates: measured from its + // containing block, as `openAtLocalPoint` reads them. It stays inside that + // box. + const toTriggerLocal = useCallback( + (point: {x: number; y: number}): {x: number; y: number} => { + const rect = getAnchorBaseRect(); + if (rect == null) { + return point; + } + return { + x: Math.min(Math.max(point.x - rect.left, 0), rect.width), + y: Math.min(Math.max(point.y - rect.top, 0), rect.height), + }; + }, + [getAnchorBaseRect], + ); + const handleContextMenu = useCallback( (e: React.MouseEvent) => { if (isDisabled) { @@ -706,19 +814,34 @@ export function ContextMenu({ [isDisabled, openAtLocalPoint, getAnchorBaseRect], ); - // Touch long-press invocation (menus-8). iOS Safari never synthesizes a - // `contextmenu` event on long-press, so a context menu is otherwise - // unreachable on touch. Open the menu at the touch point once the press is - // held long enough (see useLongPress for timer/move-cancel/cleanup logic). - // The hook also returns the imperative start/moveTo/cancel API the menu press - // model drives; only its four touch handlers belong on the trigger element. + // Touch invocation. Under the touch model, the touch layer runs UIKit's long + // press and asks for the menu here, at the client point where the finger + // landed. + const openFromFinger = useCallback( + (point: {x: number; y: number}) => { + const local = toTriggerLocal(point); + // The finger is still down: its lift belongs to the press that opened + // the menu, so it does not close it. + openingGestureRef.current = currentGesture(); + openAtLocalPoint(local.x, local.y, triggerRef.current, 'menu'); + }, + [openAtLocalPoint, toTriggerLocal], + ); + + // Today's long press for a finger outside the touch model: under a fine + // primary pointer, or with `presentation="popover"`, the way back. Safari on + // iOS never sends a `contextmenu` event for a long press. So the menu opens + // at the touch point once the finger is held for 500 ms. The useLongPress + // hook owns the timer, the move cancel and the cleanup. Under the touch + // model, the touch layer's recognizer owns the finger instead. const { onTouchStart: handleLongPressTouchStart, onTouchMove: handleLongPressTouchMove, onTouchEnd: handleLongPressTouchEnd, onTouchCancel: handleLongPressTouchCancel, } = useLongPress({ - disabled: isDisabled, + // After a failed touch-layer load, a finger gets today's 500 ms long press. + disabled: isDisabled || (touchModes && !hasTouchLayerFailed), onLongPress: useCallback( (point: {x: number; y: number}) => { const rect = getAnchorBaseRect(); @@ -734,26 +857,50 @@ export function ContextMenu({ [openAtLocalPoint, getAnchorBaseRect], ), }); - - // ContextMenu owns invocation and long-press cleanup. Consumer handlers are - // notified too, but preventing their default does not cancel component-owned - // behavior that the public API does not promise as cancelable. - const handleTriggerContextMenu = useCallback( - (event: React.MouseEvent) => { - handleContextMenu(event); - onContextMenuProp?.(event); - }, - [handleContextMenu, onContextMenuProp], - ); const handleTriggerTouchStart = useCallback( (event: React.TouchEvent) => { handleLongPressTouchStart(event); + if (touchModes && !isDisabled && TouchLayer == null) { + if (hasTouchLayerFailed) { + // After a failed load, a touch is the intent that loads it again. + // The trigger keeps no late touch, so the long press and the + // browser's own menu open the menu meanwhile. + lateTouchRef.current = null; + retryContextMenuTouchLayer(); + } else { + // Kept while the touch layer loads: one finger, until it lifts. + lateTouchRef.current = + event.touches.length === 1 + ? { + touchStart: event.nativeEvent, + pointerId: touchPointerIdRef.current, + } + : null; + } + } onTouchStartProp?.(event); }, - [handleLongPressTouchStart, onTouchStartProp], + [ + handleLongPressTouchStart, + onTouchStartProp, + touchModes, + isDisabled, + TouchLayer, + hasTouchLayerFailed, + ], ); const handleTriggerTouchMove = useCallback( (event: React.TouchEvent) => { + const late = lateTouchRef.current; + if ( + late != null && + Array.from(event.nativeEvent.changedTouches).some(touch => + driftsPastTolerance(late.touchStart, touch, touch.identifier), + ) + ) { + // A finger that drifts too far before the layer loads gets no menu. + lateTouchRef.current = null; + } handleLongPressTouchMove(event); onTouchMoveProp?.(event); }, @@ -761,6 +908,8 @@ export function ContextMenu({ ); const handleTriggerTouchEnd = useCallback( (event: React.TouchEvent) => { + lateTouchRef.current = null; + touchPointerIdRef.current = null; handleLongPressTouchEnd(event); onTouchEndProp?.(event); }, @@ -768,11 +917,66 @@ export function ContextMenu({ ); const handleTriggerTouchCancel = useCallback( (event: React.TouchEvent) => { + lateTouchRef.current = null; + touchPointerIdRef.current = null; handleLongPressTouchCancel(event); onTouchCancelProp?.(event); }, [handleLongPressTouchCancel, onTouchCancelProp], ); + const handleTriggerPointerDown = useCallback( + (event: React.PointerEvent) => { + if (event.pointerType === 'touch' && event.isPrimary) { + touchPointerIdRef.current = event.pointerId; + // A finger whose pointerdown follows its touchstart. + const late = lateTouchRef.current; + if (late != null && late.pointerId == null) { + lateTouchRef.current = {...late, pointerId: event.pointerId}; + } + } + onPointerDownProp?.(event); + }, + [onPointerDownProp], + ); + const handleTriggerPointerMove = useCallback( + (event: React.PointerEvent) => { + const late = lateTouchRef.current; + // Before the touch layer loads, Chromium sends a small drift's + // pointermove but not its touchmove. + if ( + late != null && + event.pointerType === 'touch' && + event.isPrimary && + driftsPastTolerance(late.touchStart, event) + ) { + lateTouchRef.current = null; + } + onPointerMoveProp?.(event); + }, + [onPointerMoveProp], + ); + + // ContextMenu owns invocation. Consumer handlers are notified too, but + // preventing their default does not cancel component-owned behavior that + // the public API does not promise as cancelable. + const handleTriggerContextMenu = useCallback( + (event: React.MouseEvent) => { + if ( + touchHandleRef.current?.isTracking() === true || + (lateTouchRef.current != null && !hasTouchLayerFailed) + ) { + // The browser's own long-press menu (Android Chrome) for a finger the + // recognizer is timing, or will time once the touch layer loads: the + // recognizer decides, not this event. After a failed load, a finger + // kept during that load gets the browser's menu. + event.preventDefault(); + } else { + handleContextMenu(event); + } + onContextMenuProp?.(event); + }, + [handleContextMenu, onContextMenuProp, hasTouchLayerFailed], + ); const popoverXstyle = menuWidth ? styles.popoverCustomWidth(menuWidth) @@ -918,6 +1122,8 @@ export function ContextMenu({ onTouchMove={handleTriggerTouchMove} onTouchEnd={handleTriggerTouchEnd} onTouchCancel={handleTriggerTouchCancel} + onPointerMove={handleTriggerPointerMove} + onPointerDown={handleTriggerPointerDown} data-testid={testId} {...stylex.props( styles.trigger, @@ -939,6 +1145,16 @@ export function ContextMenu({ })} /> + {TouchLayer != null ? ( + + ) : null} {usesBottomSheet ? ( ; + /** Receives the layer's handle as it mounts, and null as it unmounts. */ + ref?: Ref; + /** Open the menu at a client point (where the finger landed). */ + onOpen: (point: {x: number; y: number}) => void; + /** + * The hold committed: the menu shows at its moment or at the lift, so its + * content can mount now, hidden. + */ + onCommit?: () => void; + /** The press ended with no menu: what mounted at the commit can go. */ + onCancel?: () => void; + /** + * A finger that landed before this layer loaded and is still down, else + * null. Read once, as the layer mounts. + */ + takeLateTouch?: () => LateTouch | null; +} + +/** + * UIContextMenuInteraction's long press. iOS Safari never fires `contextmenu` + * for a held finger. So the trigger runs its own recognizer on UIKit's + * timeline, `contextMenu.press`. At the commit, the haptic plays and the + * recognizer claims the finger. The page stops scrolling under it, and its + * lift sends no click and no compatibility mouse events. The menu opens where + * the finger landed: at `menuDisplayMs` if it is still down, or at the lift. + * Before the commit, a lift, a second finger or a scroll gets no menu. So + * does a drift past the tolerance before the menu shows. A finger that landed + * before the layer loaded starts its hold as the layer mounts. + */ +export function ContextMenuTouchLayer({ + triggerRef, + ref, + onOpen, + onCommit, + onCancel, + takeLateTouch, +}: ContextMenuTouchLayerProps): null { + const onCancelRef = useCommittedRef(onCancel); + const hasPressOpenedRef = useRef(false); + + // The gesture hook follows the element behind the ref, so a `triggerAs` + // swap moves the recognizer to the new node. + const recognizer = useGestureRecognizer( + triggerRef, + () => { + const recognizer = new ContextMenuPressRecognizer(); + // Its target-action listeners never hear `failed`, so a press that ends + // with no menu releases what the commit mounted from here. + recognizer.addTransitionListener((_press, _from, to) => { + if (to === 'failed' || to === 'cancelled') { + onCancelRef.current?.(); + } + }); + return recognizer; + }, + press => { + const open = () => { + hasPressOpenedRef.current = true; + // eslint-disable-next-line @eslint-react/dom-no-flush-sync -- the menu shows in the task that decides it, as UIKit shows it at its moment, not a scheduled task later + flushSync(() => { + onOpen(press.press ?? press.location()); + }); + }; + switch (press.state) { + case 'began': + hasPressOpenedRef.current = false; + // The click haptic, where a vibration motor is the only haptic. + // iOS Safari can play none here: no tap lands at the commit. + playHaptic(contextMenu.commitHaptic); + // The menu shows at its moment or at the lift. Mounted now, its + // content costs that show nothing. + onCommit?.(); + break; + case 'changed': + if (press.isMenuDue && !hasPressOpenedRef.current) { + open(); + } + break; + case 'ended': + if (!hasPressOpenedRef.current) { + open(); + } + break; + case 'possible': + case 'failed': + case 'cancelled': + break; + } + }, + ); + + useImperativeHandle( + ref, + () => ({ + isTracking: () => recognizer.numberOfTouches > 0, + }), + [recognizer], + ); + + // Syncs a finger that landed before this layer loaded with the gesture + // host. It runs after the recognizer attaches, so the host begins that + // finger now and the hold starts at this mount. + useEffect(() => { + const late = takeLateTouch?.() ?? null; + const trigger = triggerRef.current; + if (late != null && trigger != null) { + getGestureHost(trigger.ownerDocument).beginLateTouches( + late.touchStart, + late.pointerId, + ); + } + }, [takeLateTouch, triggerRef]); + + return null; +} diff --git a/packages/core/src/ContextMenu/__tests__/ContextMenuLongPress.a11y.chromium.spec.ts b/packages/core/src/ContextMenu/__tests__/ContextMenuLongPress.a11y.chromium.spec.ts index d914ca03605f0..c65bb122ad7d1 100644 --- a/packages/core/src/ContextMenu/__tests__/ContextMenuLongPress.a11y.chromium.spec.ts +++ b/packages/core/src/ContextMenu/__tests__/ContextMenuLongPress.a11y.chromium.spec.ts @@ -2,10 +2,12 @@ /** * @file ContextMenuLongPress.a11y.chromium.spec.ts - * @input The `Core/ContextMenu` Default story in a built Storybook and CDP - * touch input. + * @input The `Core/ContextMenu` Default and popover-presentation touch stories + * in a built Storybook, and CDP touch input. * @output Real-engine proof that the long press that opens a context menu * does not close it as the finger lifts, and that a tap outside still does. + * Under the touch model the lift sends no click. Under today's long press + * (`presentation="popover"`) its click arrives and acts on nothing. * @position Run with `pnpm test:a11y-contract`; jsdom cannot produce the * compatibility mouse events a real browser sends after a touch. */ @@ -35,6 +37,11 @@ test.afterAll(async () => { }); const STORY = 'core-contextmenu--default'; +// A finger keeps today's long press under `presentation="popover"`. +const POPOVER_STORY = 'core-contextmenu--touch-long-press-popover'; + +/** The touch layer's own chunk, which loads after the page's first paint. */ +const TOUCH_LAYER_CHUNK = /\/ContextMenuTouchLayer-[\w-]+\.js(?:\?.*)?$/; async function touchCdp(page: Page): Promise { const cdp = await page.context().newCDPSession(page); @@ -45,61 +52,115 @@ async function touchCdp(page: Page): Promise { return cdp; } -async function triggerCenter(page: Page): Promise<{x: number; y: number}> { - const box = await page.getByText('Right-click this area').boundingBox(); +async function triggerCenter( + page: Page, + label = 'Right-click this area', +): Promise<{x: number; y: number}> { + const box = await page.getByText(label).boundingBox(); if (box == null) { throw new Error('the trigger area has no rendered bounds'); } return {x: box.x + box.width / 2, y: box.y + box.height / 2}; } -/** - * Resolves once the browser has delivered the `click` that follows a touch - * (the last of its compatibility mouse events) and two frames have run, so - * anything that event closes has closed. - */ -async function armCompatClick(page: Page): Promise { +interface InputEntry { + type: 'click' | 'touchstart'; + /** For a `touchstart`: whether a menu was open as it arrived. */ + isMenuOpen?: boolean; +} + +/** Records every `click` and `touchstart` the page gets from now on, in order. */ +async function recordInput(page: Page): Promise { await page.evaluate(() => { - const w = window as unknown as {__compatClick?: Promise}; - w.__compatClick = new Promise(resolve => { - document.addEventListener( - 'click', - () => - requestAnimationFrame(() => requestAnimationFrame(() => resolve())), - {once: true, capture: true}, - ); - }); + const entries: {type: string; isMenuOpen?: boolean}[] = []; + (window as unknown as {__input?: typeof entries}).__input = entries; + document.addEventListener( + 'click', + () => { + entries.push({type: 'click'}); + }, + {capture: true}, + ); + document.addEventListener( + 'touchstart', + () => { + entries.push({ + type: 'touchstart', + // A closed menu can stay mounted, hidden. + isMenuOpen: + document.querySelector('[role="menu"]')?.checkVisibility() ?? false, + }); + }, + {capture: true}, + ); }); } -async function compatClickDelivered(page: Page): Promise { - await page.evaluate( +async function recordedInput(page: Page): Promise { + return page.evaluate( + () => (window as unknown as {__input?: InputEntry[]}).__input ?? [], + ); +} + +const nextFrame = async (page: Page) => + page.evaluate( async () => - (window as unknown as {__compatClick?: Promise}).__compatClick, + new Promise(resolve => requestAnimationFrame(() => resolve())), ); + +/** + * Waits for the touch layer: its chunk's response, the module itself, then two + * frames for the layer to mount. A finger that lands sooner starts its hold + * only at that mount, so the menu would open on the load's time. + */ +async function waitForTouchLayer( + page: Page, + chunk: ReturnType, +): Promise { + const url = (await chunk).url(); + await page.evaluate(async layerUrl => { + await import(layerUrl); + await new Promise(resolve => { + requestAnimationFrame(() => requestAnimationFrame(() => resolve())); + }); + }, url); } -test('the long press that opens the menu leaves it open as the finger lifts', async ({ - page, -}) => { - await page.goto(`${storybook.origin}/iframe.html?id=${STORY}&viewMode=story`); +/** + * Holds a finger on the trigger until the menu opens, lifts it, waits one + * frame, then taps outside. Returns the input recorded from the lift on: the + * outside tap's `touchstart` is the later event that bounds the lift's click. + */ +async function holdLiftThenTapOutside( + page: Page, + story: string, + label?: string, +): Promise { + // Touch emulation makes the primary pointer coarse from the first paint. const cdp = await touchCdp(page); - const center = await triggerCenter(page); + // The popover story keeps today's long press, so its touch layer never + // loads. + const touchLayer = + story === STORY + ? page.waitForResponse(response => TOUCH_LAYER_CHUNK.test(response.url())) + : null; + await page.goto(`${storybook.origin}/iframe.html?id=${story}&viewMode=story`); + if (touchLayer != null) { + await waitForTouchLayer(page, touchLayer); + } + const center = await triggerCenter(page, label); await cdp.send('Input.dispatchTouchEvent', { type: 'touchStart', touchPoints: [{x: center.x, y: center.y, id: 1}], }); const menu = page.getByRole('menu'); await expect(menu).toBeVisible({timeout: 2000}); - await armCompatClick(page); + await recordInput(page); await cdp.send('Input.dispatchTouchEvent', { type: 'touchEnd', touchPoints: [], }); - await compatClickDelivered(page); - await expect(menu).toBeVisible(); - - // A tap outside still closes it. + await nextFrame(page); await cdp.send('Input.dispatchTouchEvent', { type: 'touchStart', touchPoints: [{x: 5, y: 5, id: 2}], @@ -108,7 +169,40 @@ test('the long press that opens the menu leaves it open as the finger lifts', as type: 'touchEnd', touchPoints: [], }); + // A tap outside still closes it. await expect(menu).toBeHidden(); + return recordedInput(page); +} + +/** The clicks before the outside tap, and whether the menu was open at it. */ +function beforeOutsideTap(entries: InputEntry[]) { + const tap = entries.findIndex(entry => entry.type === 'touchstart'); + expect(tap).toBeGreaterThanOrEqual(0); + return { + clicks: entries.slice(0, tap).filter(entry => entry.type === 'click') + .length, + isMenuOpen: entries[tap].isMenuOpen, + }; +} + +test('under the touch model, the long press that opens the menu leaves it open as the finger lifts, and the lift sends no click', async ({ + page, +}) => { + const entries = await holdLiftThenTapOutside(page, STORY); + expect(beforeOutsideTap(entries)).toEqual({clicks: 0, isMenuOpen: true}); +}); + +// The positive control: the same steps see the click that follows today's +// long press, so the check above can fail. +test('with presentation="popover", the click that follows the long press arrives before the outside tap and leaves the menu open', async ({ + page, +}) => { + const entries = await holdLiftThenTapOutside( + page, + POPOVER_STORY, + 'Hold for actions', + ); + expect(beforeOutsideTap(entries)).toEqual({clicks: 1, isMenuOpen: true}); }); test('a mouse press outside closes a right-click menu', async ({page}) => { diff --git a/packages/core/src/ContextMenu/__tests__/ContextMenuLongPress.interaction.browser.spec.ts b/packages/core/src/ContextMenu/__tests__/ContextMenuLongPress.interaction.browser.spec.ts new file mode 100644 index 0000000000000..a8da9355af6ba --- /dev/null +++ b/packages/core/src/ContextMenu/__tests__/ContextMenuLongPress.interaction.browser.spec.ts @@ -0,0 +1,868 @@ +// Copyright (c) Meta Platforms, Inc. and affiliates. + +/** + * @file ContextMenuLongPress.interaction.browser.spec.ts + * @input The built "Touch / long press" ContextMenu story, real touch input, + * the interaction harness, the context-menu constants and UIKit's frames + * @output Interaction and animation proofs for a context menu that a held + * finger opens on UIKit's timeline. They cover the menu's moments, on + * time and behind a blocked main thread. They also cover the page under + * the finger, a pan outside and a storyboard of the press + * @position Interaction specs of packages/core/src/ContextMenu; Chromium's + * finger stands for Android's engine, and WebKit's for iOS + */ + +import { + expect, + test, + type Locator, + type Page, +} from '@astryxdesign/a11y-spec/playwright'; +import { + blockMainThread, + drag, + FRAME_STARVATION_MS, + FrameStarvationError, + installInputLog, + openStory, + readInputLog, + tap, + touchDriver, + withStorybook, + type TouchDriver, +} from '@astryxdesign/interaction-harness'; +import {contextMenu} from '../../motion/uikit/contextMenu'; + +const storybook = withStorybook(test); +const {menuDisplayMs} = contextMenu.press; +interface TouchStory { + driver: TouchDriver; + trigger: Locator; + center: {x: number; y: number}; +} + +/** The touch story under the engine's own finger (a coarse pointer). */ +async function openTouchStory( + page: Page, + story = 'core-contextmenu--touch-long-press', + {waitsForTouchLayer = true}: {waitsForTouchLayer?: boolean} = {}, +): Promise { + const touchLayerChunk = waitsForTouchLayer ? watchTouchLayer(page) : null; + await installInputLog(page); + // Note when the menu is asked to show, on the page clock (no per-frame + // work: rendering proofs share this page). + await page.addInitScript(() => { + const w = window as unknown as { + __menuShownAt?: number | null; + __menuShownTimerAt?: number | null; + }; + w.__menuShownAt = null; + w.__menuShownTimerAt = null; + // When the timer task that runs now started. The hold's moments come from + // the gesture arena's timers. The menu commits in the task that decides + // it, so its show runs inside that timer task. + let timerAt: number | null = null; + const setTimer = window.setTimeout; + window.setTimeout = (( + handler: TimerHandler, + timeout?: number, + ...args: unknown[] + ) => + setTimer( + (...callArgs: unknown[]) => { + const outer = timerAt; + timerAt = performance.now(); + try { + if (typeof handler === 'function') { + handler(...callArgs); + } + } finally { + timerAt = outer; + } + }, + timeout, + ...args, + )) as typeof window.setTimeout; + const show = HTMLElement.prototype.showPopover; + HTMLElement.prototype.showPopover = function ( + this: HTMLElement, + ...args: Parameters + ) { + // Only a popover that holds the menu (Storybook shows its own). + if ( + this.matches('[role="menu"]') || + this.querySelector('[role="menu"]') != null + ) { + // Only the first show counts, so a later one cannot stand in for it. + if (w.__menuShownAt == null) { + w.__menuShownAt = performance.now(); + w.__menuShownTimerAt = timerAt; + } + } + return show.apply(this, args); + }; + }); + await openStory(page, storybook(), story); + if (touchLayerChunk != null) { + await waitForTouchLayer(page, touchLayerChunk); + } + const driver = await touchDriver(page); + const trigger = page.getByTestId('touch-context-menu'); + const box = await trigger.boundingBox(); + if (box == null) { + throw new Error('no trigger'); + } + return { + driver, + trigger, + center: {x: box.x + box.width / 2, y: box.y + box.height / 2}, + }; +} + +/** When the timer task that showed the menu started, or null outside one. */ +const menuShownTimerAt = async (page: Page) => + page.evaluate( + () => + (window as unknown as {__menuShownTimerAt?: number | null}) + .__menuShownTimerAt ?? null, + ); + +const menuShownAt = async (page: Page) => + page.evaluate( + () => + (window as unknown as {__menuShownAt?: number | null}).__menuShownAt ?? + null, + ); + +/** The page-clock timestamp of the last `type` event. */ +async function lastInput( + page: Page, + type: 'touchstart' | 'touchend', +): Promise { + const log = await readInputLog(page); + const record = log.filter(entry => entry.type === type).at(-1); + if (record == null) { + throw new Error(`no ${type} reached the page`); + } + return record.timeStamp; +} + +const touchStartedAt = async (page: Page) => lastInput(page, 'touchstart'); + +/** A finger held still for `ms`, then lifted. */ +const hold = (at: {x: number; y: number}, ms: number) => tap(at, {holdMs: ms}); + +/** One frame at 60 Hz, ms. */ +const FRAME_MS = 1000 / 60; + +/** Logs when each frame's callbacks run, on the page clock, until read. */ +async function startFrameLog(page: Page) { + await page.evaluate(() => { + const w = window as unknown as {__frameLog?: number[]}; + const log: number[] = []; + w.__frameLog = log; + const tick = () => { + log.push(performance.now()); + if (w.__frameLog === log) { + requestAnimationFrame(tick); + } + }; + requestAnimationFrame(tick); + }); +} + +/** Stops the frame log and reads it. */ +async function readFrameLog(page: Page): Promise { + return page.evaluate(() => { + const w = window as unknown as {__frameLog?: number[]}; + const log = w.__frameLog ?? []; + w.__frameLog = undefined; + return log; + }); +} + +/** + * The timer task that decides the menu starts within a frame of its due + * time. A later start fails by name when the page was starved of frames. + * Then a gap over `FRAME_STARVATION_MS` held the due time, and the task ran + * within two frames of its end. Any other late start fails bare, because + * something on the page held the timer while frames ran. + */ +function expectDecidedOnTime( + frames: ReadonlyArray, + dueAt: number, + startedAt: number, +) { + const lateMs = startedAt - dueAt; + if (lateMs <= FRAME_MS) { + return; + } + let longestGapMs = 0; + for (let i = 1; i < frames.length; i++) { + const holdsDueTime = frames[i - 1] <= dueAt + FRAME_MS && frames[i] > dueAt; + // After a long task the browser may draw a frame before the late timer. + const ranAfterIt = startedAt - frames[i] <= 2 * FRAME_MS; + if (holdsDueTime && ranAfterIt) { + longestGapMs = Math.max(longestGapMs, frames[i] - frames[i - 1]); + } + } + if (longestGapMs > FRAME_STARVATION_MS) { + throw new FrameStarvationError({ + during: `the menu's timer task was due, and it started ${lateMs.toFixed(1)} ms late`, + frames: frames.filter(t => t > dueAt && t < startedAt).length, + min: Math.max(1, Math.floor(lateMs / FRAME_MS)), + longestGapMs, + }); + } + expect( + lateMs, + 'the timer task that decides the menu started late while frames ran', + ).toBeLessThanOrEqual(FRAME_MS); +} + +test('a finger still down gets the menu at 735 ms (iOS 26.2), not before', async ({ + page, +}) => { + const {driver, center} = await openTouchStory(page); + await startFrameLog(page); + await driver.play(hold(center, menuDisplayMs + 200)); + const frames = await readFrameLog(page); + const start = await touchStartedAt(page); + const shown = await menuShownAt(page); + const decided = await menuShownTimerAt(page); + expect(shown, 'the menu never showed').not.toBeNull(); + // The menu commits in the timer task that decides it. That task runs at + // the deadline, which counts from the touch's own timestamp. + expect( + decided, + 'the menu showed after the task that decided it', + ).not.toBeNull(); + expect((decided as number) - start).toBeGreaterThanOrEqual(menuDisplayMs - 1); + expectDecidedOnTime(frames, start + menuDisplayMs, decided as number); + const after = (shown as number) - start; + // The timer runs at its deadline, give or take a task. + expect(after).toBeGreaterThanOrEqual(menuDisplayMs); + expect(after).toBeLessThan(menuDisplayMs + 20); + await expect(page.getByRole('menu', {name: 'Photo actions'})).toBeVisible(); +}); + +test('a finger held on a Table’s sortable header gets the menu where it landed', async ({ + page, +}) => { + // The header leaves its trigger unpositioned, so the cell holds the cursor + // anchor. A finger's point is measured from that cell, as a pointer's is. + const touchLayerChunk = watchTouchLayer(page); + await openStory( + page, + storybook(), + 'core-tablecolumnresize--with-sortable-columns', + ); + await waitForTouchLayer(page, touchLayerChunk); + const driver = await touchDriver(page); + const header = page.getByRole('columnheader', {name: /Name/}); + const box = await header.boundingBox(); + if (box == null) { + throw new Error('no Name header'); + } + const point = { + x: Math.round(box.x + box.width / 2), + y: Math.round(box.y + box.height / 2), + }; + await driver.play(hold(point, menuDisplayMs + 200)); + await expect(page.getByRole('menu')).toBeVisible(); + const anchor = await page + .locator('span[aria-hidden="true"][style*="anchor-name"]') + .boundingBox(); + // The menu hangs from a 1px anchor placed at the finger. + expect(anchor?.x).toBeCloseTo(point.x, 0); + expect(anchor?.y).toBeCloseTo(point.y, 0); +}); + +/** The touch layer's own chunk, which loads after the page's first paint. */ +const TOUCH_LAYER_CHUNK = /\/ContextMenuTouchLayer-[\w-]+\.js(?:\?.*)?$/; + +type ChunkResponse = Awaited>; + +/** The touch layer chunk's response, watched from before the story opens. */ +async function watchTouchLayer(page: Page): Promise { + return page.waitForResponse(response => + TOUCH_LAYER_CHUNK.test(response.url()), + ); +} + +/** + * Waits for the touch layer, which loads after the page's first paint. It + * waits for the chunk's response, then for the module itself, then two frames + * for the layer to mount. An import of the same URL resolves once it and its + * imports have run. A finger that lands sooner starts its hold only at that + * mount. + */ +async function waitForTouchLayer( + page: Page, + chunk: Promise, +): Promise { + const url = (await chunk).url(); + await page.evaluate(async layerUrl => { + await import(layerUrl); + await new Promise(resolve => { + requestAnimationFrame(() => requestAnimationFrame(() => resolve())); + }); + }, url); +} + +/** + * Holds back the touch layer's chunk. The call it returns releases the chunk + * and returns when, on the page clock. + */ +async function holdTouchLayer(page: Page): Promise<() => Promise> { + let release = () => {}; + const held = new Promise(resolve => { + release = resolve; + }); + await page.route(TOUCH_LAYER_CHUNK, async route => { + await held; + await route.continue(); + }); + return async () => { + const releasedAt = await page.evaluate(() => performance.now()); + release(); + return releasedAt; + }; +} + +/** How long a finger stays down before the held chunk is released, ms. */ +const BEFORE_LOAD_MS = 300; + +test('a finger that lands before the touch layer loads starts the hold once it loads: the menu shows 735 ms after the load', async ({ + page, +}) => { + const releaseLayer = await holdTouchLayer(page); + const {driver, center} = await openTouchStory(page, undefined, { + waitsForTouchLayer: false, + }); + const finger = await driver.press(center); + const start = await touchStartedAt(page); + await page.waitForFunction( + dueAt => performance.now() > dueAt, + start + BEFORE_LOAD_MS, + ); + const released = await releaseLayer(); + await expect + .poll(async () => menuShownAt(page), {timeout: 5000}) + .not.toBeNull(); + const shown = (await menuShownAt(page)) as number; + expect( + shown - start, + 'the menu showed before its touch layer loaded', + ).toBeGreaterThanOrEqual(BEFORE_LOAD_MS + menuDisplayMs); + expect(shown - released).toBeGreaterThanOrEqual(menuDisplayMs); + // The chunk, its imports and the layer's mount fit in this. + expect(shown - released).toBeLessThan(menuDisplayMs + 500); + await finger.lift(); + await expect(page.getByRole('menu', {name: 'Photo actions'})).toBeVisible(); +}); + +test('a finger that lifts before the touch layer loads makes a plain tap: one click, and no menu once the layer loads', async ({ + page, +}) => { + const releaseLayer = await holdTouchLayer(page); + const {driver, center} = await openTouchStory(page, undefined, { + waitsForTouchLayer: false, + }); + test.skip(!driver.drivesNativeGestures, CLICK_FROM_SCRIPT_SKIP); + const clicks = await countTriggerClicks(page); + await driver.play(hold(center, 250)); + await expect.poll(clicks).toBe(1); + const released = await releaseLayer(); + await page.waitForFunction( + dueAt => performance.now() > dueAt, + released + menuDisplayMs + 300, + ); + expect(await menuShownAt(page)).toBeNull(); + await expect(page.getByRole('menu', {name: 'Photo actions'})).toBeHidden(); + expect(await clicks()).toBe(1); +}); + +test('a finger that drifts past the tolerance before the touch layer loads gets no menu once it loads', async ({ + page, +}) => { + const releaseLayer = await holdTouchLayer(page); + const {driver, center} = await openTouchStory(page, undefined, { + waitsForTouchLayer: false, + }); + const finger = await driver.press(center); + // Past the tolerance on one axis, then back to where it landed. Before the + // layer loads, Chromium sends this drift as a pointermove only. + await finger.move({ + x: center.x + contextMenu.press.allowableMovement + 1, + y: center.y, + }); + await finger.move(center); + const released = await releaseLayer(); + await page.waitForFunction( + dueAt => performance.now() > dueAt, + released + menuDisplayMs + 300, + ); + expect(await menuShownAt(page)).toBeNull(); + await finger.lift(); + await expect(page.getByRole('menu', {name: 'Photo actions'})).toBeHidden(); +}); + +test('a right click opens the menu at once while the touch layer has not loaded', async ({ + page, +}) => { + await holdTouchLayer(page); + const {trigger} = await openTouchStory(page, undefined, { + waitsForTouchLayer: false, + }); + await trigger.click({button: 'right'}); + await expect(page.getByRole('menu', {name: 'Photo actions'})).toBeVisible(); +}); + +/** The gesture arena counts a move as late when it reaches the page this long after its own time. */ +const LATE_INPUT_MS = 33; +/** How long the gesture arena holds the menu's moment after a late move that reached the page just before it. */ +const LATE_INPUT_WAIT_MS = 50; + +/** A hold that shifts 3 px once, as the page read it, on the page clock. */ +interface ShiftedHold { + start: number; + /** The shift's own time and when the page got it. */ + shift: [number, number]; + frames: number[]; + shown: number | null; + decided: number | null; +} + +/** + * A finger held still that shifts 3 px once, then lifts at 1000 ms. In + * Chromium the page reads the timestamp the protocol hands over, so the shift + * leaves at `sentMs` stamped `stampMs`, and the case sets how late the page + * gets it. WebKit stamps a touch as it arrives, so there the shift leaves at + * `sentMs`. + */ +async function holdWithShift( + page: Page, + browserName: string, + {sentMs, stampMs}: {sentMs: number; stampMs: number}, +): Promise { + await page.addInitScript(() => { + const w = window as unknown as {__shifts: [number, number][]}; + w.__shifts = []; + window.addEventListener( + 'pointermove', + event => { + w.__shifts.push([event.timeStamp, performance.now()]); + }, + {capture: true, passive: true}, + ); + }); + const {driver, center} = await openTouchStory(page); + await startFrameLog(page); + if (browserName === 'chromium') { + const cdp = await page.context().newCDPSession(page); + const origin = Date.now(); + const at = async (ms: number) => + new Promise(resolve => { + setTimeout(resolve, Math.max(0, origin + ms - Date.now())); + }); + const touch = async ( + type: 'touchStart' | 'touchMove' | 'touchEnd', + ms: number, + dx: number | null, + ) => + cdp.send('Input.dispatchTouchEvent', { + type, + touchPoints: dx == null ? [] : [{x: center.x + dx, y: center.y}], + timestamp: (origin + ms) / 1000, + }); + await touch('touchStart', 0, 0); + await at(sentMs); + await touch('touchMove', stampMs, 3); + await at(1000); + await touch('touchEnd', 1000, null); + } else { + await driver.play( + drag( + center, + {x: center.x + 3, y: center.y}, + {holdMs: sentMs - 1, durationMs: 1, restMs: 1000 - sentMs}, + ), + ); + } + const frames = await readFrameLog(page); + const start = await touchStartedAt(page); + const shifts = await page.evaluate( + () => (window as unknown as {__shifts: [number, number][]}).__shifts, + ); + expect(shifts.length, 'the shift reached the page').toBeGreaterThan(0); + return { + start, + shift: shifts[shifts.length - 1], + frames, + shown: await menuShownAt(page), + decided: await menuShownTimerAt(page), + }; +} + +/** The shift reached the page before the menu's moment, inside the arena's wait. */ +function expectShiftInsideWait( + [, receivedAt]: [number, number], + moment: number, +) { + expect( + receivedAt, + 'the shift reached the page before the menu’s moment', + ).toBeLessThan(moment); + expect( + moment - receivedAt, + 'the shift reached the page inside the arena’s wait before the moment', + ).toBeLessThan(LATE_INPUT_WAIT_MS); +} + +test('a finger that shifts slightly just before 735 ms gets the menu at 735 ms when its move reaches the page on time (AST-094 FR12)', async ({ + page, + browserName, +}) => { + // A phone gets a move within a frame. The protocol's own path can take two + // frames on a test machine, so the shift leaves 25 ms ahead of its stamp. + // A faster path brings it before its stamp: the press counts that negative + // lag as on time, as any lag up to 33 ms. Leaving at 688 ms, it reaches the + // page less than 50 ms before the moment, and before it on any path under + // 47 ms. + const run = await holdWithShift(page, browserName, { + sentMs: 688, + stampMs: 713, + }); + const moment = run.start + menuDisplayMs; + expectShiftInsideWait(run.shift, moment); + expect( + run.shift[1] - run.shift[0], + 'the shift reached the page on time', + ).toBeLessThanOrEqual(LATE_INPUT_MS); + expect(run.shown, 'the menu never showed').not.toBeNull(); + // The moment's own timer task shows the menu: nothing waits. + expect( + run.decided, + 'the menu showed after the task that decided it', + ).not.toBeNull(); + expectDecidedOnTime(run.frames, moment, run.decided as number); + const after = (run.shown as number) - run.start; + expect(after).toBeGreaterThanOrEqual(menuDisplayMs); + expect(after).toBeLessThan(menuDisplayMs + 20); +}); + +test('a finger that shifts slightly just before 735 ms gets the menu 50 ms later when its move reaches the page late (AST-094 FR12)', async ({ + page, + browserName, +}) => { + test.skip( + browserName !== 'chromium', + 'a touch stamped before it is sent needs Chromium’s protocol', + ); + // The shift leaves 60 ms after its stamp, so the page gets it late. + const run = await holdWithShift(page, browserName, { + sentMs: 688, + stampMs: 628, + }); + const moment = run.start + menuDisplayMs; + expectShiftInsideWait(run.shift, moment); + expect( + run.shift[1] - run.shift[0], + 'the shift reached the page late', + ).toBeGreaterThan(LATE_INPUT_MS); + expect(run.decided, 'the menu never showed').not.toBeNull(); + expect( + (run.decided as number) - moment, + 'the menu waited for moves still coming late', + ).toBeGreaterThanOrEqual(LATE_INPUT_WAIT_MS - 1); + expect( + (run.decided as number) - moment, + 'the menu waited no longer than the arena allows', + ).toBeLessThan(LATE_INPUT_WAIT_MS + 20); + await expect(page.getByRole('menu', {name: 'Photo actions'})).toBeVisible(); +}); + +test('the menu mounts at the commit, closed and out of the accessibility tree, and shows at 735 ms', async ({ + page, +}) => { + const {driver, center} = await openTouchStory(page); + const playing = driver.play(hold(center, menuDisplayMs + 200)); + const prepared = page + .locator('[popover]') + .filter({has: page.locator('[role="menu"]')}); + // Mounted at the commit (400 ms), well before the menu's moment (735 ms). + await expect(prepared).toHaveCount(1, {timeout: 700}); + expect(await menuShownAt(page), 'the menu showed before 735 ms').toBeNull(); + expect(await prepared.evaluate(el => el.matches(':popover-open'))).toBe( + false, + ); + await expect(page.getByRole('menu', {name: 'Photo actions'})).toHaveCount(0); + await playing; + await expect(page.getByRole('menu', {name: 'Photo actions'})).toBeVisible(); +}); + +/** The story with somewhere to scroll below it, and its trigger's center. */ +async function openScrollableStory(page: Page) { + const story = await openTouchStory(page); + await page.evaluate(() => { + document.body.style.paddingBottom = '3000px'; + }); + const box = await story.trigger.boundingBox(); + if (box == null) { + throw new Error('no trigger'); + } + const center = {x: box.x + box.width / 2, y: box.y + box.height / 2}; + const top = async () => + story.trigger.evaluate( + el => (el.parentElement ?? el).getBoundingClientRect().y, + ); + return {...story, center, top}; +} + +/** WebKit makes a click only from its own tap gesture (harness README). */ +const CLICK_FROM_SCRIPT_SKIP = + 'WebKit makes a click from its own tap gesture only, not from a scripted touch'; + +/** Counts the clicks that reach the trigger from now on. */ +async function countTriggerClicks(page: Page) { + await page.evaluate(() => { + const w = window as unknown as {__triggerClicks?: number}; + w.__triggerClicks = 0; + const trigger = document.querySelector( + '[data-testid="touch-context-menu"]', + ); + document.addEventListener( + 'click', + event => { + if ( + trigger != null && + event.target instanceof Node && + trigger.contains(event.target) + ) { + w.__triggerClicks = (w.__triggerClicks ?? 0) + 1; + } + }, + true, + ); + }); + return async () => + page.evaluate( + () => + (window as unknown as {__triggerClicks?: number}).__triggerClicks ?? 0, + ); +} + +test('a finger that lifts before 400 ms makes a plain tap: one click and no menu', async ({ + page, +}) => { + const {driver, center} = await openTouchStory(page); + test.skip(!driver.drivesNativeGestures, CLICK_FROM_SCRIPT_SKIP); + const clicks = await countTriggerClicks(page); + // Past core's press onset at 150 ms: a long press that fails is still a + // tap. + await driver.play(hold(center, 250)); + const startedAt = await touchStartedAt(page); + const liftedAfterMs = (await lastInput(page, 'touchend')) - startedAt; + // The commit at 400 ms runs on the page clock. A lift that reached the page + // later makes a real long press, so the case cannot judge a tap. + if (liftedAfterMs >= contextMenu.press.commitMs) { + throw new Error( + `the lift reached the page ${liftedAfterMs.toFixed(1)} ms after the touch, past the ${contextMenu.press.commitMs} ms a tap allows`, + ); + } + await expect.poll(clicks).toBe(1); + // The menu's moment passes with no menu. + await page.waitForFunction( + dueAt => performance.now() > dueAt, + startedAt + menuDisplayMs + 100, + ); + // One task more, so a timer that is due runs before the read. + await page.evaluate( + async () => + new Promise(resolve => { + setTimeout(resolve, 0); + }), + ); + expect(await menuShownAt(page)).toBeNull(); + await expect(page.getByRole('menu', {name: 'Photo actions'})).toBeHidden(); + expect(await clicks()).toBe(1); +}); + +/** Two frames on the page: a click the lift makes has reached it by then. */ +const afterTwoFrames = async (page: Page) => + page.evaluate( + async () => + new Promise(resolve => { + requestAnimationFrame(() => requestAnimationFrame(() => resolve())); + }), + ); + +test('a slow drift past 11.5 px late in the hold cancels it: no menu and no click (AST-094 FR21)', async ({ + page, +}) => { + const {driver, center} = await openTouchStory(page); + const clicks = await countTriggerClicks(page); + // The finger rests past the commit at 400 ms, then drifts 14 px in 250 ms. + // It crosses 11.5 px at about 655 ms, before the menu's moment, and it + // lifts well after that moment. + await driver.play( + drag( + center, + {x: center.x + 14, y: center.y}, + {holdMs: 450, durationMs: 250, restMs: 400}, + ), + ); + await touchStartedAt(page); + await afterTwoFrames(page); + expect(await menuShownAt(page)).toBeNull(); + await expect(page.getByRole('menu', {name: 'Photo actions'})).toBeHidden(); + // Only Chromium makes a click from a scripted touch, so only it can show + // that none came. + if (driver.drivesNativeGestures) { + expect(await clicks()).toBe(0); + } +}); + +test('a drift from before 735 ms that reaches the page behind a block still cancels the hold: no menu (AST-094 FR16)', async ({ + page, + browserName, +}) => { + test.skip( + browserName !== 'chromium', + 'touches stamped and sent while the page is blocked need Chromium’s protocol', + ); + // Each move's own time, and when the page got it. + await page.addInitScript(() => { + const w = window as unknown as {__moves: [number, number][]}; + w.__moves = []; + window.addEventListener( + 'pointermove', + event => { + w.__moves.push([event.timeStamp, performance.now()]); + }, + {capture: true, passive: true}, + ); + }); + const {center} = await openTouchStory(page); + const cdp = await page.context().newCDPSession(page); + const start = Date.now(); + const at = async (ms: number) => + new Promise(resolve => { + setTimeout(resolve, Math.max(0, start + ms - Date.now())); + }); + const touch = async ( + type: 'touchStart' | 'touchMove' | 'touchEnd', + ms: number, + dx: number | null, + ) => + cdp.send('Input.dispatchTouchEvent', { + type, + touchPoints: dx == null ? [] : [{x: center.x + dx, y: center.y}], + timestamp: (start + ms) / 1000, + }); + await touch('touchStart', 0, 0); + // The page is blocked from 600 ms to 850 ms, past the menu's moment. The + // finger crosses 11.5 px at 700 ms, so the page gets that move after the + // block. + await at(600); + const blocking = blockMainThread(page, 250); + await at(650); + const moves = [touch('touchMove', 650, 6)]; + await at(700); + moves.push(touch('touchMove', 700, 14)); + const blocked = await blocking; + await Promise.all(moves); + await at(1150); + await touch('touchEnd', 1150, null); + await afterTwoFrames(page); + const moment = (await touchStartedAt(page)) + menuDisplayMs; + const origin = await page.evaluate(() => performance.timeOrigin); + const blockEnd = blocked.to - origin; + expect( + blocked.from - origin, + 'the block starts before the menu’s moment', + ).toBeLessThan(moment); + expect(blockEnd, 'the block ends after the menu’s moment').toBeGreaterThan( + moment, + ); + const early = ( + await page.evaluate( + () => (window as unknown as {__moves: [number, number][]}).__moves, + ) + ).filter(([time]) => time < moment); + expect( + early.length, + 'a move from before the menu’s moment reached the page', + ).toBeGreaterThan(0); + for (const [, receivedAt] of early) { + expect( + receivedAt, + 'the move reached the page after the block', + ).toBeGreaterThanOrEqual(blockEnd); + // The arena waits 50 ms for moves still queued. + expect( + receivedAt - blockEnd, + 'the move reached the page within the arena’s wait', + ).toBeLessThan(LATE_INPUT_WAIT_MS); + } + expect( + await menuShownAt(page), + 'the menu showed for a drift from before its moment', + ).toBeNull(); + await expect(page.getByRole('menu', {name: 'Photo actions'})).toBeHidden(); +}); + +test('a finger still inside 11.5 px at the menu’s moment that crosses it just after still gets the menu (AST-094 FR12)', async ({ + page, +}) => { + const {driver, center} = await openTouchStory(page); + // 14 px over 650–760 ms: 10.6 px at the last move before 735 ms, 12.7 px + // at the first move after it. + await driver.play( + drag( + center, + {x: center.x + 14, y: center.y}, + {holdMs: 650, durationMs: 110, restMs: 300}, + ), + ); + await expect(page.getByRole('menu', {name: 'Photo actions'})).toBeVisible(); +}); + +test('a new finger that pans outside the open menu closes it, and the page scrolls', async ({ + page, +}) => { + const {driver, center, top} = await openScrollableStory(page); + await driver.play(hold(center, menuDisplayMs + 50)); + const menu = page.getByRole('menu', {name: 'Photo actions'}); + await expect(menu).toBeVisible(); + const before = await top(); + // The menu opens at the finger. So the new finger lands beside the menu's + // box, at the first point below or above it with room for the pan. + const box = await menu.boundingBox(); + const viewport = page.viewportSize(); + if (box == null || viewport == null) { + throw new Error('the menu or the viewport has no box'); + } + const outside = [ + {x: center.x, y: Math.round(box.y + box.height + 40)}, + {x: center.x, y: Math.round(box.y - 40)}, + ].find(point => point.y - 130 > 0 && point.y + 10 < viewport.height); + if (outside == null) { + throw new Error('no point beside the menu has room for the pan'); + } + expect( + await page.evaluate( + ({x, y}) => document.elementFromPoint(x, y)?.closest('[role="menu"]'), + outside, + ), + ).toBeNull(); + await driver.play( + drag(outside, {x: outside.x, y: outside.y - 120}, {durationMs: 300}), + ); + await expect(page.getByRole('menu', {name: 'Photo actions'})).toBeHidden(); + // WebKit scrolls nothing from an injected touch (README: engine limits). + if (driver.drivesNativeGestures) { + expect(await top()).toBeLessThan(before); + } +}); diff --git a/packages/core/src/ContextMenu/contextMenuPress.test.ts b/packages/core/src/ContextMenu/contextMenuPress.test.ts new file mode 100644 index 0000000000000..92ee020122ee2 --- /dev/null +++ b/packages/core/src/ContextMenu/contextMenuPress.test.ts @@ -0,0 +1,391 @@ +// Copyright (c) Meta Platforms, Inc. and affiliates. + +/** + * @file contextMenuPress.test.ts + * @input vitest, the gesture arena driven by synthetic touches at explicit + * timestamps (the gesture tests' harness), ContextMenuPressRecognizer + * @output The context menu's touch timeline as a state machine. The press + * commits at UIKit's moment and not a millisecond before, at that moment + * even when the timer runs late. It fails on travel past the long-press + * tolerance, a lift, a second finger or the browser taking the touch. The + * commit claims the finger and drops its click. A press that fails leaves + * the click alone + * @position Unit tests of packages/core/src/ContextMenu/contextMenuPress.ts + */ + +import {describe, expect, it} from 'vitest'; +import {createHarness} from '../gestures/__tests__/harness'; +import {contextMenu} from '../motion/uikit/contextMenu'; +import {ContextMenuPressRecognizer} from './contextMenuPress'; + +const COMMIT = contextMenu.press.commitMs; +const DISPLAY = contextMenu.press.menuDisplayMs; + +function setup( + options: ConstructorParameters[0] = {}, +) { + const harness = createHarness(); + const press = new ContextMenuPressRecognizer({name: 'press', ...options}); + const states: string[] = []; + press.addTransitionListener((recognizer, _from, to) => { + states.push(`${to}@${recognizer.clockTime}`); + }); + return {harness, press, states}; +} + +describe('ContextMenuPressRecognizer', () => { + it('commits at UIKit’s moment (iOS 26.2: 400 ms, first 60 Hz tick 417 ms), not a millisecond before', () => { + const {harness, press, states} = setup(); + harness.finger(1).down(100, 200, 1000, {recognizers: [press]}); + harness.advance(1000 + COMMIT - 1); + expect(press.state).toBe('possible'); + harness.advance(1000 + COMMIT); + expect(press.state).toBe('began'); + expect(states).toEqual([`began@${1000 + COMMIT}`]); + expect(COMMIT).toBe(400); + }); + + it('commits at the deadline even when the main thread runs the timer late', () => { + const {harness, press, states} = setup(); + harness.finger(1).down(0, 0, 0, {recognizers: [press]}); + // Nothing ran until 900 ms (a blocked main thread). The arena waits 50 ms + // for input queued behind the block. None came, so the commit and the + // menu's moment then run, each at its own time. + harness.clock.time = 900; + harness.clock.runDue(900); + expect(states).toEqual([]); + harness.clock.runDue(950); + expect(states).toEqual([`began@${COMMIT}`, `changed@${DISPLAY}`]); + expect(press.beganAt).toBe(COMMIT); + }); + + it('claims the finger at the commit and drops the lift’s click', () => { + const {harness, press} = setup(); + const finger = harness.finger(1).down(0, 0, 0, {recognizers: [press]}); + expect(harness.claims).toEqual([]); + harness.advance(COMMIT); + expect(harness.claims).toEqual([1]); + expect(finger.up(COMMIT + 300)).toBe('suppress'); + expect(press.state).toBe('possible'); + expect(press.press).toBeNull(); + }); + + it('makes the menu due at 735 ms while the finger stays (changed, isMenuDue)', () => { + const {harness, press, states} = setup(); + harness.finger(1).down(0, 0, 0, {recognizers: [press]}); + harness.advance(DISPLAY - 1); + expect(press.isMenuDue).toBe(false); + harness.advance(DISPLAY); + expect(press.isMenuDue).toBe(true); + expect(states).toEqual([`began@${COMMIT}`, `changed@${DISPLAY}`]); + expect(DISPLAY).toBe(735); + }); + + it('ends at a lift after the commit, before the menu is due (UIKit shows the menu at the lift)', () => { + const {harness, press, states} = setup(); + const finger = harness.finger(1).down(0, 0, 0, {recognizers: [press]}); + harness.advance(COMMIT); + expect(finger.up(529)).toBe('suppress'); + harness.advance(DISPLAY + 100); + expect(states).toEqual([`began@${COMMIT}`, 'ended@529', 'possible@529']); + }); + + it('is cancelled by a drift past the tolerance after the commit, before the menu', () => { + const {harness, press, states} = setup(); + const finger = harness.finger(1).down(0, 0, 0, {recognizers: [press]}); + harness.advance(COMMIT); + finger.move(0, 5, 480); // within: still committed + finger.move(0, 30, 500); // a 30 px drag at 0.5 s + expect(states).toEqual([`began@${COMMIT}`, 'changed@480', 'cancelled@500']); + harness.advance(DISPLAY + 100); + expect(press.isMenuDue).toBe(false); + }); + + it('waits at the menu’s moment for moves that came before it but reach the page late, and a drift in them cancels', () => { + const {harness, press, states} = setup(); + const finger = harness.finger(1).down(0, 0, 0, {recognizers: [press]}); + harness.clock.runDue(COMMIT); + // The page gets a move from 450 ms only at 700 ms: it is behind. + finger.move(3, 0, 450, undefined, 700); + harness.clock.runDue(DISPLAY); + expect(press.isMenuDue).toBe(false); + // A late move that came at 600 ms, 14 px over. It reaches the page after + // the moment, and the hold ends at the time it came with. + finger.move(14, 0, 600, undefined, DISPLAY + 10); + expect(states).toEqual([`began@${COMMIT}`, 'changed@450', 'cancelled@600']); + expect(press.isMenuDue).toBe(false); + finger.up(DISPLAY + 300); + }); + + it('shows the menu for a move stamped from its moment on, even past the tolerance, and lets the finger move freely after', () => { + const {harness, press, states} = setup(); + const finger = harness.finger(1).down(0, 0, 0, {recognizers: [press]}); + harness.clock.runDue(COMMIT); + finger.move(3, 0, 450, undefined, 700); + harness.clock.runDue(DISPLAY); + expect(press.isMenuDue).toBe(false); + // Inside the tolerance at the moment, 14 px over 15 ms after it. + finger.move(14, 0, DISPLAY + 15, undefined, DISPLAY + 20); + expect(press.isMenuDue).toBe(true); + expect(states).toEqual([ + `began@${COMMIT}`, + 'changed@450', + `changed@${DISPLAY}`, + `changed@${DISPLAY + 15}`, + ]); + finger.up(DISPLAY + 300); + }); + + it('judges each coalesced sample of a late move at its own time while the menu waits', () => { + const {harness, press, states} = setup(); + const finger = harness.finger(1).down(0, 0, 0, {recognizers: [press]}); + harness.clock.runDue(COMMIT); + finger.move(3, 0, 450, undefined, 700); + harness.clock.runDue(DISPLAY); + // One late move with two samples: 13 px at 725 ms, before the moment, + // then 14 px at 740 ms. Two separate moves would end the hold at the + // first, so this one does too. + finger.move( + 14, + 0, + DISPLAY + 5, + [{x: 13, y: 0, time: DISPLAY - 10}], + DISPLAY + 20, + ); + expect(press.isMenuDue).toBe(false); + expect(states).toEqual([ + `began@${COMMIT}`, + 'changed@450', + `cancelled@${DISPLAY - 10}`, + ]); + }); + + it('shows the waiting menu for a coalesced move whose samples before the moment stay inside the tolerance', () => { + const {harness, press} = setup(); + const finger = harness.finger(1).down(0, 0, 0, {recognizers: [press]}); + harness.clock.runDue(COMMIT); + finger.move(3, 0, 450, undefined, 700); + harness.clock.runDue(DISPLAY); + expect(press.isMenuDue).toBe(false); + finger.move( + 14, + 0, + DISPLAY + 5, + [{x: 10, y: 0, time: DISPLAY - 10}], + DISPLAY + 20, + ); + expect(press.isMenuDue).toBe(true); + finger.up(DISPLAY + 300); + }); + + for (const blockedUntil of [760, 800, 900]) { + it(`judges a coalesced move from behind a block until ${blockedUntil} ms before the menu shows`, () => { + const {harness, press, states} = setup(); + const finger = harness.finger(1).down(0, 0, 0, {recognizers: [press]}); + harness.clock.runDue(COMMIT); + // On time until 640 ms. Then the page is blocked past the moment. + finger.move(3, 0, 640); + // The finger crossed 11.5 px at 650 ms. Its moves wait behind the block + // and come as one coalesced move. Its samples before the moment come + // first, in one move at the last of them. + finger.move( + 14, + 0, + blockedUntil - 5, + [ + {x: 13, y: 0, time: 650}, + {x: 14, y: 0, time: 700}, + ], + blockedUntil, + ); + expect(press.isMenuDue).toBe(false); + expect(states).toEqual([ + `began@${COMMIT}`, + 'changed@640', + 'cancelled@700', + ]); + }); + } + + it('shows a still finger’s menu after a block, once no move comes from behind it', () => { + const {harness, press} = setup(); + const finger = harness.finger(1).down(0, 0, 0, {recognizers: [press]}); + harness.clock.runDue(COMMIT); + // The moment's timer runs 65 ms late behind a block. + harness.clock.time = DISPLAY + 65; + harness.clock.runDue(DISPLAY + 65); + expect(press.isMenuDue).toBe(false); + harness.clock.runDue(DISPLAY + 115); + expect(press.isMenuDue).toBe(true); + finger.up(DISPLAY + 300); + }); + + it('shows the menu once the late moves pause for 50 ms', () => { + const {harness, press} = setup(); + const finger = harness.finger(1).down(0, 0, 0, {recognizers: [press]}); + harness.clock.runDue(COMMIT); + finger.move(3, 0, 450, undefined, 700); + harness.clock.runDue(DISPLAY); + expect(press.isMenuDue).toBe(false); + // The wait runs on the arena's clock. + harness.clock.runDue(DISPLAY + 49); + expect(press.isMenuDue).toBe(false); + harness.clock.runDue(DISPLAY + 50); + expect(press.isMenuDue).toBe(true); + finger.up(DISPLAY + 300); + }); + + it('shows the menu at its moment after a move that reached the page on time, with no wait', () => { + const {harness, press, states} = setup(); + const finger = harness.finger(1).down(0, 0, 0, {recognizers: [press]}); + harness.clock.runDue(COMMIT); + // A 3 px shift at 720 ms that the page gets at once: it is not behind. + finger.move(3, 0, 720); + harness.clock.runDue(DISPLAY); + expect(press.isMenuDue).toBe(true); + expect(states).toEqual([ + `began@${COMMIT}`, + 'changed@720', + `changed@${DISPLAY}`, + ]); + }); + + it('waits at the menu’s moment when its own timer runs late after a recent move', () => { + const {harness, press} = setup(); + const finger = harness.finger(1).down(0, 0, 0, {recognizers: [press]}); + harness.clock.runDue(COMMIT); + finger.move(3, 0, 730); + // The page is busy: the moment's timer runs 40 ms late, so later moves + // may still be queued. + harness.clock.time = DISPLAY + 40; + harness.clock.runDue(DISPLAY + 40); + expect(press.isMenuDue).toBe(false); + // No more moves came: the wait ends 50 ms after the late timer ran. + harness.clock.runDue(DISPLAY + 90); + expect(press.isMenuDue).toBe(true); + finger.up(DISPLAY + 300); + }); + + it('shows a still finger’s menu at its moment, with no wait', () => { + const {harness, press, states} = setup(); + harness.finger(1).down(0, 0, 0, {recognizers: [press]}); + harness.advance(DISPLAY); + expect(press.isMenuDue).toBe(true); + expect(states).toEqual([`began@${COMMIT}`, `changed@${DISPLAY}`]); + }); + + it('lets the finger move freely once the menu is due', () => { + const {harness, press, states} = setup(); + const finger = harness.finger(1).down(0, 0, 0, {recognizers: [press]}); + harness.advance(DISPLAY); + finger.move(0, 80, DISPLAY + 50); + finger.up(DISPLAY + 100); + expect(states).toEqual([ + `began@${COMMIT}`, + `changed@${DISPLAY}`, + `changed@${DISPLAY + 50}`, + `ended@${DISPLAY + 100}`, + `possible@${DISPLAY + 100}`, + ]); + }); + + it.each([ + [7, 7], + [8, 8], + [10, 0], + [11, 11], + [0, -11.5], + ])('still commits after a drift of (%d, %d) pt, as UIKit does', (dx, dy) => { + const {harness, press} = setup(); + harness + .finger(1) + .down(100, 100, 0, {recognizers: [press]}) + .move(100 + dx, 100 + dy, 100); + harness.advance(COMMIT); + expect(press.state).toBe('began'); + }); + + it.each([ + [12, 0], + [0, 12], + [-11.6, 0], + [0, -11.6], + ])( + 'fails on a drift of (%d, %d) pt, past the tolerance on one axis', + (dx, dy) => { + const {harness, press, states} = setup(); + harness + .finger(1) + .down(100, 100, 0, {recognizers: [press]}) + .move(100 + dx, 100 + dy, 250); + expect(press.state).toBe('failed'); + harness.advance(COMMIT); + expect(states).toEqual(['failed@250']); + }, + ); + + it('fails when the finger lifts before the commit, and lets that tap’s click through', () => { + const {harness, press, states} = setup(); + const finger = harness.finger(1).down(0, 0, 0, {recognizers: [press]}); + expect(finger.up(250)).toBe('allow'); + harness.advance(COMMIT); + expect(states).toEqual(['failed@250', 'possible@250']); + }); + + it('fails on a second finger before the commit', () => { + const {harness, press} = setup(); + harness.finger(1).down(0, 0, 0, {recognizers: [press]}); + harness.finger(2).down(50, 0, 120, {recognizers: [press]}); + expect(press.state).toBe('failed'); + }); + + it('ignores a second finger after the commit', () => { + const {harness, press} = setup(); + harness.finger(1).down(0, 0, 0, {recognizers: [press]}); + harness.advance(COMMIT); + harness.finger(2).down(50, 0, COMMIT + 20, {recognizers: [press]}); + expect(press.state).toBe('began'); + }); + + it('fails when the browser takes the finger to scroll', () => { + const {harness, press, states} = setup(); + harness + .finger(1) + .down(0, 0, 0, {recognizers: [press]}) + .takenByBrowser(90); + // The browser owns the finger now: the recognizer lets go of it at once. + expect(states).toEqual(['failed@90', 'possible@90']); + }); + + it('keeps the press while it fails, so a transition listener can tell which one ended', () => { + const {harness, press} = setup(); + let pressAtFailure: unknown = 'unset'; + press.addTransitionListener((recognizer, _from, to) => { + if (to === 'failed') { + pressAtFailure = recognizer.press; + } + }); + harness + .finger(1) + .down(10, 20, 5, {recognizers: [press]}) + .up(200); + expect(pressAtFailure).toEqual({time: 5, x: 10, y: 20}); + expect(press.press).toBeNull(); + }); + + it('takes a finger or a pen, not a mouse (a mouse opens the menu with its secondary button)', () => { + const mouse = setup(); + mouse.harness + .finger(1) + .down(0, 0, 0, {recognizers: [mouse.press], pointerType: 'mouse'}); + mouse.harness.advance(COMMIT); + expect(mouse.press.state).toBe('possible'); + + const pen = setup(); + pen.harness + .finger(1) + .down(0, 0, 0, {recognizers: [pen.press], pointerType: 'pen'}); + pen.harness.advance(COMMIT); + expect(pen.press.state).toBe('began'); + }); +}); diff --git a/packages/core/src/ContextMenu/contextMenuPress.ts b/packages/core/src/ContextMenu/contextMenuPress.ts new file mode 100644 index 0000000000000..592bb480f33dd --- /dev/null +++ b/packages/core/src/ContextMenu/contextMenuPress.ts @@ -0,0 +1,215 @@ +// Copyright (c) Meta Platforms, Inc. and affiliates. + +/** + * @file contextMenuPress.ts + * @input Touches from the gesture arena and the context-menu constants + * @output ContextMenuPressRecognizer: the long press that opens a context menu + * on UIContextMenuInteraction's timeline under a finger, and the press it + * reports + * @position ContextMenu's touch invocation, on the gesture foundation; + * ContextMenu.tsx attaches it to the trigger + * + * SYNC: When modified, update /packages/core/src/ContextMenu/ContextMenu.tsx + * and /packages/core/src/ContextMenu/contextMenuPress.test.ts + */ + +import {isActive} from '../gestures/GestureRecognizer'; +import { + LongPressGestureRecognizer, + type LongPressGestureRecognizerOptions, +} from '../gestures/LongPressGestureRecognizer'; +import type {GestureEventContext, GestureTouch} from '../gestures/types'; +import {contextMenu} from '../motion/uikit/contextMenu'; + +const {commitMs, menuDisplayMs, allowableMovement} = contextMenu.press; + +/** + * The foundation's own press timer, which this recognizer never lets fire: + * the hold below commits instead. It is longer than any hold, and under the + * window timer's 2^31 - 1 ms limit. + */ +const NEVER_MS = 2 ** 30; + +/** A finger that may become a context menu: when and where it landed. */ +export interface ContextMenuPress { + /** On the event clock (`performance.now()`, an event's `timeStamp`), ms. */ + readonly time: number; + /** Client CSS px. */ + readonly x: number; + readonly y: number; +} + +export type ContextMenuPressRecognizerOptions = Omit< + LongPressGestureRecognizerOptions, + | 'allowableMovement' + | 'minimumPressDuration' + | 'numberOfTapsRequired' + | 'numberOfTouchesRequired' +>; + +/** + * A context menu is not UIKit's plain long press (500 ms, 10 pt of travel). + * Its timeline is `contextMenu.press`, and these are the recognizer's states: + * - `possible`: the finger landed. A lift, a second finger, or a browser + * scroll fails it. A drift past `allowableMovement` on either + * axis fails it too. + * - `began` at `commitMs`: the click haptic. The recognizer claims the touch. + * The page stops scrolling under it, and the lift sends no click and no + * compatibility mouse events. The menu does not show yet. A drift past + * `allowableMovement` still ends it with no menu (`cancelled`). A lift shows + * the menu at once (`ended` without `isMenuDue`). + * - `changed` with `isMenuDue` at `menuDisplayMs`: the finger is still down, + * and the menu shows. From then on, the finger moves freely. + * + * The hold runs on the arena's clock and timers, so the commit lands at its + * deadline even when the main thread is busy. The foundation's long press + * gives the claim and failure rules and the trigger's style. It never begins + * on its own timer, only at the hold's commit. A press that fails or is + * cancelled reports it through `addTransitionListener`, while `press` still + * names it. + */ +export class ContextMenuPressRecognizer extends LongPressGestureRecognizer { + /** The finger in play, from its landing until the gesture resets. */ + press: ContextMenuPress | null = null; + /** + * The finger stayed until `menuDisplayMs`: the menu is due, and the finger + * moves freely from here. + */ + isMenuDue = false; + /** The finger the hold follows. */ + private pressTouchId: number | null = null; + /** Where the finger landed, while its hold runs. The drift counts from here. */ + private holdFrom: {x: number; y: number} | null = null; + /** When the finger landed, on the arena's clock. The deadlines count from it. */ + private holdStart = 0; + + constructor(options: ContextMenuPressRecognizerOptions = {}) { + super({ + ...options, + // A finger or a pen; a mouse opens the menu with its secondary button. + allowedPointerTypes: options.allowedPointerTypes ?? ['touch', 'pen'], + minimumPressDuration: NEVER_MS, + // The hold's own tolerance is the drift rule (touchesMoved below). + allowableMovement: Infinity, + }); + } + + /** + * The event clock at this moment: the timestamp of the input (or the + * deadline of the timer) being processed. Read it from a listener to + * place what the transition starts at the time it happened. + */ + get clockTime(): number { + return this.now(); + } + + protected override touchesBegan( + touches: ReadonlyArray, + event: GestureEventContext, + ): void { + super.touchesBegan(touches, event); + if ( + this.press == null && + this.state === 'possible' && + this.numberOfTouches === this.numberOfTouchesRequired + ) { + const [touch] = touches; + this.press = {time: event.time, x: touch.x, y: touch.y}; + this.pressTouchId = touch.id; + // The hold's deadlines count from the touch itself. This replaces the + // foundation's own press timer, which never fires. + this.holdFrom = {x: touch.x, y: touch.y}; + this.holdStart = event.time; + this.setTimer(event.time + commitMs, () => this.commit()); + } + } + + protected override touchesMoved(touches: ReadonlyArray): void { + const touch = touches.find(each => each.id === this.pressTouchId); + const hasDrifted = touch != null && !this.followHold(touch); + if (hasDrifted && this.state === 'possible') { + this.setState('failed'); + return; + } + if (hasDrifted && isActive(this.state) && !this.isMenuDue) { + this.setState('cancelled'); + return; + } + super.touchesMoved(touches); + } + + /** + * Follows the finger during its hold, through each sample of the move at + * the time it came with. A drift past `allowableMovement` on either axis + * before the menu's moment ends the hold; the finger moves freely after it. + * Returns whether the hold still runs. + */ + private followHold(touch: GestureTouch): boolean { + for (const sample of touch.inputSamples) { + const from = this.holdFrom; + if (from == null) { + return false; + } + if ( + Math.abs(sample.x - from.x) > allowableMovement || + Math.abs(sample.y - from.y) > allowableMovement + ) { + this.endHold(); + return false; + } + } + return this.holdFrom != null; + } + + private endHold(): void { + this.clearTimer(); + this.holdFrom = null; + } + + /** The hold's commit claims the finger, then waits for the menu's moment. */ + private commit(): void { + if (this.holdFrom == null) { + return; + } + if ( + this.state === 'possible' && + this.numberOfTouches === this.numberOfTouchesRequired + ) { + this.beganAt = this.now(); + this.setState('began'); + } + // A transition listener can end the hold. + if (this.holdFrom != null) { + this.setTimer(this.holdStart + menuDisplayMs, () => this.showMenu()); + } + } + + /** + * The finger is still down at the menu's moment: the menu is due. Behind a + * blocked page, the arena runs this moment only after the moves stamped + * before it, so a drift among them still ends the hold. + */ + private showMenu(): void { + if (!this.isMenuPending()) { + return; + } + this.presentMenu(); + } + + private isMenuPending(): boolean { + return this.holdFrom != null && isActive(this.state) && !this.isMenuDue; + } + + private presentMenu(): void { + this.isMenuDue = true; + this.setState('changed'); + } + + protected override reset(): void { + super.reset(); + this.endHold(); + this.pressTouchId = null; + this.press = null; + this.isMenuDue = false; + } +} diff --git a/packages/core/src/ContextMenu/contextMenuTouchLoader.boundary.test.ts b/packages/core/src/ContextMenu/contextMenuTouchLoader.boundary.test.ts new file mode 100644 index 0000000000000..0656db19644bd --- /dev/null +++ b/packages/core/src/ContextMenu/contextMenuTouchLoader.boundary.test.ts @@ -0,0 +1,122 @@ +// Copyright (c) Meta Platforms, Inc. and affiliates. + +/** + * @file contextMenuTouchLoader.boundary.test.ts + * @input The static import graphs of the ContextMenu entry and of Table's + * context-menu module, and every core source file + * @output The source boundary check for ContextMenu's touch layer. No entry's + * static graph reaches the layer, its recognizer or the gesture code under + * it. Only the loader imports the layer, through `import()`. + * @position Testing; the before-load behavior is in ContextMenu.test.tsx + */ + +import {existsSync, readFileSync, readdirSync, statSync} from 'node:fs'; +import {dirname, join, relative, resolve} from 'node:path'; +import {fileURLToPath} from 'node:url'; +import {describe, expect, it} from 'vitest'; + +const here = dirname(fileURLToPath(import.meta.url)); +const coreSrc = join(here, '..'); + +/** The touch modules no ContextMenu entry may import statically. */ +const TOUCH_MODULES = [ + 'ContextMenu/ContextMenuTouchLayer.tsx', + 'ContextMenu/contextMenuPress.ts', + 'gestures/GestureHost.ts', + 'gestures/GestureArena.ts', +]; + +/** The source with its comments removed, so prose cannot pass or fail it. */ +function code(source: string): string { + return source.replace(/\/\*[\s\S]*?\*\//g, '').replace(/\/\/.*$/gm, ''); +} + +/** The relative modules a file imports statically, types left out. */ +function staticImports(file: string): string[] { + const body = code(readFileSync(file, 'utf8')); + const specifiers = [ + ...body.matchAll( + /^\s*(?:import|export)\s+(?!type\b)(?:[^'";]*?\sfrom\s+)?['"]([^'"]+)['"]/gm, + ), + ].map(match => match[1]); + return specifiers.flatMap(specifier => { + if (!specifier.startsWith('.')) { + return []; + } + const base = resolve(dirname(file), specifier); + const found = [ + base, + `${base}.ts`, + `${base}.tsx`, + join(base, 'index.ts'), + join(base, 'index.tsx'), + ].find(path => existsSync(path) && statSync(path).isFile()); + return found == null ? [] : [found]; + }); +} + +/** Each touch module the entry reaches, with the chain that brings it. */ +function touchChains(entry: string): string[] { + const start = join(coreSrc, entry); + const parent = new Map([[start, null]]); + const queue = [start]; + const chains: string[] = []; + while (queue.length > 0) { + const file = queue.shift()!; + const name = relative(coreSrc, file); + if (TOUCH_MODULES.includes(name)) { + const chain: string[] = []; + for (let at: string | null = file; at != null; at = parent.get(at)!) { + chain.unshift(relative(coreSrc, at)); + } + chains.push(chain.join(' → ')); + continue; + } + for (const next of staticImports(file)) { + if (!parent.has(next)) { + parent.set(next, file); + queue.push(next); + } + } + } + return chains; +} + +function sourceFiles(dir: string): string[] { + const out: string[] = []; + for (const name of readdirSync(dir)) { + const path = join(dir, name); + if (statSync(path).isDirectory()) { + if (name !== '__tests__' && name !== 'node_modules') { + out.push(...sourceFiles(path)); + } + } else if ( + /\.(ts|tsx)$/.test(name) && + !/\.(test|spec)\.(ts|tsx)$/.test(name) + ) { + out.push(path); + } + } + return out; +} + +describe('ContextMenu loads its touch layer after first paint', () => { + it.each(['ContextMenu/index.ts', 'Table/tableContextMenu.tsx'])( + '%s reaches no touch module statically', + entry => { + expect(touchChains(entry)).toEqual([]); + }, + ); + + it('imports the touch layer only from its loader, through import()', () => { + const layer = join(coreSrc, 'ContextMenu/ContextMenuTouchLayer.tsx'); + const importers = sourceFiles(coreSrc) + .filter(file => staticImports(file).includes(layer)) + .map(file => relative(coreSrc, file)); + expect(importers).toEqual([]); + const loaderPath = join(here, 'contextMenuTouchLoader.ts'); + expect(existsSync(loaderPath)).toBe(true); + const loader = code(readFileSync(loaderPath, 'utf8')); + expect(loader).toMatch(/import\(\s*'\.\/ContextMenuTouchLayer'\s*\)/); + }); +}); diff --git a/packages/core/src/ContextMenu/contextMenuTouchLoader.ts b/packages/core/src/ContextMenu/contextMenuTouchLoader.ts new file mode 100644 index 0000000000000..8f0edcd45e254 --- /dev/null +++ b/packages/core/src/ContextMenu/contextMenuTouchLoader.ts @@ -0,0 +1,165 @@ +// Copyright (c) Meta Platforms, Inc. and affiliates. + +'use client'; + +/** + * @file contextMenuTouchLoader.ts + * @input No props: ContextMenu calls `useContextMenuTouchLayer` while its + * touch model applies + * @output The touch layer after the page loads it, `null` until then, and + * whether its latest load failed; a new load after a failure + * @position Between ContextMenu and its touch layer: loads the layer after + * first paint + * + * SYNC: When modified, update /packages/core/src/ContextMenu/ContextMenu.tsx + */ + +import {useEffect, useSyncExternalStore, type RefObject} from 'react'; +import {warnOnce} from '../utils/devWarning'; +import {createModuleLoader} from '../utils/moduleLoader'; +import type {ContextMenuTouchLayer as TouchLayer} from './ContextMenuTouchLayer'; + +// The touch layer imports the long-press recognizer, which brings the arena +// and the gesture host. These modules stay out of the page's first load. The +// first ContextMenu under the touch model in each window asks for them, and +// the page loads them once. The request waits until that window's next frame +// has painted, then for an idle moment, capped at LOAD_CAP_MS. Touches, clicks +// and keys do not change when the load starts. As the layer mounts, it takes +// a finger that landed before the load. + +/** + * How long the load waits for an idle main thread after that paint, in ms. + * Past it, the load starts anyway. + */ +export const LOAD_CAP_MS = 2000; + +/** What a ContextMenu reads of the page's touch layer. */ +export interface ContextMenuTouchLayerState { + /** The touch layer once it has loaded, else `null`. */ + readonly layer: typeof TouchLayer | null; + /** Whether the latest load failed. The next touch on a trigger asks again. */ + readonly hasFailed: boolean; +} + +const NOT_LOADED: ContextMenuTouchLayerState = {layer: null, hasFailed: false}; + +let state: ContextMenuTouchLayerState = NOT_LOADED; +// The windows whose triggers scheduled the load. Each schedules its own, so a +// window that paints no frame (a hidden tab, a closed frame) stalls no other. +let scheduledViews = new WeakSet(); +let pendingLoad: Promise | null = null; +const listeners = new Set<() => void>(); + +const layerModule = createModuleLoader( + async () => import('./ContextMenuTouchLayer'), +); + +function getState(): ContextMenuTouchLayerState { + return state; +} + +function getServerState(): ContextMenuTouchLayerState { + return NOT_LOADED; +} + +function subscribe(listener: () => void): () => void { + listeners.add(listener); + return () => { + listeners.delete(listener); + }; +} + +function publish(next: ContextMenuTouchLayerState): void { + state = next; + for (const listener of [...listeners]) { + listener(); + } +} + +function load(): void { + pendingLoad ??= layerModule.load().then( + loaded => { + pendingLoad = null; + publish({layer: loaded.ContextMenuTouchLayer, hasFailed: false}); + }, + (error: unknown) => { + pendingLoad = null; + // The next touch on a trigger asks again. + publish({layer: null, hasFailed: true}); + warnOnce( + 'ContextMenu:touch-layer-load', + 'ContextMenu', + 'the touch layer failed to load. Until a later touch loads it, a held finger opens the menu after 500 ms.', + error, + ); + }, + ); +} + +function scheduleLoad(view: Window): void { + if (state.layer != null || state.hasFailed || scheduledViews.has(view)) { + return; + } + scheduledViews.add(view); + // The timers belong to the trigger's window, so they end with its document. + // The frame callback runs just before that frame paints, so the timeout it + // sets runs just after the paint. + view.requestAnimationFrame(() => { + view.setTimeout(() => { + if (typeof view.requestIdleCallback === 'function') { + view.requestIdleCallback(load, {timeout: LOAD_CAP_MS}); + } else { + view.setTimeout(load, 0); + } + }, 0); + }); +} + +/** + * Loads the touch layer again after a failed load. A touch on a trigger calls + * it: that touch is the intent that asks. + */ +export function retryContextMenuTouchLayer(): void { + if (!state.hasFailed || pendingLoad != null) { + return; + } + load(); +} + +/** + * The touch layer after the page loads it, `null` until then, and whether its + * latest load failed. The first ContextMenu that wants it asks for the load, + * and later ones share it. It is `null` on the server and while hydrating, so + * both renders produce the same markup. `triggerRef` names the window whose + * frame and idle time start the load; the page's own window by default. + */ +export function useContextMenuTouchLayer( + isWanted: boolean, + triggerRef?: RefObject, +): ContextMenuTouchLayerState { + const current = useSyncExternalStore(subscribe, getState, getServerState); + // Syncs with the trigger window's frame and idle timers, which decide when + // the touch layer loads. + useEffect(() => { + if (isWanted) { + scheduleLoad(triggerRef?.current?.ownerDocument.defaultView ?? window); + } + }, [isWanted, triggerRef]); + return isWanted ? current : NOT_LOADED; +} + +/** + * Test only: loads the layer at once and hands it to every hook that reads + * it. + */ +export async function __loadContextMenuTouchLayerForTest(): Promise { + const loaded = await layerModule.load(); + publish({layer: loaded.ContextMenuTouchLayer, hasFailed: false}); +} + +/** Test only: drops the loaded layer and clears the scheduled loads. */ +export function __resetContextMenuTouchLayerForTest(): void { + scheduledViews = new WeakSet(); + pendingLoad = null; + publish(NOT_LOADED); +} diff --git a/packages/core/src/Indicator/boxHold.test.tsx b/packages/core/src/Indicator/boxHold.test.tsx index 05bd93d001570..538b601bd7c8a 100644 --- a/packages/core/src/Indicator/boxHold.test.tsx +++ b/packages/core/src/Indicator/boxHold.test.tsx @@ -203,7 +203,10 @@ describe('a finger held on a control’s box', () => { const onChange = vi.fn(); const onOpenChange = vi.fn(); render( - + diff --git a/packages/core/src/Layer/outsidePress.test.ts b/packages/core/src/Layer/outsidePress.test.ts index 417b8260085f4..69ba5c0f9acc0 100644 --- a/packages/core/src/Layer/outsidePress.test.ts +++ b/packages/core/src/Layer/outsidePress.test.ts @@ -4,10 +4,11 @@ * @file outsidePress.test.ts * @input isFocusInsideOwnedLayer, isPressInsideOwnedLayer and * watchOutsidePress - * @output The shared focus-leave test, and the outside-press watch that - * closes as a finger outside begins to pan, at a cancel or at a lift. With - * onPan, the watch reports only that pan, once, and no press or count, - * and no pan that touch-action keeps from the browser + * @output The shared focus-leave test, and the outside-press watch. The + * watch closes as a finger outside begins to pan, at a cancel or at a lift. + * For a mouse or a pen it closes at the press. With onPan, the watch + * reports only that pan, once, and no press or count, and no pan that + * touch-action keeps from the browser */ import {fireEvent} from '@testing-library/react'; @@ -431,3 +432,110 @@ describe('watchOutsidePress, reporting pans (onPan)', () => { expect(onPan).not.toHaveBeenCalled(); }); }); + +describe('watchOutsidePress, closing at the press', () => { + afterEach(() => { + document.body.replaceChildren(); + }); + + const press = (pointerType: string, pointerId = 1) => ({ + pointerType, + pointerId, + composed: true, + }); + + function setup(root?: Node, pressTypes = ['mouse', 'pen']) { + const owner = document.createElement('div'); + const layer = document.createElement('div'); + const item = document.createElement('button'); + layer.append(item); + const outside = document.createElement('button'); + document.body.append(owner, outside); + (root ?? document.body).appendChild(layer); + const onOutside = vi.fn(); + const stop = watchOutsidePress( + owner, + path => path.includes(layer), + onOutside, + {closesOnPan: true, pointerTypes: ['touch'], pressTypes, root}, + ); + return {item, outside, onOutside, stop}; + } + + it('closes at the mousedown of a mouse or a pen press outside, and not again at its lift', () => { + const {outside, onOutside, stop} = setup(); + fireEvent.pointerDown(outside, press('mouse')); + fireEvent.mouseDown(outside); + expect(onOutside).toHaveBeenCalledOnce(); + fireEvent.pointerUp(outside, press('mouse')); + fireEvent.mouseUp(outside); + expect(onOutside).toHaveBeenCalledOnce(); + fireEvent.pointerDown(outside, press('pen', 2)); + fireEvent.mouseDown(outside); + expect(onOutside).toHaveBeenCalledTimes(2); + stop(); + }); + + it('keeps the layer open for a mouse press inside it, in a closed shadow root too', () => { + const host = document.createElement('div'); + document.body.append(host); + const shadow = host.attachShadow({mode: 'closed'}); + const {item, onOutside, stop} = setup(shadow); + fireEvent.pointerDown(item, press('mouse')); + fireEvent.mouseDown(item, {composed: true}); + expect(onOutside).not.toHaveBeenCalled(); + fireEvent.pointerDown(host, press('mouse')); + fireEvent.mouseDown(host, {composed: true}); + expect(onOutside).toHaveBeenCalledOnce(); + stop(); + }); + + it('judges a mousedown that no pointerdown came before as a mouse press', () => { + const {outside, onOutside, stop} = setup(); + fireEvent.mouseDown(outside); + expect(onOutside).toHaveBeenCalledOnce(); + stop(); + }); + + it('leaves a press whose handler stops its mousedown before the document unjudged', () => { + const {outside, onOutside, stop} = setup(); + outside.addEventListener('mousedown', event => event.stopPropagation()); + fireEvent.pointerDown(outside, press('mouse')); + fireEvent.mouseDown(outside); + expect(onOutside).not.toHaveBeenCalled(); + stop(); + }); + + it('leaves a touch to its own judgment, and its compatibility mousedown alone', () => { + const {outside, onOutside, stop} = setup(); + fireEvent.pointerDown(outside, press('touch')); + fireEvent.pointerUp(outside, press('touch')); + expect(onOutside).toHaveBeenCalledOnce(); + fireEvent.mouseDown(outside); + expect(onOutside).toHaveBeenCalledOnce(); + stop(); + }); + + it('judges a touch at its compatibility mousedown when touch is a press type', () => { + const {outside, onOutside, stop} = setup(undefined, [ + 'mouse', + 'pen', + 'touch', + ]); + fireEvent.pointerDown(outside, press('touch')); + fireEvent.pointerUp(outside, press('touch')); + expect(onOutside).not.toHaveBeenCalled(); + fireEvent.mouseDown(outside); + expect(onOutside).toHaveBeenCalledOnce(); + stop(); + }); + + it('counts a layer it closes at the press as an outside dismissal', () => { + const {outside, stop} = setup(); + const before = outsideDismissalCount(document); + fireEvent.pointerDown(outside, press('mouse')); + fireEvent.mouseDown(outside); + expect(outsideDismissalCount(document)).toBe(before + 1); + stop(); + }); +}); diff --git a/packages/core/src/Layer/outsidePress.ts b/packages/core/src/Layer/outsidePress.ts index 43a0cdee8ca8d..b668def3ad3d6 100644 --- a/packages/core/src/Layer/outsidePress.ts +++ b/packages/core/src/Layer/outsidePress.ts @@ -5,7 +5,8 @@ /** * @file outsidePress.ts * @input Pointer presses on a document and on the shadow roots around a - * given root; with closesOnPan or onPan, pan moves from core's input stream + * given root. With closesOnPan or onPan, pan moves from core's input + * stream. With pressTypes, the presses' bubbling mousedown * @output watchOutsidePress, and useOutsidePress, one watch per component. * noteOutsideDismissal and outsideDismissalCount keep a per-document count * of layers that an outside press or focus move closed. The inside tests @@ -47,6 +48,14 @@ export interface OutsidePressOptions { * document judges presses too, and an inner root's judgment stands. */ readonly root?: Node | null; + /** + * The pointer types judged at the press rather than at the lift. A press + * outside by one of them closes the layer at its bubbling `mousedown`, as a + * manual popover's own dismissal does. A press's type is that of the last + * `pointerdown` before its `mousedown`. With none, or one that names no + * type, it is a mouse. The watch does not follow these types at the lift. + */ + readonly pressTypes?: ReadonlyArray; } // A modal host's backdrop press reads this. A press that closed a layer above @@ -75,7 +84,7 @@ export function outsideDismissalCount(doc: Document): number { * @param isInside - Whether a press with this composed path is inside. * @param onOutside - Called once for each press that starts and ends outside, * as native light dismiss does. With `closesOnPan`, also when that press - * pans or is cancelled. + * pans or is cancelled. For a press type, at the press. * @returns Stops watching. */ export function watchOutsidePress( @@ -87,6 +96,7 @@ export function watchOutsidePress( closesOnPan = false, onPan, root = null, + pressTypes = [], }: OutsidePressOptions = {}, ): () => void { const doc = owner.ownerDocument; @@ -95,8 +105,11 @@ export function watchOutsidePress( const shadows = root == null ? [] : shadowRootsOutward(root); let startedOutside = false; let panStart: {id: number; x: number; y: number} | null = null; + // The type of the pointer whose press the next mousedown belongs to. + let pressType: string | null = null; const follows = (event: PointerEvent) => - pointerTypes == null || pointerTypes.includes(event.pointerType); + !pressTypes.includes(event.pointerType) && + (pointerTypes == null || pointerTypes.includes(event.pointerType)); const close = () => { startedOutside = false; panStart = null; @@ -108,6 +121,7 @@ export function watchOutsidePress( // An inner root's listener runs after the outer ones', so its judgment // stands. const handleDown = (event: PointerEvent) => { + pressType = event.pointerType; if (!follows(event)) { return; } @@ -205,10 +219,30 @@ export function watchOutsidePress( } }; + // A press type's press is judged at its bubbling mousedown, so a handler + // that stops it keeps the layer open. An inner root sees it first, with the + // real target, and the outer ones skip it. + let judgedPress: Event | null = null; + const handlePress = (event: Event) => { + if (event === judgedPress) { + return; + } + judgedPress = event; + const type = pressType || 'mouse'; + pressType = null; + if (pressTypes.includes(type) && !isInside(event.composedPath())) { + close(); + } + }; + const judges: EventTarget[] = [ doc, ...shadows.map(({root: shadow}) => shadow), ]; + const pressJudges = pressTypes.length > 0 ? judges : []; + for (const target of pressJudges) { + target.addEventListener('mousedown', handlePress); + } for (const target of judges) { target.addEventListener('pointerdown', handleDown as EventListener, true); } @@ -231,6 +265,9 @@ export function watchOutsidePress( true, ); } + for (const target of pressJudges) { + target.removeEventListener('mousedown', handlePress); + } stopMoves?.(); doc.removeEventListener('pointerup', handleUp, true); for (const {shadow, host, handleRootUp, handleHostUp} of liftJudges) { diff --git a/packages/core/src/Layer/useLayer.test.tsx b/packages/core/src/Layer/useLayer.test.tsx index f6ae263aa167d..7e1786f4d779b 100644 --- a/packages/core/src/Layer/useLayer.test.tsx +++ b/packages/core/src/Layer/useLayer.test.tsx @@ -227,6 +227,12 @@ function KeptLazyContextHarness({ + + {unsafe ? (

{renderedLayer}

@@ -1065,6 +1071,60 @@ describe('useLayer', () => { expect(layer).toHaveAttribute('data-open', 'true'); }); + it('prepare() mounts it closed, and the next show opens that element at once', async () => { + const showSpy = mockPopover(); + const {container, getByRole} = render(); + + fireEvent.click(getByRole('button', {name: 'Prepare'})); + await waitFor(() => { + expect(container.querySelector('[popover]')).not.toBeNull(); + }); + const layer = container.querySelector('[popover]'); + expect(layer).not.toHaveAttribute('data-open'); + expect(showSpy).not.toHaveBeenCalled(); + + fireEvent.click(getByRole('button', {name: 'Trigger'})); + // Mounted: shown within the call, not after a commit. + expect(showSpy).toHaveBeenCalledOnce(); + expect(container.querySelector('[popover]')).toBe(layer); + expect(layer).toHaveAttribute('data-open', 'true'); + }); + + it('releasePrepared() unmounts a prepared layer that never showed', async () => { + const showSpy = mockPopover(); + const {container, getByRole} = render(); + + fireEvent.click(getByRole('button', {name: 'Prepare'})); + await waitFor(() => { + expect(container.querySelector('[popover]')).not.toBeNull(); + }); + fireEvent.click(getByRole('button', {name: 'Release'})); + + await waitFor(() => { + expect(container.querySelector('[popover]')).toBeNull(); + }); + expect(container.querySelector('template')).not.toBeNull(); + expect(showSpy).not.toHaveBeenCalled(); + }); + + it('releasePrepared() keeps a prepared layer that has shown since', async () => { + mockPopover(); + const {container, getByRole} = render(); + + fireEvent.click(getByRole('button', {name: 'Prepare'})); + await waitFor(() => { + expect(container.querySelector('[popover]')).not.toBeNull(); + }); + const layer = container.querySelector('[popover]'); + fireEvent.click(getByRole('button', {name: 'Trigger'})); + fireEvent.click(getByRole('button', {name: 'Close'})); + fireEvent.click(getByRole('button', {name: 'Release'})); + + await act(async () => {}); + expect(container.querySelector('[popover]')).toBe(layer); + expect(layer?.isConnected).toBe(true); + }); + it('without the option, a lazy layer still unmounts on hide', async () => { mockPopover(); const {container, getByRole} = render( diff --git a/packages/core/src/Layer/useLayer.tsx b/packages/core/src/Layer/useLayer.tsx index 5dea20956276b..f608406c207cf 100644 --- a/packages/core/src/Layer/useLayer.tsx +++ b/packages/core/src/Layer/useLayer.tsx @@ -473,6 +473,23 @@ export interface FixedLayerReturn { render: (children: ReactNode, props: FixedRenderProps) => ReactNode; } +/** Context-mode members a core component may use through `useLayerInternal`. */ +interface InternalContextLayerFields { + /** + * With `lazyMount`, mounts the layer's content without showing it. The + * popover stays closed, so it shows no pixel and is out of the accessibility + * tree until `show()`, which then only shows it. A caller that knows a show + * is coming spares that show the first mount's render. Does nothing for a + * layer that is mounted already. + */ + prepare: () => void; + /** + * Unmounts what `prepare()` mounted, unless the layer has shown since. A + * layer that has shown keeps its mount as its options say. + */ + releasePrepared: () => void; +} + /** * Context-mode options a core component may pass through `useLayerInternal`; * not part of the public `useLayer` options. @@ -517,6 +534,9 @@ interface InternalContextLayerOptions extends ContextLayerOptions { writesEntranceSide?: boolean; } +type InternalContextLayerReturn = ContextLayerReturn & + InternalContextLayerFields; + function toCssLength(value: number | string): string { return typeof value === 'number' ? `${value}px` : value; } @@ -1264,7 +1284,7 @@ export function useKeepLayerOpenProps( */ function useLayerImplementation( options: InternalContextLayerOptions | FixedLayerOptions, -): ContextLayerReturn | FixedLayerReturn { +): InternalContextLayerReturn | FixedLayerReturn { const {mode, onShow, onHide, lightDismiss = false} = options; const lazyMount = mode === 'context' ? (options.lazyMount ?? false) : false; const keepsMountAfterShow = @@ -1552,6 +1572,30 @@ function useLayerImplementation( [mountStore], ); + // The mount came from `prepare()`, and the layer has not shown since. + const isMountPreparedRef = useRef(false); + + const prepare = useCallback(() => { + if (mode !== 'context' || !lazyMount || contextMountRef.current != null) { + return; + } + isMountPreparedRef.current = true; + requestContextMount(); + }, [mode, lazyMount, requestContextMount]); + + const releasePrepared = useCallback(() => { + if ( + !isMountPreparedRef.current || + pendingShowRef.current || + isOpenRef.current + ) { + return; + } + isMountPreparedRef.current = false; + contextMountRef.current = null; + mountStore.set(null); + }, [mountStore]); + const clearContextMount = useCallback(() => { if (mode !== 'context' || !lazyMount || keepsMountAfterShow) { return; @@ -1602,6 +1646,7 @@ function useLayerImplementation( isOpenRef.current = false; stopOutsidePanWatch(); } + isMountPreparedRef.current = false; // A context popover left over until React commits a previous hide must not // be reopened. The synchronous mount ref is the source of truth. const candidate = popoverRef.current; @@ -2546,17 +2591,29 @@ function useLayerImplementation( [popoverRefCallback, id, lightDismiss], ); - const contextResult = useMemo( + const contextResult = useMemo( () => ({ ref: contextRef, anchorId, show, hide, isOpen, + prepare, + releasePrepared, id, render: renderContext, }), - [contextRef, anchorId, show, hide, isOpen, id, renderContext], + [ + contextRef, + anchorId, + show, + hide, + isOpen, + prepare, + releasePrepared, + id, + renderContext, + ], ); const fixedResult = useMemo( () => ({ @@ -2578,6 +2635,8 @@ export function useLayer(options: FixedLayerOptions): FixedLayerReturn; export function useLayer( options: ContextLayerOptions | FixedLayerOptions, ): ContextLayerReturn | FixedLayerReturn { + // Only the type hides the internal members. Stripping them at runtime + // would cost every page that uses a layer. return useLayerImplementation(options); } @@ -2587,10 +2646,10 @@ export function useLayer( */ export function useLayerInternal( options: InternalContextLayerOptions, -): ContextLayerReturn; +): InternalContextLayerReturn; export function useLayerInternal(options: FixedLayerOptions): FixedLayerReturn; export function useLayerInternal( options: InternalContextLayerOptions | FixedLayerOptions, -): ContextLayerReturn | FixedLayerReturn { +): InternalContextLayerReturn | FixedLayerReturn { return useLayerImplementation(options); } diff --git a/packages/core/src/gestures/GestureArena.ts b/packages/core/src/gestures/GestureArena.ts index 62bf6d03374cd..ff345d29c2ef0 100644 --- a/packages/core/src/gestures/GestureArena.ts +++ b/packages/core/src/gestures/GestureArena.ts @@ -36,7 +36,10 @@ * timestamp runs first, at its own deadline. A long press therefore begins at * exactly touch-down + 500 ms even when the main thread was blocked and the * timer callback came late, and a test drives the whole machine with explicit - * timestamps and no real time at all. + * timestamps and no real time at all. A deadline whose timer runs late waits + * while input from before it still reaches the page late. That holds only + * while the latest contact is a finger or a pen. A deadline among a coalesced + * move's samples runs between them. * * SYNC: When modified, update GestureRecognizer.ts and * __tests__/arena.test.ts. @@ -52,12 +55,31 @@ import type { GestureEventContext, GestureState, GestureTouch, + PointerKind, TouchBeganInput, TouchConsumer, TouchInput, TouchSample, } from './types'; import {DEFAULT_ENVIRONMENT} from './types'; + +/** + * A deadline's timer counts as late when it runs this long after it was due. + * In ms: one frame at 60 Hz. + */ +const LATE_TIMER_MS = 17; + +/** + * An input counts as late when it reaches the page this long after its own + * time. In ms: two frames at 60 Hz. + */ +const LATE_INPUT_MS = 33; + +/** + * How long a late deadline waits for input still queued before it. In ms: + * three frames at 60 Hz. + */ +const LATE_INPUT_WAIT_MS = 50; import {internals} from './recognizerInternals'; export interface GestureClock { @@ -162,6 +184,18 @@ export class GestureArena { private currentTime: number | null = null; /** The latest time processed: input never moves the clock backwards. */ private latestTime = Number.NEGATIVE_INFINITY; + /** The latest input that reached the page late: its own time, and when. */ + private lateInput: {time: number; arrivedAt: number} | null = null; + /** + * Whether the latest contact is a finger or a pen. Only then does a late + * deadline wait for queued input; a mouse keeps the one-task yield. + */ + private isLatestContactFingerOrPen = false; + /** + * When the latest wait for queued input ended with none still coming late. + * A deadline that came due during that wait is not late on its own. + */ + private quietSince = Number.NEGATIVE_INFINITY; private depth = 0; /** Open `deferResolution` calls: what their stops unblock waits. */ private deferDepth = 0; @@ -181,6 +215,14 @@ export class GestureArena { return this.currentTime ?? Math.max(this.latestTime, this.clock.now()); } + /** + * The injected clock's own reading: when the page runs now. Behind a block, + * the event clock lags it. + */ + pageTime(): number { + return this.clock.now(); + } + /** Whether a recognizer owns this touch, so the browser must not pan or zoom it. */ isClaimed(id: number): boolean { return this.records.get(id)?.isClaimed === true; @@ -222,6 +264,13 @@ export class GestureArena { if (inputs.length === 0) { return; } + this.isLatestContactFingerOrPen = isFingerOrPen( + inputs[inputs.length - 1].pointerType, + ); + this.noteArrival( + inputs[0].time, + inputs.some(input => isFingerOrPen(input.pointerType)), + ); this.run(inputs[0].time, () => { const newTouches = new Map(); const created: TouchRecord[] = []; @@ -238,6 +287,10 @@ export class GestureArena { x: input.x, y: input.y, time, + inputSamples: [ + ...(input.history ?? []), + {x: input.x, y: input.y, time: input.time}, + ], startX: input.x, startY: input.y, startTime: time, @@ -316,6 +369,8 @@ export class GestureArena { * gesture hear of it, as of any touch off their hit path. */ untrackedBegan(input: TouchBeganInput): void { + this.isLatestContactFingerOrPen = isFingerOrPen(input.pointerType); + this.noteArrival(input.time, this.isLatestContactFingerOrPen); if (!this.active.some(recognizer => recognizer.numberOfTouches > 0)) { return; } @@ -328,6 +383,7 @@ export class GestureArena { x: input.x, y: input.y, time, + inputSamples: [{x: input.x, y: input.y, time: input.time}], startX: input.x, startY: input.y, startTime: time, @@ -350,6 +406,31 @@ export class GestureArena { if (inputs.length === 0) { return; } + this.noteArrival( + inputs[0].time, + inputs.some(input => this.isFingerOrPenContact(input.id)), + ); + // A coalesced move carries the samples since the previous one. A deadline + // among them runs between them: the samples stamped before it come first. + let rest = inputs; + for ( + let deadline = this.deadlineAmong(rest); + deadline != null; + deadline = this.deadlineAmong(rest) + ) { + const before = samplesBefore(rest, deadline); + if (before.length > 0) { + this.deliverMoved(before); + } + this.advanceTime(deadline); + rest = samplesFrom(rest, deadline); + } + if (rest.length > 0) { + this.deliverMoved(rest); + } + } + + private deliverMoved(inputs: ReadonlyArray): void { this.run(inputs[0].time, () => { const changed = this.update(inputs, 'moved'); if (changed.length === 0) { @@ -383,6 +464,10 @@ export class GestureArena { if (inputs.length === 0) { return dispositions; } + this.noteArrival( + inputs[0].time, + inputs.some(input => this.isFingerOrPenContact(input.id)), + ); this.run(inputs[0].time, () => { const changed = this.update(inputs, 'ended'); const context = this.context(); @@ -407,6 +492,10 @@ export class GestureArena { /** The system took these contacts (`touchcancel`, a mouse `pointercancel`). */ cancelled(ids: ReadonlyArray, time: number): void { + this.noteArrival( + time, + ids.some(id => this.isFingerOrPenContact(id)), + ); this.run(time, () => { const touches = this.liveTouches(ids); for (const touch of touches) { @@ -437,6 +526,10 @@ export class GestureArena { * browser took stays the browser's (FR14). */ browserTookOver(ids: ReadonlyArray, time: number): void { + this.noteArrival( + time, + ids.some(id => this.isFingerOrPenContact(id)), + ); this.run(time, () => { const touches = this.liveTouches(ids).filter( touch => !touch.takenByBrowser, @@ -553,7 +646,7 @@ export class GestureArena { /** Cancel an active recognizer, or fail a possible one. */ stop(recognizer: GestureRecognizer): void { // A cancel from code between events happens at the last event's time: - // wall time would run deadlines ahead of input still queued (FR16). + // wall time would run deadlines ahead of input still queued. const time = this.currentTime ?? (Number.isFinite(this.latestTime) ? this.latestTime : this.clock.now()); @@ -993,6 +1086,10 @@ export class GestureArena { touch.x = input.x; touch.y = input.y; touch.time = time; + touch.inputSamples = [ + ...(input.history ?? []), + {x: input.x, y: input.y, time: input.time}, + ]; touch.phase = phase; changed.push(touch); } @@ -1005,6 +1102,62 @@ export class GestureArena { return clamped; } + /** Only a finger's or pen's late input keeps a late deadline waiting. */ + private noteArrival(time: number, isFingerOrPenInput: boolean): void { + const arrivedAt = this.clock.now(); + if (isFingerOrPenInput && arrivedAt - time > LATE_INPUT_MS) { + this.lateInput = {time, arrivedAt}; + } + } + + private isFingerOrPenContact(id: number): boolean { + return isFingerOrPen(this.records.get(id)?.touch.pointerType); + } + + /** + * The earliest timer deadline among the new samples of `inputs`: after the + * earliest of them, and at or before the latest. Null when none falls there. + */ + private deadlineAmong(inputs: ReadonlyArray): number | null { + let earliest = Number.POSITIVE_INFINITY; + let latest = Number.NEGATIVE_INFINITY; + for (const input of inputs) { + const known = + this.records.get(input.id)?.touch.time ?? Number.NEGATIVE_INFINITY; + for (const sample of input.history ?? []) { + if (sample.time > known) { + earliest = Math.min(earliest, sample.time); + } + } + earliest = Math.min(earliest, input.time); + latest = Math.max(latest, input.time); + } + let found: number | null = null; + for (const timer of this.timers.values()) { + if ( + timer.deadline > earliest && + timer.deadline <= latest && + (found == null || timer.deadline < found) + ) { + found = timer.deadline; + } + } + return found; + } + + /** + * Whether input from before `deadline` reached the page late within the + * last `LATE_INPUT_WAIT_MS`, so more of it may still be queued. + */ + private hasLateInputBefore(deadline: number, now: number): boolean { + const input = this.lateInput; + return ( + input != null && + input.time < deadline && + now - input.arrivedAt < LATE_INPUT_WAIT_MS + ); + } + /** * One external entry: run the timers due by `time`, then `body`, then * settle (release held deliveries, reset finished recognizers, forget @@ -1138,25 +1291,99 @@ export class GestureArena { return; } const delay = Math.max(0, earliest - this.clock.now()); - const fire = (mayYield: boolean): void => { + const fire = ( + after: 'deadline' | 'yield' | 'wait', + dueAt: number, + ): void => { this.realTimer = null; this.realTimerDeadline = Number.POSITIVE_INFINITY; - if (mayYield && this.clock.now() > earliest) { + const now = this.clock.now(); + // A deadline that came due during a quiet wait is late only past it. + const lateBy = now - Math.max(dueAt, this.quietSince); + // Only the deadline's own timer counts as late. Only input from before + // the deadline extends a wait, so a wait ends. + const isLateTimer = after === 'deadline' && lateBy > LATE_TIMER_MS; + if ( + this.isLatestContactFingerOrPen && + after !== 'yield' && + (isLateTimer || this.hasLateInputBefore(earliest, now)) + ) { + // Behind a blocked page, input from before the deadline can still be + // queued. A touch move can also reach the page a frame after other + // input. Wait while that input still comes. An input stamped at or + // past the deadline runs the deadline first, which ends the wait. + this.realTimerDeadline = earliest; + const waitUntil = now + LATE_INPUT_WAIT_MS; + this.realTimer = this.clock.setTimeout( + () => fire('wait', waitUntil), + LATE_INPUT_WAIT_MS, + ); + return; + } + if (after === 'wait') { + this.quietSince = now; + } + if (after === 'deadline' && now > earliest) { // Late: a long task held the main thread past the deadline, and // input queued behind it may come before the deadline (a lift that // fails a long press). Let that input dispatch first, once. this.realTimerDeadline = earliest; - this.realTimer = this.clock.setTimeout(() => fire(false), 0); + this.realTimer = this.clock.setTimeout(() => fire('yield', now), 0); return; } // The event clock moves to the deadline only, so input still queued // keeps its own timestamps. this.advanceTime(earliest); }; - this.realTimer = this.clock.setTimeout(() => fire(true), delay); + this.realTimer = this.clock.setTimeout( + () => fire('deadline', earliest), + delay, + ); } } +function isFingerOrPen(pointerType: PointerKind | undefined): boolean { + return pointerType === 'touch' || pointerType === 'pen'; +} + +/** Each input cut to its samples stamped before `time`; inputs with none go. */ +function samplesBefore( + inputs: ReadonlyArray, + time: number, +): TouchInput[] { + const cut: TouchInput[] = []; + for (const input of inputs) { + const samples = [ + ...(input.history ?? []), + {x: input.x, y: input.y, time: input.time}, + ].filter(sample => sample.time < time); + const last = samples[samples.length - 1]; + if (last != null) { + cut.push({ + id: input.id, + x: last.x, + y: last.y, + time: last.time, + history: samples.slice(0, -1), + }); + } + } + return cut; +} + +/** Each input cut to its samples stamped at or after `time`; inputs with none go. */ +function samplesFrom( + inputs: ReadonlyArray, + time: number, +): TouchInput[] { + return inputs + .filter(input => input.time >= time) + .map(input => ({ + ...input, + history: (input.history ?? []).filter(sample => sample.time >= time), + })); +} + function sharesTouches(a: GestureRecognizer, b: GestureRecognizer): boolean { for (const id of internals(a).seenTouchIds) { if (internals(b).seenTouchIds.has(id)) { diff --git a/packages/core/src/gestures/GestureHost.ts b/packages/core/src/gestures/GestureHost.ts index d0ae705bf777e..922aada90b94d 100644 --- a/packages/core/src/gestures/GestureHost.ts +++ b/packages/core/src/gestures/GestureHost.ts @@ -3077,17 +3077,51 @@ export class GestureHost { } private readonly onTouchStart = (event: TouchEvent): void => { - this.endWheel(eventTime(event, this.timing)); - this.noteFingersDown(event); + this.beginTouches(event, eventTime(event, this.timing)); + }; + + /** + * Begins, now, the fingers of a `touchstart` this host did not track. A + * recognizer that attaches while a finger is down on its element hands + * over that finger's own touchstart. The caller passes only a touchstart + * whose fingers are still down. A finger the host heard but left untracked + * begins too; a finger it tracks stays as it is. `pointerId` is the + * finger's own pointer, whose `pointerdown` came before the host listened. + */ + beginLateTouches(event: TouchEvent, pointerId: number | null = null): void { + const [first] = touchesOf(event.changedTouches); + if (pointerId != null && first != null) { + // The finger's touchstart pairs with this pointer as it begins. + this.pendingPointers.set(pointerId, { + x: first.clientX, + y: first.clientY, + target: isNode(first.target) + ? landedOn(event, first.target) + : landedOn(event), + }); + } + this.beginTouches(event, this.arena.pageTime(), true); + if (pointerId != null) { + // A finger that did not begin leaves no pointer waiting for it. + this.pendingPointers.delete(pointerId); + } + } + + private beginTouches(event: TouchEvent, time: number, isLate = false): void { + // A late touchstart the host heard is old news: its fingers are noted. + const isHeard = this.processed.has(event); + this.endWheel(time); + if (!isLate || !isHeard) { + this.noteFingersDown(event); + } // Where the host reads a finger from its pointer events (no ontouchstart, // as after touch emulation turns on), its Touch Events would track it twice. - if (!this.usesTouchEvents || !this.takeEvent(event)) { + if (!this.usesTouchEvents || (!this.takeEvent(event) && !isLate)) { return; } if (this.fingerTargets.length > 1) { this.failUnclaimedLoneFingerPans(); } - const time = eventTime(event, this.timing); const inputs: ArenaBeganInput[] = []; const untracked: TouchBeganInput[] = []; const stale: number[] = []; @@ -3101,6 +3135,10 @@ export class GestureHost { if ((touch as StylusTouch).touchType === 'stylus') { continue; } + if (isLate && this.touchIds.has(touch.identifier)) { + // Already tracked: the touchstart began it when the host heard it. + continue; + } // A finger number still tracked here began again: the touch it named // ended where no listener of ours could hear it. this.cancelledFingers.delete(touch.identifier); @@ -3198,7 +3236,7 @@ export class GestureHost { if (isNode(landed)) { this.lastTouch = {target: landed, time}; } - }; + } private readonly onTouchMove = (event: TouchEvent): void => { this.noteFingersDown(event); diff --git a/packages/core/src/gestures/__tests__/GestureHost.test.ts b/packages/core/src/gestures/__tests__/GestureHost.test.ts index 7f15746796097..e00380b8b7d95 100644 --- a/packages/core/src/gestures/__tests__/GestureHost.test.ts +++ b/packages/core/src/gestures/__tests__/GestureHost.test.ts @@ -4480,6 +4480,101 @@ describe('GestureHost.fingersDown', () => { }); }); +describe('a late begin: a finger that landed before its recognizer attached', () => { + it('begins the finger from its own touchstart at the host’s time now, so a hold counts from then', () => { + const {handle} = mount('
'); + const press = new LongPressGestureRecognizer({minimumPressDuration: 500}); + const states: string[] = []; + press.addListener(recognizer => states.push(recognizer.state)); + const finger = {id: 1, x: 10, y: 10, target: handle}; + // Nothing on the page listens as the finger lands. + const landed = touch('touchstart', handle, [finger], [finger], 0); + clock.time = 300; + detachers.push(host.attach(handle, press)); + host.beginLateTouches(landed as TouchEvent); + expect(press.numberOfTouches).toBe(1); + clock.runDue(799); + expect(states).not.toContain('began'); + clock.runDue(800); + expect(states).toContain('began'); + touch('touchend', handle, [finger], [], 900); + expect(press.numberOfTouches).toBe(0); + }); + + it('follows the late finger’s moves: a drift past the press’s limit fails it', () => { + const {handle} = mount('
'); + const press = new LongPressGestureRecognizer({minimumPressDuration: 500}); + const states: string[] = []; + press.addListener(recognizer => states.push(recognizer.state)); + const finger = {id: 1, x: 10, y: 10, target: handle}; + const landed = touch('touchstart', handle, [finger], [finger], 0); + clock.time = 300; + detachers.push(host.attach(handle, press)); + host.beginLateTouches(landed as TouchEvent); + const moved = {...finger, x: 60}; + touch('touchmove', handle, [moved], [moved], 350); + clock.runDue(1000); + expect(states).not.toContain('began'); + touch('touchend', handle, [moved], [], 1000); + }); + + it('begins nothing again from a touchstart it already heard', () => { + const {handle} = mount('
'); + const press = new LongPressGestureRecognizer({minimumPressDuration: 500}); + const states: string[] = []; + press.addListener(recognizer => states.push(recognizer.state)); + detachers.push(host.attach(handle, press)); + const finger = {id: 1, x: 10, y: 10, target: handle}; + const landed = touch('touchstart', handle, [finger], [finger], 0); + clock.time = 300; + host.beginLateTouches(landed as TouchEvent); + expect(press.numberOfTouches).toBe(1); + // The hold still counts from the touchstart the host heard. + clock.runDue(500); + expect(states).toContain('began'); + touch('touchend', handle, [finger], [], 600); + }); + + it('begins a finger it heard but left untracked, as when another gesture keeps it listening', () => { + const {handle, other} = mount( + '
', + ); + // A gesture elsewhere keeps the host listening on the page. + detachers.push( + host.attach(other, new LongPressGestureRecognizer({name: 'other'})), + ); + const press = new LongPressGestureRecognizer({minimumPressDuration: 500}); + const states: string[] = []; + press.addListener(recognizer => states.push(recognizer.state)); + const finger = {id: 1, x: 10, y: 10, target: handle}; + // The host hears this touchstart, but nothing on the handle takes it. + const landed = touch('touchstart', handle, [finger], [finger], 0); + clock.time = 300; + detachers.push(host.attach(handle, press)); + host.beginLateTouches(landed as TouchEvent); + expect(press.numberOfTouches).toBe(1); + clock.runDue(799); + expect(states).not.toContain('began'); + clock.runDue(800); + expect(states).toContain('began'); + touch('touchend', handle, [finger], [], 900); + }); + + it('pairs a late finger with the pointer its caller hands over', () => { + const {handle} = mount('
'); + const press = new LongPressGestureRecognizer({minimumPressDuration: 500}); + const finger = {id: 1, x: 10, y: 10, target: handle}; + // The finger's pointerdown and touchstart came before any listener. + const landed = touch('touchstart', handle, [finger], [finger], 0); + clock.time = 300; + detachers.push(host.attach(handle, press)); + host.beginLateTouches(landed as TouchEvent, 31); + const [held] = press.trackedTouches; + expect(host.pointerIdOf(held)).toBe(31); + touch('touchend', handle, [finger], [], 900); + }); +}); + describe('where the primary pointer is fine (spec:AST-094 FR43, FR24)', () => { /** Quiets the development warning, and returns its spy. */ function quietWarning() { diff --git a/packages/core/src/gestures/__tests__/arena.test.ts b/packages/core/src/gestures/__tests__/arena.test.ts index d5a724e20862d..3cdd78433a929 100644 --- a/packages/core/src/gestures/__tests__/arena.test.ts +++ b/packages/core/src/gestures/__tests__/arena.test.ts @@ -10,7 +10,9 @@ * requirements, idle recognizers), shouldBegin and shouldReceiveTouch, * innermost resolution, independent touches, delivery to the view (claims, * cancelsTouchesInView, delaysTouchesBegan, deferred and replayed clicks, - * the browser taking a touch), cancellation, and the event clock + * the browser taking a touch), cancellation, and the event clock, which + * holds a late input at its time and keeps the times the input and its + * coalesced samples came with * @position Unit tests of packages/core/src/gestures/GestureArena.ts and the * state machine of GestureRecognizer.ts */ @@ -402,6 +404,47 @@ describe('arena: cancellation and time', () => { h.finger(1).move(5, 0, 90); expect(h.log).toEqual(['r:began@100']); }); + it('holds a late input at the clock, and keeps the time it came with', () => { + const h = createHarness(); + const seen: {time: number; cameAt: number | undefined}[] = []; + const r = new Scripted('r', { + moved: recognizer => { + const [touch] = recognizer.trackedTouches; + seen.push({time: touch.time, cameAt: touch.inputSamples.at(-1)?.time}); + }, + }); + h.finger(1).down(0, 0, 100, {recognizers: [r]}); + h.advance(500); + h.finger(1).move(5, 0, 300); + h.finger(1).move(6, 0, 520); + expect(seen).toEqual([ + {time: 500, cameAt: 300}, + {time: 520, cameAt: 520}, + ]); + }); + it('keeps a late move’s coalesced samples at the times they came with', () => { + const h = createHarness(); + const seen: {samples: number[]; inputSamples: number[]}[] = []; + const r = new Scripted('r', { + moved: recognizer => { + const [touch] = recognizer.trackedTouches; + seen.push({ + samples: touch.samples.map(sample => sample.time), + inputSamples: touch.inputSamples.map(sample => sample.time), + }); + }, + }); + h.finger(1).down(0, 0, 100, {recognizers: [r]}); + h.advance(500); + h.finger(1).move(5, 0, 300); + // Both late: the clock holds them at 500 ms, and `samples` drops the + // earlier one, which comes before the touch's held time. + h.finger(1).move(7, 0, 320, [{x: 6, y: 0, time: 310}]); + expect(seen).toEqual([ + {samples: [500], inputSamples: [300]}, + {samples: [500], inputSamples: [310, 320]}, + ]); + }); }); /** A clock whose timers run one task at a time, as an event loop does. */ @@ -472,12 +515,14 @@ describe('arena: a timer that fires late', () => { expect(log.some(entry => entry.startsWith('press:began'))).toBe(false); }); - it('still fires on its deadline when nothing was queued', () => { + it('still fires on its deadline when nothing was queued, once the wait for queued input ends', () => { const {clock, arena, log} = pressArena(); clock.runTask(800); clock.runTask(800); + expect(log.some(entry => entry.startsWith('press:began'))).toBe(false); + clock.runTask(850); expect(log).toContain('press:began@500'); - arena.ended([{id: 1, x: 0, y: 0, time: 820}]); + arena.ended([{id: 1, x: 0, y: 0, time: 870}]); }); }); diff --git a/packages/core/src/gestures/__tests__/arenaTimersAndClaims.test.ts b/packages/core/src/gestures/__tests__/arenaTimersAndClaims.test.ts index e2aaeaa925a0f..b29533971589c 100644 --- a/packages/core/src/gestures/__tests__/arenaTimersAndClaims.test.ts +++ b/packages/core/src/gestures/__tests__/arenaTimersAndClaims.test.ts @@ -13,6 +13,7 @@ import {GestureArena, type GestureClock} from '../GestureArena'; import {LongPressGestureRecognizer} from '../LongPressGestureRecognizer'; import {PanGestureRecognizer} from '../PanGestureRecognizer'; import {TapGestureRecognizer} from '../TapGestureRecognizer'; +import type {PointerKind} from '../types'; import {createHarness} from './harness'; /** A clock whose timers run one task at a time, as an event loop does. */ @@ -44,7 +45,7 @@ class TaskClock implements GestureClock { } } -function pressArena(): { +function pressArena(pointerType: PointerKind = 'touch'): { clock: TaskClock; arena: GestureArena; press: LongPressGestureRecognizer; @@ -64,7 +65,7 @@ function pressArena(): { x: 0, y: 0, time: 0, - pointerType: 'touch', + pointerType, target: null, scroll: null, recognizers: [press], @@ -96,13 +97,162 @@ describe('a timer that fires late', () => { arena.ended([{id: 1, x: 40, y: 0, time: 820}]); }); - it('still fires on its deadline when nothing was queued', () => { + it('still fires on its deadline when nothing was queued, once the wait for queued input ends', () => { const {clock, arena, log} = pressArena(); + // 300 ms late: the deadline waits 50 ms for input still queued. clock.runTask(800); clock.runTask(800); + expect(log.some(entry => entry.startsWith('press:began'))).toBe(false); + clock.runTask(850); + expect(log).toContain('press:began@500'); + arena.ended([{id: 1, x: 0, y: 0, time: 870}]); + }); + + it('waits more than one task for input queued behind the block: a drift that comes after the next task still fails the press', () => { + const {clock, arena, log} = pressArena(); + // The timer task runs at 800, and so does the next task. The finger's + // drift from 300 ms reaches the page at 816, as Chromium sends touch + // moves with the next frame. + clock.runTask(800); + clock.runTask(800); + clock.time = 816; + arena.moved([{id: 1, x: 40, y: 0, time: 300}]); + clock.runTask(850); + expect(log.some(entry => entry.startsWith('press:began'))).toBe(false); + expect(log).toContain('press:failed@300'); + arena.ended([{id: 1, x: 40, y: 0, time: 870}]); + }); + + it('keeps an on-time deadline waiting while input from before it still comes late', () => { + const {clock, arena, log} = pressArena(); + // A move from 400 ms reaches the page at 470, 70 ms late, inside the + // press's tolerance. The deadline at 500 waits 50 ms past that move. + clock.time = 470; + arena.moved([{id: 1, x: 2, y: 0, time: 400}]); + clock.runTask(500); + expect(log.some(entry => entry.startsWith('press:began'))).toBe(false); + clock.runTask(550); + expect(log).toContain('press:began@500'); + arena.ended([{id: 1, x: 2, y: 0, time: 570}]); + }); + + it('ends the wait at the first input stamped at or past the deadline', () => { + const {clock, arena, log} = pressArena(); + clock.runTask(800); + clock.time = 820; + arena.moved([{id: 1, x: 1, y: 0, time: 820}]); + expect(log).toContain('press:began@500'); + arena.ended([{id: 1, x: 1, y: 0, time: 840}]); + }); + + it('ends the wait when its own timer runs late with nothing queued, with no second wait', () => { + const {clock, arena, log} = pressArena(); + // The deadline's timer runs late: it waits until 850. + clock.runTask(800); + // That wait's own timer runs 50 ms late behind another block. No input + // from before the deadline came late, so the deadline runs now. + clock.runTask(900); + expect(log).toContain('press:began@500'); + arena.ended([{id: 1, x: 0, y: 0, time: 920}]); + }); + + it('keeps the one-task yield for a mouse: its late deadline runs after the next task, with no wait', () => { + const {clock, arena, log} = pressArena('mouse'); + clock.runTask(800); + expect(log.some(entry => entry.startsWith('press:began'))).toBe(false); + clock.runTask(800); expect(log).toContain('press:began@500'); arena.ended([{id: 1, x: 0, y: 0, time: 820}]); }); + + it('waits for a pen’s late deadline as for a finger’s', () => { + const {clock, arena, log} = pressArena('pen'); + clock.runTask(800); + clock.runTask(800); + expect(log.some(entry => entry.startsWith('press:began'))).toBe(false); + clock.runTask(850); + expect(log).toContain('press:began@500'); + arena.ended([{id: 1, x: 0, y: 0, time: 870}]); + }); + + it('runs a deadline that came due during a wait just after it, with no second wait', () => { + const clock = new TaskClock(); + const log: string[] = []; + const arena: GestureArena = new GestureArena({ + clock, + onTransition: (recognizer, _from, to) => + log.push(`${recognizer.name}:${to}@${arena.now()}`), + }); + const first = new LongPressGestureRecognizer({ + name: 'first', + minimumPressDuration: 500, + }); + const second = new LongPressGestureRecognizer({ + name: 'second', + minimumPressDuration: 600, + }); + arena.began([ + { + id: 1, + x: 0, + y: 0, + time: 0, + pointerType: 'touch', + target: null, + scroll: null, + recognizers: [first], + consumer: null, + }, + { + id: 2, + x: 100, + y: 0, + time: 0, + pointerType: 'touch', + target: null, + scroll: null, + recognizers: [second], + consumer: null, + }, + ]); + // Both deadlines ran late behind one block. The first waits 50 ms; the + // second comes due during that wait, so it runs as the wait ends. + clock.runTask(900); + clock.runTask(950); + clock.runTask(950); + clock.runTask(950); + expect(log).toContain('first:began@500'); + expect(log).toContain('second:began@600'); + arena.ended([ + {id: 1, x: 0, y: 0, time: 970}, + {id: 2, x: 100, y: 0, time: 970}, + ]); + }); +}); + +describe('a coalesced move whose samples straddle a deadline', () => { + it('delivers the samples stamped before the deadline first: a drift among them fails the press', () => { + const {clock, arena, log} = pressArena(); + // One move reaches the page at 520 with the sample it coalesced: the + // finger drifted 40 px at 480, before the press's deadline at 500. + clock.time = 520; + arena.moved([ + {id: 1, x: 40, y: 0, time: 520, history: [{x: 40, y: 0, time: 480}]}, + ]); + expect(log.some(entry => entry.startsWith('press:began'))).toBe(false); + expect(log).toContain('press:failed@480'); + arena.ended([{id: 1, x: 40, y: 0, time: 540}]); + }); + + it('runs the deadline before the samples stamped at or after it', () => { + const {clock, arena, log} = pressArena(); + clock.time = 520; + arena.moved([ + {id: 1, x: 1, y: 0, time: 520, history: [{x: 1, y: 0, time: 480}]}, + ]); + expect(log).toContain('press:began@500'); + arena.ended([{id: 1, x: 1, y: 0, time: 540}]); + }); }); describe('cancelling an idle recognizer', () => { diff --git a/packages/core/src/gestures/__tests__/harness.ts b/packages/core/src/gestures/__tests__/harness.ts index 37f8796de614d..3e7fecf58ff86 100644 --- a/packages/core/src/gestures/__tests__/harness.ts +++ b/packages/core/src/gestures/__tests__/harness.ts @@ -5,8 +5,8 @@ * @input Nothing * @output Exports the synthetic-input harness the gesture tests share: a * manual clock, an arena wired to a transition log, fingers that land, - * move and lift at explicit timestamps, and a coarse primary pointer for - * tests that go through the document's host + * move (with coalesced samples) and lift at explicit timestamps, and a + * coarse primary pointer for tests that go through the document's host * @position Test-only helper of packages/core/src/gestures (excluded from the * build with the rest of __tests__) */ @@ -18,6 +18,7 @@ import type { GestureTouch, NativeScrollProbe, TouchConsumer, + TouchSample, } from '../types'; /** @@ -82,8 +83,11 @@ export interface Harness { view?: {left?: number; top?: number; width: number; height: number}; }; finger(id: number): Finger; - /** Advance the clock and run every timer due by `time`. */ - advance(time: number): void; + /** + * Advance the clock and run every timer due by `time`. `runsAt`: when the + * page runs those timers on the clock, later behind a block. + */ + advance(time: number, runsAt?: number): void; } export function createHarness(): Harness { @@ -138,8 +142,8 @@ export function createHarness(): Harness { } return finger; }, - advance: time => { - clock.time = time; + advance: (time, runsAt = time) => { + clock.time = runsAt; arena.advanceTime(time); }, }; @@ -189,12 +193,25 @@ export class Finger { return this; } - move(x: number, y: number, time: number): this { + /** + * `history`: the coalesced samples before this one, oldest first. + * `arrivesAt`: when the page gets the move on the clock, for a move that + * reaches it after its own time. + */ + move( + x: number, + y: number, + time: number, + history?: ReadonlyArray, + arrivesAt = time, + ): this { this.x = x; this.y = y; this.time = time; - this.harness.clock.time = time; - this.harness.arena.moved([{id: this.id, x, y, time}]); + this.harness.clock.time = arrivesAt; + this.harness.arena.moved([ + {id: this.id, x, y, time, ...(history == null ? {} : {history})}, + ]); return this; } diff --git a/packages/core/src/gestures/types.ts b/packages/core/src/gestures/types.ts index ef646cecde9d2..a0811112afe79 100644 --- a/packages/core/src/gestures/types.ts +++ b/packages/core/src/gestures/types.ts @@ -81,6 +81,13 @@ export interface GestureTouch { y: number; /** Timestamp of the latest position. */ time: number; + /** + * The latest event's positions at the times they came with, oldest first, + * ending with the current one. The arena's clock never runs back, so it + * holds a late input's `time` and filters `samples`; it does not change + * these. + */ + inputSamples: TouchSample[]; readonly startX: number; readonly startY: number; readonly startTime: number; diff --git a/packages/core/src/hooks/usePager.test.ts b/packages/core/src/hooks/usePager.test.ts index 0af4841366c32..7af9e1ba9a0a6 100644 --- a/packages/core/src/hooks/usePager.test.ts +++ b/packages/core/src/hooks/usePager.test.ts @@ -899,7 +899,10 @@ describe('createPager', () => { // Still moving 40 ms after the touch. expect(f.pager.isSettling).toBe(true); await advance(paging.catchStopMs, f.clock); - // The catch's deadline is on the gesture clock. + // The catch's deadline is on the gesture clock. It ran late, so it waits + // 50 ms for input still queued before it. + f.clock.runDue(now); + await advance(50, f.clock); f.clock.runDue(now); expect(f.pager.isSettling).toBe(false); const held = -f.x(); @@ -2045,6 +2048,9 @@ describe('createPager', () => { expect(pager.isSettling).toBe(true); resize(300); await advance(paging.catchStopMs, f.clock); + // The catch's deadline ran late: it waits 50 ms for queued input. + f.clock.runDue(now); + await advance(50, f.clock); f.clock.runDue(now); expect(pager.isSettling).toBe(false); const held = -f.x(); diff --git a/packages/core/src/motion/README.md b/packages/core/src/motion/README.md index 25b4b8d048010..21e141fa5b860 100644 --- a/packages/core/src/motion/README.md +++ b/packages/core/src/motion/README.md @@ -18,6 +18,7 @@ roles through `resolveMotion`. | `uikit/springs.ts` | Interaction springs (navigation, sheets, alerts, menus, controls, keyboard, banners) and the SwiftUI / UIKit presets. | | `uikit/scroll.ts` | UIScrollView: deceleration rates, rubber band, bounce-back spring, `delaysContentTouches`, scroll to top. | | `uikit/timing.ts` | Non-spring clocks and curves: press highlight, Core Animation's named curves, keyboard, Reduced Motion cross-fade. | +| `uikit/contextMenu.ts` | UIContextMenuInteraction: touch timeline (commit, menu), drift tolerance, commit haptic. | | `uikit/paging.ts` | A paging UIScrollView: the integrator that settles a release on its page, the page rule, the catch, `setContentOffset(animated:)`. | | `uikit/alert.ts` | UIAlertController: how a finger is tracked across the actions (highlight onset and bounds). | | `uikit/navigation.ts` | UINavigationController: push velocity, parallax, dimming, transition clock, interactive pop finish rule. | diff --git a/packages/core/src/motion/uikit/contextMenu.ts b/packages/core/src/motion/uikit/contextMenu.ts new file mode 100644 index 0000000000000..1b7ac9cb221fd --- /dev/null +++ b/packages/core/src/motion/uikit/contextMenu.ts @@ -0,0 +1,90 @@ +// Copyright (c) Meta Platforms, Inc. and affiliates. + +/** + * @file contextMenu.ts + * @input Measurements of UIContextMenuInteraction on iOS 26.2 + * @output `contextMenu`: UIContextMenuInteraction's touch timeline, drift + * tolerance and commit haptic + * @position The context-menu domain of the UIKit constants table. Only + * ContextMenu's own modules import it. The table's barrel does not + * re-export it. + * + * SYNC: When modified, update /packages/core/src/motion/MEASUREMENTS.md and + * /packages/core/src/ContextMenu/contextMenuPress.ts + */ + +/** + * UIContextMenuInteraction's touch timeline on iOS 26.2. A context menu is not + * a plain long press. At 400 ms the press commits. The click haptic plays, and + * the touch can no longer become a tap. The menu displays at 735 ms if the + * finger is still down, or at the lift after the commit. A finger that lifts + * before the commit gets no menu. A finger that drifts too far before the menu + * displays gets the same. + * + * UIKit runs this on display-link ticks. So a 60 Hz screen shows each moment + * on the first frame after it: the commit at 417 ms. + * The times here are the moments themselves, from the `touchstart` timestamp. + * UIKit counts from the main thread's receipt of the touch, about a frame + * after the hardware timestamp that a browser stamps. A browser's compositor + * shows a value about a frame after its time, so the two offsets cancel. + * + * Every leaf has one or more `@source`. A GUESS value also has the `@measure` + * task that confirms or replaces it. uikit.test.ts enforces both. + */ +export const contextMenu = { + press: { + /** + * When the long press commits. The click haptic plays, and from then on + * the touch belongs to the menu, not to a tap. The menu itself waits for + * `menuDisplayMs` or the lift. + * @source measured: UIKit lab (injected host app), iOS 26.2 simulator, + * iPhone 17 Pro, recognizer state log, Oct 23 2026: the + * clickPresentationExclusion and clickPresentationFailure recognizers + * ended on the first 60 Hz tick after 400 ms (at 416.7 ms; the tick + * before, at 399.5 ms, had not), the haptic played at 420 ms, and the + * platter's size ramp changes slope at 400 ms + * @measure M-CM6 + */ + commitMs: 400, + /** + * How far the finger may drift on either axis, from where it landed, + * until the menu displays; past it the press ends with no menu. Not the + * long press's `UIKIT_GESTURES.longPress.allowableMovement` (a distance): + * a diagonal drift of 15.6 pt still opens the menu. + * @source measured: UIKit lab (injected host app), iOS 26.2 simulator, + * iPhone 17 Pro, drifts at 100, 250 and 500 ms, Oct 23 2026: (7, 7), + * (8, 8), (10, 0) and (11, 11) pt open the menu; (12, 0) and (0, 12) + * cancel it, before and after the onset alike, and a 30 pt drag after + * the commit cancels it too + * @source GUESS — the value, midway in the measured bracket (11, 12) + * @measure M-CM3 + */ + allowableMovement: 11.5, + /** + * When the menu displays for a finger that is still down: the delegate's + * willDisplay, with the backdrop and the menu. Until then, only the press + * copy shows, and it grows on the second ramp. A finger lifted after the + * commit gets the menu at the lift. + * @source measured: UIKit lab (injected host app), iOS 26.2 simulator, + * iPhone 17 Pro, delegate log and per-frame view tree, Oct 23 2026: + * 735–738 ms after the touch over five warm presses at random display + * phase (734 ms on the first press of a session); a press lifted at + * 0.5 s displayed at the lift (529 ms) + */ + menuDisplayMs: 735, + }, + /** + * The click haptic at the commit, as a vibration where that is the only + * haptic (Android browsers). UIKit plays a private pattern + * (`_UIClickPresentationFeedbackGenerator`) at the commit; iOS Safari can + * play nothing at that moment, because no tap lands then. + * @source measured: UIKit lab (injected host app), iOS 26.2 simulator, + * iPhone 17 Pro, UIFeedbackGenerator hook, Oct 23 2026: the click + * presentation feedback plays 3 ms after the commit, nothing plays for a + * press lifted before it (the moment) + * @source GUESS — a medium impact stands in for the private pattern (the + * kind) + * @measure M-CM5 + */ + commitHaptic: 'impactMedium', +} as const; diff --git a/scripts/shared-identity.baseline.json b/scripts/shared-identity.baseline.json index acaeb5e67449a..c69479521c21d 100644 --- a/scripts/shared-identity.baseline.json +++ b/scripts/shared-identity.baseline.json @@ -49,6 +49,22 @@ "status": "allowed", "reason": "A memo cache; a second cache per copy changes no result." }, + "packages/core/src/ContextMenu/contextMenuTouchLoader.ts:listeners": { + "status": "allowed", + "reason": "Each copy of Core loads and renders its own touch layer, whose component reads that copy's contexts; a second copy's load changes no result." + }, + "packages/core/src/ContextMenu/contextMenuTouchLoader.ts:pendingLoad": { + "status": "allowed", + "reason": "Each copy of Core loads and renders its own touch layer, whose component reads that copy's contexts; a second copy's load changes no result." + }, + "packages/core/src/ContextMenu/contextMenuTouchLoader.ts:scheduledViews": { + "status": "allowed", + "reason": "Each copy of Core loads and renders its own touch layer, whose component reads that copy's contexts; a second copy's load changes no result." + }, + "packages/core/src/ContextMenu/contextMenuTouchLoader.ts:state": { + "status": "allowed", + "reason": "Each copy of Core loads and renders its own touch layer, whose component reads that copy's contexts; a second copy's load changes no result." + }, "packages/core/src/DateInput/monthGeometry.ts:GREGORIAN_MONTH_MODELS": { "status": "allowed", "reason": "A memo cache; a second cache per copy changes no result."