HF-24: add stringifyCurrency config callback for TEXT

[marcin-kordas-hoc]

Summary

Adds a stringifyCurrency config option mirroring the existing stringifyDateTime / stringifyDuration callbacks. When set, the TEXT function consults the callback before falling through to the built-in number formatter, so users can plug in locale-aware currency formatting (for example via Intl.NumberFormat or a third-party library) without bringing currency data into the HyperFormula core.

The default implementation returns undefined so existing TEXT behavior is preserved bit-for-bit.

Note on PR routing: this PR replaces #1661 which was opened from a fork branch (marcin-kordas-hoc). Fork-side PRs cannot access the DEPLOY_TOKEN secret needed to clone the private hyperformula-tests repo, so 3 of the matrix checks (Test performance, unit-tests, browser-tests) failed structurally there. Same content, same SHA (0246ce0bcbbed09ac9bf5e24af38b0d8aa1ac099), now from upstream branch — CI will have full access. Closing #1661 in favor of this one.

Linked

• Spec: agents/hyperformula/docs/specs/2026-04-21-hf-24-currency-in-text.md
• Tech rationale: agents/hyperformula/docs/specs/2026-04-24-hf-24-tech-rationale.md
• Implementation plan: agents/hyperformula/docs/specs/2026-04-27-hf-24-stringify-currency-plan.md
• Supersedes: HF-24: add stringifyCurrency config callback for TEXT #1661

Tests

Tests added in the matching feature/hf-24-stringify-currency branch of handsontable/hyperformula-tests. Coverage:

• default callback returns undefined
• custom callback intercepts currency formats
• callback opts out (returns undefined) → fall-through to numberFormat
• date / duration formats are not intercepted by stringifyCurrency
• six representative Excel format strings handled by the docs Intl.NumberFormat adapter (USD, EUR via LCID, JPY via LCID, PLN via LCID, accounting two-section, fall-through)

Notes

• PLN format string change: the spec example originally used #,##0.00 "zł" (trailing quoted symbol). HF's formula parser does not accept embedded quotes inside TEXT format strings, so the docs example and the corresponding test were swapped to use [$zł-415] #,##0.00 (LCID-tagged symbol). The adapter still recognizes the trailing-quote pattern for users invoking the callback outside HyperFormula.
• EUR / JPY assertion shapes reflect ICU output, not the original plan: tests assert '1.234,50 €' (symbol-trailing) for [$€-2] and '￥1,235' (full-width yen sign, no space) for [$¥-411] because that is what Intl.NumberFormat('de-DE'/'ja-JP', ...) actually produces on modern Node ICU. NBSP normalization in tests covers both \u00A0 and \u202F variants for ICU build robustness.
• No-LCID [$SYMBOL] boundary: the example regex requires the -LCID segment. A bare [$USD] pattern is not handled by the adapter and falls through to the built-in numberFormat, whose handling of [$...] in HyperFormula is implementation-defined. Test docs adapter does not handle [$SYMBOL] without LCID segment documents the boundary.

Test plan

• CI green on handsontable/hyperformula PR
• CI green on handsontable/hyperformula-tests PR (matching branch)
• Manual: build docs locally, render the new "Currency integration" section under Date and time handling, copy-paste the adapter into a fresh sandbox to confirm it runs against Intl.NumberFormat on Node 14+

---

Private tests PR: handsontable/hyperformula-tests#10

---

Note

Low Risk
Small, additive change to the TEXT formatting pipeline; default behavior is preserved by a no-op callback, with risk mainly around custom callback integration.

Overview
Adds a new stringifyCurrency configuration callback that lets TEXT() delegate currency-like formatting to user code before falling back to HyperFormula’s built-in number formatter.

Wires the callback through ConfigParams/Config defaults (with a no-op defaultStringifyCurrency that returns undefined) and updates docs/changelog with guidance and an Intl.NumberFormat adapter example for locale-aware currency output.

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

[qunabu]

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

[netlify]

✅ Deploy Preview for hyperformula-docs ready!

Name	Link
🔨 Latest commit	02134b5
🔍 Latest deploy log	https://app.netlify.com/projects/hyperformula-docs/deploys/69f1dba3c17c8800083263df
😎 Deploy Preview	https://deploy-preview-1665--hyperformula-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.

[github-actions]

Performance comparison of head (02134b5) vs base (8b525cb)

                                     testName |   base |   head | change
------------------------------------------------------------------------
                                      Sheet A |  490.6 | 482.63 | -1.62%
                                      Sheet B | 154.82 | 151.62 | -2.07%
                                      Sheet T | 137.43 | 136.42 | -0.73%
                                Column ranges | 466.07 | 468.11 | +0.44%
Sheet A:  change value, add/remove row/column |  15.19 |  14.56 | -4.15%
 Sheet B: change value, add/remove row/column | 127.84 | 125.52 | -1.81%
                   Column ranges - add column | 146.59 |  151.7 | +3.49%
                Column ranges - without batch |  426.5 | 452.27 | +6.04%
                        Column ranges - batch | 111.03 | 112.12 | +0.98%

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.19%. Comparing base (8b525cb) to head (02134b5).

Additional details and impacted files

@@           Coverage Diff            @@
##           develop    #1665   +/-   ##
========================================
  Coverage    97.18%   97.19%           
========================================
  Files          174      174           
  Lines        15086    15092    +6     
  Branches      3223     3224    +1     
========================================
+ Hits         14662    14668    +6     
  Misses         424      424           

Files with missing lines	Coverage Δ
src/Config.ts	94.11% <100.00%> (+0.05%)	⬆️
src/format/format.ts	99.32% <100.00%> (+0.02%)	⬆️

🚀 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.