@inditextech/docouture-asciidoc-extensions 1.0.0 → 1.1.0

package/lib/accordion.js

@@ -122,7 +122,7 @@ function hasOption(node, name) {
  * @returns {string} the same text, safe inside `"…"`.
  */
 function escapeConvertedAttribute(html) {
-  return html.replace(/"/g, '"')
+  return html.replaceAll('"', '"')
 }
 
 /**

package/lib/accordion.spec.js

@@ -0,0 +1,124 @@
+// SPDX-FileCopyrightText: 2026 INDUSTRIA DE DISEÑO TEXTIL S.A. (INDITEX S.A.)
+//
+// SPDX-License-Identifier: Apache-2.0
+
+'use strict'
+
+import { afterEach, describe, expect, it } from 'vitest'
+
+const asciidoctor = require('@asciidoctor/core')
+const registerAccordion = require('./accordion')
+
+/**
+ * @param {string} source
+ * @param {{ logger?: { warn: (message: string) => void } }} [options]
+ * @returns {Promise<string>}
+ */
+function convert(source, { logger } = {}) {
+  const registry = asciidoctor.Extensions.create()
+  registerAccordion(registry)
+  if (logger) asciidoctor.LoggerManager.setLogger(logger)
+  return /** @type {Promise<string>} */ (asciidoctor.convert(source, { extension_registry: registry, safe: 'safe' }))
+}
+
+describe('accordion block', () => {
+  afterEach(() => {
+    asciidoctor.LoggerManager.setLogger(asciidoctor.MemoryLogger.create())
+  })
+
+  it('wraps every [%collapsible] child in a role=group with the given aria-label', async () => {
+    const html = await convert(`[accordion,aria-label="Frequently asked questions"]
+--
+.Question one
+[%collapsible]
+====
+Answer one.
+====
+
+.Question two
+[%collapsible]
+====
+Answer two.
+====
+--
+`)
+    expect(html).toContain('role="group" aria-label="Frequently asked questions"')
+    expect(html).toContain('Question one')
+    expect(html).toContain('Question two')
+    // Independent mode by default — no shared `name=` attribute.
+    expect(html).not.toContain('name=')
+  })
+
+  it('escapes a quote inside an authored aria-label', async () => {
+    const html = await convert(`[accordion,aria-label="Say \\"hi\\""]
+--
+.Q
+[%collapsible]
+====
+A.
+====
+--
+`)
+    expect(html).toContain('aria-label="Say &quot;hi&quot;"')
+  })
+
+  it('single-open shares one native <details name> across every child', async () => {
+    const html = await convert(`[accordion%single-open,aria-label="FAQ"]
+--
+.Q1
+[%collapsible]
+====
+A1.
+====
+
+.Q2
+[%collapsible]
+====
+A2.
+====
+--
+`)
+    const names = [...html.matchAll(/<details name="([^"]+)"/g)].map((m) => m[1])
+    expect(names).toHaveLength(2)
+    expect(names[0]).toBe(names[1])
+  })
+
+  it('warns when a group has no [%collapsible] items in it', async () => {
+    const logger = asciidoctor.MemoryLogger.create()
+    const html = await convert(
+      `[accordion,aria-label="Empty"]
+--
+Just a stray paragraph.
+--
+`,
+      { logger }
+    )
+    expect(html).toContain('docouture-accordion-group')
+    const messages = logger
+      .getMessages()
+      .map((m) => m.getText())
+      .join('\n')
+    expect(messages).toContain('an accordion group with no `[%collapsible]` items in it')
+  })
+
+  it('warns when a group has no aria-label and no title', async () => {
+    const logger = asciidoctor.MemoryLogger.create()
+    await convert(
+      `[accordion]
+--
+.Q
+[%collapsible]
+====
+A.
+====
+--
+`,
+      { logger }
+    )
+    const messages = logger
+      .getMessages()
+      .map((m) => m.getText())
+      .join('\n')
+    expect(messages).toContain('has no `aria-label=` and no title')
+  })
+})

package/lib/cta.js

@@ -174,14 +174,10 @@ function renderMark(lightHtml, darkHtml) {
   const dark = darkHtml ? (IMG_RX.exec(darkHtml) || [])[0] : ''
   if (!light && !dark) return ''
   const themed = light && dark
+  const lightModifierClass = themed ? ' docouture-cta__mark-image--light' : ''
   return (
     '<div class="docouture-cta__mark">' +
-    (light
-      ? light.replace(
-          '<img',
-          '<img class="docouture-cta__mark-image' + (themed ? ' docouture-cta__mark-image--light' : '') + '"'
-        )
-      : '') +
+    (light ? light.replace('<img', '<img class="docouture-cta__mark-image' + lightModifierClass + '"') : '') +
     (dark ? dark.replace('<img', '<img class="docouture-cta__mark-image docouture-cta__mark-image--dark"') : '') +
     '</div>'
   )

package/lib/cta.spec.js

@@ -0,0 +1,182 @@
+// SPDX-FileCopyrightText: 2026 INDUSTRIA DE DISEÑO TEXTIL S.A. (INDITEX S.A.)
+//
+// SPDX-License-Identifier: Apache-2.0
+
+'use strict'
+
+import { afterEach, describe, expect, it } from 'vitest'
+
+// @asciidoctor/core 4.0's `convert` is Promise-returning (this package's own
+// async-compat.js header explains why); asciidoctor-core-2.2 is what real
+// Antora builds actually use and converts synchronously. Both run
+// registerCta identically — 4.0 here since it is this package's own
+// devDependency and its registry.create()/Extensions API needs no special
+// alias (see cta.js's own comment on the 2.2/4.0 split for why 2.2 must be
+// required under an alias elsewhere in this package).
+const asciidoctor = require('@asciidoctor/core')
+const registerCta = require('./cta')
+
+/**
+ * @param {string} source
+ * @param {{ logger?: { warn: (message: string) => void } }} [options]
+ * @returns {Promise<string>}
+ */
+function convert(source, { logger } = {}) {
+  const registry = asciidoctor.Extensions.create()
+  registerCta(registry)
+  if (logger) asciidoctor.LoggerManager.setLogger(logger)
+  return /** @type {Promise<string>} */ (asciidoctor.convert(source, { extension_registry: registry, safe: 'safe' }))
+}
+
+describe('cta block', () => {
+  afterEach(() => {
+    asciidoctor.LoggerManager.setLogger(asciidoctor.MemoryLogger.create())
+  })
+
+  it('renders a themed mark (light + dark), title, lead, primary and secondary actions', async () => {
+    const html = await convert(`[cta,title="Get started",align=start]
+====
+image::mark.svg[Mark]
+image::mark-dark.svg[role=dark]
+
+Actively maintained and open source.
+
+[.primary]
+https://github.com/InditexTech/docouture[Fork it]
+
+[.secondary]
+https://example.com/docs[Read the docs]
+====
+`)
+    expect(html).toContain('docouture-cta--start')
+    expect(html).toContain('<h2 class="docouture-cta__title discrete dt-text--title-l">Get started</h2>')
+    expect(html).toContain('docouture-cta__mark-image--light')
+    expect(html).toContain('docouture-cta__mark-image--dark')
+    // GitHub targets get the brand icon; a plain https link does not.
+    expect(html).toContain('docouture-cta__action-icon--github')
+    expect(html).toContain('dt-button--secondary docouture-cta__action" href="https://example.com/docs"')
+  })
+
+  it('defaults to center alignment and renders an untethed single mark image with no --light modifier', async () => {
+    const html = await convert(`[cta]
+====
+image::mark.svg[Mark]
+
+Some lead text.
+
+[.primary]
+https://example.com[Go]
+====
+`)
+    expect(html).toContain('docouture-cta--center')
+    // themed is false (only a light image) so no --light modifier is added.
+    expect(html).toContain('<img class="docouture-cta__mark-image" src="mark.svg" alt="Mark">')
+  })
+
+  it('warns and falls back to the default alignment for an unknown align value', async () => {
+    const logger = asciidoctor.MemoryLogger.create()
+    const html = await convert(
+      `[cta,align=bogus]
+====
+Lead only.
+
+[.primary]
+https://example.com[Go]
+====
+`,
+      { logger }
+    )
+    expect(html).toContain('docouture-cta--center')
+    expect(
+      logger
+        .getMessages()
+        .map((m) => m.getText())
+        .join('\n')
+    ).toContain('unknown alignment "bogus"')
+  })
+
+  it('warns when there is no [.primary] action', async () => {
+    const logger = asciidoctor.MemoryLogger.create()
+    await convert(
+      `[cta]
+====
+Lead only, no actions.
+====
+`,
+      { logger }
+    )
+    expect(
+      logger
+        .getMessages()
+        .map((m) => m.getText())
+        .join('\n')
+    ).toContain('a cta has no `[.primary]` action')
+  })
+
+  it('warns when a [.secondary] action is present without a [.primary] one', async () => {
+    const logger = asciidoctor.MemoryLogger.create()
+    await convert(
+      `[cta]
+====
+Lead.
+
+[.secondary]
+https://example.com[Only secondary]
+====
+`,
+      { logger }
+    )
+    const messages = logger
+      .getMessages()
+      .map((m) => m.getText())
+      .join('\n')
+    expect(messages).toContain('a cta has a `[.secondary]` action but no `[.primary]` one')
+  })
+
+  it('warns and renders nothing for an action paragraph carrying no link', async () => {
+    const logger = asciidoctor.MemoryLogger.create()
+    const html = await convert(
+      `[cta]
+====
+Lead.
+
+[.primary]
+Just plain text, no link.
+====
+`,
+      { logger }
+    )
+    // The paragraph converted fine, but renderAction found no anchor in it,
+    // so the actions wrapper renders empty rather than a real button.
+    expect(html).not.toContain('dt-button--primary')
+    const messages = logger
+      .getMessages()
+      .map((m) => m.getText())
+      .join('\n')
+    expect(messages).toContain('a cta action carries no link')
+  })
+
+  it('warns about a non-paragraph body block', async () => {
+    const logger = asciidoctor.MemoryLogger.create()
+    await convert(
+      `[cta]
+=====
+Lead paragraph.
+
+======
+Nested example block, not a paragraph.
+======
+
+[.primary]
+https://example.com[Go]
+=====
+`,
+      { logger }
+    )
+    const messages = logger
+      .getMessages()
+      .map((m) => m.getText())
+      .join('\n')
+    expect(messages).toContain('a cta body holds a')
+  })
+})

package/lib/feature-tabs.js

@@ -193,14 +193,10 @@ function renderMedia(lightHtml, darkHtml) {
   const dark = darkHtml ? (IMG_RX.exec(darkHtml) || [])[0] : ''
   if (!light && !dark) return ''
   const themed = light && dark
+  const lightModifierClass = themed ? ' docouture-feature-tabs__image--light' : ''
   return (
     '<div class="docouture-feature-tabs__media">' +
-    (light
-      ? light.replace(
-          '<img',
-          '<img class="docouture-feature-tabs__image' + (themed ? ' docouture-feature-tabs__image--light' : '') + '"'
-        )
-      : '') +
+    (light ? light.replace('<img', '<img class="docouture-feature-tabs__image' + lightModifierClass + '"') : '') +
     (dark
       ? dark.replace('<img', '<img class="docouture-feature-tabs__image docouture-feature-tabs__image--dark"')
       : '') +
@@ -305,11 +301,12 @@ function renderFeature(block, index, parent) {
       '</a>' +
       '</li>'
 
+    const headingModifierClass = label ? '' : ' docouture-feature-tabs__heading--redundant'
     const heading = title
       ? '<h3 class="docouture-feature-tabs__heading' +
         // No explicit label means the heading and the tab say the same thing, so
         // the enhanced state hides the heading rather than printing it twice.
-        (label ? '' : ' docouture-feature-tabs__heading--redundant') +
+        headingModifierClass +
         '"' +
         attr('id', headingId) +
         '>' +

package/lib/feature-tabs.spec.js

@@ -0,0 +1,178 @@
+// SPDX-FileCopyrightText: 2026 INDUSTRIA DE DISEÑO TEXTIL S.A. (INDITEX S.A.)
+//
+// SPDX-License-Identifier: Apache-2.0
+
+'use strict'
+
+import { afterEach, describe, expect, it } from 'vitest'
+
+const asciidoctor = require('@asciidoctor/core')
+const registerFeatureTabs = require('./feature-tabs')
+
+/**
+ * @param {string} source
+ * @param {{ logger?: { warn: (message: string) => void } }} [options]
+ * @returns {Promise<string>}
+ */
+function convert(source, { logger } = {}) {
+  const registry = asciidoctor.Extensions.create()
+  registerFeatureTabs(registry)
+  if (logger) asciidoctor.LoggerManager.setLogger(logger)
+  return /** @type {Promise<string>} */ (asciidoctor.convert(source, { extension_registry: registry, safe: 'safe' }))
+}
+
+describe('feature-tabs block', () => {
+  afterEach(() => {
+    asciidoctor.LoggerManager.setLogger(asciidoctor.MemoryLogger.create())
+  })
+
+  it('renders a slide with both title and label, a themed media pair and an external cta', async () => {
+    const html = await convert(`[feature-tabs]
+====
+[feature,label="UI-agnostic"]
+.Integrates with any UI framework
+--
+image::feature-1.png[Alt text]
+image::feature-1-dark.png[role=dark]
+
+Change the UI using our included primitives.
+
+[.cta]
+https://example.com/learn-more[Learn more]
+--
+====
+`)
+    expect(html).toContain('data-feature-tabs')
+    expect(html).toContain('dt-tabs-item--selected')
+    expect(html).toContain('>UI-agnostic</a>')
+    expect(html).toContain('docouture-feature-tabs__heading" id=')
+    expect(html).toContain('Integrates with any UI framework</h3>')
+    expect(html).toContain('docouture-feature-tabs__image--light')
+    expect(html).toContain('docouture-feature-tabs__image--dark')
+    // An absolute https target gets the external-link icon on the CTA.
+    expect(html).toContain('dt-icon-mask--external-link')
+  })
+
+  it('title-only slide: the tab uses the title, and the heading is marked redundant', async () => {
+    const html = await convert(`[feature-tabs]
+====
+[feature]
+.Title-only slide
+--
+image::feature-2.png[Alt]
+--
+====
+`)
+    expect(html).toContain('>Title-only slide</a>')
+    expect(html).toContain('docouture-feature-tabs__heading--redundant')
+  })
+
+  it('an internal (same-site) cta target gets no external-link icon', async () => {
+    const html = await convert(`[feature-tabs]
+====
+[feature,label="Internal"]
+--
+image::feature-3.png[Alt]
+
+[.cta]
+xref:main:quickstart.adoc[Learn more]
+--
+====
+`)
+    expect(html).not.toContain('dt-icon-mask--external-link')
+  })
+
+  it('warns when a feature-tabs block has no [feature] slides at all', async () => {
+    const logger = asciidoctor.MemoryLogger.create()
+    await convert(
+      `[feature-tabs]
+====
+Just a stray paragraph, no [feature] style.
+====
+`,
+      { logger }
+    )
+    const messages = logger
+      .getMessages()
+      .map((m) => m.getText())
+      .join('\n')
+    expect(messages).toContain('a feature-tabs block with no `[feature]` in it')
+  })
+
+  it('warns when a slide has neither a title nor a label', async () => {
+    const logger = asciidoctor.MemoryLogger.create()
+    const html = await convert(
+      `[feature-tabs]
+====
+[feature]
+--
+image::feature-4.png[Alt]
+--
+====
+`,
+      { logger }
+    )
+    // renderFeature returns { tab: '', panel: '' } for the unlabelled slide.
+    expect(html).toContain('<ul class="docouture-feature-tabs__list"></ul>')
+    const messages = logger
+      .getMessages()
+      .map((m) => m.getText())
+      .join('\n')
+    expect(messages).toContain('a slide has no label')
+  })
+
+  it('warns when a slide has no image at all', async () => {
+    const logger = asciidoctor.MemoryLogger.create()
+    await convert(
+      `[feature-tabs]
+====
+[feature,label="No image"]
+--
+Prose only, no image::.
+--
+====
+`,
+      { logger }
+    )
+    const messages = logger
+      .getMessages()
+      .map((m) => m.getText())
+      .join('\n')
+    expect(messages).toContain('a slide has no `image::` of its own')
+  })
+
+  it('warns and renders nothing for a cta paragraph carrying no link', async () => {
+    const logger = asciidoctor.MemoryLogger.create()
+    const html = await convert(
+      `[feature-tabs]
+====
+[feature,label="Broken cta"]
+--
+image::feature-5.png[Alt]
+
+[.cta]
+Just text, no link.
+--
+====
+`,
+      { logger }
+    )
+    expect(html).not.toContain('docouture-feature-tabs__cta"')
+    const messages = logger
+      .getMessages()
+      .map((m) => m.getText())
+      .join('\n')
+    expect(messages).toContain("a slide's call to action carries no link")
+  })
+
+  it('accepts a bare-paragraph [feature] slide (not an open block)', async () => {
+    const html = await convert(`[feature-tabs]
+====
+[feature,label="Prose slide"]
+Just a paragraph, no open block at all.
+====
+`)
+    expect(html).toContain('>Prose slide</a>')
+    expect(html).toContain('Just a paragraph, no open block at all.')
+  })
+})

package/lib/kroki-config.js

@@ -260,7 +260,7 @@ function resolveFormat(type, requestedFormat, onUnsupported) {
   if (requestedFormat == null || requestedFormat === '' || requestedFormat === DEFAULT_FORMAT) return DEFAULT_FORMAT
   const normalized = String(requestedFormat === JPG_ALIAS ? 'jpeg' : requestedFormat)
   const accepted = FORMAT_SUPPORT[type]
-  if (accepted && accepted.includes(normalized))
+  if (accepted?.includes(normalized))
     return /** @type {'svg' | 'png' | 'jpeg' | 'pdf' | 'base64' | 'txt' | 'atxt' | 'utxt'} */ (normalized)
   if (onUnsupported) onUnsupported(type, String(requestedFormat))
   return DEFAULT_FORMAT

package/lib/kroki-config.spec.js

@@ -0,0 +1,196 @@
+// SPDX-FileCopyrightText: 2026 INDUSTRIA DE DISEÑO TEXTIL S.A. (INDITEX S.A.)
+//
+// SPDX-License-Identifier: Apache-2.0
+
+'use strict'
+
+import { describe, expect, it } from 'vitest'
+const {
+  KROKI_URL,
+  SUPPORTED_TYPES,
+  PNG_SUPPORTED_TYPES,
+  FORMAT_SUPPORT,
+  TEXT_FORMATS,
+  DEFAULT_FORMAT,
+  ENABLED_ATTR,
+  TYPES_ATTR,
+  BUILTIN_ATTRIBUTES,
+  isTruthy,
+  resolveEnabledTypes,
+  resolveFormat,
+  isTextFormat,
+  isPositionalOrOptionKey,
+  resolveDiagramOptions,
+} = require('./kroki-config')
+
+describe('constants', () => {
+  it('exposes the fixed loopback Kroki URL', () => {
+    expect(KROKI_URL).toBe('http://localhost:8500')
+  })
+
+  it('exposes the attribute names both halves of Kroki support agree on', () => {
+    expect(ENABLED_ATTR).toBe('kroki-enabled')
+    expect(TYPES_ATTR).toBe('kroki-diagram-types')
+  })
+
+  it('exposes svg as the default format', () => {
+    expect(DEFAULT_FORMAT).toBe('svg')
+  })
+
+  it('derives PNG_SUPPORTED_TYPES from FORMAT_SUPPORT', () => {
+    for (const type of PNG_SUPPORTED_TYPES) {
+      expect(FORMAT_SUPPORT[type]).toContain('png')
+    }
+    for (const type of SUPPORTED_TYPES) {
+      if (FORMAT_SUPPORT[type].includes('png')) {
+        expect(PNG_SUPPORTED_TYPES.has(type)).toBe(true)
+      }
+    }
+  })
+
+  it('every SUPPORTED_TYPES entry has a FORMAT_SUPPORT row', () => {
+    for (const type of SUPPORTED_TYPES) {
+      expect(Array.isArray(FORMAT_SUPPORT[type])).toBe(true)
+      expect(FORMAT_SUPPORT[type]).toContain('svg')
+    }
+  })
+})
+
+describe('isTruthy', () => {
+  it('treats the real boolean true as truthy', () => {
+    expect(isTruthy(true)).toBe(true)
+  })
+
+  it('treats the string "true" as truthy', () => {
+    expect(isTruthy('true')).toBe(true)
+  })
+
+  it.each([false, 'false', undefined, null, '', 0, 'yes'])('treats %s as not truthy', (value) => {
+    expect(isTruthy(value)).toBe(false)
+  })
+})
+
+describe('resolveEnabledTypes', () => {
+  it('returns an empty set when kroki-enabled is not truthy', () => {
+    const onUnknownType = () => {
+      throw new Error('should not be called')
+    }
+    expect(resolveEnabledTypes(false, 'mermaid', onUnknownType).size).toBe(0)
+    expect(resolveEnabledTypes(undefined, 'mermaid', onUnknownType).size).toBe(0)
+  })
+
+  it('returns every supported type when types are omitted', () => {
+    const active = resolveEnabledTypes(true, undefined)
+    expect(active.size).toBe(SUPPORTED_TYPES.length)
+    expect(active.has('mermaid')).toBe(true)
+  })
+
+  it('returns every supported type when types is an empty string', () => {
+    const active = resolveEnabledTypes('true', '')
+    expect(active.size).toBe(SUPPORTED_TYPES.length)
+  })
+
+  it('parses a comma-separated, whitespace-tolerant list of requested types', () => {
+    const active = resolveEnabledTypes(true, ' mermaid, plantuml ,graphviz')
+    expect([...active].sort()).toEqual(['graphviz', 'mermaid', 'plantuml'])
+  })
+
+  it('reports each unknown type through onUnknownType and drops it', () => {
+    const unknown = []
+    const active = resolveEnabledTypes(true, 'mermaid,bogus,plantuml', (type) => unknown.push(type))
+    expect(unknown).toEqual(['bogus'])
+    expect([...active].sort()).toEqual(['mermaid', 'plantuml'])
+  })
+
+  it('does not call onUnknownType when typesAttr is omitted', () => {
+    const onUnknownType = () => {
+      throw new Error('should not be called when "all types" is meant')
+    }
+    expect(() => resolveEnabledTypes(true, undefined, onUnknownType)).not.toThrow()
+  })
+})
+
+describe('resolveFormat', () => {
+  it('resolves the default format when the requested format is absent', () => {
+    expect(resolveFormat('mermaid', undefined)).toBe('svg')
+    expect(resolveFormat('mermaid', '')).toBe('svg')
+    expect(resolveFormat('mermaid', 'svg')).toBe('svg')
+  })
+
+  it('resolves a supported non-default format', () => {
+    expect(resolveFormat('mermaid', 'png')).toBe('png')
+    expect(resolveFormat('plantuml', 'txt')).toBe('txt')
+  })
+
+  it('normalizes the jpg alias to jpeg for a type that supports it', () => {
+    expect(resolveFormat('graphviz', 'jpg')).toBe('jpeg')
+  })
+
+  it('falls back to svg and reports via onUnsupported for an unsupported format', () => {
+    const reported = []
+    const format = resolveFormat('mermaid', 'jpeg', (type, requested) => reported.push([type, requested]))
+    expect(format).toBe('svg')
+    expect(reported).toEqual([['mermaid', 'jpeg']])
+  })
+
+  it('falls back to svg for an entirely unrecognized format string', () => {
+    expect(resolveFormat('mermaid', 'bogus')).toBe('svg')
+  })
+})
+
+describe('isTextFormat', () => {
+  it('recognizes every TEXT_FORMATS entry', () => {
+    for (const format of TEXT_FORMATS) {
+      expect(isTextFormat(format)).toBe(true)
+    }
+  })
+
+  it('does not treat svg/png as text formats', () => {
+    expect(isTextFormat('svg')).toBe(false)
+    expect(isTextFormat('png')).toBe(false)
+  })
+})
+
+describe('isPositionalOrOptionKey', () => {
+  it('recognizes a bare numeric index', () => {
+    expect(isPositionalOrOptionKey('1')).toBe(true)
+    expect(isPositionalOrOptionKey('42')).toBe(true)
+  })
+
+  it('recognizes an -option flag key', () => {
+    expect(isPositionalOrOptionKey('collapsible-option')).toBe(true)
+  })
+
+  it('does not flag an ordinary named attribute', () => {
+    expect(isPositionalOrOptionKey('theme')).toBe(false)
+    expect(isPositionalOrOptionKey('view-key')).toBe(false)
+  })
+})
+
+describe('resolveDiagramOptions', () => {
+  it('forwards only the non-builtin named attributes, coerced to strings', () => {
+    const attrs = {
+      target: 'diagram.puml',
+      format: 'svg',
+      theme: 'hacker',
+      'view-key': 'SystemContext',
+      1: 'mermaid',
+      'collapsible-option': '',
+    }
+    expect(resolveDiagramOptions(attrs)).toEqual({ theme: 'hacker', 'view-key': 'SystemContext' })
+  })
+
+  it('excludes every BUILTIN_ATTRIBUTES entry', () => {
+    /** @type {Record<string, string>} */
+    const attrs = {}
+    for (const key of BUILTIN_ATTRIBUTES) attrs[key] = 'x'
+    expect(resolveDiagramOptions(attrs)).toEqual({})
+  })
+
+  it('returns an empty object for no attributes at all', () => {
+    // Real callers always pass an object; this only proves the `attrs || {}`
+    // guard inside resolveDiagramOptions holds for a caller that doesn't.
+    expect(resolveDiagramOptions(/** @type {any} */ (undefined))).toEqual({})
+    expect(resolveDiagramOptions({})).toEqual({})
+  })
+})

package/lib/shiki-syntax-highlighter.js

@@ -134,7 +134,7 @@ asciidoctor.SyntaxHighlighter.register('shiki', {
   // return value above — is read directly, rather than trusting an
   // ivar-driven default this adapter doesn't fully participate in.
   format(node, lang, opts) {
-    const preClass = opts && opts.nowrap ? 'shiki highlight nowrap' : 'shiki highlight'
+    const preClass = opts?.nowrap ? 'shiki highlight nowrap' : 'shiki highlight'
     const langAttr = lang ? ' data-lang="' + escapeHtml(lang) + '"' : ''
     return `<pre class="${preClass}"><code${langAttr}>${node.getContent()}</code></pre>`
   },

package/lib/shiki-syntax-highlighter.spec.js

@@ -0,0 +1,92 @@
+// SPDX-FileCopyrightText: 2026 INDUSTRIA DE DISEÑO TEXTIL S.A. (INDITEX S.A.)
+//
+// SPDX-License-Identifier: Apache-2.0
+
+'use strict'
+
+import { afterEach, describe, expect, it } from 'vitest'
+const shikiInstance = require('./shiki-instance')
+// Registering the 'shiki' SyntaxHighlighter is a side effect of requiring
+// this module (see its own header) — there is no other exported surface to
+// call directly, so every case here drives it the same way Antora would:
+// converting a `[source]` block through the real 2.2 Asciidoctor factory
+// with `source-highlighter=shiki`.
+require('./shiki-syntax-highlighter')
+
+const asciidoctor = /** @type {any} */ (require('asciidoctor-core-2.2'))()
+
+/**
+ * @param {string | undefined} lang
+ * @param {string} body
+ */
+function convertSource(lang, body) {
+  const source = (lang ? '[source,' + lang + ']' : '[source]') + '\n----\n' + body + '\n----'
+  return asciidoctor.convert(source, { attributes: { 'source-highlighter': 'shiki' }, safe: 'safe' })
+}
+
+describe('shiki syntax highlighter', () => {
+  afterEach(() => {
+    // Reset the module-level singleton between tests — shiki-instance.js is
+    // one shared handle for the whole process (see its own header). `set`'s
+    // own JSDoc requires a real highlighter/rootStyle; this is the one place
+    // that intentionally puts it back to the "never warmed" state its own
+    // `get()` documents returning `null` for.
+    shikiInstance.set(/** @type {any} */ (null), /** @type {any} */ (null))
+  })
+
+  it('degrades to plain escaped text when the pre-warm listener never ran', () => {
+    const html = convertSource('javascript', 'const x = 1 < 2;')
+    expect(html).toContain('<pre class="shiki highlight"><code data-lang="javascript">const x = 1 &lt; 2;</code></pre>')
+  })
+
+  it("strips Shiki's own <pre><code> wrapper and re-declares the root style", () => {
+    shikiInstance.set(
+      {
+        getLoadedLanguages: () => ['javascript'],
+        codeToHtml: (source) =>
+          '<pre class="shiki" style="--shiki-fake:1"><code>' + source.toUpperCase() + '</code></pre>',
+      },
+      '--root-style:1'
+    )
+    const html = convertSource('javascript', 'const x = 1;')
+    expect(html).toContain(
+      '<pre class="shiki highlight"><code data-lang="javascript"><span style="--root-style:1">CONST X = 1;</span></code></pre>'
+    )
+  })
+
+  it('falls back to the "text" grammar for a language the loaded set does not carry', () => {
+    shikiInstance.set(
+      {
+        getLoadedLanguages: () => ['text'],
+        codeToHtml: (source, opts) => '<pre><code>' + opts.lang + ':' + source + '</code></pre>',
+      },
+      ''
+    )
+    const html = convertSource('ruby', 'puts 1')
+    expect(html).toContain('text:puts 1')
+  })
+
+  it('resolves an unannotated [source] block (lang "none") to the "text" grammar', () => {
+    shikiInstance.set(
+      {
+        getLoadedLanguages: () => ['text'],
+        codeToHtml: (source, opts) => '<pre><code>' + opts.lang + ':' + source + '</code></pre>',
+      },
+      ''
+    )
+    const html = convertSource(undefined, 'plain text')
+    expect(html).toContain('text:plain text')
+  })
+
+  it('maps a LANG_ALIASES entry (objectivec) to its Shiki grammar id', () => {
+    shikiInstance.set(
+      {
+        getLoadedLanguages: () => ['objective-c'],
+        codeToHtml: (source, opts) => '<pre><code>' + opts.lang + ':' + source + '</code></pre>',
+      },
+      ''
+    )
+    const html = convertSource('objectivec', '@interface Foo @end')
+    expect(html).toContain('objective-c:@interface Foo @end')
+  })
+})

package/lib/svg-namespace.js

@@ -61,7 +61,7 @@ const ID_DECLARATION_RX = /id=["']([^"']+)["']/g
  * @returns {string}
  */
 function escapeRegExp(value) {
-  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  return value.replace(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`)
 }
 
 /**
@@ -89,12 +89,12 @@ function namespaceSvgIds(svgMarkup, prefix) {
   const sortedIds = Array.from(ids).sort((a, b) => b.length - a.length)
   const idAlternation = sortedIds.map(escapeRegExp).join('|')
 
-  const declarationRx = new RegExp('id=(["\'])(' + idAlternation + ')\\1', 'g')
+  const declarationRx = new RegExp(String.raw`id=(["'])(${idAlternation})\1`, 'g')
   // Not followed by another id-safe character (a word character or `-`) —
   // same reasoning as the longest-first sort, belt and suspenders: even if
   // two ids somehow shared a length, this stops a partial match at the
   // reference site too.
-  const referenceRx = new RegExp('#(' + idAlternation + ')(?![\\w-])', 'g')
+  const referenceRx = new RegExp(String.raw`#(${idAlternation})(?![\w-])`, 'g')
 
   return svgMarkup
     .replace(declarationRx, (_, quote, id) => 'id=' + quote + prefix + '-' + id + quote)

package/lib/svg-namespace.spec.js

@@ -0,0 +1,62 @@
+// SPDX-FileCopyrightText: 2026 INDUSTRIA DE DISEÑO TEXTIL S.A. (INDITEX S.A.)
+//
+// SPDX-License-Identifier: Apache-2.0
+
+'use strict'
+
+import { describe, expect, it } from 'vitest'
+const namespaceSvgIds = require('./svg-namespace')
+
+describe('namespaceSvgIds', () => {
+  it('returns the markup unchanged when it carries no ids', () => {
+    const svg = '<svg><rect width="10" height="10"/></svg>'
+    expect(namespaceSvgIds(svg, 'prefix')).toBe(svg)
+  })
+
+  it('rewrites a single id declaration and its reference', () => {
+    const svg = '<svg id="container"><use href="#container"/></svg>'
+    const result = namespaceSvgIds(svg, 'diagram-1')
+    expect(result).toBe('<svg id="diagram-1-container"><use href="#diagram-1-container"/></svg>')
+  })
+
+  it('rewrites both single- and double-quoted id declarations', () => {
+    const svg = `<svg id='container'><g id="node1"></g></svg>`
+    const result = namespaceSvgIds(svg, 'p')
+    expect(result).toContain(`id='p-container'`)
+    expect(result).toContain(`id="p-node1"`)
+  })
+
+  it('rewrites a url(#id) reference inside a fill/stroke/clip-path/mask/filter attribute', () => {
+    const svg = '<svg id="graph0"><path fill="url(#graph0)"/></svg>'
+    const result = namespaceSvgIds(svg, 'x')
+    expect(result).toBe('<svg id="x-graph0"><path fill="url(#x-graph0)"/></svg>')
+  })
+
+  it('rewrites a CSS id-selector inside an embedded <style> block', () => {
+    const svg = '<svg id="container"><style>#container{fill:red}</style></svg>'
+    const result = namespaceSvgIds(svg, 'y')
+    expect(result).toBe('<svg id="y-container"><style>#y-container{fill:red}</style></svg>')
+  })
+
+  it('rewrites longer ids before shorter ones so node1 does not eat into node10', () => {
+    const svg = '<svg><g id="node1"></g><g id="node10"></g><use href="#node1"/><use href="#node10"/></svg>'
+    const result = namespaceSvgIds(svg, 'p')
+    expect(result).toBe(
+      '<svg><g id="p-node1"></g><g id="p-node10"></g><use href="#p-node1"/><use href="#p-node10"/></svg>'
+    )
+  })
+
+  it('does not let a reference bleed into a longer word-character run', () => {
+    // #node1 followed by more id-safe characters must not be treated as a
+    // reference to "node1" — the (?![\w-]) guard in referenceRx.
+    const svg = '<svg id="node1"><a href="#node1x">not a reference to node1</a></svg>'
+    const result = namespaceSvgIds(svg, 'p')
+    expect(result).toBe('<svg id="p-node1"><a href="#node1x">not a reference to node1</a></svg>')
+  })
+
+  it('escapes ids that contain regex-special characters', () => {
+    const svg = '<svg id="a.b+c"><use href="#a.b+c"/></svg>'
+    const result = namespaceSvgIds(svg, 'p')
+    expect(result).toBe('<svg id="p-a.b+c"><use href="#p-a.b+c"/></svg>')
+  })
+})

package/lib/warn.js

@@ -72,7 +72,7 @@ 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(', ') : ''
+  const suffix = expected?.length ? '; expected one of ' + expected.join(', ') : ''
   logger.warn(source + ' — ' + problem + suffix)
 }
 

package/lib/warn.spec.js

@@ -0,0 +1,57 @@
+// SPDX-FileCopyrightText: 2026 INDUSTRIA DE DISEÑO TEXTIL S.A. (INDITEX S.A.)
+//
+// SPDX-License-Identifier: Apache-2.0
+
+'use strict'
+
+import { describe, expect, it, vi } from 'vitest'
+const warn = require('./warn')
+
+describe('warn', () => {
+  it('logs through node.getDocument().getLogger() when a document is reachable', () => {
+    const warnFn = vi.fn()
+    const node = { getDocument: () => ({ getLogger: () => ({ warn: warnFn }) }) }
+    warn(node, '[cards]', 'a cards block with no cards in it')
+    expect(warnFn).toHaveBeenCalledWith('[cards] — a cards block with no cards in it')
+  })
+
+  it('logs through node.getLogger() directly when node is itself a document', () => {
+    const warnFn = vi.fn()
+    const node = { getLogger: () => ({ warn: warnFn }) }
+    warn(node, '[cards]', 'no cards in it')
+    expect(warnFn).toHaveBeenCalledWith('[cards] — no cards in it')
+  })
+
+  it('appends the expected values when given a closed set', () => {
+    const warnFn = vi.fn()
+    const node = { getLogger: () => ({ warn: warnFn }) }
+    warn(node, 'label:mauve[]', 'unknown IDS Label variant "mauve"', ['white', 'grey'])
+    expect(warnFn).toHaveBeenCalledWith(
+      'label:mauve[] — unknown IDS Label variant "mauve"; expected one of white, grey'
+    )
+  })
+
+  it('appends nothing when expected is omitted or empty', () => {
+    const warnFn = vi.fn()
+    const node = { getLogger: () => ({ warn: warnFn }) }
+    warn(node, '[cta]', 'no primary action', [])
+    expect(warnFn).toHaveBeenCalledWith('[cta] — no primary action')
+  })
+
+  it('tolerates a node with no getDocument and no getLogger at all', () => {
+    expect(() => warn({}, '[cta]', 'problem')).not.toThrow()
+  })
+
+  it('tolerates getDocument() returning an object with no getLogger', () => {
+    const node = { getDocument: () => ({}) }
+    expect(() => warn(node, '[cta]', 'problem')).not.toThrow()
+  })
+
+  it('tolerates a logger object whose warn is not a function', () => {
+    // Intentionally not a real Logger shape — proves the `typeof
+    // logger.warn !== 'function'` guard, not something a real caller
+    // would ever construct.
+    const node = /** @type {any} */ ({ getLogger: () => ({ warn: 'not-a-function' }) })
+    expect(() => warn(node, '[cta]', 'problem')).not.toThrow()
+  })
+})

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inditextech/docouture-asciidoc-extensions",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Asciidoctor extensions shared by docouture documentation sites — authored content that has no AsciiDoc equivalent, rendered as this project's own component markup",
   "repository": {
     "type": "git",
@@ -30,6 +30,7 @@
   "scripts": {
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "lint": "eslint .",
-    "lint:fix": "eslint . --fix"
+    "lint:fix": "eslint . --fix",
+    "test": "vitest run"
   }
 }