fix(format): support thousands grouping and format sections in numberFormat/TEXT (HF-287)

[marcin-kordas-hoc]

What & why

TEXT / numberFormat only understood a single simple mask ([#0]+(\.[#0]*)?); complex masks emitted garbage — e.g. TEXT(1234.5,"#,##0.00") → "1235,##0.00". It ignored thousands grouping (#,##0), format sections (;), and HF's configured decimalSeparator/thousandSeparator.

How (Option A — extend the formatter in place; no grammar rewrite, no public API, no i18n)

• src/format/parser.ts: widen numberFormatRegex to admit , into the flat character class ([#0,]+(\.[#0]*)?) — no nested quantifier (keeps the DEV-2120 ReDoS discipline); white-box shape test via exported NUMBER_FORMAT_REGEX_SOURCE.
• src/format/format.ts: section split (positive;negative;zero, quote/escape-aware), grouping with config.thousandSeparator, decimal via config.decimalSeparator, sign on abs, color-tag strip applied AFTER the stringifyCurrency callback (doesn't disturb that extension point), parse-failure falls back to the cleaned format string.
• Docs (compatibility-with-microsoft-excel.md) reworded as nuances; CHANGELOG under Fixed.

Contract note — stringifyDateTime / stringifyDuration

The color-tag strip sits between the stringifyCurrency callback and date/time dispatch, so those two callbacks now receive the format string without color tags: a custom stringifyDateTime sees dd-mm-yyyy, not [Red]dd-mm-yyyy. stringifyCurrency still receives the raw string.

That placement is what fixes [Red]dd-mm-yyyy: the d in Red used to be read as a day token, so the mask rendered [Re1]01-01-1900. Stripping only inside the number path would leave that bug in place. Noted in the CHANGELOG entry.

Verified against Excel (HF-287 repro table)

The $#,##0.00 case was originally reported in #1138 (=TEXT(1234.567,"$#,##0.00") → $1235,##0.00 instead of $1,234.57), which was closed in favour of #1145. HF-24 shipped that issue's alternative — the stringifyCurrency callback; this PR delivers its primary ask, so the CHANGELOG entry points at #1145.

format	value	Excel	now
#,##0.00	1234.5	1,234.50	✅ (thousand ,)
#,##0.00;-#,##0.00	-1234.5	-1,234.50	✅
#,##0.00 "zł"	1234.5	1 234.50 zł	✅ (thousand )
$#,##0.00;-$#,##0.00	-1234.5	-$1,234.50	✅
000.00	-5	-005.00	✅

Tests — handsontable/hyperformula-tests#27

All HF-287 coverage lives in the private suite; this PR adds no test files.

• unit/format/format-number-sections.spec.ts — 58 single-assertion cases: grouping against a configured thousandSeparator, sign-selected sections, config decimal separator, color-tag stripping, literal-only sections, backslash escapes, degradation, regression locks on the simple masks, engine-level TEXT, and the white-box ReDoS shape assertion.
• unit/interpreter/function-text.spec.ts — one existing assertion flips (correct-behavior change): TEXT(12.45,"$###,##0.00") was '$12,##0.00' (garbage), now '$12.45'. Without the paired update, unit-tests CI fails on the old expectation.

Local run against this head: 8 suites / 233 tests green across the new spec plus unit/format/, function-text, function-textjoin, config, update-config and smoke; tsc -p tsconfig.test.json clean; eslint 0 errors on the touched files.

A before/after sweep over 45 masks (base d860eef3e vs this head) shows changes only where the old output was garbage. Two cases worth naming: TEXT(5,"0,000") was 5,000 and is now 0005 on default config (the old output only looked grouped — it was the mask tail leaking), and [Red]dd-mm-yyyy was [Re1]01-01-1900.

Scoped OUT (per ADR — not regressions)

percent 0.00%, scaler arithmetic (degrades visibly), ? placeholders, scientific E+, @/4th text section, [condition] comparators, and placeholder chars inside quoted literals. Also: =TEXT(x,"… ""zł""") as a literal formula still returns #ERROR! — HF's formula parser rejects embedded "" (unrelated to the formatter, which does handle the quoted literal when the format arrives via config/programmatically).

---

Note

Medium Risk
Changes core TEXT formatting behavior across many masks and alters the format string passed to custom date/time callbacks; incorrect edge-case handling could affect displayed cell values but is localized to the format layer.

Overview
Fixes TEXT number masks that previously leaked unparsed format fragments (e.g. #,##0.00 showing ,##0 in the output).

The built-in number path now splits Excel-style positive/negative/zero sections (;), applies thousands grouping from #,##0 using thousandSeparator / decimalSeparator, strips [Red]-style color tags before date/time dispatch (so [Red]dd-mm-yyyy no longer mis-parses), and aligns with Excel on signed zeros (TEXT(-0.4,"0") → 0) and very large magnitudes (≥1e21 expanded via BigInt). The number tokenizer admits grouping commas with a ReDoS-safe flat regex and skips placeholder-less runs as literals.

Docs/CHANGELOG document built-in coverage limits (no %, scientific, conditions) and the note that custom stringifyDateTime / stringifyDuration callbacks receive color-stripped format strings while stringifyCurrency still gets the raw mask.

^{Reviewed by Cursor Bugbot for commit 975b72c. Bugbot is set up for automated code reviews on this repo. Configure here.}

[netlify]

✅ Deploy Preview for hyperformula-dev-docs ready!

Name	Link
🔨 Latest commit	51ed68a
🔍 Latest deploy log	https://app.netlify.com/projects/hyperformula-dev-docs/deploys/6a7610dc68d7270007fc85e6
😎 Deploy Preview	https://deploy-preview-1716--hyperformula-dev-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[qunabu]

Task linked: HF-287 TEXT/numberFormat: no thousands grouping (#,##0) or format sections (;) — complex format strings emit garbage

[marcin-kordas-hoc]

bugbot run

[github-actions]

Performance comparison of head (975b72c) vs base (114fd5d)

                                     testName |    base |    head |  change
---------------------------------------------------------------------------
                                      Sheet A |  615.16 |  585.19 |  -4.87%
                                      Sheet B |  205.55 |  209.51 |  +1.93%
                                      Sheet T |   179.1 |  190.44 |  +6.33%
                                Column ranges |  585.72 |  590.91 |  +0.89%
                                Sorted lookup | 17949.3 | 18853.8 |  +5.04%
Sheet A:  change value, add/remove row/column |    19.2 |   27.26 | +41.98%
 Sheet B: change value, add/remove row/column |  174.22 |  209.63 | +20.32%
                   Column ranges - add column |  195.58 |  220.18 | +12.58%
                Column ranges - without batch |  595.61 |  663.45 | +11.39%
                        Column ranges - batch |  145.65 |  170.43 | +17.01%

[marcin-kordas-hoc]

bugbot run

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit fa890f6. Configure here.}

[qunabu]

Task linked: HF-24 Support popular currency formats in TEXT function

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	hyperformula-docs	975b72c	Commit Preview URL Branch Preview URL	Aug 31 2026, 05:20 AM

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 975b72c. Configure here.}

[cursor]

CHANGELOG uses issue not PR link

Low Severity

The new Unreleased TEXT/numberFormat bullet ends with an issue URL for #1145 rather than a GitHub pull-request link. Unreleased changelog items need a pull/NNNN link; an issue-only reference does not count.

 

^{Triggered by learned rule: CHANGELOG bullets need a PR link}

^{Reviewed by Cursor Bugbot for commit 975b72c. Configure here.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.33%. Comparing base (114fd5d) to head (975b72c).

Additional details and impacted files

@@             Coverage Diff             @@
##           develop    #1716      +/-   ##
===========================================
+ Coverage    97.32%   97.33%   +0.01%     
===========================================
  Files          195      195              
  Lines        15739    15810      +71     
  Branches      3390     3402      +12     
===========================================
+ Hits         15318    15389      +71     
  Misses         421      421              

Files with missing lines	Coverage Δ
src/format/format.ts	99.55% <100.00%> (+0.20%)	⬆️
src/format/parser.ts	100.00% <100.00%> (ø)

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[Tobiadefami]

Looks good. Grouping respects the configured separators, and positive, negative, and zero values select the expected format sections.