@matfsw/docusaurus-plantuml-plugin 1.1.2 → 1.2.0

package/CHANGELOG.md

@@ -7,6 +7,43 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.2.0]
+
+### Added
+
+- **A source view for every rendered diagram.** A `</>` control in the toolbar, beside the zoom
+  buttons, **flips the frame**: the source takes the diagram's place, in the same box. A
+  **Copy** button joins the same toolbar while the source is shown, so every control on a
+  diagram lives in one place. Enabled by default; turn it off with
+  `showSource: false`, or per fence with `showSource=false` in the metastring.
+
+  Four details are deliberate:
+  - **It shares the diagram's frame rather than sitting below it.** Below the diagram it had two
+    failure modes: a diagram taller than the window pushed it off-screen, and while maximized it
+    was painted behind the full-screen overlay. Sharing the frame removes both by construction.
+  - **The diagram is hidden, not unmounted**, so the frame keeps its height — nothing on the page
+    moves when you flip — and the reader's zoom and pan survive the round trip.
+  - The copy result is announced through a `role="status"` region rather than by renaming the
+    button, because a control whose accessible name changes is announced as a new control.
+  - A failed copy says so. `navigator.clipboard` is undefined outside a secure context, which a
+    docs site on plain HTTP genuinely is; the source is on screen either way, so the reader can
+    select the text.
+
+- `showSource` plugin option and the matching `showSource` / `showSource=false` fence flag.
+- `data-plantuml-source-open="true"` on the `<figure>` while the source is shown, part of the
+  documented `data-*` contract.
+
+### Changed
+
+- The zoom controls are hidden while the source is shown — they would act on a picture nobody
+  can see. **Maximize stays**, because it sizes the frame the source is read in and removing it
+  while maximized would leave Escape as the only way back out.
+
+- With `zoom: false` the source control gets its own row after the diagram, since there is no
+  zoom toolbar to join. `figure > div[role="img"]` remains the first child, so the shape the
+  pre-zoom markup has always had is unchanged. Setting both `zoom: false` and
+  `showSource: false` restores the bare markup exactly.
+
 ## [1.1.2]
 
 ### Fixed
@@ -247,7 +284,8 @@ Initial release.
   opt-out.
 - Plugin option validation that rejects unknown keys and out-of-range values at build time.
 
-[Unreleased]: https://github.com/matf/docusaurus-plantuml-plugin/compare/v1.1.2...HEAD
+[Unreleased]: https://github.com/matf/docusaurus-plantuml-plugin/compare/v1.2.0...HEAD
+[1.2.0]: https://github.com/matf/docusaurus-plantuml-plugin/compare/v1.1.2...v1.2.0
 [1.1.2]: https://github.com/matf/docusaurus-plantuml-plugin/compare/v1.1.1...v1.1.2
 [1.1.1]: https://github.com/matf/docusaurus-plantuml-plugin/compare/v1.1.0...v1.1.1
 [1.1.0]: https://github.com/matf/docusaurus-plantuml-plugin/compare/v1.0.3...v1.1.0

package/README.md

@@ -231,19 +231,20 @@ props untouched. Existing code-block behaviour (highlighting, line numbers, titl
 
 ## Options
 
-| Option              | Type                              | Default                | Description                                                                                                                |
-| ------------------- | --------------------------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `languages`         | `string[]`                        | `['plantuml', 'puml']` | Fence languages treated as PlantUML. Matched case-insensitively; must contain at least one non-empty, non-duplicate entry. |
-| `theme`             | `'auto' \| 'light' \| 'dark'`     | `'auto'`               | Diagram colour scheme. `auto` follows the Docusaurus colour mode; `light`/`dark` pin it.                                   |
-| `lazy`              | `boolean`                         | `true`                 | Render a diagram only once it scrolls near the viewport (300 px root margin).                                              |
-| `cache`             | `'none' \| 'memory' \| 'session'` | `'memory'`             | Where rendered SVG is cached.                                                                                              |
-| `sanitizeSvg`       | `boolean`                         | `true`                 | Run rendered SVG through DOMPurify before inserting it. See [Security model](#svg-sanitization-and-security-model).        |
-| `showSourceOnError` | `boolean`                         | `true`                 | Include the diagram source in a `<details>` block on the error panel.                                                      |
-| `renderTimeoutMs`   | `number`                          | `20000`                | Abort a single render (and the runtime load) after this many milliseconds. Integer, `100`–`600000`.                        |
-| `cacheMaxEntries`   | `number`                          | `50`                   | Upper bound on cached SVG entries. Positive integer.                                                                       |
-| `zoom`              | `boolean`                         | `true`                 | Let readers zoom and pan diagrams. Adds a control toolbar and a focusable viewport. Override per fence with `zoom=false`.  |
-| `graphviz`          | `object`                          | see below              | Graphviz/DOT support. See [Graphviz options](#graphviz-options).                                                           |
-| `id`                | `string`                          | `'default'`            | Docusaurus plugin instance id; only relevant if you register the plugin more than once.                                    |
+| Option              | Type                              | Default                | Description                                                                                                                         |
+| ------------------- | --------------------------------- | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `languages`         | `string[]`                        | `['plantuml', 'puml']` | Fence languages treated as PlantUML. Matched case-insensitively; must contain at least one non-empty, non-duplicate entry.          |
+| `theme`             | `'auto' \| 'light' \| 'dark'`     | `'auto'`               | Diagram colour scheme. `auto` follows the Docusaurus colour mode; `light`/`dark` pin it.                                            |
+| `lazy`              | `boolean`                         | `true`                 | Render a diagram only once it scrolls near the viewport (300 px root margin).                                                       |
+| `cache`             | `'none' \| 'memory' \| 'session'` | `'memory'`             | Where rendered SVG is cached.                                                                                                       |
+| `sanitizeSvg`       | `boolean`                         | `true`                 | Run rendered SVG through DOMPurify before inserting it. See [Security model](#svg-sanitization-and-security-model).                 |
+| `showSourceOnError` | `boolean`                         | `true`                 | Include the diagram source in a `<details>` block on the error panel.                                                               |
+| `renderTimeoutMs`   | `number`                          | `20000`                | Abort a single render (and the runtime load) after this many milliseconds. Integer, `100`–`600000`.                                 |
+| `cacheMaxEntries`   | `number`                          | `50`                   | Upper bound on cached SVG entries. Positive integer.                                                                                |
+| `zoom`              | `boolean`                         | `true`                 | Let readers zoom and pan diagrams. Adds a control toolbar and a focusable viewport. Override per fence with `zoom=false`.           |
+| `showSource`        | `boolean`                         | `true`                 | Offer a toolbar control that reveals the diagram source and copies it to the clipboard. Override per fence with `showSource=false`. |
+| `graphviz`          | `object`                          | see below              | Graphviz/DOT support. See [Graphviz options](#graphviz-options).                                                                    |
+| `id`                | `string`                          | `'default'`            | Docusaurus plugin instance id; only relevant if you register the plugin more than once.                                             |
 
 Every option above except `graphviz` applies to **both** engines: `lazy`, `cache`,
 `sanitizeSvg`, `showSourceOnError`, `renderTimeoutMs`, `cacheMaxEntries` and `zoom` behave
@@ -257,7 +258,7 @@ would otherwise silently disable the option you meant to set:
 ```text
 [docusaurus-plugin-plantuml-client] Unknown option 'sanitiseSvg'. Supported options:
 'languages', 'theme', 'lazy', 'cache', 'sanitizeSvg', 'showSourceOnError',
-'renderTimeoutMs', 'cacheMaxEntries', 'zoom', 'graphviz'.
+'renderTimeoutMs', 'cacheMaxEntries', 'zoom', 'showSource', 'graphviz'.
 ```
 
 The same is true one level deeper, so `graphviz: {enigne: 'neato'}` fails the build rather than
@@ -499,6 +500,58 @@ would mean most readers never discover it. The costs are real and worth knowing:
 
 Setting `zoom: false` restores the previous markup exactly.
 
+## Source view
+
+Every rendered diagram offers its own source. The `</>` control in the toolbar **flips the
+frame**: the source takes the diagram's place, in the same box. A **Copy** button appears beside
+it in the same toolbar while the source is shown. Press `</>` again to flip back.
+
+````markdown
+```plantuml title="Readers can copy this"
+@startuml
+Alice -> Bob : Hello
+@enduml
+```
+````
+
+Details worth knowing:
+
+- **The source shares the diagram's frame.** It was previously rendered _below_ the diagram,
+  which had two failure modes: a diagram taller than the window pushed it off-screen, so the
+  control looked broken; and while maximized it was painted behind the full-screen overlay, so
+  it was invisible however far you scrolled. In the frame it appears exactly where the picture
+  was.
+- **The diagram is hidden, not unmounted.** The frame keeps its height, so nothing on the page
+  moves when you flip, and your zoom and pan survive the round trip.
+- **The zoom controls step aside while the source is shown** — they would act on a picture
+  nobody can see. Maximize stays, because it sizes the frame the source is read in, and taking
+  it away while maximized would leave Escape as the only way out.
+- The source stays outside the `role="img"` subtree, which is opaque to assistive technology —
+  content inside it would be unreachable for screen-reader users.
+- **The copy result is announced through a `role="status"` region**, not by renaming the button.
+  A control whose accessible name changes is announced as a new control every time.
+- **A failed copy says so.** `navigator.clipboard` is undefined outside a secure context, which
+  a docs site served over plain HTTP genuinely is. The panel is open either way, so the reader
+  can select the text; the control never silently does nothing.
+- The panel shows the **authored source**, never the rendered SVG.
+
+Turn it off for a whole site with `showSource: false`, or for one fence:
+
+````markdown
+```plantuml showSource=false
+@startuml
+Alice -> Bob : Hello
+@enduml
+```
+````
+
+With `zoom: false` there is no zoom toolbar, so the control gets its own row after the diagram.
+Setting both `zoom: false` and `showSource: false` restores the bare markup the plugin produced
+before either feature existed.
+
+This is separate from `showSourceOnError`, which offers the source in the error panel when a
+diagram _fails_ to render.
+
 ## Lazy loading
 
 With `lazy: true` (the default), a diagram is not rendered until it scrolls within 300 px of

package/dist/constants.d.ts

@@ -39,4 +39,6 @@ export declare const DATA_ATTR: {
     readonly zoom: "data-plantuml-zoom";
     /** `"true"` on the figure while the diagram fills the browser viewport. */
     readonly maximized: "data-plantuml-maximized";
+    /** `"true"` on the figure while the source panel is open. */
+    readonly sourceOpen: "data-plantuml-source-open";
 };

package/dist/constants.js

@@ -41,4 +41,6 @@ export const DATA_ATTR = {
     zoom: 'data-plantuml-zoom',
     /** `"true"` on the figure while the diagram fills the browser viewport. */
     maximized: 'data-plantuml-maximized',
+    /** `"true"` on the figure while the source panel is open. */
+    sourceOpen: 'data-plantuml-source-open',
 };

package/dist/index.cjs

@@ -126,6 +126,7 @@ var DEFAULT_OPTIONS = {
   renderTimeoutMs: 2e4,
   cacheMaxEntries: 50,
   zoom: true,
+  showSource: true,
   graphviz: DEFAULT_GRAPHVIZ_OPTIONS
 };
 var CACHE_MODES = ["none", "memory", "session"];
@@ -276,6 +277,7 @@ function resolveOptions(rawOptions) {
     "renderTimeoutMs",
     "cacheMaxEntries",
     "zoom",
+    "showSource",
     "graphviz",
     // Docusaurus injects `id` for multi-instance plugins.
     "id"
@@ -323,7 +325,8 @@ function resolveOptions(rawOptions) {
     ),
     renderTimeoutMs: validateRenderTimeout(rawOptions.renderTimeoutMs),
     cacheMaxEntries: validateCacheMaxEntries(rawOptions.cacheMaxEntries),
-    zoom: validateBoolean(rawOptions.zoom, "zoom", DEFAULT_OPTIONS.zoom)
+    zoom: validateBoolean(rawOptions.zoom, "zoom", DEFAULT_OPTIONS.zoom),
+    showSource: validateBoolean(rawOptions.showSource, "showSource", DEFAULT_OPTIONS.showSource)
   };
 }
 

package/dist/index.d.cts

@@ -69,6 +69,11 @@ interface PlantUmlPluginOptions {
      * Override for a single fence with `zoom` or `zoom=false` in its metastring.
      */
     zoom?: boolean;
+    /**
+     * Offer a control that reveals the diagram's source and copies it to the clipboard.
+     * Override for a single fence with `showSource` or `showSource=false` in its metastring.
+     */
+    showSource?: boolean;
     /** Graphviz/DOT diagram support. See {@link GraphvizOptions}. */
     graphviz?: GraphvizOptions;
     /** Docusaurus plugin instance id, used when the plugin is registered more than once. */

package/dist/options.d.ts

@@ -66,6 +66,11 @@ export interface PlantUmlPluginOptions {
      * Override for a single fence with `zoom` or `zoom=false` in its metastring.
      */
     zoom?: boolean;
+    /**
+     * Offer a control that reveals the diagram's source and copies it to the clipboard.
+     * Override for a single fence with `showSource` or `showSource=false` in its metastring.
+     */
+    showSource?: boolean;
     /** Graphviz/DOT diagram support. See {@link GraphvizOptions}. */
     graphviz?: GraphvizOptions;
     /** Docusaurus plugin instance id, used when the plugin is registered more than once. */

package/dist/options.js

@@ -37,6 +37,7 @@ export const DEFAULT_OPTIONS = {
     renderTimeoutMs: 20_000,
     cacheMaxEntries: 50,
     zoom: true,
+    showSource: true,
     graphviz: DEFAULT_GRAPHVIZ_OPTIONS,
 };
 const CACHE_MODES = ['none', 'memory', 'session'];
@@ -189,6 +190,7 @@ export function resolveOptions(rawOptions) {
         'renderTimeoutMs',
         'cacheMaxEntries',
         'zoom',
+        'showSource',
         'graphviz',
         // Docusaurus injects `id` for multi-instance plugins.
         'id',
@@ -227,5 +229,6 @@ export function resolveOptions(rawOptions) {
         renderTimeoutMs: validateRenderTimeout(rawOptions.renderTimeoutMs),
         cacheMaxEntries: validateCacheMaxEntries(rawOptions.cacheMaxEntries),
         zoom: validateBoolean(rawOptions.zoom, 'zoom', DEFAULT_OPTIONS.zoom),
+        showSource: validateBoolean(rawOptions.showSource, 'showSource', DEFAULT_OPTIONS.showSource),
     };
 }

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

@@ -29,7 +29,7 @@ export default function Code(props) {
     if (engine === null || source === null) {
         return _jsx(OriginalCode, { ...props });
     }
-    return (_jsx(PlantUmlDiagram, { source: source, title: parseTitle(props), language: language, engine: engine, layout: engine === 'graphviz' ? parseStringMeta(props, 'engine') : undefined, zoom: parseBooleanMeta(props, 'zoom') }));
+    return (_jsx(PlantUmlDiagram, { source: source, title: parseTitle(props), language: language, engine: engine, layout: engine === 'graphviz' ? parseStringMeta(props, 'engine') : undefined, zoom: parseBooleanMeta(props, 'zoom'), showSource: parseBooleanMeta(props, 'showSource') }));
 }
 /**
  * Decides which engine — if either — owns this fence.

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

@@ -19,6 +19,11 @@ export interface PlantUmlDiagramProps {
      * Set from the fence metastring: `zoom` or `zoom=false`.
      */
     zoom?: boolean;
+    /**
+     * Overrides the `showSource` plugin option for this diagram. `undefined` follows the option.
+     * Set from the fence metastring: `showSource` or `showSource=false`.
+     */
+    showSource?: boolean;
 }
 /**
  * Renders one diagram in the browser, with either engine.
@@ -30,4 +35,4 @@ export interface PlantUmlDiagramProps {
  * 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, engine, layout, zoom: zoomProp, }: PlantUmlDiagramProps): ReactNode;
+export default function PlantUmlDiagram({ source, title, language, engine, layout, zoom: zoomProp, showSource: showSourceProp, }: PlantUmlDiagramProps): ReactNode;

package/dist/theme/PlantUmlDiagram/index.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useEffect, useId, useRef, useState } from 'react';
+import { useCallback, useEffect, useId, useRef, useState } from 'react';
 import { useColorMode } from '@docusaurus/theme-common';
 import { DATA_ATTR } from '../../constants.js';
 import { getSharedCache } from '../../runtime/cache.js';
@@ -19,6 +19,8 @@ const ENGINE_LABEL = {
 };
 /** Margin large enough that a diagram is usually ready by the time it is scrolled into view. */
 const LAZY_ROOT_MARGIN = '300px';
+/** How long the copy result stays on screen before the control goes quiet again. */
+const COPY_FEEDBACK_MS = 2_000;
 const INITIAL_STATE = { status: 'idle', svg: null, error: null };
 function escapeHtml(value) {
     return value
@@ -44,11 +46,12 @@ function messageFor(error) {
  * 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, engine = 'plantuml', layout, zoom: zoomProp, }) {
+export default function PlantUmlDiagram({ source, title, language, engine = 'plantuml', layout, zoom: zoomProp, showSource: showSourceProp, }) {
     const config = usePlantUmlConfig();
     const { colorMode } = useColorMode();
     const containerRef = useRef(null);
     const hintId = useId();
+    const sourcePanelId = useId();
     const themeOption = config?.options.theme ?? 'auto';
     const dark = themeOption === 'auto' ? colorMode === 'dark' : themeOption === 'dark';
     const lazy = config?.options.lazy ?? true;
@@ -62,8 +65,39 @@ export default function PlantUmlDiagram({ source, title, language, engine = 'pla
     const renderDark = engine === 'graphviz' ? false : dark;
     // A fence flag wins over the plugin option, which in turn wins over the built-in default.
     const interactive = zoomProp ?? config?.options.zoom ?? true;
+    const sourceAvailable = showSourceProp ?? config?.options.showSource ?? true;
     const [state, setState] = useState(INITIAL_STATE);
     const [inView, setInView] = useState(!lazy);
+    const [sourceOpen, setSourceOpen] = useState(false);
+    const [copyState, setCopyState] = useState('idle');
+    const copyTimer = useRef(undefined);
+    // A pending "Copied" message must not fire into an unmounted component.
+    useEffect(() => () => clearTimeout(copyTimer.current), []);
+    /**
+     * Copies the source, and says whether it worked.
+     *
+     * `navigator.clipboard` is undefined outside a secure context, which a documentation site
+     * served over plain HTTP genuinely is. Reporting that plainly is better than a control that
+     * silently does nothing — the panel is open, so the reader can still select the text.
+     */
+    const copySource = useCallback(() => {
+        const settle = (next) => {
+            setCopyState(next);
+            clearTimeout(copyTimer.current);
+            copyTimer.current = setTimeout(() => setCopyState('idle'), COPY_FEEDBACK_MS);
+        };
+        const clipboard = typeof navigator === 'undefined' ? undefined : navigator.clipboard;
+        if (typeof clipboard?.writeText !== 'function') {
+            settle('failed');
+            return;
+        }
+        void clipboard.writeText(source).then(() => settle('copied'), () => settle('failed'));
+    }, [source]);
+    // A diagram whose source changed is a different diagram: an open panel would otherwise keep
+    // showing the old text's copy result, and the reader would have no idea it was stale.
+    useEffect(() => {
+        setCopyState('idle');
+    }, [source]);
     // Called unconditionally, as hooks must be; it attaches nothing when not interactive.
     const zoom = useZoomPan({
         enabled: interactive && state.status === 'ready',
@@ -167,16 +201,29 @@ export default function PlantUmlDiagram({ source, title, language, engine = 'pla
     const busy = state.status === 'loading' || state.status === 'rendering';
     // The sanitized SVG always lives in this element, zoomable or not, so `role="img" > svg`
     // stays a stable contract for tests and for author CSS.
-    const canvas = state.svg !== null && (_jsx("div", { className: styles.canvas, role: "img", "aria-label": label, 
+    const canvas = state.svg !== null && (_jsx("div", { className: !interactive && sourceOpen ? `${styles.canvas} ${styles.hiddenView}` : styles.canvas, role: "img", "aria-label": label, 
         // Sanitized above unless `sanitizeSvg: false` was explicitly opted into.
         dangerouslySetInnerHTML: { __html: state.svg } }));
+    const copyControl = sourceAvailable && sourceOpen && state.status === 'ready' && (_jsx("button", { type: "button", className: `${styles.toolbarButton} ${styles.toolbarTextButton}`, "aria-label": `Copy ${engineName} source to clipboard`, onClick: copySource, children: "Copy" }));
+    const sourceToggle = sourceAvailable && (_jsx("button", { type: "button", className: styles.toolbarButton, "aria-label": sourceOpen ? 'Hide diagram source' : 'Show diagram source', "aria-expanded": sourceOpen, "aria-controls": sourcePanelId, onClick: () => setSourceOpen((open) => !open), children: _jsx("span", { "aria-hidden": "true", children: '</>' }) }));
+    /**
+     * The source *replaces the diagram in its own frame* rather than appearing beneath it.
+     *
+     * Below the diagram it had two failure modes that the frame removes by construction: a
+     * diagram taller than the window pushed the panel off-screen, so the control looked broken;
+     * and while maximized the panel was painted behind the `position: fixed` overlay, so it was
+     * invisible however far you scrolled. Living in the same box as the picture, it is visible
+     * exactly when and where the picture was.
+     */
+    const sourceView = sourceAvailable && sourceOpen && state.status === 'ready' && (_jsxs("div", { className: styles.sourceView, id: sourcePanelId, children: [_jsxs("div", { className: styles.sourceViewBar, children: [_jsxs("span", { className: styles.sourceViewTitle, children: [engineName, " source"] }), _jsxs("span", { className: styles.copyStatus, role: "status", children: [copyState === 'copied' ? 'Copied to clipboard' : null, copyState === 'failed' ? 'Could not copy — select the text instead' : null] })] }), _jsx("pre", { className: styles.sourceCode, children: source })] }));
     return (_jsxs("figure", { ref: containerRef, className: styles.figure, "aria-busy": busy || undefined, [DATA_ATTR.diagram]: language ?? engine,
         [DATA_ATTR.engine]: engine,
         ...(engine === 'graphviz' ? { [DATA_ATTR.layout]: resolvedLayout } : {}),
         [DATA_ATTR.status]: state.status,
         [DATA_ATTR.theme]: dark ? 'dark' : 'light',
         ...(interactive ? { [DATA_ATTR.interactive]: 'true' } : {}),
-        ...(zoom.maximized ? { [DATA_ATTR.maximized]: 'true' } : {}), children: [state.status === 'ready' && state.svg !== null && !interactive && canvas, state.status === 'ready' && state.svg !== null && interactive && (_jsxs("div", { ref: zoom.stageRef, className: zoom.maximized ? `${styles.stage} ${styles.maximized}` : styles.stage, children: [_jsx("div", { ref: zoom.viewportRef, className: styles.viewport, tabIndex: 0, "aria-describedby": hintId, "aria-keyshortcuts": "Plus Minus 0 ArrowUp ArrowDown ArrowLeft ArrowRight", onKeyDown: zoom.onKeyDown, [DATA_ATTR.zoom]: '1', children: _jsx("div", { ref: zoom.layerRef, className: styles.layer, children: canvas }) }), _jsxs("div", { className: styles.toolbar, role: "group", "aria-label": `${label} zoom controls`, children: [_jsx("button", { type: "button", className: styles.toolbarButton, "aria-label": "Zoom out", onClick: zoom.zoomOut, children: _jsx("span", { "aria-hidden": "true", children: "\u2212" }) }), _jsx("button", { type: "button", className: styles.toolbarButton, "aria-label": "Zoom in", onClick: zoom.zoomIn, children: _jsx("span", { "aria-hidden": "true", children: "+" }) }), _jsx("button", { type: "button", className: styles.toolbarButton, "aria-label": "Reset zoom", onClick: zoom.reset, children: _jsx("span", { "aria-hidden": "true", children: "\u27F2" }) }), _jsx("button", { type: "button", className: styles.toolbarButton, "aria-label": "Maximize diagram", "aria-pressed": zoom.maximized, onClick: zoom.toggleMaximize, children: _jsx("span", { "aria-hidden": "true", children: zoom.maximized ? '✕' : '⛶' }) }), _jsx("span", { ref: zoom.readoutRef, className: styles.readout, "aria-hidden": "true", children: "100%" })] })] })), state.status === 'ready' && state.svg !== null && interactive && (_jsx("p", { id: hintId, className: styles.visuallyHidden, children: "Zoomable diagram. Use the zoom controls, or press plus and minus to zoom, the arrow keys to pan, and zero to reset." })), state.status !== 'ready' && state.status !== 'error' && (
+        ...(zoom.maximized ? { [DATA_ATTR.maximized]: 'true' } : {}),
+        ...(sourceOpen ? { [DATA_ATTR.sourceOpen]: 'true' } : {}), children: [state.status === 'ready' && state.svg !== null && !interactive && canvas, state.status === 'ready' && state.svg !== null && !interactive && sourceView, state.status === 'ready' && state.svg !== null && !interactive && sourceAvailable && (_jsxs("div", { className: styles.plainToolbar, role: "group", "aria-label": `${label} source controls`, children: [sourceToggle, copyControl] })), state.status === 'ready' && state.svg !== null && interactive && (_jsxs("div", { ref: zoom.stageRef, className: zoom.maximized ? `${styles.stage} ${styles.maximized}` : styles.stage, children: [_jsxs("div", { className: styles.stageBody, children: [_jsx("div", { ref: zoom.viewportRef, className: sourceOpen ? `${styles.viewport} ${styles.invisibleView}` : styles.viewport, tabIndex: sourceOpen ? -1 : 0, "aria-describedby": hintId, "aria-keyshortcuts": "Plus Minus 0 ArrowUp ArrowDown ArrowLeft ArrowRight", onKeyDown: zoom.onKeyDown, [DATA_ATTR.zoom]: '1', children: _jsx("div", { ref: zoom.layerRef, className: styles.layer, children: canvas }) }), sourceView] }), _jsxs("div", { className: styles.toolbar, role: "group", "aria-label": `${label} zoom controls`, children: [!sourceOpen && (_jsx("button", { type: "button", className: styles.toolbarButton, "aria-label": "Zoom out", onClick: zoom.zoomOut, children: _jsx("span", { "aria-hidden": "true", children: "\u2212" }) })), !sourceOpen && (_jsx("button", { type: "button", className: styles.toolbarButton, "aria-label": "Zoom in", onClick: zoom.zoomIn, children: _jsx("span", { "aria-hidden": "true", children: "+" }) })), !sourceOpen && (_jsx("button", { type: "button", className: styles.toolbarButton, "aria-label": "Reset zoom", onClick: zoom.reset, children: _jsx("span", { "aria-hidden": "true", children: "\u27F2" }) })), _jsx("button", { type: "button", className: styles.toolbarButton, "aria-label": "Maximize diagram", "aria-pressed": zoom.maximized, onClick: zoom.toggleMaximize, children: _jsx("span", { "aria-hidden": "true", children: zoom.maximized ? '✕' : '⛶' }) }), sourceToggle, copyControl, _jsx("span", { ref: zoom.readoutRef, className: sourceOpen ? `${styles.readout} ${styles.hiddenView}` : styles.readout, "aria-hidden": "true", children: "100%" })] })] })), state.status === 'ready' && state.svg !== null && interactive && (_jsx("p", { id: hintId, className: styles.visuallyHidden, children: "Zoomable diagram. Use the zoom controls, or press plus and minus to zoom, the arrow keys to pan, and zero to reset." })), 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 ${engineName} 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" }), _jsxs("span", { children: ["Error: ", engineName, " 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: {

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

@@ -291,3 +291,120 @@
   overflow-x: auto;
   font-size: 0.8125rem;
 }
+
+/*
+ * Source view.
+ *
+ * The source takes the diagram's place inside the same frame rather than appearing beneath it.
+ * Below the diagram it had two failure modes this removes by construction: a diagram taller
+ * than the window pushed it off-screen, and while maximized it was painted behind the
+ * `position: fixed` overlay. In the frame it is visible exactly where the picture was.
+ */
+
+/* One grid cell shared by the viewport and the source view, so they occupy the same box. */
+.stageBody {
+  position: relative;
+  display: grid;
+}
+
+.stageBody > * {
+  grid-area: 1 / 1;
+  /* Without this a wide <pre> would stretch the grid column instead of scrolling. */
+  min-width: 0;
+}
+
+/*
+ * `visibility`, not `display`: the hidden viewport keeps contributing its height, so the frame
+ * does not resize when flipping, and the zoom hook's layout measurements stay valid for the
+ * flip back. A `visibility: hidden` subtree is also not focusable and takes no pointer events,
+ * so the invisible diagram cannot be tabbed into or dragged.
+ */
+.invisibleView {
+  visibility: hidden;
+}
+
+/* Collapses entirely — used where there is no frame height worth preserving. */
+.hiddenView {
+  display: none;
+}
+
+/*
+ * Inside a zoom frame the source is taken out of flow so that it cannot size the grid row: the
+ * row stays exactly as tall as the (hidden but still laid-out) viewport, and a long source
+ * scrolls within it. Left in flow it grew the frame from the diagram's height to the source's —
+ * on a long diagram that pushed the text back off the bottom of the window, which is the very
+ * problem moving it into the frame was meant to solve.
+ */
+.stageBody .sourceView {
+  position: absolute;
+  inset: 0;
+}
+
+.sourceView {
+  display: flex;
+  flex-direction: column;
+  min-height: 0;
+  border: 1px solid var(--ifm-color-emphasis-300);
+  border-radius: var(--ifm-global-radius);
+  background: var(--ifm-background-surface-color);
+  overflow: hidden;
+}
+
+.sourceViewBar {
+  display: flex;
+  align-items: center;
+  flex-wrap: wrap;
+  gap: 0.5rem;
+  /* Clears the toolbar, which floats over the top-right of the same frame. */
+  padding: 0.5rem 12rem 0.25rem 0.75rem;
+}
+
+.sourceViewTitle {
+  color: var(--ifm-color-emphasis-700);
+  font-size: 0.8125rem;
+  font-weight: 600;
+}
+
+.copyStatus {
+  flex: 1;
+  color: var(--ifm-color-emphasis-700);
+  font-size: 0.75rem;
+  text-align: right;
+}
+
+/*
+ * The copy control is a toolbar button like the rest, just carrying a word instead of a glyph,
+ * so it needs width where the icon buttons are square.
+ */
+.toolbarTextButton {
+  width: auto;
+  padding: 0 0.5rem;
+  font-size: 0.8125rem;
+}
+
+.sourceCode {
+  flex: 1;
+  min-height: 0;
+  margin: 0;
+  padding: 0.75rem;
+  overflow: auto;
+  background: transparent;
+  font-size: 0.8125rem;
+  /* Wraps rather than scrolls sideways: diagram source is read, not just copied. */
+  white-space: pre-wrap;
+  word-break: break-word;
+}
+
+/*
+ * Without a zoom frame the source has no box to fill, so it needs a floor of its own — and a
+ * ceiling, so a long diagram cannot produce an endless wall of text.
+ */
+.figure:not([data-plantuml-interactive]) .sourceView {
+  max-height: 30rem;
+}
+
+.plainToolbar {
+  display: flex;
+  justify-content: flex-end;
+  margin-top: 0.25rem;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@matfsw/docusaurus-plantuml-plugin",
-  "version": "1.1.2",
+  "version": "1.2.0",
   "description": "Render PlantUML diagrams in Docusaurus 3 entirely in the browser - no Java, no PlantUML server, no CDN.",
   "keywords": [
     "docusaurus",