Public gesture hooks system spec¶
{
"paths": [
"packages/core/src/hooks/**",
"packages/core/src/dragToSnapPoints/createDragToSnapPoints.ts",
"packages/core/src/gestures/createPanGesture.ts"
]
}
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-017FR21). - Presses and long presses, which
useLongPressowns. - Animating the layout of an area, which
spec:AST-105owns. - Choosing a spring or curve beyond the theme's motion knobs
(
spec:AST-108).
Public contract¶
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 animator = useAnimator(ref);
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 —
usePanGesturereports a drag as values.usePanGesture(ref, {axis?, onPan})callsonPanwith{state, translation, velocity}as a drag on the element begins, changes, ends, or is cancelled.axislimits the drag to'x'or'y'. A finger, a mouse, and a pen all drive it (spec:AST-094FR43). It never hands out a recognizer object, and it recognizes no press or long press. A cancelled pan reportsvelocity{0, 0}, so nothing flings on cancel. - FR2 —
useDragToSnapPointssettles an element on snap points.useDragToSnapPoints(ref, {axis, snapPoints, flickThreshold?, onSettle})lets a drag move the element alongaxis, under every pointer, as FR1's does.snapPointsare offsets in pixels alongaxisfrom the element's resting position, in ascending order; unlike BottomSheet'ssnapPoints, 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 thanflickThreshold, 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-094FR37). 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-002FR5); Core components keep theirs internal (spec:AST-100FR3). Under reduced motion the element goes to its snap point without travel (design:reduced-motionDR1–DR3).snapPointsis sorted before use, andonSettleandsettleTocount indexes in that ascending order; an empty list, orsettleTowith an index outside it, does nothing and warns in development. It callsonSettle(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 —
useAnimatoranimates one element.useAnimator(ref)returnsanimatorfor the element behindref, the element refusePanGestureanduseDragToSnapPointstake, so a drag and an animation share one element; it hands out no ref of its own.animatoris a public handle,AnimatorHandle, over the channelsx,y,scale,rotate, andopacity, distinct from the internal animator module:animate(target, {velocity?}) → Promise<void>springs the given channels totarget;decay(velocity) → Promise<void>coasts them from a velocity;set(values)jumps them;get()andgetVelocity()read them; andstop()halts them where they are. Reduce Motion is planned for every animation (design:reduced-motionDR1–DR3). Everyanimateplays on thesprings.stateChangemotion role (spec:AST-094FR4), which follows the theme's tempo and character (spec:AST-108FR3), and everydecayplays on the fixed momentum decay (spec:AST-108FR4); choosing any other spring or curve is not offered.animateon a channel it does not know, any call beforerefattaches, and any call afterdestroydo nothing and resolve at once. A lateranimate,decay,set, orstopon a channel resolves that channel's earlier promise where it stopped. A remount starts from the element's resting values; no animator values are kept after an unmount. -
FR4 — One hook per job.
usePanGesturedoes not do presses or long presses, whichuseLongPressowns.useAnimatoranimates one element, anduseAnimatedLayoutanimates an area (spec:AST-105). A component's own props, such as BottomSheet'ssnapPointsor Carousel'shasSnap, stay the component path to the same behavior. Everything else in the gesture and motion modules stays internal (architecture:public-component-apiINV21). -
FR6 — Each hook is a thin wrapper over a factory. Each hook has a non-React factory in the same
create…family ascreateReorderable:createPanGesture(element, {axis?, onPan}) → {destroy},createDragToSnapPoints(element, {axis, snapPoints, flickThreshold?, onSettle}) → {settleTo(index), destroy}, andcreateAnimator(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-apiINV21): the hook delegates entirely to its factory and has no behavior of its own.destroyremoves 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-runtimeINV13).createPanGesture'sdestroy()during a drag reportscancelledonce;usePanGesture's unmount reports nothing (no callback after unmount).decayonopacitystops at 0 or 1. -
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, anduseAnimatedLayout), 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 inarchitecture:react-component-runtimeINV13.createReorderable's plain-element attach path (spec:AST-103) covers collections that are not List. The internals beneath the public pan and snap-point drag arecreatePan, increatePanGesture.ts, andcreateSnapDrag, increateDragToSnapPoints.ts. No package entry exports them.createPantakes the recognizer's own options: which pointers and scrolls start the drag, its claim distance and a gate on its begin. Its reports add the claim's travel and what drives the drag.createPanGesturehas none of these: it starts on every pointer and no scroll.createSnapDragtakes a model of where a drag draws its element and where a release lands. It also takes the pan's own options and draws into a custom property when given one.createDragToSnapPointshas neither: it follows the finger one for one, drawstranslate, and lands each release by Core's one release policy. -
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), atatwhen given;render(container)fills the menu's container with custom content in plain DOM;labelnames the menu,isDisabledkeeps it from opening, and the shared options mean whatcomponent: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, a press outside the menu closes it (skipping the compatibility mouse events a finger's press sends; under a finger, asspec:AST-094FR32, FR33 and FR35 say), and focus returns to the element on close;destroyremoves every listener it added.useContextMenu(ref, options) → {open, close}is its thin React wrapper (FR6): it takes custom content asmenuContentJSX, ascomponent:ContextMenudoes, and hands the factory arenderthat portals it into the container, its only work, andcomponent:ContextMenuis built on it (FR7): one API at two layers (architecture:public-component-apiINV21). - FR5 — Each hook ships with docs and a playing-cards example. Each public
API here, factory and hook alike, and
createReorderable'spositions(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 custompositions.
Current-state impact¶
architecture:public-component-apiINV21 counts a hook over a public factory, and a component built entirely on one, as one API with it.architecture:react-component-runtimeINV13 gains three rules: the recognizer family is the only class family, told apart bykind, neverinstanceof, and the velocity tracker moves to acreate…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-runtimeINV13 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 pan and an animator on one ref |
a missing method or channel, a ref handed out by the hook, 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; an outside press with a mouse and with a finger |
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
<ContextMenu> is built on the same factory.
Rejected: a context menu reachable only through the <ContextMenu> wrapper.
DEC-4 — Edge behaviors of the public animator and pan gesture¶
Reference: spec:AST-107/DEC-4
Decider: cixzhang, 2026-11-02
A cancelled pan reports zero velocity; the factory's destroy() mid-drag reports cancelled once and the hook's unmount reports nothing; an opacity decay is clamped to 0–1; a remount starts from resting values.
Rejected: reporting the last velocity on cancel; callbacks after unmount; unclamped opacity; keeping values across an unmount (a new keyed element could inherit an off-screen position while still taking keyboard focus).
Open questions¶
None.
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx