createStepper
Create a flow and drive it.
import { createStepper } from "@stepperize/core";
const flow = createStepper(steps, options);| Parameter | Description |
|---|---|
steps | At least one step with a unique id, an optional schema, and any other field. |
options | Optional. The same options every binding accepts. |
The flow
A flow has every property and action of a stepper. Unlike the stepper a hook returns, which describes one moment, reads on a flow always return the latest state:
await flow.next(values);
flow.current.id;
flow.isLast;
flow.data; // every step as it was typed
flow.output; // what the schemas produced for the complete steps
flow.isFinished;
await flow.validate(); // check the current step without movingIt adds four members for whoever owns it.
| Member | Description |
|---|---|
get() | The current stepper: an immutable picture of the flow. A new object after every change, the same object until then. |
subscribe(listener) | Calls listener after every change. Returns a function that unsubscribes. |
setOptions(options) | Replaces the options. Bindings call it on every render so callbacks stay current. |
destroy() | Cancels a running move and drops every listener. |
Subscribing
get and subscribe are the contract external stores expect, so connecting a
framework takes a few lines.
// React
const stepper = useSyncExternalStore(flow.subscribe, flow.get);
// Svelte
const stepper = readable(flow.get(), (set) => flow.subscribe(() => set(flow.get())));
// Vue
const stepper = shallowRef(flow.get());
onScopeDispose(flow.subscribe(() => (stepper.value = flow.get())));The object get() returns is what the React hooks call a stepper. It is
immutable: one you kept keeps describing the moment it was taken, and get()
returns the same object until something changes, which is what external-store
APIs require.
Options that change
setOptions replaces every option except snapshot, which is only read when
the flow is created. A binding calls it whenever its owner re-renders, so
callbacks never go stale. When the step option changes, the flow follows it;
see The step in the URL.
Cleaning up
Call destroy() when the owner goes away. It cancels a move that is still
running (its promise resolves with reason: "cancelled") and removes every
listener.
Types
| Type | Description |
|---|---|
Step | { id: string; schema?: StandardSchemaV1 } plus your own fields. |
Id<S> | Union of the step ids. |
Input<S, I>, Output<S, I> | What a step stores, and what its schema produces. |
FlowData<S> | The data of every step, by id: schema inputs. |
FlowOutput<S> | What the schema of every complete step produced, by id: schema outputs. |
Options<S> | The options. |
Stepper<S>, Flow<S> | What get() returns, and a live flow. |
Snapshot<S> | { step, history, data, complete }. |
Result<S>, Reason | What a move resolves with. Reason is "invalid" | "guard" | "policy" | "pending" | "boundary" | "finished" | "cancelled". |
GuardContext<S> | The argument of guard. |
Issue | { message, path? }, as Standard Schema defines it. |
Last updated on