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.mjsindex 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.tsxindex 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.mjsnew file mode 100644index 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.tsxnew file mode 100644index 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.mjsnew file mode 100644index 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.tsxnew file mode 100644index 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.mjsnew file mode 100644index 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.tsxnew file mode 100644index 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.mjsnew file mode 100644index 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.tsxnew file mode 100644index 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.mjsnew file mode 100644index 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.tsxnew file mode 100644index 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.mjsnew file mode 100644index 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.tsxnew file mode 100644index 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.mjsnew file mode 100644index 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.tsxnew file mode 100644index 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.tsxindex 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 tagoptionalDot: {@@ -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 = (<divaria-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.mjsindex 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.tsxindex 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.tsxindex 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.tsindex 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.tsnew file mode 100644index 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();