Skip to content

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

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

/**
 * @file useAnimator.test.tsx
 * @input vitest (jsdom), React Testing Library, the public hook and factory
 * @output Checks `spec:AST-107` FR3 and FR6 for the hook. `useAnimator(ref)`
 *   takes the caller's element ref and returns one animator, the factory's
 *   handle and nothing more. An animator used before its element mounts does
 *   nothing and resolves at once. It follows the element behind the ref when
 *   the node is replaced, and the new node starts at rest. An unmount drops
 *   the values, and a remount starts at rest.
 *   Another hook can share the element through the same ref. Animating causes
 *   no re-render, and the hook module has no behavior of its own.
 * @position Testing; validates useAnimator.ts
 */

import fs from 'node:fs';
import path from 'node:path';
import {act, render} from '@testing-library/react';
import {useEffect, useRef} from 'react';
import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';
import type {AnimatorHandle} from '../animator/createAnimator';
import {useAnimator} from './useAnimator';

beforeEach(() => {
  HTMLElement.prototype.animate = function () {
    return {
      startTime: null,
      playState: 'running',
      ready: new Promise(() => {}),
      cancel: vi.fn(),
    } as unknown as Animation;
  };
});

afterEach(() => {
  Reflect.deleteProperty(HTMLElement.prototype, 'animate');
});

function Probe({
  box,
  onRender,
  show = true,
}: {
  box: {current: AnimatorHandle | null};
  onRender?: () => void;
  show?: boolean;
}) {
  const ref = useRef<HTMLDivElement>(null);
  const animator = useAnimator(ref);
  box.current = animator;
  onRender?.();
  return show ? <div data-testid="target" ref={ref} /> : null;
}

describe('useAnimator', () => {
  it('takes the element ref and returns one animator for the component\u2019s lifetime, and never re-renders while animating', () => {
    const animators = new Set<AnimatorHandle>();
    let renders = 0;
    function Counter({label}: {label: string}) {
      const ref = useRef<HTMLButtonElement>(null);
      const animator = useAnimator(ref);
      animators.add(animator);
      renders += 1;
      return (
        <button
          type="button"
          ref={ref}
          onClick={() => void animator.animate({x: 20})}>
          {label}
        </button>
      );
    }
    const {getByRole, rerender} = render(<Counter label="Card" />);
    rerender(<Counter label="Card again" />);
    const after = renders;
    act(() => {
      getByRole('button').click();
    });
    expect(renders).toBe(after);
    expect(animators.size).toBe(1);
  });

  it('returns the handle\u2019s six methods, and nothing else: no ref and no destroy of its own', () => {
    const box: {current: AnimatorHandle | null} = {current: null};
    render(<Probe box={box} />);
    const animator = box.current!;
    expect(Object.keys(animator).sort()).toEqual(
      ['animate', 'decay', 'get', 'getVelocity', 'set', 'stop'].sort(),
    );
    for (const method of Object.keys(animator)) {
      expect(
        typeof (animator as unknown as Record<string, unknown>)[method],
      ).toBe('function');
    }
  });

  it('an animator used before its element mounts does nothing and resolves at once', async () => {
    const box: {current: AnimatorHandle | null} = {current: null};
    const {rerender, getByTestId} = render(<Probe box={box} show={false} />);
    const animator = box.current!;
    // Unattached: no element yet, so nothing happens and nothing throws.
    animator.set({x: 30, opacity: 0.4});
    animator.stop();
    expect(animator.get()).toMatchObject({x: 0, opacity: 1});
    let resolved = 0;
    await Promise.all([
      animator.animate({y: 10}).then(() => resolved++),
      animator.decay({x: 900}).then(() => resolved++),
    ]);
    expect(resolved).toBe(2);
    rerender(<Probe box={box} show />);
    const target = getByTestId('target');
    expect(animator.get()).toMatchObject({x: 0, y: 0, opacity: 1});
    // Attached, it works.
    animator.set({x: 30});
    expect(target.style.translate).toBe('30px 0px');
  });

  it('an unmount lets the element go and drops the values; a remount starts at rest', async () => {
    const box: {current: AnimatorHandle | null} = {current: null};
    const {rerender, getByTestId} = render(<Probe box={box} />);
    const animator = box.current!;
    animator.set({x: 12, rotate: 5});
    rerender(<Probe box={box} show={false} />);
    // With no element attached, a call does nothing.
    animator.set({x: 24});
    await act(async () => {
      await Promise.resolve();
    });
    expect(animator.get()).toMatchObject({x: 0, rotate: 0});
    rerender(<Probe box={box} show />);
    expect(['', 'none', '0px 0px']).toContain(
      getByTestId('target').style.translate,
    );
    expect(['', 'none', '0deg']).toContain(getByTestId('target').style.rotate);
  });

  it('follows the element behind the ref when the node is replaced, and the new node starts at rest (architecture:react-component-runtime INV6)', () => {
    const box: {current: AnimatorHandle | null} = {current: null};
    function Swapped({id}: {id: string}) {
      const ref = useRef<HTMLDivElement>(null);
      const animator = useAnimator(ref);
      box.current = animator;
      return <div key={id} data-testid={id} ref={ref} />;
    }
    const {rerender, getByTestId} = render(<Swapped id="first" />);
    const animator = box.current!;
    animator.set({x: 8});
    expect(getByTestId('first').style.translate).toBe('8px 0px');
    rerender(<Swapped id="second" />);
    // The new node starts at rest, and the next call moves it.
    expect(['', 'none', '0px 0px']).toContain(
      getByTestId('second').style.translate,
    );
    animator.set({x: 16});
    expect(getByTestId('second').style.translate).toBe('16px 0px');
  });

  it('shares its element with another hook through the same ref: a drag and an animation on one element', () => {
    const box: {current: AnimatorHandle | null} = {current: null};
    let seen: Element | null = null;
    function Shared() {
      const ref = useRef<HTMLDivElement>(null);
      const animator = useAnimator(ref);
      box.current = animator;
      // Another hook reads the same ref, as a gesture hook does.
      useEffect(() => {
        seen = ref.current;
      });
      return <div data-testid="shared" ref={ref} />;
    }
    const {getByTestId} = render(<Shared />);
    expect(seen).toBe(getByTestId('shared'));
    box.current!.set({y: 4});
    expect(getByTestId('shared').style.translate).toBe('0px 4px');
  });

  it('delegates entirely to the factory: the hook module holds no behavior of its own', () => {
    const source = fs.readFileSync(
      path.join(__dirname, 'useAnimator.ts'),
      'utf8',
    );
    const imports = [...source.matchAll(/from '([^']+)'/g)].map(m => m[1]);
    expect(imports.sort()).toEqual([
      '../animator/createAnimator',
      './useAttachment',
      'react',
    ]);
    // One construction, the factory's. The hook only wires the caller's ref
    // to it, through the attach lifecycle the gesture hooks share.
    expect(source).toContain('createAttachableAnimator()');
    expect(source).toContain('useAttachment(ref, attach, null)');
    expect(source).not.toMatch(/\bmotion\//);
  });
});