@matfsw/docusaurus-plantuml-plugin 1.0.0 → 1.0.2

package/CHANGELOG.md

@@ -7,6 +7,37 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.0.2]
+
+### Fixed
+
+- The zoom buttons and keyboard shortcuts now zoom about the viewport's top-left corner rather
+  than its centre. A diagram that fits its viewport is left-aligned, so the empty space is to
+  its right and below; zooming about the centre scaled that empty space and pushed the diagram
+  off the top and left edges, most visibly on a maximized diagram. Wheel zoom continues to
+  track the pointer.
+
+## [1.0.1]
+
+### Fixed
+
+- Maximizing a diagram no longer uses the Fullscreen API. It took the whole browser window
+  fullscreen in Firefox instead of presenting the diagram, and the `::backdrop` sits outside
+  the fullscreened element, so the page showed through behind a diagram with a transparent
+  background. The diagram now expands into an opaque in-page overlay that fills the browser
+  viewport, closed with the same button or <kbd>Escape</kbd>.
+- The maximize control is now available in every browser. It previously required
+  `Element.requestFullscreen()` and was hidden where that is missing, notably iOS Safari.
+
+### Added
+
+- `data-plantuml-maximized` on the figure while a diagram fills the viewport.
+
+### Changed
+
+- The fourth toolbar button is labelled `Maximize diagram` (was `Toggle fullscreen`) and
+  exposes `aria-pressed`. End-to-end tests selecting it by its accessible name need updating.
+
 ## [1.0.0]
 
 First stable release. The public surface — plugin options, fence metadata flags, the `data-*`
@@ -65,6 +96,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.0.0...HEAD
+[Unreleased]: https://github.com/matf/docusaurus-plantuml-plugin/compare/v1.0.2...HEAD
+[1.0.2]: https://github.com/matf/docusaurus-plantuml-plugin/compare/v1.0.1...v1.0.2
+[1.0.1]: https://github.com/matf/docusaurus-plantuml-plugin/compare/v1.0.0...v1.0.1
 [1.0.0]: https://github.com/matf/docusaurus-plantuml-plugin/compare/v0.1.0...v1.0.0
 [0.1.0]: https://github.com/matf/docusaurus-plantuml-plugin/releases/tag/v0.1.0

package/README.md

@@ -257,7 +257,7 @@ pannable by default, with a small control toolbar in the top-right corner.
 | Drag                                | Pans, once zoomed in                 |
 | 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, fullscreen |
+| Toolbar buttons                     | Zoom out, zoom in, reset, maximize   |
 
 `Cmd` + wheel is deliberately **not** intercepted: on macOS that is the browser's own page
 zoom, and taking it over would fight the platform.
@@ -277,9 +277,28 @@ The diagram viewport is focusable. Once focused:
 Keys with Ctrl, Cmd or Alt held are left to the browser, so shortcuts such as Ctrl + 0 keep
 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.
+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.
+
 Scale is limited to 0.25×–8×, and the view resets to 100% whenever the diagram source or the
 site colour mode changes.
 
+### Maximizing
+
+The fourth toolbar button expands the diagram to fill the browser viewport, fitted to the
+available space, over an opaque background. <kbd>Escape</kbd> or the same button restores it,
+along with whatever zoom level you had before.
+
+This is an in-page overlay rather than the Fullscreen API. `requestFullscreen()` takes the
+entire browser window fullscreen in Firefox instead of presenting the element, and its
+`::backdrop` sits outside the element so the page shows through behind the diagram. An overlay
+has neither problem, behaves identically in every browser, and needs no capability detection —
+so the control also works on iOS Safari, which has no element fullscreen at all.
+
 ### Turning it off
 
 Globally:
@@ -528,8 +547,6 @@ The runtime requires:
 - Pointer Events — required for drag-to-pan when `zoom` is enabled
 - `ResizeObserver` — optional; without it zoom still works, but the view is not re-clamped when
   the column is resized
-- `Element.requestFullscreen()` — optional; the fullscreen button is simply not rendered where
-  it is unavailable, which includes iOS Safari
 
 That is modern evergreen Chrome, Edge, Firefox and Safari. Internet Explorer is not
 supported and will not be.
@@ -774,8 +791,6 @@ package.
   the browser reports it as Ctrl + wheel.
 - **Zoom state is not persisted.** Navigating away and back, or switching colour mode, returns
   the diagram to 100%.
-- **No fullscreen on iOS Safari.** It does not implement `Element.requestFullscreen()`, so the
-  button is not shown there.
 
 ## Troubleshooting
 

package/dist/constants.d.ts

@@ -26,4 +26,6 @@ export declare const DATA_ATTR: {
      * the imperative zoom writes can never race React's attribute diffing.
      */
     readonly zoom: "data-plantuml-zoom";
+    /** `"true"` on the figure while the diagram fills the browser viewport. */
+    readonly maximized: "data-plantuml-maximized";
 };

package/dist/constants.js

@@ -28,4 +28,6 @@ export const DATA_ATTR = {
      * the imperative zoom writes can never race React's attribute diffing.
      */
     zoom: 'data-plantuml-zoom',
+    /** `"true"` on the figure while the diagram fills the browser viewport. */
+    maximized: 'data-plantuml-maximized',
 };

package/dist/theme/PlantUmlDiagram/index.js

@@ -138,7 +138,8 @@ export default function PlantUmlDiagram({ source, title, language, zoom: zoomPro
     return (_jsxs("figure", { ref: containerRef, className: styles.figure, "aria-busy": busy || undefined, [DATA_ATTR.diagram]: language ?? 'plantuml',
         [DATA_ATTR.status]: state.status,
         [DATA_ATTR.theme]: dark ? 'dark' : 'light',
-        ...(interactive ? { [DATA_ATTR.interactive]: 'true' } : {}), children: [state.status === 'ready' && state.svg !== null && !interactive && canvas, state.status === 'ready' && state.svg !== null && interactive && (_jsxs("div", { ref: zoom.stageRef, className: 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" }) }), zoom.fullscreenSupported && (_jsx("button", { type: "button", className: styles.toolbarButton, "aria-label": "Toggle fullscreen", onClick: zoom.toggleFullscreen, children: _jsx("span", { "aria-hidden": "true", children: "\u26F6" }) })), _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' && (
+        ...(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' && (
             // `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 PlantUML 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" }), _jsx("span", { children: "Error: PlantUML 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

@@ -108,24 +108,36 @@
   text-align: right;
 }
 
-.stage:fullscreen {
+/*
+ * Maximized is an in-page overlay, not the Fullscreen API.
+ *
+ * `requestFullscreen()` took the whole browser window fullscreen in Firefox, and its
+ * `::backdrop` sits outside the element so the page showed through behind the diagram. A
+ * fixed overlay is fully opaque, behaves the same everywhere, and needs no capability check.
+ */
+.maximized {
+  position: fixed;
+  inset: 0;
+  z-index: var(--ifm-z-index-overlay, 400);
   display: flex;
   align-items: center;
   justify-content: center;
-  background: var(--ifm-background-color);
+  /*
+   * `--ifm-background-surface-color`, not `--ifm-background-color`: Infima defines the latter
+   * as `#0000` in light mode, so the overlay would be transparent and the page would show
+   * through — which is the defect this overlay exists to fix. The surface colour is opaque in
+   * both colour modes (white / #242526), and a `var()` fallback would not have saved us here,
+   * because the variable is defined, just transparent.
+   */
+  background: var(--ifm-background-surface-color, #ffffff);
 }
 
-.stage:fullscreen .viewport {
+.maximized .viewport {
   width: 100vw;
   height: 100dvh;
   max-height: none;
 }
 
-/* The default backdrop is black, which makes a transparent light-mode diagram look broken. */
-.stage::backdrop {
-  background: var(--ifm-background-color, #ffffff);
-}
-
 .visuallyHidden {
   position: absolute;
   width: 1px;

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

@@ -8,10 +8,10 @@ export interface ZoomPanHandle {
     zoomIn: () => void;
     zoomOut: () => void;
     reset: () => void;
-    toggleFullscreen: () => void;
+    toggleMaximize: () => void;
     onKeyDown: (event: ReactKeyboardEvent<HTMLDivElement>) => void;
-    /** Whether this browser can fullscreen an element, so the button can be hidden if not. */
-    fullscreenSupported: boolean;
+    /** Whether the diagram currently fills the browser viewport. */
+    maximized: boolean;
 }
 export interface UseZoomPanParams {
     enabled: boolean;

package/dist/theme/PlantUmlDiagram/useZoomPan.js

@@ -1,38 +1,26 @@
-import { useCallback, useEffect, useRef, } from 'react';
+import { useCallback, useEffect, 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 fullscreen for one diagram.
+ * Zoom, pan and maximize for one diagram.
  *
- * The hook holds no React state at all. The transform lives in a ref and is written straight
- * to the DOM, so panning never re-renders the component — and, more usefully, "no state update
- * after unmount" becomes structurally true rather than something a guard has to enforce.
+ * The transform lives in a ref and is written straight to the DOM, so panning and zooming
+ * never re-render the component. The single piece of React state is `maximized`, which changes
+ * only on an explicit click or Escape — it drives markup, so it belongs in React, and at one
+ * transition per user action it costs nothing.
  */
 /** Distance the pointer must travel before a press becomes a drag rather than a click. */
 const DRAG_THRESHOLD_PX = 3;
 /** Fraction of the viewport a Shift+arrow press pans. */
 const PAGE_PAN_RATIO = 0.9;
-function supportsFullscreen() {
-    if (typeof document === 'undefined')
-        return false;
-    const doc = document;
-    return Boolean(doc.fullscreenEnabled ||
-        typeof document.documentElement.webkitRequestFullscreen ===
-            'function');
-}
-function currentFullscreenElement() {
-    if (typeof document === 'undefined')
-        return null;
-    const doc = document;
-    return doc.fullscreenElement ?? doc.webkitFullscreenElement ?? null;
-}
 export function useZoomPan({ enabled, resetKey }) {
     const stageRef = useRef(null);
     const viewportRef = useRef(null);
     const layerRef = useRef(null);
     const readoutRef = useRef(null);
+    const [maximized, setMaximized] = useState(false);
     const transformRef = useRef(IDENTITY);
-    /** The view to restore when leaving fullscreen. */
-    const beforeFullscreenRef = useRef(null);
+    /** 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
@@ -66,26 +54,24 @@ export function useZoomPan({ enabled, resetKey }) {
     const reset = useCallback(() => {
         apply(IDENTITY);
     }, [apply]);
-    /** Zooms about the middle of the viewport, which is what buttons and keys should do. */
+    /**
+     * 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.
+     *
+     * Wheel zoom still tracks the pointer, which is what direct manipulation should do.
+     */
     const zoomByStep = useCallback((factor) => {
-        const viewport = viewportRef.current;
-        const focalX = (viewport?.clientWidth ?? 0) / 2;
-        const focalY = (viewport?.clientHeight ?? 0) / 2;
-        apply(zoomAbout(transformRef.current, factor, focalX, focalY));
+        apply(zoomAbout(transformRef.current, factor, 0, 0));
     }, [apply]);
     const zoomIn = useCallback(() => zoomByStep(SCALE_STEP), [zoomByStep]);
     const zoomOut = useCallback(() => zoomByStep(1 / SCALE_STEP), [zoomByStep]);
-    const toggleFullscreen = useCallback(() => {
-        const stage = stageRef.current;
-        if (!stage)
-            return;
-        const doc = document;
-        if (currentFullscreenElement()) {
-            void (doc.exitFullscreen?.() ?? doc.webkitExitFullscreen?.());
-            return;
-        }
-        beforeFullscreenRef.current = transformRef.current;
-        void (stage.requestFullscreen?.() ?? stage.webkitRequestFullscreen?.());
+    const toggleMaximize = useCallback(() => {
+        setMaximized((previous) => !previous);
     }, []);
     const onKeyDown = useCallback((event) => {
         if (!enabled)
@@ -229,19 +215,6 @@ export function useZoomPan({ enabled, resetKey }) {
             event.preventDefault();
             event.stopPropagation();
         };
-        const onFullscreenChange = () => {
-            const stage = stageRef.current;
-            const isFullscreen = stage !== null && currentFullscreenElement() === stage;
-            if (isFullscreen) {
-                // Fill the screen: the viewport is much larger now, so refit rather than keep a
-                // transform that was computed for a column-width box.
-                apply({ ...IDENTITY, k: fitScale(measure()) });
-            }
-            else {
-                apply(beforeFullscreenRef.current ?? IDENTITY);
-                beforeFullscreenRef.current = null;
-            }
-        };
         viewport.addEventListener('wheel', onWheel, { passive: false });
         viewport.addEventListener('pointerdown', onPointerDown);
         viewport.addEventListener('pointermove', onPointerMove);
@@ -249,8 +222,6 @@ export function useZoomPan({ enabled, resetKey }) {
         viewport.addEventListener('pointercancel', endDrag);
         viewport.addEventListener('lostpointercapture', endDrag);
         viewport.addEventListener('click', onClickCapture, true);
-        document.addEventListener('fullscreenchange', onFullscreenChange);
-        document.addEventListener('webkitfullscreenchange', onFullscreenChange);
         // Re-clamp when the column width changes (window resize, sidebar collapse), so a panned
         // diagram cannot end up stranded outside a narrower viewport.
         const observer = typeof ResizeObserver === 'undefined'
@@ -265,8 +236,6 @@ export function useZoomPan({ enabled, resetKey }) {
             viewport.removeEventListener('pointercancel', endDrag);
             viewport.removeEventListener('lostpointercapture', endDrag);
             viewport.removeEventListener('click', onClickCapture, true);
-            document.removeEventListener('fullscreenchange', onFullscreenChange);
-            document.removeEventListener('webkitfullscreenchange', onFullscreenChange);
             observer?.disconnect();
             if (frameRef.current !== null) {
                 cancelAnimationFrame(frameRef.current);
@@ -295,6 +264,46 @@ export function useZoomPan({ enabled, resetKey }) {
             return;
         write(IDENTITY);
     }, [enabled, resetKey, write]);
+    /**
+     * Maximizing is done in the page, not with the Fullscreen API.
+     *
+     * `requestFullscreen()` gave two problems it cannot solve: Firefox takes the whole browser
+     * window fullscreen rather than presenting the element, and the `::backdrop` is outside the
+     * element so the page behind it shows through. A fixed-position overlay we own has neither
+     * issue, works identically in every browser, and needs no capability detection — which also
+     * restores the control on iOS Safari, where element fullscreen does not exist.
+     */
+    useEffect(() => {
+        if (!enabled || !maximized)
+            return undefined;
+        beforeMaximizeRef.current = transformRef.current;
+        // The overlay covers the viewport; scrolling the page underneath it would be confusing.
+        const body = document.body;
+        const previousOverflow = body.style.overflow;
+        body.style.overflow = 'hidden';
+        // The layout is already committed by the time an effect runs, so the viewport now
+        // reports its maximized size and the diagram can be fitted to it.
+        apply({ ...IDENTITY, k: fitScale(measure()) });
+        viewportRef.current?.focus();
+        const onKeyDownDocument = (event) => {
+            if (event.key !== 'Escape')
+                return;
+            event.preventDefault();
+            setMaximized(false);
+        };
+        document.addEventListener('keydown', onKeyDownDocument);
+        return () => {
+            document.removeEventListener('keydown', onKeyDownDocument);
+            body.style.overflow = previousOverflow;
+            apply(beforeMaximizeRef.current ?? IDENTITY);
+            beforeMaximizeRef.current = null;
+        };
+    }, [apply, enabled, maximized, measure]);
+    // A diagram that is re-rendered or unmounted must not leave the page scroll-locked.
+    useEffect(() => {
+        if (!enabled)
+            setMaximized(false);
+    }, [enabled]);
     return {
         stageRef,
         viewportRef,
@@ -303,9 +312,9 @@ export function useZoomPan({ enabled, resetKey }) {
         zoomIn,
         zoomOut,
         reset,
-        toggleFullscreen,
+        toggleMaximize,
         onKeyDown,
-        fullscreenSupported: supportsFullscreen(),
+        maximized,
     };
 }
 export { MAX_SCALE, MIN_SCALE };

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

@@ -62,7 +62,7 @@ export declare function wheelZoomFactor(normalizedDelta: number): number;
 /**
  * Largest scale at which the whole diagram still fits inside the given viewport.
  *
- * Used when entering fullscreen. Small diagrams are magnified rather than left stranded in
+ * Used when maximizing. Small diagrams are magnified rather than left stranded in
  * the middle of a large screen — the output is vector, so it stays crisp — but never beyond
  * `max`, and never below {@link MIN_SCALE}.
  */

package/dist/theme/PlantUmlDiagram/zoomMath.js

@@ -82,7 +82,7 @@ export function wheelZoomFactor(normalizedDelta) {
 /**
  * Largest scale at which the whole diagram still fits inside the given viewport.
  *
- * Used when entering fullscreen. Small diagrams are magnified rather than left stranded in
+ * Used when maximizing. Small diagrams are magnified rather than left stranded in
  * the middle of a large screen — the output is vector, so it stays crisp — but never beyond
  * `max`, and never below {@link MIN_SCALE}.
  */

package/package.json

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