Skip to content

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

TypeScript

fix(stepper): audit hardening — a11y, theming, responsive labels, docs blocks (#4917)

Ernest6b81ba60811e
diff --git a/apps/docsite/scripts/generate-data.mjs b/apps/docsite/scripts/generate-data.mjs
index 11187ccfda..6b002c23f2 100644
--- a/apps/docsite/scripts/generate-data.mjs
+++ b/apps/docsite/scripts/generate-data.mjs
@@ -1357,6 +1357,29 @@ ${body}
// ── 7. Showcase Registry ───────────────────────────────────────────────
+// Blocks are copied into the docsite and rendered via a live import, so they
+// can only reference packages the docsite actually depends on. A block for a
+// component whose package is not a docsite dependency (e.g. anything in
+// `@astryxdesign/lab`, which is canary-only and deliberately not installed
+// here) is authored and version-controlled in the CLI templates, but must be
+// skipped from the docsite's live preview until its package becomes resolvable
+// — otherwise `next build` fails on the unresolved import. The block source is
+// still shown as code; it just has no rendered preview until, for example, the
+// component is promoted to core.
+const _docsiteDeps = (() => {
+ const pkg = JSON.parse(
+ fs.readFileSync(path.join(DOCSITE_ROOT, 'package.json'), 'utf-8'),
+ );
+ return {...pkg.dependencies, ...pkg.devDependencies};
+})();
+
+function importsPackageMissingFromDocsite(tsxSource) {
+ const imports = [
+ ...tsxSource.matchAll(/from\s+['"](@astryxdesign\/[^'"/]+)/g),
+ ].map(m => m[1]);
+ return imports.some(pkg => _docsiteDeps[pkg] == null);
+}
+
function generateShowcaseRegistry() {
console.log('Generating showcase registry...');
@@ -1384,6 +1407,15 @@ function generateShowcaseRegistry() {
const tsxSrc = path.join(path.dirname(docPath), basename + '.tsx');
if (!fs.existsSync(tsxSrc)) continue;
+ // Skip blocks that reference a package the docsite cannot resolve.
+ const tsxContent = fs.readFileSync(tsxSrc, 'utf-8');
+ if (importsPackageMissingFromDocsite(tsxContent)) {
+ console.log(
+ ` skipping showcase ${basename} — imports a package not installed in the docsite`,
+ );
+ continue;
+ }
+
const alsoShowcaseFor = extractStringArrayField(content, 'alsoShowcaseFor');
if (isShowcase) {
@@ -1468,6 +1500,17 @@ function generateExampleRegistry() {
let source = '';
try { source = fs.readFileSync(tsxSrc, 'utf-8'); } catch { /* ignore */ }
+ // Skip live-preview entries for blocks the docsite cannot resolve — they'd
+ // break `next build`. The block's code is still shown via the block
+ // registry; only the rendered preview is withheld until the package is a
+ // docsite dependency.
+ if (importsPackageMissingFromDocsite(source)) {
+ console.log(
+ ` skipping example ${basename} — imports a package not installed in the docsite`,
+ );
+ continue;
+ }
+
const alsoExampleFor = extractStringArrayField(content, 'alsoExampleFor');
if (!isShowcase) {
diff --git a/apps/storybook/stories/Stepper.stories.tsx b/apps/storybook/stories/Stepper.stories.tsx
index 26d592ca87..d2c689036f 100644
--- a/apps/storybook/stories/Stepper.stories.tsx
+++ b/apps/storybook/stories/Stepper.stories.tsx
@@ -1,12 +1,14 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
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 {TextInput} from '@astryxdesign/core/TextInput';
import {Button} from '@astryxdesign/core/Button';
import {Text} from '@astryxdesign/core/Text';
import {Icon} from '@astryxdesign/core/Icon';
+import {Badge} from '@astryxdesign/core/Badge';
const meta: Meta<typeof Stepper> = {
title: 'Lab/Stepper',
@@ -917,3 +919,136 @@ export const OnTrackHorizontalManySteps: Story = {
);
},
};
+
+// ============================================================
+// SLOTS & CUSTOMIZATION
+// ============================================================
+
+export const EndContent: Story = {
+ name: 'Slots — endContent (trailing badges)',
+ render: () => {
+ const [active, setActive] = useState(2);
+ return (
+ <div style={{maxWidth: 440}}>
+ <Stepper
+ activeStep={active}
+ orientation="vertical"
+ onStepClick={setActive}>
+ <Step
+ step={0}
+ label="Draft"
+ description="Written 2 days ago"
+ endContent={<Badge variant="success" label="Done" />}
+ />
+ <Step
+ step={1}
+ label="Review"
+ description="2 approvals required"
+ endContent={<Badge variant="info" label="2 pending" />}
+ />
+ <Step
+ step={2}
+ label="Publish"
+ description="Scheduled for Monday"
+ endContent={<Badge variant="warning" label="Blocked" />}
+ />
+ <Step step={3} label="Archive" />
+ </Stepper>
+ </div>
+ );
+ },
+};
+
+const xstyles = stylex.create({
+ padded: {
+ padding: 24,
+ borderWidth: 1,
+ borderStyle: 'solid',
+ borderColor: 'var(--color-border)',
+ borderRadius: 'var(--radius-container)',
+ },
+});
+
+export const CustomXStyle: Story = {
+ name: 'Customization — xstyle + accessible label',
+ render: () => {
+ const [active, setActive] = useState(1);
+ return (
+ <div style={{maxWidth: 520}}>
+ <Stepper
+ activeStep={active}
+ orientation="horizontal"
+ onStepClick={setActive}
+ label="Checkout progress"
+ xstyle={xstyles.padded}>
+ <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="Confirm" indicator="number" />
+ </Stepper>
+ </div>
+ );
+ },
+};
+
+export const CollapseLabelsWhenNarrow: Story = {
+ name: 'Responsive — Collapse Labels When Narrow',
+ render: () => {
+ const [active, setActive] = useState(2);
+ 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>
+ </div>
+ <div>
+ <Text type="label">
+ Narrow (only the current step keeps its label)
+ </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>
+ </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
new file mode 100644
index 0000000000..ae176352c5
--- /dev/null
+++ b/packages/cli/assets/templates/blocks/components/Stepper/StepperHorizontal.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 — 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
new file mode 100644
index 0000000000..1148e3ca5f
--- /dev/null
+++ b/packages/cli/assets/templates/blocks/components/Stepper/StepperHorizontal.tsx
@@ -0,0 +1,24 @@
+// 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
new file mode 100644
index 0000000000..143f0d7d51
--- /dev/null
+++ b/packages/cli/assets/templates/blocks/components/Stepper/StepperIndicatorModes.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 — 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.',
+ 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
new file mode 100644
index 0000000000..0371d773bb
--- /dev/null
+++ b/packages/cli/assets/templates/blocks/components/Stepper/StepperIndicatorModes.tsx
@@ -0,0 +1,68 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useState} from 'react';
+import {Stepper, Step} from '@astryxdesign/lab';
+import {Text} from '@astryxdesign/core/Text';
+import {Icon} from '@astryxdesign/core/Icon';
+
+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">Auto</Text>
+ <Stepper
+ activeStep={active}
+ orientation="vertical"
+ onStepClick={setActive}>
+ <Step step={0} label="Account" />
+ <Step step={1} label="Profile" />
+ <Step step={2} label="Settings" />
+ <Step step={3} label="Review" />
+ </Stepper>
+ </div>
+ <div style={{maxWidth: 220}}>
+ <Text type="label">Number</Text>
+ <Stepper
+ activeStep={active}
+ orientation="vertical"
+ onStepClick={setActive}>
+ <Step step={0} label="Account" indicator="number" />
+ <Step step={1} label="Profile" indicator="number" />
+ <Step step={2} label="Settings" indicator="number" />
+ <Step step={3} label="Review" indicator="number" />
+ </Stepper>
+ </div>
+ <div style={{maxWidth: 220}}>
+ <Text type="label">Custom icon</Text>
+ <Stepper
+ activeStep={active}
+ orientation="vertical"
+ onStepClick={setActive}>
+ <Step
+ step={0}
+ label="Account"
+ icon={<Icon icon="info" size="sm" />}
+ />
+ <Step
+ step={1}
+ label="Profile"
+ icon={<Icon icon="search" size="sm" />}
+ />
+ <Step
+ step={2}
+ label="Settings"
+ icon={<Icon icon="wrench" size="sm" />}
+ />
+ <Step
+ step={3}
+ label="Review"
+ icon={<Icon icon="check" size="sm" />}
+ />
+ </Stepper>
+ </div>
+ </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
new file mode 100644
index 0000000000..ee0688e4f2
--- /dev/null
+++ b/packages/cli/assets/templates/blocks/components/Stepper/StepperMultiStepForm.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 — 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
new file mode 100644
index 0000000000..45f342cf33
--- /dev/null
+++ b/packages/cli/assets/templates/blocks/components/Stepper/StepperMultiStepForm.tsx
@@ -0,0 +1,92 @@
+// 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/StepperOnTrackVertical.doc.mjs b/packages/cli/assets/templates/blocks/components/Stepper/StepperOnTrackVertical.doc.mjs
new file mode 100644
index 0000000000..58a2b0a85b
--- /dev/null
+++ b/packages/cli/assets/templates/blocks/components/Stepper/StepperOnTrackVertical.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 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.',
+ isReady: true,
+ aspectRatio: 4 / 3,
+ componentsUsed: ['Stepper'],
+};
diff --git a/packages/cli/assets/templates/blocks/components/Stepper/StepperOnTrackVertical.tsx b/packages/cli/assets/templates/blocks/components/Stepper/StepperOnTrackVertical.tsx
new file mode 100644
index 0000000000..05c7fc32f5
--- /dev/null
+++ b/packages/cli/assets/templates/blocks/components/Stepper/StepperOnTrackVertical.tsx
@@ -0,0 +1,41 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useState} from 'react';
+import {Stepper, Step} from '@astryxdesign/lab';
+
+export default function StepperOnTrackVertical() {
+ const [active, setActive] = useState(2);
+ return (
+ <div style={{width: '100%', maxWidth: 400}}>
+ <Stepper
+ activeStep={active}
+ orientation="vertical"
+ indicatorPosition="on-track"
+ 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/cli/assets/templates/blocks/components/Stepper/StepperShowcase.doc.mjs b/packages/cli/assets/templates/blocks/components/Stepper/StepperShowcase.doc.mjs
new file mode 100644
index 0000000000..a6c33dea40
--- /dev/null
+++ b/packages/cli/assets/templates/blocks/components/Stepper/StepperShowcase.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: 'Stepper',
+ 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.',
+ isReady: true,
+ isShowcase: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['Stepper'],
+};
diff --git a/packages/cli/assets/templates/blocks/components/Stepper/StepperShowcase.tsx b/packages/cli/assets/templates/blocks/components/Stepper/StepperShowcase.tsx
new file mode 100644
index 0000000000..a5b334024d
--- /dev/null
+++ b/packages/cli/assets/templates/blocks/components/Stepper/StepperShowcase.tsx
@@ -0,0 +1,25 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useState} from 'react';
+import {Stepper, Step} from '@astryxdesign/lab';
+
+export default function StepperShowcase() {
+ const [active, setActive] = useState(2);
+ return (
+ <div style={{width: '100%', maxWidth: 640}}>
+ <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" />
+ </Stepper>
+ </div>
+ );
+}
diff --git a/packages/cli/assets/templates/blocks/components/Stepper/StepperStatus.doc.mjs b/packages/cli/assets/templates/blocks/components/Stepper/StepperStatus.doc.mjs
new file mode 100644
index 0000000000..1a35138c37
--- /dev/null
+++ b/packages/cli/assets/templates/blocks/components/Stepper/StepperStatus.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 — Validation Status',
+ displayName: 'Stepper — Validation Status',
+ description:
+ 'Semantic status per step in a verification flow: success shows a green check, error a red glyph, accent the in-progress step. Status sets the indicator color and glyph only — never the connector — and is announced to assistive tech as text.',
+ isReady: true,
+ aspectRatio: 4 / 3,
+ componentsUsed: ['Stepper'],
+};
diff --git a/packages/cli/assets/templates/blocks/components/Stepper/StepperStatus.tsx b/packages/cli/assets/templates/blocks/components/Stepper/StepperStatus.tsx
new file mode 100644
index 0000000000..76a149be34
--- /dev/null
+++ b/packages/cli/assets/templates/blocks/components/Stepper/StepperStatus.tsx
@@ -0,0 +1,50 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useState} from 'react';
+import {Stepper, Step} from '@astryxdesign/lab';
+
+export default function StepperStatus() {
+ const [active, setActive] = useState(3);
+ return (
+ <div style={{width: '100%', maxWidth: 400}}>
+ <Stepper
+ activeStep={active}
+ orientation="vertical"
+ onStepClick={setActive}>
+ <Step
+ step={0}
+ label="Email verified"
+ description="[email protected]"
+ status="success"
+ />
+ <Step
+ step={1}
+ label="Phone verified"
+ description="+1 (555) 012-3456"
+ status="success"
+ />
+ <Step
+ step={2}
+ label="Identity document"
+ description="Passport upload failed"
+ status="error"
+ />
+ <Step
+ step={3}
+ label="Address verification"
+ description="Pending review"
+ status="accent"
+ />
+ <Step
+ step={4}
+ label="Background check"
+ isOptional
+ description="Skipped"
+ />
+ <Step step={5} label="Account activated" />
+ </Stepper>
+ </div>
+ );
+}
diff --git a/packages/cli/assets/templates/blocks/components/Stepper/StepperVerticalOnboarding.doc.mjs b/packages/cli/assets/templates/blocks/components/Stepper/StepperVerticalOnboarding.doc.mjs
new file mode 100644
index 0000000000..7f51248742
--- /dev/null
+++ b/packages/cli/assets/templates/blocks/components/Stepper/StepperVerticalOnboarding.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 — 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
new file mode 100644
index 0000000000..3ebbda7e06
--- /dev/null
+++ b/packages/cli/assets/templates/blocks/components/Stepper/StepperVerticalOnboarding.tsx
@@ -0,0 +1,40 @@
+// 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/lab/src/Stepper/Step.tsx b/packages/lab/src/Stepper/Step.tsx
index dfe16d9733..bb046ed3ae 100644
--- a/packages/lab/src/Stepper/Step.tsx
+++ b/packages/lab/src/Stepper/Step.tsx
@@ -35,6 +35,7 @@ import {VisuallyHidden} from '@astryxdesign/core/VisuallyHidden';
import {useTranslator} from '@astryxdesign/core/i18n';
import {useStepperContext} from './StepperContext';
import {themeProps} from '@astryxdesign/core/utils';
+import {stepMarker} from './stepper.stylex';
import type {StepStatus} from './StepStatus';
/**
@@ -129,10 +130,26 @@ export interface StepProps extends BaseProps<HTMLLIElement> {
// --- Default progress icons (16px) ---
//
// The `completed` progress state and the current-step ring are drawn as local
-// glyphs: `completed` is a filled circle-check (a distinct "progress done"
-// mark), deliberately different from the semantic `success` status — which
-// defers to the themed Icon registry (an outline check). `warning` / `error`
-// statuses also defer to the themed registry so they share one visual language.
+// <svg> glyphs rather than sourced from the Icon registry. This is a deliberate
+// exception to the "glyphs come from the registry" convention (audit rule T17),
+// for two reasons:
+//
+// 1. `CurrentIcon` (a dot inside a ring) has no registry equivalent — it is a
+// progress affordance, not a general-purpose icon.
+// 2. `CheckCircleIcon` (a filled circle with a check) is intentionally NOT the
+// registry `success` glyph, even though the two look similar. They mean
+// different things and must stay independently restyleable: `completed`
+// marks *progress through the sequence* (every step you've passed), while
+// the semantic `success` status marks a step's *outcome*. A stepper can
+// show a completed step that also carries a `warning`/`error` status, so
+// collapsing the two glyphs would conflate progress with outcome. The
+// semantic `success`/`warning`/`error` STATUS glyphs DO defer to the themed
+// registry (see the status branch below), so those share one visual
+// language; only the progress marks are local.
+//
+// Both glyphs paint via `currentColor`, so the indicator's color is still
+// controlled by tokens on the wrapper (never hardcoded), and the wrapper
+// carries the `astryx-step-indicator` theme target.
/** Filled circle with a check — shown for a completed step in 'auto' mode. */
function CheckCircleIcon() {
@@ -270,9 +287,9 @@ const styles = stylex.create({
width: NUMBER_SIZE,
height: NUMBER_SIZE,
borderRadius: radiusVars['--radius-full'],
- // 10px is below the smallest type token (--text-supporting-size, 12px);
- // intentional micro-type for the compact 20px numeric badge.
- fontSize: '10px',
+ // 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',
fontWeight: fontWeightVars['--font-weight-semibold'],
lineHeight: 1,
@@ -330,6 +347,17 @@ 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: {
@@ -398,7 +426,10 @@ const styles = stylex.create({
cursor: 'pointer',
borderRadius: radiusVars['--radius-element'],
transitionProperty: 'background-color',
- transitionDuration: durationVars['--duration-fast-min'],
+ transitionDuration: {
+ default: durationVars['--duration-fast-min'],
+ '@media (prefers-reduced-motion: reduce)': '0s',
+ },
transitionTimingFunction: easeVars['--ease-standard'],
backgroundColor: {
default: 'transparent',
@@ -450,7 +481,10 @@ const styles = stylex.create({
cursor: 'pointer',
borderRadius: radiusVars['--radius-element'],
transitionProperty: 'background-color',
- transitionDuration: durationVars['--duration-fast-min'],
+ transitionDuration: {
+ default: durationVars['--duration-fast-min'],
+ '@media (prefers-reduced-motion: reduce)': '0s',
+ },
transitionTimingFunction: easeVars['--ease-standard'],
backgroundColor: {
default: 'transparent',
@@ -517,8 +551,21 @@ const styles = stylex.create({
borderRadius: 0,
},
- otSegHidden: {
- visibility: 'hidden',
+ otSegHiddenIfFirst: {
+ // Structural first/last hiding keyed off the step's own <li> position via
+ // stepMarker, so it never depends on the parent counting children (which
+ // breaks when steps are grouped in a fragment). Scoped to stepMarker so only
+ // the parent <li> is checked, not the outer <ol> (also a :first/:last-child).
+ visibility: {
+ default: 'visible',
+ [stylex.when.ancestor(':first-child', stepMarker)]: 'hidden',
+ },
+ },
+ otSegHiddenIfLast: {
+ visibility: {
+ default: 'visible',
+ [stylex.when.ancestor(':last-child', stepMarker)]: 'hidden',
+ },
},
// Connector fill colors (progress-derived; status recolors when set).
@@ -645,7 +692,7 @@ export function Step({
onStepClick,
density: ctxDensity,
indicatorPosition,
- stepCount,
+ hasCollapsibleLabels,
} = ctx;
const density = densityProp ?? ctxDensity;
@@ -668,6 +715,11 @@ 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;
@@ -741,7 +793,13 @@ export function Step({
indicatorNode = (
<div
aria-hidden="true"
- {...stylex.props(styles.numberBadge, numberColorStyle)}>
+ {...mergeProps(
+ themeProps('step-indicator', {
+ progress,
+ status: status ?? undefined,
+ }),
+ stylex.props(styles.numberBadge, numberColorStyle),
+ )}>
{step + 1}
</div>
);
@@ -807,7 +865,15 @@ export function Step({
: styles.iconNotStarted;
indicatorNode = (
- <div aria-hidden="true" {...stylex.props(styles.icon, iconColorStyle)}>
+ <div
+ aria-hidden="true"
+ {...mergeProps(
+ themeProps('step-indicator', {
+ progress,
+ status: status ?? undefined,
+ }),
+ stylex.props(styles.icon, iconColorStyle),
+ )}>
{iconContent}
</div>
);
@@ -864,7 +930,14 @@ export function Step({
const iconLabelNode = (
<div {...stylex.props(styles.iconLabelRow)}>
{indicatorNode}
- <span {...stylex.props(styles.label, labelColorStyle)}>{label}</span>
+ <span
+ {...stylex.props(
+ styles.label,
+ labelColorStyle,
+ collapseLabel && styles.labelCollapsible,
+ )}>
+ {label}
+ </span>
{statusTextNode}
{isOptional && (
<>
@@ -924,9 +997,9 @@ export function Step({
? styles.lineFilled
: styles.lineUnfilled;
const afterSegStyle = afterFilled ? styles.lineFilled : styles.lineUnfilled;
- const isFirst = step === 0;
- // The last step has no next node, so its trailing segment is hidden.
- const isLast = step === stepCount - 1;
+ // 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.
const densitySpace =
density === 'compact'
@@ -940,7 +1013,14 @@ export function Step({
{...stylex.props(
isVertical ? styles.otLabelRowStart : styles.otLabelRowCenter,
)}>
- <span {...stylex.props(styles.label, labelColorStyle)}>{label}</span>
+ <span
+ {...stylex.props(
+ styles.label,
+ labelColorStyle,
+ collapseLabel && styles.labelCollapsible,
+ )}>
+ {label}
+ </span>
{statusTextNode}
{isOptional && (
<>
@@ -983,7 +1063,7 @@ export function Step({
styles.otSegBaseV,
styles.otSegLeadV(densitySpace),
beforeSegStyle,
- isFirst && styles.otSegHidden,
+ styles.otSegHiddenIfFirst,
),
)}
/>
@@ -996,7 +1076,7 @@ export function Step({
styles.otSegBaseV,
styles.otSegFlexV,
afterSegStyle,
- isLast && styles.otSegHidden,
+ styles.otSegHiddenIfLast,
),
)}
/>
@@ -1013,7 +1093,7 @@ export function Step({
ref={ref}
{...mergeProps(
stepThemeProps,
- stylex.props(styles.otVerticalRoot, xstyle),
+ stylex.props(stepMarker, styles.otVerticalRoot, xstyle),
className,
style,
)}
@@ -1058,7 +1138,7 @@ export function Step({
stylex.props(
styles.otSegH,
beforeSegStyle,
- isFirst && styles.otSegHidden,
+ styles.otSegHiddenIfFirst,
),
)}
/>
@@ -1070,7 +1150,7 @@ export function Step({
stylex.props(
styles.otSegH,
afterSegStyle,
- isLast && styles.otSegHidden,
+ styles.otSegHiddenIfLast,
),
)}
/>
@@ -1091,7 +1171,7 @@ export function Step({
ref={ref}
{...mergeProps(
stepThemeProps,
- stylex.props(styles.otHorizontalRoot, xstyle),
+ stylex.props(stepMarker, styles.otHorizontalRoot, xstyle),
className,
style,
)}
@@ -1132,7 +1212,7 @@ export function Step({
ref={ref}
{...mergeProps(
stepThemeProps,
- stylex.props(styles.verticalRoot, xstyle),
+ stylex.props(stepMarker, styles.verticalRoot, xstyle),
className,
style,
)}
@@ -1190,7 +1270,7 @@ export function Step({
ref={ref}
{...mergeProps(
stepThemeProps,
- stylex.props(styles.horizontalStep, xstyle),
+ stylex.props(stepMarker, styles.horizontalStep, xstyle),
className,
style,
)}
diff --git a/packages/lab/src/Stepper/Stepper.doc.mjs b/packages/lab/src/Stepper/Stepper.doc.mjs
index f0df3038c2..29d3245fc0 100644
--- a/packages/lab/src/Stepper/Stepper.doc.mjs
+++ b/packages/lab/src/Stepper/Stepper.doc.mjs
@@ -30,6 +30,7 @@ export const docs = {
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'},
],
@@ -82,6 +83,12 @@ export const docs = {
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',
@@ -233,6 +240,7 @@ export const docsZh = {
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'},
],
diff --git a/packages/lab/src/Stepper/Stepper.test.tsx b/packages/lab/src/Stepper/Stepper.test.tsx
index 1f863a793d..e7cc224de8 100644
--- a/packages/lab/src/Stepper/Stepper.test.tsx
+++ b/packages/lab/src/Stepper/Stepper.test.tsx
@@ -373,30 +373,46 @@ describe('Stepper', () => {
});
it('lets the current step keep its ring indicator regardless of status', () => {
- // A current step with no status.
+ // The current-step ring's painted color is driven by the StyleX
+ // `iconInProgress` class (accent), never a status color — the ring replaces
+ // any status glyph. The `astryx-step-indicator` theme target reflects
+ // `status` as a data attribute so a theme can still reach it, which is
+ // orthogonal to the painted color, so assert the StyleX color class here.
+ const stylexColorClasses = (el: HTMLElement) =>
+ el.className
+ .split(/\s+/)
+ // Keep StyleX classes (debug `Step__styles.*` names + `x*` atomic
+ // hashes); drop the themeProps data reflections (`in-progress`,
+ // `success`, `astryx-*`) which are orthogonal to the painted color.
+ .filter(c => c.startsWith('Step__styles.') || /^x[a-z0-9]+$/.test(c))
+ .sort()
+ .join(' ');
+
const plain = render(
<Stepper activeStep={0}>
<Step step={0} label="A" data-testid="plain" />
</Stepper>,
);
- const plainIndicator = (
+ const plainIndicator = stylexColorClasses(
plain.getByTestId('plain').querySelector('svg')
- ?.parentElement as HTMLElement
- ).className;
+ ?.parentElement as HTMLElement,
+ );
- // The same current step, now with status="success": the indicator must be
- // unchanged (the current-step ring replaces any status glyph).
+ // The same current step, now with status="success": the painted ring must
+ // be unchanged (the current-step ring replaces any status glyph).
const themed = render(
<Stepper activeStep={0}>
<Step step={0} label="A" status="success" data-testid="themed" />
</Stepper>,
);
- const themedIndicator = (
+ const themedIndicator = stylexColorClasses(
themed.getByTestId('themed').querySelector('svg')
- ?.parentElement as HTMLElement
- ).className;
+ ?.parentElement as HTMLElement,
+ );
expect(themedIndicator).toBe(plainIndicator);
+ // And it is the in-progress (accent) color, not a status color.
+ expect(plainIndicator).toContain('Step__styles.iconInProgress');
});
it('replaces the number badge with a status glyph on not-started steps', () => {
@@ -493,4 +509,122 @@ describe('Stepper', () => {
within(screen.getByTestId('ot-current')).queryByText('completed'),
).not.toBeInTheDocument();
});
+
+ describe('keyboard interaction', () => {
+ it('activates a step with Enter', async () => {
+ const user = userEvent.setup();
+ const handleClick = vi.fn();
+ render(
+ <Stepper activeStep={2} onStepClick={handleClick}>
+ <Step step={0} label="Step 1" />
+ <Step step={1} label="Step 2" />
+ <Step step={2} label="Step 3" />
+ </Stepper>,
+ );
+ await user.tab();
+ expect(
+ screen.getByRole('button', {name: 'Go to step 1: Step 1, completed'}),
+ ).toHaveFocus();
+ await user.keyboard('{Enter}');
+ expect(handleClick).toHaveBeenCalledWith(0);
+ });
+
+ it('activates a step with Space', async () => {
+ const user = userEvent.setup();
+ const handleClick = vi.fn();
+ render(
+ <Stepper activeStep={2} onStepClick={handleClick}>
+ <Step step={0} label="Step 1" />
+ <Step step={1} label="Step 2" />
+ <Step step={2} label="Step 3" />
+ </Stepper>,
+ );
+ await user.tab();
+ await user.keyboard(' ');
+ expect(handleClick).toHaveBeenCalledWith(0);
+ });
+
+ it('tabs through steps in document order, skipping disabled ones', async () => {
+ const user = userEvent.setup();
+ render(
+ <Stepper activeStep={3} onStepClick={() => {}}>
+ <Step step={0} label="One" />
+ <Step step={1} label="Two" isDisabled />
+ <Step step={2} label="Three" />
+ </Stepper>,
+ );
+ await user.tab();
+ expect(
+ screen.getByRole('button', {name: 'Go to step 1: One, completed'}),
+ ).toHaveFocus();
+ // The disabled step renders no button, so Tab lands on step 3 next.
+ await user.tab();
+ expect(
+ screen.getByRole('button', {name: 'Go to step 3: Three, completed'}),
+ ).toHaveFocus();
+ });
+
+ it('supports keyboard activation in the on-track layout', async () => {
+ const user = userEvent.setup();
+ const handleClick = vi.fn();
+ render(
+ <Stepper
+ activeStep={2}
+ indicatorPosition="on-track"
+ onStepClick={handleClick}>
+ <Step step={0} label="Cart" />
+ <Step step={1} label="Shipping" />
+ <Step step={2} label="Payment" />
+ </Stepper>,
+ );
+ await user.tab();
+ await user.keyboard('{Enter}');
+ expect(handleClick).toHaveBeenCalledWith(0);
+ });
+ });
+
+ describe('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) =>
+ screen
+ .getByTestId(testid)
+ .querySelector('span[class*="label"]') as HTMLElement;
+
+ it('marks non-current horizontal step labels collapsible, but not the current one', () => {
+ render(
+ <Stepper activeStep={1} orientation="horizontal" hasCollapsibleLabels>
+ <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');
+ });
+
+ it('does not collapse labels when the prop is off', () => {
+ render(
+ <Stepper activeStep={1} orientation="horizontal">
+ <Step step={0} label="A" data-testid="a" />
+ <Step step={1} label="B" data-testid="b" />
+ </Stepper>,
+ );
+ expect(labelEl('a').className).not.toContain('labelCollapsible');
+ });
+
+ it('does not collapse labels in the vertical orientation', () => {
+ render(
+ <Stepper activeStep={1} orientation="vertical" hasCollapsibleLabels>
+ <Step step={0} label="A" data-testid="a" />
+ <Step step={1} label="B" data-testid="b" />
+ </Stepper>,
+ );
+ expect(labelEl('a').className).not.toContain('labelCollapsible');
+ });
+ });
});
diff --git a/packages/lab/src/Stepper/Stepper.tsx b/packages/lab/src/Stepper/Stepper.tsx
index 43fb66df94..18b0951641 100644
--- a/packages/lab/src/Stepper/Stepper.tsx
+++ b/packages/lab/src/Stepper/Stepper.tsx
@@ -16,7 +16,7 @@
* - /packages/cli/assets/templates/blocks/components/Stepper/ (showcase blocks)
*/
-import {Children, useMemo, type ReactNode} from 'react';
+import {useMemo, type ReactNode} from 'react';
import * as stylex from '@stylexjs/stylex';
import {spacingVars} from '@astryxdesign/core/theme/tokens.stylex';
@@ -70,6 +70,16 @@ 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({
@@ -100,6 +110,13 @@ 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',
+ },
});
/**
@@ -107,9 +124,10 @@ const styles = stylex.create({
* with visual indicators for completed, active, and upcoming states.
*
* Each Step child must provide a `step` prop (zero-based index) so it
- * can derive its state from the parent's activeStep. The parent supplies
- * the total `stepCount` via context so the on-track layout can hide the
- * trailing connector on the final step.
+ * can derive its state from the parent's activeStep. The on-track layout
+ * hides the leading connector on the first step and the trailing connector
+ * on the last step structurally, from each step's own `<li>` position, so
+ * it works regardless of how the steps are grouped.
*
* Rendered as an ordered list (`<ol>`/`<li>`) rather than a `nav`
* landmark: a stepper communicates *progress through a sequence*, not a
@@ -135,13 +153,13 @@ export function Stepper({
label = 'Progress',
density = 'balanced',
indicatorPosition = 'separated',
+ hasCollapsibleLabels = false,
xstyle,
className,
style,
ref,
...rest
}: StepperProps) {
- const stepCount = Children.count(children);
const ctxValue = useMemo<StepperContextValue>(
() => ({
activeStep,
@@ -150,7 +168,7 @@ export function Stepper({
onStepClick: onStepClick ?? null,
density,
indicatorPosition,
- stepCount,
+ hasCollapsibleLabels,
}),
[
activeStep,
@@ -158,7 +176,7 @@ export function Stepper({
onStepClick,
density,
indicatorPosition,
- stepCount,
+ hasCollapsibleLabels,
],
);
@@ -172,6 +190,10 @@ 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
@@ -180,7 +202,12 @@ export function Stepper({
{...rest}
{...mergeProps(
themeProps('stepper', {orientation, indicatorPosition}),
- stylex.props(styles.root, orientationStyle, xstyle),
+ stylex.props(
+ styles.root,
+ orientationStyle,
+ isLabelCollapse && styles.labelCollapseContainer,
+ xstyle,
+ ),
className,
style,
)}>
diff --git a/packages/lab/src/Stepper/StepperContext.ts b/packages/lab/src/Stepper/StepperContext.ts
index 58300d6f19..0ee8297039 100644
--- a/packages/lab/src/Stepper/StepperContext.ts
+++ b/packages/lab/src/Stepper/StepperContext.ts
@@ -34,13 +34,13 @@ export interface StepperContextValue {
isNonLinear: boolean;
onStepClick: ((index: number) => void) | null;
density: StepperDensity;
+ indicatorPosition: StepperIndicatorPosition;
/**
- * Total number of Step children. Used by the on-track layout to hide the
- * trailing connector segment on the last step (which otherwise has no next
- * node to reach toward).
+ * 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.
*/
- stepCount: number;
- indicatorPosition: StepperIndicatorPosition;
+ hasCollapsibleLabels: boolean;
}
export const StepperContext = createContext<StepperContextValue | null>(null);
diff --git a/packages/lab/src/Stepper/stepper.stylex.ts b/packages/lab/src/Stepper/stepper.stylex.ts
new file mode 100644
index 0000000000..92111f80ab
--- /dev/null
+++ b/packages/lab/src/Stepper/stepper.stylex.ts
@@ -0,0 +1,19 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file stepper.stylex.ts
+ * @input StyleX marker system
+ * @output stepMarker — a scoped marker applied to each Step's <li>
+ * @position Shared StyleX marker consumed by Step for structural selectors
+ *
+ * Applied to each Step's root `<li>` so the on-track connector segments can
+ * key their first/last-node visibility off `stylex.when.ancestor(':first-child'
+ * | ':last-child', stepMarker)` — matching only the parent step row, never the
+ * outer `<ol>`. This replaces counting children in the parent, so steps behave
+ * correctly regardless of how the consumer groups them (arrays, fragments).
+ */
+
+import * as stylex from '@stylexjs/stylex';
+
+export const stepMarker: ReturnType<typeof stylex.defineMarker> =
+ stylex.defineMarker();