@astryxdesign/core 0.7.5-canary.fccd771 → 0.7.5

package/dist/motion/bezier.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @file bezier.ts
+ * @input Cubic-bézier control points [x1, y1, x2, y2]
+ * @output Exports `cubicBezier`, the timing function CSS and Core Animation
+ *   define by those points (progress → eased progress)
+ * @position Pure math under the animator (the Reduced Motion cross-fade runs
+ *   on Core Animation's named curves); no DOM, no React
+ *
+ * The curve runs from (0, 0) to (1, 1) with the two given control points;
+ * x is time, y is progress. Solved for x by Newton's method with a bisection
+ * fallback, the approach browser engines use for CSS `cubic-bezier()`.
+ *
+ * SYNC: When modified, update /packages/core/src/motion/bezier.test.ts
+ */
+export type BezierPoints = readonly [number, number, number, number];
+/** The timing function for `points`: maps time progress to eased progress. */
+export declare function cubicBezier([x1, y1, x2, y2]: BezierPoints): (x: number) => number;
+//# sourceMappingURL=bezier.d.ts.map

package/dist/motion/bezier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bezier.d.ts","sourceRoot":"","sources":["../../src/motion/bezier.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AAEH,MAAM,MAAM,YAAY,GAAG,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;AAErE,8EAA8E;AAC9E,wBAAgB,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,YAAY,GAAG,CAC3D,CAAC,EAAE,MAAM,KACN,MAAM,CAyCV"}

package/dist/motion/bezier.js

@@ -0,0 +1,60 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file bezier.ts
+ * @input Cubic-bézier control points [x1, y1, x2, y2]
+ * @output Exports `cubicBezier`, the timing function CSS and Core Animation
+ *   define by those points (progress → eased progress)
+ * @position Pure math under the animator (the Reduced Motion cross-fade runs
+ *   on Core Animation's named curves); no DOM, no React
+ *
+ * The curve runs from (0, 0) to (1, 1) with the two given control points;
+ * x is time, y is progress. Solved for x by Newton's method with a bisection
+ * fallback, the approach browser engines use for CSS `cubic-bezier()`.
+ *
+ * SYNC: When modified, update /packages/core/src/motion/bezier.test.ts
+ */
+
+/** The timing function for `points`: maps time progress to eased progress. */
+export function cubicBezier([x1, y1, x2, y2]) {
+  const cx = 3 * x1;
+  const bx = 3 * (x2 - x1) - cx;
+  const ax = 1 - cx - bx;
+  const cy = 3 * y1;
+  const by = 3 * (y2 - y1) - cy;
+  const ay = 1 - cy - by;
+  const sampleX = t => ((ax * t + bx) * t + cx) * t;
+  const sampleY = t => ((ay * t + by) * t + cy) * t;
+  const slopeX = t => (3 * ax * t + 2 * bx) * t + cx;
+  const solveT = x => {
+    let t = x;
+    for (let i = 0; i < 8; i++) {
+      const error = sampleX(t) - x;
+      if (Math.abs(error) < 1e-7) {
+        return t;
+      }
+      const slope = slopeX(t);
+      if (Math.abs(slope) < 1e-6) {
+        break;
+      }
+      t -= error / slope;
+    }
+    let lo = 0;
+    let hi = 1;
+    t = x;
+    for (let i = 0; i < 60; i++) {
+      const value = sampleX(t);
+      if (Math.abs(value - x) < 1e-7) {
+        break;
+      }
+      if (value < x) {
+        lo = t;
+      } else {
+        hi = t;
+      }
+      t = (lo + hi) / 2;
+    }
+    return t;
+  };
+  return x => x <= 0 ? 0 : x >= 1 ? 1 : sampleY(solveT(x));
+}

package/dist/motion/coast.d.ts

@@ -0,0 +1,61 @@
+/**
+ * @file coast.ts
+ * @input An animator, release velocities, and optional edges, deceleration
+ *   rate and edge spring
+ * @output Exports `coast`: the momentum curves of a released scroll view
+ *   (UIScrollView's coast, handing its velocity to an edge spring at a bound)
+ *   for `Animator.decay` to play; and its `CoastOptions`
+ * @position Motion foundation, pure math over an animator's presentation
+ *   values. Only a surface that coasts imports it, so the coast math and the
+ *   scroll table stay out of every other caller of the animator.
+ *
+ * Each property starts at its presentation value (`animator.get`), so a coast
+ * continues whatever was running without a jump:
+ * - inside its bounds, it coasts at `rate` (decay.ts) and comes to rest where
+ *   it projects;
+ * - a coast that reaches an edge hands its velocity at the contact to the
+ *   edge spring, which settles on the edge;
+ * - released past an edge, it springs straight back with the release
+ *   velocity: a transition, not momentum, so under Reduce Motion `decay`
+ *   plays it as `animate` does, a cross-fade on a coarse pointer or after a
+ *   touch release (`touchRelease`) and at once on any other
+ *   (`design:reduced-motion` DR2, DR3);
+ * - at zero velocity inside its bounds, it rests where it is.
+ *
+ * SYNC: When modified, update coast.test.ts.
+ */
+import { type Animator, type MotionCurve } from './animator.js';
+import { type SpringDescription } from './spring.js';
+export interface CoastOptions {
+    /** Per-millisecond velocity factor; UIScrollView's normal rate by default. */
+    rate?: number;
+    /** Edges: a coast crossing one hands its velocity to `bounce`. */
+    bounds?: Partial<Record<'x' | 'y', {
+        min: number;
+        max: number;
+    }>>;
+    /** The edge spring; `scroll.bounce` by default. */
+    bounce?: SpringDescription;
+    /**
+     * The release time on the document timeline (ms, `performance.now()`
+     * clock); now by default. Pass the same `at` to `decay`.
+     */
+    at?: number;
+}
+/**
+ * The momentum curves of a release with `velocity` (px per second on each
+ * translate axis), for `animator.decay`, which moves only `x` and `y`:
+ * momentum continues a finger's throw (design:reduced-motion DR2).
+ *
+ * @example
+ * ```
+ * animator.decay(
+ *   coast(animator, {x: velocityX}, {bounds: {x: {min: -maxScroll, max: 0}}}),
+ * );
+ * ```
+ */
+export declare function coast(animator: Animator, velocity: {
+    readonly x?: number;
+    readonly y?: number;
+}, options?: CoastOptions): Partial<Record<'x' | 'y', MotionCurve>>;
+//# sourceMappingURL=coast.d.ts.map

package/dist/motion/coast.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coast.d.ts","sourceRoot":"","sources":["../../src/motion/coast.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAmB,KAAK,QAAQ,EAAE,KAAK,WAAW,EAAC,MAAM,YAAY,CAAC;AAE7E,OAAO,EAAwB,KAAK,iBAAiB,EAAC,MAAM,UAAU,CAAC;AAGvE,MAAM,WAAW,YAAY;IAC3B,8EAA8E;IAC9E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kEAAkE;IAClE,MAAM,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,GAAG,GAAG,GAAG,EAAE;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAC,CAAC,CAAC,CAAC;IAChE,mDAAmD;IACnD,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAC3B;;;OAGG;IACH,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AAgBD;;;;;;;;;;;GAWG;AACH,wBAAgB,KAAK,CACnB,QAAQ,EAAE,QAAQ,EAClB,QAAQ,EAAE;IAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,MAAM,CAAA;CAAC,EACpD,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,MAAM,CAAC,GAAG,GAAG,GAAG,EAAE,WAAW,CAAC,CAAC,CAuEzC"}

package/dist/motion/coast.js

@@ -0,0 +1,107 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file coast.ts
+ * @input An animator, release velocities, and optional edges, deceleration
+ *   rate and edge spring
+ * @output Exports `coast`: the momentum curves of a released scroll view
+ *   (UIScrollView's coast, handing its velocity to an edge spring at a bound)
+ *   for `Animator.decay` to play; and its `CoastOptions`
+ * @position Motion foundation, pure math over an animator's presentation
+ *   values. Only a surface that coasts imports it, so the coast math and the
+ *   scroll table stay out of every other caller of the animator.
+ *
+ * Each property starts at its presentation value (`animator.get`), so a coast
+ * continues whatever was running without a jump:
+ * - inside its bounds, it coasts at `rate` (decay.ts) and comes to rest where
+ *   it projects;
+ * - a coast that reaches an edge hands its velocity at the contact to the
+ *   edge spring, which settles on the edge;
+ * - released past an edge, it springs straight back with the release
+ *   velocity: a transition, not momentum, so under Reduce Motion `decay`
+ *   plays it as `animate` does, a cross-fade on a coarse pointer or after a
+ *   touch release (`touchRelease`) and at once on any other
+ *   (`design:reduced-motion` DR2, DR3);
+ * - at zero velocity inside its bounds, it rests where it is.
+ *
+ * SYNC: When modified, update coast.test.ts.
+ */
+
+import { SETTLE_THRESHOLD } from "./animator.js";
+import { solveDecay } from "./decay.js";
+import { solveSpring, toSpring } from "./spring.js";
+import { scroll } from "./uikit/scroll.js";
+/** A curve that holds `end` from `duration` on. */
+function settling(duration, end, at, velocity) {
+  return {
+    duration,
+    at: t => t >= duration ? end : at(t),
+    velocity: t => t >= duration ? 0 : velocity(t)
+  };
+}
+
+/**
+ * The momentum curves of a release with `velocity` (px per second on each
+ * translate axis), for `animator.decay`, which moves only `x` and `y`:
+ * momentum continues a finger's throw (design:reduced-motion DR2).
+ *
+ * @example
+ * ```
+ * animator.decay(
+ *   coast(animator, {x: velocityX}, {bounds: {x: {min: -maxScroll, max: 0}}}),
+ * );
+ * ```
+ */
+export function coast(animator, velocity, options = {}) {
+  const velocities = {};
+  for (const key of ['x', 'y']) {
+    const value = velocity[key];
+    if (value != null && Number.isFinite(value)) {
+      velocities[key] = value;
+    }
+  }
+  const rate = options.rate ?? scroll.decelerationRate.normal;
+  const bounce = toSpring(options.bounce ?? scroll.bounce);
+  const curves = {};
+  for (const [key, v0] of Object.entries(velocities)) {
+    const from = animator.get(key, options.at);
+    const bounds = options.bounds?.[key];
+    const threshold = SETTLE_THRESHOLD[key];
+    if (bounds != null && (from < bounds.min || from > bounds.max)) {
+      // Released past an edge: straight back with the release velocity.
+      const edge = from < bounds.min ? bounds.min : bounds.max;
+      const back = solveSpring(bounce, {
+        from,
+        to: edge,
+        velocity: v0
+      });
+      curves[key] = {
+        ...settling(back.settleTime(threshold), edge, t => back.value(t), t => back.velocity(t)),
+        // A spring the release starts, not momentum (Reduce Motion: DR2).
+        isTransition: true
+      };
+      continue;
+    }
+    const glide = solveDecay({
+      from,
+      velocity: v0,
+      rate
+    });
+    const edge = bounds == null ? null : glide.rest < bounds.min ? bounds.min : glide.rest > bounds.max ? bounds.max : null;
+    const hit = edge == null ? null : glide.timeToReach(edge);
+    if (edge != null && hit != null) {
+      // The coast reaches the edge: the edge spring takes its velocity.
+      const spring = solveSpring(bounce, {
+        from: edge,
+        to: edge,
+        velocity: glide.velocity(hit)
+      });
+      curves[key] = settling(hit + spring.settleTime(threshold), edge, t => t < hit ? glide.value(t) : spring.value(t - hit), t => t < hit ? glide.velocity(t) : spring.velocity(t - hit));
+    } else if (v0 === 0) {
+      curves[key] = settling(0, from, () => from, () => 0);
+    } else {
+      curves[key] = settling(glide.settleTime(threshold * 2), edge ?? glide.rest, t => glide.value(t), t => glide.velocity(t));
+    }
+  }
+  return curves;
+}

package/dist/motion/decay.d.ts

@@ -0,0 +1,41 @@
+/** 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;
+}
+/** How far a coast at `velocity` units/s travels before it stops. */
+export declare function decayRestDistance(velocity: number, rate?: number): number;
+/**
+ * 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 declare function solveDecay({ from, velocity: initialVelocity, rate, }: {
+    from: number;
+    velocity: number;
+    rate?: number;
+}): DecayCurve;
+//# sourceMappingURL=decay.d.ts.map

package/dist/motion/decay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decay.d.ts","sourceRoot":"","sources":["../../src/motion/decay.ts"],"names":[],"mappings":"AA8BA,yDAAyD;AACzD,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,wBAAwB;IACxB,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,uCAAuC;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,qCAAqC;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,uCAAuC;IACvC,KAAK,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACzB,mDAAmD;IACnD,QAAQ,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC5B,wEAAwE;IACxE,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC;IACtC,8EAA8E;IAC9E,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;IACnC;;;OAGG;IACH,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;CAC5C;AASD,qEAAqE;AACrE,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,MAAM,EAChB,IAAI,GAAE,MAAuC,GAC5C,MAAM,CAER;AAED;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,EACzB,IAAI,EACJ,QAAQ,EAAE,eAAe,EACzB,IAAqC,GACtC,EAAE;IACD,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,GAAG,UAAU,CAsCb"}

package/dist/motion/decay.js

@@ -0,0 +1,90 @@
+// 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.js";
+
+/** A coast released at `from` with `initialVelocity`. */
+
+function decayConstant(rate) {
+  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, rate = scroll.decelerationRate.normal) {
+  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
+}) {
+  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;
+    }
+  };
+}

package/dist/motion/projection.d.ts

@@ -0,0 +1,36 @@
+/** Distance a surface released at `velocity` units/s coasts (WWDC18). */
+export declare function projectDistance(velocity: number, rate?: number): number;
+/** Where a surface released at `position` with `velocity` would come to rest. */
+export declare function project(position: number, velocity: number, rate?: number): number;
+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. This is the math primitive (projection + nearest); the release
+ * policy on top of it (a flick advances at least one detent, a release moving
+ * back toward its start cancels) is `resolveSnapPoint` (resolveSnapPoint.ts), so a
+ * component's release rule calls that rather than adding its own. `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 declare function selectSnapPoint(points: ReadonlyArray<number>, { position, velocity, rate, fromIndex, maxSteps, }: {
+    position: number;
+    velocity: number;
+    rate?: number;
+    fromIndex?: number;
+    maxSteps?: number;
+}): SnapSelection;
+//# sourceMappingURL=projection.d.ts.map

package/dist/motion/projection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"projection.d.ts","sourceRoot":"","sources":["../../src/motion/projection.ts"],"names":[],"mappings":"AA4BA,yEAAyE;AACzE,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,IAAI,GAAE,MAAuC,GAC5C,MAAM,CAKR;AAED,iFAAiF;AACjF,wBAAgB,OAAO,CACrB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,IAAI,GAAE,MAAuC,GAC5C,MAAM,CAER;AAED,MAAM,WAAW,aAAa;IAC5B,uDAAuD;IACvD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,wBAAwB;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,4DAA4D;IAC5D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,EAC7B,EACE,QAAQ,EACR,QAAQ,EACR,IAAqC,EACrC,SAAS,EACT,QAAQ,GACT,EAAE;IACD,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GACA,aAAa,CA2Bf"}

package/dist/motion/projection.js

@@ -0,0 +1,92 @@
+// 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) and `selectSnapPoint` (the release target UIKit-style)
+ * @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.js";
+
+/** Distance a surface released at `velocity` units/s coasts (WWDC18). */
+export function projectDistance(velocity, rate = scroll.decelerationRate.normal) {
+  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, velocity, rate = scroll.decelerationRate.normal) {
+  return position + projectDistance(velocity, rate);
+}
+/**
+ * The rest point a release goes to: the one nearest the projected rest
+ * position. This is the math primitive (projection + nearest); the release
+ * policy on top of it (a flick advances at least one detent, a release moving
+ * back toward its start cancels) is `resolveSnapPoint` (resolveSnapPoint.ts), so a
+ * component's release rule calls that rather than adding its own. `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, {
+  position,
+  velocity,
+  rate = scroll.decelerationRate.normal,
+  fromIndex,
+  maxSteps
+}) {
+  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
+  };
+}

package/dist/motion/reducedMotion.d.ts

@@ -0,0 +1,25 @@
+/** Reduce Motion on a coarse primary pointer: an opacity-only cross-fade. */
+export declare const REDUCED_MOTION_FADE_QUERY = "(prefers-reduced-motion: reduce) and (pointer: coarse)";
+/** Reduce Motion on any other primary pointer: the change completes at once. */
+export declare const REDUCED_MOTION_INSTANT_QUERY = "(prefers-reduced-motion: reduce) and (not (pointer: coarse))";
+/**
+ * The fade to play under Reduce Motion. `duration` 0 means the change
+ * completes at once; `easing` is a CSS timing function.
+ */
+export interface ReducedMotionFade {
+    readonly duration: number;
+    readonly easing: string;
+}
+/**
+ * The Reduced Motion fade for a change to `element` now, for motion the
+ * animator does not drive (two titles cross-fading with Web Animations):
+ * null when motion is not reduced (play the normal motion), else an
+ * opacity-only fade of 200 ms on a coarse pointer or for a touch release, or
+ * duration 0 (at once) on any other pointer, on Core Animation's easeInOut;
+ * the length is fixed.
+ */
+export declare function reducedMotionFade(element?: Element | null, options?: {
+    /** The change starts from the release of a touch drag (DR2). */
+    touchRelease?: boolean;
+}): ReducedMotionFade | null;
+//# sourceMappingURL=reducedMotion.d.ts.map

package/dist/motion/reducedMotion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reducedMotion.d.ts","sourceRoot":"","sources":["../../src/motion/reducedMotion.ts"],"names":[],"mappings":"AAiDA,6EAA6E;AAC7E,eAAO,MAAM,yBAAyB,2DACoB,CAAC;AAE3D,gFAAgF;AAChF,eAAO,MAAM,4BAA4B,iEACuB,CAAC;AAEjE;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,EACxB,OAAO,GAAE;IACP,gEAAgE;IAChE,YAAY,CAAC,EAAE,OAAO,CAAC;CACnB,GACL,iBAAiB,GAAG,IAAI,CAa1B"}

package/dist/motion/reducedMotion.js

@@ -0,0 +1,85 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file reducedMotion.ts
+ * @input The Reduced Motion preference, the primary pointer, the motion tables
+ * @output reducedMotionFade (the fade the animator would play, for motion it
+ *   does not drive) and the two media queries a StyleX transition spells
+ * @position The one Reduced Motion policy (design:reduced-motion) for code
+ *   beside the animator: a raw Web Animations fade, a CSS transition
+ *
+ * Under Reduce Motion nothing moves, scales or springs. On a coarse primary
+ * pointer, or for a change started by a touch drag's release on any pointer
+ * (DR2), a change becomes an opacity-only cross-fade of
+ * `timing.reducedMotionCrossFadeMs` (200 ms) on `timing.curves.move`; on
+ * any other primary pointer it completes at once (DR3). No theme value or
+ * call site lengthens the fade (DR4). The animator follows the same policy on
+ * its own (animator.ts).
+ *
+ * In StyleX, a transition spells the two keys literally and takes its values
+ * from reducedMotion.stylex.ts. A constant used as a computed key compiles to
+ * a later priority layer than the literal media key, which would outrank the
+ * element's state styles, so the keys stay literal:
+ *
+ * ```
+ * transitionProperty: {
+ *   default: 'opacity, translate',
+ *   '@media (prefers-reduced-motion: reduce) and (pointer: coarse)': 'opacity',
+ *   '@media (prefers-reduced-motion: reduce) and (not (pointer: coarse))': 'none',
+ * },
+ * transitionDuration: {
+ *   default: '300ms',
+ *   '@media (prefers-reduced-motion: reduce) and (pointer: coarse)':
+ *     reducedMotionFadeConsts.duration,
+ *   '@media (prefers-reduced-motion: reduce) and (not (pointer: coarse))': '0s',
+ * },
+ * ```
+ *
+ * reducedMotion.test.ts requires every such key in core to equal one of
+ * `reducedMotionKeys`, exactly.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/motion/reducedMotion.stylex.ts
+ * - /packages/core/src/motion/reducedMotion.test.ts
+ * - /packages/core/src/motion/animator.ts (its Reduced Motion path)
+ */
+
+import { defaultIsCoarsePointer, defaultPrefersReducedMotion } from "./animator.js";
+import { reducedMotionCrossFade } from "./uikit/timing.js";
+
+/** Reduce Motion on a coarse primary pointer: an opacity-only cross-fade. */
+export const REDUCED_MOTION_FADE_QUERY = '(prefers-reduced-motion: reduce) and (pointer: coarse)';
+
+/** Reduce Motion on any other primary pointer: the change completes at once. */
+export const REDUCED_MOTION_INSTANT_QUERY = '(prefers-reduced-motion: reduce) and (not (pointer: coarse))';
+
+/**
+ * The fade to play under Reduce Motion. `duration` 0 means the change
+ * completes at once; `easing` is a CSS timing function.
+ */
+
+/**
+ * The Reduced Motion fade for a change to `element` now, for motion the
+ * animator does not drive (two titles cross-fading with Web Animations):
+ * null when motion is not reduced (play the normal motion), else an
+ * opacity-only fade of 200 ms on a coarse pointer or for a touch release, or
+ * duration 0 (at once) on any other pointer, on Core Animation's easeInOut;
+ * the length is fixed.
+ */
+export function reducedMotionFade(element, options = {}) {
+  if (!defaultPrefersReducedMotion()) {
+    return null;
+  }
+  const fades = options.touchRelease === true || defaultIsCoarsePointer();
+  if (!fades) {
+    return {
+      duration: 0,
+      easing: 'linear'
+    };
+  }
+  const curve = reducedMotionCrossFade.curve;
+  return {
+    duration: reducedMotionCrossFade.durationMs,
+    easing: `cubic-bezier(${curve.join(', ')})`
+  };
+}

package/dist/motion/reducedMotion.stylex.d.ts

@@ -0,0 +1,19 @@
+export declare const reducedMotionFadeConsts: {
+    /** The cross-fade under Reduce Motion on a coarse pointer. */
+    duration: string;
+    /** Core Animation's easeInOut. */
+    easing: string;
+};
+/**
+ * The two Reduce Motion media keys, spelled once: under Reduce Motion a coarse
+ * primary pointer fades (DR2) and any other completes at once (DR3). A
+ * component spells the key literally rather than as a computed key: StyleX
+ * puts a constant key in a later priority layer than the literal media key,
+ * where it would outrank the element's state styles. reducedMotion.test.ts
+ * holds every literal in core to these, exactly.
+ */
+export declare const reducedMotionKeys: {
+    fade: string;
+    instant: string;
+};
+//# sourceMappingURL=reducedMotion.stylex.d.ts.map

package/dist/motion/reducedMotion.stylex.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reducedMotion.stylex.d.ts","sourceRoot":"","sources":["../../src/motion/reducedMotion.stylex.ts"],"names":[],"mappings":"AAqBA,eAAO,MAAM,uBAAuB;IAClC,8DAA8D;;IAE9D,kCAAkC;;CAElC,CAAC;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB;;;CAI5B,CAAC"}