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

[chihsuan]

Proposed changes

The final leaf in M2 — Shared Packages Integration: port @next-woo-analytics/widgets-toolkit into @automattic/jetpack-premium-analytics as the internal widgets-toolkit package. This is the layer the dashboard actually renders — 19 widget components (orders, bookings, visitors, conversion, coupons, devices, locations, leaderboards…), the chart wrappers they're built from (bar, donut, semi-circle, comparative line, leaderboard, legend, tooltip), the widget-settings fields (ReportParamsField, MetricsField), and the data-shaping helpers + hooks underneath. First ported package using CSS modules (*.module.scss).

Commits

Reviewed most easily commit-by-commit — the verbatim copy is isolated first, so every later diff shows exactly what the monorepo port changed.

Commit	Subject
7953f05cba	feat(premium-analytics): add widgets-toolkit package from next-woocommerce-analytics
38707ec512	refactor(premium-analytics): adapt widgets-toolkit imports and manifest for monorepo
397f668d7b	refactor(premium-analytics): decouple widgets-toolkit from unpublished ciab-admin packages
36147f2411	style(premium-analytics): align ported widgets-toolkit with jetpack prettier
284a65ccf3	chore(premium-analytics): wire widgets-toolkit deps and relax lint for the port
b42183f6c9	fix(premium-analytics): satisfy widgets-toolkit typecheck and import lint
c19f282486	fix(premium-analytics): rename CIAB design tokens to canonical wpds typography tokens
d874acb811	changelog: add entry for premium-analytics widgets-toolkit package port
09e6f079af	fix(premium-analytics): resolve stylelint errors in widgets-toolkit scss
01f7aa92e3	fix(premium-analytics): pin @wordpress/dataviews to 14.3.0 to avoid react-native peer issue
fe781e20f6	feat(premium-analytics): add storybook stories for widgets-toolkit
c21892f949	fix(premium-analytics): provide storybook contexts and mock data for widgets-toolkit stories

Monorepo adaptations

Upstream	Here	Why
name: @next-woo-analytics/widgets-toolkit	name: @automattic/jetpack-premium-analytics-widgets-toolkit	Internal-packages convention; the import specifier is @jetpack-premium-analytics/widgets-toolkit (tsconfig path alias), separate from the name: field
@next-woo-analytics/{datetime,data,routing,icons}, @wc-analytics/formatters, @next-woo-analytics/components	@jetpack-premium-analytics/{datetime,data,routing,icons,formatters,ui}	Consume the integrated packages
@automattic/charts from npm (^1.0.0)	@automattic/charts: workspace:*	The charts package is developed in this monorepo (projects/js-packages/charts, currently 1.5.0); workspace:* matches the existing @automattic/number-formatters wiring. Its ./style.css and ./visx/legend subpath exports are both used and resolve
import type { DataFormControlProps } from '@ciab/dataviews' (2 files)	@wordpress/dataviews 14.3.0	@ciab/dataviews is an unpublished fork of @wordpress/dataviews; the published package exports a compatible DataFormControlProps (Tier 1 per the integration audit guidelines). Pinned to 14.3.0 — the version the monorepo already resolves elsewhere; 15+/16 pulls @wordpress/components 35 whose @emotion/native demands an unmet react-native peer under the repo's strict peer-deps policy
import { EmptyState } from '@automattic/design-system' (1 file)	EmptyState from @wordpress/ui	design-system is unpublished; its EmptyState is derived from @wordpress/ui's — same compound API (Root/Description), and @wordpress/ui is already a parent dep
import { WidgetLoadingOverlay } from '@automattic/dashboard' (15 files)	local src/components/widget-loading-overlay/	dashboard (CIAB Admin) is unpublished. Stand-in modeled on Gutenberg's dashboard widget chrome LoadingOverlay (Stack + Spinner), with a TODO to swap back when available
import type { WidgetErrorConfig } from '@automattic/dashboard' (2 files)	local type in src/types.ts	Same package; shape mirrors the documented setError contract ({ message, action? } | true | null) that useWidgetError constructs
import { useColorPreference } from '@automattic/admin-toolkit' (1 file)	local src/hooks/use-color-preference.ts	admin-toolkit is unpublished. There's no interface-theme preference here yet, so the stand-in always reports 'default' → the standard WOO_COLORS palette; TODO to wire a real preference
import { getStoreInfo } from '@woocommerce-next/data' (2 files)	local src/helpers/store-info.ts	@woocommerce-next/data is unpublished. Only launchedDate is consumed, feeding getDefaultPreset( launchedDate? ) whose param is optional — the stand-in returns {} and behavior falls back to the default preset; TODO to source from boot/localized settings
@tanstack/react-router in dependencies	dropped	Declared upstream but imported nowhere in the source
--wpds-font-*, --wpds-color-bg-interactive-neutral tokens	--wpds-typography-*, --wpds-color-bg-interactive-neutral-weak	The published @wordpress/theme 0.13.0 renamed the typography tokens and split bg-interactive-neutral into -weak/-strong; wp-build's design-token validation hard-errors on the old CIAB names
'woocommerce-analytics' text domain	'jetpack-premium-analytics'	Matches the package's text domain
Leaf tsconfig.json	(deleted)	Parent includes: [packages/**/*] + path alias; mirrors all prior ports
* version specs	pinned to match siblings (@wordpress/components 33.1.0, compose 7.46.0, dataviews 14.3.0, route 0.12.0, theme 0.13.0, ui 0.13.0, clsx 2.1.1, date-fns 4.1.0)	Jetpack convention
Upstream prettier/import-order style	re-run through Jetpack ESLint + prettier	Aligns the port with monorepo formatting

Parent-level wiring (projects/packages/premium-analytics/):

• package.json: adds the three runtime deps not already wired by earlier ports — @automattic/charts (workspace), @wordpress/dataviews 14.3.0, @wordpress/theme 0.13.0 (only its FontSize type is used). Everything else the package imports (@wordpress/{components,compose,icons,i18n,route,ui}, clsx, date-fns, react) was already present. The leaf isn't a pnpm workspace member, so the parent's deps are the load-bearing ones; no link: dep is added yet — nothing imports widgets-toolkit (same as all prior ports).
• eslint.config.mjs (temporary): extends the ui-style override to packages/widgets-toolkit/** (JSDoc softening + react/jsx-no-bind), and additionally keeps three upstream patterns as-is: intentional any escapes in test fixtures / the router search record, __experimental* imports from @wordpress/components (ToggleGroupControl, Grid — no stable equivalents yet), and raw/dynamic DS token names required by the @automattic/charts theme contract. Tracked for follow-up alongside the other ports.

Build / CSS modules

pnpm build (wp-build) transpiles every internal package; widgets-toolkit transpiles cleanly. This is the first ported package using CSS modules — @wordpress/build 0.14.0 handles *.module.scss natively (esbuild plugin → sass → postcss-modules), emitting hashed class names (e.g. styles.overlay → _72f4bedab…__overlay) with the compiled CSS inlined as a runtime style injection, the same mechanism as plain SCSS in the ui port. Like all prior ports, the package is a library (not a build target), so it only lands in build/ once a route imports it; the per-package transpile confirms JS and styles compile.

The package's three jest suites (helpers + chart utils, 24 tests) are picked up by the parent's pnpm test and pass.

Storybook

The package now ships Storybook stories (13 component stories + 9 widget stories), discovered by the shared Jetpack Storybook (projects/js-packages/storybook) — projects/packages/premium-analytics/packages is already registered there, so no shared-config change was needed.

Because the shared Storybook config is off-limits, the provider/data wiring lives entirely inside the package, in src/stories/:

• Component stories (charts, metric value/delta, legend, tooltips, report-metric) render directly. Chart-primitive stories are wrapped in a local withChartTheme decorator that supplies the @automattic/charts GlobalChartsProvider (the same theme WidgetRoot provides in the app).
• Widget stories render the real data-fetching widgets, wrapped in the actual WidgetRoot via a local withWidgetRoot decorator — WidgetRoot provides the report-params context, GlobalChartsProvider, and the react-query client.
• Mock data: upstream uses MSW; since we can't touch the shared Storybook config, the mock generators are ported to src/stories/mocks/ and served through a local @wordpress/api-fetch middleware (register-report-mocks.ts, registered idempotently when withWidgetRoot loads). It intercepts only the analytics report endpoints (/wc/v3/woocommerce-analytics/proxy/reports/*) and returns generated data, so every widget story renders real charts instead of empty/loading chrome.

Verified in Storybook: all 22 stories render (the geo map's external gstatic.com CSS is CORS-blocked in Storybook, but the chart + data still render).

What's intentionally not here

• No @automattic/dashboard / @automattic/design-system / @automattic/admin-toolkit / @ciab/dataviews / @woocommerce-next/data — all five are unpublished CIAB Admin / next-admin internals. Replaced by two Tier-1 swaps (@wordpress/dataviews, @wordpress/ui EmptyState) and four small documented local stand-ins (overlay component, error-config type, color-preference hook, store-info getter), each with a TODO for when the real packages become available.
• No @tanstack/react-router — declared upstream, imported nowhere.
• No link: dependency on the parent — deferred to the first consumer (mirrors all prior ports).
• No JSDoc backfill / cleanup of upstream patterns — out of scope; tracked by the temporary eslint.config.mjs comments.

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

No.

Testing instructions

Requires Node 24 (repo engineStrict).

pnpm install
pnpm --filter @automattic/charts build   # workspace dep used via its dist exports
cd projects/packages/premium-analytics
pnpm typecheck   # tsgo --noEmit — 0 errors
pnpm build       # wp-build — passes; widgets-toolkit transpiles + CSS modules compile
pnpm test        # 131 tests incl. the 3 widgets-toolkit suites
pnpm exec eslint --max-warnings=0 packages/widgets-toolkit/   # clean (eslint 10 — the v10_config_lookup_from_file flag is now default behavior)

To browse the stories:

cd projects/js-packages/storybook
pnpm run storybook:dev   # http://localhost:50240 — see "Packages/Premium Analytics/Widgets Toolkit"

Screen.Recording.2026-06-10.at.9.48.04.PM.mov

Related to WOOA7S-1319.

[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-1319-integrate-widgets-toolkit-package-into-analytics branch.
• To test on Simple, run the following command on your sandbox:

bin/jetpack-downloader test jetpack wooa7s-1319-integrate-widgets-toolkit-package-into-analytics

bin/jetpack-downloader test jetpack-mu-wpcom-plugin wooa7s-1319-integrate-widgets-toolkit-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

This PR did not change code coverage!

That could be good or bad, depending on the situation. Everything covered before, and still is? Great! Nothing was covered before? Not so great. 🤷

Full summary · PHP report · JS report