Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

spec(ContextMenu): touch-opened menus lift with a tint, grow from the finger, and use named springs (#9423)

Cindy Zhang23c8cae985a9
diff --git a/docs/specs/AST-094-touch-presentations/spec.md b/docs/specs/AST-094-touch-presentations/spec.md
index 84ca1eea22..51dbfde118 100644
--- a/docs/specs/AST-094-touch-presentations/spec.md
+++ b/docs/specs/AST-094-touch-presentations/spec.md
@@ -130,25 +130,32 @@ a measured, sourced difference exists.
wherever the native motion settles with an overshoot or stretches with a
rubber band.
- | Role | Default | Source |
- | -------------------------- | ----------------------------------- | ---------------------------------------------------------------------------------------------- |
- | `springs.fingerTracking` | response 0.15 s, damping ratio 0.86 | Apple: SwiftUI `interactiveSpring()` |
- | `springs.emphasis` | duration 0.5 s, bounce 0.3 | Apple: SwiftUI `.bouncy` |
- | `springs.settle` | duration 0.5 s, bounce 0 | Apple: SwiftUI `.smooth` |
- | `springs.quickChange` | duration 0.5 s, bounce 0.15 | Apple: SwiftUI `.snappy` |
- | `springs.viewChange` | mass 3, stiffness 1000, damping 500 | measured: UIKit `UISpringTimingParameters()`, iOS 26.2 simulator, 2026-10-23 |
- | `springs.timedChange` | duration 0.5 s, bounce 0 | Apple: UIKit `UIView.animate(springDuration:bounce:)` |
- | `springs.stateChange` | response 0.55 s, damping ratio 1 | Apple: SwiftUI `Animation.default` |
- | `springs.directChange` | response 0.5 s, damping ratio 0.825 | Apple: SwiftUI `.spring(response:dampingFraction:)` |
- | `springs.menuOpen` | damping ratio 0.8, response 0.32 s | measured: UIMenu opening, iOS 26.2 simulator, 2026-10-23 |
- | `springs.menuClose` | damping ratio 0.85, response 0.35 s | measured: UIMenu closing, iOS 26.2 simulator, 2026-10-23 |
- | `springs.subMenuOpen` | damping ratio 0.85, response 0.4 s | measured: UIKit's own spring for UIMenu's sub-menu opening, iOS 26.2 simulator, 2026-10-24 |
- | `springs.subMenuBack` | damping ratio 1, response 0.4 s | measured: UIKit's own spring for UIMenu's sub-menu header back, iOS 26.2 simulator, 2026-10-24 |
- | `timing.stateChangeMs` | 250 ms | measured: Core Animation's implicit transaction, iOS 26.2 simulator, 2026-10-23 |
- | `timing.curves.viewChange` | cubic-bezier(0.25, 0.1, 0.25, 1) | Apple: `CAMediaTimingFunctionName.default` |
- | `timing.curves.exit` | cubic-bezier(0.42, 0, 1, 1) | measured: UIKit's ease-in, iOS 26.2 simulator, 2026-10-23 |
- | `timing.curves.entrance` | cubic-bezier(0, 0, 0.58, 1) | measured: UIKit's ease-out, iOS 26.2 simulator, 2026-10-23 |
- | `timing.curves.move` | cubic-bezier(0.42, 0, 0.58, 1) | measured: UIKit's ease-in-out, iOS 26.2 simulator, 2026-10-23 |
+ | Role | Default | Source |
+ | ---------------------------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------- |
+ | `springs.fingerTracking` | response 0.15 s, damping ratio 0.86 | Apple: SwiftUI `interactiveSpring()` |
+ | `springs.emphasis` | duration 0.5 s, bounce 0.3 | Apple: SwiftUI `.bouncy` |
+ | `springs.settle` | duration 0.5 s, bounce 0 | Apple: SwiftUI `.smooth` |
+ | `springs.quickChange` | duration 0.5 s, bounce 0.15 | Apple: SwiftUI `.snappy` |
+ | `springs.viewChange` | mass 3, stiffness 1000, damping 500 | measured: UIKit `UISpringTimingParameters()`, iOS 26.2 simulator, 2026-10-23 |
+ | `springs.timedChange` | duration 0.5 s, bounce 0 | Apple: UIKit `UIView.animate(springDuration:bounce:)` |
+ | `springs.stateChange` | response 0.55 s, damping ratio 1 | Apple: SwiftUI `Animation.default` |
+ | `springs.directChange` | response 0.5 s, damping ratio 0.825 | Apple: SwiftUI `.spring(response:dampingFraction:)` |
+ | `springs.menuOpen` | damping ratio 0.8, response 0.32 s | measured: UIMenu opening, iOS 26.2 simulator, 2026-10-23 |
+ | `springs.menuClose` | damping ratio 0.85, response 0.35 s | measured: UIMenu closing, iOS 26.2 simulator, 2026-10-23 |
+ | `springs.subMenuOpen` | damping ratio 0.85, response 0.4 s | measured: UIKit's own spring for UIMenu's sub-menu opening, iOS 26.2 simulator, 2026-10-24 |
+ | `springs.subMenuBack` | damping ratio 1, response 0.4 s | measured: UIKit's own spring for UIMenu's sub-menu header back, iOS 26.2 simulator, 2026-10-24 |
+ | `springs.contextMenuLift` | damping ratio 0.8, response 0.32 s | measured: UIContextMenuInteraction's preview lift, iOS 26.2 simulator, 2026-10-23 |
+ | `springs.contextMenuDismiss` | damping ratio 0.85, response 0.35 s | measured: UIContextMenuInteraction's dismissal, iOS 26.2 simulator, 2026-10-23 |
+ | `springs.contextMenuMorph` | damping ratio 0.8, response 0.3 s | measured: UIContextMenuInteraction's menu entrance and preview shadow, iOS 26.2 simulator, 2026-10-23 |
+ | `timing.stateChangeMs` | 250 ms | measured: Core Animation's implicit transaction, iOS 26.2 simulator, 2026-10-23 |
+ | `timing.curves.viewChange` | cubic-bezier(0.25, 0.1, 0.25, 1) | Apple: `CAMediaTimingFunctionName.default` |
+ | `timing.curves.exit` | cubic-bezier(0.42, 0, 1, 1) | measured: UIKit's ease-in, iOS 26.2 simulator, 2026-10-23 |
+ | `timing.curves.entrance` | cubic-bezier(0, 0, 0.58, 1) | measured: UIKit's ease-out, iOS 26.2 simulator, 2026-10-23 |
+ | `timing.curves.move` | cubic-bezier(0.42, 0, 0.58, 1) | measured: UIKit's ease-in-out, iOS 26.2 simulator, 2026-10-23 |
+
+ The three `springs.contextMenu*` rows are measured for ContextMenu's lift,
+ and `component:ContextMenu` owns them (DEC-5). They play only in a
+ ContextMenu that a touch opens.
### Motion
@@ -398,7 +405,8 @@ under a finger, and a mouse follows `module:DropdownMenu/useMenuPress` FR3 and
Under a finger, on every touch device, an anchored menu or a Popover MUST
open by growing out of its trigger and close by shrinking back into it, on
its motion roles (FR4; a menu on `springs.menuOpen` and
- `springs.menuClose`). The shrink plays in full after the surface has
+ `springs.menuClose`; a lifted ContextMenu's menu grows on
+ `springs.contextMenuMorph`). The shrink plays in full after the surface has
closed. This is its exit under FR7 (`family:overlay-dismissal` AV6); under
reduced motion FR8 applies. A menu or popover presented as a bottom sheet
follows the sheet instead.
@@ -675,6 +683,8 @@ under a finger, and a mouse follows `module:DropdownMenu/useMenuPress` FR3 and
its neighbors, unless a component or module record sets its own (FR42).
- `component:DropdownMenu`, `component:ContextMenu` and `component:Popover`:
under a finger they follow FR26–FR35 as each applies.
+- `component:ContextMenu`: implementation gap: the three `springs.contextMenu*`
+ roles (FR4) are not registered motion roles.
- `component:AlertDialog`, `component:Dialog`, `component:BottomSheet`,
`component:BottomSheetSwitcher`, `component:Drawer`, `component:MobileNav`
and `component:Lightbox`: under a finger, a tap or a drag during the
diff --git a/docs/specs/components/ContextMenu/ContextMenu.spec.md b/docs/specs/components/ContextMenu/ContextMenu.spec.md
index a64df5f48e..cdf5317a37 100644
--- a/docs/specs/components/ContextMenu/ContextMenu.spec.md
+++ b/docs/specs/components/ContextMenu/ContextMenu.spec.md
@@ -36,15 +36,15 @@ system_specs: [spec:AST-094, spec:AST-107]
## 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. Under a finger the menu does not grow from where it was opened or lift its trigger, and a scroll that starts outside leaves it open. |
-| Builder impact | Builders wrap any region, including an inline reference in prose (`triggerAs="span"`). |
-| Compatibility/readiness | Records shipped behavior; no API or DOM change; the released default 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 | 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 or DOM change; the released default 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`. |
This table is a review projection; the body below is authoritative.
@@ -97,18 +97,18 @@ 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 grow out of where it was opened and shrink back (`spec:AST-094` FR31), MUST close as a pan that starts outside it begins (FR32), MUST hand the held finger that opened it to the menu as the opening press and, on a block trigger, lift the trigger above the page with the menu beside it, and MUST treat a pen's press outside as FR32 does (FR33). 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 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 enabled 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. Arrow keys and typeahead skip disabled rows, shipped behavior that is not a requirement until `component:DropdownMenu` OQ1 is ruled. | 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 |
+| 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, the grow and their springs 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 trigger lifts on `springs.contextMenuLift` and returns on `springs.contextMenuDismiss`, and the menu grows on `springs.contextMenuMorph` (`spec:AST-094` FR4). 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, the three `springs.contextMenu*` roles are not registered motion roles, 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 enabled 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. Arrow keys and typeahead skip disabled rows, shipped behavior that is not a requirement until `component:DropdownMenu` OQ1 is ruled. | 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 |
### Allowed variation
@@ -177,6 +177,14 @@ The `context-menu` target intentionally appears on both alternative painted
menu surfaces. Trigger area content stays caller-owned and the 1px cursor
anchor is positioning infrastructure rather than consumer anatomy.
+### Design decisions
+
+<!-- design-decisions:v1 -->
+
+| ID | Decision | Intent or reason | Applies to | Allowed variation |
+| --- | -------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| DD1 | While a touch-opened menu lifts its trigger, the page behind the lifted trigger is tinted with the theme's overlay color and is not blurred. | The raised trigger stands out from a dimmed page using only theme tokens, so a theme and dark mode restyle it with no new token, and nothing behind the page repaints on each frame. | The lift of a touch-opened menu on a block trigger (FR5) | A theme chooses the overlay color's value. A blur or glass material behind the page is not part of the default look. |
+
### Theming anatomy
<!-- anatomy-theming:v1 -->
@@ -219,6 +227,9 @@ anchor is positioning infrastructure rather than consumer anatomy.
`useLayerDismissal`; touch hosting delegates
to BottomSheet.
- `spec:AST-094` owns the touch press, lift, grow, and dismissal rules (FR5).
+- `spec:AST-094` FR4 lists the three motion roles this component owns, measured
+ for its lift: `springs.contextMenuLift`, `springs.contextMenuDismiss` and
+ `springs.contextMenuMorph`.
- `family:overlay-dismissal` owns shared Escape and platform-close ordering.
ContextMenu's pointer presentation is a shared-stack adopter; the touch
presentation delegates dismissal to BottomSheet, which is also a shared-stack
@@ -226,31 +237,37 @@ 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` |
-| 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 "skips aria-disabled menuitemradio and menuitemcheckbox items during arrow navigation" | Wrap; typeahead; disabled rows | A clamped arrow, a missing typeahead match, or a disabled row landed on 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") | Right click, long press, keyboard | A context request that does not open the menu, or a dropped consumer handler, 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` |
-| 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 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 literal spring in the lift, or a role off its FR4 table value, fails. Evidence gap: the three roles are not registered. | `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 "skips aria-disabled menuitemradio and menuitemcheckbox items during arrow navigation" | Wrap; typeahead; disabled rows | A clamped arrow, a missing typeahead match, or a disabled row landed on 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") | Right click, long press, keyboard | A context request that does not open the menu, or a dropped consumer handler, 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` |
+| 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).** Under a finger the
- menu keeps the layer's own entrance and exit instead of growing from where it
- was opened, 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; a pen
- press outside closes it at the press. All are against `spec:AST-094` FR31,
- FR32, and FR33.
+- **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. The three `springs.contextMenu*` roles
+ are not registered motion roles (`spec:AST-094` FR4). A menu opened by mouse
+ or keyboard already keeps its released appearance and motion.
## Decision log
@@ -273,6 +290,38 @@ Rejected: styling a block `div` as inline because it remains invalid inside a
Rejected: `display: contents` because a box-less wrapper has no rect for pointer
or keyboard anchoring.
+### DEC-2 — The lift adds four elements while open, each with one job
+
+**Reference:** `component:ContextMenu/DEC-2`
+
+**Decider:** cixzhang, 2026-11-01
+
+A touch-opened menu on a block trigger lifts the trigger itself above the
+tinted page (`spec:AST-094` FR33) through the one lift module
+(`architecture:layer-runtime` INV15). While the menu is up, the page has four
+elements more than under a fine pointer, within the open-layer allowance of
+`spec:AST-017` FR60 and DEC-29, and each has one job:
+
+- the lift layer covers the viewport from the top layer, takes the page's
+ touches and paints the tint (DD1) as its `::backdrop`;
+- the shadow, a box in the layer, follows the trigger's lift as one
+ compositor animation (an animated `::backdrop` of the trigger would restyle
+ and lay out the page on every frame);
+- an empty box in the layer, at the lifted rect, is what the menu is placed
+ against (anchor positioning follows transforms, so the trigger's own cursor
+ anchor would move with the lifted trigger);
+- an empty placeholder after the trigger holds the trigger's spot, so the
+ page does not move while the trigger is in the top layer.
+
+None of the four is themeable or part of the anatomy, none is mounted at rest,
+and no content is mounted twice: the trigger lifts itself, with no copy. The
+input hold's shield joins while the lift grows, and the layer runtime's exit
+copy while the menu closes. A menu opened by mouse or keyboard adds none of
+them.
+
+Rejected: a copy of the trigger above the tint, because it mounts the
+trigger's content twice and its count grows with the trigger.
+
## Open questions
None.