@astryxdesign/core 0.7.5-canary.fccd771 → 0.7.5

package/dist/motion/roles.d.ts

@@ -0,0 +1,79 @@
+/**
+ * @file roles.ts
+ * @input The motion tables (motion/uikit and each component's own table)
+ * @output registerMotionTable, motionRoleOf, motionRoleIn, listMotionRoles,
+ *   motionRoleVariable, and the CSS form of a role's value
+ *   (formatMotionRoleValue, parseMotionRoleValue)
+ * @position Motion foundation, internal to core: read by the code that
+ *   resolves a role when a motion starts. No public API writes a role: touch
+ *   motion stays internal until the public motion-token set is decided.
+ *
+ * A motion role is one value of a motion table: a
+ * spring, a duration (a key ending in `Ms`, in milliseconds) or a curve (four
+ * cubic-bézier control points). The roles are the ones `spec:AST-094` FR4
+ * names, each by its table path, such as `springs.settle` or
+ * `timing.curves.move`: a table lists its roles when it registers, and every
+ * other value, a component's measured spring included, stays an internal
+ * constant. No shipped component reads the roles yet.
+ * A role is carried by one CSS custom property, `--motion-` followed by its id
+ * in kebab case (`--motion-springs-settle`), which nothing public writes; an
+ * empty property means the table's value, so the table stays the one measured
+ * source of every value.
+ *
+ * Gesture thresholds, the velocity filter, the timings that decide who gets a
+ * touch and haptics are not motion: they are not roles (tables leave them out
+ * with `exclude`).
+ *
+ * SYNC: When modified, update /packages/core/src/motion/roles.test.ts.
+ */
+import { formatMotionRoleValue, isMotionRoleId, motionRoleVariable, type MotionCurvePoints, type MotionRoleKind } from './roleValue.js';
+import type { DurationBounce, SpringDescription } from './spring.js';
+export { formatMotionRoleValue, isMotionRoleId, motionRoleVariable };
+export type { MotionCurvePoints, MotionRoleKind };
+/** One registered role. */
+export interface MotionRole {
+    /** The table path, e.g. `springs.sheetDetent`. */
+    readonly id: string;
+    readonly kind: MotionRoleKind;
+    /** The CSS custom property that carries the role's value. */
+    readonly variable: string;
+    /** The table's value: what plays when the property is empty. */
+    readonly value: SpringDescription | number | MotionCurvePoints;
+}
+/**
+ * Registers a motion table: each spring, `…Ms` duration and curve leaf that
+ * `roles` lists (its role name, relative to the table) becomes a role named
+ * by its path under `id`; the table's other values stay internal constants. A leaf object the table shares between
+ * two keys is replaced in the table by an equal copy, so each role has its own
+ * object (an animator resolves a role from the object it is handed).
+ * `exclude` lists paths, relative to the table, that are not motion;
+ * `rename` maps a path, relative to the table, to the role name it is
+ * registered under (relative too), so a role is named for its use while the
+ * table keeps its source's name. Registering the same table under the same id
+ * again does nothing.
+ */
+export declare function registerMotionTable(id: string, table: object, { roles, exclude, rename, }?: {
+    roles?: ReadonlyArray<string>;
+    exclude?: ReadonlyArray<string>;
+    rename?: Readonly<Record<string, string>>;
+}): void;
+/** The role a spring or curve leaf of a registered table plays, if any. */
+export declare function motionRoleOf(leaf: unknown): MotionRole | undefined;
+/**
+ * The role `group[key]` plays, for a table or one of its groups: the way to
+ * name a duration, which is a bare number.
+ */
+export declare function motionRoleIn(group: object, key: string): MotionRole | undefined;
+/** The role with this id, once its table is registered. */
+export declare function motionRole(id: string): MotionRole | undefined;
+/** Every registered role, by id. */
+export declare function listMotionRoles(): MotionRole[];
+/**
+ * Reads a role value back from its CSS custom property. Returns null for an
+ * empty or malformed value: the caller then uses the table's value.
+ */
+export declare function parseMotionRoleValue(kind: 'spring', text: string): DurationBounce | null;
+export declare function parseMotionRoleValue(kind: 'duration', text: string): number | null;
+export declare function parseMotionRoleValue(kind: 'curve', text: string): MotionCurvePoints | null;
+export declare function parseMotionRoleValue(kind: MotionRoleKind, text: string): DurationBounce | number | MotionCurvePoints | null;
+//# sourceMappingURL=roles.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"roles.d.ts","sourceRoot":"","sources":["../../src/motion/roles.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EACL,qBAAqB,EAErB,cAAc,EAEd,kBAAkB,EAClB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACpB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAC,cAAc,EAAE,iBAAiB,EAAC,MAAM,UAAU,CAAC;AAEhE,OAAO,EAAC,qBAAqB,EAAE,cAAc,EAAE,kBAAkB,EAAC,CAAC;AACnE,YAAY,EAAC,iBAAiB,EAAE,cAAc,EAAC,CAAC;AAEhD,2BAA2B;AAC3B,MAAM,WAAW,UAAU;IACzB,kDAAkD;IAClD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,6DAA6D;IAC7D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,gEAAgE;IAChE,QAAQ,CAAC,KAAK,EAAE,iBAAiB,GAAG,MAAM,GAAG,iBAAiB,CAAC;CAChE;AAYD;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CACjC,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,MAAM,EACb,EACE,KAAU,EACV,OAAY,EACZ,MAAW,GACZ,GAAE;IACD,KAAK,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC9B,OAAO,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAChC,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACtC,GACL,IAAI,CAoEN;AAED,2EAA2E;AAC3E,wBAAgB,YAAY,CAAC,IAAI,EAAE,OAAO,GAAG,UAAU,GAAG,SAAS,CAIlE;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,MAAM,GACV,UAAU,GAAG,SAAS,CAOxB;AAED,2DAA2D;AAC3D,wBAAgB,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAE7D;AAED,oCAAoC;AACpC,wBAAgB,eAAe,IAAI,UAAU,EAAE,CAE9C;AASD;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,QAAQ,EACd,IAAI,EAAE,MAAM,GACX,cAAc,GAAG,IAAI,CAAC;AACzB,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,UAAU,EAChB,IAAI,EAAE,MAAM,GACX,MAAM,GAAG,IAAI,CAAC;AACjB,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,OAAO,EACb,IAAI,EAAE,MAAM,GACX,iBAAiB,GAAG,IAAI,CAAC;AAC5B,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,cAAc,EACpB,IAAI,EAAE,MAAM,GACX,cAAc,GAAG,MAAM,GAAG,iBAAiB,GAAG,IAAI,CAAC"}

package/dist/motion/roles.js

@@ -0,0 +1,199 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file roles.ts
+ * @input The motion tables (motion/uikit and each component's own table)
+ * @output registerMotionTable, motionRoleOf, motionRoleIn, listMotionRoles,
+ *   motionRoleVariable, and the CSS form of a role's value
+ *   (formatMotionRoleValue, parseMotionRoleValue)
+ * @position Motion foundation, internal to core: read by the code that
+ *   resolves a role when a motion starts. No public API writes a role: touch
+ *   motion stays internal until the public motion-token set is decided.
+ *
+ * A motion role is one value of a motion table: a
+ * spring, a duration (a key ending in `Ms`, in milliseconds) or a curve (four
+ * cubic-bézier control points). The roles are the ones `spec:AST-094` FR4
+ * names, each by its table path, such as `springs.settle` or
+ * `timing.curves.move`: a table lists its roles when it registers, and every
+ * other value, a component's measured spring included, stays an internal
+ * constant. No shipped component reads the roles yet.
+ * A role is carried by one CSS custom property, `--motion-` followed by its id
+ * in kebab case (`--motion-springs-settle`), which nothing public writes; an
+ * empty property means the table's value, so the table stays the one measured
+ * source of every value.
+ *
+ * Gesture thresholds, the velocity filter, the timings that decide who gets a
+ * touch and haptics are not motion: they are not roles (tables leave them out
+ * with `exclude`).
+ *
+ * SYNC: When modified, update /packages/core/src/motion/roles.test.ts.
+ */
+
+import { formatMotionRoleValue, isCurve, isMotionRoleId, isSpring, motionRoleVariable } from "./roleValue.js";
+export { formatMotionRoleValue, isMotionRoleId, motionRoleVariable };
+
+/** One registered role. */
+
+const rolesById = new Map();
+/** A table id → the table registered under it. */
+const tablesById = new Map();
+/** A spring or curve leaf → its role. */
+const roleOfLeaf = new WeakMap();
+/** A table or one of its groups → its path. */
+const pathOfGroup = new WeakMap();
+/** A table path → the role id it is registered under, when renamed. */
+const roleIdOfPath = new Map();
+
+/**
+ * Registers a motion table: each spring, `…Ms` duration and curve leaf that
+ * `roles` lists (its role name, relative to the table) becomes a role named
+ * by its path under `id`; the table's other values stay internal constants. A leaf object the table shares between
+ * two keys is replaced in the table by an equal copy, so each role has its own
+ * object (an animator resolves a role from the object it is handed).
+ * `exclude` lists paths, relative to the table, that are not motion;
+ * `rename` maps a path, relative to the table, to the role name it is
+ * registered under (relative too), so a role is named for its use while the
+ * table keeps its source's name. Registering the same table under the same id
+ * again does nothing.
+ */
+export function registerMotionTable(id, table, {
+  roles = [],
+  exclude = [],
+  rename = {}
+} = {}) {
+  if (!/^[a-z][A-Za-z0-9]*$/.test(id)) {
+    throw new Error(`motion table id "${id}" must be one camelCase word`);
+  }
+  // Registering the same table again changes nothing: each table's
+  // register function may run from every touch module that uses it.
+  if (tablesById.get(id) === table) {
+    return;
+  }
+  tablesById.set(id, table);
+  const skip = new Set(exclude.map(path => `${id}.${path}`));
+  const listed = new Set(roles.map(name => `${id}.${name}`));
+  const walk = (group, prefix) => {
+    pathOfGroup.set(group, prefix);
+    for (const [key, value] of Object.entries(group)) {
+      const path = `${prefix}.${key}`;
+      if (skip.has(path)) {
+        continue;
+      }
+      let kind = null;
+      if (isSpring(value)) {
+        kind = 'spring';
+      } else if (isCurve(value)) {
+        kind = 'curve';
+      } else if (typeof value === 'number' && key.endsWith('Ms')) {
+        kind = 'duration';
+      } else if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+        walk(value, path);
+        continue;
+      }
+      if (kind == null) {
+        continue;
+      }
+      const relative = path.slice(id.length + 1);
+      const roleId = relative in rename ? `${id}.${rename[relative]}` : path;
+      // Only the roles the table lists; every other value stays internal.
+      if (!listed.has(roleId)) {
+        continue;
+      }
+      if (roleId !== path) {
+        roleIdOfPath.set(path, roleId);
+      }
+      let leaf = value;
+      if (typeof leaf === 'object') {
+        const taken = roleOfLeaf.get(leaf);
+        if (taken != null && taken.id !== roleId) {
+          leaf = Object.freeze(Array.isArray(leaf) ? [...leaf] : {
+            ...leaf
+          });
+          group[key] = leaf;
+        }
+      }
+      const role = {
+        id: roleId,
+        kind,
+        variable: motionRoleVariable(roleId),
+        value: leaf
+      };
+      rolesById.set(roleId, role);
+      if (typeof leaf === 'object') {
+        roleOfLeaf.set(leaf, role);
+      }
+    }
+  };
+  walk(table, id);
+}
+
+/** The role a spring or curve leaf of a registered table plays, if any. */
+export function motionRoleOf(leaf) {
+  return leaf !== null && typeof leaf === 'object' ? roleOfLeaf.get(leaf) : undefined;
+}
+
+/**
+ * The role `group[key]` plays, for a table or one of its groups: the way to
+ * name a duration, which is a bare number.
+ */
+export function motionRoleIn(group, key) {
+  const prefix = pathOfGroup.get(group);
+  if (prefix == null) {
+    return undefined;
+  }
+  const path = `${prefix}.${key}`;
+  return rolesById.get(roleIdOfPath.get(path) ?? path);
+}
+
+/** The role with this id, once its table is registered. */
+export function motionRole(id) {
+  return rolesById.get(id);
+}
+
+/** Every registered role, by id. */
+export function listMotionRoles() {
+  return [...rolesById.values()].sort((a, b) => a.id < b.id ? -1 : 1);
+}
+const NUMBER = '(-?(?:\\d+\\.?\\d*|\\.\\d+)(?:e-?\\d+)?)';
+const SPRING_VALUE = new RegExp(`^${NUMBER}s\\s+${NUMBER}$`);
+const DURATION_VALUE = new RegExp(`^${NUMBER}(ms|s)$`);
+const CURVE_VALUE = new RegExp(`^cubic-bezier\\(\\s*${NUMBER}\\s*,\\s*${NUMBER}\\s*,\\s*${NUMBER}\\s*,\\s*${NUMBER}\\s*\\)$`);
+
+/**
+ * Reads a role value back from its CSS custom property. Returns null for an
+ * empty or malformed value: the caller then uses the table's value.
+ */
+
+export function parseMotionRoleValue(kind, text) {
+  const value = text.trim();
+  if (value === '') {
+    return null;
+  }
+  if (kind === 'spring') {
+    const m = SPRING_VALUE.exec(value);
+    if (m == null) {
+      return null;
+    }
+    const duration = Number(m[1]);
+    const bounce = Number(m[2]);
+    // A bounce of 1 is undamped: it never settles.
+    return duration > 0 && bounce > -1 && bounce < 1 ? {
+      duration,
+      bounce
+    } : null;
+  }
+  if (kind === 'duration') {
+    const m = DURATION_VALUE.exec(value);
+    if (m == null) {
+      return null;
+    }
+    const ms = Number(m[1]) * (m[2] === 's' ? 1000 : 1);
+    return ms >= 0 ? ms : null;
+  }
+  const m = CURVE_VALUE.exec(value);
+  if (m == null) {
+    return null;
+  }
+  const points = [m[1], m[2], m[3], m[4]].map(Number);
+  return points[0] >= 0 && points[0] <= 1 && points[2] >= 0 && points[2] <= 1 ? points : null;
+}

package/dist/motion/rubberBand.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 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 declare function rubberBand(overflow: number, dimension: number, coefficient?: number): number;
+/** The finger overflow that displays `displayed`; ±Infinity at ±dimension. */
+export declare function rubberBandInverse(displayed: number, dimension: number, coefficient?: number): number;
+/**
+ * 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 declare function rubberBandSlope(overflow: number, dimension: number, coefficient?: number): number;
+/**
+ * The displayed value for a raw (finger-driven) `value` constrained to
+ * [min, max]: unchanged inside, rubber-banded past either edge.
+ */
+export declare function rubberBandClamp(value: number, min: number, max: number, dimension: number, coefficient?: number): number;
+/** Inverse of `rubberBandClamp`: the raw value that displays `displayed`. */
+export declare function rubberBandUnclamp(displayed: number, min: number, max: number, dimension: number, coefficient?: number): number;
+//# sourceMappingURL=rubberBand.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"rubberBand.d.ts","sourceRoot":"","sources":["../../src/motion/rubberBand.ts"],"names":[],"mappings":"AA6BA;;;GAGG;AACH,wBAAgB,UAAU,CACxB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,WAAW,GAAE,MAAsC,GAClD,MAAM,CAOR;AAED,8EAA8E;AAC9E,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,WAAW,GAAE,MAAsC,GAClD,MAAM,CAUR;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,WAAW,GAAE,MAAsC,GAClD,MAAM,CAMR;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,MAAM,EACjB,WAAW,GAAE,MAAsC,GAClD,MAAM,CAQR;AAED,6EAA6E;AAC7E,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,MAAM,EACjB,WAAW,GAAE,MAAsC,GAClD,MAAM,CAQR"}

package/dist/motion/rubberBand.js

@@ -0,0 +1,91 @@
+// 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.js";
+
+/**
+ * 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, dimension, coefficient = scroll.rubberBand.coefficient) {
+  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, dimension, coefficient = scroll.rubberBand.coefficient) {
+  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, dimension, coefficient = scroll.rubberBand.coefficient) {
+  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, min, max, dimension, coefficient = scroll.rubberBand.coefficient) {
+  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, min, max, dimension, coefficient = scroll.rubberBand.coefficient) {
+  if (displayed < min) {
+    return min + rubberBandInverse(displayed - min, dimension, coefficient);
+  }
+  if (displayed > max) {
+    return max + rubberBandInverse(displayed - max, dimension, coefficient);
+  }
+  return displayed;
+}

package/dist/motion/selectPage.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @file selectPage.ts
+ * @input A release (position, velocity), the page size and count, the
+ *   current page
+ * @output Exports `selectPage`: the page a paging release settles on
+ * @position UIScrollView paging (`isPagingEnabled`) on the release policy
+ *   (resolveSnapPoint.ts). Pure: no DOM, no React
+ *
+ * SYNC: When modified, update selectPage.test.ts.
+ */
+import type { SnapSelection } from './projection.js';
+/**
+ * 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 declare function selectPage({ position, velocity, pageSize, pageCount, currentPage, rate, }: {
+    position: number;
+    velocity: number;
+    pageSize: number;
+    pageCount: number;
+    currentPage: number;
+    rate?: number;
+}): SnapSelection;
+//# sourceMappingURL=selectPage.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"selectPage.d.ts","sourceRoot":"","sources":["../../src/motion/selectPage.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,cAAc,CAAC;AAIhD;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,EACzB,QAAQ,EACR,QAAQ,EACR,QAAQ,EACR,SAAS,EACT,WAAW,EACX,IAAmC,GACpC,EAAE;IACD,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,GAAG,aAAa,CAiBhB"}

package/dist/motion/selectPage.js

@@ -0,0 +1,55 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file selectPage.ts
+ * @input A release (position, velocity), the page size and count, the
+ *   current page
+ * @output Exports `selectPage`: the page a paging release settles on
+ * @position UIScrollView paging (`isPagingEnabled`) on the release policy
+ *   (resolveSnapPoint.ts). Pure: no DOM, no React
+ *
+ * SYNC: When modified, update selectPage.test.ts.
+ */
+
+import { resolveSnapPoint } from "./resolveSnapPoint.js";
+import { scroll } from "./uikit/scroll.js";
+
+/**
+ * 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
+}) {
+  const points = Array.from({
+    length: Math.max(1, pageCount)
+  }, (_, i) => i * pageSize);
+  // The release policy (resolveSnapPoint.ts), with the paging rate as the
+  // seconds of velocity it projects, no flick and one page per release.
+  const {
+    index,
+    projected
+  } = resolveSnapPoint({
+    points,
+    position,
+    velocity,
+    flickThreshold: Infinity,
+    projection: {
+      seconds: rate / (1 - rate) / 1000
+    },
+    fromIndex: currentPage,
+    maxSteps: 1
+  });
+  return {
+    index,
+    value: points[index],
+    projected
+  };
+}

package/dist/motion/spring.d.ts

@@ -0,0 +1,193 @@
+/**
+ * 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;
+}
+/**
+ * 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 declare function springFromDurationBounce({ duration, bounce, }: DurationBounce): Spring;
+/**
+ * SwiftUI's `Spring(response:dampingRatio:)` and
+ * `Animation.spring(response:dampingFraction:)`. Overdamping (ratio > 1) is
+ * kept, as SwiftUI keeps it for this initializer.
+ */
+export declare function springFromResponse({ response, dampingRatio, }: ResponseDamping): Spring;
+/**
+ * `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 declare function springFromPhysics({ mass, stiffness, damping, allowOverdamping, }: {
+    mass?: number;
+    stiffness: number;
+    damping: number;
+    allowOverdamping?: boolean;
+}): Spring;
+/** Undamped angular frequency ω₀ = √(k/m), rad/s. */
+export declare function naturalFrequency(spring: Spring): number;
+/** Damping ratio ζ = c / (2·√(k·m)). */
+export declare function dampingRatioOf(spring: Spring): number;
+/** Response (period of the undamped spring), seconds. */
+export declare function responseOf(spring: Spring): number;
+/** The spring as SwiftUI's (duration, bounce), inverting the WWDC23 equations. */
+export declare function durationBounceOf(spring: Spring): DurationBounce;
+/** The spring as (response, dampingRatio). */
+export declare function responseDampingOf(spring: Spring): ResponseDamping;
+/**
+ * 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 declare function toSpring(description: SpringDescription): Spring;
+/**
+ * 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 declare function relativeVelocity(velocity: number, from: number, to: number): number;
+/** Inverse of `relativeVelocity`: absolute units/s. */
+export declare function absoluteVelocity(relative: number, from: number, to: number): number;
+/** 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;
+}
+/**
+ * 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 declare function solveSpring(spring: Spring, { from, to, velocity: initialVelocity, }: {
+    from: number;
+    to: number;
+    velocity?: number;
+}): SpringCurve;
+/** 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 declare function solveSpringTowardRamp(spring: Spring, { from, velocity: initialVelocity, target, slope, }: {
+    from: number;
+    velocity?: number;
+    target: number;
+    slope: number;
+}): SpringRampCurve;
+/** Core Animation's settling epsilon (documented for SwiftUI's Spring). */
+export declare 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 declare function settlingDuration(spring: Spring, { initialVelocity, epsilon, }?: {
+    initialVelocity?: number;
+    epsilon?: number;
+}): number;
+/**
+ * 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 declare function springFromUIKitDampingDuration({ duration, dampingRatio, }: {
+    duration: number;
+    dampingRatio: number;
+}): Spring;
+//# sourceMappingURL=spring.d.ts.map