Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 17 additions & 0 deletions .changeset/stepper-component.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
---
"@tailor-platform/app-shell": minor
---

Add `Stepper` for showing progress through a fixed sequence of steps: the steps of a wizard form, the stages of an approval flow, the quality gates of a project. Each step has a `status` (`complete`, `current`, `upcoming` or `skipped`), an optional `badge` beside its label and an optional `description` under it, and the line between steps fills up to the furthest step reached. 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, and each marker names its step in a tooltip. `onStepClick` makes completed steps clickable, and step ids are typed so `onStepClick` receives your own id union.

```tsx
<Stepper
aria-label="New purchase order"
steps={[
{ id: "supplier", label: "Supplier", status: "complete" },
{ id: "delivery", label: "Delivery", status: "current" },
{ id: "review", label: "Review", status: "upcoming" },
]}
onStepClick={goToStep}
/>
```
28 changes: 23 additions & 5 deletions docs-manifest.json
Original file line number Diff line number Diff line change
Expand Up @@ -824,10 +824,10 @@
"symbols": [],
"hashes": {
"typeSurface": null,
"outline": "fbc09ef9994494cb",
"outline": "6f44fa0ce14bc031",
"snapshot": null,
"outputMd": "851afb4672da6673",
"examples": "157ff03dc999d3d3"
"outputMd": "e86dd12f9aaa196f",
"examples": "f0c771090062761d"
}
},
"global-header-layout": {
Expand Down Expand Up @@ -1374,6 +1374,23 @@
"examples": "2782e1f9f3822dfe"
}
},
"stepper": {
"slug": "stepper",
"kind": "code-backed",
"outline": "docs-src/components/stepper.docs.outline.md",
"output": "docs/components/stepper.md",
"examples": "docs-src/components/stepper.docs.examples.tsx",
"sources": ["packages/core/src/components/stepper/**"],
"claims": [],
"symbols": ["Stepper", "StepperProps", "StepperStep"],
"hashes": {
"typeSurface": "03575b3ae95ff031",
"outline": "620afc4168680aa7",
"snapshot": "62a67309416ceed7",
"outputMd": "dfd07cfec2f84d5b",
"examples": "9a0f9bf7c9b8fb95"
}
},
"styling-theming": {
"slug": "styling-theming",
"kind": "prose",
Expand Down Expand Up @@ -1863,6 +1880,7 @@
"packages/core/skills/app-shell-patterns/references/components/sidebar-layout.md": "af971809e42dfdb8",
"packages/core/skills/app-shell-patterns/references/components/sidebar-section.md": "281cfa2dcbff14be",
"packages/core/skills/app-shell-patterns/references/components/spinner.md": "eec440408611a233",
"packages/core/skills/app-shell-patterns/references/components/stepper.md": "dfd07cfec2f84d5b",
"packages/core/skills/app-shell-patterns/references/components/table.md": "c5933b640a78c3bf",
"packages/core/skills/app-shell-patterns/references/components/tabs.md": "a94b016f0c9709b7",
"packages/core/skills/app-shell-patterns/references/components/text.md": "e5311b1891f3ff7b",
Expand Down Expand Up @@ -1902,14 +1920,14 @@
"packages/core/skills/app-shell-patterns/references/patterns/form-modal.md": "a0d3c952b0b10351",
"packages/core/skills/app-shell-patterns/references/patterns/form-sectioned.md": "d31cd3ae6ad0790c",
"packages/core/skills/app-shell-patterns/references/patterns/form-single-page.md": "10a0f4d91a120752",
"packages/core/skills/app-shell-patterns/references/patterns/form-wizard.md": "851afb4672da6673",
"packages/core/skills/app-shell-patterns/references/patterns/form-wizard.md": "e86dd12f9aaa196f",
"packages/core/skills/app-shell-patterns/references/patterns/i18n-labels.md": "d9f0851d9c98ecfe",
"packages/core/skills/app-shell-patterns/references/patterns/interaction-confirm.md": "2db70f423c6fdf97",
"packages/core/skills/app-shell-patterns/references/patterns/interaction-multi-select.md": "253fcea1c4e5a42c",
"packages/core/skills/app-shell-patterns/references/patterns/interaction-toast.md": "f68bdab855730f48",
"packages/core/skills/app-shell-patterns/references/pages/document-collection.md": "e79d9120d86db198",
"packages/core/skills/app-shell-patterns/references/pages/document-detail.md": "e07c7fee2478a21d",
"packages/core/skills/app-shell-patterns/SKILL.md": "18efee79280174e7",
"packages/core/skills/app-shell-patterns/SKILL.md": "1594f44402a51278",
"packages/core/skills/app-shell-upgrade/references/migrations.md": "9bd2735c34fd35e3",
"packages/core/skills/app-shell-upgrade/SKILL.md": "f9be942f3e596c00"
}
Expand Down
51 changes: 51 additions & 0 deletions docs-src/components/stepper.docs.examples.tsx
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
import { Badge, Stepper } from "@tailor-platform/app-shell";

export function BasicUsage() {
return (
<Stepper
aria-label="New purchase order"
steps={[
{ id: "supplier", label: "Supplier", status: "complete" },
{ id: "delivery", label: "Delivery", status: "current" },
{ id: "approval", label: "Approval", status: "upcoming" },
{ id: "review", label: "Review", status: "upcoming" },
]}
/>
);
}

export function StageProgress() {
return (
<Stepper
aria-label="Quality gates"
steps={[
{ id: "qg1", label: "QG1", status: "complete", description: "Done 11 Aug" },
{ id: "qg2", label: "QG2", status: "complete", description: "Done 6 Sep" },
{ id: "qg3", label: "QG3", status: "skipped", description: "Not required" },
{
id: "qg4",
label: "QG4",
status: "current",
badge: <Badge variant="outline-info">Next</Badge>,
description: "Plan 18 Nov",
},
{ id: "qg5", label: "QG5", status: "upcoming", description: "Plan 9 Dec" },
]}
/>
);
}

export function Vertical() {
return (
<Stepper
aria-label="Approval"
orientation="vertical"
steps={[
{ id: "draft", label: "Draft", status: "complete", description: "Hanna Suzuki" },
{ id: "manager", label: "Manager", status: "complete", description: "Kenji Mori · 3 Nov" },
{ id: "finance", label: "Finance", status: "current", description: "Priya Nair" },
{ id: "issued", label: "Issued", status: "upcoming" },
]}
/>
);
}
89 changes: 89 additions & 0 deletions docs-src/components/stepper.docs.outline.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,89 @@
---
kind: code-backed
group: stepper
title: Stepper
description: Shows progress through a fixed sequence of steps — wizard steps, approval stages, quality gates
sources:
- packages/core/src/components/stepper/**
---

# Stepper

`Stepper` shows how far something has progressed through a fixed sequence of steps: the steps of a [wizard form](../patterns/form-wizard.md), the stages of an approval flow, the quality gates of a project. Each step has a status, and the line between steps is filled up to the furthest step reached.

It only displays progress. The page decides each step's status and what happens when a step is clicked.

## Import

```tsx
import { Stepper } from "@tailor-platform/app-shell";
```

## Basic Usage

<!-- example: basic-usage -->

## Props

| Prop | Type | Default | Description |
| ------------- | ---------------------------- | -------------- | ---------------------------------------------------------------------------------- |
| `steps` | `StepperStep[]` | - | The steps, in order |
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | A row of steps, or a column for beside a form |
| `onStepClick` | `(id: Id) => void` | - | Makes completed steps clickable — for example to go back to an earlier wizard step |
| `aria-label` | `string` | "Progress" | Accessible name for the list of steps (the default is translated) |
| `className` | `string` | - | Additional CSS classes |
| `style` | `CSSProperties` | - | Inline styles |

### `StepperStep`

| Field | Type | Description |
| ------------- | ---------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| `id` | `Id extends string` | Stable id, passed to `onStepClick` |
| `label` | `ReactNode` | Step name |
| `status` | `"complete" \| "current" \| "upcoming" \| "skipped"` | Where the step stands (below) |
| `badge` | `ReactNode` | Shown beside the label — for example a "Next" or "Overdue" `Badge` |
| `description` | `ReactNode` | Shown under the label — a short hint, or a few lines of values such as plan and actual dates |

## Status

| `status` | Marker | Use for |
| ------------ | ------------------------------ | -------------------------------------------- |
| `"complete"` | Filled, with a check | Steps that are done |
| `"current"` | Outlined in the primary colour | The step the user is on, or the next one due |
| `"upcoming"` | Outlined, muted | Steps not started |
| `"skipped"` | Dashed outline, muted | Steps that don't apply to this record |

Mark at most one step `current`. It gets `aria-current="step"`, and screen readers hear the status of the others ("Completed", "Skipped", "Not started").

The line is filled up to the furthest step reached — the last step that is `complete` or `current`. A skipped step before it is filled through; one after it isn't.

Step ids are typed: give `steps` a union of ids and `onStepClick` receives that union.

```tsx
type StepId = "supplier" | "lines" | "review";
const steps: StepperStep<StepId>[] = [
/* … */
];

<Stepper steps={steps} onStepClick={(id) => goTo(id)} />; // id: StepId
```

## Stage progress

Badges and descriptions turn the Stepper into a stage tracker on a detail page:

<!-- example: stage-progress -->

## Vertical

A vertical Stepper suits a column beside a form, such as a wizard on a page:

<!-- example: vertical -->

## Narrow containers

A horizontal Stepper adapts to the width of its container, not the viewport:

- When the steps don't fit side by side, the row scrolls sideways rather than squeezing the labels.
- Below 400px it shows only the markers and lines, with "Step 2 of 4" and the current step's label underneath. This is what a wizard needs in a dialog on a phone.
- Each marker then names its step in a tooltip on hover, and the marker of a completed step becomes the button that goes back to it, so keyboard users still have one visible place to focus.
26 changes: 11 additions & 15 deletions docs-src/patterns/form-wizard.docs.examples.tsx
Original file line number Diff line number Diff line change
@@ -1,13 +1,13 @@
import { useState } from "react";
import {
Badge,
Button,
Card,
Field,
Fieldset,
Form,
Layout,
Select,
Stepper,
} from "@tailor-platform/app-shell";

const OWNERS = ["Tanaka", "Sato", "Suzuki", "Yamada"];
Expand Down Expand Up @@ -60,20 +60,16 @@ export function FormWizard() {
<Layout>
<Layout.Header title="Create task" />
<Layout.Column>
<Card.Root>
<Card.Content>
<div className="flex items-center gap-2">
{STEPS.map((label, i) => (
<Badge
key={label}
variant={i === step ? "default" : i < step ? "success" : "neutral"}
>
{i + 1}. {label}
</Badge>
))}
</div>
</Card.Content>
</Card.Root>
{/* Statuses come from the current step; completed steps go back on click */}
<Stepper
aria-label="Create task"
steps={STEPS.map((label, i) => ({
id: String(i),
label,
status: i < step ? "complete" : i === step ? "current" : "upcoming",
}))}
onStepClick={(id) => setStep(Number(id))}
/>

<Form key={step} noValidate onFormSubmit={handleStepSubmit}>
<Card.Root>
Expand Down
4 changes: 2 additions & 2 deletions docs-src/patterns/form-wizard.docs.outline.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ title: Wizard Form
category: pattern
subcategory: form
description: Multi-stage create flow with 3-7 steps and per-step validation gates
requiredImports: [Layout, Card, Badge, Form, Fieldset, Field, Select, Button]
requiredImports: [Layout, Card, Stepper, Form, Fieldset, Field, Select, Button]
tags: [form, wizard, multi-step, stepper, onboarding]
do:
- Multi-stage Create with 3-7 steps
Expand Down Expand Up @@ -41,7 +41,7 @@ the upload → map → validate → confirm flow. Don't rebuild it here.
- Max 7 steps — more than that causes user abandonment
- Back-navigation must preserve prior step's input
- Validation must be per-step — don't defer until final submit
- Step indicator collapses to "Step 2 of 4" label below 1024px
- Show the steps with `Stepper`; it collapses to "Step 2 of 4" when its container is narrower than 400px
- One `<Form>` rendered per step, keyed by step index so it remounts cleanly
- Accumulated values live in a `draft` state object above the `Form`; each step's fields read
their initial value from it via `defaultValue`
Expand Down
1 change: 1 addition & 0 deletions docs-src/skill/app-shell-patterns/SKILL.template.md
Original file line number Diff line number Diff line change
Expand Up @@ -79,5 +79,6 @@ Full rationale in [`styling-theming`](references/concepts/styling-theming.md)
- **Metric tiles always go in a `Grid`** (`columns={{ initial: 1, md: 2, xl: 4 }}`) — never one-per-row.
- **Creating or editing a document is a routed full-page form** (`form/single-page`, `form/sectioned`, or `form/wizard`). Documents carry line items and several field groups, and a dialog has nowhere to put them. `form/modal` is for sub-elements and small entities instead — a product's variants, a user's or warehouse location's properties, an item's BOM rules — where the whole form is a handful of fields.
- **Forms use AppShell `Form` + `Field`**, submitting via `onFormSubmit` — never a bare `<form onSubmit>` with `FormData`. `onFormSubmit` reads registered `Field.Root`s, so every control (dropdowns included) just needs a wrapping `Field.Root name="…"` — no `name` on the control, no `useState`. React Hook Form is optional, consumer-installed, and only warranted for cross-field validation, field arrays, or a Zod resolver. Details in [`Form`](references/components/form.md) and the `form/*` patterns.
- **Show progress through a fixed sequence of steps with `Stepper`** — wizard steps, approval stages, quality gates — not Badges or hand-built dots. Give each step a `status` (`complete`, `current`, `upcoming`, `skipped`) derived from your own state; it collapses to "Step 2 of 4" in narrow containers by itself. Details in [`Stepper`](references/components/stepper.md).
- **Handle every state:** loading (skeleton), empty (labelled empty state), and error (inline + retry) — never ship only the happy path.
- **Keep UI language consistent:** apply the chosen language to navigation, component text, accessibility labels, and feedback. Use the catalog's `useT()` for rendered strings and `labels.t()` for `LocalizedString` metadata; keep server codes and comparison values untranslated. See [`i18n/labels`](references/patterns/i18n-labels.md).
Loading
Loading