@matfsw/docusaurus-plantuml-plugin 1.3.1 → 1.4.0

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.1",
+  "version": "1.4.0",
   "description": "Render PlantUML diagrams in Docusaurus 3 entirely in the browser - no Java, no PlantUML server, no CDN.",
   "keywords": [
     "docusaurus",