@astryxdesign/core 0.7.5 → 0.7.6-canary.0d71e8d

package/src/FieldStatus/__tests__/FieldStatusAudit.a11y.chromium.spec.ts

@@ -0,0 +1,477 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+// @pr-a11y audit FieldStatus
+
+/**
+ * @file FieldStatusAudit.a11y.chromium.spec.ts
+ * @input Exact-head FieldStatus audit matrix across themes, modes, direction, viewport, and forced colors
+ * @output Screenshots and fail-closed sensor receipts for the FieldStatus whole-component audit
+ * @position Component-owned Night Watch browser evidence; CI runs it only for a FieldStatus audit pull request
+ */
+
+import {createHash} from 'node:crypto';
+import {execFileSync} from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {expect, test, type Page} from '@playwright/test';
+import {holdMotionStill} from '@astryxdesign/a11y-spec/chromium';
+import {
+  DEFAULT_STORYBOOK_DIR,
+  serveStorybook,
+  type StaticServer,
+} from '@astryxdesign/a11y-spec/storybook';
+
+const OUTPUT = path.resolve('field-status-audit-evidence');
+const STORY_ID = 'core-fieldstatus--audit-matrix';
+const WIDE = {width: 1024, height: 900};
+const NARROW = {width: 320, height: 1400};
+
+type Mode = 'light' | 'dark';
+type Direction = 'ltr' | 'rtl';
+type Theme = 'neutral' | 'butter';
+
+type AuditCase = {
+  key: string;
+  mode: Mode;
+  direction: Direction;
+  theme: Theme;
+  viewport: {width: number; height: number};
+  forcedColors: boolean;
+};
+
+type AuditReceipt = {
+  passed: boolean;
+  expected: Record<string, unknown>;
+  failures: string[];
+};
+
+const EXPECTED_CASES = [
+  'attached-error',
+  'attached-warning',
+  'attached-success',
+  'detached-error',
+  'detached-warning',
+  'detached-success',
+  'attached-long-prose',
+  'detached-long-prose',
+  'attached-long-token',
+  'detached-long-token',
+  'attached-empty',
+  'detached-empty',
+  'attached-long-token-in-row',
+];
+
+const cases: AuditCase[] = [];
+function addPair(
+  key: string,
+  options: Partial<Omit<AuditCase, 'key' | 'mode'>> = {},
+) {
+  for (const mode of ['light', 'dark'] as const) {
+    cases.push({
+      key: `${key}-${mode}`,
+      mode,
+      direction: options.direction ?? 'ltr',
+      theme: options.theme ?? 'neutral',
+      viewport: options.viewport ?? WIDE,
+      forcedColors: options.forcedColors ?? false,
+    });
+  }
+}
+
+addPair('default');
+addPair('custom-theme', {theme: 'butter'});
+addPair('rtl', {direction: 'rtl'});
+addPair('narrow', {viewport: NARROW});
+addPair('forced-colors', {forcedColors: true});
+
+test.describe.configure({mode: 'serial', retries: 0});
+let server: StaticServer;
+let checkoutSha: string;
+let storybookSha: string;
+
+function storyUrl(item: AuditCase) {
+  return `${server.origin}/iframe.html?id=${STORY_ID}&viewMode=story&globals=colorMode:${item.mode};astryxTheme:${item.theme};direction:${item.direction}`;
+}
+
+async function settle(page: Page) {
+  await holdMotionStill(page);
+  await page.evaluate(async () => document.fonts.ready);
+  await page.evaluate(
+    async () =>
+      new Promise<void>(resolve =>
+        requestAnimationFrame(() => requestAnimationFrame(() => resolve())),
+      ),
+  );
+  await page.waitForTimeout(40);
+}
+
+async function observe(page: Page) {
+  return page.evaluate((expectedCases: string[]) => {
+    type Rgba = {r: number; g: number; b: number; a: number};
+    function parseColor(color: string): Rgba | null {
+      const match = color.match(/rgba?\(([^)]+)\)/);
+      if (!match) {
+        return null;
+      }
+      const [r, g, b, a = 1] = match[1]
+        .split(/[\s,/]+/)
+        .filter(Boolean)
+        .map(Number);
+      return {r, g, b, a};
+    }
+    function over(top: Rgba, bottom: Rgba): Rgba {
+      return {
+        r: top.r * top.a + bottom.r * (1 - top.a),
+        g: top.g * top.a + bottom.g * (1 - top.a),
+        b: top.b * top.a + bottom.b * (1 - top.a),
+        a: 1,
+      };
+    }
+    // The painted backdrop behind an element: its own fill composited over
+    // every translucent ancestor fill down to the first opaque one (or the
+    // white canvas when none is opaque).
+    function backdrop(element: Element): Rgba {
+      const layers: Rgba[] = [];
+      for (
+        let node: Element | null = element;
+        node != null;
+        node = node.parentElement
+      ) {
+        const color = parseColor(getComputedStyle(node).backgroundColor);
+        if (color != null && color.a > 0) {
+          layers.push(color);
+          if (color.a >= 1) {
+            break;
+          }
+        }
+      }
+      let result: Rgba = {r: 255, g: 255, b: 255, a: 1};
+      for (const layer of layers.reverse()) {
+        result = over(layer, result);
+      }
+      return result;
+    }
+    function luminance({r, g, b}: Rgba): number {
+      const [lr, lg, lb] = [r, g, b].map(channel => {
+        const c = channel / 255;
+        return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+      });
+      return 0.2126 * lr + 0.7152 * lg + 0.0722 * lb;
+    }
+    function contrast(element: Element): number | null {
+      const fg = parseColor(getComputedStyle(element).color);
+      if (fg == null) {
+        return null;
+      }
+      const bg = backdrop(element);
+      const a = luminance(over(fg, bg));
+      const b = luminance(bg);
+      const [hi, lo] = a > b ? [a, b] : [b, a];
+      return Math.round(((hi + 0.05) / (lo + 0.05)) * 100) / 100;
+    }
+
+    const boxes = Array.from(
+      document.querySelectorAll<HTMLElement>('.astryx-field-status'),
+    ).map(box => {
+      const style = getComputedStyle(box);
+      const rect = box.getBoundingClientRect();
+      const column = box.parentElement?.getBoundingClientRect();
+      const icons = Array.from(
+        box.querySelectorAll<HTMLElement>('.astryx-field-status-icon'),
+      );
+      const icon = icons[0] ?? null;
+      const iconRect = icon?.getBoundingClientRect() ?? null;
+      const textNode =
+        box.getAttribute('data-variant') === 'detached'
+          ? (box.firstElementChild?.lastElementChild as HTMLElement | null)
+          : box;
+      const textRange = document.createRange();
+      if (textNode) {
+        textRange.selectNodeContents(textNode);
+      }
+      const lineRects = Array.from(textRange.getClientRects());
+      const firstLine = lineRects[0] ?? null;
+      const textRect = textRange.getBoundingClientRect();
+      return {
+        auditCase: box.getAttribute('data-audit-case'),
+        type: box.getAttribute('data-type'),
+        variant: box.getAttribute('data-variant'),
+        role: box.getAttribute('role'),
+        ariaLive: box.getAttribute('aria-live'),
+        ariaHidden: box.getAttribute('aria-hidden'),
+        text: box.textContent,
+        iconCount: icons.length,
+        iconHidden: icon ? icon.closest('[aria-hidden="true"]') != null : null,
+        iconBeforeText:
+          icon && textNode
+            ? Boolean(
+                icon.compareDocumentPosition(textNode) &
+                Node.DOCUMENT_POSITION_FOLLOWING,
+              )
+            : null,
+        iconOnFirstLine:
+          iconRect && firstLine
+            ? iconRect.top + iconRect.height / 2 >= firstLine.top - 1 &&
+              iconRect.top + iconRect.height / 2 <= firstLine.bottom + 1
+            : null,
+        lines: lineRects.length,
+        boxInlineOverflow: box.scrollWidth > box.clientWidth + 1,
+        textInlineOverflow:
+          lineRects.length > 0 &&
+          (textRect.left < rect.left - 1 || textRect.right > rect.right + 1),
+        escapesColumn: column
+          ? rect.left < column.left - 1 || rect.right > column.right + 1
+          : null,
+        outlineStyle: style.outlineStyle,
+        color: style.color,
+        backgroundColor: style.backgroundColor,
+        contrast: contrast(box),
+        compositedBackground: (() => {
+          const bg = backdrop(box);
+          return `rgb(${Math.round(bg.r)}, ${Math.round(bg.g)}, ${Math.round(bg.b)})`;
+        })(),
+        fontSize: style.fontSize,
+        geometry: {
+          x: Math.round(rect.x * 10) / 10,
+          y: Math.round(rect.y * 10) / 10,
+          width: Math.round(rect.width * 10) / 10,
+          height: Math.round(rect.height * 10) / 10,
+        },
+      };
+    });
+    const root = document.querySelector<HTMLElement>('.astryx-field-status');
+    return {
+      theme: document
+        .querySelector('[data-astryx-theme]')
+        ?.getAttribute('data-astryx-theme'),
+      mode: document.documentElement.getAttribute('data-theme'),
+      direction: root ? getComputedStyle(root).direction : null,
+      viewport: {width: innerWidth, height: innerHeight},
+      dpr: devicePixelRatio,
+      reducedMotion: matchMedia('(prefers-reduced-motion: reduce)').matches,
+      forcedColors: matchMedia('(forced-colors: active)').matches,
+      documentOverflow: document.documentElement.scrollWidth > innerWidth + 1,
+      fonts: document.fonts.status,
+      runningAnimations: document
+        .getAnimations()
+        .filter(animation => animation.playState === 'running').length,
+      storybookError:
+        document.querySelector('.sb-show-errordisplay') != null ||
+        document.body.classList.contains('sb-show-errordisplay'),
+      cases: boxes.map(box => box.auditCase),
+      expectedCases,
+      boxes,
+    };
+  }, EXPECTED_CASES);
+}
+
+test.beforeAll(async () => {
+  fs.rmSync(OUTPUT, {recursive: true, force: true});
+  fs.mkdirSync(OUTPUT, {recursive: true});
+  checkoutSha = execFileSync('git', ['rev-parse', 'HEAD'], {
+    encoding: 'utf8',
+  }).trim();
+  const expected = process.env.ASTRYX_HEAD_SHA;
+  if (expected && expected !== checkoutSha) {
+    throw new Error(
+      `checkout ${checkoutSha} does not match expected head ${expected}`,
+    );
+  }
+  server = await serveStorybook(
+    process.env.ASTRYX_STORYBOOK_DIR ?? DEFAULT_STORYBOOK_DIR,
+  );
+  const response = await fetch(`${server.origin}/astryx-build-sha.txt`);
+  if (!response.ok) {
+    throw new Error(`Storybook build has no SHA stamp (${response.status})`);
+  }
+  storybookSha = (await response.text()).trim();
+  if (storybookSha !== checkoutSha) {
+    throw new Error(
+      `Storybook ${storybookSha} does not match checkout ${checkoutSha}`,
+    );
+  }
+});
+
+test.afterAll(async () => {
+  await server?.close();
+});
+
+for (const item of cases) {
+  test(item.key, async ({browser}) => {
+    const context = await browser.newContext({
+      viewport: item.viewport,
+      deviceScaleFactor: 1,
+      colorScheme: item.mode,
+      reducedMotion: 'reduce',
+      forcedColors: item.forcedColors ? 'active' : 'none',
+    });
+    const page = await context.newPage();
+    const pageErrors: string[] = [];
+    page.on('pageerror', error => pageErrors.push(String(error)));
+    await page.goto(storyUrl(item), {waitUntil: 'load'});
+    await page.locator('#storybook-root').waitFor();
+    await expect(page.locator('.astryx-field-status')).toHaveCount(
+      EXPECTED_CASES.length,
+    );
+
+    await settle(page);
+    const first = await observe(page);
+    await page.waitForTimeout(100);
+    await settle(page);
+    const observed = await observe(page);
+    const geometryStable =
+      JSON.stringify(first.boxes.map(box => box.geometry)) ===
+      JSON.stringify(observed.boxes.map(box => box.geometry));
+
+    const failures: string[] = [];
+    const check = (condition: boolean, message: string) => {
+      if (!condition) {
+        failures.push(message);
+      }
+    };
+    check(storybookSha === checkoutSha, 'storybook build mismatch');
+    check(pageErrors.length === 0, `page errors: ${pageErrors.join(' | ')}`);
+    check(!observed.storybookError, 'storybook error display');
+    check(observed.theme === item.theme, `theme ${observed.theme}`);
+    check(observed.mode === item.mode, `mode ${observed.mode}`);
+    check(
+      observed.direction === item.direction,
+      `direction ${observed.direction}`,
+    );
+    check(
+      observed.viewport.width === item.viewport.width &&
+        observed.viewport.height === item.viewport.height,
+      'viewport mismatch',
+    );
+    check(observed.dpr === 1, `dpr ${observed.dpr}`);
+    check(observed.reducedMotion, 'reduced motion not applied');
+    check(
+      observed.forcedColors === item.forcedColors,
+      `forced colors ${observed.forcedColors}`,
+    );
+    check(observed.fonts === 'loaded', `fonts ${observed.fonts}`);
+    check(observed.runningAnimations === 0, 'animations still running');
+    check(geometryStable, 'geometry changed between samples');
+    check(
+      JSON.stringify(observed.cases) === JSON.stringify(EXPECTED_CASES),
+      `cases ${observed.cases.join(',')}`,
+    );
+    for (const box of observed.boxes) {
+      const id = box.auditCase ?? 'unknown';
+      const [variant] = id.split('-');
+      // Only the empty fixtures may measure no text line; everywhere else a
+      // missing line means the text was not found, so the line-based checks
+      // below cannot pass vacuously.
+      const isEmpty = id.endsWith('-empty');
+      check(
+        isEmpty ? box.lines === 0 : box.lines > 0,
+        `${id}: ${box.lines} text lines`,
+      );
+      check(box.variant === variant, `${id}: data-variant ${box.variant}`);
+      check(
+        box.role == null && box.ariaLive == null && box.ariaHidden == null,
+        `${id}: box carries role, aria-live, or aria-hidden`,
+      );
+      if (variant === 'detached') {
+        check(box.iconCount === 1, `${id}: ${box.iconCount} status glyphs`);
+        check(box.iconHidden === true, `${id}: status glyph exposed to AT`);
+        check(box.iconBeforeText === true, `${id}: glyph not before text`);
+        // An empty message has no text line to align to.
+        if (!isEmpty) {
+          check(
+            box.iconOnFirstLine === true,
+            `${id}: glyph not aligned to first line`,
+          );
+        }
+      } else {
+        check(box.iconCount === 0, `${id}: attached box renders a glyph`);
+      }
+      check(!box.boxInlineOverflow, `${id}: message overflows its box`);
+      check(!box.textInlineOverflow, `${id}: text paints outside its box`);
+      check(box.escapesColumn === false, `${id}: box escapes its container`);
+      // WCAG 2.2 SC 1.4.3: 12px supporting text needs 4.5:1 against the
+      // composited fill it is painted on.
+      check(
+        box.contrast != null && box.contrast >= 4.5,
+        `${id}: text contrast ${box.contrast}`,
+      );
+      if (item.forcedColors) {
+        check(box.outlineStyle === 'solid', `${id}: no forced-colors boundary`);
+      }
+    }
+    check(!observed.documentOverflow, 'document scrolls horizontally');
+
+    const png = await page.screenshot({animations: 'disabled', fullPage: true});
+    check(png.length > 1000, 'screenshot is empty');
+    const image = `${item.key}.png`;
+    const receipt = {
+      schemaVersion: 1,
+      expected: {
+        build: checkoutSha,
+        storyId: STORY_ID,
+        mode: item.mode,
+        direction: item.direction,
+        theme: item.theme,
+        viewport: item.viewport,
+        forcedColors: item.forcedColors,
+        cases: EXPECTED_CASES,
+        reflow:
+          'no message overflows its box, no box escapes its container, no document horizontal scroll',
+      },
+      observed: {
+        build: storybookSha,
+        ...observed,
+        geometryStable,
+        pageErrors,
+      },
+      image: {
+        file: image,
+        sha256: createHash('sha256').update(png).digest('hex'),
+        width: png.readUInt32BE(16),
+        height: png.readUInt32BE(20),
+      },
+      failures,
+      passed: failures.length === 0,
+    };
+    fs.writeFileSync(path.join(OUTPUT, image), png);
+    fs.writeFileSync(
+      path.join(OUTPUT, `${item.key}.sensors.json`),
+      `${JSON.stringify(receipt, null, 2)}\n`,
+    );
+    await context.close();
+  });
+}
+
+test('manifest is complete', async () => {
+  const receiptFiles = fs
+    .readdirSync(OUTPUT)
+    .filter(file => file.endsWith('.sensors.json'));
+  const receipts = receiptFiles.map(
+    (file): AuditReceipt =>
+      JSON.parse(
+        fs.readFileSync(path.join(OUTPUT, file), 'utf8'),
+      ) as AuditReceipt,
+  );
+  fs.writeFileSync(
+    path.join(OUTPUT, 'manifest.json'),
+    `${JSON.stringify(
+      {
+        schemaVersion: 1,
+        component: 'core/FieldStatus',
+        build: checkoutSha,
+        frames: cases.map(item => ({
+          key: item.key,
+          image: `${item.key}.png`,
+          receipt: `${item.key}.sensors.json`,
+        })),
+      },
+      null,
+      2,
+    )}\n`,
+  );
+  expect(receiptFiles).toHaveLength(cases.length);
+  expect(
+    receipts
+      .filter(receipt => !receipt.passed)
+      .map(receipt => ({frame: receipt.expected, failures: receipt.failures})),
+  ).toEqual([]);
+});

package/src/FileInput/FileInput.test.tsx

@@ -20,6 +20,7 @@ import {
 } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {FileInput} from './FileInput';
+import {FormLayout} from '../FormLayout';
 import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';
 import {InternationalizationProvider} from '../i18n';
 import {Theme} from '../theme/Theme';
@@ -204,6 +205,26 @@ describe('FileInput', () => {
     expect(trigger).not.toHaveAttribute('aria-required');
   });
 
+  it('conveys required state under FormLayout defaultOptionality="required" unless isOptional (FormLayout FR5)', () => {
+    render(
+      <FormLayout defaultOptionality="required">
+        <FileInput label="Resume" value={null} onChange={() => {}} />
+        <FileInput
+          label="Cover letter"
+          isOptional
+          value={null}
+          onChange={() => {}}
+        />
+      </FormLayout>,
+    );
+    expect(
+      screen.getByRole('button', {name: 'Resume'}),
+    ).toHaveAccessibleDescription(/Required/);
+    expect(
+      screen.getByRole('button', {name: /Cover letter/}),
+    ).not.toHaveAccessibleDescription(/Required/);
+  });
+
   it('combines required with the description in the accessible description', () => {
     render(
       <FileInput
@@ -475,6 +496,74 @@ describe('FileInput', () => {
       expect(politeRegion()?.textContent ?? '').toBe('');
     });
 
+    it('identifies every rejected file in one status message (WCAG 3.3.1)', async () => {
+      const onChange = vi.fn();
+      render(
+        <FileInput
+          label="Reports"
+          value={null}
+          onChange={onChange}
+          isMultiple
+          accept=".pdf"
+          maxSize={1024}
+        />,
+      );
+      fireEvent.change(fileInputEl(), {
+        target: {
+          files: [
+            createFile('photo.png', 100),
+            createFile('large.pdf', 4096),
+            createFile('small.pdf', 100),
+          ],
+        },
+      });
+      await waitFor(() => {
+        const status = document.querySelector('.astryx-field-status');
+        expect(status).toHaveTextContent(
+          '"photo.png" is not an accepted file type',
+        );
+        expect(status).toHaveTextContent('"large.pdf" exceeds 1.0 KB limit');
+      });
+      // The valid file is still accepted.
+      expect(onChange).toHaveBeenCalledWith([
+        expect.objectContaining({name: 'small.pdf'}),
+      ]);
+    });
+
+    it('separates the rejected files in a locale whose unit list would run them together', async () => {
+      render(
+        <InternationalizationProvider
+          locale="zh-CN"
+          overrides={{
+            'zh-CN': {
+              '@astryx.fileInput.errorInvalidType': '“{fileName}”类型不受支持',
+              '@astryx.fileInput.errorMaxSize': '“{fileName}”超过 {maxSize}',
+            },
+          }}>
+          <FileInput
+            label="报告"
+            value={null}
+            onChange={() => {}}
+            isMultiple
+            accept=".pdf"
+            maxSize={1024}
+          />
+        </InternationalizationProvider>,
+      );
+      fireEvent.change(fileInputEl(), {
+        target: {
+          files: [createFile('photo.png', 100), createFile('large.pdf', 4096)],
+        },
+      });
+      await waitFor(() => {
+        const status = document.querySelector('.astryx-field-status');
+        // The two messages are separated (、), not run together.
+        expect(status?.textContent).toMatch(
+          /“photo\.png”类型不受支持、“large\.pdf”超过 /,
+        );
+      });
+    });
+
     it('announces a validation error exactly once across live regions', async () => {
       render(
         <FileInput
@@ -1267,4 +1356,74 @@ describe('FileInput statusVariant forwarding', () => {
       'detached',
     );
   });
+
+  // family:input-fields FR8: every input offers the tooltip placement. It has
+  // no message box, so the status button is the only place the message lives.
+  function expectReachableTooltipStatus(message: string) {
+    expect(
+      screen.getByRole('button', {name: 'Error details'}),
+    ).toBeInTheDocument();
+    expect(screen.getByRole('tooltip', h)).toHaveTextContent(message);
+    const trigger = screen.getByRole('button', {name: 'Upload'});
+    const describedBy = (trigger.getAttribute('aria-describedby') ?? '')
+      .split(' ')
+      .filter(Boolean);
+    expect(describedBy.length).toBeGreaterThan(0);
+    for (const id of describedBy) {
+      expect(document.getElementById(id)).not.toBeNull();
+    }
+  }
+
+  it.each(['input', 'dropzone'] as const)(
+    'keeps a statusVariant="tooltip" message reachable in %s mode',
+    mode => {
+      render(
+        <FileInput
+          label="Upload"
+          value={null}
+          onChange={() => {}}
+          mode={mode}
+          status={{type: 'error', message: 'File must be under 10MB'}}
+          statusVariant="tooltip"
+        />,
+      );
+      expectReachableTooltipStatus('File must be under 10MB');
+    },
+  );
+
+  it('does not open the file picker from the dropzone status button', async () => {
+    const user = userEvent.setup();
+    const click = vi.spyOn(HTMLInputElement.prototype, 'click');
+    render(
+      <FileInput
+        label="Upload"
+        value={null}
+        onChange={() => {}}
+        mode="dropzone"
+        status={{type: 'error', message: 'File must be under 10MB'}}
+        statusVariant="tooltip"
+      />,
+    );
+    await user.click(screen.getByRole('button', {name: 'Error details'}));
+    expect(click).not.toHaveBeenCalled();
+    click.mockRestore();
+  });
+
+  it.each(['input', 'dropzone'] as const)(
+    'keeps a statusVariant="tooltip" message reachable while loading in %s mode',
+    mode => {
+      render(
+        <FileInput
+          label="Upload"
+          value={null}
+          onChange={() => {}}
+          mode={mode}
+          isLoading
+          status={{type: 'error', message: 'File must be under 10MB'}}
+          statusVariant="tooltip"
+        />,
+      );
+      expectReachableTooltipStatus('File must be under 10MB');
+    },
+  );
 });