An open source design system that's fully customizable and agent ready
TypeScript
spec(AST-094): touch presentations feel native by default (#8409)
Cindy Zhang23de0923e496
diff --git a/docs/design/user-states.md b/docs/design/user-states.mdindex ded895ea65..1f2b156049 100644--- a/docs/design/user-states.md+++ b/docs/design/user-states.md@@ -52,12 +52,13 @@ surface.- **DR1 — Press the manipulated surface.** During pointer hold or drag, eachenabled surface in the matrix below MUST paint `--color-overlay-pressed` onthe named visual part. The overlay is transient and MUST clear when the press- or drag ends.+ or drag ends. Under a finger, the overlay's timing follows `spec:AST-094` FR11's press profiles.- **DR2 — Disabled means no response.** A disabled control in the matrix MUSTremain inoperable and MUST NOT gain a pressed visual treatment.- **DR3 — Persistent selection wins.** A selected SegmentedControl item MUSTkeep its raised selected surface during pointer hold; only an unselected item- receives the pressed overlay.+ receives the pressed overlay. Under a finger the item keeps that surface, and its press timing follows+ `spec:AST-094` FR11.## Anatomy and hierarchydiff --git a/docs/families/buttons.md b/docs/families/buttons.mdindex f4b666c03d..6ef0a725e9 100644--- a/docs/families/buttons.md+++ b/docs/families/buttons.md@@ -93,15 +93,15 @@ Membership follows public responsibility, not an import of Button or a rendered## Canonical concepts-| Concept | Values or states | Default semantics | Stability |-| ---------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | --------------------------------------------------- |-| activation model | momentary action, navigation, persistent press | Button and IconButton activate once; ToggleButton represents retained pressed state | shipped distinction |-| content mode | visible label, custom visible content, icon-only | every control has a required accessible `label`; icon-only hides it visually | shipped family rule |-| size | `sm`, `md`, `lg` | `md`; explicit member size wins over an inherited group size | shipped family axis |-| visual state | rest, hover, focus, active, disabled, loading; pressed where applicable | states preserve control geometry and accessible purpose | shipped family rule |-| async action | absent, fire-once, interruptible persistent action | ordinary actions deduplicate while pending; persistent toggles remain reversible | shipped family distinction |-| elevation | `none`, `low`, `med`, `high` | `none`; the element painting the visible surface owns the shadow | shipped family axis; ToggleButton adoption approved |-| grouping | standalone, spaced set, connected surface | semantics and painted containment decide ownership; grouping alone does not | family rule |+| Concept | Values or states | Default semantics | Stability |+| ---------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |+| activation model | momentary action, navigation, persistent press | Button and IconButton activate once; ToggleButton represents retained pressed state | shipped distinction |+| content mode | visible label, custom visible content, icon-only | every control has a required accessible `label`; icon-only hides it visually | shipped family rule |+| size | `sm`, `md`, `lg` | `md`; explicit member size wins over an inherited group size | shipped family axis |+| visual state | rest, hover, focus, active, disabled, loading; pressed where applicable | states preserve control geometry and accessible purpose; under a finger, press feedback follows `spec:AST-094` FR11's control profile | shipped family rule |+| async action | absent, fire-once, interruptible persistent action | ordinary actions deduplicate while pending; persistent toggles remain reversible | shipped family distinction |+| elevation | `none`, `low`, `med`, `high` | `none`; the element painting the visible surface owns the shadow | shipped family axis; ToggleButton adoption approved |+| grouping | standalone, spaced set, connected surface | semantics and painted containment decide ownership; grouping alone does not | family rule |## Cross-component invariantsdiff --git a/docs/specs/AST-013/spec.md b/docs/specs/AST-013/spec.mdindex 85cfd51a17..e202d31593 100644--- a/docs/specs/AST-013/spec.md+++ b/docs/specs/AST-013/spec.md@@ -72,10 +72,12 @@ requirements. Assistive-technology evidence remains separately owned.public [Browser Support guide](../../../packages/cli/assets/docs/browser-support.doc.mjs)and record their source and refresh date. TypeScript targets, build targets, andfeature tables are not support evidence.-- **FR3 — Two explicit browser support rows are always included.** Independently+- **FR3 — Explicit browser support rows are always included.** Independentlyof the generated Baseline coverage, Astryx explicitly supports:- - the latest stable Chrome release on desktop; and- - Safari on the latest stable iOS release.+ - the latest stable Chrome release on desktop;+ - Safari on the latest stable iOS release; and+ - for touch presentations, Chrome on the latest stable Android release+ (`spec:AST-094`).“Latest” means the current stable release identified and refreshed fromauthoritative browser release data, not a handwritten version. Other browsers@@ -191,7 +193,7 @@ hydrating render can differ from the server's markup.## Decision log-### DEC-1 — Rolling Baseline tiers plus two official browser rows+### DEC-1 — Rolling Baseline tiers plus official browser rows**Reference:** `spec:AST-013/DEC-1`**Decider:** `cixzhang`, `2026-09-01`@@ -199,7 +201,8 @@ hydrating render can differ from the server's markup.Astryx uses current Web Platform Baseline for full support, Baseline minus twoyears for reduced fallback, and no promise below that tier. Latest stable Chromeon desktop and Safari on latest stable iOS are always included as official support-and test rows independently of generated Baseline coverage. Generated compatibility+and test rows independently of generated Baseline coverage, and touch+presentations add Chrome on the latest stable Android (`spec:AST-094`). Generated compatibilityrows and the named official test matrix remain distinct public facts.### DEC-2 — Explicit support does not require proof on every change@@ -207,7 +210,7 @@ rows and the named official test matrix remain distinct public facts.**Reference:** `spec:AST-013/DEC-2`**Decider:** `cixzhang`, `2026-09-02`-DEC-1's two named browser rows are explicit support rows, not a required automated+DEC-1's named browser rows are explicit support rows, not a required automatedor per-change test matrix. Astryx investigates and fixes defects reproduced inthose browsers, but routine changes do not need to prove every supported browserbefore landing. Actual-browser evidence is required when the change makes adiff --git a/docs/specs/AST-025/spec.md b/docs/specs/AST-025/spec.mdindex 5c4978ac9d..f5117e4957 100644--- a/docs/specs/AST-025/spec.md+++ b/docs/specs/AST-025/spec.md@@ -171,7 +171,8 @@ the behavior.the requested direction. A containment policy MAY stop chaining, but its`overscroll-behavior` effect MUST be active only on axes that currently overflow.This avoids dead scroll zones in engines that honor containment on non-overflowing- `overflow: auto` elements.+ `overflow: auto` elements. Inside a touch presentation under a finger, who+ gets a drag is decided once, when it begins (`spec:AST-094` FR14).- **FR15 — Native scrollbars are the default presentation.** The default presenterMUST preserve native scrolling and use standards-based CSS such as`scrollbar-width`, `scrollbar-color`, and `scrollbar-gutter` where supported.diff --git a/docs/specs/AST-094-touch-presentations/spec.md b/docs/specs/AST-094-touch-presentations/spec.mdnew file mode 100644index 0000000000..8fe4d4f46d--- /dev/null+++ b/docs/specs/AST-094-touch-presentations/spec.md@@ -0,0 +1,615 @@+---+schema_version: 4+template_version: 2+kind: system-spec+id: spec:AST-094+authority: current+archive_reason: null+superseded_by: null+approved_by: cixzhang+approved_at: 2026-10-24+phase: accepted+owners: [vjeux]+affects_architecture:+ [+ architecture:interaction-modality,+ architecture:theme-tokens,+ architecture:theme-authoring-contract,+ ]+affects_families: [family:buttons]+affects_contributing: []+affects_consumer_docs: []+---++# Touch presentations feel native system spec++## Intent++A person using an Astryx product on a phone or tablet gets controls, sheets,+menus, lists and navigation with native-feeling touch behavior: measured+physics, timings and gesture thresholds instead of desktop motion stretched to+a finger. This behavior is the default on every touch device, iOS and Android+alike, with no opt-in, and its motion keeps running at display rate while the+page's JavaScript is busy.++The behavior comes from one measured table. Its values are measured from UIKit+on a named reference release, UIKit on iOS 26.2 today; each number names the+release it was taken from, moving the reference to a newer release re-measures+the table, and differences on older releases are noted, not targeted. Android+touch devices get the same behavior. How touch behavior differs between the+platforms is being explored, and the table records a separate value only where+a measured, sourced difference exists.++## Non-goals++- Pointer (desktop) presentations. Their timing and easing stay with the+ theme's duration and easing tokens (`architecture:theme-tokens`).+- Platform-matched look and feel: glass versus material surfaces, glyphs and+ chrome. This record governs behavior only.+- WebKit embedded in a native app and the native Swift package. This record+ governs the web components themselves.+- Scroll physics. Scrolling stays native on every platform: on iOS an overflow+ area or the page is a UIKit scroll view already.+- Which components get a touch presentation, and when. Each component's own+ record owns its presentation.+- Equivalent internal implementations remain valid when they satisfy this+ contract. The modules, files and algorithms of the motion and gesture+ foundations belong to their architecture records.++## Requirements++### Physics++- **FR1 — Measured values, the same everywhere.** Every spring, duration,+ deceleration rate, rubber-band coefficient, gesture threshold and haptic+ moment a touch presentation uses MUST default to the measured native value+ for that use (FR2), and every component that plays the same motion or+ gesture MUST use the same value; a theme MAY override a motion role (FR4).+ No component uses a value of its own where a measured value exists. The same+ values apply on every touch platform; a platform gets a value of its own only+ where a measured, sourced difference exists (FR2).+- **FR2 — Every value has a source.** Each measured value MUST name its source next to it: Apple's documentation, a WWDC session, WebKit's own+ source where WebKit states it matches UIKit, or a measurement of UIKit on+ the iOS simulator naming the app, the iOS version, the method and the date.+ A value without one of these MUST be labelled a guess and name the+ measurement that will replace it. A decompilation of UIKit MAY aim a+ measurement and MUST NOT be a source. An owner decision MAY set a value+ that departs from a measurement; it names its date and the measurement it+ departs from.++ The values this record names for menus under a finger (FR29):++ | Value | Default | Source |+ | ---------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+ | Open delay | none in a fixed bar; 150 ms with no scroll inside a scroll view (the content-touch delay, FR11) | owner decision, 2026-10-24, departing from UIKit on the iOS 26.2 simulator (iPhone 17 Pro), 2026-10-23, which opened a held finger's menu 150–153 ms after touch-down in a fixed position and about 303 ms inside a scroll view |+ | Handoff distance | 10 pt (CSS px), straight-line, from the first position the open menu sees | measured: same setup; moves of (0, 9) and (7, 7) picked nothing, and (0, 10), (10, 0) and (9, 9) picked |+ | Drift allowance | 13 pt (CSS px) of movement on the trigger before the open | unmeasured, needs a measurement or justification: a 12 pt move still opened the menu and a 14 pt move did not (OQ5) |++- **FR3 — Native physics.** Springs MUST follow UIKit's spring model+ (response and damping ratio, mass, stiffness and damping, and the release+ velocity), with overdamping clamped to critical damping wherever UIKit+ clamps it. A momentum coast MUST decay like a UIKit scroll view (0.998 per+ millisecond, 0.99 for the fast rate), a drag past an edge MUST resist with+ UIKit's rubber band `(1 − 1 ÷ (x·c ÷ d + 1))·d` with the coefficient its use+ measures (0.55 for a scroll view and a sheet), and a release MUST pick its+ rest point by projecting its velocity the way its UIKit counterpart does:+ with a deceleration rate, or with a measured projection time.+- **FR4 — Touch motion is themeable.** Every spring, duration and curve a+ touch presentation plays MUST be a theme motion role named for its use+ (`architecture:theme-tokens` INV3). The roles this record names are listed below with their defaults and+ sources; further roles a component's own record measures join through the+ generated motion role table (DEC-5). The role's default value is+ its measured value (FR1, FR2), and a theme MAY override it through `motion`, at its root or+ in an adaptation rule. A component MUST read touch motion through these roles+ and MUST NOT play a literal. A theme value MUST reach the motion at its+ start, without changing how the motion runs (FR5, FR6). Motion that+ must stay in step with the on-screen keyboard is not a theme role: it rides+ the keyboard's own motion (`spec:AST-099` FR8,+ `architecture:react-component-runtime` INV11). Gesture thresholds, the timings that decide who gets a touch (the+ content-touch delay, the scroll brake, momentum memory) and haptics are not+ motion: they stay internal measured values and are not public concepts (`spec:AST-002` FR3). This adds touch motion roles to the motion+ configuration of `architecture:theme-authoring-contract` and to+ `architecture:theme-tokens` beside the existing duration and easing tokens, whose rules are unchanged. It departs from the draft `design:motion` DR3+ 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 |++### Motion++- **FR5 — Motion runs on the compositor.** Every release and every+ programmatic animation of a touch presentation MUST animate `transform`, the+ individual `translate`, `scale` and `rotate` properties, or `opacity`+ (a dialog's `::backdrop` included) through Web Animations that the browser+ runs off the main thread,+ and MUST keep advancing at display rate through a main-thread block. It MUST+ NOT animate layout properties, and MUST NOT step a frame from script when the+ compositor can run the curve.+- **FR6 — Motion is interruptible.** A finger MUST be able to catch any+ animation mid-flight at the value on screen. That value and its velocity+ MUST come from the curve, not from a layout read. A new target MUST keep the+ current velocity, and a release MUST hand its velocity to the spring that+ follows.+- **FR7 — Exits animate as the native counterpart's do.** A touch+ presentation MUST play the exit its UIKit counterpart plays, on every touch+ platform. FR8 governs their reduced-motion form. Each overlay's own record states its+ exit, since members own their animation (`family:overlay-dismissal` AV6).+- **FR8 — Reduce Motion.** Under reduced motion, touch presentations follow+ `design:reduced-motion` DR2 and DR4.++### Gestures++- **FR9 — A finger is tracked off the render path.** A drag MUST follow the+ finger with one visual update per move, with no component render per move+ and no layout read after the gesture begins.+ Native scrolling MUST be used only where the component is a scroll view+ (lists, scroll areas, the page). A component MAY track a finger with native+ scroll snapping only with simulator evidence that it tracks through a+ main-thread block, ends on the native release curve, ends correctly when the+ finger lifts during a block, and lets a finger catch the content mid-flight.+- **FR10 — A second finger never breaks the first.** A second finger MUST NOT+ cancel or redirect a drag a recognizer has claimed. Page pinch-zoom MUST stay+ the browser's whenever no pinch recognizer claims the fingers and no drag is+ claimed (WCAG 1.4.4). A menu's press-tracking slide keeps+ `module:DropdownMenu/useMenuPress` FR4: a second pointer or `pointercancel`+ ends its gesture with nothing acting, which keeps the page zoomable over an+ open menu.+- **FR11 — Two press profiles.** Press feedback MUST follow one of two native+ profiles. A control (UIControl) highlights on touch-down outside scroll+ views and activates by the browser's click on a lift inside. On the web a+ control's press ends when the browser takes the touch (FR20), and its+ activation stays the browser's click.+ A cell (a table or collection cell) highlights 150 ms after touch-down inside+ a scroll view, drops the highlight when the scroll wins, and activates on a+ lift inside it with no scroll. A control is inside a scroll view when it sits in a scrollable container,+ or in scrolling page content with no fixed ancestor; a control in a fixed+ bar (a top bar, a tab bar, a toolbar) is not. A control inside a scroll view+ takes the same 150 ms delay before its highlight and then follows its+ control profile; the 150 ms delay applies only inside scroll views. A control whose own record keeps its press through a drag+ keeps it: Slider's overlay stays on the dragged thumb (`design:user-states`+ DR4). On every touch platform this amends+ `design:user-states` DR1 (the pressed overlay during a hold) and DR3 (a held, selected SegmentedControl item keeps its raised selected+ surface; only its press timing follows the control profile) for touch+ presentations, the press treatment of `family:buttons`, and the last sentence of+ `module:DropdownMenu/useMenuPress` FR6 (menu rows paint `:active` only under+ `(hover: hover)`): under a finger, menu rows take the cell profile. FR6's+ rule that at most one row of a menu is lit still holds, so a finger that+ slides from one row to another lights only the row under it.+- **FR12 — Long press and rubber band are per use.** A long press MUST use the+ thresholds its UIKit counterpart uses: 0.5 s and 10 pt for a plain long+ press, the measured values for context menus and menus. A rubber band MUST+ use the coefficient its use measures.+- **FR13 — One rule for the touch presentation.** A touch presentation+ applies under a coarse primary pointer, and only after hydration: a server+ render and the hydrating render produce the pointer presentation+ (`spec:AST-013` FR9). Where a presentation also depends on size, compact is+ governed by `spec:AST-012` FR9 and `architecture:public-component-api`+ INV17. A presentation asks for exactly the conditions its own record names+ (the date and time sheet asks for the pointer only, `spec:AST-043` FR1).+ A style keyed on the literal touch media query conforms, since the server+ and hydrating markup are identical (DEC-6).+- **FR14 — Nested scrolling follows the native rule.** Who gets a drag that+ starts inside a scroll area MUST be decided once, when the drag begins. If+ the area sits at its edge and the drag moves toward that edge, the+ surrounding surface (a sheet) takes the drag; otherwise the area keeps it for+ the whole gesture and rubber-bands at its edge. The drag MUST NOT change+ hands midway, in either direction. This amends `spec:AST-025` FR14 (scroll+ chaining by default) for touch presentations on every touch platform.+- **FR15 — Recognizers arbitrate like UIKit's.** Recognizers that see the+ same touch sequence MUST be exclusive by default: the first to recognize+ wins and the others fail, unless both allow simultaneous recognition. A+ recognizer that requires another to fail MUST hold its recognition until+ that one fails, and MUST fail if that one recognizes. When several recognize+ on the same event, the innermost element's recognizer MUST win.+- **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.+- **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,+ and its translation excludes that travel. Release velocity is governed by `spec:AST-100`.+- **FR18 — `touch-action` leaves the browser the rest.** An element with touch+ recognizers MUST get a `touch-action` that leaves the browser exactly what+ its recognizers do not use: the other axis for an axis-limited pan or swipe,+ `manipulation` for taps and long presses, everything for a one-way pan or a+ pan that shares its axis with native scrolling. `pinch-zoom` MUST stay+ unless a pinch or rotation recognizer is attached.+- **FR19 — Claims are made in time and only by an owner.** Recognizers attach only where the primary pointer+ is coarse (FR13, DEC-6). Where the primary pointer is fine, no recognizer+ attaches and no touch listener is registered (FR24), so a finger on a+ touchscreen whose primary pointer is fine gets the browser's defaults for+ this record's behaviors (`spec:AST-017` FR59, DEC-25). This rule governs+ this record's behaviors only; `spec:AST-057` keeps its per-event pointer+ read for the row swipe, as its record states. A recognizer that begins MUST claim its touches by cancelling+ `touchmove` through a non-passive listener on its element; a watcher,+ which never claims, is exempt (DEC-7). A `touchmove` of a touch no recognizer owns MUST NOT be cancelled, with+ two exceptions. While a scroll lock under a modal presentation holds the+ page, it MAY cancel the moves of a one-finger touch that no recognizer owns+ when that pan would scroll the page; a second finger is never cancelled+ (FR10), and the page keeps pinch-zoom. Once its press is delivered, a+ control that keeps its press through a drag (FR11) owns its touch and MAY+ cancel that finger's moves. A+ recognizer that competes with native scrolling MUST decide within 10 px of+ travel, before the browser commits to the scroll. Only an element with a+ recognizer that must claim mid-gesture registers that blocking listener; an+ element whose recognizers decide only at the lift keeps its `touchmove`+ listener passive, and its `touchend` listener stays cancelable so the+ gesture can cancel the click (FR21). Known limit: a native scroll that starts on an element with a+ blocking listener waits for a free main thread in iOS Safari and Chromium.+ That is never worse than UIKit, whose scrolling stops on a busy main thread,+ and a passive listener, or one added at `touchstart`, would hand diagonal+ drags to the scroll.+- **FR20 — The browser can take a touch.** `pointercancel`, an uncancelable+ `touchmove`, or a native scroll under the touch MUST count as the browser+ taking the touch: possible recognizers that share it fail, active ones are+ cancelled, and the view's press is cancelled without a release. A recognizer that never claims (a watcher) registers only passive+ listeners (`architecture:react-component-runtime` INV3, INV5), and a+ watcher is not cancelled when the browser takes the touch: it follows the+ scroll to the lift (DEC-7).+- **FR21 — Clicks follow the gesture.** When a gesture takes a touch, its+ `touchend` MUST be cancelled, and no click or compatibility mouse event+ reaches the page. A click held for a recognizer that may still recognize (a+ tap that a double tap may claim) MUST be replayed on its target if that+ recognizer fails. Activation with `detail === 0` (keyboard, assistive+ technology) MUST always pass. A tap MUST NOT wait for the browser's+ double-tap delay.+- **FR22 — The platform keeps its edge gestures.** iOS Safari's back swipe+ from the screen edge and Android's system back gesture MUST stay the+ browser's and the system's; a touch presentation never overrides them.++### Menus and popovers under a finger++FR26–FR28 and FR30 apply to every surface that carries the press model of+`module:DropdownMenu/useMenuPress` (DropdownMenu, ContextMenu, their sub-menus,+and Selector's listbox, whose options count as rows) when a finger or pen+drives it and the primary pointer is coarse (FR19); where the primary pointer+is fine, a finger in a menu keeps today's behavior (`spec:AST-017` FR59,+DEC-25), and menus make no per-gesture pointer read; FR29 applies to DropdownMenu's trigger under the same+condition; FR34 applies to menus;+FR31 and FR35 apply to anchored menus and to Popover under a finger; FR32 and+FR33 apply to menus only. A mouse keeps today's behavior.++- **FR26 — The lift decides.** A menu row MUST act when the finger lifts over+ it, never because the press began on it; a press that never left its row is+ a tap and acts on that row. One gesture acts at most once: the browser's+ click for that gesture acts on nothing.+- **FR27 — The highlight follows the finger.** While a finger is held in an+ open menu, the lit row MUST be the enabled row under it, and nothing is lit+ over a divider, a heading, a disabled row or outside the menu. At most one+ row is lit; the row the press began on keeps no pressed look once the+ finger leaves it (FR11).+- **FR28 — A lift outside keeps the menu open.** A finger that began inside+ a menu and lifts outside it MUST act on nothing and leave the menu open. A+ cancelled touch, a second finger, or the window losing focus ends the+ gesture: nothing acts and the lit row clears.+- **FR29 — DropdownMenu opens on press, with the opening finger's+ handoff.** This rule covers DropdownMenu's trigger only; ContextMenu,+ sub-menu rows and Selector keep their own opening. Under a finger, a+ DropdownMenu trigger in a fixed bar MUST open its menu as the finger+ presses. A trigger inside a scroll view (FR11) MUST open it once the 150 ms+ content-touch delay has passed with no scroll, or at the lift of a tap that+ ends sooner; a scroll that starts first takes the touch and nothing opens. Before the open, the finger may move no+ more than the drift allowance (FR2). After an open under a held finger,+ nothing is lit and a lift acts on nothing until the finger has travelled+ the handoff distance from the first position the open menu sees; from then+ on FR26–FR28 apply. `presentation="popover"` keeps today's open on a tap;+ the default is unset (`architecture:public-component-api` INV16). The delay and distances are internal values and gain no new props+ (`spec:AST-002` FR3); A `module:DropdownMenu/useMenuPress` caller that sets the released+ `longPressDelayMs` gets that wait in a fixed bar and in a scroll view alike,+ which keeps the released behavior (`spec:AST-017` FR3).+- **FR30 — Edge autoscroll under a finger.** While a finger is held in a menu+ that scrolls, resting near its top or bottom edge MUST scroll the menu+ toward that edge, and the lit row MUST follow the row now under the finger.+ The scrolling stops when the finger leaves the edge, the menu reaches its+ end, or the gesture ends.+- **FR31 — Menus and popovers grow from their trigger and shrink back.**+ 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 theme motion roles (FR4; a menu on `springs.menuOpen` and+ `springs.menuClose`). 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.+- **FR32 — A pan outside dismisses.** Under a finger, an open anchored menu MUST close as a touch outside it+ begins to pan, and at the lift of a tap or hold outside it. A Popover's+ dismissal is unchanged. A pinch stays available over it: its surface+ never takes `touch-action: none`, so the page keeps zooming (FR10, FR18;+ WCAG 2.2 SC 1.4.4). Listening for that outside touch costs nothing once it ends (FR24). A menu+ whose caller passes `presentation="popover"` keeps its released outside+ dismissal (FR25).+- **FR33 — A ContextMenu under a finger.** With a finger or pen, the long+ press that opens a ContextMenu MUST NOT close it at the lift, and a press+ outside it follows FR32. After a held+ finger opens it, nothing is lit and a lift acts on nothing until that finger+ has travelled the handoff distance (FR2) from the first position the open+ menu sees; from then on FR26–FR28 apply. On every touch device, a ContextMenu that a held+ finger opens on a block trigger MUST lift the trigger above the page and+ show the menu beside it, with no row lit. A tap outside closes the menu and+ reaches nothing beneath it, and closing returns the trigger to its place.+ Under reduced motion FR8 applies. An inline trigger keeps today's menu, a menu presented as a+ bottom sheet follows the sheet, and `presentation="popover"` keeps the+ released menu without the lift (`architecture:public-component-api`+ INV16).+- **FR34 — A sub-menu drills in under a finger.** Under a finger on a+ compact touch screen, an `adaptive` sub-menu row MUST drill in: the+ sub-menu's rows and a leading "Back to <parent>" row replace the menu's rows+ in the same surface, no flyout opens, and Back returns to the row that+ opened it (`component:DropdownMenu` FR11 and FR20). The change between+ levels plays on the theme motion roles `springs.subMenuOpen` and+ `springs.subMenuBack` (FR4); under reduced motion FR8 applies.+- **FR35 — A presentation takes no input while it grows.** Under a finger, a+ tap or a drag that lands while a Popover or an anchored menu is still+ growing out of its trigger MUST NOT close it, scroll the page, move focus,+ or reach anything beneath it; the presentation finishes and stays open. A+ pinch still zooms the page (FR10). A mouse keeps today's behavior.++### Release decisions++- **FR36 — One decision, at the release.** A drag that can commit an action+ MUST decide once, when the finger lifts: if its projected travel (the+ travel so far plus the release velocity times the use's projection, FR3)+ reaches the use's commit point, the action commits; otherwise the surface+ springs back. The decision MUST NOT change while the surface settles. The+ same rule backs dismissing a BottomSheet, a Toast or a Lightbox, popping a+ NavigationStack, and dismissing the keyboard; each use's commit point and+ projection are measured values (FR1, FR2). A row swipe keeps+ `spec:AST-057`'s own release rule.+- **FR37 — Moving back cancels.** A release whose velocity points back+ toward the start MUST cancel, whatever the travel so far.+- **FR38 — The settle continues the finger.** The commit or the spring-back+ MUST start at the release velocity (FR6). Under reduced motion it follows+ `design:reduced-motion` DR2.+- **FR39 — The action never needs a drag.** Every action a drag commits MUST+ also be reachable without a drag, by keyboard and by mouse+ (`architecture:interaction-modality` INV4).+- **FR40 — Release velocity.** The velocity FR36–FR38 read is governed by+ `spec:AST-100`.++### Haptics++- **FR23 — Haptics where the native counterpart plays them.** A touch+ presentation MUST play a haptic only at the moments its UIKit counterpart+ does. In iOS Safari the only haptic a page can produce is a light impact from+ a real tap landing on a `<label>` or a switch checkbox; a moment UIKit marks+ mid-drag or after the lift has no haptic there, and the component records+ that gap. `navigator.vibrate` stands in where the platform offers it.++### Resources and compatibility++- **FR24 — Touch work costs nothing where it is not used.** Where the+ primary pointer is fine (FR19), and while a touch presentation is+ disabled, no touch-only listener, observer or timer is active, except the+ released `module:DropdownMenu/useMenuPress` behavior a finger keeps there+ (its FR9). The number of `document`- or `window`-level+ touch listeners MUST NOT grow with the number of component instances, a+ repeated row or cell adds no touch observer of its own, and nothing+ touch-related remains after the last instance unmounts+ (`architecture:react-component-runtime` INV5, INV7).+- **FR25 — A moved default keeps a way back.** Where a touch presentation+ moves a released default, the way back and its release note are governed by+ `architecture:public-component-api` INV16 and `spec:AST-017` DEC-23 and FR3.+ This record moves four: Selector's `adaptive` presentation policy;+ DropdownMenu's omitted `presentation`, released as `'popover'`, which+ `presentation="popover"` keeps (FR29); ContextMenu's omitted+ `presentation`, released as `'popover'`, which `presentation="popover"`+ keeps without the lift (FR33); and `module:DropdownMenu/useMenuPress`'s+ released 500 ms `longPressDelayMs`, which a caller keeps by passing it+ (FR29).+ This replaces `component:Selector` DEC-1's width-and-pointer query with the+ FR13 rule for `adaptive`.++### Platform support++- Supported engines: Astryx's supported browsers (`spec:AST-013`) with touch+ input, on iOS and Android. UIKit on the reference release is the parity+ reference, not a support floor; an older iOS Safari gets the same behavior+ wherever its engine supports it, and Android Chrome gets the same behavior.+ This amends `spec:AST-013` FR3 with an explicit Android Chrome support row+ for touch presentations.+- Unsupported behavior: haptics outside the moments FR23 allows. Where an+ engine cannot run a curve on its compositor, the animation still plays and+ still ends on its committed state.+- Browser evidence: the busy-main-thread proof and no layout or paint during+ the animation in Chromium with phone emulation, the busy-main-thread proof+ in WebKit, curves sampled by seeking the running animations, iOS simulator+ recordings for every claim about the reference values, and real-device+ evidence for every claim about iOS Safari and Android Chrome behavior+ (`spec:AST-013` FR10).++## Current-state impact++- `architecture:theme-tokens` and `architecture:theme-authoring-contract`:+ touch motion roles join the motion configuration, with the table's values as+ their defaults; INV3 and the duration and easing tokens are unchanged (FR4).+- `architecture:interaction-modality`: the touch-presentation conditions+ (FR13) sit beside the shared modality state; its invariants are unchanged.+- `architecture:react-component-runtime`: FR24 states the caller-visible+ outcome of INV5 and INV7 for touch work; both are unchanged.+- `family:buttons`: the control and cell press profiles (FR11).+- Each overlay member's own record (Dialog, BottomSheet, Drawer, Popover, the+ menus): its touch exit and its Reduce Motion cross-fade (FR7, FR8), since+ members own their animation (`family:overlay-dismissal` AV6).+- `design:reduced-motion` owns the reduced-motion rule FR8 applies.+- `component:Selector` DEC-1: `adaptive` resolves through the FR13 touch rule+ (a coarse pointer and the `spec:AST-012` FR9 compact definition) instead of+ its own width-and-pointer query, with `presentation` as the way back (FR25).+- `component:DropdownMenu` and `component:ContextMenu`: an omitted+ `presentation`, released as `'popover'`, follows FR29 and FR33 under a+ finger; `presentation="popover"` keeps the released behavior (FR25).+- `module:DropdownMenu/useMenuPress`: the released 500 ms `longPressDelayMs`+ default gives way to FR29's timing; a caller that passes it keeps it (FR25).+- `module:DropdownMenu/useMenuPress`: its finger rules (FR1–FR3, FR6, FR7+ and FR9 under a finger) are stated here (FR26–FR30); FR6's last sentence+ gives way to the cell press profile (FR11); its mouse rules (FR8 and the+ mouse halves of FR1–FR3) and its non-gesture rules stay in the module.+- `component:DropdownMenu`, `component:ContextMenu` and `component:Popover`:+ under a finger they follow FR26–FR35 as each applies.+- BottomSheet, Toast, Lightbox, NavigationStack and keyboard dismissal: a+ drag that commits follows FR36–FR40.+- `spec:AST-100` owns release velocity, which FR17 reads.+- `design:user-states` DR1 and DR3, `spec:AST-025` FR14 and `spec:AST-013` FR3+ each carry an amendment for touch presentations (FR11, FR14, Platform+ support); `design:motion` DR3 and DR5 (draft) are departed from or met as+ FR4 and FR8 state.+- 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).++## Verification++| Contract | Verification | Representative states | Mutation or failure expectation |+| --------------- | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| FR1, FR2 | Value check over every measured value and its uses | every value; a guess and its measurement task; a platform-specific value; two components playing the same motion | an unsourced value, an unknown source kind, a guess without a listed measurement, an unsourced platform split, or two values for one use fails |+| FR3 | Unit tests of the spring, decay, rubber band and projection math against an independent integration and values read from UIKit | under-, critically and overdamped springs; release velocities; both rates; overscroll depths | changing a formula or a constant breaks the agreement with UIKit's values |+| FR4 | Theme unit tests and a browser test of a themed spring | no theme (table defaults); a theme writing a spring, a duration and a curve, at its root and in an adaptation | a role that ignores the theme, a literal played in place of a role, or a default that differs from the table fails |+| FR5 | Browser proof: an animation keeps advancing frame by frame through a 1 s main-thread block, with no layout or paint per frame | Chromium phone emulation; WebKit | a script-driven or layout-animating implementation freezes or lays out |+| FR6 | Unit and browser tests catching an animation mid-flight and retargeting it | catch at peak velocity; retarget with a new spring | a layout read, a jump, or a lost velocity fails |+| FR7, FR8 | Component browser tests and storyboards with and without Reduce Motion | entrance, exit, move; a drag and its lift under Reduce Motion | a missing exit, any travel, scale or spring under Reduce Motion, or an opacity fade over 200 ms fails |+| FR9, FR10 | Recognizer unit tests on synthetic streams and browser tests with real touch input | drag, second finger, pinch, page zoom, main-thread block | a second finger that breaks a drag, or a blocked page pinch, fails |+| FR11, FR12 | Press and long-press tests on synthetic streams with explicit timestamps | inside and outside a scroll view; a drag the browser takes; a lift inside; a menu row under a finger | the wrong profile's timing, a press that survives the browser taking the touch, or a control activated other than by the browser's click 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 blocked main thread; a pan at 10 pt per axis | a wrong winner, a late deadline, or a translation that keeps the hysteresis fails |+| FR18–FR22 | Browser tests with real touch input | 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 ghost click, a blocked scroll or zoom, or a cancelled unowned touchmove outside FR19's two exceptions fails |+| FR23 | Haptics tests on the recorded moments | tap, drag, lift | a haptic outside a native moment fails |+| FR24 | Resource tests counting listeners, observers and timers | fine primary pointer; coarse pointer enabled and disabled; many instances; unmount | a touch listener on a fine pointer, a per-instance `document` or `window` listener, or a leak fails |+| FR25 | Component tests of each moved default and its `presentation` value | default; `presentation` set to the released surface | a moved default that `presentation` does not restore, or a public threshold, fails |+| FR26–FR28, FR30 | Menu press tests on synthetic touch streams and a real-Chromium touch test | a slide from one row to another; a lift outside; a cancel; a second finger; edge autoscroll | an act on the press-start row, two acts for one gesture, a lift outside that closes, or a lit row after a cancel fails |+| FR29 | Trigger tests with explicit timestamps | a press in a fixed bar; a press in scrolling content held 149 and 150 ms; a quick tap in scrolling content; a scroll before 150 ms; a drift of 12 and 14 pt; moves before and after the handoff; `presentation="popover"` | a fixed-bar press that waits, a held finger's scroll-view open before 150 ms or after a scroll, a quick tap that does not open at its lift, an open past the drift allowance, a lift that acts before the handoff, or a `popover` trigger that opens on press fails |+| FR31–FR33 | Browser tests and storyboards under a finger | a menu, a Popover and a ContextMenu lift: open, close, a pan outside, a tap outside, a pinch over the surface; a mouse | a surface that does not grow from and shrink into its trigger, a pan outside that leaves a menu open, a Popover whose dismissal changed, a blocked pinch, a tap outside that reaches the page, or a changed mouse path fails |+| FR34, FR35 | Browser tests and storyboards under a finger | a sub-menu drilling in and its Back row returning; a tap and a drag during a popover's and a menu's growth; a pinch during growth; a mouse | a drill-in that leaves the parent's rows in place, a change between levels that does not play on its roles, a tap during growth that closes, scrolls or moves focus, a blocked pinch, or a changed mouse path fails |+| FR36–FR40 | Release tests on synthetic touch streams with explicit timestamps, per use | below and past each commit point; a flick that projects past it; a slow drag past it; a release moving back; Reduce Motion; keyboard and mouse paths | a decision that changes mid-settle, a release moving back that commits, a settle that does not start at the release velocity, or an action with no keyboard or mouse path fails |+| all | iOS simulator: the UIKit reference capture and the same gesture in Safari; real iOS Safari and Android Chrome devices | per component | an unmatched curve or timing is a parity defect |++## Decision log++### DEC-1 — Touch presentations feel native by default++**Reference:** `spec:AST-094/DEC-1`+**Decider:** `cixzhang`, `2026-10-24`++Every touch device gets one native-feeling touch behavior by default, without+an opt-in, because the people using it already know that behavior from every+other app on their phone. The behavior's values are measured from UIKit, not+remembered: a number enters the table only with a citable source, and Android+touch devices get the same values until a measured, sourced difference is+recorded.++The table supplies the defaults and a theme may retune any motion role (FR4):+a product can soften a spring without forking a component, and the measured+values stay the ones it starts from. Platform-matched look and feel is not part+of this decision.++### DEC-2 — Recognizers track fingers; the compositor plays releases++**Reference:** `spec:AST-094/DEC-2`+**Decider:** `cixzhang`, `2026-10-24`++On iOS, native scroll snapping keeps tracking through a main-thread block,+but a finger that lifts during the block finishes on WebKit's own snap+physics rather than UIKit's curve, a finger cannot catch the content+mid-spring, and full-viewport hit testing breaks surfaces that leave the page+usable around them. Tracking therefore runs in the recognizers, and every+release runs as a compositor animation of the measured curve (FR5, FR9).++### DEC-3 — Touch motion is themeable; gesture thresholds are not++**Reference:** `spec:AST-094/DEC-3`+**Decider:** `cixzhang`, `2026-10-24`++A product tunes motion as it tunes color and type, so every touch spring,+duration and curve is a theme motion role whose default is the measured value+(FR4). Thresholds decide who gets a touch, not how anything looks, so they stay+internal (`spec:AST-002` FR3).++### DEC-4 — A finger opens a menu on press++**Reference:** `spec:AST-094/DEC-4`+**Decider:** `cixzhang`, `2026-10-24`++A trigger in a fixed bar has nothing to scroll, so its menu opens as the+finger presses; inside a scroll view the menu waits out the content-touch+delay so a scroll can still claim the touch (FR29). A caller's `presentation`+choice keeps today's open on a tap (`architecture:public-component-api`+INV16).++### DEC-5 — FR4 cites the generated motion role table++**Reference:** `spec:AST-094/DEC-5`+**Decider:** `cixzhang`, `2026-10-25`++FR4 lists the roles this record names, and cites the generated motion role+table, built from every registered table, for the roles a component's own+record measures, so a new component table cannot drift from the record.++### DEC-6 — CSS keyed on the touch media query counts as after hydration++**Reference:** `spec:AST-094/DEC-6`+**Decider:** `cixzhang`, `2026-10-25`++FR13's "only after hydration" governs a presentation decided in script. A+style keyed on the literal touch media query conforms: the server and+hydrating markup are identical, and the browser applies the style at first+paint.++### DEC-7 — A watcher recognizer is passive and follows the scroll++**Reference:** `spec:AST-094/DEC-7`+**Decider:** `cixzhang`, `2026-10-25`++A recognizer that never claims registers only passive listeners (FR20), so+watching a touch never delays the browser's scroll, and it is not cancelled+when the browser takes the touch: it follows the scroll to the lift, so a bar+that reacts to scrolling keeps hearing it.++## Open questions++- **OQ1 — Scroll view bounce-back curve.** What curve brings a scroll view+ back from an overscroll? It is not a single spring from rest; the rubber+ band itself is settled. (`checkable`)+- **OQ2 — Rotation threshold.** What rotation starts a rotation gesture? No+ stored threshold is readable, and the simulator cannot script two-finger+ rotation. (`checkable`)+- **OQ5 — The menu's drift allowance.** The 13 pt drift allowance (FR29)+ sits between a 12 pt move that opened the menu and a 14 pt move that did+ not. Is that bracket its justification, or does it need a finer+ measurement? (`owner decision`)+- **OQ6 — Opening a sub-menu without a lift.** A sub-menu drills in when a+ finger lifts on its row (FR26, FR34). Can a held finger also open it+ by resting on that row, and keep picking inside it without lifting?+ `module:DropdownMenu/useMenuPress` ORD1a covers only a mouse.+ (`owner decision`)+- **OQ7 — The opening haptic.** UIKit plays a haptic as a held finger+ opens a menu; a page in iOS Safari cannot (FR23). Where does the menu record+ that gap? (`owner decision`)+- **OQ8 — Withdrawing a tentative open.** What does a screen reader hear when+ a menu that a held finger opened is withdrawn by a cancel before the+ finger reached it? (`owner decision`)+- **OQ9 — Where a menu sits on a compact touch screen.** Should an anchored+ menu on a compact touch screen (`spec:AST-012` FR9) cover its trigger,+ centered on it and top-aligned with it, or bottom-aligned with it when the+ trigger's center is below the middle of the viewport, inside a fixed margin+ from the sides, as UIKit's menu does? `component:DropdownMenu` places the+ menu beside its trigger today. (`owner decision`)+- **OQ10 — A sub-menu with its parent visible.** Should a drilled-in sub-menu+ open in place, the menu's box growing to it with the parent menu visible+ behind it, as UIKit's menu does? This is look and feel; today the sub-menu's+ rows replace the parent's (FR34). (`owner decision`)diff --git a/packages/core/src/ContextMenu/ContextMenu.spec.md b/packages/core/src/ContextMenu/ContextMenu.spec.mdindex 00182e292b..9ad771e40d 100644--- a/packages/core/src/ContextMenu/ContextMenu.spec.md+++ b/packages/core/src/ContextMenu/ContextMenu.spec.md@@ -43,11 +43,15 @@ theming reachability.## Compatibility and migration-- Released default: `popover`-- Compatibility class: compatible behavior correction; public API, defaults,- DOM shape, styling, and targets are preserved+- Released default: `popover`. Under a finger, `spec:AST-094` FR33's lift+ becomes the default, and `presentation="popover"` keeps the released menu+ (`spec:AST-094` FR25).+- Compatibility class: compatible behavior correction; public API, DOM shape,+ styling, and targets are preserved; the default under a finger changes as+ above- Controlled/uncontrolled behavior: internally managed open state-- Migration decision: none+- Migration decision: `spec:AST-094` FR25 (a caller that needs the released+ menu under a finger passes `presentation="popover"`)Consumer migration instructions belong in consumer docs and release notes.@@ -81,17 +85,17 @@ Consumer props, content modes, and presentation policy remain documented in## Behavioral and layout contract-| ID | Candidate invariant | Basis | Draft review state |-| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | --------------------------------------------------- |-| FR1 | Every render contains a caller-provided Trigger area. 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 | Current behavior; verified |-| FR2 | The current `context-menu` target remains on the painted Pointer menu surface and alternative Touch menu surface, not on the Trigger area or cursor anchor. | Current source, docs, and tests | Current inventory; verified |-| 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 | Current delegation; verified |-| 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 | Current branches; verified |-| 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. Right-click, Shift+F10, long-press invocation and keyboard navigation keep their existing behavior. | `module:DropdownMenu/useMenuPress`; `ContextMenu.test.tsx` press model suite | Current module projection; verified in jsdom |-| FR6 | With `triggerAs="span"` the Trigger area MUST be 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. | `component:ContextMenu/DEC-1` | Accepted; verified in jsdom |-| FR7 | Sub-menu rows follow `component:DropdownMenu` FR12 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. | `component:DropdownMenu/DEC-2` | Proposed; verified in jsdom; owner decision pending |-| 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 DropdownMenu FR6; a held key's auto-repeat does not activate; typeahead matches the row's label element alone. | Current source and tests; shared `useListFocus` and `useTypeahead` suites | Proposed; verified in jsdom; owner decision pending |-| 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 | Current family projection; verified in jsdom |+| ID | Candidate invariant | Basis | Draft review state |+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | --------------------------------------------------- |+| FR1 | Every render contains a caller-provided Trigger area. 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 | Current behavior; verified |+| FR2 | The current `context-menu` target remains on the painted Pointer menu surface and alternative Touch menu surface, not on the Trigger area or cursor anchor. | Current source, docs, and tests | Current inventory; verified |+| 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 | Current delegation; verified |+| 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 | Current branches; verified |+| 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. Under a finger the press follows `spec:AST-094` FR26–FR28 and FR30, and the menu's grow, dismissal, long-press lift and outside press follow FR31–FR33 and FR35 (pending implementation); a mouse press outside is unchanged. Right-click, Shift+F10, long-press invocation and keyboard navigation keep their existing behavior. | `module:DropdownMenu/useMenuPress`; `ContextMenu.test.tsx` press model suite | Current module projection; verified in jsdom |+| FR6 | With `triggerAs="span"` the Trigger area MUST be 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. | `component:ContextMenu/DEC-1` | Accepted; verified in jsdom |+| FR7 | Sub-menu rows follow `component:DropdownMenu` FR12 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. | `component:DropdownMenu/DEC-2` | Proposed; verified in jsdom; owner decision pending |+| 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 DropdownMenu FR6; a held key's auto-repeat does not activate; typeahead matches the row's label element alone. | Current source and tests; shared `useListFocus` and `useTypeahead` suites | Proposed; verified in jsdom; owner decision pending |+| 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 | Current family projection; verified in jsdom |### Allowed variationdiff --git a/packages/core/src/DropdownMenu/DropdownMenu.spec.md b/packages/core/src/DropdownMenu/DropdownMenu.spec.mdindex 84fc7347d6..d1091b9a15 100644--- a/packages/core/src/DropdownMenu/DropdownMenu.spec.md+++ b/packages/core/src/DropdownMenu/DropdownMenu.spec.md@@ -50,12 +50,18 @@ highlight follows the pointer — is contracted by## Compatibility and migration-- Released default preserved: `yes`-- Compatibility class: additive documentation; the press-model behavior- delta is recorded in `module:DropdownMenu/useMenuPress`+- Released default preserved: `no` under a finger. The omitted+ `presentation`, released as `'popover'`, follows `spec:AST-094` FR29 (open+ on press) under a finger; `presentation="popover"` keeps the released+ behavior (`spec:AST-094` FR25). Mouse and keyboard are unchanged.+- Compatibility class: compatible behavior correction; public API, DOM+ shape, styling, and targets are preserved; the default under a finger+ changes as above, and the press-model behavior delta is recorded in+ `module:DropdownMenu/useMenuPress`- Controlled/uncontrolled behavior: unchanged- Migration decision: `module:DropdownMenu/useMenuPress/DEC-3`; proposed- `module:DropdownMenu/useMenuPress/DEC-4`+ `module:DropdownMenu/useMenuPress/DEC-4`; `spec:AST-094/DEC-4` (a caller+ that needs the released tap-open passes `presentation="popover"`)Consumer migration instructions belong in consumer docs and release notes.@@ -104,10 +110,10 @@ keeps its released default.| FR2 | The six current local targets are `dropdown-menu`, `dropdown-menu-item`, `dropdown-menu-radio`, `dropdown-menu-section-heading`, `dropdown-menu-divider`, and `dropdown-menu-indicator-icon`; every target remains on its current painted element. | Current source, docs, and tests | Verified current inventory; no target change || FR3 | Button owns the Trigger button, BottomSheet owns the Touch sheet frame, List owns the Touch action list and Touch action rows, Indicator owns checkbox chrome, and Icon owns ordinary rendered icons. | Current source and owner docs | Verified current delegation; no ownership change || FR4 | The same `dropdown-menu` target reaches the alternative Pointer menu surface and Touch menu surface. Pointer action rows retain `dropdown-menu-item`; touch action rows instead use List's `list-item` target. | Current source and tests | Verified modality split; no target change |-| FR5 | Both menu surfaces carry `data-astryx-menu-press` and follow `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 browser's stray click never acts, and the Pointer menu surface declares `touch-action` by overflow. Trigger opening and keyboard navigation are unchanged. | `module:DropdownMenu/useMenuPress`; `DropdownMenu.test.tsx` press model suite | Proposed; verified in jsdom and real Chromium |+| FR5 | Both menu surfaces carry `data-astryx-menu-press` and follow `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 browser's stray click never acts, and the Pointer menu surface declares `touch-action` by overflow. Under a finger the press, the menu's grow and collapse, and its dismissal follow `spec:AST-094` FR26–FR35 (pending implementation). Trigger opening and keyboard navigation are unchanged. | `module:DropdownMenu/useMenuPress`; `DropdownMenu.test.tsx` press model suite | Proposed; verified in jsdom and real Chromium || FR6 | When the pointer menu closes, focus returns to the Trigger button with a visible ring only when the menu was driven by keyboard; a press outside that landed on a focusable control keeps focus there. | `architecture:interaction-modality` INV1; proposed in this change; `DropdownMenu.test.tsx` closing suite | Proposed; verified in jsdom, pending owner review || FR7 | `menuMaxHeight` MUST replace the 300px term of the menu's and its popover viewport's block-size cap while the viewport gutters still bound both; the touch sheet ignores it. | `component:DropdownMenu/DEC-3` | Proposed; verified in jsdom; owner to confirm DEC-3 |-| FR8 | The Trigger button opens the pointer menu on a mouse press-down and on a finger held for the long-press delay, with the module's settle rule on the opening release; pressing the trigger of an open menu closes it without reopening in the same gesture; a tap and the keyboard open as before (`module:DropdownMenu/useMenuPress` proposed FR8, FR9). | Proposed `module:DropdownMenu/useMenuPress/DEC-4`; `DropdownMenu.test.tsx` press model suite | Proposed; verified in jsdom, pending owner review |+| FR8 | The Trigger button opens the pointer menu on a mouse press-down, with the module's settle rule on the opening release, and under a finger as `spec:AST-094` FR29 states; pressing the trigger of an open menu closes it without reopening in the same gesture; a mouse click and the keyboard open as before (`module:DropdownMenu/useMenuPress` proposed FR8, FR9). | Proposed `module:DropdownMenu/useMenuPress/DEC-4`; `DropdownMenu.test.tsx` press model suite | Proposed; verified in jsdom, pending owner review || Trigger source | `button` (Button props) or `renderTrigger` (render prop) | Which control the menu hangs off. `trigger` receives `DropdownMenuTriggerProps` — the press model, keyboard opens, toggle click and ARIA wiring — and names the menu. | Both presentations | `button` | `component:DropdownMenu` | stable | Both given: `trigger` wins and a dev warning fires. || FR9 | With `renderTrigger`, the rendered control MUST carry `aria-haspopup`, `aria-expanded`, `aria-controls` and the `id` the menu's `aria-labelledby` points at, and MUST receive the same press-model, keyboard-open and toggle-click handlers as the Button path; the menu is named by that control. `button` and `trigger` are mutually exclusive: both given, `trigger` wins and a dev warning fires, in both presentations. A drilled-in Back row (FR11) returns to the menu by that same name: the caller's `aria-label` when given, else the control's accessible name, read as the menu opens. | `component:DropdownMenu/DEC-2` | Proposed; verified in jsdom; owner to confirm DEC-2 || Row destination | `href` (+ `target`, `rel`) on an action item | The row's act is navigation: the row itself is the link (`family:navigation-destinations`). | Pointer action row and Touch action row, compound and data mode | none (an action row) | `component:DropdownMenu` | stable | Blocked schemes follow the family rule; a disabled row has none. |diff --git a/packages/core/src/DropdownMenu/modules/useMenuPress.spec.md b/packages/core/src/DropdownMenu/modules/useMenuPress.spec.mdindex 7bb64d1e8b..c11ad25bc6 100644--- a/packages/core/src/DropdownMenu/modules/useMenuPress.spec.md+++ b/packages/core/src/DropdownMenu/modules/useMenuPress.spec.md@@ -35,15 +35,15 @@ references:## Contract at a glance-| Area | Contract |-| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |-| Public contract | New public hook `useMenuPress` and the pure `menuPressStep` machine it drives, exported from `@astryxdesign/core/hooks`; the marker `data-astryx-menu-press` on every menu or listbox root that mounts it; PROPOSED in this change: the hook's trigger half (`onTriggerPress`, `triggerProps`, `isTriggerClickFromPress`, `longPressDelayMs`). No consumer prop of DropdownMenu, ContextMenu, DropdownMenuSubMenu or Selector changes. |-| Behavior | The row under the pointer when it is RELEASED is the row that acts; the highlight follows a held mouse, finger or pen; a mouse released outside closes the menu and a finger leaves it open; the browser's stray click for a tracked gesture never acts; the menu root declares `touch-action` by overflow. PROPOSED (FR8, FR9, DEC-4): a mouse opens a DropdownMenu on press-down and a finger held on its trigger opens it after the long-press delay, with a settle rule on the opening release. |-| End-user impact | A finger that lands on one menu row and lifts on another acts on the second, once, instead of on the first; a drag inside an open menu picks where it lets go; a mouse that lets go outside dismisses, a finger does not. PROPOSED: a mouse can press the trigger, drag into the menu and let go on a row in one gesture; a finger held on the trigger opens the menu without lifting. Keyboard behavior and sub-menu hover are unchanged. |-| Builder impact | None for consumers of the five surfaces: they mount the model themselves. A component CAN adopt this model only when it meets the eligibility criteria below, and its component contract MUST explicitly name this module and the governed surfaces before mounting `useMenuPress`. The builder supplies an enabled-row selector and a `touch-action` declaration. |-| Compatibility/readiness | Additive public hook; existing consumer props unchanged; shipped keyboard behavior unchanged. Shipped-behavior changes: DEC-3 (current; a mouse released outside a menu dismisses it) and PROPOSED DEC-4 (a mouse opens the menu on press rather than click; a tap is unchanged). jsdom evidence is complete and real-Chromium evidence covers the touch pan, the finger slide and its stray click; iOS WebKit evidence is not required for this module. Authority: current for FR1–FR7, DEC-3, DEC-6, DEC-7 (`cixzhang`, 2026-10-02); FR8, FR9 and DEC-4 are proposed in this change and await the same owner (OQ1). |-| Review checks | Reject a row that acts on `pointerdown` or from the browser's click after a tracked release; a second activation reaching a row for one gesture; a highlight that lights two rows; a finger release outside that closes the menu, or a mouse release outside that leaves it open; a menu root without a `touch-action` declaration; a picker whose listbox takes DOM focus for the highlight; an opening release that acts before the pointer entered the menu or the press settled; a trigger whose press and click both toggle in one gesture. |-| Governing rules | `architecture:interaction-modality` INV2–INV4 (one operable path per modality, hover as enhancement, menus may move focus with the pointer); `architecture:public-component-api` for the new public hook; `architecture:layer-runtime` for the native light dismiss the model leaves in place; `family:overlay-dismissal` for Escape ordering, which this module does not change. |+| Area | Contract |+| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| Public contract | New public hook `useMenuPress` and the pure `menuPressStep` machine it drives, exported from `@astryxdesign/core/hooks`; the marker `data-astryx-menu-press` on every menu or listbox root that mounts it; the hook's trigger half (`onTriggerPress`, `triggerProps`, `isTriggerClickFromPress`, `longPressDelayMs`), released in 0.6.6. No consumer prop of DropdownMenu, ContextMenu, DropdownMenuSubMenu or Selector changes. |+| Behavior | The row under the pointer when it is RELEASED is the row that acts; the highlight follows a held mouse; a mouse released outside closes the menu; the browser's stray click for a tracked gesture never acts; the menu root declares `touch-action` by overflow. Where the primary pointer is coarse, a finger or pen's press follows `spec:AST-094` FR26–FR30; where it is fine, FR1–FR7 and FR9 here apply to it. PROPOSED (FR8, DEC-4): a mouse opens a DropdownMenu on press-down, with a settle rule on the opening release. |+| End-user impact | A finger that lands on one menu row and lifts on another acts on the second, once, instead of on the first; a drag inside an open menu picks where it lets go; a mouse that lets go outside dismisses, a finger does not. PROPOSED: a mouse can press the trigger, drag into the menu and let go on a row in one gesture. Opening under a finger is `spec:AST-094` FR29's. Keyboard behavior and sub-menu hover are unchanged. |+| Builder impact | None for consumers of the five surfaces: they mount the model themselves. A component CAN adopt this model only when it meets the eligibility criteria below, and its component contract MUST explicitly name this module and the governed surfaces before mounting `useMenuPress`. The builder supplies an enabled-row selector and a `touch-action` declaration. |+| Compatibility/readiness | Additive public hook; existing consumer props unchanged; shipped keyboard behavior unchanged. Shipped-behavior changes: DEC-3 (current; a mouse released outside a menu dismisses it) and PROPOSED DEC-4 (a mouse opens the menu on press rather than click; under a finger, `spec:AST-094` FR29). jsdom evidence is complete and real-Chromium evidence covers the touch pan, the finger slide and its stray click; iOS WebKit evidence is not required for this module. Authority: current for FR1–FR7, DEC-3, DEC-6, DEC-7 (`cixzhang`, 2026-10-02); FR8 and DEC-4 are proposed in this change and await the same owner (OQ1). |+| Review checks | Reject a row that acts on `pointerdown` or from the browser's click after a tracked release; a second activation reaching a row for one gesture; a highlight that lights two rows; a finger release outside that closes the menu, or a mouse release outside that leaves it open; a menu root without a `touch-action` declaration; a picker whose listbox takes DOM focus for the highlight; an opening release that acts before the pointer entered the menu or the press settled; a trigger whose press and click both toggle in one gesture. |+| Governing rules | `architecture:interaction-modality` INV2–INV4 (one operable path per modality, hover as enhancement, menus may move focus with the pointer); `architecture:public-component-api` for the new public hook; `architecture:layer-runtime` for the native light dismiss the model leaves in place; `family:overlay-dismissal` for Escape ordering, which this module does not change. |This table is a review projection; the body below is authoritative.@@ -60,8 +60,9 @@ carries a separate press controller for an eligible surface.The module contracts the press model only. Menu anatomy, theming,presentation policy, keyboard navigation and item semantics stay with the-owning component records; trigger opening by keyboard and by a finger's tap-stays with the component that renders the trigger.+owning component records; trigger opening by keyboard stays with the component+that renders the trigger, and opening under a finger follows `spec:AST-094`+FR29.### Adoption eligibility@@ -80,13 +81,18 @@ adopter.## Compatibility and migration-- Released default preserved: `no` for one behavior (DEC-3: a mouse released- outside a menu now dismisses it); `yes` for every consumer prop and every- item, divider, section and presentation API+- Released default preserved: `no` for two behaviors: DEC-3 (a mouse+ released outside a menu now dismisses it), and an unset `longPressDelayMs`,+ whose released 500 ms wait gives way to `spec:AST-094` FR29's timing+ where the primary pointer is coarse;+ `yes` for every consumer prop and every item, divider, section and+ presentation API- Compatibility class: additive public hook and types; behavior change insidethe menu family- Migration decision: `module:DropdownMenu/useMenuPress/DEC-3`; proposed- `module:DropdownMenu/useMenuPress/DEC-4` (pending owner review)+ `module:DropdownMenu/useMenuPress/DEC-4` (pending owner review);+ `spec:AST-094` FR25 (a caller that needs the released 500 ms wait passes+ `longPressDelayMs: 500`)Consumer migration instructions belong in consumer docs and release notes.@@ -121,8 +127,8 @@ Consumer migration instructions belong in consumer docs and release notes.scroll and never listens for `scroll`.- Native light dismiss, Escape ordering and focus trapping — owned by`architecture:layer-runtime` and `family:overlay-dismissal`.-- Opening a menu from its trigger by keyboard or by a finger's tap — owned by the- component that renders the trigger.+- Opening a menu from its trigger by keyboard — owned by the component that+ renders the trigger; under a finger, `spec:AST-094` FR29 governs it.- Keyboard navigation, typeahead and Enter/Space activation — owned by`useListFocus`, `useTypeahead` and the component records.- Hover-to-open of sub-menu flyouts — owned by `useMenuHover`.@@ -130,32 +136,32 @@ Consumer migration instructions belong in consumer docs and release notes.## Public API and concepts-| Concept | Closed values or states | Meaning | Default | Owner | Stability |-| ------------------------ | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- | ---------------------------------- | --------- |-| gesture phase | `idle`, `tracking`; proposed `triggerPress`, `open` | where the press in flight stands | `idle` | `module:DropdownMenu/useMenuPress` | stable |-| effect | `none`, `highlight`, `clear`, `act`, `settle`; proposed `open` | what one event makes the host do; `open` asks the trigger to open the menu under the held pointer; `settle` carries `stray` (swallow the browser's click) and `dismiss` (close the menu) | — | `module:DropdownMenu/useMenuPress` | stable |-| pointer type | `mouse`, `touch`, `pen` | the gesture's own pointer; `touch` and `pen` are "a finger" | from the event | `module:DropdownMenu/useMenuPress` | stable |-| enabled-row selector | caller string | the rows a release may act on; anything else inside the root highlights nothing | required | `module:DropdownMenu/useMenuPress` | stable |-| highlight | DOM focus, or a caller callback | one lit row; focus with `preventScroll` in a menu, `aria-activedescendant` in a picker | focus | `module:DropdownMenu/useMenuPress` | stable |-| stray-click window | 400 ms, or the next `pointerdown` | how long after a tracked release the browser's click is still swallowed | `MENU_PRESS_STRAY_CLICK_MS` | `module:DropdownMenu/useMenuPress` | stable |-| settle time | 300 ms | proposed: how long an opening press must last before its release may act | `MENU_PRESS_SETTLE_MS` | `module:DropdownMenu/useMenuPress` | proposed |-| long-press delay | 500 ms | proposed: how long a finger rests on the trigger before the menu opens under it | `longPressDelayMs` | `module:DropdownMenu/useMenuPress` | proposed |-| `data-astryx-menu-press` | present or absent | the root carries this model; a host controller of its own stands aside | present on every mounted root | `module:DropdownMenu/useMenuPress` | stable |-| activation click | `click` with `detail: 0`, the release's button and modifiers | how the model acts on a row, marked for the synchronous extent by `isMenuPressActivation()`; `detail === 0` alone therefore no longer means "keyboard" on a menu row | — | `module:DropdownMenu/useMenuPress` | stable |+| Concept | Closed values or states | Meaning | Default | Owner | Stability |+| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- | ---------------------------------- | --------- |+| gesture phase | `idle`, `tracking`; proposed `triggerPress`, `open` | where the press in flight stands | `idle` | `module:DropdownMenu/useMenuPress` | stable |+| effect | `none`, `highlight`, `clear`, `act`, `settle`; proposed `open` | what one event makes the host do; `open` asks the trigger to open the menu under the held pointer; `settle` carries `stray` (swallow the browser's click) and `dismiss` (close the menu) | — | `module:DropdownMenu/useMenuPress` | stable |+| pointer type | `mouse`, `touch`, `pen` | the gesture's own pointer; `touch` and `pen` are "a finger" | from the event | `module:DropdownMenu/useMenuPress` | stable |+| enabled-row selector | caller string | the rows a release may act on; anything else inside the root highlights nothing | required | `module:DropdownMenu/useMenuPress` | stable |+| highlight | DOM focus, or a caller callback | one lit row; focus with `preventScroll` in a menu, `aria-activedescendant` in a picker | focus | `module:DropdownMenu/useMenuPress` | stable |+| stray-click window | 400 ms, or the next `pointerdown` | how long after a tracked release the browser's click is still swallowed | `MENU_PRESS_STRAY_CLICK_MS` | `module:DropdownMenu/useMenuPress` | stable |+| settle time | 300 ms | proposed: how long an opening press must last before its release may act | `MENU_PRESS_SETTLE_MS` | `module:DropdownMenu/useMenuPress` | proposed |+| long-press delay | released 500 ms when set; unset, as `spec:AST-094` FR29 states where the primary pointer is coarse (none in a fixed bar; 150 ms in a scroll view), and 500 ms where it is fine | how long a held finger waits on a trigger before the menu opens. A caller that sets `longPressDelayMs` gets that wait in a fixed bar and in a scroll view alike, which keeps the released behavior (`spec:AST-094` FR25). | `longPressDelayMs` | `module:DropdownMenu/useMenuPress` | stable |+| `data-astryx-menu-press` | present or absent | the root carries this model; a host controller of its own stands aside | present on every mounted root | `module:DropdownMenu/useMenuPress` | stable |+| activation click | `click` with `detail: 0`, the release's button and modifiers | how the model acts on a row, marked for the synchronous extent by `isMenuPressActivation()`; `detail === 0` alone therefore no longer means "keyboard" on a menu row | — | `module:DropdownMenu/useMenuPress` | stable |## Behavioral contract-| ID | Invariant | Basis | Verification state |-| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ |-| FR1 | A row MUST act when a press is released over it, never because the press began on it. A press that never left its row is a tap and acts on that row. | macOS and iOS menu behavior; `menuPressGesture.test.ts`, `useMenuPress.test.tsx` | verify |-| FR2 | While a press is held inside a menu, the highlighted row MUST be the enabled row under the pointer, and nothing MUST be highlighted over a divider, a heading, a disabled row, or outside the menu. A mouse moving with no button down moves the highlight the same way (existing hover-to-focus). | `architecture:interaction-modality` allowed variation for menus; `useMenuPress.test.tsx` | verify |-| FR3 | A press that began inside a menu and is released outside it MUST act on nothing. Under a mouse the menu MUST then close; under a finger or pen it MUST stay open. | DEC-3; `useMenuPress.test.tsx`, `DropdownMenu.test.tsx`, `Selector.test.tsx` | verify |-| FR4 | A menu whose rows fit MUST declare `touch-action: pinch-zoom`; one that scrolls MUST declare `touch-action: pan-y pinch-zoom` and `overscroll-behavior: contain`. Neither admits a one-finger pan the menu does not scroll, and both leave a two-finger pinch to the browser, so the page stays zoomable over an open menu. The model MUST treat `pointercancel` and a second pointer as the end of the gesture with nothing acting, and MUST NOT re-implement scrolling. | Browser scroll ownership; WCAG 2.2 SC 1.4.4 under `spec:AST-020` FR1; `DropdownMenu.test.tsx` touch-action case, `useMenuPress.test.tsx`, `MenuPinchZoom.a11y.chromium.spec.ts` | verify |-| FR5 | The click the browser reports for a gesture this model tracked MUST NOT act on any row; only the release acts. A click with no tracked gesture behind it, or one whose `detail` is 0, MUST act on its target as before. The swallower arms at a tracked release and disarms at the next `pointerdown` or after the stray-click window. | One gesture, one activation; `useMenuPress.test.tsx` FR5 suite | verify |-| FR6 | At most one row of a menu is lit. Under a finger the row a press began on MUST NOT keep a pressed or hovered look once the pointer left it, so menu rows paint `:active` only under `(hover: hover)`. | `DropdownMenuItem.tsx` styles | verify |-| FR7 | While a press is tracked in a menu that scrolls, a pointer resting within the edge zone of the menu's top or bottom MUST scroll the menu toward that edge and re-read the row under the pointer as the rows move. | `useMenuPress.test.tsx` autoscroll case | verify |-| FR8 | On a mouse a DropdownMenu trigger MUST open its menu on press-down (button 0, no Control), and a drag from the trigger into the menu that releases over an enabled row MUST act on it. The opening gesture's release MUST act only if the pointer entered the menu or the press lasted the settle time; otherwise nothing acts and the menu stays open. Pressing the trigger of an open menu MUST close it and MUST NOT reopen it in the same gesture. | Proposed DEC-4; `DropdownMenu.test.tsx` press model suite, `menuPressGesture.test.ts` trigger states | proposed; pending owner review |-| FR9 | Under a finger a tap on the trigger MUST open the menu through its click. A press held on the trigger for the long-press delay MUST open the menu with the finger down, prevent the default of the finger's later `touchmove`s until the gesture ends, and continue under FR1–FR4 with the same settle rule. | Proposed DEC-4; `DropdownMenu.test.tsx` held-touch case, `useMenuPress.test.tsx` | proposed; pending owner review |+| ID | Invariant | Basis | Verification state |+| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ |+| FR1 | A row MUST act when a press is released over it, never because the press began on it; a press that never left its row is a tap or click on that row. Where the primary pointer is coarse, a finger or pen follows `spec:AST-094` FR26 instead; where it is fine, a finger or pen keeps this rule (`spec:AST-094` FR19). | macOS and iOS menu behavior; `menuPressGesture.test.ts`, `useMenuPress.test.tsx` | verify |+| FR2 | While a press is held inside a menu, the highlighted row MUST be the enabled row under the pointer, and nothing MUST be highlighted over a divider, a heading, a disabled row, or outside the menu. A mouse moving with no button down moves the highlight the same way (existing hover-to-focus). Where the primary pointer is coarse, a finger or pen follows `spec:AST-094` FR27 and FR11's cell profile instead, and a second finger ends the gesture (FR4); where it is fine, a finger or pen keeps this rule (`spec:AST-094` FR19). | `architecture:interaction-modality` allowed variation for menus; `useMenuPress.test.tsx` | verify |+| FR3 | A press that began inside a menu and is released outside it MUST act on nothing. Under a mouse the menu MUST then close; under a finger or pen it MUST stay open (where the primary pointer is coarse, as `spec:AST-094` FR28 states). | DEC-3; `useMenuPress.test.tsx`, `DropdownMenu.test.tsx`, `Selector.test.tsx` | verify |+| FR4 | A menu whose rows fit MUST declare `touch-action: pinch-zoom`; one that scrolls MUST declare `touch-action: pan-y pinch-zoom` and `overscroll-behavior: contain`. Neither admits a one-finger pan the menu does not scroll, and both leave a two-finger pinch to the browser, so the page stays zoomable over an open menu. The model MUST treat `pointercancel` and a second pointer as the end of the gesture with nothing acting, and MUST NOT re-implement scrolling. | Browser scroll ownership; WCAG 2.2 SC 1.4.4 under `spec:AST-020` FR1; `DropdownMenu.test.tsx` touch-action case, `useMenuPress.test.tsx`, `MenuPinchZoom.a11y.chromium.spec.ts` | verify |+| FR5 | The click the browser reports for a gesture this model tracked MUST NOT act on any row; only the release acts. A click with no tracked gesture behind it, or one whose `detail` is 0, MUST act on its target as before. The swallower arms at a tracked release and disarms at the next `pointerdown` or after the stray-click window. | One gesture, one activation; `useMenuPress.test.tsx` FR5 suite | verify |+| FR6 | At most one row of a menu is lit. Under a finger the row a press began on MUST NOT keep a pressed or hovered look once the pointer left it, so menu rows paint `:active` only under `(hover: hover)`. Where the primary pointer is coarse, `spec:AST-094` FR27 and FR11 govern a finger's lit row and its press look instead. | `DropdownMenuItem.tsx` styles | verify |+| FR7 | While a press is tracked in a menu that scrolls, a pointer resting within the edge zone of the menu's top or bottom MUST scroll the menu toward that edge and re-read the row under the pointer as the rows move. Where the primary pointer is coarse, a finger or pen follows `spec:AST-094` FR30 instead; where it is fine, a finger or pen keeps this rule (`spec:AST-094` FR19). | `useMenuPress.test.tsx` autoscroll case | verify |+| FR8 | On a mouse a DropdownMenu trigger MUST open its menu on press-down (button 0, no Control), and a drag from the trigger into the menu that releases over an enabled row MUST act on it. The opening gesture's release MUST act only if the pointer entered the menu or the press lasted the settle time; otherwise nothing acts and the menu stays open. Pressing the trigger of an open menu MUST close it and MUST NOT reopen it in the same gesture. | Proposed DEC-4; `DropdownMenu.test.tsx` press model suite, `menuPressGesture.test.ts` trigger states | proposed; pending owner review |+| FR9 | Where the primary pointer is coarse, opening a menu from its trigger under a finger and the opening finger's handoff are governed by `spec:AST-094` FR29. Where it is fine, a finger keeps the released behavior (`spec:AST-094` FR19): a tap on the trigger opens the menu through its click, and a press held on the trigger for the long-press delay opens the menu with the finger down, prevents the default of the finger's later `touchmove`s until the gesture ends, and continues under FR1–FR4. | `spec:AST-094` FR29 | as `spec:AST-094` states |### Transformation and precedence order@@ -237,16 +243,16 @@ owned by the item components.## Verification map-| Contract | Verification | Representative states | Mutation or failure expectation |-| ---------------------- | -------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |-| FR1–FR3, FR5 | `menuPressGesture.test.ts` (one case per transition of the diagram) | idle, tracking; mouse and touch; releases over a row, over chrome, on the trigger, outside; cancel | Acting on the press row, on the stray click, or dismissing under a finger fails a transition case |-| FR1–FR5, FR7, AR1, AR3 | `useMenuPress.test.tsx` with an injected hit test | release over another row, tap, stray click, `detail: 0`, mouse/finger outside, pointercancel, second pointer, autoscroll | A second activation, a swallowed assistive click, a wrong dismissal, or a dead autoscroll fails |-| FR1, FR3–FR5 | `DropdownMenu.test.tsx`, `DropdownMenuSubMenu.test.tsx`, `ContextMenu.test.tsx` press suites | finger slide across rows, outside release by mouse and finger, `touch-action`, flyout release, root marker | Each removed behavior fails its named case |-| FR1, FR3, AR2 | `Selector.test.tsx` press model suite | finger release over another option, finger/mouse release outside, listbox marker | A listbox that takes focus, acts on the press option, or closes under a finger fails |-| FR4 (scroll) | `MenuPress.a11y.chromium.spec.ts` (real Chromium) | Chromium touch pan in an overflowing menu; touch-action by overflow; finger slide and its stray click | Not provable in jsdom; a pan that acts on a row, or a slide that acts on the press row, fails |-| FR4 (pinch) | `MenuPinchZoom.a11y.chromium.spec.ts` (real Chromium, phone emulation) | two-finger pinch over a menu whose rows fit, over one that scrolls, and over a picker listbox | Not provable in jsdom; a pinch that leaves the page at scale 1, or acts on a row, fails |-| FR8, FR9 (proposed) | `menuPressGesture.test.ts` trigger states; `useMenuPress.test.tsx` trigger suite; `DropdownMenu.test.tsx` press-open cases | mouse opens at once, finger tap, held finger, settle before/after, cancel; press-open + drag-release, unsettled release, trigger toggle, held touch, tap | A menu that does not open on a mouse press, an unsettled release that acts, or a trigger that reopens in the same gesture fails |-| ORD1a (proposed) | `DropdownMenuSubMenu.test.tsx` press cases; `SubMenuHeaderFooter.a11y.chromium.spec.ts` press-drag case | a mouse press on a menu row released on a row of a sub-menu rendered beside the menu; the same press released on that sub-menu's header field | A release on such a row that acts on nothing or closes the menu, or a release on its header field that acts, fails. |+| Contract | Verification | Representative states | Mutation or failure expectation |+| ---------------------- | -------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |+| FR1–FR3, FR5 | `menuPressGesture.test.ts` (one case per transition of the diagram) | idle, tracking; mouse and touch; releases over a row, over chrome, on the trigger, outside; cancel | Acting on the press row, on the stray click, or dismissing under a finger fails a transition case |+| FR1–FR5, FR7, AR1, AR3 | `useMenuPress.test.tsx` with an injected hit test | release over another row, tap, stray click, `detail: 0`, mouse/finger outside, pointercancel, second pointer, autoscroll | A second activation, a swallowed assistive click, a wrong dismissal, or a dead autoscroll fails |+| FR1, FR3–FR5 | `DropdownMenu.test.tsx`, `DropdownMenuSubMenu.test.tsx`, `ContextMenu.test.tsx` press suites | finger slide across rows, outside release by mouse and finger, `touch-action`, flyout release, root marker | Each removed behavior fails its named case |+| FR1, FR3, AR2 | `Selector.test.tsx` press model suite | finger release over another option, finger/mouse release outside, listbox marker | A listbox that takes focus, acts on the press option, or closes under a finger fails |+| FR4 (scroll) | `MenuPress.a11y.chromium.spec.ts` (real Chromium) | Chromium touch pan in an overflowing menu; touch-action by overflow; finger slide and its stray click | Not provable in jsdom; a pan that acts on a row, or a slide that acts on the press row, fails |+| FR4 (pinch) | `MenuPinchZoom.a11y.chromium.spec.ts` (real Chromium, phone emulation) | two-finger pinch over a menu whose rows fit, over one that scrolls, and over a picker listbox | Not provable in jsdom; a pinch that leaves the page at scale 1, or acts on a row, fails |+| FR8 (proposed), FR9 | `menuPressGesture.test.ts` trigger states; `useMenuPress.test.tsx` trigger suite; `DropdownMenu.test.tsx` press-open cases | mouse opens at once, settle before/after, cancel; finger opening per `spec:AST-094` FR29; press-open + drag-release, unsettled release, trigger toggle, held touch, tap | A menu that does not open on a mouse press, an unsettled release that acts, or a trigger that reopens in the same gesture fails |+| ORD1a (proposed) | `DropdownMenuSubMenu.test.tsx` press cases; `SubMenuHeaderFooter.a11y.chromium.spec.ts` press-drag case | a mouse press on a menu row released on a row of a sub-menu rendered beside the menu; the same press released on that sub-menu's header field | A release on such a row that acts on nothing or closes the menu, or a release on its header field that acts, fails. |## Decision log@@ -261,14 +267,13 @@ outside dismisses. Each pointer keeps its platform's answer. Closing for bothwould make a finger that slid off need a second gesture to reopen; stayingopen for both would surprise a mouse user.-### DEC-4 (proposed) — A mouse opens on press-down, a finger on a tap, with a settle rule+### DEC-4 (proposed) — A mouse opens on press-down, with a settle rule**Reference:** `module:DropdownMenu/useMenuPress/DEC-4`**Decider:** proposed by `vjeux`, `2026-09-27`; pending owner review-Press-to-open with drag-release is the macOS menu. A finger opens on a tap-because a page under a finger must stay scrollable; a held press opens with-the finger down so the fast path exists too. The release of the opening+Press-to-open with drag-release is the macOS menu. Opening under a finger+follows `spec:AST-094` FR29 and DEC-4. The release of the openinggesture acts only after the pointer has entered the menu or the press hassettled (300 ms), as a native pop-up button's does; otherwise a menu thatopens under the pointer would pick a row nobody chose.@@ -301,9 +306,9 @@ availability alone does not make a component an adopter.## Open questions- **OQ1 — Is press-to-open the menu family's trigger model?** (`human-design`)- The one owner decision this change needs: proposed FR8, FR9 and DEC-4 — a- mouse opens a DropdownMenu on press-down with the settle rule, a finger on- a tap or a held press. Until the owner rules, the current record's FR1–FR7+ The one owner decision this change needs: proposed FR8 and DEC-4 — a+ mouse opens a DropdownMenu on press-down with the settle rule. Opening under+ a finger is `spec:AST-094` FR29's. Until the owner rules, the current record's FR1–FR7stand on their own.The former browser-evidence question is resolved: the touch pan, the fingerdiff --git a/packages/core/src/Popover/Popover.spec.md b/packages/core/src/Popover/Popover.spec.mdindex 27b0a67301..4552cf0bad 100644--- a/packages/core/src/Popover/Popover.spec.md+++ b/packages/core/src/Popover/Popover.spec.md@@ -181,6 +181,7 @@ table owns their semantic effect.| FR6 | Component anatomy contains the caller trigger and content, one painted Popover surface, and the optional fallback close control. Popover owns no Header, Body, or separate shared-hook surface part. | Current source, docs target inventory, and tests | Accepted anatomy; stale consumer anatomy corrected by this contract || FR7 | The painted surface has one broad canonical target, `popover`; composed components may add one authoritative component-specific refinement target. | Owner direction on 2026-08-31 plus current target inventory | Accepted canonical contract; covered by focused target tests || FR8 | The surface padding is one spacing-scale rung applied on the painted surface. Popover defaults to step 3 (the released inset); `0` paints a flush surface; a direct `usePopover` composition paints none unless it asks for a rung. The rung sits where a theme's `padding` on the `popover` target replaces it. | PR #6683 and its Popover tests; `architecture:container-padding/INV8` (padding alone does not enroll) | Pending owner review (DEC-4); implemented and covered by the Popover surface-padding suite |+| FR9 | Under a finger, Popover grows out of its trigger and shrinks back into it, and a touch during its growth is ignored, as `spec:AST-094` FR31 and FR35 state. Its dismissal is unchanged, and a mouse keeps today's entrance. | `spec:AST-094` FR31, FR35 | Pending implementation; tests land with it |### Allowed variation@@ -328,6 +329,7 @@ consumers that need distinct theme reachability provide and document an owned| FR2, AR2–AR4 | `Popover.test.tsx` focus/role suites and `useFocusTrap.test.tsx` container-entry suites | Pointer, keyboard/AT-style, read-only, neutral role, no autofocus, controlled, Tab/Shift+Tab, Escape, focus return | Changing semantic destination by modality, selecting fallback close initially, losing shared indication, or allowing focus escape fails assertions. | `audit:Popover/accessibility` || ORD2, FR4 | `Popover.test.tsx` sizing/overflow suites; `Popover.stories.tsx` match-trigger and overflow scenarios; geometry under `Core/Layer` viewport-inset stories | Explicit width clamped to the viewport, trigger matching, fitting and overflowing content | Reversing width precedence, capping to the span beside the trigger, or always enabling scroll fails emitted-style or overflow assertions. | `audit:Popover/layout` || FR8 | `Popover.test.tsx` surface-padding suite | Default rung, `0`, an explicit rung, a direct hook composition with and without a rung | A default other than step 3, a rung landing on a box inside the surface, or the hook painting a rung it was not given fails the suite. | `audit:Popover/theming` |+| FR9 | `spec:AST-094` verification for FR31 and FR35 | Under a finger: open, close, a touch during growth; a mouse | A Popover that does not grow from and shrink into its trigger, a changed dismissal, or a changed mouse path fails. | `audit:Popover/behavior` || FR5 | `Popover.test.tsx` scheduling and observer-lifecycle suites | Closed, opened, repeated signals, cleanup | Constructing observers while closed or measuring more than once per pending frame fails lifecycle assertions. | `audit:Popover/resources` || FR6, FR7 and theming anatomy | `Popover.test.tsx`, `Popover.doc.mjs`, `usePopover.doc.mjs`, `astryx theme targets Popover --json`, and `scripts/check-knowledge.mjs` | One real surface with canonical `popover` plus composed-component refinements | A fake anatomy part, missing canonical output, or an active target without a real owner fails review or validation. | `audit:Popover/theming` || AR5 | `Popover.stories.tsx` manual-AT fixture and PR #5373 test record | Read-only dialog manual-AT fixture; no recorded NVDA/VoiceOver announcement result | A fixture without recorded AT/browser observations cannot be cited as announcement proof. | `audit:Popover/at-evidence` |diff --git a/packages/core/src/Selector/Selector.spec.md b/packages/core/src/Selector/Selector.spec.mdindex a66f26aced..a2e5724a39 100644--- a/packages/core/src/Selector/Selector.spec.md+++ b/packages/core/src/Selector/Selector.spec.md@@ -362,8 +362,9 @@ FR3 implements the system decision owned by `spec:AST-004/DEC-1`.An omitted `presentation` resolves `adaptive` (FR4): the modal bottom sheet oncompact coarse-pointer screens and the anchored popover elsewhere, so-fine-pointer and large-screen output matches `popover`. `adaptive` keeps its-width-and-pointer query; a pointer-only test belongs to `spec:AST-043` OQ1.+fine-pointer and large-screen output matches `popover`. `adaptive` resolves+through `spec:AST-094` FR13: a coarse primary pointer and the `spec:AST-012` FR9+compact definition.Rejected: keeping `popover` as the default, because a phone then gets apointer-sized anchored list unless the caller opts in.