Premium Analytics: Expand AGENTS.md with widget Storybook guidance and Overview clarifications by adamwoodnz · Pull Request #49679 · Automattic/jetpack

adamwoodnz · 2026-06-17T05:10:08Z

Proposed changes

Two related updates to the package's AGENTS.md (introduced in #49678):

1. New `## Widgets` section

Requires every widget to ship with a Storybook story, anchored to the new widget layout introduced in #49505 (Average items per order), not the legacy packages/widgets-toolkit/src/widgets/* widgets which are scheduled to be migrated. Specifically:

The required folder structure for new widgets — widgets/<name>/{package.json, widget.json, widget.ts, render.tsx, stories/<name>-widget.stories.tsx} — and the jpa/<name> naming convention shared by widget.json and widget.ts.
render.tsx should stay thin: compose WidgetRoot + a toolkit widget primitive rather than reimplement data fetching, chart wiring, or theming.
Story requirements: every widget ships three stories — a Default and a WithComparison close-up, plus a WidgetDashboardWithWidget story that renders through the shared WidgetDashboardWithWidget helper from widgets/stories/widget-dashboard-with-widget.tsx (mounting the real WidgetDashboard so it inherits the size / edit-mode / host-environment controls). Call registerReportMocks() at module level for data widgets, use the Packages/Premium Analytics/Widgets/<WidgetName> title path, and tag the stories [ 'autodocs' ].
Adding projects/packages/premium-analytics/widgets to projects/js-packages/storybook/storybook/projects.js so per-widget folders get auto-discovered.
A self-contained story template — inline snippets for all three stories that an agent can copy from the doc alone, without referencing any one widget's story file (which can drift) — plus a short list of widget-specific pitfalls (including "don't put new widgets under the legacy packages/widgets-toolkit/src/widgets/* path" and "don't use the legacy withWidgetRoot() decorator for new stories").

Dependency / sequencing. This PR documents files (e.g. widgets/stories/widget-dashboard-with-widget.tsx, the widgets/ Storybook root) that land in #49505. If this PR merges first the references will be aspirational until #49505 lands; if #49505 merges first they're concrete. Either order works.

2. Overview clarifications (from review)

Per code-review suggestions from @kangzj, the ## Overview section now spells out each consolidated surface as a bullet rather than an inline parenthetical:

Jetpack Stats — flagged as the Odyssey dashboard, with the stats-admin backend and the apps/odyssey-stats Calypso frontend, and explicitly mentions email stats alongside traffic / posts / subscribers / WordAds.
Woo Analytics — links the private woocommerce/woocommerce-analytics repo so it's discoverable.

Scoped narrowly per the issue's "start light, address missing stories rather than building a broader AI compatibility layer up front" framing.

Related product discussion/links

Linear: WOOA7S-1555
Builds on Premium Analytics: add AGENTS.md / CLAUDE.md for coding agents #49678 (initial AGENTS.md)
Companion to Premium Analytics: port the Average items per order widget #49505 (Average items per order — the first widget built on this layout)

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

No.

Testing instructions

This PR only updates documentation (AGENTS.md) and a changelog entry. No runtime code changes.

Read the new ## Widgets section in projects/packages/premium-analytics/AGENTS.md.
Compare the documented folder structure, render.tsx, widget.ts, and widget.json against the Average items per order widget in Premium Analytics: port the Average items per order widget #49505 (projects/packages/premium-analytics/widgets/average-items-per-order/*) and confirm they line up. The story template is self-contained by design (it trims that widget's source-transform / preset boilerplate), so it won't match its story file line-for-line.
Skim the updated ## Overview bullets and confirm they match how Stats and Woo Analytics are described elsewhere in the project.

Linear Issue: WOOA7S-1555

github-actions · 2026-06-17T05:13:14Z

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:

Ensure all required checks appearing at the bottom of this PR are passing.
Make sure to test your changes on all platforms that it applies to. You're responsible for the quality of the code you ship.
You can use GitHub's Reviewers functionality to request a review.
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 · 2026-06-17T05:13:23Z

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

kangzj

lgtm

nerrad

I've added a widget story in my PR (#49505 ) that could probably be a template for the Agent guidance? The current path in Storybook is for older style widgets that haven't been migrated yet.

nerrad · 2026-06-17T10:29:26Z

+4. **Title**: `Packages/Premium Analytics/Widgets Toolkit/Widgets/<WidgetName>`. This matches
+   the existing Storybook sidebar hierarchy — do not put new widgets at a different top-level
+   path.


I know this is an existing path, but in my PR, I'm placing it on the Packages/Premium Analytics/Widgets/<WidgetName> path because Widgets Toolkit is temporary and the items on the current path haven't been migrated yet.

Suggested change

4. **Title**: `Packages/Premium Analytics/Widgets Toolkit/Widgets/<WidgetName>`. This matches

the existing Storybook sidebar hierarchy — do not put new widgets at a different top-level

path.

4. **Title**: `Packages/Premium Analytics/Widgets/<WidgetName>`.

Thanks, I wasn't aware those were due to be migrated. Cursor updated the guidance based on your PR.

Feedback addressed

adamwoodnz · 2026-06-21T23:42:09Z

Pausing this until #49505 lands, as it now has conflicts and I'm unsure whether the stories in it are the final shape.

…cations to AGENTS.md Add a new ## Widgets section anchored to the widget layout introduced in #49505 (Average items per order): documents the required widgets/<name>/{package.json,widget.json,widget.ts,render.tsx,stories/} folder structure, the WidgetDashboardWithWidget-based story template, the Packages/Premium Analytics/Widgets/<WidgetName> title path, registerReportMocks() / autodocs requirements, the projects/js-packages/storybook/storybook/projects.js registration step, and widget-specific pitfalls (including avoiding the legacy packages/widgets-toolkit/src/widgets/* path and the legacy withWidgetRoot() decorator). Also restructure the existing ## Overview into a bulleted list with more detail on each consolidated surface (Odyssey dashboard / apps/odyssey-stats / email stats, and a link to the private woocommerce/woocommerce-analytics repo). Co-authored-by: Jasper Kang <kangzjnet@gmail.com>

Rework the AGENTS.md story guidance so an agent can build all three required stories from the doc alone, without copying a specific widget's story file (which can drift). Inline snippets for each story — Default and WithComparison close-ups plus the WidgetDashboardWithWidget harness story — share one setup block. Reconcile the surrounding requirements: the dashboard story proves the in-product render while the close-ups use a plain canvas decorator, and the legacy note no longer points at an example widget as the thing to copy. Also corrects the WidgetRenderProps import, which pointed at a non-existent @automattic/jetpack-widget-primitives package; the real type comes from @wordpress/widget-primitives. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01P2vY2GxKEJurnaod7phrFo

adamwoodnz · 2026-06-24T00:51:41Z

Updated based on the changes to #49505 @nerrad, ready for final review 🙏

nerrad

A few additional comments on things that stand out to me. Pre-approving because I don't think you need to get an additional review, it can be iterated on as needed.

nerrad · 2026-06-18T10:55:20Z

+New widgets live at the top of the package in `widgets/<widget-name>/` and are composed from
+primitives in `packages/widgets-toolkit/`. Each widget is its own pnpm workspace package so
+its render bundle can be lazy-loaded by the dashboard at runtime.


What about @automattic/charts? Should that be referenced here? I think we're generally moving toward not needing packages/widgets-toolkit and this is temporary while in development. So it's at risk of getting out of date?

Good point — updated: the opening paragraph now notes the widgets-toolkit primitives are built on @automattic/charts, plus a caveat that the toolkit is an interim layer (expected to fold into @automattic/charts) so its module paths are provisional rather than long-term API. e8d15fd

nerrad · 2026-06-18T10:56:41Z

+> reference implementation is the **Average items per order** widget (added in
+> [#49505](https://github.com/Automattic/jetpack/pull/49505)).


I don't think we should explicitly reference this PR because it could get stale? Maybe just leave it out, keep the rest of the paragraph. The skill can always be added to in the future if needed.

Done — dropped the explicit PR link from the legacy note and kept the rest of the paragraph. e8d15fd

nerrad · 2026-06-18T10:58:19Z

+- `name` in both `widget.json` and `widget.ts` MUST use the `jpa/` prefix
+  (e.g. `jpa/<widget-name>`).


Are we all settled on this prefix (writing this knowing that we've already been creating PRs with this prefix 😄 )? I think an agent just picked it as the prefix/namespace. I'm wondering if we should be more explicit... (i.e. premium-analytics/*)

The merged widgets already standardized on jpa/ (jpa/hello-world, jpa/locations, jpa/top-posts on trunk), so the doc reflects what's shipped. Moving to something like premium-analytics/* would mean renaming those, so I've left jpa/ here to keep the guidance matching reality — happy to track a rename as a separate decision if we want one.

nerrad · 2026-06-18T10:59:59Z

+### Widget pitfalls
+
+- Putting new widgets under `packages/widgets-toolkit/src/widgets/*` — that path is for the
+  legacy widgets that haven't been migrated yet.
+- Using the legacy `withWidgetRoot()` decorator for new stories — new widgets render via the
+  real `WidgetDashboard` through the shared story helper instead.
+- Putting the story at the wrong title path (e.g. `Packages/Premium Analytics/Widgets
+  Toolkit/Widgets/<Name>` — that's the legacy path).
+- Omitting `registerReportMocks()` at the top of the story file when the widget fetches
+  report data — the widget will render an error state.
+- Forgetting to register `projects/packages/premium-analytics/widgets` in
+  `projects/js-packages/storybook/storybook/projects.js` — the story won't appear in
+  Storybook at all.
+- Omitting `tags: [ 'autodocs' ]`, which silently drops the widget from the autogenerated
+  docs page.
+- Reimplementing data fetching or chart wiring inside `render.tsx` instead of composing
+  primitives from `@jetpack-premium-analytics/widgets-toolkit`.


How much of this is needed? Is it not already clear enough in the above content?

Agreed — trimmed to the two non-obvious legacy traps (the widgets-toolkit/src/widgets/* path and the withWidgetRoot() decorator). The other bullets just restated the REQUIRED folder-structure / story rules above, so they're gone. e8d15fd

From nerrad's review (#4524224327): - Note widgets-toolkit primitives are built on @automattic/charts, and flag the toolkit as an interim layer whose module paths are provisional. - Drop the explicit #49505 link from the legacy note so it can't go stale. - Trim the widget pitfalls to the two non-obvious legacy traps; the rest just restated the REQUIRED folder-structure / story rules above. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01P2vY2GxKEJurnaod7phrFo

adamwoodnz self-assigned this Jun 17, 2026

adamwoodnz added the Docs label Jun 17, 2026

github-actions Bot added [Package] Premium Analytics [Status] In Progress labels Jun 17, 2026

github-actions Bot added the [Status] Needs Author Reply We need more details from you. This label will be auto-added until the PR meets all requirements. label Jun 17, 2026

adamwoodnz marked this pull request as ready for review June 17, 2026 05:27

adamwoodnz requested review from a team and nerrad June 17, 2026 05:27

adamwoodnz added [Status] Needs Review This PR is ready for review. and removed [Status] Needs Author Reply We need more details from you. This label will be auto-added until the PR meets all requirements. [Status] In Progress labels Jun 17, 2026

github-actions Bot added the [Status] In Progress label Jun 17, 2026

cursor Bot changed the title ~~Premium Analytics: Add lightweight AGENTS.md with widget Storybook guidance~~ Premium Analytics: Add widget Storybook guidance to AGENTS.md Jun 17, 2026

kangzj previously approved these changes Jun 17, 2026

View reviewed changes

nerrad previously requested changes Jun 17, 2026

View reviewed changes

cursor Bot dismissed kangzj’s stale review via cdfa060 June 17, 2026 21:39

adamwoodnz requested a review from nerrad June 17, 2026 21:47

adamwoodnz removed the [Status] In Progress label Jun 17, 2026

kangzj reviewed Jun 18, 2026

View reviewed changes