An open source design system that's fully customizable and agent ready
TypeScript
fix(Stepper): a disabled step stays focusable and aria-disabled in a clickable Stepper (component:Step FR2) (#8867)
Cindy Zhang962dffeebaa1
diff --git a/.changeset/stepper-disabled-step-focusable.md b/.changeset/stepper-disabled-step-focusable.mdnew file mode 100644index 0000000000..29548b6b22--- /dev/null+++ b/.changeset/stepper-disabled-step-focusable.md@@ -0,0 +1,7 @@+---+'@astryxdesign/core': patch+---++[fix] In a clickable `Stepper`, a disabled `Step` now keeps its button: it stays in the tab order, is announced as unavailable (`aria-disabled`), and keeps focus if it becomes disabled while focused, but still does not activate. Its description (the reason it is unavailable) describes the button (`spec:AST-085` FR1, FR4, FR5). Before, it rendered as plain text, so keyboard and screen-reader users could not find it or tell it was unavailable.++@cixzhangdiff --git a/packages/core/src/Stepper/Step.spec.md b/packages/core/src/Stepper/Step.spec.mdindex 02ca8e1526..12fef86337 100644--- a/packages/core/src/Stepper/Step.spec.md+++ b/packages/core/src/Stepper/Step.spec.md@@ -28,15 +28,15 @@ system_specs: [spec:AST-085]## Contract at a glance-| Area | Contract |-| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |-| Public contract | `Step` with `step`, `label`, `description`, `children`, `status`, `indicator` (`auto`, `number`, `none`, or a node; default `auto`), `isDisabled`, `isOptional`, `endContent`, and `density`. |-| Behavior | One list item of a Stepper. Its progress (completed, in progress, not started) comes from its `step` index against the Stepper's active step; it is a button that asks to go to that step when the Stepper has `onStepClick`, it is enabled, and the Stepper is not compact. |-| End-user impact | Users see each step's progress (number, ring, or check) and its status cue where one applies; screen-reader users hear the current step, a status word, and a "Go to step N" name on clickable steps; keyboard users Tab between enabled clickable steps. |-| Builder impact | None. |-| Compatibility/readiness | Records shipped behavior; no public change. Three implementation gaps (see Current-state impact). |-| Review checks | Reject status conveyed only by color under `indicator="auto"`, an indicator exposed to assistive technology, a disabled step that activates, or `aria-current` on anything but the in-progress step. |-| Governing rules | `component:Stepper` (targets, connector, label paint, compact layout); `architecture:interaction-modality`. |+| Area | Contract |+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |+| Public contract | `Step` with `step`, `label`, `description`, `children`, `status`, `indicator` (`auto`, `number`, `none`, or a node; default `auto`), `isDisabled`, `isOptional`, `endContent`, and `density`. |+| Behavior | One list item of a Stepper. Its progress (completed, in progress, not started) comes from its `step` index against the Stepper's active step; it is a button that asks to go to that step when the Stepper has `onStepClick` and is not compact; a disabled step keeps its button, `aria-disabled`, and never activates. |+| End-user impact | Users see each step's progress (number, ring, or check) and its status cue where one applies; screen-reader users hear the current step, a status word, a "Go to step N" name and the step's description on clickable steps; keyboard users Tab between clickable steps, disabled ones included. |+| Builder impact | None. |+| Compatibility/readiness | Records shipped behavior; no public change. Two implementation gaps (see Current-state impact). |+| Review checks | Reject status conveyed only by color under `indicator="auto"`, an indicator exposed to assistive technology, a disabled step that activates, or `aria-current` on anything but the in-progress step. |+| Governing rules | `component:Stepper` (targets, connector, label paint, compact layout); `architecture:interaction-modality`. |This table is a review projection; the body below is authoritative.@@ -56,12 +56,6 @@ Consumer migration instructions belong in consumer docs and release notes.## Current-state impact-- **A disabled step leaves the tab order.** In a clickable Stepper outside- compact mode a disabled Step renders no button, so keyboard users cannot reach- it or learn that it is disabled, and a focused step that becomes disabled- loses its button, dropping focus to the page. `spec:AST-085` FR1, FR4, and FR5- have a disabled control stay focusable, keep focus, and expose- `aria-disabled="true"`.- **Other indicator modes show status by color alone, or not at all.** With`indicator="number"`, a reached step shows status only through badge colorand a not-started step shows none. A custom node shows status only through@@ -70,9 +64,9 @@ Consumer migration instructions belong in consumer docs and release notes.its `status`, so in both cases status shows only in the visually hidden word. WCAG 1.4.1 requires informationnot to be conveyed by color alone.- **A clickable step's name hides its other text.** The button's name is the- step number, label, and status word, and nothing describes it, so the- description, the "Optional" cue, and `endContent` never reach assistive- technology on a clickable step. WCAG 1.3.1 requires information shown to be+ step number, label, and status word, and only the description describes it,+ so the "Optional" cue and `endContent` never reach assistive technology on a+ clickable step. WCAG 1.3.1 requires information shown to beavailable programmatically.## Ownership boundary@@ -105,17 +99,17 @@ Consumer migration instructions belong in consumer docs and release notes.## Behavioral and layout contract-| ID | Invariant | Basis |-| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------- |-| FR1 | A Step renders one `<li>`. Its progress is `in-progress` when `step` equals the Stepper's active step, `completed` when it is lower, and `not-started` when higher; only the in-progress step carries `aria-current="step"`. It registers its index and a live disabled check with the Stepper. | Current source and tests |-| FR2 | With `onStepClick` on the Stepper, an enabled Step outside compact mode wraps its indicator, label, and description in a `<button>` (the content slot stays outside it) named by `@astryx.step.goToStep` ("Go to step N: label") or `.goToStepWithStatus` when a status word applies; activation (click, Enter, Space) calls `onStepClick(step)`. Completed, in-progress, and upcoming steps are all clickable. Any Step without `onStepClick` renders no button. A disabled Step in a clickable Stepper outside compact mode MUST stay focusable with `aria-disabled="true"` and keep its tab stop (`spec:AST-085` FR1, FR5). Implementation gap: it renders no button, so it leaves the tab order, exposes no disabled state, and drops focus when it becomes disabled while focused (`spec:AST-085` FR4). | Current source and tests |-| FR3 | `indicator="auto"` shows the number while not started, the ring while in progress, and a check once completed; `number` always shows the number; `none` shows nothing; a non-string node renders as given; any other string falls back to the ring while not started or in progress and the check once completed, with no number, status glyph, or status color. Indicators are `aria-hidden`. | Current source and tests |-| FR4 | `status` never recolors the progress bar. Under `indicator="auto"` it recolors a non-current step with `success`, `warning`, or `error` and shows a distinct status glyph (replacing the number on not-started steps); the current step's ring and `accent` keep progress color. Under `number` it recolors reached badges only. | Current source and tests |-| FR5 | Each Step exposes a visually hidden status word: `error` or `warning` for those statuses, `completed` when completed or `success`, in every layout. | Current source and tests |-| FR6 | `isDisabled` dims the indicator with fixed paint and no theme state (the label's disabled paint and its `disabled` selector are `component:Stepper` FR10) and blocks activation (FR2's implementation gap). `isOptional` appends the translated `@astryx.step.optional` ("Optional") after the label. `endContent` sits at the end of the label row. | Current source and tests |-| FR7 | `density` sets the Step's padding: block padding in every layout, plus inline padding for spacious separated steps and both axes for vertical on-track steps; it falls back to the Stepper's density. | Current source |-| FR8 | `children` render below the label and description; in a compact horizontal Stepper they stay mounted, hidden with the expanded details, so local state survives. The label stays on one line and ellipsizes; its full text remains in the accessible name. | Current source, docs, and tests |-| FR9 | The step button paints the shared focus outline. | Current source |+| ID | Invariant | Basis |+| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |+| FR1 | A Step renders one `<li>`. Its progress is `in-progress` when `step` equals the Stepper's active step, `completed` when it is lower, and `not-started` when higher; only the in-progress step carries `aria-current="step"`. It registers its index and a live disabled check with the Stepper. | Current source and tests |+| FR2 | With `onStepClick` on the Stepper, an enabled Step outside compact mode wraps its indicator, label, and description in a `<button>` (the content slot stays outside it) named by `@astryx.step.goToStep` ("Go to step N: label") or `.goToStepWithStatus` when a status word applies; activation (click, Enter, Space) calls `onStepClick(step)`. Completed, in-progress, and upcoming steps are all clickable. Any Step without `onStepClick` renders no button. A disabled Step in a clickable Stepper outside compact mode keeps its button, focusable with `aria-disabled="true"` and the same name, keeps its tab stop and its focus when it becomes disabled while focused, and does not activate (`spec:AST-085` FR1, FR4). A clickable Step's description describes its button, so a disabled step's reason reaches assistive technology (`spec:AST-085` FR5). | Current source and tests |+| FR3 | `indicator="auto"` shows the number while not started, the ring while in progress, and a check once completed; `number` always shows the number; `none` shows nothing; a non-string node renders as given; any other string falls back to the ring while not started or in progress and the check once completed, with no number, status glyph, or status color. Indicators are `aria-hidden`. | Current source and tests |+| FR4 | `status` never recolors the progress bar. Under `indicator="auto"` it recolors a non-current step with `success`, `warning`, or `error` and shows a distinct status glyph (replacing the number on not-started steps); the current step's ring and `accent` keep progress color. Under `number` it recolors reached badges only. | Current source and tests |+| FR5 | Each Step exposes a visually hidden status word: `error` or `warning` for those statuses, `completed` when completed or `success`, in every layout. | Current source and tests |+| FR6 | `isDisabled` dims the indicator with fixed paint and no theme state (the label's disabled paint and its `disabled` selector are `component:Stepper` FR10) and blocks activation (FR2). `isOptional` appends the translated `@astryx.step.optional` ("Optional") after the label. `endContent` sits at the end of the label row. | Current source and tests |+| FR7 | `density` sets the Step's padding: block padding in every layout, plus inline padding for spacious separated steps and both axes for vertical on-track steps; it falls back to the Stepper's density. | Current source |+| FR8 | `children` render below the label and description; in a compact horizontal Stepper they stay mounted, hidden with the expanded details, so local state survives. The label stays on one line and ellipsizes; its full text remains in the accessible name. | Current source, docs, and tests |+| FR9 | The step button paints the shared focus outline. | Current source |### Allowed variation@@ -129,7 +123,7 @@ Consumer migration instructions belong in consumer docs and release notes.| Completed, clickable | Check indicator; "completed" text; named button. | Status color. || In progress | `aria-current="step"`; ring indicator. | — || Not started with error | Error glyph replaces the number; "error" text. | — |-| Disabled | Dimmed; no activation. Implementation gap: no button (FR2). | — |+| Disabled | Dimmed; focusable and `aria-disabled`; no activation (FR2). | — || Compact horizontal | No button; content mounted but hidden. | — |### Transformation and precedence order@@ -152,11 +146,11 @@ Consumer migration instructions belong in consumer docs and release notes.hidden word (Current-stateimpact).- **AR3 — Clickable name.** FR2's button name includes the step number, label,- and status word. Implementation gap: a clickable step's description, optional- cue, and `endContent` are not exposed (Current-state impact).-- **AR4 — Keyboard.** Clickable steps are reached with Tab in document order and- activate with Enter or Space; today disabled steps are skipped (FR2's- implementation gap).+ and status word, and the step's description describes it. Implementation gap:+ a clickable step's optional cue and `endContent` are not exposed+ (Current-state impact).+- **AR4 — Keyboard.** Clickable steps, disabled ones included, are reached with+ Tab in document order; enabled ones activate with Enter or Space.## Design relationships@@ -175,13 +169,13 @@ Consumer migration instructions belong in consumer docs and release notes.## Verification map-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |-| ------------ | ------------------------------------------------------------------- | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |-| FR1 | `Stepper.test.tsx` list and aria-current tests | Each progress | Wrong current step fails. | `audit:Step/accessibility` |-| FR2, AR3–AR4 | `Stepper.test.tsx` onStepClick, keyboard, and accessible-name tests | Completed, active, upcoming, disabled | A missing button or wrong name fails; the disabled-step and Tab-skip assertions pin FR2's implementation gap (pending conformance). | `audit:Step/behavior` |-| FR3, FR4 | `Stepper.test.tsx` step-number, indicator, and status glyph tests | Each indicator mode and status | Wrong glyph or recolored bar fails. | `audit:Step/behavior` |-| FR8 | `Stepper.test.tsx` compact content-mount tests | Both indicator positions | Step content that loses its state while hidden in a compact Stepper fails. | `audit:Step/behavior` |-| FR5, AR2 | `Stepper.test.tsx` hidden status text tests | Separated and on-track | Missing status text fails. | `audit:Step/accessibility` |+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |+| ------------ | ------------------------------------------------------------------- | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |+| FR1 | `Stepper.test.tsx` list and aria-current tests | Each progress | Wrong current step fails. | `audit:Step/accessibility` |+| FR2, AR3–AR4 | `Stepper.test.tsx` onStepClick, keyboard, and accessible-name tests | Completed, active, upcoming, disabled | A missing button or wrong name fails, and so does a disabled step that leaves the tab order, loses focus when it becomes disabled, lacks `aria-disabled`, or activates. | `audit:Step/behavior` |+| FR3, FR4 | `Stepper.test.tsx` step-number, indicator, and status glyph tests | Each indicator mode and status | Wrong glyph or recolored bar fails. | `audit:Step/behavior` |+| FR8 | `Stepper.test.tsx` compact content-mount tests | Both indicator positions | Step content that loses its state while hidden in a compact Stepper fails. | `audit:Step/behavior` |+| FR5, AR2 | `Stepper.test.tsx` hidden status text tests | Separated and on-track | Missing status text fails. | `audit:Step/accessibility` |Read from source, with no focused test yet:diff --git a/packages/core/src/Stepper/Step.tsx b/packages/core/src/Stepper/Step.tsxindex 30a239d56c..304cc10c7d 100644--- a/packages/core/src/Stepper/Step.tsx+++ b/packages/core/src/Stepper/Step.tsx@@ -38,7 +38,7 @@* - /packages/cli/assets/templates/blocks/components/Step/ (showcase blocks)*/-import {useLayoutEffect, type ReactNode} from 'react';+import {useId, useLayoutEffect, type ReactNode} from 'react';import {createPortal} from 'react-dom';import * as stylex from '@stylexjs/stylex';@@ -1072,7 +1072,12 @@ export function Step({// A compact horizontal stepper moves navigation to the named controls in its// summary row. Its track — including the on-track indicators — stays purely// presentational so it does not expose a second, denser set of click targets.- const isClickable = !isDisabled && onStepClick != null && !isCompact;+ const hasButton = onStepClick != null && !isCompact;+ // A disabled step keeps its button, focusable and aria-disabled, so it+ // keeps its tab stop, is announced as unavailable, and keeps focus when it+ // becomes disabled while focused (`spec:AST-085` FR1, FR4, FR5); only+ // activation is withheld.+ const isClickable = hasButton && !isDisabled;const handleClick = () => {if (isClickable && onStepClick) {@@ -1349,8 +1354,13 @@ export function Step({</div>);+ // A clickable step's name is its number, label and status word; the+ // description describes it, so a disabled step's reason reaches assistive+ // technology too (spec:AST-085 FR5).+ const descriptionID = useId();const descriptionNode = isRenderable(description) ? (<div+ id={descriptionID}{...stylex.props(hasIndicator? styles.descriptionRowWithIndicator@@ -1507,6 +1517,7 @@ export function Step({const otDescriptionNode = isRenderable(description) ? (<span+ id={descriptionID}{...mergeProps(descriptionThemeProps,stylex.props(styles.description),@@ -1610,11 +1621,15 @@ export function Step({aria-current={isActive ? 'step' : undefined}data-testid={dataTestId}{...rest}>- {isClickable ? (+ {hasButton ? (<buttontype="button"onClick={handleClick}aria-label={stepAriaLabel}+ aria-describedby={+ isRenderable(description) ? descriptionID : undefined+ }+ aria-disabled={isDisabled || undefined}{...pressable}{...stylex.props(styles.otInteractive,@@ -1702,11 +1717,15 @@ export function Step({aria-current={isActive ? 'step' : undefined}data-testid={dataTestId}{...rest}>- {isClickable ? (+ {hasButton ? (<buttontype="button"onClick={handleClick}aria-label={stepAriaLabel}+ aria-describedby={+ isRenderable(description) ? descriptionID : undefined+ }+ aria-disabled={isDisabled || undefined}{...pressable}{...stylex.props(styles.otInteractive,@@ -1762,11 +1781,15 @@ export function Step({/>{/* Body: button wraps only label area, children render outside */}<div {...stylex.props(styles.verticalBody)}>- {isClickable ? (+ {hasButton ? (<buttontype="button"onClick={handleClick}aria-label={stepAriaLabel}+ aria-describedby={+ isRenderable(description) ? descriptionID : undefined+ }+ aria-disabled={isDisabled || undefined}{...pressable}{...stylex.props(styles.buttonReset,@@ -1830,11 +1853,15 @@ export function Step({under the track instead. */}{isCompact ? (compactNameNode- ) : isClickable ? (+ ) : hasButton ? (<buttontype="button"onClick={handleClick}aria-label={stepAriaLabel}+ aria-describedby={+ isRenderable(description) ? descriptionID : undefined+ }+ aria-disabled={isDisabled || undefined}{...stylex.props(styles.buttonReset,interactionOverlayStyles.backgroundColor,diff --git a/packages/core/src/Stepper/Stepper.doc.mjs b/packages/core/src/Stepper/Stepper.doc.mjsindex d83147dac5..137ed603b0 100644--- a/packages/core/src/Stepper/Stepper.doc.mjs+++ b/packages/core/src/Stepper/Stepper.doc.mjs@@ -172,7 +172,7 @@ export const docs = {name: 'onStepClick',type: '(index: number) => void',description:- 'Called when a step is clicked or a compact summary control is used. Enables non-linear navigation. All non-disabled steps become clickable until a horizontal Stepper collapses, when navigation moves to summary controls that skip disabled steps.',+ 'Called when a step is clicked or a compact summary control is used. Enables non-linear navigation. Every step becomes a button until a horizontal Stepper collapses: enabled steps activate, and disabled steps stay focusable and are announced as unavailable but do not activate. When collapsed, navigation moves to summary controls that skip disabled steps.',},{name: 'label',diff --git a/packages/core/src/Stepper/Stepper.test.tsx b/packages/core/src/Stepper/Stepper.test.tsxindex b93291b9c3..9498d1918f 100644--- a/packages/core/src/Stepper/Stepper.test.tsx+++ b/packages/core/src/Stepper/Stepper.test.tsx@@ -185,17 +185,75 @@ describe('Stepper', () => {expect(handleClick).toHaveBeenCalledWith(2);});- it('does not render buttons for disabled steps', () => {+ it('keeps a disabled step focusable and aria-disabled, and never activates it (spec:AST-085 FR1, FR2, FR5)', async () => {+ const user = userEvent.setup();+ const handleClick = vi.fn();render(- <Stepper activeStep={2} onStepClick={() => {}}>+ <Stepper activeStep={2} onStepClick={handleClick}><Step step={0} label="Step 1" isDisabled /><Step step={1} label="Step 2" /><Step step={2} label="Step 3" /></Stepper>,);- expect(- screen.queryByRole('button', {name: /Go to step 1: Step 1/}),- ).not.toBeInTheDocument();+ const disabled = screen.getByRole('button', {name: /Go to step 1: Step 1/});+ expect(disabled).toHaveAttribute('aria-disabled', 'true');+ expect(disabled).not.toHaveAttribute('disabled');+ await user.click(disabled);+ disabled.focus();+ await user.keyboard('{Enter}');+ await user.keyboard(' ');+ expect(handleClick).not.toHaveBeenCalled();+ });++ it.each([+ ['separated', {}],+ ['on-track horizontal', {indicatorPosition: 'on-track'}],+ [+ 'on-track vertical',+ {indicatorPosition: 'on-track', orientation: 'vertical'},+ ],+ ] as const)(+ "describes a disabled step with its reason, the step's description, %s (spec:AST-085 FR5)",+ (_layout, layout) => {+ render(+ <Stepper activeStep={1} onStepClick={() => {}} {...layout}>+ <Step step={0} label="Setup" />+ <Step+ step={1}+ label="Permissions"+ description="Requires admin role"+ isDisabled+ />+ </Stepper>,+ );+ const step = screen.getByRole('button', {+ name: /Go to step 2: Permissions/,+ });+ expect(step).toHaveAccessibleDescription('Requires admin role');+ expect(+ screen.getByRole('button', {name: /Go to step 1: Setup/}),+ ).not.toHaveAttribute('aria-describedby');+ },+ );++ it('keeps focus on a step that becomes disabled while focused (spec:AST-085 FR4)', () => {+ const {rerender} = render(+ <Stepper activeStep={2} onStepClick={() => {}}>+ <Step step={0} label="Step 1" />+ <Step step={1} label="Step 2" />+ </Stepper>,+ );+ const step = screen.getByRole('button', {name: /Go to step 1: Step 1/});+ step.focus();+ rerender(+ <Stepper activeStep={2} onStepClick={() => {}}>+ <Step step={0} label="Step 1" isDisabled />+ <Step step={1} label="Step 2" />+ </Stepper>,+ );+ const after = screen.getByRole('button', {name: /Go to step 1: Step 1/});+ expect(after).toHaveFocus();+ expect(after).toHaveAttribute('aria-disabled', 'true');});it('does not render buttons when onStepClick is not provided', () => {@@ -610,7 +668,7 @@ describe('Stepper', () => {expect(handleClick).toHaveBeenCalledWith(0);});- it('tabs through steps in document order, skipping disabled ones', async () => {+ it('tabs through steps in document order, disabled ones included', async () => {const user = userEvent.setup();render(<Stepper activeStep={3} onStepClick={() => {}}>@@ -623,7 +681,11 @@ describe('Stepper', () => {expect(screen.getByRole('button', {name: 'Go to step 1: One, completed'}),).toHaveFocus();- // The disabled step renders no button, so Tab lands on step 3 next.+ // The disabled step keeps its tab stop (spec:AST-085 FR1).+ await user.tab();+ expect(+ screen.getByRole('button', {name: 'Go to step 2: Two, completed'}),+ ).toHaveFocus();await user.tab();expect(screen.getByRole('button', {name: 'Go to step 3: Three, completed'}),