@astryxdesign/core 0.7.1 → 0.7.2-canary.151434a

package/src/AspectRatio/__tests__/AspectRatioFitLayers.a11y.browser.spec.ts

@@ -0,0 +1,157 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file AspectRatioFitLayers.a11y.browser.spec.ts
+ * @input The built FitModes story (its rendered markup and compiled CSS) and
+ *   Tailwind's preflight.css
+ * @output Browser evidence that `fit` fills the box on the documented setups
+ * @position AspectRatio integration proof. Which rule sizes the child is a
+ *   cascade-layer question, and only a shipping engine resolves the cascade.
+ */
+
+import * as fs from 'node:fs';
+import {fileURLToPath} from 'node:url';
+import {expect, test, type Page} from '@playwright/test';
+import {
+  DEFAULT_STORYBOOK_DIR,
+  serveStorybook,
+  type StaticServer,
+} from '@astryxdesign/a11y-spec/storybook';
+
+const PREFLIGHT_CSS = fs.readFileSync(
+  fileURLToPath(import.meta.resolve('tailwindcss/preflight.css')),
+  'utf8',
+);
+
+// The layer order each setup guide declares, and the layer preflight goes in.
+const TAILWIND_SETUPS = [
+  {
+    name: 'Tailwind v4',
+    order:
+      '@layer reset, theme, base, astryx-base, astryx-theme, components, utilities;',
+    preflightLayer: 'base',
+  },
+  {
+    name: 'Tailwind v3',
+    order: '@layer reset, tw-preflight, astryx-base, astryx-theme;',
+    preflightLayer: 'tw-preflight',
+  },
+];
+
+// A 100×100 image in a 320px-wide 16:9 box: filling the box makes it 320×180.
+const IMAGE =
+  "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='100' height='100'/%3E";
+
+type Fit = 'cover' | 'contain';
+
+let storybook: StaticServer;
+test.beforeAll(async () => {
+  storybook = await serveStorybook(
+    process.env.ASTRYX_STORYBOOK_DIR ?? DEFAULT_STORYBOOK_DIR,
+  );
+});
+test.afterAll(async () => {
+  await storybook?.close();
+});
+
+/**
+ * The markup AspectRatio renders for `fit`, and every CSS rule the story
+ * page loaded, taken from the built story so the classes and rules are the
+ * component's real compiled output. The child image gets a fixed id, a
+ * local source and any extra class.
+ */
+async function captureStory(page: Page, fit: Fit, mediaClass: string) {
+  await page.goto(
+    `${storybook.origin}/iframe.html?id=core-aspectratio--fit-modes&viewMode=story`,
+  );
+  const wrapper = page.locator(`[data-astryx-aspect-ratio-override="${fit}"]`);
+  await expect(wrapper).toHaveCount(1);
+  return wrapper.evaluate(
+    (element, {image, extraClass}) => {
+      const root = element.parentElement?.cloneNode(true);
+      const media =
+        root instanceof HTMLElement ? root.querySelector('img') : null;
+      if (!(root instanceof HTMLElement) || media == null) {
+        throw new Error('FitModes no longer renders an img inside AspectRatio');
+      }
+      media.id = 'media';
+      media.src = image;
+      if (extraClass) {
+        media.classList.add(extraClass);
+      }
+      const css = [...document.styleSheets]
+        .flatMap(sheet => [...sheet.cssRules].map(rule => rule.cssText))
+        .join('\n');
+      return {html: root.outerHTML, css};
+    },
+    {image: IMAGE, extraClass: mediaClass},
+  );
+}
+
+/** Re-host the captured story with `before` CSS ahead of it and `after` CSS behind it. */
+async function measureMedia(
+  page: Page,
+  fit: Fit,
+  {
+    before = [],
+    after = [],
+    mediaClass = '',
+  }: {
+    before?: string[];
+    after?: string[];
+    mediaClass?: string;
+  },
+) {
+  const {html, css} = await captureStory(page, fit, mediaClass);
+  await page.setContent(
+    `<!doctype html><div style="width: 320px">${html}</div>`,
+  );
+  for (const content of [...before, css, ...after]) {
+    await page.addStyleTag({content});
+  }
+  await page.waitForFunction(
+    () => (document.getElementById('media') as HTMLImageElement).complete,
+  );
+  return page.evaluate(() => {
+    const media = document.getElementById('media');
+    if (!media) {
+      throw new Error('missing media');
+    }
+    const box = media.getBoundingClientRect();
+    return {
+      width: box.width,
+      height: box.height,
+      objectFit: getComputedStyle(media).objectFit,
+    };
+  });
+}
+
+for (const setup of TAILWIND_SETUPS) {
+  for (const fit of ['cover', 'contain'] as const) {
+    test(`fit="${fit}" fills the box on the ${setup.name} setup`, async ({
+      page,
+    }) => {
+      const media = await measureMedia(page, fit, {
+        before: [
+          setup.order,
+          `@layer ${setup.preflightLayer} { ${PREFLIGHT_CSS} }`,
+        ],
+      });
+      expect(media).toEqual({width: 320, height: 180, objectFit: fit});
+    });
+  }
+}
+
+test('fit fills the box with only Astryx CSS loaded', async ({page}) => {
+  const media = await measureMedia(page, 'cover', {});
+  expect(media).toEqual({width: 320, height: 180, objectFit: 'cover'});
+});
+
+test('a utility class on the child still wins over fit', async ({page}) => {
+  const media = await measureMedia(page, 'cover', {
+    before: [TAILWIND_SETUPS[0].order, `@layer base { ${PREFLIGHT_CSS} }`],
+    after: ['@layer utilities { .h-10 { height: 40px; } }'],
+    mediaClass: 'h-10',
+  });
+  expect(media).toEqual({width: 320, height: 40, objectFit: 'cover'});
+});

package/src/Button/Button.doc.mjs

@@ -138,7 +138,7 @@ export const docs = {
     {
       name: 'isLoading',
       type: 'boolean',
-      description: 'Shows a loading spinner and disables interaction. Announces "Loading" via a live region.',
+      description: 'Shows a loading spinner and blocks re-activation while staying focusable (aria-busy + aria-disabled, not native disabled, so keyboard focus is never dropped mid-action). Announces "Loading" via a live region.',
       default: 'false',
     },
     {
@@ -419,7 +419,7 @@ export const docsDense = {
     displayName: 'HTML name for form submission',
     value: 'HTML value for form submission',
     form: 'associates button with form element by ID',
-    isLoading: 'shows spinner+disables interaction; announces via live region',
+    isLoading: 'shows spinner, blocks re-activation but stays focusable (aria-disabled, not native disabled); announces via live region',
     icon: 'icon element rendered before label text; unsized Astryx Icon defaults to sm for sm/md buttons and md for lg',
     isIconOnly: 'when true, renders square icon-only button; label becomes aria-label',
     width: "Width of button. Numbers=pixels, strings=as-is (e.g. '100%' for full-width). Default: content width, capped at the container; label truncates w/ ellipsis in a narrow row; icon-only stays square.",

package/src/Button/Button.test.tsx

@@ -11,7 +11,13 @@
 
 import {readFileSync} from 'node:fs';
 import {describe, it, expect, vi} from 'vitest';
-import {render, screen, fireEvent, act} from '@testing-library/react';
+import {
+  render,
+  screen,
+  fireEvent,
+  createEvent,
+  act,
+} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {Button} from './Button';
 import * as stylex from '@stylexjs/stylex';
@@ -127,8 +133,9 @@ describe('Button', () => {
   it('shows isLoading state with spinner', () => {
     render(<Button label="Submit" isLoading />);
     const button = screen.getByRole('button');
-    // Button should be disabled when loading
-    expect(button).toBeDisabled();
+    // Busy is aria-disabled (focusable), not native disabled — see #4871.
+    expect(button).not.toBeDisabled();
+    expect(button).toHaveAttribute('aria-disabled', 'true');
     expect(button.className).toContain('styles.inactive');
     expect(button.className).not.toContain('styles.disabled');
   });
@@ -143,7 +150,7 @@ describe('Button', () => {
 
   it('sets aria-busy synchronously while clickAction is pending', async () => {
     // The spinner reveal is visually delayed (CSS animation-delay), but the
-    // loading DOM state — aria-busy and disabled — must not be delayed.
+    // loading DOM state — aria-busy and aria-disabled — must not be delayed.
     const user = userEvent.setup();
     let resolveAction: (() => void) | undefined;
     const clickAction = vi.fn(
@@ -157,7 +164,9 @@ describe('Button', () => {
 
     await user.click(button);
     expect(button).toHaveAttribute('aria-busy', 'true');
-    expect(button).toBeDisabled();
+    // Busy is aria-disabled (focusable), not native disabled — see #4871.
+    expect(button).not.toBeDisabled();
+    expect(button).toHaveAttribute('aria-disabled', 'true');
 
     await act(async () => {
       resolveAction?.();
@@ -165,6 +174,7 @@ describe('Button', () => {
     });
     expect(button).not.toHaveAttribute('aria-busy', 'true');
     expect(button).not.toBeDisabled();
+    expect(button).not.toHaveAttribute('aria-disabled');
   });
 
   it('renders the loading spinner with the inherit shade for every variant (#2717)', () => {
@@ -310,9 +320,10 @@ describe('Button', () => {
     );
     // endContent should still be in the DOM
     expect(screen.getByTestId('end')).toBeInTheDocument();
-    // Button should be disabled and have aria-busy
+    // Busy is aria-disabled (focusable), not native disabled — see #4871.
     const button = screen.getByRole('button');
-    expect(button).toBeDisabled();
+    expect(button).not.toBeDisabled();
+    expect(button).toHaveAttribute('aria-disabled', 'true');
     expect(button).toHaveAttribute('aria-busy', 'true');
   });
 
@@ -516,6 +527,111 @@ describe('Button', () => {
     expect(handleKeyDown).toHaveBeenCalledTimes(1);
   });
 
+  it('uses aria-disabled instead of disabled while isLoading, so the button stays focusable (#4871)', () => {
+    render(<Button label="Save" isLoading />);
+    const button = screen.getByRole('button');
+    // Native disabled would move focus to <body> the moment the action
+    // starts, losing the keyboard user's place — busy must stay
+    // aria-disabled + focusable per the "Disabled vs Busy" convention.
+    expect(button).not.toHaveAttribute('disabled');
+    expect(button).toHaveAttribute('aria-disabled', 'true');
+    expect(button).toHaveAttribute('aria-busy', 'true');
+    button.focus();
+    expect(button).toHaveFocus();
+  });
+
+  it('does not fire onClick while aria-disabled via isLoading', async () => {
+    const user = userEvent.setup();
+    const handleClick = vi.fn();
+    render(<Button label="Save" isLoading onClick={handleClick} />);
+    await user.click(screen.getByRole('button'));
+    expect(handleClick).not.toHaveBeenCalled();
+  });
+
+  it('does not let a click on a busy button reach a wrapping ancestor handler', async () => {
+    // A native `disabled` element never dispatches a click, so it never
+    // reaches an ancestor either. aria-disabled (busy-only) is a real,
+    // interactive element that still dispatches one — preventDefault alone
+    // only cancels the button's own default action, not propagation, so
+    // an unrelated wrapper (a clickable row/card/backdrop) would otherwise
+    // still fire.
+    const user = userEvent.setup();
+    const ancestorClick = vi.fn();
+    render(
+      <div onClick={ancestorClick}>
+        <Button label="Save" isLoading />
+      </div>,
+    );
+    await user.click(screen.getByRole('button'));
+    expect(ancestorClick).not.toHaveBeenCalled();
+  });
+
+  it('does not let a click on a busy-only anchor Button reach a wrapping ancestor handler', async () => {
+    const user = userEvent.setup();
+    const ancestorClick = vi.fn();
+    render(
+      <div onClick={ancestorClick}>
+        <Button label="Docs" href="https://example.com" isLoading />
+      </div>,
+    );
+    await user.click(screen.getByRole('link'));
+    expect(ancestorClick).not.toHaveBeenCalled();
+  });
+
+  it('suppresses activation keys but passes other keys while aria-disabled via isLoading', async () => {
+    const user = userEvent.setup();
+    const handleKeyDown = vi.fn();
+    render(<Button label="Save" isLoading onKeyDown={handleKeyDown} />);
+    const button = screen.getByRole('button');
+    button.focus();
+    await user.keyboard('{Enter}');
+    expect(handleKeyDown).not.toHaveBeenCalled();
+
+    await user.keyboard('{Escape}');
+    expect(handleKeyDown).toHaveBeenCalledTimes(1);
+  });
+
+  it('suppresses activation keys but passes other keys on a busy-only anchor Button', async () => {
+    // The button-rendered path suppresses Enter/Space while aria-disabled;
+    // the anchor-rendered path (href set, busy-only) shares the same
+    // handleKeyDown but only wires onClick, so a consumer onKeyDown still
+    // received Enter/Space on a busy link.
+    const user = userEvent.setup();
+    const handleKeyDown = vi.fn();
+    render(
+      <Button
+        label="Docs"
+        href="https://example.com"
+        isLoading
+        onKeyDown={handleKeyDown}
+      />,
+    );
+    const link = screen.getByRole('link');
+    link.focus();
+    await user.keyboard('{Enter}');
+    expect(handleKeyDown).not.toHaveBeenCalled();
+
+    await user.keyboard('{Escape}');
+    expect(handleKeyDown).toHaveBeenCalledTimes(1);
+  });
+
+  it('keeps native disabled (not aria-disabled) when isDisabled and not busy, even without a tooltip', () => {
+    render(<Button label="Save" isDisabled />);
+    const button = screen.getByRole('button');
+    expect(button).toHaveAttribute('disabled');
+    expect(button).not.toHaveAttribute('aria-disabled');
+  });
+
+  it('keeps native disabled when isDisabled and isLoading are both true (isDisabled wins)', () => {
+    render(<Button label="Save" isDisabled isLoading />);
+    const button = screen.getByRole('button');
+    // "isDisabled behavior unchanged: that stays native disabled" — busy-only
+    // aria-disabled is only for the case where busy is the SOLE reason the
+    // button can't be clicked, not when it's also genuinely isDisabled.
+    expect(button).toHaveAttribute('disabled');
+    expect(button).not.toHaveAttribute('aria-disabled');
+  });
+
   it('has a live region that announces loading state', () => {
     const {rerender} = render(<Button label="Submit" />);
     const button = screen.getByRole('button');
@@ -663,8 +779,6 @@ describe('Button', () => {
   });
 
   it('exposes aria-busy on the link-rendered button while loading', () => {
-    // Non-interruptible loading disables the button, which falls back to
-    // <button> rendering — so an anchor only shows loading when interruptible.
     render(
       <Button
         label="Docs"
@@ -682,6 +796,38 @@ describe('Button', () => {
     const link = screen.getByRole('link');
     expect(link).not.toHaveAttribute('aria-busy');
   });
+
+  it('stays an anchor while busy-only, not a disabled <button> fallback (#4871)', () => {
+    // Non-interruptible busy is exactly the isBusyOnlyDisabled case: not
+    // isDisabled, blocked only because a fire-once action is in flight.
+    // Swapping the element to <button disabled> here would drop focus the
+    // same way the native disabled attribute did (credit @AKnassa, #4879).
+    render(<Button label="Docs" href="https://example.com" isLoading />);
+    const link = screen.getByRole('link', {name: 'Docs'});
+    expect(link.tagName).toBe('A');
+    expect(link).toHaveAttribute('href', 'https://example.com');
+    expect(link).toHaveAttribute('aria-busy', 'true');
+    expect(link).toHaveAttribute('aria-disabled', 'true');
+    expect(link).not.toHaveAttribute('disabled');
+  });
+
+  it('keeps a busy-only anchor focusable and guards its navigation', () => {
+    render(<Button label="Docs" href="https://example.com" isLoading />);
+    const link = screen.getByRole('link', {name: 'Docs'});
+    link.focus();
+    expect(link).toHaveFocus();
+
+    const event = createEvent.click(link);
+    fireEvent(link, event);
+    expect(event.defaultPrevented).toBe(true);
+  });
+
+  it('falls back to <button disabled> for a truly disabled href Button', () => {
+    render(<Button label="Docs" href="https://example.com" isDisabled />);
+    expect(screen.queryByRole('link')).not.toBeInTheDocument();
+    const button = screen.getByRole('button', {name: 'Docs'});
+    expect(button).toBeDisabled();
+  });
 });
 
 describe('Button pressed state (touch)', () => {

package/src/Button/Button.tsx

@@ -594,26 +594,37 @@ export function Button({
   // the consumer is deliberately showing it.
   const delaySpinner = isPending || isInterruptible;
   const groupDisabled = buttonGroup?.isDisabled ?? false;
-  // When interruptible, the loading state drives the spinner and aria-busy but
-  // not disabled, so clicks keep landing and can interrupt the in-flight action.
-  const buttonDisabled =
-    isDisabled || groupDisabled || (isLoadingState && !isInterruptible);
-  // A loading button remains non-interactive, but its spinner communicates an
-  // active state and must retain contrast. Only explicitly disabled controls
-  // receive the visually dimmed treatment.
-  const visuallyDisabled = isDisabled || groupDisabled;
+  const isTrueDisabled = isDisabled || groupDisabled;
+  // Busy-only: the button can't fire again purely because an action is in
+  // flight, not because it's genuinely isDisabled/group-disabled. Per the API
+  // Conventions "Disabled vs Busy" rule, busy is visual-only (aria-busy +
+  // spinner) and must never take focusability away — the click-handler ref
+  // guard (actionInFlightRef) is what actually makes a fire-once action fire
+  // once, so the native disabled attribute adds nothing but a focus loss
+  // here. When interruptible, the loading state drives the spinner and
+  // aria-busy but not disabled at all, so clicks keep landing and can
+  // interrupt the in-flight action.
+  const isBusyOnlyDisabled =
+    !isTrueDisabled && isLoadingState && !isInterruptible;
+  const buttonDisabled = isTrueDisabled || isBusyOnlyDisabled;
   // isIconOnly prop is the source of truth for icon-only rendering.
   // When false (default), label is always rendered as visible text.
 
   const LinkComponent = useLinkComponent(as);
 
-  // Render as link when href is provided and button is not disabled.
-  // Disabled links are an accessibility anti-pattern — fall back to <button>.
-  const renderAsLink = href != null && !buttonDisabled;
+  // Render as link when href is provided and the button is not TRULY
+  // disabled. Disabled links are an accessibility anti-pattern, so a
+  // genuinely isDisabled/group-disabled button falls back to <button>.
+  // Busy-only does NOT fall back: swapping <a> for a disabled <button>
+  // mid-action would drop focus the same way the native attribute does
+  // (credit @AKnassa, #4879), which is exactly the bug this PR fixes.
+  const renderAsLink = href != null && !isTrueDisabled;
 
-  // Use aria-disabled when tooltip is present so the button remains focusable
-  // for keyboard users to reach the tooltip. Otherwise use native disabled.
-  const useAriaDisabled = tooltip != null && buttonDisabled;
+  // Use aria-disabled (button stays focusable) when busy-only, or when a
+  // tooltip is present so keyboard users can still reach it. A genuinely
+  // isDisabled/group-disabled button (not busy) keeps native disabled.
+  const useAriaDisabled =
+    buttonDisabled && (isBusyOnlyDisabled || tooltip != null);
 
   // Attach tooltip behavior via the hook rather than wrapping the button in a
   // <Tooltip> element. The hook adds hover/focus triggers to the button itself,
@@ -630,6 +641,16 @@ export function Button({
     // a re-click while pending starts a fresh action that interrupts the prior.
     if (buttonDisabled || (actionInFlightRef.current && !isInterruptible)) {
       e.preventDefault();
+      // A native `disabled` element never dispatches a click at all, so it
+      // never reaches a wrapping element's own handler either. An
+      // aria-disabled button (busy-only, or with a tooltip) is still a real,
+      // interactive element the DOM keeps dispatching clicks on —
+      // preventDefault alone only cancels the button's OWN default action
+      // (form submit, link navigation), not propagation. Without this, an
+      // unavailable Button inside a clickable row/card/backdrop still
+      // triggers that ancestor's action, which the previously native-disabled
+      // control never did.
+      e.stopPropagation();
       return;
     }
     props.onClick?.(e);
@@ -669,7 +690,7 @@ export function Button({
     isIconOnly && styles.iconOnly,
     interactionOverlayStyles.backgroundImage,
     buttonDisabled && styles.inactive,
-    visuallyDisabled && styles.disabled,
+    isTrueDisabled && styles.disabled,
     useAriaDisabled && styles.ariaDisabled,
     renderAsLink && styles.link,
     !buttonGroup && styles.pressable,
@@ -797,7 +818,9 @@ export function Button({
         {...describedByProp}
         {...edgeCompAttr}
         aria-busy={isLoadingState || undefined}
-        onClick={handleClick}>
+        aria-disabled={useAriaDisabled || undefined}
+        onClick={handleClick}
+        {...(handleKeyDown ? {onKeyDown: handleKeyDown} : null)}>
         {buttonContent}
       </LinkComponent>
     );

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

@@ -22,65 +22,4 @@
 
 import type {KnownFailure} from '@astryxdesign/a11y-spec';
 
-export const BUTTON_KNOWN_FAILURES: ReadonlyArray<KnownFailure> = [
-  // ---- Button and IconButton go natively disabled while busy --------------
-  // One defect, one record per component.
-  // They are written out rather than generated, because a record has to name
-  // exactly one thing that is broken — a loop would make it easy to widen this
-  // later without anyone noticing.
-  {
-    expectation: 'button.focus.reachable-and-escapable',
-    binding: 'Button',
-    state: 'button-loading',
-    evidenceLayer: 'real-browser',
-    failureEquals:
-      '10 presses of Tab from the start of the document never reached the button, so a keyboard user cannot get to this action',
-    standardsReference:
-      'WCAG 2.2 2.1.1 Keyboard and 2.1.2 No Keyboard Trap (Level A)',
-    userImpact:
-      'A keyboard user who activates Save and waits is dropped to the top of the document the moment the action starts, and the button leaves the tab sequence entirely — so they cannot get back to it, to see that it is busy or to interrupt it. The next Tab restarts from the beginning of the page.',
-    reason:
-      'Button sets the native disabled attribute while a clickAction is pending. A natively disabled element is neither focusable nor a tab stop. Separate implementation work will turn this record into an unexpected pass.',
-  },
-  {
-    expectation: 'button.focus.reachable-and-escapable',
-    binding: 'IconButton',
-    state: 'icon-button-loading',
-    evidenceLayer: 'real-browser',
-    failureEquals:
-      '10 presses of Tab from the start of the document never reached the button, so a keyboard user cannot get to this action',
-    standardsReference:
-      'WCAG 2.2 2.1.1 Keyboard and 2.1.2 No Keyboard Trap (Level A)',
-    userImpact:
-      'The same drop from an icon button, where it is worse: an icon button is usually one of several in a row, so the user loses their place among them.',
-    reason:
-      'IconButton is a thin wrapper over Button and inherits the behaviour exactly.',
-  },
-
-  {
-    expectation: 'button.unavailable.inert',
-    binding: 'Button',
-    state: 'button-loading',
-    evidenceLayer: 'real-browser',
-    failureEquals:
-      'this state is declared focusable so its reason stays reachable, but it cannot take focus — so a keyboard user can neither read why it is unavailable nor reach it to confirm it refuses to act',
-    standardsReference:
-      'Current Astryx family:buttons FR3 and WAI-ARIA APG Button unavailable-state requirement; supports WCAG 2.2 4.1.2 Name, Role, Value (Level A)',
-    userImpact:
-      'The third face of the same defect: because the busy button cannot take focus, there is no way to confirm from the keyboard that it declines a second press — the user can neither reach it nor see why it is unavailable.',
-    reason:
-      'Same native disabled attribute. Recorded separately because a record names exactly one outcome, and a fix that restored focus without keeping the button inert would satisfy one of these and not the other.',
-  },
-  {
-    expectation: 'button.unavailable.inert',
-    binding: 'IconButton',
-    state: 'icon-button-loading',
-    evidenceLayer: 'real-browser',
-    failureEquals:
-      'this state is declared focusable so its reason stays reachable, but it cannot take focus — so a keyboard user can neither read why it is unavailable nor reach it to confirm it refuses to act',
-    standardsReference:
-      'Current Astryx family:buttons FR3 and WAI-ARIA APG Button unavailable-state requirement; supports WCAG 2.2 4.1.2 Name, Role, Value (Level A)',
-    userImpact: 'The same, from an icon button.',
-    reason: 'Inherited from Button, as above.',
-  },
-];
+export const BUTTON_KNOWN_FAILURES: ReadonlyArray<KnownFailure> = [];

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

@@ -177,16 +177,9 @@ export const BUTTON_BINDING_STATES = [
     binding: 'Button',
     summary:
       'a button waiting on the action it started: the action is unavailable, and it is meant to stay focusable so the user can see that and interrupt it',
-    // `focusable: true` is the declaration, and the component does not deliver
-    // it — see the known-failure records. Declaring what the component does
-    // instead would make the expectations that catch it not-applicable, which
-    // is how a contract quietly stops noticing a defect.
     facts: facts({operable: false, unavailable: true}),
     visibleLabel: null,
     storyId: 'a11y-button-pattern--button-loading',
-    declaredNotDelivered: [
-      {fact: 'focusable', owned: 'button.focus.reachable-and-escapable'},
-    ],
   },
 
   // ---- IconButton ---------------------------------------------------------
@@ -214,9 +207,6 @@ export const BUTTON_BINDING_STATES = [
     facts: facts({operable: false, unavailable: true}),
     visibleLabel: null,
     storyId: 'a11y-button-pattern--icon-button-loading',
-    declaredNotDelivered: [
-      {fact: 'focusable', owned: 'button.focus.reachable-and-escapable'},
-    ],
   },
 
   // ---- ClickableCard ------------------------------------------------------

package/src/CheckboxInput/CheckboxInput.test.tsx

@@ -209,6 +209,40 @@ describe('CheckboxInput', () => {
     );
   });
 
+  it('preserves a caller-provided id on the input and its label', () => {
+    render(
+      <CheckboxInput
+        id="accept-terms"
+        label="Accept terms"
+        value={false}
+        onChange={() => {}}
+      />,
+    );
+
+    const checkbox = screen.getByRole('checkbox');
+    expect(checkbox).toHaveAttribute('id', 'accept-terms');
+    expect(screen.getByText('Accept terms').closest('label')).toHaveAttribute(
+      'for',
+      'accept-terms',
+    );
+    expect(screen.getByLabelText('Accept terms')).toBe(checkbox);
+  });
+
+  it('generates an id the label resolves when the caller passes an empty id', () => {
+    render(
+      <CheckboxInput
+        id=""
+        label="Accept terms"
+        value={false}
+        onChange={() => {}}
+      />,
+    );
+
+    const checkbox = screen.getByRole('checkbox');
+    expect(checkbox.id).not.toBe('');
+    expect(screen.getByLabelText('Accept terms')).toBe(checkbox);
+  });
+
   it('forwards arbitrary data-* attributes to the input', () => {
     render(
       <CheckboxInput

package/src/CheckboxInput/CheckboxInput.tsx

@@ -311,6 +311,7 @@ const dynamicWidthStyles = stylex.create({
  * ```
  */
 export function CheckboxInput({
+  id: idProp,
   label,
   isLabelHidden = false,
   description,
@@ -340,7 +341,8 @@ export function CheckboxInput({
   // The row is the pressable: the overlay's pressed arm reads the row's
   // scope marker, the way the indicator's hover tint does.
   const pressable = usePressFeedback();
-  const id = useId();
+  const generatedId = useId();
+  const id = idProp || generatedId;
   const descriptionID = useId();
   const statusMessageID = useId();
   // Announce the effective required state (form default included) while the