@edux-design/accordions

Composable React primitives for building multi-step flows, accordions, and vertical timelines that stay perfectly in sync with the Edux design tokens. The package currently ships the Stepper system: Stepper, Step, Label, StepContent, and Description.

• Context-driven – Stepper wires IDs, status, aria attributes, and animation state for every Step child.
• Flexible layout – switch between horizontal and vertical orientations with a prop; the progress track automatically realigns.
• Accessible-first – step indicators render as real buttons, labels retain semantic text, and all content stays announced via aria-current, aria-disabled, and live updates.
• Design-token ready – styling hooks use the shared @edux-design/utils cx helper so your tokens map directly to Tailwind utilities.

Installation

npm install @edux-design/accordions @edux-design/utils
# or
pnpm add @edux-design/accordions @edux-design/utils

Peer deps: react@^19.1.0, react-dom@^19.1.0.

Usage

import {
  Stepper,
  Step,
  Label,
  StepContent,
  Description,
} from "@edux-design/accordions";

export function SignupStepper() {
  const [activeStep, setActiveStep] = useState(0);

  return (
    <Stepper
      activeStep={activeStep}
      onStepChange={setActiveStep}
      orientation="horizontal"
    >
      <Step key="complete-account">
        <Label>Account</Label>
        <StepContent>
          Pick a username and password so we can create your profile.
        </StepContent>
        <Description>Required</Description>
      </Step>

      <Step key="active-profile">
        <Label>Profile</Label>
        <StepContent>
          Tell us about your background to tailor the experience.
        </StepContent>
      </Step>

      <Step key="upcoming-confirm">
        <Label>Confirm</Label>
        <Description>Review everything before submitting</Description>
      </Step>
    </Stepper>
  );
}

Props at a Glance

| Component | Key props | | ------------- | ------------------------------------------------------------------------------------------- | | Stepper | activeStep, defaultStep, onStepChange, orientation (horizontal|vertical), linear | | Step | value, disabled, status, stepKey (maps to style variants), as | | Label | as, standard button/link props | | StepContent | as, unmountOnInactive, className (merged via cx), arbitrary DOM props | | Description | No special props; renders subdued supporting text |

How the Progress Track Works

Each Step registers its indicator node with the Stepper. The parent measures the center points of the first and last indicators and renders a dashed track behind them. The filled portion animates between those centers whenever activeStep changes. This logic runs for both horizontal and vertical orientations.

Storybook Demos

• Basic – controlled horizontal flow with inline StepContent and Description.
• NonLinear – demonstrates linear={false} so users can jump steps freely.
• Vertical – showcases the vertical orientation with the shared content rendering at the root.

See src/demos/Stepper.stories.jsx for setups you can copy.

Development

• pnpm build – bundle with tsup to dist/ (ESM, CJS, and types).
• pnpm dev – watch mode for local development.
• pnpm lint – run ESLint with zero-warning policy.
• pnpm check-types – type-check via tsc --noEmit.

When adding new primitives, follow the existing folder structure: src/elements, src/utils, src/demos, and update src/index.js exports plus CHANGELOG.md.

Roadmap / Notes

• Additional accordion primitives will live in this package as they’re designed.
• Stepper currently assumes each Step provides a consistent width/height indicator; if your design deviates, revisit the measurement helpers inside Stepper.jsx.
• Vertical progress animations reuse the same measurement logic; confirm large content blocks don’t shift the indicator layout unexpectedly.

Contributions, tweaks, and style overrides should stick to the shared design tokens to keep parity with the rest of the Edux system.