From fed2e1c13b7eda6219864413d087d51f4010c4c3 Mon Sep 17 00:00:00 2001 From: Cindy Zhang Date: Mon, 26 Oct 2026 15:57:15 -0700 Subject: [PATCH 01/14] =?UTF-8?q?spec(AST-107):=20public=20gesture=20hooks?= =?UTF-8?q?=20=E2=80=94=20usePanGesture,=20useDragToSnapPoints,=20useAnima?= =?UTF-8?q?tor?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../AST-107-public-gesture-hooks/spec.md | 142 ++++++++++++++++++ 1 file changed, 142 insertions(+) create mode 100644 docs/specs/AST-107-public-gesture-hooks/spec.md diff --git a/docs/specs/AST-107-public-gesture-hooks/spec.md b/docs/specs/AST-107-public-gesture-hooks/spec.md new file mode 100644 index 0000000000000..8063c05d65e73 --- /dev/null +++ b/docs/specs/AST-107-public-gesture-hooks/spec.md @@ -0,0 +1,142 @@ +--- +schema_version: 4 +template_version: 2 +kind: system-spec +id: spec:AST-107 +authority: current +archive_reason: null +superseded_by: null +approved_by: cixzhang +approved_at: 2026-10-26 +phase: accepted +owners: [cixzhang] +affects_architecture: [architecture:public-component-api] +affects_families: [] +affects_contributing: [] +affects_consumer_docs: [usePanGesture, useDragToSnapPoints, useAnimator] +--- + +# Public gesture hooks system spec + + + +```json +{ + "paths": ["packages/core/src/hooks/**"] +} +``` + + + +## Intent + +A product can follow a drag, settle an element on snap points, and animate one +element with the same motion Core uses, through three public hooks. The hooks +hand out values, never the gesture machinery behind them, which stays +internal. + +## Non-goals + +- Recognizers, the gesture arena, the animator object, and the snap-point + resolver as public API; they stay internal (`spec:AST-017` FR21). +- Presses and long presses, which `useLongPress` owns. +- Animating the layout of an area, which `spec:AST-105` owns. +- Choosing a spring or curve, which lands with the public motion-token set + (`spec:AST-094` DEC-11). + +## Public contract + +```tsx +import { + usePanGesture, + useDragToSnapPoints, + useAnimator, +} from '@astryxdesign/core/hooks'; + +usePanGesture(ref, { + axis: 'x', + onPan: ({state, translation, velocity}) => {}, +}); + +const {settleTo} = useDragToSnapPoints(ref, { + axis: 'y', + snapPoints: [0, 240, 480], + flickThreshold: 500, + onSettle: index => {}, +}); + +const {ref: animatedRef, animator} = useAnimator(); +animator.animate({x: 120}); +``` + +## Requirements + +- **FR1 — `usePanGesture` reports a drag as values.** + `usePanGesture(ref, {axis?, onPan})` calls `onPan` with + `{state, translation, velocity}` as a drag on the element begins, changes, + ends, or is cancelled. `axis` limits the drag to `'x'` or `'y'`. It never + hands out a recognizer object, and it recognizes no press or long press. +- **FR2 — `useDragToSnapPoints` settles an element on snap points.** + `useDragToSnapPoints(ref, {axis, snapPoints, flickThreshold?, onSettle})` + lets a drag move the element along `axis`, and at the release settles it on + the snap point the release resolves to (`resolveSnapPoint`): a release faster + than `flickThreshold` carries to the next snap point in its direction, and a + drag that reverses before it ends is cancelled back to where it started. It + calls `onSettle(index)` once the element settles. It returns + `{settleTo(index)}`, which settles the element on a snap point without a + drag and is the keyboard path. +- **FR3 — `useAnimator` animates one element.** `useAnimator()` returns + `{ref, animator}`, where `animator` has `animate`, `decay`, `set`, `get`, + `getVelocity`, and `stop` for the one element `ref` attaches to. Reduce + Motion is planned for every animation (`design:reduced-motion` DR1–DR3). + Every animation plays on the default motion role; choosing a spring or curve + lands with the public motion-token set. +- **FR4 — One hook per job.** `usePanGesture` does not do presses or long + presses, which `useLongPress` owns. `useAnimator` animates one element, and + `useAnimatedLayout` animates an area (`spec:AST-105`). A component's own + props, such as BottomSheet's `snapPoints` or Carousel's `hasSnap`, stay the + component path to the same behavior. Everything else in the gesture and + motion modules stays internal (`architecture:public-component-api` INV21). + +- **FR5 — Each hook ships with docs and a playing-cards example.** Each public + API here, and `createReorderable`'s `positions` (`spec:AST-103`), ships with + docsite documentation: its usage, its options, its keyboard and + assistive-technology path, its Reduce Motion behavior, a note saying when to + use a component's own prop instead (FR4), and a live example. The flagship + example is a playing-cards demo built only on the public hooks: a card that + flicks and snaps back, cards that reorder by drag and by keyboard reorder + mode, a swipe that discards a card, and a fanned hand that uses custom + `positions`. + +## Current-state impact + +- Core gains the three hooks from `@astryxdesign/core/hooks`, their docsite + pages, and a playing-cards example. + +## Verification + +| Contract | Verification | Representative states | Mutation or failure expectation | +| -------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| FR1 | Unit and browser tests of `usePanGesture` | a drag on each axis, a cancel, a press, a long press | a recognizer in the result, a missing state, a drag off its axis, or a press or long press reported as a pan fails | +| FR2 | Unit and browser tests of `useDragToSnapPoints` | a slow release, a flick past `flickThreshold`, a reversed drag, `settleTo` from a key | a settle on the wrong snap point, a reversed drag that settles elsewhere, or a missing `onSettle` fails | +| FR3 | Unit and browser tests of `useAnimator` | each method, Reduce Motion, an unattached ref | a missing method, a spring other than the default role, or motion that ignores Reduce Motion fails | +| FR4 | Export check of `@astryxdesign/core` and its hooks | the public exports | a recognizer, arena, animator object, or resolver reachable from a public export fails | +| FR5 | Docsite review of each hook's page and the playing-cards example | each hook's page; the playing-cards demo | a hook without usage, options, a keyboard path, Reduce Motion, a component-prop note, or a live example, or a demo that imports anything but public hooks, fails | + +## Decision log + +### DEC-1 — Products get a public hook layer, not the gesture machinery + +**Reference:** `spec:AST-107/DEC-1` +**Decider:** `cixzhang`, `2026-10-26` + +Products need to follow drags, snap, and animate with the same motion Core +uses. Three hooks give them values and one method each to drive, while the +recognizers, the arena, and the animator stay internal, so Core can change +them without breaking products. + +Rejected: exporting the recognizers and the animator. + +## Open questions + +None. From eac7f2cd32025ba591a19ea76bf5becf6898591e Mon Sep 17 00:00:00 2001 From: Cindy Zhang Date: Mon, 26 Oct 2026 17:08:57 -0700 Subject: [PATCH 02/14] spec(AST-107): snap-point units and release rule as behavior; useAnimator's public handle and its motion role --- .../AST-107-public-gesture-hooks/spec.md | 46 +++++++++++-------- 1 file changed, 28 insertions(+), 18 deletions(-) diff --git a/docs/specs/AST-107-public-gesture-hooks/spec.md b/docs/specs/AST-107-public-gesture-hooks/spec.md index 8063c05d65e73..e77b608e0ba78 100644 --- a/docs/specs/AST-107-public-gesture-hooks/spec.md +++ b/docs/specs/AST-107-public-gesture-hooks/spec.md @@ -37,8 +37,8 @@ internal. ## Non-goals -- Recognizers, the gesture arena, the animator object, and the snap-point - resolver as public API; they stay internal (`spec:AST-017` FR21). +- Recognizers, the gesture arena, the internal animator module, and the + snap-point resolver as public API; they stay internal (`spec:AST-017` FR21). - Presses and long presses, which `useLongPress` owns. - Animating the layout of an area, which `spec:AST-105` owns. - Choosing a spring or curve, which lands with the public motion-token set @@ -78,19 +78,29 @@ animator.animate({x: 120}); hands out a recognizer object, and it recognizes no press or long press. - **FR2 — `useDragToSnapPoints` settles an element on snap points.** `useDragToSnapPoints(ref, {axis, snapPoints, flickThreshold?, onSettle})` - lets a drag move the element along `axis`, and at the release settles it on - the snap point the release resolves to (`resolveSnapPoint`): a release faster - than `flickThreshold` carries to the next snap point in its direction, and a - drag that reverses before it ends is cancelled back to where it started. It + lets a drag move the element along `axis`. `snapPoints` are offsets in + pixels along `axis` from the element's resting position, in ascending order; + unlike BottomSheet's `snapPoints`, they are not viewport fractions. At the + release the element settles on the nearest snap point to where it is, + except that a release faster than `flickThreshold`, in pixels per second + (default 500), carries to the next snap point in its direction, and a + release whose velocity points back toward where the drag started returns to + the snap point it started from (`spec:AST-094` FR37). It calls `onSettle(index)` once the element settles. It returns `{settleTo(index)}`, which settles the element on a snap point without a drag and is the keyboard path. - **FR3 — `useAnimator` animates one element.** `useAnimator()` returns - `{ref, animator}`, where `animator` has `animate`, `decay`, `set`, `get`, - `getVelocity`, and `stop` for the one element `ref` attaches to. Reduce - Motion is planned for every animation (`design:reduced-motion` DR1–DR3). - Every animation plays on the default motion role; choosing a spring or curve - lands with the public motion-token set. + `{ref, animator}` for the one element `ref` attaches to. `animator` is a + public handle, `AnimatorHandle`, over the channels `x`, `y`, `scale`, + `rotate`, and `opacity`, distinct from the internal animator module: + `animate(target, {velocity?}) → Promise` springs the given channels to + `target`; `decay(velocity) → Promise` coasts them from a velocity; + `set(values)` jumps them; `get()` and `getVelocity()` read them; and + `stop()` halts them where they are. Reduce Motion is planned for every + animation (`design:reduced-motion` DR1–DR3). Every `animate` plays on the + `springs.stateChange` motion role (`spec:AST-094` FR4), and `decay` on the + fixed momentum decay; choosing a spring or curve lands with the public + motion-token set. - **FR4 — One hook per job.** `usePanGesture` does not do presses or long presses, which `useLongPress` owns. `useAnimator` animates one element, and `useAnimatedLayout` animates an area (`spec:AST-105`). A component's own @@ -115,13 +125,13 @@ animator.animate({x: 120}); ## Verification -| Contract | Verification | Representative states | Mutation or failure expectation | -| -------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| FR1 | Unit and browser tests of `usePanGesture` | a drag on each axis, a cancel, a press, a long press | a recognizer in the result, a missing state, a drag off its axis, or a press or long press reported as a pan fails | -| FR2 | Unit and browser tests of `useDragToSnapPoints` | a slow release, a flick past `flickThreshold`, a reversed drag, `settleTo` from a key | a settle on the wrong snap point, a reversed drag that settles elsewhere, or a missing `onSettle` fails | -| FR3 | Unit and browser tests of `useAnimator` | each method, Reduce Motion, an unattached ref | a missing method, a spring other than the default role, or motion that ignores Reduce Motion fails | -| FR4 | Export check of `@astryxdesign/core` and its hooks | the public exports | a recognizer, arena, animator object, or resolver reachable from a public export fails | -| FR5 | Docsite review of each hook's page and the playing-cards example | each hook's page; the playing-cards demo | a hook without usage, options, a keyboard path, Reduce Motion, a component-prop note, or a live example, or a demo that imports anything but public hooks, fails | +| Contract | Verification | Representative states | Mutation or failure expectation | +| -------- | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| FR1 | Unit and browser tests of `usePanGesture` | a drag on each axis, a cancel, a press, a long press | a recognizer in the result, a missing state, a drag off its axis, or a press or long press reported as a pan fails | +| FR2 | Unit and browser tests of `useDragToSnapPoints` | a slow release, a flick past `flickThreshold` and the 500 px/s default, a release moving back, `settleTo` from a key | a settle on the wrong snap point, a reversed drag that settles elsewhere, or a missing `onSettle` fails | +| FR3 | Unit and browser tests of `useAnimator` | each method, Reduce Motion, an unattached ref | a missing method or channel, an `animate` off `springs.stateChange`, or motion that ignores Reduce Motion fails | +| FR4 | Export check of `@astryxdesign/core` and its hooks | the public exports | a recognizer, the arena, the internal animator module, or the resolver reachable from a public export fails | +| FR5 | Docsite review of each hook's page and the playing-cards example | each hook's page; the playing-cards demo | a hook without usage, options, a keyboard path, Reduce Motion, a component-prop note, or a live example, or a demo that imports anything but public hooks, fails | ## Decision log From 1d9b484cc47ce6e2ac69c0c55651c4f69da246f0 Mon Sep 17 00:00:00 2001 From: Cindy Zhang Date: Mon, 26 Oct 2026 17:10:59 -0700 Subject: [PATCH 03/14] spec(AST-107): flickThreshold defaults to the sheet's measured flick speed; animate follows the theme's motion knobs --- .../AST-107-public-gesture-hooks/spec.md | 29 ++++++++++--------- 1 file changed, 15 insertions(+), 14 deletions(-) diff --git a/docs/specs/AST-107-public-gesture-hooks/spec.md b/docs/specs/AST-107-public-gesture-hooks/spec.md index e77b608e0ba78..a4ce985a1bc0b 100644 --- a/docs/specs/AST-107-public-gesture-hooks/spec.md +++ b/docs/specs/AST-107-public-gesture-hooks/spec.md @@ -41,8 +41,8 @@ internal. snap-point resolver as public API; they stay internal (`spec:AST-017` FR21). - Presses and long presses, which `useLongPress` owns. - Animating the layout of an area, which `spec:AST-105` owns. -- Choosing a spring or curve, which lands with the public motion-token set - (`spec:AST-094` DEC-11). +- Choosing a spring or curve beyond the theme's motion knobs + (`spec:AST-108`). ## Public contract @@ -61,7 +61,7 @@ usePanGesture(ref, { const {settleTo} = useDragToSnapPoints(ref, { axis: 'y', snapPoints: [0, 240, 480], - flickThreshold: 500, + flickThreshold: 1008, onSettle: index => {}, }); @@ -83,7 +83,7 @@ animator.animate({x: 120}); unlike BottomSheet's `snapPoints`, they are not viewport fractions. At the release the element settles on the nearest snap point to where it is, except that a release faster than `flickThreshold`, in pixels per second - (default 500), carries to the next snap point in its direction, and a + (default 1008, the sheet's measured flick speed), carries to the next snap point in its direction, and a release whose velocity points back toward where the drag started returns to the snap point it started from (`spec:AST-094` FR37). It calls `onSettle(index)` once the element settles. It returns @@ -98,9 +98,10 @@ animator.animate({x: 120}); `set(values)` jumps them; `get()` and `getVelocity()` read them; and `stop()` halts them where they are. Reduce Motion is planned for every animation (`design:reduced-motion` DR1–DR3). Every `animate` plays on the - `springs.stateChange` motion role (`spec:AST-094` FR4), and `decay` on the - fixed momentum decay; choosing a spring or curve lands with the public - motion-token set. + `springs.stateChange` motion role (`spec:AST-094` FR4), which follows the + theme's tempo and character (`spec:AST-108` FR3), and `decay` on the fixed + momentum decay (`spec:AST-108` FR4); choosing any other spring or curve is + not offered. - **FR4 — One hook per job.** `usePanGesture` does not do presses or long presses, which `useLongPress` owns. `useAnimator` animates one element, and `useAnimatedLayout` animates an area (`spec:AST-105`). A component's own @@ -125,13 +126,13 @@ animator.animate({x: 120}); ## Verification -| Contract | Verification | Representative states | Mutation or failure expectation | -| -------- | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| FR1 | Unit and browser tests of `usePanGesture` | a drag on each axis, a cancel, a press, a long press | a recognizer in the result, a missing state, a drag off its axis, or a press or long press reported as a pan fails | -| FR2 | Unit and browser tests of `useDragToSnapPoints` | a slow release, a flick past `flickThreshold` and the 500 px/s default, a release moving back, `settleTo` from a key | a settle on the wrong snap point, a reversed drag that settles elsewhere, or a missing `onSettle` fails | -| FR3 | Unit and browser tests of `useAnimator` | each method, Reduce Motion, an unattached ref | a missing method or channel, an `animate` off `springs.stateChange`, or motion that ignores Reduce Motion fails | -| FR4 | Export check of `@astryxdesign/core` and its hooks | the public exports | a recognizer, the arena, the internal animator module, or the resolver reachable from a public export fails | -| FR5 | Docsite review of each hook's page and the playing-cards example | each hook's page; the playing-cards demo | a hook without usage, options, a keyboard path, Reduce Motion, a component-prop note, or a live example, or a demo that imports anything but public hooks, fails | +| Contract | Verification | Representative states | Mutation or failure expectation | +| -------- | ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| FR1 | Unit and browser tests of `usePanGesture` | a drag on each axis, a cancel, a press, a long press | a recognizer in the result, a missing state, a drag off its axis, or a press or long press reported as a pan fails | +| FR2 | Unit and browser tests of `useDragToSnapPoints` | a slow release, a flick past `flickThreshold` and the default flick speed, a release moving back, `settleTo` from a key | a settle on the wrong snap point, a reversed drag that settles elsewhere, or a missing `onSettle` fails | +| FR3 | Unit and browser tests of `useAnimator` | each method, Reduce Motion, an unattached ref | a missing method or channel, an `animate` off `springs.stateChange`, or motion that ignores Reduce Motion fails | +| FR4 | Export check of `@astryxdesign/core` and its hooks | the public exports | a recognizer, the arena, the internal animator module, or the resolver reachable from a public export fails | +| FR5 | Docsite review of each hook's page and the playing-cards example | each hook's page; the playing-cards demo | a hook without usage, options, a keyboard path, Reduce Motion, a component-prop note, or a live example, or a demo that imports anything but public hooks, fails | ## Decision log From 1f22c68af3e26be426fc9151e7d9a0188882b963 Mon Sep 17 00:00:00 2001 From: Cindy Zhang Date: Mon, 26 Oct 2026 20:41:32 -0700 Subject: [PATCH 04/14] spec(AST-107): non-React factories under the hooks; Core and Lab use the public layer (FR6, FR7, DEC-2); recognizers use a kind field --- docs/architecture/react-component-runtime.md | 6 +- .../AST-107-public-gesture-hooks/spec.md | 85 ++++++++++++++++--- 2 files changed, 78 insertions(+), 13 deletions(-) diff --git a/docs/architecture/react-component-runtime.md b/docs/architecture/react-component-runtime.md index c5af06119ec36..a2fa5352c703c 100644 --- a/docs/architecture/react-component-runtime.md +++ b/docs/architecture/react-component-runtime.md @@ -179,7 +179,11 @@ those contracts. - **INV13 — One shared set of internal touch modules.** Core's touch behavior comes from one always-present set of internal gesture and touch modules: the gesture core, the recognizers, the arena, the animator, and the - touch press recognizer. Components import them statically, and the bundler + touch press recognizer. The recognizer family (its base, the arena, and the + host) is the one place these modules use classes, and it uses no + inheritance checks: a recognizer is told apart by its `kind` field, never by + `instanceof`. Every other module, and every public layer, is built from + `create…` factories. Components import them statically, and the bundler keeps one copy per page however many components use them. There is no install call, no public entry, and no public installed check; tests reset the modules through an internal hook only. A component's own touch logic is diff --git a/docs/specs/AST-107-public-gesture-hooks/spec.md b/docs/specs/AST-107-public-gesture-hooks/spec.md index a4ce985a1bc0b..99bf6f63f45f7 100644 --- a/docs/specs/AST-107-public-gesture-hooks/spec.md +++ b/docs/specs/AST-107-public-gesture-hooks/spec.md @@ -31,7 +31,8 @@ affects_consumer_docs: [usePanGesture, useDragToSnapPoints, useAnimator] ## Intent A product can follow a drag, settle an element on snap points, and animate one -element with the same motion Core uses, through three public hooks. The hooks +element with the same motion Core uses, through three public factories and the +three React hooks over them. The hooks hand out values, never the gesture machinery behind them, which stays internal. @@ -47,6 +48,11 @@ internal. ## Public contract ```tsx +import { + createPanGesture, + createDragToSnapPoints, + createAnimator, +} from '@astryxdesign/core'; import { usePanGesture, useDragToSnapPoints, @@ -67,6 +73,18 @@ const {settleTo} = useDragToSnapPoints(ref, { const {ref: animatedRef, animator} = useAnimator(); animator.animate({x: 120}); + +// Without React: +const pan = createPanGesture(element, {axis: 'x', onPan: () => {}}); +const snap = createDragToSnapPoints(element, { + axis: 'y', + snapPoints: [0, 240, 480], + onSettle: index => {}, +}); +const animator2 = createAnimator(element); +pan.destroy(); +snap.destroy(); +animator2.destroy(); ``` ## Requirements @@ -109,30 +127,60 @@ animator.animate({x: 120}); component path to the same behavior. Everything else in the gesture and motion modules stays internal (`architecture:public-component-api` INV21). +- **FR6 — Each hook is a thin wrapper over a factory.** Each hook has a + non-React factory in the same `create…` family as `createReorderable`: + `createPanGesture(element, {axis?, onPan}) → {destroy}`, + `createDragToSnapPoints(element, {axis, snapPoints, flickThreshold?, +onSettle}) → {settleTo(index), destroy}`, and `createAnimator(element) → +{animate, decay, set, get, getVelocity, stop, destroy}`, with FR1–FR3's + behavior. A hook and its factory are one job at two layers + (`architecture:public-component-api` INV21): the hook delegates entirely to + its factory and has no behavior of its own. `destroy` removes every + listener the factory added, and importing a factory does no DOM work, so it + is safe on the server. +- **FR7 — Core and Lab use the public layer.** Wherever a public gesture or + motion API covers a component's job (the factories and hooks here, + `createReorderable`, and `useAnimatedLayout`), Core and Lab components MUST + use it rather than the internals beneath it. A component reaches internals + only for a job the public layer does not expose, and each such job is a + known public-API gap: + + | Job the public layer does not expose | Reached through internals for | + | ---------------------------------------- | ------------------------------- | + | Which of two gestures wins a touch | Recognizer relationships | + | Keeping a layer's chosen presentation | The presentation hold | + | Absorbing input while a layer enters | The input hold | + | Press feedback timing | Controls and cells | + | Growing a layer out of its trigger | Lift-from-trigger presentations | + | Press tracking across a group of actions | `family:action-groups` members | + - **FR5 — Each hook ships with docs and a playing-cards example.** Each public - API here, and `createReorderable`'s `positions` (`spec:AST-103`), ships with + API here, factory and hook alike, and `createReorderable`'s `positions` (`spec:AST-103`), ships with docsite documentation: its usage, its options, its keyboard and assistive-technology path, its Reduce Motion behavior, a note saying when to use a component's own prop instead (FR4), and a live example. The flagship - example is a playing-cards demo built only on the public hooks: a card that + example is a playing-cards demo built only on the public layer, once in + plain JavaScript with the factories and once in React with the hooks: a card that flicks and snaps back, cards that reorder by drag and by keyboard reorder mode, a swipe that discards a card, and a fanned hand that uses custom `positions`. ## Current-state impact -- Core gains the three hooks from `@astryxdesign/core/hooks`, their docsite - pages, and a playing-cards example. +- Core gains the three factories and the three hooks over them, their docsite + pages, and a playing-cards example in plain JavaScript and in React. ## Verification -| Contract | Verification | Representative states | Mutation or failure expectation | -| -------- | ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| FR1 | Unit and browser tests of `usePanGesture` | a drag on each axis, a cancel, a press, a long press | a recognizer in the result, a missing state, a drag off its axis, or a press or long press reported as a pan fails | -| FR2 | Unit and browser tests of `useDragToSnapPoints` | a slow release, a flick past `flickThreshold` and the default flick speed, a release moving back, `settleTo` from a key | a settle on the wrong snap point, a reversed drag that settles elsewhere, or a missing `onSettle` fails | -| FR3 | Unit and browser tests of `useAnimator` | each method, Reduce Motion, an unattached ref | a missing method or channel, an `animate` off `springs.stateChange`, or motion that ignores Reduce Motion fails | -| FR4 | Export check of `@astryxdesign/core` and its hooks | the public exports | a recognizer, the arena, the internal animator module, or the resolver reachable from a public export fails | -| FR5 | Docsite review of each hook's page and the playing-cards example | each hook's page; the playing-cards demo | a hook without usage, options, a keyboard path, Reduce Motion, a component-prop note, or a live example, or a demo that imports anything but public hooks, fails | +| Contract | Verification | Representative states | Mutation or failure expectation | +| -------- | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| FR1 | Unit and browser tests of `usePanGesture` | a drag on each axis, a cancel, a press, a long press | a recognizer in the result, a missing state, a drag off its axis, or a press or long press reported as a pan fails | +| FR2 | Unit and browser tests of `useDragToSnapPoints` | a slow release, a flick past `flickThreshold` and the default flick speed, a release moving back, `settleTo` from a key | a settle on the wrong snap point, a reversed drag that settles elsewhere, or a missing `onSettle` fails | +| FR3 | Unit and browser tests of `useAnimator` | each method, Reduce Motion, an unattached ref | a missing method or channel, an `animate` off `springs.stateChange`, or motion that ignores Reduce Motion fails | +| FR4 | Export check of `@astryxdesign/core` and its hooks | the public exports | a recognizer, the arena, the internal animator module, or the resolver reachable from a public export fails | +| FR6 | Unit tests of each factory and its hook, server-render and import checks, and listener counts after `destroy` | each factory without React; each hook; a server import; `destroy` mid-drag | a hook with behavior its factory lacks, a listener left after `destroy`, or DOM work at import fails | +| FR7 | Source boundary check over Core and Lab against the gap table | every Core and Lab component that drags, snaps, animates one element, reorders, or animates layout | a component reaching internals for a job the public layer covers, or an internal use whose job is not in the gap table, fails | +| FR5 | Docsite review of each hook's page and the playing-cards example | each hook's page; the playing-cards demo | a hook without usage, options, a keyboard path, Reduce Motion, a component-prop note, or a live example, or a demo that imports anything but public hooks, fails | ## Decision log @@ -148,6 +196,19 @@ them without breaking products. Rejected: exporting the recognizers and the animator. +### DEC-2 — Factories under the hooks, and Core uses the public layer + +**Reference:** `spec:AST-107/DEC-2` +**Decider:** `cixzhang`, `2026-10-26` + +A product without React, or one that manages its own elements, needs the same +gestures, so each hook is a thin wrapper over a `create…` factory, the family +`createReorderable` already uses. Core and Lab build on the same public layer +wherever it covers their job, so its gaps are visible and listed rather than +hidden behind internals. + +Rejected: hooks only, and components that bypass the public layer. + ## Open questions None. From ab539aac7d5db94dd5ca625b64871c3a1673c6fb Mon Sep 17 00:00:00 2001 From: Cindy Zhang Date: Mon, 26 Oct 2026 20:42:54 -0700 Subject: [PATCH 05/14] spec(AST-107): the public createAnimator is Core's one animator factory --- docs/specs/AST-107-public-gesture-hooks/spec.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/specs/AST-107-public-gesture-hooks/spec.md b/docs/specs/AST-107-public-gesture-hooks/spec.md index 99bf6f63f45f7..b22b9267be64c 100644 --- a/docs/specs/AST-107-public-gesture-hooks/spec.md +++ b/docs/specs/AST-107-public-gesture-hooks/spec.md @@ -137,7 +137,9 @@ onSettle}) → {settleTo(index), destroy}`, and `createAnimator(element) → (`architecture:public-component-api` INV21): the hook delegates entirely to its factory and has no behavior of its own. `destroy` removes every listener the factory added, and importing a factory does no DOM work, so it - is safe on the server. + is safe on the server. The public `createAnimator` is Core's one + animator factory: Core's internal animator either is this factory or takes + another name, and no internal factory shares a public factory's name. - **FR7 — Core and Lab use the public layer.** Wherever a public gesture or motion API covers a component's job (the factories and hooks here, `createReorderable`, and `useAnimatedLayout`), Core and Lab components MUST From b1d8762c8f6b0fe34ff69eb85e8bb14eef0e80b7 Mon Sep 17 00:00:00 2001 From: Cindy Zhang Date: Mon, 26 Oct 2026 20:43:55 -0700 Subject: [PATCH 06/14] spec(AST-107): the full known-gap table; attach covers non-List collections --- .../AST-107-public-gesture-hooks/spec.md | 29 ++++++++++++------- 1 file changed, 19 insertions(+), 10 deletions(-) diff --git a/docs/specs/AST-107-public-gesture-hooks/spec.md b/docs/specs/AST-107-public-gesture-hooks/spec.md index b22b9267be64c..eebfac6789919 100644 --- a/docs/specs/AST-107-public-gesture-hooks/spec.md +++ b/docs/specs/AST-107-public-gesture-hooks/spec.md @@ -145,16 +145,25 @@ onSettle}) → {settleTo(index), destroy}`, and `createAnimator(element) → `createReorderable`, and `useAnimatedLayout`), Core and Lab components MUST use it rather than the internals beneath it. A component reaches internals only for a job the public layer does not expose, and each such job is a - known public-API gap: - - | Job the public layer does not expose | Reached through internals for | - | ---------------------------------------- | ------------------------------- | - | Which of two gestures wins a touch | Recognizer relationships | - | Keeping a layer's chosen presentation | The presentation hold | - | Absorbing input while a layer enters | The input hold | - | Press feedback timing | Controls and cells | - | Growing a layer out of its trigger | Lift-from-trigger presentations | - | Press tracking across a group of actions | `family:action-groups` members | + known public-API gap. `createReorderable`'s plain-element attach path covers + collections that are not List, such as Lab's TransferList and ListInput. + + | Public-API gap | Used internally by | + | -------------------------------------------------------------------- | ---------------------------------- | + | Press feedback timing | controls and cells | + | Reduced Motion cross-fade constants | every Reduce Motion fade | + | Press tracking across a group of actions (`actionGroupTracker`) | `family:action-groups` members | + | Selection lock during a gesture (`selectionLock`) | gestures that block text selection | + | Keeping a layer's chosen presentation (the presentation hold) | layers | + | Absorbing input while a layer enters (the input hold) | layers | + | Growing a layer out of its trigger (`liftFromTrigger`, `rectMorph`) | lift-from-trigger presentations | + | Which of two gestures wins a touch (custom recognizer relationships) | nested gestures | + | Gesture host, velocity tracking, rubber band, and haptics | the gesture foundations | + | Long press, which has no public factory yet | long-press surfaces | + | Spring and curve helpers and UIKit's measured tables | motion foundations | + | The touch presentation query | touch presentations | + | Layout-change reporting, internal by `spec:AST-105` FR1 | animated layout | + | Touch hit-area expansion (`utils/hitArea`) | coarse-pointer targets | - **FR5 — Each hook ships with docs and a playing-cards example.** Each public API here, factory and hook alike, and `createReorderable`'s `positions` (`spec:AST-103`), ships with From 19cf1780b7ae9aee88153e758577484468ab1c02 Mon Sep 17 00:00:00 2001 From: Cindy Zhang Date: Mon, 26 Oct 2026 20:50:43 -0700 Subject: [PATCH 07/14] =?UTF-8?q?spec(AST-107):=20a=20headless=20context?= =?UTF-8?q?=20menu=20=E2=80=94=20createContextMenu=20and=20useContextMenu?= =?UTF-8?q?=20(FR8,=20DEC-3)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../AST-107-public-gesture-hooks/spec.md | 42 ++++++++++++++----- 1 file changed, 32 insertions(+), 10 deletions(-) diff --git a/docs/specs/AST-107-public-gesture-hooks/spec.md b/docs/specs/AST-107-public-gesture-hooks/spec.md index eebfac6789919..2eca6ebd8e3a1 100644 --- a/docs/specs/AST-107-public-gesture-hooks/spec.md +++ b/docs/specs/AST-107-public-gesture-hooks/spec.md @@ -165,6 +165,14 @@ onSettle}) → {settleTo(index), destroy}`, and `createAnimator(element) → | Layout-change reporting, internal by `spec:AST-105` FR1 | animated layout | | Touch hit-area expansion (`utils/hitArea`) | coarse-pointer targets | +- **FR8 — A headless context menu.** `createContextMenu(element, {items | +render, onOpenChange?, presentation?}) → {open(at?), close(), destroy()}` + attaches a context menu to any element: it opens on the element's context + request (a long press, a right click, or Shift+F10), at `at` when given, and + `destroy` removes every listener it added. `useContextMenu(ref, options) → +{open, close}` is its thin React wrapper (FR6), and `component:ContextMenu` + is built on it (FR7): one job at two layers + (`architecture:public-component-api` INV21). - **FR5 — Each hook ships with docs and a playing-cards example.** Each public API here, factory and hook alike, and `createReorderable`'s `positions` (`spec:AST-103`), ships with docsite documentation: its usage, its options, its keyboard and @@ -178,20 +186,22 @@ onSettle}) → {settleTo(index), destroy}`, and `createAnimator(element) → ## Current-state impact -- Core gains the three factories and the three hooks over them, their docsite +- Core gains the three factories and the three hooks over them, the headless + context menu and its hook, their docsite pages, and a playing-cards example in plain JavaScript and in React. ## Verification -| Contract | Verification | Representative states | Mutation or failure expectation | -| -------- | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| FR1 | Unit and browser tests of `usePanGesture` | a drag on each axis, a cancel, a press, a long press | a recognizer in the result, a missing state, a drag off its axis, or a press or long press reported as a pan fails | -| FR2 | Unit and browser tests of `useDragToSnapPoints` | a slow release, a flick past `flickThreshold` and the default flick speed, a release moving back, `settleTo` from a key | a settle on the wrong snap point, a reversed drag that settles elsewhere, or a missing `onSettle` fails | -| FR3 | Unit and browser tests of `useAnimator` | each method, Reduce Motion, an unattached ref | a missing method or channel, an `animate` off `springs.stateChange`, or motion that ignores Reduce Motion fails | -| FR4 | Export check of `@astryxdesign/core` and its hooks | the public exports | a recognizer, the arena, the internal animator module, or the resolver reachable from a public export fails | -| FR6 | Unit tests of each factory and its hook, server-render and import checks, and listener counts after `destroy` | each factory without React; each hook; a server import; `destroy` mid-drag | a hook with behavior its factory lacks, a listener left after `destroy`, or DOM work at import fails | -| FR7 | Source boundary check over Core and Lab against the gap table | every Core and Lab component that drags, snaps, animates one element, reorders, or animates layout | a component reaching internals for a job the public layer covers, or an internal use whose job is not in the gap table, fails | -| FR5 | Docsite review of each hook's page and the playing-cards example | each hook's page; the playing-cards demo | a hook without usage, options, a keyboard path, Reduce Motion, a component-prop note, or a live example, or a demo that imports anything but public hooks, fails | +| Contract | Verification | Representative states | Mutation or failure expectation | +| -------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| FR1 | Unit and browser tests of `usePanGesture` | a drag on each axis, a cancel, a press, a long press | a recognizer in the result, a missing state, a drag off its axis, or a press or long press reported as a pan fails | +| FR2 | Unit and browser tests of `useDragToSnapPoints` | a slow release, a flick past `flickThreshold` and the default flick speed, a release moving back, `settleTo` from a key | a settle on the wrong snap point, a reversed drag that settles elsewhere, or a missing `onSettle` fails | +| FR3 | Unit and browser tests of `useAnimator` | each method, Reduce Motion, an unattached ref | a missing method or channel, an `animate` off `springs.stateChange`, or motion that ignores Reduce Motion fails | +| FR4 | Export check of `@astryxdesign/core` and its hooks | the public exports | a recognizer, the arena, the internal animator module, or the resolver reachable from a public export fails | +| FR6 | Unit tests of each factory and its hook, server-render and import checks, and listener counts after `destroy` | each factory without React; each hook; a server import; `destroy` mid-drag | a hook with behavior its factory lacks, a listener left after `destroy`, or DOM work at import fails | +| FR7 | Source boundary check over Core and Lab against the gap table | every Core and Lab component that drags, snaps, animates one element, reorders, or animates layout | a component reaching internals for a job the public layer covers, or an internal use whose job is not in the gap table, fails | +| FR8 | Unit and browser tests of `createContextMenu` and `useContextMenu`, and ContextMenu's tests over them | a long press, a right click, and Shift+F10 on a plain element; `open(at)`; `close`; `destroy` while open; `items` and `render` | a context request that opens nothing, a listener left after `destroy`, a hook with behavior of its own, or a ContextMenu that bypasses the factory fails | +| FR5 | Docsite review of each hook's page and the playing-cards example | each hook's page; the playing-cards demo | a hook without usage, options, a keyboard path, Reduce Motion, a component-prop note, or a live example, or a demo that imports anything but public hooks, fails | ## Decision log @@ -220,6 +230,18 @@ hidden behind internals. Rejected: hooks only, and components that bypass the public layer. +### DEC-3 — The context menu gets a public headless layer + +**Reference:** `spec:AST-107/DEC-3` +**Decider:** `cixzhang`, `2026-10-26` + +A row in a list, a card, or any element a product owns needs a context menu +without a wrapper element that breaks its markup, so the menu is a public +factory that attaches to the element itself, with a thin hook, and +`` is built on the same factory. + +Rejected: a context menu reachable only through the `` wrapper. + ## Open questions None. From 012dea9874701e10bf60b529f12d14b0cc02ff88 Mon Sep 17 00:00:00 2001 From: Cindy Zhang Date: Mon, 26 Oct 2026 21:45:26 -0700 Subject: [PATCH 08/14] spec(AST-107 +): gap list and name rule move to react-component-runtime INV13; INV21 states the hook-over-factory rule; flickThreshold exception in AST-100/AST-094; frontmatter, failure behavior, rows --- docs/architecture/public-component-api.md | 5 +- docs/architecture/react-component-runtime.md | 13 +++- .../specs/AST-094-touch-presentations/spec.md | 4 +- docs/specs/AST-100-release-velocity/spec.md | 3 +- .../AST-107-public-gesture-hooks/spec.md | 76 +++++++++---------- 5 files changed, 57 insertions(+), 44 deletions(-) diff --git a/docs/architecture/public-component-api.md b/docs/architecture/public-component-api.md index 15068b81b1469..55c380b7b5b41 100644 --- a/docs/architecture/public-component-api.md +++ b/docs/architecture/public-component-api.md @@ -194,7 +194,10 @@ guidance owns the process used to propose and test APIs. API that shares a job with existing API, unless the existing API is being deprecated in favor of it. INV3 keeps one prop to one concept and INV16 keeps one `presentation` prop for a surface choice; INV21 applies the same rule - across props, components, hooks, and factories. A deprecation follows INV9. + across props, components, hooks, and factories. A hook that delegates + entirely to a public factory, with no behavior of its own, is one API with + that factory, not a second one (`spec:AST-107` FR6). A deprecation follows + INV9. This record applies to stable public packages. Lab components are not stable public promises until promotion. diff --git a/docs/architecture/react-component-runtime.md b/docs/architecture/react-component-runtime.md index a2fa5352c703c..db111978fea9d 100644 --- a/docs/architecture/react-component-runtime.md +++ b/docs/architecture/react-component-runtime.md @@ -183,7 +183,18 @@ those contracts. host) is the one place these modules use classes, and it uses no inheritance checks: a recognizer is told apart by its `kind` field, never by `instanceof`. Every other module, and every public layer, is built from - `create…` factories. Components import them statically, and the bundler + `create…` factories, and no internal factory shares a public factory's name + (`spec:AST-107` FR6). Core and Lab components use `spec:AST-107`'s public + layer wherever it covers their job and reach these modules directly only for + these known public-API gaps: press feedback timing; the Reduce Motion + cross-fade constants; press tracking across a group of actions; the + selection lock during a gesture; the presentation hold; the input hold; + lift-from-trigger and the rectangle morph; custom recognizer relationships; + the gesture host, velocity tracking, rubber band, and haptics; long press, + which has no public factory yet; the spring and curve helpers and UIKit's + measured tables; the touch presentation query; layout-change reporting + (`spec:AST-105` FR1); and the touch hit-area expansion. Components import + them statically, and the bundler keeps one copy per page however many components use them. There is no install call, no public entry, and no public installed check; tests reset the modules through an internal hook only. A component's own touch logic is diff --git a/docs/specs/AST-094-touch-presentations/spec.md b/docs/specs/AST-094-touch-presentations/spec.md index 94fda268d7a00..5ccf0dd934aa6 100644 --- a/docs/specs/AST-094-touch-presentations/spec.md +++ b/docs/specs/AST-094-touch-presentations/spec.md @@ -115,7 +115,9 @@ a measured, sourced difference exists. 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). When the public set is decided, its roles join the motion configuration of + motion: they stay internal measured values and are not public concepts (`spec:AST-002` FR3), + except the `flickThreshold` a product passes to `spec:AST-107`'s snap-point + drag. When the public set is decided, its roles join the motion configuration of `architecture:theme-authoring-contract` and `architecture:theme-tokens`, whose rules are unchanged until then. It departs from the draft `design:motion` DR3 wherever the native motion settles with an overshoot or stretches with a diff --git a/docs/specs/AST-100-release-velocity/spec.md b/docs/specs/AST-100-release-velocity/spec.md index d412819b94f60..5b42bdd0a90c3 100644 --- a/docs/specs/AST-100-release-velocity/spec.md +++ b/docs/specs/AST-100-release-velocity/spec.md @@ -74,7 +74,8 @@ means for them. - **FR3 — Thresholds sit on top of the one velocity.** A component's flick, fling, or commit threshold compares the FR2 velocity, possibly with travel or projection the component owns. Thresholds are per-component tuning that - stays internal (`spec:AST-002` FR3); a component never derives a second + stays internal (`spec:AST-002` FR3), except the public `flickThreshold` a + product passes to `spec:AST-107`'s snap-point drag; a component never derives a second velocity to compare against. - **FR4 — Event time for every pointer.** The velocity follows the input events' own timestamps, so a handler that runs late does not change it, and diff --git a/docs/specs/AST-107-public-gesture-hooks/spec.md b/docs/specs/AST-107-public-gesture-hooks/spec.md index 2eca6ebd8e3a1..9d6893c7a0752 100644 --- a/docs/specs/AST-107-public-gesture-hooks/spec.md +++ b/docs/specs/AST-107-public-gesture-hooks/spec.md @@ -10,10 +10,21 @@ approved_by: cixzhang approved_at: 2026-10-26 phase: accepted owners: [cixzhang] -affects_architecture: [architecture:public-component-api] +affects_architecture: + [architecture:public-component-api, architecture:react-component-runtime] affects_families: [] affects_contributing: [] -affects_consumer_docs: [usePanGesture, useDragToSnapPoints, useAnimator] +affects_consumer_docs: + [ + usePanGesture, + useDragToSnapPoints, + useAnimator, + createPanGesture, + createDragToSnapPoints, + createAnimator, + createContextMenu, + useContextMenu, + ] --- # Public gesture hooks system spec @@ -101,7 +112,7 @@ animator2.destroy(); unlike BottomSheet's `snapPoints`, they are not viewport fractions. At the release the element settles on the nearest snap point to where it is, except that a release faster than `flickThreshold`, in pixels per second - (default 1008, the sheet's measured flick speed), carries to the next snap point in its direction, and a + (default 1008, the flick speed measured for UIKit's sheet on iOS 26.2), carries to the next snap point in its direction, and a release whose velocity points back toward where the drag started returns to the snap point it started from (`spec:AST-094` FR37). It calls `onSettle(index)` once the element settles. It returns @@ -117,7 +128,8 @@ animator2.destroy(); `stop()` halts them where they are. Reduce Motion is planned for every animation (`design:reduced-motion` DR1–DR3). Every `animate` plays on the `springs.stateChange` motion role (`spec:AST-094` FR4), which follows the - theme's tempo and character (`spec:AST-108` FR3), and `decay` on the fixed + theme's tempo and character; `animate` on a channel it does not know, or + after `destroy`, does nothing and resolves at once, (`spec:AST-108` FR3), and `decay` on the fixed momentum decay (`spec:AST-108` FR4); choosing any other spring or curve is not offered. - **FR4 — One hook per job.** `usePanGesture` does not do presses or long @@ -133,37 +145,20 @@ animator2.destroy(); `createDragToSnapPoints(element, {axis, snapPoints, flickThreshold?, onSettle}) → {settleTo(index), destroy}`, and `createAnimator(element) → {animate, decay, set, get, getVelocity, stop, destroy}`, with FR1–FR3's - behavior. A hook and its factory are one job at two layers + behavior. A hook and its factory are one API at two layers (`architecture:public-component-api` INV21): the hook delegates entirely to its factory and has no behavior of its own. `destroy` removes every listener the factory added, and importing a factory does no DOM work, so it - is safe on the server. The public `createAnimator` is Core's one - animator factory: Core's internal animator either is this factory or takes - another name, and no internal factory shares a public factory's name. + is safe on the server. No internal factory shares a public factory's name + (`architecture:react-component-runtime` INV13). - **FR7 — Core and Lab use the public layer.** Wherever a public gesture or motion API covers a component's job (the factories and hooks here, `createReorderable`, and `useAnimatedLayout`), Core and Lab components MUST use it rather than the internals beneath it. A component reaches internals - only for a job the public layer does not expose, and each such job is a - known public-API gap. `createReorderable`'s plain-element attach path covers - collections that are not List, such as Lab's TransferList and ListInput. - - | Public-API gap | Used internally by | - | -------------------------------------------------------------------- | ---------------------------------- | - | Press feedback timing | controls and cells | - | Reduced Motion cross-fade constants | every Reduce Motion fade | - | Press tracking across a group of actions (`actionGroupTracker`) | `family:action-groups` members | - | Selection lock during a gesture (`selectionLock`) | gestures that block text selection | - | Keeping a layer's chosen presentation (the presentation hold) | layers | - | Absorbing input while a layer enters (the input hold) | layers | - | Growing a layer out of its trigger (`liftFromTrigger`, `rectMorph`) | lift-from-trigger presentations | - | Which of two gestures wins a touch (custom recognizer relationships) | nested gestures | - | Gesture host, velocity tracking, rubber band, and haptics | the gesture foundations | - | Long press, which has no public factory yet | long-press surfaces | - | Spring and curve helpers and UIKit's measured tables | motion foundations | - | The touch presentation query | touch presentations | - | Layout-change reporting, internal by `spec:AST-105` FR1 | animated layout | - | Touch hit-area expansion (`utils/hitArea`) | coarse-pointer targets | + only for a job the public layer does not expose; those jobs are listed as + known public-API gaps in `architecture:react-component-runtime` INV13. + `createReorderable`'s plain-element attach path (`spec:AST-103`) covers + collections that are not List. - **FR8 — A headless context menu.** `createContextMenu(element, {items | render, onOpenChange?, presentation?}) → {open(at?), close(), destroy()}` @@ -171,7 +166,7 @@ render, onOpenChange?, presentation?}) → {open(at?), close(), destroy()}` request (a long press, a right click, or Shift+F10), at `at` when given, and `destroy` removes every listener it added. `useContextMenu(ref, options) → {open, close}` is its thin React wrapper (FR6), and `component:ContextMenu` - is built on it (FR7): one job at two layers + is built on it (FR7): one API at two layers (`architecture:public-component-api` INV21). - **FR5 — Each hook ships with docs and a playing-cards example.** Each public API here, factory and hook alike, and `createReorderable`'s `positions` (`spec:AST-103`), ships with @@ -187,21 +182,22 @@ render, onOpenChange?, presentation?}) → {open(at?), close(), destroy()}` ## Current-state impact - Core gains the three factories and the three hooks over them, the headless - context menu and its hook, their docsite + context menu and its hook, Core and Lab components that move onto them + (FR7), the `architecture:react-component-runtime` INV13 gap list, their docsite pages, and a playing-cards example in plain JavaScript and in React. ## Verification -| Contract | Verification | Representative states | Mutation or failure expectation | -| -------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| FR1 | Unit and browser tests of `usePanGesture` | a drag on each axis, a cancel, a press, a long press | a recognizer in the result, a missing state, a drag off its axis, or a press or long press reported as a pan fails | -| FR2 | Unit and browser tests of `useDragToSnapPoints` | a slow release, a flick past `flickThreshold` and the default flick speed, a release moving back, `settleTo` from a key | a settle on the wrong snap point, a reversed drag that settles elsewhere, or a missing `onSettle` fails | -| FR3 | Unit and browser tests of `useAnimator` | each method, Reduce Motion, an unattached ref | a missing method or channel, an `animate` off `springs.stateChange`, or motion that ignores Reduce Motion fails | -| FR4 | Export check of `@astryxdesign/core` and its hooks | the public exports | a recognizer, the arena, the internal animator module, or the resolver reachable from a public export fails | -| FR6 | Unit tests of each factory and its hook, server-render and import checks, and listener counts after `destroy` | each factory without React; each hook; a server import; `destroy` mid-drag | a hook with behavior its factory lacks, a listener left after `destroy`, or DOM work at import fails | -| FR7 | Source boundary check over Core and Lab against the gap table | every Core and Lab component that drags, snaps, animates one element, reorders, or animates layout | a component reaching internals for a job the public layer covers, or an internal use whose job is not in the gap table, fails | -| FR8 | Unit and browser tests of `createContextMenu` and `useContextMenu`, and ContextMenu's tests over them | a long press, a right click, and Shift+F10 on a plain element; `open(at)`; `close`; `destroy` while open; `items` and `render` | a context request that opens nothing, a listener left after `destroy`, a hook with behavior of its own, or a ContextMenu that bypasses the factory fails | -| FR5 | Docsite review of each hook's page and the playing-cards example | each hook's page; the playing-cards demo | a hook without usage, options, a keyboard path, Reduce Motion, a component-prop note, or a live example, or a demo that imports anything but public hooks, fails | +| Contract | Verification | Representative states | Mutation or failure expectation | +| -------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| FR1 | Unit and browser tests of `usePanGesture` | a drag on each axis, a cancel, a press, a long press | a recognizer in the result, a missing state, a drag off its axis, or a press or long press reported as a pan fails | +| FR2 | Unit and browser tests of `useDragToSnapPoints` | a slow release, a flick past `flickThreshold` and the default flick speed, a release moving back, `settleTo` from a key | a settle on the wrong snap point, a reversed drag that settles elsewhere, or a missing `onSettle` fails | +| FR3 | Unit and browser tests of `useAnimator` | each method, Reduce Motion, an unattached ref, an unknown channel, a call after `destroy` | a missing method or channel, an `animate` off `springs.stateChange`, or motion that ignores Reduce Motion or a throw on an unknown channel or after `destroy` fails | +| FR4 | Export check of `@astryxdesign/core` and its hooks | the public exports | a recognizer, the arena, the internal animator module, or the resolver reachable from a public export fails | +| FR6 | Unit tests of each factory and its hook, server-render and import checks, and listener counts after `destroy` | each factory without React; each hook; a server import; `destroy` mid-drag | a hook with behavior its factory lacks, a listener left after `destroy`, or DOM work at import fails | +| FR7 | Source boundary check over Core and Lab against the gap table | every Core and Lab component that drags, snaps, animates one element, reorders, or animates layout | a component reaching internals for a job the public layer covers, or an internal use whose job is not in the gap table, fails | +| FR8 | Unit and browser tests of `createContextMenu` and `useContextMenu`, and ContextMenu's tests over them | a long press, a right click, and Shift+F10 on a plain element; `open(at)`; `close`; `destroy` while open; `items` and `render` | a context request that opens nothing, a listener left after `destroy`, a hook with behavior of its own, or a ContextMenu that bypasses the factory fails | +| FR5 | Docsite review of each hook's page and the playing-cards example | each hook's and factory's page; the playing-cards demo in plain JavaScript and in React | a hook without usage, options, a keyboard path, Reduce Motion, a component-prop note, or a live example, or a demo that imports anything but the public factories or hooks, fails | ## Decision log From a15fc43235c4525eac107c42af8f57b87fb906d0 Mon Sep 17 00:00:00 2001 From: Cindy Zhang Date: Mon, 26 Oct 2026 22:43:43 -0700 Subject: [PATCH 09/14] spec(AST-107 +): flickThreshold source and admission; FR3 sentence split; INV21 covers a component on a factory; INV13 class rule, row and deciding spec --- docs/architecture/public-component-api.md | 5 +-- docs/architecture/react-component-runtime.md | 36 +++++++++++-------- .../AST-107-public-gesture-hooks/spec.md | 24 +++++++++---- 3 files changed, 42 insertions(+), 23 deletions(-) diff --git a/docs/architecture/public-component-api.md b/docs/architecture/public-component-api.md index 55c380b7b5b41..2ec110be47aad 100644 --- a/docs/architecture/public-component-api.md +++ b/docs/architecture/public-component-api.md @@ -195,8 +195,9 @@ guidance owns the process used to propose and test APIs. deprecated in favor of it. INV3 keeps one prop to one concept and INV16 keeps one `presentation` prop for a surface choice; INV21 applies the same rule across props, components, hooks, and factories. A hook that delegates - entirely to a public factory, with no behavior of its own, is one API with - that factory, not a second one (`spec:AST-107` FR6). A deprecation follows + entirely to a public factory, with no behavior of its own, and a component + built entirely on a public factory are one API with that factory, not a + second one (`spec:AST-107` FR6, FR8). A deprecation follows INV9. This record applies to stable public packages. Lab components are not stable diff --git a/docs/architecture/react-component-runtime.md b/docs/architecture/react-component-runtime.md index db111978fea9d..b1005f112fcb3 100644 --- a/docs/architecture/react-component-runtime.md +++ b/docs/architecture/react-component-runtime.md @@ -15,7 +15,13 @@ verified_by: packages/core/src/Layer/useLayer.test.tsx, packages/core/src/utils/sharedResizeObserver.test.ts, ] -deciding_specs: [spec:AST-086/DEC-2, spec:AST-099/DEC-1, spec:AST-105/DEC-1] +deciding_specs: + [ + spec:AST-086/DEC-2, + spec:AST-099/DEC-1, + spec:AST-105/DEC-1, + spec:AST-107/DEC-2, + ] --- # React component runtime architecture @@ -180,7 +186,7 @@ those contracts. behavior comes from one always-present set of internal gesture and touch modules: the gesture core, the recognizers, the arena, the animator, and the touch press recognizer. The recognizer family (its base, the arena, and the - host) is the one place these modules use classes, and it uses no + host) and the velocity tracker are the one place these modules use classes, and it uses no inheritance checks: a recognizer is told apart by its `kind` field, never by `instanceof`. Every other module, and every public layer, is built from `create…` factories, and no internal factory shares a public factory's name @@ -329,6 +335,8 @@ contracts. internal and applied through functional styles (INV11). - `spec:AST-105/DEC-1` — the size-change glide's public shape and behavior (INV12). +- `spec:AST-107/DEC-2` — factories under every hook, the class and + public-name rules, and the known public-API gap list (INV13). Component, family, API, accessibility, layer, interaction, and style records remain authoritative for the other user-facing outcomes delegated above. @@ -342,15 +350,15 @@ observable-behavior predicates require review or runtime evidence. Likewise, a focused test proves only its named behavior and mutation expectation; a green component suite is not blanket conformance with every invariant. -| Invariant | Evidence | Failure signal | -| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| INV1–INV2 | Initial-render and interaction tests | Output flashes a known-wrong state, or one action is delayed or repeated through an Effect | -| INV3, INV5 | StrictMode setup/cleanup and dependency-change tests | Duplicate callback, leaked work, stale subscription, or missing resynchronization | -| INV1, INV4, INV6 | Ref attach/null/replacement, DOM-in-state rejection, and old-node cleanup-before-new-attach mutations | A DOM node or collection enters state, old node remains active, cleanup misses replacement, or ref mutation changes semantics silently | -| INV7 | Real-browser geometry plus N-consumer observer-instance/subscription mutations | Geometry is invalid, observer instances grow with repeated consumers, one unsubscribe silences peers, or cleanup removes another subscriber | -| INV8 | Owner-observable behavior across documented composition replacement; optional focused internal mechanism tests | Behavior disappears or changes owner when a documented subpart is replaced | -| INV9 | Provider/external-store identity and render-count tests | Unchanged semantic payload changes identity, or snapshot identity creates a render loop | -| INV10 | Shared test over every adopter of the announcement module | An adopter holding its own Effect, observer, timer, or listener for its own-content announcement | -| INV11 | Source boundary check plus hook tests across StrictMode replay and unmount | A second keyboard listener or measurement in Core; a consumer reading a CSS custom property on the root or a shared ancestor for the height; an export of the hook; a component outside Core measuring by a rule other than AST-099 FR2, or riding the keyboard; a listener left after unmount; a Core rider driven by JavaScript per frame or by its own transition; or more than one layout read per keyboard change | -| INV12 | Source boundary check plus real-browser tests on a throttled phone profile over a 10-level by 50-sibling tree and two changes in one frame | A per-frame height or layout, a walk past the area or into a subtree other than `display: contents`, an element moved twice for one frame, an added element, or an exported reporting function fails | -| INV13 | Source boundary check plus bundle analysis of a page with several touch components, and real-browser tests on a throttled phone profile, under a fine pointer, and on a hybrid device | A second copy of a touch module on one page, a component bundling its own copy of a module's primitive, an `import()` of a module in a component, a public export or doc entry for the modules, an install call or installed check in the public API, a touch listener under a fine primary pointer, or an import of `@astryxdesign/core/internal/*` outside Core and Lab fails | +| Invariant | Evidence | Failure signal | +| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| INV1–INV2 | Initial-render and interaction tests | Output flashes a known-wrong state, or one action is delayed or repeated through an Effect | +| INV3, INV5 | StrictMode setup/cleanup and dependency-change tests | Duplicate callback, leaked work, stale subscription, or missing resynchronization | +| INV1, INV4, INV6 | Ref attach/null/replacement, DOM-in-state rejection, and old-node cleanup-before-new-attach mutations | A DOM node or collection enters state, old node remains active, cleanup misses replacement, or ref mutation changes semantics silently | +| INV7 | Real-browser geometry plus N-consumer observer-instance/subscription mutations | Geometry is invalid, observer instances grow with repeated consumers, one unsubscribe silences peers, or cleanup removes another subscriber | +| INV8 | Owner-observable behavior across documented composition replacement; optional focused internal mechanism tests | Behavior disappears or changes owner when a documented subpart is replaced | +| INV9 | Provider/external-store identity and render-count tests | Unchanged semantic payload changes identity, or snapshot identity creates a render loop | +| INV10 | Shared test over every adopter of the announcement module | An adopter holding its own Effect, observer, timer, or listener for its own-content announcement | +| INV11 | Source boundary check plus hook tests across StrictMode replay and unmount | A second keyboard listener or measurement in Core; a consumer reading a CSS custom property on the root or a shared ancestor for the height; an export of the hook; a component outside Core measuring by a rule other than AST-099 FR2, or riding the keyboard; a listener left after unmount; a Core rider driven by JavaScript per frame or by its own transition; or more than one layout read per keyboard change | +| INV12 | Source boundary check plus real-browser tests on a throttled phone profile over a 10-level by 50-sibling tree and two changes in one frame | A per-frame height or layout, a walk past the area or into a subtree other than `display: contents`, an element moved twice for one frame, an added element, or an exported reporting function fails | +| INV13 | Source boundary check plus bundle analysis of a page with several touch components, and real-browser tests on a throttled phone profile, under a fine pointer, and on a hybrid device | A second copy of a touch module on one page, a component bundling its own copy of a module's primitive, an `import()` of a module in a component, a public export or doc entry for the modules, an install call or installed check in the public API, a touch listener under a fine primary pointer, or an import of `@astryxdesign/core/internal/*` outside Core and Lab , a class outside the recognizer family and velocity tracker, an `instanceof` check on a recognizer, an internal factory with a public factory's name, or a direct module import for a job the public layer covers fails | diff --git a/docs/specs/AST-107-public-gesture-hooks/spec.md b/docs/specs/AST-107-public-gesture-hooks/spec.md index 9d6893c7a0752..9c56fdb52065e 100644 --- a/docs/specs/AST-107-public-gesture-hooks/spec.md +++ b/docs/specs/AST-107-public-gesture-hooks/spec.md @@ -112,10 +112,16 @@ animator2.destroy(); unlike BottomSheet's `snapPoints`, they are not viewport fractions. At the release the element settles on the nearest snap point to where it is, except that a release faster than `flickThreshold`, in pixels per second - (default 1008, the flick speed measured for UIKit's sheet on iOS 26.2), carries to the next snap point in its direction, and a + (default 1008, inside the (996.7, 1028.3] pt/s bracket at which UIKit's sheet + switches from its settle spring to its flick spring, measured in a UIKit lab + host app on the iOS 26.2 simulator, iPhone 17 Pro, over 134 drag releases on + 2026-10-23 and 2026-10-24), carries to the next snap point in its direction, and a release whose velocity points back toward where the drag started returns to - the snap point it started from (`spec:AST-094` FR37). It - calls `onSettle(index)` once the element settles. It returns + the snap point it started from (`spec:AST-094` FR37). The threshold is public because a product's own + snap surface decides how readily a flick commits, which no motion role or + theme knob expresses (`spec:AST-002` FR5); Core components keep theirs + internal (`spec:AST-100` FR3). It calls `onSettle(index)` once the element + settles. It returns `{settleTo(index)}`, which settles the element on a snap point without a drag and is the keyboard path. - **FR3 — `useAnimator` animates one element.** `useAnimator()` returns @@ -128,10 +134,10 @@ animator2.destroy(); `stop()` halts them where they are. Reduce Motion is planned for every animation (`design:reduced-motion` DR1–DR3). Every `animate` plays on the `springs.stateChange` motion role (`spec:AST-094` FR4), which follows the - theme's tempo and character; `animate` on a channel it does not know, or - after `destroy`, does nothing and resolves at once, (`spec:AST-108` FR3), and `decay` on the fixed - momentum decay (`spec:AST-108` FR4); choosing any other spring or curve is - not offered. + theme's tempo and character (`spec:AST-108` FR3), and every `decay` plays on + the fixed momentum decay (`spec:AST-108` FR4); choosing any other spring or + curve is not offered. `animate` on a channel it does not know, or any call + after `destroy`, does nothing and resolves at once. - **FR4 — One hook per job.** `usePanGesture` does not do presses or long presses, which `useLongPress` owns. `useAnimator` animates one element, and `useAnimatedLayout` animates an area (`spec:AST-105`). A component's own @@ -181,6 +187,10 @@ render, onOpenChange?, presentation?}) → {open(at?), close(), destroy()}` ## Current-state impact +- `architecture:react-component-runtime` INV13 gains three rules: the + recognizer family and the velocity tracker are the only classes, told apart + by `kind`, never `instanceof`; no internal factory shares a public factory's + name; and the known public-API gap list. - Core gains the three factories and the three hooks over them, the headless context menu and its hook, Core and Lab components that move onto them (FR7), the `architecture:react-component-runtime` INV13 gap list, their docsite From 28c2719d0ec2e16a90e4f7acec02c5f36a06de77 Mon Sep 17 00:00:00 2001 From: Cindy Zhang Date: Mon, 26 Oct 2026 22:44:20 -0700 Subject: [PATCH 10/14] spec(react-component-runtime): the class exception stays the recognizer family; the velocity tracker follows the create rule (gap recorded) --- docs/architecture/react-component-runtime.md | 29 ++++++++++--------- .../AST-107-public-gesture-hooks/spec.md | 4 +-- 2 files changed, 17 insertions(+), 16 deletions(-) diff --git a/docs/architecture/react-component-runtime.md b/docs/architecture/react-component-runtime.md index b1005f112fcb3..dd8042d354019 100644 --- a/docs/architecture/react-component-runtime.md +++ b/docs/architecture/react-component-runtime.md @@ -186,10 +186,11 @@ those contracts. behavior comes from one always-present set of internal gesture and touch modules: the gesture core, the recognizers, the arena, the animator, and the touch press recognizer. The recognizer family (its base, the arena, and the - host) and the velocity tracker are the one place these modules use classes, and it uses no + host) is the one place these modules use classes, and it uses no inheritance checks: a recognizer is told apart by its `kind` field, never by `instanceof`. Every other module, and every public layer, is built from - `create…` factories, and no internal factory shares a public factory's name + `create…` factories, the velocity tracker included (implementation gap: it is + still the `VelocityTracker` class), and no internal factory shares a public factory's name (`spec:AST-107` FR6). Core and Lab components use `spec:AST-107`'s public layer wherever it covers their job and reach these modules directly only for these known public-API gaps: press feedback timing; the Reduce Motion @@ -350,15 +351,15 @@ observable-behavior predicates require review or runtime evidence. Likewise, a focused test proves only its named behavior and mutation expectation; a green component suite is not blanket conformance with every invariant. -| Invariant | Evidence | Failure signal | -| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| INV1–INV2 | Initial-render and interaction tests | Output flashes a known-wrong state, or one action is delayed or repeated through an Effect | -| INV3, INV5 | StrictMode setup/cleanup and dependency-change tests | Duplicate callback, leaked work, stale subscription, or missing resynchronization | -| INV1, INV4, INV6 | Ref attach/null/replacement, DOM-in-state rejection, and old-node cleanup-before-new-attach mutations | A DOM node or collection enters state, old node remains active, cleanup misses replacement, or ref mutation changes semantics silently | -| INV7 | Real-browser geometry plus N-consumer observer-instance/subscription mutations | Geometry is invalid, observer instances grow with repeated consumers, one unsubscribe silences peers, or cleanup removes another subscriber | -| INV8 | Owner-observable behavior across documented composition replacement; optional focused internal mechanism tests | Behavior disappears or changes owner when a documented subpart is replaced | -| INV9 | Provider/external-store identity and render-count tests | Unchanged semantic payload changes identity, or snapshot identity creates a render loop | -| INV10 | Shared test over every adopter of the announcement module | An adopter holding its own Effect, observer, timer, or listener for its own-content announcement | -| INV11 | Source boundary check plus hook tests across StrictMode replay and unmount | A second keyboard listener or measurement in Core; a consumer reading a CSS custom property on the root or a shared ancestor for the height; an export of the hook; a component outside Core measuring by a rule other than AST-099 FR2, or riding the keyboard; a listener left after unmount; a Core rider driven by JavaScript per frame or by its own transition; or more than one layout read per keyboard change | -| INV12 | Source boundary check plus real-browser tests on a throttled phone profile over a 10-level by 50-sibling tree and two changes in one frame | A per-frame height or layout, a walk past the area or into a subtree other than `display: contents`, an element moved twice for one frame, an added element, or an exported reporting function fails | -| INV13 | Source boundary check plus bundle analysis of a page with several touch components, and real-browser tests on a throttled phone profile, under a fine pointer, and on a hybrid device | A second copy of a touch module on one page, a component bundling its own copy of a module's primitive, an `import()` of a module in a component, a public export or doc entry for the modules, an install call or installed check in the public API, a touch listener under a fine primary pointer, or an import of `@astryxdesign/core/internal/*` outside Core and Lab , a class outside the recognizer family and velocity tracker, an `instanceof` check on a recognizer, an internal factory with a public factory's name, or a direct module import for a job the public layer covers fails | +| Invariant | Evidence | Failure signal | +| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| INV1–INV2 | Initial-render and interaction tests | Output flashes a known-wrong state, or one action is delayed or repeated through an Effect | +| INV3, INV5 | StrictMode setup/cleanup and dependency-change tests | Duplicate callback, leaked work, stale subscription, or missing resynchronization | +| INV1, INV4, INV6 | Ref attach/null/replacement, DOM-in-state rejection, and old-node cleanup-before-new-attach mutations | A DOM node or collection enters state, old node remains active, cleanup misses replacement, or ref mutation changes semantics silently | +| INV7 | Real-browser geometry plus N-consumer observer-instance/subscription mutations | Geometry is invalid, observer instances grow with repeated consumers, one unsubscribe silences peers, or cleanup removes another subscriber | +| INV8 | Owner-observable behavior across documented composition replacement; optional focused internal mechanism tests | Behavior disappears or changes owner when a documented subpart is replaced | +| INV9 | Provider/external-store identity and render-count tests | Unchanged semantic payload changes identity, or snapshot identity creates a render loop | +| INV10 | Shared test over every adopter of the announcement module | An adopter holding its own Effect, observer, timer, or listener for its own-content announcement | +| INV11 | Source boundary check plus hook tests across StrictMode replay and unmount | A second keyboard listener or measurement in Core; a consumer reading a CSS custom property on the root or a shared ancestor for the height; an export of the hook; a component outside Core measuring by a rule other than AST-099 FR2, or riding the keyboard; a listener left after unmount; a Core rider driven by JavaScript per frame or by its own transition; or more than one layout read per keyboard change | +| INV12 | Source boundary check plus real-browser tests on a throttled phone profile over a 10-level by 50-sibling tree and two changes in one frame | A per-frame height or layout, a walk past the area or into a subtree other than `display: contents`, an element moved twice for one frame, an added element, or an exported reporting function fails | +| INV13 | Source boundary check plus bundle analysis of a page with several touch components, and real-browser tests on a throttled phone profile, under a fine pointer, and on a hybrid device | A second copy of a touch module on one page, a component bundling its own copy of a module's primitive, an `import()` of a module in a component, a public export or doc entry for the modules, an install call or installed check in the public API, a touch listener under a fine primary pointer, or an import of `@astryxdesign/core/internal/*` outside Core and Lab , a class outside the recognizer family, an `instanceof` check on a recognizer, an internal factory with a public factory's name, or a direct module import for a job the public layer covers fails | diff --git a/docs/specs/AST-107-public-gesture-hooks/spec.md b/docs/specs/AST-107-public-gesture-hooks/spec.md index 9c56fdb52065e..2d6e31a9a66af 100644 --- a/docs/specs/AST-107-public-gesture-hooks/spec.md +++ b/docs/specs/AST-107-public-gesture-hooks/spec.md @@ -188,8 +188,8 @@ render, onOpenChange?, presentation?}) → {open(at?), close(), destroy()}` ## Current-state impact - `architecture:react-component-runtime` INV13 gains three rules: the - recognizer family and the velocity tracker are the only classes, told apart - by `kind`, never `instanceof`; no internal factory shares a public factory's + recognizer family is the only class family, told apart by `kind`, never + `instanceof`, and the velocity tracker moves to a `create…` factory; no internal factory shares a public factory's name; and the known public-API gap list. - Core gains the three factories and the three hooks over them, the headless context menu and its hook, Core and Lab components that move onto them From ef7ba824e4dc5f3dfe86381e9bb056ac25fa7a96 Mon Sep 17 00:00:00 2001 From: Cindy Zhang Date: Mon, 26 Oct 2026 23:47:47 -0700 Subject: [PATCH 11/14] spec(AST-107): pointer scope, interrupted and early calls, flickThreshold's two cases, intent names the context menu, INV21 in impact; kind gap --- docs/architecture/react-component-runtime.md | 3 ++- .../AST-107-public-gesture-hooks/spec.md | 21 +++++++++++++------ 2 files changed, 17 insertions(+), 7 deletions(-) diff --git a/docs/architecture/react-component-runtime.md b/docs/architecture/react-component-runtime.md index dd8042d354019..f7d8a73c37f98 100644 --- a/docs/architecture/react-component-runtime.md +++ b/docs/architecture/react-component-runtime.md @@ -188,7 +188,8 @@ those contracts. touch press recognizer. The recognizer family (its base, the arena, and the host) is the one place these modules use classes, and it uses no inheritance checks: a recognizer is told apart by its `kind` field, never by - `instanceof`. Every other module, and every public layer, is built from + `instanceof`. (Implementation gap: recognizers carry no `kind` + field yet.) Every other module, and every public layer, is built from `create…` factories, the velocity tracker included (implementation gap: it is still the `VelocityTracker` class), and no internal factory shares a public factory's name (`spec:AST-107` FR6). Core and Lab components use `spec:AST-107`'s public diff --git a/docs/specs/AST-107-public-gesture-hooks/spec.md b/docs/specs/AST-107-public-gesture-hooks/spec.md index 2d6e31a9a66af..7ade1f300b391 100644 --- a/docs/specs/AST-107-public-gesture-hooks/spec.md +++ b/docs/specs/AST-107-public-gesture-hooks/spec.md @@ -43,7 +43,8 @@ affects_consumer_docs: A product can follow a drag, settle an element on snap points, and animate one element with the same motion Core uses, through three public factories and the -three React hooks over them. The hooks +three React hooks over them, and can give any element a context menu through +a public headless layer. The hooks hand out values, never the gesture machinery behind them, which stays internal. @@ -103,11 +104,13 @@ animator2.destroy(); - **FR1 — `usePanGesture` reports a drag as values.** `usePanGesture(ref, {axis?, onPan})` calls `onPan` with `{state, translation, velocity}` as a drag on the element begins, changes, - ends, or is cancelled. `axis` limits the drag to `'x'` or `'y'`. It never + ends, or is cancelled. `axis` limits the drag to `'x'` or `'y'`. A finger, + a mouse, and a pen all drive it (`spec:AST-094` FR43). It never hands out a recognizer object, and it recognizes no press or long press. - **FR2 — `useDragToSnapPoints` settles an element on snap points.** `useDragToSnapPoints(ref, {axis, snapPoints, flickThreshold?, onSettle})` - lets a drag move the element along `axis`. `snapPoints` are offsets in + lets a drag move the element along `axis`, under + every pointer, as FR1's does. `snapPoints` are offsets in pixels along `axis` from the element's resting position, in ascending order; unlike BottomSheet's `snapPoints`, they are not viewport fractions. At the release the element settles on the nearest snap point to where it is, @@ -118,7 +121,9 @@ animator2.destroy(); 2026-10-23 and 2026-10-24), carries to the next snap point in its direction, and a release whose velocity points back toward where the drag started returns to the snap point it started from (`spec:AST-094` FR37). The threshold is public because a product's own - snap surface decides how readily a flick commits, which no motion role or + snap surface decides how readily a flick commits: a short drawer that should + close on a light flick and a tall sheet that should not take the same drag + to different snap points, which no motion role or theme knob expresses (`spec:AST-002` FR5); Core components keep theirs internal (`spec:AST-100` FR3). It calls `onSettle(index)` once the element settles. It returns @@ -136,8 +141,10 @@ animator2.destroy(); `springs.stateChange` motion role (`spec:AST-094` FR4), which follows the theme's tempo and character (`spec:AST-108` FR3), and every `decay` plays on the fixed momentum decay (`spec:AST-108` FR4); choosing any other spring or - curve is not offered. `animate` on a channel it does not know, or any call - after `destroy`, does nothing and resolves at once. + curve is not offered. `animate` on a channel it does not know, any call + before `ref` attaches, and any call after `destroy` do nothing and resolve at + once. A later `animate`, `decay`, `set`, or `stop` on a channel resolves that + channel's earlier promise where it stopped. - **FR4 — One hook per job.** `usePanGesture` does not do presses or long presses, which `useLongPress` owns. `useAnimator` animates one element, and `useAnimatedLayout` animates an area (`spec:AST-105`). A component's own @@ -187,6 +194,8 @@ render, onOpenChange?, presentation?}) → {open(at?), close(), destroy()}` ## Current-state impact +- `architecture:public-component-api` INV21 counts a hook over a public + factory, and a component built entirely on one, as one API with it. - `architecture:react-component-runtime` INV13 gains three rules: the recognizer family is the only class family, told apart by `kind`, never `instanceof`, and the velocity tracker moves to a `create…` factory; no internal factory shares a public factory's From 687ec4c62b07e4b126d20b597c443cda947b169a Mon Sep 17 00:00:00 2001 From: Cindy Zhang Date: Tue, 27 Oct 2026 01:30:53 -0700 Subject: [PATCH 12/14] Merge main into spec/public-gesture-hooks --- docs/architecture/public-component-api.md | 4 ++++ .../specs/AST-107-public-gesture-hooks/spec.md | 18 +++++++++++------- 2 files changed, 15 insertions(+), 7 deletions(-) diff --git a/docs/architecture/public-component-api.md b/docs/architecture/public-component-api.md index 2ec110be47aad..aabe3004ba1fa 100644 --- a/docs/architecture/public-component-api.md +++ b/docs/architecture/public-component-api.md @@ -33,6 +33,8 @@ deciding_specs: spec:AST-071/DEC-1, spec:AST-017/DEC-23, spec:AST-012/DEC-6, + spec:AST-107/DEC-2, + spec:AST-107/DEC-3, ] --- @@ -259,6 +261,8 @@ public promises until promotion. theme width names and inclusive-`from`/exclusive-`below` edge meanings. - `spec:AST-071/DEC-1` — every styling input works from every styling system, so a part's styling inputs come as a set. +- `spec:AST-107/DEC-2` and `spec:AST-107/DEC-3` — a hook over a public + factory, and a component built entirely on one, are one API with it (INV21). - `spec:AST-017/DEC-23` — a touch presentation or open-surface touch mode is a default the caller can always override, through one `presentation` prop that also restores the previous surface and mode. diff --git a/docs/specs/AST-107-public-gesture-hooks/spec.md b/docs/specs/AST-107-public-gesture-hooks/spec.md index be114bdde6077..c2dabbe6a6825 100644 --- a/docs/specs/AST-107-public-gesture-hooks/spec.md +++ b/docs/specs/AST-107-public-gesture-hooks/spec.md @@ -126,8 +126,9 @@ animator2.destroy(); to different snap points, which no motion role or theme knob expresses (`spec:AST-002` FR5); Core components keep theirs internal (`spec:AST-100` FR3). Under reduced motion the element goes to its snap point - without travel (`design:reduced-motion` DR1–DR3). It calls `onSettle(index)` - once the element settles. It returns + without travel (`design:reduced-motion` DR1–DR3). `snapPoints` is sorted before use; an empty list, + or `settleTo` with an index outside it, does nothing and warns in + development. It calls `onSettle(index)` once the element settles. It returns `{settleTo(index)}`, which settles the element on a snap point without a drag and is the keyboard path. - **FR3 — `useAnimator` animates one element.** `useAnimator()` returns @@ -174,14 +175,17 @@ onSettle}) → {settleTo(index), destroy}`, and `createAnimator(element) → `createReorderable`'s plain-element attach path (`spec:AST-103`) covers collections that are not List. -- **FR8 — A headless context menu.** `createContextMenu(element, {items | menuContent, label?, isDisabled?, +- **FR8 — A headless context menu.** `createContextMenu(element, {items | render, label?, isDisabled?, onOpenChange?, presentation?}) → {open(at?), close(), destroy()}` attaches a context menu to any element: it opens on the element's context - request (a long press, a right click, or Shift+F10), at `at` when given; `label` - names the menu, `isDisabled` keeps it from opening, and the options mean what - `component:ContextMenu`'s props of the same names mean; `destroy` removes + request (a long press, a right click, or Shift+F10), at `at` when given; `render(container)` + fills the menu's container with custom content in plain DOM; `label` names + the menu, `isDisabled` keeps it from opening, and the shared options mean + what `component:ContextMenu`'s props of the same names mean; `destroy` removes every listener it added. `useContextMenu(ref, options) → -{open, close}` is its thin React wrapper (FR6), and `component:ContextMenu` +{open, close}` is its thin React wrapper (FR6): it takes custom content as + `menuContent` JSX, as `component:ContextMenu` does, and hands the factory a + `render` that portals it into the container, its only work, and `component:ContextMenu` is built on it (FR7): one API at two layers (`architecture:public-component-api` INV21). - **FR5 — Each hook ships with docs and a playing-cards example.** Each public From 32814b98d50eaee8cc43a32f5f6ae9451b8534d3 Mon Sep 17 00:00:00 2001 From: Cindy Zhang Date: Tue, 27 Oct 2026 02:16:03 -0700 Subject: [PATCH 13/14] Merge main into spec/public-gesture-hooks --- .../AST-107-public-gesture-hooks/spec.md | 31 +++++++++++-------- 1 file changed, 18 insertions(+), 13 deletions(-) diff --git a/docs/specs/AST-107-public-gesture-hooks/spec.md b/docs/specs/AST-107-public-gesture-hooks/spec.md index c2dabbe6a6825..d0176e9f0fda7 100644 --- a/docs/specs/AST-107-public-gesture-hooks/spec.md +++ b/docs/specs/AST-107-public-gesture-hooks/spec.md @@ -64,11 +64,13 @@ import { createPanGesture, createDragToSnapPoints, createAnimator, + createContextMenu, } from '@astryxdesign/core'; import { usePanGesture, useDragToSnapPoints, useAnimator, + useContextMenu, } from '@astryxdesign/core/hooks'; usePanGesture(ref, { @@ -126,7 +128,8 @@ animator2.destroy(); to different snap points, which no motion role or theme knob expresses (`spec:AST-002` FR5); Core components keep theirs internal (`spec:AST-100` FR3). Under reduced motion the element goes to its snap point - without travel (`design:reduced-motion` DR1–DR3). `snapPoints` is sorted before use; an empty list, + without travel (`design:reduced-motion` DR1–DR3). `snapPoints` is sorted before use, and `onSettle` and + `settleTo` count indexes in that ascending order; an empty list, or `settleTo` with an index outside it, does nothing and warns in development. It calls `onSettle(index)` once the element settles. It returns `{settleTo(index)}`, which settles the element on a snap point without a @@ -181,8 +184,10 @@ onOpenChange?, presentation?}) → {open(at?), close(), destroy()}` request (a long press, a right click, or Shift+F10), at `at` when given; `render(container)` fills the menu's container with custom content in plain DOM; `label` names the menu, `isDisabled` keeps it from opening, and the shared options mean - what `component:ContextMenu`'s props of the same names mean; `destroy` removes - every listener it added. `useContextMenu(ref, options) → + what `component:ContextMenu`'s props of the same names mean; its menu follows the + WAI-ARIA menu pattern: focus starts on the first enabled row, Up and Down + move between rows, Home and End jump to the ends, Escape closes, and focus + returns to the element on close; `destroy` removes every listener it added. `useContextMenu(ref, options) → {open, close}` is its thin React wrapper (FR6): it takes custom content as `menuContent` JSX, as `component:ContextMenu` does, and hands the factory a `render` that portals it into the container, its only work, and `component:ContextMenu` @@ -214,16 +219,16 @@ onOpenChange?, presentation?}) → {open(at?), close(), destroy()}` ## Verification -| Contract | Verification | Representative states | Mutation or failure expectation | -| -------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| FR1 | Unit and browser tests of `usePanGesture` | a drag on each axis, a cancel, a press, a long press | a recognizer in the result, a missing state, a drag off its axis, or a press or long press reported as a pan fails | -| FR2 | Unit and browser tests of `useDragToSnapPoints` | a slow release, a flick past `flickThreshold` and the default flick speed, a release moving back, `settleTo` from a key | a settle on the wrong snap point, a reversed drag that settles elsewhere, or a missing `onSettle` fails | -| FR3 | Unit and browser tests of `useAnimator` | each method, Reduce Motion, an unattached ref, an unknown channel, a call after `destroy` | a missing method or channel, an `animate` off `springs.stateChange`, or motion that ignores Reduce Motion or a throw on an unknown channel or after `destroy` fails | -| FR4 | Export check of `@astryxdesign/core` and its hooks | the public exports | a recognizer, the arena, the internal animator module, or the resolver reachable from a public export fails | -| FR6 | Unit tests of each factory and its hook, server-render and import checks, and listener counts after `destroy` | each factory without React; each hook; a server import; `destroy` mid-drag | a hook with behavior its factory lacks, a listener left after `destroy`, or DOM work at import fails | -| FR7 | Source boundary check over Core and Lab against the gap table | every Core and Lab component that drags, snaps, animates one element, reorders, or animates layout | a component reaching internals for a job the public layer covers, or an internal use whose job is not in the gap table, fails | -| FR8 | Unit and browser tests of `createContextMenu` and `useContextMenu`, and ContextMenu's tests over them | a long press, a right click, and Shift+F10 on a plain element; `open(at)`; `close`; `destroy` while open; `items` and `render` | a context request that opens nothing, a listener left after `destroy`, a hook with behavior of its own, or a ContextMenu that bypasses the factory fails | -| FR5 | Docsite review of each hook's page and the playing-cards example | each hook's and factory's page; the playing-cards demo in plain JavaScript and in React | a hook without usage, options, a keyboard path, Reduce Motion, a component-prop note, or a live example, or a demo that imports anything but the public factories or hooks, fails | +| Contract | Verification | Representative states | Mutation or failure expectation | +| -------- | ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| FR1 | Unit and browser tests of `usePanGesture` | a drag on each axis, a cancel, a press, a long press | a recognizer in the result, a missing state, a drag off its axis, or a press or long press reported as a pan fails | +| FR2 | Unit and browser tests of `useDragToSnapPoints` | a slow release, a flick past `flickThreshold` and the default flick speed, a release moving back, `settleTo` from a key | a settle on the wrong snap point, a reversed drag that settles elsewhere, or a missing `onSettle` fails | +| FR3 | Unit and browser tests of `useAnimator` | each method, Reduce Motion, an unattached ref, an unknown channel, a call after `destroy` | a missing method or channel, an `animate` off `springs.stateChange`, or motion that ignores Reduce Motion or a throw on an unknown channel or after `destroy` fails | +| FR4 | Export check of `@astryxdesign/core` and its hooks | the public exports | a recognizer, the arena, the internal animator module, or the resolver reachable from a public export fails | +| FR6 | Unit tests of each factory and its hook, server-render and import checks, and listener counts after `destroy` | each factory without React; each hook; a server import; `destroy` mid-drag | a hook with behavior its factory lacks, a listener left after `destroy`, or DOM work at import fails | +| FR7 | Source boundary check over Core and Lab against the known public-API gap list in `architecture:react-component-runtime` INV13 | every Core and Lab component that drags, snaps, animates one element, reorders, or animates layout | a component reaching internals for a job the public layer covers, or an internal use whose job is not in the gap table, fails | +| FR8 | Unit and browser tests of `createContextMenu` and `useContextMenu`, and ContextMenu's tests over them | a long press, a right click, and Shift+F10 on a plain element; `open(at)`; `close`; `destroy` while open; `items` and `render` | a context request that opens nothing, a listener left after `destroy`, a hook with behavior of its own, or a ContextMenu that bypasses the factory fails | +| FR5 | Docsite review of each hook's page and the playing-cards example | each hook's and factory's page; the playing-cards demo in plain JavaScript and in React | a hook without usage, options, a keyboard path, Reduce Motion, a component-prop note, or a live example, or a demo that imports anything but the public factories or hooks, fails | ## Decision log From c63559252f3d0a75c443ec352bf462a42d6f3d24 Mon Sep 17 00:00:00 2001 From: Cindy Zhang Date: Tue, 27 Oct 2026 10:16:14 -0700 Subject: [PATCH 14/14] Merge main into spec/public-gesture-hooks --- docs/specs/AST-100-release-velocity/spec.md | 17 +++++++++-------- docs/specs/AST-107-public-gesture-hooks/spec.md | 2 +- 2 files changed, 10 insertions(+), 9 deletions(-) diff --git a/docs/specs/AST-100-release-velocity/spec.md b/docs/specs/AST-100-release-velocity/spec.md index 5b42bdd0a90c3..055b6509c406f 100644 --- a/docs/specs/AST-100-release-velocity/spec.md +++ b/docs/specs/AST-100-release-velocity/spec.md @@ -49,7 +49,8 @@ means for them. record. - Pinch scale velocity and scroll physics the browser owns. - Public API: the velocity source, its filter values, and every threshold stay - internal (`spec:AST-002` FR3). + internal (`spec:AST-002` FR3), except the public `flickThreshold` of + `spec:AST-107`'s snap-point drag (FR3). - Equivalent internal implementations remain valid when they satisfy this contract. @@ -117,13 +118,13 @@ means for them. ## Verification -| Contract | Verification | Representative states | Mutation or failure expectation | -| -------- | ------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | -| FR1 | One recorded sample stream read through two different components, plus a unit check | a sheet drag and a row swipe fed the same stream; a Lab gesture and a Core gesture fed the same stream; steady motion in x and y | Two components of the same kind reporting different velocities for the same stream, or a unit other than pixels per second | -| FR2 | Release velocity tests through a component over recorded iOS streams | recorded pan and scroll-view releases; acceleration before lift; a pause longer than the stillness interval before lift; one sample | A release that differs from the velocity iOS recorded for the same stream, or a non-zero release after a still pause | -| FR3 | Component tests at each threshold | a flick just under and just over a component's threshold; the same velocity across two components | Two components of the same kind reading different velocities for the same flick, or a threshold reachable from public API | -| FR4 | Unit tests with handler delay and per-pointer streams, plus real-browser pointer-event streams in Safari on iOS and Chrome on Android | delayed handlers with fixed event timestamps; touch, pen, and mouse streams | Velocity that changes with handler delay or pointer type | -| FR5 | Component tests in both directions | a flick toward the inline end in left-to-right and right-to-left | A flick toward the inline end treated as the opposite action in right-to-left | +| Contract | Verification | Representative states | Mutation or failure expectation | +| -------- | ------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| FR1 | One recorded sample stream read through two different components, plus a unit check | a sheet drag and a row swipe fed the same stream; a Lab gesture and a Core gesture fed the same stream; steady motion in x and y | Two components of the same kind reporting different velocities for the same stream, or a unit other than pixels per second | +| FR2 | Release velocity tests through a component over recorded iOS streams | recorded pan and scroll-view releases; acceleration before lift; a pause longer than the stillness interval before lift; one sample | A release that differs from the velocity iOS recorded for the same stream, or a non-zero release after a still pause | +| FR3 | Component tests at each threshold | a flick just under and just over a component's threshold; the same velocity across two components | Two components of the same kind reading different velocities for the same flick, or a threshold other than `spec:AST-107`'s `flickThreshold` reachable from public API | +| FR4 | Unit tests with handler delay and per-pointer streams, plus real-browser pointer-event streams in Safari on iOS and Chrome on Android | delayed handlers with fixed event timestamps; touch, pen, and mouse streams | Velocity that changes with handler delay or pointer type | +| FR5 | Component tests in both directions | a flick toward the inline end in left-to-right and right-to-left | A flick toward the inline end treated as the opposite action in right-to-left | ## Decision log diff --git a/docs/specs/AST-107-public-gesture-hooks/spec.md b/docs/specs/AST-107-public-gesture-hooks/spec.md index d0176e9f0fda7..60637da836474 100644 --- a/docs/specs/AST-107-public-gesture-hooks/spec.md +++ b/docs/specs/AST-107-public-gesture-hooks/spec.md @@ -226,7 +226,7 @@ onOpenChange?, presentation?}) → {open(at?), close(), destroy()}` | FR3 | Unit and browser tests of `useAnimator` | each method, Reduce Motion, an unattached ref, an unknown channel, a call after `destroy` | a missing method or channel, an `animate` off `springs.stateChange`, or motion that ignores Reduce Motion or a throw on an unknown channel or after `destroy` fails | | FR4 | Export check of `@astryxdesign/core` and its hooks | the public exports | a recognizer, the arena, the internal animator module, or the resolver reachable from a public export fails | | FR6 | Unit tests of each factory and its hook, server-render and import checks, and listener counts after `destroy` | each factory without React; each hook; a server import; `destroy` mid-drag | a hook with behavior its factory lacks, a listener left after `destroy`, or DOM work at import fails | -| FR7 | Source boundary check over Core and Lab against the known public-API gap list in `architecture:react-component-runtime` INV13 | every Core and Lab component that drags, snaps, animates one element, reorders, or animates layout | a component reaching internals for a job the public layer covers, or an internal use whose job is not in the gap table, fails | +| FR7 | Source boundary check over Core and Lab against the known public-API gap list in `architecture:react-component-runtime` INV13 | every Core and Lab component that drags, snaps, animates one element, reorders, or animates layout | a component reaching internals for a job the public layer covers, or an internal use whose job is not in the gap list, fails | | FR8 | Unit and browser tests of `createContextMenu` and `useContextMenu`, and ContextMenu's tests over them | a long press, a right click, and Shift+F10 on a plain element; `open(at)`; `close`; `destroy` while open; `items` and `render` | a context request that opens nothing, a listener left after `destroy`, a hook with behavior of its own, or a ContextMenu that bypasses the factory fails | | FR5 | Docsite review of each hook's page and the playing-cards example | each hook's and factory's page; the playing-cards demo in plain JavaScript and in React | a hook without usage, options, a keyboard path, Reduce Motion, a component-prop note, or a live example, or a demo that imports anything but the public factories or hooks, fails |