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.mdnew file mode 100644index 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.++@vjeuxdiff --git a/docs/specs/AST-094-touch-presentations/spec.md b/docs/specs/AST-094-touch-presentations/spec.mdindex 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 andits 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 thediff --git a/docs/specs/components/ContextMenu/ContextMenu.spec.md b/docs/specs/components/ContextMenu/ContextMenu.spec.mdindex 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 thatopened it cannot slide to a row, and a block trigger is not lifted over atinted 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 logdiff --git a/packages/core/src/motion/roles.test.ts b/packages/core/src/motion/roles.test.tsindex 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.tsindex 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.tsindex 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,};/**