CnSetupWizard

Abstract, manifest-driven first-time setup wizard (ADR-042). Wraps CnWizardDialog and renders a manifest.setup.steps[] array by each step's type, reusing the same field components the admin pages use. It is the second modal in the first-open flow (after the "help us" modal), and is also openable from the admin page via CnAdminSettingsShell.

It NEVER writes OpenRegister objects from the browser — OpenRegister enforces RBAC on saveObject, so all persistence goes through a per-app server contract (POST /apps/{appId}/api/setup/config and /api/setup/action/{actionId}), which runs privileged. CnAppRoot's setup phase gates the app shell while a required step is unmet.

Step types

`type`	Renders	Persists via
`info`	a note card (`title` + `body`)	—
`config-fields`	fields from a JSON Schema (`fieldsFromSchema`)	`POST /api/setup/config`
`choice`	an `NcSelect` bound to `configKey` (`options[]`, `multiple?`)	`POST /api/setup/config`
`run-action`	a "Run" button → `POST /api/setup/action/{action}` + result	the action itself
`summary`	a recap of step completion	—
`component`	the parent's `#step-<id>` slot (escape hatch)	up to the slot

Try it

<template>
  <CnSetupWizard
    :app-id="'procest'"
    :steps="manifest.setup.steps"
    @action-result="onActionResult"
    @complete="onComplete"
    @close="show = false" />
</template>

Props

Prop	Type	Default	Description
`appId`	`string`	— (required)	App id; builds the `/apps/{appId}/api/setup/*` URLs.
`steps`	`Array`	`[]`	The `manifest.setup.steps` array to render.
`dialogTitle`	`string`	`"Set up this app"`	Dialog header.
`submitLabel`	`string`	`"Finish"`	Final-step submit label.
`cancelLabel`	`string`	`"Cancel"`	Cancel label.
`nextLabel`	`string`	`"Next"`	Next label.
`backLabel`	`string`	`"Back"`	Back label.
`runLabel`	`string`	`"Run"`	Run-action button label.
`successText`	`string`	`"Setup complete."`	Result-phase success text.
`cancellable`	`boolean`	`true`	Whether the wizard can be dismissed before finishing. Pass `false` when a REQUIRED step is unmet and the host is gating its shell behind this wizard — an offered-but-non-functional Cancel would be misleading.
`completedStepIds`	`Array<string>`	`[]`	Ids of steps the server already reports done (e.g. from `useSetupStatus(...).steps`). Lets a freshly (re)mounted wizard resume at the first actually-unmet step and show correct done-markers, instead of restarting from the top — this component's own local state only tracks the current session.

Resuming vs. starting fresh

completedStepIds only affects resuming:

Fresh setup (completedStepIds empty) — always opens at step one, so a leading info / welcome step is actually seen.
Returning session — opens at the first unmet actionable step, skipping info and summary steps (they have nothing to resume past).
Everything done — opens at step one.

A server-done choice step also stops blocking Next when the user back-navigates onto it. choiceModel is session-local, so a resumed-past step renders blank even though its value is already persisted; the wizard treats a server-done step as satisfied instead of demanding a re-pick, and skips the redundant POST.

Events

Event	Payload	When
`complete`	—	The last step was submitted (setup finished). Note the wizard switches into its result phase here — the host should keep it mounted until `close`.
`action-result`	`{ stepId, action, success, message }`	A `run-action` step finished.
`step-change`	`{ stepId, stepIndex, direction }`	The active step changed.
`close`	—	The dialog should close.

Slots

#step-{id} — override a step's body (for component steps or any bespoke step). Scope: the CnWizardDialog step scope plus { step, runAction, saveConfig }.

Step types​

Try it​

Props​

Resuming vs. starting fresh​

Events​

Slots​

See also​