Fields API - #83368

Part of #74865
Backport PR at WordPress/wordpress-develop#13911

What?

This PR implements an extensible Fields API on the server. Consumers tap a fields_api_init action to register their fields. Two examples ship in this PR:

1. An e2e test plugin registering fields imperatively in a variety of scenarios: declarative-only fields, fields with JavaScript (script modules), fields with data (REST), fields with CSS.

function gutenberg_test_fields_api_add_field_declarative( $registry ) {
	$registry->register(
		'gutenberg-test-fields-api', // Origin.
		'postType',                  // Kind.
		'page',                      // Name.
		array(
			array(
				'id'            => 'menu_order',
				'type'          => 'integer',
				'label'         => 'Order',
				'description'   => 'Position of the page among its siblings.',
				'enableSorting' => false,
				'filterBy'      => false,
			),
		)
	);
}
add_action( 'fields_api_init', 'gutenberg_test_fields_api_add_field_declarative' );

2. Core's own fields, registered declaratively from folders of field.php files:

function register_core_field_collections( $registry ) {
	wp_register_field_collection( $registry, __DIR__ . '/page' );
}
add_action( 'fields_api_init', 'register_core_field_collections', 0 );

Why?

Part of #74865

How?

Server: fields_api_init hook, the registry, and the API

• Gutenberg_Fields_Registry holds the fields per entity (kind, name) and its script module. It exposes register(), update() and unregister().
• The registry only accepts writes while the fields_api_init action fires, and it fires that action lazily the first time something reads it. This is because fields are registered based on the post types and supports, so they need to be registered after init but before the REST route/script modules are requested.
• lib/compat/wordpress-7.2/fields-api.php wraps the registry in functions and adds wp_register_field_collection(), the declarative format: a folder with index.php and one subfolder per field whose field.php returns the serializable part of that field. See core-fields/src/page/field.php for an example.

Transport: /wp/v2/fields and preloading

• Gutenberg_REST_Fields_Controller_7_2 serves GET /wp/v2/fields?kind=…&name=…, returning the entity's fields plus the script_modules that provide their JavaScript parts.
• lib/compat/wordpress-7.2/preload.php adds the matching preload paths per screen.

Client: core-data → fields-loader → script modules

• @wordpress/core-data gains a public getFieldsConfig( kind, name ) selector (plus resolver, reducer and the FieldsConfig type) that requests and caches the route.
• @wordpress/fields-loader, a new package, exposes useFields() for components and loadFields() for route loaders and other code outside React. They merge each script module's default export into the fields that came from REST.
• The modules reach the browser through the import map: _gutenberg_add_field_modules_to_editor_script() runs on admin_footer, reads the registry, and declares every registered module as a dynamic module_dependencies entry of the wp-editor script. Dynamic means the module is listed in the import map but only fetched when the loader imports it.

Core's fields: @wordpress/core-fields

• A new package holding every field definition, PHP for the serializable part and TypeScript for the rest, structured per entity: attachment, page, wp_template, wp_template_part, wp_block.
• We also register (see post_type_supports folder) the default fields for every REST-exposed post type from what that post type/theme supports. This serves to bootstrap the fields. A post type can opt out of a registered default field using the fields_api_post_type_supports_exclusions filter (example), or just unregister it in fields_api_init.

Screens

• Every screen has been migrated from usePostFields to the new loadFields()/useFields() utils.
• Some screens still define local fields. Sometimes all of them; some other times in addition to the ones coming from core-fields. This table lists all the exceptions so far:

What changes for consumers

• wp.editor.registerEntityField and wp.editor.unregisterEntityField are deprecated and have no effect. Fields need to be registered in PHP on fields_api_init instead.
• The private usePostFields hook is gone, and the core/editor store no longer holds fields: its private registerEntityField, unregisterEntityField and getEntityFields are gone, and registerPostTypeSchema now registers only actions.
• The format field comes from the server, offered when the post type supports post-formats. Before, it also checked the disablePostFormats editor setting, which only the post editor screen set — so it is now hidden consistently in the site editor for themes without post formats.
• The content-preview field is no longer registered for post types supporting editor. No view referenced it; the views that want a preview declare their own.

How to merge this PR

I'm going to be away a few days, so I wanted to share how would I do it in case anyone is available/willing to pick it up. Feel free to use your own approach. This can also serve as a map of relationships.

Stage 1: prepare, no actual behaviour changes.

Each can be its own PR, some can be merged together.

1. Merge server side APIs (registry, fields api, endpoint, preload):
   • lib/compat/wordpress-7.1/class-gutenberg-rest-view-config-controller-7-1.php
   • lib/compat/wordpress-7.2/class-gutenberg-fields-registry.php\
   • lib/compat/wordpress-7.2/class-gutenberg-rest-fields-controller-7-2.php
   • lib/compat/wordpress-7.2/fields-api.php
   • lib/compat/wordpress-7.2/preload.php
   • lib/compat/wordpress-7.2/rest-api.php
   • lib/load.php
   • All files under phpunit but phpunit/view-config-api-test.php.
2. Copy MediaEdit to media-utils as private API:
   • All files under packages/media-utils.
   • Stop re-exporting MediaEdit from @wordpress/fields (optional, see thread)
   • tools/eslint/suppressions.json.
3. Merge new core-fields package:
   • All files under packages/private-apis/.
   • All files under packages/core-fields/.
   • Verify it doesn't become a global under wp.*.
   • Updates to .github/labeler.yml.
4. Merge data mechanism:
   • All files under packages/core-data.
   • All files under packages/fields-loader.
     • Verify the new package doesn't become a global under wp.*.
     • Updates to .github/labeler.yml.
     • tools/validation/check-private-apis.config.json
     • All files under packages/dependency-extraction-webpack-plugin/.
5. Fix docs:
   • docs/private-apis.md

Stage 2: switch consumers.

It can be done one-by-one.

1. Demo plugin
   • All files under packages/e2e-tests/plugins/fields-api/.
   • test/e2e/specs/site-editor/fields-api.spec.js
2. Site Editor v1
   • All files under packages/edit-site/ but packages/edit-site/src/components/sidebar-identity/index.jsx
3. Media editor:
   • All files under packages/media-editor.
   • All files under routes/media-editor.
   • lib/compat/wordpress-7.2/view-config-api.php
   • phpunit/view-config-api-test.php
   • packages/edit-site/src/components/sidebar-identity/index.jsx
   • packages/editor/src/components/media/media-editor-modal.jsx
   • All fields under routes/identity/
4. Site Editor v2
   • All files under routes/navigation-list/.
   • All files under routes/pattern-list/.
   • All files under routes/post-list/.
   • All files under routes/template-list/.
   • All files under routes/template-part-list/.
5. Editor
   • packages/edit-post/src/index.jsx
   • docs/contributors/code/deprecations.md.
   • All remaining files under packages/editor/.
6. Do not re-export MediaEdit from @wordpress/fields. (thread)
7. Prevent PRs from being merged into @wordpress/fields and @wordpress/media-fields. To be decided: lint rule, docs?

Stage 3: after WordPress 7.2 release.

1. Deprecate packages @wordpress/fields and @wordpress/media-fields.

Testing Instructions

Visit the existing screens and verify they still work as expected:

• Post and page lists, including quick edit and the per-view field controls.
• Templates, template parts, patterns and navigation lists.
• The post summary sidebar in the post editor.
• The media library and the attachment editor form.

Use of AI Tools

Used Claude to analyze and create parts of this pull request. The author reviewed all the changes.