documonster 0.20.1 → 0.20.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (32) hide show
  1. package/README.md +1 -1
  2. package/README_zh.md +1 -1
  3. package/dist/esm/modules/excel/core/cell.js +5 -6
  4. package/dist/esm/modules/excel/core/pivot-table.js +17 -9
  5. package/dist/esm/modules/excel/stream/xlsb-worksheet-reader.js +4 -6
  6. package/dist/esm/modules/excel/utils/cell-format-parse.js +112 -174
  7. package/dist/esm/modules/excel/utils/cell-format.js +42 -946
  8. package/dist/esm/modules/formula/functions/text.js +23 -631
  9. package/dist/esm/modules/pdf/excel-bridge.js +5 -5
  10. package/dist/esm/utils/number-format-render.js +814 -0
  11. package/dist/esm/utils/number-format.js +477 -0
  12. package/dist/esm/utils/utils.base.js +3 -70
  13. package/dist/iife/documonster.archive.iife.min.js +1 -1
  14. package/dist/iife/documonster.csv.iife.min.js +1 -1
  15. package/dist/iife/documonster.draw.iife.min.js +1 -1
  16. package/dist/iife/documonster.excel.iife.min.js +50 -50
  17. package/dist/iife/documonster.formula.iife.min.js +1 -1
  18. package/dist/iife/documonster.markdown.iife.min.js +1 -1
  19. package/dist/iife/documonster.mermaid.iife.min.js +1 -1
  20. package/dist/iife/documonster.pdf.iife.min.js +18 -18
  21. package/dist/iife/documonster.stream.iife.min.js +1 -1
  22. package/dist/iife/documonster.word.iife.min.js +60 -60
  23. package/dist/iife/documonster.xml.iife.min.js +1 -1
  24. package/dist/types/modules/excel/core/cell.d.ts +11 -0
  25. package/dist/types/modules/excel/core/pivot-table.d.ts +7 -0
  26. package/dist/types/modules/excel/utils/cell-format-parse.d.ts +13 -9
  27. package/dist/types/modules/excel/utils/cell-format.d.ts +21 -33
  28. package/dist/types/modules/excel/utils/text-metrics.d.ts +1 -0
  29. package/dist/types/utils/number-format-render.d.ts +47 -0
  30. package/dist/types/utils/number-format.d.ts +215 -0
  31. package/dist/types/utils/utils.base.d.ts +1 -9
  32. package/package.json +1 -1
@@ -1,5 +1,5 @@
1
1
  /*!
2
- * documonster v0.20.1
2
+ * documonster v0.20.2
3
3
  * Zero-dependency TypeScript toolkit for Excel, Word, PDF, CSV, Markdown, XML & ZIP — one API across Node.js, Bun & browsers.
4
4
  * (c) 2025 cjnoname
5
5
  * Released under the Apache-2.0 License
@@ -196,6 +196,15 @@ export declare function cellType(c: CellData): ValueType;
196
196
  export declare function cellEffectiveType(c: CellData): ValueType;
197
197
  export declare function cellToCsvString(c: CellData): string;
198
198
  export declare function cellGetValue(c: CellData): CellValueType;
199
+ /**
200
+ * The workbook's date system, from a cell.
201
+ *
202
+ * Needed at *assignment* time, not just at write time, because a time-of-day is anchored on the calendar date
203
+ * that is serial 0 — and that date differs between the two epochs. Reached through the row's worksheet, which is
204
+ * the only link a `CellData` has; a cell not yet attached to a workbook falls back to the 1900 system, which is
205
+ * also what the writers default to.
206
+ */
207
+ export declare function cellDate1904(cell: CellData): boolean;
199
208
  export declare function cellSetValue(c: CellData, v: CellValueInputType): void;
200
209
  /**
201
210
  * Set a date cell from plain calendar fields, saying which kind of date cell it is.
@@ -302,6 +311,8 @@ export interface CellView {
302
311
  readonly value: CellValueType;
303
312
  readonly numFmt: string | NumFmt | undefined;
304
313
  readonly text: string;
314
+ /** The workbook's date system, which turning a `Date` value back into the serial it displays needs. */
315
+ readonly date1904: boolean;
305
316
  readonly effectiveType: ValueType;
306
317
  /**
307
318
  * The cell's font — the object it *shares* with every other cell its row or column
@@ -31,6 +31,13 @@ export interface PivotTableSource {
31
31
  getSheetValues(): unknown[][];
32
32
  /** Dimensions of the source data (plain range record). */
33
33
  dimensions: RangeData;
34
+ /**
35
+ * The number format of a source cell, by the same 1-indexed row and column as `getColumn`.
36
+ *
37
+ * Row and column values are bare values, so this is the only route to a cell's format — and the format is what
38
+ * makes `45306` a date rather than a quantity. A source without it can still mark a column of `Date` values.
39
+ */
40
+ getNumberFormat?(rowNumber: number, columnNumber: number): string | undefined;
34
41
  }
35
42
  /**
36
43
  * A value field specification with optional per-field metric override.
@@ -3,10 +3,10 @@
3
3
  * fraction-of-day number, driven entirely by the *target cell's own* `numFmt`
4
4
  * — not by guessing the shape of the input string.
5
5
  *
6
- * This is the inverse of the render-direction logic in `cell-format.ts`
7
- * (`formatDate`, `isDateDisplayFormat`, `isTimeOnlyFormat`): instead of turning
8
- * a value into display text per a format, it turns display text back into a
9
- * value per that same format.
6
+ * This is the inverse of `@utils/number-format-render`: instead of turning a
7
+ * value into display text per a format, it turns display text back into a
8
+ * value per that same format. Both read the format through the one tokenizer
9
+ * in `@utils/number-format`, so a literal on one side is a literal on the other.
10
10
  *
11
11
  * ## How it works (and why it is not a heuristic)
12
12
  *
@@ -25,7 +25,7 @@
25
25
  * is what makes this robust across arbitrary formats instead of accreting a
26
26
  * patch per newly-discovered format shape.
27
27
  */
28
- type FieldRole = "year2" | "year4" | "month" | "day" | "hour" | "minute" | "second" | "ampm" | "ampmShort" | "elapsedHour" | "elapsedMinute" | "elapsedSecond";
28
+ type FieldRole = "year2" | "year4" | "month" | "day" | "weekday" | "hour" | "minute" | "second" | "secondFraction" | "ampm" | "ampmShort" | "elapsedHour" | "elapsedMinute" | "elapsedSecond";
29
29
  interface FieldSegment {
30
30
  kind: "field";
31
31
  role: FieldRole;
@@ -38,10 +38,12 @@ interface LiteralSegment {
38
38
  }
39
39
  type Segment = FieldSegment | LiteralSegment;
40
40
  /**
41
- * Compile a format section into ordered field/literal segments. Consecutive
42
- * literal characters coalesce into one literal segment; `mm`/`m` is resolved to
43
- * month vs. minute by adjacency to an hour (before) or second (after) field,
44
- * matching the render side's `resolveMonthOrMinute`.
41
+ * Compile a format's first section into ordered field/literal segments.
42
+ *
43
+ * The section is read by the shared number-format tokenizer, the same one that renders it and that
44
+ * decides on load whether a serial is a date — so a character is a field here exactly when it is a
45
+ * code there, and `m`/`mm` is a month or a minute by the same positional rule. Consecutive literal
46
+ * characters coalesce into one literal segment.
45
47
  */
46
48
  export declare function compileFormat(fmt: string): Segment[];
47
49
  export interface ParsedDateTime {
@@ -51,6 +53,8 @@ export interface ParsedDateTime {
51
53
  hour?: number;
52
54
  minute?: number;
53
55
  second?: number;
56
+ /** The digits typed after the seconds' decimal point. */
57
+ secondFraction?: string;
54
58
  elapsedSeconds?: number;
55
59
  }
56
60
  /**
@@ -1,45 +1,27 @@
1
1
  /**
2
- * Excel Cell Format Parser
3
- * A simplified implementation for formatting cell values according to Excel numFmt patterns
4
- * Supports: General, percentages, decimals, thousands separators, dates, currencies,
5
- * scientific notation, fractions, elapsed time, and more
2
+ * Display text for a cell value under its number format.
3
+ *
4
+ * Reading and rendering a number format is not done here: both live at Layer 0 in
5
+ * `@utils/number-format` and `@utils/number-format-render`, shared with the readers' date
6
+ * detection and the `TEXT` worksheet function, so that a character is a literal or a code for all
7
+ * of them at once. This file adds only what is specific to a cell — a `Date` value, a default
8
+ * date format for an unformatted date, and the date-kind classification `Cell.getDateKind` reports.
6
9
  */
7
10
  import type { NumFmt } from "../types.js";
8
11
  /**
9
- * Get format string from numFmtId
10
- * Handles default mappings for certain format IDs
11
- */
12
- export declare function getFormat(numFmtId: number): string;
13
- /**
14
- * Check if format is "General"
15
- */
16
- declare function isGeneral(fmt: string): boolean;
17
- /**
18
- * Check if format is a date format
19
- */
20
- declare function isDateFormat(fmt: string): boolean;
21
- /**
22
- * Main format function - formats a value according to Excel numFmt
23
- * @param fmt The Excel number format string (e.g., "0.00%", "#,##0", "yyyy-mm-dd")
24
- * @param val The value to format
12
+ * Format a value according to an Excel number format, as Excel displays it.
13
+ * @param fmt The Excel number format string (e.g. `"0.00%"`, `"#,##0"`, `"yyyy-mm-dd"`)
14
+ * @param val The value to format; a number is an Excel serial when the format names a date
25
15
  */
26
16
  export declare function format(fmt: string, val: number | string | boolean): string;
27
- export declare const cellFormat: {
28
- format: typeof format;
29
- getFormat: typeof getFormat;
30
- isDateFormat: typeof isDateFormat;
31
- isGeneral: typeof isGeneral;
32
- };
33
17
  /**
34
- * Check if format is a pure time format (no date components like y, m for month, d).
35
- * Time formats only contain: h, m (minutes in time context), s, AM/PM.
36
- * Excludes elapsed time formats like [h]:mm:ss which need the full serial number.
18
+ * Check if format is a pure time format: a clock reading with no date part.
19
+ * Elapsed-time formats such as `[h]:mm:ss` are excluded — they need the whole serial.
37
20
  */
38
21
  export declare function isTimeOnlyFormat(fmt: string): boolean;
39
22
  /**
40
- * Check if format is a date format (contains y, d, or month-m).
41
- * More precise than the internal isDateFormat — correctly handles elapsed time
42
- * formats like [h]:mm:ss (not a date format) and distinguishes month-m from minute-m.
23
+ * Check if format names a calendar date: a year, a day, or an `m` that reads as a month.
24
+ * Elapsed-time formats are not dates.
43
25
  */
44
26
  export declare function isDateDisplayFormat(fmt: string): boolean;
45
27
  /**
@@ -61,13 +43,19 @@ export declare function dateFormatKind(fmt: string | undefined): DateFormatKind;
61
43
  /**
62
44
  * Format a value according to the given format string.
63
45
  * Handles Date objects with timezone-independent Excel serial conversion.
46
+ *
47
+ * `date1904` is the workbook's date system. A `Date` read from a 1904 workbook has to become the same serial
48
+ * again: a calendar date survives either epoch, because its fields come back out unchanged, but an elapsed
49
+ * format reads the whole serial — and `[h]:mm` showed 36 hours as 35124 when the epoch was dropped here.
64
50
  */
65
- export declare function formatCellValue(value: Date | number | boolean | string, fmt: string, dateFormat?: string): string;
51
+ export declare function formatCellValue(value: Date | number | boolean | string, fmt: string, dateFormat?: string, date1904?: boolean): string;
66
52
  /** Minimal cell shape needed by {@link getCellDisplayText} — avoids importing Cell. */
67
53
  interface CellLike {
68
54
  value: unknown;
69
55
  numFmt: string | NumFmt | undefined;
70
56
  text: string;
57
+ /** The workbook's date system; the 1900 system when absent. */
58
+ date1904?: boolean;
71
59
  }
72
60
  /**
73
61
  * Get the formatted display text for a cell value.
@@ -126,6 +126,7 @@ export interface MeasurableCell {
126
126
  readonly value: unknown;
127
127
  readonly numFmt: string | NumFmt | undefined;
128
128
  readonly text: string;
129
+ readonly date1904?: boolean;
129
130
  readonly effectiveType: ValueType;
130
131
  readonly font: Partial<Font> | undefined;
131
132
  readonly alignment: Partial<Alignment> | undefined;
@@ -0,0 +1,47 @@
1
+ /**
2
+ * Render a value through an Excel number format.
3
+ *
4
+ * **One renderer for every caller.** A cell's display text and the `TEXT` worksheet function
5
+ * format a number the same way in Excel, but this library used to carry two implementations:
6
+ * `excel/utils/cell-format.ts` for display and a second copy inside the formula engine. They had
7
+ * different rounding, different fraction search, different month/minute rules and different ideas
8
+ * of what a literal is — `TEXT` read `0" hours"` as a date and dropped every literal from a
9
+ * percentage, while the display path placed the minus sign after a currency symbol. The formula
10
+ * engine sits below the Excel module and could not import the display renderer, so the shared one
11
+ * lives here, at Layer 0, where both can reach it.
12
+ *
13
+ * It renders from the tokens of `./number-format`, so the question "is this character a code or a
14
+ * literal" has one answer for rendering, for date detection on load, for date-kind classification
15
+ * and for input parsing.
16
+ */
17
+ export interface NumberFormatRenderOptions {
18
+ /**
19
+ * The workbook's epoch, which date codes read the serial in. Defaults to the 1900 epoch. A serial made
20
+ * from a `Date` has to be made with the same epoch passed here: calendar fields would survive a mismatch,
21
+ * but an elapsed format reads the whole serial and would be off by 1,462 days.
22
+ */
23
+ readonly date1904?: boolean;
24
+ }
25
+ /**
26
+ * Format `value` as Excel would display it under `fmt`.
27
+ *
28
+ * Text is shown through the format's text section (the fourth, or a trailing section carrying
29
+ * `@`), or as is when there is none. Booleans are `TRUE`/`FALSE`. An empty format is `General`.
30
+ * A value the format cannot show — a date past 9999 or before 1900, a negative time, a conditional
31
+ * format no section of which matches — is shown as hashes, as Excel shows it in a cell.
32
+ */
33
+ export declare function renderNumberFormat(fmt: string, value: number | string | boolean, options?: NumberFormatRenderOptions): string;
34
+ /**
35
+ * {@link renderNumberFormat}, but `undefined` for a value the format cannot show — which is where
36
+ * Excel's `TEXT()` returns `#VALUE!` and a cell shows hashes.
37
+ */
38
+ export declare function tryRenderNumberFormat(fmt: string, value: number | string | boolean, options?: NumberFormatRenderOptions): string | undefined;
39
+ /**
40
+ * Excel's `General`: at most eleven characters, not counting a minus sign, switching to scientific
41
+ * notation with six significant digits when a number cannot fit — `0.333333333`, `1.23457E+11`,
42
+ * `1234567891` for 1234567890.5. The shape of the algorithm is SheetJS's, which its authors calibrated
43
+ * against Excel; the rounding is decimal, at fifteen significant digits, so a half like -501059677.45 rounds
44
+ * away from zero as Excel does rather than as its nearest double would. It agreed with Excel on all 146
45
+ * values measured.
46
+ */
47
+ export declare function formatGeneral(value: number): string;
@@ -0,0 +1,215 @@
1
+ /**
2
+ * Excel number formats, read once.
3
+ *
4
+ * **Why this exists.** A number format such as `\$0.0,,"M"` or `[h]:mm:ss` is a small language,
5
+ * and this codebase used to read it with a separate scanner per consumer: the XLSX/XLSB readers
6
+ * deciding whether a serial is a date, the display formatter, the date-kind classifier, the
7
+ * pivot cache writer, the `TEXT` function and the input parser. Each one stripped a different
8
+ * subset of the constructs that make a character *literal* — quotes, backslash escapes,
9
+ * `_x` padding, `*x` fill, bracket tags — so each one mistook a different literal for a code.
10
+ * `\$0.0,,\M` turned a five-billion-dollar figure into `Invalid Date` on load because one of them
11
+ * read the escaped `M` as a month; `0_m` was a date to one reader and a number to another.
12
+ *
13
+ * Patching each scanner is how they drifted apart in the first place. So there is now one
14
+ * tokenizer: every consumer asks it what a format says, and a character is a code or a literal
15
+ * for all of them or for none.
16
+ *
17
+ * What it models:
18
+ *
19
+ * - **Sections** split on `;`, except inside quotes, brackets or after a backslash.
20
+ * - **Literals**: `"quoted"`, `\x`, and any character that is not a code.
21
+ * - **Layout**: `_x` (space the width of `x`) and `*x` (repeat `x` to fill).
22
+ * - **Bracket tags**: colours, conditions (`[>=100]`), locale/currency (`[$€-407]`), elapsed time
23
+ * (`[h]`, `[mm]`, `[ss]`) and anything else (`[DBNum1]`), each kept apart so a consumer can act
24
+ * on the one it needs.
25
+ * - **Date and time codes**, with each `m`/`mm` resolved to month or minute where it stands —
26
+ * Excel's rule is positional (minute directly after an hour or directly before a second), so
27
+ * `yyyy-mm-dd hh:mm` holds one of each and no format-wide flag can describe it.
28
+ * - **Number codes**: `0 # ?`, `.`, `,`, `%`, `E+`/`E-`, `/` and `@`, and the word `General`.
29
+ *
30
+ * `e` and `g` (era years in East Asian locales) are deliberately literals: an unquoted word such
31
+ * as `zero` in `0;-0;zero` must stay a word, and no locale this library renders uses them.
32
+ * `b` (Buddhist year) is a code, as it was for the XLSX reader before this module existed.
33
+ */
34
+ /** English month names, January first: what `mmm`/`mmmm`/`mmmmm` print and what input parsing accepts. */
35
+ export declare const MONTH_NAMES: readonly string[];
36
+ /** English weekday names, Sunday first: what `ddd`/`dddd` print and what input parsing accepts. */
37
+ export declare const DAY_NAMES: readonly string[];
38
+ /** A comparison in a conditional section such as `[>=100]`. */
39
+ export type FormatCompareOp = "=" | "<>" | "<" | "<=" | ">" | ">=";
40
+ /** What a date/time code stands for, after `m` has been resolved to month or minute. */
41
+ export type FormatDatePart = "year" | "buddhistYear" | "month" | "day" | "hour" | "minute" | "second";
42
+ /** One lexical element of a number-format section. */
43
+ export type FormatToken =
44
+ /** Text shown as written: a quoted run, an escaped character, or a character that is not a code. */
45
+ {
46
+ readonly kind: "literal";
47
+ readonly text: string;
48
+ }
49
+ /**
50
+ * An unquoted digit 1–9. It prints as itself, and is kept apart from `literal` because it is also the one
51
+ * place a digit is syntax: the fixed denominator of `# ?/16`. A quoted or escaped digit (`"8"`, `\8`) is a
52
+ * `literal` and never a denominator.
53
+ */
54
+ | {
55
+ readonly kind: "numeral";
56
+ readonly text: string;
57
+ }
58
+ /** `_x`: a space as wide as `x`. */
59
+ | {
60
+ readonly kind: "pad";
61
+ readonly char: string;
62
+ }
63
+ /** `*x`: `x` repeated to fill the cell. */
64
+ | {
65
+ readonly kind: "fill";
66
+ readonly char: string;
67
+ } | {
68
+ readonly kind: "color";
69
+ readonly name: string;
70
+ } | {
71
+ readonly kind: "condition";
72
+ readonly op: FormatCompareOp;
73
+ readonly value: number;
74
+ }
75
+ /** `[$…]`: a currency symbol and/or locale id. `symbol` is the text before any `-`. */
76
+ | {
77
+ readonly kind: "locale";
78
+ readonly symbol: string;
79
+ }
80
+ /** A bracket tag with no effect on the rendered text, such as `[DBNum1]`. */
81
+ | {
82
+ readonly kind: "bracket";
83
+ readonly text: string;
84
+ }
85
+ /**
86
+ * `[h]`, `[mm]`, `[ss]`: a total count of units rather than a clock reading. `fraction` is the number of
87
+ * decimal places after `[ss]` (`[ss].00`), and 0 otherwise.
88
+ */
89
+ | {
90
+ readonly kind: "elapsed";
91
+ readonly unit: "h" | "m" | "s";
92
+ readonly width: number;
93
+ readonly fraction: number;
94
+ }
95
+ /**
96
+ * A date or time code. `fraction` is the number of decimal places of a seconds code (`ss.000`); the point
97
+ * and its zeros belong to the code, not to the number layout, and 0 means there are none.
98
+ */
99
+ | {
100
+ readonly kind: "date";
101
+ readonly part: FormatDatePart;
102
+ readonly width: number;
103
+ readonly fraction: number;
104
+ }
105
+ /** `AM/PM` or `A/P`; `lower` when written in lower case, which is how Excel prints it back. */
106
+ | {
107
+ readonly kind: "ampm";
108
+ readonly short: boolean;
109
+ readonly lower: boolean;
110
+ } | {
111
+ readonly kind: "digit";
112
+ readonly char: "0" | "#" | "?";
113
+ } | {
114
+ readonly kind: "decimal";
115
+ } | {
116
+ readonly kind: "thousands";
117
+ } | {
118
+ readonly kind: "percent";
119
+ } | {
120
+ readonly kind: "exponent";
121
+ readonly sign: "+" | "-";
122
+ readonly upper: boolean;
123
+ } | {
124
+ readonly kind: "slash";
125
+ }
126
+ /** `@`: the cell's text. */
127
+ | {
128
+ readonly kind: "text";
129
+ } | {
130
+ readonly kind: "general";
131
+ };
132
+ /** One section of a format, with the facts every consumer asks about computed once. */
133
+ export interface FormatSection {
134
+ /** The section as written. */
135
+ readonly source: string;
136
+ readonly tokens: readonly FormatToken[];
137
+ /** A year, month or day code. */
138
+ readonly hasDate: boolean;
139
+ /** An hour, minute or second code, or an AM/PM marker. */
140
+ readonly hasTime: boolean;
141
+ /** An elapsed-time tag such as `[h]`. */
142
+ readonly hasElapsed: boolean;
143
+ /** The `@` text placeholder. */
144
+ readonly hasText: boolean;
145
+ /** The `General` keyword. */
146
+ readonly hasGeneral: boolean;
147
+ /** The section's condition, if it carries one. */
148
+ readonly condition: {
149
+ readonly op: FormatCompareOp;
150
+ readonly value: number;
151
+ } | undefined;
152
+ }
153
+ /** A whole format: its sections, and which of them formats text. */
154
+ export interface ParsedNumberFormat {
155
+ readonly source: string;
156
+ readonly sections: readonly FormatSection[];
157
+ /**
158
+ * The sections that format numbers, in order. A section carrying `@` is the *text* section and
159
+ * is excluded, which is what makes `0.00;@` a one-section number format rather than one whose
160
+ * negative numbers are rendered as text.
161
+ */
162
+ readonly numberSections: readonly FormatSection[];
163
+ /** The section that formats a text value, or `undefined` when text is shown as is. */
164
+ readonly textSection: FormatSection | undefined;
165
+ }
166
+ /**
167
+ * Split a format into its `;`-separated sections (positive; negative; zero; text).
168
+ *
169
+ * A `;` inside `"…"`, inside `[…]`, or taken as the argument of `\`, `_` or `*` is part of a section,
170
+ * not a separator — the same rules `tokenizeFormatSection` reads a character by.
171
+ */
172
+ export declare function splitFormatSections(fmt: string): string[];
173
+ /**
174
+ * Read one section into tokens.
175
+ *
176
+ * Every construct that makes a character literal is recognised here and only here, so no consumer
177
+ * can mistake `\M`, `"M"`, `_M` or `*M` for a month.
178
+ */
179
+ export declare function tokenizeFormatSection(section: string): FormatToken[];
180
+ /**
181
+ * Parse a whole format. Results are cached: a reader asks about the same handful of formats once
182
+ * per cell.
183
+ */
184
+ export declare function parseNumberFormat(fmt: string): ParsedNumberFormat;
185
+ /** What a format's first section says about dates and times. */
186
+ export interface NumberFormatFacets {
187
+ /** A year, month or day code. */
188
+ readonly date: boolean;
189
+ /** An hour, minute or second code, or AM/PM. */
190
+ readonly time: boolean;
191
+ /** An elapsed-time tag such as `[h]`. */
192
+ readonly elapsed: boolean;
193
+ /** The `@` text placeholder. */
194
+ readonly text: boolean;
195
+ /** `General`, or no format at all. */
196
+ readonly general: boolean;
197
+ }
198
+ /**
199
+ * The date and time facts of a format, read from its **first** section — the one that applies to
200
+ * a positive serial, and therefore to every date. `";;;dd"` hides numbers; it is not a date format.
201
+ */
202
+ export declare function numberFormatFacets(fmt: string | null | undefined): NumberFormatFacets;
203
+ /**
204
+ * Whether a cell carrying this format holds a date: its first section names a calendar or clock code
205
+ * outside every literal, and is not a text format.
206
+ *
207
+ * This is the rule every reader applies when deciding whether a stored serial becomes a `Date`.
208
+ *
209
+ * **An elapsed tag on its own does not count.** `[h]` or `[ss]` is a quantity of time, and a `Date` would
210
+ * misstate it — and could not hold it past a few thousand years. `[h]:mm:ss` still counts, through its
211
+ * clock codes, which is the reading these readers have always given both forms.
212
+ */
213
+ export declare function isDateFmt(fmt: string | null | undefined): boolean;
214
+ /** Whether a format is `General` — or empty, which Excel treats the same way. */
215
+ export declare function isGeneralFormat(fmt: string | null | undefined): boolean;
@@ -72,15 +72,7 @@ export declare function encodeOoxmlEscape(text: string): string;
72
72
  */
73
73
  export declare function encodeOoxmlAttr(text: string): string;
74
74
  export declare function validInt(value: string | number): number;
75
- /**
76
- * Split an Excel numFmt string by semicolons, respecting quoted strings and brackets.
77
- *
78
- * Excel numFmt can have up to 4 sections: `positive ; negative ; zero ; text`.
79
- * Semicolons inside `"..."` (literal text) or `[...]` (locale/color tags) must NOT
80
- * be treated as section separators.
81
- */
82
- export declare function splitFormatSections(fmt: string): string[];
83
- export declare function isDateFmt(fmt: string | null | undefined): boolean;
75
+ export { isDateFmt, splitFormatSections } from "./number-format.js";
84
76
  export declare function parseBoolean(value: unknown): boolean;
85
77
  export declare function range(start: number, stop: number, step?: number): Generator<number>;
86
78
  export declare function toSortedArray<T>(values: Iterable<T>): T[];
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "documonster",
3
- "version": "0.20.1",
3
+ "version": "0.20.2",
4
4
  "description": "Zero-dependency TypeScript toolkit for Excel, Word, PDF, CSV, Markdown, XML & ZIP — one API across Node.js, Bun & browsers.",
5
5
  "keywords": [
6
6
  "archive",