@astryxdesign/core 0.7.5-canary.fccd771 → 0.7.5

package/dist/motion/reducedMotion.stylex.js

@@ -0,0 +1,37 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file reducedMotion.stylex.ts
+ * @input StyleX constant definitions
+ * @output reducedMotionFadeConsts (the Reduced Motion cross-fade's duration
+ *   and easing) for StyleX transitions, and reducedMotionKeys (its two media
+ *   keys, which a transition spells literally)
+ * @position The CSS side of the Reduced Motion policy (reducedMotion.ts):
+ *   values a transition takes under its two Reduce Motion media keys
+ *
+ * Constants, not theme variables: no theme lengthens the fade
+ * (design:reduced-motion DR4). They equal `timing.reducedMotionCrossFadeMs`
+ * and `timing.curves.move`, which reducedMotion.test.ts checks.
+ *
+ * SYNC: When modified, update /packages/core/src/motion/uikit/timing.ts and
+ * /packages/core/src/motion/reducedMotion.test.ts.
+ */
+
+import * as stylex from '@stylexjs/stylex';
+export const reducedMotionFadeConsts = {
+  duration: "200ms",
+  easing: "cubic-bezier(0.42, 0, 0.58, 1)"
+};
+
+/**
+ * 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 const reducedMotionKeys = {
+  fade: "@media (prefers-reduced-motion: reduce) and (pointer: coarse)",
+  instant: "@media (prefers-reduced-motion: reduce) and (not (pointer: coarse))"
+};

package/dist/motion/reducedMotionPlan.d.ts

@@ -0,0 +1,89 @@
+/**
+ * @file reducedMotionPlan.ts
+ * @input A call's targets and a read-only view of the animator's opacity
+ *   state
+ * @output planReducedMotion, TRAVEL_PROPERTIES and the plan's types
+ * @position The animator's Reduce Motion planner (packages/core/src/motion):
+ *   what one call becomes under Reduce Motion. animator.ts applies the plan;
+ *   the policy itself is described in its header (design:reduced-motion
+ *   DR1–DR4).
+ *
+ * With `fade` (a coarse primary pointer, or a touch drag's release), a call
+ * becomes an opacity-only cross-fade whose travel lands while the element is
+ * transparent: an entrance from 0 lands at once and fades in, an exit to 0
+ * fades out in place and then lands, and any other call that moves dips
+ * (fades out, lands, fades back in). Without `fade`, everything lands at once. When no call owns
+ * the opacity, a dip or a fade by role starts from and returns to the
+ * element's own (stylesheet) opacity, which the plan reports as `borrowed`.
+ * The planner is pure: it reads the animator only through
+ * `ReducedMotionView` and returns what to write.
+ *
+ * SYNC: When modified, update animator.ts (its header's Reduce Motion
+ * section, and `reducedMotion`, which applies the plan) and animator.test.ts.
+ */
+import type { MotionProperty } from './animator.js';
+/** The properties that move an element rather than fade it. */
+export declare const TRAVEL_PROPERTIES: ReadonlyArray<MotionProperty>;
+/** A point of the opacity fade: ms after the call's start, and the value. */
+export interface FadePoint {
+    readonly at: number;
+    readonly value: number;
+}
+/** The travel a plan writes later, while the element is transparent. */
+export interface PlannedLanding {
+    /** ms after the call's start. */
+    readonly at: number;
+    readonly values: Map<MotionProperty, number>;
+    /**
+     * The fade back in that follows the landing (a dip); `isBorrowed` when it
+     * returns to the stylesheet's opacity, which owns it again once it ends.
+     */
+    fadeIn: {
+        readonly to: number;
+        readonly ms: number;
+        readonly isBorrowed?: boolean;
+    } | null;
+    /** The opacity written with the landing (an exit by role). */
+    restore: number | null;
+    /**
+     * The restore returns to the stylesheet's opacity (an exit by role on a
+     * surface no call owns opacity on): the stylesheet owns it again.
+     */
+    restoreIsBorrowed?: boolean;
+}
+/** What the planner reads of the animator, at the call's time. */
+export interface ReducedMotionView {
+    valueAt(property: MotionProperty, time: number): number;
+    /** Where the opacity is heading (a running fade's end, else its value). */
+    opacityHeading(): number;
+    /** The element's own (stylesheet) opacity. */
+    ownOpacity(): number;
+    /** Whether the animator writes the element's opacity itself. */
+    writesOwnOpacity(): boolean;
+    /** The stylesheet opacity a running dip borrowed, if any. */
+    readonly borrowedOpacity: number | null;
+    readonly hasOpacityCurve: boolean;
+    readonly restingOpacity: number;
+    /** Whether a move of an earlier call still waits to land. */
+    readonly hasPendingLanding: boolean;
+}
+/** What Reduce Motion makes of a call. */
+export interface ReducedMotionPlan {
+    /** Properties written at once, with no curve. */
+    readonly atOnce: MotionProperty[];
+    /** The opacity fade, when the call fades. */
+    readonly opacityFade: FadePoint[] | null;
+    /** Values that stay where they are until the landing writes them. */
+    readonly holds: Partial<Record<MotionProperty, number>>;
+    readonly landing: PlannedLanding | null;
+    /** The stylesheet opacity a dip borrowed (no call owns opacity). */
+    readonly borrowed?: number | null;
+}
+/**
+ * Plans one call under Reduce Motion: with `fade`, an opacity-only
+ * cross-fade whose travel lands while the element is transparent; without,
+ * everything at once. `role` gives a call that names no opacity its
+ * direction (`crossfadeAs`).
+ */
+export declare function planReducedMotion(view: ReducedMotionView, time: number, targets: Partial<Record<MotionProperty, number>>, properties: ReadonlyArray<MotionProperty>, fade: boolean, role?: 'entrance' | 'exit'): ReducedMotionPlan;
+//# sourceMappingURL=reducedMotionPlan.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"reducedMotionPlan.d.ts","sourceRoot":"","sources":["../../src/motion/reducedMotionPlan.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,YAAY,CAAC;AAG/C,+DAA+D;AAC/D,eAAO,MAAM,iBAAiB,EAAE,aAAa,CAAC,cAAc,CAM3D,CAAC;AAEF,6EAA6E;AAC7E,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,wEAAwE;AACxE,MAAM,WAAW,cAAc;IAC7B,iCAAiC;IACjC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,MAAM,EAAE,GAAG,CAAC,cAAc,EAAE,MAAM,CAAC,CAAC;IAC7C;;;OAGG;IACH,MAAM,EAAE;QACN,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;QACpB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;QACpB,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;KAC/B,GAAG,IAAI,CAAC;IACT,8DAA8D;IAC9D,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB;;;OAGG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,kEAAkE;AAClE,MAAM,WAAW,iBAAiB;IAChC,OAAO,CAAC,QAAQ,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IACxD,2EAA2E;IAC3E,cAAc,IAAI,MAAM,CAAC;IACzB,8CAA8C;IAC9C,UAAU,IAAI,MAAM,CAAC;IACrB,gEAAgE;IAChE,gBAAgB,IAAI,OAAO,CAAC;IAC5B,6DAA6D;IAC7D,QAAQ,CAAC,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IACxC,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,6DAA6D;IAC7D,QAAQ,CAAC,iBAAiB,EAAE,OAAO,CAAC;CACrC;AAED,0CAA0C;AAC1C,MAAM,WAAW,iBAAiB;IAChC,iDAAiD;IACjD,QAAQ,CAAC,MAAM,EAAE,cAAc,EAAE,CAAC;IAClC,6CAA6C;IAC7C,QAAQ,CAAC,WAAW,EAAE,SAAS,EAAE,GAAG,IAAI,CAAC;IACzC,qEAAqE;IACrE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,MAAM,CAAC,cAAc,EAAE,MAAM,CAAC,CAAC,CAAC;IACxD,QAAQ,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI,CAAC;IACxC,oEAAoE;IACpE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACnC;AAKD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,iBAAiB,EACvB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,cAAc,EAAE,MAAM,CAAC,CAAC,EAChD,UAAU,EAAE,aAAa,CAAC,cAAc,CAAC,EACzC,IAAI,EAAE,OAAO,EACb,IAAI,CAAC,EAAE,UAAU,GAAG,MAAM,GACzB,iBAAiB,CAqJnB"}

package/dist/motion/reducedMotionPlan.js

@@ -0,0 +1,194 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file reducedMotionPlan.ts
+ * @input A call's targets and a read-only view of the animator's opacity
+ *   state
+ * @output planReducedMotion, TRAVEL_PROPERTIES and the plan's types
+ * @position The animator's Reduce Motion planner (packages/core/src/motion):
+ *   what one call becomes under Reduce Motion. animator.ts applies the plan;
+ *   the policy itself is described in its header (design:reduced-motion
+ *   DR1–DR4).
+ *
+ * With `fade` (a coarse primary pointer, or a touch drag's release), a call
+ * becomes an opacity-only cross-fade whose travel lands while the element is
+ * transparent: an entrance from 0 lands at once and fades in, an exit to 0
+ * fades out in place and then lands, and any other call that moves dips
+ * (fades out, lands, fades back in). Without `fade`, everything lands at once. When no call owns
+ * the opacity, a dip or a fade by role starts from and returns to the
+ * element's own (stylesheet) opacity, which the plan reports as `borrowed`.
+ * The planner is pure: it reads the animator only through
+ * `ReducedMotionView` and returns what to write.
+ *
+ * SYNC: When modified, update animator.ts (its header's Reduce Motion
+ * section, and `reducedMotion`, which applies the plan) and animator.test.ts.
+ */
+
+import { reducedMotionCrossFade } from "./uikit/timing.js";
+
+/** The properties that move an element rather than fade it. */
+export const TRAVEL_PROPERTIES = ['x', 'y', 'rotate', 'scaleX', 'scaleY'];
+
+/** A point of the opacity fade: ms after the call's start, and the value. */
+
+/** The travel a plan writes later, while the element is transparent. */
+
+/** What the planner reads of the animator, at the call's time. */
+
+/** What Reduce Motion makes of a call. */
+
+/** The opacity no call has changed. */
+const IDENTITY_OPACITY = 1;
+
+/**
+ * Plans one call under Reduce Motion: with `fade`, an opacity-only
+ * cross-fade whose travel lands while the element is transparent; without,
+ * everything at once. `role` gives a call that names no opacity its
+ * direction (`crossfadeAs`).
+ */
+export function planReducedMotion(view, time, targets, properties, fade, role) {
+  const holds = {};
+  if (!fade) {
+    return {
+      atOnce: [...properties],
+      opacityFade: null,
+      holds,
+      landing: null
+    };
+  }
+  const atOnce = properties.filter(property => TRAVEL_PROPERTIES.includes(property));
+  const opacityNow = view.valueAt('opacity', time);
+  // A fade the call does not name keeps going where it was heading.
+  const opacityTo = targets.opacity ?? view.opacityHeading();
+  const travel = properties.filter(property => TRAVEL_PROPERTIES.includes(property) && Math.abs(targets[property] - view.valueAt(property, time)) > 1e-9);
+  // Only the call's own opacity (or its role) makes it an entrance or an
+  // exit: a fade it does not name, such as a dip still running, does not.
+  const named = targets.opacity != null;
+  let entering = named && opacityTo > opacityNow + 1e-6;
+  let leaving = named && opacityTo < opacityNow - 1e-6;
+  let fadeFrom = opacityNow;
+  let fadeTo = opacityTo;
+  let restore = null;
+  // A fade by role on a surface no call owns opacity on starts from, or
+  // returns to, the element's own (stylesheet) opacity, as a dip does.
+  const roleBorrow = role != null && !named && view.borrowedOpacity == null && !view.hasOpacityCurve && view.restingOpacity === IDENTITY_OPACITY && !view.writesOwnOpacity() ? view.ownOpacity() : null;
+  if (!entering && !leaving && role === 'entrance') {
+    entering = true;
+    // From transparent, or from where a running fade (an exit caught
+    // midway) has it.
+    fadeFrom = view.hasOpacityCurve ? opacityNow : 0;
+    fadeTo = roleBorrow ?? opacityTo;
+  } else if (!entering && !leaving && role === 'exit') {
+    leaving = true;
+    fadeFrom = roleBorrow ?? opacityNow;
+    fadeTo = 0;
+    restore = roleBorrow ?? opacityTo;
+  }
+  // A move still waiting to land (an earlier dip's) lands at this call's
+  // invisible moment, never while the element shows.
+  const pending = view.hasPendingLanding;
+  // Not a theme role: no theme lengthens it (design:reduced-motion DR4).
+  const ms = reducedMotionCrossFade.durationMs;
+  const landsLater = (at, fadeIn) => {
+    const values = new Map();
+    for (const property of travel) {
+      holds[property] = view.valueAt(property, time);
+      values.set(property, targets[property]);
+    }
+    return {
+      at,
+      values,
+      fadeIn,
+      restore,
+      ...(roleBorrow != null && restore != null ? {
+        restoreIsBorrowed: true
+      } : {})
+    };
+  };
+  // Travel lands only while the element is transparent (DR1, DR2): an
+  // entrance that starts visible, or an exit that ends visible, dips instead
+  // when it has travel or a waiting landing to carry.
+  const carries = travel.length > 0 || pending;
+  if (entering && !pending && (!carries || fadeFrom <= 1e-6)) {
+    // Lands at once (the travel is written at once) and fades in.
+    return {
+      atOnce,
+      opacityFade: [{
+        at: 0,
+        value: fadeFrom
+      }, {
+        at: ms,
+        value: fadeTo
+      }],
+      holds,
+      landing: null,
+      borrowed: roleBorrow
+    };
+  }
+  if (leaving && (!carries || fadeTo <= 1e-6)) {
+    // Fades out in place, then lands.
+    const opacityFade = [{
+      at: 0,
+      value: fadeFrom
+    }, {
+      at: ms,
+      value: fadeTo
+    }];
+    return {
+      atOnce,
+      opacityFade,
+      holds,
+      landing: travel.length > 0 || restore != null || pending ? landsLater(ms, null) : null
+    };
+  }
+  if (carries) {
+    // A dip: fades out, lands while transparent, fades back in. When no
+    // call owns opacity it starts from and returns to the element's own
+    // (stylesheet) opacity, not the model's 1.
+    // A dip still running on borrowed opacity (its fade out or back in)
+    // lends the same borrow to the next one: overlapping dips never pin
+    // the stylesheet's value inline.
+    const priorBorrow = view.borrowedOpacity;
+    // An opacity the animator left inline (a `set` over a stylesheet that
+    // hides or dims the element) is owned too: a dip returns to it.
+    const ownsOpacity = named || priorBorrow == null && (view.hasOpacityCurve || view.restingOpacity !== IDENTITY_OPACITY || view.writesOwnOpacity());
+    const borrowed = ownsOpacity ? null : priorBorrow ?? view.ownOpacity();
+    if (borrowed != null && borrowed <= 1e-6) {
+      // A stylesheet that hides the element lends nothing: invisible, the
+      // move lands at once, with no dip.
+      return {
+        atOnce,
+        opacityFade: null,
+        holds,
+        landing: null
+      };
+    }
+    // It opens at the opacity on screen: an earlier dip's, when one is
+    // still running, else the borrowed stylesheet value.
+    const opacityFade = [{
+      at: 0,
+      value: view.hasOpacityCurve ? opacityNow : borrowed ?? opacityNow
+    }, {
+      at: ms / 2,
+      value: 0
+    }];
+    const landing = landsLater(ms / 2, {
+      to: borrowed ?? opacityTo,
+      ms: ms / 2,
+      isBorrowed: borrowed != null
+    });
+    return {
+      atOnce,
+      opacityFade,
+      holds,
+      landing,
+      borrowed
+    };
+  }
+  return {
+    atOnce: 'opacity' in targets ? [...atOnce, 'opacity'] : atOnce,
+    opacityFade: null,
+    holds,
+    landing: null
+  };
+}

package/dist/motion/resolveSnapPoint.d.ts

@@ -0,0 +1,52 @@
+/** Where a release lands. */
+export interface SnapPointRelease {
+    /** Index into the points passed in. */
+    readonly index: number;
+    /** The rest position the choice was judged from (the position without a projection). */
+    readonly projected: number;
+}
+/** A release's projection: how far ahead it is judged, and from what speed. */
+export interface SnapPointProjection {
+    /** Seconds of the release velocity the projection reaches. */
+    readonly seconds: number;
+    /** Below this speed (units/s), nothing is projected (default 0). */
+    readonly minSpeed?: number;
+}
+/**
+ * The snap point a release lands on.
+ *
+ * @example
+ * ```
+ * // Snap points at 0, 300 and 640 px. Released at 300 px moving toward 640 at
+ * // 1200 px/s, a flick: on to 640, although its projection (420 px) is
+ * // nearer 300.
+ * resolveSnapPoint({
+ *   points: [0, 300, 640],
+ *   position: 300,
+ *   velocity: 1200,
+ *   flickThreshold: 1008,
+ *   tolerance: 1,
+ *   projection: {seconds: 0.1, minSpeed: 250},
+ *   start: 0,
+ * }); // {index: 2, projected: 420}
+ * ```
+ */
+export declare function resolveSnapPoint({ points, position, velocity, flickThreshold, tolerance, projection, start, fromIndex, maxSteps, }: {
+    /** Snap point positions, ascending. */
+    points: ReadonlyArray<number>;
+    position: number;
+    velocity: number;
+    /** From this speed (units/s) on, a release is a flick. */
+    flickThreshold: number;
+    /** A snap point this close to the position counts as reached by a flick. */
+    tolerance?: number;
+    /** Judge a slow release where it would coast to; absent, where it was let go. */
+    projection?: SnapPointProjection;
+    /** Where the drag began: a release moving back toward it cancels to it. */
+    start?: number;
+    /** The snap point the release starts from, for `maxSteps`. */
+    fromIndex?: number;
+    /** At most this many points away from `fromIndex`. */
+    maxSteps?: number;
+}): SnapPointRelease;
+//# sourceMappingURL=resolveSnapPoint.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"resolveSnapPoint.d.ts","sourceRoot":"","sources":["../../src/motion/resolveSnapPoint.ts"],"names":[],"mappings":"AA0CA,6BAA6B;AAC7B,MAAM,WAAW,gBAAgB;IAC/B,uCAAuC;IACvC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,wFAAwF;IACxF,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,+EAA+E;AAC/E,MAAM,WAAW,mBAAmB;IAClC,8DAA8D;IAC9D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,oEAAoE;IACpE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAoBD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,gBAAgB,CAAC,EAC/B,MAAM,EACN,QAAQ,EACR,QAAQ,EACR,cAAc,EACd,SAAa,EACb,UAAU,EACV,KAAK,EACL,SAAS,EACT,QAAQ,GACT,EAAE;IACD,uCAAuC;IACvC,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,0DAA0D;IAC1D,cAAc,EAAE,MAAM,CAAC;IACvB,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iFAAiF;IACjF,UAAU,CAAC,EAAE,mBAAmB,CAAC;IACjC,2EAA2E;IAC3E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8DAA8D;IAC9D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sDAAsD;IACtD,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,gBAAgB,CA8CnB"}

package/dist/motion/resolveSnapPoint.js

@@ -0,0 +1,135 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file resolveSnapPoint.ts
+ * @input A release (position and velocity on one axis), the points it can
+ *   land on, and the release policy's thresholds
+ * @output Exports resolveSnapPoint: the index of the snap point a release lands on,
+ *   and the projected rest position it was judged from
+ * @position The release policy of the motion foundation, on
+ *   `selectSnapPoint` (projection.ts), which stays the math primitive
+ *   (projection + nearest). Pure: no DOM, no React. Internal to core: not
+ *   exported from the package or any barrel (resolveSnapPoint.test.ts locks
+ *   that). A component's release rule calls it with its own points and
+ *   thresholds; this is the one "where does a release land" helper, so a
+ *   second one should not be added beside it.
+ *
+ * - A slow release lands on the snap point nearest where it would come to rest:
+ *   its position, or, with `projection`, its position plus the distance it
+ *   would coast at its velocity (projection.ts). Below
+ *   `projection.minSpeed` nothing is projected, so it lands on the snap point
+ *   nearest where it was let go. A tie goes the way a projected release
+ *   moves, and otherwise to the earlier snap point (`selectSnapPoint`).
+ * - A flick (`flickThreshold` or faster) lands at least on the next snap point
+ *   beyond its position in the direction it moves, or on the nearest
+ *   snap point to its projection if that is farther. A snap point within
+ *   `tolerance` of the position counts as reached, so the flick goes on to
+ *   the one after it.
+ * - With `start` (where the drag began), a release moving back toward it
+ *   cancels to the snap point nearest `start`, whatever its travel so far or its
+ *   speed.
+ * - With `fromIndex` and `maxSteps`, a release lands at most `maxSteps`
+ *   points away from the one at `fromIndex` (a pager's one page per
+ *   release).
+ *
+ * Snap points are ascending positions on the axis; velocities are in the same
+ * units per second, positive toward larger positions.
+ *
+ * SYNC: When modified, update resolveSnapPoint.test.ts.
+ */
+
+import { selectSnapPoint } from "./projection.js";
+
+/** Where a release lands. */
+
+/** A release's projection: how far ahead it is judged, and from what speed. */
+
+/** The deceleration rate whose projection reaches `seconds` of the velocity. */
+function rateForProjection(seconds) {
+  // WWDC18's projection coasts (v / 1000) · r / (1 − r): r / (1 − r) = 1000·τ.
+  const ms = seconds * 1000;
+  return ms / (1 + ms);
+}
+
+/** The index of the snap point nearest `position` (the first on a tie). */
+function nearestIndex(points, position) {
+  let best = 0;
+  for (let i = 1; i < points.length; i += 1) {
+    if (Math.abs(points[i] - position) < Math.abs(points[best] - position)) {
+      best = i;
+    }
+  }
+  return best;
+}
+
+/**
+ * The snap point a release lands on.
+ *
+ * @example
+ * ```
+ * // Snap points at 0, 300 and 640 px. Released at 300 px moving toward 640 at
+ * // 1200 px/s, a flick: on to 640, although its projection (420 px) is
+ * // nearer 300.
+ * resolveSnapPoint({
+ *   points: [0, 300, 640],
+ *   position: 300,
+ *   velocity: 1200,
+ *   flickThreshold: 1008,
+ *   tolerance: 1,
+ *   projection: {seconds: 0.1, minSpeed: 250},
+ *   start: 0,
+ * }); // {index: 2, projected: 420}
+ * ```
+ */
+export function resolveSnapPoint({
+  points,
+  position,
+  velocity,
+  flickThreshold,
+  tolerance = 0,
+  projection,
+  start,
+  fromIndex,
+  maxSteps
+}) {
+  if (points.length === 0) {
+    throw new RangeError('resolveSnapPoint needs at least one snap point');
+  }
+  const projectedVelocity = projection == null || Math.abs(velocity) < (projection.minSpeed ?? 0) ? 0 : velocity;
+  const choice = selectSnapPoint(points, {
+    position,
+    velocity: projectedVelocity,
+    rate: projection == null ? undefined : rateForProjection(projection.seconds),
+    fromIndex,
+    maxSteps
+  });
+  let index = choice.index;
+  if (Math.abs(velocity) >= flickThreshold) {
+    // A flick goes at least to the next snap point beyond where it is.
+    let next = -1;
+    if (velocity > 0) {
+      next = points.findIndex(d => d > position + tolerance);
+    } else {
+      for (let i = points.length - 1; i >= 0 && next === -1; i -= 1) {
+        if (points[i] < position - tolerance) {
+          next = i;
+        }
+      }
+    }
+    if (next !== -1 && (velocity > 0 ? next > index : next < index)) {
+      index = next;
+    }
+  }
+  if (start != null && velocity !== 0 && Math.sign(velocity) === Math.sign(start - position)) {
+    index = nearestIndex(points, start);
+  }
+  if (fromIndex != null && maxSteps != null) {
+    // A stale index past either end counts from the nearest real snap point.
+    const from = Math.min(Math.max(fromIndex, 0), points.length - 1);
+    index = Math.min(Math.max(index, from - maxSteps), from + maxSteps);
+  }
+  return {
+    index,
+    projected: choice.projected
+  };
+}

package/dist/motion/roleValue.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @file roleValue.ts
+ * @input A role id, or a role's kind and value
+ * @output isMotionRoleId, motionRoleVariable and formatMotionRoleValue (a
+ *   role value's CSS form), with the role kinds
+ * @position The value half of the internal motion roles: no registry and
+ *   no parsing. roles.ts holds the registry and re-exports these.
+ *
+ * SYNC: When modified, update /packages/core/src/motion/roles.test.ts.
+ */
+import { type SpringDescription } from './spring.js';
+/** The three kinds of value a role can hold. */
+export type MotionRoleKind = 'spring' | 'duration' | 'curve';
+/** Cubic-bézier control points `[x1, y1, x2, y2]`. */
+export type MotionCurvePoints = readonly [number, number, number, number];
+/** Whether `id` is a well-formed role name (a dotted table path). */
+export declare function isMotionRoleId(id: string): boolean;
+/** The CSS custom property for a role: `--motion-` + the path in kebab case. */
+export declare function motionRoleVariable(id: string): string;
+export declare function isSpring(value: unknown): value is SpringDescription;
+export declare function isCurve(value: unknown): value is MotionCurvePoints;
+/** Six significant digits: enough for any motion, free of float noise. */
+export declare function short(n: number): string;
+/**
+ * A role value as its CSS custom property holds it:
+ * - spring: SwiftUI's duration and bounce, `0.5s 0.15` (exact for every
+ *   spring: mass folds into the duration, overdamping into a negative bounce);
+ * - duration: `250ms`;
+ * - curve: `cubic-bezier(0.42, 0, 0.58, 1)`, usable as is in CSS.
+ * Throws on a value that is not a valid value of its kind.
+ */
+export declare function formatMotionRoleValue(kind: MotionRoleKind, value: unknown): string;
+//# sourceMappingURL=roleValue.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"roleValue.d.ts","sourceRoot":"","sources":["../../src/motion/roleValue.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AAEH,OAAO,EAA6B,KAAK,iBAAiB,EAAC,MAAM,UAAU,CAAC;AAE5E,gDAAgD;AAChD,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,UAAU,GAAG,OAAO,CAAC;AAE7D,sDAAsD;AACtD,MAAM,MAAM,iBAAiB,GAAG,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;AAI1E,qEAAqE;AACrE,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAElD;AAED,gFAAgF;AAChF,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAUrD;AAED,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,iBAAiB,CASnE;AAED,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,iBAAiB,CAMlE;AAED,0EAA0E;AAC1E,wBAAgB,KAAK,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAEvC;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,cAAc,EACpB,KAAK,EAAE,OAAO,GACb,MAAM,CA4BR"}

package/dist/motion/roleValue.js

@@ -0,0 +1,84 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file roleValue.ts
+ * @input A role id, or a role's kind and value
+ * @output isMotionRoleId, motionRoleVariable and formatMotionRoleValue (a
+ *   role value's CSS form), with the role kinds
+ * @position The value half of the internal motion roles: no registry and
+ *   no parsing. roles.ts holds the registry and re-exports these.
+ *
+ * SYNC: When modified, update /packages/core/src/motion/roles.test.ts.
+ */
+
+import { durationBounceOf, toSpring } from "./spring.js";
+
+/** The three kinds of value a role can hold. */
+
+/** Cubic-bézier control points `[x1, y1, x2, y2]`. */
+
+const ROLE_ID = /^[a-z][A-Za-z0-9]*(\.[a-z][A-Za-z0-9]*)+$/;
+
+/** Whether `id` is a well-formed role name (a dotted table path). */
+export function isMotionRoleId(id) {
+  return ROLE_ID.test(id);
+}
+
+/** The CSS custom property for a role: `--motion-` + the path in kebab case. */
+export function motionRoleVariable(id) {
+  if (!isMotionRoleId(id)) {
+    throw new Error(`motion role "${id}" must be a dotted table path such as "springs.sheetPresent"`);
+  }
+  return `--motion-${id.split('.').map(part => part.replace(/[A-Z]/g, c => `-${c.toLowerCase()}`)).join('-')}`;
+}
+export function isSpring(value) {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    return false;
+  }
+  return 'response' in value && 'dampingRatio' in value || 'duration' in value && 'bounce' in value || 'stiffness' in value && 'damping' in value;
+}
+export function isCurve(value) {
+  return Array.isArray(value) && value.length === 4 && value.every(n => typeof n === 'number');
+}
+
+/** Six significant digits: enough for any motion, free of float noise. */
+export function short(n) {
+  return String(Number(n.toPrecision(6)));
+}
+
+/**
+ * A role value as its CSS custom property holds it:
+ * - spring: SwiftUI's duration and bounce, `0.5s 0.15` (exact for every
+ *   spring: mass folds into the duration, overdamping into a negative bounce);
+ * - duration: `250ms`;
+ * - curve: `cubic-bezier(0.42, 0, 0.58, 1)`, usable as is in CSS.
+ * Throws on a value that is not a valid value of its kind.
+ */
+export function formatMotionRoleValue(kind, value) {
+  if (kind === 'spring') {
+    if (!isSpring(value)) {
+      throw new TypeError('a spring is {response, dampingRatio}, {duration, bounce} or {mass?, stiffness, damping}');
+    }
+    const {
+      duration,
+      bounce
+    } = durationBounceOf(toSpring(value));
+    if (!(bounce < 1)) {
+      throw new RangeError('a spring must settle: its bounce must be below 1 (a damping ratio above 0)');
+    }
+    return `${short(duration)}s ${short(bounce)}`;
+  }
+  if (kind === 'duration') {
+    if (!(typeof value === 'number' && Number.isFinite(value) && value >= 0)) {
+      throw new TypeError('a duration is a finite number of milliseconds ≥ 0');
+    }
+    return `${short(value)}ms`;
+  }
+  if (!isCurve(value) || !value.every(Number.isFinite)) {
+    throw new TypeError('a curve is four finite numbers [x1, y1, x2, y2]');
+  }
+  if (value[0] < 0 || value[0] > 1 || value[2] < 0 || value[2] > 1) {
+    throw new RangeError("a curve's x1 and x2 must lie in [0, 1]");
+  }
+  return `cubic-bezier(${value.map(short).join(', ')})`;
+}