diff --git a/docs/architecture/public-component-api.md b/docs/architecture/public-component-api.md index 15068b81b1469..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, ] --- @@ -194,7 +196,11 @@ 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, 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 public promises until promotion. @@ -255,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/architecture/react-component-runtime.md b/docs/architecture/react-component-runtime.md index 31e4af0d9ff64..52607dfaea885 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,24 @@ 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`. (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 + 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 @@ -327,6 +350,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. @@ -340,16 +365,16 @@ 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 gesture listener in a component that uses no gesture, or an idle document listener outside a press other than the one shared press controller and the one stray-click swallower, or an import of `@astryxdesign/core/internal/*` outside Core and Lab fails | -| INV15 | Unit tests of the animator's value mode and real-browser proofs of its adopters | A value off its motion role, a count past the component's swap size, a count or cross-fade under reduced motion with a coarse or a fine pointer, an intermediate value announced, or a public export 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 gesture listener in a component that uses no gesture, or an idle document listener outside a press other than the one shared press controller and the one stray-click swallower, 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 | +| INV15 | Unit tests of the animator's value mode and real-browser proofs of its adopters | A value off its motion role, a count past the component's swap size, a count or cross-fade under reduced motion with a coarse or a fine pointer, an intermediate value announced, or a public export fails | diff --git a/docs/specs/AST-094-touch-presentations/spec.md b/docs/specs/AST-094-touch-presentations/spec.md index 5e0e66f3ecd2a..9c0995b96a26d 100644 --- a/docs/specs/AST-094-touch-presentations/spec.md +++ b/docs/specs/AST-094-touch-presentations/spec.md @@ -122,7 +122,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). The three knobs 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. The three knobs join the motion configuration of `architecture:theme-authoring-contract` and `architecture:theme-tokens` (`spec:AST-108`). 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..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. @@ -74,7 +75,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 @@ -116,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 new file mode 100644 index 0000000000000..60637da836474 --- /dev/null +++ b/docs/specs/AST-107-public-gesture-hooks/spec.md @@ -0,0 +1,274 @@ +--- +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, architecture:react-component-runtime] +affects_families: [] +affects_contributing: [] +affects_consumer_docs: + [ + usePanGesture, + useDragToSnapPoints, + useAnimator, + createPanGesture, + createDragToSnapPoints, + createAnimator, + createContextMenu, + useContextMenu, + ] +--- + +# 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 factories and the +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. + +## Non-goals + +- 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 beyond the theme's motion knobs + (`spec:AST-108`). + +## Public contract + +```tsx +import { + createPanGesture, + createDragToSnapPoints, + createAnimator, + createContextMenu, +} from '@astryxdesign/core'; +import { + usePanGesture, + useDragToSnapPoints, + useAnimator, + useContextMenu, +} from '@astryxdesign/core/hooks'; + +usePanGesture(ref, { + axis: 'x', + onPan: ({state, translation, velocity}) => {}, +}); + +const {settleTo} = useDragToSnapPoints(ref, { + axis: 'y', + snapPoints: [0, 240, 480], + flickThreshold: 1008, + onSettle: index => {}, +}); + +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 + +- **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'`. 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`, 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, + except that a release faster than `flickThreshold`, in pixels per second + (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). The threshold is public because a product's own + 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). Under reduced motion the element goes to its snap point + 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 + drag and is the keyboard path. +- **FR3 — `useAnimator` animates one element.** `useAnimator()` returns + `{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), 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, 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 + 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). + +- **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 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. 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; 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, 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; `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; 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` + 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 + 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 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 + +- `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 + 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 + 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, 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 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 | + +## 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. + +### 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. + +### 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.