Widgets: carry declarative attributes through the widget pipeline

[retrofox]

What

Moves a widget's attribute schema into widget.json and carries it through the build manifest, the PHP registry, and /wp/v2/widget-modules, where useWidgetTypes merges it with the module's entries by id. The three core widgets that declared attributes (activity, events, hello-world) now do so in JSON.

Closes #82483. Part of #77629.

Why

Attributes were the only part of the declaration that never left widget.ts: the server could not see them, a widget without a JS module could not declare any, and field labels bypassed textdomain. Since the field type registry (#80148) the declarations are plain data, so the split had no reason left.

How

packages/wp-build/lib/build.mjs, widget-utils.mjs

collectWidgets reads attributes from widget.json and generateWidgetRegistry writes it into build/widgets/registry.php through a generic JSON-to-PHP literal helper. Entries without a string id drop at build time; the shape is constrained at registration.

lib/experimental/dashboard-widgets/widget-types.php, widget-i18n.json, class-wp-widget-type.php

gutenberg_sanitize_widget_attributes() keeps the JSON-expressible Field keys, requires a unique string id, and strips isValid.custom. label, description, placeholder and option labels translate through the i18n schema like action labels.

lib/experimental/dashboard-widgets/class-wp-rest-widget-modules-controller.php

Exposes attributes in the response and the item schema, with type as an open string and relevance as an enum.

packages/widget-primitives/src/types.ts, hooks/use-widget-types.ts

WidgetAttributeRecord is the wire form of an attribute and joins WidgetModuleRecord. The hook resolves record attributes on both paths: a record without a module gets its schema for the first time, and a record with a module merges by id, the record winning a shared key and module-only entries appended.

widgets/activity, widgets/events, widgets/hello-world

The declarations move to widget.json. activity and events drop widget.ts; hello-world keeps it for example.

Docs

The architecture document, the two package READMEs and the field types story describe the new home and the merge rule.

Testing

1. Build, then check the registry carries the schema:

grep -n "'attributes'" build/widgets/registry.php

2. Open the dashboard, add the WordPress events widget and confirm the location control renders in the tile header. Add Activity and open its settings to see "Items per page".

3. Confirm the REST record carries the schema:

wp eval 'wp_set_current_user( 1 ); $r = rest_do_request( new WP_REST_Request( "GET", "/wp/v2/widget-modules/core/events" ) ); echo json_encode( $r->get_data()["attributes"] );'

4. Run the unit tests:

npm run test:unit -- packages/widget-primitives/src/hooks/test/use-widget-types.jsdom.test.tsx

vendor/bin/phpunit -c phpunit.xml.dist --filter 'Gutenberg_Widget_Types_Test|WP_REST_Widget_Modules_Controller_Test'

Follow-ups

• attributes in schemas/json/widget.json once Widgets: Add widget.json metadata schema #77640 lands, derived from the DataViews Field type
• The three widgets still list @wordpress/widget-primitives in package.json; dropping it needs a lockfile update
• The gettext extraction in Dashboard Widgets: emit a gettext strings file for widget.json metadata #80564 needs the attribute paths

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. To trigger a review, include @coderabbitai review in the PR description. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Team

Run ID: c7431f5b-38ae-4659-9a0f-d26fdab195ac

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: retrofox <retrofox@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[github-actions]

🤖 PR meta 🤖

📦 Bundle size

Size Change: +82 B (0%)

Total Size: 8 MB

📦 View Changed

Filename	Size	Change
build/modules/widget-primitives/index.min.js	1.72 kB	+86 B (+5.26%)	🔍
build/scripts/block-library/index.min.js	367 kB	-4 B (0%)

_{619e3c5 Run}

⚡ Performance

Show the results

Client side metrics exclude the server response time.

front-end-block-theme

Metric	282766f	trunk	% Change
timeToFirstByte	48.65 ms +13.67% -9.66%	47 ms +9.47% -8.51%	3.51%
largestContentfulPaint	80 ms +2.5% -10%	76 ms +2.63% -7.89%	5.26%
lcpMinusTtfb	27.4 ms +19.53% -7.3%	26.4 ms +14.02% -7.58%	3.79%
wpBeforeTemplate	25.98 ms +8.16% -17.24%	23.81 ms +15.75% -10.42%	9.11%
wpTemplate	19.54 ms +1.64% -5.78%	19 ms +5.21% -4.95%	2.84%
wpTotal	45 ms +11.96% -9.07%	43.1 ms +9.47% -7.73%	4.41%
wpMemoryUsage	7.52 MB +0% -0%	7.48 MB +0% -0%	0.44%
wpDbQueries	17 +0% -0%	17 +0% -0%	0%

front-end-classic-theme

Metric	282766f	trunk	% Change
timeToFirstByte	36.25 ms +10.21% -4.69%	30.05 ms +17.14% -5.66%	20.63%
largestContentfulPaint	74 ms +8.11% -2.7%	64 ms +6.25% -6.25%	15.63%
lcpMinusTtfb	37.55 ms +5.86% -1.46%	31.9 ms +10.19% -1.1%	17.71%
wpBeforeTemplate	19.98 ms +21.47% -5.16%	19.04 ms +21.06% -2.73%	4.94%
wpTemplate	12.32 ms +9.42% -7.39%	7.79 ms +8.47% -1.93%	58.15%
wpTotal	33.08 ms +11.91% -3.69%	26.89 ms +20.12% -2.75%	23.02%
wpMemoryUsage	5.51 MB +0% -0%	5.37 MB +0% -0%	2.64%
wpDbQueries	14 +0% -0%	10 +0% -0%	40%

media-processing

Metric	282766f	trunk	% Change
mediaProcessingJpeg	324.11 ms +2.32% -0.79%	322.57 ms +0.13% -0.86%	0.48%
mediaProcessingAvif	4955.7 ms +0.25% -0.11%	4963.18 ms +0.17% -0.12%	-0.15%
mediaProcessingJpegToAvif	3548.13 ms +0.1% -0.2%	3554.77 ms +0.41% -0.2%	-0.19%

media-upload

Metric	282766f	trunk	% Change
jpegUploadProcessing	1424.38 ms +1.39% -1.79%	1408.39 ms +1.53% -0.54%	1.14%
pngUploadProcessing	183.73 ms +6.71% -3.43%	183.65 ms +1.95% -3.52%	0.04%
largeJpegUploadProcessing	1407.48 ms +1.74% -0.37%	1396.23 ms +0.91% -0.36%	0.81%
multipleImageUploadProcessing	1472 ms +0.79% -0.89%	1475.98 ms +1.65% -1.33%	-0.27%

post-editor

Metric	282766f	trunk	% Change
serverResponse	310.86 ms +4.27% -9.02%	308.24 ms +3.67% -7.4%	0.85%
firstPaint	147.38 ms +92.23% -13.31%	148.48 ms +24.56% -8.71%	-0.74%
domContentLoaded	861.18 ms +2.97% -0.64%	857.39 ms +2.13% -1.29%	0.44%
loaded	862.07 ms +2.97% -0.61%	858.23 ms +2.12% -1.3%	0.45%
firstContentfulPaint	300.29 ms +0.82% -4.7%	286.09 ms +8.28% -3.08%	4.96%
firstBlock	2268.21 ms +0.98% -2.27%	2287.72 ms +1.22% -1.85%	-0.85%
type	10.43 ms +4.89% -7.38%	11.04 ms +3.53% -2.63%	-5.53%
typeWithoutInspector	10.65 ms +5.73% -9.01%	11.26 ms +4.88% -12.43%	-5.42%
typeWithTopToolbar	14.34 ms +12.97% -6.07%	14.58 ms +11.87% -1.99%	-1.65%
typeContainer	7.76 ms +7.22% -2.32%	8.13 ms +9.1% -10.7%	-4.55%
focus	54.74 ms +8.48% -2.16%	56.3 ms +11.56% -3.68%	-2.77%
firstFocus	120.48 ms +0% -0%	132.09 ms +0% -0%	-8.79%
selectAll	330.83 ms +8.23% -0.19%	347.54 ms +1.97% -5.21%	-4.81%
listViewOpen	48.33 ms +13.24% -11.4%	45.84 ms +23.3% -6.74%	5.43%
inserterOpen	18.21 ms +10.71% -10.76%	17.58 ms +4.95% -10.18%	3.58%
inserterHover	3.17 ms +10.09% -28.08%	2.39 ms +11.72% -20.5%	32.64%
inserterSearch	7.4 ms +8.78% -8.92%	6.55 ms +7.33% -6.26%	12.98%
loadPatterns	462.53 ms +2.5% -1.84%	463.16 ms +0.89% -5.67%	-0.14%
wpTotal	303.59 ms +3.98% -9.23%	300.47 ms +3.59% -7.41%	1.04%
wpMemoryUsage	13.09 MB +0% -0%	13.05 MB +0% -0%	0.27%
wpDbQueries	54 +0% -0%	54 +0% -0%	0%

site-editor

Metric	282766f	trunk	% Change
serverResponse	417.6 ms +6.5% -2.47%	428.91 ms +4.04% -4.25%	-2.64%
firstPaint	207.76 ms +40.9% -4.71%	202.79 ms +17.82% -8.58%	2.45%
domContentLoaded	1284.39 ms +1.61% -0.77%	1271.22 ms +1.75% -0.48%	1.04%
loaded	1285.51 ms +1.62% -0.77%	1272.35 ms +1.75% -0.49%	1.03%
firstContentfulPaint	399.53 ms +3.48% -0.98%	399.88 ms +1.89% -0.79%	-0.09%
firstBlock	3921.65 ms +1.04% -0.65%	3891.12 ms +0.62% -0.44%	0.78%
type	14.71 ms +6.8% -7.75%	14.07 ms +7.96% -6.97%	4.55%
navigate	96.95 ms +2.23% -4.79%	106.68 ms +4.15% -6.9%	-9.12%
loadPatterns	1484.75 ms +5.42% -9.01%	1187.07 ms +4.26% -6.31%	25.08%
loadPages	1080.31 ms +2.85% -0.79%	1108.83 ms +9.35% -6.63%	-2.57%
wpTotal	407.93 ms +6.6% -2.59%	419.01 ms +4.06% -4.34%	-2.64%
wpMemoryUsage	12.07 MB +0% -0%	12.04 MB +0% -0%	0.22%
wpDbQueries	43.5 +1.15% -1.15%	43.5 +1.15% -1.15%	0%

_{619e3c5 Run}