Skip to content

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

TypeScript
9.5 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.
// @pr-a11y scope ^(packages/core/src/(Dialog|AlertDialog|Drawer|MobileNav|BottomSheet)/|apps/storybook/stories/(Dialog|AlertDialog|Drawer|MobileNav|BottomSheet)\.stories)

/**
 * @file ModalBackdrop.a11y.browser.spec.ts
 * @input The Dialog, AlertDialog, Drawer, MobileNav and BottomSheet stories in
 *   a built Storybook, under a finger at phone width and with a mouse at
 *   desktop width, in light and dark mode
 * @output Browser evidence that no modal blurs the page and that each
 *   `::backdrop` keeps the theme's overlay colour. In forced colors, each modal
 *   has one 1px edge and the focus ring keeps the outline. A screenshot of an
 *   open Dialog in each mode.
 * @position Cross-browser proof for the shared modal backdrop. jsdom paints
 *   nothing, so modalBackdrop.test.tsx pins only the declarations. WebKit here
 *   is desktop WebKit under Playwright, not iOS Safari.
 * SYNC: When a component gains a modal ::backdrop, add it to MODALS.
 */

import * as fs from 'node:fs';
import * as path from 'node:path';
import {expect, test, type Page} from '@astryxdesign/a11y-spec/playwright';
import {
  DEFAULT_STORYBOOK_DIR,
  serveStorybook,
  type StaticServer,
} from '@astryxdesign/a11y-spec/storybook';

let storybook: StaticServer;
test.beforeAll(async () => {
  storybook = await serveStorybook(
    process.env.ASTRYX_STORYBOOK_DIR ?? DEFAULT_STORYBOOK_DIR,
  );
});
test.afterAll(async () => {
  await storybook?.close();
});

test.use({viewport: {width: 390, height: 844}, hasTouch: true, isMobile: true});

/** Each modal surface that dims the page, and the tap that opens it. */
const MODALS = [
  {name: 'Dialog', story: 'core-dialog--default', opener: 'Open Modal'},
  {
    name: 'AlertDialog',
    story: 'core-alertdialog--delete',
    opener: 'Delete item',
  },
  {name: 'Drawer', story: 'core-drawer--scrim', opener: 'With scrim'},
  {
    name: 'MobileNav',
    story: 'core-mobilenav--default',
    opener: 'Open Navigation',
  },
  {
    name: 'BottomSheet',
    story: 'core-bottomsheet--showcase',
    opener: 'Open sheet',
  },
] as const;

type Mode = 'light' | 'dark';

/** The dim with the base tokens, under every pointer: `--color-overlay`. */
const OVERLAY_DIM: Record<Mode, string> = {
  light: 'rgba(1, 18, 40, 0.4)',
  dark: 'rgba(17, 17, 18, 0.6)',
};

async function openModal(
  page: Page,
  modal: (typeof MODALS)[number],
  mode: Mode,
  theme: 'none' | 'neutral',
): Promise<void> {
  await page.goto(
    `${storybook.origin}/iframe.html?id=${modal.story}&viewMode=story&globals=colorMode:${mode};astryxTheme:${theme}`,
  );
  const opener = page.getByRole('button', {name: modal.opener}).first();
  if (await page.evaluate(() => matchMedia('(pointer: coarse)').matches)) {
    await opener.tap();
  } else {
    await opener.click();
  }
  await expect(page.locator('dialog[open]').last()).toBeVisible();
}

/** The open modal's ::backdrop as the browser computes it. */
async function readBackdrop(
  page: Page,
): Promise<{color: string; filter: string}> {
  return page
    .locator('dialog[open]')
    .last()
    .evaluate(dialog => {
      const style = getComputedStyle(dialog, '::backdrop');
      return {
        color: style.backgroundColor,
        filter:
          style.backdropFilter ??
          (style as unknown as {webkitBackdropFilter?: string})
            .webkitBackdropFilter ??
          'none',
      };
    });
}

/**
 * The open modal's visible surface (the dialog, or MobileNav's drawer): its
 * outline, and its drawn side borders (solid and wider than 0), as
 * `side width`.
 */
async function readSurfaceEdge(
  page: Page,
  name: string,
): Promise<{outline: string; sides: string[]}> {
  return page
    .locator('dialog[open]')
    .last()
    .evaluate((dialog, isMobileNav) => {
      // MobileNav's dialog is a transparent full-viewport container; its
      // drawer panel (the focus target) is what the person sees.
      const surface = isMobileNav
        ? (dialog.querySelector('[tabindex="-1"]') ?? dialog)
        : dialog;
      const style = getComputedStyle(surface);
      return {
        outline: `${style.outlineStyle} ${style.outlineWidth}`,
        sides: (['left', 'right'] as const)
          .filter(
            side =>
              style.getPropertyValue(`border-${side}-style`) === 'solid' &&
              Number.parseFloat(
                style.getPropertyValue(`border-${side}-width`),
              ) > 0,
          )
          .map(
            side => `${side} ${style.getPropertyValue(`border-${side}-width`)}`,
          ),
      };
    }, name === 'MobileNav');
}

for (const modal of MODALS) {
  for (const mode of ['light', 'dark'] as const) {
    test(`${modal.name} keeps the overlay colour under a finger in ${mode} mode, unblurred`, async ({
      page,
    }) => {
      await openModal(page, modal, mode, 'none');
      expect(
        await page.evaluate(() => matchMedia('(pointer: coarse)').matches),
      ).toBe(true);
      const backdrop = await readBackdrop(page);
      expect(backdrop.color).toBe(OVERLAY_DIM[mode]);
      expect(backdrop.filter).toBe('none');
    });
  }

  test(`${modal.name} keeps the neutral theme's own dim under a finger, unblurred`, async ({
    page,
  }) => {
    await openModal(page, modal, 'light', 'neutral');
    const backdrop = await readBackdrop(page);
    // neutral's overlay: black at 50 %.
    expect(backdrop.color).toBe('rgba(0, 0, 0, 0.5)');
    expect(backdrop.filter).toBe('none');
  });
}

test.describe('with a mouse', () => {
  test.use({
    hasTouch: false,
    isMobile: false,
    viewport: {width: 1280, height: 800},
  });

  for (const modal of MODALS) {
    test(`${modal.name} keeps the overlay colour, unblurred`, async ({
      page,
    }) => {
      await openModal(page, modal, 'dark', 'none');
      expect(
        await page.evaluate(() => matchMedia('(pointer: coarse)').matches),
      ).toBe(false);
      const backdrop = await readBackdrop(page);
      expect(backdrop.color).toBe(OVERLAY_DIM.dark);
      expect(backdrop.filter).toBe('none');
    });
  }
});

test.describe('forced colors', () => {
  test.use({colorScheme: 'light'});

  for (const modal of MODALS.filter(m => m.name !== 'BottomSheet')) {
    test(`${modal.name} has one 1px edge under a finger, where no blur sets it apart`, async ({
      page,
      browserName,
    }) => {
      test.skip(
        browserName !== 'chromium',
        'forced-colors emulation is Chromium-only in Playwright',
      );
      await page.emulateMedia({forcedColors: 'active'});
      await openModal(page, modal, 'light', 'none');
      const edge = await readSurfaceEdge(page, modal.name);
      if (modal.name === 'Drawer' || modal.name === 'MobileNav') {
        // The side panel's border facing the page is its edge; no outline
        // doubles it.
        expect(edge.outline, JSON.stringify(edge)).toMatch(/^none /);
        expect(edge.sides, JSON.stringify(edge)).toHaveLength(1);
        expect(edge.sides[0], JSON.stringify(edge)).toMatch(/ 1px$/);
      } else {
        // Dialog's border is its edge, on every side; its outline stays the
        // focus ring's (none until keyboard focus).
        expect(edge, JSON.stringify(edge)).toEqual({
          outline: 'none 0px',
          sides: ['left 1px', 'right 1px'],
        });
      }
    });
  }

  test.describe('with a mouse', () => {
    test.use({
      hasTouch: false,
      isMobile: false,
      viewport: {width: 1280, height: 800},
    });

    for (const modal of MODALS.filter(m => m.name !== 'BottomSheet')) {
      test(`${modal.name} has the same one 1px edge`, async ({
        page,
        browserName,
      }) => {
        test.skip(
          browserName !== 'chromium',
          'forced-colors emulation is Chromium-only in Playwright',
        );
        await page.emulateMedia({forcedColors: 'active'});
        await openModal(page, modal, 'light', 'none');
        expect(
          await page.evaluate(() => matchMedia('(pointer: coarse)').matches),
        ).toBe(false);
        const edge = await readSurfaceEdge(page, modal.name);
        expect(edge, JSON.stringify(edge)).toEqual(
          modal.name === 'Drawer' || modal.name === 'MobileNav'
            ? {
                outline: expect.stringMatching(/^none /),
                sides: [expect.stringMatching(/ 1px$/)],
              }
            : {outline: 'none 0px', sides: ['left 1px', 'right 1px']},
        );
      });
    }
  });
});

test('the media scrim keeps --color-overlay', async ({page}) => {
  // Overlay's dark scrim keeps text legible over media; it is not a modal
  // dim and keeps the overlay colour.
  await page.goto(
    `${storybook.origin}/iframe.html?id=core-overlay--bottom-strip&viewMode=story&globals=colorMode:light;astryxTheme:none`,
  );
  const scrim = page.locator('.astryx-overlay-scrim').first();
  await expect(scrim).toBeAttached();
  expect(
    await scrim.evaluate(element => getComputedStyle(element).backgroundColor),
  ).toBe('rgba(1, 18, 40, 0.4)');
});

const EVIDENCE = process.env.MODAL_BACKDROP_EVIDENCE_DIR ?? '';
test('evidence: an open Dialog over a page under a finger, per mode', async ({
  page,
}, testInfo) => {
  test.skip(EVIDENCE === '', 'evidence capture runs on request');
  fs.mkdirSync(EVIDENCE, {recursive: true});
  for (const mode of ['light', 'dark'] as const) {
    await openModal(page, MODALS[0], mode, 'none');
    // The page under the dim, with the open dialog: the viewport, no chrome.
    await page.screenshot({
      path: path.join(EVIDENCE, `${testInfo.project.name}-dialog-${mode}.png`),
      animations: 'disabled',
    });
  }
});