documonster 0.16.1 → 0.17.0

package/README.md

@@ -211,7 +211,7 @@ const buffer = await Workbook.toBuffer(wb);
 
 ```html
 <!-- Script tag (no bundler) — one IIFE per module, each under the shared `Documonster` global -->
-<script src="https://unpkg.com/documonster@0.16.1/dist/iife/documonster.excel.iife.min.js"></script>
+<script src="https://unpkg.com/documonster@0.17.0/dist/iife/documonster.excel.iife.min.js"></script>
 <script>
   const { Workbook, Cell } = Documonster.Excel;
   const wb = Workbook.create();

package/README_zh.md

@@ -198,7 +198,7 @@ const buffer = await Workbook.toBuffer(wb);
 
 ```html
 <!-- Script 标签（无需打包工具）— 每个模块一个 IIFE，共享同一个 `Documonster` 全局 -->
-<script src="https://unpkg.com/documonster@0.16.1/dist/iife/documonster.excel.iife.min.js"></script>
+<script src="https://unpkg.com/documonster@0.17.0/dist/iife/documonster.excel.iife.min.js"></script>
 <script>
   const { Workbook, Cell } = Documonster.Excel;
   const wb = Workbook.create();

package/dist/esm/modules/excel/core/worksheet.js

@@ -26,7 +26,7 @@ import { copyStyle } from "../utils/copy-style.js";
 import { isExternalImage } from "../utils/drawing-utils.js";
 import { applyMergeBorders, collectMergeBorders } from "../utils/merge-borders.js";
 import { buildSheetProtection, verifySheetPassword } from "../utils/sheet-protection.js";
-import { calculateAutoFitWidth, getMaxDigitWidth, getColumnContentWidthPx, getCellTextWidthPx, getCellHeightPt } from "../utils/text-metrics.js";
+import { calculateAutoFitWidth, getMaxDigitWidth, charWidthToPixel, getPixelPadding, getCellTextWidthPx, getCellHeightPt } from "../utils/text-metrics.js";
 // Worksheet requirements
 //  Operate as sheet inside workbook or standalone
 //  Load and Save from file and stream
@@ -1200,12 +1200,23 @@ export function removeConditionalFormatting(ws, filter) {
         ws.conditionalFormattings = [];
     }
 }
-export function autoFitColumn(ws, col) {
+/**
+ * Set a column's width to fit its content, as Excel's AutoFit does.
+ *
+ * Cells in hidden rows are ignored unless `includeHiddenRows` is set. A
+ * merged cell counts as visible while any row of the merge is, since that is
+ * where Excel draws it; a merge spanning several columns is not measured,
+ * because its width cannot be attributed to one of them.
+ */
+export function autoFitColumn(ws, col, options) {
     const colNum = typeof col === "string" ? colCache.l2n(col) : col;
-    _autoFitColumnImpl(ws, colNum);
+    _autoFitColumnImpl(ws, colNum, options);
     return ws;
 }
-export function autoFitColumns(ws, startCol, endCol) {
+export function autoFitColumns(ws, startColOrOptions, endCol, rangeOptions) {
+    const rangeGiven = startColOrOptions === null || typeof startColOrOptions !== "object";
+    const startCol = rangeGiven ? startColOrOptions : undefined;
+    const options = rangeGiven ? rangeOptions : startColOrOptions;
     const dims = getSheetDimensions(ws);
     if (!dims || dims.left === undefined) {
         return ws;
@@ -1217,7 +1228,7 @@ export function autoFitColumns(ws, startCol, endCol) {
         : dims.left;
     const end = endCol != null ? (typeof endCol === "string" ? colCache.l2n(endCol) : endCol) : dims.right;
     for (let c = start; c <= end; c++) {
-        _autoFitColumnImpl(ws, c);
+        _autoFitColumnImpl(ws, c, options);
     }
     return ws;
 }
@@ -1237,8 +1248,45 @@ export function autoFitRows(ws, startRow, endRow) {
     }
     return ws;
 }
-function _autoFitColumnImpl(ws, colNum) {
+/** A row that has never been created has default visibility. */
+function _isRowHidden(ws, rowNumber) {
+    const row = ws._rows[rowNumber - 1];
+    return row ? rowHidden(row) : false;
+}
+function _isColumnHidden(ws, colNum) {
+    return ws._columns[colNum - 1]?.hidden === true;
+}
+function _anyRowVisible(ws, top, bottom) {
+    for (let r = top; r <= bottom; r++) {
+        if (!_isRowHidden(ws, r)) {
+            return true;
+        }
+    }
+    return false;
+}
+function _anyColumnVisible(ws, left, right) {
+    for (let c = left; c <= right; c++) {
+        if (!_isColumnHidden(ws, c)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * The merged range a master cell heads, or `undefined` for any other cell.
+ *
+ * A merge's content is stored only in its master, yet it is displayed wherever
+ * any part of the merge is. Auto-fit therefore decides a master's visibility
+ * over this range rather than its own row or column — which is what keeps a
+ * merge whose master is hidden, one inside a collapsed outline group say, from
+ * being dropped.
+ */
+function _mergeRangeOf(ws, cell) {
+    return cellIsMerged(cell) ? ws._merges[cell.address] : undefined;
+}
+function _autoFitColumnImpl(ws, colNum, options) {
     const mdw = getMaxDigitWidth(); // default font MDW
+    const includeHiddenRows = options?.includeHiddenRows === true;
     // Check if this column is under an autofilter
     const hasAutoFilter = _isColumnInAutoFilter(ws, colNum);
     let maxWidthPx = 0;
@@ -1247,26 +1295,23 @@ function _autoFitColumnImpl(ws, colNum) {
         if (!row) {
             return;
         }
-        // Skip hidden rows — Excel excludes them from auto-fit
-        if (rowHidden(row)) {
-            return;
-        }
         const cell = rowFindCell(row, colNum);
         if (!cell) {
             return;
         }
         // Skip merged cell slaves — the content belongs to the master cell.
-        // For the master cell of a multi-column merge, skip too (the width
-        // should not be attributed to a single column).
         if (cellType(cell) === Enums.ValueType.Merge) {
             return;
         }
-        if (cellIsMerged(cell)) {
-            // This is a master cell with merges spanning multiple columns
-            const mergeRange = ws._merges[cell.address];
-            if (mergeRange && mergeRange.left !== mergeRange.right) {
-                return; // multi-column merge — skip
-            }
+        const merge = _mergeRangeOf(ws, cell);
+        // A multi-column merge's width should not be attributed to one column.
+        if (merge && merge.left !== merge.right) {
+            return;
+        }
+        // Skip content in hidden rows — Excel excludes it from auto-fit
+        if (!includeHiddenRows &&
+            (merge ? !_anyRowVisible(ws, merge.top, merge.bottom) : rowHidden(row))) {
+            return;
         }
         // Skip shrinkToFit cells — they adapt to the column, not vice versa
         if (cellAlignment(cell)?.shrinkToFit) {
@@ -1303,19 +1348,17 @@ function _autoFitRowImpl(ws, rowNumber) {
         if (cellType(cell) === Enums.ValueType.Merge) {
             return;
         }
-        // Skip multi-row merged masters
-        if (cellIsMerged(cell)) {
-            const mergeRange = ws._merges[cell.address];
-            if (mergeRange && mergeRange.top !== mergeRange.bottom) {
-                return;
-            }
+        const merge = _mergeRangeOf(ws, cell);
+        // A multi-row merge's height should not be attributed to one row.
+        if (merge && merge.top !== merge.bottom) {
+            return;
         }
-        // Skip cells in hidden columns
-        const col = ws._columns[cellCol(cell) - 1];
-        if (col?.hidden) {
+        // Skip content in hidden columns
+        const col = cellCol(cell);
+        if (merge ? !_anyColumnVisible(ws, merge.left, merge.right) : _isColumnHidden(ws, col)) {
             return;
         }
-        const columnWidthPx = _getColumnContentWidthForCell(ws, cell, mdw);
+        const columnWidthPx = _getColumnContentWidthForCell(ws, cell, mdw, merge?.left ?? col, merge?.right ?? col);
         const heightPt = getCellHeightPt(cellView(cell), mdw, columnWidthPx);
         if (heightPt > maxHeightPt) {
             maxHeightPt = heightPt;
@@ -1326,14 +1369,23 @@ function _autoFitRowImpl(ws, rowNumber) {
         row.customHeight = true;
     }
 }
-function _getColumnContentWidthForCell(ws, cell, mdw) {
+function _getColumnContentWidthForCell(ws, cell, mdw, left, right) {
     if (!cellAlignment(cell)?.wrapText) {
         return undefined;
     }
-    // Try to get explicit column width; avoid creating a column as side effect
-    const col = ws._columns[cellCol(cell) - 1];
-    const colWidth = col?.width ?? ws.properties.defaultColWidth ?? 9;
-    return getColumnContentWidthPx(colWidth, mdw);
+    // Text wraps across the visible columns the cell spans, with the cell padding
+    // charged once for the whole merge rather than once per column.
+    let totalPx = 0;
+    for (let c = left; c <= right; c++) {
+        if (!_isColumnHidden(ws, c)) {
+            totalPx += charWidthToPixel(_columnWidthChars(ws, c), mdw);
+        }
+    }
+    return Math.max(0, totalPx - getPixelPadding(mdw));
+}
+/** Width of a column in characters, without creating it as a side effect. */
+function _columnWidthChars(ws, colNum) {
+    return ws._columns[colNum - 1]?.width ?? ws.properties.defaultColWidth ?? 9;
 }
 function _isColumnInAutoFilter(ws, colNum) {
     if (!ws.autoFilter) {

package/dist/esm/modules/mermaid/index.js

@@ -41,7 +41,7 @@ import { erDiagramNodes, erNodeSizer, erToFlowchart } from "./render/er.js";
 import { flowchartNodes } from "./render/flowchart.js";
 import { ganttDrawList } from "./render/gantt.js";
 import { blockDrawList, c4DiagramNodes, c4NodeSizer, c4ToFlowchart, requirementDiagramNodes, requirementNodeSizer, requirementToFlowchart } from "./render/model.js";
-import { backdrop } from "./render/shared.js";
+import { backdrop, centredText } from "./render/shared.js";
 import { pieDrawList, sequenceDrawList } from "./render/simple.js";
 import { stateToFlowchart } from "./render/state.js";
 import { journeyDrawList, timelineDrawList } from "./render/track.js";
@@ -177,3 +177,30 @@ export function mermaidToSvg(source, options = {}) {
 }
 export { MermaidSyntaxError, parseMermaid };
 export { layoutFlowchart };
+/**
+ * Draw a laid-out diagram yourself, in the colours and at the text positions the built-in
+ * renderer would have used.
+ *
+ * {@link layoutFlowchart} is public, so "use the layout and render it your own way" is a
+ * supported route — a caller wanting a different node shape, an annotation of their own, or
+ * an HTML/canvas target rather than a `DrawList` takes it. It was half-open: the geometry
+ * came back, and everything needed to *paint* it was internal.
+ *
+ * {@link Theme} was published without either the function that produces one or any signature
+ * accepting one, which made it a name for a thing a consumer could not obtain, could not
+ * construct — ten required `Rgba01` fields plus a `paletteText` callback — and could not pass
+ * anywhere. `resolveTheme` is what it was missing: {@link MermaidRenderOptions.theme} takes
+ * CSS strings, and this is the same resolution the renderer applies to them, so a
+ * self-rendered diagram matches one from {@link mermaidToSvg} instead of approximating it.
+ * Without it the only route to the palette was to copy the hex literals out of this module's
+ * source and hope they did not move.
+ *
+ * `centredText` is exported rather than the two constants behind it (`LINE_HEIGHT`,
+ * `BASELINE_SHIFT`) on purpose. A display list positions text by its baseline, because that
+ * is the one thing every backend can honour, so stacking `NodeBox.lines` in the middle of a
+ * box is arithmetic the caller has to do — and handing out the constants invites a ninth copy
+ * of that arithmetic, free to disagree with the eight inside. The box shape it takes is
+ * exactly what the layout already returns: `NodeBox`, `GroupBox` and `EdgeRoute.label` all
+ * carry `x`/`y`/`width`/`height`, and the last two carry the wrapped `lines` with them.
+ */
+export { centredText, resolveTheme };

package/dist/esm/modules/pdf/render/layout-engine.js

@@ -1110,11 +1110,23 @@ function buildMergeMap(sheet) {
     }
     for (const rangeStr of merges) {
         const range = parseRangeRef(rangeStr);
+        const top = range.s.r + 1;
+        const left = range.s.c + 1;
+        const bottom = range.e.r + 1;
+        const right = range.e.c + 1;
+        const rowShown = (r) => !sheet.rows.get(r)?.hidden;
+        const colShown = (c) => !sheet.columns.get(c)?.hidden;
+        const [shownTop, shownBottom] = shownSpan(top, bottom, rowShown);
+        const [shownLeft, shownRight] = shownSpan(left, right, colShown);
         const region = {
-            top: range.s.r + 1,
-            left: range.s.c + 1,
-            bottom: range.e.r + 1,
-            right: range.e.c + 1
+            top,
+            left,
+            bottom,
+            right,
+            shownTop,
+            shownLeft,
+            shownBottom,
+            shownRight
         };
         for (let r = region.top; r <= region.bottom; r++) {
             for (let c = region.left; c <= region.right; c++) {
@@ -1124,6 +1136,21 @@ function buildMergeMap(sheet) {
     }
     return map;
 }
+/**
+ * The first and last tracks in `first..last` that are shown, or the range
+ * itself when none is.
+ */
+function shownSpan(first, last, shown) {
+    let lo = first;
+    while (lo < last && !shown(lo)) {
+        lo++;
+    }
+    let hi = last;
+    while (hi > lo && !shown(hi)) {
+        hi--;
+    }
+    return shown(lo) ? [lo, hi] : [first, last];
+}
 /**
  * How far a merged region reaches along one axis of one page, starting at the
  * page track `at`.
@@ -1292,20 +1319,25 @@ function mergePieceInput(piece, sheet) {
     const { region } = piece;
     const borderAt = (row, col) => sheet.rows.get(row)?.cells.get(col)?.style?.border;
     // Excel formats the whole region from the master and draws its value once, in
-    // the piece that holds it — the others are the same box continued, not a
-    // repeat of its contents.
+    // the piece that begins where the region is first displayed — the others are
+    // the same box continued, not a repeat of its contents. That is the master's
+    // own piece unless the master's row or column is hidden.
     const master = sheet.rows.get(region.top)?.cells.get(region.left);
-    const holdsMaster = piece.top === region.top && piece.left === region.left;
+    const holdsValue = piece.top === region.shownTop && piece.left === region.shownLeft;
+    // Each edge is the region's own only where the piece reaches its displayed
+    // boundary; the style is still read from the boundary cells that own it.
     return {
         styleCell: master,
-        valueCell: holdsMaster ? master : undefined,
+        valueCell: holdsValue ? master : undefined,
         colSpan: piece.colSpan,
         rowSpan: piece.rowSpan,
         borders: {
-            top: piece.top === region.top ? borderAt(region.top, piece.left)?.top : undefined,
-            bottom: piece.bottom === region.bottom ? borderAt(region.bottom, piece.left)?.bottom : undefined,
-            left: piece.left === region.left ? borderAt(piece.top, region.left)?.left : undefined,
-            right: piece.right === region.right ? borderAt(piece.top, region.right)?.right : undefined
+            top: piece.top === region.shownTop ? borderAt(region.top, piece.left)?.top : undefined,
+            bottom: piece.bottom === region.shownBottom
+                ? borderAt(region.bottom, piece.left)?.bottom
+                : undefined,
+            left: piece.left === region.shownLeft ? borderAt(piece.top, region.left)?.left : undefined,
+            right: piece.right === region.shownRight ? borderAt(piece.top, region.right)?.right : undefined
         }
     };
 }

package/dist/iife/documonster.archive.iife.min.js

@@ -1,5 +1,5 @@
 /*!
-* documonster v0.16.1
+* documonster v0.17.0
 * Zero-dependency TypeScript toolkit for Excel, Word, PDF, CSV, Markdown, XML & ZIP — one API across Node.js, Bun & browsers.
 * (c) 2025 cjnoname
 * Released under the Apache-2.0 License

package/dist/iife/documonster.csv.iife.min.js

@@ -1,5 +1,5 @@
 /*!
-* documonster v0.16.1
+* documonster v0.17.0
 * Zero-dependency TypeScript toolkit for Excel, Word, PDF, CSV, Markdown, XML & ZIP — one API across Node.js, Bun & browsers.
 * (c) 2025 cjnoname
 * Released under the Apache-2.0 License

package/dist/iife/documonster.draw.iife.min.js

@@ -1,5 +1,5 @@
 /*!
-* documonster v0.16.1
+* documonster v0.17.0
 * Zero-dependency TypeScript toolkit for Excel, Word, PDF, CSV, Markdown, XML & ZIP — one API across Node.js, Bun & browsers.
 * (c) 2025 cjnoname
 * Released under the Apache-2.0 License