Skip to content

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

TypeScript
12.0 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

/**
 * @file roles.test.ts
 * @input roles.ts and the shared UIKit tables (registered by this test)
 * @output Proof that the registered roles are every role spec:AST-094 FR4
 *   names plus the ones the generated motion role table lists, each by its
 *   table path and each named by FR4 or a component's own record (DEC-5);
 *   that the generated table is in step with the registered tables; that
 *   every other table value, a component's measured spring included, is no
 *   role; and that a role's CSS value reads back as the same motion
 * @position Testing for /packages/core/src/motion/roles.ts
 */

import {spawnSync} from 'node:child_process';
import {readFileSync} from 'node:fs';
import {resolve} from 'node:path';
import {describe, expect, it} from 'vitest';
import {
  formatMotionRoleValue,
  isMotionRoleId,
  listMotionRoles,
  motionRoleIn,
  motionRoleOf,
  motionRoleVariable,
  parseCssEasing,
  parseMotionRoleValue,
  registerMotionTable,
} from './roles';
import {dampingRatioOf, naturalFrequency, toSpring} from './spring';
import {navigation, scroll, springs, timing} from './uikit';
import {
  motionTableFiles,
  REGISTER_EXPORT,
} from '../../../../scripts/motion-table-files.mjs';
import {
  fr4RoleIds,
  MOTION_ROLE_TABLE,
  tableRoleIds,
} from '../../../../scripts/motion-roles-table.mjs';

const ROOT = resolve(__dirname, '../../../..');

// Every table the role list is generated from, registered the way the
// generator does: through each module's register<Name>Table.
for (const file of motionTableFiles(resolve(__dirname, '..'))) {
  const module = (await import(file)) as Record<string, unknown>;
  for (const [name, value] of Object.entries(module)) {
    if (REGISTER_EXPORT.test(name) && typeof value === 'function') {
      (value as () => void)();
    }
  }
}
// The tables that discovery registered, before any test adds a fixture.
const DISCOVERED = new Set(
  listMotionRoles().map(role => role.id.split('.')[0]),
);
/** The roles of the tables discovery registered (tests here add fixtures). */
const discoveredRoles = () =>
  listMotionRoles().filter(role => DISCOVERED.has(role.id.split('.')[0]));

describe('motion roles', () => {
  it('names a role by its table path, and its CSS variable in kebab case', () => {
    expect(isMotionRoleId('sheet.present')).toBe(true);
    expect(isMotionRoleId('timing.curves.move')).toBe(true);
    expect(isMotionRoleId('sheet')).toBe(false);
    expect(isMotionRoleId('Sheet.present')).toBe(false);
    expect(motionRoleVariable('springs.sheetDetent')).toBe(
      '--motion-springs-sheet-detent',
    );
    expect(motionRoleVariable('timing.curves.move')).toBe(
      '--motion-timing-curves-move',
    );
    expect(() => motionRoleVariable('sheet')).toThrow(/dotted table path/);
  });

  it('leaves a table value FR4 does not name an internal constant', () => {
    const shared = {response: 0.4, dampingRatio: 0.9};
    const table = {
      present: shared,
      dismiss: shared,
      fadeMs: 200,
      curves: {out: [0, 0, 0.58, 1] as const},
    };
    registerMotionTable('fixture', table);
    // No role, no CSS variable, and the table is untouched.
    expect(motionRoleOf(table.present)).toBeUndefined();
    expect(table.dismiss).toBe(table.present);
    expect(motionRoleIn(table, 'fadeMs')).toBeUndefined();
    expect(motionRoleOf(table.curves.out)).toBeUndefined();
    expect(listMotionRoles().some(role => role.id.startsWith('fixture.'))).toBe(
      false,
    );
  });

  it('has every role spec:AST-094 FR4 names, and exactly the roles the generated motion role table lists', () => {
    const named = fr4RoleIds(
      readFileSync(
        resolve(ROOT, 'docs/specs/AST-094-touch-presentations/spec.md'),
        'utf8',
      ),
    );
    expect(named.length).toBeGreaterThan(0);
    const registered = new Set(discoveredRoles().map(role => role.id));
    for (const id of named) {
      expect(registered.has(id), id).toBe(true);
    }
    // FR4's roles and the ones a component's record measures (DEC-5).
    expect(registered).toEqual(
      new Set(
        tableRoleIds(readFileSync(resolve(ROOT, MOTION_ROLE_TABLE), 'utf8')),
      ),
    );
  });

  it('keeps the generated motion role table in step with the registered tables, each role named by FR4 or a component record (spec:AST-094 DEC-5)', () => {
    // The generator registers every table itself, in its own Node process:
    // it reads the knowledge records, which this environment cannot load.
    const run = spawnSync(
      process.execPath,
      [resolve(ROOT, 'scripts/generate-motion-roles.mjs'), '--check'],
      {cwd: ROOT, encoding: 'utf8'},
    );
    expect(run.stderr).toBe('');
    expect(run.status).toBe(0);
  });

  it('names the shared roles for their use, as spec:AST-094 FR4 does', () => {
    expect(
      [
        springs.fingerTracking,
        springs.emphasis,
        springs.settle,
        springs.quickChange,
        springs.viewChange,
        springs.timedChange,
        springs.stateChange,
        springs.directChange,
        springs.menuOpen,
        springs.menuClose,
        timing.curves.viewChange,
        timing.curves.exit,
        timing.curves.entrance,
        timing.curves.move,
      ].map(leaf => motionRoleOf(leaf)?.id),
    ).toEqual([
      'springs.fingerTracking',
      'springs.emphasis',
      'springs.settle',
      'springs.quickChange',
      'springs.viewChange',
      'springs.timedChange',
      'springs.stateChange',
      'springs.directChange',
      'springs.menuOpen',
      'springs.menuClose',
      'timing.curves.viewChange',
      'timing.curves.exit',
      'timing.curves.entrance',
      'timing.curves.move',
    ]);
    expect(motionRoleIn(timing, 'stateChangeMs')?.id).toBe(
      'timing.stateChangeMs',
    );
    // A preset or curve-shape name is no role id.
    for (const old of [
      'springs.smooth',
      'springs.bouncy',
      'timing.curves.easeInOut',
      'timing.implicitAnimationMs',
    ]) {
      expect(listMotionRoles().map(role => role.id)).not.toContain(old);
    }
  });

  it("leaves the keyboard's motion out: it rides the keyboard (FR4)", () => {
    expect(motionRoleOf(springs.keyboard)).toBeUndefined();
    expect(motionRoleIn(timing, 'keyboardNotificationMs')).toBeUndefined();
  });

  it('refuses a spring that never settles', () => {
    expect(() =>
      formatMotionRoleValue('spring', {duration: 0.5, bounce: 1}),
    ).toThrow(/must settle/);
    expect(() =>
      formatMotionRoleValue('spring', {response: 0.5, dampingRatio: 0}),
    ).toThrow(/must settle/);
    expect(parseMotionRoleValue('spring', '0.5s 1')).toBeNull();
  });

  it('makes the roles of the shared tables, and keeps every other value internal', () => {
    expect(motionRoleOf(springs.viewChange)?.id).toBe('springs.viewChange');
    expect(motionRoleOf(timing.curves.move)?.kind).toBe('curve');
    expect(motionRoleIn(timing, 'stateChangeMs')?.kind).toBe('duration');
    // A component's measured value is an internal constant, not a role.
    expect(motionRoleOf(springs.sheetPresent)).toBeUndefined();
    expect(springs.sheetPresent).toEqual(springs.viewChange);
    expect(motionRoleOf(scroll.bounce)).toBeUndefined();
    expect(motionRoleIn(timing.press, 'flashMs')).toBeUndefined();
    expect(motionRoleIn(navigation, 'transitionMs')).toBeUndefined();
    // The Reduced Motion fade, UIKit's menu spring under Reduce Motion, the
    // thresholds and the arbitration timings are not motion roles either.
    expect(motionRoleIn(timing, 'reducedMotionCrossFadeMs')).toBeUndefined();
    expect(motionRoleOf(springs.menuReducedMotion)).toBeUndefined();
    // Nor is the keyboard's motion: it rides the keyboard's own spring and
    // notification duration, not a role (spec:AST-094 FR4).
    expect(motionRoleIn(springs, 'keyboard')).toBeUndefined();
    expect(motionRoleIn(timing, 'keyboardNotificationMs')).toBeUndefined();
    expect(motionRoleIn(timing.press, 'scrollBrakeMs')).toBeUndefined();
    expect(motionRoleIn(scroll, 'delaysContentTouchesMs')).toBeUndefined();
    expect(motionRoleIn(navigation, 'parallax')).toBeUndefined();
    const ids = listMotionRoles().map(role => role.id);
    expect(ids.some(id => id.startsWith('gestures.'))).toBe(false);
    // Every role has its own CSS variable.
    const variables = listMotionRoles().map(role => role.variable);
    expect(new Set(variables).size).toBe(variables.length);
  });

  it('registers the roles spec:AST-094 FR4 names internally, each of its kind', () => {
    expect(
      Object.fromEntries(discoveredRoles().map(role => [role.id, role.kind])),
    ).toMatchObject({
      'segmented.selectionSpring': 'spring',
      'springs.contextMenuDismiss': 'spring',
      'springs.contextMenuLift': 'spring',
      'springs.contextMenuMorph': 'spring',
      'springs.directChange': 'spring',
      'springs.emphasis': 'spring',
      'springs.fingerTracking': 'spring',
      'springs.menuClose': 'spring',
      'springs.menuOpen': 'spring',
      'springs.quickChange': 'spring',
      'springs.settle': 'spring',
      'springs.stateChange': 'spring',
      'springs.subMenuBack': 'spring',
      'springs.subMenuOpen': 'spring',
      'springs.timedChange': 'spring',
      'springs.viewChange': 'spring',
      'timing.curves.entrance': 'curve',
      'timing.curves.exit': 'curve',
      'timing.curves.move': 'curve',
      'timing.curves.viewChange': 'curve',
      'timing.stateChangeMs': 'duration',
    });
  });

  it('writes every table value in CSS form and reads back the same motion', () => {
    for (const role of listMotionRoles()) {
      const text = formatMotionRoleValue(role.kind, role.value);
      const back = parseMotionRoleValue(role.kind, text);
      expect(back, `${role.id}: ${text}`).not.toBeNull();
      if (role.kind === 'spring') {
        const a = toSpring(role.value as Parameters<typeof toSpring>[0]);
        const b = toSpring(back as Parameters<typeof toSpring>[0]);
        expect(naturalFrequency(b) / naturalFrequency(a)).toBeCloseTo(1, 5);
        expect(dampingRatioOf(b)).toBeCloseTo(dampingRatioOf(a), 5);
      } else {
        expect(back).toEqual(role.value);
      }
    }
    expect(
      formatMotionRoleValue('spring', {response: 0.5, dampingRatio: 0.85}),
    ).toBe('0.5s 0.15');
    expect(formatMotionRoleValue('duration', 250)).toBe('250ms');
    expect(formatMotionRoleValue('curve', [0.42, 0, 0.58, 1])).toBe(
      'cubic-bezier(0.42, 0, 0.58, 1)',
    );
  });

  it('refuses invalid values and reads malformed CSS as unset', () => {
    expect(() => formatMotionRoleValue('duration', -1)).toThrow(/≥ 0/);
    expect(() => formatMotionRoleValue('curve', [2, 0, 0.5, 1])).toThrow(
      /x1 and x2/,
    );
    expect(() => formatMotionRoleValue('spring', {response: 0.5})).toThrow(
      /spring is/,
    );
    // A spring with no damping never settles.
    for (const never of [
      {duration: 0.5, bounce: 1},
      {duration: 0.5, bounce: 1.5},
      {response: 0.5, dampingRatio: 0},
      {mass: 1, stiffness: 100, damping: 0},
    ]) {
      expect(() => formatMotionRoleValue('spring', never)).toThrow(
        /must settle/,
      );
    }
    expect(parseMotionRoleValue('spring', '0.5s 1')).toBeNull();
    expect(parseMotionRoleValue('spring', '')).toBeNull();
    expect(parseMotionRoleValue('spring', 'fast')).toBeNull();
    expect(parseMotionRoleValue('spring', '0.4s 0.2')).toEqual({
      duration: 0.4,
      bounce: 0.2,
    });
    expect(parseMotionRoleValue('duration', ' 0.3s ')).toBe(300);
    expect(parseMotionRoleValue('curve', 'ease-in')).toBeNull();
  });
});

describe('parseCssEasing', () => {
  it('reads a keyword as the control points CSS gives it, and a cubic-bezier() as a curve role does', () => {
    expect(parseCssEasing('linear')).toEqual([0, 0, 1, 1]);
    expect(parseCssEasing(' ease-out ')).toEqual([0, 0, 0.58, 1]);
    expect(parseCssEasing('cubic-bezier(0.24, 1, 0.4, 1)')).toEqual([
      0.24, 1, 0.4, 1,
    ]);
  });

  it('gives null for an easing it cannot read as one curve', () => {
    expect(parseCssEasing('steps(4)')).toBeNull();
    expect(parseCssEasing('')).toBeNull();
    expect(parseCssEasing('cubic-bezier(2, 0, 0.5, 1)')).toBeNull();
  });
});