Premium Analytics: port the Average items per order widget

[nerrad]

Fixes #

Proposed changes

Ports the Average items per order widget from next-woocommerce-analytics (woocommerce/woocommerce-analytics@develop) into the Premium Analytics customizable dashboard — the first real analytics widget on the dashboard introduced by #49502, and the first consumer of the internal package ports.

The widget is a thin composition over the merged internal packages (~200 lines total):

• Data: useReportOrders from @jetpack-premium-analytics/data (feat(premium-analytics): port data package from next-woocommerce-analytics #49263) against /wc/v3/woocommerce-analytics/proxy/reports/orders, with comparison range.
• Rendering: WidgetRoot + OrderMetricWidget from @jetpack-premium-analytics/widgets-toolkit (feat(premium-analytics): port widgets-toolkit package from next-woocommerce-analytics #49422) — metric value, comparison delta, and @automattic/charts sparkline all come from the toolkit.
• Range editor: the reportParams attribute's Edit control is ReportParamsField from @jetpack-premium-analytics/fields (Premium Analytics: add the fields package for widget DataForm controls #49575), externalized as a script-module dependency so the styled date-picker graph never enters the metadata module's style-less build.
• Internal package resolution: completes the link:packages/* deps on the parent manifest for the packages the widget (transitively) imports — the mechanism documented in feat(premium-analytics): resolve internal packages for build and types #49189.

Deviations from upstream (documented inline)

• The host widget contract (WidgetRenderProps) has no setError channel, so render.tsx holds the toolkit's setError state and renders an inline WidgetErrorNotice (message + retry action from the toolkit's error config). Clearing the error remounts the widget, which refetches.
• Widget id is jpa/average-items-per-order (host namespace) rather than the upstream woocommerce-analytics/average-items-per-order.

Known limitations / follow-ups

• The data and ui packages are externalized script modules since Premium Analytics: build the internal ui and data packages as script modules #49574 (shared QueryClient/report cache across widget types); the widgets-toolkit is still bundled per widget render — revisit when the toolkit dissolution lands.
• No unit tests carried over; upstream's only relevant test (align-series-dates) can be added cheaply.

Related product discussion/links

• Builds on [Do not merge] Premium Analytics: introduce the customizable widget dashboard #49502 (base branch); composes feat(premium-analytics): port data package from next-woocommerce-analytics #49263 (data), feat(premium-analytics): port widgets-toolkit package from next-woocommerce-analytics #49422 (widgets-toolkit), Premium Analytics: build the internal ui and data packages as script modules #49574 (script-module externalization), and Premium Analytics: add the fields package for widget DataForm controls #49575 (fields package), all now in trunk; resolution mechanism from feat(premium-analytics): resolve internal packages for build and types #49189

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

No.

Testing instructions

Requires pnpm ^11.5 and Node ^24.15.

• Build: pnpm --filter @automattic/jetpack-premium-analytics build — both hello-world and average-items-per-order widgets should build, and build/widgets.php registers them.
• Typecheck: pnpm --filter @automattic/jetpack-premium-analytics typecheck — only the pre-existing useSelect/preferences errors in widget-dashboard/widget-primitives remain (present on the base branch; verified with a clean install).
• On a test site (WooCommerce + the wp.org woocommerce-analytics plugin active and synced, e.g. via jetpack rsync premium-analytics <site>:...):
  1. Open the Premium Analytics admin page → Customize → Add widget → insert "Average items per order" (bar-chart icon).
  2. DevTools → Network: GET /wp-json/jetpack/v4/widget-modules lists jpa/average-items-per-order; widgets/average-items-per-order/render.min.js loads as a separate chunk on mount; two proxy/reports/orders requests fire (primary + comparison).
  3. With order data: metric value + comparison delta + sparkline render; hover shows the styled tooltip; loading overlay appears during refetch.
  4. Open the widget's settings (gear icon): the Range panel renders the full date-range editor (presets, calendar, comparison dropdown); changing the range refetches the report.
  5. Without the analytics plugin/data: the widget shows the inline "We couldn't load this data" notice and the Retry button recovers.

[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-1460-port-woo-widget-average-items-per-order branch.
• To test on Simple, run the following command on your sandbox:

bin/jetpack-downloader test jetpack add/wooa7s-1460-port-woo-widget-average-items-per-order

bin/jetpack-downloader test jetpack-mu-wpcom-plugin add/wooa7s-1460-port-woo-widget-average-items-per-order

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!

---

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.

[jp-launch-control]

Code Coverage Summary

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

Full summary · PHP report · JS report

[nerrad]

Follow-up: the reportParams range editor, and where the toolkit pieces should land

Context for reviewers on the one fidelity gap in this PR (no user-editable date range), plus proposed next steps now that widgets-toolkit (#49422) has landed and we can plan its dissolution — it was always a transitional construct for the port.

The problem

The upstream widget declares an editable range attribute with a custom dataviews Edit component:

attributes: [ { id: 'reportParams', label: 'Range', Edit: ReportParamsField } ]

Widget attributes flow into the dashboard's settings drawer, which renders them directly through DataForm with no per-widget form wiring (widget-settings.tsx#L75-L86):

const fields = useMemo< Field< WidgetAttributes >[] >(
	() => ( widgetType?.attributes ?? [] ) as Field< WidgetAttributes >[],
	[ widgetType?.attributes ]
);

…where widgetType.attributes comes straight from the widget's metadata module per the contract (widget-primitives types.ts#L108):

attributes?: Field< Item >[];

So the Edit component must ship inside the widget's metadata module (widget.ts), which useWidgetTypes() imports eagerly for every registered widget at dashboard boot.

That's where it breaks. In @wordpress/build's buildWidget(), the two builds get different plugin sets — render.* gets style handling, widget.* doesn't:

// render.min.js build:
plugins: [
	...createStyleBundlingPlugins( widgetDir ),   // CSS modules → style runtime
	wordpressExternalsPlugin( 'render.min', 'esm', [], true ),
],
// widget.min.js (metadata) build:
plugins: [
	styleRuntimeAliasPlugin(),                    // no sass/css-modules support
	wordpressExternalsPlugin( 'widget.min', 'esm', [], true ),
],

And ReportParamsField's import graph carries .module.scss (date-report-params-field.tsx#L16):

import { DateFiltersPanel } from '@jetpack-premium-analytics/ui';

→ ✘ [ERROR] No loader is configured for ".scss" files the moment widget.ts imports the field. So this PR ships no editable attributes; new instances bake the default last-30-days + comparison range via example.attributes.

Nobody else hits this: premium-analytics is the only consumer of wp-build's widget pipeline, and the ecosystem convention elsewhere avoids the pattern entirely — block.json metadata is pure JSON with edit components living in editor bundles, and wpScript packages keep styles out of the JS graph (separate build-style/ compilation). Our own hello-world widget already follows the safe form, a string-typed control with no component import (hello-world/widget.ts#L14-L20):

attributes: [
	{
		id: 'message',
		label: 'Message',
		type: 'text',
	},
],

Notably, the dashboard host already does exactly what ReportParamsField wants to do — a custom styled DataForm control — but defined in the host bundle, which builds with full style support (layout-model-edit-field/index.tsx#L60):

}: DataFormControlProps< WidgetGridSettings > ): React.ReactNode {

The pattern works; the problem is purely where the component code lives.

Proposed next steps (doubles as the toolkit dissolution plan)

1. Host-level providers; dissolve WidgetRoot. Today every widget instance mounts its own providers (widget-root.tsx#L120-L128):

<AnalyticsQueryClientProvider>
	<GlobalChartsProvider theme={ chartTheme }>
		<WidgetRootContext.Provider value={ contextValue }>

…and the QueryClient is a module-scope singleton per bundle (query-client-provider.tsx#L109), so each widget gets its own cache. Since react/react-dom are externalized to the WP-shared instance in widget bundles (from the generated render.min.asset.php: 'dependencies' => array('react', 'react-dom', …)), context crosses bundle boundaries — the dashboard route can mount the providers once around WidgetDashboard, widgets shrink to a useResolvedReportParams( attributes ) hook + chart composition, and identical report requests dedupe across widgets via the shared cache. Small PR, pays off before widget #2.

2. Declarative metadata; resolve Edit controls by name. Keep widget.ts to strings/icon (block.json philosophy); the attribute declares a control reference (e.g. edit: 'jpa/report-params') and the host registers implementations via a small registry in the widget-primitives contract — the field implementation moves to a bundle built by the route pipeline, which has style support (per the host precedent above). Kills this build issue permanently and the eager-load weight of bundling a date picker into N metadata modules. Needs contract discussion since widget-primitives is headed upstream.

3. Upstream chart compositions to @automattic/charts. ComparativeLineChart, ChartTooltip, empty-state helpers, metric value/delta. Charts' compositions directory is literally waiting (charts/src/compositions/index.ts):

// Compositions directory - prepared for future use
export {};

One decoupling needed first — these components import the analytics-local formatters directly (comparative-line-chart.tsx#L5):

import { formatDate, formatMetricValue } from '@jetpack-premium-analytics/formatters';

Make formatting injectable via props (formatValue/formatDate) so the analytics flavoring stays at the call site.

4. Regardless of the above: file the render/metadata style-plugin asymmetry upstream against @wordpress/build — the next widget-pipeline consumer will trip on it for something lighter than a date picker.

End state: data hooks stay in the data package, charts pieces live in charts, field controls live host-side, and widgets-toolkit deletes itself.

*left by Biff (AI agent) on behalf of Darren

[nerrad]

Besides the inline comments, the package-lock.json diff seems to be larger than it should be?

[nerrad]

Are there no existing widget error handling components at in either the widget toolkit or other packages? Other widgets will need something too? Also, check and see what exists for notices in the WordPress Design System.

[nerrad]

Investigate a way to hide this in the analytics dashboard but make available when the widget is inserted in non-analytics dashboards. Otherwise, if there is no straightforward implementation that can apply globally to all analytics type widgets, let's just remove this for now because report params will be defined at the global level for these widgets.