Widget Primitives: extract into @wordpress/widget-primitives

[retrofox]

What?

Moves the widget toolkit from routes/dashboard/widget-primitives/ into a standalone package, packages/widget-primitives/, published as @wordpress/widget-primitives at 0.1.0-prerelease (experimental). No behavior changes.

The package is the single source of truth for the widget contract:

• Contract types: WidgetType, WidgetName, WidgetIcon, WidgetRenderProps, ResolveWidgetModule.
• Discovery: the useWidgetTypes() hook.
• Rendering: the <WidgetRender> host entry point.

Also adds docs/explanations/architecture/dashboard-widgets.md, explaining how the pieces of the widget system fit together (authoring convention, build pipeline, server registry, client contract, hosts).

Why?

The widget contract is a public boundary: authors write against it, hosts render through it.

While it lives in routes/dashboard/, it stays private: no external project can consume it.
Moving it to a public, top-level package makes it consumable on its own.

How?

• git mv of the tree into packages/widget-primitives/src/, preserving history; the sources are unchanged.
• Publish-ready package.json (exports/types pointing at the build artifacts, wpScript: false, publishConfig.access: public, peer dep on react) and a tsconfig.json with its project references.
• WidgetIcon stays a plain SVG ReactElement, with no @wordpress/ui dependency: any host can define and consume its own icons.
• The dashboard route now consumes the package: a file: workspace dependency, imports pointing at @wordpress/widget-primitives, its exclude in routes/dashboard/tsconfig.json removed, and a reference in the root tsconfig.json.
• README aligned to the standard package pattern and an initial CHANGELOG.md; WidgetRender stories, with an Introduction page that renders the architecture document.

Testing

1. Run the unit tests covering the dashboard route and the widget contract (dashboard rendering, inserter, commands, settings, widget creation):

npm run test:unit routes/dashboard

2. Storybook

• Widget Primitives/Introduction renders the architecture document; under Widget Primitives/WidgetRender, Default shows the render contract.
• WithSettings edits the widget through a DataForm mounted from the type's declarative attributes (Field[]).
• WithHostChrome frames the widget in host chrome (striped) around the widget render (solid).

npm run storybook:dev

Screen.Recording.2026-06-12.at.10.19.26.AM.mov

3. Manual check through the dashboard route. Enable the gutenberg-dashboard-widgets experiment and load /wp-admin/:

4. Confirm that widgets render, that the inserter lists the registered widget types, and that widget settings open.
   All widget-type data now flows through @wordpress/widget-primitives.

5. Disable the gutenberg-dashboard-widgets experiment and confirm wp-admin still works as before: the package is consumed only behind the experiment, so the default admin must be unaffected.

Follow-ups

• Extract the dashboard rendering engine (widget-dashboard) into its own package, depending on this one.
• Decide per package whether to expose the externalized ES module.
• After the first npm sync, verify @wordpress/[email protected] installs and resolves outside the monorepo.

[github-actions]

Size Change: 0 B

Total Size: 8.58 MB

_{compressed-size-action}

[github-actions]

Flaky tests detected in 21d2816.
Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/27568263274
📝 Reported issues:

• [Flaky Test] shouldn't conflict with server-side autosave #78706 in /test/e2e/specs/editor/various/autosave.spec.js
• [Flaky Test] shows post-locked modal when document size limit is exceeded #78753 in /test/e2e/specs/editor/collaboration/http-only/collaboration-document-size-lock.spec.ts

[chihsuan]

Nice, clean extraction! @retrofox Verified that widgets still render and wp-admin still works.

Just flagged a small thing in the package README's "How discovery works" section. Other than that, LGTM.

[chihsuan]

I noticed that the SVG diagram show { name, render_module, widget_module, presentation }. Should we aligning step 2 and step 4 to include presentation?

[retrofox]

yes, we should. Thanks!!!

[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 <[email protected]>
Co-authored-by: chihsuan <[email protected]>

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