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

package/lib/tabs.js

@@ -0,0 +1,263 @@
+'use strict'
+
+const { chain, chainAll, precomputeSubtree } = require('./async-compat')
+const { escapeHtml, attr } = require('./html')
+const uniqueId = require('./unique-id')
+const warn = require('./warn')
+
+// Content tabs — GH-45. IDS Tabs (`Kind=Underlined`, Figma 2735:69397 for
+// light, 2735:69401 for dark), used for the one real case the migration
+// found: `main/quickstart.adoc`'s package-manager command blocks
+// (`code/tools/fumadocs-migrate`'s README, "Degraded" section). Both frames
+// are the same component with only the ink swapped (`#000000` / `#FFFFFF`,
+// which is `--ids-color-content-default` in each theme) — dark costs
+// tabs.css nothing, same reasoning as card-grid.js's own header.
+//
+// Not to be confused with `feature-tabs.js` (GH-22, the landing's "Key
+// features" switcher): that block's slides are a fixed composition — media,
+// prose, one call to action, in the design's own order regardless of
+// authoring order. A tab here is arbitrary CONTENT — prose, tables, images,
+// admonitions, titled blocks, a nested `[cards]` — so this holds authored
+// blocks in authored order and never re-sorts anything.
+//
+// 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, for the opposite reason
+// accordion.js gives for the same choice: the real use site nests this
+// INSIDE `[steps]`'s own `====`, and if `[tabs]` were also an example block,
+// that nesting would force it to `=====` (one more `=`) — easy to get wrong
+// and a pattern with no precedent anywhere in this corpus. An open block's
+// delimiter never collides with the enclosing `====`, so `[tabs]` reads the
+// same whether it sits at a page's top level or inside a step.
+//
+// Each child is `[tab,label="…"]` on its OWN SIDEBAR block (`****`), not an
+// example block and not title-grouped the way `[steps]` groups its
+// children. Two reasons, not one:
+//
+//   - a tab can hold prose, tables, a titled source block, even another
+//     titled block entirely, and title-grouping (steps.js's own
+//     `groupBySteps`) would silently start a new tab at the first titled
+//     child it found. An explicit per-tab delimiter has no such trap.
+//   - it CANNOT be `====` either, despite `[tabs]` itself being an open
+//     block: AsciiDoc's delimited-block matching is a plain stack keyed on
+//     the exact delimiter string, with no regard for what sits between two
+//     fences of the same kind. A `[tab]` example block nested inside
+//     `[tabs]`'s `--`, itself nested inside `[steps]`'s `====`, closes the
+//     OUTER `[steps]` block the instant Asciidoctor meets the tab's own
+//     closing `====` — verified empirically (the outer step's remaining
+//     content and the whole rest of the page fell out of the timeline and
+//     rendered as a bare, un-stepped `====` example instead). `****` never
+//     collides with `====` at any nesting depth, which is the only property
+//     that matters here.
+//
+// One more line per tab than an example block would need, in exchange for
+// never having to reason about ambient nesting depth:
+//
+//   [tabs]
+//   --
+//   [tab,label="pnpm"]
+//   ****
+//   [source,bash]
+//   ----
+//   pnpm create weave-backend-app
+//   ----
+//   ****
+//
+//   [tab,label="npm"]
+//   ****
+//   [source,bash]
+//   ----
+//   npm create weave-backend-app
+//   ----
+//   ****
+//   --
+//
+// `label=` is required on every tab — a block style attribute, not a
+// `.Title` (unlike `[card]`/`[feature]`, whose titles are already-converted
+// links or headings the label reuses): a tab's label is never itself
+// content, and reading it off a `.Title` line would make an author's first
+// line of prose double as the tab strip by accident. A `[tabs]` with fewer
+// than two `[tab]` children is a build-fatal warning — a single tab is not a
+// choice.
+//
+// Every `[tabs]` block is independent. There is no cross-block linking (no
+// `sync=`, nothing shared in `localStorage`): an earlier revision of this
+// file had exactly that, and it was wrong on two counts — picking a tab in
+// one block is not supposed to change an unrelated block elsewhere on the
+// page, full stop, and the mechanism used to make GROUPS switch together
+// (real `<a href="#panel-id">` tabs) collided with
+// `ui-bundle/src/js/03-fragment-jumper.ts`, which globally rewrites
+// `window.location.hash` for every `a[href^="#"]` on the page regardless of
+// this file's own `click` handler and its `preventDefault()`. Two problems,
+// one fix: tabs are BUTTONS now (see below), and every block only ever
+// touches its own DOM.
+//
+// WHAT THIS EMITS
+//
+// One `<button type="button">` per tab (never an anchor — see above),
+// `role=tab`/`aria-selected`/`aria-controls` set here directly rather than
+// layered on by script: unlike `feature-tabs.js`, there is no readable
+// "plain document" state this degrades to first — exactly one panel is
+// ever visible (`ui-bundle/src/js/11-tabs.ts` only handles switching which
+// one, never whether more than one shows), so the tab semantics are true
+// from the first paint, script or not. A reader without JavaScript sees the
+// first tab's content and a strip of inert (but clearly labelled) buttons —
+// a real limitation of a widget that fundamentally requires script to
+// switch state, same trade-off any tab component makes.
+//
+// CASE SENSITIVITY (GH-45's own requirement)
+//
+// Labels render in the author's own case — tabs.css does not force
+// uppercase (a deliberate deviation from the Figma text styles it is
+// otherwise built from; see that file's header) — and are matched
+// CASE-SENSITIVELY everywhere: `data-tab-value` and the ARIA relationships
+// this file builds both use the author's label byte for byte, and an exact
+// duplicate or a same-except-case pair (`"pnpm"` vs `"Pnpm"`) both warn,
+// since two tabs that differ only by case are almost always a typo rather
+// than an intentional pair.
+
+/**
+ * An Asciidoctor block, in whichever major is running.
+ *
+ * @typedef {import('@asciidoctor/core').AbstractBlock} Block
+ */
+
+/**
+ * One tab: its strip button, and its panel.
+ *
+ * @param {Block} block - the `[tab]` sidebar block.
+ * @param {number} index - its position, zero-based.
+ * @param {string} groupId - the unique id shared by every tab/panel pair in this block.
+ * @param {string[]} seenLabels - every raw label rendered so far in this block, for duplicate detection.
+ * @param {Block} parent - the enclosing block, for warnings.
+ * @returns {{ tab: string, panel: string } | Promise<{ tab: string, panel: string }>}
+ */
+function renderTab(block, index, groupId, seenLabels, parent) {
+  // A block style attribute, so raw and unsubstituted — escaped, per
+  // lib/html.js's own table (row "block style attribute").
+  const label = block.getAttribute('label')
+  if (!label) {
+    warn(parent, '[tab]', 'a tab has no `label=`; give it one, e.g. `[tab,label="pnpm"]`')
+    return { tab: '', panel: '' }
+  }
+
+  if (seenLabels.includes(label)) {
+    warn(parent, '[tab,label="' + label + '"]', 'a tab set already has a tab labelled "' + label + '"')
+  } else if (seenLabels.some((seen) => seen.toLowerCase() === label.toLowerCase())) {
+    warn(
+      parent,
+      '[tab,label="' + label + '"]',
+      'a tab set already has a tab labelled "' +
+        seenLabels.find((seen) => seen.toLowerCase() === label.toLowerCase()) +
+        '"; labels are matched case-sensitively, but two that differ only by case are ' +
+        'almost always a typo rather than an intentional pair'
+    )
+  }
+  seenLabels.push(label)
+
+  const tabId = groupId + '-tab-' + (index + 1)
+  const panelId = groupId + '-panel-' + (index + 1)
+  const selected = index === 0
+
+  const bodies = block.getBlocks().map((child) => child.convert())
+
+  return chainAll(bodies, (parts) => {
+    const tab =
+      '<li class="docouture-tabs__item" role="presentation">' +
+      '<button type="button" class="ids-tabs-item docouture-tabs__tab' +
+      (selected ? ' ids-tabs-item--selected' : '') +
+      '"' +
+      attr('id', tabId) +
+      attr('role', 'tab') +
+      attr('aria-selected', String(selected)) +
+      attr('aria-controls', panelId) +
+      attr('tabindex', selected ? '0' : '-1') +
+      attr('data-tab-value', label) +
+      '>' +
+      '<span class="ids-tabs-item__label">' +
+      escapeHtml(label) +
+      '</span>' +
+      '</button>' +
+      '</li>'
+
+    const panel =
+      '<section class="docouture-tabs__panel' +
+      (selected ? ' is-selected' : '') +
+      '"' +
+      attr('id', panelId) +
+      attr('role', 'tabpanel') +
+      attr('aria-labelledby', tabId) +
+      attr('tabindex', '0') +
+      attr('data-tab-value', label) +
+      '>' +
+      parts.join('\n') +
+      '</section>'
+
+    return { tab, panel }
+  })
+}
+
+/**
+ * Assembles the block once every tab has been rendered.
+ *
+ * @param {Block} parent - the block this replaces.
+ * @param {Block} wrapper - the parsed `[tabs]` content.
+ * @param {Record<string, unknown>} attrs - the block's own attributes.
+ * @param {{ createBlock: Function }} self - the block processor.
+ * @returns {object | Promise<object>} the `pass` block carrying the markup.
+ */
+function finish(parent, wrapper, attrs, self) {
+  const tabBlocks = wrapper.getBlocks().filter((block) => block.getStyle() === 'tab')
+  if (tabBlocks.length < 2) {
+    warn(parent, '[tabs]', tabBlocks.length + ' `[tab]` block(s) found; a tab set needs at least two')
+  }
+
+  const groupId = uniqueId(parent, 'tabs')
+  /** @type {string[]} */
+  const seenLabels = []
+  const rendered = tabBlocks.map((block, index) => renderTab(block, index, groupId, seenLabels, parent))
+
+  return chainAll(rendered, (tabs) => {
+    const html =
+      '<div class="docouture-tabs" data-tabs>' +
+      '<ul class="docouture-tabs__list" role="tablist">' +
+      tabs.map((tab) => tab.tab).join('') +
+      '</ul>' +
+      '<div class="docouture-tabs__panels">' +
+      tabs.map((tab) => tab.panel).join('') +
+      '</div>' +
+      '</div>'
+    return self.createBlock(parent, 'pass', html, attrs)
+  })
+}
+
+function tabsBlock() {
+  this.named('tabs')
+  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.
+    return chain(this.parseContent(wrapper, reader.getLines()), () =>
+      chain(precomputeSubtree(wrapper), () => finish(parent, wrapper, attrs, self))
+    )
+  })
+}
+
+module.exports = function registerTabs(registry) {
+  registry.block(tabsBlock)
+}
+module.exports.tabsBlock = tabsBlock

package/lib/unique-id.js

@@ -0,0 +1,78 @@
+'use strict'
+
+// Document-scoped id generation, for blocks that have to wire one element to
+// another through an id — ARIA relationships (`aria-controls`,
+// `aria-labelledby`, `aria-describedby`), `<label for>`, and in-page anchors.
+//
+// Why this cannot be a plain module-level counter: extensions are registered
+// ONCE per process in the ui-bundle preview harness (see index.js's own
+// header comment on the global registration path), and that harness converts
+// every preview page in the same process. A module-level counter would keep
+// climbing across pages, so the same block would get different ids depending
+// on which page happened to be converted first — output that changes with
+// build order rather than with content. Antora's own per-page registry does
+// not have that problem, but the harness does, and the same extension code
+// runs under both.
+//
+// Counting per DOCUMENT instead makes the ids a function of the page's own
+// content and nothing else: page A always produces the same ids whether it is
+// converted first or last. The counter is stashed on the document object,
+// which Asciidoctor discards along with the page.
+//
+// The ids are NOT globally unique across a site, and do not need to be — an
+// id only has to be unique within the page it appears on.
+
+/**
+ * Property name for the per-document counter map. A `$`-prefixed, package-
+ * scoped name, matching the convention index.js already uses for its own
+ * registration guard, so it cannot collide with anything Asciidoctor or Antora
+ * puts on the same object.
+ */
+const COUNTER_KEY = '$docoutureUniqueIdCounters'
+
+/**
+ * Anything with a document behind it: the `parent` handed to a block
+ * processor, or a Document itself.
+ *
+ * @typedef {{ getDocument?: () => object }} DocumentLike
+ */
+
+/**
+ * Resolves the object the counter is stashed on. A block processor receives
+ * `parent`, which is a block, not the document — but two blocks on one page
+ * must share a counter, so the document is what the count has to hang off.
+ *
+ * @param {DocumentLike} node - a block, or a document.
+ * @returns {object} the document, or `node` itself if it has none (a detached
+ *   node, only reachable in tests).
+ */
+function documentOf(node) {
+  return (typeof node.getDocument === 'function' && node.getDocument()) || node
+}
+
+/**
+ * Returns the next id for `prefix` on this node's document.
+ *
+ * ```js
+ * const panelId = uniqueId(parent, 'feature-tabs-panel')   // feature-tabs-panel-1
+ * const labelId = uniqueId(parent, 'feature-tabs-label')   // feature-tabs-label-1
+ * ```
+ *
+ * Each prefix counts independently, so related elements can be paired by
+ * generating both from the same iteration rather than by parsing an id apart.
+ *
+ * @param {DocumentLike} node - the block processor's `parent`, or a document.
+ * @param {string} prefix - a stable, extension-specific prefix. Include the
+ *   block's own name so two extensions on one page cannot collide.
+ * @returns {string} `${prefix}-${n}`, with `n` starting at 1.
+ */
+function uniqueId(node, prefix) {
+  const doc = /** @type {Record<string, Record<string, number>>} */ (documentOf(node))
+  const counters = doc[COUNTER_KEY] || (doc[COUNTER_KEY] = {})
+  const next = (counters[prefix] || 0) + 1
+  counters[prefix] = next
+  return prefix + '-' + next
+}
+
+module.exports = uniqueId
+module.exports.COUNTER_KEY = COUNTER_KEY

package/lib/video-size.js

@@ -0,0 +1,89 @@
+'use strict'
+
+// GH-15 (A9) follow-up: `video::target[youtube,640,360]`'s own `width`/
+// `height` land as plain HTML attributes on the `<iframe>`/`<video>` tag
+// (@asciidoctor/core's html5 converter, convert_video — verified against
+// its own source: `width="${node.getAttribute('width')}"`, no unit, no
+// clamping unlike a table's `width=` percentage). A browser does NOT derive
+// `aspect-ratio` from an iframe's `width`/`height` attributes the way it
+// does for `<img>`, so a CSS `max-width` alone would leave the element's
+// height fixed in pixels regardless of the viewport, distorting the embed
+// at any width narrower than its own attribute. There is no CSS-only fix —
+// `aspect-ratio: attr(width) / attr(height)` is real syntax but Chrome-only
+// (133+) and unsupported everywhere else as of writing — so this moves both
+// numbers into an inline `style` as custom properties doc.css consumes,
+// same mechanism as `table-width.js` + `table-container.js` one file over:
+// a postprocessor scanning the ALREADY-CONVERTED html5 output, since the
+// converter (hard-set by Antora, @antora/asciidoc-loader/lib/load-asciidoc.js)
+// has no passthrough for an arbitrary attribute into an inline style.
+//
+// No separate tree processor needed here, unlike the table case: a table's
+// own `width=` attribute gets CLAMPED by Asciidoctor's Table constructor
+// before a postprocessor ever runs, so table-width.js has to read the RAW
+// value at tree-processor time, before that happens. A video block's
+// `width`/`height` are never touched by any such constructor — `doc`
+// (handed to every postprocessor by @asciidoctor/core) is still fully
+// queryable then, so `doc.findBy({ context: 'video' })` at postprocess time
+// already returns the same un-clamped values a tree processor would.
+//
+// Author-facing effect: `video::x[youtube]` (no size) gets neither custom
+// property, so doc.css's own fallback applies (full width, 16:9).
+// `video::x[youtube,640,360]` caps the block at 640px and locks it to a
+// correct 640:360 ratio at any narrower viewport; `video::x[youtube,640]`
+// (width only) caps the width and leaves the ratio at doc.css's 16:9
+// fallback.
+const VIDEO_OPEN_RX = /<div((?:\s+id="[^"]*")?\s+class="videoblock\b[^"]*")>/g
+const VALID_RX = /^\d+(?:\.\d+)?$/
+
+function parseDimension(raw) {
+  const trimmed = raw == null ? '' : String(raw).trim()
+  return VALID_RX.test(trimmed) ? trimmed : null
+}
+
+function sizeVideos(html, sizes = []) {
+  let result = ''
+  let cursor = 0
+  let match
+  let videoIndex = -1
+  while ((match = VIDEO_OPEN_RX.exec(html))) {
+    videoIndex += 1
+    const size = sizes[videoIndex]
+    if (!size || (!size.width && !size.height)) continue
+
+    const declarations = []
+    if (size.width) declarations.push(`--video-max-width:${size.width}px`)
+    if (size.width && size.height) {
+      declarations.push(`--video-aspect-ratio:${size.width}/${size.height}`)
+    }
+    if (!declarations.length) continue
+
+    result += html.slice(cursor, match.index)
+    // Capture group 1 is not optional in VIDEO_OPEN_RX, so a match always
+    // carries it — but `noUncheckedIndexedAccess` types every group past 0 as
+    // possibly undefined, since it cannot know that. Cast rather than add a
+    // runtime guard for a branch that cannot be reached.
+    const attrs = /** @type {string} */ (match[1])
+    const styledAttrs = /\sstyle="/.test(attrs)
+      ? attrs.replace(/\sstyle="/, ` style="${declarations.join(';')};`)
+      : `${attrs} style="${declarations.join(';')}"`
+    result += `<div${styledAttrs}>`
+    cursor = match.index + match[0].length
+    VIDEO_OPEN_RX.lastIndex = cursor
+  }
+  result += html.slice(cursor)
+  return result
+}
+
+module.exports = function registerVideoSize(registry) {
+  registry.postprocessor(function () {
+    this.process(function (doc, output) {
+      const sizes = doc.findBy({ context: 'video' }).map((video) => ({
+        width: parseDimension(video.getAttribute('width')),
+        height: parseDimension(video.getAttribute('height')),
+      }))
+      return sizeVideos(output, sizes)
+    })
+  })
+}
+
+module.exports.sizeVideos = sizeVideos

package/lib/warn.js

@@ -0,0 +1,75 @@
+'use strict'
+
+// Reporting an authoring mistake.
+//
+// Both site playbooks set `runtime.log.failure_level: warn`, so a warning
+// logged here does not merely print — it FAILS THE BUILD. That is the intended
+// severity for this package: an unknown IDS Label colour, a `[cards]` block
+// with no cards in it, a tab set with no panels. Each of those renders as
+// something plausible-looking but wrong (unstyled markup, an empty region, a
+// silently dropped section), and a documentation site that ships those is worse
+// than one that fails to build.
+//
+// So the choice this helper encodes is: authoring mistakes are warnings,
+// because warnings are fatal here. Anything that should NOT stop a build does
+// not belong at this level.
+//
+// It exists mostly to get the logger lookup right in one place. Reaching the
+// logger means walking `node -> document -> logger`, and the node an extension
+// holds varies by extension point — a block processor's `parent`, a
+// postprocessor's `doc`. Getting that wrong throws a TypeError from inside the
+// extension, which surfaces as an opaque conversion failure rather than as the
+// authoring error it was trying to report.
+
+/**
+ * Anything a warning can be raised from: the `parent` handed to a block or
+ * macro processor, or a Document.
+ *
+ * @typedef {{ getDocument?: () => { getLogger?: () => Logger }, getLogger?: () => Logger }} WarnSource
+ */
+
+/**
+ * The subset of the Asciidoctor logger this uses. Typed structurally rather
+ * than imported from `@asciidoctor/core`, because the object at runtime comes
+ * from 2.2 under Antora and 4.0 under the preview harness.
+ *
+ * @typedef {{ warn: (message: string) => void }} Logger
+ */
+
+/**
+ * Logs a warning against the document, failing the build under both site
+ * playbooks' `failure_level: warn`.
+ *
+ * ```js
+ * warn(parent, 'label:' + target + '[]', 'unknown IDS Label variant "' + variant + '"', VARIANTS)
+ * // → label:mauve[] — unknown IDS Label variant "mauve"; expected one of white, grey, ...
+ * ```
+ *
+ * The message is assembled here so every extension reports in the same shape:
+ * what the author wrote, what is wrong with it, and — when there is a closed
+ * set — what was expected instead. The author gets told how to fix it, not just
+ * that something is broken.
+ *
+ * A missing logger is tolerated silently. Asciidoctor always provides one in
+ * both majors; a detached node constructed in a test may not, and losing a
+ * warning is a better failure mode there than masking the real assertion with a
+ * TypeError.
+ *
+ * @param {WarnSource} node - the block processor's `parent`, or a document.
+ * @param {string} source - what the author wrote, verbatim enough to find:
+ *   `label:mauve[]`, `[cards]`, `cta::[]`.
+ * @param {string} problem - what is wrong, in lower case, no trailing period.
+ * @param {readonly string[]} [expected] - the permitted values, when the
+ *   mistake is a value outside a closed set. Appended as
+ *   `; expected one of a, b, c`.
+ * @returns {void}
+ */
+function warn(node, source, problem, expected) {
+  const doc = (typeof node.getDocument === 'function' && node.getDocument()) || node
+  const logger = typeof doc.getLogger === 'function' ? doc.getLogger() : undefined
+  if (!logger || typeof logger.warn !== 'function') return
+  const suffix = expected && expected.length ? '; expected one of ' + expected.join(', ') : ''
+  logger.warn(source + ' — ' + problem + suffix)
+}
+
+module.exports = warn

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@inditextech/docouture-asciidoc-extensions",
+  "version": "0.1.0-SNAPSHOT.40.1",
+  "description": "Asciidoctor extensions shared by docouture documentation sites — authored content that has no AsciiDoc equivalent, rendered as IOP DS markup",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/InditexTech/test-antoradocs.git",
+    "directory": "code/packages/asciidoc-extensions"
+  },
+  "license": "MPL-2.0",
+  "main": "index.js",
+  "files": [
+    "index.js",
+    "lib",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "devDependencies": {
+    "@asciidoctor/core": "~4.0.8",
+    "typescript": "6.0.3"
+  },
+  "dependencies": {
+    "asciidoctor-core-2.2": "npm:@asciidoctor/core@~2.2",
+    "shiki": "~4.4.0"
+  },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix"
+  }
+}