@matfsw/docusaurus-plantuml-plugin 0.1.0

package/dist/runtime/queue.js

@@ -0,0 +1,101 @@
+import { PlantUmlError, toError } from './errors.js';
+const pending = [];
+let active = false;
+function pump() {
+    if (active)
+        return;
+    const next = pending.shift();
+    if (!next)
+        return;
+    active = true;
+    next.start();
+}
+/**
+ * Queues `task` behind every previously queued task.
+ *
+ * `task` receives a signal that is aborted on timeout or caller abort, so long-running
+ * work can bail out instead of writing into a discarded render.
+ */
+export function enqueueRender(task, options) {
+    const { timeoutMs, signal } = options;
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        let advanced = false;
+        let timer;
+        const controller = new AbortController();
+        const onExternalAbort = () => {
+            controller.abort();
+            // Deliberately does not advance the queue: the engine may still be mid-render, and
+            // starting the next diagram now would reintroduce the concurrency corruption.
+            settleWith(() => reject(new PlantUmlError('aborted', 'Render aborted.')));
+        };
+        function settleWith(fn) {
+            if (settled)
+                return;
+            settled = true;
+            if (timer !== undefined)
+                clearTimeout(timer);
+            signal?.removeEventListener('abort', onExternalAbort);
+            fn();
+        }
+        /** Releases the single execution slot. Idempotent, so timeout + late settle is safe. */
+        function advance() {
+            if (advanced)
+                return;
+            advanced = true;
+            active = false;
+            // Yield so a synchronously-resolving task cannot grow the stack without bound.
+            queueMicrotask(pump);
+        }
+        if (signal?.aborted) {
+            // Never occupy a queue slot for work whose result is already unwanted.
+            reject(new PlantUmlError('aborted', 'Render aborted before it started.'));
+            return;
+        }
+        signal?.addEventListener('abort', onExternalAbort, { once: true });
+        pending.push({
+            start: () => {
+                if (settled) {
+                    advance();
+                    return;
+                }
+                timer = setTimeout(() => {
+                    controller.abort();
+                    settleWith(() => reject(new PlantUmlError('timeout', `PlantUML rendering timed out after ${timeoutMs} ms.`)));
+                    // A hung engine call must not block every later diagram on the page.
+                    advance();
+                }, timeoutMs);
+                let taskPromise;
+                try {
+                    taskPromise = task(controller.signal);
+                }
+                catch (error) {
+                    settleWith(() => reject(toError(error)));
+                    advance();
+                    return;
+                }
+                void taskPromise.then((value) => {
+                    settleWith(() => resolve(value));
+                    advance();
+                }, (error) => {
+                    settleWith(() => reject(toError(error)));
+                    advance();
+                });
+            },
+        });
+        pump();
+    });
+}
+/** Number of tasks waiting to start. Exposed for tests and diagnostics. */
+export function pendingRenderCount() {
+    return pending.length;
+}
+/** Whether a task is currently running. Exposed for tests and diagnostics. */
+export function isRenderActive() {
+    return active;
+}
+/** Test-only: drops queued work and clears the active flag. */
+export function resetRenderQueue() {
+    pending.length = 0;
+    active = false;
+}

package/dist/runtime/renderer.d.ts

@@ -0,0 +1,23 @@
+import { type LoadRuntimeOptions } from './assetLoader.js';
+import { type DiagramCache } from './cache.js';
+export interface RenderDiagramRequest {
+    source: string;
+    dark: boolean;
+    sanitize: boolean;
+    timeoutMs: number;
+    assetsBaseUrl: string;
+    coreVersion: string;
+    cache: DiagramCache;
+    signal?: AbortSignal;
+    /** Reports which long-running phase is in progress, so the UI can show an accurate state. */
+    onPhase?: (phase: 'loading' | 'rendering') => void;
+    /** Test seam mirroring {@link LoadRuntimeOptions.importModule}. */
+    importModule?: LoadRuntimeOptions['importModule'];
+}
+/**
+ * Renders one diagram to sanitized SVG.
+ *
+ * Cache hits skip the queue entirely; everything else is serialized behind
+ * {@link enqueueRender} because the engine cannot render two diagrams at once.
+ */
+export declare function renderDiagram(request: RenderDiagramRequest): Promise<string>;

package/dist/runtime/renderer.js

@@ -0,0 +1,70 @@
+import { loadPlantUmlRuntime } from './assetLoader.js';
+import { computeCacheKey } from './cache.js';
+import { describeEngineError, detectDiagramError, PlantUmlError } from './errors.js';
+import { enqueueRender } from './queue.js';
+import { sanitizeSvgMarkup } from './sanitize.js';
+/**
+ * `renderToString` takes its options as a *fourth* argument, after the two callbacks.
+ * This was verified against the installed `@plantuml/core` rather than assumed: the
+ * function's arity is 4 and `{dark: true}` produces different fill colours from `{dark:
+ * false}`, which itself is byte-identical to omitting the argument.
+ */
+function renderWithEngine(engine, source, dark) {
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const lines = source.split(/\r\n|\r|\n/);
+        try {
+            engine.renderToString(lines, (svg) => {
+                if (settled)
+                    return;
+                settled = true;
+                resolve(svg);
+            }, (raw) => {
+                if (settled)
+                    return;
+                settled = true;
+                reject(new PlantUmlError('engine', describeEngineError(raw)));
+            }, { dark });
+        }
+        catch (error) {
+            if (settled)
+                return;
+            settled = true;
+            reject(new PlantUmlError('engine', describeEngineError(error), { cause: error }));
+        }
+    });
+}
+/**
+ * Renders one diagram to sanitized SVG.
+ *
+ * Cache hits skip the queue entirely; everything else is serialized behind
+ * {@link enqueueRender} because the engine cannot render two diagrams at once.
+ */
+export async function renderDiagram(request) {
+    const { source, dark, sanitize, timeoutMs, cache, coreVersion, signal, onPhase } = request;
+    const cacheKey = computeCacheKey({ source, dark, sanitized: sanitize, coreVersion });
+    const cached = cache.get(cacheKey);
+    if (cached !== undefined)
+        return cached;
+    // Loading happens outside the queue: it is shared, idempotent work, and holding the
+    // single render slot for an 8 MB download would stall every other diagram on the page.
+    onPhase?.('loading');
+    const engine = await loadPlantUmlRuntime({
+        assetsBaseUrl: request.assetsBaseUrl,
+        timeoutMs,
+        importModule: request.importModule,
+    });
+    onPhase?.('rendering');
+    const svg = await enqueueRender(async () => {
+        const raw = await renderWithEngine(engine, source, dark);
+        // Invalid PlantUML is reported as a successfully rendered "error picture", not through
+        // the error callback, so a rendered SVG still has to be inspected before it is trusted.
+        const diagramError = detectDiagramError(raw);
+        if (diagramError !== null) {
+            throw new PlantUmlError('diagram', diagramError);
+        }
+        return sanitize ? sanitizeSvgMarkup(raw) : raw;
+    }, { timeoutMs, signal });
+    cache.set(cacheKey, svg);
+    return svg;
+}

package/dist/runtime/sanitize.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Sanitizes a rendered SVG string.
+ *
+ * Scripts, event-handler attributes and `javascript:` URLs are removed; ordinary PlantUML
+ * geometry, text, gradients, markers, links and `data-*`/ARIA attributes are preserved.
+ *
+ * @throws PlantUmlError when the input contains no SVG root at all, which would otherwise
+ *   surface as a silently blank diagram.
+ */
+export declare function sanitizeSvgMarkup(svg: string): string;
+/** Test-only: forces the DOMPurify instance to be rebuilt against the current window. */
+export declare function resetSanitizer(): void;

package/dist/runtime/sanitize.js

@@ -0,0 +1,47 @@
+import createDOMPurify from 'dompurify';
+import { PlantUmlError } from './errors.js';
+let purifier = null;
+function getPurifier() {
+    if (purifier)
+        return purifier;
+    if (typeof window === 'undefined') {
+        throw new PlantUmlError('config', 'SVG sanitization requires a browser environment.');
+    }
+    purifier = createDOMPurify(window);
+    return purifier;
+}
+/**
+ * `foreignObject` is the one SVG element that can host arbitrary HTML, which reintroduces
+ * exactly the injection surface the SVG profile exists to remove. PlantUML does not need it.
+ */
+const FORBIDDEN_TAGS = ['foreignobject', 'script', 'iframe', 'object', 'embed', 'audio', 'video'];
+/**
+ * Sanitizes a rendered SVG string.
+ *
+ * Scripts, event-handler attributes and `javascript:` URLs are removed; ordinary PlantUML
+ * geometry, text, gradients, markers, links and `data-*`/ARIA attributes are preserved.
+ *
+ * @throws PlantUmlError when the input contains no SVG root at all, which would otherwise
+ *   surface as a silently blank diagram.
+ */
+export function sanitizeSvgMarkup(svg) {
+    const purify = getPurifier();
+    const clean = purify.sanitize(svg, {
+        USE_PROFILES: { svg: true, svgFilters: true },
+        FORBID_TAGS: FORBIDDEN_TAGS,
+        FORBID_ATTR: ['formaction', 'xlink:show', 'ping'],
+        ADD_ATTR: ['role', 'aria-label', 'aria-labelledby', 'aria-describedby'],
+        ALLOW_DATA_ATTR: true,
+        KEEP_CONTENT: true,
+        RETURN_DOM: false,
+        RETURN_DOM_FRAGMENT: false,
+    });
+    if (!/<svg[\s>]/i.test(clean)) {
+        throw new PlantUmlError('engine', 'Sanitization removed the rendered diagram: the engine output contained no usable <svg> root.');
+    }
+    return clean;
+}
+/** Test-only: forces the DOMPurify instance to be rebuilt against the current window. */
+export function resetSanitizer() {
+    purifier = null;
+}

package/dist/runtime/types.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The public surface of `@plantuml/core@1.2026.x`, verified against the installed package.
+ *
+ * `plantuml.js` exports exactly two functions. Both take an optional trailing options
+ * object whose only recognized member is `dark`; see `docs/architecture.md` for how this
+ * was established and `tests/e2e/engine-contract.spec.ts` for the regression guard.
+ */
+export interface PlantUmlCoreModule {
+    render(lines: string[], targetId: string, options?: PlantUmlRenderOptions): void;
+    renderToString(lines: string[], onSuccess: (svg: string) => void, onError: (message: unknown) => void, options?: PlantUmlRenderOptions): void;
+}
+export interface PlantUmlRenderOptions {
+    dark?: boolean;
+}
+export type DiagramStatus = 'idle' | 'loading' | 'rendering' | 'ready' | 'error';

package/dist/runtime/types.js

@@ -0,0 +1 @@
+export {};

package/dist/theme/MDXComponents/Code/index.d.ts

@@ -0,0 +1,16 @@
+import type { ReactNode } from 'react';
+import { type CodeBlockProps } from '../../codeBlockMeta.js';
+/**
+ * Wraps Docusaurus' `MDXComponents/Code` extension point.
+ *
+ * Only fences whose language is configured as PlantUML are intercepted. Everything else —
+ * inline code, ordinary fenced blocks, JSX-authored blocks — is delegated to the original
+ * component with its props untouched, so no existing code-block behaviour changes.
+ *
+ * The delegate is imported from `@theme-init/`, not `@theme-original/`. Docusaurus points
+ * *both* `@theme/X` and `@theme-original/X` at the last plugin theme that provides `X`, so
+ * a plugin importing `@theme-original/MDXComponents/Code` imports itself and recurses until
+ * the stack overflows. `@theme-init/X` is the alias that keeps pointing at the first theme
+ * to provide the component — see `docs/adr/0001-theme-init-alias.md`.
+ */
+export default function Code(props: CodeBlockProps): ReactNode;

package/dist/theme/MDXComponents/Code/index.js

@@ -0,0 +1,28 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import OriginalCode from '@theme-init/MDXComponents/Code';
+import PlantUmlDiagram from '@theme/PlantUmlDiagram';
+import { extractLanguage, extractSource, parseTitle, } from '../../codeBlockMeta.js';
+import { usePlantUmlConfig } from '../../usePlantUmlConfig.js';
+/**
+ * Wraps Docusaurus' `MDXComponents/Code` extension point.
+ *
+ * Only fences whose language is configured as PlantUML are intercepted. Everything else —
+ * inline code, ordinary fenced blocks, JSX-authored blocks — is delegated to the original
+ * component with its props untouched, so no existing code-block behaviour changes.
+ *
+ * The delegate is imported from `@theme-init/`, not `@theme-original/`. Docusaurus points
+ * *both* `@theme/X` and `@theme-original/X` at the last plugin theme that provides `X`, so
+ * a plugin importing `@theme-original/MDXComponents/Code` imports itself and recurses until
+ * the stack overflows. `@theme-init/X` is the alias that keeps pointing at the first theme
+ * to provide the component — see `docs/adr/0001-theme-init-alias.md`.
+ */
+export default function Code(props) {
+    const config = usePlantUmlConfig();
+    const language = extractLanguage(props);
+    const isPlantUml = config !== null && language !== undefined && config.options.languages.includes(language);
+    const source = isPlantUml ? extractSource(props.children) : null;
+    if (!isPlantUml || source === null) {
+        return _jsx(OriginalCode, { ...props });
+    }
+    return _jsx(PlantUmlDiagram, { source: source, title: parseTitle(props), language: language });
+}

package/dist/theme/PlantUmlDiagram/index.d.ts

@@ -0,0 +1,16 @@
+import { type ReactNode } from 'react';
+export interface PlantUmlDiagramProps {
+    /** Raw PlantUML source, exactly as authored between the fence markers. */
+    source: string;
+    /** `title="..."` from the fence metastring; used as caption and accessible label. */
+    title?: string;
+    /** The fence language that matched, e.g. `plantuml` or `puml`. */
+    language?: string;
+}
+/**
+ * Renders one PlantUML diagram in the browser.
+ *
+ * Nothing happens during server-side rendering: the markup emitted on the server is the
+ * same deferred placeholder the client renders first, so hydration never mismatches.
+ */
+export default function PlantUmlDiagram({ source, title, language, }: PlantUmlDiagramProps): ReactNode;

package/dist/theme/PlantUmlDiagram/index.js

@@ -0,0 +1,134 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from 'react';
+import { useColorMode } from '@docusaurus/theme-common';
+import { DATA_ATTR } from '../../constants.js';
+import { getSharedCache } from '../../runtime/cache.js';
+import { PlantUmlError } from '../../runtime/errors.js';
+import { renderDiagram } from '../../runtime/renderer.js';
+import { usePlantUmlConfig } from '../usePlantUmlConfig.js';
+import styles from './styles.module.css';
+const DEFAULT_LABEL = 'PlantUML diagram';
+/** Margin large enough that a diagram is usually ready by the time it is scrolled into view. */
+const LAZY_ROOT_MARGIN = '300px';
+const INITIAL_STATE = { status: 'idle', svg: null, error: null };
+function escapeHtml(value) {
+    return value
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;');
+}
+function messageFor(error) {
+    if (error instanceof PlantUmlError)
+        return error.message;
+    if (error instanceof Error)
+        return error.message;
+    return 'The diagram could not be rendered.';
+}
+/**
+ * Renders one PlantUML diagram in the browser.
+ *
+ * Nothing happens during server-side rendering: the markup emitted on the server is the
+ * same deferred placeholder the client renders first, so hydration never mismatches.
+ */
+export default function PlantUmlDiagram({ source, title, language, }) {
+    const config = usePlantUmlConfig();
+    const { colorMode } = useColorMode();
+    const containerRef = useRef(null);
+    const themeOption = config?.options.theme ?? 'auto';
+    const dark = themeOption === 'auto' ? colorMode === 'dark' : themeOption === 'dark';
+    const lazy = config?.options.lazy ?? true;
+    const [state, setState] = useState(INITIAL_STATE);
+    const [inView, setInView] = useState(!lazy);
+    useEffect(() => {
+        if (!lazy || inView)
+            return undefined;
+        const element = containerRef.current;
+        if (!element)
+            return undefined;
+        // jsdom and older browsers have no IntersectionObserver; rendering immediately is the
+        // correct fallback, since a missing observer must not mean a permanently blank diagram.
+        if (typeof IntersectionObserver === 'undefined') {
+            setInView(true);
+            return undefined;
+        }
+        const observer = new IntersectionObserver((entries) => {
+            if (entries.some((entry) => entry.isIntersecting)) {
+                setInView(true);
+                observer.disconnect();
+            }
+        }, { rootMargin: LAZY_ROOT_MARGIN });
+        observer.observe(element);
+        return () => observer.disconnect();
+    }, [lazy, inView]);
+    useEffect(() => {
+        if (!inView)
+            return undefined;
+        if (!config) {
+            setState({
+                status: 'error',
+                svg: null,
+                error: 'PlantUML plugin data is missing. Add the plugin to the `plugins` array in your ' +
+                    'Docusaurus configuration and restart the build.',
+            });
+            return undefined;
+        }
+        const controller = new AbortController();
+        const { options } = config;
+        // The signal is the single guard against both stale results and post-unmount updates:
+        // the cleanup aborts it, and every state write checks it first. Identical states are
+        // dropped so a repeated phase report cannot cause a pointless re-render.
+        const commit = (next) => {
+            if (controller.signal.aborted)
+                return;
+            setState((previous) => previous.status === next.status &&
+                previous.svg === next.svg &&
+                previous.error === next.error
+                ? previous
+                : next);
+        };
+        void renderDiagram({
+            source,
+            dark,
+            sanitize: options.sanitizeSvg,
+            timeoutMs: options.renderTimeoutMs,
+            assetsBaseUrl: config.assetsBaseUrl,
+            coreVersion: config.coreVersion,
+            cache: getSharedCache(options.cache, options.cacheMaxEntries),
+            signal: controller.signal,
+            onPhase: (phase) => commit({ status: phase, svg: null, error: null }),
+        })
+            .then((svg) => commit({ status: 'ready', svg, error: null }))
+            .catch((error) => {
+            if (error instanceof PlantUmlError && error.kind === 'aborted')
+                return;
+            commit({ status: 'error', svg: null, error: messageFor(error) });
+        });
+        return () => controller.abort();
+        // Depends on the individual values rather than the `config` object, so that an
+        // unmemoized config from a future refactor cannot restart rendering on every render.
+    }, [
+        inView,
+        source,
+        dark,
+        config,
+        config?.assetsBaseUrl,
+        config?.coreVersion,
+        config?.options.sanitizeSvg,
+        config?.options.renderTimeoutMs,
+        config?.options.cache,
+        config?.options.cacheMaxEntries,
+    ]);
+    const label = title ?? DEFAULT_LABEL;
+    const busy = state.status === 'loading' || state.status === 'rendering';
+    return (_jsxs("figure", { ref: containerRef, className: styles.figure, "aria-busy": busy || undefined, [DATA_ATTR.diagram]: language ?? 'plantuml',
+        [DATA_ATTR.status]: state.status,
+        [DATA_ATTR.theme]: dark ? 'dark' : 'light', children: [state.status === 'ready' && state.svg !== null && (_jsx("div", { className: styles.canvas, role: "img", "aria-label": label, 
+                // Sanitized above unless `sanitizeSvg: false` was explicitly opted into.
+                dangerouslySetInnerHTML: { __html: state.svg } })), state.status !== 'ready' && state.status !== 'error' && (
+            // `aria-busy` on the figure already conveys progress; announcing every phase change
+            // would make a page with several diagrams unusable with a screen reader.
+            _jsxs("div", { className: styles.placeholder, children: [_jsx("span", { className: styles.spinner, "aria-hidden": "true" }), _jsxs("span", { children: [state.status === 'loading' ? 'Loading PlantUML runtime…' : null, state.status === 'rendering' ? `Rendering ${label}…` : null, state.status === 'idle' ? `${label} (waiting to render)` : null] })] })), state.status === 'error' && (_jsxs("div", { className: styles.error, role: "alert", children: [_jsxs("p", { className: styles.errorHeading, children: [_jsx("span", { className: styles.errorIcon, "aria-hidden": "true", children: "\u26A0" }), _jsx("span", { children: "Error: PlantUML diagram could not be rendered" })] }), _jsx("pre", { className: styles.errorMessage, children: state.error }), config?.options.showSourceOnError !== false && (_jsxs("details", { className: styles.errorDetails, children: [_jsx("summary", { children: "Show diagram source" }), _jsx("pre", { className: styles.source, children: source })] }))] })), title !== undefined && _jsx("figcaption", { className: styles.caption, children: title }), _jsx("noscript", { dangerouslySetInnerHTML: {
+                    __html: `<pre class="${styles.source ?? ''}">${escapeHtml(source)}</pre>`,
+                } })] }));
+}

package/dist/theme/PlantUmlDiagram/styles.module.css

@@ -0,0 +1,107 @@
+.figure {
+  margin: 0 0 1.25rem;
+  padding: 0;
+}
+
+.canvas {
+  display: flex;
+  justify-content: flex-start;
+  overflow-x: auto;
+}
+
+.canvas svg {
+  max-width: 100%;
+  height: auto;
+}
+
+.placeholder {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  min-height: 4rem;
+  padding: 0.75rem 1rem;
+  border: 1px dashed var(--ifm-color-emphasis-300);
+  border-radius: var(--ifm-global-radius);
+  color: var(--ifm-color-emphasis-700);
+  font-size: 0.875rem;
+}
+
+.spinner {
+  width: 0.875rem;
+  height: 0.875rem;
+  border: 2px solid var(--ifm-color-emphasis-400);
+  border-top-color: transparent;
+  border-radius: 50%;
+  animation: plantuml-spin 0.8s linear infinite;
+}
+
+@keyframes plantuml-spin {
+  to {
+    transform: rotate(360deg);
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .spinner {
+    animation: none;
+  }
+}
+
+.caption {
+  margin-top: 0.5rem;
+  color: var(--ifm-color-emphasis-700);
+  font-size: 0.875rem;
+  text-align: left;
+}
+
+/*
+ * Failure is signalled by the "Error" label and the icon as well as by colour, so the state
+ * remains readable for colour-blind readers and in forced-colours mode.
+ */
+.error {
+  padding: 0.75rem 1rem;
+  border: 1px solid var(--ifm-color-danger-dark);
+  border-left-width: 4px;
+  border-radius: var(--ifm-global-radius);
+  background: var(--ifm-color-danger-contrast-background);
+  color: var(--ifm-color-danger-contrast-foreground);
+}
+
+.errorHeading {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  margin: 0 0 0.5rem;
+  font-size: 0.9375rem;
+  font-weight: 600;
+}
+
+.errorIcon {
+  flex: none;
+  font-size: 1rem;
+  line-height: 1;
+}
+
+.errorMessage {
+  margin: 0;
+  overflow-x: auto;
+  font-family: var(--ifm-font-family-monospace);
+  font-size: 0.8125rem;
+  white-space: pre-wrap;
+  word-break: break-word;
+}
+
+.errorDetails {
+  margin-top: 0.75rem;
+}
+
+.errorDetails summary {
+  cursor: pointer;
+  font-size: 0.875rem;
+}
+
+.source {
+  margin: 0.5rem 0 0;
+  overflow-x: auto;
+  font-size: 0.8125rem;
+}

package/dist/theme/codeBlockMeta.d.ts

@@ -0,0 +1,27 @@
+import { type ReactNode } from 'react';
+export interface CodeBlockProps {
+    children?: ReactNode;
+    className?: string;
+    metastring?: string;
+    language?: string;
+    title?: string;
+}
+/**
+ * Extracts the fence language.
+ *
+ * MDX preserves the case the author typed (```PlantUML yields `language-PlantUML`), and
+ * Docusaurus lower-cases it before handing it to Prism. Matching is therefore
+ * case-insensitive: `plantuml`, `PlantUML` and `PUML` all resolve to the same language.
+ */
+export declare function extractLanguage(props: CodeBlockProps): string | undefined;
+export declare function isPlantUmlLanguage(props: CodeBlockProps, languages: readonly string[]): boolean;
+/**
+ * Flattens fence children into the raw diagram source.
+ *
+ * Returns `null` when the children contain React elements, which happens for JSX-authored
+ * code blocks. Those are handed back to the original Docusaurus component untouched rather
+ * than being rendered from a partially-known source string.
+ */
+export declare function extractSource(children: ReactNode): string | null;
+/** Reads `title="..."` (or `title='...'`) from the fence metastring. */
+export declare function parseTitle(props: CodeBlockProps): string | undefined;

package/dist/theme/codeBlockMeta.js

@@ -0,0 +1,58 @@
+import { Children, isValidElement } from 'react';
+/**
+ * Mirrors Docusaurus' own code-block metadata parsing so that a `plantuml` fence behaves
+ * exactly like any other fence up to the point where this plugin takes over.
+ */
+/** Same expression Docusaurus uses in `theme-common`'s `parseCodeBlockTitle`. */
+const TITLE_REGEX = /title=(?<quote>["'])(?<title>.*?)\1/;
+const LANGUAGE_CLASS_PREFIX = 'language-';
+/**
+ * Extracts the fence language.
+ *
+ * MDX preserves the case the author typed (```PlantUML yields `language-PlantUML`), and
+ * Docusaurus lower-cases it before handing it to Prism. Matching is therefore
+ * case-insensitive: `plantuml`, `PlantUML` and `PUML` all resolve to the same language.
+ */
+export function extractLanguage(props) {
+    if (typeof props.language === 'string' && props.language.trim() !== '') {
+        return props.language.trim().toLowerCase();
+    }
+    const fromClass = props.className
+        ?.split(' ')
+        .find((entry) => entry.startsWith(LANGUAGE_CLASS_PREFIX));
+    if (!fromClass)
+        return undefined;
+    const language = fromClass.slice(LANGUAGE_CLASS_PREFIX.length).trim();
+    return language === '' ? undefined : language.toLowerCase();
+}
+export function isPlantUmlLanguage(props, languages) {
+    const language = extractLanguage(props);
+    return language !== undefined && languages.includes(language);
+}
+/**
+ * Flattens fence children into the raw diagram source.
+ *
+ * Returns `null` when the children contain React elements, which happens for JSX-authored
+ * code blocks. Those are handed back to the original Docusaurus component untouched rather
+ * than being rendered from a partially-known source string.
+ */
+export function extractSource(children) {
+    const parts = Children.toArray(children);
+    if (parts.length === 0)
+        return null;
+    if (parts.some((part) => isValidElement(part)))
+        return null;
+    if (!parts.every((part) => typeof part === 'string' || typeof part === 'number'))
+        return null;
+    const source = parts.join('');
+    // MDX always terminates a fence with a newline that is not part of the diagram.
+    return source.replace(/\n$/, '');
+}
+/** Reads `title="..."` (or `title='...'`) from the fence metastring. */
+export function parseTitle(props) {
+    if (typeof props.title === 'string' && props.title !== '')
+        return props.title;
+    const match = props.metastring?.match(TITLE_REGEX);
+    const title = match?.groups?.['title'];
+    return title !== undefined && title !== '' ? title : undefined;
+}