@matfsw/docusaurus-plantuml-plugin 1.5.2 → 1.6.0

package/CHANGELOG.md

@@ -7,6 +7,36 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.6.0] - 2026-08-21
+
+### Fixed
+
+- **The zoom controls no longer cover the diagram.** The toolbar was painted over the frame's
+  top-right corner and the minimap toggle over its bottom-left, so at 100% — the view a reader
+  arrives at without touching anything — a sequence diagram's first participant and a graph's
+  leftmost node were sitting underneath a row of buttons. No placement fixes that, because the
+  picture is whatever shape its author drew.
+
+  A zoomable diagram is now two stacked rows: every control in one row (search bar included),
+  and the diagram beneath it. Nothing is painted over the picture at any zoom level; the frame
+  is one button-bar row taller than before, which is the price of never covering the content.
+  The control row is also the frame's **first** child in the DOM, so tab order follows what the
+  reader sees. Maximizing uses the same two rows.
+
+  The **minimap toggle has moved into the toolbar**, beside Maximize; it no longer has a row of
+  its own beneath the diagram. The toolbar wraps rather than overflowing a narrow column. The
+  minimap _panel_ still opens over the diagram's bottom-left corner — the reader opens it
+  deliberately, closes it from its own ✕, and putting it opposite the toolbar keeps the control
+  from covering the map. The source view's header no longer reserves a 12rem gutter for a
+  toolbar that is no longer above it.
+
+  Released as a **minor** rather than the patch these headings would normally derive: the
+  rendered markup changed shape. The minimap's own bar element is gone, its toggle is a button
+  inside the existing control group, and that group is now the frame's first child rather than
+  its last. Site CSS or tests that reached for those positions need updating; the documented
+  selectors — `[data-plantuml-diagram]`, `div[role="img"] > svg`, `[data-plantuml-zoom]` and the
+  control group's accessible name — are all unchanged.
+
 ## [1.5.2] - 2026-08-20
 
 ### Changed
@@ -540,7 +570,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.5.2...HEAD
+[Unreleased]: https://github.com/matf/docusaurus-plantuml-plugin/compare/v1.6.0...HEAD
+[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
 [1.5.0]: https://github.com/matf/docusaurus-plantuml-plugin/compare/v1.4.0...v1.5.0

package/README.md

@@ -525,7 +525,24 @@ diagram, whichever engine produced it.
 ## Zoom and pan
 
 Large diagrams are unreadable at column width. Rendered diagrams are therefore zoomable and
-pannable by default, with a small control toolbar in the top-right corner.
+pannable by default, with a small control toolbar above the picture.
+
+### The frame's layout
+
+A zoomable diagram is two stacked rows: **the controls**, at the top right, and **the diagram**
+beneath them. The search bar opens beside the toolbar, in the same row, and the toolbar wraps
+rather than overflowing a narrow column.
+
+Nothing is painted over the picture, so at 100% — the view a reader arrives at — the whole
+diagram is visible. The controls used to float over the frame's corners, which is exactly where
+a sequence diagram draws its first participant and a graph its leftmost node; no amount of
+nudging fixes that, because the picture is whatever shape its author drew. The row costs the
+height of one small button bar per diagram, which is the price of never covering the content.
+
+Zooming in can still slide the diagram under the row's edge — the viewport clips it there — and
+that is deliberate: by then the reader is driving, and a frame that grew as you zoomed would
+reflow the page around it. The **minimap**, once opened, does float over the picture's
+bottom-left corner: the reader asked for it, and it closes with its own ✕.
 
 ### Interaction
 
@@ -587,10 +604,12 @@ highlight without touching the plugin.
 
 ### Minimap
 
-The button in the bottom-left corner opens a minimap: a small copy of the diagram with a
-rectangle marking what the viewport currently shows. Press or drag anywhere on the map to
-centre the view there — a single press works as "jump there". The map follows every zoom,
-pan and resize, works while maximized, and closes from its own ✕ or the toggle.
+The minimap button in the toolbar opens a minimap: a small copy of the diagram with a
+rectangle marking what the viewport currently shows. It appears in the diagram's bottom-left
+corner — the opposite one from the toolbar, so the control that opens it never covers it.
+Press or drag anywhere on the map to centre the view there — a single press works as "jump
+there". The map follows every zoom, pan and resize, works while maximized, and closes from its
+own ✕ or the toggle.
 
 The map is pointer-only and hidden from assistive technology on purpose: the real viewport is
 already keyboard-operable with the arrow keys, so announcing a second, duplicated view of the
@@ -635,6 +654,8 @@ would mean most readers never discover it. The costs are real and worth knowing:
 
 - Each zoomable diagram adds a **keyboard tab stop for the viewport and one per toolbar
   button**. On a page with six diagrams that is a meaningful amount of tabbing.
+- The frame is **one button-bar row taller** than the picture, because the controls sit above it
+  rather than over it — see [The frame's layout](#the-frames-layout).
 - The rendered markup gains a viewport and transform wrapper around the `role="img"` container.
   Site CSS that targets `[data-plantuml-diagram] > div[role="img"]` as a **direct child** needs
   updating — see [Accessibility](#accessibility) for both shapes.

package/dist/theme/PlantUmlDiagram/index.js

@@ -296,9 +296,9 @@ export default function PlantUmlDiagram({ source, title, language, engine = 'pla
         ...(zoom.maximized ? { [DATA_ATTR.maximized]: 'true' } : {}),
         ...(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
+        ...(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.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' && (
+                                            : `${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, {}) }), !sourceOpen && (_jsx("button", { type: "button", className: styles.toolbarButton, "aria-label": minimapOpen ? 'Hide minimap' : 'Show minimap', "aria-expanded": minimapOpen, onClick: () => setMinimapOpen((open) => !open), children: _jsx(MinimapIcon, {}) })), sourceToggle, copyControl, _jsx("span", { ref: zoom.readoutRef, className: sourceOpen ? `${styles.readout} ${styles.hiddenView}` : styles.readout, "aria-hidden": "true", children: "100%" })] })] }), _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 }) }), !sourceOpen && minimapOpen && (_jsx(Minimap, { svg: state.svg, zoom: zoom, onClose: () => setMinimapOpen(false) })), sourceView] })] })), 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

@@ -52,8 +52,26 @@
  * the figure keeps the exact height it has at 100% no matter how far the reader zooms in, and
  * `max-width: 100%` on the SVG keeps constraining the base size as it always did.
  */
+
+/*
+ * The frame is two stacked rows — controls, then picture — not one box with chrome floating
+ * over it.
+ *
+ * Floating it covered the diagram: the toolbar sat over the top right of every figure and the
+ * minimap toggle over the bottom left, and at 100% — the view every reader arrives at — that
+ * is exactly where a sequence diagram's first participant and a graph's leftmost node are
+ * drawn. No amount of nudging fixes that, because the picture is whatever shape its author
+ * drew. A row above the picture means the opening view has nothing painted over it at all.
+ * Zooming can still slide content under the row's edge, which is fine: by then the reader is
+ * driving, and the alternative is a frame that grows as you zoom.
+ *
+ * `position: relative` stays for the maximized overlay's sake, not for the controls.
+ */
 .stage {
   position: relative;
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
 }
 
 .viewport {
@@ -108,25 +126,32 @@
 /*
  * 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.
+ *
+ * `flex-end` keeps the toolbar where readers have always found it, at the top right of the
+ * frame — now above the picture rather than on top of it.
  */
 .controls {
-  position: absolute;
-  top: 0.5rem;
-  right: 0.5rem;
   display: flex;
+  /*
+   * Wrapping, in both directions, because the row is the only thing holding the controls now:
+   * in a narrow column the search bar drops below the toolbar rather than squeezing it, and
+   * the toolbar itself breaks across lines rather than overflowing the frame.
+   */
+  flex-wrap: wrap;
   gap: 0.5rem;
   align-items: flex-start;
+  justify-content: flex-end;
 }
 
 .toolbar {
   display: flex;
+  flex-wrap: wrap;
   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 {
@@ -137,7 +162,6 @@
   border: 1px solid var(--ifm-color-emphasis-300);
   border-radius: var(--ifm-global-radius);
   background: var(--ifm-background-surface-color);
-  opacity: 0.92;
 }
 
 .searchInput {
@@ -275,9 +299,8 @@
   position: fixed;
   inset: 0;
   z-index: var(--ifm-z-index-overlay, 400);
-  display: flex;
-  align-items: center;
-  justify-content: center;
+  /* Keeps the control rows off the screen's edges; `inset: 0` fixes the border box either way. */
+  padding: 0.5rem;
   /*
    * `--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
@@ -288,35 +311,49 @@
   background: var(--ifm-background-surface-color, #ffffff);
 }
 
+/*
+ * The picture takes every pixel the two control rows leave. `min-height: 0` is what allows
+ * that: a flex item's floor is its content, so without it a tall diagram would push the
+ * minimap row off the bottom of the screen instead of being clipped by its own viewport.
+ *
+ * The viewport itself needs no size: it is the lone item in `.stageBody`'s grid cell, so it
+ * stretches to whatever the row is given — 100vw/100dvh here would ignore the padding and
+ * the rows and overflow the overlay by exactly their height.
+ */
+.maximized .stageBody {
+  flex: 1;
+  min-height: 0;
+  /*
+   * The row must take the height it is *given*, not the height the picture wants. A grid
+   * track sized `auto` floors at max-content, so a diagram taller than the screen sized the
+   * row past the frame and the viewport painted straight over the minimap row below it —
+   * and, worse, `fitScale` then measured that overflowing viewport and concluded the diagram
+   * already fitted. `minmax(0, 1fr)` removes the floor, so the track is exactly the free
+   * height and the viewport clips the picture as it does everywhere else.
+   */
+  grid-template-rows: minmax(0, 1fr);
+}
+
 .maximized .viewport {
-  width: 100vw;
-  height: 100dvh;
   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.
+ * A small copy of the diagram 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.
+ *
+ * It floats over the picture's bottom-left corner — it is a child of `.stageBody`, so that is
+ * the box it is anchored in, and it is the one control positioned that way. A control the
+ * reader has explicitly opened may cover the picture; the toolbar, which is simply always
+ * there, may not. The corner is deliberately the opposite one from the toolbar that opens it:
+ * a map painted under its own control would be half hidden by it.
  */
-.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;
+  bottom: 0.5rem;
   left: 0.5rem;
   /*
    * The close control sits *beside* the map, not floating over it: a wide, short diagram
@@ -383,7 +420,6 @@
 @media (forced-colors: active) {
   .toolbar,
   .searchBar,
-  .minimapBar,
   .minimap {
     border-color: ButtonBorder;
   }
@@ -563,8 +599,8 @@
   align-items: center;
   flex-wrap: wrap;
   gap: 0.5rem;
-  /* Clears the toolbar, which floats over the top-right of the same frame. */
-  padding: 0.5rem 12rem 0.25rem 0.75rem;
+  /* No clearance needed: the toolbar has a row above the frame, not a corner inside it. */
+  padding: 0.5rem 0.75rem 0.25rem;
 }
 
 .sourceViewTitle {

package/package.json

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