Automattic · adamwoodnz · Jun 24, 2026 · Jun 10, 2026 · Jun 12, 2026 · Jun 13, 2026
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
diff --git a/projects/js-packages/storybook/changelog/add-average-items-order-widget-story b/projects/js-packages/storybook/changelog/add-average-items-order-widget-story
@@ -0,0 +1,4 @@
+Significance: patch
+Type: added
+
+Add a Premium Analytics Average items per order widget story.
@@ -0,0 +1,4 @@
+Significance: patch
+Type: added
+
+Port the Average items per order dashboard widget from next-woocommerce-analytics, composed from the widgets-toolkit and data packages.
@@ -105,5 +105,22 @@ export default defineConfig(
 			'@wordpress/no-unsafe-wp-apis': 'off',
 			'@wordpress/no-unknown-ds-tokens': 'off',
 		},
+	},
+	{
+		// Ported widget code keeps the upstream next-woocommerce-analytics
+		// JSDoc style, and imports internal `@jetpack-premium-analytics/*`
+		// link: packages whose deps are declared on the parent manifest.
+		files: [ 'widgets/**' ],
+		rules: {
+			'import/order': 'off',
+			'jsdoc/require-description': 'off',
+			'jsdoc/require-param-description': 'off',
+			'jsdoc/require-returns': 'off',
+			'jsdoc/check-indentation': 'off',
+			'jsdoc/require-param': 'off',
+			'jsdoc/require-jsdoc': 'off',
+			'jsdoc/escape-inline-tags': 'off',
+			'import/no-extraneous-dependencies': 'off',
+		},
 	}
 );
@@ -45,9 +45,11 @@
 		"@jetpack-premium-analytics/datetime": "link:packages/datetime",
 		"@jetpack-premium-analytics/fields": "link:packages/fields",
 		"@jetpack-premium-analytics/formatters": "link:packages/formatters",
+		"@jetpack-premium-analytics/icons": "link:packages/icons",
 		"@jetpack-premium-analytics/routing": "link:packages/routing",
 		"@jetpack-premium-analytics/site-sync": "link:packages/site-sync",
 		"@jetpack-premium-analytics/ui": "link:packages/ui",
+		"@jetpack-premium-analytics/widgets-toolkit": "link:packages/widgets-toolkit",
 		"@tanstack/react-query": "5.90.8",
 		"@wordpress/admin-ui": "2.3.1",
 		"@wordpress/api-fetch": "7.48.1",

@@ -1,23 +1,46 @@
 .chart {
 	height: 100%;
+	min-height: 0;
+	flex: 1 1 auto;
+	display: flex;
+	flex-direction: column;
+
+	> div {
+		flex: 1 1 auto;
+		min-height: 0;
+	}
+
+	.chartContent {
+		height: 100%;
+		min-height: 0;
+	}
 
 	.legend {
 		flex: 0 0 auto;
-		height: var(--wpds-typography-line-height-lg);
+		width: 100%;
+		height: auto;
 		min-height: var(--wpds-typography-line-height-lg);
-		flex-wrap: nowrap;
+		align-content: center;
+		align-items: center;
+		justify-content: center;
+		flex-wrap: wrap;
+		row-gap: var(--wpds-dimension-gap-xs) !important;
 	}
 
 	.legendItem {
 		min-width: 0;
+		max-width: 100%;
+		flex: 0 1 auto;
 		gap: var(--wpds-dimension-gap-sm);
+		justify-content: flex-start;
 		padding: var(--wpds-dimension-padding-xs) var(--wpds-dimension-padding-sm); // 4px 6px->8px
 	}
 
 	.legendLabel {
 		// font-size and color come from chartTheme.legendLabelStyles
 		min-width: 0;
-		flex: 1 1 0 !important; // Override the 0 0 auto default value
+		flex: 0 1 auto !important; // Override the 0 0 auto default value
+		text-align: start;
 
 		span {
 			display: block;

@@ -317,35 +317,37 @@ export function ComparativeLineChart( {
 	] );
 
 	return (
-		<LineChart
-			className={ clsx( styles.chart, className ) }
-			data={ styledSeries }
-			options={ chartOptions }
-			margin={ percentageMargin ?? emptyChartProps.margin ?? DEFAULT_MARGIN }
-			maxWidth={ maxWidth }
-			resizeDebounceTime={ RESIZE_DEBOUNCE_MS }
-			withLegendGlyph={ false }
-			showLegend={ false }
-			curveType="monotone"
-			withGradientFill
-			withTooltips={ !! renderTooltip && ! isEmptyData }
-			renderTooltip={ renderTooltip }
-		>
-			<LineChart.Legend
-				shape="line"
-				className={ styles.legend }
-				itemClassName={ styles.legendItem }
-				itemStyles={ {
-					margin: 0,
-				} }
-				labelClassName={ styles.legendLabel }
-				labelStyles={ {
-					maxWidth: '100%',
-					textOverflow: 'ellipsis',
-					margin: 0,
-				} }
-				shapeStyles={ { margin: 0 } }
-			/>
-		</LineChart>
+		<div className={ clsx( styles.chart, className ) }>
+			<LineChart
+				className={ styles.chartContent }
+				data={ styledSeries }
+				options={ chartOptions }
+				margin={ percentageMargin ?? emptyChartProps.margin ?? DEFAULT_MARGIN }
+				maxWidth={ maxWidth }
+				resizeDebounceTime={ RESIZE_DEBOUNCE_MS }
+				withLegendGlyph={ false }
+				showLegend={ false }
+				curveType="monotone"
+				withGradientFill
+				withTooltips={ !! renderTooltip && ! isEmptyData }
+				renderTooltip={ renderTooltip }
+			>
+				<LineChart.Legend
+					shape="line"
+					className={ styles.legend }
+					itemClassName={ styles.legendItem }
+					itemStyles={ {
+						margin: 0,
+					} }
+					labelClassName={ styles.legendLabel }
+					labelStyles={ {
+						maxWidth: '100%',
+						textOverflow: 'ellipsis',
+						margin: 0,
+					} }
+					shapeStyles={ { margin: 0 } }
+				/>
+			</LineChart>
+		</div>
 	);
 }
@@ -0,0 +1,13 @@
+{
+	"name": "@automattic/jetpack-premium-analytics-widget-average-items-per-order",
+	"version": "0.1.0-alpha",
+	"private": true,
+	"type": "module",
+	"dependencies": {
+		"@jetpack-premium-analytics/widgets-toolkit": "link:../../packages/widgets-toolkit",
+		"@wordpress/i18n": "^6.9.0",
+		"@wordpress/icons": "^13.0.0",
+		"@wordpress/ui": "0.13.0",
+		"react": "18.3.1"
+	}
+}
@@ -0,0 +1,27 @@
+import {
+	OrderMetricWidget,
+	WidgetRoot,
+	type ReportParamsFieldAttributes,
+} from '@jetpack-premium-analytics/widgets-toolkit';
+
+type AverageItemsPerOrderRenderProps = {
+	attributes?: Partial< ReportParamsFieldAttributes >;
+};
+
+/**
+ * Average items per order widget.
+ *
+ * Thin composition over the widgets-toolkit: WidgetRoot provides the query
+ * client, chart theme, and resolved report params; OrderMetricWidget fetches
+ * the orders report and renders the avg_items metric with a comparison delta
+ * and sparkline.
+ */
+export default function AverageItemsPerOrderRender( {
+	attributes,
+}: AverageItemsPerOrderRenderProps ) {
+	return (
+		<WidgetRoot attributes={ attributes } options={ { from: '/' } }>
+			<OrderMetricWidget metricKey="avg_items" />
+		</WidgetRoot>
+	);
+}
@@ -0,0 +1,70 @@
+import { getDefaultQueryParams } from '@jetpack-premium-analytics/data';
+import {
+	DEFAULT_WIDGET_DASHBOARD_STORY_ARGS,
+	WidgetDashboardWithWidget as WidgetDashboardWithWidgetStory,
+	widgetDashboardWithWidgetArgTypes,
+	type WidgetDashboardWithWidgetControls,
+} from '../../stories/widget-dashboard-with-widget';
+import { registerReportMocks } from '../../../packages/widgets-toolkit/src/stories/mocks/register-report-mocks';
+import AverageItemsPerOrderRender from '../render';
+import widgetDefinition from '../widget';
+import type { Meta, StoryObj } from '@storybook/react';
+import type { WidgetRenderProps } from '@wordpress/widget-primitives';
+import type { ComponentType } from 'react';
+
+registerReportMocks();
+
+const AVERAGE_ITEMS_RENDER_MODULE = 'storybook/average-items-per-order';
+
+interface AverageItemsPerOrderDashboardStoryProps extends WidgetDashboardWithWidgetControls {
+	withComparison: boolean;
+}
+
+function AverageItemsPerOrderDashboardStory( {
+	withComparison,
+	...dashboardStoryArgs
+}: AverageItemsPerOrderDashboardStoryProps ) {
+	return (
+		<WidgetDashboardWithWidgetStory
+			{ ...dashboardStoryArgs }
+			widgetType={ widgetDefinition }
+			renderModule={ AVERAGE_ITEMS_RENDER_MODULE }
+			renderComponent={
+				AverageItemsPerOrderRender as ComponentType< WidgetRenderProps< unknown > >
+			}
+			attributes={ {
+				reportParams: getDefaultQueryParams( withComparison ),
+			} }
+		/>
+	);
+}
+
+const meta = {
+	title: 'Packages/Premium Analytics/Widgets/AverageItemsPerOrder',
+	component: AverageItemsPerOrderDashboardStory,
+	tags: [ 'autodocs' ],
+	args: {
+		...DEFAULT_WIDGET_DASHBOARD_STORY_ARGS,
+		withComparison: true,
+	},
+	argTypes: {
+		...widgetDashboardWithWidgetArgTypes,
+		withComparison: {
+			control: 'boolean',
+		},
+	},
+	parameters: {
+		docs: {
+			description: {
+				component:
+					'Dashboard widget that displays the average number of items per order with an optional comparison period and sparkline.',
+			},
+		},
+	},
+} satisfies Meta< typeof AverageItemsPerOrderDashboardStory >;
+
+export default meta;
+
+type Story = StoryObj< typeof meta >;
+
+export const WidgetDashboardWithWidget: Story = {};
@@ -0,0 +1,6 @@
+{
+	"name": "jpa/average-items-per-order",
+	"title": "Average items per order",
+	"description": "Show the average number of products per order over a set period of time.",
+	"category": "orders"
+}
@@ -0,0 +1,26 @@
+/**
+ * WordPress dependencies
+ */
+import { __ } from '@wordpress/i18n';
+import { chartBar } from '@wordpress/icons';
+
+/**
+ * Widget type definition.
+ *
+ * Ported from `woocommerce-analytics/average-items-per-order` in
+ * woocommerce/woocommerce-analytics (next-woocommerce-analytics).
+ *
+ * Report params intentionally come from the analytics dashboard's global
+ * date-range state for now. Adding widget-level overrides needs a host-level
+ * control registry so analytics dashboards can hide the field while other
+ * dashboards can opt in.
+ */
+export default {
+	name: 'jpa/average-items-per-order',
+	title: __( 'Average items per order', 'jetpack-premium-analytics' ),
+	description: __(
+		'Show the average number of products per order over a set period of time.',
+		'jetpack-premium-analytics'
+	),
+	icon: chartBar,
+};