Skip to content

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

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

/**
 * @file themeTiming.test.ts
 * @input vitest (jsdom), themeTiming's readers and easedProgress, the
 *   theme's duration and easing defaults
 * @output Checks how a motion reads its timing: from the element's own
 *   transition, and from tokens set where the element is or at their
 *   defaults. A default that refers to a token reads it there. Also checks
 *   the values that give no curve, the progress velocity and easedProgress's
 *   curve, and that a jump in an easing carries no speed. jsdom resolves no
 *   `calc()` and plays no `linear()` or `steps()`: a stand-in plays one, and
 *   the browser proof covers both.
 * @position Testing; validates themeTiming.ts
 */

import {afterEach, describe, expect, it} from 'vitest';
import {cubicBezier} from './bezier';
import {parseCssEasing} from './roles';
import {
  declaredTimingTokens,
  easedProgress,
  readThemeTiming,
  readThemeTokens,
  resolveTiming,
  type ThemeTimingTokens,
} from './themeTiming';
import {durationDefaults, easeDefaults} from '../theme/tokens.stylex';

const FAST: ThemeTimingTokens = {
  duration: '--duration-fast',
  easing: '--ease-standard',
};

const standardEase = cubicBezier(
  parseCssEasing(easeDefaults['--ease-standard'])!,
);

function element(styles: Record<string, string> = {}): HTMLElement {
  const node = document.createElement('div');
  for (const [name, value] of Object.entries(styles)) {
    node.style.setProperty(name, value);
  }
  document.body.appendChild(node);
  return node;
}

describe('declaredTimingTokens', () => {
  it('declares every timing token as the token file does', () => {
    expect(declaredTimingTokens).toEqual({
      ...durationDefaults,
      ...easeDefaults,
    });
  });
});

describe('readThemeTiming', () => {
  afterEach(() => {
    document.body.replaceChildren();
  });

  it('reads the element\u2019s own transition with no tokens', () => {
    const timing = readThemeTiming(
      element({
        'transition-duration': '0.3s, 1s',
        'transition-timing-function': 'linear, ease-in',
      }),
    )!;
    expect(timing.duration).toBeCloseTo(0.3, 6);
    expect(timing.at(0.15)).toBeCloseTo(0.5, 6);
    expect(readThemeTiming(element())).toBe(null);
  });

  it('reads tokens set where the element is, in ms or s', () => {
    const seconds = readThemeTiming(
      element({'--duration-fast': '0.3s', '--ease-standard': 'linear'}),
      FAST,
    )!;
    expect(seconds.duration).toBeCloseTo(0.3, 6);
    expect(seconds.at(0.15)).toBeCloseTo(0.5, 6);
    const ms = readThemeTiming(element({'--duration-fast': '250ms'}), FAST)!;
    expect(ms.duration).toBeCloseTo(0.25, 6);
    expect(document.body.children).toHaveLength(2);
  });

  it('reads a token with no value on the element at the default core declares', () => {
    const timing = readThemeTiming(element(), FAST)!;
    expect(timing.duration).toBeCloseTo(0.175, 6);
    expect(timing.at(0.0875)).toBeCloseTo(standardEase(0.5), 6);
    expect(timing.at(0.175)).toBe(1);
  });

  it('reads --duration-exit with no value at its declared default, var(--duration-fast), resolved where the element is', () => {
    const exit: ThemeTimingTokens = {
      duration: '--duration-exit',
      easing: '--ease-exit',
    };
    expect(readThemeTiming(element(), exit)?.duration).toBeCloseTo(0.175, 6);
    expect(
      readThemeTokens(element({'--duration-fast': '250ms'}), {
        duration: '--duration-exit',
      }),
    ).toEqual({ms: 250, points: null});
    expect(readThemeTokens(element({'--duration-exit': '90ms'}), exit).ms).toBe(
      90,
    );
  });

  it('gives the progress velocity per second, and none once the motion ends', () => {
    const timing = readThemeTiming(
      element({'--duration-fast': '0.3s', '--ease-standard': 'linear'}),
      FAST,
    )!;
    expect(timing.velocity(0)).toBeCloseTo(1 / 0.3, 4);
    expect(timing.velocity(0.15)).toBeCloseTo(1 / 0.3, 4);
    expect(timing.velocity(0.3)).toBe(0);
    const eased = readThemeTiming(element(), {
      duration: '--duration-fast',
      easing: '--ease-exit',
    })!;
    const t = 0.05;
    const h = 1e-6;
    expect(eased.velocity(t)).toBeCloseTo(
      (eased.at(t + h) - eased.at(t - h)) / (2 * h),
      3,
    );
  });

  it('plays an easing that is not a cubic Bézier as the browser does, and a jump in it hands on no speed', () => {
    // jsdom has no Web Animations, so a stand-in plays steps(4, jump-end).
    class StandInEffect {
      time = 0;
      constructor(_target: null, _frames: null, timing: {easing: string}) {
        if (timing.easing !== 'steps(4, jump-end)') {
          throw new TypeError(timing.easing);
        }
      }
      getComputedTiming() {
        return {progress: Math.floor((4 * this.time) / 1000) / 4};
      }
    }
    class StandInAnimation {
      constructor(readonly effect: StandInEffect) {}
      set currentTime(ms: number) {
        this.effect.time = ms;
      }
    }
    const view = window as unknown as Record<string, unknown>;
    const before = {
      Animation: view.Animation,
      KeyframeEffect: view.KeyframeEffect,
    };
    Object.assign(view, {
      Animation: StandInAnimation,
      KeyframeEffect: StandInEffect,
    });
    try {
      const curve = readThemeTiming(
        element({'--ease-standard': 'steps(4, jump-end)'}),
        FAST,
      );
      // 175 ms at the default, so the jumps fall at 43.75, 87.5 and 131.25 ms.
      expect(curve?.duration).toBeCloseTo(0.175, 6);
      expect(curve?.at(0.05)).toBe(0.25);
      // A retarget at a jump inherits this speed.
      for (const t of [0.04375, 0.0875, 0.13125, 0.1749]) {
        expect(curve?.velocity(t), `${t} s`).toBe(0);
      }
    } finally {
      Object.assign(view, before);
    }
  });

  it('returns no curve for a duration that is not a positive length, or an easing it does not read', () => {
    expect(readThemeTiming(element({'--duration-fast': '0ms'}), FAST)).toBe(
      null,
    );
    expect(readThemeTiming(element({'--duration-fast': 'fast'}), FAST)).toBe(
      null,
    );
    expect(readThemeTiming(element({'--ease-standard': 'bounce'}), FAST)).toBe(
      null,
    );
    expect(readThemeTiming(element({'transition-duration': '0s'}))).toBe(null);
  });
});

describe('resolveTiming', () => {
  afterEach(() => {
    document.body.replaceChildren();
  });

  it('resolves a time of zero or more and a cubic Bézier, and null for anything else or a text left out', () => {
    const node = element();
    expect(
      resolveTiming(node, {duration: '0.3s', easing: 'ease-in-out'}),
    ).toEqual({ms: 300, points: [0.42, 0, 0.58, 1]});
    expect(resolveTiming(node, {duration: '0ms'}).ms).toBe(0);
    expect(resolveTiming(node, {duration: 'fast'}).ms).toBe(null);
    expect(resolveTiming(node, {duration: '-1ms'}).ms).toBe(null);
    expect(resolveTiming(node, {easing: 'steps(4)'}).points).toBe(null);
    expect(resolveTiming(node, {})).toEqual({ms: null, points: null});
    expect(document.body.children).toHaveLength(1);
  });
});

describe('easedProgress', () => {
  it('eases from 0 to 1 over its length, and a curve of no length is at its end', () => {
    const curve = easedProgress(0.2, x => x * x);
    expect(curve.duration).toBe(0.2);
    expect(curve.at(0)).toBe(0);
    expect(curve.at(0.1)).toBeCloseTo(0.25, 6);
    expect(curve.at(0.2)).toBe(1);
    expect(curve.velocity(0.1)).toBeCloseTo(5, 3);
    expect(curve.velocity(0.2)).toBe(0);
    const none = easedProgress(0, x => x);
    expect(none.at(0)).toBe(1);
    expect(none.velocity(0)).toBe(0);
  });

  it('with jumps, a jump carries no speed and a smooth stretch keeps its slope', () => {
    const steps = (x: number) => Math.floor(4 * x) / 4;
    // Without the option, the jump at a quarter of 300 ms reads as a spike.
    expect(easedProgress(0.3, steps).velocity(0.075)).toBeGreaterThan(100);
    const jumping = easedProgress(0.3, steps, {jumps: true});
    for (const t of [0, 0.0749, 0.075, 0.0751, 0.15, 0.225, 0.2995]) {
      expect(jumping.velocity(t), `${t} s`).toBe(0);
    }
    expect(
      easedProgress(0.2, x => x * x, {jumps: true}).velocity(0.1),
    ).toBeCloseTo(5, 1);
  });
});