Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(core): spring roles register themselves when they load (#10138)

Christopher Chedeauab7facf1e1df
diff --git a/.changeset/motion-tables-register-at-import.md b/.changeset/motion-tables-register-at-import.md
new file mode 100644
index 0000000000..25f91733f4
--- /dev/null
+++ b/.changeset/motion-tables-register-at-import.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[chore] Internal: each spring role, and the navigation, paging and picker motion tables, register themselves when their module loads, so a spring role plays at the theme's `tempo` wherever it plays, with no register call. A page that plays no spring ships no springs registry. A module that imports single spring rows carries only those rows, unless it also reads the whole `springs` table or calls `registerSpringsTable()`. Not exported from the package entry point.
+
+@vjeux
diff --git a/packages/core/src/DateInput/PickerWheel.tsx b/packages/core/src/DateInput/PickerWheel.tsx
index 2e39ee5f3c..1b8fa58340 100644
--- a/packages/core/src/DateInput/PickerWheel.tsx
+++ b/packages/core/src/DateInput/PickerWheel.tsx
@@ -159,9 +159,9 @@ const styles = stylex.create({
/**
* The motion tables the wheel resolves internal roles from: the timing curve,
- * the scroll bounce and the picker's tap spin. Nothing registers on import
- * (motion/roles.ts) and each register is idempotent, so the wheel calls this
- * right before it resolves a role.
+ * the scroll bounce and the picker's tap spin. The picker table registers as
+ * its module loads, but the timing and scroll tables do not. Each register is
+ * idempotent, so the wheel calls this right before it resolves a role.
*/
function registerWheelTables(): void {
registerTimingTable();
diff --git a/packages/core/src/SegmentedControl/useSegmentedSelectionMotion.ts b/packages/core/src/SegmentedControl/useSegmentedSelectionMotion.ts
index f048ae81ae..5d760e4b22 100644
--- a/packages/core/src/SegmentedControl/useSegmentedSelectionMotion.ts
+++ b/packages/core/src/SegmentedControl/useSegmentedSelectionMotion.ts
@@ -492,9 +492,9 @@ export class SegmentedSelectionMotion {
}),
options: SegmentedSelectionMotionOptions = {},
) {
- // The chase plays the shared `springs.fingerTracking` role, and the slide
- // plays the segmented role. Both register before the first animation,
- // because nothing registers on import. A second call does nothing.
+ // The chase plays the shared `springs.fingerTracking` role, which
+ // registers as its module loads. The slide plays the segmented role, which
+ // registers here before the first animation. A second call does nothing.
registerSpringsTable();
registerSegmentedTable();
this.now = options.now ?? defaultNow;
diff --git a/packages/core/src/animator/createAnimator.ts b/packages/core/src/animator/createAnimator.ts
index 0fe0663ba4..efd6d6ffa1 100644
--- a/packages/core/src/animator/createAnimator.ts
+++ b/packages/core/src/animator/createAnimator.ts
@@ -212,7 +212,8 @@ export function createAttachableAnimator(): {
if (inactive() || Object.keys(to).length === 0) {
return;
}
- // The role registry is written on first use, never on import.
+ // The spring roles registered as their module loaded, so this call
+ // registers nothing new.
registerSpringsTable();
const velocity = motionValues(options?.velocity);
await motion.animate(to, {
diff --git a/packages/core/src/motion/README.md b/packages/core/src/motion/README.md
index 4e50f27d9b..c0882d0dc1 100644
--- a/packages/core/src/motion/README.md
+++ b/packages/core/src/motion/README.md
@@ -59,11 +59,13 @@ names for their use (`springs.settle`, `timing.stateChangeMs`,
a plain constant. The per-role tables stay internal (`spec:AST-094` DEC-15): a
role plays its table value at the theme's tempo, and nothing reads the
role's own CSS variable (`--motion-springs-settle`), so no page or theme
-style sets a role. A table's
-roles exist once its `register<Name>Table()` has run: the animator registers
-the Reduce Motion fade's curve, and code that plays the shared springs calls
-`registerSpringsTable()` before its first motion. The animator resolves each
-role it is handed when the motion starts; code that times something itself
+style sets a role. A table's roles exist once its `register<Name>Table()`
+has run. A page that plays no spring ships no springs registry; each spring
+role registers itself when the module that plays it loads (one idempotent
+in-memory write, no DOM). The navigation, paging and picker tables register
+themselves at import, and the animator registers the Reduce Motion fade's
+curve. The animator resolves each role it is handed when the
+motion starts; code that times something itself
calls `resolveMotion(element, timing, 'stateChangeMs')`. Gesture thresholds and
the timings that decide who gets a touch are not roles.
@@ -74,10 +76,7 @@ import {createMotionEngine} from '../motion/animator';
import {coast} from '../motion/coast';
import {solveSpringTowardRamp, toSpring} from '../motion/spring';
import {resolveMotion} from '../motion/resolveMotion';
-import {registerSpringsTable, springs} from '../motion/uikit';
-
-// Once, so the springs are registered as their roles:
-registerSpringsTable();
+import {springs} from '../motion/uikit';
const animator = createMotionEngine(sheet);
// The animator plays a motion role (spec:AST-094 FR4), its table value, as the
diff --git a/packages/core/src/motion/__tests__/themeTempo.interaction.browser.spec.ts b/packages/core/src/motion/__tests__/themeTempo.interaction.browser.spec.ts
index 5fc2cb3f2a..1d4ada6889 100644
--- a/packages/core/src/motion/__tests__/themeTempo.interaction.browser.spec.ts
+++ b/packages/core/src/motion/__tests__/themeTempo.interaction.browser.spec.ts
@@ -8,8 +8,9 @@
* @output Proof that the springs follow the tempo of the theme they play
* in. A spring the animator plays inside a scope at tempo 1.5 is
* inherited through a nested element. At 1.5 × t it draws what the same
- * spring draws at t outside the scope. Finger tracking draws the same in
- * both. Under three real themes that set only `motion.tempo`, the
+ * spring draws at t outside the scope. A page that imports only the
+ * springs and the engine, and never registers them, plays at its tempo
+ * too. Finger tracking draws the same in both. Under three real themes that set only `motion.tempo`, the
* animated-layout glide lasts 0.75, 1 and 1.5 times as long, with a
* finger or a mouse. A theme with only a duration scale, nested in one at
* tempo 1.5, glides at its own pace
@@ -53,19 +54,21 @@ test.afterAll(async () => {
const TRAVEL = 300;
-// A real navigation (not setContent): the page keeps its own window. The
+// A real navigation (not setContent): the page keeps its own window. Each
// scope writes the private property a theme that sets `tempo` writes.
-async function openScopes(page: Page) {
+async function openScopes(page: Page, {register = true} = {}) {
const html = `<!doctype html><meta name="viewport" content="width=device-width,initial-scale=1">
<style>
html, body { margin: 0; background: #fff; }
.box { position: relative; width: 48px; height: 48px; margin: 8px 0; background: #36c; }
.slow { --_astryx-motion-tempo: 1.5; }
+ .quick { --_astryx-motion-tempo: 0.75; }
</style>
<div class="box" id="base"></div>
<div class="slow"><section><div class="box" id="slowed"></div></section></div>
+<div class="quick"><section><div class="box" id="quick"></div></section></div>
<script>${script}</script>
-<script>Motion.registerSpringsTable();</script>`;
+${register ? '<script>Motion.registerSpringsTable();</script>' : ''}`;
await page.route('http://tempo.test/', async route =>
route.fulfill({contentType: 'text/html', body: html}),
);
@@ -73,18 +76,19 @@ async function openScopes(page: Page) {
}
/**
- * Plays `role` on both boxes and reads each one's travel, paused at each of
- * `times` (ms), the slowed box at its time times `scale`.
+ * Plays `role` on the base box and the `scaled` one. Reads each one's travel,
+ * paused at each of `times` (ms), the scaled box at its time times `scale`.
*/
async function travels(
page: Page,
role: 'settle' | 'fingerTracking',
times: number[],
scale: number,
+ scaled: 'slowed' | 'quick' = 'slowed',
): Promise<{base: number; slowed: number}[]> {
return page.evaluate(
- async ({role, times, scale, travel}) => {
- const boxes = ['base', 'slowed'].map(
+ async ({role, times, scale, travel, scaled}) => {
+ const boxes = ['base', scaled].map(
id => document.getElementById(id) as HTMLElement,
);
const handles = boxes.map(box =>
@@ -108,7 +112,7 @@ async function travels(
return {base: xOf(boxes[0]), slowed: xOf(boxes[1])};
});
},
- {role, times, scale, travel: TRAVEL},
+ {role, times, scale, travel: TRAVEL, scaled},
);
}
@@ -126,6 +130,24 @@ test.describe('the springs follow the theme tempo (spec:AST-108 FR3)', () => {
}
});
+ test('a page that imports only the springs and the engine, with no register call, plays settle at 0.75 and 1.5 × t', async ({
+ page,
+ }) => {
+ // A page whose only motion is one spring role, as a Lightbox is.
+ for (const [scaled, scale] of [
+ ['slowed', 1.5],
+ ['quick', 0.75],
+ ] as const) {
+ await openScopes(page, {register: false});
+ const read = await travels(page, 'settle', [40, 120, 240], scale, scaled);
+ expect(read[0].base).toBeGreaterThan(5);
+ expect(read[0].base).toBeLessThan(TRAVEL - 5);
+ for (const {base, slowed} of read) {
+ expect(Math.abs(slowed - base), scaled).toBeLessThan(1.5);
+ }
+ }
+ });
+
test('finger tracking plays as measured inside the scope (FR4)', async ({
page,
}) => {
diff --git a/packages/core/src/motion/animator.ts b/packages/core/src/motion/animator.ts
index 9eb2f81cd3..2f46072797 100644
--- a/packages/core/src/motion/animator.ts
+++ b/packages/core/src/motion/animator.ts
@@ -153,9 +153,9 @@
* release (`touchRelease`) and at once elsewhere (DR2, DR3).
*
* Roles: every spring and curve the animator plays passes through
- * resolveMotion.ts, which names the motion role it plays (`springs.settle`
- * once `registerSpringsTable()` has run, the Reduce Motion fade's curve,
- * which the animator registers alone). The per-role tables stay internal
+ * resolveMotion.ts, which names the motion role it plays. `springs.settle`
+ * registers as its module loads, and the animator registers the Reduce Motion
+ * fade's curve alone. The per-role tables stay internal
* (`spec:AST-094` DEC-15), so a role plays its table value: nothing reads a
* role's own CSS variable. Its time scales by the tempo of the element's
* theme. A spring written inline at the call
diff --git a/packages/core/src/motion/roles.ts b/packages/core/src/motion/roles.ts
index f3a6d6d3cb..9d0ba5f9d0 100644
--- a/packages/core/src/motion/roles.ts
+++ b/packages/core/src/motion/roles.ts
@@ -159,6 +159,35 @@ export function registerMotionTable(
walk(table as Record<string, unknown>, id);
}
+/**
+ * Registers `leaf` as the spring role `id` (a table path such as
+ * `springs.settle`) and returns it, so a table row can register itself. A row
+ * that calls it under a pure annotation drops out of a bundle that does not
+ * use it, call included. Registering the same leaf under the same id again
+ * does nothing.
+ */
+export function registerSpringRole<T extends SpringDescription>(
+ id: string,
+ leaf: T,
+): T {
+ if (!isMotionRoleId(id)) {
+ throw new Error(
+ `motion role "${id}" must be a dotted table path such as "springs.settle"`,
+ );
+ }
+ if (roleOfLeaf.get(leaf)?.id !== id) {
+ const role: MotionRole = {
+ id,
+ kind: 'spring',
+ variable: motionRoleVariable(id),
+ value: leaf,
+ };
+ rolesById.set(id, role);
+ roleOfLeaf.set(leaf, role);
+ }
+ return leaf;
+}
+
/** The role a spring or curve leaf of a registered table plays, if any. */
export function motionRoleOf(leaf: unknown): MotionRole | undefined {
return leaf !== null && typeof leaf === 'object'
diff --git a/packages/core/src/motion/uikit/navigation.ts b/packages/core/src/motion/uikit/navigation.ts
index 4d4a7eebcf..eaecce705c 100644
--- a/packages/core/src/motion/uikit/navigation.ts
+++ b/packages/core/src/motion/uikit/navigation.ts
@@ -76,8 +76,12 @@ export const navigation = {
/**
* Registers this table with the motion registry (motion/roles.ts). It lists
* no role: spec:AST-094 FR4 names none of its values, so each plays as
- * measured. Nothing registers on import, and a second call does nothing.
+ * measured. A page that plays no navigation motion ships no navigation
+ * registry. The module registers its own table at import (one idempotent
+ * in-memory write, no DOM).
*/
export function registerNavigationTable(): void {
registerMotionTable('navigation', navigation);
}
+
+registerNavigationTable();
diff --git a/packages/core/src/motion/uikit/paging.ts b/packages/core/src/motion/uikit/paging.ts
index e4109c88f8..197c77faff 100644
--- a/packages/core/src/motion/uikit/paging.ts
+++ b/packages/core/src/motion/uikit/paging.ts
@@ -183,7 +183,8 @@ export const paging = {
* then reads `setContentOffset(_:animated:)`'s duration and curve through
* `resolveMotion`, as it reads every touch motion. The table lists no role,
* because no motion role names any of its values, so each plays as measured.
- * Nothing registers on import, and a second call does nothing.
+ * A page that plays no paging motion ships no paging registry. The module
+ * registers its own table at import (one idempotent in-memory write, no DOM).
*/
export function registerPagingTable(): void {
registerMotionTable('paging', paging, {
@@ -191,3 +192,5 @@ export function registerPagingTable(): void {
exclude: ['catchStopMs'],
});
}
+
+registerPagingTable();
diff --git a/packages/core/src/motion/uikit/picker.ts b/packages/core/src/motion/uikit/picker.ts
index e9c7015349..5ef450013e 100644
--- a/packages/core/src/motion/uikit/picker.ts
+++ b/packages/core/src/motion/uikit/picker.ts
@@ -108,9 +108,12 @@ export const picker = {
* Registers the tap spin's duration as an internal motion role,
* `picker.tapSpin.durationMs`. Every other value stays an internal measured
* constant. The tap spin's curve is the shared role `timing.curves.move`, and
- * the bounce at an end is `scroll.bounce`. Nothing registers on import, and
- * registering again does nothing.
+ * the bounce at an end is `scroll.bounce`. A page that plays no picker motion
+ * ships no picker registry. The module registers its own table at import (one
+ * idempotent in-memory write, no DOM).
*/
export function registerPickerTable(): void {
registerMotionTable('picker', picker, {roles: ['tapSpin.durationMs']});
}
+
+registerPickerTable();
diff --git a/packages/core/src/motion/uikit/selfRegistration.test.ts b/packages/core/src/motion/uikit/selfRegistration.test.ts
new file mode 100644
index 0000000000..eeb001a04e
--- /dev/null
+++ b/packages/core/src/motion/uikit/selfRegistration.test.ts
@@ -0,0 +1,96 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file selfRegistration.test.ts
+ * @input vitest (jsdom); each touch table imported in a fresh module graph,
+ * with no call to its register function
+ * @output Checks that each spring role row, and the navigation, paging and
+ * picker tables, register at import, so a role plays at the theme's tempo
+ * @position Testing; validates uikit/springs.ts, navigation.ts, paging.ts and
+ * picker.ts
+ */
+
+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';
+
+const TEMPO_PROPERTY = '--_astryx-motion-tempo';
+/** The tempo the stubbed theme writes; empty where no theme sets one. */
+let tempo = '';
+
+beforeEach(() => {
+ vi.resetModules();
+ tempo = '';
+ vi.spyOn(window, 'getComputedStyle').mockImplementation(
+ () =>
+ ({
+ getPropertyValue: (name: string) =>
+ name === TEMPO_PROPERTY ? tempo : '',
+ }) as unknown as CSSStyleDeclaration,
+ );
+});
+
+afterEach(() => {
+ vi.doUnmock('../roles');
+ vi.restoreAllMocks();
+ document.body.innerHTML = '';
+});
+
+function element(): HTMLElement {
+ const child = document.createElement('div');
+ document.body.append(child);
+ return child;
+}
+
+describe('the touch tables register at import', () => {
+ it('a page that imports only the settle row plays it at the tempo', async () => {
+ const {SETTLE_SPRING} = await import('./springs');
+ const {resolveMotion} = await import('../resolveMotion');
+ const {solveSpring, toSpring} = await import('../spring');
+ const target = element();
+ const base = solveSpring(toSpring(SETTLE_SPRING), {from: 0, to: 1});
+ for (const scale of [0.75, 1.5]) {
+ tempo = String(scale);
+ const played = solveSpring(
+ toSpring(resolveMotion(target, SETTLE_SPRING)),
+ {from: 0, to: 1},
+ );
+ expect(played.settleTime(0.001)).toBeCloseTo(
+ base.settleTime(0.001) * scale,
+ 6,
+ );
+ }
+ });
+
+ it('a page that imports only the picker plays its tap spin at the tempo', async () => {
+ const {picker} = await import('./picker');
+ const {resolveMotion} = await import('../resolveMotion');
+ tempo = '1.5';
+ expect(resolveMotion(element(), picker.tapSpin, 'durationMs')).toBe(
+ picker.tapSpin.durationMs * 1.5,
+ );
+ });
+
+ it('each role row and table registers itself, at import', async () => {
+ const registered: string[] = [];
+ vi.doMock('../roles', async importOriginal => {
+ const actual = await importOriginal<typeof import('../roles')>();
+ return {
+ ...actual,
+ registerMotionTable: (
+ ...args: Parameters<typeof actual.registerMotionTable>
+ ) => {
+ registered.push(args[0]);
+ actual.registerMotionTable(...args);
+ },
+ };
+ });
+ const {SETTLE_SPRING, KEYBOARD_SPRING} = await import('./springs');
+ await import('./navigation');
+ await import('./paging');
+ await import('./picker');
+ const {motionRoleOf} = await import('../roles');
+ expect(motionRoleOf(SETTLE_SPRING)?.id).toBe('springs.settle');
+ // The keyboard's spring is a measured constant, not a role.
+ expect(motionRoleOf(KEYBOARD_SPRING)).toBeUndefined();
+ expect(registered).toEqual(['navigation', 'paging', 'picker']);
+ });
+});
diff --git a/packages/core/src/motion/uikit/springs.ts b/packages/core/src/motion/uikit/springs.ts
index b6088f8d75..5bdd5e6c4f 100644
--- a/packages/core/src/motion/uikit/springs.ts
+++ b/packages/core/src/motion/uikit/springs.ts
@@ -27,7 +27,19 @@
* - /packages/core/src/motion/MEASUREMENTS.md (measurement tasks)
*/
-import {registerMotionTable} from '../roles';
+import {registerMotionTable, registerSpringRole} from '../roles';
+import type {SpringDescription} from '../spring';
+
+/**
+ * Registers the row as the role `springs.<name>` and returns it. A page that
+ * plays no spring ships no springs registry. Each spring role registers
+ * itself when the module that plays it loads (one idempotent in-memory write,
+ * no DOM). Write each call with the pure annotation, so a bundle that does
+ * not use the row drops the call.
+ */
+function springRole<T extends SpringDescription>(name: string, spring: T): T {
+ return registerSpringRole(`springs.${name}`, spring);
+}
// ---------------------------------------------------------------------
// Sourced presets
@@ -38,49 +50,67 @@ import {registerMotionTable} from '../roles';
* `.spring(duration:bounce:)` defaults.
* @source apple-docs https://developer.apple.com/documentation/swiftui/spring/smooth(duration:extrabounce:)
*/
-export const SETTLE_SPRING = {duration: 0.5, bounce: 0} as const;
+export const SETTLE_SPRING = /* @__PURE__ */ springRole('settle', {
+ duration: 0.5,
+ bounce: 0,
+} as const);
/**
* SwiftUI `.snappy`: "small amount of bounce", base bounce 0.15.
* @source apple-docs https://developer.apple.com/documentation/swiftui/spring/snappy(duration:extrabounce:)
*/
-export const QUICK_CHANGE_SPRING = {duration: 0.5, bounce: 0.15} as const;
+export const QUICK_CHANGE_SPRING = /* @__PURE__ */ springRole('quickChange', {
+ duration: 0.5,
+ bounce: 0.15,
+} as const);
/**
* SwiftUI `.bouncy`: base bounce 0.3.
* @source apple-docs https://developer.apple.com/documentation/swiftui/spring/bouncy(duration:extrabounce:)
*/
-export const EMPHASIS_SPRING = {duration: 0.5, bounce: 0.3} as const;
+export const EMPHASIS_SPRING = /* @__PURE__ */ springRole('emphasis', {
+ duration: 0.5,
+ bounce: 0.3,
+} as const);
/**
* SwiftUI `interactiveSpring()` defaults: for a value that tracks a finger.
* @source apple-docs https://developer.apple.com/documentation/swiftui/animation/interactivespring(response:dampingfraction:blendduration:)
*/
-export const FINGER_TRACKING_SPRING = {
- response: 0.15,
- dampingRatio: 0.86,
-} as const;
+export const FINGER_TRACKING_SPRING = /* @__PURE__ */ springRole(
+ 'fingerTracking',
+ {
+ response: 0.15,
+ dampingRatio: 0.86,
+ } as const,
+);
/**
* SwiftUI `Animation.default` since iOS 17 (what `withAnimation` uses).
* @source apple-docs https://developer.apple.com/documentation/swiftui/animation/default
*/
-export const STATE_CHANGE_SPRING = {response: 0.55, dampingRatio: 1} as const;
+export const STATE_CHANGE_SPRING = /* @__PURE__ */ springRole('stateChange', {
+ response: 0.55,
+ dampingRatio: 1,
+} as const);
/**
* SwiftUI `.spring(response:dampingFraction:blendDuration:)` defaults.
* @source apple-docs https://developer.apple.com/documentation/swiftui/animation/spring(response:dampingfraction:blendduration:)
*/
-export const DIRECT_CHANGE_SPRING = {
+export const DIRECT_CHANGE_SPRING = /* @__PURE__ */ springRole('directChange', {
response: 0.5,
dampingRatio: 0.825,
-} as const;
+} as const);
/**
* UIKit `UIView.animate(springDuration:bounce:…)` defaults (iOS 17).
* @source apple-docs https://developer.apple.com/documentation/uikit/uiview/animate(springduration:bounce:initialspringvelocity:delay:options:animations:completion:)
*/
-export const TIMED_CHANGE_SPRING = {duration: 0.5, bounce: 0} as const;
+export const TIMED_CHANGE_SPRING = /* @__PURE__ */ springRole('timedChange', {
+ duration: 0.5,
+ bounce: 0,
+} as const);
/**
* UIKit's default spring, `UISpringTimingParameters()`: Apple documents
@@ -97,11 +127,11 @@ export const TIMED_CHANGE_SPRING = {duration: 0.5, bounce: 0} as const;
* `UIView.animate` with curve 7 outside the keyboard is this spring with
* its duration forced to 0.5 s
*/
-export const VIEW_CHANGE_SPRING = {
+export const VIEW_CHANGE_SPRING = /* @__PURE__ */ springRole('viewChange', {
mass: 3,
stiffness: 1000,
damping: 500,
-} as const;
+} as const);
// ---------------------------------------------------------------------
// Navigation (UINavigationController)
@@ -280,14 +310,20 @@ export const ACTION_SHEET_DISMISS_SPRING = {
* iPhone 17 Pro, `_animateUsingSpringWithDampingRatio:response:tracking:`
* hooked (0.8, 0.32, tracking), Oct 23 2026
*/
-export const MENU_OPEN_SPRING = {response: 0.32, dampingRatio: 0.8} as const;
+export const MENU_OPEN_SPRING = /* @__PURE__ */ springRole('menuOpen', {
+ response: 0.32,
+ dampingRatio: 0.8,
+} as const);
/**
* UIMenu closing (a tap outside).
* @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
* iPhone 17 Pro, the same hook (0.85, 0.35, not tracking), Oct 23 2026
*/
-export const MENU_CLOSE_SPRING = {response: 0.35, dampingRatio: 0.85} as const;
+export const MENU_CLOSE_SPRING = /* @__PURE__ */ springRole('menuClose', {
+ response: 0.35,
+ dampingRatio: 0.85,
+} as const);
/**
* A sub-menu opening in place (its row tapped on a phone): a card laid over
@@ -308,10 +344,10 @@ export const MENU_CLOSE_SPRING = {response: 0.35, dampingRatio: 0.85} as const;
* It fits the box's eleven frames to 0.12 pt rms of the 99 pt travel
* (start 89.5 ms), as a free single-spring fit does (0.86, 0.395)
*/
-export const SUB_MENU_OPEN_SPRING = {
+export const SUB_MENU_OPEN_SPRING = /* @__PURE__ */ springRole('subMenuOpen', {
response: 0.4,
dampingRatio: 0.85,
-} as const;
+} as const);
/**
* Back out of a sub-menu (its header tapped): the card shrinks back up into
@@ -330,7 +366,10 @@ export const SUB_MENU_OPEN_SPRING = {
* frames to 0.28 pt rms of the 99 pt travel (start 111 ms), the opacity to
* 0.0055 rms
*/
-export const SUB_MENU_BACK_SPRING = {response: 0.4, dampingRatio: 1} as const;
+export const SUB_MENU_BACK_SPRING = /* @__PURE__ */ springRole('subMenuBack', {
+ response: 0.4,
+ dampingRatio: 1,
+} as const);
/**
* Context menu (UIContextMenuInteraction): the preview lifting once the
@@ -338,20 +377,26 @@ export const SUB_MENU_BACK_SPRING = {response: 0.4, dampingRatio: 1} as const;
* @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
* iPhone 17 Pro, the same hook (0.8, 0.32, tracking), Oct 23 2026
*/
-export const CONTEXT_MENU_LIFT_SPRING = {
- response: 0.32,
- dampingRatio: 0.8,
-} as const;
+export const CONTEXT_MENU_LIFT_SPRING = /* @__PURE__ */ springRole(
+ 'contextMenuLift',
+ {
+ response: 0.32,
+ dampingRatio: 0.8,
+ } as const,
+);
/**
* Context menu dismissing (a tap outside).
* @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
* iPhone 17 Pro, the same hook (0.85, 0.35, not tracking), Oct 23 2026
*/
-export const CONTEXT_MENU_DISMISS_SPRING = {
- response: 0.35,
- dampingRatio: 0.85,
-} as const;
+export const CONTEXT_MENU_DISMISS_SPRING = /* @__PURE__ */ springRole(
+ 'contextMenuDismiss',
+ {
+ response: 0.35,
+ dampingRatio: 0.85,
+ } as const,
+);
/**
* Context menu: the menu's entrance beside the lifted preview and the preview
@@ -363,10 +408,13 @@ export const CONTEXT_MENU_DISMISS_SPRING = {
* preview shadow's opacity each fit (0.30, 0.80), rms ≤ 0.001; the issued
* UIViewSpringAnimationBehaviorSettings are (0.8, 0.3)
*/
-export const CONTEXT_MENU_MORPH_SPRING = {
- response: 0.3,
- dampingRatio: 0.8,
-} as const;
+export const CONTEXT_MENU_MORPH_SPRING = /* @__PURE__ */ springRole(
+ 'contextMenuMorph',
+ {
+ response: 0.3,
+ dampingRatio: 0.8,
+ } as const,
+);
/**
* What UIKit plays for a menu with Reduce Motion on: critically damped,
@@ -435,7 +483,10 @@ export const BANNER_SPRING = {mass: 3, stiffness: 1000, damping: 500} as const;
* damping ratio 1. Four releases fit it per frame (the UIKit slider
* table). Oct 23 2026
*/
-export const SLIDER_RELEASE_SPRING = {response: 0.4, dampingRatio: 1} as const;
+export const SLIDER_RELEASE_SPRING = /* @__PURE__ */ springRole(
+ 'sliderRelease',
+ {response: 0.4, dampingRatio: 1} as const,
+);
/**
* UISlider's lift: a finger's touch-down scales the thumb up on this spring.
@@ -443,7 +494,10 @@ export const SLIDER_RELEASE_SPRING = {response: 0.4, dampingRatio: 1} as const;
* thumb's scale per frame after touch-down (the UIKit slider table).
* Oct 23 2026
*/
-export const SLIDER_LIFT_SPRING = {response: 0.215, dampingRatio: 0.6} as const;
+export const SLIDER_LIFT_SPRING = /* @__PURE__ */ springRole('sliderLift', {
+ response: 0.215,
+ dampingRatio: 0.6,
+} as const);
/**
* UISlider's drop: the lift's end scales the thumb back down on this spring.
@@ -451,7 +505,10 @@ export const SLIDER_LIFT_SPRING = {response: 0.215, dampingRatio: 0.6} as const;
* thumb's scale per frame after the lift (the UIKit slider table).
* Oct 23 2026
*/
-export const SLIDER_DROP_SPRING = {response: 0.5, dampingRatio: 0.7} as const;
+export const SLIDER_DROP_SPRING = /* @__PURE__ */ springRole('sliderDrop', {
+ response: 0.5,
+ dampingRatio: 0.7,
+} as const);
/**
* Every spring above, by row name: the table the existing readers use. A
@@ -527,9 +584,9 @@ const SPRING_ROLES = {
* Registers the role springs (`SPRING_ROLES`) as internal motion roles
* (motion/roles.ts), by their row names (`springs.settle`). Every other
* spring, UIKit's menu spring under Reduce Motion and the keyboard's
- * included, is not a role. Nothing registers on import: the touch code that
- * plays a role calls it once (it is idempotent), so a page that never does
- * ships no registry.
+ * included, is not a role. Each role row registers itself when it loads, so
+ * a call registers nothing new. A call still puts all 18 role rows in the
+ * caller's bundle.
*/
export function registerSpringsTable(): void {
registerMotionTable('springs', SPRING_ROLES, {
diff --git a/packages/core/src/motion/uikit/uikit.test.ts b/packages/core/src/motion/uikit/uikit.test.ts
index 495cd82070..c540195164 100644
--- a/packages/core/src/motion/uikit/uikit.test.ts
+++ b/packages/core/src/motion/uikit/uikit.test.ts
@@ -71,7 +71,12 @@ function leavesOf(file: string): Leaf[] {
// of them is checked where it is declared.
const exported = new Set<string>();
lines.forEach((line, index) => {
- const match = /^export const (\w+) = \{/.exec(line);
+ // A spring role row is built by `springRole(name, {...})`, which
+ // registers it as it loads.
+ const match =
+ /^export const (\w+) = (?:\{|\/\* @__PURE__ \*\/ springRole\()/.exec(
+ line,
+ );
if (match == null) {
return;
}