steps

Ordered walkthrough steps

Install

docsloth component add @docsloth/steps@1.0.0

Live package: sha256:0ba6c7b14beefa4700152e0095a95ac319e7f7b4d9e87440d9bbba78710fab87 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/steps.schema.json.

Example props generated from this schema:

{
  "title": "Quickstart"
}

This schema requires no props beyond the component envelope.

Example

Example document IR (the block the renderer consumes):

{
  "type": "steps",
  "props": {
    "title": "Quickstart"
  },
  "children": [
    {
      "type": "prose",
      "props": {
        "label": "Install the CLI",
        "text": "Add the package."
      }
    },
    {
      "type": "prose",
      "props": {
        "label": "Render a page",
        "text": "Call renderPageToMarkdown."
      }
    }
  ]
}

Renderer HTML (entities decoded and wrapped for display):

<ol class="ds-steps" data-component="steps" aria-label="Quickstart">
<li class="ds-step" data-step="1">
<span class="ds-step-number" aria-hidden="true" data-markdown-ignore="true">1</span>
<p class="ds-step-title">Install the CLI</p>
<div class="ds-prose">Add the package.</div>
</li>
<li class="ds-step" data-step="2">
<span class="ds-step-number" aria-hidden="true" data-markdown-ignore="true">2</span>
<p class="ds-step-title">Render a page</p>
<div class="ds-prose">Call renderPageToMarkdown.</div>
</li>
</ol>

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/steps.md.

Contract

Packaged: this block ships as @docsloth/steps@1.0.0 — an installable component package (kind block, capability render.html, Apache-2.0) whose production props schema is packages/contracts/component-props/steps.schema.json and whose catalog entry is in packages/contracts/component-catalog.json. No protocol manifest fixture is published (manifest_fixture: null): the fixture models a packaged protocol runtime this block does not have.

Intended behavior

Ordered walkthrough: each child renders as an <li> inside a single <ol>, with an optional step title from label/title/summary. Markdown emits a numbered list with the step body nested under its item, and JSON preserves child order and labels.

Failure and fallback

Empty children or a non-array children value degrades to the labelled fallback block (data-fallback="true", Markdown note, JSON fallback: true); an empty walkthrough never renders as silent success, and no prop shape throws.

Required acceptance cases

Render two steps and assert <ol>/<li> order, aria-hidden="true" + data-markdown-ignore="true" on the number markers, 1./2. Markdown items, and HTML/Markdown visible-text parity. Also test empty data, a non-array children value, unknown extra props, mobile 360px, 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.

Native renderer block

Block type: steps. Renderer: packages/renderer/src/index.ts (native, no permission surface).

Native block props

Ordering comes from the <ol> and the Markdown list markers; the visible number badge is interface-only chrome marked data-markdown-ignore and aria-hidden.

Example

{
  "type": "steps",
  "props": { "title": "Quickstart" },
  "children": [
    { "type": "prose", "props": { "label": "Install the CLI", "text": "Add the package." } },
    { "type": "prose", "props": { "label": "Render a page", "text": "Call renderPageToMarkdown." } }
  ]
}

Markdown:

1. **Install the CLI**

   Add the package.

2. **Render a page**

   Call renderPageToMarkdown.

Package manifest

No protocol fixture is published for this renderer-native block.

Sources