An open source design system that's fully customizable and agent ready
TypeScript
// 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, type Animator, type MotionCurve} from './animator';
import {solveDecay} from './decay';
import {resolveMotion} from './resolveMotion';
import {solveSpring, toSpring, type SpringDescription} from './spring';
import {registerScrollTable, scroll} from './uikit/scroll';
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, which plays its table value
* (it is not a motion role: `spec:AST-094` FR4 lists no scroll spring).
*/
bounce?: SpringDescription;
/**
* The release time on the document timeline (ms, `performance.now()`
* clock); now by default. Pass the same `at` to `decay`.
*/
at?: number;
}
/** A curve that holds `end` from `duration` on. */
function settling(
duration: number,
end: number,
at: (t: number) => number,
velocity: (t: number) => number,
): MotionCurve {
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: Animator,
velocity: {readonly x?: number; readonly y?: number},
options: CoastOptions = {},
): Partial<Record<'x' | 'y', MotionCurve>> {
const velocities: Partial<Record<'x' | 'y', number>> = {};
for (const key of ['x', 'y'] as const) {
const value = velocity[key];
if (value != null && Number.isFinite(value)) {
velocities[key] = value;
}
}
const rate = options.rate ?? scroll.decelerationRate.normal;
registerScrollTable();
const bounce = toSpring(
resolveMotion(animator.element, options.bounce ?? scroll.bounce),
);
const curves: Partial<Record<'x' | 'y', MotionCurve>> = {};
for (const [key, v0] of Object.entries(velocities) as ['x' | 'y', number][]) {
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;
}