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

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

# AppStepper

## Overview

High-level stepper built on `Stepper` primitives. Renders labeled steps with indicators and panels, supports horizontal/vertical layouts, separators, controlled navigation and custom click behavior.

---

## Props

| Prop                      | Type                                                                                         | Default       | Description                                                     |
| ------------------------- | -------------------------------------------------------------------------------------------- | ------------- | --------------------------------------------------------------- | ----------------------- |
| `steps`                   | `{ id: number; label: ReactNode; component: ReactNode; completed?; disabled?; loading?; }[]` | **required**  | Steps to render (id is the step value).                         |
| `align`                   | `"horizontal"                                                                                | "vertical"`   | `"horizontal"`                                                  | Layout orientation.     |
| `size`                    | `"sm"                                                                                        | "md"`         | `"sm"`                                                          | Indicator/title sizing. |
| `showSeparators`          | `boolean`                                                                                    | `true`        | Show separators between steps.                                  |
| `value`                   | `number`                                                                                     | first step id | Current step value (controlled).                                |
| `onValueChange`           | `(value: number) => void`                                                                    | `undefined`   | Called when step changes.                                       |
| `defaultStep`             | `number`                                                                                     | `undefined`   | Initial step if `value` is not provided.                        |
| `allowStepNavigation`     | `boolean`                                                                                    | `true`        | If `false`, steps are not clickable.                            |
| `allowClickOnlyCompleted` | `boolean`                                                                                    | `false`       | If `true`, only completed steps are clickable.                  |
| `onStepClick`             | `(step, index) => void`                                                                      | `undefined`   | Custom click handler; if provided, handles activation manually. |
| `indicators`              | `{ active?; completed?; inactive?; loading? }`                                               | `undefined`   | Custom indicator content per state.                             |

Inherits the rest of `StepperProps` (e.g., `orientation` is controlled by `align`).

---

## Behavior

- **Controlled**: Always passes a `value` to `Stepper`. Update via `onValueChange`.
- **Clickable steps**: Governed by `allowStepNavigation` and `allowClickOnlyCompleted`.
- **Indicators**: Customize the indicator content through `indicators`.

---

## Examples

```tsx
import * as React from "react";
import { AppStepper } from "laif-ds";

const steps = [
  { id: 1, label: "Account Setup", component: <div>Step 1</div> },
  { id: 2, label: "Profile Information", component: <div>Step 2</div> },
  { id: 3, label: "Preferences", component: <div>Step 3</div> },
] as const;

export function HorizontalStepper() {
  const [current, setCurrent] = React.useState(1);
  return (
    <AppStepper
      steps={steps}
      value={current}
      onValueChange={setCurrent}
      align="horizontal"
      size="md"
      showSeparators
    />
  );
}

export function VerticalStepper() {
  const [current, setCurrent] = React.useState(1);
  return (
    <AppStepper
      steps={steps}
      value={current}
      onValueChange={setCurrent}
      align="vertical"
    />
  );
}
```

---

## Notes

- **Accessibility**: Based on `Stepper` primitives which manage keyboard and focus.
- **Custom click logic**: Provide `onStepClick` to intercept clicks (e.g., validation before navigation).