Premium Analytics: carry widget attributes through the registry

[retrofox]

Part of WOOA7S-2176

Proposed changes

• register_widget_types_from_manifest() carries the attributes

A widget.json declares into the registry, sanitized by sanitize_widget_attributes().
An attribute is one setting of a widget instance: a DataViews field in its JSON form (id, the string and boolean keys, elements, filterBy, format, isValid without custom, Edit), plus the keys the dashboard reads on top of a field, relevance so far.

A malformed or empty key drops, never the entry; an entry without a unique string id drops.
This mirrors gutenberg_sanitize_widget_attributes() from WordPress/gutenberg#82485.

• Beyond upstream, an element names its icon by reference (collection/icon-name, through sanitize_widget_icon()): the dashboard's jpa/toggle-group draws its options from it (Premium Analytics: resolve toggle group option icons by reference #53771).

• Widget_Type::$attributes

The attributes field on the /widget-modules REST record and the attributes contexts in src/widget-i18n.json mean that labels, headers, descriptions, placeholders, and option text translate with the widget's text domain.

• WIDGET_API_VERSION moves to 1.14.0: a consumer may declare attributes in its manifest and rely on the registry carrying them.

@wordpress/build 0.25.0 already emits attributes into the manifest and @wordpress/widget-primitives 0.9.0 merges a record's entries over the module's by id, so nothing else is needed on the client. No bundled widget declares attributes in widget.json yet; that move follows, widget by widget, once the widget.json string extraction is in place.

Related product discussion/links

• Linear: WOOA7S-2176 (part of WOOA7S-2174)
• Upstream: Widgets: carry declarative attributes through the widget pipeline WordPress/gutenberg#82485

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

No.

Testing instructions

• composer phpunit in projects/packages/premium-analytics: Widget_Metadata_Test covers the sanitizer, the translation contexts, hydration, and the REST record.

• To see it end-to-end, add to any widget's widget.json, e.g., widgets/clicks/widget.json:

  "attributes": [
    {
      "id": "chartType",
      "type": "jpa/toggle-group",
      "label": "Chart type",
      "relevance": "high",
      "elements": [
        { "value": "line", "label": "Line chart", "icon": "jpa/chart-line" },
        { "value": "bar", "label": "Bar chart", "icon": "jpa/chart-bar" }
      ]
    }
  ]

Rebuild

jetpack build packages/premium-analytics

Open the dashboard and check GET /wp-json/wpcom/v2/widget-modules: the jpa/clicks record carries the attribute with both elements and their icons.

Before

|

This branch, with the testing code above:

The widget's controls then show the toggle (the attribute reaches the module's schema by id).

[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), and enable the update/pa-widget-attributes-registry branch.
• To test on Simple, run the following command on your sandbox:

bin/jetpack-downloader test jetpack update/pa-widget-attributes-registry

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!

[jp-launch-control]

Code Coverage Summary

Coverage changed in 2 files.

File	Coverage	Δ%	Δ Uncovered
projects/packages/premium-analytics/src/widget-types.php	198/207 (95.65%)	0.45%	2 ❤️‍🩹
projects/packages/premium-analytics/src/widget-modules.php	39/54 (72.22%)	0.52%	0 💚

Full summary · PHP report · JS report

[louwie17]

Thanks @retrofox, this tested well and code looks good! I added the chartType example to the Clicks widget.json on a local Docker site, and the /widget-modules record carried it through with both elements, while a duplicate id, an empty label, an unknown relevance and isValid.custom were all dropped as expected.

Left one small inline nit on the changelog entry, can be a quick fix before merging. LGTM 🚀

[dognose24]

Thanks, this looks good. I compared sanitize_widget_attributes() line by line with gutenberg_sanitize_widget_attributes() at the merge commit of WordPress/gutenberg#82485: identical apart from the element icon going through sanitize_widget_icon().

I also checked the "nothing else is needed on the client" claim: @wordpress/build 0.25.0 serializes each attribute object whole into the PHP manifest (toPhpAttributesLiteral() → toPhpValueLiteral()), element icons included, and @wordpress/widget-primitives 0.9.0 merges the record's entries over the module's by id in mergeAttributes().

Changelog scope is right too: no bundled widget declares attributes yet, so nothing is observable in a plugin.

Two small notes inline, neither blocking.

[dognose24]

#53771 also moves WIDGET_API_VERSION from 1.13.0 to 1.14.0, on an independent branch, and its 1.14.0 row in the docs says something different (that branch still has the paragraph form, this one the table). From #53778 I read the intent as one combined 1.14.0, which is fine, but whichever of the two lands second will conflict here and in dashboard-widgets.md. Suggest the second one, on rebase, replaces its 1.14.0 row with the merged wording #53778 already carries rather than bumping to 1.15.0.

[dognose24]

The same explanation now lives in three places: this docblock, the Widget_Type::$attributes docblock, and the Vocabulary table in docs/dashboard-widgets.md ("a DataViews field in its JSON form, plus the keys the dashboard reads on top of a field (relevance, so far)"). The docs table is the natural owner. Suggest this docblock keeps only what the function does, which also brings it back inside the comment budget:

/**
 * Sanitizes a widget attribute schema. A malformed or empty key drops, never
 * the entry; an entry without a unique string `id` drops.

and the property docblock in class-widget-type.php a one-liner pointing at the docs: Attribute schema, one entry per setting of a widget instance; see docs/dashboard-widgets.md § Vocabulary.

[retrofox]

sgtm. updating.