Skip to content

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

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

/**
 * @file CircleCheckIndicator.interaction.browser.spec.ts
 * @input The built Lab CircleCheckIndicator "Mapped Checkbox List" story, in
 *   which a theme maps the circle to `checkbox`. Real touch input (Chromium
 *   CDP, WebKit's tap) and the interaction harness drive it.
 * @output Proofs that a finger and a mouse both fade the circle over the
 *   theme's duration. Under Reduce Motion both change it at once.
 *   A storyboard shows a tap's blended frames. The row keeps its checkbox
 *   semantics.
 * @position Real-engine layer of CircleCheckIndicator; the stylesheet layer
 *   is circleCheck.test.tsx
 */

import {expect, test, type Page} from '@astryxdesign/a11y-spec/playwright';
import {
  castStoryboard,
  frames,
  openStory,
  startScreencast,
  touchDriver,
  withStorybook,
} from '@astryxdesign/interaction-harness';

const storybook = withStorybook(test);

const STORY = 'lab-circlecheckindicator--mapped-checkbox-list';

/** What the page saw in the microtask after the circle's class changed. */
interface CircleRead {
  first: string;
  transitions: {property: string; duration: number}[];
}

/** The circle of the row labelled `name`. */
const CIRCLE = '.astryx-circle-check-indicator';

async function watchCircle(page: Page, name: string): Promise<void> {
  await page.getByRole('checkbox', {name}).evaluate(
    (input, {selector, key}) => {
      const circle = input
        .closest('li, .astryx-item')
        ?.querySelector<HTMLElement>(selector);
      if (circle == null) {
        throw new Error(`no circle for ${key}`);
      }
      const reads = ((
        window as unknown as Record<string, unknown>
      ).__circleMarkReads ??= {}) as Record<string, unknown>;
      const observer = new MutationObserver(() => {
        if (reads[key] != null) {
          return;
        }
        reads[key] = {
          first: getComputedStyle(circle).backgroundColor,
          transitions: circle
            .getAnimations()
            .filter(animation => 'transitionProperty' in animation)
            .map(animation => ({
              property: (animation as CSSTransition).transitionProperty,
              duration: Number(animation.effect?.getTiming().duration ?? 0),
            })),
        };
        observer.disconnect();
      });
      observer.observe(circle, {attributes: true, attributeFilter: ['class']});
    },
    {selector: CIRCLE, key: name},
  );
}

async function readCircle(page: Page, name: string): Promise<CircleRead> {
  await page.waitForFunction(
    key =>
      ((window as unknown as Record<string, Record<string, unknown>>)
        .__circleMarkReads ?? {})[key] != null,
    name,
  );
  return page.evaluate(
    key =>
      (window as unknown as Record<string, Record<string, CircleRead>>)
        .__circleMarkReads[key],
    name,
  );
}

async function circleColour(page: Page, name: string): Promise<string> {
  return page.getByRole('checkbox', {name}).evaluate((input, selector) => {
    const circle = input.closest('li, .astryx-item')?.querySelector(selector);
    if (circle == null) {
      throw new Error('no circle');
    }
    return getComputedStyle(circle).backgroundColor;
  }, CIRCLE);
}

/** How many animations the circle of the row labelled `name` runs. */
async function runningOn(page: Page, name: string): Promise<number> {
  return page.getByRole('checkbox', {name}).evaluate((input, selector) => {
    const circle = input.closest('li, .astryx-item')?.querySelector(selector);
    if (circle == null) {
      throw new Error('no circle');
    }
    return circle.getAnimations().length;
  }, CIRCLE);
}

/**
 * Waits until the circle runs no animation. The two frames first let the
 * last input's transition start.
 */
async function untilStill(page: Page, name: string): Promise<void> {
  await frames(page, 2);
  await expect.poll(() => runningOn(page, name)).toBe(0);
}

/** The circle's colour once it is still, held for two more frames. */
async function settledColour(page: Page, name: string): Promise<string> {
  await untilStill(page, name);
  const colour = await circleColour(page, name);
  await frames(page, 2);
  expect(await circleColour(page, name), 'two frames later').toBe(colour);
  return colour;
}

/** The centre of the circle of the row labelled `name`: a mouse there is on the checkbox. */
async function circleCentreOf(page: Page, name: string) {
  const box = await page
    .getByRole('checkbox', {name})
    .evaluate((input, selector) => {
      const circle = input.closest('li, .astryx-item')?.querySelector(selector);
      if (circle == null) {
        throw new Error('no circle');
      }
      const r = circle.getBoundingClientRect();
      return {x: r.x + r.width / 2, y: r.y + r.height / 2};
    }, CIRCLE);
  return {x: Math.round(box.x), y: Math.round(box.y)};
}

async function centreOf(page: Page, name: string) {
  const box = await page.getByRole('checkbox', {name}).evaluate(input => {
    const row = input.closest('li, .astryx-item');
    if (row == null) {
      throw new Error('no row');
    }
    const r = row.getBoundingClientRect();
    return {x: r.x + r.width / 2, y: r.y + r.height / 2};
  });
  return {x: Math.round(box.x), y: Math.round(box.y)};
}

/** The circle's background on every animation frame for `ms`. */
async function traceCircle(
  page: Page,
  name: string,
  ms: number,
): Promise<{t: number; colour: string}[]> {
  return page.getByRole('checkbox', {name}).evaluate(
    async (input, {selector, ms}) => {
      const circle = input.closest('li, .astryx-item')?.querySelector(selector);
      if (circle == null) {
        throw new Error('no circle');
      }
      const samples: {t: number; colour: string}[] = [];
      const end = performance.now() + ms;
      return new Promise<{t: number; colour: string}[]>(resolve => {
        const tick = () => {
          samples.push({
            t: Date.now(),
            colour: getComputedStyle(circle).backgroundColor,
          });
          if (performance.now() < end) {
            requestAnimationFrame(tick);
          } else {
            resolve(samples);
          }
        };
        requestAnimationFrame(tick);
      });
    },
    {selector: CIRCLE, ms},
  );
}

test.describe('CircleCheckIndicator under a finger', () => {
  // One touch model on every touch device: a coarse primary pointer. The
  // touch page here is the engine's own touch emulation; real iOS Safari and
  // Android Chrome are the simulator and emulator recordings.

  test('a tap fades the circle over the theme’s duration, and the row stays a checkbox', async ({
    page,
  }) => {
    await openStory(page, storybook(), STORY);
    await watchCircle(page, 'Mountains');
    const driver = await touchDriver(page);
    await driver.tap(await centreOf(page, 'Mountains'));
    await expect(page.getByRole('checkbox', {name: 'Mountains'})).toBeChecked();
    const read = await readCircle(page, 'Mountains');
    expect(
      read.transitions.some(
        ({property, duration}) =>
          property === 'background-color' && duration > 0,
      ),
    ).toBe(true);
    expect(read.first).not.toBe(await settledColour(page, 'Mountains'));
  });

  test('a tap’s fade, filmed: the transition runs from the start colour @storyboard', async ({
    page,
  }, testInfo) => {
    await openStory(page, storybook(), STORY);
    const driver = await touchDriver(page);
    const at = await centreOf(page, 'Mountains');
    const before = await circleColour(page, 'Mountains');
    await watchCircle(page, 'Mountains');
    const cast = await startScreencast(page);
    await frames(page, 4);
    const tapAt = Date.now();
    const [trace] = await Promise.all([
      traceCircle(page, 'Mountains', 500),
      driver.tap(at),
    ]);
    const shot = await cast.stop();
    const after = trace.at(-1)?.colour;
    const nearest = (t: number) =>
      trace.reduce((best, sample) =>
        Math.abs(sample.t - t) < Math.abs(best.t - t) ? sample : best,
      );
    // The evidence is written first, so a failing run shows its blend.
    const storyboard = await castStoryboard(page, shot, {
      name: 'circle-check-tap',
      zero: tapAt,
      cellScale: 0.5,
      columns: 4,
      data: t => ({circle: nearest(t).colour}),
    });
    await storyboard.write(testInfo, {
      claim:
        'under a finger the circle fades in over the theme duration, as with a mouse',
      before,
      after,
    });
    expect(after).not.toBe(before);
    // The frames are evidence only: a busy main thread can skip every blended
    // frame. The transition itself is read from the first style after the change.
    const read = await readCircle(page, 'Mountains');
    expect(
      read.transitions.some(
        ({property, duration}) =>
          property === 'background-color' && duration > 0,
      ),
    ).toBe(true);
    expect(read.first).toBe(before);
  });

  test('a mouse fades the circle the same way', async ({browser}) => {
    const context = await browser.newContext({
      viewport: {width: 1024, height: 768},
      hasTouch: false,
      isMobile: false,
    });
    const page = await context.newPage();
    try {
      await openStory(page, storybook(), STORY);
      // A fine-pointer case proves nothing under a coarse primary pointer.
      expect(
        await page.evaluate(() => matchMedia('(pointer: coarse)').matches),
      ).toBe(false);
      await watchCircle(page, 'Mountains');
      const at = await centreOf(page, 'Mountains');
      await page.mouse.move(at.x, at.y);
      await untilStill(page, 'Mountains');
      await page.mouse.click(at.x, at.y);
      const read = await readCircle(page, 'Mountains');
      expect(
        read.transitions.some(
          ({property, duration}) =>
            property === 'background-color' && duration > 0,
        ),
      ).toBe(true);
      await untilStill(page, 'Mountains');
      expect(read.first).not.toBe(await circleColour(page, 'Mountains'));
    } finally {
      await context.close();
    }
  });
});

test.describe('CircleCheckIndicator under Reduce Motion', () => {
  test('a finger changes the circle at once', async ({page}) => {
    await page.emulateMedia({reducedMotion: 'reduce'});
    await openStory(page, storybook(), STORY);
    await watchCircle(page, 'Mountains');
    const driver = await touchDriver(page);
    await driver.tap(await centreOf(page, 'Mountains'));
    await expect(page.getByRole('checkbox', {name: 'Mountains'})).toBeChecked();
    const read = await readCircle(page, 'Mountains');
    expect(read.transitions).toEqual([]);
    expect(read.first).toBe(await settledColour(page, 'Mountains'));
  });

  test('a mouse changes at once (design:reduced-motion DR3)', async ({
    browser,
  }) => {
    const context = await browser.newContext({
      viewport: {width: 1024, height: 768},
      hasTouch: false,
      isMobile: false,
      reducedMotion: 'reduce',
    });
    const page = await context.newPage();
    try {
      await openStory(page, storybook(), STORY);
      // A fine-pointer case proves nothing under a coarse primary pointer.
      expect(
        await page.evaluate(() => matchMedia('(pointer: coarse)').matches),
      ).toBe(false);
      await watchCircle(page, 'Mountains');
      const at = await circleCentreOf(page, 'Mountains');
      await page.mouse.move(at.x, at.y);
      await untilStill(page, 'Mountains');
      await page.mouse.click(at.x, at.y);
      await expect(
        page.getByRole('checkbox', {name: 'Mountains'}),
      ).toBeChecked();
      const read = await readCircle(page, 'Mountains');
      expect(read.transitions).toEqual([]);
      expect(read.first).toBe(await circleColour(page, 'Mountains'));
    } finally {
      await context.close();
    }
  });
});

/** The host's press layer and the circle's own, while the row is pressed. */
async function readPress(page: Page, name: string) {
  return page.getByRole('checkbox', {name}).evaluate((input, selector) => {
    const wrapper = input.parentElement;
    const circle = input
      .closest('li, .astryx-item')
      ?.querySelector<HTMLElement>(selector);
    if (wrapper == null || circle == null) {
      throw new Error('no circle');
    }
    const host = getComputedStyle(wrapper, '::after');
    const own = getComputedStyle(circle, '::after');
    return {
      hostContent: host.content,
      circleContent: own.content,
      circleImage: own.backgroundImage,
      circleColour: own.backgroundColor,
      circleLayerRadius: own.borderRadius,
      circleRadius: getComputedStyle(circle).borderRadius,
    };
  }, CIRCLE);
}

/** Whether the list row that holds the named checkbox carries a press. */
async function rowPressed(page: Page, name: string): Promise<boolean> {
  return page
    .getByRole('checkbox', {name})
    .evaluate(
      input => input.closest('li')?.hasAttribute('data-astryx-press') ?? false,
    );
}

test.describe('CircleCheckIndicator press', () => {
  test('a held circle presses the row and paints round; the host’s square layer stays off', async ({
    page,
  }) => {
    await openStory(page, storybook(), STORY);
    const at = await circleCentreOf(page, 'Mountains');
    const driver = await touchDriver(page);
    // At rest the circle paints no press image.
    const rest = await readPress(page, 'Mountains');
    let read: Awaited<ReturnType<typeof readPress>> | null = null;
    let pressedRow = false;
    await driver.play(
      [
        {t: 0, fingers: [{id: 1, ...at}]},
        {t: 600, fingers: []},
      ],
      {
        onEvent: async step => {
          if (step.type !== 'touchStart') {
            return;
          }
          // The press paints after the content-touch delay, inside the hold.
          await expect
            .poll(
              async () => {
                read = await readPress(page, 'Mountains');
                return read.circleImage;
              },
              {timeout: 500},
            )
            .not.toBe(rest.circleImage);
          pressedRow = await rowPressed(page, 'Mountains');
        },
      },
    );
    if (read == null) {
      throw new Error('the press was not read');
    }
    const held: Awaited<ReturnType<typeof readPress>> = read;
    // Under a finger the row is the one press surface; the circle paints it.
    expect(pressedRow).toBe(true);
    expect(held.hostContent).toBe('none');
    expect(held.circleContent).not.toBe('none');
    expect(held.circleImage).not.toBe(rest.circleImage);
    expect(held.circleLayerRadius).toBe(held.circleRadius);
  });

  test('a held label presses the row, and the circle paints with it', async ({
    page,
  }) => {
    await openStory(page, storybook(), STORY);
    const at = await centreOf(page, 'Mountains');
    const driver = await touchDriver(page);
    const rest = await readPress(page, 'Mountains');
    let held: Awaited<ReturnType<typeof readPress>> | null = null;
    await driver.play(
      [
        {t: 0, fingers: [{id: 1, ...at}]},
        {t: 600, fingers: []},
      ],
      {
        onEvent: async step => {
          if (step.type !== 'touchStart') {
            return;
          }
          // The row's own press proves the hold landed. The circle is read then.
          await expect
            .poll(async () => rowPressed(page, 'Mountains'), {timeout: 500})
            .toBe(true);
          held = await readPress(page, 'Mountains');
        },
      },
    );
    if (held == null) {
      throw new Error('the hold was not read');
    }
    const read: Awaited<ReturnType<typeof readPress>> = held;
    // The row hands its own checkbox the press, wherever the finger lands, and
    // the circle paints it round while the host's square layer stays off.
    expect(read.circleImage).not.toBe(rest.circleImage);
    expect(read.circleContent).not.toBe('none');
    expect(read.hostContent).toBe('none');
  });

  test('a mouse press tints the circle, not a square around it', async ({
    browser,
  }) => {
    const context = await browser.newContext({
      viewport: {width: 1024, height: 768},
      hasTouch: false,
      isMobile: false,
    });
    const page = await context.newPage();
    try {
      await openStory(page, storybook(), STORY);
      // A fine-pointer case proves nothing under a coarse primary pointer.
      expect(
        await page.evaluate(() => matchMedia('(pointer: coarse)').matches),
      ).toBe(false);
      const at = await circleCentreOf(page, 'Mountains');
      await page.mouse.move(at.x, at.y);
      await page.mouse.down();
      const held = await readPress(page, 'Mountains');
      await page.mouse.up();
      expect(held.hostContent).toBe('none');
      expect(held.circleColour).not.toBe('rgba(0, 0, 0, 0)');
      expect(held.circleLayerRadius).toBe(held.circleRadius);
    } finally {
      await context.close();
    }
  });

  test('a mouse hovering the checkbox tints the circle', async ({browser}) => {
    const context = await browser.newContext({
      viewport: {width: 1024, height: 768},
      hasTouch: false,
      isMobile: false,
    });
    const page = await context.newPage();
    try {
      await openStory(page, storybook(), STORY);
      // A fine-pointer case proves nothing under a coarse primary pointer.
      expect(
        await page.evaluate(() => matchMedia('(pointer: coarse)').matches),
      ).toBe(false);
      const ring = async () =>
        page
          .getByRole('checkbox', {name: 'Mountains'})
          .evaluate(
            (input, selector) =>
              getComputedStyle(
                input
                  .closest('li, .astryx-item')
                  ?.querySelector(selector) as Element,
              ).boxShadow,
            CIRCLE,
          );
      await page.mouse.move(1, 1);
      const rest = await ring();
      const at = await circleCentreOf(page, 'Mountains');
      await page.mouse.move(at.x, at.y);
      await expect.poll(ring).not.toBe(rest);
    } finally {
      await context.close();
    }
  });
});

test.describe('CircleCheckIndicator in forced colors', () => {
  test('the ring falls back to a 1px system-coloured border, and the check stays visible', async ({
    page,
  }) => {
    /** The circle and check of the first row whose checkbox is `checked`. */
    const read = async (checked: boolean) =>
      page.evaluate(
        ({want, circleSelector}) => {
          const input = Array.from(
            document.querySelectorAll<HTMLInputElement>(
              '#storybook-root input[type="checkbox"]',
            ),
          ).find(el => el.checked === want);
          const row = input?.closest('li, .astryx-item');
          const circle = row?.querySelector<HTMLElement>(circleSelector);
          const check = row?.querySelector<SVGElement>(
            '.astryx-circle-check-indicator-check',
          );
          if (circle == null || check == null) {
            return null;
          }
          const ring = getComputedStyle(circle);
          const mark = getComputedStyle(check);
          return {
            borderStyle: ring.borderTopStyle,
            borderWidth: ring.borderTopWidth,
            boxShadow: ring.boxShadow,
            checkDisplay: mark.display,
            checkVisibility: mark.visibility,
          };
        },
        {want: checked, circleSelector: CIRCLE},
      );
    await openStory(page, storybook(), STORY);
    // Default: the empty circle's ring is the inset shadow, with no border.
    const normal = await read(false);
    expect(normal).not.toBeNull();
    expect(normal?.borderStyle).toBe('none');
    expect(normal?.boxShadow).toContain('inset');
    // Forced colors drops shadows: the ring comes back as a 1px border.
    await page.emulateMedia({forcedColors: 'active'});
    const forced = await read(false);
    expect(forced?.borderStyle).toBe('solid');
    expect(forced?.borderWidth).toBe('1px');
    // A checked circle still shows its check.
    const checked = await read(true);
    expect(checked).not.toBeNull();
    expect(checked?.checkDisplay).not.toBe('none');
    expect(checked?.checkVisibility).toBe('visible');
  });
});