Skip to content

feat(core): the shared drag path takes a component's own drag - #9720

Merged
cixzhang merged 6 commits into
meta:mainfrom
vjeux:uikit/c12-shared-drag-internal-options
Nov 12, 2026
Merged

cixzhang merged 6 commits into
meta:mainfrom
vjeux:uikit/c12-shared-drag-internal-options

Conversation

@vjeux

@vjeux vjeux commented Nov 3, 2026 •

Copy link
Copy Markdown
Contributor

Own commits, over main: vjeux/astryx@79b95eb...4b59cba, then merges of main: vjeux/astryx@4b59cba...36ebfcf

User need

A Core component whose drag needs more than the public layer should run the shared drag path, not a private copy. Item's swipe row is the first.

Problem and solution fit

  • The public createPanGesture and createDragToSnapPoints now run on internal factories, createPan and createSnapDrag. Their behavior does not change.
  • A Core component calls the internal factories for jobs the public layer does not expose. architecture:react-component-runtime INV13 lists those jobs, as spec:AST-107 FR7 requires.
  • The swipe row's rebuild, feat(core): swipe actions come from createSwipe on the shared drag path #8690, is the first user; the custom property option has no caller here.

Current specification

spec:AST-107 FR1 and FR2 keep the public pan and snap-point drag. FR7 lets Core reach internal modules only for INV13's listed gaps.

Public delta and caller burden

None: nothing new is exported, and packages/core/api-report.md does not change.

Design and alternatives

  • createPan, under createPanGesture: which pointers and scrolls start a drag, its claim distance, a begin gate and the selection lock. Each report says what drove the drag.
  • createSnapDrag, under createDragToSnapPoints:
    • a model of where a drag draws the element and where a release or a cancel lands;
    • a custom property an x drag draws into; a y drag that asks for one warns;
    • settleTo with a spring, a velocity and a touch release;
    • an onPass callback on the first frame the settle's curve passes an offset, with no timer.
  • The animator draws x into one registered custom property, with an optional companion drawn from x in the same keyframes. These keyframes are never shared with another call's.

Alternative: public options. Not now: each serves one Core job, and INV13 records them as known gaps.

Evidence

  • createSnapDrag.test.ts covers each internal option: the models, a release or a cancel, the custom property and its companion, and the onPass callback.
  • Nine setSnapPoints cases each fail without their fix, and two more pin a dead-zone re-aim's cancel and settleTo after an empty list.
  • A createPan case runs a real finger, mouse and pen through the document's gesture host and checks the input each reports.
  • The public factories' tests pass; the Reduce Motion test's stand-in is now createPan.

Scope

  • One capability is added.
  • Unrelated fixes, cleanup, and policy changes were removed or split.
  • Consumer docs, focused tests, and migration evidence ship with the feature.
  • Public text and artifacts contain no internal Meta context.

Testing

This head, 36ebfcf220, merges main 17fcb15daf into ba0f0b76a2, which merged main 2aa31a3cee into 4b59cba106. Neither merge has a conflict, and this change's own lines are as they were. INV13 keeps main's timing note beside this change's entry. Main's ref-sync records (#10161, #11368) touch react-component-runtime.md beside this change's INV13 entry. This change's three product files hold no React code, so they write no ref during render and copy no value through an Effect. 4b59cba106 is the earlier head: 81c8831753, d9abfa50a9 and a1a2db3a3e, moved off #9261 onto main with no line changed, and an AST-107 paragraph. The suites ran at this head:

  • The motion, snap-point, gesture and hook unit suites: 3,144 pass in 144 files.
  • tsc reports 0 errors in Core. Strict ESLint reports 0 errors on the three product files, and pnpm check:knowledge passes. pnpm review:pre reports 0 findings.
  • At 4b59cba106, not re-run at this head, the node project: every file outside packages/cli passes, the bundle guards under scripts/ among them (94 pass, 2 skip). In packages/cli, 11 files that pack or build against Core's dist failed in that run, before this checkout had built it. Run together again after the build, 10 of them pass and packed-gather-cache.test.mjs fails 2 of its 17 tests: "a kept catalog › answers as a fresh gather, and is used while nothing changed" (expected 9111872 to be 9111477, the kept entry's inode, at line 300) and "a kept catalog › is not used after an edit, an added or removed file, or a copy that keeps the time" (expected [ 'miss', 'miss' ] to deeply equal [ 'miss', 'hit' ], at line 307). Run alone twice after that, it passes all 17 both times. The test reads nothing this change touches.
  • The snap-point drag, gesture, createAnimator and animator interaction proofs in Chromium, at 1 worker: 116 pass and 4 skip. Each skip is a test.skip the spec declares for that engine's driver (trackpad scrolls).
  • The same proofs in WebKit, with CI's four CPUs: 101 pass and 19 skip. Each skip is a test.skip the spec declares for that engine's driver (pen input, native scrolls, frame timing, Chromium's tracing).

Public and internal API delta

Size: +1410/−197 lines in 9 files (17fcb15daf..36ebfcf220); product code +677/−177.

App-level bytes, gzip, React and StyleX left out, with this change's code measured on main 79b95ebe36. The page has Button, Heading, Text, TextInput, Selector, DropdownMenu, MoreMenu, Popover, Tooltip, Dialog, BottomSheet and TabList. It loads 196,002 B up front on main and 196,409 B with this change (+407 B). With a List added: 211,737 B and 212,144 B (+407 B).

Public: none. createPanGesture and createDragToSnapPoints keep their options and behavior.

Internal; no package entry exports them, and no module or hook is added:

  • createPan and its types PanState, PanInput, PanEvent, PanOptions and Pan, in gestures/createPanGesture.ts, beside the public factory. Why: a component's own drag starts on the same pointers and scrolls, with the same claim and selection lock.
    createPan(element, {axis: 'x', onPan: event => …})
    Existing modules considered: it lives in createPanGesture.ts. createPanGesture's public options and events stay as they are, since a begin gate, the claim and the input kind would widen them.
  • createSnapDrag and its types SnapDragMove, SnapDragRelease, SnapDragTarget, SnapDragLanding, SnapDragModel, SnapDragOptions, SettleOptions and SnapDrag, in dragToSnapPoints/createDragToSnapPoints.ts, beside the public factory. Why: a component runs its own drag on the shared path and declares only its stops and its release.
    createSnapDrag(element, {axis: 'x', snapPoints: [0, -72], onSettle: index => …})
    Existing modules considered: it lives in createDragToSnapPoints.ts. The public options stay as they are, since the drag's model, its custom property, settleTo and onPass would become public API.
  • The motion engine's customProperty option renders x into a registered custom property instead of translate, with an optional companion. Why: every part of an element can read one value, such as a row's swipe travel. The engine keeps no state for it: it catches only a repeat registration's InvalidModificationError, and throws any other error.
    createMotionEngine(root, {customProperty: {name: '--travel', syntax: '<length>'}})
    Existing options considered: translate moves one element. One animation per part would need its own keyframes, and the parts could drift apart.
  • The owning record names them: spec:AST-107 FR7 names createPan and createSnapDrag and the modules that hold them.

Writing rubric results

Records edited:

  • spec:AST-107 FR7, this round: what createPan takes (the recognizer's own options; the claim's travel and the input in its reports) and what createSnapDrag takes (a model, the pan's options, a custom property), which createPanGesture and createDragToSnapPoints do not.
  • architecture:react-component-runtime INV13: the known public-API gaps gain three drag jobs, for spec-owner review. They are a drag's own input filter, claim distance and begin gate; a snap-point drag's own model; and a drag drawn into one custom property.
  • spec:AST-107: FR7 names createPan and createSnapDrag and the public modules that hold them, and that no package entry exports them. Its path applicability lists dragToSnapPoints/createDragToSnapPoints.ts and gestures/createPanGesture.ts.

Results:

  • R1 narration: none. The edits state what the system does, in the present tense.
  • R2 research: none.
  • R3 evidence: INV13's addition cites spec:AST-057 AR2, FR2 and FR5; no evidence cell names a pull request.
  • R4 rejected alternatives: none added.
  • R5 change references: none.
  • R6 open questions: none.

@vercel

vercel Bot commented Nov 3, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
astryx Ready Ready Preview Nov 12, 2026 12:32pm UTC

Request Review

@meta-cla meta-cla Bot added the CLA Signed This label is managed by the Meta Open Source bot. label Nov 3, 2026
@github-actions github-actions Bot added the needs:design-review Affects visuals — Design should review label Nov 3, 2026
@github-actions github-actions Bot added the needs:spec-owner-review Current knowledge records await owner approval label Nov 3, 2026
@astracat-bot

astracat-bot Bot commented Nov 3, 2026 •

Copy link
Copy Markdown
Contributor

AI review status for this pull request.

Review status Updated
🟢 Reviewed (for maintainers only) Nov 12, 2026, 12:43 PM UTC

@cixzhang

cixzhang commented Nov 3, 2026

Copy link
Copy Markdown
Contributor

/approve-spec 91d713b

@github-actions github-actions Bot removed the needs:spec-owner-review Current knowledge records await owner approval label Nov 3, 2026

@astracat-bot astracat-bot Bot left a comment

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.

Requesting changes before this can merge.

  • The diff against main has 7,917 authored lines because it also carries #8653, #8655, #8658 and #9261; please land those first, or rebase once they land, so this pull request reviews as its own 1,363-line commit.

The internal options themselves have spec cover: AST-107 governs the public layer, and an engineering owner approved the AST-107 and INV13 edits for this head. One question about the onPass contract and three small comment fixes are inline. None of them blocks.

[Automated review]

Comment thread packages/core/src/gestures/createPan.ts Resolved
Comment thread packages/core/src/gestures/createPan.ts Resolved
@vjeux
vjeux force-pushed the uikit/c12-shared-drag-internal-options branch from 91d713b to fce60ce Compare November 10, 2026 03:20
@vjeux vjeux changed the title feat(core): the shared drag path takes a component's own drag (internal options) feat(core): the shared drag path takes a component's own drag Nov 10, 2026
@github-actions github-actions Bot added the needs:spec-owner-review Current knowledge records await owner approval label Nov 10, 2026
@github-actions

github-actions Bot commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

PR Analysis Report

🔎 Preview · 36ebfcf

Storybook · Sandbox · built from this PR's head

Modified components

Component Size LoC
TimeInput 168.3 kB (+440 B) · 16.4 kB CSS (0) —
SegmentedControl 100.9 kB (+434 B) · 6.9 kB CSS (0) —
Switch 107.6 kB (+429 B) · 10.0 kB CSS (0) —
32 more components
Component Size LoC
Lightbox 127.4 kB (+424 B) · 10.9 kB CSS (0) —
lab/PageControl 77.5 kB (+412 B) · 709 B CSS (0) —
lab/NavigationScreen 84.3 kB (+403 B) · 1.5 kB CSS (0) —
lab/NavigationStack 84.3 kB (+403 B) · 1.5 kB CSS (0) —
BottomSheet 69.8 kB (+397 B) · 7.7 kB CSS (0) —
Slider 113.1 kB (+392 B) · 8.8 kB CSS (0) —
SideNav 118.7 kB (+383 B) · 11.7 kB CSS (0) —
lab/CommentComposer 156.8 kB (+373 B) · 1.9 kB CSS (0) —
PowerSearch 300.8 kB (+371 B) · 24.7 kB CSS (0) —
DateInput 194.3 kB (+370 B) · 17.4 kB CSS (0) —
lab/CommentThread 353.5 kB (+363 B) · 2.4 kB CSS (0) —
Popover 95.8 kB (+354 B) · 14.6 kB CSS (0) —
lab/TourStep 102.0 kB (+354 B) · 590 B CSS (0) —
DateTimeInput 216.8 kB (+352 B) · 19.1 kB CSS (0) —
ChatLayout 86.6 kB (+347 B) · 10.9 kB CSS (0) —
lab/Comments 360.2 kB (+346 B) · 2.5 kB CSS (0) —
lab/ChatReactionBar 112.2 kB (+334 B) · 1.1 kB CSS (0) —
lab/ChatEmojiPicker 111.0 kB (+332 B) · 773 B CSS (0) —
lab/TabBar 82.9 kB (+326 B) · 1.8 kB CSS (0) —
TableCell 114.5 kB (+2 B) · 18.2 kB CSS (0) —
MoreMenu 102.7 kB (+1 B) · 17.9 kB CSS (0) —
ContextMenu 113.3 kB (0) · 17.8 kB CSS (0) —
DropdownMenu 102.4 kB (0) · 17.9 kB CSS (0) —
Pagination 115.5 kB (0) · 18.2 kB CSS (0) —
Selector 105.4 kB (0) · 17.8 kB CSS (0) —
Table 130.4 kB (0) · 18.7 kB CSS (0) —
TableHeaderCell 114.1 kB (0) · 18.0 kB CSS (0) —
Tokenizer 102.0 kB (0) · 19.5 kB CSS (0) —
lab/TabBarItem 3.9 kB (0) · 1.8 kB CSS (0) —
richtext/RichTextEditorToolbar 284.7 kB (0) · 454 B CSS (0) —
Markdown 193.4 kB (−1 B) · 21.0 kB CSS (0) —
MultiSelector 99.7 kB (−1 B) · 17.2 kB CSS (0) —

Package size: @astryxdesign/core 7.40 MB packed (+8.3 kB); no new dependencies.

Not run on this PR: add ci:run-visual, ci:run-a11y or ci:run-rtl to run them.


Generated by PR Enrichment workflow | View full report

@astracat-bot astracat-bot Bot left a comment

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.

Approval waits on an engineering owner's spec decision; no blocking code defect was found.

  • This pull request adds three known public-API gaps to architecture:react-component-runtime INV13, and the existing /approve-spec names an earlier head, so an engineering owner needs to approve again by commenting /approve-spec with this pull request's full head SHA (the author may do so as an engineering owner).
  • That decision should also say which rule governs a swipe row's release, because the animator's new customProperty channel animates on the main thread while spec:AST-094 FR5 requires a touch presentation's release to run off the main thread and spec:AST-057 FR2 asks for the row's travel in a custom property.

Six non-blocking fixes are noted inline: the onPass contract, a y drag with customProperty, the Reduce Motion test's stand-in, and three comments. Merging this pull request also lands #9261's commit.

[Automated review]

@astracat-bot astracat-bot Bot left a comment

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.

Approval waits on an engineering owner's spec decision, and one code fix is needed.

  • This pull request adds three known public-API gaps to architecture:react-component-runtime INV13 and the only /approve-spec names an earlier head, so an engineering owner needs to approve them with /approve-spec and the full head SHA (the author may do so as an engineering owner), and that decision should say which rule governs a swipe row's release, since the animator's new customProperty channel animates on the main thread while spec:AST-094 FR5 requires a touch presentation's release to run off it.
  • Miss: createSnapDrag's setSnapPoints keeps the resting index from the old list (createSnapDrag.ts:413-415), so after the list shrinks a cancelled drag calls onSettle with an index that no longer exists and leaves the element between points; re-resolve the index against the new points and add a test.

Every earlier inline point is fixed at this head. A few non-blocking notes on comments and on the description's "tests do not change" are inline. Merging this pull request also lands #9261's commit.

[Automated review]

Comment thread packages/core/src/motion/animator.ts Resolved
@vjeux
vjeux force-pushed the uikit/c12-shared-drag-internal-options branch from d86aebe to 02cabc5 Compare November 10, 2026 04:50
@cixzhang

Copy link
Copy Markdown
Contributor

/approve-spec 02cabc5

@github-actions github-actions Bot removed the needs:spec-owner-review Current knowledge records await owner approval label Nov 10, 2026

@astracat-bot astracat-bot Bot left a comment

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.

Changes requested: one fix in setSnapPoints; the spec side is settled.

  • setSnapPoints (packages/core/src/dragToSnapPoints/createSnapDrag.ts:426) re-aims a settle only when no drag is in progress, so a settle still running under a drag inside its dead zone lands on a snap point the new list no longer has and onSettle names the new list's index; re-aim when the drag has not caught the settle (drag == null || !drag.caught), re-resolve drag.startIndex there, and add the case to createSnapDrag.test.ts.

An engineering owner approved the three INV13 entries at this head; spec:AST-094 FR5 still names no exception for a release drawn into a custom property, so the swipe row's rebuild should cite that approval or amend FR5. The earlier setSnapPoints finding is fixed, the public pan and snap-point drag behave as before, and no public API changes. A few non-blocking comment notes are inline.

[Automated review]

Comment thread packages/core/src/motion/animator.ts Resolved
Comment thread packages/core/src/motion/animator.ts Resolved
@vjeux
vjeux force-pushed the uikit/c12-shared-drag-internal-options branch from 02cabc5 to 960e7b6 Compare November 10, 2026 05:38
@vjeux
vjeux requested a review from josephfarina as a code owner November 12, 2026 04:16
@vjeux
vjeux marked this pull request as draft November 12, 2026 06:18
@vjeux vjeux closed this Nov 12, 2026
@vjeux vjeux reopened this Nov 12, 2026
@vjeux
vjeux marked this pull request as ready for review November 12, 2026 06:20
@vjeux
vjeux marked this pull request as draft November 12, 2026 10:07
@github-actions github-actions Bot added the needs:spec-owner-review Current knowledge records await owner approval label Nov 12, 2026
@cixzhang

Copy link
Copy Markdown
Contributor

/approve-spec ba0f0b7

@github-actions github-actions Bot removed the needs:spec-owner-review Current knowledge records await owner approval label Nov 12, 2026

@astracat-bot astracat-bot Bot left a comment

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.

Approved pending CI: CI has not run on this head yet, and it runs once the pull request is marked ready for review. The internal pan and snap-point drag sit under the public factories without changing their options or behavior, and the spec edits that record their jobs carry an engineering owner's approval for this head. There are no blocking findings.

  • Non-blocking: set still promotes translate while the animator draws into a custom property (packages/core/src/motion/animator.ts:4529-4532); skip it for the custom channel, as animate already does.
  • Non-blocking: the internal snap-point drag's dev warnings name createDragToSnapPoints (packages/core/src/dragToSnapPoints/createDragToSnapPoints.ts:211, :428), so a Core caller is warned about a factory it never called.
Claims and files checked
  • Changeset: a Core component's own drag can run on the shared drag path through internal factories that take a begin gate, a drag model and a custom property, beside the public factories, not exported from the entry point: verified (createPanGesture.ts:57, createDragToSnapPoints.ts:114-136, index.ts:190-207).
  • Changeset: the animator draws x into a registered custom property: verified (animator.ts:378-398, :1229-1261).
  • The public pan and snap-point drag run on the internal factories and their behavior does not change: verified by reading (createPanGesture.ts:168-180, createDragToSnapPoints.ts:554-582; option and handle types identical to the base; the release reads the last drawn value, which the lift does not move).
  • The runtime record lists the new jobs as the gesture spec's FR7 requires: verified (react-component-runtime.md:314-320).
  • The custom-property option has no caller here and nothing new is exported: verified (no Core or Lab caller; root and hooks barrel re-export by name).
  • The internal pan takes pointer and scroll filters, a claim distance, a begin gate and the selection lock, and each report names its input: verified (recognizer options; createPanGesture.ts:93-101).
  • The internal snap-point drag takes a model, an x-only custom property that warns for y, settle springs, velocity and touch release, and a frame-read crossing callback with no timer: verified (createDragToSnapPoints.ts:88-157, :224-229, :299-316).
  • The companion is drawn in the same keyframes and custom-property keyframes are never shared: verified (animator.ts:1338-1343, :2055).
  • The new unit file covers each internal option, with nine layout-change cases plus two more, and a real-host case checks finger, mouse and pen input: verified by reading (createSnapDrag.test.ts, createPanGesture.test.tsx:342-360); the red-first runs were not repeated.
  • The Reduce Motion test's stand-in is now the internal pan: verified (createDragToSnapPoints.reducedMotion.test.ts:21-26).
  • This head merges main with no conflict and leaves the change's own lines as they were, and the earlier head moved three commits unchanged and added one spec paragraph: verified (merge tree matches the head; range-diff shows three identical commits).
  • The merged runtime-record updates sit beside the edited entry, and the three product files hold no React code: verified.
  • Size: +1410/−197 in 9 files, product code +677/−177: verified.
  • Suite, typecheck, lint, knowledge-check, browser-proof and bundle-size results: the author's runs; not reproduced here and pending CI.
  • Files: .changeset/shared-drag-component-drag.md clear; docs/architecture/react-component-runtime.md clear; docs/specs/AST-107-public-gesture-hooks/spec.md note (option list); createDragToSnapPoints.reducedMotion.test.ts clear; createDragToSnapPoints.ts note (warning names); createSnapDrag.test.ts clear; createPanGesture.test.tsx clear; createPanGesture.ts clear; animator.ts note (set promotion).

Automated review (maintainer link)

@vjeux
vjeux marked this pull request as ready for review November 12, 2026 11:13
@vjeux
vjeux marked this pull request as draft November 12, 2026 12:04
@github-actions github-actions Bot added the needs:spec-owner-review Current knowledge records await owner approval label Nov 12, 2026
@cixzhang

Copy link
Copy Markdown
Contributor

/approve-spec 36ebfcf

@cixzhang

Copy link
Copy Markdown
Contributor

Decision: D-20261112-368

@github-actions github-actions Bot removed the needs:spec-owner-review Current knowledge records await owner approval label Nov 12, 2026

@astracat-bot astracat-bot Bot left a comment

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.

Approved pending CI: CI has not run on this head yet; it runs once the pull request is marked ready for review. The internal pan and snap-point drag sit under the public factories without changing their options or behavior, and the spec edits that record their jobs carry an engineering owner's approval for this head. There are no blocking findings.

  • Non-blocking: set still promotes translate while the animator draws into a custom property (packages/core/src/motion/animator.ts:4529-4532); skip it for the custom channel, as animate already does.
  • Non-blocking: the internal snap-point drag's dev warnings name createDragToSnapPoints (packages/core/src/dragToSnapPoints/createDragToSnapPoints.ts:211, :428), so a Core caller is warned about a factory it never called.
  • Non-blocking: the FR7 sentence on createPan's options (docs/specs/AST-107-public-gesture-hooks/spec.md:192-193) reads as a complete list, while it takes every recognizer option except its direction.
Claims and files checked
  • Changeset: a Core component's own drag can run on the shared drag path through internal factories that take a begin gate, a drag model and a custom property, beside the public factories, not exported from the entry point: verified (createPanGesture.ts:57, createDragToSnapPoints.ts:114-136, index.ts:191-207).
  • Changeset: the animator draws x into a registered custom property: verified (animator.ts:389-398, :1235-1261).
  • The public pan and snap-point drag run on the internal factories and their behavior does not change: verified by reading (createPanGesture.ts:168-180, createDragToSnapPoints.ts:554-582; option and handle types identical to the base; the release reads the last drawn value, which the lift does not move).
  • The runtime record lists the new jobs as the gesture spec's FR7 requires: verified (react-component-runtime.md:314-320).
  • The custom-property option has no caller here and nothing new is exported: verified (no Core or Lab caller; root and hooks barrel re-export by name).
  • The internal pan takes pointer and scroll filters, a claim distance, a begin gate and the selection lock, and each report names its input: verified (recognizer options; createPanGesture.ts:93-101).
  • The internal snap-point drag takes a model, an x-only custom property that warns for y, settle springs, velocity and touch release, and a frame-read crossing callback with no timer: verified (createDragToSnapPoints.ts:88-157, :224-229, :296-319).
  • The companion is drawn in the same keyframes, and custom-property keyframes are never shared: verified (animator.ts:1334-1343, :2052-2055).
  • A repeat registration's error is caught and any other error is thrown: verified (animator.ts:1245-1260).
  • The new unit file covers each internal option, with nine layout-change cases plus two more, and a real-host case checks finger, mouse and pen input: verified by reading (createSnapDrag.test.ts, createPanGesture.test.tsx:342-360); the red-first runs were not repeated.
  • The Reduce Motion test's stand-in is now the internal pan: verified (createDragToSnapPoints.reducedMotion.test.ts:21-26).
  • This head and the one before it each merge main with no conflict, and the change's own lines are as they were: verified (each merge tree matches its head; the patch is unchanged).
  • The runtime record keeps the merged internal-subpath timing note beside the new entry, and the three product files hold no React code: verified.
  • The spec's path applicability lists the two modules, and the INV13 addition cites the row-actions spec's AR2, FR2 and FR5: verified.
  • Size: +1410/−197 in 9 files, product code +677/−177: verified.
  • Suite, typecheck, lint, knowledge-check, browser-proof and bundle-size results: the author's runs; not reproduced here and pending CI.
  • Files: .changeset/shared-drag-component-drag.md clear; docs/architecture/react-component-runtime.md clear; docs/specs/AST-107-public-gesture-hooks/spec.md note (option list); createDragToSnapPoints.reducedMotion.test.ts clear; createDragToSnapPoints.ts note (warning names); createSnapDrag.test.ts clear; createPanGesture.test.tsx clear; createPanGesture.ts clear; animator.ts note (set promotion).

Automated review (maintainer link)

@vjeux
vjeux marked this pull request as ready for review November 12, 2026 12:53
@cixzhang
cixzhang merged commit 06b7e61 into meta:main Nov 12, 2026
134 checks passed
@vjeux
vjeux deleted the uikit/c12-shared-drag-internal-options branch November 12, 2026 13:55
cixzhang pushed a commit that referenced this pull request Nov 14, 2026
…th (#8690)

* chore(core): the animator takes start: 'next-frame' in an input event

A caller handling an input event (a key, a click, a pointer, a touch)
runs in that event's own task, never in a frame callback, so the first
frame whose callbacks run after its call is the one that commits the
call's animations, however long the task ran. The animator cannot tell
that from a call a page's own frame callback makes before a busy task,
whose browser start is right, so the caller says so with the internal
option `start: 'next-frame'`. A call from rest made with it starts at
that frame, and a later listener of the same event that holds the main
thread delays the motion instead of letting it skip into its curve.

- Chromium tells the page the start a frame or more after the
  compositor takes it. Such a call starts at its first frame, as a call
  whose first frame comes within LATE_START_MS already does, and also
  when an unrelated task delayed that frame.
- WebKit dates the start at its last frame time before the task. The
  task's end is read at the call's first read, not at its first
  microtask, which runs before a later listener's block, so the dated
  start moves past the block. The first read stands for the task's end,
  so a first frame that merely comes late (more than LATE_START_MS after
  the call, with no block) moves the dated start to that frame too.
  Nothing was painted before it, so the motion waits for that slow frame
  instead of skipping into its curve.

The option marks the call's whole task, so every call of that task
moves together, in either order. A call without the option in another
task, a call with an explicit start, and a call that continues motion
keep the rule they had. Internal only: the public animator does not
take it.

* feat(core): the shared drag path takes a component's own drag

The public pan and snap-point drag keep their behavior (spec:AST-107
FR1, FR2). They now run on internal factories that a Core component can
use for a job the public layer does not expose (spec:AST-107 FR7):

- createPan, under createPanGesture: the recognizer's own options
  (which pointers and scrolls start the drag, its claim distance, a
  begin gate, a selection lock), and what drove the drag and its travel
  from where the touch began in each report.
- createSnapDrag, under createDragToSnapPoints: a model of where a drag
  draws its element (one for one, a spring, or nothing yet inside a dead
  zone, the first target catching a settle in flight) and where a
  release or a cancel lands; a custom property an x drag draws into (a y
  drag that asks for one warns); settleTo
  with a spring, a velocity and a touch release, returning the settle's
  motion; and an onPass callback on the first frame the settle's curve
  passes an offset (no timer).
- The animator draws x into a registered custom property (a length or a
  number), on the main thread, for a component whose parts all read one
  value, with an optional companion property drawn from x in the same
  keyframes. Those keyframes are never shared with another call's.

architecture:react-component-runtime INV13 names these jobs among the
known public-API gaps, and spec:AST-107's path applicability links the
two internal factories.

* fix(Item): a flick reveals swipe actions; only a deliberate drag fires

A fling opens the row at its actions and never fires one. Only the
finger's own travel past the commit point fires the outermost entry.
On a side with two or more entries, only a drag that starts on the
resting open row does. The panel wears no entry's colour: the entries
grow to fill it, and the entry that fires covers it from the commit
point until the row comes back or holds out. A tapped entry with
hasRemoval covers it the same way while the row holds out.

* Merge the #11054 head into the #9720 head

* Merge main

* feat(core): swipe actions come from createSwipe on the shared drag path

* Merge main

* Merge main

* Merge main

* fix(core): a held swipe row stays under the finger

From its claim on the touch, a finger's row is at the finger's travel
since touch-down at every frame until the release. No spring follows
the finger. Past the confirm point, a lead grows to the confirmation
offset on UIKit's tracking spring, and the row keeps it over that base.
The release's settle starts from the finger's velocity.

The full swipe still confirms on UIKit's measure, from its 25 px dead
zone; the release's half-open rule reads where the row is drawn.

Deprecated rows take the new behavior, and their docs say so.

* feat(core): swipe actions carry ids, and handlers get the row's key

Each SwipeAction has a required id, and createSwipe infers the ids as
literals. The Swipe it returns carries them in its type. So an id the
swipe lacks, a handler for fewer ids, or an action with no id fails to
compile.

onActivate receives {id, itemKey}: the action's id, and the ListItem's
itemKey or undefined on a plain Item. So one definition at module
scope serves every row. ListItem hands its Item a copy of the value
keyed with its itemKey, memoized on the value and the key.

A row keys its swipe on the ids. A new value with the same ids keeps
an open row open; one with other ids closes it.

The new API reuses ItemSwipeActionVariant and ItemSwipeBehavior, which
stay supported. DEP-0017 now deprecates four symbols: the swipeActions
and swipeBehavior props, and ItemSwipeAction and ItemSwipeActions,
which keep their released shape.

The codemod gives each literal entry with no id one from its side and
place, such as 'trailing-0', so its output compiles. It reports a
value whose entries it cannot see, and leaves the ItemSwipe* types as
they are.

The stories that taught swipeActions now pass swipe.

AST-057: FR1 and FR11 restated, DEC-10, verification rows, DEP-0017
and CLN-0025.

* refactor(core): createPan and createSnapDrag live in the public modules

createPan moves into createPanGesture.ts, and createSnapDrag into
createDragToSnapPoints.ts, as internal named exports beside the public
factories. No package entry exports them, and no behavior changes.

The animator registers a custom property with no state of its own. It
catches only a second registration's InvalidModificationError, and
throws any other error.

The change gains its changeset, an internal chore: Core ships it, and
no consumer sees it.

* docs(AST-107): name the internal pan and snap-point drag

FR7 names createPan and createSnapDrag and the modules that hold them.
The path list follows them into those modules.

* Merge #9720's head a1a2db3

#9720 folds createPan into createPanGesture.ts, and createSnapDrag into
createDragToSnapPoints.ts. This change's edits to createSnapDrag.ts move
with it into createDragToSnapPoints.ts, and its imports follow.

* refactor(core): the swipe keeps no registry, and folds two modules

A Swipe value carries its host under a Symbol.for key, not in a
realm-wide map. A swizzled Item still finds it, and swipeHost.ts
imports nothing at run time.

A row's root forwards its key events into the bridge the swipe layer
fills, on a row given swipe as on the deprecated path. swipeRoots.ts,
its map from roots to key handlers, and the attachment's root props go.

The release rules move from swipeRelease.ts into useSwipeAction.ts,
their only user. Item's loader for the deprecated props loads
SwipeActionsLayer itself. DeprecatedSwipeLayer.tsx goes, and its
released commit warning moves into Item's deprecated path.

The bundle guard follows: createSnapDrag lives in
createDragToSnapPoints.ts, and ListItem reads its swipe value through
swipeHost.ts to key it.

* test(cli): the records follow the swipe's modules and createSwipe

The resolution record opens useSwipeAction from its new place under
Swipe/, and drops ItemSwipeLayer, which no longer exists. The search
goldens for "close" and "delete" gain createSwipe, whose docs name both.

* test(core): the confirm lead's frames follow UIKit's tracking spring

Each frame between 10 % and 70 % of the lead must name the same start
on the tracking spring, within two frames. A lead that jumps, or that
plays on another curve, fails: with the lead set at once, no frame
falls in that band.

* docs(AST-094): name the compositor settle under FR5

FR5 names compositorSettle.ts, the settle a snap-point drag's parts
play on the compositor, and why the animator cannot play it. The path
list gains the module.

* docs(core): the swipe's doc comments sit on their declarations

The ids Effect's note names the drag it settles. outTravel's doc comment
and the layer component's doc comment go back above their declarations.
ListItem's swipe prop says that Item gets the swipe with this row's
itemKey added.

* fix(core): a touch on the outermost entry may confirm a full swipe

On a side with two or more entries, a full swipe confirmed only from the
row open on that side. A scroll that starts the row's close before the
touch moves made a drag that landed on the outermost entry unable to
confirm. Now a touch that lands on the side's outermost entry confirms
too, as the two-entry rule states.

A browser test lands a touch on Delete, scrolls the page, and drags past
the confirm point: Delete fires.

* fix(core): only a touch tap closes an open row, as before

A press by any pointer on an open row's content closed it, so a mouse
click on that content closed the row and activated nothing. No decision
asked for that. Again only a touch tap closes it, and a mouse's or a
pen's press reaches the row. AST-057 FR7 says so again.

The unit tests for a mouse's and a pen's press, and the WebKit test for
a mouse click on a row a trackpad opened, now expect the click to reach
the row and the row to stay open.

* test(cli): the swizzle proof renders the Swipe folder through a row

The Swipe folder exports createSwipe, not a component named Swipe, so
the proof's render step found nothing to render whenever a change
touched the folder. Its sample renders an Item whose swipe the copy's
createSwipe makes, as the samples of other folders without a component
do.

* docs(AST-057): FR7's verification row says a touch tap, as on main

FR7's verification row still named a press by a finger, a pen and a
mouse. It returns to main's words: a touch tap on the open row's content
closes it, and a tap that activates the row or paints a press fails.

* fix(core): only a press on an open row's outermost entry confirms

A press counted as landing on a side's outermost entry when its target
was inside that entry. The panel turns inert when a close begins, but
only when React commits it. So a press in the task between a scroll
that began the close and that commit still counted. Now a press counts
only while the row is open on that side.

A unit test scrolls the page and presses the outermost entry in one
task, then drags past the confirm point: nothing fires.

* Merge main

* refactor(core): the swipe's pan notes where a press lands

A capture listener on the row's root noted which outermost entry a
press landed on, beside the pan. The gesture host already offers each
touch to the pan, with its target. Now the pan's shouldReceiveTouch
notes it, so the two-entry rule reads the touch the pan took. A mouse
press or a trackpad's scroll never counts.

* docs(core): only a touch tap closes an open row, in each description

The swipe prop's doc comment said a press by any pointer closes an open
row, and the dismissal changeset said a tap or a click. AST-057 said a
press starts the close. Each now says a touch tap, as FR7 does. The
ListItem swipe prop's doc comment says Item gets this row's itemKey.

* docs(AST-094): a swipe row's close starts on the next frame

FR6 says a swipe row's close that a touch tap on its content, Escape or
a press outside it starts uses the animator's internal next-frame start.
The first frame after the input event's task commits it, so the close
never skips ahead into its curve.

* docs(core): the swipe's notes describe the held row

The gesture-system changeset said a swipe begins at UIKit's 25 px, and
the swipe constants said the row lags the finger. Since the held row, a
finger's row follows the finger from the 8 px claim, and 25 px only sets
where UIKit's measure counts from. They say so now. The pan's note on a
press says why it is noted. AST-057 drops a status phrase and names
FR10 for its implementation gap.

* docs(AST-057): name the swipe layer module and why it stands alone

The record names Swipe/SwipeActionsLayer.tsx, which Item imports on its
deprecated path: it renders a row's two panels and runs the row's
gesture. createSwipe imports it, and Item loads it with import() only
for the deprecated props. No existing module can hold it.

* docs(AST-107): say what the internal pan and snap-point drag add

FR7 says what each internal takes that its public factory does not.
createPan takes the recognizer's own options and reports the claim's
travel and the input; createPanGesture starts on every pointer and no
scroll. createSnapDrag takes a model, the pan's options and a custom
property; createDragToSnapPoints keeps Core's one release policy.

* Merge main

* docs(AST-057): DEP-0017 names its decider for the four deprecations

DEP-0017 gains a decider row: the owner confirmed deprecating
swipeActions, swipeBehavior, ItemSwipeAction and ItemSwipeActions on
2026-11-10, with the variant and behavior types kept under DEC-10.
FR7 adds that under a coarse primary pointer a pen's or a mouse's press
on an open row's content paints no press either. The press-held
module's header loses a stray line break.

* docs(AST-057): DEP-0017's decider row quotes the owner's decision

DEP-0017's decider row now quotes the owner's own decision, with its
date and time: the option she chose and the decision's text, which
confirms the deprecation of the swipe symbols. The row says why the
variant and behavior types stay. FR7's verification row covers a pen's
or a mouse's press under a coarse primary pointer, with a new pen case
in the press controller's suite. The swipe layer's bridge Effect keeps
one comment.

* chore(lint): the provenance baseline drops the old swipe layer

The comment-provenance baseline still listed Item/ItemSwipeLayer.tsx,
which this change deletes. Regenerated with the baseline script; it
adds no entry.

* docs(storybook): swipe stories define each swipe once

The mail and commit stories built a new swipe for every row on every
render. Each now defines its swipe once in useMemo, and every handler
reads its row from the itemKey that each row now passes. Unread and read
rows offer different leading verbs, so the mail story has two swipes.

* Merge main

* refactor(core): the swipe reads its options and model through refs

The swipe copied its options into a ref in a layout Effect of its own.
It now uses useCommittedRef. The shared drag, made once for the row
root's life, reaches its model through a second committed ref, and its
Effect lists everything it reads. sideFor, a pure function, moves to
module scope.

Every reader runs in a later task, so behavior does not change. Two
tests guard it: a new value's behavior and handler reach the next
drag, and a drag that begins before a new value carries on through
it.

* docs(AST-057): the deprecated path keeps only its key forwarder

DEP-0017's compatibility field, CLN-0025's delta, FR10 and the two
exception lists named an Item click guard and event forwarders that
this change removed. Item's deprecated path keeps the bridge and one
key forwarder into it. The runtime record's sentence on Item's swipe
code says the same.

* Merge main

* test(core): the swipe tracking tests order frames by move count

The tracking and lead tests matched each frame to the last touch move
recorded at or before its time. WebKit's clock has whole milliseconds,
so a move handled just after a frame read the travel could share that
frame's time and count as before it. The frame recorder now stores
how many moves the page had handled, and the tests read the finger
from that count.

* test(core): the lead test measures the lead, not the frame rate

Two checks in the lead test stood on how often the page draws. One
needed 6 frames between 10 % and 70 % of the lead. Every frame drawn
there must still name one start within two frames, and three frames
are the fewest that test the curve's shape.

The other judged the lead's end from the base at the first frame
drawn past the confirm point. That frame can be some moves after the
confirm. The check now takes the base at the confirm move itself.

* test(core): the flick test checks the settle against the page's release

The flick test compared the settle's starting velocity with the
script's 1000 px/s. WebKit's page reads the release from when each
touch arrives, and a busy runner stretches those gaps, so the page can
read a slower finger. The settle starts at exactly the release the page
read. The test now checks that, within 2 % of that release, and the
play keeps each gap from the touch before.

* Merge main

* Merge main

* Merge main

* Merge main

* Merge main

* Merge main

* Merge main

* Merge main

* Merge main

This branch was successfully deployed

1 active deployment
Preview — 36ebfcf2 Deployed Nov 12, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ci:run A maintainer lets this outside contributor's pull request run CI (AST-030 FR17) CLA Signed This label is managed by the Meta Open Source bot. needs:design-review Affects visuals — Design should review

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants