Skip to content
Merged
Changes from 1 commit
Commits
Show all changes
25 commits
Select commit Hold shift + click to select a range
fed2e1c
spec(AST-107): public gesture hooks — usePanGesture, useDragToSnapPoi…
cixzhang Oct 26, 2026
eac7f2c
spec(AST-107): snap-point units and release rule as behavior; useAnim…
cixzhang Oct 27, 2026
92becf1
Merge remote-tracking branch 'origin/main' into spec/public-gesture-h…
cixzhang Oct 27, 2026
1d9b484
spec(AST-107): flickThreshold defaults to the sheet's measured flick …
cixzhang Oct 27, 2026
55870f6
Merge remote-tracking branch 'origin/main' into spec/public-gesture-h…
cixzhang Oct 27, 2026
1f22c68
spec(AST-107): non-React factories under the hooks; Core and Lab use …
cixzhang Oct 27, 2026
ab539aa
spec(AST-107): the public createAnimator is Core's one animator factory
cixzhang Oct 27, 2026
b1d8762
spec(AST-107): the full known-gap table; attach covers non-List colle…
cixzhang Oct 27, 2026
19cf178
spec(AST-107): a headless context menu — createContextMenu and useCon…
cixzhang Oct 27, 2026
7c6f609
Merge remote-tracking branch 'origin/main' into spec/public-gesture-h…
cixzhang Oct 27, 2026
012dea9
spec(AST-107 +): gap list and name rule move to react-component-runti…
cixzhang Oct 27, 2026
88396a4
Merge remote-tracking branch 'origin/main' into spec/public-gesture-h…
cixzhang Oct 27, 2026
a15fc43
spec(AST-107 +): flickThreshold source and admission; FR3 sentence sp…
cixzhang Oct 27, 2026
28c2719
spec(react-component-runtime): the class exception stays the recogniz…
cixzhang Oct 27, 2026
f10e47a
Merge remote-tracking branch 'origin/main' into spec/public-gesture-h…
cixzhang Oct 27, 2026
ef7ba82
spec(AST-107): pointer scope, interrupted and early calls, flickThres…
cixzhang Oct 27, 2026
2749909
Merge main into spec/public-gesture-hooks
cixzhang Oct 27, 2026
4fb2207
Merge remote-tracking branch 'origin/main' into spec/public-gesture-h…
cixzhang Oct 27, 2026
687ec4c
Merge main into spec/public-gesture-hooks
cixzhang Oct 27, 2026
387feee
Merge remote-tracking branch 'origin/main' into spec/public-gesture-h…
cixzhang Oct 27, 2026
32814b9
Merge main into spec/public-gesture-hooks
cixzhang Oct 27, 2026
738ca2c
Merge main into spec/public-gesture-hooks
cixzhang Oct 27, 2026
f9412c1
Merge remote-tracking branch 'origin/main' into spec/public-gesture-h…
cixzhang Oct 27, 2026
c635592
Merge main into spec/public-gesture-hooks
cixzhang Oct 27, 2026
e2455c8
Merge remote-tracking branch 'origin/main' into spec/public-gesture-h…
cixzhang Oct 27, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
142 changes: 142 additions & 0 deletions docs/specs/AST-107-public-gesture-hooks/spec.md
Original file line number Diff line number Diff line change
@@ -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]

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This pull request also amends architecture:react-component-runtime, and FR5 requires docs for the factories and createContextMenu/useContextMenu, but affects_architecture, affects_consumer_docs and the Current-state impact name none of them, nor FR7's component migrations or ContextMenu's rebuild.

affects_families: []
affects_contributing: []
affects_consumer_docs: [usePanGesture, useDragToSnapPoints, useAnimator]
---

# Public gesture hooks system spec

<!-- path-applicability:v1 -->

```json
{
"paths": ["packages/core/src/hooks/**"]
}
```

<!-- Describe the system, not the project: present tense, what it does. No proposals, history, pull requests, or research in the record; see docs/contributing/spec-writing.md and report its rubric results in the pull request. -->

## 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],

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

snapPoints shares BottomSheet's public option name, where a number is a viewport fraction in (0, 1], so 0, 240 and 480 would all be ignored there. Could FR2 state this option's unit and origin, or use a different name?

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,

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Which pointers drive this drag? architecture:react-component-runtime INV13 still says “Where the primary pointer is fine, no recognizer attaches”, so a desktop mouse or trackpad drag may do nothing, FR5’s live examples included. Could FR1 and FR2 state the pointer scope, and whether INV13’s fine-pointer rule binds the public layer?

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Non-blocking: could FR1 name state's values and say whether translation and velocity are points or scalars along axis? With no _experimental suffix, the first implementation would otherwise fix them for a stable API.

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

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

resolveSnapPoint is an internal function, and architecture:knowledge-contracts INV18 keeps internal function names out of requirements unless they are public contracts (the Non-goals keep the resolver internal). It is also not on main yet. Suggest stating the rule as behavior, citing spec:AST-094 FR37 for the moving-back cancel, and giving flickThreshold's default and unit.

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

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No current record or code defines a "default motion role": spec:AST-094 FR4 names each role for its use, and none is a default. Which role should useAnimator play? The FR3 verification row depends on the answer.

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

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

spec:AST-103 FR1 on main lists only onReorder and isReorderable as createReorderable options, and positions arrives with #8601. Land that first, or drop this clause and the fanned hand until it does.

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 |

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Under architecture:public-component-api INV12, the animator that useAnimator() returns is reachable from a public export, so this row fails FR3 as written. Suggest giving the public object its own name, with signatures for decay, set, get, getVelocity and stop, and rewording this row and the Non-goal to mean the internal animator module.

| 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.
Loading