feat(ui): add Stepper component to @automattic/ui

packages/ui/.storybook/preview.js

@@ -23,12 +23,15 @@ const parameters = {
 				return aIndex - bIndex;
 			}
 
-			// If they're in the same section, put MDX files first
-			const aIsMdx = a.importPath.endsWith( '.mdx' );
-			const bIsMdx = b.importPath.endsWith( '.mdx' );
+			// If they're in the same section, put docs entries first (MDX files or
+			// autodocs-generated pages). Storybook 9 no longer auto-pins Docs to the
+			// top of each component group, so we need to handle it here.
+			// Autodocs entries have type === 'docs' but importPath ending in .stories.*
+			const aIsDocs = a.type === 'docs' || a.importPath.endsWith( '.mdx' );
+			const bIsDocs = b.type === 'docs' || b.importPath.endsWith( '.mdx' );
 
-			if ( aIsMdx && ! bIsMdx ) return -1;
-			if ( ! aIsMdx && bIsMdx ) return 1;
+			if ( aIsDocs && ! bIsDocs ) return -1;
+			if ( ! aIsDocs && bIsDocs ) return 1;
 
 			// If both are MDX or both are not MDX, maintain original order
 			return 0;
@@ -38,4 +41,5 @@ const parameters = {
 
 export default {
 	parameters,
+	tags: [ 'autodocs' ],
 };

packages/ui/.storybook/style.scss

@@ -1,4 +1,5 @@
 @use "@wordpress/base-styles/variables";
+@import "@wordpress/theme/design-tokens.css";
 
 body {
 	font-family: variables.$font-family-body;

packages/ui/CHANGELOG.md

@@ -1,5 +1,11 @@
 ## Unreleased
 
+## 1.1.0
+
+### Enhancements
+
+- `Stepper`, `VerticalStepper`, `HorizontalStepper`: Add Stepper component suite with vertical and horizontal orientations, step indicators, linear flow support, and accessible ARIA semantics ([#111036](https://github.com/Automattic/wp-calypso/pull/111036)).
+
 ## 1.0.2
 
 ### Enhancements

packages/ui/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@automattic/ui",
-	"version": "1.0.2",
+	"version": "1.1.0",
 	"description": "Automattic Design System UI components.",
 	"homepage": "https://github.com/Automattic/wp-calypso",
 	"license": "GPL-2.0-or-later",
@@ -40,12 +40,14 @@
 	],
 	"types": "dist",
 	"dependencies": {
+		"@base-ui/react": "^1.5.0",
 		"@wordpress/base-styles": "9.1.0",
 		"@wordpress/compose": "patch:@wordpress/compose@npm%3A8.1.0#~/.yarn/patches/@wordpress-compose-npm-8.1.0-ea108e3129.patch",
 		"@wordpress/element": "^8.0.0",
 		"@wordpress/i18n": "^6.21.0",
 		"@wordpress/icons": "^13.3.0",
 		"@wordpress/primitives": "^4.48.0",
+		"@wordpress/ui": "0.13.0",
 		"clsx": "^2.1.1",
 		"date-fns": "^4.1.0",
 		"react-day-picker": "^9.7.0"

packages/ui/src/horizontal-stepper/horizontal-stepper-step.tsx

@@ -0,0 +1,11 @@
+// packages/ui/src/horizontal-stepper/horizontal-stepper-step.tsx
+import type { StepProps } from '../stepper/types';
+
+export type HorizontalStepperStepProps = Omit< StepProps, 'description' >;
+
+/**
+ * Step descriptor for HorizontalStepper.
+ * Renders nothing — HorizontalStepper reads props from this element directly
+ * at render time to build the tab list and panels.
+ */
+export const HorizontalStepperStep: ( props: HorizontalStepperStepProps ) => null = () => null;

packages/ui/src/horizontal-stepper/horizontal-stepper.tsx

@@ -0,0 +1,83 @@
+// packages/ui/src/horizontal-stepper/horizontal-stepper.tsx
+import { Children, forwardRef, isValidElement } from '@wordpress/element';
+import clsx from 'clsx';
+import { Stepper } from '../stepper';
+import { HorizontalStepperStep, type HorizontalStepperStepProps } from './horizontal-stepper-step';
+import styles from './style.module.scss';
+import type { AriaLabelXOR, StepperBaseProps, StepperRef } from '../stepper/types';
+import type { ReactNode, Ref } from 'react';
+
+// Omit is applied to StepperBaseProps (a plain object type) before intersecting
+// with AriaLabelXOR so that the XOR union constraint is preserved. Applying
+// Omit directly to StepperProps (which is StepperBaseProps & AriaLabelXOR)
+// flattens the union and widens aria-label/aria-labelledby to string|undefined,
+// breaking TypeScript's ability to verify the constraint downstream.
+type HorizontalStepperProps = Omit< StepperBaseProps, 'headingLevel' > & AriaLabelXOR;
+
+/**
+ * Extracts step descriptors from children at render time.
+ * Only direct HorizontalStepperStep children are collected — deeply nested
+ * or wrapped steps are not supported (use Stepper primitives for those).
+ */
+function getStepperSteps( children: ReactNode ): HorizontalStepperStepProps[] {
+	const steps: HorizontalStepperStepProps[] = [];
+	Children.forEach( children, ( child ) => {
+		if ( isValidElement( child ) && child.type === HorizontalStepperStep ) {
+			steps.push( child.props as HorizontalStepperStepProps );
+		}
+	} );
+	return steps;
+}
+
+function HorizontalStepperInner(
+	{ children, className, ...props }: HorizontalStepperProps,
+	ref: Ref< StepperRef >
+) {
+	const steps = getStepperSteps( children );
+
+	return (
+		<Stepper.Root
+			orientation="horizontal"
+			ref={ ref }
+			className={ clsx( styles[ 'root' ], className ) }
+			{ ...props }
+		>
+			<Stepper.List className={ styles[ 'list' ] }>
+				{ steps.map( ( step ) => (
+					<Stepper.Step
+						key={ step.value }
+						value={ step.value }
+						status={ step.status }
+						optional={ step.optional }
+						disabled={ step.disabled }
+						className={ clsx( styles[ 'step' ], step.className ) }
+					>
+						<Stepper.Trigger className={ styles[ 'trigger' ] }>
+							<Stepper.Indicator>{ step.indicator }</Stepper.Indicator>
+							<Stepper.Title className={ styles[ 'text-block' ] }>{ step.title }</Stepper.Title>
+						</Stepper.Trigger>
+					</Stepper.Step>
+				) ) }
+			</Stepper.List>
+
+			{ steps.map( ( step ) => (
+				<Stepper.Panel
+					key={ step.value }
+					value={ step.value }
+					keepMounted={ step.keepMounted }
+					className={ styles[ 'panel' ] }
+				>
+					{ step.children }
+				</Stepper.Panel>
+			) ) }
+		</Stepper.Root>
+	);
+}
+
+const HorizontalStepperBase = forwardRef< StepperRef, HorizontalStepperProps >(
+	HorizontalStepperInner
+);
+
+export const HorizontalStepper = Object.assign( HorizontalStepperBase, {
+	Step: HorizontalStepperStep,
+} );

packages/ui/src/horizontal-stepper/index.ts

@@ -0,0 +1,2 @@
+// packages/ui/src/horizontal-stepper/index.ts
+export { HorizontalStepper } from './horizontal-stepper';