An open source design system that's fully customizable and agent ready
TypeScript
// 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), and parseCssEasing for a
* CSS transition's easing
* @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,
type MotionCurvePoints,
type MotionRoleKind,
} from './roleValue';
import type {DurationBounce, SpringDescription} from './spring';
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;
}
const rolesById = new Map<string, MotionRole>();
/** A table id → the table registered under it. */
const tablesById = new Map<string, object>();
/** A spring or curve leaf → its role. */
const roleOfLeaf = new WeakMap<object, MotionRole>();
/** A table or one of its groups → its path. */
const pathOfGroup = new WeakMap<object, string>();
/** A table path → the role id it is registered under, when renamed. */
const roleIdOfPath = new Map<string, string>();
/**
* 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: string,
table: object,
{
roles = [],
exclude = [],
rename = {},
}: {
roles?: ReadonlyArray<string>;
exclude?: ReadonlyArray<string>;
rename?: Readonly<Record<string, string>>;
} = {},
): void {
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: Record<string, unknown>, prefix: string) => {
pathOfGroup.set(group, prefix);
for (const [key, value] of Object.entries(group)) {
const path = `${prefix}.${key}`;
if (skip.has(path)) {
continue;
}
let kind: MotionRoleKind | null = 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 as Record<string, unknown>, 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 as SpringDescription | number | MotionCurvePoints;
if (typeof leaf === 'object') {
const taken = roleOfLeaf.get(leaf);
if (taken != null && taken.id !== roleId) {
leaf = Object.freeze(Array.isArray(leaf) ? [...leaf] : {...leaf}) as
SpringDescription | MotionCurvePoints;
group[key] = leaf;
}
}
const role: MotionRole = {
id: roleId,
kind,
variable: motionRoleVariable(roleId),
value: leaf,
};
rolesById.set(roleId, role);
if (typeof leaf === 'object') {
roleOfLeaf.set(leaf, role);
}
}
};
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'
? 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: object,
key: string,
): MotionRole | undefined {
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: string): MotionRole | undefined {
return rolesById.get(id);
}
/** Every registered role, by id. */
export function listMotionRoles(): MotionRole[] {
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: 'spring',
text: string,
): DurationBounce | null;
export function parseMotionRoleValue(
kind: 'duration',
text: string,
): number | null;
export function parseMotionRoleValue(
kind: 'curve',
text: string,
): MotionCurvePoints | null;
export function parseMotionRoleValue(
kind: MotionRoleKind,
text: string,
): DurationBounce | number | MotionCurvePoints | null;
export function parseMotionRoleValue(
kind: MotionRoleKind,
text: string,
): DurationBounce | number | MotionCurvePoints | null {
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) as unknown as [
number,
number,
number,
number,
];
return points[0] >= 0 && points[0] <= 1 && points[2] >= 0 && points[2] <= 1
? points
: null;
}
/** The CSS easing keywords, as the control points CSS gives them. */
const EASING_KEYWORDS: Readonly<Record<string, MotionCurvePoints>> = {
linear: [0, 0, 1, 1],
ease: [0.25, 0.1, 0.25, 1],
'ease-in': [0.42, 0, 1, 1],
'ease-out': [0, 0, 0.58, 1],
'ease-in-out': [0.42, 0, 0.58, 1],
};
/**
* Reads a CSS easing, a keyword or a `cubic-bezier()`, as a curve role's value
* is read. Returns null for any other easing, such as `steps()`.
*/
export function parseCssEasing(text: string): MotionCurvePoints | null {
const value = text.trim();
return EASING_KEYWORDS[value] ?? parseMotionRoleValue('curve', value);
}