### Install and Develop Stepperize Docs

Source: https://github.com/damianricobelli/stepperize/blob/main/apps/docs/README.md

Run these commands from the repository root to install dependencies and start the development server for the Stepperize documentation site. The dev server typically runs on localhost:3000.

```bash
pnpm install
pnpm --filter docs dev
```

--------------------------------

### Install Dependencies

Source: https://github.com/damianricobelli/stepperize/blob/main/CONTRIBUTING.md

Install project dependencies using pnpm.

```bash
pnpm i
```

--------------------------------

### Start Development Server

Source: https://github.com/damianricobelli/stepperize/blob/main/README.md

Start the development server to run the application and view changes in real-time. This command is typically used during the development phase.

```bash
pnpm dev
```

--------------------------------

### Install Conform Dependencies

Source: https://github.com/damianricobelli/stepperize/blob/main/apps/docs/content/docs/docs/latest/forms/conform.mdx

Install the necessary Conform packages for React and Zod validation.

```bash
npm install @conform-to/react @conform-to/zod
```

--------------------------------

### Quick Start: Basic Wizard Implementation

Source: https://github.com/damianricobelli/stepperize/blob/main/packages/react/README.md

Define a stepper configuration and use the `useStepper` hook to manage the current step and navigation within a React component. This example shows a simple account, profile, and done step wizard.

```tsx
import { defineStepper } from "@stepperize/react";

const wizard = defineStepper([
  { id: "account", title: "Account" },
  { id: "profile", title: "Profile" },
  { id: "done", title: "Done" },
]);

function Wizard() {
  const stepper = wizard.useStepper();

  return (
    <div>
      <h2>{stepper.current.title}</h2>

      {stepper.match({
        account: () => <AccountStep />,
        profile: () => <ProfileStep />,
        done: () => <DoneStep />,
      })}

      <button onClick={() => stepper.prev()} disabled={!stepper.canPrev}>
        Back
      </button>
      <button onClick={() => stepper.next()} disabled={!stepper.canNext}>
        Next
      </button>
    </div>
  );
}
```

--------------------------------

### Complete Stepper Example

Source: https://github.com/damianricobelli/stepperize/blob/main/apps/docs/content/docs/docs/latest/getting-started/first-stepper.mdx

A full example integrating step definition, hook usage, conditional rendering, and navigation controls within a single component.

```tsx
import { defineStepper } from "@stepperize/react";

const signup = defineStepper([
  { id: "name", title: "Name" },
  { id: "email", title: "Email" },
  { id: "confirm", title: "Confirm" },
]);

export function Signup() {
  const stepper = signup.useStepper();

  return (
    <form>
      <p>
        Step {stepper.index + 1} of {stepper.count}: {stepper.current.title}
      </p>

      {stepper.match({
        name: () => <input name="name" placeholder="Ada Lovelace" />,
        email: () => <input name="email" placeholder="ada@example.com" />,
        confirm: () => <p>Review your details.</p>,
      })}

      <button type="button" disabled={!stepper.canPrev} onClick={() => stepper.prev()}>
        Back
      </button>
      <button type="button" disabled={!stepper.canNext} onClick={() => stepper.next()}>
        Next
      </button>
    </form>
  );
}
```

--------------------------------

### Install Dependencies for Development

Source: https://github.com/damianricobelli/stepperize/blob/main/README.md

Install project dependencies using pnpm, which is required for development. This command should be run after cloning the repository.

```bash
pnpm install
```

--------------------------------

### Run Development Docs Server

Source: https://github.com/damianricobelli/stepperize/blob/main/CONTRIBUTING.md

Start the development server for the documentation, filtering for the 'docs' package.

```bash
pnpm dev --filter docs
```

--------------------------------

### Install TanStack Form

Source: https://github.com/damianricobelli/stepperize/blob/main/apps/docs/content/docs/docs/latest/forms/tanstack-form.mdx

Install the TanStack Form package using npm.

```bash
npm install @tanstack/react-form
```

--------------------------------

### Install React Package

Source: https://github.com/damianricobelli/stepperize/blob/main/apps/docs/content/docs/docs/latest/getting-started/installation.mdx

Install the Stepperize React package using your preferred package manager.

```bash
pnpm add @stepperize/react
```

```bash
npm install @stepperize/react
```

```bash
yarn add @stepperize/react
```

```bash
bun add @stepperize/react
```

--------------------------------

### Quick Start: Define and Use a Stepper

Source: https://github.com/damianricobelli/stepperize/blob/main/README.md

Define a stepper with multiple steps and use the `useStepper` hook to manage its state within a React component. This example demonstrates basic navigation and conditional rendering based on the current step.

```tsx
import { defineStepper } from "@stepperize/react";

const checkout = defineStepper([
  { id: "shipping", title: "Shipping", description: "Enter your address" },
  { id: "payment", title: "Payment", description: "Payment details" },
  { id: "review", title: "Review", description: "Confirm your order" },
]);

function Checkout() {
  const stepper = checkout.useStepper();

  return (
    <section>
      <h2>{stepper.current.title}</h2>
      <p>{stepper.current.description}</p>

      {stepper.match({
        shipping: () => <ShippingForm />,
        payment: () => <PaymentForm />,
        review: () => <ReviewOrder />,
      })}

      <button onClick={() => stepper.prev()} disabled={!stepper.canPrev}>
        Back
      </button>
      <button onClick={() => stepper.next()} disabled={!stepper.canNext}>
        Continue
      </button>
    </section>
  );
}
```

--------------------------------

### Install React Hook Form and Resolver

Source: https://github.com/damianricobelli/stepperize/blob/main/apps/docs/content/docs/docs/latest/forms/react-hook-form.mdx

Install the necessary packages for React Hook Form and its Zod resolver.

```bash
npm install react-hook-form @hookform/resolvers
```

--------------------------------

### Run Development Server for Docs App

Source: https://github.com/damianricobelli/stepperize/blob/main/README.md

Start the development server for the documentation application. This command uses pnpm filters to target the docs app.

```bash
pnpm --filter docs dev
```

--------------------------------

### Reusable Component Example

Source: https://github.com/damianricobelli/stepperize/blob/main/apps/docs/content/docs/docs/latest/api/react/types.mdx

This example demonstrates how to create a reusable `Progress` component that accepts a `Stepper` instance and displays the current step progress. It utilizes the `Stepper` type for type safety.

```APIDOC
## Reusable Component

### Description
This example demonstrates how to create a reusable `Progress` component that accepts a `Stepper` instance and displays the current step progress. It utilizes the `Stepper` type for type safety.

### Component Signature
```tsx
import type { Step, Stepper } from "@stepperize/react";

function Progress<Steps extends readonly Step[]>({ stepper }: { stepper: Stepper<Steps> }) {
  return (
    <p>
      Step {stepper.index + 1} of {stepper.count}
    </p>
  );
}
```

**Note:** If a component can call the generated hook directly, prefer that over passing types around.
```

--------------------------------

### Install Stepperize React Package

Source: https://github.com/damianricobelli/stepperize/blob/main/README.md

Install the Stepperize React package using npm. This command adds the necessary library to your project for building step-by-step experiences.

```bash
npm install @stepperize/react
```

--------------------------------

### Checkout Provider Setup

Source: https://github.com/damianricobelli/stepperize/blob/main/apps/docs/content/docs/docs/latest/api/react/provider.mdx

Sets up the checkout stepper provider with a default initial step. Descendant components can then access the stepper instance using `useStepper`.

```tsx
function CheckoutShell() {
  return (
    <checkout.Provider defaultStep="shipping">
      <StepperNav />
      <CheckoutPanel />
      <Actions />
    </checkout.Provider>
  );
}
```

--------------------------------

### Syncing Stepper Step with URL

Source: https://github.com/damianricobelli/stepperize/blob/main/apps/docs/content/docs/docs/latest/core-concepts/controlled-vs-uncontrolled.mdx

This example demonstrates controlling the stepper's step by syncing it with the URL. It also includes handling invalid steps by navigating to a default.

```tsx
const stepper = checkout.useStepper({
  step: stepFromUrl,
  onStepChange: (next) => navigate({ search: { step: next } }),
  onInvalidStep: () => navigate({ search: { step: "shipping" }, replace: true }),
});
```

--------------------------------

### Complete Guarded Example with React State

Source: https://github.com/damianricobelli/stepperize/blob/main/apps/docs/content/docs/docs/latest/forms/schema-validation.mdx

An example demonstrating how to keep input in React state until a user clicks 'Continue', using `ctx.validate()` in the `beforeStepChange` guard to validate pending data before committing.

```tsx
import { defineStepper } from "@stepperize/react";
import { useState } from "react";
import { z } from "zod";

const shippingSchema = z.object({
  address: z.string().min(1, "Address is required"),
  zip: z.string().regex(/^\d{5}$/, "Enter a 5-digit ZIP"),
});

const checkout = defineStepper([
  { id: "shipping", title: "Shipping", schema: shippingSchema },
  { id: "review", title: "Review" },
] as const);

type Shipping = z.input<typeof shippingSchema>;

export function CheckoutShippingStep() {
  const [shipping, setShipping] = useState<Shipping>({
    address: "",
    zip: "",
  });
  const [errors, setErrors] = useState<string[]>([]);

  const stepper = checkout.useStepper({
    beforeStepChange: async ({ direction, validate }) => {
      if (direction === "prev") return true;

      const result = await validate();

      if (!result.success) {
        setErrors(result.issues.map((issue) => issue.message));
        return false;
      }

      setErrors([]);
      return true;
    },
  });

  return (
    <form onSubmit={(event) => event.preventDefault()}>
      {stepper.is("shipping") && (
        <>
          <label>
            Address
            <input
              value={shipping.address}
              onChange={(event) =>
                setShipping({ ...shipping, address: event.target.value })
              }
            />
          </label>
          <label>
            ZIP
            <input
              value={shipping.zip}
              onChange={(event) =>
                setShipping({ ...shipping, zip: event.target.value })
              }
            />
          </label>
          {errors.map((error) => (
            <p key={error} role="alert">
              {error}
            </p>
          ))}
          <button type="button" onClick={() => stepper.next({ data: shipping }) }>
            Continue
          </button>
        </>
      )}

      {stepper.is("review") && (
        <>
          <pre>{JSON.stringify(stepper.data.get("shipping"), null, 2)}</pre>
          <button type="button" onClick={() => stepper.prev()}>
            Back
          </button>
        </>
      )}
    </form>
  );
}
```

--------------------------------

### Define a Stepper

Source: https://github.com/damianricobelli/stepperize/blob/main/apps/docs/content/docs/docs/latest/api/react/primitives.mdx

Define a stepper with multiple steps, each having an id, title, and description. This setup is used across all examples.

```tsx
import { defineStepper } from "@stepperize/react";

const checkout = defineStepper([
  { id: "shipping", title: "Shipping", description: "Delivery address" },
  { id: "payment", title: "Payment", description: "Payment method" },
  { id: "review", title: "Review", description: "Confirm order" },
]);
```

--------------------------------

### Get Helpers

Source: https://github.com/damianricobelli/stepperize/blob/main/apps/docs/content/docs/docs/latest/api/react/types.mdx

The `Get` helper utility, along with `defineStepper`, allows you to derive specific types based on your stepper definition. This is particularly useful for creating strongly-typed references to step IDs or specific step configurations.

```APIDOC
## Get Helpers

### Description
The `Get` helper utility, along with `defineStepper`, allows you to derive specific types based on your stepper definition. This is particularly useful for creating strongly-typed references to step IDs or specific step configurations.

### Usage
```tsx
import { defineStepper, type Get } from "@stepperize/react";

const checkout = defineStepper([
  { id: "shipping", title: "Shipping" },
  { id: "payment", title: "Payment" },
  { id: "review", title: "Review" },
]);

type StepId = Get.Id<typeof checkout.steps>;
type PaymentStep = Get.StepById<typeof checkout.steps, "payment">;
```
```

--------------------------------

### Expensive Data Table Example with Activity Component

Source: https://github.com/damianricobelli/stepperize/blob/main/apps/docs/content/docs/docs/latest/guides/react-activity.mdx

This example demonstrates how to use the Activity component to maintain the state of an expensive data table (including query, sort, and selected rows) across different steps in a report builder wizard. It ensures that when the user navigates back to the table step, its UI state is preserved.

```tsx
import { defineStepper } from "@stepperize/react";
import { Activity, useMemo, useState } from "react";

type Row = {
  id: string;
  name: string;
  revenue: number;
};

const reportFlow = defineStepper([
  { id: "filters", title: "Filters" },
  { id: "table", title: "Data table" },
  { id: "review", title: "Review" },
] as const);

export function ReportBuilder() {
  const stepper = reportFlow.useStepper();

  return (
    <>
      {stepper.steps.map((step) => (
        <Activity key={step.id} mode={stepper.is(step.id) ? "visible" : "hidden"}>
          {step.id === "filters" && <FilterStep />}
          {step.id === "table" && <ExpensiveTableStep />}
          {step.id === "review" && <ReviewStep />}
        </Activity>
      ))}

      <button type="button" disabled={!stepper.canPrev} onClick={() => stepper.prev()}>
        Back
      </button>
      <button type="button" disabled={!stepper.canNext} onClick={() => stepper.next()}>
        Continue
      </button>
    </>
  );
}

function ExpensiveTableStep() {
  const rows = useMemo(() => buildLargeDataset(), []);
  const [query, setQuery] = useState("");
  const [sort, setSort] = useState<"name" | "revenue">("revenue");
  const [selected, setSelected] = useState<string[]>([]);

  const visibleRows = useMemo(
    () =>
      rows
        .filter((row) => row.name.toLowerCase().includes(query.toLowerCase()))
        .sort((a, b) =>
          sort === "name"
            ? a.name.localeCompare(b.name)
            : b.revenue - a.revenue,
        ),
    [rows, query, sort],
  );

  return (
    <section>
      <input value={query} onChange={(event) => setQuery(event.target.value)} />
      <button type="button" onClick={() => setSort("name")}>Sort by name</button>
      <button type="button" onClick={() => setSort("revenue")}>Sort by revenue</button>

      <table>
        <tbody>
          {visibleRows.map((row) => (
            <tr key={row.id}>
              <td>
                <input
                  type="checkbox"
                  checked={selected.includes(row.id)}
                  onChange={(event) =>
                    setSelected((current) =>
                      event.target.checked
                        ? [...current, row.id]
                        : current.filter((id) => id !== row.id),
                    )
                  }
                />
              </td>
              <td>{row.name}</td>
              <td>{row.revenue}</td>
            </tr>
          ))}
        </tbody>
      </table>
    </section>
  );
}

function FilterStep() {
  const [region, setRegion] = useState("all");

  return (
    <section>
      <label>
        Region
        <select value={region} onChange={(event) => setRegion(event.target.value)}>
          <option value="all">All regions</option>
          <option value="americas">Americas</option>
          <option value="emea">EMEA</option>
          <option value="apac">APAC</option>
        </select>
      </label>
    </section>
  );
}

function ReviewStep() {
  return (
    <section>
      <h2>Review</h2>
      <p>Return to the table: its query, sort, and selected rows are preserved.</p>
    </section>
  );
}

function buildLargeDataset(): Row[] {
  return Array.from({ length: 500 }, (_, index) => ({
    id: `row-${index}`,
    name: `Customer ${index + 1}`,
    revenue: Math.round(1000 + Math.random() * 9000),
  }));
}

```

--------------------------------

### React Wizard with Stepperize Activity

Source: https://github.com/damianricobelli/stepperize/blob/main/apps/docs/content/docs/docs/latest/guides/react-activity.mdx

This example demonstrates an uncontrolled Stepperize state for navigation and local React state within each step. It's a copy-pasteable TypeScript example that can be adapted for various form components.

```typescript
import { defineStepper } from "@stepperize/react";
import { Activity, useId, useState } from "react";

const signup = defineStepper([
  { id: "account", title: "Account" },
  { id: "profile", title: "Profile" },
  { id: "preferences", title: "Preferences" },
  { id: "review", title: "Review" },
] as const);

type StepId = (typeof signup.steps)[number]["id"];

export function PreservedSignupWizard() {
  const stepper = signup.useStepper();

  return (
    <div className="wizard">
      <nav aria-label="Signup steps">
        {stepper.steps.map((step, index) => (
          <button
            key={step.id}
            type="button"
            aria-current={stepper.is(step.id) ? "step" : undefined}
            onClick={() => stepper.goTo(step.id)}
          >
            {index + 1}. {step.title}
          </button>
        ))}
      </nav>

      <div className="step-panels">
        {stepper.steps.map((step) => (
          <Activity
            key={step.id}
            mode={stepper.is(step.id) ? "visible" : "hidden"}
          >
            <StepPanel stepId={step.id} />
          </Activity>
        ))}
      </div>

      <footer>
        <button type="button" disabled={!stepper.canPrev} onClick={() => stepper.prev()}>
          Back
        </button>
        <span>
          Step {stepper.index + 1} of {stepper.count}
        </span>
        <button type="button" disabled={!stepper.canNext} onClick={() => stepper.next()}>
          {stepper.isLast ? "Done" : "Continue"}
        </button>
      </footer>
    </div>
  );
}

function StepPanel({ stepId }: { stepId: StepId }) {
  switch (stepId) {
    case "account":
      return <AccountStep />;
    case "profile":
      return <ProfileStep />;
    case "preferences":
      return <PreferencesStep />;
    case "review":
      return <ReviewStep />;
  }
}

function AccountStep() {
  const instanceId = useStableInstanceId();
  const [name, setName] = useState("");
  const [email, setEmail] = useState("");

  return (
    <section>
      <Header title="Account" instanceId={instanceId} />
      <label>
        Name
        <input value={name} onChange={(event) => setName(event.target.value)} />
      </label>
      <label>
        Email
        <input
          type="email"
          value={email}
          onChange={(event) => setEmail(event.target.value)}
        />
      </label>
      <pre>{JSON.stringify({ name, email }, null, 2)}</pre>
    </section>
  );
}

function ProfileStep() {
  const instanceId = useStableInstanceId();
  const [bio, setBio] = useState("");

  return (
    <section>
      <Header title="Profile" instanceId={instanceId} />
      <label>
        Bio
        <textarea value={bio} onChange={(event) => setBio(event.target.value)} />
      </label>
      <p>{bio.length} characters</p>
    </section>
  );
}

function PreferencesStep() {
  const instanceId = useStableInstanceId();
  const [newsletter, setNewsletter] = useState(true);
  const [theme, setTheme] = useState("system");

  return (
    <section>
      <Header title="Preferences" instanceId={instanceId} />
      <label>
        <input
          type="checkbox"
          checked={newsletter}
          onChange={(event) => setNewsletter(event.target.checked)}
        />
        Product newsletter
      </label>
      <label>
        Theme
        <select value={theme} onChange={(event) => setTheme(event.target.value)}>
          <option value="system">System</option>
          <option value="light">Light</option>
          <option value="dark">Dark</option>
        </select>
      </label>
    </section>
  );
}

function ReviewStep() {
  const instanceId = useStableInstanceId();
  const [notes, setNotes] = useState("");

  return (
    <section>
      <Header title="Review" instanceId={instanceId} />
      <p>
        Go back to earlier steps. Their inputs are still mounted behind Activity
        boundaries, so local state is restored immediately.
      </p>
      <label>
        Review notes
        <textarea value={notes} onChange={(event) => setNotes(event.target.value)} />
      </label>
    </section>
  );
}

function Header({ title, instanceId }: { title: string; instanceId: string }) {
  return (
    <header>
      <h2>{title}</h2>
      <p>Stable component instance: {instanceId}</p>
    </header>
  );
}

function useStableInstanceId() {
  return useId();
}

```

--------------------------------

### Inferring Step IDs and Types with Get Helpers

Source: https://github.com/damianricobelli/stepperize/blob/main/apps/docs/content/docs/docs/latest/api/react/types.mdx

Demonstrates how to use the `Get` helper type from `@stepperize/react` to infer specific types like Step IDs and individual Step types based on a stepper definition.

```typescript
import { defineStepper, type Get } from "@stepperize/react";

const checkout = defineStepper([
  { id: "shipping", title: "Shipping" },
  { id: "payment", title: "Payment" },
  { id: "review", title: "Review" },
]);

type StepId = Get.Id<typeof checkout.steps>;
type PaymentStep = Get.StepById<typeof checkout.steps, "payment">;
```

--------------------------------

### Controlled Stepper Initialization

Source: https://github.com/damianricobelli/stepperize/blob/main/apps/docs/content/docs/docs/latest/core-concepts/controlled-vs-uncontrolled.mdx

Use this when you need to manage the current step externally, for example, syncing with a URL or an external state manager. You provide the current step value and a handler to update it.

```tsx
const [step, setStep] = React.useState("shipping");

const stepper = checkout.useStepper({
  step, // you provide the value
  onStepChange: setStep, // you apply the change
});
```

--------------------------------

### LLM Migration Prompt for Stepperize v6 to v7

Source: https://github.com/damianricobelli/stepperize/blob/main/apps/docs/content/docs/docs/latest/migration/v7.mdx

Use this comprehensive prompt with a coding assistant to guide the migration of a Stepperize v6 codebase to v7, ensuring behavioral preservation and adherence to v7's flat API model.

```markdown
# Task: migrate this codebase from @stepperize/react v6 to v7

You are a senior React + TypeScript engineer and a **Stepperize migration expert**.
Migrate every Stepperize usage in the code I provide from **v6** to **v7**.

The defining change in v7: the instance is **flat**. v6's nested namespaces
(`state`, `navigation`, `flow`, `metadata`, `lookup`, `lifecycle`) are gone — every
property and method now lives directly on the `stepper` object.

## Prime directives (read first, obey throughout)

- **Preserve behavior, type safety, accessibility, and UX exactly.** The migrated
  app must do what it did before.
- **Change only what v7 requires.** No drive-by refactors, renames, reordering,
  reformatting, or dependency bumps. Touch the smallest possible surface.
- **Preserve intent, not just syntax.** When a mapping is ambiguous, reason about
  what the code is trying to achieve and migrate to the idiomatic v7 pattern.
- **Never invent APIs.** Use only the v7 surface documented below. If something has
  no clear v7 equivalent, stop and ask rather than guessing.
- **Explain every non-mechanical decision** and flag anything you cannot preserve
  exactly.

## The v7 mental model (six ideas)

1. **Flat instance** — `stepper.current`, `stepper.next()`, `stepper.match({...})`,
   `stepper.data`, `stepper.setComplete()`. No nested namespaces.
2. **Steps are an array** — `defineStepper([stepA, stepB])`.
3. **Navigation is async** — `next`, `prev`, `goTo`, `reset` return
   `Promise<boolean>` (`true` = the step changed, `false` = blocked/edge/cancelled).
4. **`data` replaces `metadata`** — typed (via per-step `schema`), per-step flow data.
5. **Status vs completion are separate axes.** Positional status
   (`active` / `previous` / `upcoming`) is derived automatically. Completion
   (`setComplete()` / `isComplete()`) is **explicit business state you set**. A
   `previous` step is **not** automatically completed.
6. **Lifecycle is `beforeStepChange` (guard) and `onStepChange` (after / write).**
   Both are instance options — there are no imperative event subscriptions.

## API mapping (v6 → v7)

| v6 | v7 |
| --- | --- |
| `defineStepper(a, b, c)` | `defineStepper([a, b, c])` |
| `Scoped` | generated `Provider` |
| `initialStep` (prop) | `defaultStep` (instance/Provider/Root) |
| `initialStep` (shared default) | `defaultStep` in the `defineStepper` options object |
| `initialMetadata` | `defaultData` (definition option) |
| `stepper.metadata.get/set/reset` | `stepper.data.get/set/reset` |
| `stepper.state.current.data` | `stepper.current` |
| `stepper.state.current.id` | `stepper.id` |
| `stepper.state.current.index` | `stepper.index` |
| `stepper.state.all` | `stepper.steps` |
| `stepper.state.isFirst` / `isLast` | `stepper.isFirst` / `stepper.isLast` |
| `stepper.navigation.next/prev/goTo/reset` | `stepper.next/prev/goTo/reset` (async) |
| `stepper.flow.switch({...})` | `stepper.match({...})` (exhaustive) |
| `stepper.flow.when(id, ...)` | `stepper.is(id) && ...` |
| `stepper.lookup.get(id)` | `checkout.get(id)` (definition helper) |
| `stepper.lifecycle.onBeforeTransition` | `beforeStepChange` option |
| `stepper.lifecycle.onAfterTransition` | `onStepChange` option |
| status "success" | positional "previous" **or** `isComplete(id)` — decide by intent (see pitfalls) |
| status "inactive" | "upcoming" |
```

--------------------------------

### Primitive Components for Custom UI

Source: https://github.com/damianricobelli/stepperize/blob/main/packages/react/README.md

Utilize the primitive components like `Stepper.Root`, `Stepper.List`, `Stepper.Item`, `Stepper.Trigger`, `Stepper.Indicator`, `Stepper.Title`, `Stepper.Actions`, `Stepper.Prev`, and `Stepper.Next` for building a fully custom stepper UI. This example demonstrates a more advanced usage with a step list and custom action buttons.

```tsx
const { Stepper } = wizard;

function PrimitiveWizard() {
  return (
    <Stepper.Root>
      {({ stepper }) => (
        <>
          <Stepper.List>
            <Stepper.Items>
              {(step) => (
                <Stepper.Item key={step.id} step={step.id}>
                  <Stepper.Trigger>
                    <Stepper.Indicator />
                    <Stepper.Title>{step.title}</Stepper.Title>
                  </Stepper.Trigger>
                </Stepper.Item>
              )}
            </Stepper.Items>
          </Stepper.List>

          <Stepper.Actions>
            <Stepper.Prev>Back</Stepper.Prev>
            <Stepper.Next>{stepper.isLast ? "Finish" : "Next"}</Stepper.Next>
          </Stepper.Actions>
        </>
      )}
    </Stepper.Root>
  );
}
```

--------------------------------

### Define Stepper with TypeScript

Source: https://github.com/damianricobelli/stepperize/blob/main/apps/docs/content/docs/docs/latest/getting-started/installation.mdx

Import and define a stepper using the `defineStepper` function. This example shows a basic checkout flow with shipping, payment, and review steps.

```tsx
import { defineStepper } from "@stepperize/react";

const checkout = defineStepper([
  { id: "shipping", title: "Shipping" },
  { id: "payment", title: "Payment" },
  { id: "review", title: "Review" },
]);
```

```tsx
const checkout = defineStepper([
  { id: "shipping", title: "Shipping" },
  { id: "payment", title: "Payment" },
  { id: "review", title: "Review" },
]);
```

--------------------------------

### Build Project

Source: https://github.com/damianricobelli/stepperize/blob/main/README.md

Build the project for production. This command compiles and bundles the code, preparing it for deployment.

```bash
pnpm build
```

--------------------------------

### Create and Use Step Map

Source: https://github.com/damianricobelli/stepperize/blob/main/apps/docs/content/docs/docs/latest/api/core/overview.mdx

Demonstrates how to create a step map from a steps configuration and access its various properties and methods for navigation and lookup.

```typescript
import { createStepMap } from "@stepperize/core";

const stepMap = createStepMap(steps);

stepMap.ids;
stepMap.get("shipping");
stepMap.at(0);
stepMap.indexOf("payment");
stepMap.has("review");
stepMap.first();
stepMap.last();
stepMap.next("shipping");
stepMap.prev("review");
stepMap.neighbors("payment");
```

--------------------------------

### Set and Get Flow Data

Source: https://github.com/damianricobelli/stepperize/blob/main/apps/docs/content/docs/docs/latest/api/react/stepper-instance.mdx

Manage cross-step data using the stepper.data object. Set data for the current or a specific step, retrieve individual step data, or get all flow data.

```tsx
stepper.data.set("profile", { name: "Ada" });
const all = stepper.data.all(); // for review / summary screens
```

--------------------------------

### Format and Lint Project Code

Source: https://github.com/damianricobelli/stepperize/blob/main/README.md

Format the code according to project standards and then run the linter. This command ensures both code style and quality.

```bash
pnpm format-and-lint
```

--------------------------------

### Review Step Displaying Summary

Source: https://github.com/damianricobelli/stepperize/blob/main/apps/docs/content/docs/docs/latest/forms/react-hook-form.mdx

Display a summary of all collected data in the review step. Allows users to navigate back to previous steps to edit their information using the goTo method.

```typescript
function ReviewStep() {
  const stepper = checkout.useStepper();
  const all = stepper.data.all();

  return (
    <>
      <Summary section="Personal" data={all.personal} onEdit={() => stepper.goTo("personal")} />
      <Summary section="Shipping" data={all.shipping} onEdit={() => stepper.goTo("shipping")} />
      <Summary section="Payment"  data={all.payment}  onEdit={() => stepper.goTo("payment")} />
      <button type="button" onClick={submitOrder}>Place order</button>
    </>
  );
}

async function submitOrder() {
  await api.createOrder(checkout /* instance */.data.all());
}
```

--------------------------------

### Review Step Summary

Source: https://github.com/damianricobelli/stepperize/blob/main/apps/docs/content/docs/docs/latest/forms/patterns.mdx

Renders a summary of all drafted steps. Use `data.all()` to retrieve all drafted data for display. This step is read-only.

```tsx
function ReviewStep() {
  const stepper = checkout.useStepper();
  const all = stepper.data.all();

  return (
    <>
      <Summary section="Personal" data={all.personal} onEdit={() => stepper.goTo("personal")} />
      <Summary section="Shipping" data={all.shipping} onEdit={() => stepper.goTo("shipping")} />
      <Summary section="Payment"  data={all.payment}  onEdit={() => stepper.goTo("payment")} />

      <button type="button" onClick={submitOrder}>Place order</button>
    </>
  );
}
```

--------------------------------

### Initial Helpers

Source: https://github.com/damianricobelli/stepperize/blob/main/apps/docs/content/docs/docs/latest/api/core/overview.mdx

Utility functions to determine the initial step index and retrieve initial data, primarily useful when building custom adapters for Stepperize.

```typescript
getInitialStepIndex(steps, initial);
getInitialData(data);
```

--------------------------------

### Flow Data Management

Source: https://github.com/damianricobelli/stepperize/blob/main/apps/docs/content/docs/docs/latest/api/react/stepper-instance.mdx

Manage cross-step data, including getting, setting, clearing, and resetting data for individual steps or all steps.

```APIDOC
## Flow Data Management

### Description
Manage cross-step data, including getting, setting, clearing, and resetting data for individual steps or all steps.

### Methods
- `stepper.data.get()`: Get the data for the current step (type `unknown`).
- `stepper.data.get(id: string)`: Get the data for a specific step, typed according to its schema.
- `stepper.data.set(value: unknown)`: Set the data for the current step.
- `stepper.data.set(id: string, value: unknown)`: Set the data for a specific step.
- `stepper.data.all()`: Get all flow data, keyed by step ID.
- `stepper.data.clear(id?: string)`: Clear data for a specific step, or all steps if no ID is provided.
- `stepper.data.reset()`: Reset all flow data to defaults.
```

--------------------------------

### Review Step Data with Conform

Source: https://github.com/damianricobelli/stepperize/blob/main/apps/docs/content/docs/docs/latest/forms/conform.mdx

Access all collected step data for review without a form library.

```typescript
stepper.data.all() (no form library)
```

--------------------------------

### Await Navigation Result

Source: https://github.com/damianricobelli/stepperize/blob/main/apps/docs/content/docs/docs/latest/api/react/stepper-instance.mdx

Await navigation methods like stepper.next to get a boolean result indicating whether the navigation was successful and a change occurred.

```tsx
const accepted = await stepper.next(payload);
const accepted = await stepper.next({ data: currentStepData });
```

--------------------------------

### Get Stepper Status

Source: https://github.com/damianricobelli/stepperize/blob/main/apps/docs/content/docs/docs/latest/getting-started/concepts.mdx

Retrieve the positional status of a step (active, previous, upcoming) using its ID. This reflects the step's place in the sequence.

```tsx
stepper.status("shipping"); // "active" | "previous" | "upcoming"
```

--------------------------------

### Clone Repository

Source: https://github.com/damianricobelli/stepperize/blob/main/CONTRIBUTING.md

Clone your forked repository to your local machine.

```bash
git clone https://github.com/damianricobelli/stepperize.git
```

--------------------------------

### Basic Navigation Methods

Source: https://github.com/damianricobelli/stepperize/blob/main/apps/docs/content/docs/docs/latest/guides/navigation.mdx

Directly call navigation methods like next, prev, goTo, and reset from event handlers. Await them only when you need to process their results, such as saving form values.

```tsx
stepper.next();
stepper.prev();
stepper.goTo("payment");
stepper.reset();
```

--------------------------------

### Get Step Status

Source: https://github.com/damianricobelli/stepperize/blob/main/apps/docs/content/docs/docs/latest/api/core/overview.mdx

Provides functions to retrieve the status of a single step or all steps relative to the current index. Statuses are positional: 'active', 'previous', or 'upcoming'.

```typescript
getStepStatus(steps, currentIndex, "shipping");
getStepStatuses(steps, currentIndex);
```

--------------------------------

### Stepper with Options

Source: https://github.com/damianricobelli/stepperize/blob/main/apps/docs/content/docs/docs/latest/api/react/use-stepper.mdx

Configures a stepper instance with options such as defaultStep and linear navigation. Use this for custom UI implementations.

```typescript
const stepper = checkout.useStepper({
  defaultStep: "payment",
  linear: true,
});
```

--------------------------------

### Uncontrolled Stepper Initialization

Source: https://github.com/damianricobelli/stepperize/blob/main/apps/docs/content/docs/docs/latest/core-concepts/controlled-vs-uncontrolled.mdx

Use this when Stepperize should manage the current step internally. Set a default starting step and allow Stepperize to handle navigation via its methods.

```tsx
const stepper = checkout.useStepper({ defaultStep: "shipping" });
// Stepperize owns the current step. next()/prev() just work.
```

--------------------------------

### Stepper Item with Index Number

Source: https://github.com/damianricobelli/stepperize/blob/main/apps/docs/content/docs/docs/latest/api/react/primitives.mdx

Render stepper items using their index. This example shows how to access the index within the Stepper.Items iterator to display step numbers.

```tsx
<Stepper.Root>
  {({ stepper }) => (
    <Stepper.List>
      <Stepper.Items>
        {(step, index) => (
          <Stepper.Item>
            <Stepper.Trigger>{index + 1}</Stepper.Trigger>
          </Stepper.Item>
        )}
      </Stepper.Items>
    </Stepper.List>
  )}
</Stepper.Root>
```

--------------------------------

### Initialize Stepper Instance

Source: https://github.com/damianricobelli/stepperize/blob/main/apps/docs/content/docs/docs/latest/api/react/stepper-instance.mdx

Use the useStepper hook from the stepper definition to create a runtime instance. This instance manages the live state and actions of the stepper.

```tsx
const stepper = checkout.useStepper();
```

--------------------------------

### Reusable Progress Component

Source: https://github.com/damianricobelli/stepperize/blob/main/apps/docs/content/docs/docs/latest/api/react/types.mdx

An example of a generic reusable component that accepts a stepper instance and displays progress information. It uses the `Step` and `Stepper` types for type safety.

```tsx
import type { Step, Stepper } from "@stepperize/react";

function Progress<Steps extends readonly Step[]>({ 
  stepper,
}: { 
  stepper: Stepper<Steps>;
}) {
  return (
    <p>
      Step {stepper.index + 1} of {stepper.count}
    </p>
  );
}
```

--------------------------------

### Accessing Draft Data vs. Validated Output

Source: https://github.com/damianricobelli/stepperize/blob/main/apps/docs/content/docs/docs/latest/forms/schema-validation.mdx

Illustrates the difference between accessing raw draft data using `stepper.data.get(id)` and obtaining validated, schema-compliant output via `await stepper.validate(id)`. Draft data is untrusted and may be incomplete.

```ts
// DRAFT — whatever was last written. May be incomplete or invalid.
const draft = stepper.data.get("shipping");

// VALIDATED — runs the step's schema and tells you if it passed.
const result = await stepper.validate("shipping");

```

--------------------------------

### Build Stepperize Blocks Registry

Source: https://github.com/damianricobelli/stepperize/blob/main/apps/docs/README.md

Generate the blocks registry by running this command. This script processes block components and writes registry files to 'registry.json', 'public/r/registry.json', and 'public/r/<block-name>.json'.

```bash
pnpm --filter docs registry:build
```

--------------------------------

### Controlled Provider Props

Source: https://github.com/damianricobelli/stepperize/blob/main/apps/docs/content/docs/docs/latest/api/react/provider.mdx

Configures the checkout provider with controlled state for step, data, and completion, along with event handlers. This example also enables linear navigation.

```tsx
<checkout.Provider
  step={step}
  onStepChange={setStep}
  data={values}
  onDataChange={setValues}
  linear
>
  <Checkout />
</checkout.Provider>
```

--------------------------------

### Navigation Gate with Conform

Source: https://github.com/damianricobelli/stepperize/blob/main/apps/docs/content/docs/docs/latest/forms/conform.mdx

Implement an optional navigation gate for steps using Conform's beforeStepChange.

```typescript
beforeStepChange on the Provider/instance
```

--------------------------------

### Accessing Stepper Instance Properties and Methods

Source: https://github.com/damianricobelli/stepperize/blob/main/apps/docs/content/docs/docs/latest/core-concepts/stepper-instance.mdx

Demonstrates how to access properties like `current` and `index`, and call methods like `next()` on a stepper instance obtained from `useStepper()`. This is a fundamental pattern for interacting with the stepper.

```tsx
const stepper = onboarding.useStepper();

stepper.current; // the active step object (with your custom fields)
stepper.index; // where the pointer is
stepper.next(); // move the pointer forward
stepper.match({ ... }); // render exactly the active step
```

--------------------------------

### Access Steps Without State

Source: https://github.com/damianricobelli/stepperize/blob/main/apps/docs/content/docs/docs/latest/api/react/define-stepper.mdx

Retrieves step information directly from the stepper definition using `at` for index-based access or `get` for id-based access. This is useful for static configuration or testing.

```tsx
const first = checkout.at(0);
const payment = checkout.get("payment");
```

--------------------------------

### Render Steps with `stepper.match`

Source: https://github.com/damianricobelli/stepperize/blob/main/apps/docs/content/docs/docs/latest/getting-started/first-stepper.mdx

Use `stepper.match` for rendering distinct content for each step. This method is exhaustive, ensuring all defined steps are handled.

```tsx
function Signup() {
  const stepper = signup.useStepper();

  return (
    <form>
      <p>
        Step {stepper.index + 1} of {stepper.count}: {stepper.current.title}
      </p>

      {stepper.match({
        name: () => <input name="name" placeholder="Ada Lovelace" />,
        email: () => <input name="email" placeholder="ada@example.com" />,
        confirm: () => <p>Review your details.</p>,
      })}

      <button type="button" disabled={!stepper.canPrev} onClick={() => stepper.prev()}>
        Back
      </button>
      <button type="button" disabled={!stepper.canNext} onClick={() => stepper.next()}>
        Next
      </button>
    </form>
  );
}
```

--------------------------------

### Stepper Navigation Methods

Source: https://github.com/damianricobelli/stepperize/blob/main/apps/docs/content/docs/docs/latest/api/react/use-stepper.mdx

Provides methods to navigate between steps: next, prev, goTo, and reset. Navigation can be awaited to confirm acceptance.

```typescript
stepper.next();
stepper.prev();
stepper.goTo("review");
stepper.reset();
```

--------------------------------

### ArkType Schema Validation with Stepperize

Source: https://github.com/damianricobelli/stepperize/blob/main/apps/docs/content/docs/docs/latest/forms/schema-validation.mdx

Shows how to use ArkType for schema definition and validation with Stepperize. This example validates a 'code' field against a regular expression using ArkType's `type` function.

```tsx
import { defineStepper } from "@stepperize/react";
import { type } from "arktype";
import { useEffect, useState } from "react";

const form = defineStepper([
  {
    id: "user",
    schema: type({ code: "/^[A-Z]{3}$/" }),
  },
]);

export function ArktypeValidationDemo() {
  const [code, setCode] = useState("ab");
  const [result, setResult] =
    useState<Awaited<ReturnType<typeof form.validate>> | null>(null);

  // `validate()` is async, so we derive the result in an effect — this runs on
  // mount (validating the initial value) and again on every change.
  useEffect(() => {
    form.validate("user", { code }).then(setResult);
  }, [code]);

  return (
    <div>
      <input value={code} onChange={(e) => setCode(e.target.value)} />
      {result?.success ? (
        <pre>{JSON.stringify(result.data, null, 2)}</pre>
      ) : (
        result?.issues.map((issue, i) => <p key={i}>{issue.message}</p>)
      )}
    </div>
  );
}
```

--------------------------------

### Zod Schema Validation with Stepperize

Source: https://github.com/damianricobelli/stepperize/blob/main/apps/docs/content/docs/docs/latest/forms/schema-validation.mdx

Example of defining a schema using Zod and validating user input with Stepperize's `defineStepper` and `validate` functions. The validation result is displayed, showing either the validated data or any issues found.

```tsx
import { defineStepper } from "@stepperize/react";
import { useEffect, useState } from "react";
import { z } from "zod";

const form = defineStepper([
  {
    id: "user",
    schema: z.object({ username: z.string().min(3, "At least 3 characters") }),
  },
]);

export function ZodValidationDemo() {
  const [username, setUsername] = useState("ab");
  const [result, setResult] =
    useState<Awaited<ReturnType<typeof form.validate>> | null>(null);

  // `validate()` is async, so we derive the result in an effect — this runs on
  // mount (validating the initial value) and again on every change.
  useEffect(() => {
    form.validate("user", { username }).then(setResult);
  }, [username]);

  return (
    <div>
      <input value={username} onChange={(e) => setUsername(e.target.value)} />
      {result?.success ? (
        <pre>{JSON.stringify(result.data, null, 2)}</pre>
      ) : (
        result?.issues.map((issue, i) => <p key={i}>{issue.message}</p>)
      )}
    </div>
  );
}
```

--------------------------------

### Style Stepper Indicator with Tailwind CSS

Source: https://github.com/damianricobelli/stepperize/blob/main/apps/docs/content/docs/docs/latest/guides/styling.mdx

Target the data-status attribute with the data-[…] variant in Tailwind CSS to style a stepper indicator based on its active, previous, or upcoming state. This example shows how to set border, background, and text colors.

```tsx
<Stepper.Indicator
  className="
    grid size-8 place-items-center rounded-full border text-sm font-medium
    data-[status=active]:border-primary data-[status=active]:bg-primary data-[status=active]:text-primary-foreground
    data-[status=previous]:border-primary data-[status=previous]:bg-primary/10 data-[status=previous]:text-primary
    data-[status=upcoming]:border-border data-[status=upcoming]:text-muted-foreground
  "
/>
```

--------------------------------

### Status and Rendering

Source: https://github.com/damianricobelli/stepperize/blob/main/apps/docs/content/docs/docs/latest/api/react/stepper-instance.mdx

Determine the status of a step and conditionally render components based on the current step.

```APIDOC
## Status and Rendering

### Description
Determine the status of a step and conditionally render components based on the current step.

### Methods
- `stepper.status(stepId: string)`: Returns the status of a given step (`"active"`, `"previous"`, or `"upcoming"`).
- `stepper.is(stepId: string)`: Returns a boolean indicating if the given step is the current step.
- `stepper.match(matchers: Record<string, () => React.ReactNode>)`: Renders a component based on the current step ID. The `matchers` object maps step IDs to functions that return React nodes.
```

--------------------------------

### Navigate (v7)

Source: https://github.com/damianricobelli/stepperize/blob/main/apps/docs/content/docs/docs/latest/migration/v7.mdx

Performs navigation actions like next, prev, and goTo directly on the stepper object in v7. Await navigation calls when the result is needed.

```tsx
// v7
stepper.next();
stepper.prev();
stepper.goTo("review");

```

--------------------------------

### Primitives Usage

Source: https://github.com/damianricobelli/stepperize/blob/main/apps/docs/content/docs/docs/latest/migration/v7.mdx

Demonstrates the usage of primitive stepper components like Stepper.Root, Stepper.List, Stepper.Items, Stepper.Item, Stepper.Trigger, Stepper.Content, and Stepper.Actions in v7.

```tsx
<Stepper.Root>
  {({
    stepper
  }) => (
    <>
      <Stepper.List>
        <Stepper.Items>
          {step => (
            <Stepper.Item key={step.id}>
              <Stepper.Trigger>{step.title}</Stepper.Trigger>
            </Stepper.Item>
          )}
        </Stepper.Items>
      </Stepper.List>

      <Stepper.Content step="shipping">Shipping</Stepper.Content>
      <Stepper.Content step="payment">Payment</Stepper.Content>

      <Stepper.Actions>
        <Stepper.Prev>Back</Stepper.Prev>
        <Stepper.Next>{stepper.isLast ? "Finish" : "Next"}</Stepper.Next>
      </Stepper.Actions>
    </>
  )}
</Stepper.Root>

```

--------------------------------

### Seed from Draft with Conform

Source: https://github.com/damianricobelli/stepperize/blob/main/apps/docs/content/docs/docs/latest/forms/conform.mdx

Initialize a Conform form with default values from a draft state.

```typescript
useForm({ defaultValue: stepper.data.get(id) })
```

--------------------------------

### Create New Branch

Source: https://github.com/damianricobelli/stepperize/blob/main/CONTRIBUTING.md

Create a new branch for your feature or bug fix.

```bash
git checkout -b your-feature-name
```

--------------------------------

### Basic Navigation Buttons

Source: https://github.com/damianricobelli/stepperize/blob/main/apps/docs/content/docs/docs/latest/getting-started/first-stepper.mdx

Implement navigation buttons using `stepper.prev()` and `stepper.next()`. The `stepper.canPrev` and `stepper.canNext` properties control button disabled states.

```tsx
<button type="button" disabled={!stepper.canPrev} onClick={() => stepper.prev()}>
  Back
</button>

<button type="button" disabled={!stepper.canNext} onClick={() => stepper.next()}>
  Next
</button>
```