Skip to content

JSE-18: javascript-excel/format, the number-format renderer - #92

Merged
securedeveloper merged 7 commits into
mainfrom
jse-18-format
Nov 16, 2026
Merged

securedeveloper merged 7 commits into
mainfrom
jse-18-format

Conversation

@securedeveloper

@securedeveloper securedeveloper commented Nov 16, 2026 •

Copy link
Copy Markdown
Owner

JSE-18: javascript-excel/format, the number-format renderer. It renders a value the way Excel shows it in a cell. react-xlsx-viewer 1.0 needs it, and import previews and "as displayed" text can use it too.

Release timing: Afzal decided (2026-11-16) that /format ships in 2.0, with /import, in 2.0.0-alpha.3. The minor changeset goes into that prerelease. The docs say so: the §5.7 intro, the §2 entry table, §3.5.5, §12 Q14, the §13 roadmap row and both READMEs.

API (docs/api.md §5.7)

import { formatCell, formatValue } from "javascript-excel/format";
formatValue(1234.5, "#,##0.00");                   // { text: "1,234.50", align: "right" }
formatValue(-12.5, "0.0;[Red]-0.0").color;         // "FFFF0000"
formatValue(45306, "dddd, mmmm d, yyyy").text;     // "Monday, January 15, 2024"
formatCell(cell, { locale: "de-DE", date1904 });   // the cell's own numFmt and cached value
  • Result. FormattedValue has { text, color?, fill?, align }:
    • color is the section colour as ARGB;
    • fill is a *x repeat character and its position, not expanded in text. Dates Excel can't show come back as a # fill;
    • align is Excel's general alignment for the value type.
  • Options: locale (default en-US), date1904, dateZone (for Date inputs only), generalWidth (default 11), indexedColors (for [ColorN]).
  • Dates come from serials. Formatting is arithmetic on the serial, never a local-zone Date, so the output is the same in every time zone. Viewers read with dates: 'serial'. Date inputs go through dateToSerial, like the writer.
  • Robust on untrusted codes. It never throws on a format code from a file. The parser is linear with no nested-quantifier regexes, unknown characters are literal, at most 4 sections are used, and compiled codes are cached up to 1,000.

Coverage

  • Sections, conditions and colours:
    • sections (pos;neg;zero;text) and conditions ([>100], …);
    • the eight named colours and [Color1]–[Color56] (from the workbook palette when given).
  • Number formatting:
    • placeholders 0 # ?, literals between placeholders (000-00-0000);
    • thousands grouping, scaling commas, percent;
    • scientific and engineering notation, fractions (best approximation or a fixed denominator);
    • @, quoted and escaped literals, _x spacing, *x fill;
    • General (11 characters, scientific beyond).
  • Dates and times:
    • every date/time token, with the month/minute rule;
    • AM/PM forms and fractional seconds;
    • elapsed [h] [m] [s];
    • Excel's 1900 calendar (day 0, the fictitious 1900-02-29, Excel's weekdays), and rounding to the shown second.
  • Locale:
    • [$€-407] and [$-409] tags (common LCIDs), and the system long-date/time tags [$-F800]/[$-F400]/x-sysdate/x-systime;
    • built-in ids: fixed ones from §11.2; 14/22 as the locale's short date; 27–31/36/50–58 as short date and 32–35 as time; 5–8/41–44 with their en-US codes;
    • separators, month/day names and the short date come from Intl, so no locale tables ship.

Reference: LibreOffice "as shown" export (CI job LibreOffice)

  • What it compares. test/format/libreoffice.test.ts writes every case of test/format/cases.ts, plus every number-formatted cell of conformance files 10-number-formats and 11-number-formats-locale, to one workbook. LibreOffice 26.2 exports it to CSV with "save cell contents as shown" in en-US, and each cell is compared with formatCell(cell, { locale: 'en-US' }).
  • Result. 439 probes: 344 identical, 95 different for a known reason, 0 unexplained. The job fails on any unexplained difference.
  • Known reasons. Each one is a rule that proves its cause where it can. For example, time rounding is accepted only if formatting the value truncated to the second gives LibreOffice's text. The reasons:
    • the 1900 calendar (LibreOffice has no day 0 or 1900-02-29): 27;
    • LibreOffice truncates seconds where Excel rounds: 27;
    • LibreOffice's General isn't width-limited: 12;
    • LibreOffice drops a dangling decimal point: 7;
    • LibreOffice uses Excel's real codes for ids 39/40/47 where we use the spec table: 7;
    • LibreOffice pads ? with U+2007: 9;
    • am/pm case: 5;
    • LibreOffice has no Buddhist-year tokens: 1.
  • Recorded for Excel. docs/api.md §5.7.4 lists each difference as [to verify] in Excel. Conformance file 10 gains a Display sheet whose rows show the expected Excel output for these rules, and docs/conformance.md (regenerated) adds it as an open item for the manual Excel check.

Packaging and checks

  • Wiring. New subpath ./format in exports (with types conditions), the tsdown entry, entries.test.ts, the smoke/consumer expectations (runtime and type checks, plus a tree-shaking marker), the TypeDoc entry, and a README section with a type-checked snippet.
  • Zero runtime dependencies. It imports only cellText, dateToSerial and the built-in table from the core.
  • Size. dist/format.js is 36.2 kB unminified, 11.7 kB gzipped.
  • Throughput. On an Apple-silicon laptop with Node 26: 200,000 calls take 873 ms with #,##0.00, 603 ms with yyyy-mm-dd hh:mm, and 1,209 ms with General. That's about 3–6 µs per value.
  • Tests. 98 unit tests in test/format/format.test.ts, with Excel outputs per token class, locales, colours, fills, the 1900 calendar, rounding, odd codes that must not throw, and formatCell.
  • Local (Node 26): typecheck clean, npm test 704 passed, publint, smoke (tsc node16/nodenext/bundler; the unused-entry tree-shaking check drops /format), docs snippets, examples and the API reference build.
  • CI: all jobs green, including Consumer TS and LibreOffice.

Docs

  • api.md §5.7 (new; §5.6 is /import): API, the coverage table, built-in ids, locale, and reference results.
  • The §2 entry table, §3.5.5, §12 Q14 (now in 2.0, from 2.0.0-alpha.3) and the §13 roadmap row are updated. The branch has main merged in (JSE-19 /import, JSE-20), with both entries kept everywhere.

No new dependencies.

@securedeveloper
securedeveloper merged commit 5ad9340 into main Nov 16, 2026
9 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant