feat(core): let Stepper collapse itself in narrow containers

[ernestt]

Summary

A horizontal Stepper had no answer for narrow widths, so every consumer hand-rolled the same fallback: a media query, a ProgressBar, and a line of "Step 2 of 4" text standing in for the component. Four wizard templates carried a version of it, each with its own breakpoint.

The Stepper now measures its own frame and collapses once a step has under ~112px to work with. Labels give way to a bare track, and the current step is named in a row beneath it, flanked by prev/next controls when onStepClick makes them meaningful.

Measuring the frame rather than the viewport means the breakpoint follows the step count, so a stepper collapses on the width it actually has rather than the width of the window around it. Four steps hold out to ~448px; seven need ~784px.

The two indicator positions collapse differently, deliberately. separated gives up its click targets along with its labels, since all that would be left to aim at is a 4px bar — the paired controls become the way through. on-track keeps its indicators as a row of pressable nodes on the rail, which is the better affordance and costs nothing to leave in place.

No child introspection. Steps register with the parent to report the count, and the active step portals its own summary into a slot the Stepper provides. Nothing reads child.props or walks Children.

The sequence stays whole for screen readers at every width — collapsed steps keep visually hidden names, so the ordered list is never silently shortened.

Two fixes the collapse work surfaced, folded in because they only matter here:

• Step labels hold to one line and ellipsize instead of wrapping and breaking mid-word, so a row of steps keeps one height and the track under it stays straight. The full label still reaches the accessible name.
• The gap between connector segments is now --spacing-1, matching the connector's own thickness, so the track reads as one dashed line at any theme scale.

Scope

Core only. The wizard templates that motivated this still carry their hand-rolled fallbacks and are being cleaned up one PR per template. An unrelated LayoutContent padding fix in my working tree is deliberately left out.

Test plan

• 58 Stepper tests pass, including a new block covering the collapse: labels dropping, the summary appearing with the current step's name and description, vertical steppers staying unaffected, the accessible sequence staying whole, controls bounding at both ends, collapsed steps leaving the tab order, and on-track nodes staying pressable.
• pnpm -F @astryxdesign/core typecheck and pnpm -F @astryxdesign/storybook typecheck clean.
• Lint clean on the changed files.
• Verified in a browser at 1280 / 900 / 480 / 380px against a real wizard, driving the flow with both the form's own Continue and the stepper's controls, and confirming an errored step surfaces in the collapsed summary.
• Truncation measured live: every label reports one line, with clipping starting exactly when its slice gets too narrow.
• Gap measured live at 4px.
• Reviewer: the new Narrow — Collapsed Track story exercises all four cases side by side.

Known gap, not addressed here

status never recolors the connector — progress is the bar's channel, status is the indicator's. That holds when every step shows an indicator, but collapsing removes indicators for every step except the current one, so an error on a step you have navigated away from is invisible while collapsed. In the labelled layout that step keeps its glyph. Worth a follow-up; I did not want to quietly break the channel separation to paper over it.

Made with Cursor

Screenshots

Separated, wide — unchanged. Four labelled steps, icons as indicators.

Separated, 380px — collapsed. Labels and click targets gone, four bars left, the current step named underneath between two flat controls. Previous is disabled on step 1.

Separated, 380px — error on the current step. The summary carries the error glyph; Previous is now live.

On-track, wide.

On-track, 380px — collapsed differently, on purpose. The numbered nodes stay on the rail and stay pressable; all four remain hit-targets. Only the labels go.

Label truncation. Captured with deliberately long labels. Each holds one line and ellipsizes, so the row keeps one height and the track stays straight; short labels are untouched.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
astryx	Ready	Preview	Aug 28, 2026 6:20pm

[github-actions]

PR Analysis Report

📚 Storybook Preview

View Storybook for this PR
GitHub Pages may take up to a minute to hydrate after deploy.

🧪 Sandbox Preview

View Sandbox for this PR
GitHub Pages may take up to a minute to hydrate after deploy.

Modified Components

Stepper _{(@astryxdesign/core)} · View in Storybook

Metric	Before	After	Delta
Bundle Size (ESM)	N/A	N/A	N/A
Lines of Code	N/A	1437	-
Complexity	N/A	Very High (155)	-

Bundle Size Summary

Package	Size (ESM)	Size (CJS)	Gzipped
@astryxdesign/core	N/A	4.8KB	1.2KB

Accessibility Audit

Status: 1 accessibility violation(s) found — 1 serious.

Stepper - 1 issue(s)

• 🟠 serious: Ensure the contrast between foreground and background colors meets WCAG 2 AA minimum contrast ratio thresholds
  • Rule: color-contrast · Affects 1/29 stories · Learn more
  • WCAG: 1.4.3 (Level AA)

Visual Regression

2 of 406 shot(s) changed. View the report

To accept these exact frames: /accept-visual 33198611074/1 <reason>

A change here is a question, not a failure: check whether the after is the
picture you intended. If it is, say so in the PR — the release gate's baseline
is updated deliberately, and this check never rewrites it.

component	story	theme	mode	pixels
Stepper	Default	neutral	light	5,451
Stepper	Default	neutral	dark	5,325

Stepper — Default — neutral light

Before	After	Diff

Stepper — Default — neutral dark

Before	After	Diff

---

_{Generated by PR Enrichment workflow | Storybook | Sandbox | View full report}

[xinzi-bot]

What this change fixes at narrow widths

I rendered the same 320px fixture on current main (88fde9103f) and this PR (21ba26155e). Each image contains the same three horizontal Stepper scenarios with the same active step and labels.

Before — main	After — this PR

Scenario-by-scenario

1. Separated · navigable

   • Before: all four labels and their click targets compete for roughly 80px each, so labels wrap and the row grows.
   • After: the Stepper becomes a bare segmented track. Only the active step is named below it, with Previous/Next controls as usable narrow-width targets.

2. On-track · navigable

   • Before: the numbered rail and all four labels remain visible in the same narrow space.
   • After: the labels collapse, but the numbered nodes stay visible and directly pressable; the active step is also named below the rail.

3. Separated · form-driven

   • Before: every step's label and description remains in the narrow row, while the form's Back/Continue controls sit below it.
   • After: only the active step's label and description are shown. The Stepper does not add its own navigation controls because there is no onStepClick; the form's existing Back/Continue buttons remain the sole controls.

This is the core value of the PR: consumers no longer need to replace a crowded horizontal Stepper with their own media-query + progress-bar fallback. The component adapts based on its actual container width and step count.

[ernestt]

/accept-visual 33198611074/1 4px segments the individual steps more clearly instead of one continuous line

[github-actions]

Visual acceptance could not be recorded. See this workflow run for the rejected invariant or infrastructure error.

[xinzi-bot]

Changes suggested (non-maintainer review)

The responsive collapse is the right idea, and the horizontal single-line improvement works. In a measured fixture, the uneven [42, 62, 42, 42] step heights become a uniform [42, 42, 42, 42].

@xinzi-bot is not a maintainer, so this is advisory and does not change the PR's review state. I found four newly introduced regressions that are worth addressing before landing:

1. Vertical labels now overflow. The new whiteSpace: 'nowrap' applies to vertical Steppers too, but verticalBody lacks minWidth: 0, so the ellipsis cannot engage. At 150px, “Shipping address” previously wrapped and fit; it now extends beyond the container. otBodyV already has the needed floor release. (code)

2. Compact controls can navigate onto a disabled step. With four steps and step 2 disabled, Next at 320px calls onStepClick(2) and moves aria-current there. At full width, that same step correctly has no button. (code)

3. Compact mode unmounts Step.children. The conditional around contentNode drops the public content slot, not just the label. A form input disappears from the DOM at the compact threshold, and resizing destroys its state and focus. (code)

4. The measured box is not the styled box. style, xstyle, className, and ref remain on the <ol>, while the new frame is measured. A Stepper constrained to 300px inside a 1000px parent therefore measures 1000px and does not collapse. It would be better to settle the outer-element contract now, following the existing TabList pattern. (code)

Non-blocking follow-ups: long summary labels can overlap the chevron; endContent/“Optional” are absent from the compact accessibility tree; an out-of-range activeStep leaves an empty summary; compact touch targets are 32px; focus is lost across the threshold; and the responsive behavior needs documentation.

The feature does not need redesigning, but these four cases warrant another revision before acceptance.

[xinzi-bot]

Automated review found three compact-mode contract regressions: resizing unmounts Step content and can lose state or focus; compact controls can select disabled steps; and responsive measurement reads a wrapper instead of the public styled root. Preserving content/state, disabled semantics, and root sizing would keep existing contracts.

[Automated review]