toolmark-monorepo / @toolmark/react / useWizardTool
Function: useWizardTool()
useWizardTool(
opts):void
Defined in: packages/react/src/use-wizard-tool.ts:206
Registers a multi-step wizard (spec §8.2, D25) while the component is mounted: parent-state mode (opts.data + opts.setData present) uses createWizardTools; otherwise the stepwise fallback (createStepwiseWizardTools) is used, which requires opts.next, opts.previous and opts.currentAdapter — their absence is a misconfiguration (ToolmarkError code wizard_misconfigured when the registry was created with dev: true, an error event of the same code otherwise; nothing is registered either way).
Registration happens in an effect, under the current scope. submit, goTo, next, previous, setData, resetCurrent, currentAdapter and every step's options providers are read through refs, so a fresh closure/object each render never forces a re-registration by itself and every call always uses the latest one. The wizard re-registers only when name, description, title, the step names/count, a step's input/jsonSchema identity, or the presence of resetCurrent/parent-state-vs-stepwise mode changes.
Current-step sync (Task 4 review, requirement (b)): the wizard engine writes the current step only through its mounted currentAdapter, never into data — so data alone can miss the current step's latest edits. This hook closes that gap: right before <name>.goTo navigates away and right before <name>.submit runs the app's submit, it writes the current step's currentAdapter.getValues() into data (via setData), so a later tm.undo() sees them. The app's submit receives that merged data as its argument — read it from there, not from closed-over state, which is still the pre-merge snapshot in that same tick.
Synchronous parent-data reads (requirement (a)): setData updates an internal ref synchronously (in addition to calling the app's setData, which typically triggers a React state update that only becomes visible on the next render). The wizard reads data through that ref, so two fill/undo calls issued back-to-back — before React has re-rendered in between — each see the other's write instead of one silently overwriting the other from a stale snapshot.
Stepwise mode calls refresh() (bumping the current step's <name>.step.fill schema) whenever opts.current changes, in a second effect that never itself re-registers the wizard.
Parameters
opts
See UseWizardToolOptions.
Returns
void