laif-ds/dist/agent-docs/components/Stepper.md

Design System di Laif con componenti React basati su principi di Atomic Design

# Stepper (Primitives)

## Overview

Accessible stepper primitives to build multi-step flows with keyboard navigation, indicators, separators and panels. Supports horizontal and vertical layouts.

---

## Subcomponents & Props

- **Stepper**: Root context.
  - `defaultValue?: number` (default `1`)
  - `value?: number`, `onValueChange?: (n:number)=>void`
  - `orientation?: "horizontal" | "vertical"` (default `"horizontal"`)
  - `indicators?: { active?, completed?, inactive?, loading? }`
- **StepperItem**: Defines a step. Props: `step` (number), `completed?`, `disabled?`, `loading?`, `orientation?`.
- **StepperTrigger**: Click/keyboard target to activate step. Props: `size?: "sm"|"default"|"lg"`.
- **StepperIndicator**: Circular indicator; accepts `size`.
- **StepperTitle / StepperDescription**: Labels; accept `size`.
- **StepperSeparator**: Visual separator between steps; respects orientation.
- **StepperNav**: Wraps triggers; accepts `orientation?`.
- **StepperPanel**: Container for contents.
- **StepperContent**: Conditional render area for a given `value` (step id). `forceMount?` keeps DOM mounted.

---

## Behavior

- **Keyboard**: Arrow keys navigate between triggers; Home/End jump to first/last; Enter/Space selects.
- **Controlled/Uncontrolled**: Use `value/onValueChange` or `defaultValue`.
- **Indicators**: Provide custom nodes for states via `indicators`.

---

## Example

```tsx
import {
  Stepper,
  StepperNav,
  StepperItem,
  StepperTrigger,
  StepperIndicator,
  StepperTitle,
  StepperSeparator,
  StepperPanel,
  StepperContent,
} from "laif-ds";

export function BasicStepper() {
  const [step, setStep] = React.useState(1);
  return (
    <Stepper value={step} onValueChange={setStep}>
      <div className="flex w-full flex-col">
        <StepperNav>
          <StepperItem step={1}>
            <StepperTrigger>
              <StepperIndicator>1</StepperIndicator>
              <StepperTitle>Account</StepperTitle>
            </StepperTrigger>
            <StepperSeparator />
          </StepperItem>
          <StepperItem step={2}>
            <StepperTrigger>
              <StepperIndicator>2</StepperIndicator>
              <StepperTitle>Profile</StepperTitle>
            </StepperTrigger>
            <StepperSeparator />
          </StepperItem>
          <StepperItem step={3}>
            <StepperTrigger>
              <StepperIndicator>3</StepperIndicator>
              <StepperTitle>Done</StepperTitle>
            </StepperTrigger>
          </StepperItem>
        </StepperNav>
        <StepperPanel className="mt-6">
          <StepperContent value={1}>Step 1</StepperContent>
          <StepperContent value={2}>Step 2</StepperContent>
          <StepperContent value={3}>Step 3</StepperContent>
        </StepperPanel>
      </div>
    </Stepper>
  );
}
```

---

## Notes

- **Focus**: Triggers manage focus order for accessible navigation.
- **Layouts**: Use `orientation="vertical"` to show left rail of steps with content on the right.