feat(premium-analytics): port formatters package from next-woocommerce-analytics

[chihsuan]

Proposed changes

Second leaf in M2 — Shared Packages Integration (WOOA7S-1311): port @wc-analytics/formatters (formerly @next-woo-analytics/formatters) into @automattic/jetpack-premium-analytics as an internal package. Provides locale-aware number / currency / percentage formatting (formatMetricValue) on top of @automattic/number-formatters, plus thin date helpers (formatDate, formatDateRange) on top of date-fns.

Chosen as another leaf because it has no internal cross-package imports — only @automattic/number-formatters (already a Jetpack workspace package) and date-fns. Stacked on #49189 (which sets up the @jetpack-premium-analytics/* tsconfig paths alias this work relies on), parallel to #49221 (datetime port — same patterns).

What's in the package

File	Purpose
src/date/format-date.ts	formatDate( date, format? ) with 11 named presets (short, medium, long, full, iso, etc.)
src/date/format-date-range.ts	formatDateRange( { from, to } ) — collapses ranges by same-day / same-month / same-year
src/metric/format-metric-value.ts	formatMetricValue( value, type, options ) — type-routed orchestrator (number / currency / percentage / average) over @automattic/number-formatters

Monorepo adaptations

Upstream	Here	Why
name: @wc-analytics/formatters	name: @automattic/jetpack-premium-analytics-formatters	Per the internal-packages convention in the parent README.md — the import specifier (@jetpack-premium-analytics/formatters) comes from wpPlugin.packageNamespace; the name: field is separate and must use the @automattic/... form
version: "1.0.0"	version: "0.1.0"	Match other internal packages (init, datetime); these aren't published so version is informational
"@automattic/number-formatters": "*"	"workspace:*"	Use the workspace-linked Jetpack package, not the npm registry
"date-fns": "^4.1.0"	"4.1.0"	Jetpack convention — every other package pins concrete versions; the repo also sets minimumReleaseAge: 1440 which conflicts with caret ranges
Leaf tsconfig.json	(deleted)	Parent already includes: [packages/**/*]; sibling packages/init/ has no leaf tsconfig either
CIAB date-format link in format-date.ts JSDoc	stripped	Internal P2 URL; the table itself is self-explanatory
Mirrors DateRange from @next-woo-analytics/datetime comment in format-date-range.ts	Updated to reference @jetpack-premium-analytics/datetime	The sibling package now lives next door via #49221
code: 'USD' unused destructured param in metric test mock	dropped	Triggered @typescript-eslint/no-unused-vars; the mock never consumed it, the code?: string field in the param type stays so call sites still type-check
Blank line between External/Internal import groups in tests	removed	Jetpack import/order rule disallows blank lines inside import groups
Auto-fix: prettier formatting	applied via pnpm exec prettier --write	Upstream had a slightly different prettier config

Two structural files added at the parent level:

• package.json: adds @automattic/number-formatters (workspace) and date-fns so the leaf's imports resolve. packages/formatters/ is not a pnpm workspace member (the root pnpm-workspace.yaml glob projects/*/* doesn't reach in two levels), so the leaf's own dep declarations are decorative — only the parent's matter to pnpm. This mirrors how packages/init/ and the datetime port in feat(premium-analytics): port datetime package from next-woocommerce-analytics #49221 declare deps. Also adds @types/jest (devDep) so the ported test files typecheck.
• eslint.config.mjs (new — temporary): softens jsdoc/require-* for packages/formatters/** so the initial port can land with the upstream JSDoc style (function-body descriptions, no per-param tags). The plan is to backfill proper JSDoc on the helpers in a follow-up and delete this config file entirely. Same pattern as feat(premium-analytics): port datetime package from next-woocommerce-analytics #49221.

What's intentionally not here

• No link: dep on the parent yet. Same reason as feat(premium-analytics): port datetime package from next-woocommerce-analytics #49221 — eslint-plugin-package-json's valid-dependencies rule rejects link: URLs by default. Since no route or sibling package imports formatters yet, the wiring isn't load-bearing — wp-build's packages/* autodiscovery is enough for the package to exist. The first consumer PR will need to resolve the lint conflict (probably by relaxing the rule for this package.json).
• No jest runtime / test runner. The tests are ported verbatim from upstream (3 files, ~50 cases) and pass tsgo --noEmit typecheck (@types/jest is wired), but the parent package has no jest.config.cjs or test script yet. They'll execute once test infrastructure is wired in a follow-up.

Related product discussion/links

• WOOA7S-1313
• Parent: WOOA7S-1311 (Shared Packages Integration audit)
• Stacked on feat(premium-analytics): resolve internal packages for build and types #49189 (WOOA7S-1320)
• Sibling: feat(premium-analytics): port datetime package from next-woocommerce-analytics #49221 (WOOA7S-1312 — datetime port, same patterns)

Does this pull request change what data or activity we track or use?

No.

Testing instructions

Requires Node 24 (repo engineStrict).

pnpm install
cd projects/packages/premium-analytics
pnpm typecheck   # tsgo --noEmit — passes
pnpm build       # wp-build — passes (~400ms)
pnpm exec eslint --flag v10_config_lookup_from_file --max-warnings=0 packages/formatters/   # clean

Optional smoke import, to confirm the path alias works through the typechecker:

1. Edit routes/dashboard/stage.tsx:

   import { formatMetricValue } from '@jetpack-premium-analytics/formatters';
   void formatMetricValue( 1234, 'currency' );

2. pnpm typecheck — resolves and passes.
3. Revert the edit.

Optional — build-time resolution via link: (confirms wp-build tracks the package as a module dependency once a consumer imports it):

1. Add to projects/packages/premium-analytics/package.json dependencies: "@jetpack-premium-analytics/formatters": "link:packages/formatters" (the valid-dependencies lint rejects link: — relax it for the temp edit).
2. Import + reference a formatters export in routes/dashboard/stage.tsx.
3. pnpm install && pnpm build → build/routes/dashboard/content.min.asset.php lists the dependency under module_dependencies.
4. Revert the edits + pnpm install.

Note: the @jetpack-premium-analytics/formatters specifier is a temporary bridge inherited from the source repo. Once name-based identity (WordPress/gutenberg#78822, mirrored monorepo-wide by #48089) lands, the specifier becomes the package's own name (@automattic/jetpack-premium-analytics-formatters) and the bare-scope alias/link: drop out — so long term there's no @jetpack-premium-analytics/... to maintain. The package README already uses the canonical @automattic/jetpack-premium-analytics-formatters name.

[github-actions]

Are you an Automattician? Please test your changes on all WordPress.com environments to help mitigate accidental explosions.

• To test on WoA, go to the Plugins menu on a WoA dev site. Click on the "Upload" button and follow the upgrade flow to be able to upload, install, and activate the Jetpack Beta plugin. Once the plugin is active, go to Jetpack > Jetpack Beta, select your plugin (Jetpack or WordPress.com Site Helper), and enable the wooa7s-1313-integrate-formatters-package-into-analytics branch.
• To test on Simple, run the following command on your sandbox:

bin/jetpack-downloader test jetpack wooa7s-1313-integrate-formatters-package-into-analytics

bin/jetpack-downloader test jetpack-mu-wpcom-plugin wooa7s-1313-integrate-formatters-package-into-analytics

Interested in more tips and information?

• In your local development environment, use the jetpack rsync command to sync your changes to a WoA dev blog.
• Read more about our development workflow here: PCYsg-eg0-p2
• Figure out when your changes will be shipped to customers here: PCYsg-eg5-p2

[github-actions]

Thank you for your PR!

When contributing to Jetpack, we have a few suggestions that can help us test and review your patch:

• ✅ Include a description of your PR changes.
  
• ✅ Add a "[Status]" label (In Progress, Needs Review, ...).
  
• ✅ Add testing instructions.
  
• ✅ Specify whether this PR includes any changes to data or privacy.
  
• ✅ Add changelog entries to affected projects
  

This comment will be updated as you work on your PR and make changes. If you think that some of those checks are not needed for your PR, please explain why you think so. Thanks for cooperation 🤖

---

Follow this PR Review Process:

1. Ensure all required checks appearing at the bottom of this PR are passing.
2. Make sure to test your changes on all platforms that it applies to. You're responsible for the quality of the code you ship.
3. You can use GitHub's Reviewers functionality to request a review.
4. When it's reviewed and merged, you will be pinged in Slack to deploy the changes to WordPress.com simple once the build is done.

If you have questions about anything, reach out in #jetpack-developers for guidance!

[jp-launch-control]

Code Coverage Summary

No summary data is available for parent commit 2beeaa9, so cannot calculate coverage changes. 😴

If that commit is a feature branch rather than a trunk commit, this is expected. Otherwise, this should be updated once coverage for 2beeaa9 is available.

Full summary · PHP report · JS report

[dognose24]

Walked through local verification (Node 24.14.0, branch tip):

• pnpm typecheck — exit 0
• pnpm build — formatters transpiled, full build clean
• pnpm exec eslint --flag v10_config_lookup_from_file --max-warnings=0 packages/formatters/ — exit 0
• Smoke import (formatMetricValue + formatDate from routes/dashboard/stage.tsx) — typecheck passes, the @jetpack-premium-analytics/* alias resolves end-to-end

One coordination note: this PR and #49221 both add projects/packages/premium-analytics/eslint.config.mjs as a new file with mutually exclusive files globs (packages/datetime/** vs packages/formatters/**). Whichever lands second will need to merge both rule sets into one config. Worth coordinating with @chihsuan on merge order.

Two small doc nits inline. Otherwise LGTM. Disclosure: downstream consumer of these formatters via WOOA7S-1329 (widget metric display in dashboard route needs exactly this).