An open source design system that's fully customizable and agent ready
TypeScript
// Copyright (c) Meta Platforms, Inc. and affiliates.
'use client';
/**
* @file Step.tsx
* @input Uses React, stylex, theme tokens (including the motion duration token
* the connector fill animates on), StepperContext, and per-step theme selector
* state
* @output Exports Step component and StepProps
* @position Individual step item; used inside Stepper
*
* Every connector this file draws — the separated progress bars and the
* on-track segments alike — paints its accent fill as a scaled ::before rather
* than by swapping a background color, so a step the flow advances into grows
* its line along the track. See the CONNECTOR FILL block in the styles below
* for the axis/RTL/reduced-motion rules that go with it.
*
* Exactly one change animates: advancing a single step. Going back, jumping
* forward by more than one, and mounting mid-flow all land at once. The rule
* and the reasoning behind it sit above the styles; the arithmetic that keeps
* the one animated span reading as a single front — an on-track span is drawn
* by two steps, three where a content slot splits it — is in the component.
* Nothing about it is public API: Stepper hands each Step the step it came
* from through context, and the rest is derived. In a compact horizontal
* Stepper, each track node is presentational rather than clickable; navigation
* moves to the named previous/next controls in the summary row. The on-track
* layout keeps each indicator on the rail and does not repeat the active one
* beside the summary label. Each public content slot stays mounted and is
* hidden to preserve local state.
*
* SYNC: When modified, update these files to stay in sync:
* - /packages/core/src/Stepper/Stepper.doc.mjs
* - /packages/core/src/Stepper/Stepper.test.tsx
* - /packages/core/src/Stepper/index.ts
* - /apps/storybook/stories/Stepper.stories.tsx
* - /packages/cli/assets/templates/blocks/components/Stepper/ (showcase blocks)
* - /packages/cli/assets/templates/blocks/components/Step/ (showcase blocks)
*/
import {useId, useLayoutEffect, type ReactNode} from 'react';
import {createPortal} from 'react-dom';
import * as stylex from '@stylexjs/stylex';
import {
colorVars,
spacingVars,
radiusVars,
fontWeightVars,
typeScaleVars,
textSizeVars,
durationVars,
easeVars,
} from '../theme/tokens.stylex';
import {
focusOutlineStyles,
mergeProps,
isRenderable,
themeProps,
} from '../utils';
import {interactionOverlayStyles} from '../utils/interactionOverlay.stylex';
import {usePressFeedback} from '../hooks/usePressFeedback';
import type {BaseProps} from '../BaseProps';
import {Icon} from '../Icon';
import {VisuallyHidden} from '../VisuallyHidden';
import {useStepperInternalContext} from './StepperContext';
import {stepMarker} from './stepper.stylex';
import type {StepStatus} from './StepStatus';
import {
registerEnglishFallback,
useComponentTranslator,
} from '../i18n/useComponentTranslator';
import english from '../i18n/generated-english/Stepper/Step.generated';
registerEnglishFallback(english);
/**
* Built-in indicator presets. Anything other than these strings passed to
* `indicator` is treated as a custom ReactNode (e.g. an `<Icon />`).
* - 'auto': numbered badge for not-yet-reached steps, a check once completed
* (default)
* - 'number': always a numbered badge
* - 'none': no indicator — just the progress bar and label
*/
export type StepIndicatorPreset = 'auto' | 'number' | 'none';
export type StepDensity = 'compact' | 'balanced' | 'spacious';
export interface StepProps extends BaseProps<HTMLLIElement> {
/** Ref forwarded to the root element */
ref?: React.Ref<HTMLLIElement>;
/**
* Zero-based index of this step. Used to derive progress (completed /
* active / not-started) 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. Compact
* horizontal steppers hide it without unmounting it, preserving local state.
*/
children?: ReactNode;
/**
* Semantic status for the step, mapped to the global Astryx semantic tokens
* (`accent`, `success`, `warning`, `error`). In the default `auto` indicator
* mode it sets both the indicator color and a matching glyph: `success` shows
* a green check-circle, `warning`/`error` show the shared Input status icons.
* `accent` is color-only. The current (in-progress) step always keeps its
* current-step indicator regardless of `status`. Never recolors the
* connector/track.
*
* Because the indicator glyphs are decorative (aria-hidden), the status also
* reaches assistive technology as text: visually hidden "completed" /
* "warning" / "error" next to the label, and composed into the accessible
* name of clickable steps.
*/
status?: StepStatus;
/**
* Disable interaction for this step.
* @default false
*/
isDisabled?: boolean;
/**
* Marks the step as optional, appending an "Optional" affordance after the
* label.
* @default false
*/
isOptional?: boolean;
/**
* Trailing content rendered at the end of the label row (e.g. a timestamp
* or status chip).
*/
endContent?: ReactNode;
/**
* What to show as the step indicator. Accepts a preset string or any
* ReactNode:
* - 'auto': numbered badge until completed, then a check (default)
* - 'number': always a numbered badge
* - 'none': no indicator, just the bar + label
* - ReactNode: any custom icon or element to render as the indicator
* @default 'auto'
*/
indicator?: StepIndicatorPreset | ReactNode;
/**
* Controls vertical padding of the step. Falls back to the stepper-level
* density when unset.
* - 'compact': minimal padding (4px block)
* - 'balanced': default (8px block)
* - 'spacious': generous (12px block, 12px inline)
*/
density?: StepDensity;
}
// --- Default progress icons (16px) ---
//
// The `completed` progress state and the current-step ring are drawn as local
// <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() {
return (
<svg width="16" height="16" viewBox="0 0 16 16" fill="none">
<circle cx="8" cy="8" r="8" fill="currentColor" />
<path
d="M4.75 8.25 7 10.5l4.25-4.5"
stroke={colorVars['--color-background-surface']}
strokeWidth="1.75"
strokeLinecap="round"
strokeLinejoin="round"
/>
</svg>
);
}
/** Filled dot in a ring — shown for the active step in 'auto' mode. */
function CurrentIcon() {
return (
<svg width="16" height="16" viewBox="0 0 16 16" fill="none">
<circle cx="8" cy="8" r="7" stroke="currentColor" strokeWidth="2" />
<circle cx="8" cy="8" r="4" fill="currentColor" />
</svg>
);
}
// --- Styles ---
const BAR_WIDTH = spacingVars['--spacing-1'];
/**
* How much of itself a connector gives up where it meets the indicator, read
* from the public `--step-connector-gap` declared on the Stepper root.
*
* Clipped, not padded. The gap has to apply to two layers — the track, which is
* the segment's own background, and the accent fill, which is an absolutely
* placed `::before`. Spending it on each separately meant two declarations on
* two boxes: a percentage then resolved against a different containing block
* for each and stopped them ~1.2px apart. `clip-path` is ONE declaration on the
* segment that clips the element and its pseudo-element together, against one
* reference box — so every accepted value behaves the same way on both layers,
* which is what a public input owes its full value domain.
*
* Clipping also cannot change layout: the segment keeps its box, so the node it
* positions cannot move and the Stepper cannot grow. A raw `1rem` padding grew
* a 180px stepper to 240px.
*
* Still clamped, because the value arrives with nothing in between to reject
* it. Both halves earn their place, and not for the reasons padding needed:
*
* - `max(0px, …)` — `inset()` ACCEPTS a negative length. Chromium computes
* `inset(0 0 -4px 0)` as-is rather than dropping it, which is the opposite
* of padding (there CSS clamps a negative to `0` for you). This normalises
* it to `0` so a negative gap means "no gap" rather than a clip rect
* stretched outside the segment's own box.
* - `min(…, --spacing-2)` — the flexible segment's own `min-height`, so an
* oversized gap leaves a short track rather than an unbounded one.
*
* The Stepper root explicitly inherits the property, so a horizontal Stepper
* can receive a consumer value (or its 0px default) from the styled frame while
* a theme can still set the property directly on the `stepper` target. The
* use-site fallback supplies the same default to an unframed vertical Stepper.
*/
const CONNECTOR_GAP = `max(0px, min(var(--step-connector-gap, 0px), ${spacingVars['--spacing-2']}))`;
// Every indicator — check, ring, custom icon, number badge — occupies the same
// box, so the `auto` mode swapping a number for a check as a step completes
// never nudges the label or the track.
const INDICATOR_SIZE = spacingVars['--spacing-4'];
// Indicator (16px) + the label-row gap (8px). The indent that lines a
// description or a content slot up with the label above it.
const INDICATOR_GUTTER = spacingVars['--spacing-6'];
// --- Connector fill motion ---
//
// One change animates: advancing exactly one step. Going back, jumping
// forward by more than one, and mounting mid-flow all apply at once.
//
// Animating the others was tried and read worse than not animating them. A
// retreat is the clearest case: run forward, the transition ends with a bar
// that is nearly full, and nearly full is indistinguishable from full, so the
// eye calls it arrived well before it settles. Run backward, the same curve
// ends with a shrinking stub of accent still on the track, and a remnant that
// is still there reads unmistakably as not finished. Identical arithmetic in
// both directions — measurably so — and the backward one still feels slow,
// because the tail is what is visible rather than what is hidden. No easing
// fixes that; only not animating it does. A multi-step jump fails differently:
// it is a navigation rather than a progression, and sweeping a front across
// four segments makes the user sit through a journey they asked to skip.
//
// What is left is the one gesture where the movement carries the meaning: the
// flow went forward one step, and the line grows to show it. That span takes
// the medium band — a fill crossing a whole segment is a spatial change, not a
// micro-interaction, so per `astryx docs motion` it sits above the fast band
// reserved for high-frequency states like hover.
const FILL_SPAN_TIME = durationVars['--duration-medium'];
// Share of one node-to-node span owned by the segment *arriving* at the far
// node; the segment leaving the near node takes the rest. On-track spans are
// drawn by two steps (see the ON-TRACK section), and the time has to be split
// the way the length is or the two halves sweep at visibly different speeds.
//
// Horizontal: both halves are `flex: 1` inside equal-width steps, so an even
// split is the proportional one.
//
// Vertical: the halves are nothing like equal, and no constant can be right
// for all of them. The arriving half is otSegLeadV, a cap fixed at one density
// space; the leaving half is otSegFlexV, grown to whatever is left of the step
// row, so its length turns on label and description lengths this file cannot
// see. Measured in the browser the cap is 40% of a plain balanced span (8 of
// 20px) but 21% once the step carries a description (8 of 38px). 0.3 is the
// value that minimises the worse of those two: it leaves the cap ~1.6x off the
// rail's speed either way, where tuning to one case puts the other past 2x.
// Matching each case exactly would mean measuring the rendered rail, a layout
// read this system avoids.
const OT_ARRIVAL_SHARE_H = 0.5;
const OT_ARRIVAL_SHARE_V = 0.3;
// A vertical step carrying a content slot draws a third segment down the side
// of it (otContentSegV) which continues the leaving half past the row, so the
// leaving half's time splits again. A slot runs several times the rail left
// above it — 34px of rail to 108px of slot in the spacious content story — and
// this is the middle of that range. Matching it exactly would mean measuring
// the rendered slot; the ordering is what keeps the front contiguous, and this
// keeps its speed in the right neighbourhood.
const OT_RAIL_SHARE_OF_LEAVING = 0.25;
/** Scale a CSS `<time>` by a unitless factor, collapsing the trivial cases. */
function fillTimeSlice(time: string, factor: number): string {
if (factor <= 0) {
return '0s';
}
if (factor === 1) {
return time;
}
// Rounded because the factors are sums of shares, and float noise would
// otherwise reach the emitted custom property as `calc(... * 0.7000000001)`.
return `calc(${time} * ${Number(factor.toFixed(4))})`;
}
const styles = stylex.create({
// ===================== VERTICAL LAYOUT =====================
verticalRoot: {
display: 'flex',
flexDirection: 'row',
alignItems: 'stretch',
position: 'relative',
gap: spacingVars['--spacing-0-5'],
},
// 4px progress bar segment. Its filled/unfilled paint comes from the shared
// connector styles below, not from here.
verticalBar: {
width: BAR_WIDTH,
borderRadius: radiusVars['--radius-full'],
flexShrink: 0,
alignSelf: 'stretch',
},
// Step body — the selectable area
verticalBody: {
display: 'flex',
flexDirection: 'column',
flex: 1,
},
// ===================== HORIZONTAL LAYOUT =====================
horizontalStep: {
display: 'flex',
flexDirection: 'column',
// Stretch, not flex-start: a flex-start child is sized to fit-content,
// which is floored at its own min-content and would spill the label past
// the step's slice of the track and into the next step. Stretched, the
// label row is exactly as wide as the step and the label ellipsizes
// inside it.
alignItems: 'stretch',
flex: 1,
// `flex: 1` alone does not make the steps equal: a flex item's default
// `min-width: auto` floors it at its own min-content width, so a step
// labelled "Integrations" claims a wider slice of the track than one
// labelled "Team". Zeroing the floor lets the even distribution actually
// apply, which is what keeps every progress segment the same width.
minWidth: 0,
// density padding applied via density styles below
},
// Full-width progress bar segment sitting above each horizontal step.
// Each step owns its own segment (filled from its derived progress) so the
// parent never has to introspect children to build the bar.
horizontalBar: {
width: '100%',
height: BAR_WIDTH,
borderRadius: radiusVars['--radius-full'],
flexShrink: 0,
marginBlockEnd: spacingVars['--spacing-0-5'],
},
// ===================== CONNECTOR FILL =====================
// Shared by every connector the four layout combinations draw: the separated
// bars (verticalBar, horizontalBar) and the on-track segments (otSegBaseV,
// otSegH, otContentSegV).
//
// The segment element is the *unfilled* track and never changes color; the
// accent fill is a ::before scaled along the track axis. Advancing a step
// grows it out of the segment's leading edge, so the line reads as progress
// travelling rather than a bar changing state. The obvious alternative,
// transitioning `background-color` between accent and border on the segment
// itself, lights the whole segment at once: a flash, with no direction in
// it. Going the other way the scale still returns to zero, but instantly —
// only a single step forward is given a duration to cross (see the motion
// block above).
//
// A pseudo-element rather than a real child element, because the connector is
// emitted from seven places and several of them size themselves in ways a
// child would have to re-derive (otSegFlexV grows, otSegLeadV is fixed,
// otContentSegV is absolutely positioned). ::before inherits the box for
// free, so one style covers all of them.
//
// Mount is deliberately not animated, and falls out of how transitions work:
// interpolation needs a previous computed value and a freshly rendered
// element has none. A stepper that opens on step 3 paints the segments behind
// it filled, instantly, instead of playing its whole history back.
connectorTrack: {
position: 'relative',
backgroundColor: colorVars['--color-border'],
'::before': {
content: '""',
position: 'absolute',
inset: 0,
// Follows whatever the segment itself rounds to: the full pill of a
// separated bar, the square ends the on-track segments need in order to
// stack into one continuous line.
borderRadius: 'inherit',
backgroundColor: colorVars['--color-accent'],
transitionProperty: 'transform',
// Resting duration, for a segment moving on its own. connectorTiming
// below replaces it on every connector — each one is handed either its
// slice of the animated span or a zero — so this is the fallback that
// applies if a connector is ever rendered without it.
transitionDuration: {
default: FILL_SPAN_TIME,
'@media (prefers-reduced-motion: reduce)': '0s',
},
// Linear, deliberately, and not the `--ease-standard` the rest of the
// system transitions on. A node-to-node span is not always one element:
// in the on-track layouts the segment leaving one node and the segment
// arriving at the next draw it between them, and a vertical step with a
// content slot splits it three ways. A curve applied per segment
// restarts its deceleration at every seam, so the front lurches, stalls
// at the joint, and the joint becomes the most visible thing in the
// animation — the fill stops reading as one line growing and starts
// reading as two pieces taking turns. Linear is the only timing that
// stitches into a single constant-speed front. The separated bars run
// linear too: a lone segment gives up very little by it, and the two
// layouts should not animate with different character.
transitionTimingFunction: 'linear',
},
},
// This segment's slice of the animated span, or a pair of zeros for a
// segment that is not part of it (see the motion block above the styles).
// Dynamic because which segments animate, and over what part of the span,
// depends on where the active step just moved from — known only at render.
// StyleX routes the values through a custom property, so these are still
// generated rules and not inline styles.
//
// Restates the reduced-motion escape connectorTrack declares rather than
// relying on it: a StyleX style that redefines a property replaces the
// earlier definition wholesale, conditions included. Without it a
// reduced-motion user would get an on-track span as two instant snaps spaced
// apart by the delay — motion smuggled back in as timing. Zeroing the delay
// alongside the duration lands the whole span at once instead.
connectorTiming: (duration: string, delay: string) => ({
'::before': {
transitionDuration: {
default: duration,
'@media (prefers-reduced-motion: reduce)': '0s',
},
transitionDelay: {
default: delay,
'@media (prefers-reduced-motion: reduce)': '0s',
},
},
}),
// Vertical track: progress runs down the block axis under both LTR and RTL
// (direction only mirrors the inline axis), so the growth anchors at the
// physical top either way.
connectorFillV: {
'::before': {transformOrigin: 'center top', transform: 'scaleY(1)'},
},
connectorEmptyV: {
'::before': {transformOrigin: 'center top', transform: 'scaleY(0)'},
},
// Horizontal track: progress runs along the reading direction, so the growth
// anchors at the inline-start edge — physically left in LTR, right in RTL.
// `transform-origin` accepts no logical keywords, so the flip is spelled out
// with the same `:is([dir="rtl"] *)` hook Switch's thumb travel and the
// shared rtlStyles.mirror use. Stated on both states rather than hoisted onto
// connectorTrack, which is axis-agnostic and shared with the vertical
// segments.
connectorFillH: {
'::before': {
transformOrigin: {
default: 'left center',
':is([dir="rtl"] *)': 'right center',
},
transform: 'scaleX(1)',
},
},
connectorEmptyH: {
'::before': {
transformOrigin: {
default: 'left center',
':is([dir="rtl"] *)': 'right center',
},
transform: 'scaleX(0)',
},
},
// ===================== SHARED =====================
// Icon + Label in one row
iconLabelRow: {
display: 'flex',
flexDirection: 'row',
alignItems: 'center',
gap: spacingVars['--spacing-2'],
// The row is a flex item wherever a step stacks it under a bar, so it
// needs the floor released too — otherwise it holds itself open at the
// label's min-content width and the label never reaches its ellipsis.
minWidth: 0,
},
// Indicator icon container
icon: {
display: 'flex',
alignItems: 'center',
justifyContent: 'center',
width: INDICATOR_SIZE,
height: INDICATOR_SIZE,
flexShrink: 0,
},
iconCompleted: {
color: colorVars['--color-accent'],
},
iconInProgress: {
color: colorVars['--color-accent'],
},
iconNotStarted: {
color: colorVars['--color-icon-secondary'],
},
iconDisabled: {
color: colorVars['--color-icon-disabled'],
opacity: 0.5,
},
// Semantic status overrides for the icon — color only.
iconAccent: {
color: colorVars['--color-accent'],
},
iconSuccess: {
color: colorVars['--color-icon-success'],
},
iconWarning: {
color: colorVars['--color-icon-warning'],
},
iconError: {
color: colorVars['--color-icon-error'],
},
// Number badge — same box as every other indicator (see INDICATOR_SIZE).
numberBadge: {
display: 'grid',
// Forced colors replace status fills with Canvas; this boundary keeps the
// fill's shape visible (architecture:theme-tokens INV11).
outlineWidth: {default: null, '@media (forced-colors: active)': '1px'},
outlineStyle: {default: null, '@media (forced-colors: active)': 'solid'},
outlineColor: {
default: null,
'@media (forced-colors: active)': 'CanvasText',
},
outlineOffset: {default: null, '@media (forced-colors: active)': '-1px'},
placeItems: 'center',
width: INDICATOR_SIZE,
height: INDICATOR_SIZE,
borderRadius: radiusVars['--radius-full'],
// The digit has to read at the same optical weight as the check glyph it
// alternates with inside a 16px circle, which the supporting size (12px)
// overfills — it leaves no room for a two-digit step. This is the scale
// step below it, still a token so themes rescale it. The digit is centered
// by the grid (placeItems), so no explicit line-height is needed — this
// matches how Avatar/AvatarGroup center a single glyph in a circle.
fontSize: textSizeVars['--font-size-xs'],
fontWeight: fontWeightVars['--font-weight-semibold'],
flexShrink: 0,
textAlign: 'center',
},
numberCompleted: {
backgroundColor: colorVars['--color-accent'],
color: colorVars['--color-background-surface'],
},
numberInProgress: {
backgroundColor: colorVars['--color-accent'],
color: colorVars['--color-background-surface'],
},
numberNotStarted: {
backgroundColor: colorVars['--color-background-muted'],
color: colorVars['--color-text-secondary'],
},
numberDisabled: {
backgroundColor: colorVars['--color-background-muted'],
color: colorVars['--color-text-disabled'],
opacity: 0.5,
},
// Semantic status overrides for the number badge — color only.
numberAccent: {
backgroundColor: colorVars['--color-accent'],
color: colorVars['--color-on-accent'],
},
numberSuccess: {
backgroundColor: colorVars['--color-success'],
color: colorVars['--color-on-success'],
},
numberWarning: {
backgroundColor: colorVars['--color-warning'],
color: colorVars['--color-on-warning'],
},
numberError: {
backgroundColor: colorVars['--color-error'],
color: colorVars['--color-on-error'],
},
// Label
label: {
fontSize: typeScaleVars['--text-body-size'],
lineHeight: typeScaleVars['--text-body-leading'],
fontWeight: fontWeightVars['--font-weight-normal'],
color: colorVars['--color-text-primary'],
// Horizontal steps divide the track evenly, so a label can end up with
// less room than it wants. It stays on one line and ellipsizes rather than
// wrapping, so every step in a row keeps the same height and the track
// below them stays straight. minWidth releases the flex floor that would
// otherwise hold the label at its min-content width and let it overlap the
// neighbouring step. Inert wherever there is room, which is most vertical
// steppers. The full string stays in the accessible name either way.
minWidth: 0,
whiteSpace: 'nowrap',
overflow: 'hidden',
textOverflow: 'ellipsis',
},
labelInProgress: {
fontWeight: fontWeightVars['--font-weight-semibold'],
},
labelNotStarted: {
color: colorVars['--color-text-secondary'],
},
labelDisabled: {
color: colorVars['--color-text-disabled'],
},
// Optional tag
optionalDot: {
fontSize: typeScaleVars['--text-body-size'],
color: colorVars['--color-text-secondary'],
},
optionalText: {
fontSize: typeScaleVars['--text-body-size'],
color: colorVars['--color-text-secondary'],
},
// Description
descriptionRow: {
paddingInlineStart: spacingVars['--spacing-0'],
},
descriptionRowWithIndicator: {
paddingInlineStart: INDICATOR_GUTTER,
},
description: {
// Block, not inline. An inline span is laid out in a line box belonging to
// its parent, and that box is floored by the parent's strut — the invisible
// box every block container reserves from its own font and line-height. The
// row inherits the page's 16px/24px, so an inline description sat in a 24px
// line box no matter how tight its own leading was, padding the gap under
// the label. Blockifying moves the strut onto this span, where the metrics
// below apply and the box hugs the text at 16px.
display: 'block',
fontSize: typeScaleVars['--text-supporting-size'],
// The supporting-leading token (1.667 → 20px at 12px) reads too loose for
// a caption sitting under its label; a fixed 16px line box (the --spacing-4
// step) is tighter without collapsing the text the way capsize trim did,
// and stays on the spacing scale rather than a raw literal.
lineHeight: spacingVars['--spacing-4'],
color: colorVars['--color-text-secondary'],
},
// Step content (children / flex slot)
stepContent: {
paddingBlockStart: spacingVars['--spacing-2'],
},
// The label row sits inside the density-padded hover target, but the content
// slot is that target's *sibling* — a <button> cannot contain the buttons and
// inputs a content slot usually holds, so the slot has to live outside it.
// Left alone the slot therefore starts at the step edge while the label above
// starts one density pad in. Reproducing that pad here is what keeps the two
// flush; the gutter on top of it is what lines the content up with the label
// rather than with the indicator.
contentIndent: (inlinePad: string, gutter: string) => ({
paddingInlineStart: `calc(${inlinePad} + ${gutter})`,
paddingInlineEnd: inlinePad,
}),
// Density. Block padding only — the inline half comes from densityInline,
// which is passed in so the content slot outside this wrapper can apply the
// same value.
densityCompact: {
paddingBlock: spacingVars['--spacing-1'],
},
densityBalanced: {
paddingBlock: spacingVars['--spacing-2'],
},
densitySpacious: {
paddingBlock: spacingVars['--spacing-3'],
},
densityInline: (value: string) => ({
paddingInline: value,
}),
// Button reset for clickable steps
buttonReset: {
textAlign: 'start',
alignItems: 'stretch',
display: 'flex',
flexDirection: 'column',
width: '100%',
cursor: {
default: 'pointer',
':is(:disabled,[aria-disabled="true"])': 'default',
},
borderRadius: radiusVars['--radius-element'],
transitionProperty: 'background-color',
transitionDuration: {
default: durationVars['--duration-fast-min'],
'@media (prefers-reduced-motion: reduce)': '0s',
},
transitionTimingFunction: easeVars['--ease-standard'],
backgroundColor: 'transparent',
},
// ===================== ON-TRACK LAYOUT =====================
// Indicator is slotted into the connector line as a node on the track.
// Each step draws the connector segments that flank its own indicator; the
// segment *before* the indicator is hidden on the first step (step === 0) so
// the track starts at the first node. Segments abut the indicator directly,
// so no child introspection or total-count is needed.
otVerticalRoot: {
display: 'flex',
flexDirection: 'column',
position: 'relative',
},
otHorizontalRoot: {
display: 'flex',
flexDirection: 'column',
flex: 1,
minWidth: 0,
},
// Interactive wrapper (indicator + label act as one click target).
otInteractive: {
boxSizing: 'border-box',
// Force start alignment so vertical labels/descriptions read left-aligned. Horizontal
// labels re-center via otLabelWrapH (a deeper element).
textAlign: 'start',
cursor: {
default: 'pointer',
':is(:disabled,[aria-disabled="true"])': 'default',
},
borderRadius: radiusVars['--radius-element'],
transitionProperty: 'background-color',
transitionDuration: {
default: durationVars['--duration-fast-min'],
'@media (prefers-reduced-motion: reduce)': '0s',
},
transitionTimingFunction: easeVars['--ease-standard'],
backgroundColor: 'transparent',
},
otRowWrap: {
display: 'flex',
flexDirection: 'row',
alignItems: 'stretch',
gap: spacingVars['--spacing-2'],
width: '100%',
},
otColWrap: {
display: 'flex',
flexDirection: 'column',
alignItems: 'stretch',
width: '100%',
},
// Vertical indicator column: [segment] [indicator] [segment] stacked.
otIndicatorColV: {
display: 'flex',
flexDirection: 'column',
alignItems: 'center',
width: INDICATOR_SIZE,
flexShrink: 0,
alignSelf: 'stretch',
},
// Shared segment base: square ends so stacked segments read as one
// continuous line (no radius).
otSegBaseV: {
width: BAR_WIDTH,
flexShrink: 0,
borderRadius: 0,
},
// The gap a connector leaves where it meets the indicator, spent on the side
// that faces the node so the pair leaves a symmetric hole around it.
//
// Clip the segment rather than changing its box: one `clip-path` clips the
// segment's own track and its absolutely positioned `::before` fill against
// the same reference box. The indicator stays put, the Stepper cannot grow,
// and percentage values cannot resolve differently between the two layers.
// The inherited value is clamped in CONNECTOR_GAP; its default is declared
// once on the Stepper root, where a generated theme override can replace it.
//
// A public var rather than a per-segment theme vocabulary: "do not touch the
// indicator" is one intent, and naming the segments would publish which
// pieces this layout happens to be drawn from today.
otSegGapLeadV: {
clipPath: `inset(0 0 ${CONNECTOR_GAP} 0)`,
},
otSegGapRailV: {
clipPath: `inset(${CONNECTOR_GAP} 0 0 0)`,
},
// The horizontal pair is PHYSICAL: `clip-path: inset()` takes top/right/
// bottom/left and has no logical form, while the row itself reverses under
// `dir="rtl"`. Left unflipped, the leading segment sits to the RIGHT of the
// node in RTL and still clips its right edge — opening the hole at the join
// between steps instead of at the indicator. The block axis needs no such
// handling: `dir` does not reverse it.
otSegGapLeadH: {
clipPath: {
default: `inset(0 ${CONNECTOR_GAP} 0 0)`,
':is([dir="rtl"] *)': `inset(0 0 0 ${CONNECTOR_GAP})`,
},
},
otSegGapRailH: {
clipPath: {
default: `inset(0 0 0 ${CONNECTOR_GAP})`,
':is([dir="rtl"] *)': `inset(0 ${CONNECTOR_GAP} 0 0)`,
},
},
// Flexible segment (below the node) — grows to fill the step height and
// meets the next node's leading segment.
otSegFlexV: {
flex: 1,
minHeight: spacingVars['--spacing-2'],
},
// Fixed leading segment (above the node) — its height offsets the node down
// so it aligns with the label's first line instead of the step's center.
otSegLeadV: (value: string) => ({
height: value,
}),
// Horizontal track row: [segment] [indicator] [segment] in a line.
otTrackRowH: {
display: 'flex',
flexDirection: 'row',
alignItems: 'center',
width: '100%',
},
otSegH: {
height: BAR_WIDTH,
flex: 1,
minWidth: spacingVars['--spacing-2'],
borderRadius: 0,
},
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',
},
},
otBodyV: {
display: 'flex',
flexDirection: 'column',
justifyContent: 'flex-start',
flex: 1,
gap: spacingVars['--spacing-0-5'],
minWidth: 0,
},
otLabelWrapH: {
display: 'flex',
flexDirection: 'column',
// Stretch rather than center for the same reason as horizontalStep: a
// centered child is fit-content sized and would spill past its node.
// The label still reads centered under the node — otLabelRowCenter
// centers it inside the full-width row.
alignItems: 'stretch',
gap: spacingVars['--spacing-0-5'],
textAlign: 'center',
},
otLabelRowStart: {
display: 'flex',
flexDirection: 'row',
alignItems: 'center',
gap: spacingVars['--spacing-2'],
},
otLabelRowCenter: {
display: 'flex',
flexDirection: 'row',
alignItems: 'center',
justifyContent: 'center',
flexWrap: 'wrap',
gap: spacingVars['--spacing-1'],
},
// Inline offset comes from contentIndent, and only in the vertical layout —
// a horizontal on-track step pads its hover target on the block axis alone,
// so its content slot already starts flush with the column above it.
otContent: {
paddingBlockStart: spacingVars['--spacing-2'],
},
// A vertical on-track step draws its connector inside the row holding the
// indicator and label, and the content slot sits below that row rather than
// in it (the row is a <button> when the step is clickable, which cannot
// contain the controls a content slot usually holds). So the line stops at
// the label and the track breaks open wherever a step carries content.
// otContentSegV continues it: a segment spanning the slot's full height, on
// the same rail the row's segments run down, which closes the gap between
// this step's indicator and the next one's.
otContentWrapV: {
position: 'relative',
},
otContentSegV: (inlinePad: string) => ({
position: 'absolute',
insetBlock: 0,
// Center on the rail: the row pads itself by inlinePad, then centers a
// BAR_WIDTH line inside an INDICATOR_SIZE-wide column.
insetInlineStart: `calc(${inlinePad} + (${INDICATOR_SIZE} - ${BAR_WIDTH}) / 2)`,
width: BAR_WIDTH,
}),
// Density-driven spacing. The connector runs along the "track axis"
// (vertical = block, horizontal = inline), so density is only ever applied
// to the *cross* axis — padding the track axis would break the line into
// gapped segments.
//
// Vertical: pad the whole step row (indicator rail + label) so density adds
// breathing room *around the indicators*, not just the text. Applied to the
// hover target itself.
otRowPadV: (value: string) => ({
paddingBlock: value,
paddingInline: value,
}),
// The rail draws the connector, so it must span the row's full block extent
// to keep the line continuous. A negative block margin cancels the wrapper's
// block padding, letting the line bridge step-to-step while the label still
// sits inside the padding.
otRailBridgeV: (value: string) => ({
marginBlock: `calc(-1 * ${value})`,
}),
// Horizontal: block padding around the track+label column (inside the hover
// target) adds vertical breathing room while the inline track stays flush.
otPadBlock: (value: string) => ({
paddingBlock: value,
}),
otMarginTop: (value: string) => ({
marginBlockStart: value,
}),
// The current step, named below a track whose own labels have collapsed.
// Centred rather than indented under an indicator: there is one of these and
// it sits under the whole track, so it lines up with the track's middle and
// not with any one segment of it.
summaryRoot: {
alignItems: 'center',
display: 'flex',
flexDirection: 'column',
gap: spacingVars['--spacing-0-5'],
minWidth: 0,
},
});
/**
* An individual step within an Stepper. Renders a 4px progress-bar segment,
* an indicator (numbered badge, check, or any custom icon), a label with
* optional description, and an optional content slot.
*
* Progress (completed / active / not-started) is derived from the parent's
* `activeStep` and this step's `step` prop. The optional `status` prop layers a
* semantic meaning on top: in the default `auto` indicator mode it recolors the
* indicator and swaps in a matching glyph (`success` → green check-circle,
* `warning`/`error` → the shared Input status icons). The current step always
* keeps its current-step ring. `status` never recolors the connector/track.
*
* @example
* ```
* <Step step={0} label="Account details" description="Enter your email" />
* ```
*
* @example
* ```
* <Step step={1} label="Payment" status="error" />
* ```
*/
export function Step({
step,
label,
description,
children,
status,
isDisabled = false,
isOptional = false,
endContent,
indicator: indicatorProp,
density: densityProp,
xstyle,
className,
style,
ref,
'data-testid': dataTestId,
...rest
}: StepProps) {
const pressable = usePressFeedback();
const t = useComponentTranslator();
const ctx = useStepperInternalContext();
const {
activeStep,
previousActiveStep,
orientation,
onStepClick,
density: ctxDensity,
indicatorPosition,
registerStep,
isCompact,
summarySlot,
} = ctx;
// Register this step index with the parent Stepper, which uses the tally to
// warn about duplicate indices and work out how much width each step gets.
// The optional getter keeps disabled state owned by this Step while compact
// navigation can read its latest registration.
//
// A layout effect, not an effect: the width each step has is the stepper's
// width divided by this count, so a stepper narrow enough to collapse can
// only know it once every step is counted. Running after paint would show
// the full stepper for a frame and then snap it shut.
useLayoutEffect(
() => registerStep(step, {getIsDisabled: () => isDisabled}),
[registerStep, step, isDisabled],
);
const density = densityProp ?? ctxDensity;
// Inline padding of a separated step's hover target. Density varies the block
// padding freely, but the inline value has to be readable from out here: the
// content slot renders outside that target and re-applies it to stay aligned
// (see contentIndent), so keeping it in one place is what stops the two
// drifting apart.
const separatedDensityInline =
density === 'spacious'
? spacingVars['--spacing-3']
: spacingVars['--spacing-2'];
// Resolve indicator prop — may be a preset string or a custom ReactNode.
const isCustomIndicator =
indicatorProp != null && typeof indicatorProp !== 'string';
const indicator: StepIndicatorPreset = isCustomIndicator
? 'auto'
: ((indicatorProp as StepIndicatorPreset | undefined) ?? 'auto');
// Internal progress, derived from the parent's activeStep. This is NOT the
// public `status` prop — `status` controls semantic color only.
const progress: 'completed' | 'in-progress' | 'not-started' =
step === activeStep
? 'in-progress'
: step < activeStep
? 'completed'
: 'not-started';
const isVertical = orientation === 'vertical';
const isActive = progress === 'in-progress';
// A compact horizontal stepper moves navigation to the named controls in its
// summary row. Its track — including the on-track indicators — stays purely
// presentational so it does not expose a second, denser set of click targets.
const hasButton = onStepClick != null && !isCompact;
// A disabled step keeps its button, focusable and aria-disabled, so it
// keeps its tab stop, is announced as unavailable, and keeps focus when it
// becomes disabled while focused (`spec:AST-085` FR1, FR4, FR5); only
// activation is withheld.
const isClickable = hasButton && !isDisabled;
const handleClick = () => {
if (isClickable && onStepClick) {
onStepClick(step);
}
};
// Bar fill is purely progress-based. `status` never recolors the bar — it
// only recolors the indicator (icon / number badge) below.
const isBarFilled = progress === 'completed' || progress === 'in-progress';
// --- This step's slice of the animated span ---
// Both layouts are measured in the same unit, the node-to-node span: on-track
// span k runs from node k to node k+1, and a separated step's lone bar is the
// span arriving at it (bar s fills on exactly the condition span s-1 does).
// So one rule serves both, and neither needs to know the step count.
//
// Only a single forward step animates, and the span it crosses is the one
// leaving the step the flow came from. Every other segment — the untouched
// ones, and every segment of a jump or a retreat — is handed a zero
// duration, so it lands at once and carries no stale delay into a later
// change.
const isSingleAdvance = activeStep === previousActiveStep + 1;
const animatedSpan = previousActiveStep;
/**
* Timing for the segment covering `[offset, offset + share)` of span
* `spanIndex`, both expressed as fractions of that span.
*/
const fillTiming = (spanIndex: number, offset: number, share: number) => {
if (!isSingleAdvance || spanIndex !== animatedSpan) {
return styles.connectorTiming('0s', '0s');
}
return styles.connectorTiming(
fillTimeSlice(FILL_SPAN_TIME, share),
fillTimeSlice(FILL_SPAN_TIME, offset),
);
};
// A separated step draws the whole span arriving at it, so it fills for the
// span's entire slice with nothing to sequence against.
const barTiming = fillTiming(step - 1, 0, 1);
// --- Build indicator node ---
// 'auto': number for not-started, check/dot icon once reached
// 'number': always number badge
// 'none': nothing
// custom ReactNode (or `icon` prop): render as-is
let indicatorNode: ReactNode = null;
const customIcon = isCustomIndicator ? indicatorProp : null;
// Semantic `status` drives a distinct indicator glyph (default 'auto' mode,
// no custom icon), all sourced from the themed Icon registry so a step reads
// the same as the rest of the system:
// - success → the themed `success` glyph (same check-circle as a completed
// step), tinted success — i.e. a green check
// - warning → the themed `warning` glyph
// - error → the themed `error` glyph
// The current (in-progress) step always shows the current-step ring — its
// indicator "replaces" any status glyph. `accent` has no distinct glyph and
// falls through to the progress-derived default.
const statusGlyph: 'success' | 'warning' | 'error' | null =
indicator === 'auto' &&
customIcon == null &&
!isActive &&
(status === 'success' || status === 'warning' || status === 'error')
? status
: null;
if (indicator !== 'none') {
const showNumber =
customIcon == null &&
statusGlyph == null &&
(indicator === 'number' ||
(indicator === 'auto' && progress === 'not-started'));
if (showNumber) {
// Status only fills the badge once the step is reached. A not-started
// step stays neutral — otherwise `accent` (which has no glyph to swap in)
// would paint an inverted accent badge on an upcoming step, making it
// read as active/completed.
const isReached = progress === 'completed' || progress === 'in-progress';
const numberColorStyle = isDisabled
? styles.numberDisabled
: isReached && status === 'accent'
? styles.numberAccent
: isReached && status === 'success'
? styles.numberSuccess
: isReached && status === 'warning'
? styles.numberWarning
: isReached && status === 'error'
? styles.numberError
: progress === 'completed'
? styles.numberCompleted
: progress === 'in-progress'
? styles.numberInProgress
: styles.numberNotStarted;
indicatorNode = (
<div
aria-hidden="true"
{...mergeProps(
themeProps('step-indicator', {
progress,
status: status ?? undefined,
}),
stylex.props(styles.numberBadge, numberColorStyle),
)}>
{step + 1}
</div>
);
} else {
// Priority: explicit custom icon → status glyph (non-current steps) →
// progress-derived default (check when completed, ring when current).
const iconContent: ReactNode =
customIcon != null ? (
customIcon
) : statusGlyph === 'success' ? (
<Icon
icon="success"
size="sm"
color={isDisabled ? 'disabled' : 'success'}
/>
) : statusGlyph === 'warning' ? (
<Icon
icon="warning"
size="sm"
color={isDisabled ? 'disabled' : 'warning'}
/>
) : statusGlyph === 'error' ? (
<Icon
icon="error"
size="sm"
color={isDisabled ? 'disabled' : 'error'}
/>
) : progress === 'completed' ? (
<CheckCircleIcon />
) : (
<CurrentIcon />
);
// Wrapper tint drives the currentColor glyphs (check-circle / ring /
// custom icon). The <Icon> status glyphs set their own color, but we tint
// the wrapper to match so the indicator's color reflects `status` too.
const iconColorStyle = isDisabled
? styles.iconDisabled
: customIcon != null
? status === 'accent'
? styles.iconAccent
: status === 'success'
? styles.iconSuccess
: status === 'warning'
? styles.iconWarning
: status === 'error'
? styles.iconError
: progress === 'completed'
? styles.iconCompleted
: progress === 'in-progress'
? styles.iconInProgress
: styles.iconNotStarted
: statusGlyph === 'success'
? styles.iconSuccess
: statusGlyph === 'warning'
? styles.iconWarning
: statusGlyph === 'error'
? styles.iconError
: progress === 'completed'
? styles.iconCompleted
: progress === 'in-progress'
? styles.iconInProgress
: styles.iconNotStarted;
indicatorNode = (
<div
aria-hidden="true"
{...mergeProps(
themeProps('step-indicator', {
progress,
status: status ?? undefined,
}),
stylex.props(styles.icon, iconColorStyle),
)}>
{iconContent}
</div>
);
}
}
// Every indicator glyph above is aria-hidden (pure decoration), so the
// step's progress/status must also reach assistive tech as text
// (WCAG 1.4.1 / 1.3.1). `error`/`warning` announce the semantic status;
// `success` and a completed step both announce "completed". The current
// step is announced via aria-current="step" instead, and not-started steps
// stay silent (the default state needs no qualifier).
const statusText: string | null =
status === 'error'
? t('@astryx.step.status.error')
: status === 'warning'
? t('@astryx.step.status.warning')
: status === 'success' || progress === 'completed'
? t('@astryx.step.status.completed')
: null;
// Rendered next to the label: hidden text for static steps, and composed
// into the button's accessible name for clickable ones (an aria-label on
// the button would otherwise override the hidden text). Two separate keys
// rather than string concatenation so translations control the joiner.
const statusTextNode = isRenderable(statusText) ? (
<VisuallyHidden>{statusText}</VisuallyHidden>
) : null;
const stepAriaLabel =
statusText != null
? t('@astryx.step.goToStepWithStatus', {
stepNumber: step + 1,
label,
status: statusText,
})
: t('@astryx.step.goToStep', {stepNumber: step + 1, label});
const hasIndicator = indicator !== 'none';
const labelColorStyle = isDisabled
? styles.labelDisabled
: progress === 'not-started'
? styles.labelNotStarted
: isActive
? styles.labelInProgress
: undefined;
// Both text parts carry {progress, status}, the phase vocabulary of
// `step-indicator` above. The label additionally owns Stepper's disabled
// paint, so it alone carries disabled below.
const labelThemeProps = themeProps('step-label', {
progress,
status: status ?? undefined,
// The label owns Stepper's disabled paint (`styles.labelDisabled` above),
// so it owns the selector too. The description does not change under
// disabled and deliberately keeps the smaller {progress, status} surface.
disabled: isDisabled ? 'disabled' : null,
});
const descriptionThemeProps = themeProps('step-description', {
progress,
status: status ?? undefined,
});
// Indicator + Label row. In compact on-track mode the indicator remains
// visible on the rail, so the summary reuses this row without drawing the
// active indicator a second time beside the label.
const iconLabelNode = (
<div {...stylex.props(styles.iconLabelRow)}>
{(!isCompact || indicatorPosition !== 'on-track') && indicatorNode}
{/* A space between the indicator and the label: the row is a flex
container, which drops whitespace-only text, so nothing changes on
screen, but a text reading of the button then keeps "1 Account" as two
words instead of "1Account". */}{' '}
<span
{...mergeProps(
labelThemeProps,
stylex.props(styles.label, labelColorStyle),
)}>
{label}
</span>
{statusTextNode}
{isOptional && (
<>
<span {...stylex.props(styles.optionalDot)}>•</span>
<span {...stylex.props(styles.optionalText)}>
{t('@astryx.step.optional')}
</span>
</>
)}
{endContent}
</div>
);
// A clickable step's name is its number, label and status word; the
// description describes it, so a disabled step's reason reaches assistive
// technology too (spec:AST-085 FR5).
const descriptionID = useId();
const descriptionNode = isRenderable(description) ? (
<div
id={descriptionID}
{...stylex.props(
hasIndicator
? styles.descriptionRowWithIndicator
: styles.descriptionRow,
)}>
<span
{...mergeProps(
descriptionThemeProps,
stylex.props(styles.description),
)}>
{description}
</span>
</div>
) : null;
// Compact horizontal layouts hide public step content without unmounting it,
// so local state survives as the container crosses the threshold.
const contentNode = isRenderable(children) ? (
<div
hidden={isCompact || undefined}
{...stylex.props(
styles.stepContent,
styles.contentIndent(
separatedDensityInline,
hasIndicator ? INDICATOR_GUTTER : '0px',
),
)}>
{children}
</div>
) : null;
// Theme data attributes reflect progress + optional semantic status.
const stepThemeProps = themeProps('step', {
progress,
status: status ?? undefined,
});
// ======= SUMMARY: this step, drawn below a collapsed track =======
//
// Only the current step draws one, into a row the stepper owns and keeps
// outside the `<ol>` — so the list is left with exactly the children it was
// given, and the on-track connectors go on reading their own
// `:first-child`/`:last-child` position to decide which caps to hide.
//
// Rendered here rather than handed up as data because it reuses
// `iconLabelNode`: indicator resolution, status glyphs, completed checks,
// disabled tints, and the compact on-track rule above stay in one place. The
// description is re-wrapped, though — the row version indents itself under
// an indicator, and centred under a track there is nothing to line it up with.
const summaryNode =
isCompact && isActive && summarySlot != null
? createPortal(
<div
{...mergeProps(stepThemeProps, stylex.props(styles.summaryRoot))}>
{iconLabelNode}
{isRenderable(description) ? (
<span {...stylex.props(styles.description)}>{description}</span>
) : null}
</div>,
summarySlot,
)
: null;
// Every compact step is presentational, including on-track indicators, so
// each item restores its label and status as hidden text. The list stays a
// complete ordered sequence with `aria-current` intact, while the summary row
// below it owns the compact navigation controls and remains decorative apart
// from those buttons.
const compactNameNode = isCompact ? (
<>
<VisuallyHidden>{label}</VisuallyHidden>
{statusTextNode}
</>
) : null;
// ======= ON-TRACK: indicator is a node on the connector =======
if (indicatorPosition === 'on-track') {
// Connector fill is purely progress-based (matches the separated bar):
// the segment before the indicator is "reached" once we're at/past this
// step; the segment after is filled only once this step is completed.
// `status` never recolors the connector — only the indicator.
const beforeFilled = step <= activeStep;
const afterFilled = step < activeStep;
// Both segments animate their fill along the track (see connectorTrack), so
// the pair is picked by orientation: the vertical column scales down its
// block axis, the horizontal row along the reading direction.
const segFilledStyle = isVertical
? styles.connectorFillV
: styles.connectorFillH;
const segEmptyStyle = isVertical
? styles.connectorEmptyV
: styles.connectorEmptyH;
const beforeSegStyle = beforeFilled ? segFilledStyle : segEmptyStyle;
const afterSegStyle = afterFilled ? segFilledStyle : segEmptyStyle;
// First/last connector visibility is decided structurally from the step's
// own <li> position (see otSegHiddenIfFirst/Last), not by counting children
// in the parent — so grouping steps in a fragment can't break it.
// A node-to-node span is drawn by two steps: this one's trailing segments
// leave its own node, the next one's leading cap arrives at the next node.
// Both flip on the same condition, so left to themselves they fill together
// and one gap between two nodes reads as two dashes converging on the space
// between them. Handing each its own slice of the span's time, in track
// order — the leaving half first, then the arriving one — is what closes
// that into a single line growing.
const arrivalShare = isVertical ? OT_ARRIVAL_SHARE_V : OT_ARRIVAL_SHARE_H;
const leavingShare = 1 - arrivalShare;
// A content slot's segment continues the leaving half below the row, so the
// two divide the leaving time between them; with no slot the rail segment
// takes all of it. Each step can work this out for its own trailing side
// alone: the arriving cap always takes the span's last `arrivalShare`, so
// the step drawing it never has to know whether the step before it carries
// a slot.
const hasContentSeg = isVertical && isRenderable(children);
const railShare =
leavingShare * (hasContentSeg ? OT_RAIL_SHARE_OF_LEAVING : 1);
const contentShare = leavingShare - railShare;
const beforeTiming = fillTiming(step - 1, leavingShare, arrivalShare);
const railTiming = fillTiming(step, 0, railShare);
const contentTiming = fillTiming(step, railShare, contentShare);
const densitySpace =
density === 'compact'
? spacingVars['--spacing-1']
: density === 'spacious'
? spacingVars['--spacing-3']
: spacingVars['--spacing-2'];
const labelLineNode = (
<div
{...stylex.props(
isVertical ? styles.otLabelRowStart : styles.otLabelRowCenter,
)}>
<span
{...mergeProps(
labelThemeProps,
stylex.props(styles.label, labelColorStyle),
)}>
{label}
</span>
{statusTextNode}
{isOptional && (
<>
<span {...stylex.props(styles.optionalDot)}>•</span>
<span {...stylex.props(styles.optionalText)}>
{t('@astryx.step.optional')}
</span>
</>
)}
{endContent}
</div>
);
const otDescriptionNode = isRenderable(description) ? (
<span
id={descriptionID}
{...mergeProps(
descriptionThemeProps,
stylex.props(styles.description),
)}>
{description}
</span>
) : null;
const otContentNode = !isRenderable(children) ? null : isVertical ? (
<div {...stylex.props(styles.otContentWrapV)}>
<div
aria-hidden="true"
{...mergeProps(
themeProps('step-connector'),
stylex.props(
// connectorTrack first: it declares `position: relative` to
// anchor its fill layer, but this segment is absolutely placed
// on the rail beside the content slot and must keep that. An
// absolute box is a containing block too, so the fill still
// pins to it.
styles.connectorTrack,
styles.otContentSegV(densitySpace),
afterSegStyle,
contentTiming,
styles.otSegHiddenIfLast,
),
)}
/>
<div
{...stylex.props(
styles.otContent,
styles.contentIndent(densitySpace, INDICATOR_GUTTER),
)}>
{children}
</div>
</div>
) : (
<div hidden={isCompact || undefined} {...stylex.props(styles.otContent)}>
{children}
</div>
);
if (isVertical) {
const inner = (
<>
<div
{...stylex.props(
styles.otIndicatorColV,
styles.otRailBridgeV(densitySpace),
)}>
<div
aria-hidden="true"
{...mergeProps(
themeProps('step-connector'),
stylex.props(
styles.otSegBaseV,
styles.otSegLeadV(densitySpace),
styles.connectorTrack,
hasIndicator && styles.otSegGapLeadV,
beforeSegStyle,
beforeTiming,
styles.otSegHiddenIfFirst,
),
)}
/>
{indicatorNode}
<div
aria-hidden="true"
{...mergeProps(
themeProps('step-connector'),
stylex.props(
styles.otSegBaseV,
styles.otSegFlexV,
styles.connectorTrack,
hasIndicator && styles.otSegGapRailV,
afterSegStyle,
railTiming,
styles.otSegHiddenIfLast,
),
)}
/>
</div>
{/* Whitespace between the indicator column and the label, as in
iconLabelNode. */}{' '}
<div {...stylex.props(styles.otBodyV)}>
{labelLineNode}
{otDescriptionNode}
</div>
</>
);
return (
<li
ref={ref}
{...mergeProps(
stepThemeProps,
stylex.props(stepMarker, styles.otVerticalRoot, xstyle),
className,
style,
)}
data-testid={dataTestId}
{...rest}
// Keep this after `{...rest}` so a caller's `aria-current` cannot replace it.
aria-current={isActive ? 'step' : undefined}>
{hasButton ? (
<button
type="button"
onClick={handleClick}
aria-label={stepAriaLabel}
aria-describedby={
isRenderable(description) ? descriptionID : undefined
}
aria-disabled={isDisabled || undefined}
{...pressable}
{...stylex.props(
styles.otInteractive,
interactionOverlayStyles.backgroundColor,
styles.otRowWrap,
styles.otRowPadV(densitySpace),
focusOutlineStyles.focusVisible,
)}>
{inner}
</button>
) : (
<div
{...stylex.props(
styles.otRowWrap,
styles.otRowPadV(densitySpace),
)}>
{inner}
</div>
)}
{otContentNode}
</li>
);
}
// Horizontal on-track
const innerH = (
<>
<div {...stylex.props(styles.otTrackRowH)}>
<div
aria-hidden="true"
{...mergeProps(
themeProps('step-connector'),
stylex.props(
styles.otSegH,
styles.connectorTrack,
hasIndicator && styles.otSegGapLeadH,
beforeSegStyle,
beforeTiming,
styles.otSegHiddenIfFirst,
),
)}
/>
{indicatorNode}
<div
aria-hidden="true"
{...mergeProps(
themeProps('step-connector'),
stylex.props(
styles.otSegH,
styles.connectorTrack,
hasIndicator && styles.otSegGapRailH,
afterSegStyle,
railTiming,
styles.otSegHiddenIfLast,
),
)}
/>
</div>
{/* Whitespace between the rail and the label, as in iconLabelNode. */}{' '}
{/* The on-track indicator remains visible as a node on the rail at
compact widths, but the wrapper becomes presentational with its
label. Navigation moves to the named controls in the summary row. */}
{!isCompact && (
<div
{...stylex.props(
styles.otLabelWrapH,
styles.otMarginTop(densitySpace),
)}>
{labelLineNode}
{otDescriptionNode}
</div>
)}
</>
);
return (
<li
ref={ref}
{...mergeProps(
stepThemeProps,
stylex.props(stepMarker, styles.otHorizontalRoot, xstyle),
className,
style,
)}
data-testid={dataTestId}
{...rest}
// Keep this after `{...rest}` so a caller's `aria-current` cannot replace it.
aria-current={isActive ? 'step' : undefined}>
{hasButton ? (
<button
type="button"
onClick={handleClick}
aria-label={stepAriaLabel}
aria-describedby={
isRenderable(description) ? descriptionID : undefined
}
aria-disabled={isDisabled || undefined}
{...pressable}
{...stylex.props(
styles.otInteractive,
interactionOverlayStyles.backgroundColor,
styles.otColWrap,
styles.otPadBlock(densitySpace),
focusOutlineStyles.focusVisible,
)}>
{innerH}
</button>
) : (
<div
{...stylex.props(
styles.otColWrap,
styles.otPadBlock(densitySpace),
)}>
{innerH}
</div>
)}
{compactNameNode}
{otContentNode}
{summaryNode}
</li>
);
}
// ======= VERTICAL =======
if (isVertical) {
return (
<li
ref={ref}
{...mergeProps(
stepThemeProps,
stylex.props(stepMarker, styles.verticalRoot, xstyle),
className,
style,
)}
data-testid={dataTestId}
{...rest}
// Keep this after `{...rest}` so a caller's `aria-current` cannot replace it.
aria-current={isActive ? 'step' : undefined}>
{/* 4px progress bar */}
<div
{...mergeProps(
themeProps('step-bar'),
stylex.props(
styles.verticalBar,
styles.connectorTrack,
isBarFilled ? styles.connectorFillV : styles.connectorEmptyV,
barTiming,
),
)}
aria-hidden="true"
/>
{/* Body: button wraps only label area, children render outside */}
<div {...stylex.props(styles.verticalBody)}>
{hasButton ? (
<button
type="button"
onClick={handleClick}
aria-label={stepAriaLabel}
aria-describedby={
isRenderable(description) ? descriptionID : undefined
}
aria-disabled={isDisabled || undefined}
{...pressable}
{...stylex.props(
styles.buttonReset,
interactionOverlayStyles.backgroundColor,
focusOutlineStyles.focusVisible,
density === 'compact' && styles.densityCompact,
density === 'balanced' && styles.densityBalanced,
density === 'spacious' && styles.densitySpacious,
styles.densityInline(separatedDensityInline),
)}>
{iconLabelNode}
{descriptionNode}
</button>
) : (
<div
{...stylex.props(
density === 'compact' && styles.densityCompact,
density === 'balanced' && styles.densityBalanced,
density === 'spacious' && styles.densitySpacious,
styles.densityInline(separatedDensityInline),
)}>
{iconLabelNode}
{descriptionNode}
</div>
)}
{contentNode}
</div>
</li>
);
}
// ======= HORIZONTAL =======
return (
<li
ref={ref}
{...mergeProps(
stepThemeProps,
stylex.props(stepMarker, styles.horizontalStep, xstyle),
className,
style,
)}
data-testid={dataTestId}
{...rest}
// Keep this after `{...rest}` so a caller's `aria-current` cannot replace it.
aria-current={isActive ? 'step' : undefined}>
{/* 4px progress bar segment for this step */}
<div
{...mergeProps(
themeProps('step-bar'),
stylex.props(
styles.horizontalBar,
styles.connectorTrack,
isBarFilled ? styles.connectorFillH : styles.connectorEmptyH,
barTiming,
),
)}
aria-hidden="true"
/>
{/* The click target goes with the label, deliberately. A step narrow
enough to lose its label is narrow enough that all that would be left
to press is a 4px bar; the stepper puts a pair of named controls
under the track instead. */}
{isCompact ? (
compactNameNode
) : hasButton ? (
<button
type="button"
onClick={handleClick}
aria-label={stepAriaLabel}
aria-describedby={
isRenderable(description) ? descriptionID : undefined
}
aria-disabled={isDisabled || undefined}
{...stylex.props(
styles.buttonReset,
interactionOverlayStyles.backgroundColor,
focusOutlineStyles.focusVisible,
density === 'compact' && styles.densityCompact,
density === 'balanced' && styles.densityBalanced,
density === 'spacious' && styles.densitySpacious,
styles.densityInline(separatedDensityInline),
)}>
{iconLabelNode}
{descriptionNode}
</button>
) : (
<div
{...stylex.props(
density === 'compact' && styles.densityCompact,
density === 'balanced' && styles.densityBalanced,
density === 'spacious' && styles.densitySpacious,
styles.densityInline(separatedDensityInline),
)}>
{iconLabelNode}
{descriptionNode}
</div>
)}
{contentNode}
{summaryNode}
</li>
);
}
Step.displayName = 'Step';