[marcin-kordas-hoc]

Context

TEXT and the built-in number formatter understood only a plain mask of digit placeholders with an optional decimal part. Other masks leaked their tail into the result: TEXT(1234.5,"#,##0.00") returned 1235,##0.00. Thousands grouping (#,##0), sections (positive;negative;zero), and the decimalSeparator and thousandSeparator options were ignored.

This PR extends the formatter in place rather than rewriting its grammar:

• the number-format regular expression admits , inside its flat character class, with no nested quantifier, so it stays free of catastrophic backtracking;
• the formatter splits the mask into sections (aware of quotes and backslash escapes), picks the section by the sign of the value, groups digits with thousandSeparator, and writes the decimal point with decimalSeparator. A section it cannot parse is rendered as literal text. Values of 1e21 and above are converted to digits with BigInt, which is why hyperformula/tsconfig.json adds the es2020.bigint library;
• color tags such as [Red] are stripped after the stringifyCurrency callback and before date and time formatting. That fixes [Red]dd-mm-yyyy, whose d in Red was read as a day token: TEXT(1,"[Red]dd-mm-yyyy") returned [Re31]31-12-1899 and now returns 31-12-1899. As a consequence, a custom stringifyDateTime now receives the mask without color tags (dd-mm-yyyy), while stringifyCurrency still receives it unchanged ([Red]0.00).

The compatibility guide (docs/guide/compatibility-with-microsoft-excel.md) now lists what the built-in formatter handles and what still needs a callback.

How did you test your changes?

Paired tests: handsontable/hyperformula-tests#27, branch feat/hf-287-numberformat-sections.

• unit/format/format-number-sections.spec.ts: 65 tests, all green on this head. Run against develop, with its one white-box import stubbed (the exported regular-expression source does not exist there), 43 of them fail.
• unit/interpreter/function-text.spec.ts: one existing assertion changes, TEXT(12.45,"$###,##0.00") from $12,##0.00 to $12.45 on the default config.
• Both specs together: 110 tests green on this head.

Results that changed for masks that used to work: on the default config, TEXT(5,"0,000") was 5,000 and is now 0005, because the default thousandSeparator is empty and the old output was the mask tail, not grouping.

Compatibility with Excel and Google Sheets

HyperFormula results measured on this head, with thousandSeparator: ',' and functionArgSeparator: ';' unless noted. The Excel column is the expected result of each mask and was not re-measured for this revision. Google Sheets was not checked.

Formula	Excel	Google Sheets	HyperFormula
=TEXT(1234.5;"#,##0.00")	1,234.50	Not checked	1,234.50
=TEXT(-1234.5;"#,##0.00;-#,##0.00")	-1,234.50	Not checked	-1,234.50
=TEXT(-1234.5;"$#,##0.00;-$#,##0.00")	-$1,234.50	Not checked	-$1,234.50
=TEXT(1234.567;"$#,##0.00")	$1,234.57	Not checked	$1,234.57
=TEXT(-5,"000.00") (default config)	-005.00	Not checked	-005.00

The formatter still does not implement percent scaling (0.00% returns 0.50% for 0.5), scaler commas (0,,), the ? placeholder, scientific notation (0.00E+00) or [condition] comparators; the compatibility guide lists them.

Public API changes

None in signatures. Behaviour: a custom stringifyDateTime callback receives the format without color tags, as described in Context.

Out of scope and follow-ups

• The formats listed at the end of the compatibility section above. No follow-up ticket yet.

Types of changes

• Breaking change (existing functionality no longer works as before) – agreed with the maintainers
• New feature or improvement (a non-breaking change that adds functionality)
• Bug fix (a non-breaking change that fixes an issue)
• Additional language file, or a change to an existing language file (translations)
• Change to the documentation

Related issues

1. HF-287. Public issue: TEXT() function should support popular currency formats #1145, which asked for $#,##0.00 in TEXT.

Checklist

• My pull request meets the Definition of Done. External contributors: see also Contributing to HyperFormula.
• I have signed the Contributor License Agreement.
• I read my own diff end to end before requesting a review.
• I added a CHANGELOG.md entry, written by the changelog rules – or none is needed (docs, tests or tooling only).
• I updated the documentation and JSDoc to match the change.
• Breaking change only: I added a section to the migration guide.
• I updated the dev-docs/ pages this change affects – or none needed it.

---

Note

Medium Risk
Changes core TEXT/formatting behavior and what custom stringifyDateTime receives; some previously wrong outputs (e.g. masks that looked like grouping with default config) will differ intentionally.

Overview
Fixes TEXT and the shared format() number path so Excel-style masks like #,##0 and multi-section patterns (0.00;(0.00)) render correctly instead of leaking mask tail text (e.g. 1235,##0.00). The formatter now splits sections on unescaped ; (respecting quotes/escapes), picks positive/negative/zero by value sign, applies decimalSeparator / thousandSeparator from config, handles literal-only sections, signed-zero rounding, and uses BigInt for magnitudes ≥ 1e21 (es2020.bigint in tsconfig).

Color tags ([Red], etc.) are stripped after stringifyCurrency and before date/duration dispatch, so colored date masks format as dates and custom stringifyDateTime receives the mask without the color segment (documented as a behavior change). The number-format tokenizer admits grouping commas with a flat regex and only treats runs containing #/0 as number tokens.

Docs and CHANGELOG cover supported vs callback-only format features and the stringifyDateTime callback input change.

^{Reviewed by Cursor Bugbot for commit eb272ea. 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 (eb272ea) vs base (d143456)

                                     testName |    base |    head | change
--------------------------------------------------------------------------
                                      Sheet A |  414.06 |  399.53 | -3.51%
                                      Sheet B |  140.32 |   135.3 | -3.58%
                                      Sheet T |  117.82 |  114.23 | -3.05%
                                Column ranges |  433.45 |  421.15 | -2.84%
                                Sorted lookup | 12822.3 | 12328.8 | -3.85%
Sheet A:  change value, add/remove row/column |   14.81 |   14.85 | +0.27%
 Sheet B: change value, add/remove row/column |   122.3 |  132.34 | +8.21%
                   Column ranges - add column |  140.49 |  131.96 | -6.07%
                Column ranges - without batch |  428.28 |  423.17 | -1.19%
                        Column ranges - batch |  106.48 |  109.45 | +2.79%

[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	eb272ea	Commit Preview URL Branch Preview URL	Oct 25 2026, 01:50 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.}

[Tobiadefami]

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

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.29%. Comparing base (d143456) to head (eb272ea).

Additional details and impacted files

@@             Coverage Diff             @@
##           develop    #1716      +/-   ##
===========================================
+ Coverage    97.28%   97.29%   +0.01%     
===========================================
  Files          207      207              
  Lines        16218    16289      +71     
  Branches      3556     3600      +44     
===========================================
+ Hits         15777    15848      +71     
  Misses         433      433              
  Partials         8        8              

Files with missing lines	Coverage Δ
hyperformula/src/format/format.ts	99.55% <100.00%> (+0.20%)	⬆️
hyperformula/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.