Skip to content

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

TypeScript

chore(core): the touch motion tables register FR4's context-menu springs as roles (#9432)

Christopher Chedeau8d1864b673d5
diff --git a/.changeset/context-menu-spring-roles.md b/.changeset/context-menu-spring-roles.md
new file mode 100644
index 0000000000..228c92fdc1
--- /dev/null
+++ b/.changeset/context-menu-spring-roles.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[chore] Internal: the touch motion tables register the three context-menu springs spec:AST-094 FR4 names (`springs.contextMenuLift`, `springs.contextMenuDismiss` and `springs.contextMenuMorph`, a new row at response 0.3 s and damping ratio 0.8) as internal motion roles, so the registered roles are FR4's again. Nothing public changes: themes do not set motion roles, and no shipped component reads these springs yet.
+
+@vjeux
diff --git a/docs/specs/AST-094-touch-presentations/spec.md b/docs/specs/AST-094-touch-presentations/spec.md
index 51dbfde118..73a2faf4b4 100644
--- a/docs/specs/AST-094-touch-presentations/spec.md
+++ b/docs/specs/AST-094-touch-presentations/spec.md
@@ -683,8 +683,6 @@ 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 cdf5317a37..9ed24d8152 100644
--- a/docs/specs/components/ContextMenu/ContextMenu.spec.md
+++ b/docs/specs/components/ContextMenu/ContextMenu.spec.md
@@ -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 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 |
+| 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, 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
@@ -245,7 +245,7 @@ anchor is positioning infrastructure rather than consumer anatomy.
| 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` |
+| 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. | `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` |
@@ -265,9 +265,8 @@ anchor is positioning infrastructure rather than consumer anatomy.
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.
+ `spec:AST-094` FR31, FR32, and FR33. A menu opened by mouse or keyboard
+ already keeps its released appearance and motion.
## Decision log
diff --git a/packages/core/src/motion/roles.test.ts b/packages/core/src/motion/roles.test.ts
index 2bedd65028..74fe2c95ca 100644
--- a/packages/core/src/motion/roles.test.ts
+++ b/packages/core/src/motion/roles.test.ts
@@ -198,6 +198,9 @@ describe('motion roles', () => {
expect(
Object.fromEntries(discovered.map(role => [role.id, role.kind])),
).toEqual({
+ 'springs.contextMenuDismiss': 'spring',
+ 'springs.contextMenuLift': 'spring',
+ 'springs.contextMenuMorph': 'spring',
'springs.directChange': 'spring',
'springs.emphasis': 'spring',
'springs.fingerTracking': 'spring',
diff --git a/packages/core/src/motion/uikit/index.ts b/packages/core/src/motion/uikit/index.ts
index 317b51207a..a63ae7d6ea 100644
--- a/packages/core/src/motion/uikit/index.ts
+++ b/packages/core/src/motion/uikit/index.ts
@@ -48,6 +48,7 @@ export {
BANNER_SPRING,
CONTEXT_MENU_DISMISS_SPRING,
CONTEXT_MENU_LIFT_SPRING,
+ CONTEXT_MENU_MORPH_SPRING,
DIRECT_CHANGE_SPRING,
EMPHASIS_SPRING,
FINGER_TRACKING_SPRING,
diff --git a/packages/core/src/motion/uikit/springs.ts b/packages/core/src/motion/uikit/springs.ts
index f94b102884..4cdcde8ecc 100644
--- a/packages/core/src/motion/uikit/springs.ts
+++ b/packages/core/src/motion/uikit/springs.ts
@@ -353,6 +353,21 @@ export const CONTEXT_MENU_DISMISS_SPRING = {
dampingRatio: 0.85,
} as const;
+/**
+ * Context menu: the menu's entrance beside the lifted preview and the preview
+ * shadow's rise and fade (the preview's growth and the backdrop's fade take
+ * the lift spring above).
+ * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+ * iPhone 17 Pro, per-frame morph and platter layers, Oct 23 2026: the menu
+ * content's opacity, blur and scale, the morph container's centre and the
+ * preview shadow's opacity each fit (0.30, 0.80), rms ≤ 0.001; the issued
+ * UIViewSpringAnimationBehaviorSettings are (0.8, 0.3)
+ */
+export const CONTEXT_MENU_MORPH_SPRING = {
+ response: 0.3,
+ dampingRatio: 0.8,
+} as const;
+
/**
* What UIKit plays for a menu with Reduce Motion on: critically damped,
* slower, no overshoot. A reference reading of UIKit only, never played:
@@ -472,6 +487,7 @@ export const springs = {
subMenuBack: SUB_MENU_BACK_SPRING,
contextMenuLift: CONTEXT_MENU_LIFT_SPRING,
contextMenuDismiss: CONTEXT_MENU_DISMISS_SPRING,
+ contextMenuMorph: CONTEXT_MENU_MORPH_SPRING,
menuReducedMotion: MENU_REDUCED_MOTION_SPRING,
switchThumbMove: SWITCH_THUMB_MOVE_SPRING,
switchThumbStretch: SWITCH_THUMB_STRETCH_SPRING,
@@ -497,6 +513,9 @@ const SPRING_ROLES = {
menuClose: MENU_CLOSE_SPRING,
subMenuOpen: SUB_MENU_OPEN_SPRING,
subMenuBack: SUB_MENU_BACK_SPRING,
+ contextMenuLift: CONTEXT_MENU_LIFT_SPRING,
+ contextMenuDismiss: CONTEXT_MENU_DISMISS_SPRING,
+ contextMenuMorph: CONTEXT_MENU_MORPH_SPRING,
};
/**