Skip to content

feat(stepper): show progress through a fixed sequence of steps - #707

Open
itsprade wants to merge 6 commits into
mainfrom
feat/stepper
Open

itsprade wants to merge 6 commits into
mainfrom
feat/stepper

Conversation

@itsprade

@itsprade itsprade commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

What

A new public component, Stepper. It shows how far something has progressed through a fixed sequence of steps: the steps of a wizard form, the stages of an approval flow, the quality gates of a project. Nothing like it existed in AppShell or ERP Kit; the wizard pattern built its step indicator from Badges.

Refs tailor-inc/platform-planning#2178

<Stepper
  aria-label="New purchase order"
  steps={[
    { id: "supplier", label: "Supplier", status: "complete" },
    { id: "lines", label: "Lines", status: "current" },
    { id: "review", label: "Review", status: "upcoming" },
  ]}
  onStepClick={goTo}
/>

API

  • steps: each step has an id, label, status (complete, current, upcoming or skipped), and an optional badge (beside the label) and description (under it, for hints or planned/actual dates).
  • orientation: horizontal (default) or vertical, for a column beside a form.
  • onStepClick: makes completed steps clickable, for example to go back in a wizard.
  • Typed ids: StepperStep<Id>, so onStepClick receives your own id union.
  • aria-label: defaults to a translated "Progress".
  • Exports: Stepper, StepperProps, StepperStep.

The Stepper only displays progress: the page decides each step's status. The line between steps is filled up to the furthest step reached, meaning the last step that is complete or current.

Narrow containers

A horizontal Stepper adapts to its container, not the viewport.

  • When the steps don't fit side by side, the row scrolls sideways.
  • Below 400px it shows only the markers, with "Step 2 of 4" and the current step's label underneath.
  • In that compact mode each marker shows a tooltip naming its step and status, and a completed step's marker becomes the button that goes back to it. So keyboard users still have one visible place to focus, and nothing focusable is hidden.

Accessibility

  • An ordered list, with aria-current="step" on the current step.
  • Screen readers hear the status of the other steps ("Completed", "Skipped", "Not started").
  • Strings are in English and Japanese.

Docs and demo

  • New component docs, plus a skill rule ("show progress through a fixed sequence of steps with Stepper").
  • The form/wizard pattern now uses Stepper instead of Badges.
  • New demo page at /showcase/stepper: an interactive wizard, quality gates with badges, dates and a skipped step, an approval flow (wide and in a narrow card), and a vertical layout.

Testing

  • 19 Stepper tests cover:
    • structure and status
    • SR text and markers
    • line fill, including skipped steps before and after the furthest step reached
    • badge and description slots
    • the narrow caption, and Japanese strings
    • click targets in wide and compact modes, and the compact tooltip
    • id typing
  • Checked in the browser at desktop and phone widths.
  • All checks pass: tests (3,109), types, lint, format and docs.

Stack

A separate component, released on its own schedule. It targets main and doesn't depend on the forms PRs, and they no longer depend on it: #708 (FormLayout) can merge before or after this one.

The wizard template built from FormLayout and Stepper was taken out of #708. It comes back as a follow-up once both have landed.

🤖 Generated with Claude Code

Add Stepper for wizard steps, approval stages, quality gates and other
fixed sequences. Each step has a status (complete, current, upcoming,
skipped), an optional badge and an optional description, and the line
between steps fills up to the furthest step reached. The current step
gets aria-current="step"; the others announce their status in English
or Japanese.

It lays out horizontally or vertically. A horizontal Stepper scrolls
sideways when its steps don't fit and, below 400px of container width,
shows only its markers with "Step 2 of 4" and the current step's label.
onStepClick makes completed steps clickable.

The Stepper only displays progress; the page decides each step's status.
The example app gets a Stepper showcase page.

Refs tailor-inc/platform-planning#2178

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@github-actions

github-actions Bot commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

Code Metrics Report

main (923933d) #707 (09a2ce1) +/-
Coverage 62.9% 62.9% +0.0%
Test Execution Time 4m3s 4m30s +27s
Details
  |                     | main (923933d) | #707 (09a2ce1) |  +/-  |
  |---------------------|----------------|----------------|-------|
+ | Coverage            |          62.9% |          62.9% | +0.0% |
  |   Files             |            294 |            297 |    +3 |
  |   Lines             |          13483 |          13562 |   +79 |
+ |   Covered           |           8485 |           8535 |   +50 |
- | Test Execution Time |           4m3s |          4m30s |  +27s |

Code coverage of files in pull request scope (8.5% → 9.5%, patch 100.0%)

Files Coverage +/- Patch Coverage Status
packages/core/dist/app-shell.js 8.5% -0.1% - affected
packages/core/src/components/stepper/i18n.ts 100.0% +100.0% 100.0% added
packages/core/src/components/stepper/index.ts 0.0% 0.0% - added
packages/core/src/components/stepper/stepper.tsx 100.0% +100.0% 100.0% added
packages/core/src/index.ts 0.0% 0.0% - modified

Reported by octocov

@itsprade
itsprade marked this pull request as draft November 10, 2026 15:23
@itsprade
itsprade marked this pull request as ready for review November 17, 2026 10:02
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant