@matfsw/docusaurus-plantuml-plugin 1.6.0 → 1.6.1

package/CHANGELOG.md

@@ -7,6 +7,39 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.6.1] - 2026-08-21
+
+### Fixed
+
+- **A diagram that fits can now be dragged around the space beside it.** The viewport has always
+  shown a grab cursor, but content that fitted was pinned at the origin, so on anything short of
+  a magnified diagram the cursor promised something that did not happen. It was most obvious
+  maximized: a modest diagram is fitted into the top-left corner of the screen with room to
+  spare, and none of that room could be used.
+
+  `clampTransform` now bounds each axis by the empty space beside the picture,
+  `viewport - content × scale`, instead of pinning content that fits at the origin. The diagram
+  moves through that space and no further, so it can never leave the viewport, and a magnified
+  one still cannot be dragged until an edge comes inside it. Axes stay independent, so a wide,
+  short diagram pans sideways while moving only through what little vertical room it has, and
+  **Reset** puts everything back.
+
+  Note that *fitting* makes one axis flush with the screen by construction, so a freshly
+  maximized diagram slides only along the other one. Zoom out a step and it moves both ways.
+
+- **Dragging no longer marks the diagram's text.** `pointerdown` cannot `preventDefault()`
+  without breaking focus, links and double-click, so the browser anchored a text selection on
+  the first press — before the 3px drag threshold could tell a drag from a click. The labels
+  flashed blue for the whole gesture, a drag past the frame kept extending the selection across
+  the page, and it could not be cleared by clicking, because the click that ends a drag is the
+  one the component swallows so a drag over a link does not follow it.
+
+  The canvas inside a zoom viewport is now `user-select: none`, which removes the anchor rather
+  than trying to undo its effects. The text stays reachable where it is actually read: the `</>`
+  source view with Copy, the diagram search, and the browser's find-in-page. A diagram with
+  `zoom=false` is not a drag surface and is untouched; a site that wants the selection back can
+  say `[data-plantuml-diagram] svg {user-select: text}`.
+
 ## [1.6.0] - 2026-08-21
 
 ### Fixed
@@ -570,7 +603,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.6.0...HEAD
+[Unreleased]: https://github.com/matf/docusaurus-plantuml-plugin/compare/v1.6.1...HEAD
+[1.6.1]: https://github.com/matf/docusaurus-plantuml-plugin/compare/v1.6.0...v1.6.1
 [1.6.0]: https://github.com/matf/docusaurus-plantuml-plugin/compare/v1.5.2...v1.6.0
 [1.5.2]: https://github.com/matf/docusaurus-plantuml-plugin/compare/v1.5.1...v1.5.2
 [1.5.1]: https://github.com/matf/docusaurus-plantuml-plugin/compare/v1.5.0...v1.5.1

package/README.md

@@ -550,7 +550,7 @@ bottom-left corner: the reader asked for it, and it closes with its own ✕.
 | ----------------------------------- | -------------------------------------------------------------- |
 | Plain scroll wheel                  | Scrolls the page. Never intercepted.                           |
 | **Ctrl** + wheel, or trackpad pinch | Zooms about the pointer                                        |
-| Drag                                | Pans, once zoomed in                                           |
+| Drag                                | Moves the diagram, at any zoom level                           |
 | One finger on a touchscreen         | Scrolls the page                                               |
 | Two-finger pinch on a touchscreen   | The browser's own page zoom                                    |
 | Toolbar buttons                     | Zoom out, zoom in, reset, maximize — plus fit, while maximized |
@@ -581,11 +581,32 @@ working, and `Tab` always moves on — the diagram is never a keyboard trap.
 
 The toolbar buttons and the keyboard zoom about the **top-left corner** of the viewport, while
 the wheel zooms about the **pointer**. That difference is deliberate: a diagram rarely fills its
-viewport, and one that fits is left-aligned, so the empty space sits to its right and below.
+viewport, and one that fits opens at the origin, so the empty space sits to its right and below.
 Zooming about the centre would scale that empty space and push the diagram off the top and left
 edges — most visibly when maximized. Anchoring at the top-left grows the diagram into the empty
 space instead and keeps it visible as long as possible.
 
+### Moving the diagram
+
+Dragging moves the diagram **whatever the zoom level** — including a small one, and including a
+diagram that fits its frame whole. Maximize a modest diagram and it is fitted into a corner of
+the screen with room to spare; that space is now yours to move it into, rather than a grab
+cursor that did nothing.
+
+Text inside a zoomable diagram is **not selectable**, because the same box is the drag surface:
+the browser anchors a selection on the first press, before a drag can be told apart from a
+click, so dragging used to paint the labels blue and leave them that way. The text is still
+reachable everywhere it is actually read — the `</>` source view with its Copy button, the
+diagram search, and the browser's find-in-page. A diagram with `zoom=false` is not a drag
+surface and stays selectable, and a site that wants the selection back everywhere can say
+`[data-plantuml-diagram] svg {user-select: text}`.
+
+The rule in both directions is that the diagram stays reachable: it can never be dragged so far
+that an edge comes inside the viewport, and never so far that it leaves the viewport altogether.
+Where there is no room — a picture exactly as wide as its frame — it does not budge on that axis,
+so a wide, short diagram still pans sideways while staying put vertically. The arrow keys move it
+the same way, and **Reset** puts it back where it opened.
+
 Scale is limited to 0.25×–8×, and the view resets to 100% whenever the diagram source or the
 site colour mode changes.
 

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

@@ -90,13 +90,30 @@
 
 .viewport[data-plantuml-dragging='true'] {
   cursor: grabbing;
-  user-select: none;
 }
 
-/* Inside the viewport the SVG must not be clipped by the old scroll container. */
+/*
+ * Inside the viewport the SVG must not be clipped by the old scroll container — and its text
+ * is not selectable, because this box is a drag surface.
+ *
+ * Pressing on SVG text used to anchor a native selection: `pointerdown` deliberately does not
+ * `preventDefault()`, so that focus, links and double-click keep working, which means the
+ * browser starts selecting before the 3px drag threshold has been crossed. Marking the box
+ * unselectable once dragging began was too late — the anchor already existed, the labels
+ * flashed blue for the whole gesture, a drag past the edge kept extending the selection into
+ * the page, and the click that would normally collapse it is the very click a drag swallows.
+ * Removing the anchor removes all of that at once.
+ *
+ * The text stays reachable everywhere it was actually read: the `</>` source view (with Copy),
+ * this component's own search, and the browser's find-in-page, none of which need a selection.
+ * A diagram with `zoom=false` is not a drag surface and is left alone. A site that wants the
+ * old behaviour can say `[data-plantuml-diagram] svg {user-select: text}` — an attribute
+ * selector, so no hashed class name is needed.
+ */
 .viewport .canvas {
   display: block;
   overflow: visible;
+  user-select: none;
 }
 
 .layer {

package/dist/theme/PlantUmlDiagram/useZoomPan.js

@@ -27,9 +27,9 @@ export function useZoomPan({ enabled, resetKey }) {
      * Layout sizes, never `getBoundingClientRect()`: the layer's rect includes the transform we
      * 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}.
+     * picture's, not the full-width frame's; that is what lets fitting fill a maximized screen,
+     * keeps the minimap honest about where the diagram ends, and tells the clamp how much empty
+     * space a fitted diagram may be dragged into.
      */
     const measure = useCallback(() => {
         const viewport = viewportRef.current;
@@ -41,20 +41,6 @@ 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;
@@ -76,20 +62,26 @@ export function useZoomPan({ enabled, resetKey }) {
         };
     }, []);
     const getTransform = useCallback(() => transformRef.current, []);
+    /**
+     * Every gesture ends here, so the clamp is the single place that decides where a diagram may
+     * sit. It is handed the measured picture: the floor that keeps focal zoom honest lives inside
+     * {@link clampTransform}, applied to that end of the range only, so the other end can offer a
+     * fitted diagram the real empty space beside it.
+     */
     const apply = useCallback((next) => {
-        write(clampTransform(next, clampBounds()));
-    }, [clampBounds, write]);
+        write(clampTransform(next, measure()));
+    }, [measure, write]);
     const reset = useCallback(() => {
         apply(IDENTITY);
     }, [apply]);
     /**
      * Zooms about the viewport's top-left corner.
      *
-     * Not the centre: a diagram rarely fills its viewport, and a diagram that fits is
-     * left-aligned, so the empty space sits to its right and below. Zooming about the centre
-     * scales that empty space too and pushes the diagram off the top and left edges — most
-     * visibly when maximized. Anchoring at the top-left leaves a left-aligned diagram exactly
-     * where it is and grows it into the empty space, keeping it visible as long as possible.
+     * Not the centre: a diagram rarely fills its viewport, and one that fits opens at the origin,
+     * so the empty space sits to its right and below. Zooming about the centre scales that empty
+     * space too and pushes the diagram off the top and left edges — most visibly when maximized.
+     * Anchoring at the top-left leaves the diagram exactly where it is and grows it into the
+     * empty space, keeping it visible as long as possible.
      *
      * Wheel zoom still tracks the pointer, which is what direct manipulation should do.
      */
@@ -104,8 +96,8 @@ export function useZoomPan({ enabled, resetKey }) {
      *
      * 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.
+     * a fit to add. Translation returns to the origin: fitting is "show me all of it from the
+     * top", and the reader can drag it wherever they like from there.
      */
     const fit = useCallback(() => {
         apply({ ...IDENTITY, k: fitScale(measure()) });

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

@@ -42,12 +42,18 @@ export declare function clamp(value: number, min: number, max: number): number;
 export declare function zoomAbout(transform: Transform, factor: number, focalX: number, focalY: number, min?: number, max?: number): Transform;
 export declare function panBy(transform: Transform, dx: number, dy: number): Transform;
 /**
- * Keeps the diagram reachable: an edge can never be dragged inside the viewport, and content
- * that fits is left-aligned — matching the `justify-content: flex-start` behaviour diagrams
- * had before they became zoomable.
+ * Keeps the diagram reachable, in both directions, one axis at a time.
  *
- * The axes are clamped independently, so a wide, short diagram pans horizontally while staying
- * pinned vertically.
+ * The two ends of the range answer different questions, and are deliberately measured against
+ * different things — see {@link clampAxis}. Forwards, the limit is the *empty space* beside the
+ * picture: a diagram that fits can be moved through it but never out of the viewport. Content
+ * that fits used to be pinned at `0` outright, which left the reader with a grab cursor that
+ * moved nothing — most obviously while maximized, where a fitted diagram sits in a corner of a
+ * screen with room to spare. Backwards, the limit keeps a magnified diagram from being dragged
+ * until an edge comes inside the viewport.
+ *
+ * The axes are clamped independently, so a wide, short diagram pans horizontally while moving
+ * only through the little vertical space it has.
  */
 export declare function clampTransform(transform: Transform, bounds: Bounds): Transform;
 /**

package/dist/theme/PlantUmlDiagram/zoomMath.js

@@ -39,23 +39,45 @@ export function panBy(transform, dx, dy) {
     return { k: transform.k, x: transform.x + dx, y: transform.y + dy };
 }
 /**
- * Keeps the diagram reachable: an edge can never be dragged inside the viewport, and content
- * that fits is left-aligned — matching the `justify-content: flex-start` behaviour diagrams
- * had before they became zoomable.
+ * Keeps the diagram reachable, in both directions, one axis at a time.
  *
- * The axes are clamped independently, so a wide, short diagram pans horizontally while staying
- * pinned vertically.
+ * The two ends of the range answer different questions, and are deliberately measured against
+ * different things — see {@link clampAxis}. Forwards, the limit is the *empty space* beside the
+ * picture: a diagram that fits can be moved through it but never out of the viewport. Content
+ * that fits used to be pinned at `0` outright, which left the reader with a grab cursor that
+ * moved nothing — most obviously while maximized, where a fitted diagram sits in a corner of a
+ * screen with room to spare. Backwards, the limit keeps a magnified diagram from being dragged
+ * until an edge comes inside the viewport.
+ *
+ * The axes are clamped independently, so a wide, short diagram pans horizontally while moving
+ * only through the little vertical space it has.
  */
 export function clampTransform(transform, bounds) {
-    const scaledWidth = bounds.contentWidth * transform.k;
-    const scaledHeight = bounds.contentHeight * transform.k;
-    const x = scaledWidth <= bounds.viewportWidth
-        ? 0
-        : clamp(transform.x, bounds.viewportWidth - scaledWidth, 0);
-    const y = scaledHeight <= bounds.viewportHeight
-        ? 0
-        : clamp(transform.y, bounds.viewportHeight - scaledHeight, 0);
-    return { k: transform.k, x, y };
+    return {
+        k: transform.k,
+        x: clampAxis(transform.x, bounds.viewportWidth, bounds.contentWidth, transform.k),
+        y: clampAxis(transform.y, bounds.viewportHeight, bounds.contentHeight, transform.k),
+    };
+}
+/**
+ * One axis of the clamp.
+ *
+ * **Forwards** (positive translation) the picture may travel exactly as far as the empty space
+ * beside it, `viewport - content * k`, and no further — so it never leaves the viewport. Once
+ * the content overflows there is no empty space and the limit is `0`.
+ *
+ * **Backwards** the content size is floored at the viewport's *before* scaling. That looks odd
+ * until you zoom: focal zoom must hold the point under the pointer, and a picture narrower than
+ * its frame reaches a scale where it overflows while the pointer is still asking it to travel
+ * further left than a flush right edge allows. Clamping to the picture there yanks it sideways
+ * mid-gesture. The floor buys that fidelity for the price of some empty space at the right
+ * while zoomed, which is the trade this component has always made — it is only the *forward*
+ * limit, above, that had to stop being measured this way for a fitted diagram to move at all.
+ */
+function clampAxis(value, viewport, content, k) {
+    const forward = Math.max(0, viewport - content * k);
+    const backward = Math.min(0, viewport - Math.max(content, viewport) * k);
+    return clamp(value, backward, forward);
 }
 /** `WheelEvent.deltaMode` constants, which jsdom does not define. */
 const DELTA_PIXEL = 0;

package/package.json

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