benefriches: Skill for Claude Code

Wizard-Form Engine (apps/web)

One generic algorithm drives every guided, multi-step form in the app — urban & photovoltaic, creation & editing. Each form is a thin definition plugged into a shared engine through an injected lens. Decision record: docs/adr/0015-extract-wizard-form-engine-via-injected-lens.md.

Glossary: Wizard form — one guided flow instance (e.g. urban-create). Context — the eager, guaranteed-present data buildContext derives from the slice (e.g. the site). Answers — the per-step user input accumulated in WizardFormSubState, keyed by StepId.

Read this before reading the files — it saves you from reverse-engineering the abstraction. Paths below are the source of truth; open them when you need detail.

The one idea: engine + definition, joined by a lens

The engine knows one abstract state shape, generic over <StepId, TAnswers>. It knows nothing about projects, sites, urban, or PV. A consumer connects its concrete form to the engine by supplying a WizardFormDefinition whose two key functions are the injected lens:

• selectForm(state) — locates this instance's WizardFormSubState inside the consumer's slice.
• buildContext(state) — builds the eager context (the site) handlers read.

That lens is why the same engine + same handler registry serve project and site forms alike: urban-create, urban-update, pv-create, pv-update, and the site forms — create-site/core/{custom, urban-zone, demo} and update-site/core (reusing the custom and urban-zone lenses).

Three layers

L1  shared/core/wizard-form/                     generic engine — ZERO domain, no slice/reducer
      stepHandler.type.ts    handler contract: AnswerStepHandler / InfoStepHandler
      wizardForm.reducer.ts  the shapes: WizardFormSubState, WizardFormDefinition
      wizardForm.actions.ts  makeWizardFormActionType(prefix, name)  — namespacing
      helpers/               the algorithm (pure fns): computeStepChanges, applyStepChanges,
                             navigateToStep, mutateState, readState, stepsSequence

L2  features/create-project/core/project-form/   shared "reconversion-project-on-a-site" domain
      site · stakeholders · soils-carbon · local-authorities · project-name
      (used by BOTH project types AND by create + update)

L3  features/create-project/core/{urban-project, renewable-energy}/   one per form type
      {type}Steps.ts               StepId union + AnswersByStep map (this is TAnswers)
      step-handlers/**             one pure handler per step
        stepHandlerRegistry.ts     aggregates them (answerStepHandlers + full nav registry)
      {type}Form.reducer.ts        add{Type}FormCasesToBuilder(builder, actions, definition)
      {type}Form.actions.ts        create{Type}FormActions(prefix)
      {type}Form.selectors.ts      create{Type}FormSelectors(prefix)

Views (feature-owned, shared by create + update):
  features/create-project/views/{urban-project, photovoltaic-power-station}/**   containers
  features/create-project/views/{project-form, .../renewable-energy-form}/       context seam
  .../stepToComponent.tsx    maps StepId -> the lazy-loaded container