xertica-ui 2.2.1 → 2.4.0

package/docs/components/stepper.md

@@ -1,268 +1,268 @@
-# Stepper
-
-## Overview
-
-A visual multi-step progress indicator that shows the user's current position within a sequential process. Uses a composable primitive pattern: `<Stepper>` wraps one or more `<Step>` children, automatically inferring the total number of steps.
-
-The package also exports a **headless `useStepper` hook** for building fully custom step-navigation UIs — including async validation guards before advancing — while reusing all the step-state logic.
-
----
-
-## Exports
-
-| Export             | Description                                      |
-| ------------------ | ------------------------------------------------ |
-| `Stepper`          | Visual step indicator component                  |
-| `Step`             | Individual step item                             |
-| `useStepper`       | Headless hook — all step navigation logic, no UI |
-| `UseStepperProps`  | TypeScript props type for the hook               |
-| `UseStepperReturn` | TypeScript return type for the hook              |
-
----
-
-## When to Use
-
-- Multi-step forms (checkout, registration, onboarding)
-- Sequential configuration wizards
-- Any process with 2–7 ordered steps
-
-## When NOT to Use
-
-- Processes with more than 7 steps — collapse or restructure.
-- Simple 2-step flows — a dialog with "Next"/"Back" is sufficient.
-
----
-
-## Anatomy
-
-```tsx
-<Stepper currentStep={2}>
-  <Step step={1} label="Account" description="Create your account" />
-  <Step step={2} label="Plan" description="Choose a plan" />
-  <Step step={3} label="Confirm" description="Review and confirm" />
-</Stepper>
-```
-
-- Steps are numbered from `1` (not `0`).
-- Steps before `currentStep` render as **completed** (green checkmark).
-- The step equal to `currentStep` renders as **active** (filled primary).
-- Steps after `currentStep` render as **pending** (muted).
-
----
-
-## Sub-Components
-
-### `Stepper`
-
-| Prop          | Type                         | Required | Description                                |
-| ------------- | ---------------------------- | -------- | ------------------------------------------ |
-| `currentStep` | `number`                     | **Yes**  | The currently active step (1-indexed)      |
-| `orientation` | `'horizontal' \| 'vertical'` | No       | Layout direction (default: `'horizontal'`) |
-| `className`   | `string`                     | No       | Additional CSS classes                     |
-
-The step wrapper div renders with `role="list"` and `aria-label="Progresso: etapa N de M"` automatically.
-
-### `Step`
-
-| Prop          | Type      | Required | Description                                         |
-| ------------- | --------- | -------- | --------------------------------------------------- |
-| `step`        | `number`  | **Yes**  | Position of this step (1-indexed, must match order) |
-| `label`       | `string`  | **Yes**  | Step label text                                     |
-| `description` | `string`  | No       | Optional supplementary text below the label         |
-| `error`       | `boolean` | No       | When `true`, renders the step in error state (red)  |
-| `className`   | `string`  | No       | Additional CSS classes                              |
-
-Each `<Step>` renders with `role="listitem"`, `aria-current="step"` (active step only), and `aria-label="Etapa N: Label[, concluída | , atual]"` automatically — no manual ARIA attributes needed.
-
----
-
-## Examples
-
-### Basic 3-Step Flow
-
-```tsx
-import { Stepper, Step, Button } from 'xertica-ui/ui';
-import { useState } from 'react';
-
-const [currentStep, setCurrentStep] = useState(1);
-
-<div className="space-y-8">
-  <Stepper currentStep={currentStep}>
-    <Step step={1} label="Account" description="Create your account" />
-    <Step step={2} label="Plan" description="Choose a plan" />
-    <Step step={3} label="Confirm" description="Review and confirm" />
-  </Stepper>
-
-  <div className="min-h-[200px] flex items-center justify-center">
-    <p className="text-muted-foreground">Content for step {currentStep}</p>
-  </div>
-
-  <div className="flex justify-between">
-    <Button
-      variant="outline"
-      onClick={() => setCurrentStep(s => Math.max(1, s - 1))}
-      disabled={currentStep === 1}
-    >
-      Previous
-    </Button>
-    <Button onClick={() => setCurrentStep(s => Math.min(3, s + 1))} disabled={currentStep === 3}>
-      {currentStep === 3 ? 'Finish' : 'Next'}
-    </Button>
-  </div>
-</div>;
-```
-
----
-
-## `useStepper` Hook
-
-A headless hook that manages step navigation state. Supports both **uncontrolled** (internal state) and **controlled** (external `step` prop) modes, plus an optional async `onBeforeNext` guard for validating the current step before advancing.
-
-### Props
-
-| Prop           | Type                                                   | Default | Description                                                                                                       |
-| -------------- | ------------------------------------------------------ | ------- | ----------------------------------------------------------------------------------------------------------------- |
-| `totalSteps`   | `number`                                               | —       | **Required.** Total number of steps in the flow                                                                   |
-| `initialStep`  | `number`                                               | `1`     | Starting step (uncontrolled mode only). Automatically clamped to `[1, totalSteps]` — out-of-range values are safe |
-| `step`         | `number`                                               | —       | Controlled current step — when provided, the hook uses this value instead of internal state                       |
-| `onStepChange` | `(step: number) => void`                               | —       | Called whenever the step changes                                                                                  |
-| `onBeforeNext` | `(currentStep: number) => boolean \| Promise<boolean>` | —       | Optional async guard — return `false` (or resolve to `false`) to block advancing to the next step                 |
-
-### Return Value
-
-| Property      | Type                     | Description                                                      |
-| ------------- | ------------------------ | ---------------------------------------------------------------- |
-| `currentStep` | `number`                 | The currently active step (1-indexed)                            |
-| `totalSteps`  | `number`                 | Total number of steps                                            |
-| `isFirstStep` | `boolean`                | Whether the current step is the first step                       |
-| `isLastStep`  | `boolean`                | Whether the current step is the last step                        |
-| `canGoPrev`   | `boolean`                | Whether navigating to the previous step is possible              |
-| `canGoNext`   | `boolean`                | Whether navigating to the next step is possible                  |
-| `next`        | `() => Promise<void>`    | Advance to the next step (runs `onBeforeNext` guard if provided) |
-| `prev`        | `() => void`             | Go back to the previous step                                     |
-| `goTo`        | `(step: number) => void` | Jump to a specific step number                                   |
-| `reset`       | `() => void`             | Reset to the initial step                                        |
-
-### Uncontrolled Example
-
-```tsx
-import { useStepper, Stepper, Step, Button } from 'xertica-ui/ui';
-
-function OnboardingWizard() {
-  const { currentStep, isFirstStep, isLastStep, next, prev } = useStepper({
-    totalSteps: 3,
-  });
-
-  return (
-    <div className="space-y-8">
-      <Stepper currentStep={currentStep}>
-        <Step step={1} label="Account" />
-        <Step step={2} label="Plan" />
-        <Step step={3} label="Confirm" />
-      </Stepper>
-
-      <div className="min-h-[200px]">
-        {currentStep === 1 && <AccountForm />}
-        {currentStep === 2 && <PlanSelector />}
-        {currentStep === 3 && <ConfirmationSummary />}
-      </div>
-
-      <div className="flex justify-between">
-        <Button variant="outline" onClick={prev} disabled={isFirstStep}>
-          Previous
-        </Button>
-        <Button onClick={next} disabled={isLastStep}>
-          {isLastStep ? 'Finish' : 'Next'}
-        </Button>
-      </div>
-    </div>
-  );
-}
-```
-
-### With Async Validation Guard
-
-```tsx
-import { useStepper, Stepper, Step, Button } from 'xertica-ui/ui';
-import { useForm } from 'react-hook-form';
-
-function ValidatedWizard() {
-  const form = useForm();
-
-  const { currentStep, isFirstStep, isLastStep, next, prev } = useStepper({
-    totalSteps: 3,
-    onBeforeNext: async step => {
-      // Validate only the fields relevant to the current step
-      const fieldsPerStep: Record<number, string[]> = {
-        1: ['email', 'password'],
-        2: ['plan'],
-      };
-      const fields = fieldsPerStep[step];
-      if (!fields) return true;
-      return form.trigger(fields as never[]);
-    },
-  });
-
-  return (
-    <div className="space-y-8">
-      <Stepper currentStep={currentStep}>
-        <Step step={1} label="Account" />
-        <Step step={2} label="Plan" />
-        <Step step={3} label="Confirm" />
-      </Stepper>
-
-      <form>{/* step content */}</form>
-
-      <div className="flex justify-between">
-        <Button variant="outline" onClick={prev} disabled={isFirstStep}>
-          Previous
-        </Button>
-        <Button onClick={next}>{isLastStep ? 'Submit' : 'Next'}</Button>
-      </div>
-    </div>
-  );
-}
-```
-
-### Controlled Example
-
-```tsx
-import { useStepper } from 'xertica-ui/ui';
-import { useState } from 'react';
-
-function ControlledWizard() {
-  const [step, setStep] = useState(1);
-
-  const { currentStep, next, prev, isFirstStep, isLastStep } = useStepper({
-    totalSteps: 4,
-    step,               // controlled
-    onStepChange: setStep,
-  });
-
-  // currentStep === step at all times
-  return (/* ... */);
-}
-```
-
----
-
-## AI Rules
-
-- `step` props on `<Step>` are **1-indexed** — the first step is `step={1}`, not `step={0}`.
-- Each `<Step>` `step` prop must match its position sequentially: `1, 2, 3, ...`.
-- `currentStep` on `<Stepper>` must be a number from `1` to the total number of steps.
-- Always render the navigation buttons (Previous/Next) below the Stepper.
-- Disable "Previous" on step `1` (`isFirstStep`) and "Next" on the final step (`isLastStep`).
-- Use `onBeforeNext` for async form validation — return `false` to block advancing.
-- `next()` is **async** — always `await` it or use it as an `onClick` handler directly (React handles the Promise).
-- In controlled mode, pass both `step` and `onStepChange` — omitting `onStepChange` makes the hook read-only.
-- Use `reset()` to return to step 1 after a successful submission.
-- `initialStep` is automatically clamped to `[1, totalSteps]` — passing `0`, negative values, or values beyond `totalSteps` is safe and will not throw.
-- Do NOT add `role="list"`, `aria-current`, or `aria-label` manually to `<Stepper>` or `<Step>` — they are applied automatically since v2.1.9.
-
----
-
-## Related Components
-
-- [`Progress`](./progress.md) — For generic percentage progress display
-- [`Form`](./form.md) — Commonly used inside multi-step steppers
+# Stepper
+
+## Overview
+
+A visual multi-step progress indicator that shows the user's current position within a sequential process. Uses a composable primitive pattern: `<Stepper>` wraps one or more `<Step>` children, automatically inferring the total number of steps.
+
+The package also exports a **headless `useStepper` hook** for building fully custom step-navigation UIs — including async validation guards before advancing — while reusing all the step-state logic.
+
+---
+
+## Exports
+
+| Export             | Description                                      |
+| ------------------ | ------------------------------------------------ |
+| `Stepper`          | Visual step indicator component                  |
+| `Step`             | Individual step item                             |
+| `useStepper`       | Headless hook — all step navigation logic, no UI |
+| `UseStepperProps`  | TypeScript props type for the hook               |
+| `UseStepperReturn` | TypeScript return type for the hook              |
+
+---
+
+## When to Use
+
+- Multi-step forms (checkout, registration, onboarding)
+- Sequential configuration wizards
+- Any process with 2–7 ordered steps
+
+## When NOT to Use
+
+- Processes with more than 7 steps — collapse or restructure.
+- Simple 2-step flows — a dialog with "Next"/"Back" is sufficient.
+
+---
+
+## Anatomy
+
+```tsx
+<Stepper currentStep={2}>
+  <Step step={1} label="Account" description="Create your account" />
+  <Step step={2} label="Plan" description="Choose a plan" />
+  <Step step={3} label="Confirm" description="Review and confirm" />
+</Stepper>
+```
+
+- Steps are numbered from `1` (not `0`).
+- Steps before `currentStep` render as **completed** (green checkmark).
+- The step equal to `currentStep` renders as **active** (filled primary).
+- Steps after `currentStep` render as **pending** (muted).
+
+---
+
+## Sub-Components
+
+### `Stepper`
+
+| Prop          | Type                         | Required | Description                                |
+| ------------- | ---------------------------- | -------- | ------------------------------------------ |
+| `currentStep` | `number`                     | **Yes**  | The currently active step (1-indexed)      |
+| `orientation` | `'horizontal' \| 'vertical'` | No       | Layout direction (default: `'horizontal'`) |
+| `className`   | `string`                     | No       | Additional CSS classes                     |
+
+The step wrapper div renders with `role="list"` and `aria-label="Progresso: etapa N de M"` automatically.
+
+### `Step`
+
+| Prop          | Type      | Required | Description                                         |
+| ------------- | --------- | -------- | --------------------------------------------------- |
+| `step`        | `number`  | **Yes**  | Position of this step (1-indexed, must match order) |
+| `label`       | `string`  | **Yes**  | Step label text                                     |
+| `description` | `string`  | No       | Optional supplementary text below the label         |
+| `error`       | `boolean` | No       | When `true`, renders the step in error state (red)  |
+| `className`   | `string`  | No       | Additional CSS classes                              |
+
+Each `<Step>` renders with `role="listitem"`, `aria-current="step"` (active step only), and `aria-label="Etapa N: Label[, concluída | , atual]"` automatically — no manual ARIA attributes needed.
+
+---
+
+## Examples
+
+### Basic 3-Step Flow
+
+```tsx
+import { Stepper, Step, Button } from 'xertica-ui/ui';
+import { useState } from 'react';
+
+const [currentStep, setCurrentStep] = useState(1);
+
+<div className="space-y-8">
+  <Stepper currentStep={currentStep}>
+    <Step step={1} label="Account" description="Create your account" />
+    <Step step={2} label="Plan" description="Choose a plan" />
+    <Step step={3} label="Confirm" description="Review and confirm" />
+  </Stepper>
+
+  <div className="min-h-[200px] flex items-center justify-center">
+    <p className="text-muted-foreground">Content for step {currentStep}</p>
+  </div>
+
+  <div className="flex justify-between">
+    <Button
+      variant="outline"
+      onClick={() => setCurrentStep(s => Math.max(1, s - 1))}
+      disabled={currentStep === 1}
+    >
+      Previous
+    </Button>
+    <Button onClick={() => setCurrentStep(s => Math.min(3, s + 1))} disabled={currentStep === 3}>
+      {currentStep === 3 ? 'Finish' : 'Next'}
+    </Button>
+  </div>
+</div>;
+```
+
+---
+
+## `useStepper` Hook
+
+A headless hook that manages step navigation state. Supports both **uncontrolled** (internal state) and **controlled** (external `step` prop) modes, plus an optional async `onBeforeNext` guard for validating the current step before advancing.
+
+### Props
+
+| Prop           | Type                                                   | Default | Description                                                                                                       |
+| -------------- | ------------------------------------------------------ | ------- | ----------------------------------------------------------------------------------------------------------------- |
+| `totalSteps`   | `number`                                               | —       | **Required.** Total number of steps in the flow                                                                   |
+| `initialStep`  | `number`                                               | `1`     | Starting step (uncontrolled mode only). Automatically clamped to `[1, totalSteps]` — out-of-range values are safe |
+| `step`         | `number`                                               | —       | Controlled current step — when provided, the hook uses this value instead of internal state                       |
+| `onStepChange` | `(step: number) => void`                               | —       | Called whenever the step changes                                                                                  |
+| `onBeforeNext` | `(currentStep: number) => boolean \| Promise<boolean>` | —       | Optional async guard — return `false` (or resolve to `false`) to block advancing to the next step                 |
+
+### Return Value
+
+| Property      | Type                     | Description                                                      |
+| ------------- | ------------------------ | ---------------------------------------------------------------- |
+| `currentStep` | `number`                 | The currently active step (1-indexed)                            |
+| `totalSteps`  | `number`                 | Total number of steps                                            |
+| `isFirstStep` | `boolean`                | Whether the current step is the first step                       |
+| `isLastStep`  | `boolean`                | Whether the current step is the last step                        |
+| `canGoPrev`   | `boolean`                | Whether navigating to the previous step is possible              |
+| `canGoNext`   | `boolean`                | Whether navigating to the next step is possible                  |
+| `next`        | `() => Promise<void>`    | Advance to the next step (runs `onBeforeNext` guard if provided) |
+| `prev`        | `() => void`             | Go back to the previous step                                     |
+| `goTo`        | `(step: number) => void` | Jump to a specific step number                                   |
+| `reset`       | `() => void`             | Reset to the initial step                                        |
+
+### Uncontrolled Example
+
+```tsx
+import { useStepper, Stepper, Step, Button } from 'xertica-ui/ui';
+
+function OnboardingWizard() {
+  const { currentStep, isFirstStep, isLastStep, next, prev } = useStepper({
+    totalSteps: 3,
+  });
+
+  return (
+    <div className="space-y-8">
+      <Stepper currentStep={currentStep}>
+        <Step step={1} label="Account" />
+        <Step step={2} label="Plan" />
+        <Step step={3} label="Confirm" />
+      </Stepper>
+
+      <div className="min-h-[200px]">
+        {currentStep === 1 && <AccountForm />}
+        {currentStep === 2 && <PlanSelector />}
+        {currentStep === 3 && <ConfirmationSummary />}
+      </div>
+
+      <div className="flex justify-between">
+        <Button variant="outline" onClick={prev} disabled={isFirstStep}>
+          Previous
+        </Button>
+        <Button onClick={next} disabled={isLastStep}>
+          {isLastStep ? 'Finish' : 'Next'}
+        </Button>
+      </div>
+    </div>
+  );
+}
+```
+
+### With Async Validation Guard
+
+```tsx
+import { useStepper, Stepper, Step, Button } from 'xertica-ui/ui';
+import { useForm } from 'react-hook-form';
+
+function ValidatedWizard() {
+  const form = useForm();
+
+  const { currentStep, isFirstStep, isLastStep, next, prev } = useStepper({
+    totalSteps: 3,
+    onBeforeNext: async step => {
+      // Validate only the fields relevant to the current step
+      const fieldsPerStep: Record<number, string[]> = {
+        1: ['email', 'password'],
+        2: ['plan'],
+      };
+      const fields = fieldsPerStep[step];
+      if (!fields) return true;
+      return form.trigger(fields as never[]);
+    },
+  });
+
+  return (
+    <div className="space-y-8">
+      <Stepper currentStep={currentStep}>
+        <Step step={1} label="Account" />
+        <Step step={2} label="Plan" />
+        <Step step={3} label="Confirm" />
+      </Stepper>
+
+      <form>{/* step content */}</form>
+
+      <div className="flex justify-between">
+        <Button variant="outline" onClick={prev} disabled={isFirstStep}>
+          Previous
+        </Button>
+        <Button onClick={next}>{isLastStep ? 'Submit' : 'Next'}</Button>
+      </div>
+    </div>
+  );
+}
+```
+
+### Controlled Example
+
+```tsx
+import { useStepper } from 'xertica-ui/ui';
+import { useState } from 'react';
+
+function ControlledWizard() {
+  const [step, setStep] = useState(1);
+
+  const { currentStep, next, prev, isFirstStep, isLastStep } = useStepper({
+    totalSteps: 4,
+    step,               // controlled
+    onStepChange: setStep,
+  });
+
+  // currentStep === step at all times
+  return (/* ... */);
+}
+```
+
+---
+
+## AI Rules
+
+- `step` props on `<Step>` are **1-indexed** — the first step is `step={1}`, not `step={0}`.
+- Each `<Step>` `step` prop must match its position sequentially: `1, 2, 3, ...`.
+- `currentStep` on `<Stepper>` must be a number from `1` to the total number of steps.
+- Always render the navigation buttons (Previous/Next) below the Stepper.
+- Disable "Previous" on step `1` (`isFirstStep`) and "Next" on the final step (`isLastStep`).
+- Use `onBeforeNext` for async form validation — return `false` to block advancing.
+- `next()` is **async** — always `await` it or use it as an `onClick` handler directly (React handles the Promise).
+- In controlled mode, pass both `step` and `onStepChange` — omitting `onStepChange` makes the hook read-only.
+- Use `reset()` to return to step 1 after a successful submission.
+- `initialStep` is automatically clamped to `[1, totalSteps]` — passing `0`, negative values, or values beyond `totalSteps` is safe and will not throw.
+- Do NOT add `role="list"`, `aria-current`, or `aria-label` manually to `<Stepper>` or `<Step>` — they are applied automatically since v2.1.9.
+
+---
+
+## Related Components
+
+- [`Progress`](./progress.md) — For generic percentage progress display
+- [`Form`](./form.md) — Commonly used inside multi-step steppers