wizard

Collect configuration and validate prerequisites

Install

docsloth component add @docsloth/wizard@1.0.0

Live package: sha256:500b2eb0f2f3cd3c5ec3a66e20981fec775e727c18547a8105edddb8d5c55862 with 2 file digest(s); the catalog entry is generated from the built package, not a placeholder.

Props

The prop schema is normative in packages/contracts/component-props/wizard.schema.json.

Example props generated from this schema:

{
  "title": "example-title",
  "workflow_id": "example-workflow_id",
  "input_schema": {},
  "steps": [
    {
      "id": "example-id",
      "fields": [
        "example-fields"
      ]
    }
  ],
  "resource": {
    "resource_id": "00000000-0000-4000-8000-000000000000",
    "operation": "example-operation",
    "environment": "test"
  }
}

Required props: workflow_id, input_schema, steps.

Example

Example document IR (the block the renderer consumes):

{
  "type": "wizard",
  "props": {
    "title": "example-title",
    "workflow_id": "example-workflow_id",
    "input_schema": {},
    "steps": [
      {
        "id": "example-id",
        "fields": [
          "example-fields"
        ]
      }
    ],
    "resource": {
      "resource_id": "00000000-0000-4000-8000-000000000000",
      "operation": "example-operation",
      "environment": "test"
    }
  }
}

Renderer HTML (entities decoded and wrapped for display):

<section class="ds-block ds-wizard" data-component="wizard" aria-labelledby="b-title">
<h3 class="ds-block-title" id="b-title">example-title</h3>
<ol class="ds-list">
<li>
<code>example-id</code>: <code>example-fields</code>
</li>
</ol>
<dl class="ds-facts">
<div>
<dt>Workflow</dt>
<dd>
<code>example-workflow_id</code>
</dd>
</div>
<div>
<dt>Runs</dt>
<dd>
<code>example-operation</code> in the test environment</dd>
</div>
</dl>
<p class="ds-live-note" role="note">Filling in and validating this wizard needs the live documentation site.</p>
</section>

Preview (interface-only; the markup above is the same output):

The renderer resolves this component as a native block; the preview above is its real HTML output, and Markdown parity for native blocks is covered by the renderer test suite.

Specification

Generated from packages/contracts/component-specs/wizard.md.

Contract

Production props are normative in ../contracts/component-props/wizard.schema.json. The corresponding component-fixtures manifest is only a minimal protocol fixture; use the production props schema when building the published package. The packaged artifact ships exactly its generated component-package.json manifest plus props.schema.json (the production props schema, copied byte-for-byte) and spec.md (this spec, copied byte-for-byte); it contains no executable payload, fallback implementation, Storybook, test suite, SSR harness or README. Rendering behavior and the acceptance cases below belong to the renderer and the repository tests, not to the package. Installation pins the package version and the digest of every shipped byte.

Intended behavior

JSON-schema guided config with accessible errors; secrets use broker set-secret flow, never ordinary fields.

Failure and fallback

Invalid value cannot advance required step.

Required acceptance cases

Back navigation retains nonsecret values; no hidden paid-resource enable. Also test empty data, loading, denied access, browser without JS, mobile 360px, keyboard navigation, dark mode and an explicit constrained agent tool call. The server independently authorizes capability requests; a package manifest cannot grant authority.

Data and maintenance

Data bindings resolve from a specific publication/release vector and permitted fact/evidence graph. Configuration edits create versioned component patches. Update invalidation uses dependency IDs, never indiscriminate whole-page regeneration. Human-owned props survive automatic updates unless invalidated with an explicit conflict. Missing optional resources leave an honest inert/readable fallback, not a broken page or fake success.

Cost and tools

Pure/local interaction must never invoke a model by accident. Any model, remote query or executor call must reserve approved budget before dispatch. Public visitors do not inherit owner resources. The component may call only named tools in its signed manifest with valid typed inputs. A cancelled job stops polling and closes resources. No component gets platform administration, raw credentials or an unlimited execution loop.

React configuration adapter

Production workflow_id, input_schema, steps and optional resource define a local draft. The current renderer supports a bounded flat JSON Schema 2020-12 object: string, number, safe integer and boolean properties; required fields; scalar enum/const choices; Unicode code-point length and numeric bounds; and nonsecret defaults. Unsupported types, references, conditional or regular-expression constraints refuse the entire form instead of silently weakening validation. Every property must appear in exactly one step; no invisible defaults can enable resources. There are at most 100 fields and 100 steps, 100 choices per field, 4,096 UTF-16 code units per ordinary input and 65,536 overall. Optional untouched fields remain absent; zero, false and an explicitly entered empty string keep their meaning. Back retains nonsecret draft values.

Fields marked writeOnly: true, format: "password", or common credential names use only a separate host secret broker. Secret defaults are ignored and secret enum/const values refuse. The wizard never renders a raw secret input. Schema authors must mark other credential fields explicitly; name matching is not a complete secret classifier. The host must not deliver actual secrets as props, annotations or defaults: omitting them from the UI cannot protect bytes already sent to a browser. The broker owns entry, validates secret constraints and returns an opaque reference; references are kept separately from nonsecret values and are never displayed.

ComponentContentProvider.wizards selects a binding with wizardKey(workflow_id, resource) from @docsloth/official-components/host. Available bindings name the release ID, workflow ID/version and actor session ID. Optional setSecret receives that scope, the field ID and an abort signal. Its typed stored result must repeat the scope, field ID and bounded opaque reference. Optional validate receives the scope, typed values, separate secretReferences and an abort signal. It returns scoped validated with a public-safe summary, scoped invalid with known field errors, or permission_required, unsupported or failed. HTTP success alone never proves validation. Messages must not contain secrets.

Next and Back are local. The last step opens a review; a separate explicit action invokes configured prerequisite validation. This wizard never applies configuration, enables a paid resource, issues arbitrary execution requests or persists drafts in browser storage. Without JavaScript all fields remain readable with actions disabled. Missing/restricted/loading adapters are labelled; required secrets cannot advance without the broker. Scope changes clear drafts and references. Stop waiting aborts the adapter and discards late replies without claiming remote rollback. The host must independently authorize the exact published workflow/resource, reserve approved budget, validate all submitted values and reference ownership/liveness, and enforce the schema again on the server. Real broker, core/cloud transport and constrained agent-tool dispatch remain host integration work; browser tests exercise this adapter over a scoped HTTP fixture.

Package manifest

Protocol fixture: packages/contracts/component-fixtures/wizard.json.

Sources