Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

feat(core): promote Stepper from Lab (#5201)

Ernestecaf7796bd2b
diff --git a/.changeset/promote-stepper-to-core.md b/.changeset/promote-stepper-to-core.md
new file mode 100644
index 0000000000..d6f3ae8d96
--- /dev/null
+++ b/.changeset/promote-stepper-to-core.md
@@ -0,0 +1,12 @@
+---
+'@astryxdesign/cli': patch
+'@astryxdesign/core': patch
+---
+
+[component] Promote `Stepper` and `Step` from the canary-only Lab package to Core. The stable package now ships their existing horizontal/vertical layouts, separated and on-track indicators, semantic status, density, and non-linear navigation, plus Core documentation and rendered examples. The default `aria-label` is now localized.
+
+Advancing one step now animates the connector. Every connector the four layouts draw — the separated bars and the on-track segments alike — grows its accent fill out of the segment's leading edge instead of swapping a background color, so moving forward reads as progress travelling the track. That one gesture is the only thing that animates: going back, jumping forward by more than one step, and mounting mid-flow all apply at once, as does any change under `prefers-reduced-motion`. Retreats are deliberately instant — run in reverse the same transition ends on a shrinking stub of accent, and a remnant still on the track reads as unfinished where the identical curve growing forward reads as arrived — and multi-step jumps are instant because a jump is a navigation rather than a progression, so sweeping a front across the crossed segments only makes the user sit out a journey they asked to skip. Where one span is drawn by several segments (the on-track layouts split a span between two steps, three when a content slot sits between them) the segments take abutting slices of the span's time and run linearly, so the fill reads as one line growing at a constant speed rather than pieces lighting in turn.
+
+Five visual fixes land with the promotion. Horizontal steps now divide the track evenly instead of sizing to their own labels, so every progress segment is the same width regardless of how long a step is named. Number indicators shrink from 20px to 16px to match the check, ring, and custom-icon indicators, so a step swapping its number for a check as it completes no longer nudges the label beside it. A step description now occupies a 16px box rather than a 24px one — it previously inherited the page's line box instead of applying its own leading, which opened an 8px gap under the label. A step's content slot now starts flush with the label above it at every density: the slot renders outside the density-padded label area, so it was hanging one pad short of it. And a vertical on-track step carrying content keeps its connector unbroken — the content renders below the row that draws the line, so the track used to split open around any step with content.
+
+@ernestt
diff --git a/apps/storybook/stories/Stepper.stories.tsx b/apps/storybook/stories/Stepper.stories.tsx
index 3c41becff0..48165f8b49 100644
--- a/apps/storybook/stories/Stepper.stories.tsx
+++ b/apps/storybook/stories/Stepper.stories.tsx
@@ -3,7 +3,7 @@
import {useState} from 'react';
import * as stylex from '@stylexjs/stylex';
import type {Meta, StoryObj} from '@storybook/react';
-import {Stepper, Step} from '@astryxdesign/lab/Stepper';
+import {Stepper, Step} from '@astryxdesign/core/Stepper';
import {TextInput} from '@astryxdesign/core/TextInput';
import {Button} from '@astryxdesign/core/Button';
import {Text} from '@astryxdesign/core/Text';
@@ -11,7 +11,7 @@ import {Icon} from '@astryxdesign/core/Icon';
import {Badge} from '@astryxdesign/core/Badge';
const meta: Meta<typeof Stepper> = {
- title: 'Lab/Stepper',
+ title: 'Core/Stepper',
component: Stepper,
tags: ['autodocs'],
argTypes: {
@@ -366,7 +366,7 @@ export const IndicatorComparison: Story = {
</Stepper>
</div>
<div style={{maxWidth: 280}}>
- <Text type="label">Custom icon</Text>
+ <Text type="label">Custom indicator</Text>
<Stepper
activeStep={active}
orientation="vertical"
@@ -374,27 +374,27 @@ export const IndicatorComparison: Story = {
<Step
step={0}
label="Account"
- icon={<Icon icon="info" size="sm" />}
+ indicator={<Icon icon="info" size="sm" />}
/>
<Step
step={1}
label="Profile"
- icon={<Icon icon="search" size="sm" />}
+ indicator={<Icon icon="search" size="sm" />}
/>
<Step
step={2}
label="Settings"
- icon={<Icon icon="wrench" size="sm" />}
+ indicator={<Icon icon="wrench" size="sm" />}
/>
<Step
step={3}
label="Review"
- icon={<Icon icon="clock" size="sm" />}
+ indicator={<Icon icon="clock" size="sm" />}
/>
<Step
step={4}
label="Done"
- icon={<Icon icon="check" size="sm" />}
+ indicator={<Icon icon="check" size="sm" />}
/>
</Stepper>
</div>
@@ -506,6 +506,42 @@ export const WithContentSlot: Story = {
},
};
+export const ContentSlotAlignment: Story = {
+ name: 'With Content — Alignment',
+ render: () => (
+ // The content slot renders outside the density-padded hover target, so it
+ // has to re-apply that padding to line up with the label above it. Spacious
+ // density is the widest pad, and on-track uses a different scale to
+ // separated, so between them these two catch a slot that has drifted.
+ <div style={{display: 'flex', gap: 48, flexWrap: 'wrap'}}>
+ {(['separated', 'on-track'] as const).map(position => (
+ <div key={position} style={{width: 320}}>
+ <Text type="label">{position}, spacious</Text>
+ <Stepper
+ activeStep={1}
+ orientation="vertical"
+ indicatorPosition={position}
+ density="spacious">
+ <Step step={0} label="Contact details" />
+ <Step
+ step={1}
+ label="Billing address"
+ description="Used for invoices and tax">
+ <div style={{display: 'flex', flexDirection: 'column', gap: 12}}>
+ <TextInput label="Street" placeholder="1 Hacker Way" value="" />
+ <div>
+ <Button label="Save address" variant="primary" />
+ </div>
+ </div>
+ </Step>
+ <Step step={2} label="Review" />
+ </Stepper>
+ </div>
+ ))}
+ </div>
+ ),
+};
+
// ============================================================
// DENSITY
// ============================================================
@@ -991,62 +1027,86 @@ export const CustomXStyle: Story = {
},
};
-export const CollapseLabelsWhenNarrow: Story = {
- name: 'Responsive — Collapse Labels When Narrow',
+// ============================================================
+// CONNECTOR FILL MOTION
+// ============================================================
+
+export const StepAdvance: Story = {
+ name: 'Motion — Step Advance',
render: () => {
- const [active, setActive] = useState(2);
+ // One change animates the connector: advancing a single step. Clicking the
+ // next number along grows the fill across the span it just covered;
+ // clicking anything else — further ahead, or back — lands at once. Both
+ // halves of the rule are worth seeing next to each other, which is what
+ // this story is for. All four layouts share one activeStep so the same
+ // change can be compared across them, and the buttons reach further than
+ // clicking the steps themselves makes convenient.
+ const [active, setActive] = useState(0);
+ const labels = ['Cart', 'Shipping', 'Payment', 'Review', 'Confirm'];
+ // A vertical on-track step carrying content draws a third segment down the
+ // side of the slot, so the span leaving it is stitched from three pieces
+ // rather than two — the case most likely to show a seam.
+ const stepsFor = (withContent: boolean) => (
+ <>
+ {labels.map((label, i) => (
+ <Step key={label} step={i} label={label} indicator="number">
+ {withContent && i === 2 ? (
+ <Text type="body">Applied at checkout.</Text>
+ ) : null}
+ </Step>
+ ))}
+ </>
+ );
return (
<div style={{display: 'flex', flexDirection: 'column', gap: 32}}>
- <div>
- <Text type="label">Wide (labels shown)</Text>
- <div style={{width: 640}}>
- <Stepper
- activeStep={active}
- orientation="horizontal"
- hasCollapsibleLabels
- onStepClick={setActive}>
- <Step step={0} label="Cart" indicator="number" />
- <Step step={1} label="Shipping" indicator="number" />
- <Step step={2} label="Payment" indicator="number" />
- <Step step={3} label="Review" indicator="number" />
- <Step step={4} label="Confirm" indicator="number" />
- </Stepper>
+ <div style={{display: 'flex', flexDirection: 'column', gap: 8}}>
+ <div style={{display: 'flex', gap: 8, alignItems: 'center'}}>
+ <Text type="label">Jump to</Text>
+ {labels.map((label, i) => (
+ <Button
+ key={label}
+ label={`${i}`}
+ variant={i === active ? 'primary' : 'secondary'}
+ onClick={() => setActive(i)}
+ />
+ ))}
</div>
- </div>
- <div>
- <Text type="label">
- Narrow (only the current step keeps its label)
+ <Text type="body">
+ Advancing one step animates the fill. Jumping further ahead, and
+ every move backwards, lands at once.
</Text>
- <div style={{width: 360}}>
- <Stepper
- activeStep={active}
- orientation="horizontal"
- hasCollapsibleLabels
- onStepClick={setActive}>
- <Step step={0} label="Cart" indicator="number" />
- <Step step={1} label="Shipping" indicator="number" />
- <Step step={2} label="Payment" indicator="number" />
- <Step step={3} label="Review" indicator="number" />
- <Step step={4} label="Confirm" indicator="number" />
- </Stepper>
- </div>
</div>
- <div>
- <Text type="label">Narrow, on-track</Text>
- <div style={{width: 320}}>
- <Stepper
- activeStep={active}
- orientation="horizontal"
- indicatorPosition="on-track"
- hasCollapsibleLabels
- onStepClick={setActive}>
- <Step step={0} label="Cart" indicator="number" />
- <Step step={1} label="Shipping" indicator="number" />
- <Step step={2} label="Payment" indicator="number" />
- <Step step={3} label="Review" indicator="number" />
- <Step step={4} label="Confirm" indicator="number" />
- </Stepper>
- </div>
+ <div style={{display: 'flex', gap: 48, flexWrap: 'wrap'}}>
+ {(['separated', 'on-track'] as const).map(position => (
+ <div
+ key={position}
+ style={{display: 'flex', flexDirection: 'column', gap: 24}}>
+ <div style={{width: 460}}>
+ <Text type="label">{position}, horizontal</Text>
+ <Stepper
+ activeStep={active}
+ orientation="horizontal"
+ indicatorPosition={position}
+ onStepClick={setActive}
+ data-testid={`h-${position}`}>
+ {stepsFor(false)}
+ </Stepper>
+ </div>
+ <div style={{width: 460}}>
+ <Text type="label">
+ {position}, vertical (step 3 has content)
+ </Text>
+ <Stepper
+ activeStep={active}
+ orientation="vertical"
+ indicatorPosition={position}
+ onStepClick={setActive}
+ data-testid={`v-${position}`}>
+ {stepsFor(true)}
+ </Stepper>
+ </div>
+ </div>
+ ))}
</div>
</div>
);
diff --git a/packages/cli/assets/templates/blocks/components/Step/StepContent.doc.mjs b/packages/cli/assets/templates/blocks/components/Step/StepContent.doc.mjs
new file mode 100644
index 0000000000..363b0434e8
--- /dev/null
+++ b/packages/cli/assets/templates/blocks/components/Step/StepContent.doc.mjs
@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ exampleFor: 'Step',
+ name: 'Step — Content Slot',
+ displayName: 'Step — Content Slot',
+ description:
+ 'Children passed to a Step render below its description, indented to line up with the label rather than the indicator, and stay outside the clickable label area so buttons inside remain their own targets. In a full flow you gate the slot on the step being active — that is what turns a vertical stepper into an expanding one.',
+ isReady: true,
+ aspectRatio: 4 / 3,
+ componentsUsed: ['Stepper', 'Step', 'TextInput', 'Button'],
+};
diff --git a/packages/cli/assets/templates/blocks/components/Step/StepContent.tsx b/packages/cli/assets/templates/blocks/components/Step/StepContent.tsx
new file mode 100644
index 0000000000..c5d14f5e09
--- /dev/null
+++ b/packages/cli/assets/templates/blocks/components/Step/StepContent.tsx
@@ -0,0 +1,32 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {Stepper, Step} from '@astryxdesign/core/Stepper';
+import {TextInput} from '@astryxdesign/core/TextInput';
+import {Button} from '@astryxdesign/core/Button';
+
+export default function StepContent() {
+ // Anything passed as children renders below the description, indented to line
+ // up with the label rather than the indicator. In a full flow you would gate
+ // this on the step being active; here it is a single Step so the slot is
+ // always shown.
+ return (
+ <div style={{width: 400}}>
+ <Stepper activeStep={1} orientation="vertical">
+ <Step
+ step={1}
+ label="Billing address"
+ description="Used for invoices and tax calculation">
+ <div style={{display: 'flex', flexDirection: 'column', gap: 12}}>
+ <TextInput label="Street" placeholder="1 Hacker Way" value="" />
+ <TextInput label="City" placeholder="Menlo Park" value="" />
+ <div>
+ <Button label="Save address" variant="primary" />
+ </div>
+ </div>
+ </Step>
+ </Stepper>
+ </div>
+ );
+}
diff --git a/packages/cli/assets/templates/blocks/components/Step/StepIndicator.doc.mjs b/packages/cli/assets/templates/blocks/components/Step/StepIndicator.doc.mjs
new file mode 100644
index 0000000000..f970078d1b
--- /dev/null
+++ b/packages/cli/assets/templates/blocks/components/Step/StepIndicator.doc.mjs
@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ exampleFor: 'Step',
+ name: 'Step — Indicator',
+ displayName: 'Step — Indicator',
+ description:
+ 'Everything the indicator prop accepts: the auto default, an always-number badge, a custom ReactNode, and none — each on its own completed Step so the prop is the only difference between them. Every variant occupies the same 16px box, so a step swapping its number for a check as it completes never shifts the label beside it. The last cell shows that a custom node can be live rather than static: a Spinner on a step that is in progress, shaded `inherit` so it picks up the step\u2019s own tint like any other glyph.',
+ isReady: true,
+ aspectRatio: 4 / 3,
+ componentsUsed: ['Stepper', 'Step', 'Icon', 'Spinner', 'Text'],
+};
diff --git a/packages/cli/assets/templates/blocks/components/Step/StepIndicator.tsx b/packages/cli/assets/templates/blocks/components/Step/StepIndicator.tsx
new file mode 100644
index 0000000000..5603eff986
--- /dev/null
+++ b/packages/cli/assets/templates/blocks/components/Step/StepIndicator.tsx
@@ -0,0 +1,60 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {Stepper, Step} from '@astryxdesign/core/Stepper';
+import {Text} from '@astryxdesign/core/Text';
+import {Icon} from '@astryxdesign/core/Icon';
+import {Spinner} from '@astryxdesign/core/Spinner';
+
+export default function StepIndicator() {
+ // The first four steps are all completed — same progress, so the indicator
+ // prop is the only difference between them. `auto` is the one that reacts to
+ // progress: a numbered badge until the step is reached, then a check. The
+ // last step is in progress instead, because the node it passes to `indicator`
+ // is a spinner and a spinner only makes sense on work that is running.
+ return (
+ <div style={{display: 'flex', flexWrap: 'wrap', gap: 24}}>
+ <div style={{width: 190}}>
+ <Text type="label">auto (default)</Text>
+ <Stepper activeStep={1} orientation="vertical">
+ <Step step={0} label="Verify email" />
+ </Stepper>
+ </div>
+ <div style={{width: 190}}>
+ <Text type="label">number</Text>
+ <Stepper activeStep={1} orientation="vertical">
+ <Step step={0} label="Verify email" indicator="number" />
+ </Stepper>
+ </div>
+ <div style={{width: 190}}>
+ <Text type="label">Custom node</Text>
+ <Stepper activeStep={1} orientation="vertical">
+ <Step
+ step={0}
+ label="Verify email"
+ indicator={<Icon icon="wrench" size="sm" />}
+ />
+ </Stepper>
+ </div>
+ <div style={{width: 190}}>
+ <Text type="label">none</Text>
+ <Stepper activeStep={1} orientation="vertical">
+ <Step step={0} label="Verify email" indicator="none" />
+ </Stepper>
+ </div>
+ <div style={{width: 190}}>
+ <Text type="label">Spinner (in progress)</Text>
+ <Stepper activeStep={0} orientation="vertical">
+ <Step
+ step={0}
+ label="Verify email"
+ // `inherit` picks up the indicator's own tint, so the spinner is
+ // colored by the step's progress and status like any other glyph.
+ indicator={<Spinner size="md" shade="inherit" />}
+ />
+ </Stepper>
+ </div>
+ </div>
+ );
+}
diff --git a/packages/cli/assets/templates/blocks/components/Step/StepShowcase.doc.mjs b/packages/cli/assets/templates/blocks/components/Step/StepShowcase.doc.mjs
new file mode 100644
index 0000000000..c618abeef0
--- /dev/null
+++ b/packages/cli/assets/templates/blocks/components/Step/StepShowcase.doc.mjs
@@ -0,0 +1,15 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ exampleFor: 'Step',
+ name: 'Step',
+ displayName: 'Step',
+ description:
+ 'A single Step, with every part it can render: the indicator, the label with its optional marker and trailing endContent, and the description beneath. A Step never sets its own completed/current state — it declares its index and derives the rest from the parent Stepper, so one Step in one Stepper is a complete example.',
+ isReady: true,
+ isShowcase: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['Stepper', 'Step', 'Text'],
+};
diff --git a/packages/cli/assets/templates/blocks/components/Step/StepShowcase.tsx b/packages/cli/assets/templates/blocks/components/Step/StepShowcase.tsx
new file mode 100644
index 0000000000..f886260287
--- /dev/null
+++ b/packages/cli/assets/templates/blocks/components/Step/StepShowcase.tsx
@@ -0,0 +1,26 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {Stepper, Step} from '@astryxdesign/core/Stepper';
+import {Text} from '@astryxdesign/core/Text';
+
+export default function StepShowcase() {
+ // One Step, and every part it renders: the indicator, the label with its
+ // optional marker and trailing slot, and the description beneath. A Step is
+ // always wrapped in a Stepper — that is where it reads its progress from —
+ // so a single Step in a single Stepper is the smallest complete example.
+ return (
+ <div style={{width: 380}}>
+ <Stepper activeStep={1} orientation="vertical">
+ <Step
+ step={1}
+ label="Connect a repository"
+ description="Astryx reads your build settings from the default branch"
+ endContent={<Text type="supporting">2 min</Text>}
+ isOptional
+ />
+ </Stepper>
+ </div>
+ );
+}
diff --git a/packages/cli/assets/templates/blocks/components/Step/StepStates.doc.mjs b/packages/cli/assets/templates/blocks/components/Step/StepStates.doc.mjs
new file mode 100644
index 0000000000..f2fca315f4
--- /dev/null
+++ b/packages/cli/assets/templates/blocks/components/Step/StepStates.doc.mjs
@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ exampleFor: 'Step',
+ name: 'Step — States',
+ displayName: 'Step — States',
+ description:
+ 'Every state a single Step can land in, each shown as one Step in its own Stepper. Completed, current, and upcoming are derived by comparing the step index against the parent activeStep, so they are never set directly; isDisabled and status are the two a step declares itself. Status is a separate axis from progress, which is why a completed step can still carry a warning.',
+ isReady: true,
+ aspectRatio: 4 / 3,
+ componentsUsed: ['Stepper', 'Step', 'Text'],
+};
diff --git a/packages/cli/assets/templates/blocks/components/Step/StepStates.tsx b/packages/cli/assets/templates/blocks/components/Step/StepStates.tsx
new file mode 100644
index 0000000000..51b27ff5b7
--- /dev/null
+++ b/packages/cli/assets/templates/blocks/components/Step/StepStates.tsx
@@ -0,0 +1,46 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {Stepper, Step} from '@astryxdesign/core/Stepper';
+import {Text} from '@astryxdesign/core/Text';
+
+export default function StepStates() {
+ // A Step holds no state of its own — it compares its `step` index against the
+ // Stepper's `activeStep`. Each state below is therefore one Step in its own
+ // Stepper, with activeStep placed on one side of it or the other.
+ return (
+ <div style={{display: 'flex', flexWrap: 'wrap', gap: 32}}>
+ <div style={{width: 220}}>
+ <Text type="label">Completed</Text>
+ <Stepper activeStep={1} orientation="vertical">
+ <Step step={0} label="Verify email" />
+ </Stepper>
+ </div>
+ <div style={{width: 220}}>
+ <Text type="label">Current</Text>
+ <Stepper activeStep={0} orientation="vertical">
+ <Step step={0} label="Verify email" />
+ </Stepper>
+ </div>
+ <div style={{width: 220}}>
+ <Text type="label">Upcoming</Text>
+ <Stepper activeStep={0} orientation="vertical">
+ <Step step={1} label="Add a payment method" />
+ </Stepper>
+ </div>
+ <div style={{width: 220}}>
+ <Text type="label">Disabled</Text>
+ <Stepper activeStep={0} orientation="vertical" onStepClick={() => {}}>
+ <Step step={1} label="Add a payment method" isDisabled />
+ </Stepper>
+ </div>
+ <div style={{width: 220}}>
+ <Text type="label">Completed, with a status</Text>
+ <Stepper activeStep={1} orientation="vertical">
+ <Step step={0} label="Verify email" status="warning" />
+ </Stepper>
+ </div>
+ </div>
+ );
+}
diff --git a/packages/cli/assets/templates/blocks/components/Stepper/StepperCustomContent.doc.mjs b/packages/cli/assets/templates/blocks/components/Stepper/StepperCustomContent.doc.mjs
new file mode 100644
index 0000000000..b05514f2f1
--- /dev/null
+++ b/packages/cli/assets/templates/blocks/components/Stepper/StepperCustomContent.doc.mjs
@@ -0,0 +1,22 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ exampleFor: 'Stepper',
+ name: 'Stepper — Custom Content',
+ displayName: 'Stepper — Custom Content',
+ description:
+ 'A vertical stepper where each step owns a slice of the page. The content slot takes any node — form fields, a summary panel, a banner — so a stepper is not limited to multi-step forms. Rendering the slot only for the active step is what makes the flow expand one step at a time.',
+ isReady: true,
+ aspectRatio: 4 / 3,
+ componentsUsed: [
+ 'Stepper',
+ 'TextInput',
+ 'Button',
+ 'Text',
+ 'Card',
+ 'Badge',
+ 'Banner',
+ ],
+};
diff --git a/packages/cli/assets/templates/blocks/components/Stepper/StepperCustomContent.tsx b/packages/cli/assets/templates/blocks/components/Stepper/StepperCustomContent.tsx
new file mode 100644
index 0000000000..db44074e23
--- /dev/null
+++ b/packages/cli/assets/templates/blocks/components/Stepper/StepperCustomContent.tsx
@@ -0,0 +1,126 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useState} from 'react';
+import {Stepper, Step} from '@astryxdesign/core/Stepper';
+import {TextInput} from '@astryxdesign/core/TextInput';
+import {Button} from '@astryxdesign/core/Button';
+import {Text} from '@astryxdesign/core/Text';
+import {Card} from '@astryxdesign/core/Card';
+import {Badge} from '@astryxdesign/core/Badge';
+import {Banner} from '@astryxdesign/core/Banner';
+
+export default function StepperCustomContent() {
+ const [active, setActive] = useState(0);
+ // The content slot takes any node, not just form fields — a panel, a summary,
+ // a notice. Gating it on `active` is what makes the flow expand a step at a
+ // time.
+ return (
+ <div style={{width: 680}}>
+ <Stepper
+ activeStep={active}
+ orientation="vertical"
+ onStepClick={setActive}>
+ <Step
+ step={0}
+ label="Project details"
+ description="Name it and point us at the source"
+ indicator="number">
+ {active === 0 && (
+ <div style={{display: 'flex', flexDirection: 'column', gap: 12}}>
+ <div style={{display: 'flex', gap: 12}}>
+ <TextInput
+ label="Project name"
+ placeholder="My awesome project"
+ value=""
+ width="100%"
+ />
+ <TextInput
+ label="Repository URL"
+ placeholder="https://github.com/..."
+ value=""
+ width="100%"
+ />
+ </div>
+ <div>
+ <Button
+ label="Continue"
+ variant="primary"
+ onClick={() => setActive(1)}
+ />
+ </div>
+ </div>
+ )}
+ </Step>
+ <Step
+ step={1}
+ label="Review the build"
+ description="What we detected from your default branch"
+ indicator="number">
+ {active === 1 && (
+ <div style={{display: 'flex', flexDirection: 'column', gap: 12}}>
+ <Card variant="muted" padding={3}>
+ <div style={{display: 'flex', flexDirection: 'column', gap: 8}}>
+ <div
+ style={{
+ display: 'flex',
+ alignItems: 'center',
+ gap: 8,
+ }}>
+ <Text type="label">Next.js 15</Text>
+ <Badge variant="success" label="Detected" />
+ </div>
+ <Text type="supporting">
+ Build command <code>next build</code> · Output{' '}
+ <code>.next</code> · Node 20
+ </Text>
+ </div>
+ </Card>
+ <div style={{display: 'flex', gap: 8}}>
+ <Button
+ label="Back"
+ variant="secondary"
+ onClick={() => setActive(0)}
+ />
+ <Button
+ label="Looks right"
+ variant="primary"
+ onClick={() => setActive(2)}
+ />
+ </div>
+ </div>
+ )}
+ </Step>
+ <Step
+ step={2}
+ label="Deploy"
+ description="Ships to production"
+ indicator="number">
+ {active === 2 && (
+ <div style={{display: 'flex', flexDirection: 'column', gap: 12}}>
+ <Banner
+ status="info"
+ title="First deploy takes a few minutes"
+ description="Later deploys reuse the build cache and finish in under a minute."
+ />
+ <div style={{display: 'flex', gap: 8}}>
+ <Button
+ label="Back"
+ variant="secondary"
+ onClick={() => setActive(1)}
+ />
+ <Button
+ label="Deploy now"
+ variant="primary"
+ onClick={() => setActive(3)}
+ />
+ </div>
+ </div>
+ )}
+ </Step>
+ <Step step={3} label="Live" indicator="number" />
+ </Stepper>
+ </div>
+ );
+}
diff --git a/packages/cli/assets/templates/blocks/components/Stepper/StepperHorizontal.doc.mjs b/packages/cli/assets/templates/blocks/components/Stepper/StepperHorizontal.doc.mjs
deleted file mode 100644
index ae176352c5..0000000000
--- a/packages/cli/assets/templates/blocks/components/Stepper/StepperHorizontal.doc.mjs
+++ /dev/null
@@ -1,14 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
-export const doc = {
- type: 'block',
- exampleFor: 'Stepper',
- name: 'Stepper — Horizontal Progress',
- displayName: 'Stepper — Horizontal Progress',
- description:
- 'A horizontal separated stepper: each step owns a segment of the progress bar above its label. Filled segments track how far the flow has progressed.',
- isReady: true,
- aspectRatio: 16 / 9,
- componentsUsed: ['Stepper'],
-};
diff --git a/packages/cli/assets/templates/blocks/components/Stepper/StepperHorizontal.tsx b/packages/cli/assets/templates/blocks/components/Stepper/StepperHorizontal.tsx
deleted file mode 100644
index 1148e3ca5f..0000000000
--- a/packages/cli/assets/templates/blocks/components/Stepper/StepperHorizontal.tsx
+++ /dev/null
@@ -1,24 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-'use client';
-
-import {useState} from 'react';
-import {Stepper, Step} from '@astryxdesign/lab';
-
-export default function StepperHorizontal() {
- const [active, setActive] = useState(1);
- return (
- <div style={{width: '100%', maxWidth: 600}}>
- <Stepper
- activeStep={active}
- orientation="horizontal"
- onStepClick={setActive}>
- <Step step={0} label="Workspace" />
- <Step step={1} label="Team" />
- <Step step={2} label="Integrations" />
- <Step step={3} label="Import" />
- <Step step={4} label="Launch" />
- </Stepper>
- </div>
- );
-}
diff --git a/packages/cli/assets/templates/blocks/components/Stepper/StepperIndicatorModes.doc.mjs b/packages/cli/assets/templates/blocks/components/Stepper/StepperIndicatorModes.doc.mjs
index 143f0d7d51..ccea8db5d8 100644
--- a/packages/cli/assets/templates/blocks/components/Stepper/StepperIndicatorModes.doc.mjs
+++ b/packages/cli/assets/templates/blocks/components/Stepper/StepperIndicatorModes.doc.mjs
@@ -7,7 +7,7 @@ export const doc = {
name: 'Stepper — Indicator Modes',
displayName: 'Stepper — Indicator Modes',
description:
- 'The indicator prop side by side: auto (check when done, ring when current, number ahead), always-number, and a custom icon per step.',
+ 'The indicator prop side by side: none (the bar and label carry the progress on their own), auto (check when done, ring when current, number ahead), always-number, and a custom icon per step.',
isReady: true,
aspectRatio: 4 / 3,
componentsUsed: ['Stepper', 'Text', 'Icon'],
diff --git a/packages/cli/assets/templates/blocks/components/Stepper/StepperIndicatorModes.tsx b/packages/cli/assets/templates/blocks/components/Stepper/StepperIndicatorModes.tsx
index 0371d773bb..401823d372 100644
--- a/packages/cli/assets/templates/blocks/components/Stepper/StepperIndicatorModes.tsx
+++ b/packages/cli/assets/templates/blocks/components/Stepper/StepperIndicatorModes.tsx
@@ -3,7 +3,7 @@
'use client';
import {useState} from 'react';
-import {Stepper, Step} from '@astryxdesign/lab';
+import {Stepper, Step} from '@astryxdesign/core/Stepper';
import {Text} from '@astryxdesign/core/Text';
import {Icon} from '@astryxdesign/core/Icon';
@@ -11,6 +11,18 @@ export default function StepperIndicatorModes() {
const [active, setActive] = useState(2);
return (
<div style={{display: 'flex', gap: 48, flexWrap: 'wrap'}}>
+ <div style={{maxWidth: 220}}>
+ <Text type="label">None</Text>
+ <Stepper
+ activeStep={active}
+ orientation="vertical"
+ onStepClick={setActive}>
+ <Step step={0} label="Account" indicator="none" />
+ <Step step={1} label="Profile" indicator="none" />
+ <Step step={2} label="Settings" indicator="none" />
+ <Step step={3} label="Review" indicator="none" />
+ </Stepper>
+ </div>
<div style={{maxWidth: 220}}>
<Text type="label">Auto</Text>
<Stepper
@@ -44,22 +56,22 @@ export default function StepperIndicatorModes() {
<Step
step={0}
label="Account"
- icon={<Icon icon="info" size="sm" />}
+ indicator={<Icon icon="info" size="sm" />}
/>
<Step
step={1}
label="Profile"
- icon={<Icon icon="search" size="sm" />}
+ indicator={<Icon icon="search" size="sm" />}
/>
<Step
step={2}
label="Settings"
- icon={<Icon icon="wrench" size="sm" />}
+ indicator={<Icon icon="wrench" size="sm" />}
/>
<Step
step={3}
label="Review"
- icon={<Icon icon="check" size="sm" />}
+ indicator={<Icon icon="check" size="sm" />}
/>
</Stepper>
</div>
diff --git a/packages/cli/assets/templates/blocks/components/Stepper/StepperMultiStepForm.doc.mjs b/packages/cli/assets/templates/blocks/components/Stepper/StepperMultiStepForm.doc.mjs
deleted file mode 100644
index ee0688e4f2..0000000000
--- a/packages/cli/assets/templates/blocks/components/Stepper/StepperMultiStepForm.doc.mjs
+++ /dev/null
@@ -1,14 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
-export const doc = {
- type: 'block',
- exampleFor: 'Stepper',
- name: 'Stepper — Multi-Step Form',
- displayName: 'Stepper — Multi-Step Form',
- description:
- 'A vertical stepper driving a multi-step form. Each step renders its own fields in the content slot for the active step, with Back/Continue buttons advancing activeStep.',
- isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['Stepper', 'TextInput', 'Button', 'Text'],
-};
diff --git a/packages/cli/assets/templates/blocks/components/Stepper/StepperMultiStepForm.tsx b/packages/cli/assets/templates/blocks/components/Stepper/StepperMultiStepForm.tsx
deleted file mode 100644
index 45f342cf33..0000000000
--- a/packages/cli/assets/templates/blocks/components/Stepper/StepperMultiStepForm.tsx
+++ /dev/null
@@ -1,92 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-'use client';
-
-import {useState} from 'react';
-import {Stepper, Step} from '@astryxdesign/lab';
-import {TextInput} from '@astryxdesign/core/TextInput';
-import {Button} from '@astryxdesign/core/Button';
-import {Text} from '@astryxdesign/core/Text';
-
-export default function StepperMultiStepForm() {
- const [active, setActive] = useState(0);
- return (
- <div style={{width: '100%', maxWidth: 480}}>
- <Stepper
- activeStep={active}
- orientation="vertical"
- onStepClick={setActive}>
- <Step step={0} label="Project details" indicator="number">
- {active === 0 && (
- <div style={{display: 'flex', flexDirection: 'column', gap: 12}}>
- <TextInput
- label="Project name"
- placeholder="My awesome project"
- value=""
- />
- <TextInput
- label="Repository URL"
- placeholder="https://github.com/..."
- value=""
- />
- <div>
- <Button
- label="Continue"
- variant="primary"
- onClick={() => setActive(1)}
- />
- </div>
- </div>
- )}
- </Step>
- <Step step={1} label="Environment" indicator="number">
- {active === 1 && (
- <div style={{display: 'flex', flexDirection: 'column', gap: 12}}>
- <TextInput label="Node version" placeholder="20" value="" />
- <TextInput
- label="Build command"
- placeholder="npm run build"
- value=""
- />
- <div style={{display: 'flex', gap: 8}}>
- <Button
- label="Back"
- variant="secondary"
- onClick={() => setActive(0)}
- />
- <Button
- label="Continue"
- variant="primary"
- onClick={() => setActive(2)}
- />
- </div>
- </div>
- )}
- </Step>
- <Step step={2} label="Deploy" indicator="number">
- {active === 2 && (
- <div style={{display: 'flex', flexDirection: 'column', gap: 12}}>
- <Text type="body">
- Ready to deploy. This creates a production build and pushes to
- your configured hosting.
- </Text>
- <div style={{display: 'flex', gap: 8}}>
- <Button
- label="Back"
- variant="secondary"
- onClick={() => setActive(1)}
- />
- <Button
- label="Deploy now"
- variant="primary"
- onClick={() => setActive(3)}
- />
- </div>
- </div>
- )}
- </Step>
- <Step step={3} label="Done" indicator="number" />
- </Stepper>
- </div>
- );
-}
diff --git a/packages/cli/assets/templates/blocks/components/Stepper/StepperOnTrackHorizontal.doc.mjs b/packages/cli/assets/templates/blocks/components/Stepper/StepperOnTrackHorizontal.doc.mjs
new file mode 100644
index 0000000000..95fe5f80ee
--- /dev/null
+++ b/packages/cli/assets/templates/blocks/components/Stepper/StepperOnTrackHorizontal.doc.mjs
@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ exampleFor: 'Stepper',
+ name: 'Stepper — On-Track Horizontal',
+ displayName: 'Stepper — On-Track Horizontal',
+ description:
+ 'The on-track layout in horizontal orientation: instead of sitting beside the label, each indicator is slotted into the connector itself, so the numbered nodes read as beads on one continuous line. Labels center under their node.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['Stepper'],
+};
diff --git a/packages/cli/assets/templates/blocks/components/Stepper/StepperOnTrackHorizontal.tsx b/packages/cli/assets/templates/blocks/components/Stepper/StepperOnTrackHorizontal.tsx
new file mode 100644
index 0000000000..bbe4d19fe5
--- /dev/null
+++ b/packages/cli/assets/templates/blocks/components/Stepper/StepperOnTrackHorizontal.tsx
@@ -0,0 +1,25 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useState} from 'react';
+import {Stepper, Step} from '@astryxdesign/core/Stepper';
+
+export default function StepperOnTrackHorizontal() {
+ const [active, setActive] = useState(2);
+ return (
+ <div style={{width: 560}}>
+ <Stepper
+ activeStep={active}
+ orientation="horizontal"
+ indicatorPosition="on-track"
+ onStepClick={setActive}>
+ <Step step={0} label="Workspace" indicator="number" />
+ <Step step={1} label="Team" indicator="number" />
+ <Step step={2} label="Integrations" indicator="number" />
+ <Step step={3} label="Import" indicator="number" />
+ <Step step={4} label="Launch" indicator="number" />
+ </Stepper>
+ </div>
+ );
+}
diff --git a/packages/cli/assets/templates/blocks/components/Stepper/StepperOnTrackVertical.doc.mjs b/packages/cli/assets/templates/blocks/components/Stepper/StepperOnTrackVertical.doc.mjs
index 58a2b0a85b..e7d2a0b75c 100644
--- a/packages/cli/assets/templates/blocks/components/Stepper/StepperOnTrackVertical.doc.mjs
+++ b/packages/cli/assets/templates/blocks/components/Stepper/StepperOnTrackVertical.doc.mjs
@@ -7,8 +7,8 @@ export const doc = {
name: 'Stepper — On-Track Vertical',
displayName: 'Stepper — On-Track Vertical',
description:
- 'The on-track layout in vertical orientation: indicators sit inline on a continuous connector rail, with each label and description beside its node.',
+ 'The on-track layout in vertical orientation: indicators sit inline on a continuous connector rail, with each label and description beside its node. Compare with the separated layout, where the indicator sits alongside its own bar segment instead of on a shared rail.',
isReady: true,
aspectRatio: 4 / 3,
- componentsUsed: ['Stepper'],
+ componentsUsed: ['Stepper', 'Step'],
};
diff --git a/packages/cli/assets/templates/blocks/components/Stepper/StepperOnTrackVertical.tsx b/packages/cli/assets/templates/blocks/components/Stepper/StepperOnTrackVertical.tsx
index 05c7fc32f5..ba557b1964 100644
--- a/packages/cli/assets/templates/blocks/components/Stepper/StepperOnTrackVertical.tsx
+++ b/packages/cli/assets/templates/blocks/components/Stepper/StepperOnTrackVertical.tsx
@@ -3,7 +3,7 @@
'use client';
import {useState} from 'react';
-import {Stepper, Step} from '@astryxdesign/lab';
+import {Stepper, Step} from '@astryxdesign/core/Stepper';
export default function StepperOnTrackVertical() {
const [active, setActive] = useState(2);
diff --git a/packages/cli/assets/templates/blocks/components/Stepper/StepperShowcase.doc.mjs b/packages/cli/assets/templates/blocks/components/Stepper/StepperShowcase.doc.mjs
index a6c33dea40..ced8544eba 100644
--- a/packages/cli/assets/templates/blocks/components/Stepper/StepperShowcase.doc.mjs
+++ b/packages/cli/assets/templates/blocks/components/Stepper/StepperShowcase.doc.mjs
@@ -7,7 +7,7 @@ export const doc = {
name: 'Stepper — Checkout Progress',
displayName: 'Stepper — Checkout Progress',
description:
- 'A horizontal on-track stepper for a checkout flow: numbered nodes sit on a continuous connector, with completed and current steps filled. Click any step to jump.',
+ 'The default stepper: a horizontal track where every step owns an equal segment of the progress bar above its label. The default auto indicator resolves itself per step — a check once the step is done, a ring on the current step, a number for the ones still ahead. Click any step to jump.',
isReady: true,
isShowcase: true,
aspectRatio: 16 / 9,
diff --git a/packages/cli/assets/templates/blocks/components/Stepper/StepperShowcase.tsx b/packages/cli/assets/templates/blocks/components/Stepper/StepperShowcase.tsx
index a5b334024d..253f96f131 100644
--- a/packages/cli/assets/templates/blocks/components/Stepper/StepperShowcase.tsx
+++ b/packages/cli/assets/templates/blocks/components/Stepper/StepperShowcase.tsx
@@ -3,7 +3,7 @@
'use client';
import {useState} from 'react';
-import {Stepper, Step} from '@astryxdesign/lab';
+import {Stepper, Step} from '@astryxdesign/core/Stepper';
export default function StepperShowcase() {
const [active, setActive] = useState(2);
@@ -12,13 +12,12 @@ export default function StepperShowcase() {
<Stepper
activeStep={active}
orientation="horizontal"
- indicatorPosition="on-track"
onStepClick={setActive}>
- <Step step={0} label="Cart" indicator="number" />
- <Step step={1} label="Shipping" indicator="number" />
- <Step step={2} label="Payment" indicator="number" />
- <Step step={3} label="Review" indicator="number" />
- <Step step={4} label="Confirm" indicator="number" />
+ <Step step={0} label="Cart" />
+ <Step step={1} label="Shipping" />
+ <Step step={2} label="Payment" />
+ <Step step={3} label="Review" />
+ <Step step={4} label="Confirm" />
</Stepper>
</div>
);
diff --git a/packages/cli/assets/templates/blocks/components/Stepper/StepperStatus.tsx b/packages/cli/assets/templates/blocks/components/Stepper/StepperStatus.tsx
index 76a149be34..f147c35949 100644
--- a/packages/cli/assets/templates/blocks/components/Stepper/StepperStatus.tsx
+++ b/packages/cli/assets/templates/blocks/components/Stepper/StepperStatus.tsx
@@ -3,7 +3,7 @@
'use client';
import {useState} from 'react';
-import {Stepper, Step} from '@astryxdesign/lab';
+import {Stepper, Step} from '@astryxdesign/core/Stepper';
export default function StepperStatus() {
const [active, setActive] = useState(3);
diff --git a/packages/cli/assets/templates/blocks/components/Stepper/StepperVerticalOnboarding.doc.mjs b/packages/cli/assets/templates/blocks/components/Stepper/StepperVerticalOnboarding.doc.mjs
deleted file mode 100644
index 7f51248742..0000000000
--- a/packages/cli/assets/templates/blocks/components/Stepper/StepperVerticalOnboarding.doc.mjs
+++ /dev/null
@@ -1,14 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
-export const doc = {
- type: 'block',
- exampleFor: 'Stepper',
- name: 'Stepper — Vertical Onboarding',
- displayName: 'Stepper — Vertical Onboarding',
- description:
- 'A vertical stepper for an onboarding flow, with a label and description per step. The auto indicator shows a check for completed steps, a ring for the current step, and a number for upcoming ones.',
- isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['Stepper'],
-};
diff --git a/packages/cli/assets/templates/blocks/components/Stepper/StepperVerticalOnboarding.tsx b/packages/cli/assets/templates/blocks/components/Stepper/StepperVerticalOnboarding.tsx
deleted file mode 100644
index 3ebbda7e06..0000000000
--- a/packages/cli/assets/templates/blocks/components/Stepper/StepperVerticalOnboarding.tsx
+++ /dev/null
@@ -1,40 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-'use client';
-
-import {useState} from 'react';
-import {Stepper, Step} from '@astryxdesign/lab';
-
-export default function StepperVerticalOnboarding() {
- const [active, setActive] = useState(2);
- return (
- <div style={{width: '100%', maxWidth: 400}}>
- <Stepper
- activeStep={active}
- orientation="vertical"
- onStepClick={setActive}>
- <Step
- step={0}
- label="Create workspace"
- description="Name and configure your workspace"
- />
- <Step
- step={1}
- label="Invite team members"
- description="Add collaborators by email"
- />
- <Step
- step={2}
- label="Set up integrations"
- description="Connect Slack, GitHub, Jira"
- />
- <Step
- step={3}
- label="Import data"
- description="Bring in existing projects"
- />
- <Step step={4} label="Launch" description="Go live with your team" />
- </Stepper>
- </div>
- );
-}
diff --git a/packages/core/locales/en.json b/packages/core/locales/en.json
index 3b871a9530..001012d494 100644
--- a/packages/core/locales/en.json
+++ b/packages/core/locales/en.json
@@ -1067,29 +1067,33 @@
"defaultMessage": "Expand all rows",
"description": "Screen-reader-only label on the header expand-all/collapse-all button when at least one row is collapsed (clicking expands every expandable row). Part of the four-way set."
},
+ "@astryx.stepper.label": {
+ "defaultMessage": "Progress",
+ "description": "Screen-reader-only fallback name for the Stepper's ordered list of steps, describing the sequence as a whole (e.g. `Progress`). Used as the aria-label when the consumer does not pass a `label`. Singular per ARIA convention."
+ },
"@astryx.step.goToStep": {
"defaultMessage": "Go to step {stepNumber, number}: {label}",
- "description": "Accessible name for a clickable step in the lab Stepper. {stepNumber} is the 1-based position, {label} is the step's visible label."
+ "description": "Accessible name for a clickable step in the Stepper. {stepNumber} is the 1-based position, {label} is the step's visible label."
},
"@astryx.step.goToStepWithStatus": {
"defaultMessage": "Go to step {stepNumber, number}: {label}, {status}",
- "description": "Accessible name for a clickable lab Stepper step that also carries a status. {status} is one of the translated `step.status.*` words (completed/warning/error). Keep the pattern parallel to `step.goToStep`."
+ "description": "Accessible name for a clickable Stepper step that also carries a status. {status} is one of the translated `step.status.*` words (completed/warning/error). Keep the pattern parallel to `step.goToStep`."
},
"@astryx.step.optional": {
"defaultMessage": "Optional",
- "description": "Visible indicator appended after a lab Stepper step's label when the step is optional (isOptional). Very short; appears inline after the label text."
+ "description": "Visible indicator appended after a Stepper step's label when the step is optional (isOptional). Very short; appears inline after the label text."
},
"@astryx.step.status.completed": {
"defaultMessage": "completed",
- "description": "Screen-reader-only status word rendered next to a lab Stepper step label when the step is done (either progress-completed or status=success). Lowercase adjective; it is read mid-sentence after the step label."
+ "description": "Screen-reader-only status word rendered next to a Stepper step label when the step is done (either progress-completed or status=success). Lowercase adjective; it is read mid-sentence after the step label."
},
"@astryx.step.status.warning": {
"defaultMessage": "warning",
- "description": "Screen-reader-only status word rendered next to a lab Stepper step label when status=warning. Lowercase noun/adjective; read mid-sentence after the step label."
+ "description": "Screen-reader-only status word rendered next to a Stepper step label when status=warning. Lowercase noun/adjective; read mid-sentence after the step label."
},
"@astryx.step.status.error": {
"defaultMessage": "error",
- "description": "Screen-reader-only status word rendered next to a lab Stepper step label when status=error. Lowercase noun; read mid-sentence after the step label."
+ "description": "Screen-reader-only status word rendered next to a Stepper step label when status=error. Lowercase noun; read mid-sentence after the step label."
},
"@astryx.tableTree.collapseRow": {
"defaultMessage": "Collapse row",
diff --git a/packages/core/package.json b/packages/core/package.json
index b68be6f358..d565ee1588 100644
--- a/packages/core/package.json
+++ b/packages/core/package.json
@@ -489,6 +489,11 @@
"types": "./dist/StatusDot/index.d.ts",
"default": "./dist/StatusDot/index.js"
},
+ "./Stepper": {
+ "source": "./src/Stepper/index.ts",
+ "types": "./dist/Stepper/index.d.ts",
+ "default": "./dist/Stepper/index.js"
+ },
"./Switch": {
"source": "./src/Switch/index.ts",
"types": "./dist/Switch/index.d.ts",
diff --git a/packages/core/src/Stepper/Step.doc.mjs b/packages/core/src/Stepper/Step.doc.mjs
new file mode 100644
index 0000000000..ce071221ae
--- /dev/null
+++ b/packages/core/src/Stepper/Step.doc.mjs
@@ -0,0 +1,98 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
+
+export const docs = {
+ name: 'Step',
+ subComponentOf: 'Stepper',
+ displayName: 'Step',
+ group: 'Stepper',
+ category: 'Navigation',
+ isHiddenFromOverview: true,
+ description:
+ 'Individual step within a Stepper. Renders a progress-bar segment, an indicator, and a label with optional description. Progress (completed/active/not-started) is derived from the parent Stepper\u2019s activeStep and this step\u2019s step index.',
+ props: [
+ {
+ name: 'step',
+ type: 'number',
+ description:
+ 'Zero-based index of this step. Used to derive progress (completed/active/not-started) relative to the parent activeStep.',
+ required: true,
+ },
+ {
+ name: 'label',
+ type: 'string',
+ description: 'Step label text.',
+ required: true,
+ },
+ {
+ name: 'description',
+ type: 'string',
+ description:
+ 'Optional description shown below the label for additional context.',
+ },
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description:
+ 'Content rendered below the label and description. Useful in vertical steppers for form fields or detailed step content.',
+ },
+ {
+ name: 'status',
+ type: "'accent' | 'success' | 'warning' | 'error'",
+ description:
+ 'Semantic color for the step. Controls color only and maps to the global Astryx semantic tokens. Leave unset for the progress-derived default coloring.',
+ },
+ {
+ name: 'indicator',
+ type: "'auto' | 'number' | 'none' | ReactNode",
+ description:
+ "What to show as the step indicator. 'auto' shows a number until completed then a check, 'number' always shows a numbered badge, 'none' hides it, or pass any ReactNode (e.g. an Icon) for a fully custom indicator.",
+ slotElements: [{__element: 'Icon', props: {icon: 'check', size: 'sm'}}],
+ default: "'auto'",
+ },
+ {
+ name: 'isDisabled',
+ type: 'boolean',
+ description:
+ 'Disables interaction and dims the step indicator and label.',
+ default: 'false',
+ },
+ {
+ name: 'isOptional',
+ type: 'boolean',
+ description:
+ 'Marks the step as optional, appending an "Optional" affordance after the label.',
+ default: 'false',
+ },
+ {
+ name: 'endContent',
+ type: 'ReactNode',
+ description: 'Trailing content rendered at the end of the label row.',
+ },
+ {
+ name: 'density',
+ type: "'compact' | 'balanced' | 'spacious'",
+ description:
+ 'Controls vertical padding of the step. Falls back to the stepper-level density when unset.',
+ },
+ ],
+ // A Step reads its progress from the parent Stepper's context and throws
+ // without one, so the preview needs a real Stepper around it. Without this
+ // block Step inherits Stepper's playground, which renders it bare and hands
+ // it the parent's `activeStep`. The wrapper is vertical because that is the
+ // orientation where one step shows its whole anatomy — indicator, label, and
+ // description stacked — and `step` matches the wrapper's `activeStep` so the
+ // preview opens on the current step rather than an inert upcoming one.
+ playground: {
+ wrapper: {
+ component: 'Stepper',
+ props: {activeStep: 1, orientation: 'vertical'},
+ },
+ defaults: {
+ step: 1,
+ label: 'Billing address',
+ description: 'Used for invoices and tax',
+ },
+ },
+};
diff --git a/packages/lab/src/Stepper/Step.tsx b/packages/core/src/Stepper/Step.tsx
similarity index 60%
rename from packages/lab/src/Stepper/Step.tsx
rename to packages/core/src/Stepper/Step.tsx
index 2bd32219d7..d74dc74f5a 100644
--- a/packages/lab/src/Stepper/Step.tsx
+++ b/packages/core/src/Stepper/Step.tsx
@@ -4,19 +4,35 @@
/**
* @file Step.tsx
- * @input Uses React, stylex, theme tokens, StepperContext
+ * @input Uses React, stylex, theme tokens (including the motion duration token
+ * the connector fill animates on), StepperContext
* @output Exports Step component and StepProps
* @position Individual step item; used inside Stepper
*
+ * Every connector this file draws — the separated progress bars and the
+ * on-track segments alike — paints its accent fill as a scaled ::before rather
+ * than by swapping a background color, so a step the flow advances into grows
+ * its line along the track. See the CONNECTOR FILL block in the styles below
+ * for the axis/RTL/reduced-motion rules that go with it.
+ *
+ * Exactly one change animates: advancing a single step. Going back, jumping
+ * forward by more than one, and mounting mid-flow all land at once. The rule
+ * and the reasoning behind it sit above the styles; the arithmetic that keeps
+ * the one animated span reading as a single front — an on-track span is drawn
+ * by two steps, three where a content slot splits it — is in the component.
+ * Nothing about it is public API: Stepper hands each Step the step it came
+ * from through context, and the rest is derived.
+ *
* SYNC: When modified, update these files to stay in sync:
- * - /packages/lab/src/Stepper/Stepper.doc.mjs
- * - /packages/lab/src/Stepper/Stepper.test.tsx
- * - /packages/lab/src/Stepper/index.ts
+ * - /packages/core/src/Stepper/Stepper.doc.mjs
+ * - /packages/core/src/Stepper/Stepper.test.tsx
+ * - /packages/core/src/Stepper/index.ts
* - /apps/storybook/stories/Stepper.stories.tsx
* - /packages/cli/assets/templates/blocks/components/Stepper/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/Step/ (showcase blocks)
*/
-import {type ReactNode} from 'react';
+import {useEffect, type ReactNode} from 'react';
import * as stylex from '@stylexjs/stylex';
import {
@@ -25,16 +41,21 @@ import {
radiusVars,
fontWeightVars,
typeScaleVars,
+ textSizeVars,
durationVars,
easeVars,
-} from '@astryxdesign/core/theme/tokens.stylex';
-import {focusOutlineStyles, mergeProps} from '@astryxdesign/core/utils';
-import type {BaseProps} from '@astryxdesign/core';
-import {Icon} from '@astryxdesign/core/Icon';
-import {VisuallyHidden} from '@astryxdesign/core/VisuallyHidden';
-import {useTranslator} from '@astryxdesign/core/i18n';
+} from '../theme/tokens.stylex';
+import {
+ focusOutlineStyles,
+ mergeProps,
+ isRenderable,
+ themeProps,
+} from '../utils';
+import type {BaseProps} from '../BaseProps';
+import {Icon} from '../Icon';
+import {VisuallyHidden} from '../VisuallyHidden';
+import {useTranslator} from '../i18n';
import {useStepperContext} from './StepperContext';
-import {themeProps} from '@astryxdesign/core/utils';
import {stepMarker} from './stepper.stylex';
import type {StepStatus} from './StepStatus';
@@ -70,12 +91,7 @@ export interface StepProps extends BaseProps<HTMLLIElement> {
* steppers to show form fields or detailed content for each step.
*/
children?: ReactNode;
- /**
- * Custom icon rendered inside the indicator. Accepts any ReactNode (for
- * example an `<Icon />`). Equivalent to passing the node directly to
- * `indicator`; takes precedence over the built-in number/check.
- */
- icon?: ReactNode;
+
/**
* Semantic status for the step, mapped to the global Astryx semantic tokens
* (`accent`, `success`, `warning`, `error`). In the default `auto` indicator
@@ -180,8 +196,79 @@ function CurrentIcon() {
// --- Styles ---
const BAR_WIDTH = spacingVars['--spacing-1'];
-const ICON_SIZE = spacingVars['--spacing-4'];
-const NUMBER_SIZE = spacingVars['--spacing-5'];
+// Every indicator — check, ring, custom icon, number badge — occupies the same
+// box, so the `auto` mode swapping a number for a check as a step completes
+// never nudges the label or the track.
+const INDICATOR_SIZE = spacingVars['--spacing-4'];
+// Indicator (16px) + the label-row gap (8px). The indent that lines a
+// description or a content slot up with the label above it.
+const INDICATOR_GUTTER = spacingVars['--spacing-6'];
+
+// --- Connector fill motion ---
+//
+// One change animates: advancing exactly one step. Going back, jumping
+// forward by more than one, and mounting mid-flow all apply at once.
+//
+// Animating the others was tried and read worse than not animating them. A
+// retreat is the clearest case: run forward, the transition ends with a bar
+// that is nearly full, and nearly full is indistinguishable from full, so the
+// eye calls it arrived well before it settles. Run backward, the same curve
+// ends with a shrinking stub of accent still on the track, and a remnant that
+// is still there reads unmistakably as not finished. Identical arithmetic in
+// both directions — measurably so — and the backward one still feels slow,
+// because the tail is what is visible rather than what is hidden. No easing
+// fixes that; only not animating it does. A multi-step jump fails differently:
+// it is a navigation rather than a progression, and sweeping a front across
+// four segments makes the user sit through a journey they asked to skip.
+//
+// What is left is the one gesture where the movement carries the meaning: the
+// flow went forward one step, and the line grows to show it. That span takes
+// the medium band — a fill crossing a whole segment is a spatial change, not a
+// micro-interaction, so per `astryx docs motion` it sits above the fast band
+// reserved for high-frequency states like hover.
+const FILL_SPAN_TIME = durationVars['--duration-medium'];
+
+// Share of one node-to-node span owned by the segment *arriving* at the far
+// node; the segment leaving the near node takes the rest. On-track spans are
+// drawn by two steps (see the ON-TRACK section), and the time has to be split
+// the way the length is or the two halves sweep at visibly different speeds.
+//
+// Horizontal: both halves are `flex: 1` inside equal-width steps, so an even
+// split is the proportional one.
+//
+// Vertical: the halves are nothing like equal, and no constant can be right
+// for all of them. The arriving half is otSegLeadV, a cap fixed at one density
+// space; the leaving half is otSegFlexV, grown to whatever is left of the step
+// row, so its length turns on label and description lengths this file cannot
+// see. Measured in the browser the cap is 40% of a plain balanced span (8 of
+// 20px) but 21% once the step carries a description (8 of 38px). 0.3 is the
+// value that minimises the worse of those two: it leaves the cap ~1.6x off the
+// rail's speed either way, where tuning to one case puts the other past 2x.
+// Matching each case exactly would mean measuring the rendered rail, a layout
+// read this system avoids.
+const OT_ARRIVAL_SHARE_H = 0.5;
+const OT_ARRIVAL_SHARE_V = 0.3;
+// A vertical step carrying a content slot draws a third segment down the side
+// of it (otContentSegV) which continues the leaving half past the row, so the
+// leaving half's time splits again. A slot runs several times the rail left
+// above it — 34px of rail to 108px of slot in the spacious content story — and
+// this is the middle of that range. Matching it exactly would mean measuring
+// the rendered slot; the ordering is what keeps the front contiguous, and this
+// keeps its speed in the right neighbourhood.
+const OT_RAIL_SHARE_OF_LEAVING = 0.25;
+
+/** Scale a CSS `<time>` by a unitless factor, collapsing the trivial cases. */
+function fillTimeSlice(time: string, factor: number): string {
+ if (factor <= 0) {
+ return '0s';
+ }
+ if (factor === 1) {
+ return time;
+ }
+ // Rounded because the factors are sums of shares, and float noise would
+ // otherwise reach the emitted custom property as `calc(... * 0.7000000001)`.
+ return `calc(${time} * ${Number(factor.toFixed(4))})`;
+}
const styles = stylex.create({
// ===================== VERTICAL LAYOUT =====================
@@ -193,19 +280,14 @@ const styles = stylex.create({
gap: spacingVars['--spacing-0-5'],
},
- // 4px progress bar segment
+ // 4px progress bar segment. Its filled/unfilled paint comes from the shared
+ // connector styles below, not from here.
verticalBar: {
width: BAR_WIDTH,
borderRadius: radiusVars['--radius-full'],
flexShrink: 0,
alignSelf: 'stretch',
},
- barCompleted: {
- backgroundColor: colorVars['--color-accent'],
- },
- barIncomplete: {
- backgroundColor: colorVars['--color-border'],
- },
// Step body — the selectable area
verticalBody: {
@@ -218,8 +300,18 @@ const styles = stylex.create({
horizontalStep: {
display: 'flex',
flexDirection: 'column',
- alignItems: 'flex-start',
+ // Stretch, not flex-start: a flex-start child is sized to fit-content,
+ // which is floored at its own min-content and would spill the label past
+ // the step's slice of the track and into the next step. Stretched, the
+ // label row is exactly as wide as the step and the label wraps inside it.
+ alignItems: 'stretch',
flex: 1,
+ // `flex: 1` alone does not make the steps equal: a flex item's default
+ // `min-width: auto` floors it at its own min-content width, so a step
+ // labelled "Integrations" claims a wider slice of the track than one
+ // labelled "Team". Zeroing the floor lets the even distribution actually
+ // apply, which is what keeps every progress segment the same width.
+ minWidth: 0,
// density padding applied via density styles below
},
@@ -234,6 +326,127 @@ const styles = stylex.create({
marginBlockEnd: spacingVars['--spacing-0-5'],
},
+ // ===================== CONNECTOR FILL =====================
+ // Shared by every connector the four layout combinations draw: the separated
+ // bars (verticalBar, horizontalBar) and the on-track segments (otSegBaseV,
+ // otSegH, otContentSegV).
+ //
+ // The segment element is the *unfilled* track and never changes color; the
+ // accent fill is a ::before scaled along the track axis. Advancing a step
+ // grows it out of the segment's leading edge, so the line reads as progress
+ // travelling rather than a bar changing state. The obvious alternative,
+ // transitioning `background-color` between accent and border on the segment
+ // itself, lights the whole segment at once: a flash, with no direction in
+ // it. Going the other way the scale still returns to zero, but instantly —
+ // only a single step forward is given a duration to cross (see the motion
+ // block above).
+ //
+ // A pseudo-element rather than a real child element, because the connector is
+ // emitted from seven places and several of them size themselves in ways a
+ // child would have to re-derive (otSegFlexV grows, otSegLeadV is fixed,
+ // otContentSegV is absolutely positioned). ::before inherits the box for
+ // free, so one style covers all of them.
+ //
+ // Mount is deliberately not animated, and falls out of how transitions work:
+ // interpolation needs a previous computed value and a freshly rendered
+ // element has none. A stepper that opens on step 3 paints the segments behind
+ // it filled, instantly, instead of playing its whole history back.
+ connectorTrack: {
+ position: 'relative',
+ backgroundColor: colorVars['--color-border'],
+ '::before': {
+ content: '""',
+ position: 'absolute',
+ inset: 0,
+ // Follows whatever the segment itself rounds to: the full pill of a
+ // separated bar, the square ends the on-track segments need in order to
+ // stack into one continuous line.
+ borderRadius: 'inherit',
+ backgroundColor: colorVars['--color-accent'],
+ transitionProperty: 'transform',
+ // Resting duration, for a segment moving on its own. connectorTiming
+ // below replaces it on every connector — each one is handed either its
+ // slice of the animated span or a zero — so this is the fallback that
+ // applies if a connector is ever rendered without it.
+ transitionDuration: {
+ default: FILL_SPAN_TIME,
+ '@media (prefers-reduced-motion: reduce)': '0s',
+ },
+ // Linear, deliberately, and not the `--ease-standard` the rest of the
+ // system transitions on. A node-to-node span is not always one element:
+ // in the on-track layouts the segment leaving one node and the segment
+ // arriving at the next draw it between them, and a vertical step with a
+ // content slot splits it three ways. A curve applied per segment
+ // restarts its deceleration at every seam, so the front lurches, stalls
+ // at the joint, and the joint becomes the most visible thing in the
+ // animation — the fill stops reading as one line growing and starts
+ // reading as two pieces taking turns. Linear is the only timing that
+ // stitches into a single constant-speed front. The separated bars run
+ // linear too: a lone segment gives up very little by it, and the two
+ // layouts should not animate with different character.
+ transitionTimingFunction: 'linear',
+ },
+ },
+ // This segment's slice of the animated span, or a pair of zeros for a
+ // segment that is not part of it (see the motion block above the styles).
+ // Dynamic because which segments animate, and over what part of the span,
+ // depends on where the active step just moved from — known only at render.
+ // StyleX routes the values through a custom property, so these are still
+ // generated rules and not inline styles.
+ //
+ // Restates the reduced-motion escape connectorTrack declares rather than
+ // relying on it: a StyleX style that redefines a property replaces the
+ // earlier definition wholesale, conditions included. Without it a
+ // reduced-motion user would get an on-track span as two instant snaps spaced
+ // apart by the delay — motion smuggled back in as timing. Zeroing the delay
+ // alongside the duration lands the whole span at once instead.
+ connectorTiming: (duration: string, delay: string) => ({
+ '::before': {
+ transitionDuration: {
+ default: duration,
+ '@media (prefers-reduced-motion: reduce)': '0s',
+ },
+ transitionDelay: {
+ default: delay,
+ '@media (prefers-reduced-motion: reduce)': '0s',
+ },
+ },
+ }),
+ // Vertical track: progress runs down the block axis under both LTR and RTL
+ // (direction only mirrors the inline axis), so the growth anchors at the
+ // physical top either way.
+ connectorFillV: {
+ '::before': {transformOrigin: 'center top', transform: 'scaleY(1)'},
+ },
+ connectorEmptyV: {
+ '::before': {transformOrigin: 'center top', transform: 'scaleY(0)'},
+ },
+ // Horizontal track: progress runs along the reading direction, so the growth
+ // anchors at the inline-start edge — physically left in LTR, right in RTL.
+ // `transform-origin` accepts no logical keywords, so the flip is spelled out
+ // with the same `:is([dir="rtl"] *)` hook Switch's thumb travel and the
+ // shared rtlStyles.mirror use. Stated on both states rather than hoisted onto
+ // connectorTrack, which is axis-agnostic and shared with the vertical
+ // segments.
+ connectorFillH: {
+ '::before': {
+ transformOrigin: {
+ default: 'left center',
+ ':is([dir="rtl"] *)': 'right center',
+ },
+ transform: 'scaleX(1)',
+ },
+ },
+ connectorEmptyH: {
+ '::before': {
+ transformOrigin: {
+ default: 'left center',
+ ':is([dir="rtl"] *)': 'right center',
+ },
+ transform: 'scaleX(0)',
+ },
+ },
+
// ===================== SHARED =====================
// Icon + Label in one row
@@ -249,8 +462,8 @@ const styles = stylex.create({
display: 'flex',
alignItems: 'center',
justifyContent: 'center',
- width: ICON_SIZE,
- height: ICON_SIZE,
+ width: INDICATOR_SIZE,
+ height: INDICATOR_SIZE,
flexShrink: 0,
},
iconCompleted: {
@@ -280,19 +493,21 @@ const styles = stylex.create({
color: colorVars['--color-error'],
},
- // Number badge
+ // Number badge — same box as every other indicator (see INDICATOR_SIZE).
numberBadge: {
display: 'grid',
placeItems: 'center',
- width: NUMBER_SIZE,
- height: NUMBER_SIZE,
+ width: INDICATOR_SIZE,
+ height: INDICATOR_SIZE,
borderRadius: radiusVars['--radius-full'],
- // Smallest semantic type token — keeps the compact numeric badge legible
- // (>=12px) and themeable rather than a raw literal.
- fontSize: typeScaleVars['--text-supporting-size'],
- paddingBlockEnd: '1px',
+ // The digit has to read at the same optical weight as the check glyph it
+ // alternates with inside a 16px circle, which the supporting size (12px)
+ // overfills — it leaves no room for a two-digit step. This is the scale
+ // step below it, still a token so themes rescale it. The digit is centered
+ // by the grid (placeItems), so no explicit line-height is needed — this
+ // matches how Avatar/AvatarGroup center a single glyph in a circle.
+ fontSize: textSizeVars['--font-size-xs'],
fontWeight: fontWeightVars['--font-weight-semibold'],
- lineHeight: 1,
flexShrink: 0,
textAlign: 'center',
},
@@ -337,6 +552,12 @@ const styles = stylex.create({
lineHeight: typeScaleVars['--text-body-leading'],
fontWeight: fontWeightVars['--font-weight-normal'],
color: colorVars['--color-text-primary'],
+ // Horizontal steps divide the track evenly, so a label can end up with
+ // less room than it wants. Let it shrink past its longest word and break
+ // that word rather than overlap the neighbouring step. Inert wherever
+ // there is room, which is every vertical stepper.
+ minWidth: 0,
+ overflowWrap: 'break-word',
},
labelInProgress: {
fontWeight: fontWeightVars['--font-weight-semibold'],
@@ -347,17 +568,6 @@ const styles = stylex.create({
labelDisabled: {
color: colorVars['--color-text-disabled'],
},
- // Collapse a non-current step's label when the stepper container is narrow
- // (opt-in via Stepper hasCollapsibleLabels). Hidden from layout AND from
- // the accessibility tree's visible text — the step stays reachable via
- // aria-current and each control's accessible name, which are unaffected.
- // The current step never gets this style, so its label always shows.
- labelCollapsible: {
- display: {
- default: 'block',
- '@container astryx-stepper (max-width: 480px)': 'none',
- },
- },
// Optional tag
optionalDot: {
@@ -374,19 +584,23 @@ const styles = stylex.create({
paddingInlineStart: spacingVars['--spacing-0'],
},
descriptionRowWithIndicator: {
- // Align with label: icon (16px) + gap (8px) = 24px
- paddingInlineStart: spacingVars['--spacing-6'],
- },
- descriptionRowWithNumber: {
- // Align with label: number badge (20px) + gap (8px) = 28px
- paddingInlineStart: spacingVars['--spacing-7'],
+ paddingInlineStart: INDICATOR_GUTTER,
},
description: {
+ // Block, not inline. An inline span is laid out in a line box belonging to
+ // its parent, and that box is floored by the parent's strut — the invisible
+ // box every block container reserves from its own font and line-height. The
+ // row inherits the page's 16px/24px, so an inline description sat in a 24px
+ // line box no matter how tight its own leading was, padding the gap under
+ // the label. Blockifying moves the strut onto this span, where the metrics
+ // below apply and the box hugs the text at 16px.
+ display: 'block',
fontSize: typeScaleVars['--text-supporting-size'],
// The supporting-leading token (1.667 → 20px at 12px) reads too loose for
- // a caption sitting under its label; a fixed 16px line box (1.33) is
- // tighter without collapsing the text the way capsize trim did.
- lineHeight: '16px',
+ // a caption sitting under its label; a fixed 16px line box (the --spacing-4
+ // step) is tighter without collapsing the text the way capsize trim did,
+ // and stays on the spacing scale rather than a raw literal.
+ lineHeight: spacingVars['--spacing-4'],
color: colorVars['--color-text-secondary'],
},
@@ -394,26 +608,33 @@ const styles = stylex.create({
stepContent: {
paddingBlockStart: spacingVars['--spacing-2'],
},
- stepContentWithIndicator: {
- paddingInlineStart: spacingVars['--spacing-6'],
- },
- stepContentWithNumber: {
- paddingInlineStart: spacingVars['--spacing-7'],
- },
+ // The label row sits inside the density-padded hover target, but the content
+ // slot is that target's *sibling* — a <button> cannot contain the buttons and
+ // inputs a content slot usually holds, so the slot has to live outside it.
+ // Left alone the slot therefore starts at the step edge while the label above
+ // starts one density pad in. Reproducing that pad here is what keeps the two
+ // flush; the gutter on top of it is what lines the content up with the label
+ // rather than with the indicator.
+ contentIndent: (inlinePad: string, gutter: string) => ({
+ paddingInlineStart: `calc(${inlinePad} + ${gutter})`,
+ paddingInlineEnd: inlinePad,
+ }),
- // Density
+ // Density. Block padding only — the inline half comes from densityInline,
+ // which is passed in so the content slot outside this wrapper can apply the
+ // same value.
densityCompact: {
paddingBlock: spacingVars['--spacing-1'],
- paddingInline: spacingVars['--spacing-2'],
},
densityBalanced: {
paddingBlock: spacingVars['--spacing-2'],
- paddingInline: spacingVars['--spacing-2'],
},
densitySpacious: {
paddingBlock: spacingVars['--spacing-3'],
- paddingInline: spacingVars['--spacing-3'],
},
+ densityInline: (value: string) => ({
+ paddingInline: value,
+ }),
// Button reset for clickable steps
buttonReset: {
@@ -509,7 +730,7 @@ const styles = stylex.create({
display: 'flex',
flexDirection: 'column',
alignItems: 'center',
- width: NUMBER_SIZE,
+ width: INDICATOR_SIZE,
flexShrink: 0,
alignSelf: 'stretch',
},
@@ -563,14 +784,6 @@ const styles = stylex.create({
},
},
- // Connector fill colors (progress-derived; status recolors when set).
- lineFilled: {
- backgroundColor: colorVars['--color-accent'],
- },
- lineUnfilled: {
- backgroundColor: colorVars['--color-border'],
- },
-
otBodyV: {
display: 'flex',
flexDirection: 'column',
@@ -582,7 +795,11 @@ const styles = stylex.create({
otLabelWrapH: {
display: 'flex',
flexDirection: 'column',
- alignItems: 'center',
+ // Stretch rather than center for the same reason as horizontalStep: a
+ // centered child is fit-content sized and would spill past its node.
+ // The label still reads centered under the node — otLabelRowCenter
+ // centers it inside the full-width row.
+ alignItems: 'stretch',
gap: spacingVars['--spacing-0-5'],
textAlign: 'center',
},
@@ -601,13 +818,31 @@ const styles = stylex.create({
gap: spacingVars['--spacing-1'],
},
- otContentV: {
- paddingInlineStart: spacingVars['--spacing-7'],
+ // Inline offset comes from contentIndent, and only in the vertical layout —
+ // a horizontal on-track step pads its hover target on the block axis alone,
+ // so its content slot already starts flush with the column above it.
+ otContent: {
paddingBlockStart: spacingVars['--spacing-2'],
},
- otContentH: {
- paddingBlockStart: spacingVars['--spacing-2'],
+ // A vertical on-track step draws its connector inside the row holding the
+ // indicator and label, and the content slot sits below that row rather than
+ // in it (the row is a <button> when the step is clickable, which cannot
+ // contain the controls a content slot usually holds). So the line stops at
+ // the label and the track breaks open wherever a step carries content.
+ // otContentSegV continues it: a segment spanning the slot's full height, on
+ // the same rail the row's segments run down, which closes the gap between
+ // this step's indicator and the next one's.
+ otContentWrapV: {
+ position: 'relative',
},
+ otContentSegV: (inlinePad: string) => ({
+ position: 'absolute',
+ insetBlock: 0,
+ // Center on the rail: the row pads itself by inlinePad, then centers a
+ // BAR_WIDTH line inside an INDICATOR_SIZE-wide column.
+ insetInlineStart: `calc(${inlinePad} + (${INDICATOR_SIZE} - ${BAR_WIDTH}) / 2)`,
+ width: BAR_WIDTH,
+ }),
// Density-driven spacing. The connector runs along the "track axis"
// (vertical = block, horizontal = inline), so density is only ever applied
@@ -665,7 +900,6 @@ export function Step({
label,
description,
children,
- icon,
status,
isDisabled = false,
isOptional = false,
@@ -683,14 +917,27 @@ export function Step({
const ctx = useStepperContext();
const {
activeStep,
+ previousActiveStep,
orientation,
onStepClick,
density: ctxDensity,
indicatorPosition,
- hasCollapsibleLabels,
+ registerStep,
} = ctx;
+ // Register this step index with the parent Stepper for duplicate detection.
+ useEffect(() => registerStep(step), [registerStep, step]);
+
const density = densityProp ?? ctxDensity;
+ // Inline padding of a separated step's hover target. Density varies the block
+ // padding freely, but the inline value has to be readable from out here: the
+ // content slot renders outside that target and re-applies it to stay aligned
+ // (see contentIndent), so keeping it in one place is what stops the two
+ // drifting apart.
+ const separatedDensityInline =
+ density === 'spacious'
+ ? spacingVars['--spacing-3']
+ : spacingVars['--spacing-2'];
// Resolve indicator prop — may be a preset string or a custom ReactNode.
const isCustomIndicator =
@@ -710,11 +957,6 @@ export function Step({
const isVertical = orientation === 'vertical';
const isActive = progress === 'in-progress';
- // Non-current step labels collapse only when the stepper opted in, the layout
- // is horizontal (width-constrained), and this step is not the current one —
- // the current step always keeps its label. The actual hide is a container
- // query on the label element (styles.labelCollapsible).
- const collapseLabel = hasCollapsibleLabels && !isVertical && !isActive;
// Any non-disabled step is navigable when an onStepClick handler is provided,
// including not-started steps (free navigation across the flow).
const isClickable = !isDisabled && onStepClick != null;
@@ -729,6 +971,38 @@ export function Step({
// only recolors the indicator (icon / number badge) below.
const isBarFilled = progress === 'completed' || progress === 'in-progress';
+ // --- This step's slice of the animated span ---
+ // Both layouts are measured in the same unit, the node-to-node span: on-track
+ // span k runs from node k to node k+1, and a separated step's lone bar is the
+ // span arriving at it (bar s fills on exactly the condition span s-1 does).
+ // So one rule serves both, and neither needs to know the step count.
+ //
+ // Only a single forward step animates, and the span it crosses is the one
+ // leaving the step the flow came from. Every other segment — the untouched
+ // ones, and every segment of a jump or a retreat — is handed a zero
+ // duration, so it lands at once and carries no stale delay into a later
+ // change.
+ const isSingleAdvance = activeStep === previousActiveStep + 1;
+ const animatedSpan = previousActiveStep;
+
+ /**
+ * Timing for the segment covering `[offset, offset + share)` of span
+ * `spanIndex`, both expressed as fractions of that span.
+ */
+ const fillTiming = (spanIndex: number, offset: number, share: number) => {
+ if (!isSingleAdvance || spanIndex !== animatedSpan) {
+ return styles.connectorTiming('0s', '0s');
+ }
+ return styles.connectorTiming(
+ fillTimeSlice(FILL_SPAN_TIME, share),
+ fillTimeSlice(FILL_SPAN_TIME, offset),
+ );
+ };
+
+ // A separated step draws the whole span arriving at it, so it fills for the
+ // span's entire slice with nothing to sequence against.
+ const barTiming = fillTiming(step - 1, 0, 1);
+
// --- Build indicator node ---
// 'auto': number for not-started, check/dot icon once reached
// 'number': always number badge
@@ -736,7 +1010,7 @@ export function Step({
// custom ReactNode (or `icon` prop): render as-is
let indicatorNode: ReactNode = null;
- const customIcon = isCustomIndicator ? indicatorProp : (icon ?? null);
+ const customIcon = isCustomIndicator ? indicatorProp : null;
// Semantic `status` drives a distinct indicator glyph (default 'auto' mode,
// no custom icon), all sourced from the themed Icon registry so a step reads
@@ -894,8 +1168,9 @@ export function Step({
// into the button's accessible name for clickable ones (an aria-label on
// the button would otherwise override the hidden text). Two separate keys
// rather than string concatenation so translations control the joiner.
- const statusTextNode =
- statusText != null ? <VisuallyHidden>{statusText}</VisuallyHidden> : null;
+ const statusTextNode = isRenderable(statusText) ? (
+ <VisuallyHidden>{statusText}</VisuallyHidden>
+ ) : null;
const stepAriaLabel =
statusText != null
? t('@astryx.step.goToStepWithStatus', {
@@ -906,12 +1181,6 @@ export function Step({
: t('@astryx.step.goToStep', {stepNumber: step + 1, label});
const hasIndicator = indicator !== 'none';
- const isNumber =
- hasIndicator &&
- customIcon == null &&
- statusGlyph == null &&
- (indicator === 'number' ||
- (indicator === 'auto' && progress === 'not-started'));
const labelColorStyle = isDisabled
? styles.labelDisabled
@@ -925,14 +1194,7 @@ export function Step({
const iconLabelNode = (
<div {...stylex.props(styles.iconLabelRow)}>
{indicatorNode}
- <span
- {...stylex.props(
- styles.label,
- labelColorStyle,
- collapseLabel && styles.labelCollapsible,
- )}>
- {label}
- </span>
+ <span {...stylex.props(styles.label, labelColorStyle)}>{label}</span>
{statusTextNode}
{isOptional && (
<>
@@ -946,33 +1208,29 @@ export function Step({
</div>
);
- const descriptionNode =
- description != null ? (
- <div
- {...stylex.props(
- hasIndicator
- ? isNumber
- ? styles.descriptionRowWithNumber
- : styles.descriptionRowWithIndicator
- : styles.descriptionRow,
- )}>
- <span {...stylex.props(styles.description)}>{description}</span>
- </div>
- ) : null;
-
- const contentNode =
- children != null ? (
- <div
- {...stylex.props(
- styles.stepContent,
- hasIndicator &&
- (isNumber
- ? styles.stepContentWithNumber
- : styles.stepContentWithIndicator),
- )}>
- {children}
- </div>
- ) : null;
+ const descriptionNode = isRenderable(description) ? (
+ <div
+ {...stylex.props(
+ hasIndicator
+ ? styles.descriptionRowWithIndicator
+ : styles.descriptionRow,
+ )}>
+ <span {...stylex.props(styles.description)}>{description}</span>
+ </div>
+ ) : null;
+
+ const contentNode = isRenderable(children) ? (
+ <div
+ {...stylex.props(
+ styles.stepContent,
+ styles.contentIndent(
+ separatedDensityInline,
+ hasIndicator ? INDICATOR_GUTTER : '0px',
+ ),
+ )}>
+ {children}
+ </div>
+ ) : null;
// Theme data attributes reflect progress + optional semantic status.
const stepThemeProps = themeProps('step', {
@@ -988,14 +1246,45 @@ export function Step({
// `status` never recolors the connector — only the indicator.
const beforeFilled = step <= activeStep;
const afterFilled = step < activeStep;
- const beforeSegStyle = beforeFilled
- ? styles.lineFilled
- : styles.lineUnfilled;
- const afterSegStyle = afterFilled ? styles.lineFilled : styles.lineUnfilled;
+ // Both segments animate their fill along the track (see connectorTrack), so
+ // the pair is picked by orientation: the vertical column scales down its
+ // block axis, the horizontal row along the reading direction.
+ const segFilledStyle = isVertical
+ ? styles.connectorFillV
+ : styles.connectorFillH;
+ const segEmptyStyle = isVertical
+ ? styles.connectorEmptyV
+ : styles.connectorEmptyH;
+ const beforeSegStyle = beforeFilled ? segFilledStyle : segEmptyStyle;
+ const afterSegStyle = afterFilled ? segFilledStyle : segEmptyStyle;
// First/last connector visibility is decided structurally from the step's
// own <li> position (see otSegHiddenIfFirst/Last), not by counting children
// in the parent — so grouping steps in a fragment can't break it.
+ // A node-to-node span is drawn by two steps: this one's trailing segments
+ // leave its own node, the next one's leading cap arrives at the next node.
+ // Both flip on the same condition, so left to themselves they fill together
+ // and one gap between two nodes reads as two dashes converging on the space
+ // between them. Handing each its own slice of the span's time, in track
+ // order — the leaving half first, then the arriving one — is what closes
+ // that into a single line growing.
+ const arrivalShare = isVertical ? OT_ARRIVAL_SHARE_V : OT_ARRIVAL_SHARE_H;
+ const leavingShare = 1 - arrivalShare;
+ // A content slot's segment continues the leaving half below the row, so the
+ // two divide the leaving time between them; with no slot the rail segment
+ // takes all of it. Each step can work this out for its own trailing side
+ // alone: the arriving cap always takes the span's last `arrivalShare`, so
+ // the step drawing it never has to know whether the step before it carries
+ // a slot.
+ const hasContentSeg = isVertical && isRenderable(children);
+ const railShare =
+ leavingShare * (hasContentSeg ? OT_RAIL_SHARE_OF_LEAVING : 1);
+ const contentShare = leavingShare - railShare;
+
+ const beforeTiming = fillTiming(step - 1, leavingShare, arrivalShare);
+ const railTiming = fillTiming(step, 0, railShare);
+ const contentTiming = fillTiming(step, railShare, contentShare);
+
const densitySpace =
density === 'compact'
? spacingVars['--spacing-1']
@@ -1008,14 +1297,7 @@ export function Step({
{...stylex.props(
isVertical ? styles.otLabelRowStart : styles.otLabelRowCenter,
)}>
- <span
- {...stylex.props(
- styles.label,
- labelColorStyle,
- collapseLabel && styles.labelCollapsible,
- )}>
- {label}
- </span>
+ <span {...stylex.props(styles.label, labelColorStyle)}>{label}</span>
{statusTextNode}
{isOptional && (
<>
@@ -1029,18 +1311,41 @@ export function Step({
</div>
);
- const otDescriptionNode =
- description != null ? (
- <span {...stylex.props(styles.description)}>{description}</span>
- ) : null;
+ const otDescriptionNode = isRenderable(description) ? (
+ <span {...stylex.props(styles.description)}>{description}</span>
+ ) : null;
- const otContentNode =
- children != null ? (
+ const otContentNode = !isRenderable(children) ? null : isVertical ? (
+ <div {...stylex.props(styles.otContentWrapV)}>
+ <div
+ aria-hidden="true"
+ {...mergeProps(
+ themeProps('step-connector'),
+ stylex.props(
+ // connectorTrack first: it declares `position: relative` to
+ // anchor its fill layer, but this segment is absolutely placed
+ // on the rail beside the content slot and must keep that. An
+ // absolute box is a containing block too, so the fill still
+ // pins to it.
+ styles.connectorTrack,
+ styles.otContentSegV(densitySpace),
+ afterSegStyle,
+ contentTiming,
+ styles.otSegHiddenIfLast,
+ ),
+ )}
+ />
<div
- {...stylex.props(isVertical ? styles.otContentV : styles.otContentH)}>
+ {...stylex.props(
+ styles.otContent,
+ styles.contentIndent(densitySpace, INDICATOR_GUTTER),
+ )}>
{children}
</div>
- ) : null;
+ </div>
+ ) : (
+ <div {...stylex.props(styles.otContent)}>{children}</div>
+ );
if (isVertical) {
const inner = (
@@ -1057,7 +1362,9 @@ export function Step({
stylex.props(
styles.otSegBaseV,
styles.otSegLeadV(densitySpace),
+ styles.connectorTrack,
beforeSegStyle,
+ beforeTiming,
styles.otSegHiddenIfFirst,
),
)}
@@ -1070,7 +1377,9 @@ export function Step({
stylex.props(
styles.otSegBaseV,
styles.otSegFlexV,
+ styles.connectorTrack,
afterSegStyle,
+ railTiming,
styles.otSegHiddenIfLast,
),
)}
@@ -1132,7 +1441,9 @@ export function Step({
themeProps('step-connector'),
stylex.props(
styles.otSegH,
+ styles.connectorTrack,
beforeSegStyle,
+ beforeTiming,
styles.otSegHiddenIfFirst,
),
)}
@@ -1144,7 +1455,9 @@ export function Step({
themeProps('step-connector'),
stylex.props(
styles.otSegH,
+ styles.connectorTrack,
afterSegStyle,
+ railTiming,
styles.otSegHiddenIfLast,
),
)}
@@ -1220,7 +1533,9 @@ export function Step({
themeProps('step-bar'),
stylex.props(
styles.verticalBar,
- isBarFilled ? styles.barCompleted : styles.barIncomplete,
+ styles.connectorTrack,
+ isBarFilled ? styles.connectorFillV : styles.connectorEmptyV,
+ barTiming,
),
)}
aria-hidden="true"
@@ -1238,6 +1553,7 @@ export function Step({
density === 'compact' && styles.densityCompact,
density === 'balanced' && styles.densityBalanced,
density === 'spacious' && styles.densitySpacious,
+ styles.densityInline(separatedDensityInline),
)}>
{iconLabelNode}
{descriptionNode}
@@ -1248,6 +1564,7 @@ export function Step({
density === 'compact' && styles.densityCompact,
density === 'balanced' && styles.densityBalanced,
density === 'spacious' && styles.densitySpacious,
+ styles.densityInline(separatedDensityInline),
)}>
{iconLabelNode}
{descriptionNode}
@@ -1278,7 +1595,9 @@ export function Step({
themeProps('step-bar'),
stylex.props(
styles.horizontalBar,
- isBarFilled ? styles.barCompleted : styles.barIncomplete,
+ styles.connectorTrack,
+ isBarFilled ? styles.connectorFillH : styles.connectorEmptyH,
+ barTiming,
),
)}
aria-hidden="true"
@@ -1294,6 +1613,7 @@ export function Step({
density === 'compact' && styles.densityCompact,
density === 'balanced' && styles.densityBalanced,
density === 'spacious' && styles.densitySpacious,
+ styles.densityInline(separatedDensityInline),
)}>
{iconLabelNode}
{descriptionNode}
@@ -1304,6 +1624,7 @@ export function Step({
density === 'compact' && styles.densityCompact,
density === 'balanced' && styles.densityBalanced,
density === 'spacious' && styles.densitySpacious,
+ styles.densityInline(separatedDensityInline),
)}>
{iconLabelNode}
{descriptionNode}
diff --git a/packages/lab/src/Stepper/StepStatus.ts b/packages/core/src/Stepper/StepStatus.ts
similarity index 100%
rename from packages/lab/src/Stepper/StepStatus.ts
rename to packages/core/src/Stepper/StepStatus.ts
diff --git a/packages/core/src/Stepper/Stepper.doc.mjs b/packages/core/src/Stepper/Stepper.doc.mjs
new file mode 100644
index 0000000000..9a397ea0b0
--- /dev/null
+++ b/packages/core/src/Stepper/Stepper.doc.mjs
@@ -0,0 +1,370 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
+
+export const docs = {
+ name: 'Stepper',
+ displayName: 'Stepper',
+ category: 'Navigation',
+ group: 'Stepper',
+ keywords: [
+ 'stepper',
+ 'steps',
+ 'wizard',
+ 'workflow',
+ 'progress',
+ 'multi-step',
+ 'form wizard',
+ 'onboarding',
+ ],
+ usage: {
+ description:
+ 'Steppers display progress through a sequence of logical and numbered steps. Use them for multi-step workflows like forms, onboarding flows, or checkout processes where users need to see their position and the steps ahead. Rendered as an ordered list (not a navigation landmark).',
+ bestPractices: [
+ {
+ guidance: true,
+ description:
+ 'Keep step labels short and descriptive: "Payment" not "Enter your payment information".',
+ },
+ {
+ guidance: true,
+ description:
+ 'Use the vertical orientation for narrow containers or when steps have longer descriptions.',
+ },
+ {
+ guidance: true,
+ description:
+ 'Provide onStepClick for non-linear workflows where users may need to revisit earlier steps.',
+ },
+ {
+ guidance: true,
+ description:
+ 'Use status only to apply a semantic color (accent/success/warning/error); pass a custom icon for richer indicators.',
+ },
+ {
+ guidance: false,
+ description:
+ 'Use a stepper for fewer than 3 steps; a simple heading or progress bar works better.',
+ },
+ {
+ guidance: false,
+ description:
+ 'Use more than 7 steps; consider grouping related steps or using a different pattern.',
+ },
+ ],
+ anatomy: [
+ {
+ name: 'Progress bar',
+ required: true,
+ description:
+ 'A 4px segmented bar per step. Filled for completed and active steps. Advancing one step grows the fill along the track it just covered, so the movement reads as progress rather than a bar changing color. Every other change applies at once: going back, jumping forward by more than one step, mounting mid-flow, and any change at all under prefers-reduced-motion. Where a span is drawn by more than one segment — the on-track layouts split it between two steps, three when a content slot sits between them — the segments run in track order at one constant speed, so the fill reads as a single line growing rather than pieces lighting in turn.',
+ },
+ {
+ name: 'Indicator',
+ required: false,
+ description:
+ 'A numbered badge, a check, or any custom icon. Controlled via the indicator prop.',
+ },
+ {
+ name: 'Label',
+ required: true,
+ description: 'Text identifying the step.',
+ },
+ {
+ name: 'Description',
+ required: false,
+ description: 'Supporting text below the label with additional context.',
+ },
+ ],
+ },
+ theming: {
+ targets: [
+ {
+ className: 'astryx-stepper',
+ visualProps: ['orientation', 'indicatorPosition'],
+ },
+ {className: 'astryx-step', visualProps: ['progress', 'status']},
+ {className: 'astryx-step-indicator', visualProps: ['progress', 'status']},
+ {className: 'astryx-step-bar'},
+ {className: 'astryx-step-connector'},
+ ],
+ },
+ components: [
+ {
+ name: 'Stepper',
+ displayName: 'Stepper',
+ description:
+ 'Container component that manages step state and renders steps in horizontal or vertical orientation as an ordered list.',
+ props: [
+ {
+ name: 'activeStep',
+ type: 'number',
+ description:
+ 'Zero-based index of the currently active step. Steps before this index are marked as completed.',
+ required: true,
+ },
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'Step elements to render in the stepper.',
+ required: true,
+ },
+ {
+ name: 'orientation',
+ type: "'horizontal' | 'vertical'",
+ description: 'Layout direction of the stepper.',
+ default: "'horizontal'",
+ },
+ {
+ name: 'onStepClick',
+ type: '(index: number) => void',
+ description:
+ 'Called when a step is clicked. Enables non-linear navigation. All non-disabled steps become clickable, including not-started steps.',
+ },
+ {
+ name: 'label',
+ type: 'string',
+ description:
+ 'Accessible label describing the set of steps (applied to the ordered list). Defaults to a localized "Progress".',
+ default: "'Progress' (localized)",
+ },
+ {
+ name: 'density',
+ type: "'compact' | 'balanced' | 'spacious'",
+ description: 'Controls the padding of all steps.',
+ default: "'balanced'",
+ },
+ {
+ name: 'indicatorPosition',
+ type: "'separated' | 'on-track'",
+ description:
+ 'Position of step indicators relative to the connector track.',
+ default: "'separated'",
+ },
+ {
+ name: 'xstyle',
+ type: 'StyleXStyles',
+ description:
+ 'StyleX styles for layout customization. Must be a stylex.create() value.',
+ },
+ ],
+ },
+ {
+ // Name-only cross-reference. Step's full documentation (description,
+ // props) lives in Step.doc.mjs as a `subComponentOf: 'Stepper'` doc, so
+ // it is emitted once from there and skipped here to avoid double emission.
+ name: 'Step',
+ },
+ ],
+ // A Stepper draws nothing on its own — every bar, indicator, and label comes
+ // from its Steps — so without seeded children the preview opens on an empty
+ // stage and the orientation/density/indicator knobs have nothing to act on.
+ // Three steps is the smallest set that shows all three progress states at
+ // once: completed, current, and upcoming.
+ playground: {
+ defaults: {
+ activeStep: 1,
+ children: [
+ {__element: 'Step', props: {step: 0, label: 'Cart'}},
+ {__element: 'Step', props: {step: 1, label: 'Shipping'}},
+ {__element: 'Step', props: {step: 2, label: 'Payment'}},
+ ],
+ },
+ },
+};
+
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
+export const docsDense = {
+ description: 'numbered step sequence for multi-step workflows',
+ usage: {
+ description:
+ 'Steppers show progress through numbered steps. Use for forms, onboarding, checkout.',
+ bestPractices: [
+ {
+ guidance: true,
+ description:
+ 'Keep step labels short. Use vertical in narrow containers.',
+ },
+ {
+ guidance: true,
+ description: 'Provide onStepClick for non-linear workflows.',
+ },
+ {
+ guidance: false,
+ description: 'Use for fewer than 3 or more than 7 steps.',
+ },
+ ],
+ },
+ components: [
+ {
+ name: 'Stepper',
+ displayName: 'Stepper',
+ description:
+ 'container managing step state w/ horizontal/vertical layout',
+ propDescriptions: {
+ activeStep: 'zero-based active step index',
+ children: 'Step elements',
+ orientation: 'horizontal or vertical layout',
+ onStepClick: 'enables non-linear navigation',
+ label: 'ordered-list aria-label',
+ density: 'padding of all steps',
+ xstyle: 'StyleX layout customization',
+ },
+ },
+ {
+ name: 'Step',
+ displayName: 'Step',
+ description: 'individual step w/ progress bar, indicator, label',
+ propDescriptions: {
+ step: 'zero-based step index',
+ label: 'step label text',
+ description: 'supporting text below label',
+ status: 'semantic color: accent/success/warning/error (color only)',
+ indicator: "'auto' | 'number' | 'none' | custom node",
+ isDisabled: 'disable interaction',
+ isOptional: 'append Optional affordance',
+ endContent: 'trailing content in label row',
+ density: 'per-step padding override',
+ },
+ },
+ ],
+};
+
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
+export const docsZh = {
+ name: 'Stepper',
+ displayName: 'Stepper',
+ group: 'Stepper',
+ usage: {
+ description:
+ '步骤器显示通过一系列逻辑编号步骤的进度。用于多步骤工作流程,如表单、入职流程或结账流程。',
+ bestPractices: [
+ {guidance: true, description: '保持步骤标签简短和描述性。'},
+ {
+ guidance: true,
+ description: '在窄容器中使用垂直方向,或当步骤有较长描述时。',
+ },
+ {guidance: true, description: '为非线性工作流程提供 onStepClick。'},
+ {guidance: false, description: '少于3个步骤时使用步骤器。'},
+ {guidance: false, description: '超过7个步骤时使用步骤器。'},
+ ],
+ },
+ theming: {
+ targets: [
+ {
+ className: 'astryx-stepper',
+ visualProps: ['orientation', 'indicatorPosition'],
+ },
+ {className: 'astryx-step', visualProps: ['progress', 'status']},
+ {className: 'astryx-step-indicator', visualProps: ['progress', 'status']},
+ {className: 'astryx-step-bar'},
+ {className: 'astryx-step-connector'},
+ ],
+ },
+ components: [
+ {
+ name: 'Stepper',
+ displayName: 'Stepper',
+ description: '容器组件,管理步骤状态并以水平或垂直方向渲染步骤。',
+ props: [
+ {
+ name: 'activeStep',
+ type: 'number',
+ description: '当前活动步骤的从零开始的索引。',
+ required: true,
+ },
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: '要在步骤器中渲染的 Step 元素。',
+ required: true,
+ },
+ {
+ name: 'orientation',
+ type: "'horizontal' | 'vertical'",
+ description: '步骤器的布局方向。',
+ default: "'horizontal'",
+ },
+ {
+ name: 'onStepClick',
+ type: '(index: number) => void',
+ description: '点击步骤时调用。启用非线性导航。',
+ },
+ {
+ name: 'label',
+ type: 'string',
+ description: '有序列表的无障碍标签。',
+ default: "'Progress'(本地化)",
+ },
+ {
+ name: 'density',
+ type: "'compact' | 'balanced' | 'spacious'",
+ description: '控制所有步骤的内边距。',
+ default: "'balanced'",
+ },
+ {
+ name: 'xstyle',
+ type: 'StyleXStyles',
+ description: '用于布局自定义的 StyleX 样式。',
+ },
+ ],
+ },
+ {
+ name: 'Step',
+ displayName: 'Step',
+ description: '步骤器中的单个步骤。渲染进度条、指示器和带可选描述的标签。',
+ props: [
+ {
+ name: 'step',
+ type: 'number',
+ description: '此步骤的从零开始的索引。',
+ required: true,
+ },
+ {
+ name: 'label',
+ type: 'string',
+ description: '步骤标签文本。',
+ required: true,
+ },
+ {
+ name: 'description',
+ type: 'string',
+ description: '标签下方的可选描述。',
+ },
+ {
+ name: 'status',
+ type: "'accent' | 'success' | 'warning' | 'error'",
+ description: '步骤的语义颜色,仅控制颜色。',
+ },
+ {
+ name: 'indicator',
+ type: "'auto' | 'number' | 'none' | ReactNode",
+ description: '指示器显示内容。',
+ default: "'auto'",
+ },
+ {
+ name: 'isDisabled',
+ type: 'boolean',
+ description: '禁用交互并使步骤指示器和标签变暗。',
+ default: 'false',
+ },
+ {
+ name: 'isOptional',
+ type: 'boolean',
+ description: '标记步骤为可选。',
+ default: 'false',
+ },
+ {
+ name: 'endContent',
+ type: 'ReactNode',
+ description: '标签行末尾的尾随内容。',
+ },
+ {
+ name: 'density',
+ type: "'compact' | 'balanced' | 'spacious'",
+ description: '步骤的内边距覆盖。',
+ },
+ ],
+ },
+ ],
+};
diff --git a/packages/lab/src/Stepper/Stepper.test.tsx b/packages/core/src/Stepper/Stepper.test.tsx
similarity index 60%
rename from packages/lab/src/Stepper/Stepper.test.tsx
rename to packages/core/src/Stepper/Stepper.test.tsx
index afad248670..1782cd9b6e 100644
--- a/packages/lab/src/Stepper/Stepper.test.tsx
+++ b/packages/core/src/Stepper/Stepper.test.tsx
@@ -1,5 +1,6 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
+import {StrictMode} from 'react';
import {describe, it, expect, vi} from 'vitest';
import {render, screen, within} from '@testing-library/react';
import userEvent from '@testing-library/user-event';
@@ -326,13 +327,13 @@ describe('Stepper', () => {
expect(screen.getByText('★')).toBeInTheDocument();
});
- it('accepts a generic icon via the icon prop', () => {
+ it('accepts a ReactNode as indicator', () => {
render(
<Stepper activeStep={1}>
<Step
step={1}
label="Payment"
- icon={<span data-testid="pay-icon">$</span>}
+ indicator={<span data-testid="pay-icon">$</span>}
/>
</Stepper>,
);
@@ -510,6 +511,34 @@ describe('Stepper', () => {
).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();
@@ -652,48 +681,344 @@ describe('Stepper', () => {
});
});
- describe('hasCollapsibleLabels', () => {
- // The collapse is a container query, so jsdom can't evaluate the media
- // condition — assert the opt-in wiring instead: the collapsible class is
- // applied to non-current horizontal step labels and withheld from the
- // current step and from every step when the prop is off / vertical.
- const labelEl = (testid: string) =>
+ // 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('span[class*="label"]') as HTMLElement;
+ .getByTestId(testId)
+ .querySelector('[class*="connectorTrack"]') as HTMLElement;
- it('marks non-current horizontal step labels collapsible, but not the current one', () => {
+ it('scales the separated bar along the inline axis when horizontal', () => {
render(
- <Stepper activeStep={1} orientation="horizontal" hasCollapsibleLabels>
+ <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>,
);
- expect(labelEl('a').className).toContain('labelCollapsible');
- expect(labelEl('c').className).toContain('labelCollapsible');
- // The current step keeps its label unconditionally.
- expect(labelEl('b').className).not.toContain('labelCollapsible');
+ // 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('does not collapse labels when the prop is off', () => {
+ it('scales the separated bar along the block axis when vertical', () => {
render(
- <Stepper activeStep={1} orientation="horizontal">
+ <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(labelEl('a').className).not.toContain('labelCollapsible');
+ expect(barEl('a').className).toContain('connectorFillV');
+ expect(barEl('c').className).toContain('connectorEmptyV');
+ expect(barEl('c').className).not.toContain('connectorEmptyH');
});
- it('does not collapse labels in the vertical orientation', () => {
+ it('gives every on-track segment the track style and its axis pair', () => {
render(
- <Stepper activeStep={1} orientation="vertical" hasCollapsibleLabels>
+ <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>,
);
- expect(labelEl('a').className).not.toContain('labelCollapsible');
+ // 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);
});
});
});
diff --git a/packages/lab/src/Stepper/Stepper.tsx b/packages/core/src/Stepper/Stepper.tsx
similarity index 57%
rename from packages/lab/src/Stepper/Stepper.tsx
rename to packages/core/src/Stepper/Stepper.tsx
index 18b0951641..e8a3d432b8 100644
--- a/packages/lab/src/Stepper/Stepper.tsx
+++ b/packages/core/src/Stepper/Stepper.tsx
@@ -8,21 +8,27 @@
* @output Exports Stepper component and StepperProps
* @position Core container component; consumed by index.ts
*
+ * Besides the props it is given, this component tracks the `activeStep` it
+ * last rendered with and publishes it on the context. Steps need the distance
+ * and direction of a change to choreograph their connector fill; see the
+ * CONNECTOR FILL block in Step.tsx.
+ *
* SYNC: When modified, update these files to stay in sync:
- * - /packages/lab/src/Stepper/Stepper.doc.mjs (props table, features, implementation notes)
- * - /packages/lab/src/Stepper/Stepper.test.tsx (tests for new/changed behavior)
- * - /packages/lab/src/Stepper/index.ts (exports if types change)
+ * - /packages/core/src/Stepper/Stepper.doc.mjs (props table, features, implementation notes)
+ * - /packages/core/src/Stepper/Stepper.test.tsx (tests for new/changed behavior)
+ * - /packages/core/src/Stepper/index.ts (exports if types change)
* - /apps/storybook/stories/Stepper.stories.tsx (storybook stories)
* - /packages/cli/assets/templates/blocks/components/Stepper/ (showcase blocks)
*/
-import {useMemo, type ReactNode} from 'react';
+import {useCallback, useMemo, useRef, useState, type ReactNode} from 'react';
import * as stylex from '@stylexjs/stylex';
-import {spacingVars} from '@astryxdesign/core/theme/tokens.stylex';
-import {mergeProps} from '@astryxdesign/core/utils';
-import type {BaseProps} from '@astryxdesign/core';
-import {themeProps} from '@astryxdesign/core/utils';
+import {spacingVars} from '../theme/tokens.stylex';
+import {mergeProps} from '../utils';
+import type {BaseProps} from '../BaseProps';
+import {themeProps} from '../utils';
+import {useTranslator} from '../i18n';
import {
StepperContext,
type StepperOrientation,
@@ -52,8 +58,8 @@ export interface StepperProps extends BaseProps<HTMLOListElement> {
*/
onStepClick?: (index: number) => void;
/**
- * Accessible label describing the set of steps.
- * @default 'Progress'
+ * Accessible label describing the set of steps. Defaults to a translated
+ * "Progress" when unset.
*/
label?: string;
/**
@@ -70,16 +76,6 @@ export interface StepperProps extends BaseProps<HTMLOListElement> {
* @default 'separated'
*/
indicatorPosition?: StepperIndicatorPosition;
- /**
- * Horizontal only. When the stepper gets too narrow to fit every label,
- * collapse the labels of non-current steps so the track can shrink — only
- * the current step keeps its visible label (the rest stay reachable via
- * `aria-current` and the accessible names). Uses a container query, so it
- * responds to the stepper's own width, not the viewport. No effect in the
- * vertical orientation, where width is not the constraint.
- * @default false
- */
- hasCollapsibleLabels?: boolean;
}
const styles = stylex.create({
@@ -110,13 +106,6 @@ const styles = stylex.create({
flexDirection: 'column',
gap: 0,
},
- // Establishes the stepper as an inline-size container so each step's label
- // can collapse via a container query when the stepper (not the viewport) is
- // too narrow. Named so the child @container rules target this element only.
- labelCollapseContainer: {
- containerType: 'inline-size',
- containerName: 'astryx-stepper',
- },
});
/**
@@ -150,33 +139,89 @@ export function Stepper({
children,
orientation = 'horizontal',
onStepClick,
- label = 'Progress',
+ label: labelFromProps,
density = 'balanced',
indicatorPosition = 'separated',
- hasCollapsibleLabels = false,
xstyle,
className,
style,
ref,
...rest
}: StepperProps) {
+ const t = useTranslator();
+ const label = labelFromProps ?? t('@astryx.stepper.label');
+
+ // Dev-mode duplicate step index detection. Steps register on mount and
+ // deregister on unmount; a Map tracks count per index so we can warn when
+ // two Steps share the same `step` value (which breaks aria-current).
+ const stepCountsRef = useRef<Map<number, number>>(new Map());
+ const registerStep = useCallback((index: number) => {
+ const counts = stepCountsRef.current;
+ const prev = counts.get(index) ?? 0;
+ counts.set(index, prev + 1);
+ if (process.env.NODE_ENV !== 'production' && prev + 1 > 1) {
+ console.warn(
+ `[Stepper] Duplicate step index ${index}: two <Step> elements share the same \`step\` value. ` +
+ `This breaks \`aria-current="step"\` and causes both to show as active simultaneously.`,
+ );
+ }
+ return () => {
+ const cur = counts.get(index) ?? 1;
+ if (cur <= 1) {
+ counts.delete(index);
+ } else {
+ counts.set(index, cur - 1);
+ }
+ };
+ }, []);
+
+ // The step we came *from*. Steps need it to stagger their connector fill:
+ // the distance and direction of the change decide which segment moves first
+ // and how long the whole sweep may take (see Step.tsx's CONNECTOR FILL).
+ //
+ // Derived during render from state rather than written in an effect. An
+ // effect runs after paint, so the browser would already have committed the
+ // new fill states with last render's delays — the first frame of the sweep
+ // would be wrong, and on a jump of one that is the entire animation. React
+ // discards and re-runs a render that sets its own state before committing,
+ // so this costs a re-render but never a wrong frame.
+ //
+ // Seeding both halves from the current `activeStep` is what suppresses the
+ // cascade on mount: a stepper that opens on step 3 has no previous step to
+ // have travelled from, so its completed segments paint filled at once. That
+ // also makes the first render pure and identical on the server, so there is
+ // nothing for hydration to disagree about. Storing the pair in one state
+ // object keeps the update idempotent under StrictMode's double render — both
+ // invocations read the same `seen` and queue the same successor.
+ const [seen, setSeen] = useState(() => ({
+ current: activeStep,
+ previous: activeStep,
+ }));
+ if (seen.current !== activeStep) {
+ setSeen({current: activeStep, previous: seen.current});
+ }
+ const previousActiveStep =
+ seen.current === activeStep ? seen.previous : seen.current;
+
const ctxValue = useMemo<StepperContextValue>(
() => ({
activeStep,
+ previousActiveStep,
orientation,
isNonLinear: onStepClick != null,
onStepClick: onStepClick ?? null,
density,
indicatorPosition,
- hasCollapsibleLabels,
+ registerStep,
}),
[
activeStep,
+ previousActiveStep,
orientation,
onStepClick,
density,
indicatorPosition,
- hasCollapsibleLabels,
+ registerStep,
],
);
@@ -190,10 +235,6 @@ export function Stepper({
? styles.verticalOnTrack
: styles.vertical;
- // Label collapse is a width constraint, so it only applies to the horizontal
- // orientation; vertical steppers are never width-limited this way.
- const isLabelCollapse = hasCollapsibleLabels && orientation === 'horizontal';
-
return (
<StepperContext value={ctxValue}>
<ol
@@ -202,12 +243,7 @@ export function Stepper({
{...rest}
{...mergeProps(
themeProps('stepper', {orientation, indicatorPosition}),
- stylex.props(
- styles.root,
- orientationStyle,
- isLabelCollapse && styles.labelCollapseContainer,
- xstyle,
- ),
+ stylex.props(styles.root, orientationStyle, xstyle),
className,
style,
)}>
diff --git a/packages/lab/src/Stepper/StepperContext.ts b/packages/core/src/Stepper/StepperContext.ts
similarity index 61%
rename from packages/lab/src/Stepper/StepperContext.ts
rename to packages/core/src/Stepper/StepperContext.ts
index 0ee8297039..831784d6e6 100644
--- a/packages/lab/src/Stepper/StepperContext.ts
+++ b/packages/core/src/Stepper/StepperContext.ts
@@ -9,8 +9,8 @@
* @position Context for Stepper <-> Step communication
*
* SYNC: When modified, update these files to stay in sync:
- * - /packages/lab/src/Stepper/Stepper.doc.mjs
- * - /packages/lab/src/Stepper/index.ts
+ * - /packages/core/src/Stepper/Stepper.doc.mjs
+ * - /packages/core/src/Stepper/index.ts
*/
import {createContext, use} from 'react';
@@ -30,17 +30,30 @@ export type StepperIndicatorPosition = 'separated' | 'on-track';
export interface StepperContextValue {
activeStep: number;
+ /**
+ * The `activeStep` this stepper last rendered with, so a Step can tell
+ * whether the change it is reacting to was a single step forward — the one
+ * change that animates the connector fill — and which span that change
+ * crossed (see the CONNECTOR FILL block in Step.tsx). Equal to `activeStep`
+ * on the first render, which is what keeps a stepper that mounts mid-flow
+ * from animating its way to the step it opened on.
+ *
+ * Internal: not part of the public API, and deliberately not a Stepper prop.
+ * When the connector animates is behaviour the stepper owns, not something a
+ * consumer configures.
+ */
+ previousActiveStep: number;
orientation: StepperOrientation;
isNonLinear: boolean;
onStepClick: ((index: number) => void) | null;
density: StepperDensity;
indicatorPosition: StepperIndicatorPosition;
/**
- * Horizontal only. When true, non-current step labels collapse via a
- * container query once the stepper is too narrow to fit them all, so the
- * track can shrink. The current step keeps its label.
+ * Dev-mode index registration. Each Step calls this on mount with its `step`
+ * index. The Stepper tracks the set and warns if two Steps share the same
+ * index. Returns a cleanup function to call on unmount.
*/
- hasCollapsibleLabels: boolean;
+ registerStep: (index: number) => () => void;
}
export const StepperContext = createContext<StepperContextValue | null>(null);
diff --git a/packages/lab/src/Stepper/index.ts b/packages/core/src/Stepper/index.ts
similarity index 94%
rename from packages/lab/src/Stepper/index.ts
rename to packages/core/src/Stepper/index.ts
index 80cf57b4c7..ca4e963c46 100644
--- a/packages/lab/src/Stepper/index.ts
+++ b/packages/core/src/Stepper/index.ts
@@ -12,6 +12,7 @@ export type {StepStatus} from './StepStatus';
export {useStepperContext} from './StepperContext';
export type {
+ StepperContextValue,
StepperOrientation,
StepperIndicatorPosition,
} from './StepperContext';
diff --git a/packages/lab/src/Stepper/stepper.stylex.ts b/packages/core/src/Stepper/stepper.stylex.ts
similarity index 100%
rename from packages/lab/src/Stepper/stepper.stylex.ts
rename to packages/core/src/Stepper/stepper.stylex.ts
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index 0d4ac73e5b..224cf8909a 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -55,6 +55,7 @@ export * from './NavIcon';
export * from './NavMenu';
export * from './Slider';
export * from './Stack';
+export * from './Stepper';
export * from './Switch';
export * from './DateInput';
export * from './DateTimeInput';
diff --git a/packages/lab/src/Stepper/Step.doc.mjs b/packages/lab/src/Stepper/Step.doc.mjs
deleted file mode 100644
index 80a2a9f97e..0000000000
--- a/packages/lab/src/Stepper/Step.doc.mjs
+++ /dev/null
@@ -1,17 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
-
-export const docs = {
- name: 'Step',
- displayName: 'Step',
- group: 'Stepper',
- category: 'Navigation',
- isHiddenFromOverview: true,
-
- usage: {
- description: '',
- },
-
- props: [],
-};
diff --git a/packages/lab/src/Stepper/Stepper.doc.mjs b/packages/lab/src/Stepper/Stepper.doc.mjs
deleted file mode 100644
index 29d3245fc0..0000000000
--- a/packages/lab/src/Stepper/Stepper.doc.mjs
+++ /dev/null
@@ -1,281 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
-
-export const docs = {
- name: 'Stepper',
- displayName: 'Stepper',
- category: 'Navigation',
- group: 'Stepper',
- keywords: ['stepper', 'steps', 'wizard', 'workflow', 'progress', 'multi-step', 'form wizard', 'onboarding'],
- usage: {
- description:
- 'Steppers display progress through a sequence of logical and numbered steps. Use them for multi-step workflows like forms, onboarding flows, or checkout processes where users need to see their position and the steps ahead. Rendered as an ordered list (not a navigation landmark).',
- bestPractices: [
- {guidance: true, description: 'Keep step labels short and descriptive: "Payment" not "Enter your payment information".'},
- {guidance: true, description: 'Use the vertical orientation for narrow containers or when steps have longer descriptions.'},
- {guidance: true, description: 'Provide onStepClick for non-linear workflows where users may need to revisit earlier steps.'},
- {guidance: true, description: 'Use status only to apply a semantic color (accent/success/warning/error); pass a custom icon for richer indicators.'},
- {guidance: false, description: 'Use a stepper for fewer than 3 steps; a simple heading or progress bar works better.'},
- {guidance: false, description: 'Use more than 7 steps; consider grouping related steps or using a different pattern.'},
- ],
- anatomy: [
- {name: 'Progress bar', required: true, description: 'A 4px segmented bar per step. Filled for completed and active steps.'},
- {name: 'Indicator', required: false, description: 'A numbered badge, a check, or any custom icon. Controlled via the indicator and icon props.'},
- {name: 'Label', required: true, description: 'Text identifying the step.'},
- {name: 'Description', required: false, description: 'Supporting text below the label with additional context.'},
- ],
- },
- theming: {
- targets: [
- {className: 'astryx-stepper', visualProps: ['orientation', 'indicatorPosition']},
- {className: 'astryx-step', visualProps: ['progress', 'status']},
- {className: 'astryx-step-indicator', visualProps: ['progress', 'status']},
- {className: 'astryx-step-bar'},
- {className: 'astryx-step-connector'},
- ],
- },
- components: [
- {
- name: 'Stepper',
- displayName: 'Stepper',
- description:
- 'Container component that manages step state and renders steps in horizontal or vertical orientation as an ordered list.',
- props: [
- {
- name: 'activeStep',
- type: 'number',
- description: 'Zero-based index of the currently active step. Steps before this index are marked as completed.',
- required: true,
- },
- {
- name: 'children',
- type: 'ReactNode',
- description: 'Step elements to render in the stepper.',
- required: true,
- },
- {
- name: 'orientation',
- type: "'horizontal' | 'vertical'",
- description: 'Layout direction of the stepper.',
- default: "'horizontal'",
- },
- {
- name: 'onStepClick',
- type: '(index: number) => void',
- description: 'Called when a step is clicked. Enables non-linear navigation. All non-disabled steps become clickable, including not-started steps.',
- },
- {
- name: 'label',
- type: 'string',
- description: 'Accessible label describing the set of steps (applied to the ordered list).',
- default: "'Progress'",
- },
- {
- name: 'density',
- type: "'compact' | 'balanced' | 'spacious'",
- description: 'Controls the padding of all steps.',
- default: "'balanced'",
- },
- {
- name: 'indicatorPosition',
- type: "'separated' | 'on-track'",
- description: 'Position of step indicators relative to the connector track.',
- default: "'separated'",
- },
- {
- name: 'hasCollapsibleLabels',
- type: 'boolean',
- description: 'Horizontal only. When the stepper is too narrow to fit every label, collapse the labels of non-current steps (via a container query) so the track can shrink; the current step keeps its label. Steps stay reachable via aria-current and their accessible names.',
- default: 'false',
- },
- {
- name: 'xstyle',
- type: 'StyleXStyles',
- description: 'StyleX styles for layout customization. Must be a stylex.create() value.',
- },
- ],
- },
- {
- name: 'Step',
- displayName: 'Step',
- description:
- 'Individual step within a stepper. Renders a progress-bar segment, an indicator, and a label with optional description.',
- props: [
- {
- name: 'step',
- type: 'number',
- description: 'Zero-based index of this step. Used to derive progress (completed/active/not-started) relative to the parent activeStep.',
- required: true,
- },
- {
- name: 'label',
- type: 'string',
- description: 'Step label text.',
- required: true,
- },
- {
- name: 'description',
- type: 'string',
- description: 'Optional description shown below the label for additional context.',
- },
- {
- name: 'children',
- type: 'ReactNode',
- description: 'Content rendered below the label and description. Useful in vertical steppers for form fields or detailed step content.',
- },
- {
- name: 'icon',
- type: 'ReactNode',
- description: 'Custom icon rendered inside the indicator. Accepts any node (e.g. an Icon). Takes precedence over the built-in number/check.',
- slotElements: [{__element: 'Icon', props: {icon: 'check', size: 'sm'}}],
- },
- {
- name: 'status',
- type: "'accent' | 'success' | 'warning' | 'error'",
- description: 'Semantic color for the step. Controls color only and maps to the global Astryx semantic tokens. Leave unset for the progress-derived default coloring.',
- },
- {
- name: 'indicator',
- type: "'auto' | 'number' | 'none' | ReactNode",
- description: "What to show as the step indicator. 'auto' shows a number until completed then a check, 'number' always shows a numbered badge, 'none' hides it, or pass any ReactNode for a custom indicator.",
- default: "'auto'",
- },
- {
- name: 'isDisabled',
- type: 'boolean',
- description: 'Disables interaction and dims the step indicator and label.',
- default: 'false',
- },
- {
- name: 'isOptional',
- type: 'boolean',
- description: 'Marks the step as optional, appending an "Optional" affordance after the label.',
- default: 'false',
- },
- {
- name: 'endContent',
- type: 'ReactNode',
- description: 'Trailing content rendered at the end of the label row.',
- },
- {
- name: 'density',
- type: "'compact' | 'balanced' | 'spacious'",
- description: 'Controls vertical padding of the step. Falls back to the stepper-level density when unset.',
- },
- ],
- },
- ],
- playground: {
- defaults: {
- activeStep: 1,
- },
- },
-};
-
-/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
-export const docsDense = {
- description: 'numbered step sequence for multi-step workflows',
- usage: {
- description:
- 'Steppers show progress through numbered steps. Use for forms, onboarding, checkout.',
- bestPractices: [
- {guidance: true, description: 'Keep step labels short. Use vertical in narrow containers.'},
- {guidance: true, description: 'Provide onStepClick for non-linear workflows.'},
- {guidance: false, description: 'Use for fewer than 3 or more than 7 steps.'},
- ],
- },
- components: [
- {
- name: 'Stepper',
- displayName: 'Stepper',
- description: 'container managing step state w/ horizontal/vertical layout',
- propDescriptions: {
- activeStep: 'zero-based active step index',
- children: 'Step elements',
- orientation: 'horizontal or vertical layout',
- onStepClick: 'enables non-linear navigation',
- label: 'ordered-list aria-label',
- density: 'padding of all steps',
- xstyle: 'StyleX layout customization',
- },
- },
- {
- name: 'Step',
- displayName: 'Step',
- description: 'individual step w/ progress bar, indicator, label',
- propDescriptions: {
- step: 'zero-based step index',
- label: 'step label text',
- description: 'supporting text below label',
- icon: 'custom icon for the indicator',
- status: 'semantic color: accent/success/warning/error (color only)',
- indicator: "'auto' | 'number' | 'none' | custom node",
- isDisabled: 'disable interaction',
- isOptional: 'append Optional affordance',
- endContent: 'trailing content in label row',
- density: 'per-step padding override',
- },
- },
- ],
-};
-
-/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
-export const docsZh = {
- name: 'Stepper',
- displayName: 'Stepper',
- group: 'Stepper',
- usage: {
- description:
- '步骤器显示通过一系列逻辑编号步骤的进度。用于多步骤工作流程,如表单、入职流程或结账流程。',
- bestPractices: [
- {guidance: true, description: '保持步骤标签简短和描述性。'},
- {guidance: true, description: '在窄容器中使用垂直方向,或当步骤有较长描述时。'},
- {guidance: true, description: '为非线性工作流程提供 onStepClick。'},
- {guidance: false, description: '少于3个步骤时使用步骤器。'},
- {guidance: false, description: '超过7个步骤时使用步骤器。'},
- ],
- },
- theming: {
- targets: [
- {className: 'astryx-stepper', visualProps: ['orientation', 'indicatorPosition']},
- {className: 'astryx-step', visualProps: ['progress', 'status']},
- {className: 'astryx-step-indicator', visualProps: ['progress', 'status']},
- {className: 'astryx-step-bar'},
- {className: 'astryx-step-connector'},
- ],
- },
- components: [
- {
- name: 'Stepper',
- displayName: 'Stepper',
- description: '容器组件,管理步骤状态并以水平或垂直方向渲染步骤。',
- props: [
- {name: 'activeStep', type: 'number', description: '当前活动步骤的从零开始的索引。', required: true},
- {name: 'children', type: 'ReactNode', description: '要在步骤器中渲染的 Step 元素。', required: true},
- {name: 'orientation', type: "'horizontal' | 'vertical'", description: '步骤器的布局方向。', default: "'horizontal'"},
- {name: 'onStepClick', type: '(index: number) => void', description: '点击步骤时调用。启用非线性导航。'},
- {name: 'label', type: 'string', description: '有序列表的无障碍标签。', default: "'Progress'"},
- {name: 'density', type: "'compact' | 'balanced' | 'spacious'", description: '控制所有步骤的内边距。', default: "'balanced'"},
- {name: 'xstyle', type: 'StyleXStyles', description: '用于布局自定义的 StyleX 样式。'},
- ],
- },
- {
- name: 'Step',
- displayName: 'Step',
- description: '步骤器中的单个步骤。渲染进度条、指示器和带可选描述的标签。',
- props: [
- {name: 'step', type: 'number', description: '此步骤的从零开始的索引。', required: true},
- {name: 'label', type: 'string', description: '步骤标签文本。', required: true},
- {name: 'description', type: 'string', description: '标签下方的可选描述。'},
- {name: 'icon', type: 'ReactNode', description: '指示器中的自定义图标。'},
- {name: 'status', type: "'accent' | 'success' | 'warning' | 'error'", description: '步骤的语义颜色,仅控制颜色。'},
- {name: 'indicator', type: "'auto' | 'number' | 'none' | ReactNode", description: '指示器显示内容。', default: "'auto'"},
- {name: 'isDisabled', type: 'boolean', description: '禁用交互并使步骤指示器和标签变暗。', default: 'false'},
- {name: 'isOptional', type: 'boolean', description: '标记步骤为可选。', default: 'false'},
- {name: 'endContent', type: 'ReactNode', description: '标签行末尾的尾随内容。'},
- {name: 'density', type: "'compact' | 'balanced' | 'spacious'", description: '步骤的内边距覆盖。'},
- ],
- },
- ],
-};
diff --git a/packages/lab/src/__tests__/labApiContractDrift.test.tsx b/packages/lab/src/__tests__/labApiContractDrift.test.tsx
index be43cf9a65..4293f8916e 100644
--- a/packages/lab/src/__tests__/labApiContractDrift.test.tsx
+++ b/packages/lab/src/__tests__/labApiContractDrift.test.tsx
@@ -5,7 +5,6 @@ import {describe, it, expect} from 'vitest';
import {docs as ChatReasoningDocs} from '../ChatReasoning/ChatReasoning.doc.mjs';
import {docs as CodeEditorDocs} from '../CodeEditor/CodeEditor.doc.mjs';
import {docs as LogStreamDocs} from '../LogStream/LogStream.doc.mjs';
-import {docs as StepperDocs} from '../Stepper/Stepper.doc.mjs';
function getProps(docs: Record<string, unknown>): Array<{name: string}> {
return (
@@ -49,9 +48,4 @@ describe('Lab API Contract Drift (#4163)', () => {
expect(props).toContain('hasTimestamps');
expect(props).toContain('renderEntry');
});
-
- it('documents Stepper indicatorPosition prop', () => {
- const props = getProps(StepperDocs).map(p => p.name);
- expect(props).toContain('indicatorPosition');
- });
});
diff --git a/packages/lab/src/index.ts b/packages/lab/src/index.ts
index f1006413d0..7c8e7cfbb1 100644
--- a/packages/lab/src/index.ts
+++ b/packages/lab/src/index.ts
@@ -240,7 +240,6 @@ export {
// Chart v2 (config model) moved to its own package: @astryxdesign/charts.
// It is no longer re-exported from @astryxdesign/lab.
-export * from './Stepper';
export * from './CircularProgress';
// ListInput — compact editor for short collections of simple records