Skip to content

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

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

/**
 * @file presentation.test.ts
 * @input Uses vitest, React Testing Library, react-dom/server and a
 *   query-aware matchMedia and CSS.supports stub
 * @output A caller's explicit presentation wins: `'popover'` pins the fine
 *   surface and input modes on an iPhone; an omitted value follows the
 *   component's default (`'popover'` or `'touch'`), distinguishable from an
 *   explicit `'popover'`; `'adaptive'` and `'bottom-sheet'` keep their sheet
 *   meaning with touch modes under a finger, the same on every touch device;
 *   the surface equals useAdaptivePresentation's for every
 *   value on every device; live pointer changes; the server and hydrating
 *   render, which no hint can put into touch modes; the one-moment read
 * @position Unit tests of packages/core/src/utils/presentation.ts
 */

import {act, renderHook} from '@testing-library/react';
import {createElement, type ComponentProps, type ReactNode} from 'react';
import {hydrateRoot, type Root} from 'react-dom/client';
import {renderToString} from 'react-dom/server';
import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';
import {
  useAdaptivePresentation,
  type AdaptivePresentation,
} from '../hooks/useAdaptivePresentation';
import {
  readPresentation,
  usePresentation,
  type PresentationDefault,
  type UsePresentationOptions,
} from './presentation';
import {Theme, defineTheme} from '../theme';
import {IOS_SUPPORTS_QUERY} from './touchPresentation';
import {
  compactDefinition,
  DEFAULT_COMPACT_DEFINITION,
} from '../theme/themeAdaptations';

const device = {coarse: false, width: 1280, height: 800, iosWebKit: false};
const listeners = new Set<() => void>();

/** Answers a media query list: `,` is or, `and` is and. */
function answer(query: string): boolean {
  return query.split(', ').some(alternative =>
    alternative.split(' and ').every(part => {
      if (part === '(pointer: coarse)') {
        return device.coarse;
      }
      const range = /^\((width|height) < (\d+)px\)$/.exec(part);
      if (range != null) {
        return device[range[1] as 'width' | 'height'] < Number(range[2]);
      }
      throw new Error(`unexpected query ${query}`);
    }),
  );
}

function setDevice(next: Partial<typeof device>): void {
  Object.assign(device, next);
  for (const listener of [...listeners]) {
    listener();
  }
}

const IPHONE = {coarse: true, width: 393, height: 852, iosWebKit: true};
const IPAD = {coarse: true, width: 820, height: 1180, iosWebKit: true};
const ANDROID = {coarse: true, width: 412, height: 915, iosWebKit: false};
const DESKTOP = {coarse: false, width: 1280, height: 800, iosWebKit: false};
const MAC_SAFARI = {coarse: false, width: 1440, height: 900, iosWebKit: false};
/** A narrow window under a fine pointer: compact by size, never by touch. */
const FINE_NARROW = {coarse: false, width: 600, height: 800, iosWebKit: false};
/** A phone in landscape: compact by its height alone. */
const PHONE_LANDSCAPE = {
  coarse: true,
  width: 852,
  height: 393,
  iosWebKit: true,
};
/** The compact edges at the default md point (768 wide, 500 high). */
const COMPACT_EDGES = [
  {coarse: true, width: 767, height: 800, iosWebKit: false},
  {coarse: true, width: 768, height: 800, iosWebKit: false},
  {coarse: true, width: 1024, height: 499, iosWebKit: false},
  {coarse: true, width: 1024, height: 500, iosWebKit: false},
];

beforeEach(() => {
  setDevice(DESKTOP);
  vi.stubGlobal('CSS', {
    supports: (condition: string) =>
      condition === IOS_SUPPORTS_QUERY && device.iosWebKit,
  });
  vi.stubGlobal(
    'matchMedia',
    vi.fn((query: string) => ({
      get matches() {
        return answer(query);
      },
      media: query,
      addEventListener: (_type: string, listener: () => void) =>
        listeners.add(listener),
      removeEventListener: (_type: string, listener: () => void) =>
        listeners.delete(listener),
    })),
  );
});

afterEach(() => {
  listeners.clear();
  vi.unstubAllGlobals();
});

const resolve = (
  presentation: AdaptivePresentation | undefined,
  whenOmitted?: PresentationDefault,
) =>
  renderHook(() => usePresentation(presentation, {whenOmitted})).result.current;

/** A component whose omitted presentation is the touch default. */
const TOUCH_WHEN_OMITTED: UsePresentationOptions = {whenOmitted: 'touch'};

describe('presentation: a caller choice wins over touch defaults', () => {
  it('pins the fine surface and input modes with an explicit popover, even on an iPhone', () => {
    setDevice(IPHONE);
    for (const whenOmitted of ['popover', 'touch'] as const) {
      expect(resolve('popover', whenOmitted)).toEqual({
        surface: 'popover',
        touchModes: false,
      });
    }
  });

  it("tells an omitted value from an explicit popover: the component's touch default applies only when omitted", () => {
    setDevice(IPHONE);
    expect(resolve(undefined, 'touch')).toEqual({
      surface: 'popover',
      touchModes: true,
    });
    // Today's components: omitted is popover.
    expect(resolve(undefined)).toEqual(resolve('popover'));
    expect(resolve(undefined, 'popover')).toEqual(resolve('popover'));
  });

  it('turns touch modes on under a finger only, the same on every touch device', () => {
    setDevice(ANDROID);
    expect(resolve(undefined, 'touch')).toEqual({
      surface: 'popover',
      touchModes: true,
    });
    for (const desk of [DESKTOP, MAC_SAFARI]) {
      setDevice(desk);
      expect(resolve(undefined, 'touch')).toMatchObject({
        touchModes: false,
      });
    }
  });

  it('keeps the sheet meaning of adaptive and bottom-sheet, with touch modes under a finger', () => {
    setDevice(IPHONE);
    expect(resolve('adaptive')).toEqual({
      surface: 'bottom-sheet',
      touchModes: true,
    });
    setDevice(IPAD);
    expect(resolve('adaptive')).toMatchObject({
      surface: 'popover',
      touchModes: true,
    });
    setDevice(DESKTOP);
    expect(resolve('adaptive')).toMatchObject({
      surface: 'popover',
      touchModes: false,
    });
    expect(resolve('bottom-sheet')).toMatchObject({
      surface: 'bottom-sheet',
      touchModes: false,
    });
  });

  it("renders useAdaptivePresentation's surface for every value on every device", () => {
    for (const next of [
      IPHONE,
      IPAD,
      ANDROID,
      DESKTOP,
      MAC_SAFARI,
      FINE_NARROW,
      PHONE_LANDSCAPE,
      ...COMPACT_EDGES,
    ]) {
      setDevice(next);
      for (const value of ['popover', 'bottom-sheet', 'adaptive'] as const) {
        const {result} = renderHook(() => ({
          surface: usePresentation(value).surface,
          adaptive: useAdaptivePresentation(value),
        }));
        expect(result.current.surface).toBe(result.current.adaptive);
      }
    }
  });

  it("answers 'adaptive' with the sheet only on a compact touch screen: a fine narrow window, a phone in landscape and each compact edge (spec:AST-094 FR13, spec:AST-012 FR9)", () => {
    for (const [next, surface] of [
      [FINE_NARROW, 'popover'],
      [PHONE_LANDSCAPE, 'bottom-sheet'],
      [COMPACT_EDGES[0], 'bottom-sheet'],
      [COMPACT_EDGES[1], 'popover'],
      [COMPACT_EDGES[2], 'bottom-sheet'],
      [COMPACT_EDGES[3], 'popover'],
    ] as const) {
      setDevice(next);
      expect({...next, surface: resolve('adaptive').surface}).toEqual({
        ...next,
        surface,
      });
    }
  });

  it("follows the active theme's md point for 'adaptive' (spec:AST-012 FR9)", () => {
    const wideMd = defineTheme({
      name: 'wide-md-presentation',
      adaptations: {widthBreakpoints: {md: 1000, lg: 1100}},
    });
    const wrapper = ({children}: {children: ReactNode}) =>
      createElement(
        Theme,
        {theme: wideMd} as ComponentProps<typeof Theme>,
        children,
      );
    setDevice({coarse: true, width: 900, height: 1024});
    // Under the default md point (768) this screen is not compact.
    const plain = renderHook(() => usePresentation('adaptive'));
    expect(plain.result.current.surface).toBe('popover');
    plain.unmount();
    // Under a theme whose md is 1000, the same screen is compact.
    const themed = renderHook(() => usePresentation('adaptive'), {wrapper});
    expect(themed.result.current).toEqual({
      surface: 'bottom-sheet',
      touchModes: true,
    });
  });

  it('follows the pointer when it changes (an iPad docking a trackpad)', () => {
    setDevice(IPAD);
    const {result} = renderHook(() =>
      usePresentation(undefined, {whenOmitted: 'touch'}),
    );
    expect(result.current.touchModes).toBe(true);
    act(() => setDevice({coarse: false}));
    // A fine pointer in this context, checked before the claim.
    expect(window.matchMedia('(pointer: coarse)').matches).toBe(false);
    expect(result.current).toMatchObject({touchModes: false});
    act(() => setDevice({coarse: true}));
    expect(result.current).toMatchObject({touchModes: true});
  });

  it('renders no touch surface or input mode on the server or while hydrating, and takes no hint that would (spec:AST-094 FR13)', () => {
    // On a phone, where a live read would answer touch modes.
    setDevice(IPHONE);
    function Probe({
      presentation,
      options = TOUCH_WHEN_OMITTED,
    }: {
      presentation?: AdaptivePresentation;
      options?: UsePresentationOptions;
    }) {
      const resolved = usePresentation(presentation, options);
      return `${resolved.surface}/${String(resolved.touchModes)}`;
    }
    expect(renderToString(createElement(Probe))).toContain('popover/false');
    expect(
      renderToString(createElement(Probe, {presentation: 'adaptive'})),
    ).toContain('popover/false');
    expect(
      renderToString(createElement(Probe, {presentation: 'bottom-sheet'})),
    ).toContain('bottom-sheet/false');
    // A server hint would put touch modes into the server render, which
    // hydration then contradicts: usePresentation takes none.
    const hinted = {
      whenOmitted: 'touch',
      // @ts-expect-error usePresentation takes no serverDefault.
      serverDefault: {isTouch: true, isCompact: true},
    } satisfies UsePresentationOptions;
    expect(
      renderToString(
        createElement(Probe, {presentation: 'adaptive', options: hinted}),
      ),
    ).toContain('popover/false');
  });

  it('hydrates on a phone from the server render, then follows the device (spec:AST-094 FR13)', async () => {
    setDevice(IPHONE);
    const renders: string[] = [];
    function Probe({presentation}: {presentation: AdaptivePresentation}) {
      const resolved = usePresentation(presentation, TOUCH_WHEN_OMITTED);
      const text = `${resolved.surface}/${String(resolved.touchModes)}`;
      renders.push(text);
      return text;
    }
    const html = renderToString(
      createElement(Probe, {presentation: 'adaptive'}),
    );
    expect(html).toContain('popover/false');
    const container = document.createElement('div');
    container.innerHTML = html;
    document.body.append(container);
    renders.length = 0;
    const recoverable = vi.fn();
    let root: Root | null = null;
    await act(async () => {
      root = hydrateRoot(
        container,
        createElement(Probe, {presentation: 'adaptive'}),
        {onRecoverableError: recoverable},
      );
    });
    // The hydrating render is the server's; the phone's answer follows it.
    expect(renders[0]).toBe('popover/false');
    expect(renders.at(-1)).toBe('bottom-sheet/true');
    expect(recoverable).not.toHaveBeenCalled();
    act(() => root?.unmount());
    container.remove();
  });

  it('subscribes only to the queries a request reads (architecture:react-component-runtime INV5)', () => {
    setDevice(IPHONE);
    for (const [presentation, whenOmitted, subscriptions] of [
      ['popover', 'touch', 0],
      [undefined, 'popover', 0],
      ['bottom-sheet', 'popover', 1],
      [undefined, 'touch', 1],
      ['adaptive', 'popover', 2],
    ] as const) {
      listeners.clear();
      const {unmount} = renderHook(() =>
        usePresentation(presentation, {whenOmitted}),
      );
      expect({
        presentation,
        whenOmitted,
        subscriptions: listeners.size,
      }).toEqual({presentation, whenOmitted, subscriptions});
      unmount();
      expect(listeners.size).toBe(0);
    }
  });

  it('answers at one moment as the hook does, and as the server would with no window', () => {
    setDevice(IPHONE);
    const compact = DEFAULT_COMPACT_DEFINITION;
    expect(
      readPresentation(undefined, {whenOmitted: 'touch', compact}),
    ).toEqual(resolve(undefined, 'touch'));
    expect(
      readPresentation('popover', {whenOmitted: 'touch', compact}),
    ).toEqual(resolve('popover', 'touch'));
    expect(readPresentation('adaptive', {compact})).toEqual(
      resolve('adaptive'),
    );
    expect(
      readPresentation(undefined, {whenOmitted: 'touch', view: null, compact}),
    ).toEqual({
      surface: 'popover',
      touchModes: false,
    });
  });

  it('answers the default presentation where the window has no matchMedia, as in a test DOM', () => {
    vi.stubGlobal('matchMedia', undefined);
    expect(resolve(undefined, 'touch')).toEqual({
      surface: 'popover',
      touchModes: false,
    });
    expect(resolve('adaptive')).toEqual({
      surface: 'popover',
      touchModes: false,
    });
    expect(resolve('bottom-sheet')).toEqual({
      surface: 'bottom-sheet',
      touchModes: false,
    });
    expect(
      renderHook(() => useAdaptivePresentation('adaptive')).result.current,
    ).toBe('popover');
  });

  it('reads the compact definition it is given, so a theme that moves md moves the sheet (spec:AST-012 FR9)', () => {
    setDevice({...IPHONE, width: 900, height: 1024});
    expect(
      readPresentation('adaptive', {compact: DEFAULT_COMPACT_DEFINITION})
        .surface,
    ).toBe('popover');
    expect(
      readPresentation('adaptive', {compact: compactDefinition({md: 1000})})
        .surface,
    ).toBe('bottom-sheet');
  });
});