Widget Primitives: Add a field type registry for widget attributes

[retrofox]

What

Adds an extensible field type registry to @wordpress/widget-primitives: named, reusable DataViews field bundles that widget attributes can reference by type.

Registers the first one, location, from the dashboard route, and migrates the events widget to consume it by name.

Why

DataViews' field types and form controls are closed lists, so the only way a widget could ship a custom control was a per-field Edit component in its metadata module. That binds the schema to code: controls can't be reused across widgets, and a schema carrying component references can't stay serializable.

A named registry keeps the widget metadata declarative (type: 'location') while the consuming application decides the vocabulary it provides.

How

• New packages/widget-primitives/src/field-types/ module. Public API: registerFieldType and the FieldTypeDefinition type; resolution stays package-internal, applied through useWidgetTypes.
• Names are lowercase identifiers, plain (location) or namespaced (acme/rating); resolution is registry-first, so a registered name wins over a DataViews built-in of the same name. First registration wins; invalid names are ignored; unregistered names degrade exactly as unknown types do in core: silently.
• Resolution translates a reference into plain per-field Field props. baseType names the DataViews type whose defaults the field inherits; isValid merges rule by rule; the field's own props win. DataViews is never patched.
• WidgetAttribute.type widens through ResolvableField to accept registered names, keeping DataViews' native names as IDE suggestions.
• The dashboard route registers the vocabulary at module scope (routes/dashboard/field-types/) and hosts the location control, moved from the events widget, which goes fully declarative: type: 'location', no Edit import. Registration and consumption share the route bundle: no build changes needed.

Documentation

New Field Types doc (registration, resolution, and rendering on the chrome header and the settings surface, with a pipeline diagram) and a WithFieldType story on WidgetRender: rating registered once, referenced by name, rendered on the prominent surface. Both under Widget Primitives in Storybook (npm run storybook:dev).

Screen.Recording.2026-07-12.at.11.25.17.PM.mov

Testing

1. Run npm run build (or npm start) and open the dashboard with the gutenberg-dashboard-widgets experiment enabled.
2. Add the WordPress Events widget.
3. The widget toolbar renders the location control inline (city autocomplete plus geolocation) as the high-relevance field.
4. Unit tests: npx jest --config test/unit/jest.config.js packages/widget-primitives.

Follow-ups

• Move widget attributes into widget.json: manifest them through the build, expose them via the widget-modules endpoint (Add widget.json metadata schema #77629), and translate label/description like title today. widget.ts then remains only for icons, custom validators, and per-field Edit escapes.
• Ship @wordpress/widget-primitives as a WordPress script module and move the registration to the dashboard's page init module: page-level (route-agnostic) vocabulary and one shared registry instance (Widget Primitives: Ship as a script module #80149).
• Extensibility beyond the app: let third-party widget modules register field types (needs the script-module surface), and open the upstream conversation about native fieldTypes in DataViews; the registry would then become a thin adapter.

[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>
Co-authored-by: chihsuan <chihsuan@git.wordpress.org>

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

[Copilot]

Pull request overview

Adds an extensible field type registry to @wordpress/widget-primitives so widgets can reference named, reusable DataViews field bundles (e.g. type: 'core/location') while keeping widget metadata serializable and host-resolved.

Changes:

• Introduces a field type registry (registerFieldType) and resolution step (resolveFields applied via useWidgetTypes) to translate namespaced field type references into plain DataViews Field props.
• Registers the first dashboard-provided field type (core/location) from packages/dashboard-init and migrates the Events widget to consume it declaratively.
• Exposes @wordpress/widget-primitives as a WordPress script module to ensure a page-wide singleton registry instance.

Reviewed changes

Copilot reviewed 25 out of 28 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
widgets/events/widget.ts	Switches the location attribute to reference the registered core/location field type and removes the per-widget Edit control wiring.
widgets/events/types.ts	Adds a dedicated EventsWidgetAttributes type for reuse across the widget module.
widgets/events/render.tsx	Updates imports to use EventsWidgetAttributes from the new types module.
widgets/events/components/location-setting-control/index.ts	Removes the old re-export entrypoint (control moved to dashboard-init).
widgets/events/components/index.ts	Removes exports for the old location control/picker from the events widget component barrel.
tsconfig.json	Adds packages/dashboard-init to TS project references.
packages/widget-primitives/src/types.ts	Widens widget attribute typing to allow namespaced resolvable field type references.
packages/widget-primitives/src/index.ts	Exposes registerFieldType and FieldTypeDefinition from the package public API.
packages/widget-primitives/src/hooks/use-widget-types.ts	Applies resolveFields so hosts receive plain DataViews fields after widget metadata is loaded.
packages/widget-primitives/src/field-types/test/field-types.ts	Adds unit tests for the registry and field resolution behavior.
packages/widget-primitives/src/field-types/index.ts	Adds an internal barrel for field-type registry helpers and types.
packages/widget-primitives/src/field-types/field-types.ts	Implements the registry and resolveFields resolution/merge logic.
packages/widget-primitives/src/components/widget-render/stories/index.story.tsx	Updates Storybook story to resolve fields when bypassing useWidgetTypes.
packages/widget-primitives/README.md	Documents the new field type registry capability and behavior.
packages/widget-primitives/package.json	Marks the package as a WordPress script module via wpScriptModuleExports.
packages/widget-primitives/CHANGELOG.md	Notes the new registry and script-module exposure in changelog entries.
packages/dashboard-init/tsconfig.json	Adds TS project config and references for the new dashboard-init workspace.
packages/dashboard-init/src/index.ts	Registers dashboard field types early during init, before entity registration.
packages/dashboard-init/src/field-types/index.ts	Registers the dashboard’s core/location field type mapping to LocationControl.
packages/dashboard-init/src/components/location-picker/location-picker.tsx	Adjusts lint suppression placement and updates CSS module class usage.
packages/dashboard-init/src/components/location-picker/location-picker.module.css	Renames the class to kebab-case to match the updated access pattern.
packages/dashboard-init/src/components/location-picker/index.ts	Adds a barrel export for LocationPicker.
packages/dashboard-init/src/components/location-control/location-control.tsx	Introduces LocationControl DataForm edit control for the core/location field type.
packages/dashboard-init/src/components/location-control/index.ts	Adds a barrel export for LocationControl.
packages/dashboard-init/README.md	Documents that the init module now also registers dashboard field types (e.g. core/location).
packages/dashboard-init/package.json	Adds runtime dependencies needed for the new field type/control registration.
packages/dashboard-init/CHANGELOG.md	Notes registering dashboard field types on init and the moved location control.
package-lock.json	Updates lockfile to reflect the new/updated dashboard-init dependencies.

[github-actions]

Size Change: 0 B

Total Size: 7.71 MB

_{compressed-size-action}

[github-actions]

Flaky tests detected in 1b1125d.
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/29254416633
📝 Reported issues:

• [Flaky Test] displays edits to the post title and content in the preview #38826 in /test/e2e/specs/editor/various/preview.spec.js

[chihsuan]

Really like this, it's nice improvement! @retrofox

I left a few non-blocking suggestions, also should we update dashboard-widgets.md? That document currently describes useWidgetTypes as importing and merging metadata, but not the new application registration → named reference → field resolution stage.

[chihsuan]

Could we surface a warning when a name is invalid or it's already registered? Right now a small typo could make the control quietly disappear with nothing in the console.

[chihsuan]

Would a small test here be worth it? The resolver is covered on its own, but this is the line that actually wires it into the pipeline. Fully optional.

[chihsuan]

name is any lowercase identifier

Could we make the accepted name syntax a little more explicit here? “Any lowercase identifier” sounds slightly broader than the regex we used.

[retrofox]

Really like this, it's nice improvement! @retrofox

I left a few non-blocking suggestions, also should we update dashboard-widgets.md?

Yes, we already started to improve the doc in this PR #80208.

Let's continue there to keep improving it. Initially, I focused mainly on the primitives package, but it's time to do the same for the dashboard package.