@astryxdesign/core 0.7.6-canary.f73623d → 0.7.6-canary.f78b205

package/src/Switch/__tests__/Switch.a11y.chromium.spec.ts

@@ -1,211 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-// @pr-a11y release-only
-
-/**
- * @file Switch.a11y.chromium.spec.ts
- * @input Uses @playwright/test, @astryxdesign/a11y-spec (the switch contract,
- *   the Chromium harness, the runner, the Storybook server) and the checked-in
- *   Switch stories
- * @output The Chromium lane of Switch's binding to the shared switch pattern:
- *   the computed accessibility tree, real focus, and real activation.
- * @position The lane that carries most of this contract. jsdom cannot compute a
- *   role or a name, cannot resolve a tab sequence, and cannot turn a key press
- *   into an activation, so those outcomes are proven here or not at all.
- *
- * Run it with:
- *   pnpm storybook:build && npx playwright install chromium
- *   pnpm test:a11y-contract
- *
- * SYNC: States live in ./Switch.a11y.states.ts, known failures in
- *   ./Switch.a11y.known-failures.ts, both shared with the jsdom lane.
- */
-
-import {expect, test, type CDPSession, type Page} from '@playwright/test';
-import {
-  SWITCH_PATTERN,
-  blockingResults,
-  formatFailures,
-  formatReport,
-  neverExercised,
-  checkAccessibilitySpec,
-  spokenWords,
-  summarize,
-  unmatchedKnownFailures,
-  type BindingResult,
-} from '@astryxdesign/a11y-spec';
-import {
-  createChromiumHarness,
-  holdMotionStill,
-} from '@astryxdesign/a11y-spec/chromium';
-import {
-  DEFAULT_STORYBOOK_DIR,
-  serveStorybook,
-  type StaticServer,
-} from '@astryxdesign/a11y-spec/storybook';
-import {SWITCH_KNOWN_FAILURES} from './Switch.a11y.known-failures';
-import {
-  REMOTE_CONTROL_LABEL,
-  SWITCH_BINDING_STATES,
-  type SwitchBindingState,
-} from './Switch.a11y.states';
-
-let storybook: StaticServer;
-
-test.beforeAll(async () => {
-  storybook = await serveStorybook(
-    process.env.ASTRYX_STORYBOOK_DIR ?? DEFAULT_STORYBOOK_DIR,
-  );
-});
-
-test.afterAll(async () => {
-  await storybook?.close();
-});
-
-/** Load the story and put it into the state this row describes. */
-async function mountState(
-  page: Page,
-  state: SwitchBindingState,
-): Promise<void> {
-  await page.goto(
-    `${storybook.origin}/iframe.html?id=${state.storyId}&viewMode=story`,
-    {waitUntil: 'load'},
-  );
-  await holdMotionStill(page);
-  const root = page.locator('#storybook-root');
-  await root.getByRole('switch').waitFor({state: 'attached'});
-  if (state.arrivesBy === 'controlled-update') {
-    // Getting into this state is the owner's doing, not the user's: the story's
-    // second control changes the value the switch is given. Doing it here, in
-    // the mount, keeps every expectation about the switch.
-    await root.getByRole('button', {name: REMOTE_CONTROL_LABEL}).click();
-    // A mount precondition, not a contract claim: if the owner's change never
-    // reached the control, every expectation below would be about a state this
-    // binding is not in.
-    await root
-      .getByRole('switch', {checked: state.facts.checked})
-      .waitFor({state: 'attached'});
-  }
-}
-
-async function runState(
-  page: Page,
-  cdp: CDPSession,
-  state: SwitchBindingState,
-): Promise<BindingResult> {
-  return checkAccessibilitySpec({
-    spec: SWITCH_PATTERN,
-    binding: 'Switch',
-    state: state.id,
-    facts: state.facts,
-    knownFailures: SWITCH_KNOWN_FAILURES,
-    // Reload per expectation: each one starts from the state the story
-    // renders, not from whatever the previous expectation toggled it to.
-    mount: async () => {
-      await mountState(page, state);
-      return createChromiumHarness({
-        page,
-        subject: page.locator('#storybook-root').getByRole('switch'),
-        cdp,
-      });
-    },
-  });
-}
-
-/** Astryx renders these after the label text; they are not part of it. */
-const FIELD_MARKERS = ['required', 'optional'];
-
-/**
- * Whether the page renders exactly the label the inventory claims.
- *
- * Word-for-word, not a prefix or a substring: "Sync" must not pass for "Sync
- * photos", or a half-written entry would sit here unnoticed. The one allowance
- * is Astryx's own trailing field marker, which the component adds and the
- * inventory names the label without.
- */
-function namesTheSameLabel(rendered: string, claimed: string): boolean {
-  const words = [...spokenWords(rendered)];
-  const last = words[words.length - 1];
-  if (last != null && FIELD_MARKERS.includes(last)) {
-    words.pop();
-  }
-  const expected = spokenWords(claimed);
-  return (
-    words.length === expected.length &&
-    words.every((word, index) => word === expected[index])
-  );
-}
-
-/**
- * The inventory AST-021 FR2 asks for, checked against the page rather than
- * trusted. It is deliberately NOT part of the shared spec: a wrong entry
- * here is a stale inventory, and reporting it as a WCAG 2.5.3 failure would put
- * a metadata typo and a real accessibility defect in the same bucket.
- */
-test('the state inventory describes the labels the page actually renders', async ({
-  page,
-}) => {
-  const cdp = await page.context().newCDPSession(page);
-  const wrong: string[] = [];
-  for (const state of SWITCH_BINDING_STATES) {
-    await mountState(page, state);
-    const harness = createChromiumHarness({
-      page,
-      subject: page.locator('#storybook-root').getByRole('switch'),
-      cdp,
-    });
-    const rendered = await (await harness.subject()).visibleLabelText();
-    const matches =
-      state.visibleLabel == null
-        ? rendered == null
-        : rendered != null && namesTheSameLabel(rendered, state.visibleLabel);
-    if (!matches) {
-      wrong.push(
-        `${state.id}: inventory says ${JSON.stringify(state.visibleLabel)}, page renders ${JSON.stringify(rendered)}`,
-      );
-    }
-  }
-  expect(wrong).toEqual([]);
-});
-
-// Each state's result, recorded by its own test below so the whole-suite check
-// at the end reads it instead of measuring every state a second time. A state
-// whose test did not run in this worker (a filtered run, or a worker restarted
-// after a failure) is measured by the whole-suite check itself.
-const recorded = new Map<string, BindingResult>();
-
-for (const state of SWITCH_BINDING_STATES) {
-  test(`Switch [${state.id}] — ${state.summary}`, async ({page}) => {
-    const cdp = await page.context().newCDPSession(page);
-    const result = await runState(page, cdp, state);
-    recorded.set(state.id, result);
-    const report = summarize(SWITCH_PATTERN, [result]);
-    // eslint-disable-next-line no-console -- the report is this run's artifact
-    console.log(formatReport(report));
-
-    expect(formatFailures(blockingResults([result]))).toBe('');
-    // Every layer this contract assigns is observable here, so a state that
-    // reports one as unrun means the harness lost a capability, not that the
-    // outcome is covered.
-    expect(report.unrunLayers).toEqual([]);
-    expect(report.counts.unexpectedPass).toBe(0);
-  });
-}
-
-test('every expectation is exercised by at least one bound state', async ({
-  page,
-}) => {
-  // A whole-binding sweep: every state's result, read from its own test or,
-  // when that test did not run in this worker, measured here (minutes of real
-  // browser work in that case, so the budget stays).
-  test.setTimeout(5 * 60 * 1000);
-  const cdp = await page.context().newCDPSession(page);
-  const results: BindingResult[] = [];
-  for (const state of SWITCH_BINDING_STATES) {
-    results.push(recorded.get(state.id) ?? (await runState(page, cdp, state)));
-  }
-  // An expectation that applies to nothing is not coverage, however green it
-  // looks. This is the only place that can notice: the contract never sees the
-  // states, so whether a condition matches a real one is a binding-side fact.
-  expect(neverExercised(results)).toEqual([]);
-  expect(unmatchedKnownFailures(SWITCH_KNOWN_FAILURES, results)).toEqual([]);
-});

package/src/Switch/__tests__/Switch.a11y.known-failures.ts

@@ -1,28 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file Switch.a11y.known-failures.ts
- * @input Uses KnownFailure from @astryxdesign/a11y-spec
- * @output SWITCH_KNOWN_FAILURES — the switch-pattern outcomes Switch does not
- *   deliver today, each pinned to one expectation, binding, state, and layer.
- * @position Read by both Switch bindings. Nothing here is a pass: a recorded
- *   failure still runs, still fails, and is reported as debt.
- *
- * `docs/specs/AST-021/spec.md` FR8–FR10 govern this file:
- *
- * - a record names the expectation, binding, state, evidence layer, exact
- *   failure, user impact, and why the migration does not fix it;
- * - it covers only that exact failure — a different message, another state, or
- *   a wider failure still fails the build;
- * - when the outcome starts passing, the run reports an unexpected pass and the
- *   record must be deleted rather than left standing.
- *
- * Adding or widening a record after the baseline is an owner decision with a
- * linked defect, not a routine test update.
- *
- * SYNC: Deleting a record should close, or follow, its linked issue.
- */
-
-import type {KnownFailure} from '@astryxdesign/a11y-spec';
-
-export const SWITCH_KNOWN_FAILURES: ReadonlyArray<KnownFailure> = [];

package/src/Switch/__tests__/Switch.a11y.states.ts

@@ -1,275 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file Switch.a11y.states.ts
- * @input Uses SwitchStateFacts from @astryxdesign/a11y-spec and SwitchProps
- * @output SWITCH_BINDING_STATES — every Switch state that can change the shared
- *   switch-pattern outcome, what each declares itself to be, and how each is
- *   mounted in either lane.
- * @position The binding inventory required before any assertion moves
- *   (`docs/specs/AST-021/spec.md` FR2, FR4). Shared by the jsdom and Chromium
- *   bindings so both cover the same states and cannot drift apart.
- *
- * A state earns a row when it can change what the switch pattern promises: a
- * different exposed state, a different operability, a different name source, a
- * different attached description. States that change only appearance — size,
- * label position, label spacing, width, theme — cannot, so they stay in
- * Switch.test.tsx where the component owns them.
- *
- * SYNC: Every row's `storyId` must exist in
- * - /apps/storybook/stories/Switch.stories.tsx
- */
-
-import type {SwitchStateFacts} from '@astryxdesign/a11y-spec';
-import type {SwitchProps} from '../Switch';
-
-/**
- * The label of the second control the ControlledUpdate story renders beside the
- * switch. Both lanes press it to reach `on-after-controlled-update`.
- *
- * SYNC: /apps/storybook/stories/Switch.stories.tsx — the ControlledUpdate story
- */
-export const REMOTE_CONTROL_LABEL = 'Turn on remotely';
-
-export interface SwitchBindingState {
-  /** Stable state id. Named by known-failure records, so it does not churn. */
-  readonly id: string;
-  /** What this state is, for the report and the test name. */
-  readonly summary: string;
-  /**
-   * What the state declares itself to be. `checked` is compared against what
-   * the browser exposes, so a binding cannot pass by rendering on and reporting
-   * off. The rest select which expectations apply to this state — declaring a
-   * state described, disabled, required, or in error turns those expectations
-   * on; it does not assert the negative when they are false.
-   */
-  readonly facts: SwitchStateFacts;
-  /**
-   * The label this state is expected to render where a person can read it, or
-   * null when it renders none.
-   *
-   * INVENTORY, not contract input. The shared 2.5.3 expectation reads the
-   * rendered label itself and never consults this — otherwise a binding could
-   * switch a criterion off by describing itself. This exists so the inventory
-   * AST-021 FR2 asks for is checked against the page rather than trusted, and a
-   * typo here is reported as a stale inventory, not as a standards failure.
-   */
-  readonly visibleLabel: string | null;
-  /**
-   * The props the jsdom lane renders the switch with. `value` is always the
-   * value it is FIRST rendered with — for a state the owner updates into, that
-   * is the value before the update, and `facts.checked` is where the update
-   * takes it.
-   */
-  readonly props: Omit<SwitchProps, 'onChange'>;
-  /** The checked-in Storybook story the Chromium lane drives. */
-  readonly storyId: string;
-  /**
-   * How this state comes to be, when it is not simply how the binding first
-   * renders. `controlled-update` means the switch renders with `props.value`
-   * and the owner then moves it to `facts.checked` through a second control —
-   * nobody touched the switch — so both lanes press that control during mount
-   * rather than asserting anything about it.
-   */
-  readonly arrivesBy?: 'controlled-update';
-}
-
-export const SWITCH_BINDING_STATES: ReadonlyArray<SwitchBindingState> = [
-  {
-    id: 'off',
-    summary: 'the default: a labelled switch that is off and can be turned on',
-    storyId: 'core-switch--default',
-    visibleLabel: 'Enable notifications',
-    props: {label: 'Enable notifications', value: false},
-    facts: {
-      checked: false,
-      operable: true,
-      focusable: true,
-      disabled: false,
-      described: false,
-      required: false,
-      invalid: false,
-    },
-  },
-  {
-    id: 'on',
-    summary: 'a switch whose controlled value is already on',
-    storyId: 'core-switch--on',
-    visibleLabel: 'Notifications enabled',
-    props: {label: 'Notifications enabled', value: true},
-    facts: {
-      checked: true,
-      operable: true,
-      focusable: true,
-      disabled: false,
-      described: false,
-      required: false,
-      invalid: false,
-    },
-  },
-  {
-    id: 'described',
-    summary: 'a switch with supporting text under its label',
-    storyId: 'core-switch--with-description',
-    visibleLabel: 'Dark mode',
-    props: {
-      label: 'Dark mode',
-      description: 'Switch to a darker color scheme for reduced eye strain.',
-      value: false,
-    },
-    facts: {
-      checked: false,
-      operable: true,
-      focusable: true,
-      disabled: false,
-      described: true,
-      required: false,
-      invalid: false,
-    },
-  },
-  {
-    id: 'label-hidden',
-    summary:
-      'a switch whose label is read by assistive technology but not rendered visibly',
-    storyId: 'core-switch--with-hidden-label',
-    visibleLabel: null,
-    props: {label: 'Toggle row', isLabelHidden: true, value: false},
-    facts: {
-      checked: false,
-      operable: true,
-      focusable: true,
-      disabled: false,
-      // Nothing is rendered visibly, so WCAG 2.5.3 has nothing to compare against.
-      described: false,
-      required: false,
-      invalid: false,
-    },
-  },
-  {
-    id: 'disabled',
-    summary: 'a disabled switch that keeps its tab stop',
-    storyId: 'core-switch--disabled',
-    visibleLabel: 'Premium feature',
-    props: {
-      label: 'Premium feature',
-      description: 'Upgrade to enable this option',
-      isDisabled: true,
-      value: false,
-    },
-    facts: {
-      checked: false,
-      operable: false,
-      focusable: true,
-      disabled: true,
-      described: true,
-      required: false,
-      invalid: false,
-    },
-  },
-  {
-    id: 'focusable-disabled',
-    summary:
-      'a switch disabled with a reason: still focusable so the reason is discoverable, still not operable',
-    storyId: 'core-switch--disabled-with-message',
-    visibleLabel: 'Enable notifications',
-    props: {
-      label: 'Enable notifications',
-      isDisabled: true,
-      disabledMessage: 'Notifications are turned off org-wide',
-      value: false,
-    },
-    facts: {
-      checked: false,
-      operable: false,
-      focusable: true,
-      disabled: true,
-      described: true,
-      required: false,
-      invalid: false,
-    },
-  },
-  {
-    id: 'required',
-    summary: 'a switch that has to be on before the form can be submitted',
-    storyId: 'core-switch--required',
-    visibleLabel: 'Accept terms and conditions',
-    props: {
-      label: 'Accept terms and conditions',
-      isRequired: true,
-      value: false,
-    },
-    facts: {
-      checked: false,
-      operable: true,
-      focusable: true,
-      disabled: false,
-      described: false,
-      required: true,
-      invalid: false,
-    },
-  },
-  {
-    id: 'invalid',
-    // Chromium also derives an invalid state from constraint validation on a
-    // required-but-off checkbox, so this state proves that a switch in error is
-    // reported as being in error — not that Switch's own error-status-to-
-    // aria-invalid mapping is what does it. That mapping stays gated in
-    // Switch.test.tsx.
-    summary: 'a required switch reporting an error, with the message attached',
-    storyId: 'core-switch--with-error-status',
-    visibleLabel: 'Accept terms and conditions',
-    props: {
-      label: 'Accept terms and conditions',
-      isRequired: true,
-      status: {
-        type: 'error',
-        message: 'You must accept the terms to continue',
-      },
-      value: false,
-    },
-    facts: {
-      checked: false,
-      operable: true,
-      focusable: true,
-      disabled: false,
-      described: true,
-      required: true,
-      invalid: true,
-    },
-  },
-  {
-    id: 'on-after-controlled-update',
-    summary:
-      'a switch the owner turned on through another control — the value changed, nobody touched the switch',
-    storyId: 'core-switch--controlled-update',
-    arrivesBy: 'controlled-update',
-    visibleLabel: 'Sync photos',
-    props: {label: 'Sync photos', value: false},
-    facts: {
-      checked: true,
-      operable: true,
-      focusable: true,
-      disabled: false,
-      described: false,
-      required: false,
-      invalid: false,
-    },
-  },
-  {
-    id: 'loading',
-    summary:
-      'a switch waiting on the change it started: focusable, busy, and not operable until it settles',
-    storyId: 'core-switch--loading',
-    visibleLabel: 'Sync photos',
-    props: {label: 'Sync photos', isLoading: true, value: false},
-    facts: {
-      checked: false,
-      operable: false,
-      focusable: true,
-      disabled: false,
-      described: false,
-      required: false,
-      invalid: false,
-    },
-  },
-];

package/src/Switch/__tests__/Switch.a11y.test.tsx

@@ -1,144 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file Switch.a11y.test.tsx
- * @input Uses @astryxdesign/a11y-spec (the switch contract, the jsdom harness,
- *   the runner), @testing-library/react, and the Switch component
- * @output The jsdom lane of Switch's binding to the shared switch pattern.
- * @position Binds Switch to the reusable contract at the layers jsdom can
- *   honestly observe. The accessibility-tree and real-browser layers are bound
- *   in Switch.a11y.chromium.spec.ts, and this lane reports them as unrun rather
- *   than pretending markup proves them.
- *
- * What is NOT here is as deliberate as what is. Callback payloads, form
- * participation, tooltip composition, and styling stay in Switch.test.tsx: they
- * are Switch's own contract, not the switch pattern's
- * (`docs/specs/AST-021/spec.md` FR5).
- *
- * SYNC: States live in ./Switch.a11y.states.ts, known failures in
- *   ./Switch.a11y.known-failures.ts, both shared with the Chromium lane.
- */
-
-import {useState} from 'react';
-import {describe, expect, it} from 'vitest';
-import {cleanup, fireEvent, render, screen} from '@testing-library/react';
-import {
-  SWITCH_PATTERN,
-  checkAccessibilitySpec,
-  createJsdomHarness,
-  expectAccessibilitySpec,
-  summarize,
-  type BindingResult,
-} from '@astryxdesign/a11y-spec';
-import {Switch, type SwitchProps} from '../Switch';
-import {SWITCH_KNOWN_FAILURES} from './Switch.a11y.known-failures';
-import {
-  REMOTE_CONTROL_LABEL,
-  SWITCH_BINDING_STATES,
-  type SwitchBindingState,
-} from './Switch.a11y.states';
-
-/**
- * Switch is controlled, so a binding that pinned `value` would be testing a
- * switch nobody ships. The wrapper is the consumer's own wiring.
- */
-function ControlledSwitch({value, ...props}: Omit<SwitchProps, 'onChange'>) {
-  const [checked, setChecked] = useState(value);
-  return <Switch {...props} value={checked} onChange={setChecked} />;
-}
-
-/**
- * The same switch, plus a second control its owner uses to change the value.
- * This is the controlled-update case: the value changes because the owner
- * changed it, not because anyone touched the switch — and the switch stays
- * operable afterwards. Mirrors the ControlledUpdate story the Chromium lane
- * drives, including the order, so Tab still reaches the switch first.
- */
-function RemotelyToggledSwitch({
-  value,
-  movesTo,
-  ...props
-}: Omit<SwitchProps, 'onChange'> & {movesTo: boolean}) {
-  const [checked, setChecked] = useState(value);
-  return (
-    <>
-      <Switch {...props} value={checked} onChange={setChecked} />
-      <button type="button" onClick={() => setChecked(movesTo)}>
-        {REMOTE_CONTROL_LABEL}
-      </button>
-    </>
-  );
-}
-
-function renderState(state: SwitchBindingState): void {
-  if (state.arrivesBy === 'controlled-update') {
-    render(
-      <RemotelyToggledSwitch {...state.props} movesTo={state.facts.checked} />,
-    );
-    fireEvent.click(screen.getByRole('button', {name: REMOTE_CONTROL_LABEL}));
-    // A render precondition, not a contract claim: if the owner's change never
-    // reached the control, every expectation would check the wrong state.
-    const control = screen.getByRole('switch', {hidden: true});
-    if ((control as HTMLInputElement).checked !== state.facts.checked) {
-      throw new Error(
-        `rendering "${state.id}" did not reach the declared state: the owner's change left the switch ${(control as HTMLInputElement).checked ? 'on' : 'off'}`,
-      );
-    }
-  } else {
-    render(<ControlledSwitch {...state.props} />);
-  }
-}
-
-async function expectState(state: SwitchBindingState): Promise<void> {
-  await expectAccessibilitySpec({
-    spec: SWITCH_PATTERN,
-    binding: 'Switch',
-    state: state.id,
-    facts: state.facts,
-    knownFailures: SWITCH_KNOWN_FAILURES,
-    render: () => renderState(state),
-    subject: () => screen.getByRole('switch', {hidden: true}),
-    cleanup,
-  });
-}
-
-async function checkState(state: SwitchBindingState): Promise<BindingResult> {
-  return checkAccessibilitySpec({
-    spec: SWITCH_PATTERN,
-    binding: 'Switch',
-    state: state.id,
-    facts: state.facts,
-    knownFailures: SWITCH_KNOWN_FAILURES,
-    mount: async () => {
-      renderState(state);
-      return createJsdomHarness({
-        subject: screen.getByRole('switch', {hidden: true}),
-      });
-    },
-    unmount: cleanup,
-  });
-}
-
-describe('Switch — the shared switch pattern, jsdom lane', () => {
-  it.each(
-    SWITCH_BINDING_STATES.map(
-      state => [state.id, state.summary, state] as const,
-    ),
-  )('%s (%s)', async (_id, _summary, state) => {
-    await expectState(state);
-  });
-
-  it('runs the DOM layer here and reports the higher layers as unrun', async () => {
-    const results: BindingResult[] = [];
-    for (const state of SWITCH_BINDING_STATES) {
-      results.push(await checkState(state));
-    }
-    const report = summarize(SWITCH_PATTERN, results);
-
-    // Something actually ran, or this lane would prove nothing at all.
-    expect(report.counts.pass).toBeGreaterThan(0);
-    // And what it could not see is named, not quietly counted as covered.
-    expect(report.unrunLayers).toEqual(['accessibility-tree', 'real-browser']);
-    expect(report.counts.unexpectedPass).toBe(0);
-  });
-});