diff --git a/.changeset/uikit-paging-values.md b/.changeset/uikit-paging-values.md new file mode 100644 index 0000000000000..0e4639c28ff04 --- /dev/null +++ b/.changeset/uikit-paging-values.md @@ -0,0 +1,7 @@ +--- +'@astryxdesign/core': patch +--- + +[chore] Internal: UIKit's paging values and math for touch presentations, measured on iOS 26.2: the thresholds that pick the page a release settles on, the settle that carries it there and `setContentOffset(animated:)`. The settle and `setContentOffset(animated:)` replay the recorded frames to under half a pixel. The unused projection rule (`selectPage` and `scroll.paging`) is gone, so the measured thresholds are the one paging rule. Not exported from the package entry point. + +@vjeux diff --git a/docs/specs/AST-094-touch-presentations/spec.md b/docs/specs/AST-094-touch-presentations/spec.md index 830b769fac5e6..7080a095be34c 100644 --- a/docs/specs/AST-094-touch-presentations/spec.md +++ b/docs/specs/AST-094-touch-presentations/spec.md @@ -103,6 +103,17 @@ a measured, sourced difference exists. measures (0.55 for a scroll view and a sheet), and a release MUST pick its rest point by projecting its velocity the way its UIKit counterpart does: with a deceleration rate, or with a measured projection time. + A paging scroll view (the pager, and Carousel with `hasSnap` where the + pager runs) picks its rest page as its UIKit counterpart measures it, with no + projection: the nearest page, or the next page in the release's direction + when the release is at least `paging.release.advanceSpeed` (300 pt/s) fast, + at any position on the page. It moves at most + `paging.release.maxPagesFromStart` (one page) from the page the drag started + on, and a release moving back toward that page stays on it (FR37). Both + values are measured on the iOS 26.2 simulator, 2026-10-23: steady releases + at 10, 25 and 40 % of a 402 pt page stay at 292.7–298.6 pt/s and advance at + 310.7–329.9 pt/s; releases at rest stay at 45–48.5 % and advance at + 55–57.5 % (DEC-25). - **FR4 — Touch motion uses named roles.** Every spring, duration and curve a touch presentation plays MUST be a motion role named for its use (`architecture:theme-tokens` INV3). The roles this record names are listed below with their defaults and @@ -157,6 +168,10 @@ a measured, sourced difference exists. and `component:ContextMenu` owns them (DEC-5). They play only in a ContextMenu that a touch opens. + Implementation gap: the pager's measured paging motion (its settle + integrator, its 300 ms animated scroll and that scroll's sinusoidal curve, + DEC-25) plays from internal constants and is not yet a named role. + ### Motion - **FR5 — Motion runs on the compositor.** Every release and every @@ -172,6 +187,14 @@ a measured, sourced difference exists. MUST come from the curve, not from a layout read. A new target MUST keep the current velocity, and a release MUST hand its velocity to the spring that follows. + A pager's release slower than `paging.release.velocityFloor` (225 pt/s) + starts its settle from rest, as UIKit's does; a faster release hands its + velocity to the settle. The floor is a guess inside the measured bracket + (UIKit zeroes steady releases at 175 and 200 pt/s and keeps 249 pt/s, iOS + 26.2 simulator, 2026-10-23) until a measurement replaces it (FR2). A + programmatic page change on a pager (a page control's tap, a keyboard step) + starts from rest: this is a known gap against this requirement until the + pager carries the current velocity into the page change (DEC-25). - **FR7 — Exits animate as the native counterpart's do.** A touch presentation MUST play the exit its UIKit counterpart plays, on every touch platform. FR8 governs their reduced-motion form. Each overlay's own record states its @@ -672,7 +695,9 @@ under a finger, and a mouse follows `module:DropdownMenu/useMenuPress` FR3 and stretch for the same travel; a mouse wheel scrolls its content and never moves it. Implementation gap: a finger drags it one for one below rest. - The shared pager (Carousel's paging presentation, Lightbox's viewer): a - trackpad swipe follows FR43's pager rule. + trackpad swipe follows FR43's pager rule in Lightbox's viewer under every + pointer (`component:Lightbox` FR11), and in Carousel's paging presentation + where the primary pointer is coarse. - `architecture:react-component-runtime` INV13: gestures attach for every pointer, within FR24's listener budget. - `design:user-states` DR1, DR3 and `family:buttons`: press timing follows @@ -713,9 +738,11 @@ under a finger, and a mouse follows `module:DropdownMenu/useMenuPress` FR3 and | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | FR1, FR2 | Value check over every measured value and its uses | every value; a guess and its measurement task; a platform-specific value; two components playing the same motion | an unsourced value, an unknown source kind, a guess without a listed measurement, an unsourced platform split, or two values for one use fails | | FR3 | Unit tests of the spring, decay, rubber band and projection math against an independent integration and values read from UIKit | under-, critically and overdamped springs; release velocities; both rates; overscroll depths | changing a formula or a constant breaks the agreement with UIKit's values | +| FR3 pager | Unit tests of the pager's page choice against the recorded UIKit releases | releases at 292.7–298.6 pt/s that stay and 310.7–329.9 pt/s that advance, at 10, 25 and 40 % of a page; releases at rest at 45–48.5 % and 55–57.5 %; a 1.5-page drag released at 0, 600 and 3000 pt/s; a release moving back toward the start page | a page chosen by projection, a release at or past 300 pt/s that stays, or a release that travels more than one page from its start fails | | FR4 | Role unit tests over every touch motion | each role at its table value; a theme that writes `motion` | a literal played in place of a role, a value that differs from the table at `tempo` 1 and `'standard'`, or a theme that changes a role other than through its motion knobs fails | | FR5 | Browser proof: an animation keeps advancing frame by frame through a 1 s main-thread block, with no layout or paint per frame | Chromium phone emulation; WebKit | a script-driven or layout-animating implementation freezes or lays out | | FR6 | Unit and browser tests catching an animation mid-flight and retargeting it | catch at peak velocity; retarget with a new spring; a retarget before the browser reports the call's start | a layout read, a jump, or a lost velocity fails | +| FR6 pager | Unit and browser tests of a pager's settle start | releases just under and over 225 pt/s; a catch mid-settle; a programmatic page change mid-settle | a release under the floor whose settle starts moving, a release over it whose settle starts from rest, or a catch that loses the on-screen velocity fails; a programmatic page change from rest is the recorded gap | | FR7, FR8 | Component browser tests and storyboards with and without Reduce Motion | entrance, exit, move; a drag and its lift under Reduce Motion | a missing exit, any travel, scale or spring under Reduce Motion other than a coast after a throw and its settle at an edge (`design:reduced-motion` DR2), or an opacity fade over 200 ms fails | | FR9, FR10 | Recognizer unit tests on synthetic streams and browser tests with real touch input | drag, second finger, pinch, page zoom, main-thread block | a second finger that breaks a drag, or a page pinch blocked other than by the author's `touch-action`, fails | | FR11, FR12 | Press and long-press tests on synthetic streams with explicit timestamps | inside and outside a scroll view; a drag the browser takes; a lift inside; a menu row under a finger; a press on a row of a menu whose rows fit and of one that scrolls; a slide-off lift on a Switch and on a Radio | the wrong profile's timing, a press that survives the browser taking the touch, or a control outside an action group activated other than by the browser's click, outside `spec:AST-020` FR9's slide-off exception, a row of a menu whose rows fit that waits 150 ms, or one of a scrolling menu that does not, or a slide-off lift that completes a control outside `spec:AST-020` FR9's exception, fails | @@ -731,7 +758,7 @@ under a finger, and a mouse follows `module:DropdownMenu/useMenuPress` FR3 and | FR29 | Trigger tests with explicit timestamps | a press in a fixed bar; a press in scrolling content held 149 and 150 ms; a quick tap in scrolling content; a scroll taking the touch before 150 ms; a drift of 12 and 14 pt; moves before and after the handoff; `presentation="popover"` | a fixed-bar press that waits, a held finger's scroll-view open before 150 ms or after a scroll, a quick tap that does not open at its lift, an open past the drift allowance, a lift that acts before the handoff, or a `popover` trigger that opens on press fails | | FR31–FR33 | Browser tests and storyboards under a finger | a menu, a Popover and a ContextMenu lift: open, close, a pan outside, a tap outside, a pinch over the surface; a mouse | a surface that does not grow from and shrink into its trigger, a pan outside that leaves a menu open, a Popover whose dismissal changed, a pinch blocked other than by the author's `touch-action`, a tap outside that reaches the page, or a changed mouse path fails | | FR34, FR35 | Browser tests and storyboards under a finger | a sub-menu drilling in and its Back row returning; a tap and a drag during a popover's and a menu's growth; a pinch during growth; a mouse; a tap and a drag during an alert's, a sheet's, and a dialog's entrance; a key and a screen reader during an entrance; a pinch during an alert's and a sheet's entrance; a tap and a scroll on the page beside an entering non-modal sheet, which pass | a drill-in that leaves the parent's rows in place, a change between levels that does not play on its roles, a tap during growth that closes, scrolls or moves focus, a pinch blocked other than by the author's `touch-action`, or a changed mouse path, a held key or assistive-technology activation, a hidden content tree, or a tap or drag during an entrance that closes the presentation, scrolls a held page, moves focus or reaches anything beneath, fails | -| FR36–FR40 | Release tests on synthetic touch streams with explicit timestamps, per use | below and past each commit point; a flick that projects past it; a slow drag past it; a release moving back; Reduce Motion; keyboard and mouse paths | a decision that changes mid-settle, a release moving back that commits, a settle that does not start at the release velocity, or an action with no keyboard or mouse path fails | +| FR36–FR40 | Release tests on synthetic touch streams with explicit timestamps, per use | below and past each commit point; a flick that projects past it; a slow drag past it; a release moving back; Reduce Motion; keyboard and mouse paths | a decision that changes mid-settle, a release moving back that commits, a settle that does not start at the release velocity (a paging release starts its settle per FR6's paging paragraph, DEC-25), or an action with no keyboard or mouse path fails | | FR41 | Browser tests with real touch input (`spec:AST-013` FR10) | a tap; a long press on a ContextMenu trigger, a DropdownMenu trigger the caller renders, a row with a context menu, and a slider thumb; a long press on a checkbox row's label and on plain text; a cancelled press; mouse and keyboard selection; a pen long press; a mouse long press, which makes no context request | a tap that selects, a hold with an action that starts a selection or callout, a label or plain text whose long press does not select natively, a suppression that outlives the press, or a change to native selection elsewhere or to mouse, keyboard, or assistive-technology selection fails | | FR42 | Default-theme geometry tests under a coarse and a fine pointer, and hit-testing between adjacent targets | every component at phone width with a finger and with a mouse; a dense toolbar; a chip and its remove button; a Switch beside a label link | a default-theme box that grows under touch or at phone width other than with its text, or, where no component or module record sets the hit area, a touch target under 44 px where neighbors allow it or a hit area that overlaps a neighbor's target, fails | | FR43 | Browser tests with a mouse, a trackpad, a pen, a finger, and the keyboard, and resource counts | a pan by drag and by wheel; a slider's thumb under a wheel and a trackpad scroll; a ctrl-wheel pinch; a long press, a right click, and Shift+F10; a mouse press; a handle drag; a row swipe with a mouse and a trackpad; a component with no gesture | a gesture missing under a mouse or pen, a mouse-drag swipe action, a pen pinch, an edge pan under a mouse, a trackpad, or a pen, a press delay under a fine pointer, a wheel or trackpad scroll that changes a thumb's value or does not reach the scroll under it, an idle listener in a component with no gesture, or added stylesheet bytes, fails | @@ -1028,6 +1055,25 @@ from its top. Rejected: cancelling moves only after the pan begins. +### DEC-25 — A pager pages as UIKit measures it + +**Reference:** `spec:AST-094/DEC-25` +**Decider:** `cixzhang`, `2026-11-01` + +A pager, Carousel with `hasSnap` where the pager runs, and Lightbox's gallery pick the rest page and +start the settle as UIKit's paging scroll view does on iOS 26.2. UIKit +chooses the page by a speed threshold, the same 300 pt/s at 10, 25 and 40 % +of a page, not by a projection, and starts a slow release's settle from rest. +The owner tried this paging on the pager and the paging Carousel on +2026-11-01, with a trackpad and on a phone: "trackpad is good", "phone good". +This narrows FR3 and FR6 for paging only; every other release keeps them. A +programmatic page change starts from rest until the pager carries velocity +into it. A paging release decides by FR3's paging rule, and its settle starts +as FR6's paging paragraph says; FR37 applies unchanged. + +Rejected: projecting a paging release with a deceleration rate; handing a +slow paging release's velocity to the settle. + ## Open questions - **OQ1 — Scroll view bounce-back curve.** What curve brings a scroll view diff --git a/docs/specs/components/Lightbox/Lightbox.spec.md b/docs/specs/components/Lightbox/Lightbox.spec.md index c28e10d405889..8c28a713c8e00 100644 --- a/docs/specs/components/Lightbox/Lightbox.spec.md +++ b/docs/specs/components/Lightbox/Lightbox.spec.md @@ -139,7 +139,7 @@ FR21). Consumer props and usage remain documented in `Lightbox.doc.mjs`. | FR4 | The open viewer is a focus region through Core's shared focus-region module (`component:Dialog/DEC-2`): Tab from its last control moves focus to its first and Shift+Tab from its first moves focus to its last, so focus never leaves the viewer for the browser's own interface. | `component:Dialog/DEC-2` | settled; implementation gap | | FR5 | Under a coarse primary pointer, after hydration, Lightbox presents FR6–FR10 with no opt-in. Every spring, duration, and curve they play is a named motion role (zoom settle, page settle, dismiss, pinch close, controls fade, zoom transition) read through the motion role table, never a literal. Under reduced motion they follow AR6. | `spec:AST-094` FR4, FR13 | settled; implementation gap | | FR6 | With `hasZoom`, on an image, a pinch zooms about the fingers and pans while it zooms; past the minimum or maximum the photo resists and eases back without overshoot. A double tap zooms to the larger of filling the viewer and 2×, about the tapped point; a second double tap returns to the fitted size. A zoomed photo pans with momentum and rubber-band edges. A pinch on the controls or the caption still zooms the page. | `spec:AST-094` FR3, FR10 | settled; implementation gap | -| FR7 | In a gallery, a horizontal drag moves the row of items, which sit apart by the measured gap. The release lands on at most one neighbouring item by the projection rule. Paging applies over a video item's frame as over a photo; a drag that starts on the video's own controls, such as its scrubber or volume, stays the video's. A zoomed photo pans to its edge before a new drag pages. A pinch never pages. Previous, Next, and the arrow keys keep paging. A controlled `index` the caller refuses springs back. `onIndexChange` reports a swipe. | `spec:AST-094` FR14, FR36–FR39 | settled; implementation gap | +| FR7 | In a gallery, a horizontal drag moves the row of items, which sit apart by the measured gap. The release lands on at most one neighbouring item by `spec:AST-094` FR3's paging rule (DEC-25). Paging applies over a video item's frame as over a photo; a drag that starts on the video's own controls, such as its scrubber or volume, stays the video's. A zoomed photo pans to its edge before a new drag pages. A pinch never pages. Previous, Next, and the arrow keys keep paging. A controlled `index` the caller refuses springs back. `onIndexChange` reports a swipe. | `spec:AST-094` FR3, FR14, FR36–FR39, DEC-25 | settled; implementation gap | | FR8 | On a fitted image, a downward drag moves the photo with the finger, shrinks it, and fades the backdrop. The release decides once: a projected travel past the commit point closes the viewer and reports `onOpenChange(false)` at the lift; a release moving back springs back. Video is unchanged. | `spec:AST-094` FR36–FR40 | settled; implementation gap | | FR9 | With `hasZoom`, a pinch in from the fitted size is a release decision: below the measured fraction of the fitted size the release closes the viewer; opening the fingers again by the measured amount before the lift is moving back and cancels. A pinch that starts zoomed in never closes the viewer. | `spec:AST-094` FR36, FR37 | settled; implementation gap | | FR10 | With `hasZoom`, under a coarse pointer only, a tap on the photo fades the controls and caption and darkens the backdrop. While they are hidden, the next tap on the photo, a tap beside the photo, or a cancelled drag brings them back, and that tap beside the photo does not close the viewer (ORD3). AR5 governs keyboard and assistive-technology access while they are hidden. | `architecture:public-component-api` INV16 | settled; implementation gap | diff --git a/packages/core/src/motion/MEASUREMENTS.md b/packages/core/src/motion/MEASUREMENTS.md index fe236bf310866..da3fac0b72cbf 100644 --- a/packages/core/src/motion/MEASUREMENTS.md +++ b/packages/core/src/motion/MEASUREMENTS.md @@ -43,7 +43,7 @@ installed); rows marked † also on iOS 18 for the pre-glass delta. iPhone | M-S2 | Momentum coast | A long list (Contacts, or a probe table of 500 rows): flicks released at 1000, 2500, 5000 pt/s | contentOffset(t) from release to rest; decay constant; per-millisecond vs per-frame model; the speed at which it stops | C | `scroll.decelerationRate` | | M-S3 | Bounce-back spring | Same list: drag 120 pt past the top, hold still, release; a flick into the top edge at 3000 pt/s | contentOffset(t) after release and after edge contact; spring response and damping ratio; velocity hand-off | C | `scroll.bounce` | | M-S5 | Rubber band | Same list on an 852 pt view: drag 100, 300, 600 pt past the top; a horizontal pager | displayed overflow against finger overflow; confirm c = 0.55 and d = the view's size on the axis | C | `scroll.rubberBand` | -| M-PG1 | Paging | Photos full-screen swipes; a probe paging scroll view | page chosen per release position × velocity (thresholds; at most one page?); contentOffset(t) onto the page | B, C | `scroll.paging` | +| M-PG1 | Paging | Photos full-screen swipes; a probe paging scroll view | page chosen per release position × velocity (thresholds; at most one page?); contentOffset(t) onto the page | B, C | `paging` | | M-ST1 | Scroll to top | Settings scrolled down 500, 2000, 8000 pt; tap the status bar | contentOffset(t); duration against distance; curve or spring fit | B, C | `scroll.scrollToTopRate` | | M-N1 | Navigation push | Settings: tap General | incoming leading edge x(t), outgoing x(t) (parallax fraction), dimming alpha(t); animation parameters | A, B | `springs.navigationPush` | | M-N2 | Navigation pop | General: back button | same as M-N1 | A, B | `springs.navigationPop` | @@ -72,6 +72,13 @@ initial velocity's sign flipped, a curve that overshoots. Push and pop are not Core Animation animations on iOS 26.2: UIKit writes presentation modifiers every frame from the main thread. +## Paging (UIScrollView `isPagingEnabled`, UIPageViewController) + +| ID | What | App and gesture | Extract | Method | Feeds | +| ------ | --------------------- | ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | ------ | ------------------------------ | +| M-PG12 | End of a settle | Same pager: releases at rest from 10 %, 49 %, 60 % and 90 % of a page, logged at 120 fps | remaining distance and step velocity at the frame the offset lands exactly on the page | C | `paging.integrator.restSpeed` | +| M-PG13 | Settle velocity floor | Same pager: steady releases from 200 to 250 pt/s in 5 pt/s steps, at 25 % of a page | the slowest release whose `scrollViewWillEndDragging` velocity is not 0 | C | `paging.release.velocityFloor` | + ## Gestures (UIKit gesture recognizers) Thresholds the gesture system reads (`uikit/gestures.ts`). Safari on iOS runs diff --git a/packages/core/src/motion/README.md b/packages/core/src/motion/README.md index 6a0f6b68ac379..43ace5d4e52d2 100644 --- a/packages/core/src/motion/README.md +++ b/packages/core/src/motion/README.md @@ -15,8 +15,9 @@ so each keeps its measured value; no shipped component reads the roles yet. | ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `uikit/` | THE constants table: every spring, duration, deceleration rate, rubber-band constant and curve, with its source. | | `uikit/springs.ts` | Interaction springs (navigation, sheets, alerts, menus, controls, keyboard, banners) and the SwiftUI / UIKit presets. | -| `uikit/scroll.ts` | UIScrollView: deceleration rates, rubber band, bounce-back spring, paging, `delaysContentTouches`, scroll to top. | +| `uikit/scroll.ts` | UIScrollView: deceleration rates, rubber band, bounce-back spring, `delaysContentTouches`, scroll to top. | | `uikit/timing.ts` | Non-spring clocks and curves: press highlight, Core Animation's named curves, keyboard, Reduced Motion cross-fade. | +| `uikit/paging.ts` | A paging UIScrollView: the integrator that settles a release on its page, the page rule, the catch, `setContentOffset(animated:)`. | | `uikit/navigation.ts` | UINavigationController: push velocity, parallax, dimming, transition clock, interactive pop finish rule. | | `uikit/gestures.ts` | Gesture recognizer thresholds, the velocity filter and haptic stand-ins, as `{value, unit}` entries (sources in JSDoc). | | `roles.ts` | The internal motion roles: the springs, durations and curves `spec:AST-094` FR4 names, registered by the shared tables, and a role's CSS form read back. | @@ -28,8 +29,8 @@ so each keeps its measured value; no shipped component reads the roles yet. | `coast.ts` | A release's momentum curves for `animator.decay`: the coast, the edge spring, a release past an edge. | | `rubberBand.ts` | UIScrollView's resistance past an edge, and its inverse. | | `projection.ts` | Release targets: the rest point nearest the projected coast. | +| `paging.ts` | Paging: UIKit's paging settle as a playable curve, its velocity floor, the animated page scroll. | | `resolveSnapPoint.ts` | Release policy: the snap point a release lands on (flick, back-out cancel, step limit), on `selectSnapPoint`. Internal. | -| `selectPage.ts` | Paging: at most one page per release, on `resolveSnapPoint`. | | `bezier.ts` | Cubic-bézier timing functions (Core Animation's named curves). | | `animator.ts` | Compositor animator: springs, coasts and any closed-form curve compiled to Web Animations, read back analytically. | | `presentation.ts` | Where each moving element is drawn relative to where the engine hit-tests it, reported by the animator while translate runs; read by the gesture host at touch-down. | diff --git a/packages/core/src/motion/paging.test.ts b/packages/core/src/motion/paging.test.ts new file mode 100644 index 0000000000000..bb0e585a17b53 --- /dev/null +++ b/packages/core/src/motion/paging.test.ts @@ -0,0 +1,393 @@ +// Copyright (c) Meta Platforms, Inc. and affiliates. + +/** + * @file paging.test.ts + * @input vitest, the paging math, and UIKit reference curves recorded on the + * iOS 26.2 simulator (a 402 pt paging UIScrollView, contentOffset per 60 Hz + * frame) + * @output Holds solvePaging and solveAnimatedPageScroll to the recorded + * motion + * @position Testing; validates paging.ts without a browser + */ + +import {describe, expect, it} from 'vitest'; +import { + pagingSettleVelocity, + solveAnimatedPageScroll, + solvePaging, +} from './paging'; +import {paging} from './uikit/paging'; + +/** + * contentOffset per frame after a release at rest, from the frame the settle + * starts (ms, px). UIKit lab, iOS 26.2 simulator, 402 pt pages. + */ +const SETTLES: Record< + string, + {from: number; velocity?: number; to: number; frames: number[][]} +> = { + // 60 % of the way from page 1 to page 2, released at rest: page 2. + forwardFrom60: { + from: 633.33, + to: 804, + frames: [ + [0.7, 633.33], + [17.4, 639], + [34.0, 652], + [50.7, 668.67], + [67.4, 686.67], + [84.0, 704.67], + [100.7, 721.33], + [117.4, 736.33], + [134.0, 749.67], + [150.7, 761], + [167.4, 770.67], + [184.0, 778.33], + [200.7, 784.67], + [217.4, 789.67], + [234.0, 793.67], + [250.7, 796.67], + [267.4, 799], + [284.0, 800.67], + [300.7, 802], + [317.4, 803], + [334.0, 803.67], + [350.7, 804], + ], + }, + // 46 % (content) of the way to page 2, released at rest: back to page 1. + backFrom46: { + from: 589, + to: 402, + frames: [ + [0.6, 589], + [17.3, 583], + [33.9, 569], + [50.6, 550.67], + [67.3, 531], + [83.9, 511.33], + [100.6, 493], + [117.3, 476.33], + [133.9, 461.67], + [150.6, 449.33], + [167.3, 439], + [183.9, 430.33], + [200.6, 423.33], + [217.3, 417.67], + [233.9, 413.33], + [250.6, 410], + [267.3, 407.33], + [283.9, 405.33], + [300.6, 404], + [317.3, 403], + [333.9, 402.33], + [350.6, 402], + ], + }, + // Dragged back 23 % toward page 0, released at rest: page 1. + forwardFromMinus23: { + from: 311.33, + to: 402, + frames: [ + [0.6, 311.33], + [17.2, 314.33], + [33.9, 321], + [50.6, 330], + [67.2, 339.67], + [83.9, 349.33], + [100.6, 358.33], + [117.2, 366.33], + [133.9, 373.33], + [150.6, 379.33], + [167.2, 384.33], + [183.9, 388.33], + [200.6, 391.67], + [217.2, 394.33], + [233.9, 396.33], + [250.6, 398], + [267.2, 399.33], + [283.9, 400.33], + [300.6, 401], + [317.2, 401.33], + [333.9, 401.67], + [350.6, 402], + ], + }, + // Released moving forward at 25 % with a settle velocity of 0.314 pt/ms + // (steady 320 pt/s drag): the next page. + flick314From24: { + from: 499.67, + velocity: 314, + to: 804, + frames: [ + [15.0, 499.67], + [31.7, 513.33], + [48.4, 538.33], + [65.0, 569], + [81.7, 601.67], + [98.4, 633.33], + [115.0, 662.67], + [131.7, 689], + [148.4, 712], + [165.0, 731.67], + [181.7, 748], + [198.4, 761.33], + [215.0, 772], + [231.7, 780.33], + [248.4, 787], + [265.0, 792], + [281.7, 796], + [298.4, 799], + [315.0, 801], + [331.7, 802.33], + [348.4, 803.33], + [365.0, 804], + ], + }, + // 600 pt/s drag released with no hold: settle velocity 0.565 pt/ms. + flick565From24: { + from: 497.33, + velocity: 565, + to: 804, + frames: [ + [-3.2, 497.33], + [13.5, 514.33], + [30.2, 541.33], + [46.8, 573], + [63.5, 606], + [80.2, 637.67], + [96.8, 667], + [113.5, 693], + [130.2, 715.33], + [146.8, 734.33], + [163.5, 750], + [180.2, 763], + [196.8, 773.33], + [213.5, 781.67], + [230.2, 788], + [246.8, 793], + [263.5, 796.67], + [280.2, 799.33], + [296.8, 801.33], + [313.5, 802.67], + [330.2, 803.67], + [346.8, 804], + ], + }, + // 290 pt of pan past page 0 (114.33 pt shown), released at rest. + overscrollReturn: { + from: -114.33, + to: 0, + frames: [ + [0, -114.33], + [10.6, -113], + [27.3, -105.67], + [43.9, -95.33], + [60.6, -83.33], + [77.3, -71], + [93.9, -59.33], + [110.6, -48.67], + [127.3, -39.33], + [143.9, -31.33], + [160.6, -24.67], + [177.3, -19], + [193.9, -14.33], + [210.6, -10.67], + [227.3, -7.67], + [243.9, -5.33], + [260.6, -3.67], + [277.3, -2.33], + [293.9, -1.33], + [310.6, -0.67], + [327.3, -0.33], + [343.9, 0], + ], + }, +}; + +/** `setContentOffset(_:animated:)` per frame from its first frame (ms, px). */ +const ANIMATED: Record = + { + twoPages: { + from: 402, + to: 1206, + frames: [ + [0, 402], + [16.7, 408], + [33.3, 426.33], + [50, 456], + [66.7, 496], + [83.3, 545.67], + [100, 603], + [116.7, 666.67], + [133.3, 734.33], + [150, 804], + [166.7, 873.67], + [183.3, 941.33], + [200, 1005], + [216.7, 1062.33], + [233.3, 1112], + [250, 1152], + [266.7, 1181.67], + [283.3, 1200], + [300, 1206], + ], + }, + fivePages: { + from: 0, + to: 2010, + frames: [ + [0, 0], + [16.7, 15.33], + [33.3, 60.67], + [50, 134.67], + [66.7, 235], + [83.3, 359], + [100, 502.67], + [116.7, 661.33], + [133.3, 830.33], + [150, 1005], + [166.7, 1179.67], + [183.3, 1348.67], + [200, 1507.67], + [216.7, 1651], + [233.3, 1775], + [250, 1875.33], + [266.7, 1949.33], + [283.3, 1994.67], + [300, 2010], + ], + }, + }; + +/** + * Residuals of a curve against recorded frames. The paging integrator runs + * floor(elapsed ms) steps on each frame. So a frame shows the curve after the + * floored steps since the start (`steps`). A timed curve, such as the animated + * scroll, is read at the frame times (`time`). + */ +function errors( + curve: {at(t: number): number}, + frames: number[][], + clock: 'steps' | 'time', +): {rms: number; max: number} { + let steps = 0; + const residuals = frames.map(([ms, x], i) => { + if (clock === 'steps' && i > 0) { + steps += Math.floor(ms - frames[i - 1][0] + 1e-6); + } + const t = + clock === 'steps' ? steps / paging.integrator.stepsPerSecond : ms / 1000; + return curve.at(t) - x; + }); + const rms = Math.sqrt( + residuals.reduce((sum, r) => sum + r * r, 0) / residuals.length, + ); + return {rms, max: Math.max(...residuals.map(Math.abs))}; +} + +describe('pagingSettleVelocity: the floor on the one release velocity (spec:AST-100 FR3)', () => { + it('zeroes a release velocity below the floor, either way', () => { + expect(pagingSettleVelocity(200)).toBe(0); + expect(pagingSettleVelocity(-200)).toBe(0); + }); + + it('keeps a velocity at or above the floor: UIKit keeps a steady 249 pt/s release (0.249 pt/ms)', () => { + expect(pagingSettleVelocity(249)).toBe(249); + expect(pagingSettleVelocity(-260)).toBe(-260); + }); +}); + +describe("solvePaging: UIKit's paging settle, frame by frame", () => { + it.each(Object.entries(SETTLES))( + 'reproduces the recorded %s within a pixel', + (_, {from, velocity = 0, to, frames}) => { + const curve = solvePaging({from, velocity, to}); + const {rms, max} = errors(curve, frames, 'steps'); + expect(rms).toBeLessThan(0.35); + expect(max).toBeLessThan(0.8); + }, + ); + + it('ends exactly on the page about 0.33 s after a release at rest', () => { + const curve = solvePaging({from: 633.33, velocity: 0, to: 804}); + expect(curve.at(curve.duration)).toBe(804); + expect(curve.velocity(curve.duration)).toBe(0); + expect(curve.duration).toBeGreaterThan(0.3); + expect(curve.duration).toBeLessThan(0.36); + }); + + it("starts at the release position with UIKit's step velocity", () => { + const curve = solvePaging({from: 500, velocity: 1000, to: 804}); + expect(curve.at(0)).toBe(500); + // 1000 px/s enters as 1 px per step; 960 steps a second. + expect(curve.velocity(0)).toBeCloseTo(960, 6); + }); + + it('is continuous and monotonic for a release at rest', () => { + const curve = solvePaging({from: 589, velocity: 0, to: 402}); + let previous = curve.at(0); + for (let t = 0.001; t <= curve.duration; t += 0.001) { + const value = curve.at(t); + expect(value).toBeLessThanOrEqual(previous + 1e-9); + expect(Math.abs(value - previous)).toBeLessThan(3); + previous = value; + } + }); + + it('carries a forward flick on with a small overshoot-free approach', () => { + const curve = solvePaging({from: 450, velocity: 600, to: 804}); + // The pull is underdamped (ζ ≈ 0.88): it may pass the page by a hair. + let maxValue = -Infinity; + for (let t = 0; t <= curve.duration; t += 0.004) { + maxValue = Math.max(maxValue, curve.at(t)); + } + expect(maxValue).toBeLessThan(804 + 2); + expect(curve.at(curve.duration)).toBe(804); + }); + + it('settles at once when already on the page and at rest', () => { + const curve = solvePaging({from: 804, velocity: 0, to: 804}); + expect(curve.steps).toBe(0); + expect(curve.duration).toBe(0); + expect(curve.at(0.1)).toBe(804); + }); + + it('runs the documented integrator', () => { + const {springPull, friction} = paging.integrator; + const curve = solvePaging({from: 0, velocity: 0, to: 100}); + // One step from rest: v = (0 + 100·pull)·friction. + const oneStep = 100 * springPull * friction; + expect(curve.at(1 / paging.integrator.stepsPerSecond)).toBeCloseTo( + oneStep, + 9, + ); + }); +}); + +describe('solveAnimatedPageScroll: setContentOffset(_:animated:)', () => { + it.each(Object.entries(ANIMATED))( + 'reproduces the recorded %s', + (_, {from, to, frames}) => { + const curve = solveAnimatedPageScroll({from, to}); + const {rms, max} = errors(curve, frames, 'time'); + expect(rms).toBeLessThan(0.5); + expect(max).toBeLessThan(1.2); + }, + ); + + it('lasts 0.3 s whatever the distance and ends at rest', () => { + for (const distance of [402, 804, 2010]) { + const curve = solveAnimatedPageScroll({from: 0, to: distance}); + expect(curve.duration).toBe(0.3); + expect(curve.at(0.3)).toBe(distance); + expect(curve.velocity(0.3)).toBe(0); + expect(curve.velocity(0)).toBe(0); + } + }); + + it('peaks at π/2 times the average speed halfway', () => { + const curve = solveAnimatedPageScroll({from: 0, to: 402}); + expect(curve.velocity(0.15)).toBeCloseTo((Math.PI / 2) * (402 / 0.3), 6); + }); +}); diff --git a/packages/core/src/motion/paging.ts b/packages/core/src/motion/paging.ts new file mode 100644 index 0000000000000..77dce4693836b --- /dev/null +++ b/packages/core/src/motion/paging.ts @@ -0,0 +1,138 @@ +// Copyright (c) Meta Platforms, Inc. and affiliates. + +/** + * @file paging.ts + * @input A release velocity, a settle's start, end and velocity, and the UIKit + * paging constants + * @output Exports `pagingSettleVelocity`, `solvePaging` (UIKit's paging settle + * as a curve the animator plays) and `solveAnimatedPageScroll` + * @position Pure math, with no DOM and no React + * + * SYNC: When modified, update: + * - /packages/core/src/motion/paging.test.ts + * - /packages/core/src/motion/README.md + */ + +import type {MotionCurve} from './animator'; +import {paging} from './uikit/paging'; + +/** + * The velocity a paging settle starts at. It is the release velocity that every + * gesture reads, zeroed below `velocityFloor`. The page choice reads the + * release velocity itself. + */ +export function pagingSettleVelocity(velocity: number): number { + return Math.abs(velocity) < paging.release.velocityFloor ? 0 : velocity; +} + +/** A paging settle: the curve and where it ends. */ +export interface PagingCurve extends MotionCurve { + readonly from: number; + readonly to: number; + /** Integration steps the settle took. */ + readonly steps: number; +} + +/** + * UIKit's paging settle from `from` (px), moving at `velocity` (px/s), onto + * `to`. It steps `paging.integrator` `stepsPerSecond` times a second and ends + * exactly on `to`. The same motion returns an overscrolled pager to its first + * or last page. + * + * Positions are content offsets along the paging axis, 0 at page 0 and growing + * toward later pages. Velocities are px/s of that offset. + * + * No closed form reproduces the per-frame stepping, so the settle integrates + * once into a table, and the curve reads the table. A release needs at most + * about 400 steps, well under a millisecond of work. + * + * The release velocity enters in px per millisecond per step, as UIKit hands it + * to the integrator. At 960 steps a second, the content starts at 96 % of the + * finger's speed, as in UIKit. + */ +export function solvePaging({ + from, + velocity, + to, +}: { + from: number; + velocity: number; + to: number; +}): PagingCurve { + const {springPull, friction, stepsPerSecond, restDistance, restSpeed} = + paging.integrator; + const xs: number[] = [from]; + const vs: number[] = [velocity / 1000]; + let x = from; + let v = velocity / 1000; + // ~10 s of steps: far beyond any settle (≈ 0.35 s from rest). + const maxSteps = stepsPerSecond * 10; + let steps = 0; + while (steps < maxSteps) { + if (Math.abs(to - x) < restDistance && Math.abs(v) < restSpeed) { + break; + } + v = (v + (to - x) * springPull) * friction; + x += v; + steps += 1; + xs.push(x); + vs.push(v); + } + xs[xs.length - 1] = to; + vs[vs.length - 1] = 0; + const duration = steps / stepsPerSecond; + const last = xs.length - 1; + const read = (table: number[], t: number): number => { + if (!(t > 0)) { + return table[0]; + } + const s = t * stepsPerSecond; + if (s >= last) { + return table[last]; + } + const i = Math.floor(s); + const f = s - i; + return table[i] + (table[i + 1] - table[i]) * f; + }; + return { + from, + to, + steps, + duration, + at: t => read(xs, t), + // px per step × steps per second + velocity: t => read(vs, t) * stepsPerSecond, + }; +} + +/** + * `setContentOffset(_:animated:)`: `paging.animatedScroll.duration` on a + * sinusoidal ease-in-out, whatever the distance. UIKit starts it from the + * current offset and drops any velocity, as here. + */ +export function solveAnimatedPageScroll({ + from, + to, +}: { + from: number; + to: number; +}): MotionCurve { + const {duration} = paging.animatedScroll; + const distance = to - from; + return { + duration, + at: t => { + const u = Math.min(1, Math.max(0, t / duration)); + return from + (distance * (1 - Math.cos(Math.PI * u))) / 2; + }, + velocity: t => { + if (t <= 0 || t >= duration) { + return 0; + } + return ( + ((distance * Math.PI) / (2 * duration)) * + Math.sin((Math.PI * t) / duration) + ); + }, + }; +} diff --git a/packages/core/src/motion/selectPage.test.ts b/packages/core/src/motion/selectPage.test.ts deleted file mode 100644 index 39d8785d2d453..0000000000000 --- a/packages/core/src/motion/selectPage.test.ts +++ /dev/null @@ -1,31 +0,0 @@ -// Copyright (c) Meta Platforms, Inc. and affiliates. - -import {describe, expect, it} from 'vitest'; -import {selectPage} from './selectPage'; - -describe('selectPage', () => { - it('lands on a real page when the current page is past the end', () => { - const result = selectPage({ - position: 400, - velocity: 0, - pageSize: 100, - pageCount: 3, - currentPage: 4, - }); - expect(result.value).toBeDefined(); - expect(result.index).toBeGreaterThanOrEqual(0); - expect(result.index).toBeLessThanOrEqual(2); - }); - - it('moves at most one page per release', () => { - const page = (position: number, velocity: number, currentPage: number) => - selectPage({position, velocity, pageSize: 390, pageCount: 6, currentPage}) - .index; - expect(page(390, 0, 1)).toBe(1); - expect(page(430, 8000, 1)).toBe(2); - expect(page(350, -8000, 1)).toBe(0); - // A slow drag past half a page settles on the next page. - expect(page(600, 0, 1)).toBe(2); - expect(page(1950, 9000, 5)).toBe(5); - }); -}); diff --git a/packages/core/src/motion/selectPage.ts b/packages/core/src/motion/selectPage.ts deleted file mode 100644 index 26f76cb0fee19..0000000000000 --- a/packages/core/src/motion/selectPage.ts +++ /dev/null @@ -1,55 +0,0 @@ -// Copyright (c) Meta Platforms, Inc. and affiliates. - -/** - * @file selectPage.ts - * @input A release (position, velocity), the page size and count, the - * current page - * @output Exports `selectPage`: the page a paging release settles on - * @position UIScrollView paging (`isPagingEnabled`) on the release policy - * (resolveSnapPoint.ts). Pure: no DOM, no React - * - * SYNC: When modified, update selectPage.test.ts. - */ - -import type {SnapSelection} from './projection'; -import {resolveSnapPoint} from './resolveSnapPoint'; -import {scroll} from './uikit/scroll'; - -/** - * UIScrollView paging (`isPagingEnabled`): the page a release settles on, at - * most one page from `currentPage`, chosen by projecting the release with - * the paging projection rate (uikit/scroll.ts; a GUESS until measured). - * Pages are `pageSize` apart starting at 0. - */ -export function selectPage({ - position, - velocity, - pageSize, - pageCount, - currentPage, - rate = scroll.paging.projectionRate, -}: { - position: number; - velocity: number; - pageSize: number; - pageCount: number; - currentPage: number; - rate?: number; -}): SnapSelection { - const points = Array.from( - {length: Math.max(1, pageCount)}, - (_, i) => i * pageSize, - ); - // The release policy (resolveSnapPoint.ts), with the paging rate as the - // seconds of velocity it projects, no flick and one page per release. - const {index, projected} = resolveSnapPoint({ - points, - position, - velocity, - flickThreshold: Infinity, - projection: {seconds: rate / (1 - rate) / 1000}, - fromIndex: currentPage, - maxSteps: 1, - }); - return {index, value: points[index], projected}; -} diff --git a/packages/core/src/motion/uikit/paging.ts b/packages/core/src/motion/uikit/paging.ts new file mode 100644 index 0000000000000..7448fec409f4b --- /dev/null +++ b/packages/core/src/motion/uikit/paging.ts @@ -0,0 +1,162 @@ +// Copyright (c) Meta Platforms, Inc. and affiliates. + +/** + * @file paging.ts + * @input Nothing; data only + * @output Exports `paging`, the measured constants of a paging UIScrollView + * @position The paging domain of the UIKit constants table (motion/uikit). Only + * core reads it, so the `uikit` namespace does not re-export it + * + * SYNC: When modified, update: + * - /packages/core/src/motion/MEASUREMENTS.md (measurement tasks) + * - /packages/core/src/motion/paging.ts and paging.test.ts + */ + +export const paging = { + /** + * After the lift, one model moves the content: the settle onto the chosen + * page and the return from an overscroll. Each display frame runs floor(frame + * interval in ms) steps of 1 ms: + * + * v = (v + (target − x) · springPull) · friction; x += v (v: pt per step) + * + * A 60 Hz frame runs 16 steps, not 16.67. With these values, the model + * replays eight captured releases to 0.20 pt RMS. It replays five overscroll + * returns to 0.16–0.33 pt RMS (402 pt pages, iOS 26.2, 3× screen). Without + * the floor, the error is 1.0 pt RMS, with a systematic shape. + */ + integrator: { + /** + * Velocity added per 1 ms step, per point of distance to the target page + * (pt per step²). + * @source measured: UIKit lab, iOS 26.2 simulator, Oct 23 2026. + * `_pagingSpringPull` reads the same on a 402 pt paging UIScrollView and + * on UIPageViewController's scroll view. It replays 8 captured settles to + * 0.20 pt RMS. + */ + springPull: 0.000284858, + /** + * Velocity kept per step after the pull (`_pagingFriction`, equal to + * `_defaultPagingFriction`). + * @source measured: UIKit lab, iOS 26.2 simulator, Oct 23 2026. Both read + * the same on the two scroll views of `springPull`, and they replay with + * it. + */ + friction: 0.970815, + /** + * Integration steps per second: floor(16.67 ms) = 16 steps per 60 Hz frame, + * and floor(8.33 ms) = 8 per 120 Hz frame, so 960. + * @source measured: UIKit lab, iOS 26.2 simulator, Oct 23 2026. In a 60 fps + * log of 8 releases at rest, floored stepping fits to 0.20 pt RMS. + * Unfloored stepping fits to 1.0 pt RMS. + */ + stepsPerSecond: 960, + /** + * A settle ends exactly on the page once the remaining distance is below + * this many points and the step velocity is below `restSpeed`. + * @source measured: UIKit lab, iOS 26.2 simulator, Oct 23 2026. The + * captured settles jump the last 0.33 pt onto the page about 0.35 s after + * a release at rest. + */ + restDistance: 0.5, + /** + * Step velocity (pt per step) below which a settle may end. + * @source GUESS — the captured settles end at about 0.04 pt per step; + * the threshold is not observable more finely at 60 fps + * @measure M-PG12 + */ + restSpeed: 0.05, + }, + release: { + /** + * Released slower than `advanceSpeed`, the scroll view settles on the page + * nearest the content position: past half a page, the next one. + * @source measured: UIKit lab, iOS 26.2 simulator, Oct 23 2026. In releases + * at rest from page 1, content at 48.5 % of the page stays, and 57.5 % + * goes to the next page. On a second 402 pt pager, 45 % stays and 55 % + * advances. + */ + commitFraction: 0.5, + /** + * Released at least this fast (pt/s), the scroll view pages in the + * direction of the velocity, from any content position. A flick from 6 % of + * the page advances. The speed is UIPanGestureRecognizer's velocity at the + * last movement, and it never decays. The scroll view's + * `_horizontalVelocity` equals it at every sample. A drag held still for + * 397 ms before the lift still pages at the speed it had. + * @source measured: UIKit lab, iOS 26.2 simulator, Oct 23 2026. Steady + * releases at 10, 25 and 40 % of a 402 pt page: 292.7, 295.3 and 298.6 + * pt/s stay; 310.7, 316.4 and 329.9 advance. The result is the same at + * every position: a threshold, not a projection. + */ + advanceSpeed: 300, + /** + * A settle velocity slower than this (pt/s) is zeroed, so the settle starts + * at rest. It is paging's own tuning on the one release velocity that every + * gesture reads. + * @source GUESS — the middle of the measured (200, 249] bracket. In the + * UIKit lab (iOS 26.2 simulator, Oct 23 2026), + * `scrollViewWillEndDragging` reads 0 for steady releases at 175 and 200 + * pt/s. It reads 0.249 pt/ms for a release at 249 pt/s. + * @measure M-PG13 + */ + velocityFloor: 225, + /** + * Pages a release may travel from the page the drag started on, at any + * speed and drag distance. + * @source measured: UIKit lab, iOS 26.2 simulator, Oct 23 2026. A drag of + * 1.5 pages from page 1 lands on page 2 at release speeds of 0, 600 and + * 3000 pt/s. + */ + maxPagesFromStart: 1, + }, + /** + * A finger that lands on a settling pager does not stop it at once. The + * settle runs on for about this long, then the content holds under the + * finger. Lifted without a move, the content settles again on the nearest + * page. + * @source measured: UIKit lab, iOS 26.2 simulator, Oct 23 2026. After + * touch-downs 60 and 160 ms into a settle, the content moved on for 82.6 + * and 87.5 ms (5 frames), then held. + */ + catchStopMs: 85, + /** + * A horizontal pager's pan begins only for a drag within atan(1 ÷ this) of + * horizontal (26.6° for 2). A steeper drag goes to the vertical scroll around + * it. Between 26.6° and 45°, neither moves. + * @source measured: UIKit lab, iOS 26.2 simulator, Oct 23 2026. A scroll + * view's directional lock holds the major axis up to 25° and frees it from + * 30°. An inline calendar pager in a sheet pages at 20° from horizontal. At + * 35° and 45°, it moves neither itself nor the sheet, and it leaves 55° to + * the sheet. + */ + panAxisRatio: 2, + animatedScroll: { + /** + * `setContentOffset(_:animated:)` duration. It is the same for one page and + * for five, as for a page control's tap. + * @source measured: UIKit lab, iOS 26.2 simulator, Oct 23 2026. + * `_contentOffsetAnimationDuration` reads 0.3, and five animated moves of + * 1 to 5 pages each last 0.30 s. + */ + duration: 0.3, + /** + * Its curve is a sinusoidal ease-in-out: x = from + (to − from) · (1 − cos + * πu) ÷ 2, for u = t ÷ duration. + * @source measured: UIKit lab, iOS 26.2 simulator, Oct 23 2026. The five + * moves fit the sinusoid to 0.14–0.51 pt RMS, and a 2010 pt move fits to + * 0.20 pt. The curve easeInEaseOut (0.42, 0, 0.58, 1) misses by 7.7 pt. + */ + curve: 'sineInOut', + }, + /** + * Past the first or last page, the content follows the finger through the + * scroll view's rubber band (scroll.rubberBand.coefficient), with d = the + * page width. It returns on the integrator above. + * @source measured: UIKit lab, iOS 26.2 simulator, Oct 23 2026. A pan of 90 + * pt past page 0 shows 42.7–45 pt, and 290 pt shows 114.3 pt. The formula + * gives 44.1 and 114.2, with c 0.55 and d 402. The return replays on the + * integrator to 0.16–0.33 pt RMS. + */ + rubberBandDimension: 'pageWidth', +} as const; diff --git a/packages/core/src/motion/uikit/scroll.ts b/packages/core/src/motion/uikit/scroll.ts index 7158a8d94717c..c2fc26ff260ed 100644 --- a/packages/core/src/motion/uikit/scroll.ts +++ b/packages/core/src/motion/uikit/scroll.ts @@ -4,8 +4,8 @@ * @file scroll.ts * @input Nothing; data only * @output Exports `scroll`, the UIScrollView constants: deceleration rates, - * the rubber-band coefficient, the bounce-back spring, paging and the - * content-touch delay + * the rubber-band coefficient, the bounce-back spring and the content-touch + * delay * @position The scroll domain of the UIKit constants table (motion/uikit); * read by the motion math and components * @@ -82,22 +82,6 @@ export const scroll = { * @measure M-S3 */ bounce: {duration: 0.5, bounce: 0}, - paging: { - /** - * Deceleration rate a paging release is projected with to pick the next - * page. - * @source GUESS — UIScrollView paging behaves like a fast scroll view; - * the rate it uses internally is not documented - * @measure M-PG1 - */ - projectionRate: 0.99, - /** - * The spring that carries a paging scroll view onto its page. - * @source GUESS — SwiftUI `.smooth` default until measured - * @measure M-PG1 - */ - snap: {duration: 0.5, bounce: 0}, - }, /** * `delaysContentTouches`: how long a scroll view holds a touch-down from * its content while it decides whether the touch is a scroll (no highlight diff --git a/packages/core/src/motion/uikit/tableImports.test.ts b/packages/core/src/motion/uikit/tableImports.test.ts index 97715084abc23..65b1986f5247a 100644 --- a/packages/core/src/motion/uikit/tableImports.test.ts +++ b/packages/core/src/motion/uikit/tableImports.test.ts @@ -16,12 +16,16 @@ import {existsSync, readdirSync, readFileSync, statSync} from 'node:fs'; import {dirname, join, relative, resolve} from 'node:path'; import {describe, expect, it} from 'vitest'; -/** The tables every touch module may share: the animator and gestures read them. */ +/** + * The tables shared code may read. The animator and gestures read these, and + * the paging math reads paging. + */ const SHARED_TABLES = new Set([ 'motion/uikit/gestures.ts', // The long-press values: useLongPress and the menus' press model read them. 'motion/uikit/longPress.ts', 'motion/uikit/navigation.ts', + 'motion/uikit/paging.ts', 'motion/uikit/scroll.ts', 'motion/uikit/springs.ts', 'motion/uikit/timing.ts', diff --git a/packages/core/src/motion/uikit/values.test.ts b/packages/core/src/motion/uikit/values.test.ts index 467ffb6d40b42..aa58c72fe32fd 100644 --- a/packages/core/src/motion/uikit/values.test.ts +++ b/packages/core/src/motion/uikit/values.test.ts @@ -32,7 +32,6 @@ describe('UIKit constants table through the motion math', () => { const springEntries: [string, SpringDescription][] = [ ...Object.entries(springs), ['scroll.bounce', scroll.bounce], - ['scroll.paging.snap', scroll.paging.snap], ]; it.each(springEntries)(