An open source design system that's fully customizable and agent ready
TypeScript
// Copyright (c) Meta Platforms, Inc. and affiliates.
import {StrictMode, createRef, useLayoutEffect} from 'react';
import {describe, it, expect, vi} from 'vitest';
import {act, render, screen, within} from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import {Stepper} from './Stepper';
import {Step} from './Step';
import {useStepperContext} from './StepperContext';
import {useLayer} from '../Layer/useLayer';
import {defineTheme} from '../theme/defineTheme';
import {generateThemeCSS} from '../theme/generateThemeRules';
import {getForcedColorsRules} from '../__tests__/forcedColors';
describe('Stepper', () => {
it('renders an ordered list of steps (not a nav landmark)', () => {
render(
<Stepper activeStep={0}>
<Step step={0} label="Step 1" />
<Step step={1} label="Step 2" />
<Step step={2} label="Step 3" />
</Stepper>,
);
// A stepper is a sequence/progress list, not a navigation landmark.
expect(screen.queryByRole('navigation')).not.toBeInTheDocument();
const list = screen.getByRole('list', {name: 'Progress'});
expect(list.tagName).toBe('OL');
expect(screen.getByText('Step 1')).toBeInTheDocument();
expect(screen.getByText('Step 2')).toBeInTheDocument();
expect(screen.getByText('Step 3')).toBeInTheDocument();
});
it('renders step numbers', () => {
render(
<Stepper activeStep={0}>
<Step step={0} label="First" indicator="number" />
<Step step={1} label="Second" indicator="number" />
</Stepper>,
);
expect(screen.getByText('1')).toBeInTheDocument();
expect(screen.getByText('2')).toBeInTheDocument();
});
it('marks the active step with aria-current', () => {
render(
<Stepper activeStep={1}>
<Step step={0} label="Step 1" data-testid="step-0" />
<Step step={1} label="Step 2" data-testid="step-1" />
<Step step={2} label="Step 3" data-testid="step-2" />
</Stepper>,
);
expect(screen.getByTestId('step-0')).not.toHaveAttribute('aria-current');
expect(screen.getByTestId('step-1')).toHaveAttribute(
'aria-current',
'step',
);
expect(screen.getByTestId('step-2')).not.toHaveAttribute('aria-current');
});
it.each([
['horizontal', 'separated'],
['vertical', 'separated'],
['horizontal', 'on-track'],
['vertical', 'on-track'],
] as const)(
'keeps aria-current on the in-progress step over a caller’s (%s, %s)',
(orientation, indicatorPosition) => {
render(
<Stepper
activeStep={1}
orientation={orientation}
indicatorPosition={indicatorPosition}>
<Step
step={0}
label="Step 1"
data-testid="step-0"
aria-current="page"
/>
<Step
step={1}
label="Step 2"
data-testid="step-1"
aria-current="false"
/>
<Step
step={2}
label="Step 3"
data-testid="step-2"
aria-current="true"
/>
</Stepper>,
);
expect(screen.getByTestId('step-0')).not.toHaveAttribute('aria-current');
expect(screen.getByTestId('step-1')).toHaveAttribute(
'aria-current',
'step',
);
expect(screen.getByTestId('step-2')).not.toHaveAttribute('aria-current');
},
);
it('renders descriptions when provided', () => {
render(
<Stepper activeStep={0}>
<Step step={0} label="Account" description="Create your account" />
<Step step={1} label="Profile" />
</Stepper>,
);
expect(screen.getByText('Create your account')).toBeInTheDocument();
});
it('supports custom accessible label', () => {
render(
<Stepper activeStep={0} label="Checkout progress">
<Step step={0} label="Cart" />
<Step step={1} label="Payment" />
</Stepper>,
);
expect(
screen.getByRole('list', {name: 'Checkout progress'}),
).toBeInTheDocument();
});
it.each(['horizontal', 'vertical'] as const)(
'exposes only the supported public context keys at runtime when %s',
orientation => {
let contextKeys: string[] = [];
function ContextProbe() {
contextKeys = Object.keys(useStepperContext()).sort();
return null;
}
render(
<Stepper activeStep={0} orientation={orientation}>
<ContextProbe />
<Step step={0} label="Step 1" />
</Stepper>,
);
expect(contextKeys).toEqual(
[
'activeStep',
'previousActiveStep',
'orientation',
'isNonLinear',
'onStepClick',
'density',
'indicatorPosition',
'registerStep',
].sort(),
);
},
);
it('supports vertical orientation', () => {
render(
<Stepper activeStep={0} orientation="vertical">
<Step step={0} label="Step 1" />
<Step step={1} label="Step 2" />
</Stepper>,
);
const list = screen.getByRole('list');
expect(list).toHaveAttribute('data-orientation', 'vertical');
});
it('calls onStepClick when a completed step is clicked', async () => {
const user = userEvent.setup();
const handleClick = vi.fn();
render(
<Stepper activeStep={2} onStepClick={handleClick}>
<Step step={0} label="Step 1" />
<Step step={1} label="Step 2" />
<Step step={2} label="Step 3" />
</Stepper>,
);
await user.click(
screen.getByRole('button', {name: 'Go to step 1: Step 1, completed'}),
);
expect(handleClick).toHaveBeenCalledWith(0);
});
it('calls onStepClick when the active step is clicked', async () => {
const user = userEvent.setup();
const handleClick = vi.fn();
render(
<Stepper activeStep={1} onStepClick={handleClick}>
<Step step={0} label="Step 1" />
<Step step={1} label="Step 2" />
<Step step={2} label="Step 3" />
</Stepper>,
);
await user.click(
screen.getByRole('button', {name: 'Go to step 2: Step 2'}),
);
expect(handleClick).toHaveBeenCalledWith(1);
});
it('renders buttons for upcoming steps in non-linear mode', () => {
render(
<Stepper activeStep={0} onStepClick={() => {}}>
<Step step={0} label="Step 1" />
<Step step={1} label="Step 2" />
</Stepper>,
);
expect(
screen.getByRole('button', {name: 'Go to step 1: Step 1'}),
).toBeInTheDocument();
expect(
screen.getByRole('button', {name: 'Go to step 2: Step 2'}),
).toBeInTheDocument();
});
it('calls onStepClick when an upcoming step is clicked', async () => {
const user = userEvent.setup();
const handleClick = vi.fn();
render(
<Stepper activeStep={0} onStepClick={handleClick}>
<Step step={0} label="Step 1" />
<Step step={1} label="Step 2" />
<Step step={2} label="Step 3" />
</Stepper>,
);
await user.click(
screen.getByRole('button', {name: 'Go to step 3: Step 3'}),
);
expect(handleClick).toHaveBeenCalledWith(2);
});
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={handleClick}>
<Step step={0} label="Step 1" isDisabled />
<Step step={1} label="Step 2" />
<Step step={2} label="Step 3" />
</Stepper>,
);
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', () => {
render(
<Stepper activeStep={2}>
<Step step={0} label="Step 1" />
<Step step={1} label="Step 2" />
<Step step={2} label="Step 3" />
</Stepper>,
);
expect(screen.queryAllByRole('button')).toHaveLength(0);
});
it('applies a semantic color status (color only) via data attribute', () => {
render(
<Stepper activeStep={1}>
<Step step={0} label="Step 1" data-testid="step-0" />
<Step step={1} label="Step 2" status="error" data-testid="step-1" />
</Stepper>,
);
expect(screen.getByTestId('step-1')).toHaveAttribute(
'data-status',
'error',
);
// status is color-only — it must not change progress semantics.
expect(screen.getByTestId('step-1')).toHaveAttribute(
'aria-current',
'step',
);
});
it('reflects each global semantic status on the data attribute', () => {
render(
<Stepper activeStep={0}>
<Step step={0} label="A" status="accent" data-testid="s-accent" />
<Step step={1} label="B" status="success" data-testid="s-success" />
<Step step={2} label="C" status="warning" data-testid="s-warning" />
<Step step={3} label="D" status="error" data-testid="s-error" />
</Stepper>,
);
expect(screen.getByTestId('s-accent')).toHaveAttribute(
'data-status',
'accent',
);
expect(screen.getByTestId('s-success')).toHaveAttribute(
'data-status',
'success',
);
expect(screen.getByTestId('s-warning')).toHaveAttribute(
'data-status',
'warning',
);
expect(screen.getByTestId('s-error')).toHaveAttribute(
'data-status',
'error',
);
});
it('keeps the progress bar progress-colored regardless of status, recoloring only the indicator', () => {
// Baseline: a completed step with no status.
const baseline = render(
<Stepper activeStep={1}>
<Step step={0} label="A" data-testid="base" />
</Stepper>,
);
const baseStep = baseline.getByTestId('base');
const baseBar = baseStep.querySelector('.astryx-step-bar') as HTMLElement;
const baseIndicator = baseStep.querySelector('svg')
?.parentElement as HTMLElement;
// Same completed step, now with a semantic status.
const themed = render(
<Stepper activeStep={1}>
<Step step={0} label="A" status="error" data-testid="themed" />
</Stepper>,
);
const themedStep = themed.getByTestId('themed');
const themedBar = themedStep.querySelector(
'.astryx-step-bar',
) as HTMLElement;
const themedIndicator = themedStep.querySelector('svg')
?.parentElement as HTMLElement;
// Bar coloring must be identical — status must NOT recolor the bar
// (always --color-accent when filled / --color-border when incomplete).
expect(themedBar.className).toBe(baseBar.className);
// The indicator, however, must pick up the status color.
expect(themedIndicator.className).not.toBe(baseIndicator.className);
});
it('keeps an incomplete step bar border-colored regardless of status', () => {
// Baseline: a not-started step with no status.
const baseline = render(
<Stepper activeStep={0}>
<Step step={0} label="A" data-testid="base-active" />
<Step step={1} label="B" data-testid="base" />
</Stepper>,
);
const baseBar = baseline
.getByTestId('base')
.querySelector('.astryx-step-bar') as HTMLElement;
// Same not-started step, now with a semantic status.
const themed = render(
<Stepper activeStep={0}>
<Step step={0} label="A" data-testid="themed-active" />
<Step step={1} label="B" status="warning" data-testid="themed" />
</Stepper>,
);
const themedBar = themed
.getByTestId('themed')
.querySelector('.astryx-step-bar') as HTMLElement;
// Incomplete bar stays border-colored — status must not recolor it.
expect(themedBar.className).toBe(baseBar.className);
});
it('does not set a status data attribute when status is unset', () => {
render(
<Stepper activeStep={0}>
<Step step={0} label="Step 1" data-testid="step-0" />
</Stepper>,
);
expect(screen.getByTestId('step-0')).not.toHaveAttribute('data-status');
});
it('handles zero active step correctly', () => {
render(
<Stepper activeStep={0}>
<Step step={0} label="Step 1" data-testid="step-0" />
<Step step={1} label="Step 2" data-testid="step-1" />
</Stepper>,
);
expect(screen.getByTestId('step-0')).toHaveAttribute(
'aria-current',
'step',
);
expect(screen.getByTestId('step-1')).not.toHaveAttribute('aria-current');
});
it('renders each step as a list item', () => {
render(
<Stepper activeStep={0}>
<Step step={0} label="Step 1" />
<Step step={1} label="Step 2" />
<Step step={2} label="Step 3" />
</Stepper>,
);
const items = screen.getAllByRole('listitem');
expect(items).toHaveLength(3);
expect(items[0].tagName).toBe('LI');
});
it('accepts a custom ReactNode as indicator', () => {
render(
<Stepper activeStep={0}>
<Step
step={0}
label="Step 1"
indicator={<span data-testid="custom-icon">★</span>}
/>
</Stepper>,
);
expect(screen.getByTestId('custom-icon')).toBeInTheDocument();
expect(screen.getByText('★')).toBeInTheDocument();
});
it('accepts a ReactNode as indicator', () => {
render(
<Stepper activeStep={1}>
<Step
step={1}
label="Payment"
indicator={<span data-testid="pay-icon">$</span>}
/>
</Stepper>,
);
expect(screen.getByTestId('pay-icon')).toBeInTheDocument();
});
it('renders a distinct indicator glyph per status on non-current steps', () => {
// All steps completed (activeStep past them) so none is the current step.
render(
<Stepper activeStep={4}>
<Step step={0} label="A" status="success" data-testid="s-success" />
<Step step={1} label="B" status="warning" data-testid="s-warning" />
<Step step={2} label="C" status="error" data-testid="s-error" />
<Step step={3} label="D" data-testid="s-plain" />
</Stepper>,
);
const indicatorClass = (testid: string) =>
(
screen.getByTestId(testid).querySelector('svg')
?.parentElement as HTMLElement
).className;
// Each status renders an svg indicator (no number badge)...
expect(screen.getByTestId('s-success').querySelector('svg')).toBeTruthy();
expect(screen.getByTestId('s-warning').querySelector('svg')).toBeTruthy();
expect(screen.getByTestId('s-error').querySelector('svg')).toBeTruthy();
// ...and each status tints the indicator differently from the others and
// from the plain completed (accent) step.
const classes = new Set([
indicatorClass('s-success'),
indicatorClass('s-warning'),
indicatorClass('s-error'),
indicatorClass('s-plain'),
]);
expect(classes.size).toBe(4);
});
it('lets the current step keep its ring indicator regardless of status', () => {
// The current-step ring's painted color is driven by the StyleX
// `iconInProgress` class (accent), never a status color — the ring replaces
// any status glyph. The `astryx-step-indicator` theme target reflects
// `status` as a data attribute so a theme can still reach it, which is
// orthogonal to the painted color, so assert the StyleX color class here.
const stylexColorClasses = (el: HTMLElement) =>
el.className
.split(/\s+/)
// Keep StyleX classes (debug `Step__styles.*` names + `x*` atomic
// hashes); drop the themeProps data reflections (`in-progress`,
// `success`, `astryx-*`) which are orthogonal to the painted color.
.filter(c => c.startsWith('Step__styles.') || /^x[a-z0-9]+$/.test(c))
.sort()
.join(' ');
const plain = render(
<Stepper activeStep={0}>
<Step step={0} label="A" data-testid="plain" />
</Stepper>,
);
const plainIndicator = stylexColorClasses(
plain.getByTestId('plain').querySelector('svg')
?.parentElement as HTMLElement,
);
// The same current step, now with status="success": the painted ring must
// be unchanged (the current-step ring replaces any status glyph).
const themed = render(
<Stepper activeStep={0}>
<Step step={0} label="A" status="success" data-testid="themed" />
</Stepper>,
);
const themedIndicator = stylexColorClasses(
themed.getByTestId('themed').querySelector('svg')
?.parentElement as HTMLElement,
);
expect(themedIndicator).toBe(plainIndicator);
// And it is the in-progress (accent) color, not a status color.
expect(plainIndicator).toContain('Step__styles.iconInProgress');
});
it('replaces the number badge with a status glyph on not-started steps', () => {
render(
<Stepper activeStep={0}>
<Step step={0} label="A" data-testid="current" />
<Step step={1} label="B" status="error" data-testid="future" />
</Stepper>,
);
const future = screen.getByTestId('future');
// The not-started step would normally show its number ("2"); with a status
// glyph it shows an icon instead.
expect(future.textContent).not.toContain('2');
expect(future.querySelector('svg')).toBeTruthy();
});
it('exposes progress/status as visually hidden text (indicators are aria-hidden)', () => {
render(
<Stepper activeStep={2}>
<Step step={0} label="Account" data-testid="done" />
<Step step={1} label="Payment" status="error" data-testid="failed" />
<Step step={2} label="Review" data-testid="current" />
<Step step={3} label="Confirm" data-testid="upcoming" />
</Stepper>,
);
// Completed step announces "completed"; error status wins over completion.
expect(
within(screen.getByTestId('done')).getByText('completed'),
).toBeInTheDocument();
expect(
within(screen.getByTestId('failed')).getByText('error'),
).toBeInTheDocument();
expect(
within(screen.getByTestId('failed')).queryByText('completed'),
).not.toBeInTheDocument();
// Current step is announced via aria-current, not hidden text; upcoming
// steps stay silent.
expect(
within(screen.getByTestId('current')).queryByText('completed'),
).not.toBeInTheDocument();
expect(
within(screen.getByTestId('upcoming')).queryByText(
/completed|error|warning/,
),
).not.toBeInTheDocument();
});
it('exposes warning and success statuses as visually hidden text', () => {
render(
<Stepper activeStep={2}>
<Step step={0} label="Build" status="warning" data-testid="warned" />
<Step step={1} label="Deploy" status="success" data-testid="passed" />
</Stepper>,
);
expect(
within(screen.getByTestId('warned')).getByText('warning'),
).toBeInTheDocument();
expect(
within(screen.getByTestId('passed')).getByText('completed'),
).toBeInTheDocument();
});
it('composes status into the accessible name of clickable steps', () => {
render(
<Stepper activeStep={2} onStepClick={() => {}}>
<Step step={0} label="Account" />
<Step step={1} label="Payment" status="error" />
<Step step={2} label="Review" />
</Stepper>,
);
expect(
screen.getByRole('button', {name: 'Go to step 1: Account, completed'}),
).toBeInTheDocument();
expect(
screen.getByRole('button', {name: 'Go to step 2: Payment, error'}),
).toBeInTheDocument();
// The current step gets no status suffix (aria-current covers it).
expect(
screen.getByRole('button', {name: 'Go to step 3: Review'}),
).toBeInTheDocument();
});
it('exposes hidden status text in the on-track layout too', () => {
render(
<Stepper activeStep={1} indicatorPosition="on-track">
<Step step={0} label="Account" data-testid="ot-done" />
<Step step={1} label="Payment" data-testid="ot-current" />
</Stepper>,
);
expect(
within(screen.getByTestId('ot-done')).getByText('completed'),
).toBeInTheDocument();
expect(
within(screen.getByTestId('ot-current')).queryByText('completed'),
).not.toBeInTheDocument();
});
// A vertical on-track step's content slot renders outside the row that draws
// the connector, so without its own segment the track breaks open around any
// step carrying content. jsdom can't measure the line, so assert the wiring:
// the slot carries a segment, and it hides on the last step like the row's
// trailing one does.
it('continues the on-track connector past a step content slot', () => {
render(
<Stepper
activeStep={1}
orientation="vertical"
indicatorPosition="on-track">
<Step step={0} label="Account" data-testid="ot-plain" />
<Step step={1} label="Payment" data-testid="ot-content">
<button type="button">Pay now</button>
</Step>
</Stepper>,
);
expect(
screen
.getByTestId('ot-content')
.querySelector('[class*="otContentSegV"][class*="otSegHiddenIfLast"]'),
).toBeInTheDocument();
// A step without content has no slot, so no extra segment.
expect(
screen.getByTestId('ot-plain').querySelector('[class*="otContentSegV"]'),
).not.toBeInTheDocument();
});
describe('keyboard interaction', () => {
it('activates a step with Enter', async () => {
const user = userEvent.setup();
const handleClick = vi.fn();
render(
<Stepper activeStep={2} onStepClick={handleClick}>
<Step step={0} label="Step 1" />
<Step step={1} label="Step 2" />
<Step step={2} label="Step 3" />
</Stepper>,
);
await user.tab();
expect(
screen.getByRole('button', {name: 'Go to step 1: Step 1, completed'}),
).toHaveFocus();
await user.keyboard('{Enter}');
expect(handleClick).toHaveBeenCalledWith(0);
});
it('activates a step with Space', async () => {
const user = userEvent.setup();
const handleClick = vi.fn();
render(
<Stepper activeStep={2} onStepClick={handleClick}>
<Step step={0} label="Step 1" />
<Step step={1} label="Step 2" />
<Step step={2} label="Step 3" />
</Stepper>,
);
await user.tab();
await user.keyboard(' ');
expect(handleClick).toHaveBeenCalledWith(0);
});
it('tabs through steps in document order, disabled ones included', async () => {
const user = userEvent.setup();
render(
<Stepper activeStep={3} onStepClick={() => {}}>
<Step step={0} label="One" />
<Step step={1} label="Two" isDisabled />
<Step step={2} label="Three" />
</Stepper>,
);
await user.tab();
expect(
screen.getByRole('button', {name: 'Go to step 1: One, completed'}),
).toHaveFocus();
// 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'}),
).toHaveFocus();
});
it('supports keyboard activation in the on-track layout', async () => {
const user = userEvent.setup();
const handleClick = vi.fn();
render(
<Stepper
activeStep={2}
indicatorPosition="on-track"
onStepClick={handleClick}>
<Step step={0} label="Cart" />
<Step step={1} label="Shipping" />
<Step step={2} label="Payment" />
</Stepper>,
);
await user.tab();
await user.keyboard('{Enter}');
expect(handleClick).toHaveBeenCalledWith(0);
});
});
describe('fragment-grouped steps', () => {
const onTrackSteps = (
<>
<Step step={0} label="Cart" />
<Step step={1} label="Shipping" />
<Step step={2} label="Payment" />
</>
);
it('renders on-track steps identically whether they are flat or grouped in a fragment', () => {
const flat = render(
<Stepper activeStep={1} indicatorPosition="on-track">
<Step step={0} label="Cart" />
<Step step={1} label="Shipping" />
<Step step={2} label="Payment" />
</Stepper>,
);
const flatHtml = flat.container.innerHTML;
flat.unmount();
const grouped = render(
<Stepper activeStep={1} indicatorPosition="on-track">
{onTrackSteps}
</Stepper>,
);
expect(grouped.container.innerHTML).toBe(flatHtml);
});
// The connector's end segments are hidden by CSS keyed to the step's own
// <li> position, which jsdom can't evaluate — assert the wiring instead:
// every step carries the same hide-if-first/hide-if-last classes, so no
// step is singled out by counting children.
it('gives every grouped step the same structural connector classes', () => {
render(
<Stepper activeStep={1} indicatorPosition="on-track">
{onTrackSteps}
</Stepper>,
);
const items = screen.getAllByRole('listitem');
expect(items).toHaveLength(3);
for (const item of items) {
expect(
item.querySelector('[class*="otSegHiddenIfFirst"]'),
).toBeInTheDocument();
expect(
item.querySelector('[class*="otSegHiddenIfLast"]'),
).toBeInTheDocument();
}
});
it('keeps every grouped step keyboard-activatable', async () => {
const user = userEvent.setup();
const handleClick = vi.fn();
render(
<Stepper
activeStep={2}
indicatorPosition="on-track"
onStepClick={handleClick}>
{onTrackSteps}
</Stepper>,
);
screen
.getByRole('button', {name: 'Go to step 2: Shipping, completed'})
.focus();
await user.keyboard('{Enter}');
expect(handleClick).toHaveBeenCalledWith(1);
});
});
// The connector fill animates a ::before scaled along the track axis, which
// jsdom neither renders nor times — so assert the wiring the animation hangs
// off: every connector carries the shared track style (the element that owns
// the fill layer and its transition), and the fill/empty pair it gets is the
// one for its axis, since the wrong axis would scale the line's thickness
// away instead of its length.
describe('connector fill', () => {
const barEl = (testId: string) =>
screen
.getByTestId(testId)
.querySelector('[class*="connectorTrack"]') as HTMLElement;
it('scales the separated bar along the inline axis when horizontal', () => {
render(
<Stepper activeStep={1} orientation="horizontal">
<Step step={0} label="A" data-testid="a" />
<Step step={1} label="B" data-testid="b" />
<Step step={2} label="C" data-testid="c" />
</Stepper>,
);
// Reached steps are filled, upcoming ones empty — both on the H pair.
expect(barEl('a').className).toContain('connectorFillH');
expect(barEl('b').className).toContain('connectorFillH');
expect(barEl('c').className).toContain('connectorEmptyH');
expect(barEl('c').className).not.toContain('connectorEmptyV');
});
it('scales the separated bar along the block axis when vertical', () => {
render(
<Stepper activeStep={1} orientation="vertical">
<Step step={0} label="A" data-testid="a" />
<Step step={1} label="B" data-testid="b" />
<Step step={2} label="C" data-testid="c" />
</Stepper>,
);
expect(barEl('a').className).toContain('connectorFillV');
expect(barEl('c').className).toContain('connectorEmptyV');
expect(barEl('c').className).not.toContain('connectorEmptyH');
});
it('gives every on-track segment the track style and its axis pair', () => {
render(
<Stepper activeStep={1} indicatorPosition="on-track">
<Step step={0} label="A" data-testid="a" />
<Step step={1} label="B" data-testid="b" />
<Step step={2} label="C" data-testid="c" />
</Stepper>,
);
// A step draws the segments flanking its own indicator, so each carries
// the track style; none may fall back to the vertical axis pair here.
for (const id of ['a', 'b', 'c']) {
const segs = Array.from(
screen.getByTestId(id).querySelectorAll('[class*="connectorTrack"]'),
);
expect(segs).toHaveLength(2);
for (const seg of segs) {
expect(seg.className).toMatch(/connector(Fill|Empty)H/);
expect(seg.className).not.toMatch(/connector(Fill|Empty)V/);
}
}
// Progress splits at the current step: the segment arriving at it is
// filled, the one leaving it is not.
const current = Array.from(
screen.getByTestId('b').querySelectorAll('[class*="connectorTrack"]'),
);
expect(current[0].className).toContain('connectorFillH');
expect(current[1].className).toContain('connectorEmptyH');
});
});
// One change animates the connector: advancing a single step. jsdom runs no
// transitions, so what is asserted here is the schedule one would run on.
// Every segment's slice is expressed in one unit — the node-to-node span —
// so a slice reads as `{start, length}` in spans, a segment that lands at
// once reads as a pair of zeros, and a span stitched from several segments
// is contiguous when its slices abut in track order.
describe('connector fill motion', () => {
const separated = (activeStep: number) => (
<Stepper activeStep={activeStep} orientation="horizontal">
<Step step={0} label="A" data-testid="a" />
<Step step={1} label="B" data-testid="b" />
<Step step={2} label="C" data-testid="c" />
<Step step={3} label="D" data-testid="d" />
<Step step={4} label="E" data-testid="e" />
</Stepper>
);
// StyleX routes dynamic values through hashed custom properties, whose
// names are not readable by hand. Recover the mapping from the one change
// that animates — the only one where the two carry different values. The
// probe mounts alongside whatever the calling test rendered, so it needs a
// test id of its own to be found.
const timingVarNames = (() => {
let cached: {duration: string; delay: string} | null = null;
return () => {
if (cached) {
return cached;
}
const steps = (
<>
<Step step={0} label="A" />
<Step step={1} label="B" data-testid="timing-probe" />
</>
);
const probe = render(<Stepper activeStep={0}>{steps}</Stepper>);
probe.rerender(<Stepper activeStep={1}>{steps}</Stepper>);
const el = probe
.getByTestId('timing-probe')
.querySelector('[class*="connectorTiming"]') as HTMLElement;
const found: Record<string, string> = {};
for (const name of Array.from(el.style)) {
const value = el.style.getPropertyValue(name).trim();
if (value === 'var(--duration-medium)') {
found.duration = name;
} else if (value === '0s') {
found.delay = name;
}
}
probe.unmount();
cached = found as {duration: string; delay: string};
return cached;
};
})();
/**
* A slice as a multiple of one span: `0s` is none of a span, a bare span
* expression is all of one, and `calc(<span> * n)` is n of them.
*/
const spans = (value: string): number => {
if (value === '0s') {
return 0;
}
const scaled = value.match(/\* ([\d.]+)\)$/);
return scaled ? Number(scaled[1]) : 1;
};
/** Every connector in track order, as `{start, length}` in spans. */
const schedule = (el: HTMLElement) =>
Array.from(
el.querySelectorAll<HTMLElement>('[class*="connectorTiming"]'),
).map(seg => {
const names = timingVarNames();
return {
start: spans(seg.style.getPropertyValue(names.delay).trim()),
length: spans(seg.style.getPropertyValue(names.duration).trim()),
};
});
/** Nothing in this subtree moves over time. */
const isInstant = (el: HTMLElement) =>
schedule(el).every(slice => slice.start === 0 && slice.length === 0);
/** The span expression itself, which carries the fill's duration. */
const spanExpression = (el: HTMLElement) => {
const raw = (
el.querySelector('[class*="connectorTiming"]') as HTMLElement
).style
.getPropertyValue(timingVarNames().duration)
.trim();
return raw.replace(/^calc\((.*) \* [\d.]+\)$/, '$1');
};
/**
* The timing functions the fills in this subtree run on. Unlike the
* duration and the delay this is a static style, so it lives in the
* injected stylesheet under one of each segment's atomic classes rather
* than in an inline custom property.
*/
const fillEasings = (el: HTMLElement) => {
const found = new Set<string>();
for (const seg of Array.from(
el.querySelectorAll<HTMLElement>('[class*="connectorTrack"]'),
)) {
const classes = new Set(seg.className.split(/\s+/));
for (const sheet of Array.from(document.styleSheets)) {
for (const rule of Array.from(sheet.cssRules)) {
if (!('selectorText' in rule)) {
continue;
}
const {selectorText, style} = rule as CSSStyleRule;
const owner = selectorText.match(/^\.([\w-]+)/);
if (
owner == null ||
!classes.has(owner[1]) ||
!selectorText.endsWith('::before')
) {
continue;
}
const value = style
.getPropertyValue('transition-timing-function')
.trim();
if (value !== '') {
found.add(value);
}
}
}
}
return [...found];
};
it('animates the one span a single forward step crosses', () => {
const {rerender, getByTestId} = render(separated(0));
rerender(separated(1));
// The bar arriving at the new step fills across the whole span.
expect(schedule(getByTestId('b'))).toEqual([{start: 0, length: 1}]);
// Every other bar is untouched, so it is handed no timing that a later
// change could inherit as a stale delay.
for (const id of ['a', 'c', 'd', 'e']) {
expect(isInstant(getByTestId(id))).toBe(true);
}
});
it('fills that span over the medium duration', () => {
// A fill crossing a whole segment is a spatial change, not a
// micro-interaction, so it sits above the fast band.
const {rerender, getByTestId} = render(separated(0));
rerender(separated(1));
expect(spanExpression(getByTestId('b'))).toBe('var(--duration-medium)');
});
it('fills linearly so a stitched span reads as one front', () => {
// An on-track span is drawn by two segments, three where a content slot
// splits it. A curve applied per segment restarts its deceleration at
// every seam, and the seam becomes the most visible part of the result.
const {container} = render(separated(0));
expect(fillEasings(container.firstElementChild as HTMLElement)).toEqual([
'linear',
]);
});
it('lands a forward jump of more than one step at once', () => {
// A jump is a navigation rather than a progression: sweeping a front
// across the crossed segments makes the user sit out a journey they
// asked to skip.
const {rerender, getByTestId} = render(separated(0));
rerender(separated(3));
for (const id of ['a', 'b', 'c', 'd', 'e']) {
expect(isInstant(getByTestId(id))).toBe(true);
}
});
it('lands a backward change at once, one step or several', () => {
// Retracting is the same arithmetic as filling, but it ends on a
// shrinking stub of accent rather than a nearly-full bar, and a remnant
// still on the track reads as unfinished however briefly it is there.
for (const to of [2, 0]) {
const view = render(separated(3));
view.rerender(separated(to));
for (const id of ['a', 'b', 'c', 'd', 'e']) {
expect(isInstant(view.getByTestId(id))).toBe(true);
}
view.unmount();
}
});
it('leaves every segment instant on mount', () => {
// A stepper opening mid-flow has no previous step to have travelled
// from, so its completed segments must paint filled at once rather than
// replaying the history that would have produced them.
const {getByTestId} = render(separated(3));
for (const id of ['a', 'b', 'c', 'd', 'e']) {
expect(isInstant(getByTestId(id))).toBe(true);
}
});
const onTrack = (activeStep: number) => (
<Stepper
activeStep={activeStep}
orientation="horizontal"
indicatorPosition="on-track">
<Step step={0} label="A" data-testid="a" />
<Step step={1} label="B" data-testid="b" />
<Step step={2} label="C" data-testid="c" />
</Stepper>
);
it('runs the leaving half of an on-track span before the arriving half', () => {
const {rerender, getByTestId} = render(onTrack(0));
rerender(onTrack(1));
// The span is drawn by two steps. Left alone both halves flip together
// and the gap between two nodes reads as two dashes converging on the
// space between them; split, the one leaving the near node runs first
// and the pair reads as one stretch of track filling.
const [aCap, aRail] = schedule(getByTestId('a'));
const [bCap, bRail] = schedule(getByTestId('b'));
expect(aRail).toEqual({start: 0, length: 0.5});
expect(bCap).toEqual({start: 0.5, length: 0.5});
// The segments either side of the span are not part of it.
expect(aCap).toEqual({start: 0, length: 0});
expect(bRail).toEqual({start: 0, length: 0});
expect(isInstant(getByTestId('c'))).toBe(true);
});
const verticalWithContent = (activeStep: number) => (
<Stepper
activeStep={activeStep}
orientation="vertical"
indicatorPosition="on-track">
<Step step={0} label="A" data-testid="a" />
<Step step={1} label="B" data-testid="b">
<button type="button">Do it</button>
</Step>
<Step step={2} label="C" data-testid="c" />
</Stepper>
);
it('threads a content slot segment into its span between rail and cap', () => {
const {rerender, getByTestId} = render(verticalWithContent(1));
rerender(verticalWithContent(2));
// A vertical step with content draws a third segment down the side of
// the slot, so the span leaving it is stitched from three pieces and all
// three have to fall in track order. The rail and cap are unequal
// lengths, so the slices are unequal too.
const [bCap, bRail, bContent] = schedule(getByTestId('b'));
const [cCap] = schedule(getByTestId('c'));
expect(bRail).toEqual({start: 0, length: 0.175});
expect(bContent).toEqual({start: 0.175, length: 0.525});
expect(cCap).toEqual({start: 0.7, length: 0.3});
// The span arriving at this step belongs to the previous change.
expect(bCap).toEqual({start: 0, length: 0});
expect(isInstant(getByTestId('a'))).toBe(true);
});
it('tracks the previous step correctly under StrictMode double rendering', () => {
// The previous step is derived during render from state, so StrictMode
// invoking the render twice must queue the same successor both times
// rather than losing a step or advancing two — which would turn a single
// forward step into a two-step jump and stop it animating.
const {rerender, getByTestId} = render(
<StrictMode>{separated(0)}</StrictMode>,
);
rerender(<StrictMode>{separated(1)}</StrictMode>);
expect(schedule(getByTestId('b'))).toEqual([{start: 0, length: 1}]);
// A second step measures from step 1, not from the original mount, so
// the next span animates and the one behind it stops.
rerender(<StrictMode>{separated(2)}</StrictMode>);
expect(schedule(getByTestId('c'))).toEqual([{start: 0, length: 1}]);
expect(isInstant(getByTestId('b'))).toBe(true);
});
});
describe('Stepper collapse (narrow containers)', () => {
const FRAME = '.astryx-stepper-frame';
const SUMMARY = '.astryx-stepper-summary';
/**
* jsdom has no layout, so the width the public Stepper list measures is
* described by hand. The frame deliberately reports a wide parent: this
* catches any accidental switch to measuring an unconstrained wrapper, while
* the regression below separately pins consumer layout styling to that frame.
* The value has to be in place before the first render because the shared
* resize observer takes its opening measurement synchronously during commit.
*/
function atWidth(width: number, ui: React.ReactElement) {
const original = Object.getOwnPropertyDescriptor(
Element.prototype,
'clientWidth',
);
Object.defineProperty(Element.prototype, 'clientWidth', {
configurable: true,
get(this: Element) {
if (this.classList.contains('astryx-stepper')) {
return width;
}
return this.classList.contains('astryx-stepper-frame') ? 1000 : 0;
},
});
try {
return render(ui);
} finally {
if (original) {
Object.defineProperty(Element.prototype, 'clientWidth', original);
} else {
delete (Element.prototype as {clientWidth?: number}).clientWidth;
}
}
}
const fourSteps = (
props: Partial<React.ComponentProps<typeof Stepper>>,
) => (
<Stepper activeStep={1} {...props}>
<Step step={0} label="Cart" />
<Step step={1} label="Shipping" description="Where it goes" />
<Step step={2} label="Delivery" />
<Step step={3} label="Payment" />
</Stepper>
);
it('keeps every label while each step has room for one', () => {
// Four steps across 600px is 150 each, comfortably over the threshold.
atWidth(600, fourSteps({}));
for (const name of ['Cart', 'Shipping', 'Delivery', 'Payment']) {
expect(screen.getByText(name)).toBeInTheDocument();
}
expect(document.querySelector(FRAME)).toBeInTheDocument();
});
it('keeps a consumer-constrained summary inside the styled component box', () => {
atWidth(
320,
<div style={{width: 1000}}>
<Stepper activeStep={1} style={{width: 320}}>
<Step step={0} label="Cart" />
<Step step={1} label="Shipping" />
<Step step={2} label="Delivery" />
<Step step={3} label="Payment" />
</Stepper>
</div>,
);
const list = screen.getByRole<HTMLOListElement>('list');
const frame = list.parentElement as HTMLElement;
const summary = document.querySelector<HTMLElement>(SUMMARY);
expect(summary).not.toBeNull();
expect(frame).toHaveClass('astryx-stepper-frame');
expect(frame).toHaveStyle({width: '320px'});
expect(summary!.parentElement).toBe(frame);
expect(list.style.width).toBe('');
});
it('puts horizontal className on the frame without moving list DOM props or ref', () => {
const ref = createRef<HTMLOListElement>();
atWidth(
320,
<Stepper
ref={ref}
activeStep={1}
className="consumer-stepper"
data-testid="public-stepper-list"
aria-describedby="stepper-help">
<Step step={0} label="Cart" />
<Step step={1} label="Shipping" />
<Step step={2} label="Delivery" />
<Step step={3} label="Payment" />
</Stepper>,
);
const list = screen.getByTestId('public-stepper-list');
const frame = list.parentElement as HTMLElement;
expect(ref.current).toBe(list);
expect(list).toHaveAttribute('aria-describedby', 'stepper-help');
expect(list).not.toHaveClass('consumer-stepper');
expect(frame).toHaveClass('consumer-stepper');
expect(frame).not.toHaveAttribute('data-testid');
expect(frame).not.toHaveAttribute('aria-describedby');
});
it('drops the labels and names the current step once they no longer fit', () => {
// 320px over four steps is 80 each, under the 112px a label needs.
atWidth(320, fourSteps({}));
const summary = document.querySelector<HTMLElement>(SUMMARY);
expect(summary).not.toBeNull();
// Only the current step is named where it can be seen, and only it keeps
// a description — the rest have no label left to hang one under.
expect(within(summary!).getByText('Shipping')).toBeInTheDocument();
expect(within(summary!).getByText('Where it goes')).toBeInTheDocument();
// The separated track has no indicator nodes of its own, so the compact
// label keeps the active indicator beside it.
expect(
summary!.querySelector('.astryx-step-indicator'),
).toBeInTheDocument();
const list = screen.getByRole('list');
expect(within(list).queryByText('Where it goes')).toBeNull();
expect(screen.getAllByRole('listitem')).toHaveLength(4);
});
it('places the compact summary directly against the track', () => {
atWidth(320, fourSteps({}));
const frame = document.querySelector<HTMLElement>(FRAME);
expect(frame).not.toBeNull();
expect(['0', '0px']).toContain(getComputedStyle(frame!).gap);
});
it('collapses later the more steps there are', () => {
// 320px is ample for two steps at 160 each, and far too little for four.
atWidth(
320,
<Stepper activeStep={0}>
<Step step={0} label="Details" />
<Step step={1} label="Review" />
</Stepper>,
);
expect(screen.getByRole('list')).toBeInTheDocument();
expect(document.querySelector('.astryx-stepper-summary')).toBeNull();
});
it('treats the minimum step width as pixels without a measurement probe', () => {
atWidth(
360,
fourSteps({
horizontalOptions: {
minimumStepWidth: 80,
collapsedVariant: 'withLabelAndControls',
},
}),
);
expect(document.querySelector(SUMMARY)).toBeNull();
expect(
Array.from(
document.querySelectorAll<HTMLElement>('[aria-hidden="true"]'),
).find(element => element.style.width !== ''),
).toBeUndefined();
});
it('leaves a vertical stepper alone at any width', () => {
// A column gives every label a row of its own, so there is nothing to
// run out of and no frame to measure.
atWidth(120, fourSteps({orientation: 'vertical'}));
for (const name of ['Cart', 'Shipping', 'Delivery', 'Payment']) {
expect(screen.getByText(name)).toBeInTheDocument();
}
expect(document.querySelector(FRAME)).toBeNull();
});
it('keeps the sequence whole for a screen reader after collapsing', () => {
atWidth(320, fourSteps({}));
const items = screen.getAllByRole('listitem');
// Every step still names itself and the current one is still marked, so
// the list reads as a complete sequence with the labels off the screen.
// The status word rides along with the name, as it does when visible —
// "Cart" is behind the current step, so it reads as completed.
expect(items.map(li => li.textContent)).toEqual([
'Cartcompleted',
'Shipping',
'Delivery',
'Payment',
]);
expect(items[1]).toHaveAttribute('aria-current', 'step');
});
it('offers no step controls on a stepper that cannot be navigated', () => {
// A linear flow is driven by the form's own Back and Continue; a second
// pair pointed at a step it will not honour is worse than none.
atWidth(320, fourSteps({}));
expect(screen.queryByRole('button', {name: 'Next step'})).toBeNull();
expect(screen.queryByRole('button', {name: 'Previous step'})).toBeNull();
});
it('moves a step at a time through the controls when one is given', async () => {
const user = userEvent.setup();
const onStepClick = vi.fn();
atWidth(320, fourSteps({onStepClick}));
await user.click(screen.getByRole('button', {name: 'Next step'}));
expect(onStepClick).toHaveBeenCalledWith(2);
await user.click(screen.getByRole('button', {name: 'Previous step'}));
expect(onStepClick).toHaveBeenCalledWith(0);
});
it('skips disabled steps in either direction', async () => {
const user = userEvent.setup();
const onStepClick = vi.fn();
const forward = atWidth(
320,
<Stepper activeStep={1} onStepClick={onStepClick}>
<Step step={0} label="Cart" />
<Step step={1} label="Shipping" />
<Step step={2} label="Delivery" isDisabled />
<Step step={3} label="Payment" />
</Stepper>,
);
await user.click(screen.getByRole('button', {name: 'Next step'}));
expect(onStepClick).toHaveBeenLastCalledWith(3);
forward.unmount();
atWidth(
320,
<Stepper activeStep={2} onStepClick={onStepClick}>
<Step step={0} label="Cart" />
<Step step={1} label="Shipping" isDisabled />
<Step step={2} label="Delivery" />
<Step step={3} label="Payment" />
</Stepper>,
);
await user.click(screen.getByRole('button', {name: 'Previous step'}));
expect(onStepClick).toHaveBeenLastCalledWith(0);
});
it('reads registration state again when a compact control activates', async () => {
const user = userEvent.setup();
const onStepClick = vi.fn();
const disabled = {
0: false,
1: false,
2: false,
3: false,
};
function Registration({step}: {step: 0 | 1 | 2 | 3}) {
const {registerStep} = useStepperContext();
useLayoutEffect(
() =>
registerStep(step, {
getIsDisabled: () => disabled[step],
}),
[registerStep, step],
);
return null;
}
atWidth(
320,
<Stepper activeStep={1} onStepClick={onStepClick}>
<Registration step={0} />
<Registration step={1} />
<Registration step={2} />
<Registration step={3} />
</Stepper>,
);
// Step 2 was the target during render. Change only the registered source;
// no parent render should be needed before activation skips it.
disabled[2] = true;
await user.click(screen.getByRole('button', {name: 'Next step'}));
expect(onStepClick).toHaveBeenCalledWith(3);
});
it('reads the current disabled state from each registration', async () => {
const user = userEvent.setup();
const onStepClick = vi.fn();
const steps = (isDeliveryDisabled: boolean) => (
<Stepper activeStep={1} onStepClick={onStepClick}>
<Step step={0} label="Cart" />
<Step step={1} label="Shipping" />
<Step step={2} label="Delivery" isDisabled={isDeliveryDisabled} />
<Step step={3} label="Payment" />
</Stepper>
);
const {rerender} = atWidth(320, steps(true));
await user.click(screen.getByRole('button', {name: 'Next step'}));
expect(onStepClick).toHaveBeenLastCalledWith(3);
rerender(steps(false));
await user.click(screen.getByRole('button', {name: 'Next step'}));
expect(onStepClick).toHaveBeenLastCalledWith(2);
});
it('disables a summary control with no enabled step in its direction', () => {
atWidth(
320,
<Stepper activeStep={1} onStepClick={() => {}}>
<Step step={0} label="Cart" />
<Step step={1} label="Shipping" />
<Step step={2} label="Delivery" isDisabled />
<Step step={3} label="Payment" isDisabled />
</Stepper>,
);
expect(screen.getByRole('button', {name: 'Next step'})).toHaveAttribute(
'aria-disabled',
'true',
);
});
it.each(['separated', 'on-track'] as const)(
'keeps %s step content mounted across compact resizing',
async indicatorPosition => {
const originalWidth = Object.getOwnPropertyDescriptor(
Element.prototype,
'clientWidth',
);
let width = 600;
let resize: ResizeObserverCallback = () => {};
class ResizeObserverStub {
constructor(callback: ResizeObserverCallback) {
resize = callback;
}
observe() {}
unobserve() {}
disconnect() {}
}
vi.stubGlobal('ResizeObserver', ResizeObserverStub);
Object.defineProperty(Element.prototype, 'clientWidth', {
configurable: true,
get(this: Element) {
return this.classList.contains('astryx-stepper') ? width : 0;
},
});
let view: ReturnType<typeof render> | null = null;
try {
view = render(
<Stepper activeStep={0} indicatorPosition={indicatorPosition}>
<Step step={0} label="Account">
<input aria-label="Account name" defaultValue="" />
</Step>
<Step step={1} label="Review" />
</Stepper>,
);
const user = userEvent.setup();
const input = screen.getByRole<HTMLInputElement>('textbox', {
name: 'Account name',
});
await user.type(input, 'Draft');
const list = screen.getByRole('list');
width = 120;
act(() =>
resize([{target: list} as unknown as ResizeObserverEntry], null!),
);
const compactInput = document.querySelector<HTMLInputElement>(
'input[aria-label="Account name"]',
);
expect(compactInput).toBe(input);
expect(compactInput).toHaveValue('Draft');
expect(compactInput?.closest('[hidden]')).not.toBeNull();
expect(document.querySelector(SUMMARY)).toBeInTheDocument();
width = 600;
act(() =>
resize([{target: list} as unknown as ResizeObserverEntry], null!),
);
expect(
document.querySelector('input[aria-label="Account name"]'),
).toBe(input);
expect(input.closest('[hidden]')).toBeNull();
expect(document.querySelector(SUMMARY)).toBeNull();
} finally {
view?.unmount();
vi.unstubAllGlobals();
if (originalWidth) {
Object.defineProperty(
Element.prototype,
'clientWidth',
originalWidth,
);
} else {
delete (Element.prototype as {clientWidth?: number}).clientWidth;
}
}
},
);
it('measures the list only while it is mounted and horizontal', () => {
const observed = new Set<Element>();
class ResizeObserverStub {
observe(element: Element) {
observed.add(element);
}
unobserve(element: Element) {
observed.delete(element);
}
disconnect() {
observed.clear();
}
}
vi.stubGlobal('ResizeObserver', ResizeObserverStub);
const stepper = (orientation: 'horizontal' | 'vertical') => (
<Stepper activeStep={0} orientation={orientation}>
<Step step={0} label="Account" />
<Step step={1} label="Review" />
</Stepper>
);
try {
const view = render(stepper('horizontal'));
const horizontalList = screen.getByRole('list');
expect(observed.has(horizontalList)).toBe(true);
view.rerender(stepper('vertical'));
expect(observed.has(horizontalList)).toBe(false);
expect(observed.has(screen.getByRole('list'))).toBe(false);
view.rerender(stepper('horizontal'));
const list = screen.getByRole('list');
expect(observed.has(list)).toBe(true);
view.unmount();
expect(observed.has(list)).toBe(false);
} finally {
vi.unstubAllGlobals();
}
});
it('stops the controls at both ends of the sequence', () => {
const onStepClick = vi.fn();
// Disabled the Astryx way: aria-disabled, so the control keeps its place
// in the tab order and can still explain itself at the end of a flow.
const disabled = (name: string) =>
screen.getByRole('button', {name}).getAttribute('aria-disabled');
const {unmount} = atWidth(320, fourSteps({onStepClick, activeStep: 0}));
expect(disabled('Previous step')).toBe('true');
expect(disabled('Next step')).not.toBe('true');
unmount();
atWidth(320, fourSteps({onStepClick, activeStep: 3}));
expect(disabled('Previous step')).not.toBe('true');
expect(disabled('Next step')).toBe('true');
});
it('takes the collapsed steps out of the tab order', () => {
// The label goes and the click target goes with it: a 4px bar is not
// something to press, and a focus stop with nothing visible to show for
// it is worse than no focus stop at all.
atWidth(320, fourSteps({onStepClick: vi.fn()}));
const stepButtons = screen
.getAllByRole('button')
.filter(b => (b.getAttribute('aria-label') ?? '').startsWith('Go to'));
expect(stepButtons).toHaveLength(0);
});
it('keeps collapsed on-track nodes visible but non-interactive', () => {
// The indicator stays on the rail as progress information, while the
// summary controls below it own navigation in the compact presentation.
atWidth(
320,
fourSteps({indicatorPosition: 'on-track', onStepClick: vi.fn()}),
);
const delivery = screen.getAllByRole('listitem')[2];
expect(
delivery.querySelector('.astryx-step-indicator'),
).toBeInTheDocument();
const summary = document.querySelector<HTMLElement>(SUMMARY);
expect(summary).not.toBeNull();
expect(summary!.querySelector('.astryx-step-indicator')).toBeNull();
expect(
screen.queryByRole('button', {name: /^Go to step 3: Delivery/}),
).not.toBeInTheDocument();
expect(screen.getByRole('button', {name: 'Previous step'})).toBeEnabled();
expect(screen.getByRole('button', {name: 'Next step'})).toBeEnabled();
});
it('drops the controls but keeps the name on request', () => {
// The shape of a wizard whose footer already has Back and Continue: the
// steps stay clickable at full width, and the phone gets one pair of
// controls rather than two.
atWidth(
320,
fourSteps({
onStepClick: vi.fn(),
horizontalOptions: {
minimumStepWidth: 112,
collapsedVariant: 'withLabel',
},
}),
);
expect(screen.queryByRole('button', {name: 'Next step'})).toBeNull();
expect(screen.queryByRole('button', {name: 'Previous step'})).toBeNull();
const summary = document.querySelector<HTMLElement>(SUMMARY);
expect(summary).not.toBeNull();
expect(within(summary!).getByText('Shipping')).toBeInTheDocument();
});
it('leaves a bare track when the label is hidden, even with a handler', () => {
// The surrounding flow owns both its heading and navigation. Keeping an
// onStepClick handler for the expanded layout must not add a compact row.
atWidth(
320,
fourSteps({
onStepClick: vi.fn(),
horizontalOptions: {
minimumStepWidth: 112,
collapsedVariant: 'hiddenLabel',
},
}),
);
expect(document.querySelector(SUMMARY)).toBeNull();
expect(screen.queryByRole('button', {name: 'Previous step'})).toBeNull();
expect(screen.queryByRole('button', {name: 'Next step'})).toBeNull();
expect(screen.getByRole('list')).toBeInTheDocument();
expect(screen.getAllByRole('listitem')).toHaveLength(4);
});
it('also leaves the bare track when there is no handler', () => {
atWidth(
320,
fourSteps({
horizontalOptions: {
minimumStepWidth: 112,
collapsedVariant: 'hiddenLabel',
},
}),
);
expect(document.querySelector(SUMMARY)).toBeNull();
expect(screen.getByRole('list')).toBeInTheDocument();
expect(screen.getAllByRole('listitem')).toHaveLength(4);
});
it('keeps the sequence whole for a screen reader when the label is hidden', () => {
// The visible row only repeats the list, so suppressing it cannot shorten
// what a screen reader hears. Same expectation as the default collapse.
atWidth(
320,
fourSteps({
horizontalOptions: {
minimumStepWidth: 112,
collapsedVariant: 'hiddenLabel',
},
}),
);
const items = screen.getAllByRole('listitem');
expect(items.map(li => li.textContent)).toEqual([
'Cartcompleted',
'Shipping',
'Delivery',
'Payment',
]);
expect(items[1]).toHaveAttribute('aria-current', 'step');
});
it('leaves a stepper that has room for its labels alone', () => {
// The variant is scoped to the collapse and does not strip desktop labels.
atWidth(
600,
fourSteps({
onStepClick: vi.fn(),
horizontalOptions: {
minimumStepWidth: 112,
collapsedVariant: 'hiddenLabel',
},
}),
);
for (const name of ['Cart', 'Shipping', 'Delivery', 'Payment']) {
expect(screen.getByText(name)).toBeInTheDocument();
}
expect(
screen.getByRole('button', {name: /^Go to step 3: Delivery/}),
).toBeInTheDocument();
});
it('keeps on-track nodes presentational after controls are dropped', () => {
// Compact navigation belongs to the summary controls in both layouts.
// Turning those controls off leaves the rail as progress information,
// rather than reviving a second, denser set of click targets.
atWidth(
320,
fourSteps({
indicatorPosition: 'on-track',
onStepClick: vi.fn(),
horizontalOptions: {
minimumStepWidth: 112,
collapsedVariant: 'withLabel',
},
}),
);
expect(screen.queryByRole('button', {name: 'Next step'})).toBeNull();
expect(
screen.queryByRole('button', {name: /^Go to step 3: Delivery/}),
).toBeNull();
const indicators = screen
.getAllByRole('listitem')
.map(item => item.querySelector('.astryx-step-indicator'));
expect(indicators).toHaveLength(4);
expect(indicators.every(Boolean)).toBe(true);
});
});
describe('--step-connector-gap', () => {
// The on-track layouts draw the connector as one segment either side of
// the indicator. A theme that wants the track to stop short of the node
// sets one var; Astryx spends it on whichever side each segment faces the
// node from, so the pair leaves a symmetric hole and the caller never
// names the pieces.
const onTrack = (orientation: 'vertical' | 'horizontal') => (
<Stepper
activeStep={1}
orientation={orientation}
indicatorPosition="on-track">
<Step step={0} label="One" />
<Step step={1} label="Two" />
</Stepper>
);
/**
* Every declaration the injected stylesheet carries for an element's own
* atomic classes, `::before` rules included — the same route `fillEasings`
* above takes, because StyleX puts static styles in the sheet rather than
* inline and jsdom resolves no cascade of its own.
*
* Atomic class names are unique hashes, so the owning class is matched
* anywhere in the selector rather than only at its head: a StyleX variant
* such as the `dir="rtl"` mirror emits a compound selector the class does
* not lead. Those rules are tagged `rtl:` so a test can tell the two
* directions apart.
*/
const declarationsFor = (el: Element) => {
const classes = new Set(el.className.split(/\s+/));
const out: string[] = [];
for (const sheet of Array.from(document.styleSheets)) {
for (const rule of Array.from(sheet.cssRules)) {
if (!('selectorText' in rule)) {
continue;
}
const {selectorText, style} = rule as CSSStyleRule;
const owner = [...selectorText.matchAll(/\.([\w-]+)/g)].find(match =>
classes.has(match[1]),
);
if (owner == null) {
continue;
}
const prefix =
(selectorText.includes('[dir="rtl"]') ? 'rtl:' : '') +
(selectorText.endsWith('::before') ? 'before:' : '');
for (const prop of Array.from(style)) {
out.push(`${prefix}${prop}:${style.getPropertyValue(prop)}`);
}
}
}
return out.join(';');
};
it('clips the side each segment faces the node from', () => {
const {container} = render(onTrack('vertical'));
const [lead, rail] = [
...container.querySelectorAll('.astryx-step-connector'),
];
// Above the node clips its bottom edge, below it clips its top —
// mirrored, so the hole is centred on the indicator.
expect(declarationsFor(lead)).toMatch(/clip-path:inset\(0 0 [^;]*\)/);
expect(declarationsFor(rail)).toMatch(/clip-path:inset\([^0][^;]*0 0\)/);
});
it('uses the inline axis when the stepper is horizontal', () => {
const {container} = render(onTrack('horizontal'));
const [lead, rail] = [
...container.querySelectorAll('.astryx-step-connector'),
];
expect(declarationsFor(lead)).toMatch(
/clip-path:inset\(0 [^0][^;]*0 0\)/,
);
expect(declarationsFor(rail)).toMatch(
/clip-path:inset\(0 0 0 [^0][^;]*\)/,
);
});
it('clips the track and the fill with one declaration', () => {
// The gap has to reach two layers: the track is the segment's own
// background, the accent fill an absolutely placed ::before. Spending it
// on each separately meant two declarations on two boxes, so a
// percentage resolved against a different containing block for each and
// stopped them ~1.2px apart. One clip on the segment covers both.
const {container} = render(onTrack('vertical'));
const lead = container.querySelector(
'.astryx-step-connector',
) as HTMLElement;
const declarations = declarationsFor(lead);
expect(declarations).toContain('clip-path');
// No per-layer copy of the gap to disagree with.
expect(declarations).not.toMatch(
/before:[a-z-]*padding[^;]*connector-gap/,
);
expect(declarations).not.toMatch(/before:inset[^;]*connector-gap/);
});
it('clamps a negative gap away and caps an oversized one', () => {
// A theme value arrives with nothing in between to reject it, and
// `inset()` is not padding: Chromium ACCEPTS `inset(0 0 -4px 0)` rather
// than clamping it, so the floor has to be written. The cap is the
// flexible segment's own `min-height`, bounding an oversized gap to a
// short track. Neither can grow the Stepper — a clip cannot change
// layout.
const {container} = render(onTrack('vertical'));
const lead = container.querySelector(
'.astryx-step-connector',
) as HTMLElement;
const declarations = declarationsFor(lead);
expect(declarations).toContain('max(0px');
expect(declarations).toContain('min(var(--step-connector-gap');
});
it('flips the horizontal clip under dir="rtl"', () => {
// `clip-path: inset()` is physical (top/right/bottom/left) and has no
// logical form, but the row reverses under `dir="rtl"`. Unflipped, the
// leading segment sits to the RIGHT of the node in RTL and still clips
// its right edge, opening the hole at the join between steps instead of
// at the indicator.
const {container} = render(onTrack('horizontal'));
const [lead, rail] = [
...container.querySelectorAll('.astryx-step-connector'),
];
// Each segment carries BOTH the LTR clip and its mirrored RTL variant.
const leadRules = declarationsFor(lead);
const railRules = declarationsFor(rail);
expect(leadRules).toMatch(/rtl:clip-path:inset\(0 0 0 [^0]/);
expect(railRules).toMatch(/rtl:clip-path:inset\(0 [^0][^;]*0 0\)/);
});
it('leaves the track unbroken when there is no indicator to avoid', () => {
// `indicator="none"` renders no node, so a gap is a hole in a track that
// is meant to be continuous.
const {container} = render(
<Stepper activeStep={0} indicatorPosition="on-track">
<Step step={0} label="One" indicator="none" />
<Step step={1} label="Two" indicator="none" />
</Stepper>,
);
const connectors = [
...container.querySelectorAll('.astryx-step-connector'),
];
expect(connectors.length).toBeGreaterThan(0);
for (const node of connectors) {
expect(declarationsFor(node)).not.toContain('--step-connector-gap');
}
});
it('defaults to no connector gap at the point of use', () => {
const {container} = render(onTrack('vertical'));
const root = container.querySelector('.astryx-stepper') as HTMLElement;
const lead = container.querySelector(
'.astryx-step-connector',
) as HTMLElement;
expect(declarationsFor(root)).toContain('--step-connector-gap:inherit');
expect(declarationsFor(lead)).toContain('var(--step-connector-gap,0px)');
});
it('inherits a horizontal frame override through the root', () => {
// Horizontal layout props belong to the frame. The list must leave the
// public variable inheriting so that value reaches its connectors; the
// use-site fallback above supplies 0px when no ancestor sets a value.
const {container} = render(
<Stepper
activeStep={1}
orientation="horizontal"
indicatorPosition="on-track"
style={{'--step-connector-gap': '6px'} as React.CSSProperties}>
<Step step={0} label="One" />
<Step step={1} label="Two" />
</Stepper>,
);
const root = container.querySelector('.astryx-stepper') as HTMLElement;
const frame = container.querySelector(
'.astryx-stepper-frame',
) as HTMLElement;
expect(frame.style.getPropertyValue('--step-connector-gap')).toBe('6px');
expect(declarationsFor(frame)).toContain('--step-connector-gap:0px');
expect(root.style.getPropertyValue('--step-connector-gap')).toBe('');
expect(declarationsFor(root)).toContain('--step-connector-gap:inherit');
});
it('emits a root-owned override through the theme build path', () => {
const theme = defineTheme({
name: 'stepper-connector-gap-test',
components: {
stepper: {
base: {'--step-connector-gap': '6px'},
},
},
});
const {component} = generateThemeCSS(theme);
expect(component).toMatch(
/\.astryx-stepper\s*\{[^}]*--step-connector-gap:\s*6px;/,
);
expect(component).not.toMatch(
/\.astryx-step-connector\s*\{[^}]*--step-connector-gap:/,
);
});
it('stops an outer gap at a layer opened from a step', async () => {
// An outer Stepper's gap is scoped to its own track. A layer opened from
// one of its steps is new content, so an inner Stepper there starts from
// the connector's own 0px fallback (AST-038 FR7) instead of inheriting
// the outer value through the DOM.
function StepLayer() {
const layer = useLayer({mode: 'context'});
return (
<>
<button type="button" ref={layer.ref} onClick={layer.show}>
Details
</button>
{layer.render(
<Stepper activeStep={0} indicatorPosition="on-track">
<Step step={0} label="Inner one" />
<Step step={1} label="Inner two" />
</Stepper>,
)}
</>
);
}
const user = userEvent.setup();
const {container} = render(
<div style={{'--step-connector-gap': '6px'} as React.CSSProperties}>
<Stepper activeStep={0} indicatorPosition="on-track">
<Step step={0} label="Outer one">
<StepLayer />
</Step>
<Step step={1} label="Outer two" />
</Stepper>
</div>,
);
await user.click(screen.getByRole('button', {name: 'Details'}));
const layerRoot = container.querySelector('[popover]') as HTMLElement;
expect(layerRoot).not.toBeNull();
expect(declarationsFor(layerRoot)).toContain(
'--step-connector-gap:initial',
);
// Ancestor inheritance still works outside the layer, and the inner
// Stepper keeps the same inheriting root, so a value set on it or through
// the `stepper` target still reaches its connectors.
const [outerRoot, innerRoot] = [
...container.querySelectorAll<HTMLElement>('.astryx-stepper'),
];
expect(layerRoot.contains(outerRoot)).toBe(false);
expect(layerRoot.contains(innerRoot)).toBe(true);
expect(declarationsFor(innerRoot)).toContain(
'--step-connector-gap:inherit',
);
});
it('leaves the connector target itself free of a segment vocabulary', () => {
// The pieces are an implementation of the on-track layout, not API: no
// `data-segment`, and no bare `lead`/`rail`/`content` class that could
// collide with a consumer's own stylesheet.
const {container} = render(onTrack('vertical'));
const connectors = [
...container.querySelectorAll('.astryx-step-connector'),
];
expect(connectors.length).toBeGreaterThan(0);
for (const node of connectors) {
expect(node.getAttribute('data-segment')).toBeNull();
for (const cls of ['lead', 'rail', 'content']) {
expect(node.classList.contains(cls)).toBe(false);
}
}
});
});
});
describe('step-label and step-description theme targets', () => {
// A step's two text parts each declare their own typography, so a theme
// cannot reach them by styling the step and letting the cascade do the rest
// — an inherited value never beats a value the element declares itself.
// These targets are the seam; the assertions below pin what a theme selects
// and, in the last case, why the cheaper route does not work.
const withText = (props = {}) => (
<Stepper activeStep={1}>
<Step step={0} label="Account" description="Your email" {...props} />
<Step step={1} label="Payment" description="Card details" />
<Step step={2} label="Review" description="Check and submit" />
</Stepper>
);
it('puts the target on the element that paints the text', () => {
const {container} = render(withText());
const label = container.querySelector('.astryx-step-label') as HTMLElement;
const description = container.querySelector(
'.astryx-step-description',
) as HTMLElement;
// The text is the element's own content, not a descendant's: the target
// sits where the paint is rather than on a wrapper around it.
expect(label.textContent).toBe('Account');
expect(description.textContent).toBe('Your email');
});
it('reflects progress and status, the vocabulary step-indicator uses', () => {
// Same shape as the sibling target in this file, so a theme states a
// step's phase identically wherever it reaches in. Without it a theme
// could not say "the label of a completed step": the compiler emits a
// compound selector on one element, never a descendant of `.astryx-step`.
const {container} = render(
<Stepper activeStep={1}>
<Step step={0} label="Done" description="d" />
<Step step={1} label="Now" description="d" />
<Step step={2} label="Later" description="d" status="error" />
</Stepper>,
);
const labels = [
...container.querySelectorAll<HTMLElement>('.astryx-step-label'),
];
expect(labels.map(el => el.dataset.progress)).toEqual([
'completed',
'in-progress',
'not-started',
]);
expect(labels[2].dataset.status).toBe('error');
const descriptions = [
...container.querySelectorAll<HTMLElement>('.astryx-step-description'),
];
expect(descriptions.map(el => el.dataset.progress)).toEqual([
'completed',
'in-progress',
'not-started',
]);
expect(descriptions[2].dataset.status).toBe('error');
});
it('reflects disabled on the label target and emits its theme selector', () => {
// The label owns disabled paint (`styles.labelDisabled`); the description
// does not. The selector follows that ownership instead of being copied to
// every text target for vocabulary symmetry.
const {container} = render(
<Stepper activeStep={0}>
<Step
step={0}
label="Unavailable"
description="Try again later"
isDisabled
/>
</Stepper>,
);
const label = container.querySelector('.astryx-step-label');
const description = container.querySelector('.astryx-step-description');
expect(label).toHaveAttribute('data-disabled', 'disabled');
expect(label).toHaveAttribute('data-disabled', 'disabled');
expect(description).not.toHaveAttribute('data-disabled');
expect(description).not.toHaveAttribute('data-disabled');
// A DOM attribute alone would not prove the public defineTheme path accepts
// and emits the state. Hold both halves of the contract.
const theme = defineTheme({
name: 'step-label-disabled-state-test',
components: {
'step-label': {
'disabled:disabled': {opacity: '0.4'},
},
},
});
const {component: css} = generateThemeCSS(theme);
expect(css).toContain('.astryx-step-label[data-disabled="disabled"]');
expect(css).toContain('opacity: 0.4');
});
it('carries them on the on-track layout too', () => {
// The indicator-on-the-connector layout renders its own label and
// description nodes; a target that only covered the default layout would
// leave a theme reaching for structural selectors in exactly one mode.
const {container} = render(
<Stepper activeStep={0} indicatorPosition="on-track">
<Step step={0} label="Account" description="Your email" />
<Step step={1} label="Payment" description="Card details" />
</Stepper>,
);
expect(container.querySelectorAll('.astryx-step-label')).toHaveLength(2);
expect(container.querySelectorAll('.astryx-step-description')).toHaveLength(
2,
);
});
});
describe('clickable step text reading', () => {
// axe-core's Label in Name rule joins a button's text nodes with nothing
// between them, aria-hidden ones included, so a number badge next to a label
// reads as one word ("1Account") that the step's name does not contain.
// Whitespace between them changes nothing on screen (the rows are flex
// containers) and keeps the two words apart.
it.each([
['vertical', 'separated'],
['horizontal', 'separated'],
['vertical', 'on-track'],
['horizontal', 'on-track'],
] as const)(
'keeps the number and label apart in a %s %s step',
(orientation, indicatorPosition) => {
render(
<Stepper
orientation={orientation}
indicatorPosition={indicatorPosition}
activeStep={0}
label="Steps"
onStepClick={() => {}}>
<Step step={0} label="Account" indicator="number" />
<Step step={1} label="Payment" indicator="number" />
</Stepper>,
);
const button = screen.getByRole('button', {name: /Account/});
expect(button.textContent).toMatch(/1\s+Account/);
expect(button.textContent).not.toMatch(/1Account/);
},
);
});
// jsdom cannot emulate forced colors, so this asserts the compiled rule the
// number badge fill relies on (architecture:theme-tokens INV11).
describe('Step number badge forced colors', () => {
it('keeps a visible boundary on the badge fill', () => {
render(
<Stepper activeStep={0}>
<Step step={0} label="First" indicator="number" />
<Step step={1} label="Second" indicator="number" />
</Stepper>,
);
const css = getForcedColorsRules();
expect(css).toContain('outline-style: solid;');
expect(css).toContain('outline-color: canvastext;');
});
});