Premium Analytics: add Traffic chart stats widget

[kangzj]

Fixes WOOA7S-1504

Proposed changes

Premium Analytics users get a Traffic widget for their customizable dashboard: a line chart of the site's Views and Visitors over the last 30 days — the Jetpack Stats traffic card brought into the new dashboard.

This is the second real dashboard widget (after Average items per order, #49505) and the second Stats card port. It follows the self-contained widget pattern: widget-local copies of the chart toolkit pieces that are deletable once the shared widgets-toolkit (#49422) lands.

• widgets/traffic-chart/ — new jpa/traffic-chart widget (stats category). A providers-only WidgetRoot (query client + chart theme) wraps TrafficChartWidget, which fetches visits and renders Views + Visitors as two line series via a ComparativeLineChart (adapted from Premium Analytics: port the Average items per order widget #49505). Loading/refetch overlay and an inline error notice with Retry. Period/quantity are hardcoded for v1 via attribute defaults (unit: day, quantity: 30); a shared date-range context can drive them later.
• Data package (packages/data):
  • useReportStatsVisits — uses useQuery directly (stats has no comparison concept in v1) and returns the sanitized time series.
  • fetchReportStatsVisits against the existing jetpack/v4/stats-app/sites/{site_id}/stats/visits proxy from the jetpack-stats-admin package — no new REST proxy, no new composer dependency.
  • A normalizer that zips the WPCOM fields+data arrays into typed period rows. It parses all of views/visitors/likes/comments even though v1 charts only the first two, so adding the Calypso tabs later is a frontend-only change.
  • getJpaConfig() reading window.jpaConfig, plus getStatsApiPath() building the proxy base path from the runtime site ID.
• Config_Data PHP class — emits window.jpaConfig = { siteId, apiRoot, nonce } ahead of the boot script (a small take on stats-admin's Odyssey_Config_Data), wired through the *_boot_dependencies filters.

Deviations from upstream (documented inline)

• Errors render inline (WidgetErrorNotice with Retry) — the host WidgetRenderProps contract has no setError channel.
• WidgetRoot is providers-only: Stats widgets are driven by stats period/quantity attributes, not WooCommerce-Analytics report params, so there's no report-params context.
• Chart-only v1: no metric readout, no Views/Visitors/Likes/Comments tabs, no bar↔line toggle, no heartbeat polling.

Notes for reviewers

• Builds on [Do not merge] Premium Analytics: introduce the customizable widget dashboard #49502 (base branch). Overlaps with the in-flight Top posts stats widget (Premium Analytics: add Top posts & pages stats widget #49508), which introduces the same jpaConfig/Config_Data stats infra on the widgets-toolkit branch; whichever merges second reconciles the duplication. This PR is self-contained on the dashboard base so it doesn't depend on the toolkit stack.
• Assumes Jetpack is installed alongside Premium Analytics (the stats proxy 404s otherwise) — accepted v1 constraint.

Related product discussion/links

• Linear: WOOA7S-1504 (parent: WOOA7S-1458, port Jetpack Stats cards and widgets)
• Source: stats-chart-tabs/index.jsx
• Adjacent: [Do not merge] Premium Analytics: introduce the customizable widget dashboard #49502 (dashboard), Premium Analytics: port the Average items per order widget #49505 (avg items per order), Premium Analytics: add Top posts & pages stats widget #49508 (Top posts), feat(premium-analytics): port widgets-toolkit package from next-woocommerce-analytics #49422 (widgets-toolkit)

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

No. It reads existing Jetpack Stats visit data through the existing jetpack-stats-admin REST proxy.

Testing instructions

Automated:

• cd projects/packages/premium-analytics && pnpm test — fetcher URL-composition, normalizer, and series-builder tests (113 total).
• pnpm typecheck — only the pre-existing widget-dashboard/widget-primitives errors remain (present on the base branch).
• pnpm build — the traffic-chart widget builds and build/widgets/registry.php registers jpa/traffic-chart.

Manual (on a site with both Jetpack — connected, with stats — and Premium Analytics active):

• Open the Premium Analytics admin page → view source and confirm window.jpaConfig = { siteId, apiRoot, nonce } appears before the boot module import.
• In DevTools → Network, fetch the proxy path (<apiRoot>jetpack/v4/stats-app/sites/<siteId>/stats/visits?unit=day&quantity=30&stat_fields=views,visitors with the X-WP-Nonce header) and confirm it returns a fields/data payload.
• With the widget dashboard rendering branch merged in: Customize → Add widget → insert Traffic, and confirm the chart shows Views and Visitors over the last 30 days, the tooltip lists both, and a site with no traffic shows an empty chart.

[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!

---

Premium Analytics plugin:

No scheduled milestone found for this plugin.

If you have any questions about the release process, please ask in the #jetpack-releases channel on Slack.

[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 add/wooa7s-1504-port-stats-traffic-chart branch.
• To test on Simple, run the following command on your sandbox:

bin/jetpack-downloader test jetpack add/wooa7s-1504-port-stats-traffic-chart

bin/jetpack-downloader test jetpack-mu-wpcom-plugin add/wooa7s-1504-port-stats-traffic-chart

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

[jp-launch-control]

Code Coverage Summary

No summary data is available for parent commit cd69ce2, 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 cd69ce2 is available.

Full summary · PHP report · JS report

[kangzj]

🤖 Review-cycle summary — 799ce1692c → 8f78fc0c4b

3 round(s); claude[bot] LGTM; all required checks passing; 1 review addressed. The only red checks are inherited from the base branch (#49502) and unrelated to this change.

What changed during the cycle

Commits added:

• 8f78fc0c4b — Fix CI: restore pnpm-lock.yaml to a minimal diff
• 43e42d8f54 — Address review: log error in effect, document comparison-series + config semantics

Diff summary: 4 files changed, 3366 insertions(+), 176 deletions(-)

Review threads addressed:

Source	Comment	Resolution
claude[bot]	console.error in render	Moved into a useEffect keyed on [ isError, error ] (43e42d8f)
claude[bot]	Visitors treated as comparison series	Documented that the toolkit's index-based comparison semantics are inert for two identical-date primary series (43e42d8f)
claude[bot]	apiRoot/nonce dead config	Documented they're reserved (client uses wp-api-fetch's root+nonce); kept identical to #49508 for clean reconciliation (43e42d8f)

claude[bot] re-reviewed 43e42d8f and confirmed all three resolved (LGTM). Acknowledged-no-change nits (double Number() coercion, deliberate chart-toolkit carry-over, widget.json/widget.ts string split, day-only weekly normalization) were accepted as reasonable.

CI fix: 8f78fc0c — an earlier pnpm install (run before the workspace store was warmed) had pruned ~3,300 unrelated lines from pnpm-lock.yaml, breaking the monorepo install and cascading failures across CI. Reset to the base lock and re-resolved so the only lock change is the premium-analytics importer (charts + the three internal link: packages). CI went from ~30 failures to the 3 inherited ones below.

Unaddressed (flagged for owner): None.

CI: No required checks are failing. The remaining red checks are inherited from the base branch #49502 (which fails the identical set) and not introduced here:

• Type checking — pre-existing errors in the vendored widget-primitives/widget-dashboard packages; zero in this PR's files.
• Project structure — noEmit / missing changelog/.gitkeep on the vendored js-packages/grid|widget-dashboard|widget-primitives; this PR's packages/+plugins/premium-analytics check clean.
• Static analysis — phan flags src/widget-modules.php (a base-branch file, untouched here) calling the build-generated jpa_get_registered_widget_modules(); this PR's new PHP produced no phan errors.
• Code coverage requirement — expected: coverage can't compute against a feature-branch base (no trunk baseline), per jp-launch-control.

Open (non-blocking, on the manual-test checklist): full-page-app happy-path auth (does apiFetch get a valid wp_rest nonce on the wp-build app?) — gated on the widget-dashboard rendering branch + a connected site.

[kangzj]

Screenshot — Traffic chart widget

The jpa/traffic-chart widget rendering on the Premium Analytics dashboard (local docker, atlas env), showing Views and Visitors over the last 30 days as a line chart with the bottom legend:

Data note: the atlas dev env is in Jetpack Offline Mode and can't reach the real Stats proxy, so the /jetpack/v4/stats-app/.../stats/visits response was stubbed with representative 30-day data (via a temporary mu-plugin, since removed) purely to exercise the real widget → useReportStatsVisits → buildVisitsSeries → ComparativeLineChart path. Shape/styling are real; the numbers are illustrative. Live data verification against a connected site remains the tracked manual-test item.