fix(core): keep disabled SelectableCard focusable with aria-disabled

Author: Geervan

.changeset/selectable-card-focusable-disabled.md

@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] SelectableCard: keep disabled cards in sequential focus navigation with aria-disabled, form detachment, and gated interaction handlers.
+
+@Geervan

apps/storybook/stories/SelectableCard.stories.tsx

@@ -234,7 +234,7 @@ export const Disabled: Story = {
     docs: {
       description: {
         story:
-          '`isDisabled` suppresses toggle, hover, focus. Accent border remains visible on disabled+selected cards.',
+          '`isDisabled` suppresses toggle and hover; the control remains focusable and exposes aria-disabled. Accent border remains visible on disabled+selected cards.',
       },
     },
   },

packages/core/src/CheckboxInput/__tests__/Checkbox.a11y.chromium.spec.ts

@@ -321,31 +321,6 @@ test('CheckboxInput keeps supporting text out of its accessible name', async ({
   expect(computed.description).toBe('Help improve the product');
 });
 
-test('the disabled SelectableCard records only its documented focusability mismatch', async ({
-  page,
-}) => {
-  const state = CHECKBOX_BINDING_STATES.find(
-    candidate => candidate.id === 'card-disabled',
-  );
-  if (state == null) {
-    throw new Error('missing card-disabled binding state');
-  }
-  const cdp = await page.context().newCDPSession(page);
-  const result = await runState(page, cdp, state);
-  expect(
-    result.results.find(
-      candidate =>
-        candidate.expectation ===
-        'checkbox.focus.declared-inoperable-reachable',
-    )?.status,
-  ).toBe('known-failure');
-  expect(
-    result.results.find(
-      candidate => candidate.expectation === 'checkbox.state.inoperable',
-    )?.status,
-  ).toBe('pass');
-});
-
 for (const state of CHECKBOX_BINDING_STATES) {
   test(`${state.binding} [${state.id}] — ${state.summary}`, async ({page}) => {
     test.setTimeout(2 * 60 * 1000);

packages/core/src/CheckboxInput/__tests__/Checkbox.a11y.known-failures.ts

@@ -90,18 +90,4 @@ export const CHECKBOX_KNOWN_FAILURES: ReadonlyArray<KnownFailure> = [
     reason:
       'DropdownMenuCheckboxItem makes onChange optional. Without it, the controlled value cannot persist a user change, but the role-bearing item remains exposed as available.',
   },
-  {
-    expectation: 'checkbox.focus.declared-inoperable-reachable',
-    binding: 'SelectableCard',
-    state: 'card-disabled',
-    evidenceLayer: 'real-browser',
-    failureEquals:
-      '10 presses of Tab from the start of the document never reached the checkbox, so a keyboard user cannot get to this setting',
-    standardsReference:
-      'Astryx spec:AST-021 FR7 (preserve existing documented behavior); SelectableCard isDisabled public prop contract',
-    userImpact:
-      'A keyboard user cannot tab to the disabled card to discover that the option exists and is unavailable, despite the public prop contract promising continued focusability.',
-    reason:
-      'SelectableCard documents a focusable aria-disabled state, but the implementation applies native disabled to its checkbox and removes it from the tab sequence. This advisory migration check records that public-contract mismatch without presenting disabled focusability as a WCAG requirement.',
-  },
 ];

packages/core/src/CheckboxInput/__tests__/Checkbox.a11y.states.ts

@@ -404,11 +404,5 @@ export const CHECKBOX_BINDING_STATES = [
     visibleLabelSelector: '[data-a11y-visible-label]',
     pointerTargetSelector: '[data-a11y-pointer-target]',
     storyId: 'a11y-checkbox-pattern--card-disabled',
-    declaredNotDelivered: [
-      {
-        fact: 'focusable',
-        owned: 'checkbox.focus.declared-inoperable-reachable',
-      },
-    ],
   },
 ] as const satisfies ReadonlyArray<CheckboxBindingState>;

packages/core/src/SelectableCard/SelectableCard.test.tsx

@@ -111,6 +111,22 @@ describe('SelectableCard', () => {
     expect(handleChange).not.toHaveBeenCalled();
   });
 
+  it('does not toggle on Space when disabled', () => {
+    const handleChange = vi.fn();
+    render(
+      <SelectableCard
+        label="Disabled"
+        isSelected={false}
+        onChange={handleChange}
+        isDisabled>
+        Content
+      </SelectableCard>,
+    );
+    const checkbox = screen.getByRole('checkbox', {name: 'Disabled'});
+    fireEvent.keyDown(checkbox, {key: ' '});
+    expect(handleChange).not.toHaveBeenCalled();
+  });
+
   it('toggles exactly once on Space (native), not doubled by the Enter handler', () => {
     const handleChange = vi.fn();
     render(

packages/core/src/SelectableCard/SelectableCard.tsx

@@ -332,7 +332,13 @@ export function SelectableCard({
   // handling, so we deliberately do not toggle on Space here (would double).
   const handleKeyDown = useCallback(
     (event: KeyboardEvent<HTMLInputElement>) => {
-      if (!isDisabled && event.key === 'Enter') {
+      if (isDisabled) {
+        if (event.key === ' ' || event.key === 'Enter') {
+          event.preventDefault();
+        }
+        return;
+      }
+      if (event.key === 'Enter') {
         event.preventDefault();
         onChange(!isSelected);
       }
@@ -397,8 +403,13 @@ export function SelectableCard({
         type="checkbox"
         checked={isSelected}
         aria-label={label}
-        disabled={isDisabled}
-        onChange={() => onChange(!isSelected)}
+        aria-disabled={isDisabled ? 'true' : undefined}
+        onChange={() => {
+          if (isDisabled) {
+            return;
+          }
+          onChange(!isSelected);
+        }}
         onKeyDown={handleKeyDown}
         {...stylex.props(styles.srOnly)}
       />