# Changelog

> Review recent documentation and package changes.

Source: https://stepperize.com/docs/v8/changelog

Release notes for the current Stepperize documentation line.

## v8.0.0 — upcoming [#v800--upcoming]

- Test React and interactive examples in Chromium with Vitest Browser Mode; keep core and server tests in Node. Remove jsdom and Testing Library dependencies and recalculate the performance comparison with production React in a real browser.

### Breaking changes [#breaking-changes]

- Require React 18 or 19. `useStepper()` always creates local state; shared consumers use `useStepperContext(selector?, isEqual?)` under the matching Provider or Root.
- Navigation returns `NavigationResult`: `{ accepted: true, from, to }` or `{ accepted: false, reason }`.
- `goTo` respects linear policy. Intentional branches can pass `bypassPolicy: true`; guards still run.
- `reset()` restores mount-time step, data and completion. Replace old reset payloads with `keepData` / `keepCompleted` options.
- `createStepperPrimitives` is internal. Use each definition's generated `Stepper` primitives.

### Added [#added]

- Atomic source data and completion with `next/prev/goTo({ data, complete: true })`.
- `defaultCompleted` on hooks, Provider and Root; typed functional `data.update`; typed data in `match` handlers.
- Selector subscriptions with optional equality, independent nested scopes, `context.signal` cancellation and structured rejection reasons.
- Root orientation inheritance, `Content forceMount`, explicit `data-complete` and instance-scoped accessible IDs.

### Fixed [#fixed]

- Same-event duplicate navigation, lost compound writes, stale controlled state/callbacks in child effects, and uncached object selector loops.
- Cancelled/unmounted async guards cannot commit stale transitions or leak rejected promises.
- Triggers default to button type inside forms. Static step lookup indexes and linear-time status computation reduce repeated work.

### Documentation and examples [#documentation-and-examples]

- Separate `/docs/v7` and `/docs/v8` documentation, version-specific navigation and search, and a compatible `/docs/latest` alias.

- New local/shared guide and interactive demo, context-hook reference and v7-to-v8 migration guide.
- Updated API references, form integrations, FAQ, AI-readable documentation and v8-compatible registry examples.

Read [Migrating to v8](https://stepperize.com/docs/v8/migration/v8) before upgrading. These changes are prepared on the v8 branch and are not a published release yet.

## v7.0.0 [#v700]

v7 is a deliberate API reset for Stepperize. The goal is to make the stepper
instance easier to read, easier to type, and easier to wire into real workflows:
forms, guarded transitions, branching flows, URL-driven state, and headless UI.

The short version: define an ordered step list once, then work with one flat
instance everywhere.

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

const stepper = checkout.useStepper();

stepper.current;
await stepper.next();
stepper.data.set(values);
stepper.match({
  shipping: () => <ShippingForm />,
  payment: () => <PaymentForm />,
  review: () => <ReviewOrder />,
});
```

### Packages [#packages]

- `@stepperize/core`
- `@stepperize/react`

### Highlights [#highlights]

- Flat React instance: use `stepper.current`, `stepper.id`, `stepper.next()`,
  `stepper.match(...)`, `stepper.data`, and `stepper.setComplete()` directly.
  The old nested namespaces are gone.
- Ordered step definitions: `defineStepper([...])` now receives one array, which
  makes order explicit and gives the definition room for shared options like
  `defaultStep`, `defaultData`, `defaultCompleted`, and `linear`.
- Async navigation: `next`, `prev`, `goTo`, and `reset` now resolve to
  `Promise<boolean>`, so guarded transitions can block movement and callers can
  branch on the result.
- Guarded transitions: `beforeStepChange` can validate or cancel a move before
  data is committed. `onStepChange` runs after an accepted transition.
- Typed flow data: `data` replaces legacy metadata and can be inferred from each
  step's `schema` using Standard Schema-compatible validators.
- Explicit completion: positional status (`active`, `previous`, `upcoming`) is
  separate from business completion (`setComplete`, `isComplete`).
- Controlled state support for `step`, `data`, and `completed`, with matching
  change handlers for router, URL, store, or persisted-state integrations.
- Bound, unstyled React primitives are generated from each stepper definition,
  so headless UI keeps the same step ids, types, ARIA attributes, and navigation
  behavior as the hook.

### Breaking changes [#breaking-changes-1]

- `defineStepper(stepA, stepB)` is now `defineStepper([stepA, stepB])`.
- `Scoped` was renamed to the generated `Provider`.
- `initialStep` is now `defaultStep`; `initialMetadata` is now `defaultData`.
- `metadata.get`, `metadata.set`, and `metadata.reset` moved to `data.get`,
  `data.set`, and `data.reset`.
- Namespaced instance APIs were flattened:
  - `stepper.state.current.data` -> `stepper.current`
  - `stepper.state.current.id` -> `stepper.id`
  - `stepper.state.current.index` -> `stepper.index`
  - `stepper.state.all` -> `stepper.steps`
  - `stepper.navigation.next()` -> `stepper.next()`
  - `stepper.navigation.prev()` -> `stepper.prev()`
  - `stepper.navigation.goTo(id)` -> `stepper.goTo(id)`
  - `stepper.flow.switch(...)` -> `stepper.match(...)`
  - `stepper.flow.when(id, ...)` -> `stepper.is(id) && ...`
- Lifecycle subscriptions were replaced with instance options:
  `beforeStepChange` for guards and `onStepChange` for accepted transitions.
- Navigation methods are async. If code branches on whether navigation worked,
  `await` the call before checking the result.
- Status names changed from `"success"` / `"inactive"` to `"previous"` /
  `"upcoming"`. Use `isComplete(id)` when you mean "this step is done" instead
  of "this step appears before the current one."

### Features [#features]

- New `@stepperize/core` package with public types and pure helpers for shared,
  framework-independent stepper logic.
- New step map helpers with `get`, `at`, `indexOf`, `has`, `first`, `last`,
  `next`, `prev`, and `neighbors`.
- New `parseStep` helper for narrowing external values, such as URL params or
  persisted snapshots, into known step ids.
- New `validateStep` helper and instance-level `validate()` method for
  Standard Schema-compatible step validation.
- New status helpers for deriving positional step state from the active index.
- New exhaustive `matchStep` core utility and React `stepper.match(...)` API for
  typed rendering by step id.
- New transition payloads: pass `{ data }` to `next`, `prev`, `goTo`, or `reset`
  to stage current-step data before guards run.
- New `isPending` state and `canPrev` / `canNext` guards to make async
  transitions easier to reflect in UI.
- New `canGoTo(id)` policy check used by trigger primitives and useful for
  linear flows.
- New `Stepper.Items` primitive for iterating through the typed step list inside
  a generated primitive tree.

### Migration example [#migration-example]

```tsx
// v6
const { useStepper, Scoped } = defineStepper(
  { id: "account", title: "Account" },
  { id: "profile", title: "Profile" },
);
```

```tsx
// v7
const accountFlow = defineStepper([
  { id: "account", title: "Account" },
  { id: "profile", title: "Profile" },
]);

const { useStepper, Provider } = accountFlow;
```

```tsx
// v6
stepper.navigation.next();
stepper.flow.switch({
  account: () => <Account />,
  profile: () => <Profile />,
});
```

```tsx
// v7
await stepper.next();
stepper.match({
  account: () => <Account />,
  profile: () => <Profile />,
});
```

### Migration [#migration]

Read [Migrating to v7](https://stepperize.com/docs/v8/migration/v7) for the full v6 -> v7 API
map, common pitfalls, and a copy-paste migration prompt for coding assistants.

## Interactive guides [#interactive-guides]

Explore guarded navigation and cancellation, reset options, controlled state, selectors, linear policy and nested ownership through live examples. Each v8 guide includes guided exercises and the exact source of its demo.
