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

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

@@ -374,7 +374,7 @@ function toCivilDate(value, date1904) {
  * the only link a `CellData` has; a cell not yet attached to a workbook falls back to the 1900 system, which is
  * also what the writers default to.
  */
-function cellDate1904(cell) {
+export function cellDate1904(cell) {
     const workbook = cell.row?.worksheet?._workbook;
     return workbook?.properties?.date1904 === true;
 }
@@ -659,11 +659,7 @@ export function cellText(c) {
     return c._value.toString();
 }
 export function cellDisplayText(c) {
-    return getCellDisplayText({
-        value: c._value.value,
-        numFmt: c.style.numFmt,
-        text: c._value.toString()
-    });
+    return getCellDisplayText(cellView(c));
 }
 const HTML_ESCAPE_MAP = {
     '"': """,
@@ -686,6 +682,9 @@ export function cellView(c) {
         get text() {
             return c._value.toString();
         },
+        get date1904() {
+            return cellDate1904(c);
+        },
         get effectiveType() {
             return c._value.effectiveType;
         },

package/dist/esm/modules/excel/core/pivot-table.js

@@ -1,16 +1,22 @@
+import { cellNumFmt } from "./cell.js";
 import { METRIC_DISPLAY_NAMES, pivotError, isPivotError, formatPivotError, VALID_SUBTOTALS } from "./pivot-table-types.js";
 import { rangeCreate, rangeExpand } from "./range.js";
 import { rowDimensions, rowValues } from "./row.js";
 import { tableModel } from "./table.js";
-import { columnValues, getColumn, getRow, getSheetName, getSheetValues } from "./worksheet-core.js";
+import { columnValues, findCell, getColumn, getRow, getSheetName, getSheetValues } from "./worksheet-core.js";
 import { PivotTableError } from "../errors.js";
 import { colCache } from "../utils/col-cache.js";
-import { range } from "#platform/utils/utils";
+import { isDateFmt, range } from "#platform/utils/utils";
 // Re-export the pure OOXML data types/constants that were relocated to
 // pivot-table-types.ts, preserving backward compatibility for existing
 // `import { X } from "./pivot-table.js"` call sites (worksheet.ts,
 // surface/pivot.ts, etc.).
 export { METRIC_DISPLAY_NAMES, pivotError, isPivotError, formatPivotError, VALID_SUBTOTALS };
+/** A cell's number format as a code, whichever of its two shapes it is stored in. */
+function formatCodeOf(cell) {
+    const numFmt = cell === undefined ? undefined : cellNumFmt(cell);
+    return typeof numFmt === "string" ? numFmt : numFmt?.formatCode;
+}
 /** Extract the values array from a getRow result (RowData or `{ values }`). */
 function rowValuesOf(row) {
     return "cells" in row ? rowValues(row) : row.values;
@@ -91,6 +97,10 @@ function createTableSourceAdapter(table) {
             }
             return { values };
         },
+        getNumberFormat(rowNumber, columnNumber) {
+            // The table's rows are a copy of its values; the formats stay on the worksheet's cells.
+            return formatCodeOf(findCell(table.worksheet, startRow + rowNumber - 1, startCol + columnNumber - 1));
+        },
         getSheetValues() {
             // Return sparse array where index 1 is header row, and subsequent indices are data rows
             const result = [];
@@ -129,6 +139,7 @@ function resolveSource(model) {
             getRow: (rowNumber) => getRow(ws, rowNumber),
             getColumn: (columnNumber) => getColumn(ws, columnNumber),
             getSheetValues: () => getSheetValues(ws),
+            getNumberFormat: (rowNumber, columnNumber) => formatCodeOf(findCell(ws, rowNumber, columnNumber)),
             get dimensions() {
                 return computeSourceDimensions(ws);
             }
@@ -492,8 +503,7 @@ function makeCacheFields(source, fieldNamesWithSharedItems, valueFieldNames) {
         const columnValues = columnValuesOf(source.getColumn(columnIndex));
         let sawDate = false;
         for (let i = DATA_START_INDEX; i < columnValues.length; i++) {
-            const cell = columnValues[i];
-            const value = unwrapCellValue(cell);
+            const value = unwrapCellValue(columnValues[i]);
             if (value === null || value === undefined) {
                 continue;
             }
@@ -501,11 +511,9 @@ function makeCacheFields(source, fieldNamesWithSharedItems, valueFieldNames) {
                 sawDate = true;
                 continue;
             }
-            const numFmt = cell
-                ?.style?.numFmt;
-            const code = typeof numFmt === "string" ? numFmt : numFmt?.formatCode;
-            // A date format names a date or time component outside a literal.
-            if (typeof code === "string" && /(?:^|[^\\])[dmyhs]/i.test(code)) {
+            // A date format, by the same rule the readers use to turn a serial into a `Date`. Column values are bare
+            // values, so the format has to come from the cell itself.
+            if (typeof value === "number" && isDateFmt(source.getNumberFormat?.(i, columnIndex))) {
                 sawDate = true;
                 continue;
             }

package/dist/esm/modules/excel/stream/xlsb-worksheet-reader.js

@@ -185,12 +185,10 @@ function readWideString(reader) {
 /**
  * A serial wearing a date format is a date — through `isDateFmt`, the same rule every other reader applies.
  *
- * This used to carry its own detector and its own epoch expression, and both differed from the buffered reader's.
- * The detector disagreed on four of forty-five real formats: it did not take only the first section, so `";;;dd"`
- * and `"@;;;yyyy"` were dates here and numbers there, and it stripped `\\`-escapes and lacked the `b`/`y` codes, so
- * `"\\d0"` and `"y"` were numbers here and dates there. The same workbook therefore read back differently
- * depending on which container it arrived in and whether the caller streamed it — the one thing two readers of the
- * same document must not do, as `readXlsbInto` says in as many words.
+ * This used to carry its own detector and its own epoch expression, and both differed from the buffered reader's,
+ * so the same workbook read back differently depending on which container it arrived in and whether the caller
+ * streamed it — the one thing two readers of the same document must not do, as `readXlsbInto` says in as many words.
+ * There is now one tokenizer for number formats (`@utils/number-format`), shared with display and `TEXT`.
  */
 function dated(value, numberFormat, context) {
     return isDateFmt(numberFormat) ? excelToDate(value, context.date1904) : value;

package/dist/esm/modules/excel/utils/cell-format-parse.js

@@ -3,10 +3,10 @@
  * fraction-of-day number, driven entirely by the *target cell's own* `numFmt`
  * — not by guessing the shape of the input string.
  *
- * This is the inverse of the render-direction logic in `cell-format.ts`
- * (`formatDate`, `isDateDisplayFormat`, `isTimeOnlyFormat`): instead of turning
- * a value into display text per a format, it turns display text back into a
- * value per that same format.
+ * This is the inverse of `@utils/number-format-render`: instead of turning a
+ * value into display text per a format, it turns display text back into a
+ * value per that same format. Both read the format through the one tokenizer
+ * in `@utils/number-format`, so a literal on one side is a literal on the other.
  *
  * ## How it works (and why it is not a heuristic)
  *
@@ -25,24 +25,14 @@
  * is what makes this robust across arbitrary formats instead of accreting a
  * patch per newly-discovered format shape.
  */
-const MONTHS_LONG = [
-    "january",
-    "february",
-    "march",
-    "april",
-    "may",
-    "june",
-    "july",
-    "august",
-    "september",
-    "october",
-    "november",
-    "december"
-];
+import { DAY_NAMES, MONTH_NAMES, numberFormatFacets, splitFormatSections, tokenizeFormatSection } from "../../../utils/number-format.js";
+const MONTHS_LONG = MONTH_NAMES.map(m => m.toLowerCase());
 const MONTHS_SHORT = MONTHS_LONG.map(m => m.slice(0, 3));
+const WEEKDAYS = DAY_NAMES.map(d => d.toLowerCase());
+const WEEKDAYS_SHORT = WEEKDAYS.map(d => d.slice(0, 3));
 /** A field consumes letters (names, AM/PM) rather than digits. */
 function isAlphaField(role) {
-    return role === "month" || role === "ampm" || role === "ampmShort";
+    return role === "month" || role === "weekday" || role === "ampm" || role === "ampmShort";
 }
 /**
  * Time-tail roles that may be omitted from the *end* of the input. Excel treats
@@ -53,181 +43,114 @@ const OMITTABLE_TRAILING_ROLES = new Set([
     "hour",
     "minute",
     "second",
+    "secondFraction",
     "ampm",
     "ampmShort"
 ]);
 /**
- * Take the first (positive) of a format's up-to-four `;`-separated sections,
- * honouring quoted spans and backslash escapes so a `;` inside a literal does
- * not split the section.
- */
-function firstSection(fmt) {
-    let quoted = false;
-    for (let i = 0; i < fmt.length; i++) {
-        const ch = fmt[i];
-        if (ch === "\\") {
-            i++;
-        }
-        else if (ch === '"') {
-            quoted = !quoted;
-        }
-        else if (ch === ";" && !quoted) {
-            return fmt.slice(0, i);
-        }
-    }
-    return fmt;
-}
-// Sticky (`y`) so it only matches at the exact cursor, and case-insensitive
-// (`i`) because Excel format tokens are case-insensitive (`YYYY-MM-DD`,
-// `AM/PM`, `am/pm`, `A/P` are all valid and mean the same thing).
-const TOKEN_RE = /yyyy|yy|mmmmm|mmmm|mmm|AM\/PM|A\/P|\[h+\]|\[m+\]|\[s+\]|mm|m|dd|d|hh|h|ss|s/iy;
-/**
- * Compile a format section into ordered field/literal segments. Consecutive
- * literal characters coalesce into one literal segment; `mm`/`m` is resolved to
- * month vs. minute by adjacency to an hour (before) or second (after) field,
- * matching the render side's `resolveMonthOrMinute`.
+ * Compile a format's first section into ordered field/literal segments.
+ *
+ * The section is read by the shared number-format tokenizer, the same one that renders it and that
+ * decides on load whether a serial is a date — so a character is a field here exactly when it is a
+ * code there, and `m`/`mm` is a month or a minute by the same positional rule. Consecutive literal
+ * characters coalesce into one literal segment.
  */
 export function compileFormat(fmt) {
-    const section = firstSection(fmt);
+    const tokens = tokenizeFormatSection(splitFormatSections(fmt)[0]);
     const segments = [];
-    // Indices (into `segments`) of month/minute placeholders awaiting resolution.
-    const ambiguous = [];
     let literal = "";
-    let literalHasLetters = false;
     const flushLiteral = () => {
         if (literal.length > 0) {
-            segments.push({ kind: "literal", hasLetters: literalHasLetters });
+            segments.push({ kind: "literal", hasLetters: /\p{L}/u.test(literal) });
             literal = "";
-            literalHasLetters = false;
-        }
-    };
-    const pushLiteralChar = (ch) => {
-        literal += ch;
-        if (/[A-Za-z]/.test(ch)) {
-            literalHasLetters = true;
         }
     };
     const pushField = (role) => {
         flushLiteral();
         segments.push({ kind: "field", role });
     };
-    for (let i = 0; i < section.length;) {
-        const ch = section[i];
-        // Quoted literal span.
-        if (ch === '"') {
-            const end = section.indexOf('"', i + 1);
-            const inner = section.slice(i + 1, end === -1 ? section.length : end);
-            for (const c of inner) {
-                pushLiteralChar(c);
-            }
-            i = end === -1 ? section.length : end + 1;
-            continue;
-        }
-        // Backslash escape — next char is a literal.
-        if (ch === "\\" && i + 1 < section.length) {
-            pushLiteralChar(section[i + 1]);
-            i += 2;
-            continue;
-        }
-        // Bracketed span: elapsed-time ([h]/[mm]/[s]) is a field; anything else
-        // ([Red], [$-409], locale/condition) is display-only — skip entirely.
-        if (ch === "[") {
-            const end = section.indexOf("]", i + 1);
-            const body = section.slice(i + 1, end === -1 ? section.length : end);
-            const head = body[0]?.toLowerCase();
-            if (/^h+$/i.test(body)) {
-                pushField("elapsedHour");
-            }
-            else if (/^m+$/i.test(body)) {
-                pushField("elapsedMinute");
-            }
-            else if (/^s+$/i.test(body)) {
-                pushField("elapsedSecond");
-            }
-            void head;
-            i = end === -1 ? section.length : end + 1;
-            continue;
+    for (const token of tokens) {
+        switch (token.kind) {
+            case "date":
+                switch (token.part) {
+                    case "year":
+                        pushField(token.width <= 2 ? "year2" : "year4");
+                        break;
+                    case "month":
+                        pushField("month");
+                        break;
+                    case "day":
+                        pushField(token.width <= 2 ? "day" : "weekday");
+                        break;
+                    case "hour":
+                        pushField("hour");
+                        break;
+                    case "minute":
+                        pushField("minute");
+                        break;
+                    case "second":
+                        pushField("second");
+                        break;
+                }
+                break;
+            case "elapsed":
+                pushField(token.unit === "h"
+                    ? "elapsedHour"
+                    : token.unit === "m"
+                        ? "elapsedMinute"
+                        : "elapsedSecond");
+                break;
+            case "numeral":
+                literal += token.text;
+                break;
+            case "ampm":
+                pushField(token.short ? "ampmShort" : "ampm");
+                break;
+            case "literal":
+                literal += token.text;
+                break;
+            case "locale":
+                literal += token.symbol;
+                break;
+            case "pad":
+                literal += " ";
+                break;
+            case "digit":
+                literal += token.char;
+                break;
+            case "decimal":
+                literal += ".";
+                break;
+            case "thousands":
+                literal += ",";
+                break;
+            case "percent":
+                literal += "%";
+                break;
+            case "slash":
+                literal += "/";
+                break;
+            default:
+                // Fill, colour, condition and other bracket tags are display-only.
+                break;
         }
-        // Date/time token?
-        TOKEN_RE.lastIndex = i;
-        const m = TOKEN_RE.exec(section);
-        if (m && m.index === i) {
-            const raw = m[0].toLowerCase();
-            switch (raw) {
-                case "yyyy":
-                    pushField("year4");
-                    break;
-                case "yy":
-                    pushField("year2");
-                    break;
-                case "mmmmm":
-                case "mmmm":
-                case "mmm":
-                    pushField("month");
-                    break;
-                case "dd":
-                case "d":
-                    pushField("day");
-                    break;
-                case "hh":
-                case "h":
-                    pushField("hour");
-                    break;
-                case "ss":
-                case "s":
-                    pushField("second");
-                    break;
-                case "am/pm":
-                    pushField("ampm");
-                    break;
-                case "a/p":
-                    pushField("ampmShort");
-                    break;
-                case "mm":
-                case "m":
-                    // Provisionally month; resolved after the whole scan.
-                    flushLiteral();
-                    ambiguous.push(segments.length);
-                    segments.push({ kind: "field", role: "month" });
-                    break;
-            }
-            i += m[0].length;
-            continue;
+        // `ss.00` and `[ss].00`: the tokenizer has already attached the decimal places to the seconds code.
+        if ((token.kind === "date" || token.kind === "elapsed") && token.fraction > 0) {
+            pushField("secondFraction");
         }
-        // Anything else is a literal separator character.
-        pushLiteralChar(ch);
-        i++;
     }
     flushLiteral();
-    // Resolve each ambiguous m/mm: it is a minute if the nearest field before it
-    // is an hour, or the nearest field after it is a second (mirroring the
-    // render-side adjacency rule).
-    const fieldRoleAt = (segIndex, dir) => {
-        for (let k = segIndex + dir; k >= 0 && k < segments.length; k += dir) {
-            const seg = segments[k];
-            if (seg.kind === "field") {
-                return seg.role;
-            }
-        }
-        return undefined;
-    };
-    for (const idx of ambiguous) {
-        const before = fieldRoleAt(idx, -1);
-        const after = fieldRoleAt(idx, 1);
-        if (before === "hour" || before === "elapsedHour" || after === "second") {
-            segments[idx].role = "minute";
-        }
-    }
     return segments;
 }
-function monthIndexFromName(word) {
+/** A full name or its three-letter abbreviation — not any word that happens to start like one. */
+function nameIndex(word, full, short) {
     const lower = word.toLowerCase();
-    const fullIdx = MONTHS_LONG.indexOf(lower);
-    if (fullIdx !== -1) {
-        return fullIdx;
-    }
-    const shortIdx = MONTHS_SHORT.indexOf(lower.slice(0, 3));
-    return shortIdx !== -1 ? shortIdx : undefined;
+    const fullIdx = full.indexOf(lower);
+    return fullIdx !== -1 ? fullIdx : short.indexOf(lower);
+}
+function monthIndexFromName(word) {
+    const idx = nameIndex(word, MONTHS_LONG, MONTHS_SHORT);
+    return idx !== -1 ? idx : undefined;
 }
 /** True if the compiled format carries at least one date field. */
 function hasDateField(segments) {
@@ -240,6 +163,7 @@ function hasTimeField(segments) {
         (s.role === "hour" ||
             s.role === "minute" ||
             s.role === "second" ||
+            s.role === "secondFraction" ||
             s.role === "elapsedHour" ||
             s.role === "elapsedMinute" ||
             s.role === "elapsedSecond"));
@@ -300,7 +224,13 @@ function matchSegments(segments, input) {
                 return remainingAreOptional(segments, s) ? finalize() : undefined;
             }
             const word = lm[0];
-            if (seg.role === "month") {
+            if (seg.role === "weekday") {
+                // A weekday name is redundant with the date it sits beside; it must only be a real one.
+                if (nameIndex(word, WEEKDAYS, WEEKDAYS_SHORT) === -1) {
+                    return undefined;
+                }
+            }
+            else if (seg.role === "month") {
                 const idx = monthIndexFromName(word);
                 if (idx === undefined) {
                     return undefined;
@@ -329,6 +259,9 @@ function matchSegments(segments, input) {
             case "year4":
                 result.year = num;
                 break;
+            case "secondFraction":
+                result.secondFraction = digits;
+                break;
             case "year2":
                 // The `yy` token only controls display width; a typed 4-digit year is
                 // taken verbatim, a 1–2(–3) digit year uses the 1900/2000 pivot.
@@ -403,7 +336,8 @@ function matchSegments(segments, input) {
  * meaning or the input does not conform to it.
  */
 export function parseValueByFormat(fmt, input) {
-    if (input.trim() === "") {
+    // A text format (`yyyy-mm-dd@`) keeps what is typed as text, as the readers keep its values numbers.
+    if (input.trim() === "" || numberFormatFacets(fmt).text) {
         return undefined;
     }
     const segments = compileFormat(fmt);
@@ -421,12 +355,16 @@ export function parseValueByFormat(fmt, input) {
         const h = parsed.hour ?? 0;
         const m = parsed.minute ?? 0;
         const s = parsed.second ?? 0;
-        return ((parsed.elapsedSeconds ?? 0) + h * 3600 + m * 60 + s) / 86400;
+        const fraction = Number("0." + (parsed.secondFraction ?? "0"));
+        return ((parsed.elapsedSeconds ?? 0) + h * 3600 + m * 60 + s + fraction) / 86400;
     }
     if (parsed.year === undefined || parsed.month === undefined || parsed.day === undefined) {
         return undefined;
     }
-    const date = new Date(Date.UTC(parsed.year, parsed.month - 1, parsed.day, parsed.hour ?? 0, parsed.minute ?? 0, parsed.second ?? 0));
+    const date = new Date(Date.UTC(parsed.year, parsed.month - 1, parsed.day, parsed.hour ?? 0, parsed.minute ?? 0, parsed.second ?? 0, 
+    // A `Date` holds whole milliseconds: take the first three typed digits, so .9999… stays on its
+    // second however many nines follow — converting through a double first rounded it up to 1.
+    Number((parsed.secondFraction ?? "").slice(0, 3).padEnd(3, "0"))));
     // Reject overflowed components (e.g. day 31 in a 30-day month) rather than
     // silently rolling over into the next month.
     if (date.getUTCMonth() !== parsed.month - 1 || date.getUTCDate() !== parsed.day) {