@astryxdesign/lab 0.7.3-canary.fba04ed → 0.7.4-canary.3f6ea7d

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/lab",
-  "version": "0.7.3-canary.fba04ed",
+  "version": "0.7.4-canary.3f6ea7d",
   "description": "Experimental Astryx components — published to npm only under the @canary dist-tag for early testing; never released as a stable (latest) version.",
   "author": "Meta Open Source",
   "license": "MIT",
@@ -49,7 +49,7 @@
   },
   "peerDependencies": {
     "@stylexjs/stylex": ">=0.10.0",
-    "@astryxdesign/core": "0.7.3-canary.fba04ed",
+    "@astryxdesign/core": "0.7.4-canary.3f6ea7d",
     "react": ">=19.0.0",
     "react-dom": ">=19.0.0"
   },
@@ -59,8 +59,8 @@
     "d3-shape": "^3.2.0"
   },
   "devDependencies": {
-    "@astryxdesign/a11y-spec": "0.7.3-canary.fba04ed",
-    "@astryxdesign/cli": "0.7.3-canary.fba04ed",
+    "@astryxdesign/a11y-spec": "0.7.4-canary.3f6ea7d",
+    "@astryxdesign/cli": "0.7.4-canary.3f6ea7d",
     "@babel/cli": "^7.29.7",
     "@babel/core": "^7.29.7",
     "@babel/preset-react": "^7.29.7",

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

@@ -0,0 +1,114 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file CircularProgress.a11y.chromium.spec.ts
+ * @input Built CircularProgress stories and PROGRESSBAR_PATTERN in real Chromium
+ * @output Browser evidence for every progressbar expectation across the binding's states, reconciled against the exact known failures
+ * @position Chromium lane of the CircularProgress binding
+ */
+
+import {
+  expect,
+  test,
+  type CDPSession,
+  type Locator,
+  type Page,
+} from '@playwright/test';
+import {
+  PROGRESSBAR_PATTERN,
+  blockingResults,
+  checkAccessibilitySpec,
+  formatFailures,
+  neverExercised,
+  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 {CIRCULAR_PROGRESS_KNOWN_FAILURES} from './CircularProgress.a11y.known-failures';
+import {
+  CIRCULAR_PROGRESS_BINDING_STATES,
+  type CircularProgressBindingState,
+} from './CircularProgress.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();
+});
+
+function storyUrl(storyId: string): string {
+  return `${storybook.origin}/iframe.html?id=${storyId}&viewMode=story`;
+}
+
+async function mountState(
+  page: Page,
+  state: CircularProgressBindingState,
+): Promise<{subject: Locator; related: Record<string, Locator>}> {
+  await page.goto(storyUrl(state.storyId), {waitUntil: 'load'});
+  await holdMotionStill(page);
+  const subject = page
+    .locator('#storybook-root')
+    .getByRole('progressbar', {name: state.facts.name});
+  await subject.waitFor({state: 'attached'});
+  return {subject, related: {}};
+}
+
+async function runState(
+  page: Page,
+  cdp: CDPSession,
+  state: CircularProgressBindingState,
+): Promise<BindingResult> {
+  return checkAccessibilitySpec({
+    spec: PROGRESSBAR_PATTERN,
+    binding: 'CircularProgress',
+    state: state.id,
+    facts: state.facts,
+    knownFailures: CIRCULAR_PROGRESS_KNOWN_FAILURES,
+    mount: async () => {
+      const {subject, related} = await mountState(page, state);
+      return createChromiumHarness({page, cdp, subject, related});
+    },
+  });
+}
+
+test('every progressbar expectation is exercised by a CircularProgress state', async ({
+  page,
+}) => {
+  const cdp = await page.context().newCDPSession(page);
+  const results: BindingResult[] = [];
+  for (const state of CIRCULAR_PROGRESS_BINDING_STATES) {
+    results.push(await runState(page, cdp, state));
+  }
+  expect(neverExercised(results)).toEqual([]);
+  expect(
+    unmatchedKnownFailures(CIRCULAR_PROGRESS_KNOWN_FAILURES, results),
+  ).toEqual([]);
+});
+
+for (const state of CIRCULAR_PROGRESS_BINDING_STATES) {
+  test(`CircularProgress [${state.id}] — ${state.summary}`, async ({page}) => {
+    const cdp = await page.context().newCDPSession(page);
+    const result = await runState(page, cdp, state);
+    const report = summarize(PROGRESSBAR_PATTERN, [result]);
+    // Required rows block (AST-020 FR9); advisory rows and exact known
+    // failures report.
+    expect(formatFailures(blockingResults([result]))).toBe('');
+    expect(report.unrunLayers).toEqual([]);
+    expect(report.counts.unexpectedPass).toBe(0);
+  });
+}

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

@@ -0,0 +1,12 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file CircularProgress.a11y.known-failures.ts
+ * @input The exact progressbar-contract failures the shipped CircularProgress produces today
+ * @output CIRCULAR_PROGRESS_KNOWN_FAILURES — records both lanes reconcile against, so a fix shows up as an unexpected pass and any other failure stays a failure
+ * @position Known-failure ledger for the CircularProgress binding
+ */
+
+import type {KnownFailure} from '@astryxdesign/a11y-spec';
+
+export const CIRCULAR_PROGRESS_KNOWN_FAILURES: ReadonlyArray<KnownFailure> = [];

package/src/CircularProgress/__tests__/CircularProgress.a11y.renders.tsx

@@ -0,0 +1,41 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file CircularProgress.a11y.renders.tsx
+ * @input One CircularProgress binding state
+ * @output The React tree every lane renders for that state (the jsdom test directly, the story through Storybook)
+ * @position Shared fixture for the CircularProgress binding
+ */
+
+import type {ReactElement} from 'react';
+import {CircularProgress} from '../CircularProgress';
+import {
+  formatSteps,
+  type CircularProgressBindingState,
+} from './CircularProgress.a11y.states';
+
+export function renderCircularProgressState(
+  state: CircularProgressBindingState,
+): ReactElement {
+  return (
+    <div style={{padding: 24}}>
+      <CircularProgress
+        label={state.facts.name}
+        // An indeterminate state still passes a value, so the proof shows the
+        // ring withholds it rather than never having had one.
+        value={state.facts.value ?? 50}
+        max={state.facts.max}
+        isLabelHidden={state.isLabelHidden}
+        hasValueLabel={state.hasValueLabel}
+        formatValueLabel={state.formatsValue ? formatSteps : undefined}
+        isIndeterminate={state.isIndeterminate}
+        isDisabled={state.isDisabled}>
+        {state.centerLink != null ? (
+          <a href="#upload-details">{state.centerLink}</a>
+        ) : null}
+      </CircularProgress>
+    </div>
+  );
+}

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

@@ -0,0 +1,106 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file CircularProgress.a11y.states.ts
+ * @input CircularProgress's representative states and the facts PROGRESSBAR_PATTERN reads
+ * @output CIRCULAR_PROGRESS_BINDING_STATES and the explicit ownership exclusions for this binding
+ * @position Binding inventory shared by the jsdom test, the Chromium spec, and the story
+ */
+
+import type {ProgressbarStateFacts} from '@astryxdesign/a11y-spec';
+
+export interface CircularProgressBindingState {
+  readonly id: string;
+  readonly summary: string;
+  readonly storyId: string;
+  readonly facts: ProgressbarStateFacts;
+  /** Props beyond label/value/max that shape the state. */
+  readonly isLabelHidden?: boolean;
+  readonly hasValueLabel?: boolean;
+  readonly formatsValue?: boolean;
+  readonly isIndeterminate?: boolean;
+  readonly isDisabled?: boolean;
+  /**
+   * A focusable link rendered as the ring's center content, which must sit
+   * beside the progress bar rather than inside its presentational subtree.
+   */
+  readonly centerLink?: string;
+}
+
+function facts(
+  overrides: Partial<ProgressbarStateFacts> = {},
+): ProgressbarStateFacts {
+  return {
+    name: 'Upload',
+    value: 40,
+    min: 0,
+    max: 100,
+    valueText: '40%',
+    ...overrides,
+  };
+}
+
+const story = (id: string) => `a11y-progressbar--circular-progress-${id}`;
+
+/** The custom formatter the `formatted` state passes, so its facts can quote the text. */
+export const formatSteps = (value: number, max: number): string =>
+  `${value} of ${max}`;
+
+export const CIRCULAR_PROGRESS_BINDING_STATES = [
+  {
+    id: 'determinate',
+    summary:
+      'a CircularProgress at 40 of 0–100 with its default hidden label and percentage',
+    storyId: story('determinate'),
+    facts: facts(),
+  },
+  {
+    id: 'formatted',
+    summary:
+      'a CircularProgress with a custom formatter shown in the ring: 3 of 10 speaks "3 of 10"',
+    storyId: story('formatted'),
+    facts: facts({name: 'Steps', value: 3, max: 10, valueText: '3 of 10'}),
+    hasValueLabel: true,
+    formatsValue: true,
+  },
+  {
+    id: 'label-visible',
+    summary: 'a CircularProgress whose label is shown names the ring with it',
+    storyId: story('label-visible'),
+    facts: facts({name: 'Storage used'}),
+    isLabelHidden: false,
+  },
+  {
+    id: 'indeterminate',
+    summary:
+      'an indeterminate CircularProgress with hasValueLabel claims no value or text',
+    storyId: story('indeterminate'),
+    facts: facts({name: 'Loading data', value: null, valueText: null}),
+    isIndeterminate: true,
+    hasValueLabel: true,
+  },
+  {
+    id: 'center-content',
+    summary:
+      'a disabled CircularProgress whose center content is a focusable link: the link sits beside the ring, not inside it',
+    storyId: story('center-content'),
+    facts: facts({value: 75, valueText: '75%'}),
+    isDisabled: true,
+    centerLink: 'Upload details',
+  },
+] as const satisfies ReadonlyArray<CircularProgressBindingState>;
+
+export const CIRCULAR_PROGRESS_EXCLUSIONS = [
+  {
+    id: 'value-clamping',
+    owner: 'CircularProgress.test.tsx clamping and non-finite value tests',
+    reason:
+      'Clamping an out-of-range or non-finite value before it reaches aria-valuenow is component input handling; this binding proves the value the ring exposes once it is in range.',
+  },
+  {
+    id: 'ring-geometry',
+    owner: 'CircularProgress.test.tsx size and dash-offset tests',
+    reason:
+      'Ring size, stroke, and the dash offset that draws the completed arc are paint geometry; this binding proves the programmatic value they illustrate.',
+  },
+] as const;

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

@@ -0,0 +1,108 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+/** @vitest-environment jsdom */
+
+/**
+ * @file CircularProgress.a11y.test.tsx
+ * @input PROGRESSBAR_PATTERN bound to CircularProgress's representative states
+ * @output jsdom-lane proof of the DOM expectations and an honest "unrun" report for the browser layers
+ * @position Binding test for the CircularProgress binding (the Chromium spec covers the rest)
+ */
+
+import {cleanup, render, screen} from '@testing-library/react';
+import {describe, expect, it} from 'vitest';
+import {
+  PROGRESSBAR_PATTERN,
+  checkAccessibilitySpec,
+  createJsdomHarness,
+  expectAccessibilitySpec,
+  summarize,
+  type BindingResult,
+} from '@astryxdesign/a11y-spec';
+import {CIRCULAR_PROGRESS_KNOWN_FAILURES} from './CircularProgress.a11y.known-failures';
+import {renderCircularProgressState} from './CircularProgress.a11y.renders';
+import {
+  CIRCULAR_PROGRESS_BINDING_STATES,
+  CIRCULAR_PROGRESS_EXCLUSIONS,
+  type CircularProgressBindingState,
+} from './CircularProgress.a11y.states';
+
+function progressbar(state: CircularProgressBindingState): HTMLElement {
+  return screen.getByRole('progressbar', {name: state.facts.name});
+}
+
+async function checkState(
+  state: CircularProgressBindingState,
+): Promise<BindingResult> {
+  return checkAccessibilitySpec({
+    spec: PROGRESSBAR_PATTERN,
+    binding: 'CircularProgress',
+    state: state.id,
+    facts: state.facts,
+    knownFailures: CIRCULAR_PROGRESS_KNOWN_FAILURES,
+    mount: async () => {
+      render(renderCircularProgressState(state));
+      return createJsdomHarness({subject: progressbar(state), related: {}});
+    },
+    unmount: cleanup,
+  });
+}
+
+describe('CircularProgress — progressbar pattern, jsdom lane', () => {
+  it.each(
+    CIRCULAR_PROGRESS_BINDING_STATES.map(
+      state => [state.id, state.summary, state] as const,
+    ),
+  )('%s — %s', async (_id, _summary, state) => {
+    await expectAccessibilitySpec({
+      spec: PROGRESSBAR_PATTERN,
+      binding: 'CircularProgress',
+      state: state.id,
+      facts: state.facts,
+      knownFailures: CIRCULAR_PROGRESS_KNOWN_FAILURES,
+      render: () => {
+        render(renderCircularProgressState(state));
+      },
+      subject: () => progressbar(state),
+      related: () => ({}),
+      cleanup,
+    });
+  });
+
+  it('runs the DOM layer and reports the browser-owned outcomes as unrun', async () => {
+    const results: BindingResult[] = [];
+    for (const state of CIRCULAR_PROGRESS_BINDING_STATES) {
+      results.push(await checkState(state));
+    }
+    const report = summarize(PROGRESSBAR_PATTERN, results);
+    expect(report.counts.pass).toBeGreaterThan(0);
+    expect(report.unrunLayers).toEqual(['accessibility-tree']);
+    expect(report.counts.unexpectedPass).toBe(0);
+  });
+});
+
+describe('CircularProgress binding inventory', () => {
+  it('gives every representative state a distinct checked-in story', () => {
+    const stories = CIRCULAR_PROGRESS_BINDING_STATES.map(
+      state => state.storyId,
+    );
+    expect(new Set(stories).size).toBe(stories.length);
+  });
+
+  it('keeps clamping and ring-geometry ownership explicit', () => {
+    expect(CIRCULAR_PROGRESS_EXCLUSIONS.map(exclusion => exclusion.id)).toEqual(
+      ['value-clamping', 'ring-geometry'],
+    );
+    for (const exclusion of CIRCULAR_PROGRESS_EXCLUSIONS) {
+      expect(exclusion.owner.length, exclusion.id).toBeGreaterThan(20);
+      expect(exclusion.reason.length, exclusion.id).toBeGreaterThan(80);
+    }
+  });
+
+  it('renders exactly one named progress bar for every state', () => {
+    for (const state of CIRCULAR_PROGRESS_BINDING_STATES) {
+      render(renderCircularProgressState(state));
+      expect(progressbar(state), state.id).toBeTruthy();
+      cleanup();
+    }
+  });
+});