An open source design system that's fully customizable and agent ready
TypeScript
feat(Stepper): add XDSStepper and XDSStep components (#2206)
Andrey Godere65657dd1e9f
diff --git a/apps/storybook/stories/Stepper.stories.tsx b/apps/storybook/stories/Stepper.stories.tsxnew file mode 100644index 0000000000..d8f9da86b4--- /dev/null+++ b/apps/storybook/stories/Stepper.stories.tsx@@ -0,0 +1,221 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++import {useState} from 'react';+import type {Meta, StoryObj} from '@storybook/react';+import {XDSStepper, XDSStep} from '@xds/core/Stepper';+import {XDSTextInput} from '@xds/core/TextInput';+import {XDSButton} from '@xds/core/Button';+import {XDSText} from '@xds/core/Text';++const meta: Meta<typeof XDSStepper> = {+ title: 'Core/Navigation/Stepper',+ component: XDSStepper,+ tags: ['autodocs'],+ argTypes: {+ activeStep: {+ control: {type: 'number', min: 0, max: 4},+ description: 'Zero-based index of the active step',+ },+ orientation: {+ control: 'select',+ options: ['horizontal', 'vertical'],+ description: 'Layout direction',+ },+ },+};++export default meta;+type Story = StoryObj<typeof XDSStepper>;++export const Default: Story = {+ args: {activeStep: 1},+ render: args => (+ <XDSStepper activeStep={args.activeStep} orientation={args.orientation}>+ <XDSStep step={0} label="Account" />+ <XDSStep step={1} label="Profile" />+ <XDSStep step={2} label="Review" />+ </XDSStepper>+ ),+};++export const AllCompleted: Story = {+ render: () => (+ <XDSStepper activeStep={3}>+ <XDSStep step={0} label="Account" />+ <XDSStep step={1} label="Profile" />+ <XDSStep step={2} label="Review" />+ </XDSStepper>+ ),+};++export const FirstStep: Story = {+ render: () => (+ <XDSStepper activeStep={0}>+ <XDSStep step={0} label="Account" />+ <XDSStep step={1} label="Profile" />+ <XDSStep step={2} label="Review" />+ </XDSStepper>+ ),+};++export const WithDescriptions: Story = {+ render: () => (+ <XDSStepper activeStep={1}>+ <XDSStep step={0} label="Account" description="Create your account" />+ <XDSStep step={1} label="Profile" description="Set up your profile" />+ <XDSStep step={2} label="Review" description="Review and confirm" />+ </XDSStepper>+ ),+};++export const Vertical: Story = {+ render: () => (+ <div style={{maxWidth: 400}}>+ <XDSStepper activeStep={1} orientation="vertical">+ <XDSStep step={0} label="Account" description="Create your account" />+ <XDSStep step={1} label="Profile" description="Set up your profile" />+ <XDSStep step={2} label="Review" description="Review and confirm" />+ </XDSStepper>+ </div>+ ),+};++export const NonLinear: Story = {+ name: 'Non-Linear (Clickable)',+ render: () => {+ const [activeStep, setActiveStep] = useState(1);+ return (+ <XDSStepper activeStep={activeStep} onStepClick={setActiveStep}>+ <XDSStep step={0} label="Account" />+ <XDSStep step={1} label="Profile" />+ <XDSStep step={2} label="Review" />+ </XDSStepper>+ );+ },+};++export const WithError: Story = {+ render: () => (+ <XDSStepper activeStep={1}>+ <XDSStep step={0} label="Account" />+ <XDSStep step={1} label="Profile" hasError />+ <XDSStep step={2} label="Review" />+ </XDSStepper>+ ),+};++export const WithDisabled: Story = {+ render: () => (+ <XDSStepper activeStep={1}>+ <XDSStep step={0} label="Account" />+ <XDSStep step={1} label="Profile" />+ <XDSStep step={2} label="Review" isDisabled />+ </XDSStepper>+ ),+};++export const FiveSteps: Story = {+ render: () => (+ <XDSStepper activeStep={2}>+ <XDSStep step={0} label="Cart" />+ <XDSStep step={1} label="Shipping" />+ <XDSStep step={2} label="Payment" />+ <XDSStep step={3} label="Review" />+ <XDSStep step={4} label="Confirm" />+ </XDSStepper>+ ),+};++export const VerticalNonLinear: Story = {+ name: 'Vertical Non-Linear',+ render: () => {+ const [activeStep, setActiveStep] = useState(2);+ return (+ <div style={{maxWidth: 400}}>+ <XDSStepper+ activeStep={activeStep}+ orientation="vertical"+ onStepClick={setActiveStep}>+ <XDSStep step={0} label="Account" description="Create your account" />+ <XDSStep step={1} label="Profile" description="Set up your profile" />+ <XDSStep step={2} label="Review" description="Review and confirm" />+ <XDSStep step={3} label="Done" description="All finished!" />+ </XDSStepper>+ </div>+ );+ },+};++export const VerticalWithContent: Story = {+ name: 'Vertical with Content',+ render: () => {+ const [activeStep, setActiveStep] = useState(1);+ return (+ <div style={{maxWidth: 480}}>+ <XDSStepper activeStep={activeStep} orientation="vertical">+ <XDSStep step={0} label="Account" description="Create your account">+ {activeStep === 0 && (+ <div style={{display: 'flex', flexDirection: 'column', gap: 12}}>+ <XDSTextInput label="Email" placeholder="[email protected]" />+ <XDSTextInput label="Password" placeholder="••••••••" />+ <div>+ <XDSButton+ label="Continue"+ variant="primary"+ onClick={() => setActiveStep(1)}+ />+ </div>+ </div>+ )}+ </XDSStep>+ <XDSStep+ step={1}+ label="Profile"+ description="Tell us about yourself">+ {activeStep === 1 && (+ <div style={{display: 'flex', flexDirection: 'column', gap: 12}}>+ <XDSTextInput label="Full name" placeholder="Jane Doe" />+ <XDSTextInput label="Company" placeholder="Acme Inc." />+ <XDSTextInput label="Role" placeholder="Engineer" />+ <div style={{display: 'flex', gap: 8}}>+ <XDSButton+ label="Back"+ variant="secondary"+ onClick={() => setActiveStep(0)}+ />+ <XDSButton+ label="Continue"+ variant="primary"+ onClick={() => setActiveStep(2)}+ />+ </div>+ </div>+ )}+ </XDSStep>+ <XDSStep step={2} label="Review" description="Confirm your details">+ {activeStep === 2 && (+ <div style={{display: 'flex', flexDirection: 'column', gap: 12}}>+ <XDSText type="body">+ Review your account details and click Finish to complete+ setup.+ </XDSText>+ <div style={{display: 'flex', gap: 8}}>+ <XDSButton+ label="Back"+ variant="secondary"+ onClick={() => setActiveStep(1)}+ />+ <XDSButton+ label="Finish"+ variant="primary"+ onClick={() => setActiveStep(3)}+ />+ </div>+ </div>+ )}+ </XDSStep>+ </XDSStepper>+ </div>+ );+ },+};diff --git a/packages/cli/templates/blocks/components/Stepper/StepperShowcase.doc.mjs b/packages/cli/templates/blocks/components/Stepper/StepperShowcase.doc.mjsnew file mode 100644index 0000000000..a1629be469--- /dev/null+++ b/packages/cli/templates/blocks/components/Stepper/StepperShowcase.doc.mjs@@ -0,0 +1,13 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */+export const doc = {+ type: 'block',+ exampleFor: 'Stepper',+ name: 'Stepper',+ isReady: true,+ aspectRatio: 16 / 9,+ isShowcase: true,+ description: 'A horizontal stepper with three steps, the second step active.',+ componentsUsed: ['Stepper'],+};diff --git a/packages/cli/templates/blocks/components/Stepper/StepperShowcase.tsx b/packages/cli/templates/blocks/components/Stepper/StepperShowcase.tsxnew file mode 100644index 0000000000..20dd854983--- /dev/null+++ b/packages/cli/templates/blocks/components/Stepper/StepperShowcase.tsx@@ -0,0 +1,15 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++'use client';++import {XDSStepper, XDSStep} from '@xds/core/Stepper';++export default function StepperShowcase() {+ return (+ <XDSStepper activeStep={1}>+ <XDSStep step={0} label="Account" />+ <XDSStep step={1} label="Profile" />+ <XDSStep step={2} label="Review" />+ </XDSStepper>+ );+}diff --git a/packages/core/package.json b/packages/core/package.jsonindex 4ef970919d..3be722a29e 100644--- a/packages/core/package.json+++ b/packages/core/package.json@@ -481,6 +481,12 @@"import": "./dist/StatusDot/index.mjs","require": "./dist/StatusDot/index.js"},+ "./Stepper": {+ "source": "./src/Stepper/index.ts",+ "types": "./dist/Stepper/index.d.ts",+ "import": "./dist/Stepper/index.mjs",+ "require": "./dist/Stepper/index.js"+ },"./Switch": {"source": "./src/Switch/index.ts","types": "./dist/Switch/index.d.ts",diff --git a/packages/core/src/Stepper/Stepper.doc.mjs b/packages/core/src/Stepper/Stepper.doc.mjsnew file mode 100644index 0000000000..6b025fcc34--- /dev/null+++ b/packages/core/src/Stepper/Stepper.doc.mjs@@ -0,0 +1,227 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/** @type {import('../docs-types').ComponentDoc} */++export const docs = {+ name: 'Stepper',+ group: 'Stepper',+ keywords: ['stepper', 'steps', 'wizard', 'workflow', 'progress', 'multi-step', 'form wizard', 'onboarding'],+ usage: {+ description:+ 'Steppers display progress through a sequence of logical and numbered steps. Use them for multi-step workflows like forms, onboarding flows, or checkout processes where users need to see their position and the steps ahead.',+ bestPractices: [+ {guidance: true, description: 'Keep step labels short and descriptive — "Payment" not "Enter your payment information".'},+ {guidance: true, description: 'Use the vertical orientation for narrow containers or when steps have longer descriptions.'},+ {guidance: true, description: 'Provide onStepClick for non-linear workflows where users may need to revisit earlier steps.'},+ {guidance: false, description: 'Use a stepper for fewer than 3 steps — a simple heading or progress bar works better.'},+ {guidance: false, description: 'Use more than 7 steps — consider grouping related steps or using a different pattern.'},+ ],+ anatomy: [+ {name: 'Step indicator', required: true, description: 'A numbered circle showing the step position. Shows a checkmark when completed.'},+ {name: 'Connector', required: true, description: 'A line between step indicators. Filled when the preceding step is completed.'},+ {name: 'Label', required: true, description: 'Text identifying the step.'},+ {name: 'Description', required: false, description: 'Supporting text below the label with additional context.'},+ ],+ },+ theming: {+ targets: [+ {className: 'xds-stepper', visualProps: ['orientation']},+ {className: 'xds-step', states: ['active', 'completed', 'upcoming', 'disabled', 'error']},+ {className: 'xds-step-indicator', states: ['active', 'completed', 'upcoming', 'disabled', 'error']},+ {className: 'xds-step-connector'},+ ],+ },+ components: [+ {+ name: 'XDSStepper',+ description:+ 'Container component that manages step state and renders steps in horizontal or vertical orientation.',+ props: [+ {+ name: 'activeStep',+ type: 'number',+ description: 'Zero-based index of the currently active step. Steps before this index are marked as completed.',+ required: true,+ },+ {+ name: 'children',+ type: 'ReactNode',+ description: 'XDSStep elements to render in the stepper.',+ required: true,+ },+ {+ name: 'orientation',+ type: "'horizontal' | 'vertical'",+ description: 'Layout direction of the stepper.',+ default: "'horizontal'",+ },+ {+ name: 'onStepClick',+ type: '(index: number) => void',+ description: 'Called when a step indicator is clicked. Enables non-linear navigation. Completed and active steps become clickable.',+ },+ {+ name: 'label',+ type: 'string',+ description: 'Accessible label for the stepper navigation landmark.',+ default: "'Progress'",+ },+ {+ name: 'xstyle',+ type: 'StyleXStyles',+ description: 'StyleX styles for layout customization. Must be a stylex.create() value.',+ },+ ],+ },+ {+ name: 'XDSStep',+ description:+ 'Individual step within a stepper. Renders a numbered indicator, connector line, and label with optional description.',+ props: [+ {+ name: 'step',+ type: 'number',+ description: 'Zero-based index of this step. Used to determine active/completed state relative to the parent activeStep.',+ required: true,+ },+ {+ name: 'label',+ type: 'string',+ description: 'Step label text displayed below (horizontal) or beside (vertical) the indicator.',+ required: true,+ },+ {+ name: 'description',+ type: 'string',+ description: 'Optional description shown below the label for additional context.',+ },+ {+ name: 'children',+ type: 'ReactNode',+ description: 'Content rendered below the label and description. Useful in vertical steppers for form fields or detailed step content.',+ },+ {+ name: 'icon',+ type: 'ReactNode',+ description: 'Custom icon to replace the step number or checkmark indicator.',+ slotElements: [{__element: 'XDSIcon', props: {icon: 'check', size: 'sm'}}],+ },+ {+ name: 'isCompleted',+ type: 'boolean',+ description: 'Override the auto-computed completed state. By default, steps before activeStep are completed.',+ },+ {+ name: 'isDisabled',+ type: 'boolean',+ description: 'Disables interaction and dims the step indicator and label.',+ default: 'false',+ },+ {+ name: 'hasError',+ type: 'boolean',+ description: 'Shows an error state on the step indicator and label.',+ default: 'false',+ },+ ],+ },+ ],+ playground: {+ defaults: {+ activeStep: 1,+ },+ },+};++/** @type {import('../docs-types').TranslationDoc} */+export const docsDense = {+ description: 'numbered step sequence for multi-step workflows',+ usage: {+ description:+ 'Steppers show progress through numbered steps. Use for forms, onboarding, checkout.',+ bestPractices: [+ {guidance: true, description: 'Keep step labels short. Use vertical in narrow containers.'},+ {guidance: true, description: 'Provide onStepClick for non-linear workflows.'},+ {guidance: false, description: 'Use for fewer than 3 or more than 7 steps.'},+ ],+ },+ components: [+ {+ name: 'XDSStepper',+ description: 'container managing step state w/ horizontal/vertical layout',+ propDescriptions: {+ activeStep: 'zero-based active step index',+ children: 'XDSStep elements',+ orientation: 'horizontal or vertical layout',+ onStepClick: 'enables non-linear navigation',+ label: 'nav landmark aria-label',+ xstyle: 'StyleX layout customization',+ },+ },+ {+ name: 'XDSStep',+ description: 'individual step w/ indicator, connector, label',+ propDescriptions: {+ step: 'zero-based step index',+ label: 'step label text',+ description: 'supporting text below label',+ icon: 'custom icon replacing number/check',+ isCompleted: 'override auto-completed state',+ isDisabled: 'disable interaction',+ hasError: 'error state on indicator and label',+ },+ },+ ],+};++/** @type {import('../docs-types').ComponentDoc} */+export const docsZh = {+ name: 'Stepper',+ group: 'Stepper',+ usage: {+ description:+ '步骤器显示通过一系列逻辑编号步骤的进度。用于多步骤工作流程,如表单、入职流程或结账流程。',+ bestPractices: [+ {guidance: true, description: '保持步骤标签简短和描述性。'},+ {guidance: true, description: '在窄容器中使用垂直方向,或当步骤有较长描述时。'},+ {guidance: true, description: '为非线性工作流程提供 onStepClick。'},+ {guidance: false, description: '少于3个步骤时使用步骤器。'},+ {guidance: false, description: '超过7个步骤时使用步骤器。'},+ ],+ },+ theming: {+ targets: [+ {className: 'xds-stepper', visualProps: ['orientation']},+ {className: 'xds-step', states: ['active', 'completed', 'upcoming', 'disabled', 'error']},+ {className: 'xds-step-indicator', states: ['active', 'completed', 'upcoming', 'disabled', 'error']},+ {className: 'xds-step-connector'},+ ],+ },+ components: [+ {+ name: 'XDSStepper',+ description: '容器组件,管理步骤状态并以水平或垂直方向渲染步骤。',+ props: [+ {name: 'activeStep', type: 'number', description: '当前活动步骤的从零开始的索引。', required: true},+ {name: 'children', type: 'ReactNode', description: '要在步骤器中渲染的 XDSStep 元素。', required: true},+ {name: 'orientation', type: "'horizontal' | 'vertical'", description: '步骤器的布局方向。', default: "'horizontal'"},+ {name: 'onStepClick', type: '(index: number) => void', description: '点击步骤指示器时调用。启用非线性导航。'},+ {name: 'label', type: 'string', description: '步骤器导航地标的无障碍标签。', default: "'Progress'"},+ {name: 'xstyle', type: 'StyleXStyles', description: '用于布局自定义的 StyleX 样式。'},+ ],+ },+ {+ name: 'XDSStep',+ description: '步骤器中的单个步骤。渲染编号指示器、连接线和带可选描述的标签。',+ props: [+ {name: 'step', type: 'number', description: '此步骤的从零开始的索引。', required: true},+ {name: 'label', type: 'string', description: '步骤标签文本。', required: true},+ {name: 'description', type: 'string', description: '标签下方的可选描述。'},+ {name: 'icon', type: 'ReactNode', description: '替换步骤编号或勾选指示器的自定义图标。'},+ {name: 'isCompleted', type: 'boolean', description: '覆盖自动计算的完成状态。'},+ {name: 'isDisabled', type: 'boolean', description: '禁用交互并使步骤指示器和标签变暗。', default: 'false'},+ {name: 'hasError', type: 'boolean', description: '在步骤指示器和标签上显示错误状态。', default: 'false'},+ ],+ },+ ],+};diff --git a/packages/core/src/Stepper/XDSStep.tsx b/packages/core/src/Stepper/XDSStep.tsxnew file mode 100644index 0000000000..7d1c2a66e6--- /dev/null+++ b/packages/core/src/Stepper/XDSStep.tsx@@ -0,0 +1,496 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++'use client';++/**+ * @file XDSStep.tsx+ * @input Uses React, stylex, theme tokens, XDSStepperContext+ * @output Exports XDSStep component and XDSStepProps+ * @position Individual step item; used inside XDSStepper+ *+ * SYNC: When modified, update these files to stay in sync:+ * - /packages/core/src/Stepper/Stepper.doc.mjs+ * - /packages/core/src/Stepper/XDSStepper.test.tsx+ * - /packages/core/src/Stepper/index.ts+ * - /apps/storybook/stories/Stepper.stories.tsx+ * - /packages/cli/templates/blocks/components/Stepper/ (showcase blocks)+ */++import {type ReactNode} from 'react';+import * as stylex from '@stylexjs/stylex';++import {+ colorVars,+ spacingVars,+ radiusVars,+ fontWeightVars,+ typeScaleVars,+ durationVars,+ easeVars,+} from '../theme/tokens.stylex';+import {xdsClassName, mergeProps} from '../utils';+import {XDSIcon} from '../Icon';+import type {XDSBaseProps} from '../XDSBaseProps';+import {useXDSStepperContext} from './XDSStepperContext';++export interface XDSStepProps extends XDSBaseProps<HTMLDivElement> {+ /** Ref forwarded to the root element */+ ref?: React.Ref<HTMLDivElement>;+ /**+ * Zero-based index of this step. Used to determine active/completed state+ * relative to the parent's activeStep.+ */+ step: number;+ /**+ * Step label text.+ */+ label: string;+ /**+ * Optional description shown below the label.+ */+ description?: string;+ /**+ * Content rendered below the label and description. Useful in vertical+ * steppers to show form fields or detailed content for each step.+ */+ children?: ReactNode;+ /**+ * Custom icon to replace the step number/check indicator.+ */+ icon?: ReactNode;+ /**+ * Override the auto-computed completed state.+ * By default, steps before activeStep are completed.+ */+ isCompleted?: boolean;+ /**+ * Disable interaction for this step.+ * @default false+ */+ isDisabled?: boolean;+ /**+ * Optional error state for this step.+ * @default false+ */+ hasError?: boolean;+}++const styles = stylex.create({+ // Horizontal layout+ horizontalRoot: {+ display: 'flex',+ flexDirection: 'row',+ alignItems: 'flex-start',+ flex: {+ default: 1,+ ':last-child': 'none',+ },+ '--_show-connector': {+ default: 'flex',+ ':last-child': 'none',+ },+ position: 'relative',+ },+ horizontalContent: {+ display: 'flex',+ flexDirection: 'column',+ alignItems: 'center',+ position: 'relative',+ zIndex: 1,+ },+ horizontalConnector: {+ flex: 1,+ display: 'var(--_show-connector)',+ alignItems: 'center',+ paddingInline: spacingVars['--spacing-2'],+ minWidth: spacingVars['--spacing-6'],+ height: spacingVars['--spacing-7'],+ },+ horizontalConnectorLine: {+ height: spacingVars['--spacing-0-5'],+ width: '100%',+ borderRadius: radiusVars['--radius-full'],+ transitionProperty: 'background-color',+ transitionDuration: durationVars['--duration-fast'],+ transitionTimingFunction: easeVars['--ease-standard'],+ },++ // Vertical layout+ verticalRoot: {+ display: 'flex',+ flexDirection: 'row',+ alignItems: 'stretch',+ position: 'relative',+ minHeight: spacingVars['--spacing-12'],+ '--_show-connector': {+ default: 'flex',+ ':last-child': 'none',+ },+ },+ verticalIndicatorColumn: {+ display: 'flex',+ flexDirection: 'column',+ alignItems: 'center',+ width: spacingVars['--spacing-7'],+ flexShrink: 0,+ },+ verticalConnector: {+ flex: 1,+ display: 'var(--_show-connector)',+ justifyContent: 'center',+ paddingBlock: spacingVars['--spacing-1'],+ },+ verticalConnectorLine: {+ width: spacingVars['--spacing-0-5'],+ height: '100%',+ borderRadius: radiusVars['--radius-full'],+ transitionProperty: 'background-color',+ transitionDuration: durationVars['--duration-fast'],+ transitionTimingFunction: easeVars['--ease-standard'],+ },+ verticalContent: {+ display: 'flex',+ flexDirection: 'column',+ paddingInlineStart: spacingVars['--spacing-3'],+ paddingBlockEnd: spacingVars['--spacing-6'],+ flex: 1,+ },+ verticalLastContent: {+ paddingBlockEnd: spacingVars['--spacing-0'],+ },++ // Indicator circle+ indicator: {+ display: 'flex',+ alignItems: 'center',+ justifyContent: 'center',+ width: spacingVars['--spacing-7'],+ height: spacingVars['--spacing-7'],+ borderRadius: radiusVars['--radius-full'],+ fontSize: typeScaleVars['--text-supporting-size'],+ fontWeight: fontWeightVars['--font-weight-semibold'],+ lineHeight: typeScaleVars['--text-supporting-leading'],+ transitionProperty: 'background-color, color, border-color',+ transitionDuration: durationVars['--duration-fast'],+ transitionTimingFunction: easeVars['--ease-standard'],+ flexShrink: 0,+ userSelect: 'none',+ borderWidth: spacingVars['--spacing-0-5'],+ borderStyle: 'solid',+ position: 'relative',+ },+ indicatorActive: {+ backgroundColor: colorVars['--color-accent'],+ borderColor: colorVars['--color-accent'],+ color: colorVars['--color-on-accent'],+ },+ indicatorCompleted: {+ backgroundColor: colorVars['--color-accent'],+ borderColor: colorVars['--color-accent'],+ color: colorVars['--color-on-accent'],+ },+ indicatorUpcoming: {+ backgroundColor: 'transparent',+ borderColor: colorVars['--color-border-emphasized'],+ color: colorVars['--color-text-secondary'],+ },+ indicatorDisabled: {+ backgroundColor: 'transparent',+ borderColor: colorVars['--color-border'],+ color: colorVars['--color-text-disabled'],+ },+ indicatorError: {+ backgroundColor: colorVars['--color-error'],+ borderColor: colorVars['--color-error'],+ color: colorVars['--color-on-error'],+ },+ indicatorClickable: {+ cursor: 'pointer',+ ':hover': {+ '@media (hover: hover)': {+ opacity: 0.85,+ },+ },+ },++ // Connector line colors+ connectorCompleted: {+ backgroundColor: colorVars['--color-accent'],+ },+ connectorIncomplete: {+ backgroundColor: colorVars['--color-border-emphasized'],+ },++ // Label and description+ labelRow: {+ display: 'flex',+ flexDirection: 'column',+ alignItems: 'center',+ paddingBlockStart: spacingVars['--spacing-1'],+ // No spacing token at 120px — nearest are --spacing-12 (48px) and --spacing-14 (56px)+ maxWidth: '120px',+ },+ labelRowVertical: {+ alignItems: 'flex-start',+ maxWidth: 'none',+ paddingBlockStart: spacingVars['--spacing-0-5'],+ },+ label: {+ fontSize: typeScaleVars['--text-body-size'],+ lineHeight: typeScaleVars['--text-body-leading'],+ fontWeight: fontWeightVars['--font-weight-medium'],+ textAlign: 'center',+ },+ labelVertical: {+ textAlign: 'start',+ },+ labelActive: {+ color: colorVars['--color-text-primary'],+ fontWeight: fontWeightVars['--font-weight-semibold'],+ },+ labelCompleted: {+ color: colorVars['--color-text-primary'],+ },+ labelUpcoming: {+ color: colorVars['--color-text-secondary'],+ },+ labelDisabled: {+ color: colorVars['--color-text-disabled'],+ },+ labelError: {+ color: colorVars['--color-error'],+ },+ description: {+ fontSize: typeScaleVars['--text-supporting-size'],+ lineHeight: typeScaleVars['--text-supporting-leading'],+ color: colorVars['--color-text-secondary'],+ textAlign: 'center',+ },+ descriptionVertical: {+ textAlign: 'start',+ },+ descriptionError: {+ color: colorVars['--color-error'],+ },++ // Button reset for clickable indicators+ buttonReset: {+ background: 'none',+ border: 'none',+ padding: 0,+ margin: 0,+ font: 'inherit',+ },++ // Step content (children)+ stepContent: {+ paddingBlockStart: spacingVars['--spacing-3'],+ },+});++/**+ * An individual step within an XDSStepper. Renders a numbered indicator+ * circle, a connector line to the next step, and a label with optional+ * description. Step state (active, completed, upcoming) is derived from+ * the parent's activeStep and this step's `step` prop.+ *+ * @example+ * ```+ * <XDSStep step={0} label="Account details" description="Enter your email" />+ * ```+ */+export function XDSStep({+ step,+ label,+ description,+ children,+ icon,+ isCompleted: isCompletedProp,+ isDisabled = false,+ hasError = false,+ xstyle,+ className,+ style,+ ref,+ 'data-testid': dataTestId,+ ...rest+}: XDSStepProps) {+ const ctx = useXDSStepperContext();+ const {activeStep, orientation, isNonLinear, onStepClick} = ctx;++ const isActive = step === activeStep;+ const isCompleted = isCompletedProp ?? step < activeStep;+ const isVertical = orientation === 'vertical';++ const isClickable = isNonLinear && !isDisabled && (isCompleted || isActive);++ const handleClick = () => {+ if (isClickable && onStepClick) {+ onStepClick(step);+ }+ };++ const indicatorContent = hasError ? (+ <XDSIcon icon="warning" size="sm" color="inherit" />+ ) : icon != null ? (+ icon+ ) : isCompleted ? (+ <XDSIcon icon="check" size="sm" color="inherit" />+ ) : (+ <span>{step + 1}</span>+ );++ const indicatorVariantStyle = hasError+ ? styles.indicatorError+ : isDisabled+ ? styles.indicatorDisabled+ : isActive+ ? styles.indicatorActive+ : isCompleted+ ? styles.indicatorCompleted+ : styles.indicatorUpcoming;++ const stepState = hasError+ ? 'error'+ : isDisabled+ ? 'disabled'+ : isActive+ ? 'active'+ : isCompleted+ ? 'completed'+ : 'upcoming';++ const indicator = isClickable ? (+ <button+ type="button"+ onClick={handleClick}+ aria-label={`Go to step ${step + 1}: ${label}`}+ {...mergeProps(+ xdsClassName('step-indicator', {state: stepState}),+ stylex.props(+ styles.buttonReset,+ styles.indicator,+ indicatorVariantStyle,+ styles.indicatorClickable,+ ),+ )}>+ {indicatorContent}+ </button>+ ) : (+ <div+ aria-hidden="true"+ {...mergeProps(+ xdsClassName('step-indicator', {state: stepState}),+ stylex.props(styles.indicator, indicatorVariantStyle),+ )}>+ {indicatorContent}+ </div>+ );++ const labelNode = (+ <div+ {...stylex.props(styles.labelRow, isVertical && styles.labelRowVertical)}>+ <span+ {...stylex.props(+ styles.label,+ isVertical && styles.labelVertical,+ hasError+ ? styles.labelError+ : isDisabled+ ? styles.labelDisabled+ : isActive+ ? styles.labelActive+ : isCompleted+ ? styles.labelCompleted+ : styles.labelUpcoming,+ )}>+ {label}+ </span>+ {description != null && (+ <span+ {...stylex.props(+ styles.description,+ isVertical && styles.descriptionVertical,+ hasError && styles.descriptionError,+ )}>+ {description}+ </span>+ )}+ </div>+ );++ if (isVertical) {+ return (+ <div+ ref={ref}+ {...mergeProps(+ xdsClassName('step', {state: stepState}),+ stylex.props(styles.verticalRoot, xstyle),+ className,+ style,+ )}+ aria-current={isActive ? 'step' : undefined}+ data-testid={dataTestId}+ role="listitem"+ {...rest}>+ <div {...stylex.props(styles.verticalIndicatorColumn)}>+ {indicator}+ <div {...stylex.props(styles.verticalConnector)}>+ <div+ {...mergeProps(+ xdsClassName('step-connector'),+ stylex.props(+ styles.verticalConnectorLine,+ isCompleted+ ? styles.connectorCompleted+ : styles.connectorIncomplete,+ ),+ )}+ />+ </div>+ </div>+ <div {...stylex.props(styles.verticalContent)}>+ {labelNode}+ {children != null && (+ <div {...stylex.props(styles.stepContent)}>{children}</div>+ )}+ </div>+ </div>+ );+ }++ return (+ <div+ ref={ref}+ {...mergeProps(+ xdsClassName('step', {state: stepState}),+ stylex.props(styles.horizontalRoot, xstyle),+ className,+ style,+ )}+ aria-current={isActive ? 'step' : undefined}+ data-testid={dataTestId}+ role="listitem"+ {...rest}>+ <div {...stylex.props(styles.horizontalContent)}>+ {indicator}+ {labelNode}+ </div>+ <div {...stylex.props(styles.horizontalConnector)}>+ <div+ {...mergeProps(+ xdsClassName('step-connector'),+ stylex.props(+ styles.horizontalConnectorLine,+ isCompleted+ ? styles.connectorCompleted+ : styles.connectorIncomplete,+ ),+ )}+ />+ </div>+ </div>+ );+}++XDSStep.displayName = 'XDSStep';diff --git a/packages/core/src/Stepper/XDSStepper.test.tsx b/packages/core/src/Stepper/XDSStepper.test.tsxnew file mode 100644index 0000000000..ffc2a9e8a9--- /dev/null+++ b/packages/core/src/Stepper/XDSStepper.test.tsx@@ -0,0 +1,192 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++import {describe, it, expect, vi} from 'vitest';+import {render, screen} from '@testing-library/react';+import userEvent from '@testing-library/user-event';+import {XDSStepper} from './XDSStepper';+import {XDSStep} from './XDSStep';++describe('XDSStepper', () => {+ it('renders a navigation landmark with steps', () => {+ render(+ <XDSStepper activeStep={0}>+ <XDSStep step={0} label="Step 1" />+ <XDSStep step={1} label="Step 2" />+ <XDSStep step={2} label="Step 3" />+ </XDSStepper>,+ );+ expect(+ screen.getByRole('navigation', {name: 'Progress'}),+ ).toBeInTheDocument();+ expect(screen.getByText('Step 1')).toBeInTheDocument();+ expect(screen.getByText('Step 2')).toBeInTheDocument();+ expect(screen.getByText('Step 3')).toBeInTheDocument();+ });++ it('renders step numbers', () => {+ render(+ <XDSStepper activeStep={0}>+ <XDSStep step={0} label="First" />+ <XDSStep step={1} label="Second" />+ </XDSStepper>,+ );+ expect(screen.getByText('1')).toBeInTheDocument();+ expect(screen.getByText('2')).toBeInTheDocument();+ });++ it('marks the active step with aria-current', () => {+ render(+ <XDSStepper activeStep={1}>+ <XDSStep step={0} label="Step 1" data-testid="step-0" />+ <XDSStep step={1} label="Step 2" data-testid="step-1" />+ <XDSStep step={2} label="Step 3" data-testid="step-2" />+ </XDSStepper>,+ );+ expect(screen.getByTestId('step-0')).not.toHaveAttribute('aria-current');+ expect(screen.getByTestId('step-1')).toHaveAttribute(+ 'aria-current',+ 'step',+ );+ expect(screen.getByTestId('step-2')).not.toHaveAttribute('aria-current');+ });++ it('renders descriptions when provided', () => {+ render(+ <XDSStepper activeStep={0}>+ <XDSStep step={0} label="Account" description="Create your account" />+ <XDSStep step={1} label="Profile" />+ </XDSStepper>,+ );+ expect(screen.getByText('Create your account')).toBeInTheDocument();+ });++ it('supports custom accessible label', () => {+ render(+ <XDSStepper activeStep={0} label="Checkout progress">+ <XDSStep step={0} label="Cart" />+ <XDSStep step={1} label="Payment" />+ </XDSStepper>,+ );+ expect(+ screen.getByRole('navigation', {name: 'Checkout progress'}),+ ).toBeInTheDocument();+ });++ it('supports vertical orientation', () => {+ render(+ <XDSStepper activeStep={0} orientation="vertical">+ <XDSStep step={0} label="Step 1" />+ <XDSStep step={1} label="Step 2" />+ </XDSStepper>,+ );+ const nav = screen.getByRole('navigation');+ expect(nav).toBeInTheDocument();+ });++ it('calls onStepClick when a completed step is clicked', async () => {+ const user = userEvent.setup();+ const handleClick = vi.fn();+ render(+ <XDSStepper activeStep={2} onStepClick={handleClick}>+ <XDSStep step={0} label="Step 1" />+ <XDSStep step={1} label="Step 2" />+ <XDSStep step={2} label="Step 3" />+ </XDSStepper>,+ );+ await user.click(+ screen.getByRole('button', {name: 'Go to step 1: Step 1'}),+ );+ expect(handleClick).toHaveBeenCalledWith(0);+ });++ it('calls onStepClick when the active step is clicked', async () => {+ const user = userEvent.setup();+ const handleClick = vi.fn();+ render(+ <XDSStepper activeStep={1} onStepClick={handleClick}>+ <XDSStep step={0} label="Step 1" />+ <XDSStep step={1} label="Step 2" />+ <XDSStep step={2} label="Step 3" />+ </XDSStepper>,+ );+ await user.click(+ screen.getByRole('button', {name: 'Go to step 2: Step 2'}),+ );+ expect(handleClick).toHaveBeenCalledWith(1);+ });++ it('does not render buttons for upcoming steps in non-linear mode', () => {+ render(+ <XDSStepper activeStep={0} onStepClick={() => {}}>+ <XDSStep step={0} label="Step 1" />+ <XDSStep step={1} label="Step 2" />+ </XDSStepper>,+ );+ expect(+ screen.getByRole('button', {name: 'Go to step 1: Step 1'}),+ ).toBeInTheDocument();+ expect(+ screen.queryByRole('button', {name: 'Go to step 2: Step 2'}),+ ).not.toBeInTheDocument();+ });++ it('does not render buttons for disabled steps', () => {+ render(+ <XDSStepper activeStep={2} onStepClick={() => {}}>+ <XDSStep step={0} label="Step 1" isDisabled />+ <XDSStep step={1} label="Step 2" />+ <XDSStep step={2} label="Step 3" />+ </XDSStepper>,+ );+ expect(+ screen.queryByRole('button', {name: 'Go to step 1: Step 1'}),+ ).not.toBeInTheDocument();+ });++ it('does not render buttons when onStepClick is not provided', () => {+ render(+ <XDSStepper activeStep={2}>+ <XDSStep step={0} label="Step 1" />+ <XDSStep step={1} label="Step 2" />+ <XDSStep step={2} label="Step 3" />+ </XDSStepper>,+ );+ expect(screen.queryAllByRole('button')).toHaveLength(0);+ });++ it('supports isCompleted override', () => {+ render(+ <XDSStepper activeStep={0}>+ <XDSStep step={0} label="Step 1" data-testid="step-0" />+ <XDSStep step={1} label="Step 2" isCompleted data-testid="step-1" />+ </XDSStepper>,+ );+ const step1 = screen.getByTestId('step-1');+ expect(step1).toBeInTheDocument();+ });++ it('handles zero active step correctly', () => {+ render(+ <XDSStepper activeStep={0}>+ <XDSStep step={0} label="Step 1" data-testid="step-0" />+ <XDSStep step={1} label="Step 2" data-testid="step-1" />+ </XDSStepper>,+ );+ expect(screen.getByTestId('step-0')).toHaveAttribute(+ 'aria-current',+ 'step',+ );+ expect(screen.getByTestId('step-1')).not.toHaveAttribute('aria-current');+ });++ it('renders listitem roles for each step', () => {+ render(+ <XDSStepper activeStep={0}>+ <XDSStep step={0} label="Step 1" />+ <XDSStep step={1} label="Step 2" />+ <XDSStep step={2} label="Step 3" />+ </XDSStepper>,+ );+ expect(screen.getAllByRole('listitem')).toHaveLength(3);+ });+});diff --git a/packages/core/src/Stepper/XDSStepper.tsx b/packages/core/src/Stepper/XDSStepper.tsxnew file mode 100644index 0000000000..d3ecae3ac5--- /dev/null+++ b/packages/core/src/Stepper/XDSStepper.tsx@@ -0,0 +1,137 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++'use client';++/**+ * @file XDSStepper.tsx+ * @input Uses React, stylex, theme tokens, XDSStepperContext+ * @output Exports XDSStepper component and XDSStepperProps+ * @position Core container component; consumed by index.ts+ *+ * SYNC: When modified, update these files to stay in sync:+ * - /packages/core/src/Stepper/Stepper.doc.mjs (props table, features, implementation notes)+ * - /packages/core/src/Stepper/XDSStepper.test.tsx (tests for new/changed behavior)+ * - /packages/core/src/Stepper/index.ts (exports if types change)+ * - /apps/storybook/stories/Stepper.stories.tsx (storybook stories)+ * - /packages/cli/templates/blocks/components/Stepper/ (showcase blocks)+ */++import {useMemo, type ReactNode} from 'react';+import * as stylex from '@stylexjs/stylex';++import {xdsClassName, mergeProps} from '../utils';+import type {XDSBaseProps} from '../XDSBaseProps';+import {+ XDSStepperContext,+ type XDSStepperOrientation,+ type XDSStepperContextValue,+} from './XDSStepperContext';++export interface XDSStepperProps extends XDSBaseProps<HTMLDivElement> {+ /** Ref forwarded to the root element */+ ref?: React.Ref<HTMLDivElement>;+ /**+ * Zero-based index of the active step.+ */+ activeStep: number;+ /**+ * XDSStep elements to render.+ */+ children: ReactNode;+ /**+ * Layout direction of the stepper.+ * @default 'horizontal'+ */+ orientation?: XDSStepperOrientation;+ /**+ * Called when a step indicator is clicked. Enables non-linear navigation.+ * When provided, completed and current steps become clickable.+ */+ onStepClick?: (index: number) => void;+ /**+ * Accessible label for the stepper navigation landmark.+ * @default 'Progress'+ */+ label?: string;+}++const styles = stylex.create({+ root: {+ display: 'flex',+ width: '100%',+ listStyleType: 'none',+ margin: 0,+ padding: 0,+ },+ horizontal: {+ flexDirection: 'row',+ alignItems: 'flex-start',+ },+ vertical: {+ flexDirection: 'column',+ },+});++/**+ * A stepper component for multi-step workflows. Displays numbered steps+ * with visual indicators for completed, active, and upcoming states.+ *+ * Each XDSStep child must provide a `step` prop (zero-based index) so it+ * can derive its state from the parent's activeStep. CSS :last-child+ * handles connector hiding — no child introspection needed.+ *+ * @example+ * ```+ * <XDSStepper activeStep={1}>+ * <XDSStep step={0} label="Account" />+ * <XDSStep step={1} label="Profile" />+ * <XDSStep step={2} label="Review" />+ * </XDSStepper>+ * ```+ */+export function XDSStepper({+ activeStep,+ children,+ orientation = 'horizontal',+ onStepClick,+ label = 'Progress',+ xstyle,+ className,+ style,+ ref,+ ...rest+}: XDSStepperProps) {+ const ctxValue = useMemo<XDSStepperContextValue>(+ () => ({+ activeStep,+ orientation,+ isNonLinear: onStepClick != null,+ onStepClick: onStepClick ?? null,+ }),+ [activeStep, orientation, onStepClick],+ );++ return (+ <XDSStepperContext.Provider value={ctxValue}>+ <nav ref={ref} aria-label={label} {...rest}>+ <ol+ {...mergeProps(+ xdsClassName('stepper', {orientation}),+ stylex.props(+ styles.root,+ orientation === 'horizontal'+ ? styles.horizontal+ : styles.vertical,+ xstyle,+ ),+ className,+ style,+ )}>+ {children}+ </ol>+ </nav>+ </XDSStepperContext.Provider>+ );+}++XDSStepper.displayName = 'XDSStepper';diff --git a/packages/core/src/Stepper/XDSStepperContext.ts b/packages/core/src/Stepper/XDSStepperContext.tsnew file mode 100644index 0000000000..ec6bdb06b1--- /dev/null+++ b/packages/core/src/Stepper/XDSStepperContext.ts@@ -0,0 +1,40 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++'use client';++/**+ * @file XDSStepperContext.ts+ * @input Uses React createContext/useContext+ * @output Exports XDSStepperContext, useXDSStepperContext, and context types+ * @position Context for XDSStepper <-> XDSStep communication+ *+ * SYNC: When modified, update these files to stay in sync:+ * - /packages/core/src/Stepper/Stepper.doc.mjs+ * - /packages/core/src/Stepper/index.ts+ */++import {createContext, useContext} from 'react';++export type XDSStepperOrientation = 'horizontal' | 'vertical';++export interface XDSStepperContextValue {+ activeStep: number;+ orientation: XDSStepperOrientation;+ isNonLinear: boolean;+ onStepClick: ((index: number) => void) | null;+}++export const XDSStepperContext = createContext<XDSStepperContextValue | null>(+ null,+);++export function useXDSStepperContext(): XDSStepperContextValue {+ const ctx = useContext(XDSStepperContext);+ if (ctx == null) {+ throw new Error(+ 'useXDSStepperContext must be used within XDSStepper. ' ++ 'Wrap your XDSStep in <XDSStepper>.',+ );+ }+ return ctx;+}diff --git a/packages/core/src/Stepper/index.ts b/packages/core/src/Stepper/index.tsnew file mode 100644index 0000000000..dd40cc2300--- /dev/null+++ b/packages/core/src/Stepper/index.ts@@ -0,0 +1,21 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++'use client';++/**+ * @file index.ts+ * @input Imports from Stepper component files+ * @output Exports XDSStepper, XDSStep and their types+ * @position Component entry point; re-exported by /packages/core/src/index.ts+ *+ * SYNC: When modified, update this header and /packages/core/src/Stepper/Stepper.doc.mjs+ */++export {XDSStepper} from './XDSStepper';+export type {XDSStepperProps} from './XDSStepper';++export {XDSStep} from './XDSStep';+export type {XDSStepProps} from './XDSStep';++export {useXDSStepperContext} from './XDSStepperContext';+export type {XDSStepperOrientation} from './XDSStepperContext';diff --git a/packages/core/src/index.ts b/packages/core/src/index.tsindex 8e03e29c90..6e6fa28244 100644--- a/packages/core/src/index.ts+++ b/packages/core/src/index.ts@@ -93,6 +93,7 @@ export * from './SideNav';export * from './MobileNav';export * from './Pagination';export * from './ProgressBar';+export * from './Stepper';// Layout utilities and components (includes XDSHStack, XDSVStack)export * from './Layout';