@inditextech/docouture-asciidoc-extensions 0.1.0-SNAPSHOT.40.1

package/README.md

@@ -0,0 +1,254 @@
+# @inditextech/docouture-asciidoc-extensions
+
+Asciidoctor extensions shared by the docouture documentation sites.
+
+They exist for one reason: **authored content that AsciiDoc has no syntax for**.
+A card grid, a set of steps, a landing hero, a tab switcher — none of these are
+expressible in AsciiDoc, and none of them belong baked into a Handlebars layout,
+because then they stop being content an author can write and become markup only
+a UI developer can change. An extension is the seam between the two: the author
+writes AsciiDoc, the extension emits the design system's markup.
+
+Where a thing belongs, before you write anything here:
+
+| the thing is                                   | it lives in                                      |
+| ---------------------------------------------- | ------------------------------------------------ |
+| site chrome, present on every page             | a Handlebars partial in `ui-bundle/src/partials` |
+| derived from HTML Asciidoctor already produces | CSS alone, in `ui-bundle/src/css`                |
+| authored content with no AsciiDoc equivalent   | **an extension here**                            |
+
+If Asciidoctor already emits the element and you only need it to look right,
+this package is the wrong tool — style it in `ui-bundle`. Admonitions, tables and
+code blocks are all handled that way.
+
+## The contract
+
+Every extension in this package keeps all eight of these.
+
+### 1. One file per extension, registered in `index.js`
+
+`lib/<name>.js` exports a single `register<Name>(registry)` function.
+`index.js` requires it and calls it from `registerAll`. Nothing else registers
+anything — a site lists this package once and gets the whole set.
+
+`lib/` also holds modules that register nothing: `async-compat.js`,
+`first-positional.js`, `html.js`, `unique-id.js`, `warn.js`, `kroki-config.js`
+and `kroki-instance.js`. They are helpers, required directly by the
+extensions, and are deliberately absent from `index.js`.
+
+### 2. `register` is exported as both a named export and `module.exports.register`
+
+Only `index.js` deals with this, and it already does. The shape is not
+cosmetic — it is what makes registration work in two different hosts, and each
+one fails silently when it is wrong:
+
+- **Antora** matches `register.toString()` against a regex requiring the first
+  parameter to be **literally named `registry`**. Rename it, or ship a bundled
+  build that renames it, and Antora decides the module is an _Antora_ extension
+  listed under the wrong key, logs `Skipping possible Antora extension
+registered as an Asciidoctor extension`, and moves on. Nothing renders. No
+  error.
+- **The ui-bundle preview harness** calls `register.call(Asciidoctor.Extensions)`
+  with no argument — `this` is the namespace, not a registry — and does so once
+  per rebuild in the same process, which is why `index.js` carries an
+  idempotency guard. Without it, a table ends up wrapped in one more nested
+  container per rebuild.
+
+Read `index.js`'s own header comment before touching any of it, and
+`.opencode/skills/asciidoc/reference/extensions.md` for the registration
+mechanics in full.
+
+### 3. Emit IOP DS BEM markup, exactly
+
+Copy the DS component's real markup and class names. Never invent a class on a
+DS block, never re-implement a component's styling from memory. If nothing in
+the DS models what you need, say so before inventing — it usually means the
+wrong component was identified. See `.opencode/skills/iop-ds-components`.
+
+### 4. Ship no CSS
+
+This package emits markup and nothing else. Styling lives in
+`ui-bundle/src/css`. An extension that needs new CSS is a change to two
+packages, in that order — never a `<style>` tag, never a stylesheet here.
+
+### 5. Degrade without JavaScript
+
+A page must be readable, navigable and correctly styled with JavaScript off.
+Tabs render as sequential sections, each under its own heading; accordions
+render as `<details>`; anything clickable is a real `<a href>`. Behaviour is
+layered onto server-rendered markup by `ui-bundle/src/js` — it never creates
+markup.
+
+### 6. Set real ARIA, and never an inline `style`
+
+Interactive markup carries the roles and relationships its pattern requires
+(`role=tablist`/`tab`/`tabpanel`, `aria-controls`, `aria-selected`), keyboard
+operability included. Use `lib/unique-id.js` for the ids those relationships
+need; see its header for why a module-level counter is wrong here.
+
+Inline `style` is not a styling escape hatch. The one existing exception —
+`video-size.js` — sets _custom properties_ that the stylesheet consumes, because
+a browser will not derive `aspect-ratio` from an iframe's HTML attributes and
+there is no CSS-only fix. That is the bar: a documented impossibility, not a
+convenience.
+
+### 7. Escape raw attribute values — and only those
+
+Asciidoctor substitutes some authored strings before an extension sees them and
+others not at all. Escaping the wrong ones double-encodes (`&` renders as
+`&amp;`); missing the right ones lets authored text inject markup. Measured on
+both majors this repo runs, with `A & B <x>`:
+
+| source                                | arrives as            | escape? |
+| ------------------------------------- | --------------------- | ------- |
+| inline macro, positional or named     | `A &amp; B &lt;x&gt;` | no      |
+| document attribute (`:page-k:`)       | `A &amp; B &lt;x&gt;` | no      |
+| **block macro attribute** (`x::t[…]`) | `A & B <x>`           | **yes** |
+| **block style attribute** (`[x,k=…]`) | `A & B <x>`           | **yes** |
+
+Identical on 2.2.9 and 4.0.8 — it is a block-vs-inline split, not a version
+split. Separately, anything from `getText()` is **already converted HTML** (a
+dlist term with an `xref:` arrives as a full `<a>`), so it must never be
+escaped.
+
+Use `lib/html.js`: `escapeHtml(value)` and `attr(name, value)`. Its header
+carries the full table and the probe behind it.
+
+### 8. Stay portable across both Asciidoctor majors
+
+Site builds run **2.2** (via Antora); the ui-bundle preview harness runs **4.0**.
+Touch only `registry`/`this` — never the `@asciidoctor/core` module object,
+whose export shape differs between the two.
+
+Two behavioural splits are already solved, and both must be reused rather than
+rediscovered:
+
+- **Attribute shape.** An inline macro's first positional attribute is
+  `attrs.$positional[0]` under 2.2 and `attrs['1']` under 4.0 — use
+  `lib/first-positional.js`.
+- **Sync vs async.** `parseContent`, `convert` and `precomputeText` are
+  synchronous under 2.2 and Promise-returning under 4.0. An extension cannot
+  simply be `async`: that hands 2.2's synchronous Opal caller a Promise, which
+  renders as the literal text `[object Promise]`. Use `chain`/`chainAll`/
+  `precomputeSubtree` from `lib/async-compat.js`.
+
+`@asciidoctor/core` is a devDependency for its TypeScript types only. It is
+version 4.0, so those types describe the preview harness's runtime, not
+Antora's — treat them as a typing aid, not as proof that an API exists in 2.2.
+
+## Reporting authoring mistakes
+
+Both site playbooks set `runtime.log.failure_level: warn`, so **a warning fails
+the build**. That is the right severity for an authoring error: an unknown label
+colour, a `[cards]` block with no cards, a tab set with no panels all render as
+something plausible but wrong, and shipping that is worse than not building.
+
+Use `lib/warn.js` so every extension reports in the same shape — what the author
+wrote, what is wrong, and what was expected:
+
+```js
+warn(parent, 'label:mauve[]', 'unknown IDS Label variant "mauve"', VARIANTS)
+// → label:mauve[] — unknown IDS Label variant "mauve"; expected one of white, grey, …
+```
+
+## Using this package in a site
+
+Two steps, both required. Doing only one fails silently.
+
+1. List it under `asciidoc.extensions` in the site's `antora-playbook.yml`
+   (or, for the ui-bundle preview, in `preview-src/ui-model.yml`).
+2. Add it as a dependency with the workspace protocol:
+   `"@inditextech/docouture-asciidoc-extensions": "workspace:*"`.
+
+Note the neighbouring package: `@inditextech/docouture-antora-extensions` hooks
+Antora's own pipeline under the **`antora.extensions`** key. Listing either
+package under the other's key makes Antora log a warning and skip it.
+
+### Kroki: opt-in, disabled by default
+
+`[mermaid]`, `[plantuml]`, `[graphviz]` and the rest of `kroki.js`'s
+`SUPPORTED_TYPES` are the one extension in this package that is **not** active
+just by listing the package — see that file's own header. A site turns it on
+with two more `asciidoc.attributes`:
+
+```yaml
+asciidoc:
+  attributes:
+    kroki-enabled: true
+    kroki-diagram-types: mermaid,plantuml # optional; omitted = every supported type
+```
+
+Per-block, `[mermaid,format=png]` renders a transparent PNG `<img>` instead of the
+default inline SVG — see `kroki-config.js`'s `PNG_SUPPORTED_TYPES` for which of
+`SUPPORTED_TYPES` actually support it (`bpmn` and `excalidraw` notably don't; Kroki
+itself rejects those two output formats outright). An unsupported combination falls
+back to `svg` with a build warning.
+
+Mermaid diagrams also get IOP DS-aligned styling (square corners, DS colors, DS body
+typography) baked in server-side via a `%%{init: {...}}%%` directive
+`kroki-mermaid-theme.js` prepends to the diagram's own source before it reaches Kroki
+— not a CSS override, so it applies identically whether the block renders as `svg` or
+`format=png`. An author who opens their own diagram with `%%{init...}%%` opts out
+automatically (Mermaid only honors the first one); every other `SUPPORTED_TYPES` entry
+keeps its own baked-in look, font aside (ui-bundle's `diagram.css` normalizes that one
+blanket, safely, for every type).
+
+It also needs a Kroki service reachable at build time, at the fixed local URL
+`kroki-config.js` hardcodes (not itself configurable — see that file's own
+header for why). No manual setup: the sibling `@inditextech/docouture-antora-
+extensions` package's `kroki-prewarm.js` starts one itself, via `docker
+compose`, the first time a build needs it and finds nothing already
+listening — on every invocation path (`docouture dev`/`docouture build`, this
+monorepo's own `just dev`/`just build-site`, a raw `antora` call, any
+consumer's own CI) equally, with no automatic teardown (a stopped-and-
+restarted Kroki on every build would only add latency back). Run `docouture
+eject kroki` to copy the bundled compose file into a site's own repo for
+customization (a different image version, a companion container for
+another diagram type); run `docouture teardown kroki` (or, in this monorepo,
+`just kroki-down`) to stop it manually once you're actually done with it.
+Without `kroki-enabled: true`, or if Docker/the service never becomes
+reachable, these blocks render exactly as plain AsciiDoc already would — a
+disabled or unavailable Kroki is never itself a build failure.
+
+A healthy run is otherwise silent: `kroki-docker.js` and `kroki-prewarm.js`
+log their whole lifecycle (already-reachable / starting via which compose
+file / `docker compose up -d` succeeded / became reachable after Ns /
+render summary) at `info`, so nothing about a working setup looks different
+from Nx quietly replaying a stale cached build. Antora's own default log
+level is `warn`, so these are invisible unless you ask for them — as is
+every other docouture extension's own `getLogger('docouture-...')` observability
+(search-index's per-component summary, llms-txt's, footer's, ...), same
+reasoning throughout. This monorepo's own `just dev`/`just build-site`
+recipes, and `docouture dev`/`docouture build` (`antora-log.ts` in the `cli`
+package), all pass `--log-level=info` to every Antora invocation they make
+for exactly this reason, so no extra flag is needed there — a raw `antora`
+invocation of your own still needs `--log-level=info` (or
+`ANTORA_LOG_LEVEL=info`) passed explicitly. A real failure (Docker missing,
+daemon unreachable, service never comes up, an individual diagram failing
+to render) still logs at `warn` unconditionally either way.
+
+## Targets
+
+```
+pnpm nx run @inditextech/docouture-asciidoc-extensions:lint
+pnpm nx run @inditextech/docouture-asciidoc-extensions:typecheck
+```
+
+There is deliberately **no `build` and no `clean`**: the package is plain
+CommonJS, consumed by `require()` straight from source. Nothing is compiled,
+nothing is emitted, so there is nothing to remove. Adding no-op targets to
+match the other packages would be noise.
+
+`typecheck` runs TypeScript over the JavaScript (`allowJs` + `checkJs`) using
+the JSDoc annotations. `noImplicitAny` and `noImplicitThis` are off, and only
+those two — see `tsconfig.json` for the measurement behind that and for how they
+get retired. New files are written fully annotated; `lib/html.js`,
+`lib/unique-id.js` and `lib/warn.js` are the reference for what that looks like.
+
+## Further reading
+
+- `.opencode/skills/asciidoc/reference/extensions.md` — extension points, the
+  DSL, and the registration rules in full
+- `.opencode/skills/iop-ds-components` — choosing a DS component and emitting
+  its markup
+- `.opencode/skills/iop-ds-foundations` — tokens, theming, breakpoints

package/index.js

@@ -0,0 +1,117 @@
+'use strict'
+
+// Every extension in lib/ is registered here, and only here — see README.md
+// for the contract each one keeps. Note that lib/ also holds modules that
+// register nothing and are absent from this list on purpose: async-compat.js,
+// first-positional.js, html.js, unique-id.js, warn.js, shiki-instance.js and
+// shiki-config.js are shared helpers the extensions require directly.
+// kroki-config.js and kroki-instance.js are the same kind of helper, shared
+// between kroki.js (below) and the sibling
+// @inditextech/docouture-antora-extensions package's kroki-prewarm.js — see
+// kroki.js's own header. shiki-syntax-highlighter.js is the one exception
+// that DOES register something outside `registerAll` — see its own
+// `require(...)` below.
+const registerLabelMacro = require('./lib/label-macro')
+const registerMonoMacro = require('./lib/mono-macro')
+const registerTableWidth = require('./lib/table-width')
+const registerTableContainer = require('./lib/table-container')
+const registerNowrapCols = require('./lib/nowrap-cols')
+const registerVideoSize = require('./lib/video-size')
+const registerCardGrid = require('./lib/card-grid')
+const registerFeatureTabs = require('./lib/feature-tabs')
+const registerCta = require('./lib/cta')
+const registerAccordion = require('./lib/accordion')
+const registerTabs = require('./lib/tabs')
+const registerKroki = require('./lib/kroki')
+
+// GH-89: registers Asciidoctor's 'shiki' SyntaxHighlighter adapter. Required
+// here, at module top level, NOT inside `registerAll` below — this is a
+// GLOBAL, one-time registration on the `@asciidoctor/core` module itself
+// (node's require cache is what makes "once" hold), not a per-page
+// `registry` registration like everything else in this file. See that
+// module's own header for the full explanation.
+require('./lib/shiki-syntax-highlighter')
+
+function registerAll(target) {
+  registerLabelMacro(target)
+  registerMonoMacro(target)
+  // table-width.js's tree processor must run (be registered) before
+  // table-container.js's postprocessor for its stash to exist by the time
+  // the postprocessor reads it — tree processors always run before
+  // postprocessors regardless of registration order (Asciidoctor's own
+  // fixed processor-phase pipeline), but keeping the registration order
+  // matching that phase order here too, for anyone reading top to bottom.
+  registerTableWidth(target)
+  registerTableContainer(target)
+  registerNowrapCols(target)
+  registerVideoSize(target)
+  // [cards] — Weave.js migration Phase 2, see its own
+  // header comment for the DS components behind it and why.
+  registerCardGrid(target)
+  // [feature-tabs] — the landing's Key features switcher (GH-22). The only
+  // block here with behaviour layered on top of it; see its own header for
+  // why the tab ARIA is applied by ui-bundle's 07-feature-tabs.ts rather
+  // than emitted from here.
+  registerFeatureTabs(target)
+  // [cta] — the landing's call to action (GH-23), styled after Fumadocs'
+  // "Free & Open Source" block rather than a Figma frame; see its own header
+  // for why it deviates from GH-23's original macro sketch.
+  registerCta(target)
+  // [accordion] — GH-61 Part 2, grouping semantics (role=group, single-open)
+  // over a run of ordinary [%collapsible] blocks (Part 1's own restyle of
+  // those, in ui-bundle/src/css/accordion.css). An OPEN block, not an
+  // example block like every entry above it — see its own header for why.
+  registerAccordion(target)
+  // [tabs] — GH-45, real tabs for the migrated quickstart's package-manager
+  // code blocks (and any other authored content wanting a switcher). Also
+  // an OPEN block, for the mirror-image reason accordion.js gives — see its
+  // own header.
+  registerTabs(target)
+  // [mermaid]/[plantuml]/etc — GH-44, real diagrams via a self-hosted Kroki
+  // service, over the literal diagram source the Weave.js migration left
+  // behind (see tools/fumadocs-migrate/lib/emit.mjs). Unlike every extension
+  // above, OPT IN and disabled by default per site — see its own header for
+  // why, and for the `kroki-enabled`/`kroki-diagram-types` attributes that
+  // turn it on. Registers once per supported diagram type, not once overall.
+  registerKroki(target)
+}
+
+/**
+ * Registers docouture' AsciiDoc extensions.
+ *
+ * Antora calls this once per page with a fresh, per-page `registry` (see
+ * @antora/asciidoc-loader's resolve-asciidoc-config.js) — the first
+ * parameter must be literally named `registry` or Antora's own regex match
+ * against `register.toString()` fails, decides this is an Antora pipeline
+ * extension mistakenly listed here, logs a warning, and skips it entirely.
+ *
+ * The ui-bundle preview harness (gulp.d/tasks/build-preview-pages.js) calls
+ * this differently: `extension.register.call(Asciidoctor.Extensions)` — no
+ * argument, `this` bound to the Asciidoctor 4.0 `Extensions` NAMESPACE, not
+ * a registry. That object has `.register`/`.create` but no `.inlineMacro`
+ * of its own (verified empirically) — `.register(fn)` is what hands `fn` a
+ * real registry as ITS `this`, one more hop than the Antora case.
+ *
+ * That global path is a one-time registration for the life of the process —
+ * fine for a single `gulp preview:build` run, but `gulp preview` (the
+ * watch server) re-runs build-preview-pages.js, and so this whole module,
+ * on every rebuild WITHOUT restarting the node process. `Extensions.register`
+ * has no dedupe of its own: each rebuild adds one more global registration,
+ * so a table ends up wrapped in as many nested `.tableblock-wrap`s as
+ * rebuilds have happened — a real bug reproduced live in that watch server
+ * (`.tableblock-wrap` nested inside its own `.tablecontainer`, doubling the
+ * width cap). Guarded here with a flag on the namespace object itself,
+ * rather than in gulp.d (out of this package's own control) — idempotent
+ * across any number of calls in the same process.
+ */
+module.exports.register = function (registry) {
+  const target = registry || this
+  if (typeof target.inlineMacro === 'function') {
+    registerAll(target)
+  } else if (!target.$docoutureAsciidocExtensionsRegistered) {
+    target.$docoutureAsciidocExtensionsRegistered = true
+    target.register(function () {
+      registerAll(this)
+    })
+  }
+}

package/lib/accordion.js

@@ -0,0 +1,243 @@
+'use strict'
+
+const { chain, chainAll, precomputeSubtree } = require('./async-compat')
+const { escapeHtml, attr, stripTags } = require('./html')
+const uniqueId = require('./unique-id')
+const warn = require('./warn')
+
+// Accordion grouping — GH-61 Part 2. Adds only what a native `[%collapsible]`
+// cannot express on its own: group semantics (`role=group`, an accessible
+// name) and, optionally, single-open behaviour. Part 1 (accordion.css,
+// ui-bundle) already restyles every `[%collapsible]` as a DS accordion item,
+// independent-mode by construction — this block is the thinnest possible
+// wrapper around a run of them, never a reimplementation.
+//
+// SYNTAX
+//
+// An OPEN block (`--`/`--`), not an example block (`====`) like every other
+// grouping extension in this package (`[cards]`, `[steps]`, `[feature-tabs]`
+// all use `onContext('example')`). Deliberate: the children here are
+// THEMSELVES example blocks — a `[%collapsible]` is `[%collapsible]====…====`
+// — and nesting an example block inside another example block forces the
+// child to `=====` (one more `=`), which is easy to get wrong and stops
+// looking like an ordinary, standalone collapsible. An open block's own
+// delimiter is `--`, so the children stay ordinary `====` blocks, unchanged,
+// exactly as they would read outside a group:
+//
+//   [accordion%single-open,aria-label="Frequently asked questions"]
+//   --
+//   .Can I use Weave.js with any UI framework?
+//   [%collapsible]
+//   ====
+//   Yes, Weave.js is framework-agnostic by design.
+//   ====
+//
+//   .Can I deploy the frontend and backend on a single artifact?
+//   [%collapsible]
+//   ====
+//   Yes, you can bundle them together.
+//   ====
+//   --
+//
+// `single-open` is the DS component's own vocabulary (`AccordionProps.
+// singleOpen`, `accordion.d.ts`), spelled as Asciidoctor's own option
+// shorthand — the same `%name` mechanism `[%collapsible]` itself already
+// uses (`Parser.parseStyleAttribute`, verified against the vendored parser:
+// a style token can carry a style name AND `%option`s together, e.g. the
+// `[%collapsible%open]` an author can already write today). Absent the
+// option, items are independent — the same default the DS component's own
+// `singleOpen` prop has.
+//
+// WHAT THIS EMITS
+//
+// `<div class="docouture-accordion-group" role="group" aria-label="…">` wrapping
+// the children's OWN converted markup verbatim — nothing here re-renders a
+// collapsible; `child.convert()` is Asciidoctor's own `convert_example`
+// (`node.hasOption('collapsible')` branch), unchanged. `docouture-accordion-group`
+// is not an invented DS class — the real `Accordion` component's own wrapper
+// `<div>` (`accordion.js`) carries no class of its own beyond whatever the
+// CALLER passes; there is nothing to match here, so this file names its own
+// wrapper the same way every other non-DS wrapper in this package does
+// (`docouture-cta`, `docouture-card-grid`, `docouture-feature-tabs`). Styled in
+// `ui-bundle/src/css/accordion.css`, alongside the items it groups.
+//
+// Single-open is implemented with the native `<details name="…">` radio-group
+// behaviour, `name` shared across every child in the group via
+// `lib/unique-id.js` — regex-patched onto each child's own rendered
+// `<details>` tag, the same "lift the converter's own tag, patch one
+// attribute" technique `video-size.js`/`cta.js` already use. That makes
+// single-open work with NO JavaScript in every browser new enough to
+// support `<details name>` (Chrome 120+, Safari 17.2+, Firefox 130+) — a
+// degradation to independent mode elsewhere, never a break. Real keyboard
+// roving focus (arrow/Home/End across headers) is layered on top of this
+// same markup by `ui-bundle/src/js/10-accordion.ts`; this file emits no
+// script and no inline `style`.
+
+/** The first `<details` of a child's own converted markup — see header. */
+const DETAILS_OPEN_RX = /^<details\b/
+
+/**
+ * Cross-major `hasOption` — the same split `first-positional.js`'s own
+ * header documents for a different method, here for this one: 2.2's JS API
+ * names it `isOption` (verified against the vendored dist,
+ * `AbstractNode.prototype.isOption`); 4.0 renamed it to `hasOption`
+ * (`abstract_node.js`'s own comment: "option? → hasOption"). Needed here,
+ * unlike `child.hasRole(...)` elsewhere in this package's other extensions —
+ * `hasRole` kept its name across both majors, `hasOption` did not.
+ *
+ * @param {Block} node
+ * @param {string} name
+ * @returns {boolean}
+ */
+function hasOption(node, name) {
+  if (typeof node.hasOption === 'function') return node.hasOption(name)
+  // 2.2's own JS API (Opal, real Antora builds) — absent from 4.0's
+  // `AbstractNode` type declarations, so a plain property access is a type
+  // error even though it exists at runtime; only reachable when the
+  // `hasOption` branch above is false, i.e. actually running 2.2.
+  return /** @type {{ isOption(name: string): boolean }} */ (/** @type {unknown} */ (node)).isOption(name)
+}
+
+/**
+ * An Asciidoctor block, in whichever major is running.
+ *
+ * @typedef {import('@asciidoctor/core').AbstractBlock} Block
+ */
+
+/**
+ * Escapes a value ALREADY produced by the converter (`getTitle()`) for
+ * placement inside a double-quoted HTML attribute. Deliberately not
+ * `lib/html.js`'s `escapeHtml` — that helper is for RAW block attributes
+ * Asciidoctor never substitutes; a block's title is the opposite case
+ * (`lib/html.js`'s own header: "anything from `getText()`/`getTitle()` is
+ * already converted HTML"), so `&`/`<`/`>` are already entities and escaping
+ * them again would double-encode (`&amp;` → `&amp;amp;`). Only the quote
+ * that would otherwise close the attribute early needs handling here.
+ *
+ * @param {string} html - converted HTML, e.g. `wrapper.getTitle()`.
+ * @returns {string} the same text, safe inside `"…"`.
+ */
+function escapeConvertedAttribute(html) {
+  return html.replace(/"/g, '&quot;')
+}
+
+/**
+ * The group's accessible name: the `aria-label=` attribute when given (a raw
+ * block attribute, so escaped normally), falling back to the wrapper's own
+ * block title with its markup stripped (converted HTML, so quote-escaped
+ * only — see {@link escapeConvertedAttribute}) — an ARIA attribute value
+ * cannot itself carry HTML, so any tags a titled `.Title` line converted to
+ * (a bold word, an `xref:`) are dropped rather than left as visible text.
+ *
+ * @param {object} attrs - the block's own attributes.
+ * @param {Block} wrapper - the parsed `[accordion]` content, for its title.
+ * @returns {string} the label, or `''` when there is none.
+ */
+function ariaLabelFor(attrs, wrapper) {
+  const raw = attrs['aria-label']
+  if (raw) return escapeHtml(raw)
+  const title = wrapper.getTitle()
+  if (!title) return ''
+  return escapeConvertedAttribute(stripTags(String(title)))
+}
+
+/**
+ * The group's `[%collapsible]` children — anything else authored inside the
+ * open block (a stray paragraph, a non-collapsible example block) is left
+ * out silently, the same judgement `card-grid.js`/`feature-tabs.js` make for
+ * a stray child that isn't their own `[card]`/`[feature]` style.
+ *
+ * @param {Block} wrapper
+ * @returns {Block[]}
+ */
+function collapsibleChildren(wrapper) {
+  return wrapper.getBlocks().filter((block) => block.getContext() === 'example' && hasOption(block, 'collapsible'))
+}
+
+/**
+ * Assembles the block once every child has been rendered.
+ *
+ * @param {Block} parent - the block this replaces.
+ * @param {Block} wrapper - the parsed `[accordion]` content.
+ * @param {object} attrs - the block's own attributes.
+ * @param {{ createBlock: Function }} self
+ * @returns {object | Promise<object>}
+ */
+function finish(parent, wrapper, attrs, self) {
+  const children = collapsibleChildren(wrapper)
+  if (!children.length) {
+    warn(parent, '[accordion]', 'an accordion group with no `[%collapsible]` items in it')
+  }
+
+  const ariaLabel = ariaLabelFor(attrs, wrapper)
+  if (!ariaLabel) {
+    warn(
+      parent,
+      '[accordion]',
+      'an accordion group has no `aria-label=` and no title; give it one — a `role=group` with no accessible name is a strongly-discouraged pattern for screen reader users'
+    )
+  }
+
+  // Shared across every child so native `<details name>` groups them into
+  // one mutually-exclusive set — `null` (and no `name=` patched in below)
+  // leaves every child independent, the DS's own `singleOpen` default.
+  const groupName = 'single-open-option' in attrs ? uniqueId(wrapper, 'accordion-group') : null
+
+  const rendered = children.map((child) => child.convert())
+
+  return chainAll(rendered, (htmls) => {
+    const itemsHtml = htmls
+      .map((html, index) => {
+        if (!groupName) return html
+        if (!DETAILS_OPEN_RX.test(html)) {
+          warn(
+            parent,
+            '[accordion]',
+            'child ' + (index + 1) + " didn't render as a <details>; single-open needs every item to be one"
+          )
+          return html
+        }
+        return html.replace(DETAILS_OPEN_RX, '<details' + attr('name', groupName))
+      })
+      .join('')
+
+    const html =
+      '<div class="docouture-accordion-group" role="group"' +
+      (ariaLabel ? ' aria-label="' + ariaLabel + '"' : '') +
+      '>' +
+      itemsHtml +
+      '</div>'
+    return self.createBlock(parent, 'pass', html, attrs)
+  })
+}
+
+function accordionBlock() {
+  this.named('accordion')
+  this.onContext('open')
+  this.process((parent, reader, attrs) => {
+    // See steps.js's own comment: Opal (2.2) can hand this a bare JS `null`
+    // for a block with no attributes beyond its style, and `createBlock`
+    // crashes on that.
+    attrs = attrs || {}
+    // See steps.js's own comment: a literal JS `null` "source" crashes Opal
+    // (2.2) inside `Block#initialize`'s `.nil_or_empty?()` check.
+    const wrapper = this.createBlock(parent, 'open', '', attrs)
+    // See label-macro.js's own comment on this same pattern.
+    // eslint-disable-next-line @typescript-eslint/no-this-alias
+    const self = this
+    // See async-compat.js's own header comment: parseContent is sync under
+    // 2.2 (Opal, real Antora builds) and Promise-returning under 4.0 (the
+    // ui-bundle preview harness) — chain() handles either without making
+    // this function `async` unconditionally. precomputeSubtree is what makes
+    // a `.Title` carrying inline markup (this block's own, or a child
+    // `[%collapsible]`'s) arrive converted rather than raw.
+    return chain(this.parseContent(wrapper, reader.getLines()), () =>
+      chain(precomputeSubtree(wrapper), () => finish(parent, wrapper, attrs, self))
+    )
+  })
+}
+
+module.exports = function registerAccordion(registry) {
+  registry.block(accordionBlock)
+}
+module.exports.accordionBlock = accordionBlock