An open source design system that's fully customizable and agent ready
TypeScript
chore(core): UIKit's spring, decay, rubber-band and projection math (#8054)
Christopher Chedeaub58ca635e629
diff --git a/.changeset/uikit-motion-math.md b/.changeset/uikit-motion-math.mdnew file mode 100644index 0000000000..7af3d73a92--- /dev/null+++ b/.changeset/uikit-motion-math.md@@ -0,0 +1,7 @@+---+'@astryxdesign/core': patch+---++[chore] Internal: the spring, decay, rubber-band and projection math of UIKit for touch presentations, as pure functions checked against an independent integration and against values read from UIKit. Not exported from the package entry point; no component uses it yet.++@vjeuxdiff --git a/packages/core/src/motion/MEASUREMENTS.md b/packages/core/src/motion/MEASUREMENTS.mdindex bbdf52edab..7fb90666fc 100644--- a/packages/core/src/motion/MEASUREMENTS.md+++ b/packages/core/src/motion/MEASUREMENTS.md@@ -56,6 +56,7 @@ installed); rows marked † also on iOS 18 for the pre-glass delta. iPhone| M-CA1 | Settling duration | none: `CASpringAnimation` mass 1, stiffness 100, damping 5, 10, 15, 20, 40 × initialVelocity 0, 5, −5 × allowsOverdamping on, off | `settlingDuration` of each (checks the critically damped and overdamped branches) | D | `springs.ts` (settling) || M-T1 | Banner | A notification pushed to the simulator while an app is in the foreground | banner y(t) in and out; time on screen | B | `springs.banner` || M-RM1 | Reduced Motion | Reduce Motion on, Prefer Cross-Fade Transitions on and off: Settings push and pop, an alert (sheets: M-SH13; controls: M-SW11, M-SL12, M-SG15) | which transitions become cross-fades; alpha(t), duration and curve; what still moves | B | `timing.reducedMotionCrossFadeMs` (a reference reading, not played: `spec:AST-094` FR8) |+| M-PR1 | Press release curve | Settings and Contacts: a row tapped and released (the deselect cross-fade) | the timing function Core Animation attaches to the deselect fade (control points) | A | `timing.press.highlightOutCurve` || M-NB1 | Navigation bar hide / show | none | `UINavigationController.hideShowBarDuration` | D | `timing.navigationBarHideShowMs` |Done (UIKit lab, iOS 26.2 simulator, Oct 23 2026; values in `uikit/` taggeddiff --git a/packages/core/src/motion/README.md b/packages/core/src/motion/README.mdindex eee925f2d8..1de471ca79 100644--- a/packages/core/src/motion/README.md+++ b/packages/core/src/motion/README.md@@ -1,12 +1,12 @@# Motion-Internal motion foundation for the touch presentations of core components. It-starts with the UIKit constants table: every spring, duration, deceleration-rate, rubber-band constant, curve and gesture threshold a touch presentation-uses, each with its source. Nothing here is exported from the package entry-point. Core's motion and gesture modules read it by path; components take-touch motion from the theme's motion roles (`spec:AST-094` FR4), not from-this table.+Internal motion foundation for the touch presentations of core components: the+UIKit constants table (every spring, duration, deceleration rate, rubber-band+constant, curve and gesture threshold a touch presentation uses, each with its+source) and the spring, decay, rubber-band and projection math UIKit uses.+Nothing here is exported from the package entry point. Core's motion and+gesture modules read the table by path; components take touch motion from the+theme's motion roles (`spec:AST-094` FR4), not from this table.## Files@@ -19,11 +19,35 @@ this table.| `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). || `MEASUREMENTS.md` | The UIKit reference captures each unconfirmed value still needs. |+| `spring.ts` | Closed-form damped spring, every Apple parameterization, settling duration, a spring chasing a moving target. |+| `decay.ts` | UIScrollView's momentum coast. |+| `rubberBand.ts` | UIScrollView's resistance past an edge, and its inverse. |+| `projection.ts` | Release targets: the rest point nearest the projected coast; paging. |Component-specific values (a sheet's detents, a switch's geometry, a contextmenu's timeline) live in a domain file per component, `uikit/<component>.ts`,under the same rules.+## Math++`spring.ts` solves m·x″ + c·x′ + k·x = 0 in closed form in all three regimes:+the model behind SwiftUI's `Spring`, `CASpringAnimation` and+`UISpringTimingParameters`. A spring description stays in its source's+vocabulary (mass, stiffness and damping; duration and bounce; response and+damping ratio) and `toSpring` normalizes it. A mass, stiffness and damping+description that does not allow overdamping is clamped to critical, as Core+Animation does for every spring UIKit attaches. The tests hold it to an+independent fourth-order Runge-Kutta integration over a sweep of damping+ratios, responses and release velocities; to a port of WebKit's own spring+solver; to the WWDC23 "Animate with springs" conversion equations; and to+values read from UIKit on the iOS 26.2 simulator: `settlingDuration` for a+grid of springs and velocities, and the durations UIKit gives its spring APIs,+which the settling formula reproduces to the last digit (underdamped) or within+0.02 % (critically damped). `decay.ts` is held to a literal per-millisecond+simulation of the deceleration rate and to WWDC18's projection function;+`rubberBand.ts` to UIScrollView's overscroll measured on the simulator.+`uikit/values.test.ts` plays the table's values through this math.+## SourcesEvery value in `uikit/` carries its source next to it, as a JSDoc tag on thediff --git a/packages/core/src/motion/decay.test.ts b/packages/core/src/motion/decay.test.tsnew file mode 100644index 0000000000..41d5bee1b6--- /dev/null+++ b/packages/core/src/motion/decay.test.ts@@ -0,0 +1,120 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file decay.test.ts+ * @input vitest, the decay model+ * @output Checks the continuous coast against an independent per-millisecond+ * simulation of UIScrollView's deceleration, against WWDC18's projection,+ * and every derived time (settle, speed, reach)+ * @position Testing; validates decay.ts without a browser+ */++import {describe, expect, it} from 'vitest';+import {decayRestDistance, solveDecay} from './decay';+import {projectDistance} from './projection';+import {scroll} from './uikit/scroll';++/**+ * Independent reference: the deceleration rate applied literally, the+ * velocity multiplied by the rate once per millisecond and integrated+ * exactly over each millisecond step.+ */+function perMillisecond(+ from: number,+ velocity: number,+ rate: number,+ ms: number,+) {+ let x = from;+ let v = velocity / 1000; // units per ms+ const k = -Math.log(rate);+ for (let i = 0; i < ms; i++) {+ // Within one ms the speed falls from v to v·rate exponentially.+ x += (v * (1 - rate)) / k;+ v *= rate;+ }+ return {value: x, velocity: v * 1000};+}++describe('solveDecay', () => {+ for (const rate of [+ scroll.decelerationRate.normal,+ scroll.decelerationRate.fast,+ ]) {+ for (const velocity of [-3000, -400, 150, 2500, 8000]) {+ it(`matches a per-millisecond simulation (rate ${rate}, ${velocity} units/s)`, () => {+ const coast = solveDecay({from: 100, velocity, rate});+ for (const ms of [0, 1, 16, 100, 250, 600, 1500, 4000]) {+ const reference = perMillisecond(100, velocity, rate, ms);+ expect(coast.value(ms / 1000)).toBeCloseTo(reference.value, 6);+ expect(coast.velocity(ms / 1000)).toBeCloseTo(reference.velocity, 6);+ }+ });+ }+ }++ it('rests where the coast ends, 0.1 % past WWDC18\u2019s geometric projection', () => {+ const coast = solveDecay({from: 0, velocity: 2000});+ expect(coast.rest).toBeCloseTo(2000 / (-1000 * Math.log(0.998)), 9);+ expect(coast.value(60)).toBeCloseTo(coast.rest, 6);+ // −1 ÷ ln(0.998) = 499.5 ms against 0.998 ÷ 0.002 = 499 ms.+ expect(coast.rest / projectDistance(2000)).toBeCloseTo(499.5 / 499, 3);+ expect(decayRestDistance(2000)).toBeCloseTo(coast.rest, 9);+ });++ it('a fast rate stops sooner and shorter', () => {+ const normal = solveDecay({from: 0, velocity: 2000});+ const fast = solveDecay({+ from: 0,+ velocity: 2000,+ rate: scroll.decelerationRate.fast,+ });+ expect(fast.rest).toBeLessThan(normal.rest);+ expect(fast.settleTime(0.5)).toBeLessThan(normal.settleTime(0.5));+ });++ it('settleTime bounds every later distance to rest', () => {+ const coast = solveDecay({from: 0, velocity: -5000});+ for (const threshold of [5, 0.5, 0.01]) {+ const settle = coast.settleTime(threshold);+ expect(Math.abs(coast.value(settle) - coast.rest)).toBeCloseTo(+ threshold,+ 9,+ );+ expect(Math.abs(coast.value(settle + 0.5) - coast.rest)).toBeLessThan(+ threshold,+ );+ }+ expect(solveDecay({from: 0, velocity: 0.1}).settleTime(0.5)).toBe(0);+ });++ it('timeToSpeed lands on the asked speed', () => {+ const coast = solveDecay({from: 0, velocity: 3000});+ const t = coast.timeToSpeed(100);+ expect(coast.velocity(t)).toBeCloseTo(100, 9);+ expect(coast.timeToSpeed(5000)).toBe(0);+ expect(coast.timeToSpeed(0)).toBe(Infinity);+ });++ it('timeToReach finds the crossing, or null when the coast never gets there', () => {+ const coast = solveDecay({from: 0, velocity: 2000});+ const t = coast.timeToReach(400);+ expect(t).not.toBeNull();+ expect(coast.value(t ?? 0)).toBeCloseTo(400, 9);+ expect(coast.timeToReach(-10)).toBeNull();+ expect(coast.timeToReach(coast.rest)).toBeNull();+ expect(coast.timeToReach(coast.rest + 1)).toBeNull();+ const back = solveDecay({from: 0, velocity: -2000});+ expect(back.value(back.timeToReach(-400) ?? 0)).toBeCloseTo(-400, 9);+ expect(solveDecay({from: 3, velocity: 0}).timeToReach(3)).toBe(0);+ });++ it('rejects a rate outside (0, 1)', () => {+ expect(() => solveDecay({from: 0, velocity: 1, rate: 1})).toThrow(+ RangeError,+ );+ expect(() => solveDecay({from: 0, velocity: 1, rate: 0})).toThrow(+ RangeError,+ );+ });+});diff --git a/packages/core/src/motion/decay.ts b/packages/core/src/motion/decay.tsnew file mode 100644index 0000000000..be005048d0--- /dev/null+++ b/packages/core/src/motion/decay.ts@@ -0,0 +1,126 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file decay.ts+ * @input A release value, velocity and a UIScrollView deceleration rate+ * @output Exports `solveDecay`, the closed-form momentum coast of a scroll+ * view after the finger lifts (value, velocity, rest point, settle time,+ * time to reach a value), and `decayRestDistance`+ * @position Pure math under the motion animator; no DOM, no React+ *+ * UIScrollView's deceleration rate is a per-millisecond velocity factor: the+ * speed is multiplied by the rate every millisecond (0.998 normal, 0.99 fast;+ * see uikit/scroll.ts). As a continuous decay that is+ * v(t) = v₀·e^(−λt), x(t) = x₀ + v₀·(1 − e^(−λt)) ÷ λ, λ = −1000·ln(rate) /s+ * and the coast ends at x₀ + v₀ ÷ λ. WWDC18 "Designing Fluid Interfaces"+ * projects the same rest point with the geometric series v₀·rate ÷ (1 − rate)+ * per millisecond (projection.ts), 0.1 % shorter at the normal rate (499.0+ * against 499.5 ms of the release speed); the continuous form is the one+ * that also gives the position and velocity at every instant, which the+ * animator needs to grab a coasting surface mid-flight.+ *+ * Units: time in seconds, velocity in units per second.+ *+ * SYNC: When modified, update:+ * - /packages/core/src/motion/decay.test.ts+ * - /packages/core/src/motion/README.md+ */++import {scroll} from './uikit/scroll';++/** A coast released at `from` with `initialVelocity`. */+export interface DecayCurve {+ readonly from: number;+ /** Units per second. */+ readonly initialVelocity: number;+ /** Per-millisecond velocity factor. */+ readonly rate: number;+ /** Where the coast comes to rest. */+ readonly rest: number;+ /** Value `t` seconds after release. */+ value(t: number): number;+ /** Velocity `t` seconds after release, units/s. */+ velocity(t: number): number;+ /** Seconds until the value is within `threshold` of `rest` for good. */+ settleTime(threshold: number): number;+ /** Seconds until the speed falls to `speed` units/s (0 if already slower). */+ timeToSpeed(speed: number): number;+ /**+ * Seconds until the coast reaches `target`, or null when it never gets+ * there (behind the release point, or at or past the rest point).+ */+ timeToReach(target: number): number | null;+}++function decayConstant(rate: number): number {+ if (!(rate > 0 && rate < 1)) {+ throw new RangeError(`decay: rate must be in (0, 1), got ${rate}`);+ }+ return -1000 * Math.log(rate);+}++/** How far a coast at `velocity` units/s travels before it stops. */+export function decayRestDistance(+ velocity: number,+ rate: number = scroll.decelerationRate.normal,+): number {+ return velocity / decayConstant(rate);+}++/**+ * The momentum coast UIScrollView performs after the finger lifts.+ *+ * @example+ * ```+ * const coast = solveDecay({from: 0, velocity: 2000});+ * coast.rest; // ≈ 999 px+ * coast.value(0.2); // px after 200 ms+ * ```+ */+export function solveDecay({+ from,+ velocity: initialVelocity,+ rate = scroll.decelerationRate.normal,+}: {+ from: number;+ velocity: number;+ rate?: number;+}): DecayCurve {+ const lambda = decayConstant(rate);+ const rest = from + initialVelocity / lambda;+ const speed0 = Math.abs(initialVelocity);+ return {+ from,+ initialVelocity,+ rate,+ rest,+ value: t => from + (initialVelocity * -Math.expm1(-lambda * t)) / lambda,+ velocity: t => initialVelocity * Math.exp(-lambda * t),+ settleTime: threshold => {+ const remaining = speed0 / lambda;+ if (!(threshold > 0)) {+ return Infinity;+ }+ return remaining <= threshold+ ? 0+ : Math.log(remaining / threshold) / lambda;+ },+ timeToSpeed: speed =>+ speed0 <= speed+ ? 0+ : speed > 0+ ? Math.log(speed0 / speed) / lambda+ : Infinity,+ timeToReach: target => {+ if (initialVelocity === 0) {+ return target === from ? 0 : null;+ }+ // 1 − e^(−λt) = λ·(target − from) ÷ v₀+ const fraction = (lambda * (target - from)) / initialVelocity;+ if (fraction < 0 || fraction >= 1) {+ return null;+ }+ return -Math.log1p(-fraction) / lambda;+ },+ };+}diff --git a/packages/core/src/motion/projection.test.ts b/packages/core/src/motion/projection.test.tsnew file mode 100644index 0000000000..21bdae9f96--- /dev/null+++ b/packages/core/src/motion/projection.test.ts@@ -0,0 +1,139 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file projection.test.ts+ * @input vitest, the projection functions+ * @output Checks WWDC18's projection verbatim and the release-target rules+ * (nearest projected rest, step limits, paging)+ * @position Testing; validates projection.ts without a browser+ */++import {describe, expect, it} from 'vitest';+import {+ project,+ projectDistance,+ selectPage,+ selectSnapPoint,+} from './projection';+import {scroll} from './uikit/scroll';++describe('projectDistance', () => {+ it('is WWDC18\u2019s (v ÷ 1000)·r ÷ (1 − r)', () => {+ for (const velocity of [-2500, -1, 0, 640, 3000]) {+ for (const rate of [0.998, 0.99]) {+ expect(projectDistance(velocity, rate)).toBeCloseTo(+ ((velocity / 1000) * rate) / (1 - rate),+ 9,+ );+ }+ }+ });++ it('projects 499 ms of the release speed at the normal rate (the sheet\u2019s prior art)', () => {+ expect(projectDistance(1000)).toBeCloseTo(499, 9);+ expect(projectDistance(1000, scroll.decelerationRate.fast)).toBeCloseTo(+ 99,+ 9,+ );+ });++ it('a release at rest projects onto itself', () => {+ expect(project(321, 0)).toBe(321);+ });++ it('rejects a rate outside (0, 1)', () => {+ expect(() => projectDistance(10, 1)).toThrow(RangeError);+ });+});++describe('selectSnapPoint', () => {+ const detents = [0, 300, 600];++ it('goes to the point nearest the projected rest, not the release point', () => {+ // Released nearer 300, but thrown toward 600.+ expect(selectSnapPoint(detents, {position: 320, velocity: 900}).value).toBe(+ 600,+ );+ // A slow release places.+ expect(selectSnapPoint(detents, {position: 320, velocity: 20}).value).toBe(+ 300,+ );+ // Thrown the other way.+ expect(+ selectSnapPoint(detents, {position: 320, velocity: -900}).value,+ ).toBe(0);+ });++ it('a projection past the ends lands on the end', () => {+ expect(+ selectSnapPoint(detents, {position: 580, velocity: 6000}).value,+ ).toBe(600);+ expect(+ selectSnapPoint(detents, {position: 10, velocity: -6000}).index,+ ).toBe(0);+ });++ it('reports the projection it chose from', () => {+ const choice = selectSnapPoint(detents, {position: 100, velocity: 400});+ expect(choice.projected).toBeCloseTo(100 + 0.4 * 499, 9);+ });++ it('limits the travel to maxSteps points from fromIndex', () => {+ const pages = [0, 100, 200, 300, 400];+ expect(selectSnapPoint(pages, {position: 110, velocity: 5000}).value).toBe(+ 400,+ );+ expect(+ selectSnapPoint(pages, {+ position: 110,+ velocity: 5000,+ fromIndex: 1,+ maxSteps: 1,+ }).value,+ ).toBe(200);+ });++ it('breaks an exact tie toward the direction of travel', () => {+ expect(+ selectSnapPoint([0, 100], {position: 50, velocity: 0.0001, rate: 0.5})+ .value,+ ).toBe(100);+ expect(+ selectSnapPoint([0, 100], {position: 50, velocity: -0.0001, rate: 0.5})+ .value,+ ).toBe(0);+ });++ it('needs at least one point', () => {+ expect(() => selectSnapPoint([], {position: 0, velocity: 0})).toThrow(+ RangeError,+ );+ });+});++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/projection.ts b/packages/core/src/motion/projection.tsnew file mode 100644index 0000000000..8f0d0c8b92--- /dev/null+++ b/packages/core/src/motion/projection.ts@@ -0,0 +1,148 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file projection.ts+ * @input A release position and velocity, candidate rest points+ * @output Exports `projectDistance` / `project` (WWDC18's momentum+ * projection), `selectSnapPoint` (the release target UIKit-style) and+ * `selectPage` (paging: at most one page per release)+ * @position Pure math; no DOM, no React+ *+ * WWDC18 "Designing Fluid Interfaces" (session 803): a thrown object goes to+ * the endpoint nearest to where it WOULD coast if it were scrolled, not the+ * endpoint nearest to where the finger let go. The talk's projection+ * function, verbatim in units/s:+ *+ * func project(initialVelocity: CGFloat, decelerationRate: CGFloat) -> CGFloat {+ * return (initialVelocity / 1000.0) * decelerationRate / (1.0 - decelerationRate)+ * }+ *+ * used with `UIScrollView.DecelerationRate.normal`. A slow release projects+ * onto itself, so it places; a flick continues past the finger.+ *+ * SYNC: When modified, update:+ * - /packages/core/src/motion/projection.test.ts+ * - /packages/core/src/motion/README.md+ */++import {scroll} from './uikit/scroll';++/** Distance a surface released at `velocity` units/s coasts (WWDC18). */+export function projectDistance(+ velocity: number,+ rate: number = scroll.decelerationRate.normal,+): number {+ if (!(rate > 0 && rate < 1)) {+ throw new RangeError(`projection: rate must be in (0, 1), got ${rate}`);+ }+ return ((velocity / 1000) * rate) / (1 - rate);+}++/** Where a surface released at `position` with `velocity` would come to rest. */+export function project(+ position: number,+ velocity: number,+ rate: number = scroll.decelerationRate.normal,+): number {+ return position + projectDistance(velocity, rate);+}++export interface SnapSelection {+ /** Index of the chosen point in the list passed in. */+ readonly index: number;+ /** The chosen point. */+ readonly value: number;+ /** The projected rest position the choice was made from. */+ readonly projected: number;+}++/**+ * The rest point a release goes to: the one nearest the projected rest+ * position. `fromIndex` + `maxSteps` limit how many points away from the+ * starting one a single release may travel (by index order; pass points+ * sorted along the axis). Ties go to the point in the direction of travel.+ *+ * @example+ * ```+ * // A sheet with detents at 0, 300 and 600 px, released at 320 px moving+ * // 900 px/s toward 600: projected ≈ 769 → 600.+ * selectSnapPoint([0, 300, 600], {position: 320, velocity: 900});+ * ```+ */+export function selectSnapPoint(+ points: ReadonlyArray<number>,+ {+ position,+ velocity,+ rate = scroll.decelerationRate.normal,+ fromIndex,+ maxSteps,+ }: {+ position: number;+ velocity: number;+ rate?: number;+ fromIndex?: number;+ maxSteps?: number;+ },+): SnapSelection {+ if (points.length === 0) {+ throw new RangeError(+ 'projection: selectSnapPoint needs at least one point',+ );+ }+ const projected = project(position, velocity, rate);+ let lo = 0;+ let hi = points.length - 1;+ if (fromIndex != null && maxSteps != null) {+ // A stale index past either end counts from the nearest real point.+ const from = Math.min(Math.max(fromIndex, 0), points.length - 1);+ lo = Math.max(lo, from - maxSteps);+ hi = Math.min(hi, from + maxSteps);+ }+ let best = lo;+ let bestDistance = Infinity;+ for (let i = lo; i <= hi; i++) {+ const distance = Math.abs(points[i] - projected);+ const isTie = Math.abs(distance - bestDistance) < 1e-9;+ const isAhead = Math.sign(points[i] - points[best]) === Math.sign(velocity);+ if (distance < bestDistance - 1e-9 || (isTie && isAhead)) {+ best = i;+ bestDistance = distance;+ }+ }+ return {index: best, value: points[best], projected};+}++/**+ * 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,+ );+ return selectSnapPoint(points, {+ position,+ velocity,+ rate,+ fromIndex: currentPage,+ maxSteps: 1,+ });+}diff --git a/packages/core/src/motion/rubberBand.test.ts b/packages/core/src/motion/rubberBand.test.tsnew file mode 100644index 0000000000..3328d94eab--- /dev/null+++ b/packages/core/src/motion/rubberBand.test.ts@@ -0,0 +1,88 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file rubberBand.test.ts+ * @input vitest, the rubber-band functions+ * @output Checks the formula against a published device measurement of+ * UIScrollView, its slope, inverse and clamp round trips+ * @position Testing; validates rubberBand.ts without a browser+ */++import {describe, expect, it} from 'vitest';+import {+ rubberBand,+ rubberBandClamp,+ rubberBandInverse,+ rubberBandSlope,+ rubberBandUnclamp,+} from './rubberBand';++describe('rubberBand', () => {+ it('reproduces the published UIScrollView measurement (812 pt view)', () => {+ // Finger 500 / 1000 / 1500 pt past the edge displayed 205 / 328 / 409 pt+ // (I. Lobanov, "How UIScrollView works").+ expect(Math.abs(rubberBand(500, 812) - 205)).toBeLessThan(0.5);+ expect(Math.abs(rubberBand(1000, 812) - 328)).toBeLessThan(0.5);+ expect(Math.abs(rubberBand(1500, 812) - 409)).toBeLessThan(0.5);+ });++ it('is (1 − 1 ÷ (x·c ÷ d + 1))·d with c = 0.55', () => {+ for (const x of [0, 1, 10, 80, 300, 2000]) {+ expect(rubberBand(x, 600)).toBeCloseTo(+ (1 - 1 / ((x * 0.55) / 600 + 1)) * 600,+ 9,+ );+ }+ expect(rubberBand(100, 600, 0.3)).toBeCloseTo(+ (1 - 1 / ((100 * 0.3) / 600 + 1)) * 600,+ 9,+ );+ });++ it('keeps the sign, never reaches the dimension, starts at slope c', () => {+ expect(rubberBand(-120, 700)).toBeCloseTo(-rubberBand(120, 700), 12);+ expect(rubberBand(1e9, 700)).toBeLessThan(700);+ expect(rubberBandSlope(0, 700)).toBeCloseTo(0.55, 12);+ for (const x of [0, 50, 400, 3000]) {+ const h = 1e-4;+ const numeric =+ (rubberBand(x + h, 700) - rubberBand(x - h, 700)) / (2 * h);+ expect(rubberBandSlope(x, 700)).toBeCloseTo(numeric, 6);+ }+ });++ it('inverts exactly', () => {+ for (const x of [-900, -40, 0, 3, 75, 640, 5000]) {+ expect(rubberBandInverse(rubberBand(x, 812), 812)).toBeCloseTo(x, 6);+ }+ expect(rubberBandInverse(812, 812)).toBe(Infinity);+ expect(rubberBandInverse(-900, 812)).toBe(-Infinity);+ });++ it('a degenerate dimension bands nothing', () => {+ expect(rubberBand(50, 0)).toBe(0);+ expect(rubberBandInverse(50, 0)).toBe(0);+ expect(rubberBandSlope(50, 0)).toBe(0);+ });+});++describe('rubberBandClamp', () => {+ it('passes values inside the range through and bands past either edge', () => {+ expect(rubberBandClamp(120, 0, 500, 800)).toBe(120);+ expect(rubberBandClamp(-100, 0, 500, 800)).toBeCloseTo(+ rubberBand(-100, 800),+ 12,+ );+ expect(rubberBandClamp(650, 0, 500, 800)).toBeCloseTo(+ 500 + rubberBand(150, 800),+ 12,+ );+ });++ it('round-trips through rubberBandUnclamp (a grab mid-bounce resumes in place)', () => {+ for (const raw of [-600, -12, 0, 250, 500, 510, 1400]) {+ const shown = rubberBandClamp(raw, 0, 500, 800);+ expect(rubberBandUnclamp(shown, 0, 500, 800)).toBeCloseTo(raw, 6);+ }+ });+});diff --git a/packages/core/src/motion/rubberBand.ts b/packages/core/src/motion/rubberBand.tsnew file mode 100644index 0000000000..bde101ec3c--- /dev/null+++ b/packages/core/src/motion/rubberBand.ts@@ -0,0 +1,115 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file rubberBand.ts+ * @input An overflow past an edge, the scroll view's dimension and UIKit's+ * rubber-band coefficient+ * @output Exports `rubberBand` (finger overflow → displayed overflow), its+ * inverse, its slope, and the clamp/unclamp pair over a [min, max] range+ * @position Pure math; no DOM, no React+ *+ * UIScrollView resists a drag past its content edge with+ * b = (1 − 1 ÷ (x·c ÷ d + 1))·d+ * where x is how far the finger has gone past the edge, d the scroll view's+ * size on that axis and c = 0.55 (uikit/scroll.ts records the sources). The+ * displayed overflow b approaches d but never reaches it, and its slope at+ * the edge is c: the first points of overflow move at 55 % of the finger.+ *+ * The inverse matters for spec:AST-094 FR6 (a finger catches any animation+ * mid-flight): a finger that lands on content still bouncing back has to+ * resume the drag from the finger position that would produce the overflow+ * on screen, or the content jumps.+ *+ * SYNC: When modified, update:+ * - /packages/core/src/motion/rubberBand.test.ts+ * - /packages/core/src/motion/README.md+ */++import {scroll} from './uikit/scroll';++/**+ * Displayed overflow for a finger `overflow` past the edge (signed: the sign+ * is kept). `dimension` is the scroll view's size on the axis.+ */+export function rubberBand(+ overflow: number,+ dimension: number,+ coefficient: number = scroll.rubberBand.coefficient,+): number {+ if (!(dimension > 0)) {+ return 0;+ }+ const x = Math.abs(overflow);+ const banded = (1 - 1 / ((x * coefficient) / dimension + 1)) * dimension;+ return overflow < 0 ? -banded : banded;+}++/** The finger overflow that displays `displayed`; ±Infinity at ±dimension. */+export function rubberBandInverse(+ displayed: number,+ dimension: number,+ coefficient: number = scroll.rubberBand.coefficient,+): number {+ if (!(dimension > 0)) {+ return 0;+ }+ const b = Math.abs(displayed);+ if (b >= dimension) {+ return displayed < 0 ? -Infinity : Infinity;+ }+ const x = ((dimension / coefficient) * b) / (dimension - b);+ return displayed < 0 ? -x : x;+}++/**+ * d(displayed) ÷ d(finger) at a finger overflow: what a finger velocity+ * becomes on screen while banding (c at the edge, falling toward 0).+ */+export function rubberBandSlope(+ overflow: number,+ dimension: number,+ coefficient: number = scroll.rubberBand.coefficient,+): number {+ if (!(dimension > 0)) {+ return 0;+ }+ const u = (Math.abs(overflow) * coefficient) / dimension + 1;+ return coefficient / (u * u);+}++/**+ * The displayed value for a raw (finger-driven) `value` constrained to+ * [min, max]: unchanged inside, rubber-banded past either edge.+ */+export function rubberBandClamp(+ value: number,+ min: number,+ max: number,+ dimension: number,+ coefficient: number = scroll.rubberBand.coefficient,+): number {+ if (value < min) {+ return min + rubberBand(value - min, dimension, coefficient);+ }+ if (value > max) {+ return max + rubberBand(value - max, dimension, coefficient);+ }+ return value;+}++/** Inverse of `rubberBandClamp`: the raw value that displays `displayed`. */+export function rubberBandUnclamp(+ displayed: number,+ min: number,+ max: number,+ dimension: number,+ coefficient: number = scroll.rubberBand.coefficient,+): number {+ if (displayed < min) {+ return min + rubberBandInverse(displayed - min, dimension, coefficient);+ }+ if (displayed > max) {+ return max + rubberBandInverse(displayed - max, dimension, coefficient);+ }+ return displayed;+}diff --git a/packages/core/src/motion/spring.test.ts b/packages/core/src/motion/spring.test.tsnew file mode 100644index 0000000000..e770107b77--- /dev/null+++ b/packages/core/src/motion/spring.test.ts@@ -0,0 +1,650 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file spring.test.ts+ * @input vitest, the spring model+ * @output Checks the closed-form spring against an independent RK4+ * integration of the ODE across damping regimes, every conversion against+ * Apple's published equations, and the settling duration against every+ * published reference value+ * @position Testing; validates spring.ts without a browser+ */++import {describe, expect, it} from 'vitest';+import {+ absoluteVelocity,+ dampingRatioOf,+ durationBounceOf,+ relativeVelocity,+ responseDampingOf,+ responseOf,+ settlingDuration,+ solveSpring,+ solveSpringTowardRamp,+ springFromDurationBounce,+ springFromPhysics,+ springFromResponse,+ springFromUIKitDampingDuration,+ type Spring,+} from './spring';++/**+ * Independent reference: classic fourth-order Runge-Kutta on+ * m·x″ + c·x′ + k·(x − to) = 0. Shares nothing with the closed form.+ */+function rk4(+ spring: Spring,+ from: number,+ to: number,+ velocity: number,+ until: number,+ dt = 1e-4,+): {t: number; value: number; velocity: number}[] {+ const {mass: m, stiffness: k, damping: c} = spring;+ const accel = (x: number, v: number) => (-k * (x - to) - c * v) / m;+ let x = from;+ let v = velocity;+ const out = [{t: 0, value: x, velocity: v}];+ const steps = Math.round(until / dt);+ for (let i = 1; i <= steps; i++) {+ const k1x = v;+ const k1v = accel(x, v);+ const k2x = v + (dt / 2) * k1v;+ const k2v = accel(x + (dt / 2) * k1x, v + (dt / 2) * k1v);+ const k3x = v + (dt / 2) * k2v;+ const k3v = accel(x + (dt / 2) * k2x, v + (dt / 2) * k2v);+ const k4x = v + dt * k3v;+ const k4v = accel(x + dt * k3x, v + dt * k3v);+ x += (dt / 6) * (k1x + 2 * k2x + 2 * k3x + k4x);+ v += (dt / 6) * (k1v + 2 * k2v + 2 * k3v + k4v);+ if (i % 100 === 0) {+ out.push({t: i * dt, value: x, velocity: v});+ }+ }+ return out;+}++const RATIOS = [+ 0, 0.05, 0.3, 0.5, 0.75, 0.9, 0.99, 0.999999, 1, 1.000001, 1.2, 2, 5,+];+const RESPONSES = [0.15, 0.35, 0.5, 1];+const RELEASES = [+ {from: 0, to: 1, velocity: 0},+ {from: 0, to: 300, velocity: 0},+ {from: 300, to: 0, velocity: -2500},+ {from: -120, to: 80, velocity: 4000},+ // Zero displacement, all velocity: the case UIKit's relative velocity+ // cannot express.+ {from: 50, to: 50, velocity: 1800},+];++describe('solveSpring matches an RK4 integration of the ODE', () => {+ for (const dampingRatio of RATIOS) {+ for (const response of RESPONSES) {+ it(`ζ=${dampingRatio}, response=${response}s`, () => {+ // springFromResponse keeps overdamping, so every regime is covered.+ const spring = springFromResponse({response, dampingRatio});+ for (const release of RELEASES) {+ const curve = solveSpring(spring, release);+ const scale = Math.max(+ 1,+ Math.abs(release.from - release.to),+ Math.abs(release.velocity) * response,+ );+ for (const sample of rk4(+ spring,+ release.from,+ release.to,+ release.velocity,+ 1.5,+ )) {+ expect(Math.abs(curve.value(sample.t) - sample.value)).toBeLessThan(+ 1e-6 * scale,+ );+ expect(+ Math.abs(curve.velocity(sample.t) - sample.velocity),+ ).toBeLessThan((1e-6 * scale * 2 * Math.PI) / response);+ }+ }+ });+ }+ }+});++describe('solveSpring', () => {+ it('agrees with WebKit\u2019s SpringSolver (an independent port of its code)', () => {+ // Source/WebCore/platform/graphics/SpringSolver.h, verbatim in+ // structure: unit move, initial velocity positive toward the target.+ const webkitSolve = (+ m: number,+ k: number,+ c: number,+ v0: number,+ t: number,+ ) => {+ const w0 = Math.sqrt(k / m);+ const zeta = c / (2 * Math.sqrt(k * m));+ let x: number;+ if (zeta < 1) {+ const wd = w0 * Math.sqrt(1 - zeta * zeta);+ const b = (zeta * w0 + -v0) / wd;+ x =+ Math.exp(-t * zeta * w0) * (Math.cos(wd * t) + b * Math.sin(wd * t));+ } else {+ x = (1 + (-v0 + w0) * t) * Math.exp(-t * w0);+ }+ return 1 - x;+ };+ const cases = [+ [1, 438.64908449286042, 31.415926535897931, 0],+ [1, 322.27279677026473, 31.2364069556928, 0],+ [1, 100, 5, 0],+ [1, 100, 20, 0],+ [2, 300, 12, 4],+ [1, 250, 31.6227766016838, -3],+ ];+ for (const [m, k, c, v0] of cases) {+ const curve = solveSpring(+ springFromPhysics({mass: m, stiffness: k, damping: c}),+ {+ from: 0,+ to: 1,+ velocity: v0,+ },+ );+ for (let t = 0; t <= 1.5; t += 0.01) {+ expect(curve.value(t)).toBeCloseTo(webkitSolve(m, k, c, v0, t), 6);+ }+ }+ });++ it('starts at the release value and velocity in every regime', () => {+ for (const dampingRatio of RATIOS) {+ const curve = solveSpring(+ springFromResponse({response: 0.4, dampingRatio}),+ {+ from: 10,+ to: 250,+ velocity: -700,+ },+ );+ expect(curve.value(0)).toBeCloseTo(10, 9);+ expect(curve.velocity(0)).toBeCloseTo(-700, 6);+ }+ });++ it('is continuous across critical damping', () => {+ const release = {from: 0, to: 300, velocity: 1200};+ const critical = solveSpring(+ springFromResponse({response: 0.5, dampingRatio: 1}),+ release,+ );+ for (const dampingRatio of [1 - 1e-5, 1 - 1e-7, 1 + 1e-7, 1 + 1e-5]) {+ const near = solveSpring(+ springFromResponse({response: 0.5, dampingRatio}),+ release,+ );+ for (let t = 0; t <= 1.5; t += 0.01) {+ expect(Math.abs(near.value(t) - critical.value(t))).toBeLessThan(0.01);+ }+ }+ });++ it('comes to rest at the target', () => {+ for (const dampingRatio of RATIOS.filter(r => r > 0)) {+ const curve = solveSpring(+ springFromResponse({response: 0.3, dampingRatio}),+ {from: 0, to: 100},+ );+ const settle = curve.settleTime(0.01);+ expect(Math.abs(curve.value(settle + 5) - 100)).toBeLessThan(0.01);+ }+ });++ it('settleTime bounds every later displacement (property sweep)', () => {+ for (const dampingRatio of RATIOS.filter(r => r > 0)) {+ for (const response of RESPONSES) {+ for (const release of RELEASES) {+ const curve = solveSpring(+ springFromResponse({response, dampingRatio}),+ release,+ );+ for (const threshold of [1, 0.1, 0.001]) {+ const settle = curve.settleTime(threshold);+ expect(Number.isFinite(settle)).toBe(true);+ for (let i = 0; i <= 400; i++) {+ const t = settle + (i / 400) * 3 * response;+ expect(Math.abs(curve.value(t) - release.to)).toBeLessThanOrEqual(+ threshold * (1 + 1e-9),+ );+ }+ }+ }+ }+ }+ });++ it('settleTime is 0 when already settled, Infinity when undamped and displaced', () => {+ const spring = springFromResponse({response: 0.4, dampingRatio: 0.8});+ expect(solveSpring(spring, {from: 5, to: 5}).settleTime(0.5)).toBe(0);+ expect(solveSpring(spring, {from: 5.1, to: 5}).settleTime(0.5)).toBe(0);+ const undamped = springFromResponse({response: 0.4, dampingRatio: 0});+ expect(solveSpring(undamped, {from: 0, to: 1}).settleTime(0.001)).toBe(+ Infinity,+ );+ });++ it('an undamped spring oscillates with the response as its period (WWDC23: bounce 1 is a cosine)', () => {+ const curve = solveSpring(+ springFromDurationBounce({duration: 0.5, bounce: 1}),+ {from: 0, to: 1},+ );+ for (let t = 0; t <= 2; t += 0.05) {+ expect(curve.value(t)).toBeCloseTo(+ 1 - Math.cos((2 * Math.PI * t) / 0.5),+ 9,+ );+ }+ });+});++describe('solveSpringTowardRamp (a target moving at constant speed)', () => {+ /** RK4 on m·x″ + c·x′ + k·(x − (target + slope·t)) = 0. */+ function rk4Ramp(+ spring: Spring,+ {+ from,+ velocity,+ target,+ slope,+ }: {from: number; velocity: number; target: number; slope: number},+ until: number,+ dt = 1e-4,+ ): {t: number; value: number; velocity: number}[] {+ const {mass: m, stiffness: k, damping: c} = spring;+ const accel = (time: number, x: number, v: number) =>+ (-k * (x - (target + slope * time)) - c * v) / m;+ let x = from;+ let v = velocity;+ const out = [{t: 0, value: x, velocity: v}];+ const steps = Math.round(until / dt);+ for (let i = 1; i <= steps; i++) {+ const time = (i - 1) * dt;+ const k1x = v;+ const k1v = accel(time, x, v);+ const k2x = v + (dt / 2) * k1v;+ const k2v = accel(time + dt / 2, x + (dt / 2) * k1x, v + (dt / 2) * k1v);+ const k3x = v + (dt / 2) * k2v;+ const k3v = accel(time + dt / 2, x + (dt / 2) * k2x, v + (dt / 2) * k2v);+ const k4x = v + dt * k3v;+ const k4v = accel(time + dt, x + dt * k3x, v + dt * k3v);+ x += (dt / 6) * (k1x + 2 * k2x + 2 * k3x + k4x);+ v += (dt / 6) * (k1v + 2 * k2v + 2 * k3v + k4v);+ if (i % 100 === 0) {+ out.push({t: i * dt, value: x, velocity: v});+ }+ }+ return out;+ }++ it.each([+ {+ name: 'underdamped',+ spring: springFromResponse({response: 0.32, dampingRatio: 0.8}),+ slope: 0.16,+ },+ {+ name: 'critically damped',+ spring: springFromResponse({response: 0.3, dampingRatio: 1}),+ slope: -40,+ },+ {+ name: 'overdamped',+ spring: springFromPhysics({+ stiffness: 100,+ damping: 40,+ allowOverdamping: true,+ }),+ slope: 250,+ },+ ])('matches an RK4 integration ($name)', ({spring, slope}) => {+ const start = {from: 1, velocity: 0.5, target: 1.02, slope};+ const curve = solveSpringTowardRamp(spring, start);+ const scale = Math.max(1, Math.abs(slope));+ for (const sample of rk4Ramp(spring, start, 1.5)) {+ expect(Math.abs(curve.value(sample.t) - sample.value)).toBeLessThan(+ 1e-7 * scale,+ );+ expect(Math.abs(curve.velocity(sample.t) - sample.velocity)).toBeLessThan(+ 1e-6 * scale,+ );+ }+ });++ it('starts where it is told and settles lag behind, at the target\u2019s speed', () => {+ const spring = springFromResponse({response: 0.3, dampingRatio: 1});+ const curve = solveSpringTowardRamp(spring, {+ from: 0,+ velocity: 2,+ target: 0,+ slope: 10,+ });+ expect(curve.value(0)).toBeCloseTo(0, 12);+ expect(curve.velocity(0)).toBeCloseTo(2, 12);+ expect(curve.lag).toBeCloseTo((spring.damping * 10) / spring.stiffness, 12);+ expect(curve.value(5) - (10 * 5 - curve.lag)).toBeCloseTo(0, 6);+ expect(curve.velocity(5)).toBeCloseTo(10, 6);+ });++ it('with no slope it is the ordinary spring', () => {+ const spring = springFromResponse({response: 0.35, dampingRatio: 0.85});+ const ramp = solveSpringTowardRamp(spring, {+ from: 0,+ velocity: 3,+ target: 1,+ slope: 0,+ });+ const plain = solveSpring(spring, {from: 0, to: 1, velocity: 3});+ for (let t = 0; t <= 1; t += 0.05) {+ expect(ramp.value(t)).toBeCloseTo(plain.value(t), 12);+ expect(ramp.velocity(t)).toBeCloseTo(plain.velocity(t), 12);+ }+ });+});++describe('conversions', () => {+ it('(duration, bounce) follows the WWDC23 equations', () => {+ // stiffness = (2π ÷ duration)², damping = (1 − bounce) × 4π ÷ duration.+ const bouncy = springFromDurationBounce({duration: 0.5, bounce: 0.3});+ expect(bouncy.mass).toBe(1);+ expect(bouncy.stiffness).toBeCloseTo(((2 * Math.PI) / 0.5) ** 2, 9);+ expect(bouncy.damping).toBeCloseTo((0.7 * 4 * Math.PI) / 0.5, 9);+ // damping = 4π ÷ (duration × (1 + bounce)) for negative bounce.+ const flattened = springFromDurationBounce({duration: 0.4, bounce: -0.5});+ expect(flattened.damping).toBeCloseTo((4 * Math.PI) / (0.4 * 0.5), 9);+ expect(dampingRatioOf(flattened)).toBeCloseTo(2, 9);+ });++ it('round-trips (duration, bounce) over the whole range', () => {+ for (const duration of [0.15, 0.3, 0.5, 0.75, 1.2]) {+ for (const bounce of [-0.9, -0.5, -0.1, 0, 0.15, 0.3, 0.6, 0.95, 1]) {+ const back = durationBounceOf(+ springFromDurationBounce({duration, bounce}),+ );+ expect(back.duration).toBeCloseTo(duration, 9);+ expect(back.bounce).toBeCloseTo(bounce, 9);+ }+ }+ });++ it('SwiftUI presets map to their damping ratios (smooth 0, snappy 0.15, bouncy 0.3)', () => {+ expect(+ dampingRatioOf(springFromDurationBounce({duration: 0.5, bounce: 0})),+ ).toBeCloseTo(1, 12);+ expect(+ dampingRatioOf(springFromDurationBounce({duration: 0.5, bounce: 0.15})),+ ).toBeCloseTo(0.85, 12);+ expect(+ dampingRatioOf(springFromDurationBounce({duration: 0.5, bounce: 0.3})),+ ).toBeCloseTo(0.7, 12);+ });++ it('(response, dampingRatio) reproduces WebKit\u2019s UIKit-matched switch springs exactly', () => {+ // Source/WebCore/rendering/cocoa/RenderThemeCocoa.mm:+ // SpringSolver(1.0, 438.64908449286042, 31.415926535897931, 0.0) and+ // SpringSolver(1.0, 322.27279677026473, 31.2364069556928, 0.0).+ const move = springFromResponse({response: 0.3, dampingRatio: 0.75});+ expect(move.stiffness).toBeCloseTo(438.64908449286042, 9);+ expect(move.damping).toBeCloseTo(31.415926535897931, 9);+ const press = springFromResponse({response: 0.35, dampingRatio: 0.87});+ expect(press.stiffness).toBeCloseTo(322.27279677026473, 9);+ expect(press.damping).toBeCloseTo(31.2364069556928, 9);+ });++ it('round-trips (response, dampingRatio) and physics', () => {+ const spring = springFromPhysics({mass: 2, stiffness: 300, damping: 20});+ const {response, dampingRatio} = responseDampingOf(spring);+ expect(response).toBeCloseTo((2 * Math.PI) / Math.sqrt(150), 12);+ expect(dampingRatio).toBeCloseTo(20 / (2 * Math.sqrt(600)), 12);+ // A different mass with the same ω₀ and ζ is the same motion.+ const unit = springFromResponse({response, dampingRatio});+ const a = solveSpring(spring, {from: 0, to: 1, velocity: 3});+ const b = solveSpring(unit, {from: 0, to: 1, velocity: 3});+ for (let t = 0; t < 1; t += 0.05) {+ expect(a.value(t)).toBeCloseTo(b.value(t), 9);+ }+ expect(responseOf(unit)).toBeCloseTo(response, 12);+ });++ it('treats an overdamped physics spring as critical unless allowed (SwiftUI, UIKit)', () => {+ const clamped = springFromPhysics({stiffness: 100, damping: 50});+ expect(dampingRatioOf(clamped)).toBeCloseTo(1, 12);+ const kept = springFromPhysics({+ stiffness: 100,+ damping: 50,+ allowOverdamping: true,+ });+ expect(dampingRatioOf(kept)).toBeCloseTo(2.5, 12);+ });++ it('rejects impossible parameters', () => {+ expect(() => springFromDurationBounce({duration: 0, bounce: 0})).toThrow(+ RangeError,+ );+ expect(() => springFromResponse({response: -1, dampingRatio: 1})).toThrow(+ RangeError,+ );+ expect(() => springFromPhysics({stiffness: 100, damping: -1})).toThrow(+ RangeError,+ );+ expect(() =>+ springFromPhysics({mass: 0, stiffness: 100, damping: 1}),+ ).toThrow(RangeError);+ });++ it('relative velocity follows UIKit\u2019s documented example', () => {+ // "if the total animation distance is 200 points and you want the start+ // of the animation to match a view velocity of 100 pt/s, use 0.5"+ expect(relativeVelocity(100, 0, 200)).toBe(0.5);+ expect(absoluteVelocity(0.5, 0, 200)).toBe(100);+ expect(relativeVelocity(-100, 300, 100)).toBe(0.5);+ });+});++describe('settlingDuration (CASpringAnimation semantics)', () => {+ it('matches Apple\u2019s CASpringAnimation documentation example', () => {+ // mass 1, stiffness 100: damping 5 → "approximately 2.85 seconds";+ // damping 15 → "just over 1 second".+ const loose = settlingDuration(+ springFromPhysics({stiffness: 100, damping: 5}),+ );+ expect(loose).toBeGreaterThan(2.845);+ expect(loose).toBeLessThan(2.865);+ const tight = settlingDuration(+ springFromPhysics({stiffness: 100, damping: 15}),+ );+ expect(tight).toBeGreaterThan(1);+ expect(tight).toBeLessThan(1.05);+ });++ it('matches WebKit\u2019s iOS switch durations, the settling durations of its springs', () => {+ // Source/WebCore/rendering/ios/RenderThemeIOS.h:+ // switchAnimationVisuallyOnDuration 0.4880138408543766_s,+ // switchAnimationHeldDuration 0.5073965509413827_s.+ expect(+ settlingDuration(springFromResponse({response: 0.3, dampingRatio: 0.75})),+ ).toBeCloseTo(0.4880138408543766, 9);+ expect(+ settlingDuration(+ springFromResponse({response: 0.35, dampingRatio: 0.87}),+ ),+ ).toBeCloseTo(0.5073965509413827, 9);+ });++ it('is shorter for a stiffer or a better-damped spring, as documented', () => {+ const base = settlingDuration(+ springFromPhysics({stiffness: 100, damping: 10}),+ );+ expect(+ settlingDuration(springFromPhysics({stiffness: 200, damping: 10})),+ ).toBeLessThan(base);+ expect(+ settlingDuration(springFromPhysics({stiffness: 100, damping: 15})),+ ).toBeLessThan(base);+ expect(+ settlingDuration(+ springFromPhysics({mass: 2, stiffness: 100, damping: 10}),+ ),+ ).toBeGreaterThan(base);+ });++ it('a critically damped unit move settles at (1 + u)·e^(−u) = ε', () => {+ const spring = springFromResponse({response: 0.5, dampingRatio: 1});+ const omega = (2 * Math.PI) / 0.5;+ const u = settlingDuration(spring) * omega;+ expect((1 + u) * Math.exp(-u)).toBeCloseTo(0.001, 9);+ });++ it('accounts for the initial velocity', () => {+ const spring = springFromResponse({response: 0.5, dampingRatio: 0.8});+ const still = settlingDuration(spring);+ // Moving away from the target, or toward it hard enough to overshoot+ // further, settles later; a velocity close to the spring's own natural+ // start (here ζ·ω₀ ≈ 10 distances/s) shrinks the oscillation instead.+ expect(settlingDuration(spring, {initialVelocity: -8})).toBeGreaterThan(+ still,+ );+ expect(settlingDuration(spring, {initialVelocity: 40})).toBeGreaterThan(+ still,+ );+ expect(settlingDuration(spring, {initialVelocity: 8})).toBeLessThan(still);+ });+});++// Read from UIKit on the iOS 26.2 simulator (UIKit lab, injected host app,+// iPhone 17 Pro, Oct 23 2026): CASpringAnimation.settlingDuration for mass 1,+// stiffness 100, and the duration UIKit gives UIView.animate(springDuration:+// bounce:initialSpringVelocity:).+const CA_SETTLING = [+ {damping: 5, velocity: 0, settling: 2.854974609888761},+ {damping: 5, velocity: 5, settling: 2.854974609888761},+ {damping: 5, velocity: -5, settling: 2.992531378997136},+ {damping: 10, velocity: 0, settling: 1.4727003346780927},+ {damping: 10, velocity: 5, settling: 1.3815510557964277},+ {damping: 10, velocity: -5, settling: 1.5350814063145797},+ {damping: 15, velocity: 0, settling: 1.0220937981854987},+ {damping: 15, velocity: 5, settling: 0.9637816892907282},+ {damping: 15, velocity: -5, settling: 1.0625267085113923},+];+const UIKIT_SPRING_DURATION = [+ {duration: 0.3, bounce: 0, velocity: 0, uikit: 0.4409405178437803},+ {duration: 0.3, bounce: 0, velocity: 2, uikit: 0.43617534275714415},+ {duration: 0.3, bounce: 0.15, velocity: 0, uikit: 0.4419904194536484},+ {duration: 0.3, bounce: 0.15, velocity: 2, uikit: 0.4379526271453696},+ {duration: 0.3, bounce: 0.3, velocity: 0, uikit: 0.5177731699046524},+ {duration: 0.5, bounce: 0, velocity: 0, uikit: 0.734900863},+ {duration: 0.5, bounce: 0.15, velocity: 0, uikit: 0.736650699089414},+ {duration: 0.5, bounce: 0.3, velocity: 2, uikit: 0.8493819071116907},+ {duration: 1, bounce: 0, velocity: 0, uikit: 1.469801726},+ {duration: 1, bounce: 0, velocity: 2, uikit: 1.410252226},+ {duration: 1, bounce: 0.15, velocity: 2, uikit: 1.4240715395795775},+ {duration: 1, bounce: 0.3, velocity: 0, uikit: 1.725910566348841},+];++describe('settlingDuration against values read from UIKit', () => {+ it.each(CA_SETTLING)(+ 'CASpringAnimation(stiffness 100, damping $damping, v $velocity).settlingDuration',+ ({damping, velocity, settling}) => {+ const spring = springFromPhysics({stiffness: 100, damping});+ expect(settlingDuration(spring, {initialVelocity: velocity})).toBeCloseTo(+ settling,+ 12,+ );+ },+ );++ it.each(UIKIT_SPRING_DURATION)(+ 'UIView.animate(springDuration: $duration, bounce: $bounce, v $velocity) runs $uikit s',+ ({duration, bounce, velocity, uikit}) => {+ const spring = springFromDurationBounce({duration, bounce});+ const mine = settlingDuration(spring, {initialVelocity: velocity});+ if (bounce > 0) {+ expect(mine).toBeCloseTo(uikit, 12);+ } else {+ // Critically damped: UIKit stops 0.0016 later in ω₀·t.+ expect(Math.abs(mine - uikit) / uikit).toBeLessThan(3e-4);+ }+ },+ );++ it('UIKit’s default spring runs 0.505824 s: overdamping clamped to critical', () => {+ const spring = springFromPhysics({mass: 3, stiffness: 1000, damping: 500});+ expect(dampingRatioOf(spring)).toBeCloseTo(1, 12);+ expect(+ Math.abs(settlingDuration(spring) - 0.505824) / 0.505824,+ ).toBeLessThan(3e-4);+ });+});++describe('springFromUIKitDampingDuration (legacy damping/duration API)', () => {+ // Read from UIKit (same capture): UIView.animate(withDuration: D,+ // usingSpringWithDamping: ζ, initialSpringVelocity: 0) → mass 1 and these.+ it.each([+ {duration: 0.3, dampingRatio: 0.5, stiffness: 1796.883, damping: 42.3897},+ {duration: 0.3, dampingRatio: 0.8, stiffness: 898.86, damping: 47.9696},+ {duration: 0.3, dampingRatio: 1, stiffness: 947.288, damping: 61.5561},+ {duration: 0.5, dampingRatio: 0.5, stiffness: 646.878, damping: 25.4338},+ {duration: 0.5, dampingRatio: 0.8, stiffness: 323.589, damping: 28.7817},+ {duration: 0.5, dampingRatio: 1, stiffness: 341.024, damping: 36.9337},+ {duration: 1, dampingRatio: 0.5, stiffness: 161.72, damping: 12.7169},+ {duration: 1, dampingRatio: 0.8, stiffness: 80.897, damping: 14.3909},+ {duration: 1, dampingRatio: 1, stiffness: 85.256, damping: 18.4668},+ ])(+ 'D $duration, ζ $dampingRatio → stiffness $stiffness',+ ({duration, dampingRatio, stiffness, damping}) => {+ const spring = springFromUIKitDampingDuration({duration, dampingRatio});+ expect(spring.mass).toBe(1);+ expect(Math.abs(spring.stiffness - stiffness) / stiffness).toBeLessThan(+ 1e-4,+ );+ expect(Math.abs(spring.damping - damping) / damping).toBeLessThan(1e-4);+ },+ );++ it('at ζ 1 the derived spring settles exactly at the duration', () => {+ const spring = springFromUIKitDampingDuration({+ duration: 0.4,+ dampingRatio: 1,+ });+ expect(settlingDuration(spring)).toBeCloseTo(0.4, 3);+ });++ it.each([+ {dampingRatio: 0.1, omega: 46.1019536228216},+ {dampingRatio: 0.3, omega: 19.1698},+ {dampingRatio: 0.65, omega: 10.3869},+ {dampingRatio: 0.95, omega: 8.4425},+ ])(+ 'reproduces the wide read at D 1, ζ $dampingRatio',+ ({dampingRatio, omega}) => {+ const spring = springFromUIKitDampingDuration({+ duration: 1,+ dampingRatio,+ });+ expect(Math.sqrt(spring.stiffness)).toBeCloseTo(omega, 3);+ },+ );++ it('interpolates between the measured ratios', () => {+ const a = springFromUIKitDampingDuration({duration: 1, dampingRatio: 0.6});+ const b = springFromUIKitDampingDuration({+ duration: 1,+ dampingRatio: 0.625,+ });+ const c = springFromUIKitDampingDuration({duration: 1, dampingRatio: 0.65});+ expect(Math.sqrt(b.stiffness)).toBeCloseTo(+ (Math.sqrt(a.stiffness) + Math.sqrt(c.stiffness)) / 2,+ 9,+ );+ });+});diff --git a/packages/core/src/motion/spring.ts b/packages/core/src/motion/spring.tsnew file mode 100644index 0000000000..bfd5fa91c9--- /dev/null+++ b/packages/core/src/motion/spring.ts@@ -0,0 +1,551 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file spring.ts+ * @input Spring parameters in any of the four vocabularies Apple uses+ * @output Exports the `Spring` model, conversions between SwiftUI+ * (duration, bounce), SwiftUI/WWDC (response, damping ratio),+ * CASpringAnimation (mass, stiffness, damping) and UIKit's legacy+ * `usingSpringWithDamping:initialSpringVelocity:` parameters, the closed-form+ * solution of the spring (`solveSpring`) and of a spring chasing a target+ * that moves at a constant speed (`solveSpringTowardRamp`), and+ * `settlingDuration`+ * @position Pure math under the motion animator; no DOM, no React+ *+ * One model, the damped harmonic oscillator m·x″ + c·x′ + k·x = 0, solved in+ * closed form for its three regimes (under-, critically and over-damped). It+ * is the model behind SwiftUI's `Spring`, `CASpringAnimation` and UIKit's+ * spring timing parameters, so a curve computed here is the curve UIKit+ * computes for the same parameters.+ *+ * Units: time in seconds, velocity in units per second (the units of the+ * animated value: px for a translation, 1 for a scale or an opacity), the+ * same units SwiftUI and Core Animation use.+ *+ * Conversions, with their sources:+ * - (duration, bounce) → (mass, stiffness, damping): the three equations of+ * WWDC23 "Animate with springs" (session 10158):+ * mass = 1, stiffness = (2π ÷ duration)²,+ * damping = (1 − bounce) × 4π ÷ duration for bounce ≥ 0,+ * damping = 4π ÷ (duration × (1 + bounce)) for bounce < 0.+ * - (response, dampingRatio) → physics: WWDC18 "Designing Fluid Interfaces"+ * (session 803) defines the response as the period of the undamped spring,+ * so ω₀ = 2π ÷ response; damping ratio ζ = c ÷ (2·√(k·m)) as stated in+ * https://developer.apple.com/documentation/uikit/uispringtimingparameters/init(mass:stiffness:damping:initialvelocity:)+ * - UIKit's relative initial velocity: "A value of 1 corresponds to the total+ * animation distance traversed in one second"+ * (https://developer.apple.com/documentation/uikit/uiview/animate(withduration:delay:usingspringwithdamping:initialspringvelocity:options:animations:completion:)).+ *+ * Settling duration follows UIKit's own duration solver: the time after which+ * the displacement from the target, for a unit move, stays below ε = 0.001+ * (the epsilon SwiftUI documents for `Spring.settlingDuration`). Underdamped,+ * it is the closed-form time at which the decaying envelope |A| + |B| of+ * A·cos + B·sin falls to ε; critically damped and overdamped, the root of the+ * envelope found numerically. Read from UIKit on the iOS 26.2 simulator, the+ * underdamped values match to the last digit (`CASpringAnimation`+ * `settlingDuration` for every stiffness/damping/velocity in the grid, and the+ * duration UIKit gives `UIView.animate(springDuration:bounce:)`); critically+ * damped ones land within 0.02 % of the duration UIKit picks (it stops 0.0016+ * later in ω₀·t). Core Animation's `settlingDuration` PROPERTY additionally+ * rounds critically damped and overdamped springs up to the next 0.1 s; that+ * rounding is not modeled. Nor is Core Animation's overdamped rendering: with+ * `allowsOverdamping` on (only `UIView.animate(springDuration:bounce:)` with a+ * negative bounce turns it on) Core Animation swaps the two exponentials'+ * coefficients and flips the initial velocity's sign, so its "overdamped"+ * curve overshoots (stiffness 100, damping 40: 104.5 % at 200 ms); every other+ * UIKit spring has it off and is clamped to critical, as `springFromPhysics`+ * does. The bound also reproduces Apple's+ * CASpringAnimation documentation example (stiffness 100, damping 5 →+ * "approximately 2.85 seconds"; damping 15 → "just over 1 second") and+ * WebKit's iOS switch durations, the settling durations of its UIKit-matched+ * springs (0.4880138408543766 s and 0.5073965509413827 s in+ * Source/WebCore/rendering/ios/RenderThemeIOS.h). See spring.test.ts.+ *+ * SYNC: When modified, update:+ * - /packages/core/src/motion/spring.test.ts+ * - /packages/core/src/motion/README.md+ */++const TAU = 2 * Math.PI;++/**+ * A spring, in Core Animation's physical vocabulary. Every other way of+ * describing a spring converts to this one.+ */+export interface Spring {+ /** Mass m of the attached object (`CASpringAnimation.mass`). */+ readonly mass: number;+ /** Stiffness k (`CASpringAnimation.stiffness`). */+ readonly stiffness: number;+ /** Viscous damping coefficient c (`CASpringAnimation.damping`). */+ readonly damping: number;+}++/** SwiftUI's two-parameter description: `Spring(duration:bounce:)`. */+export interface DurationBounce {+ /**+ * Perceptual duration in seconds: the period of the undamped spring, "the+ * pace of the spring".+ */+ readonly duration: number;+ /**+ * 0 is critically damped (no overshoot), up to 1 (undamped oscillation);+ * negative values, down to −1, are overdamped ("flattened") springs.+ */+ readonly bounce: number;+}++/** WWDC18's design-friendly description: response and damping ratio. */+export interface ResponseDamping {+ /** Period of the undamped spring in seconds. */+ readonly response: number;+ /**+ * Damping as a fraction of critical damping (SwiftUI's `dampingFraction`):+ * 1 settles without overshoot, values toward 0 oscillate longer.+ */+ readonly dampingRatio: number;+}++function assertPositiveFinite(name: string, value: number): void {+ if (!(Number.isFinite(value) && value > 0)) {+ throw new RangeError(+ `spring: ${name} must be a positive number, got ${value}`,+ );+ }+}++/**+ * SwiftUI's `Spring(duration:bounce:)` and UIKit's+ * `UIView.animate(springDuration:bounce:…)`: the WWDC23 equations. Bounce is+ * clamped to SwiftUI's documented range (−1, 1].+ *+ * @example+ * ```+ * springFromDurationBounce({duration: 0.5, bounce: 0}); // SwiftUI .smooth+ * ```+ */+export function springFromDurationBounce({+ duration,+ bounce,+}: DurationBounce): Spring {+ assertPositiveFinite('duration', duration);+ if (!Number.isFinite(bounce)) {+ throw new RangeError(`spring: bounce must be finite, got ${bounce}`);+ }+ // −1 itself would be infinite damping.+ const b = Math.min(1, Math.max(-0.999999, bounce));+ const stiffness = (TAU / duration) ** 2;+ const damping =+ b >= 0 ? ((1 - b) * 2 * TAU) / duration : (2 * TAU) / (duration * (1 + b));+ return {mass: 1, stiffness, damping};+}++/**+ * SwiftUI's `Spring(response:dampingRatio:)` and+ * `Animation.spring(response:dampingFraction:)`. Overdamping (ratio > 1) is+ * kept, as SwiftUI keeps it for this initializer.+ */+export function springFromResponse({+ response,+ dampingRatio,+}: ResponseDamping): Spring {+ assertPositiveFinite('response', response);+ if (!(Number.isFinite(dampingRatio) && dampingRatio >= 0)) {+ throw new RangeError(+ `spring: dampingRatio must be ≥ 0, got ${dampingRatio}`,+ );+ }+ const omega = TAU / response;+ return {mass: 1, stiffness: omega * omega, damping: 2 * dampingRatio * omega};+}++/**+ * `CASpringAnimation` / `UISpringTimingParameters(mass:stiffness:damping:)`+ * / SwiftUI `Spring(mass:stiffness:damping:allowOverDamping:)`. Like SwiftUI,+ * an overdamped spring is treated as critically damped unless+ * `allowOverdamping` is set: "a value of false specifies that such cases+ * should instead be treated as critically damped".+ */+export function springFromPhysics({+ mass = 1,+ stiffness,+ damping,+ allowOverdamping = false,+}: {+ mass?: number;+ stiffness: number;+ damping: number;+ allowOverdamping?: boolean;+}): Spring {+ assertPositiveFinite('mass', mass);+ assertPositiveFinite('stiffness', stiffness);+ if (!(Number.isFinite(damping) && damping >= 0)) {+ throw new RangeError(`spring: damping must be ≥ 0, got ${damping}`);+ }+ const critical = 2 * Math.sqrt(stiffness * mass);+ return {+ mass,+ stiffness,+ damping: allowOverdamping ? damping : Math.min(damping, critical),+ };+}++/** Undamped angular frequency ω₀ = √(k/m), rad/s. */+export function naturalFrequency(spring: Spring): number {+ return Math.sqrt(spring.stiffness / spring.mass);+}++/** Damping ratio ζ = c / (2·√(k·m)). */+export function dampingRatioOf(spring: Spring): number {+ return spring.damping / (2 * Math.sqrt(spring.stiffness * spring.mass));+}++/** Response (period of the undamped spring), seconds. */+export function responseOf(spring: Spring): number {+ return TAU / naturalFrequency(spring);+}++/** The spring as SwiftUI's (duration, bounce), inverting the WWDC23 equations. */+export function durationBounceOf(spring: Spring): DurationBounce {+ const zeta = dampingRatioOf(spring);+ return {+ duration: responseOf(spring),+ bounce: zeta <= 1 ? 1 - zeta : 1 / zeta - 1,+ };+}++/** The spring as (response, dampingRatio). */+export function responseDampingOf(spring: Spring): ResponseDamping {+ return {response: responseOf(spring), dampingRatio: dampingRatioOf(spring)};+}++/**+ * A spring in any of the vocabularies the constants table uses: physical+ * (mass, stiffness, damping), SwiftUI (duration, bounce) or WWDC18+ * (response, dampingRatio). Tables keep the vocabulary of their source so a+ * value reads exactly as it was published.+ */+export type SpringDescription =+ | {+ readonly mass?: number;+ readonly stiffness: number;+ readonly damping: number;+ }+ | DurationBounce+ | ResponseDamping;++/**+ * Normalizes a description to the physical `Spring`. A physical description+ * gets `springFromPhysics`' treatment: overdamping is clamped to critical, as+ * SwiftUI and Core Animation do by default.+ */+export function toSpring(description: SpringDescription): Spring {+ if ('stiffness' in description) {+ return springFromPhysics(description);+ }+ if ('bounce' in description) {+ return springFromDurationBounce(description);+ }+ return springFromResponse(description);+}++/**+ * UIKit's relative initial spring velocity for a move from `from` to `to`+ * at `velocity` units/s: 1 means the whole distance in one second. Undefined+ * (±Infinity) when `from === to`; animate in absolute units instead+ * (`solveSpring` takes an absolute velocity).+ */+export function relativeVelocity(+ velocity: number,+ from: number,+ to: number,+): number {+ return velocity / (to - from);+}++/** Inverse of `relativeVelocity`: absolute units/s. */+export function absoluteVelocity(+ relative: number,+ from: number,+ to: number,+): number {+ return relative * (to - from);+}++/** A spring released from a value with a velocity, heading for a target. */+export interface SpringCurve {+ readonly spring: Spring;+ readonly from: number;+ readonly to: number;+ /** Initial velocity, units/s. */+ readonly initialVelocity: number;+ /** Value at `t` seconds after release. */+ value(t: number): number;+ /** Velocity at `t` seconds after release, units/s. */+ velocity(t: number): number;+ /**+ * The time after which |value(t) − to| stays below `threshold` (in the+ * value's own units) for good: the envelope bound used by+ * `settlingDuration`, applied in absolute units. 0 when already within.+ * Infinity for an undamped spring that is displaced or moving.+ */+ settleTime(threshold: number): number;+}++// |ζ − 1| below this is solved as critically damped: the under/overdamped+// forms lose precision as ωd or the root gap goes to zero, and the critical+// form differs from them by O(|ζ − 1|) there.+const CRITICAL_TOLERANCE = 1e-6;++/**+ * Closed-form solution of the spring released at `from` with+ * `initialVelocity` (units/s), heading for `to`.+ *+ * @example+ * ```+ * const curve = solveSpring(springFromDurationBounce({duration: 0.5, bounce: 0}), {from: 0, to: 300});+ * curve.value(0.1); // px after 100 ms+ * ```+ */+export function solveSpring(+ spring: Spring,+ {+ from,+ to,+ velocity: initialVelocity = 0,+ }: {from: number; to: number; velocity?: number},+): SpringCurve {+ const omega0 = naturalFrequency(spring);+ const zeta = dampingRatioOf(spring);+ // Displacement from the target; the ODE is solved for x(t) = value − to.+ const x0 = from - to;+ const v0 = initialVelocity;+ let displacement: (t: number) => number;+ let speed: (t: number) => number;+ let envelope: (t: number) => number;+ // Where the envelope peaks (critically damped only; elsewhere 0).+ let envelopePeak = 0;++ if (zeta < 1 - CRITICAL_TOLERANCE) {+ const decay = zeta * omega0;+ const omegaD = omega0 * Math.sqrt(1 - zeta * zeta);+ const a = x0;+ const b = (v0 + decay * x0) / omegaD;+ const bv = (decay * v0 + omega0 * omega0 * x0) / omegaD;+ displacement = t =>+ Math.exp(-decay * t) *+ (a * Math.cos(omegaD * t) + b * Math.sin(omegaD * t));+ speed = t =>+ Math.exp(-decay * t) *+ (v0 * Math.cos(omegaD * t) - bv * Math.sin(omegaD * t));+ const amplitude = Math.abs(a) + Math.abs(b);+ envelope = t => amplitude * Math.exp(-decay * t);+ } else if (zeta <= 1 + CRITICAL_TOLERANCE) {+ const b = v0 + omega0 * x0;+ displacement = t => (x0 + b * t) * Math.exp(-omega0 * t);+ speed = t => (v0 - omega0 * b * t) * Math.exp(-omega0 * t);+ const absA = Math.abs(x0);+ const absB = Math.abs(b);+ envelope = t => (absA + absB * t) * Math.exp(-omega0 * t);+ // (|A| + |B|·t)·e^(−ω₀t) rises until t = 1/ω₀ − |A|/|B|, then decays.+ envelopePeak = absB > 0 ? Math.max(0, 1 / omega0 - absA / absB) : 0;+ } else {+ const root = omega0 * Math.sqrt(zeta * zeta - 1);+ const r1 = -zeta * omega0 + root; // slow root+ const r2 = -zeta * omega0 - root; // fast root+ const c1 = (v0 - r2 * x0) / (r1 - r2);+ const c2 = x0 - c1;+ displacement = t => c1 * Math.exp(r1 * t) + c2 * Math.exp(r2 * t);+ speed = t => r1 * c1 * Math.exp(r1 * t) + r2 * c2 * Math.exp(r2 * t);+ const absC1 = Math.abs(c1);+ const absC2 = Math.abs(c2);+ envelope = t => absC1 * Math.exp(r1 * t) + absC2 * Math.exp(r2 * t);+ }++ const settleTime = (threshold: number): number => {+ if (!(threshold > 0)) {+ return Infinity;+ }+ if (zeta === 0) {+ return x0 === 0 && v0 === 0 ? 0 : Infinity;+ }+ const start = envelopePeak;+ if (envelope(start) <= threshold) {+ // `start` is where the bound peaks (0 when it only decays), so the+ // bound is within the threshold everywhere.+ return 0;+ }+ if (zeta < 1 - CRITICAL_TOLERANCE) {+ // Closed form: amplitude · e^(−ζω₀t) = threshold.+ const amplitude = envelope(0);+ return Math.log(amplitude / threshold) / (zeta * omega0);+ }+ // Monotone decreasing after `start`: bracket, then bisect.+ let lo = start;+ let hi = Math.max(start, 1 / omega0);+ while (envelope(hi) > threshold) {+ lo = hi;+ hi *= 2;+ if (hi > 1e6) {+ return Infinity;+ }+ }+ for (let i = 0; i < 100 && hi - lo > 1e-12; i++) {+ const mid = (lo + hi) / 2;+ if (envelope(mid) > threshold) {+ lo = mid;+ } else {+ hi = mid;+ }+ }+ return hi;+ };++ return {+ spring,+ from,+ to,+ initialVelocity,+ value: t => to + displacement(t),+ velocity: t => speed(t),+ settleTime,+ };+}++/** A spring chasing a target that moves at a constant speed. */+export interface SpringRampCurve {+ readonly spring: Spring;+ /** Value at `t` seconds after the start. */+ value(t: number): number;+ /** Velocity at `t` seconds after the start, units/s. */+ velocity(t: number): number;+ /**+ * How far behind the moving target the spring settles: c·slope ÷ k+ * (it then moves at the target's speed).+ */+ readonly lag: number;+}++/**+ * A spring whose target moves at a constant speed, `target + slope · t`: the+ * "tracking" springs UIKit drives per frame (a press that keeps deepening, a+ * lift that follows the finger). Closed form: the spring settles `lag` behind+ * the moving target, and what is left is a free spring around that point,+ * solved by `solveSpring`. Chain pieces (a new slope, a fixed target) by+ * starting each from the previous piece's value and velocity.+ */+export function solveSpringTowardRamp(+ spring: Spring,+ {+ from,+ velocity: initialVelocity = 0,+ target,+ slope,+ }: {from: number; velocity?: number; target: number; slope: number},+): SpringRampCurve {+ const lag = (spring.damping * slope) / spring.stiffness;+ // x(t) = target + slope·t − lag + h(t), with h a free spring around 0.+ const free = solveSpring(spring, {+ from: from - target + lag,+ to: 0,+ velocity: initialVelocity - slope,+ });+ return {+ spring,+ lag,+ value: t => target + slope * t - lag + free.value(t),+ velocity: t => slope + free.velocity(t),+ };+}++/** Core Animation's settling epsilon (documented for SwiftUI's Spring). */+export const SETTLING_EPSILON = 0.001;++/**+ * `CASpringAnimation.settlingDuration` / SwiftUI `Spring.settlingDuration`:+ * seconds until a unit move (target 1) stays within `epsilon` of its target.+ * `initialVelocity` is UIKit's relative velocity (distance fractions per+ * second, positive toward the target), 0 by default as in SwiftUI.+ */+export function settlingDuration(+ spring: Spring,+ {+ initialVelocity = 0,+ epsilon = SETTLING_EPSILON,+ }: {initialVelocity?: number; epsilon?: number} = {},+): number {+ return solveSpring(spring, {+ from: 0,+ to: 1,+ velocity: initialVelocity,+ }).settleTime(epsilon);+}++/**+ * ω₀ · duration that UIKit's legacy spring derivation lands on, by damping+ * ratio, for a release at rest. Read from UIKit+ * (`UIView.animate(withDuration: 1, usingSpringWithDamping: ζ,+ * initialSpringVelocity: 0)`; `UIViewPropertyAnimator(duration:dampingRatio:)`+ * gives identical springs, and ω₀ scales as 1 ÷ duration): measured: UIKit+ * lab (injected host app), iOS 26.2 sim iPhone 17 Pro, CAAnimation read,+ * Oct 23 2026.+ */+const UIKIT_LEGACY_OMEGA_DURATION: ReadonlyArray<readonly [number, number]> = [+ [0.1, 46.102],+ [0.15, 33.4801],+ [0.2, 26.5936],+ [0.25, 22.2149],+ [0.3, 19.1698],+ [0.35, 16.9236],+ [0.4, 15.1966],+ [0.45, 13.8275],+ [0.5, 12.7169],+ [0.55, 11.8001],+ [0.6, 11.0335],+ [0.65, 10.3869],+ [0.7, 9.8396],+ [0.75, 9.3779],+ [0.8, 8.9943],+ [0.85, 8.6897],+ [0.9, 8.4808],+ [0.95, 8.4425],+ [1, 9.2334],+];++/**+ * UIKit's legacy `animate(withDuration:delay:usingSpringWithDamping:+ * initialSpringVelocity:…)`: the caller fixes the total duration and the+ * damping ratio, and UIKit derives the spring: mass 1, the given damping+ * ratio, and ω₀ = c(ζ) ÷ duration with c read from UIKit every 0.05 of ζ from+ * 0.1 to 1 (at ζ 1 the spring settles exactly at the duration). The animation+ * is cut at the duration.+ *+ * GUESS between the measured ratios (linear interpolation, within 0.05 of a+ * read) and below 0.1 (extrapolated as c ∝ 1 ÷ ζ). A non-zero initial+ * velocity shifts UIKit's root slightly, and at low ratios makes its solver+ * jump to a far smaller one (ζ 0.1, velocity 1 → ω₀·D 9.74); neither is+ * modeled. Measurement task M-K1.+ */+export function springFromUIKitDampingDuration({+ duration,+ dampingRatio,+}: {+ duration: number;+ dampingRatio: number;+}): Spring {+ assertPositiveFinite('duration', duration);+ // UIKit's ratio is clamped to (0, 1]: it has no overdamped springs.+ const zeta = Math.min(1, Math.max(1e-3, dampingRatio));+ const table = UIKIT_LEGACY_OMEGA_DURATION;+ let c = (table[0][1] * table[0][0]) / zeta;+ for (let i = 0; i + 1 < table.length; i++) {+ const [z0, c0] = table[i];+ const [z1, c1] = table[i + 1];+ if (zeta >= z0 && zeta <= z1) {+ c = c0 + ((c1 - c0) * (zeta - z0)) / (z1 - z0);+ break;+ }+ }+ const omega0 = c / duration;+ return {mass: 1, stiffness: omega0 * omega0, damping: 2 * zeta * omega0};+}diff --git a/packages/core/src/motion/uikit/gestures.ts b/packages/core/src/motion/uikit/gestures.tsindex 4e6963b375..6f6d410628 100644--- a/packages/core/src/motion/uikit/gestures.ts+++ b/packages/core/src/motion/uikit/gestures.ts@@ -253,8 +253,9 @@ export const UIKIT_VELOCITY = {* instantaneous velocity plus the rest times the previous event's* (instantaneous velocity: position change over timestamp change between* consecutive events, the touch-down counting as the first). The lift- * does not update it, and a finger at rest sends no events, so a release- * after a pause reports the last moving value.+ * does not update it, and a finger at rest sends no events, so UIKit+ * reports the last moving value after a pause; Astryx's release reads 0+ * once the finger has rested (`spec:AST-100` FR2).* @source measured: UIKit lab, iOS 26.2 simulator, ivar reads confirmed* with HID touches, Oct 23 2026: fitted to all 69 velocity(in:) values of* six HID streams (constant, accelerating, pauses before the lift) to 0.0diff --git a/packages/core/src/motion/uikit/timing.ts b/packages/core/src/motion/uikit/timing.tsindex c3c4c461d7..8ce8079df0 100644--- a/packages/core/src/motion/uikit/timing.ts+++ b/packages/core/src/motion/uikit/timing.ts@@ -54,6 +54,15 @@ export const press = {* packages/core/src/utils/pressGesture.ts, 2026-10-06)*/highlightOutMs: 200,+ /**+ * The highlight fade's curve after release: an ease-out that spends the+ * whole clock fading (strength about 0.2 at the midpoint).+ * @source GUESS — the release curve the touch press model ships with+ * (`RELEASE_EASE`, packages/core/src/utils/interactionOverlay.stylex.ts),+ * chosen to read as UIKit's deselect cross-fade, not read from UIKit+ * @measure M-PR1+ */+ highlightOutCurve: [0, 0, 0.2, 1],/*** A touch on a scroller that moved this recently brakes it instead of* pressing.diff --git a/packages/core/src/motion/uikit/values.test.ts b/packages/core/src/motion/uikit/values.test.tsnew file mode 100644index 0000000000..e64e09d3c9--- /dev/null+++ b/packages/core/src/motion/uikit/values.test.ts@@ -0,0 +1,110 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file values.test.ts+ * @input vitest, the UIKit constants table and the motion math+ * @output Checks the table's values through the math that plays them: every+ * spring is valid and settles; the alert spring is UIKit's legacy+ * derivation; a sheet's detent and presentation springs render alike;+ * scroll-to-top and the rubber band reproduce what UIKit was measured doing;+ * the press release curve is the press model's+ * @position Testing; the source rules are uikit.test.ts+ */++import {readFileSync} from 'node:fs';+import {join} from 'node:path';+import {describe, expect, it} from 'vitest';+import {solveDecay} from '../decay';+import {rubberBand} from '../rubberBand';+import {+ naturalFrequency,+ settlingDuration,+ springFromUIKitDampingDuration,+ toSpring,+ type SpringDescription,+} from '../spring';+import {scroll, springs} from '.';+import {press} from './timing';++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)(+ '%s is a valid spring that settles',+ (_, description) => {+ const spring = toSpring(description);+ const settle = settlingDuration(spring);+ expect(settle).toBeGreaterThan(0.05);+ expect(settle).toBeLessThan(2);+ },+ );++ it('the alert spring is UIKit\u2019s legacy derivation at 0.404 s, critically damped', () => {+ // UIKit asks for damping 600 (clamped to 1) over 0.404 s; the measured+ // grid predicts the spring Core Animation was handed.+ const derived = springFromUIKitDampingDuration({+ duration: 0.404,+ dampingRatio: 1,+ });+ expect(derived.stiffness).toBeCloseTo(springs.alertPresent.stiffness, 1);+ expect(derived.damping).toBeCloseTo(springs.alertPresent.damping, 2);+ });++ it('a sheet\u2019s detent spring is its presentation spring as rendered (critical, same pace)', () => {+ // Core Animation clamps UIKit\u2019s default spring to critical damping.+ expect(naturalFrequency(toSpring(springs.sheetDetent))).toBeCloseTo(+ naturalFrequency(toSpring(springs.sheetPresent)),+ 6,+ );+ });++ it('scroll-to-top as a decay lands on the top along the measured curve', () => {+ // 2000 pt from the top: remaining distance every ~50 ms after the start.+ const measured = [1257, 768, 475, 296, 186, 118];+ const coast = solveDecay({+ from: 0,+ velocity: 9.7 * 2000,+ rate: scroll.scrollToTopRate,+ });+ expect(coast.rest).toBeCloseTo(2000, -1);+ measured.forEach((remaining, i) => {+ expect(+ Math.abs(2000 - coast.value((i + 1) * 0.05) - remaining),+ ).toBeLessThan(30);+ });+ });++ it('the rubber band reproduces UIScrollView\u2019s released overscroll', () => {+ // Finger 100 / 300 / 600 pt past the edge of an 874 pt view, minus the+ // pan\u2019s 10 pt hysteresis.+ const cases: [number, number][] = [+ [90, 47],+ [290, 135],+ [590, 236.67],+ ];+ for (const [overflow, shown] of cases) {+ expect(+ Math.abs(+ rubberBand(overflow, 874, scroll.rubberBand.coefficient) - shown,+ ),+ ).toBeLessThan(0.5);+ }+ });++ it('the press release curve is the press model\u2019s RELEASE_EASE', () => {+ // The table records the curve the touch press model ships with; this pins+ // the two together so neither drifts alone.+ const source = readFileSync(+ join(__dirname, '../../utils/interactionOverlay.stylex.ts'),+ 'utf8',+ );+ const match = /const RELEASE_EASE = 'cubic-bezier\(([^)]*)\)'/.exec(source);+ expect(match?.[1].split(',').map(Number)).toEqual([+ ...press.highlightOutCurve,+ ]);+ });+});