Premium Analytics: update widget packages and promote in-body controls to widget attributes

[retrofox]

Closes WOOA7S-1667

What

Updates Premium Analytics to the current @wordpress/widget-primitives / @wordpress/widget-dashboard / @wordpress/build development snapshots and migrates the widgets to the attribute model those versions introduce:

• In-body selectors are replaced with high-relevance widget attributes rendered by the widget host

  • locations view mode (geoGranularity)
  • top platforms mode (platformDimension)
  • UTM Insights param (utmDimension)
  • Emails metric (metric)
  • and the Group by selectors in the Subscribers and Traffic charts (granularity).

• Commerce widgets declare presentation: framed in widget.json.

• Widget attribute shapes are typed and exported once from widget.ts
  Render components compose host fields (ReportParamsFieldAttributes) instead of re-declaring them, and the widget-audit rule covers the new conventions.

• Package pins
  widget-primitives / widget-dashboard 0.3.1-next.v.202607070741.0 and build 0.19.1-next.v.202607070741.0 in the package root; unit manifests (routes and widgets) keep declaring the 0.2.0 stable floor.

• Bundled deps needed by the new stack
  Scoped to this package: admin-ui 2.5.0, dataviews 17.1.0, icons ^15, theme / ui 0.17.0, plus the design-token migration to the renamed @wordpress/theme 0.17 groups (fg → foreground, bg → background). PA's tokens are ahead of the repo-wide token list, so a scoped override in the shared stylelint base config exempts projects/packages/premium-analytics/** from the plugin-wpds/no-unknown-ds-tokens rule; tools/js-tools keeps its @wordpress/theme on the repo's stable 0.15.1, so every other project lints unchanged.

• Carries the @wordpress/dataviews/wp pnpmfile rework from the renovate group branch, which dataviews 17 requires.

Why

The widget features this migration relies on (high-relevance attributes with DataViews-compatible types, framed presentation, render-attribute composition) exist today only in Gutenberg trunk.

They are published as development snapshots (-next.v.<timestamp>), so the team can build on them now instead of waiting for the next stable release cycle.

The versioning strategy is deliberate:

• Now:
  Pin the published snapshots, exact versions, scoped to premium-analytics only.
  Installs are reproducible from npm for every developer and CI.

• While on snapshots
  Newer trunk features are adopted by publishing a fresh development release and bumping the three pins together (same timestamp, so their transitive -next dependencies resolve to a single tree).

• Exit: automatic.
  Once stable releases ship with these changes (widget-* ≥ 0.3.1, build ≥ 0.19.1), the Bundled @wordpress/* monorepo renovate group proposes them, since a stable release always supersedes a prerelease pin.
  Renovate never downgrades the pins to older stables and never moves other projects onto the snapshots.

Other consumers of @wordpress/build (backup, forms, jetpack-mu-wpcom, newsletter, podcast, publicize, scan, seo, videopress, wp-build-polyfills) are unaffected: each project pins its own version and keeps building with it.

How

• Every in-body SelectControl replaced by an attribute is declared in widget.ts with relevance: 'high' and a DataViews-compatible text type, so the host renders the control and persists the value.

• render.tsx components default attributes and pass them through <WidgetRoot>, composing the widget's own attribute type with Partial<ReportParamsFieldAttributes>.

• The dependency bumps mirror the pending Bundled @wordpress/* monorepo renovate group, applied only within premium-analytics so this package can move ahead of the repo-wide update.

• Mid-branch commits temporarily linked a local Gutenberg checkout; the final commit replaces those links with the published snapshots and regenerates the lockfile, so the diff only ever ships registry versions.

Testing

1. Install dependencies — the lockfile applies cleanly (CI validates it with a frozen install):

nvm use
pnpm install

2. Build the package and its monorepo dependencies:

jetpack build --deps packages/premium-analytics

3. Open the Premium Analytics dashboard in wp-admin and confirm it loads without console or PHP errors.

4. Locations, Top platforms, UTM Insights, Emails, Subscribers chart, and Traffic chart: the old in-body selectors are gone; the equivalent controls now appear as widget attributes on the widget host, and switching them updates the widget data.

Screen.Recording.2026-07-07.at.10.50.00.AM.mov

5. Date range and comparison state still reach the widgets (Subscribers list reflects the picker).

6. Storybook — the widget stories render with the dashboard controls:

cd projects/js-packages/storybook

pnpm run storybook

Verifying that each project keeps its own package versions

The snapshot pins are scoped to premium-analytics; every other consumer of @wordpress/build keeps building with its own pinned version. Three checks, from declared to executed.

Declared — what each project pins in git:

git grep -n '"@wordpress/build"' -- '*package.json'

projects/packages/backup/package.json:72:		"@wordpress/build": "0.16.1",
projects/packages/forms/package.json:116:		"@wordpress/build": "0.16.1",
projects/packages/premium-analytics/package.json:94:		"@wordpress/build": "0.19.1-next.v.202607070741.0",
projects/packages/videopress/package.json:94:		"@wordpress/build": "0.16.1",
…

Installed — the copy pnpm materialized in each project's node_modules:

node -p "require('./projects/packages/forms/node_modules/@wordpress/build/package.json').version"

node -p "require('./projects/packages/premium-analytics/node_modules/@wordpress/build/package.json').version"

node -p "require('./projects/packages/premium-analytics/node_modules/@wordpress/widget-primitives/package.json').version"

0.16.1
0.19.1-next.v.202607070741.0+a51d59513
0.3.1-next.v.202607070741.0+a51d59513

The +a51d59513 build metadata identifies the Gutenberg trunk commit the snapshots were published from — the three pinned packages come from the same commit.

Executed — pnpm exec resolves the binary from the current project's node_modules, so each build runs its own pinned copy:

cd projects/packages/forms && pnpm exec wp-build
cd projects/packages/premium-analytics && pnpm exec wp-build

🎉 All packages built successfully! (1492ms total)
🎉 All packages built successfully! (4921ms total)

The lockfile is validated with a frozen install in CI, so these resolutions cannot drift silently.

Follow-ups

• Return widget-primitives / widget-dashboard / build to stable pins via the Bundled @wordpress/* monorepo renovate PR once stables ship with these changes.
• Remove the scoped no-unknown-ds-tokens exemption for premium-analytics (and bump tools/js-tools back to @wordpress/theme 0.17) once the repo-wide token renames land, so PA's tokens are validated again.
• The repo-wide 0.17 stack update (with the Forms/VideoPress compat fixes and the WPDS token renames for other projects) lands separately in Update Bundled @wordpress/* monorepo #49272; if repo-wide stylelint flags legacy token names in projects this PR doesn't touch, they are covered there.

[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 update/premium-analytics-widget-packages branch.
• To test on Simple, run the following command on your sandbox:

bin/jetpack-downloader test jetpack update/premium-analytics-widget-packages

bin/jetpack-downloader test jetpack-mu-wpcom-plugin update/premium-analytics-widget-packages

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 🤖

---

🔴 Action required: Please include detailed testing steps, explaining how to test your change, like so:

## Testing instructions:

* Go to '..'
*

---

🔴 Action required: We would recommend that you add a section to the PR description to specify whether this PR includes any changes to data or privacy, like so:

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

My PR adds *x* and *y*.

---

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

[chihsuan]

Tested well and looks good to me.

Approving. I'm going to go ahead and merge this so we can keep moving on the other tasks. Thanks @retrofox! 🚀

[retrofox]

Approving. I'm going to go ahead and merge this

Thanks, Chi