@matfsw/docusaurus-plantuml-plugin 1.3.0 → 1.4.0

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]);
+}

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

@@ -1,5 +1,5 @@
 import { type KeyboardEvent as ReactKeyboardEvent, type MutableRefObject } from 'react';
-import { MAX_SCALE, MIN_SCALE } from './zoomMath.js';
+import { MAX_SCALE, MIN_SCALE, type Bounds, type Transform } from './zoomMath.js';
 export interface ZoomPanHandle {
     viewportRef: MutableRefObject<HTMLDivElement | null>;
     layerRef: MutableRefObject<HTMLDivElement | null>;
@@ -8,10 +8,26 @@ export interface ZoomPanHandle {
     zoomIn: () => void;
     zoomOut: () => void;
     reset: () => void;
+    /** Fits the whole diagram inside the viewport, at whatever scale that takes to fill it. */
+    fit: () => void;
     toggleMaximize: () => void;
     onKeyDown: (event: ReactKeyboardEvent<HTMLDivElement>) => void;
     /** Whether the diagram currently fills the browser viewport. */
     maximized: boolean;
+    /** Reads the live transform without subscribing to it. */
+    getTransform: () => Transform;
+    /** Applies a transform through the same clamp as every gesture. */
+    applyTransform: (next: Transform) => void;
+    /** Layout sizes of the viewport and content — the bounds the clamp runs against. */
+    measure: () => Bounds;
+    /**
+     * Calls the listener after every committed transform write; returns the unsubscribe.
+     *
+     * This is how the minimap tracks the view: the transform is written straight to the DOM on
+     * every pan frame, so anything that mirrored it through React state would re-render the
+     * component once per frame.
+     */
+    subscribe: (listener: (transform: Transform) => void) => () => void;
 }
 export interface UseZoomPanParams {
     enabled: boolean;

package/dist/theme/PlantUmlDiagram/useZoomPan.js

@@ -1,4 +1,4 @@
-import { useCallback, useEffect, useRef, useState, } from 'react';
+import { useCallback, useEffect, useMemo, useRef, useState, } from 'react';
 import { clampTransform, fitScale, formatPercent, formatZoom, IDENTITY, MAX_SCALE, MIN_SCALE, normalizeWheelDelta, panBy, PAN_STEP, SCALE_STEP, toCssTransform, wheelZoomFactor, zoomAbout, } from './zoomMath.js';
 /**
  * Zoom, pan and maximize for one diagram.
@@ -19,12 +19,17 @@ export function useZoomPan({ enabled, resetKey }) {
     const readoutRef = useRef(null);
     const [maximized, setMaximized] = useState(false);
     const transformRef = useRef(IDENTITY);
+    const listenersRef = useRef(new Set());
     /** The view to restore when the diagram is un-maximized. */
     const beforeMaximizeRef = useRef(null);
     const frameRef = useRef(null);
     /**
      * Layout sizes, never `getBoundingClientRect()`: the layer's rect includes the transform we
-     * are about to change, which would feed back into the next measurement.
+     * are about to change — and, mid-easing, the transition — which would feed back into the
+     * next measurement. The layer is `width: fit-content`, so its layout size *is* the rendered
+     * picture's, not the full-width frame's; that is what lets fitting fill a maximized screen
+     * and keeps the minimap honest about where the diagram ends. The clamp deliberately runs
+     * against wider bounds — see {@link clampBounds}.
      */
     const measure = useCallback(() => {
         const viewport = viewportRef.current;
@@ -36,6 +41,20 @@ export function useZoomPan({ enabled, resetKey }) {
             contentHeight: layer?.offsetHeight ?? 0,
         };
     }, []);
+    /**
+     * The bounds the clamp runs against: the picture or the viewport, whichever is *wider*.
+     *
+     * Fitting wants the true picture size; the clamp deliberately does not. Focal zoom must
+     * hold the point under the pointer even when that slides the picture's right edge inside
+     * the viewport — clamping to the picture itself yanks the diagram sideways mid-gesture the
+     * moment that edge is reached. Flooring the width at the viewport's restores exactly the
+     * geometry the full-width layer always gave. Height is not floored: the layer never
+     * stretched vertically, so the height clamp has always run against the real picture.
+     */
+    const clampBounds = useCallback(() => {
+        const bounds = measure();
+        return { ...bounds, contentWidth: Math.max(bounds.contentWidth, bounds.viewportWidth) };
+    }, [measure]);
     const write = useCallback((next) => {
         transformRef.current = next;
         const layer = layerRef.current;
@@ -47,10 +66,19 @@ export function useZoomPan({ enabled, resetKey }) {
         const readout = readoutRef.current;
         if (readout)
             readout.textContent = formatPercent(next.k);
+        for (const listener of listenersRef.current)
+            listener(next);
+    }, []);
+    const subscribe = useCallback((listener) => {
+        listenersRef.current.add(listener);
+        return () => {
+            listenersRef.current.delete(listener);
+        };
     }, []);
+    const getTransform = useCallback(() => transformRef.current, []);
     const apply = useCallback((next) => {
-        write(clampTransform(next, measure()));
-    }, [measure, write]);
+        write(clampTransform(next, clampBounds()));
+    }, [clampBounds, write]);
     const reset = useCallback(() => {
         apply(IDENTITY);
     }, [apply]);
@@ -70,6 +98,18 @@ export function useZoomPan({ enabled, resetKey }) {
     }, [apply]);
     const zoomIn = useCallback(() => zoomByStep(SCALE_STEP), [zoomByStep]);
     const zoomOut = useCallback(() => zoomByStep(1 / SCALE_STEP), [zoomByStep]);
+    /**
+     * The fitted view maximizing opens with: the diagram scaled to fill the screen, magnified
+     * or shrunk as the picture demands, capped at {@link MAX_SCALE}.
+     *
+     * Only offered while maximized. Inline it would duplicate Reset, because the inline frame
+     * grows with the diagram — at 100% everything is already visible, so there is nothing for
+     * a fit to add. Translation returns to the origin because a diagram that fits is
+     * left-aligned, exactly as `clampTransform` would force anyway.
+     */
+    const fit = useCallback(() => {
+        apply({ ...IDENTITY, k: fitScale(measure()) });
+    }, [apply, measure]);
     const toggleMaximize = useCallback(() => {
         setMaximized((previous) => !previous);
     }, []);
@@ -309,7 +349,10 @@ export function useZoomPan({ enabled, resetKey }) {
         if (!enabled)
             setMaximized(false);
     }, [enabled]);
-    return {
+    // One stable object per set of values: consumers hang effects off the handle (the search
+    // hook, the minimap), and an object recreated every render would re-run all of them — with
+    // visible consequences, such as a search that resets to its first match on any re-render.
+    return useMemo(() => ({
         stageRef,
         viewportRef,
         layerRef,
@@ -317,9 +360,26 @@ export function useZoomPan({ enabled, resetKey }) {
         zoomIn,
         zoomOut,
         reset,
+        fit,
+        toggleMaximize,
+        onKeyDown,
+        maximized,
+        getTransform,
+        applyTransform: apply,
+        measure,
+        subscribe,
+    }), [
+        zoomIn,
+        zoomOut,
+        reset,
+        fit,
         toggleMaximize,
         onKeyDown,
         maximized,
-    };
+        getTransform,
+        apply,
+        measure,
+        subscribe,
+    ]);
 }
 export { MAX_SCALE, MIN_SCALE };

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

@@ -67,6 +67,34 @@ export declare function wheelZoomFactor(normalizedDelta: number): number;
  * `max`, and never below {@link MIN_SCALE}.
  */
 export declare function fitScale(bounds: Bounds, max?: number): number;
+export interface Rect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * Scale of the minimap image: the largest scale that fits the content into the given box,
+ * but never past 1 — a small diagram is shown at its own size, not blown up into a blurrier
+ * copy of itself sitting next to the original.
+ *
+ * Returns 0 when there is nothing to draw, which callers treat as "no minimap".
+ */
+export declare function minimapScale(bounds: Bounds, maxWidth: number, maxHeight: number): number;
+/**
+ * The part of the content the viewport currently shows, in content coordinates.
+ *
+ * Clamped to the content box, so the minimap's viewport rectangle can never poke outside the
+ * picture — not even mid-gesture, when the transform itself may be momentarily out of range.
+ */
+export declare function visibleContentRect(transform: Transform, bounds: Bounds): Rect;
+/**
+ * The transform that centres the viewport on a content point, at the current scale.
+ *
+ * Deliberately unclamped: callers apply it through the same clamp as every gesture, which
+ * pins edge cases exactly the way the end of a drag is pinned.
+ */
+export declare function centerViewportOn(transform: Transform, contentX: number, contentY: number, bounds: Bounds): Transform;
 export declare function toCssTransform(transform: Transform): string;
 /** Machine-readable scale for `data-plantuml-zoom`, used by tests and author CSS. */
 export declare function formatZoom(scale: number): string;

package/dist/theme/PlantUmlDiagram/zoomMath.js

@@ -94,6 +94,48 @@ export function fitScale(bounds, max = MAX_SCALE) {
         return 1;
     return clamp(scale, MIN_SCALE, max);
 }
+/**
+ * Scale of the minimap image: the largest scale that fits the content into the given box,
+ * but never past 1 — a small diagram is shown at its own size, not blown up into a blurrier
+ * copy of itself sitting next to the original.
+ *
+ * Returns 0 when there is nothing to draw, which callers treat as "no minimap".
+ */
+export function minimapScale(bounds, maxWidth, maxHeight) {
+    if (bounds.contentWidth <= 0 || bounds.contentHeight <= 0)
+        return 0;
+    const scale = Math.min(maxWidth / bounds.contentWidth, maxHeight / bounds.contentHeight, 1);
+    return Number.isFinite(scale) && scale > 0 ? scale : 0;
+}
+/**
+ * The part of the content the viewport currently shows, in content coordinates.
+ *
+ * Clamped to the content box, so the minimap's viewport rectangle can never poke outside the
+ * picture — not even mid-gesture, when the transform itself may be momentarily out of range.
+ */
+export function visibleContentRect(transform, bounds) {
+    const width = Math.min(bounds.viewportWidth / transform.k, bounds.contentWidth);
+    const height = Math.min(bounds.viewportHeight / transform.k, bounds.contentHeight);
+    return {
+        x: clamp(-transform.x / transform.k, 0, Math.max(0, bounds.contentWidth - width)),
+        y: clamp(-transform.y / transform.k, 0, Math.max(0, bounds.contentHeight - height)),
+        width,
+        height,
+    };
+}
+/**
+ * The transform that centres the viewport on a content point, at the current scale.
+ *
+ * Deliberately unclamped: callers apply it through the same clamp as every gesture, which
+ * pins edge cases exactly the way the end of a drag is pinned.
+ */
+export function centerViewportOn(transform, contentX, contentY, bounds) {
+    return {
+        k: transform.k,
+        x: bounds.viewportWidth / 2 - contentX * transform.k,
+        y: bounds.viewportHeight / 2 - contentY * transform.k,
+    };
+}
 /** Rounds away floating-point noise so repeated zoom in/out returns to exactly 1. */
 function tidy(value) {
     return Math.abs(value) < 1e-6 ? 0 : Math.round(value * 1e6) / 1e6;

package/package.json

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