configurator

Prepare safe software configuration

Install

docsloth component add @docsloth/configurator@1.0.0

Live package: sha256:97c8deb6cdb1b9547d963504aaf0908d2048a07e478a7e88601d1ba07854bf90 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/configurator.schema.json.

Example props generated from this schema:

{
  "title": "example-title",
  "schema_ref": "example-schema_ref",
  "resource": {
    "resource_id": "00000000-0000-4000-8000-000000000000",
    "operation": "example-operation",
    "environment": "test"
  },
  "output_format": "yaml",
  "safe_defaults": {}
}

Required props: schema_ref, output_format, safe_defaults.

Example

Example document IR (the block the renderer consumes):

{
  "type": "configurator",
  "props": {
    "title": "example-title",
    "schema_ref": "example-schema_ref",
    "resource": {
      "resource_id": "00000000-0000-4000-8000-000000000000",
      "operation": "example-operation",
      "environment": "test"
    },
    "output_format": "yaml",
    "safe_defaults": {}
  }
}

Renderer HTML (entities decoded and wrapped for display):

<section class="ds-block ds-configurator" data-component="configurator" aria-labelledby="b-title">
<h3 class="ds-block-title" id="b-title">example-title</h3>
<dl class="ds-facts">
<div>
<dt>Schema</dt>
<dd>
<code>example-schema_ref</code>
</dd>
</div>
<div>
<dt>Runs</dt>
<dd>
<code>example-operation</code> in the test environment</dd>
</div>
</dl>
<p class="ds-code-caption">Safe defaults</p>
<pre class="ds-code" data-lang="yaml">
<code>{}</code>
</pre>
<p class="ds-live-note" role="note">Editing, validating and exporting this configuration 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/configurator.md.

Contract

Production props are normative in ../contracts/component-props/configurator.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

Generate copy/download configuration with unresolved secret references clearly marked.

Failure and fallback

No provider selected means unresolved config, not bogus working tokens.

Required acceptance cases

Secrets never serialized; escaping prevents code injection. 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 host binding

The host provides configurators keyed by configuratorKey(schema_ref, resource ?? null, output_format). An available record pins release, schema reference/version, session, resource operation/environment (or null), and output format. The schema is delivered only after audience authorization; missing, loading, restricted and mismatched bindings expose no configuration fields. This renderer does not invoke the manifest's remote tools or generic executors. Any separately implemented agent tool must be authorized per call and budgeted by its host; denials use permission_required.

The local form supports bounded flat scalar JSON Schema fields, required fields, enums, constants, numeric ranges and string lengths. Unsupported constraints fail closed. Production safe_defaults override ordinary schema defaults; unknown fields and invalid scalar types refuse. Schema/default changes reset the draft. Fields marked writeOnly, format: password or recognized common credential names have no input: their defaults are discarded and exports contain synthetic ${DOCSLOTH_SECRET_n} unresolved references. The host must correctly classify all secret fields before delivery; name detection is only a fallback and cannot identify an arbitrary credential hidden in an ordinary text field. No credentials belong in props or schema.

The preview and clipboard/download contain identical local bytes. JSON uses native serialization; YAML uses quoted JSON keys/scalars (YAML 1.2 compatible). env emits **POSIX shell assignments**, with literal single-quote escaping; it is not a universal dotenv dialect. Invalid shell variable names and NUL values refuse. Draft input and output are bounded; exports cannot exceed 128 KiB. No generated text is executed, applied or persisted by this renderer. Without a selected provider or resolved secrets, the template explicitly makes no working-connection claim.

No-JavaScript defaults and preview remain readable with disabled controls. Clipboard denial retains manual selection; download errors are visible. Scope/access/default/schema replacement removes prior draft state and suppresses late clipboard status. Host schema retrieval, server access control, secret resolution and versioned persistence of any applied component patch remain integration responsibilities.

Package manifest

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

Sources