i18n: Abstract number-formatters in i18n-calypso. Add caching and numberFormatCompact abstraction.

[chriskmnds]

Closes https://github.com/Automattic/i18n-issues/issues/941
Closes https://github.com/Automattic/i18n-issues/issues/926
Related to #99110

Proposed Changes

A couple of refactors and additions to i18n-calypso's numberFormat

Abstractions

• Adds a numberFormatCompact abstraction that makes it easier to quickly format "compact" numbers - quite common in stats/etc. Addresses https://github.com/Automattic/i18n-issues/issues/941
  • This will require a follow-up to update existing cases
• Migrates the main handlers into a separate folder (number-formatters), which can be extracted later to a package. For the moment, these are exported (internally) as: __DO_NOT_IMPORT__numberFormat and __DO_NOT_IMPORT__numberFormatCompact to prevent anyone from importing and using these directly while we complete other refactors.
• Keeps separate wrappers over these handlers on the I18N prototype: the motivation being to make use of i18n-calypso's locale state and to avoid having to make updates to all the calls in the repo if the signature changes (it does)

I've written the core handlers' signatures to accept a single object parameter:

export interface NumberFormatParams {
	/**
	 * Number to format.
	 */
	number: number | bigint;
	/**
	 * Browser-safe locale string that works with Intl.NumberFormat e.g. 'en-US' (not 'en_US').
	 */
	browserSafeLocale: string;
	/**
	 * Number of decimal places to use.
	 * This is just convenience over setting `minimumFractionDigits`, `maximumFractionDigits` to the same value.
	 * ( default = 0 )
	 */
	decimals?: number;
	/**
	 * Whether to use latin numbers by default ( default = true ).
	 */
	forceLatin?: boolean;
	/**
	 * `Intl.NumberFormat` options to pass through.
	 * `minimumFractionDigits` & `maximumFractionDigits` will override `decimals` if set.
	 */
	numberFormatOptions?: Intl.NumberFormatOptions;
}

export type NumberFormat = ( params: NumberFormatParams ) => string;

The prototype methods haven't changed, so i18n-calypso consumers will still do numberFormat( 123 ) or numberFormatCompact( 123 ) for the most part. I find it easier to work on a single-parameter signature, especially if we'll be introducing additional optional parameters next. However, I see the value in doing numberFormat( number ) for the default cases VS numberFormat( { number } ). Aso, not sure what would constitute "options" (all non-required parameters are basically options, so not sure if that's a standard we should follow everywhere or not).

Performance Optimization

We introduce caching of the Intl.NumberFormat instance via a getFormatter separate function. The approach was tested and benchmarked in a separate PR and incorporated: #99110

Why are these changes being made?

Address https://github.com/Automattic/i18n-issues/issues/941
Address https://github.com/Automattic/i18n-issues/issues/926

TODO

• Tests
• Readme updates

Testing Instructions

We will handle migration of "compact" notation in a follow-up. Let's confirm a few numberFormat calls for this change:

• Switch locale to EL/DE
• Go to /stats/insights/:site and confirm numbers render correctly (use FG/a8ckudos sites)

• Go to /stats/day/:site and confirm numbers render correctly - also in popovers (use FG/a8ckudos sites)

Pre-merge Checklist

• Has the general commit checklist been followed? (PCYsg-hS-p2)
• Have you written new tests for your changes?
• Have you tested the feature in Simple (P9HQHe-k8-p2), Atomic (P9HQHe-jW-p2), and self-hosted Jetpack sites (PCYsg-g6b-p2)?
• Have you checked for TypeScript, React or other console errors?
• Have you used memoizing on expensive computations? More info in Memoizing with create-selector and Using memoizing selectors and Our Approach to Data
• Have we added the "[Status] String Freeze" label as soon as any new strings were ready for translation (p4TIVU-5Jq-p2)?
  • For UI changes, have we tested the change in various languages (for example, ES, PT, FR, or DE)? The length of text and words vary significantly between languages.
• For changes affecting Jetpack: Have we added the "[Status] Needs Privacy Updates" label if this pull request changes what data or activity we track or use (p4TIVU-aUh-p2)?

[github-actions]

Calypso Live (direct link)

https://calypso.live?image=registry.a8c.com/calypso/app:build-133146

Jetpack Cloud live (direct link)

https://calypso.live?image=registry.a8c.com/calypso/app:build-133146&env=jetpack

Automattic for Agencies live (direct link)

https://calypso.live?image=registry.a8c.com/calypso/app:build-133146&env=a8c-for-agencies

[matticbot]

Here is how your PR affects size of JS and CSS bundles shipped to the user's browser:

App Entrypoints (~143 bytes added 📈 [gzipped])

name                   parsed_size           gzip_size
entry-subscriptions         +723 B  (+0.0%)     +143 B  (+0.0%)
entry-stepper               +723 B  (+0.1%)     +143 B  (+0.0%)
entry-main                  +723 B  (+0.0%)     +143 B  (+0.0%)
entry-login                 +723 B  (+0.0%)     +143 B  (+0.0%)
entry-domains-landing       +723 B  (+0.1%)     +143 B  (+0.1%)

Common code that is always downloaded and parsed every time the app is loaded, no matter which route is used.

Legend

What is parsed and gzip size?

Parsed Size: Uncompressed size of the JS and CSS files. This much code needs to be parsed and stored in memory.
Gzip Size: Compressed size of the JS and CSS files. This much data needs to be downloaded over network.

Generated by performance advisor bot at iscalypsofastyet.com.

[matticbot]

This PR modifies the release build for the following Calypso Apps:

For info about this notification, see here: PCYsg-OT6-p2

• blaze-dashboard
• command-palette-wp-admin
• happy-blocks
• help-center
• notifications
• odyssey-stats
• whats-new
• wpcom-block-editor

To test WordPress.com changes, run install-plugin.sh $pluginSlug update/i18n-number-formatters-extracted on your sandbox.

[chriskmnds]

Also brought the caching from #99110 here. So this should have all the current explorations, main functions in a separate folder, bindings as before, and ready for a package extraction. It will close both https://github.com/Automattic/i18n-issues/issues/941 and https://github.com/Automattic/i18n-issues/issues/926

[chriskmnds]

I will go ahead and deploy this. Happy to address any feedback in a follow-up.