documonster 0.18.1 → 0.18.2

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.18.1/dist/iife/documonster.excel.iife.min.js"></script>
+<script src="https://unpkg.com/documonster@0.18.2/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.18.1/dist/iife/documonster.excel.iife.min.js"></script>
+<script src="https://unpkg.com/documonster@0.18.2/dist/iife/documonster.excel.iife.min.js"></script>
 <script>
   const { Workbook, Cell } = Documonster.Excel;
   const wb = Workbook.create();

package/dist/esm/modules/excel/xlsb/pivot-cache.js

@@ -12,6 +12,7 @@
  * this exact sequence. An earlier version of this module's documentation claimed no such authority existed;
  * it does, in the same chapter as the filter example that was already being relied on.
  */
+import { encodeWideString } from "./binary.js";
 import { BinaryWriter, concatUint8Arrays } from "../../../utils/binary.js";
 import { dateToExcel } from "#platform/utils/utils";
 /**
@@ -21,15 +22,6 @@ import { dateToExcel } from "#platform/utils/utils";
  */
 const CACHE_APP_VERSION = 8;
 const CACHE_MIN_VERSION = 3;
-/** An `XLWideString`: a four-byte character count, then UTF-16. */
-function wideString(value) {
-    const characters = [...value];
-    const writer = new BinaryWriter().writeUint32(characters.length);
-    for (const character of characters.join("")) {
-        writer.writeUint16(character.charCodeAt(0));
-    }
-    return writer.toUint8Array();
-}
 /** An `RfX`: four unsigned 32-bit bounds, first row, last row, first column, last column. */
 function rfx(rowFirst, rowLast, columnFirst, columnLast) {
     return new BinaryWriter()
@@ -66,7 +58,7 @@ export function pivotCacheIdRecords(caches) {
             "BrtBeginPivotCacheID",
             concatUint8Arrays([
                 new BinaryWriter().writeUint32(cache.cacheId).toUint8Array(),
-                wideString(cache.relationshipId)
+                encodeWideString(cache.relationshipId)
             ])
         ]);
         records.push(["BrtEndPivotCacheID", undefined]);
@@ -180,7 +172,7 @@ function cacheDefinitionPayload(cache) {
         .writeUint32(cache.records.length);
     const parts = [writer.toUint8Array()];
     if (hasRecords) {
-        parts.push(wideString(cache.recordsRelationshipId));
+        parts.push(encodeWideString(cache.recordsRelationshipId));
     }
     // Present because `fLoadRefreshedWho` is 0 — see the note above.
     parts.push(new BinaryWriter().writeUint32(0).toUint8Array());
@@ -203,7 +195,7 @@ function sourceRangePayload(cache) {
             // single sheet, which is what makes `sheetName` meaningful.
             .writeUint8(0x02)
             .toUint8Array(),
-        wideString(cache.sheetName),
+        encodeWideString(cache.sheetName),
         rfx(cache.range.rowFirst, cache.range.rowLast, cache.range.columnFirst, cache.range.columnLast)
     ]);
 }
@@ -228,7 +220,7 @@ function cacheFieldPayload(field) {
             // `cIsxtmps` — member-property field indices, which only an OLAP cache has.
             .writeUint32(0)
             .toUint8Array(),
-        wideString(field.name)
+        encodeWideString(field.name)
     ]);
 }
 /**
@@ -393,7 +385,7 @@ function sharedItemRecord(item) {
     // A value none of the above: written as text. `String(item)` on a `Date` is what used to happen here, and
     // it put `"Mon Jan 15 2024 00:00:00 GMT+0800 (China Standard Time)"` into the cache — a sentence whose
     // content depends on the machine's locale and timezone.
-    return ["BrtPCDIString", wideString(String(item))];
+    return ["BrtPCDIString", encodeWideString(String(item))];
 }
 /**
  * `PCDIDateTime`, MS-XLSB 2.5.101 — a calendar date and a wall-clock time, not a serial number.
@@ -470,7 +462,7 @@ function cacheRecordPayload(row, fields) {
             parts.push(encodePcdiDateTime(value));
             continue;
         }
-        parts.push(wideString(value === null || value === undefined ? "" : String(value)));
+        parts.push(encodeWideString(value === null || value === undefined ? "" : String(value)));
     }
     return concatUint8Arrays(parts);
 }

package/dist/esm/modules/excel/xlsb/pivot-model.js

@@ -16,6 +16,7 @@
 import { METRIC_DISPLAY_NAMES, VALID_SUBTOTALS } from "../core/pivot-table-types.js";
 import { decodeCell } from "../utils/address.js";
 import { PIT_DATA, PIT_DEFAULT, PIT_GRAND } from "./pivot-view.js";
+import { parseXsdBoolean } from "../xlsx/xform/xsd-values.js";
 /**
  * Reduce one source value to what a cache record holds for it: an index into the field's shared items, or the
  * value itself when the field has none.
@@ -195,7 +196,17 @@ export function pivotParts(pivot, recordsRelationshipId) {
                     `${METRIC_DISPLAY_NAMES[subtotal]} of ${pivot.cacheFields[field]?.name ?? ""}`
             };
         }),
-        dataCaption: "Values"
+        // A loaded table carries its own view strings; a new one has only the default data caption. They were
+        // all dropped here, so converting a workbook to XLSB reset every caption the user had typed.
+        dataCaption: pivot.dataCaption ?? "Values",
+        grandTotalCaption: pivot.grandTotalCaption,
+        rowHeaderCaption: pivot.rowHeaderCaption,
+        colHeaderCaption: pivot.colHeaderCaption,
+        showError: parseXsdBoolean(pivot.showError),
+        errorCaption: pivot.errorCaption,
+        showMissing: parseXsdBoolean(pivot.showMissing),
+        missingCaption: pivot.missingCaption,
+        tag: pivot.tag
     };
     return { cache, view };
 }

package/dist/esm/modules/excel/xlsb/pivot-view.js

@@ -11,6 +11,7 @@
  * and only the declared `0x3B` reveals that the trailing `reserved` is inside the `PivotNumFmt` rather than
  * beside it.
  */
+import { encodeWideString } from "./binary.js";
 import { encodeTableStyleClient } from "./table-style.js";
 import { BinaryWriter, concatUint8Arrays } from "../../../utils/binary.js";
 /**
@@ -101,15 +102,6 @@ export const PIT_GRAND = 0x0d;
 const PIVOT_APP_VERSION = 8;
 /** `bVerSxUpdateableMin` — the oldest version allowed to update the view. Three, as Excel writes. */
 const PIVOT_MIN_VERSION = 3;
-/** An `XLWideString`: a four-byte character count, then UTF-16. */
-function wideString(value) {
-    const characters = [...value];
-    const writer = new BinaryWriter().writeUint32(characters.length);
-    for (const character of characters.join("")) {
-        writer.writeUint16(character.charCodeAt(0));
-    }
-    return writer.toUint8Array();
-}
 /** A counted array of 32-bit field indices, which four of these collections are. */
 function indexArray(indices) {
     const writer = new BinaryWriter().writeUint32(indices.length);
@@ -300,13 +292,24 @@ export function pivotViewRecords(view) {
 /**
  * `BrtBeginSXView` — MS-XLSB 2.4.278. Thirty-two fixed bytes and up to eleven conditional strings.
  *
- * Three of the flags are **presence** flags for those strings, and two of them are **inverted**:
- * `fDisplayData` (bit 25 of the second word) says `irstData` *is* present and MUST be 1, while
- * `fEmptyDisplayErrorString` and `fEmptyDisplayNullString` say their strings are *absent*. So a minimal
- * record has to *set* the two "empty" bits and clear the rest — reading them as ordinary "has a value" flags
- * produces a record whose string fields are read from whatever follows it.
+ * Every string after `irstName` has a **presence** flag, and two of them are **inverted**: `fDisplayData`
+ * (bit 19 of the second word) says `irstData` *is* present and MUST be 1, while `fEmptyDisplayErrorString`
+ * and `fEmptyDisplayNullString` say their strings are *absent*. So a record without those strings has to
+ * *set* the two "empty" bits — reading them as ordinary "has a value" flags produces a record whose string
+ * fields are read from whatever follows it.
+ *
+ * Note the specification's own slip: it says `irstColHdrName` is governed by `fUseRwHdrName`. Each header
+ * string has its own flag (`fUseColHdrName` for the column one), and the column string comes first.
  */
 function viewPayload(view) {
+    // The conditional strings, each paired with the flag that declares it. A flag and its string must agree or
+    // every later string is read from the wrong offset, so both come from the same `!== undefined` test.
+    const grand = limitedCaption(view.grandTotalCaption, SHORT_STRING_LIMIT);
+    const error = limitedCaption(view.errorCaption, SHORT_STRING_LIMIT);
+    const missing = limitedCaption(view.missingCaption, SHORT_STRING_LIMIT);
+    const tag = limitedCaption(view.tag, SHORT_STRING_LIMIT);
+    const columnHeader = limitedCaption(view.colHeaderCaption, HEADER_STRING_LIMIT);
+    const rowHeader = limitedCaption(view.rowHeaderCaption, HEADER_STRING_LIMIT);
     // Every value below was read out of an XLSB that Excel wrote for this pivot table. Where a bit's purpose is
     // known it is named; where it is not, it is still written, because a view Excel will not open is worth less
     // than a view carrying a flag nobody here can explain.
@@ -325,20 +328,25 @@ function viewPayload(view) {
         (1 << 6) | // fEnableFieldDialog
         (1 << 7) | // fPreserveFormatting
         (1 << 8) | // fAutoFormat
-        (1 << 10) | // fDisplayNullString
+        (view.showError === true ? 1 << 9 : 0) | // fDisplayErrorString
+        (view.showMissing === false ? 0 : 1 << 10) | // fDisplayNullString
         (1 << 13) | // fRwGrand
         (1 << 14) | // fColGrand
         (1 << 17) | // fRepeatItemsOnEachPrintedPage
         (1 << 19) | // fDisplayData — MUST be 1, `irstData` follows
-        (1 << 29) // ibitAtrProt
+        (grand !== undefined ? 1 << 20 : 0) | // fDisplayGrand — `irstGrand` follows
+        (1 << 29) | // ibitAtrProt
+        (tag !== undefined ? 1 << 30 : 0) // fDisplayTag — `irstTag` follows
     )
         // Third flag word, `0x000002D0`. `fCompactData` is **clear**: it was set here to "match what Excel writes
         // for a new pivot table", and Excel writes it clear for this one — as does this library's XLSX writer,
         // which declares `compactData="0"` in the file Excel opens.
         .writeUint32((1 << (36 - 32)) | // fNewDropZones
-        (1 << (38 - 32)) | // fEmptyDisplayErrorString
-        (1 << (39 - 32)) | // fEmptyDisplayNullString
-        (1 << (41 - 32)) // fSingleFilterPerField
+        (error === undefined ? 1 << (38 - 32) : 0) | // fEmptyDisplayErrorString — inverted
+        (missing === undefined ? 1 << (39 - 32) : 0) | // fEmptyDisplayNullString — inverted
+        (1 << (41 - 32)) | // fSingleFilterPerField
+        (rowHeader !== undefined ? 1 << (42 - 32) : 0) | // fUseRwHdrName
+        (columnHeader !== undefined ? 1 << (43 - 32) : 0) // fUseColHdrName
     )
         // `sxaxis4Data`: the axis the data field sits on — see {@link dataFieldAxis} for why this is a constant.
         .writeUint8(dataFieldAxis())
@@ -356,13 +364,40 @@ function viewPayload(view) {
         // `dwCrtFmtId`: the next pivot-chart identifier. 0 because no pivot chart is written.
         .writeUint32(0)
         .writeUint32(view.cacheId);
+    // In the record's order: name, data, grand, error, null, page-field style, table style, vacate style, tag,
+    // column header, row header. The three styles are never written, so their flags stay clear.
+    const strings = [
+        view.name,
+        // `irstData`, present because `fDisplayData` is 1.
+        limitedCaption(view.dataCaption, SHORT_STRING_LIMIT),
+        grand,
+        error,
+        missing,
+        tag,
+        columnHeader,
+        rowHeader
+    ];
     return concatUint8Arrays([
         writer.toUint8Array(),
-        wideString(view.name),
-        // `irstData`, present because `fDisplayData` is 1.
-        wideString(view.dataCaption)
+        ...strings.flatMap(value => (value === undefined ? [] : [encodeWideString(value)]))
     ]);
 }
+/** `XLWideString` limit for the view's captions — 255 characters, as Excel's own user interface enforces. */
+const SHORT_STRING_LIMIT = 255;
+/** `irstRwHdrName` / `irstColHdrName` may be longer when `bVerSxMacro` is 3 or more, which this writer's is. */
+const HEADER_STRING_LIMIT = 32767;
+/**
+ * A caption cut to the length the record allows. XLSX has no such limit, so a longer caption from a loaded
+ * file has to be shortened rather than written into a record a reader is entitled to reject; the cut is made
+ * on a code-unit boundary that does not split a surrogate pair.
+ */
+function limitedCaption(value, limit) {
+    if (value === undefined || value.length <= limit) {
+        return value;
+    }
+    const end = /[\uD800-\uDBFF]/.test(value[limit - 1]) ? limit - 1 : limit;
+    return value.slice(0, end);
+}
 /**
  * `BrtBeginSXLocation` — MS-XLSB 2.4.259. The body's extent, then four positions inside it.
  *
@@ -670,6 +705,6 @@ function dataItemPayload(item) {
             // `fLoadDisplayName` — the caption follows.
             .writeUint8(1)
             .toUint8Array(),
-        wideString(item.caption)
+        encodeWideString(item.caption)
     ]);
 }

package/dist/esm/modules/excel/xlsx/xform/pivot-table/cache-field-xform.js

@@ -1,6 +1,7 @@
 import { pivotError } from "../../../core/pivot-table-types.js";
 import { BaseXform } from "../base-xform.js";
 import { RawXmlCollector } from "./raw-xml-collector.js";
+import { parseXsdBoolean } from "../xsd-values.js";
 import { parseOoxmlDate } from "#platform/utils/utils";
 /** Attribute keys on <cacheField> that are individually parsed (not collected into extraAttrs). */
 const KNOWN_CACHE_FIELD_KEYS = new Set(["name", "numFmtId"]);
@@ -189,7 +190,7 @@ function parseSharedItemValue(tag, attributes) {
             }
             return parseFloat(attributes.v);
         case "b":
-            return attributes.v === "1";
+            return parseXsdBoolean(attributes.v) ?? false;
         case "e":
             return pivotError(attributes.v ?? "");
         case "m":

package/dist/esm/modules/excel/xlsx/xform/pivot-table/pivot-cache-records-xform.js

@@ -2,6 +2,7 @@ import { isPivotError } from "../../../core/pivot-table-types.js";
 import { PivotTableError } from "../../../errors.js";
 import { BaseXform } from "../base-xform.js";
 import { formatDateForExcel } from "./cache-field.js";
+import { parseXsdBoolean } from "../xsd-values.js";
 import { parseOoxmlDate } from "#platform/utils/utils";
 import { xmlEncode } from "../../../../xml/encode.js";
 import { StdDocAttributes } from "../../../../xml/writer.js";
@@ -236,7 +237,7 @@ class PivotCacheRecordsXform extends BaseXform {
                 if (this.currentRecord) {
                     this.currentRecord.push({
                         type: "b",
-                        value: attributes.v === "1"
+                        value: parseXsdBoolean(attributes.v) ?? false
                     });
                 }
                 break;