@matfsw/docusaurus-plantuml-plugin 1.3.1 → 1.4.0

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

@@ -24,10 +24,23 @@ export declare function ZoomOutIcon(): ReactElement;
 export declare function ZoomInIcon(): ReactElement;
 /** Replaces `⟲` U+27F2: a circular arrow, open at the top right where the arrowhead sits. */
 export declare function ResetZoomIcon(): ReactElement;
+/**
+ * Fit to view: the maximize corners with the diagram drawn inside them, so the two controls
+ * read as siblings — both are about the frame, one keeps you in the page.
+ */
+export declare function FitIcon(): ReactElement;
 /** Replaces `⛶` U+26F6, the character that had no glyph. */
 export declare function MaximizeIcon(): ReactElement;
 /** Replaces `✕` U+2715, shown in place of maximize while the diagram fills the viewport. */
 export declare function CloseIcon(): ReactElement;
+/** The search toggle: a lens. */
+export declare function SearchIcon(): ReactElement;
+/** Previous search match. */
+export declare function ChevronUpIcon(): ReactElement;
+/** Next search match. */
+export declare function ChevronDownIcon(): ReactElement;
+/** The minimap toggle: a map frame with the viewport rectangle marked inside it. */
+export declare function MinimapIcon(): ReactElement;
 /**
  * Replaces the literal `</>` of the source toggle.
  *

package/dist/theme/PlantUmlDiagram/icons.js

@@ -24,6 +24,13 @@ export function ZoomInIcon() {
 export function ResetZoomIcon() {
     return (_jsxs("svg", { ...iconProps, children: [_jsx("path", { d: "M13 8A5 5 0 1 1 11.4 4.3" }), _jsx("path", { d: "M13 2v3h-3" })] }));
 }
+/**
+ * Fit to view: the maximize corners with the diagram drawn inside them, so the two controls
+ * read as siblings — both are about the frame, one keeps you in the page.
+ */
+export function FitIcon() {
+    return (_jsxs("svg", { ...iconProps, children: [_jsx("path", { d: "M2 6V2h4M14 6V2h-4M2 10v4h4M14 10v4h-4" }), _jsx("rect", { x: "5.5", y: "5.5", width: "5", height: "5", rx: "1" })] }));
+}
 /** Replaces `⛶` U+26F6, the character that had no glyph. */
 export function MaximizeIcon() {
     return (_jsx("svg", { ...iconProps, children: _jsx("path", { d: "M2 6V2h4M14 6V2h-4M2 10v4h4M14 10v4h-4" }) }));
@@ -32,6 +39,22 @@ export function MaximizeIcon() {
 export function CloseIcon() {
     return (_jsx("svg", { ...iconProps, children: _jsx("path", { d: "M4 4l8 8M12 4l-8 8" }) }));
 }
+/** The search toggle: a lens. */
+export function SearchIcon() {
+    return (_jsxs("svg", { ...iconProps, children: [_jsx("circle", { cx: "7", cy: "7", r: "4" }), _jsx("path", { d: "M10 10l4 4" })] }));
+}
+/** Previous search match. */
+export function ChevronUpIcon() {
+    return (_jsx("svg", { ...iconProps, children: _jsx("path", { d: "M4 10l4-4 4 4" }) }));
+}
+/** Next search match. */
+export function ChevronDownIcon() {
+    return (_jsx("svg", { ...iconProps, children: _jsx("path", { d: "M4 6l4 4 4-4" }) }));
+}
+/** The minimap toggle: a map frame with the viewport rectangle marked inside it. */
+export function MinimapIcon() {
+    return (_jsxs("svg", { ...iconProps, children: [_jsx("rect", { x: "2", y: "3", width: "12", height: "10", rx: "1" }), _jsx("rect", { x: "4.5", y: "7.5", width: "4", height: "3", fill: "currentColor", stroke: "none" })] }));
+}
 /**
  * Replaces the literal `</>` of the source toggle.
  *

package/dist/theme/PlantUmlDiagram/index.js

@@ -1,5 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useCallback, useEffect, useId, useRef, useState } from 'react';
+import { useCallback, useEffect, useId, useMemo, useRef, useState, } from 'react';
+import { useLocation } from '@docusaurus/router';
 import { useColorMode } from '@docusaurus/theme-common';
 import { DATA_ATTR } from '../../constants.js';
 import { getSharedCache } from '../../runtime/cache.js';
@@ -7,7 +8,11 @@ import { PlantUmlError } from '../../runtime/errors.js';
 import { renderGraphvizDiagram } from '../../runtime/graphvizRenderer.js';
 import { renderDiagram } from '../../runtime/renderer.js';
 import { usePlantUmlConfig } from '../usePlantUmlConfig.js';
-import { CloseIcon, MaximizeIcon, ResetZoomIcon, SourceIcon, ZoomInIcon, ZoomOutIcon, } from './icons.js';
+import { ChevronDownIcon, ChevronUpIcon, CloseIcon, FitIcon, MaximizeIcon, MinimapIcon, ResetZoomIcon, SearchIcon, SourceIcon, ZoomInIcon, ZoomOutIcon, } from './icons.js';
+import { parseDiagramHash } from './deeplink.js';
+import Minimap from './Minimap.js';
+import { useDiagramDeeplink } from './useDiagramDeeplink.js';
+import { useDiagramSearch } from './useDiagramSearch.js';
 import { useZoomPan } from './useZoomPan.js';
 import styles from './styles.module.css';
 /**
@@ -50,6 +55,9 @@ function messageFor(error) {
 export default function PlantUmlDiagram({ source, title, language, engine = 'plantuml', layout, zoom: zoomProp, showSource: showSourceProp, }) {
     const config = usePlantUmlConfig();
     const { colorMode } = useColorMode();
+    // The router, not `window.location`: `<Link>` navigations are `history.pushState` calls
+    // that fire no DOM event, so only the router sees every way the hash can change.
+    const routerLocation = useLocation();
     const containerRef = useRef(null);
     const hintId = useId();
     const sourcePanelId = useId();
@@ -68,8 +76,12 @@ export default function PlantUmlDiagram({ source, title, language, engine = 'pla
     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);
+    // A diagram deep link must be able to reach a diagram below the fold, so a `#graph?…`
+    // hash defeats lazy rendering. The router's server-side location has no hash, and the
+    // first paint is the placeholder either way, so hydration cannot mismatch.
+    const [inView, setInView] = useState(() => !lazy || parseDiagramHash(routerLocation.hash) !== null);
     const [sourceOpen, setSourceOpen] = useState(false);
+    const [minimapOpen, setMinimapOpen] = useState(false);
     const [copyState, setCopyState] = useState('idle');
     const copyTimer = useRef(undefined);
     // A pending "Copied" message must not fire into an unmounted component.
@@ -107,6 +119,48 @@ export default function PlantUmlDiagram({ source, title, language, engine = 'pla
         // gratuitous jump.
         resetKey: `${source}|${engine}|${resolvedLayout}|${renderDark ? 'dark' : 'light'}`,
     });
+    const search = useDiagramSearch({
+        enabled: interactive && state.status === 'ready',
+        zoom,
+        svg: state.svg,
+    });
+    useDiagramDeeplink({
+        ready: state.status === 'ready' && state.svg !== null,
+        svg: state.svg,
+        interactive,
+        zoom,
+        containerRef,
+    });
+    // A hash arriving *after* mount must defeat lazy rendering too — a deep link followed
+    // from another diagram on the same page may point below the fold. Driven by the router
+    // location rather than `hashchange`, which `<Link>` navigations never fire.
+    useEffect(() => {
+        if (!inView && parseDiagramHash(routerLocation.hash) !== null)
+            setInView(true);
+    }, [inView, routerLocation.hash]);
+    const searchToggleRef = useRef(null);
+    // Escape and the ✕ hand focus back to the toggle, so the keyboard is not left stranded on
+    // a control that just left the page.
+    const closeSearch = useCallback(() => {
+        search.close();
+        searchToggleRef.current?.focus();
+    }, [search]);
+    const onSearchKeyDown = useCallback((event) => {
+        if (event.key === 'Enter') {
+            event.preventDefault();
+            if (event.shiftKey)
+                search.previous();
+            else
+                search.next();
+        }
+        else if (event.key === 'Escape') {
+            event.preventDefault();
+            // Escape in the search closes the search. Without this, the document-level listener
+            // would also un-maximize the diagram in the same keystroke.
+            event.stopPropagation();
+            closeSearch();
+        }
+    }, [closeSearch, search]);
     useEffect(() => {
         if (!lazy || inView)
             return undefined;
@@ -201,11 +255,18 @@ export default function PlantUmlDiagram({ source, title, language, engine = 'pla
     ]);
     const label = title ?? `${engineName} diagram`;
     const busy = state.status === 'loading' || state.status === 'rendering';
+    /**
+     * One wrapper object per SVG string, not a fresh literal in the JSX: React 19 compares
+     * `dangerouslySetInnerHTML` by the wrapper's identity, not by `__html`, so an inline
+     * literal makes every re-render of the figure re-parse the whole SVG subtree — visibly
+     * so once anything marks the rendered elements, as the search's highlights do.
+     */
+    const svgHtml = useMemo(() => (state.svg === null ? null : { __html: state.svg }), [state.svg]);
     // 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: !interactive && sourceOpen ? `${styles.canvas} ${styles.hiddenView}` : styles.canvas, role: "img", "aria-label": label, 
+    const canvas = state.svg !== null && svgHtml !== 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 } }));
+        dangerouslySetInnerHTML: svgHtml }));
     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(SourceIcon, {}) }));
     /**
@@ -225,7 +286,11 @@ export default function PlantUmlDiagram({ source, title, language, engine = 'pla
         [DATA_ATTR.theme]: dark ? 'dark' : 'light',
         ...(interactive ? { [DATA_ATTR.interactive]: 'true' } : {}),
         ...(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(ZoomOutIcon, {}) })), !sourceOpen && (_jsx("button", { type: "button", className: styles.toolbarButton, "aria-label": "Zoom in", onClick: zoom.zoomIn, children: _jsx(ZoomInIcon, {}) })), !sourceOpen && (_jsx("button", { type: "button", className: styles.toolbarButton, "aria-label": "Reset zoom", onClick: zoom.reset, children: _jsx(ResetZoomIcon, {}) })), _jsx("button", { type: "button", className: styles.toolbarButton, "aria-label": "Maximize diagram", "aria-pressed": zoom.maximized, onClick: zoom.toggleMaximize, children: zoom.maximized ? _jsx(CloseIcon, {}) : _jsx(MaximizeIcon, {}) }), 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' && (
+        ...(sourceOpen ? { [DATA_ATTR.sourceOpen]: 'true' } : {}),
+        ...(minimapOpen ? { [DATA_ATTR.minimapOpen]: 'true' } : {}),
+        ...(search.open ? { [DATA_ATTR.searchOpen]: '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.controls, children: [search.open && !sourceOpen && (_jsxs("div", { className: styles.searchBar, role: "search", "aria-label": `${label} search`, children: [_jsx("input", { ref: search.inputRef, type: "text", className: styles.searchInput, placeholder: "Search diagram", "aria-label": "Search diagram text", value: search.query, onChange: (event) => search.setQuery(event.target.value), onKeyDown: onSearchKeyDown }), _jsx("span", { className: styles.searchCount, role: "status", children: search.matchCount === 0
+                                            ? '0/0'
+                                            : `${search.currentIndex + 1}/${search.matchCount}` }), _jsx("button", { type: "button", className: styles.toolbarButton, "aria-label": "Previous match", onClick: search.previous, children: _jsx(ChevronUpIcon, {}) }), _jsx("button", { type: "button", className: styles.toolbarButton, "aria-label": "Next match", onClick: search.next, children: _jsx(ChevronDownIcon, {}) }), _jsx("button", { type: "button", className: styles.toolbarButton, "aria-label": "Close search", onClick: closeSearch, children: _jsx(CloseIcon, {}) })] })), _jsxs("div", { className: styles.toolbar, role: "group", "aria-label": `${label} zoom controls`, children: [!sourceOpen && (_jsx("button", { ref: searchToggleRef, type: "button", className: styles.toolbarButton, "aria-label": "Search diagram", "aria-expanded": search.open, onClick: search.toggle, children: _jsx(SearchIcon, {}) })), !sourceOpen && (_jsx("button", { type: "button", className: styles.toolbarButton, "aria-label": "Zoom out", onClick: zoom.zoomOut, children: _jsx(ZoomOutIcon, {}) })), !sourceOpen && (_jsx("button", { type: "button", className: styles.toolbarButton, "aria-label": "Zoom in", onClick: zoom.zoomIn, children: _jsx(ZoomInIcon, {}) })), !sourceOpen && (_jsx("button", { type: "button", className: styles.toolbarButton, "aria-label": "Reset zoom", onClick: zoom.reset, children: _jsx(ResetZoomIcon, {}) })), !sourceOpen && zoom.maximized && (_jsx("button", { type: "button", className: styles.toolbarButton, "aria-label": "Fit diagram to screen", onClick: zoom.fit, children: _jsx(FitIcon, {}) })), _jsx("button", { type: "button", className: styles.toolbarButton, "aria-label": "Maximize diagram", "aria-pressed": zoom.maximized, onClick: zoom.toggleMaximize, children: zoom.maximized ? _jsx(CloseIcon, {}) : _jsx(MaximizeIcon, {}) }), sourceToggle, copyControl, _jsx("span", { ref: zoom.readoutRef, className: sourceOpen ? `${styles.readout} ${styles.hiddenView}` : styles.readout, "aria-hidden": "true", children: "100%" })] })] }), !sourceOpen && minimapOpen && (_jsx(Minimap, { svg: state.svg, zoom: zoom, onClose: () => setMinimapOpen(false) })), !sourceOpen && (_jsx("div", { className: styles.minimapBar, children: _jsx("button", { type: "button", className: styles.toolbarButton, "aria-label": minimapOpen ? 'Hide minimap' : 'Show minimap', "aria-expanded": minimapOpen, onClick: () => setMinimapOpen((open) => !open), children: _jsx(MinimapIcon, {}) }) }))] })), 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

@@ -82,6 +82,20 @@
 }
 
 .layer {
+  /*
+   * Shrinks to the rendered picture instead of stretching across the viewport. The zoom
+   * hook measures content through `offsetWidth`/`offsetHeight` — layout sizes, immune to
+   * both the transform and its transition — so this is what makes those measurements mean
+   * "the diagram" rather than "the full-width frame". Fitting (which fills the screen when
+   * maximized) and the minimap both read that measurement.
+   *
+   * `max-width` is load-bearing, not decoration: in intrinsic (`fit-content`) sizing the
+   * SVG's own `max-width: 100%` resolves against an indefinite width and is ignored, so
+   * without this cap a diagram wider than the column would blow the layer out to the SVG's
+   * intrinsic width and overflow the frame.
+   */
+  width: fit-content;
+  max-width: 100%;
   transform-origin: 0 0;
   transition: transform var(--plantuml-zoom-transition, 150ms) ease-out;
 }
@@ -91,10 +105,31 @@
   transition: none;
 }
 
-.toolbar {
+/*
+ * One flex row holds the search bar and the toolbar, so opening the search never needs to
+ * know how wide the toolbar happens to be — it simply takes the space to its left.
+ */
+.controls {
   position: absolute;
   top: 0.5rem;
   right: 0.5rem;
+  display: flex;
+  gap: 0.5rem;
+  align-items: flex-start;
+}
+
+.toolbar {
+  display: flex;
+  gap: 0.25rem;
+  align-items: center;
+  padding: 0.25rem;
+  border: 1px solid var(--ifm-color-emphasis-300);
+  border-radius: var(--ifm-global-radius);
+  background: var(--ifm-background-surface-color);
+  opacity: 0.92;
+}
+
+.searchBar {
   display: flex;
   gap: 0.25rem;
   align-items: center;
@@ -105,6 +140,66 @@
   opacity: 0.92;
 }
 
+.searchInput {
+  width: 10rem;
+  max-width: 40vw;
+  height: 1.75rem;
+  padding: 0 0.5rem;
+  border: 1px solid var(--ifm-color-emphasis-300);
+  border-radius: var(--ifm-global-radius);
+  /* Not `--ifm-background-color`: Infima defines it as `#0000` in light mode. */
+  background: var(--ifm-background-surface-color);
+  color: var(--ifm-font-color-base);
+  font-size: 0.8125rem;
+}
+
+.searchInput:focus-visible {
+  outline: 2px solid var(--ifm-color-primary);
+  outline-offset: 1px;
+}
+
+.searchCount {
+  min-width: 2.25rem;
+  color: var(--ifm-color-emphasis-700);
+  font-size: 0.75rem;
+  font-variant-numeric: tabular-nums;
+  text-align: center;
+}
+
+/*
+ * Search highlights, keyed on the attributes the search hook sets. Attribute + CSS rather
+ * than mutating the SVG string: the string is shared through the render cache, and a
+ * highlight must never leak into another figure showing the same diagram.
+ *
+ * These rules sit after the Graphviz `currentColor` retargeting above and tie on
+ * specificity, so source order is what makes the highlight win there too.
+ */
+.layer .canvas svg text[data-plantuml-search-match] {
+  fill: var(--ifm-color-primary);
+}
+
+.layer .canvas svg text[data-plantuml-search-current] {
+  fill: var(--ifm-color-danger-dark);
+  text-decoration: underline;
+}
+
+/*
+ * The node a `#graph?highlight-node=…` deep link resolved to.
+ *
+ * The attribute may sit on a text line itself, or on the group/anchor wrapping a whole node
+ * (Graphviz `g.node`, a PlantUML self-anchor), so both spellings are styled. Scoped to
+ * `.figure` rather than `.layer`: a diagram that opted out of zoom still highlights, it
+ * just cannot pan.
+ *
+ * Placed after the Graphviz `currentColor` retargeting, whose specificity these tie —
+ * source order is what makes the highlight win there.
+ */
+.figure .canvas svg text[data-plantuml-focused-node],
+.figure .canvas svg [data-plantuml-focused-node] text {
+  fill: var(--ifm-color-danger-dark);
+  text-decoration: underline;
+}
+
 .toolbarButton {
   display: flex;
   align-items: center;
@@ -169,6 +264,80 @@
   max-height: none;
 }
 
+/*
+ * Minimap.
+ *
+ * A small copy of the diagram, bottom-left where the toolbar is top-right, with a rectangle
+ * marking the visible part. The copy is laid out at the content's own width and scaled down
+ * as one block, so it keeps exactly the geometry of the real canvas and the rectangle's
+ * coordinates can be multiplied straight through.
+ */
+.minimapBar {
+  position: absolute;
+  bottom: 0.5rem;
+  left: 0.5rem;
+  display: flex;
+  padding: 0.25rem;
+  border: 1px solid var(--ifm-color-emphasis-300);
+  border-radius: var(--ifm-global-radius);
+  background: var(--ifm-background-surface-color);
+  opacity: 0.92;
+}
+
+.minimap {
+  position: absolute;
+  bottom: 3.25rem;
+  left: 0.5rem;
+  /*
+   * The close control sits *beside* the map, not floating over it: a wide, short diagram
+   * makes a map only a couple of buttons tall, and an overlaid control would cover — and
+   * steal presses from — the map's whole right end.
+   */
+  display: flex;
+  gap: 0.25rem;
+  align-items: flex-start;
+  max-width: calc(100% - 1rem);
+  padding: 0.25rem;
+  border: 1px solid var(--ifm-color-emphasis-300);
+  border-radius: var(--ifm-global-radius);
+  background: var(--ifm-background-surface-color);
+  opacity: 0.95;
+}
+
+.minimapCanvas {
+  position: relative;
+  max-width: 100%;
+  overflow: hidden;
+  cursor: crosshair;
+  /* The map pans the diagram; a drag on it must never scroll the page instead. */
+  touch-action: none;
+}
+
+.minimapLayer {
+  transform-origin: 0 0;
+  /* The map is one press-or-drag surface; its copy of the diagram must not eat the events. */
+  pointer-events: none;
+}
+
+.minimapLayer svg {
+  display: block;
+  max-width: 100%;
+  height: auto;
+}
+
+.minimapRect {
+  position: absolute;
+  border: 2px solid var(--ifm-color-primary);
+  background: color-mix(in srgb, var(--ifm-color-primary) 20%, transparent);
+  pointer-events: none;
+}
+
+.minimapClose {
+  flex: none;
+  width: 1.5rem;
+  height: 1.5rem;
+}
+
 .visuallyHidden {
   position: absolute;
   width: 1px;
@@ -182,7 +351,10 @@
 }
 
 @media (forced-colors: active) {
-  .toolbar {
+  .toolbar,
+  .searchBar,
+  .minimapBar,
+  .minimap {
     border-color: ButtonBorder;
   }
 
@@ -190,6 +362,12 @@
     border-color: ButtonBorder;
     color: ButtonText;
   }
+
+  /* `color-mix` resolves to nothing useful here; the outline alone must carry the meaning. */
+  .minimapRect {
+    border-color: Highlight;
+    background: transparent;
+  }
 }
 
 .placeholder {

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

@@ -0,0 +1,32 @@
+import { type MutableRefObject } from 'react';
+import type { ZoomPanHandle } from './useZoomPan.js';
+/**
+ * Makes one diagram react to `#graph?highlight-node=…` deep links.
+ *
+ * On a matching hash the target node is marked (`data-plantuml-focused-node`, styled from
+ * the stylesheet), the page scrolls to the first matching figure, and — when the diagram is
+ * zoomable — the view snaps to 100% centred on the node. A diagram without the node does
+ * nothing, which is what lets every diagram on the page react without any of them carrying
+ * an id.
+ *
+ * The hash comes from the router, not from a `hashchange` listener: Docusaurus `<Link>`
+ * navigations are `history.pushState` calls, which fire no `hashchange` — so a listener
+ * kept a stale hash whenever a link changed or dropped it while the page (and this
+ * component) stayed mounted, leaving the old node highlighted. `useLocation` re-renders on
+ * push, replace and pop alike, and native `#…` anchor clicks reach it too, via the
+ * `popstate` the browser fires for hash navigations.
+ *
+ * Highlighting is imperative for the same reason the search's is: the marked elements live
+ * in a `dangerouslySetInnerHTML` subtree React cannot render into.
+ */
+export interface UseDiagramDeeplinkParams {
+    /** Whether the diagram is rendered and its SVG is in the DOM. */
+    ready: boolean;
+    /** The rendered SVG string — a dependency, so a re-rendered picture is re-matched. */
+    svg: string | null;
+    /** Whether the diagram is zoomable; centring and the 100% snap need the viewport. */
+    interactive: boolean;
+    zoom: ZoomPanHandle;
+    containerRef: MutableRefObject<HTMLElement | null>;
+}
+export declare function useDiagramDeeplink({ ready, svg, interactive, zoom, containerRef, }: UseDiagramDeeplinkParams): void;

package/dist/theme/PlantUmlDiagram/useDiagramDeeplink.js

@@ -0,0 +1,54 @@
+import { useEffect } from 'react';
+import { useLocation } from '@docusaurus/router';
+import { DATA_ATTR } from '../../constants.js';
+import { claimDeeplinkScroll, findDeeplinkTarget, parseDiagramHash } from './deeplink.js';
+import { centerViewportOn } from './zoomMath.js';
+export function useDiagramDeeplink({ ready, svg, interactive, zoom, containerRef, }) {
+    const location = useLocation();
+    const target = parseDiagramHash(location.hash);
+    // One value per history entry. Undefined on entries the router did not create itself
+    // (native hash clicks, the initial load); those still differ in `target`, which the
+    // scroll claim includes.
+    const navigationKey = location.key ?? 'pop';
+    const pathname = location.pathname;
+    /**
+     * Marks, scrolls and centres. The cleanup unmarks, so a changed hash, a navigation that
+     * drops the hash and an unmounting diagram all sweep up through the same code path; a
+     * replaced SVG re-runs the effect (via `svg`) against the new elements.
+     *
+     * `navigationKey` is a dependency on purpose: following the same deep link again is a new
+     * history entry with an unchanged `target`, and it should scroll and re-centre again.
+     */
+    useEffect(() => {
+        if (!ready || target === null)
+            return undefined;
+        const figure = containerRef.current;
+        const canvas = figure?.querySelector('[role="img"]');
+        if (!figure || !canvas)
+            return undefined;
+        const match = findDeeplinkTarget(canvas, target);
+        if (!match)
+            return undefined;
+        for (const element of match.elements) {
+            element.setAttribute(DATA_ATTR.focusedNode, 'true');
+        }
+        claimDeeplinkScroll(`${navigationKey}|${pathname}|${target}`, figure);
+        if (interactive) {
+            const layer = zoom.layerRef.current;
+            if (layer) {
+                // The node's offset inside the layer, divided back by the current scale, is its
+                // position in content coordinates whatever the zoom was; the view then snaps to
+                // 100% centred there — the zoom level a deep link promises.
+                const transform = zoom.getTransform();
+                const layerBox = layer.getBoundingClientRect();
+                const box = match.anchor.getBoundingClientRect();
+                zoom.applyTransform(centerViewportOn({ k: 1, x: 0, y: 0 }, (box.left + box.width / 2 - layerBox.left) / transform.k, (box.top + box.height / 2 - layerBox.top) / transform.k, zoom.measure()));
+            }
+        }
+        return () => {
+            for (const element of match.elements) {
+                element.removeAttribute(DATA_ATTR.focusedNode);
+            }
+        };
+    }, [containerRef, interactive, navigationKey, pathname, ready, svg, target, zoom]);
+}

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

@@ -0,0 +1,37 @@
+import { type MutableRefObject } from 'react';
+import type { ZoomPanHandle } from './useZoomPan.js';
+/**
+ * Text search over one rendered diagram.
+ *
+ * The search runs against the *rendered SVG's* `<text>` elements rather than the diagram
+ * source: what the reader sees is what they are searching, and a match can be highlighted and
+ * panned to because it is a real element with a position. Matches are marked with data
+ * attributes and coloured from the stylesheet, so the SVG string itself — which the cache
+ * shares between diagrams — is never mutated.
+ *
+ * Highlighting is imperative for the same reason the zoom transform is: the elements live in
+ * a `dangerouslySetInnerHTML` subtree that React cannot render into. React state carries only
+ * what drives markup — the query, the match count and the current position.
+ */
+export interface DiagramSearchHandle {
+    /** Whether the search bar is shown. */
+    open: boolean;
+    query: string;
+    /** Number of `<text>` elements matching the query; 0 when the query is empty. */
+    matchCount: number;
+    /** Zero-based position of the current match, or -1 when there is none. */
+    currentIndex: number;
+    inputRef: MutableRefObject<HTMLInputElement | null>;
+    toggle: () => void;
+    close: () => void;
+    setQuery: (value: string) => void;
+    next: () => void;
+    previous: () => void;
+}
+export interface UseDiagramSearchParams {
+    enabled: boolean;
+    zoom: ZoomPanHandle;
+    /** The rendered SVG string — a dependency, so a re-rendered picture is re-searched. */
+    svg: string | null;
+}
+export declare function useDiagramSearch({ enabled, zoom, svg, }: UseDiagramSearchParams): DiagramSearchHandle;

package/dist/theme/PlantUmlDiagram/useDiagramSearch.js

@@ -0,0 +1,107 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { DATA_ATTR } from '../../constants.js';
+import { centerViewportOn } from './zoomMath.js';
+export function useDiagramSearch({ enabled, zoom, svg, }) {
+    const [open, setOpen] = useState(false);
+    const [query, setQuery] = useState('');
+    const [matchCount, setMatchCount] = useState(0);
+    const [currentIndex, setCurrentIndex] = useState(-1);
+    const matchesRef = useRef([]);
+    const inputRef = useRef(null);
+    const toggle = useCallback(() => setOpen((value) => !value), []);
+    const close = useCallback(() => setOpen(false), []);
+    const next = useCallback(() => {
+        setCurrentIndex((index) => {
+            const total = matchesRef.current.length;
+            return total === 0 ? -1 : (index + 1) % total;
+        });
+    }, []);
+    const previous = useCallback(() => {
+        setCurrentIndex((index) => {
+            const total = matchesRef.current.length;
+            return total === 0 ? -1 : (index - 1 + total) % total;
+        });
+    }, []);
+    // Typing should not require a second click after pressing the toggle.
+    useEffect(() => {
+        if (open)
+            inputRef.current?.focus();
+    }, [open]);
+    // A diagram that lost its zoom lost the viewport the search pans; the bar goes with it.
+    useEffect(() => {
+        if (!enabled)
+            setOpen(false);
+    }, [enabled]);
+    /**
+     * Finds and marks the matches. The effect's cleanup unmarks them, so closing the bar,
+     * changing the query and unmounting all sweep up through the same code path. A replaced
+     * SVG needs no sweeping — its marked elements left the document with it — but re-runs the
+     * effect (via `svg`) so the new elements are searched.
+     */
+    useEffect(() => {
+        if (!enabled || !open)
+            return undefined;
+        const layer = zoom.layerRef.current;
+        const needle = query.trim().toLowerCase();
+        if (!layer || needle === '') {
+            matchesRef.current = [];
+            setMatchCount(0);
+            setCurrentIndex(-1);
+            return undefined;
+        }
+        // `<text>` elements, not their tspans: a PlantUML label is one text element, and marking
+        // the whole label keeps the highlight readable instead of colouring a fragment.
+        const matches = Array.from(layer.querySelectorAll('svg text')).filter((element) => (element.textContent ?? '').toLowerCase().includes(needle));
+        matchesRef.current = matches;
+        for (const match of matches)
+            match.setAttribute(DATA_ATTR.searchMatch, 'true');
+        setMatchCount(matches.length);
+        // Every new query starts at its first match, exactly like the browser's own find bar.
+        setCurrentIndex(matches.length > 0 ? 0 : -1);
+        return () => {
+            matchesRef.current = [];
+            for (const match of matches)
+                match.removeAttribute(DATA_ATTR.searchMatch);
+        };
+    }, [enabled, open, query, svg, zoom]);
+    /**
+     * Marks the current match and centres the viewport on it.
+     *
+     * Declared after the match effect on purpose: effects run in order, so by the time this
+     * one reads `matchesRef` the list belongs to the current query. `query` and `svg` are
+     * dependencies because a new list can leave the index at 0 — unchanged — while element 0
+     * is a different match.
+     */
+    useEffect(() => {
+        if (!enabled || !open)
+            return undefined;
+        const target = currentIndex >= 0 ? matchesRef.current[currentIndex] : undefined;
+        if (!target)
+            return undefined;
+        target.setAttribute(DATA_ATTR.searchCurrent, 'true');
+        const layer = zoom.layerRef.current;
+        if (layer) {
+            // The match's offset inside the layer, both measured in the same transformed space,
+            // divided back by the scale — which yields content coordinates whatever the zoom is.
+            const transform = zoom.getTransform();
+            const layerBox = layer.getBoundingClientRect();
+            const box = target.getBoundingClientRect();
+            zoom.applyTransform(centerViewportOn(transform, (box.left + box.width / 2 - layerBox.left) / transform.k, (box.top + box.height / 2 - layerBox.top) / transform.k, zoom.measure()));
+        }
+        return () => target.removeAttribute(DATA_ATTR.searchCurrent);
+    }, [currentIndex, enabled, open, query, svg, zoom]);
+    // Stable per set of values, like the zoom handle: consumers may hang callbacks and
+    // effects off the handle, and those must not churn on unrelated re-renders.
+    return useMemo(() => ({
+        open,
+        query,
+        matchCount,
+        currentIndex,
+        inputRef,
+        toggle,
+        close,
+        setQuery,
+        next,
+        previous,
+    }), [open, query, matchCount, currentIndex, toggle, close, next, previous]);
+}