code-group

Labelled alternative code samples

Install

docsloth component add @docsloth/code-group@1.0.0

Live package: sha256:eb5f37eae33a615a71ec7d4f1b84f436655eb8f4020762901bf67e80a0c8b5e8 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/code-group.schema.json.

Example props generated from this schema:

{
  "title": "Install",
  "active": 0,
  "activeTab": "npm"
}

This schema requires no props beyond the component envelope.

Example

Example document IR (the block the renderer consumes):

{
  "type": "code-group",
  "props": {
    "title": "Install",
    "active": 0
  },
  "children": [
    {
      "type": "code",
      "props": {
        "label": "npm",
        "language": "bash",
        "code": "npm add @docsloth/renderer"
      }
    },
    {
      "type": "code",
      "props": {
        "label": "pnpm",
        "language": "bash",
        "code": "pnpm add @docsloth/renderer"
      }
    }
  ]
}

Renderer HTML (entities decoded and wrapped for display):

<div class="ds-code-group" data-component="code-group">
<div class="ds-tablist" role="tablist" aria-label="Install">
<button type="button" class="ds-tab" role="tab" id="b-tab-0" aria-controls="b-panel-0" aria-selected="true" tabindex="0">npm</button>
<button type="button" class="ds-tab" role="tab" id="b-tab-1" aria-controls="b-panel-1" aria-selected="false" tabindex="-1">pnpm</button>
</div>
<div class="ds-tabpanels">
<div class="ds-tabpanel" role="tabpanel" id="b-panel-0" aria-labelledby="b-tab-0" tabindex="0">
<pre class="ds-code" data-lang="bash">
<code>npm add @docsloth/renderer</code>
</pre>
</div>
<div class="ds-tabpanel" role="tabpanel" id="b-panel-1" aria-labelledby="b-tab-1" tabindex="0">
<pre class="ds-code" data-lang="bash">
<code>pnpm add @docsloth/renderer</code>
</pre>
</div>
</div>
</div>

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

npm add @docsloth/renderer

pnpm add @docsloth/renderer

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/code-group.md.

Contract

Packaged: this block ships as @docsloth/code-group@1.0.0 — an installable component package (kind block, capability render.html, Apache-2.0) whose production props schema is packages/contracts/component-props/code-group.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

Group equivalent code samples (package managers, language variants, platform variants) without duplicating page content. Every sample stays in the DOM so no-JS and agent readers see all of them; the tablist only selects emphasis.

Failure and fallback

A group with no children, a child without a non-empty props.label, or a child that is not a code block degrades the whole block to the labelled fallback while keeping the child content visible. Unknown active/activeTab values degrade in place to the first sample.

Required acceptance cases

Switching samples must not change the meaning or content of any fence; the same language tag survives in the Markdown twin. 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.

Native renderer block

packages/renderer renders a code-group block with the existing tabs a11y contract: a role="tablist" whose role="tab" buttons wire aria-controls to matching role="tabpanel" panels, with the accessible name from props.title (default Code samples). Panels stay in the DOM (no hidden), so every sample reaches no-JS and agent readers. Markdown flattens the block to ### <label> subsections, each containing the child code fence with its original language tag.

Native block props

The tab buttons are content labels, not chrome, so they are not marked data-markdown-ignore; the Markdown twin carries the same labels as headings and the same language tags as fence info strings.

Example

{
  "type": "code-group",
  "props": { "title": "Install", "active": 0 },
  "children": [
    { "type": "code", "props": { "label": "npm", "language": "bash", "code": "npm add @docsloth/renderer" } },
    { "type": "code", "props": { "label": "pnpm", "language": "bash", "code": "pnpm add @docsloth/renderer" } }
  ]
}

Package manifest

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

Sources