Premium Analytics: author widget metadata in widget.json, not widget.ts

[retrofox]

What?

Follow-up to #50615. Moves declarative widget metadata (name, title, help) out of each widget's widget.ts module and into its widget.json manifest, across all 74 widgets. widget.ts now carries only the non-serializable runtime fields (icon, attributes, example). Stories build their widget type from the manifest via a new shared createStoryWidgetType() helper.

Why?

#50615 wired the widget.json → PHP → REST metadata pipeline, with the dashboard merging the REST manifest over the lazily-imported module. That already made name/title/help on the module dead weight in production, since the REST value always wins. This follow-up completes the split the pipeline enabled: widget.json is the single source of truth for declarative metadata, and widget.ts holds only what cannot be serialized to JSON (a React icon element, attribute field components, example data). It also unifies how stories construct the widget type and removes ~50 ad-hoc as WidgetType[...] casts.

How?

• widget.ts → widget.json: moved help (unwrapping __()) into the manifest for 71 widgets, removed name/title/help from every widget.ts, and dropped the 44 now-orphan __ imports. Done with a TypeScript AST script (locate + extract + delete by text range, so formatting is preserved).
• Story helper: new widgets/stories/create-story-widget-type.ts. createStoryWidgetType( manifest, moduleDefinition ) combines identity + declarative metadata (from widget.json) with the runtime-only fields (from widget.ts), centralizing the casts in one place. It mirrors the runtime REST-over-module merge, which Storybook has no REST layer to perform.
• 72 stories migrated to the helper. The direct-pass (widgetType={ widgetDefinition }), spread, and explicit-object patterns all collapse to a single helper call. Incidental win: stories that previously omitted help/attributes now render them.
• Docs: AGENTS.md and rules/widgets.md updated (folder contract, name bullet, pitfall, and the story template future widgets copy).

Testing

• pnpm run typecheck: clean.
• eslint (touched ts/tsx): clean.
• pnpm run test: 1105/1109 pass. The 4 failures (clicks/referrers drill-down) are timeout flakes under load and pass in isolation (12/12). Those tests render render.tsx with attributes and touch none of the changed code.
• Storybook: each widget still renders its title, icon, and help in the dashboard story, now sourced from widget.json.

Follow-ups

• i18n extraction gap. widget.json strings are emitted by wp-build as bare PHP literals in the generated manifest, which no gettext extractor picks up (unlike block.json, which WP-CLI extracts via a dedicated BlockExtractor). The runtime translate pipeline added in Premium Analytics: carry widget.json metadata through the registry and REST #50615 therefore has no strings to look up. This is pre-existing (the title/description already in widget.json were never extracted either), but this PR widens it to help. The fix belongs upstream in @wordpress/build (emit translatable strings wrapped in __() with the text domain). Tracked separately.

[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 (WordPress.com Site Helper), and enable the update/widget-metadata-json branch.
• To test on Simple, run the following command on your sandbox:

bin/jetpack-downloader test jetpack-mu-wpcom-plugin update/widget-metadata-json

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]

Thanks @retrofox Looks good and confirmed widgets still render help.