Proposal: The registerBlockSupport API

[Mamaduka]

Disclaimer: The document is based on the proposed API by @ellatrix and @gziolo. See #48809.

Summary

Introduce a new API, registerBlockSupport, for describing the behavior and rendering of block features that utilize support properties.

Problem

As the block editor started absorbing the complexities of block features like color, fonts, and dimension controls, it became apparent that the current method of integrating UI controls is not very sustainable and may sometimes hinder performance.

The present approach to add the "block support" features requires fragmenting the logic across multiple filters. Each filter is applied separately, overriding whole components multiple times. Additionally, it requires specific checks to ensure controls are only rendered when necessary and workarounds to prevent redundant re-mounting of the block's "Edit" component.

Example of current method

Alignment support

function addAttribute( settings ) {
	if ( 'type' in ( settings.attributes?.align ?? {} ) ) {
		return settings;
	}
	if ( hasBlockSupport( settings, 'align' ) ) {
		// Gracefully handle if settings.attributes is undefined.
		settings.attributes = {
			...settings.attributes,
			align: {
				type: 'string',
				// Allow for '' since it is used by updateAlignment function
				// in withToolbarControls for special cases with defined default values.
				enum: [ ...ALL_ALIGNMENTS, '' ],
			},
		};
	}

	return settings;
}

export const withToolbarControls = createHigherOrderComponent(
	( BlockEdit ) => ( props ) => {
		const blockEdit = <BlockEdit key="edit" { ...props } />;

		return (
			<>
				<BlockControls group="block" __experimentalShareWithChildBlocks>
					<BlockAlignmentControl
						value={ props.attributes.align }
						onChange={ ( nextAlign ) =>
							props.setAttributes( { align: nextAlign } )
						}
					/>
				</BlockControls>
				{ blockEdit }
			</>
		);
	},
	'withToolbarControls'
);

export const withDataAlign = createHigherOrderComponent(
	( BlockListBlock ) => ( props ) => {
		const { attributes } = props;
		const { align } = attributes;

		// If an alignment is not assigned, there's no need to go through the
		// effort to validate or assign its value.
		if ( align === undefined ) {
			return <BlockListBlock { ...props } />;
		}

		let wrapperProps = props.wrapperProps;
		wrapperProps = { ...wrapperProps, 'data-align': align };

		return <BlockListBlock { ...props } wrapperProps={ wrapperProps } />;
	},
	'withDataAlign'
);

export function addAssignedAlign( props, blockType, attributes ) {
	const { align } = attributes;

	props.className = classnames( `align${ align }`, props.className );

	return props;
}

addFilter(
	'blocks.registerBlockType',
	'core/align/addAttribute',
	addAttribute
);
addFilter(
	'editor.BlockListBlock',
	'core/editor/align/with-data-align',
	withDataAlign
);
addFilter(
	'editor.BlockEdit',
	'core/editor/align/with-toolbar-controls',
	withToolbarControls
);
addFilter(
	'blocks.getSaveContent.extraProps',
	'core/align/addAssignedAlign',
	addAssignedAlign
);

Proposal

The new first-class API will shift the implementation burden to the Block Editor, reducing the complexity for developers.

Design in #48809

registerBlockSupport( 'align', {
	blockSettings: {
		attributes: {
			align: { type: 'string' },
		},
	},
	Controls( props ) {
		return (
			<BlockControls group="block" __experimentalShareWithChildBlocks>
				<BlockAlignmentControl
					value={ props.attributes.align }
					onChange={ ( nextAlign ) =>
						props.setAttributes( { align: nextAlign } )
					}
				/>
			</BlockControls>
		);
	},
	useBlockProps( attributes ) {
		const { align } = attributes;
		return { 'data-align': align };
	},
	getSaveProps( attributes ) {
		const { align } = attributes;
		return {
			className: `align${ align }`,
		};
	},
} );

A support key based registrar; doesn't require a separate isSupported check. The new settings object is merged into the block type definition.

The API is easy to use but lacks flexibility. e.g., Some block support features must consider multiple support keys before rendering UI.

Proposed Design

/**
 * @typedef {Object} WPBlockSupport
 *
 * @property {Function}    isSupported   Whether the block type supports the feature.
 * @property {Function}    blockSettings Updates block type settings.
 * @property {WPComponent} EditControls  Renders the controls when editing a block that supports the feature.
 * @property {Function}    useBlockProps Returns updated props are applied to the block's primary node in the editor.
 * @property {Function}    getSaveProps  Returns updated props applied to the block's primary node when serializing.
 */

/**
 * Registers a new block supports feature provided a unique name and an object defining its behavior.
 *
 * @param {string}         name     A string identifying the block support feature.
 * @param {WPBlockSupport} settings A block support settings.
 */
registerBlockSupport( 'core/align', {
	isSupported( blockType ) {
		return hasBlockSupport( blockType, 'align' );
	},
	blockSettings( settings ) {
		if ( 'type' in ( settings.attributes?.align ?? {} ) ) {
			return settings;
		}

		settings.attributes = {
			...settings.attributes,
			align: {
				type: 'string',
				enum: [ ...ALL_ALIGNMENTS, '' ],
			},
		};

		return settings;
	},
	EditControls( props ) {
		return (
			<BlockControls group="block" __experimentalShareWithChildBlocks>
				<BlockAlignmentControl
					value={ props.attributes.align }
					onChange={ ( nextAlign ) =>
						props.setAttributes( { align: nextAlign } )
					}
				/>
			</BlockControls>
		);
	},
	useBlockProps( { attributes, blockType } ) {
		const { align } = attributes;
		return { 'data-align': align };
	},
	getSaveProps( { attributes, blockType } ) {
		const { align } = attributes;
		return {
			className: `align${ align }`,
		};
	},
} );

This results from "migrating" current block support implementations to the proposed API. It builds on the initial design but uses functions to determine block support and update block settings, as they seem more flexible.

In the future, we could potentially offer "shortcut" options for both isSupported and blockSettings.

Unresolved questions

• Should new API support adding inline styles and SVGs to the editor? See Block editor: new blockEditor.useBlockProps filter #48884
• Some features change the block transformation logic. Should we consider supporting it on the API level?

cc @WordPress/gutenberg-core, @aaronrobertshaw, @andrewserong

[nerrad]

isSupported( blockType ) {
		return hasBlockSupport( blockType, 'align' );
	},

This still seems like something that could be absorbed internally?

[Mamaduka]

Of course, that's what I meant in offering a "shortcut" option for isSupported.

[youknowriad]

We discussed this previously with @ellatrix and @gziolo

I think there's a lot of value in such proposal but I have my doubts. Especially around the "UI" part. A lot of these block supports are grouped together in panels... and it's unclear whether separate registration is a good thing here.

That said, I believe this is one of those proposals that can only be "validated"/"approved" if actually tried. I believe we should explore this for the existing "core" block supports as a private API before releasing any official API.

I also believe that ideally, this API shouldn't be relying on "filters" like we do now in block supports but instead it should be baked in into the block editor components...

[Mamaduka]

I also believe that ideally, this API shouldn't be relying on "filters" like we do now in block supports but instead it should be baked in into the block editor components...

100%. The new API should be integrated directly into the block editor. Should I clarify this in the proposal?

[fabiankaegy]

For a while now we have a similar though much less powerful API called registerBlockExtension in our 10up Block Components Library.

It really cuts down on the amount of error-prone boilerplate code you have to write for these extensions.

I also really like the idea of the additional filter which doesn't cause re-renders of the full BlockEdit component but instead only allows additional SlotFills like BlockControls and InspectorControls to be rendered.

Something that we've found to be an issue which I think core could solve better that an external library ever could is providing a similar API for the PHP side. Whenever we register additional attributes for blocks we also need to register them server side. And any new attributes that we try to add to the block props / save element won't affect dynamic blocks. So we always have to duplicate this logic on the server as well. (Here is the example of the align block support: https://github.com/WordPress/wordpress-develop/blob/trunk/src/wp-includes/block-supports/align.php)

[fabiankaegy]

(For our usecase where we are trying to extend other blocks with custom functionality we also try to avoid adding anything to the save element and instead rely on purely adding the additional attributes in the editor via JS and then using the HTML API with the render_block filter to add the additional attributes to the markup of the block dynamically.)

[Mamaduka]

The new registerBlockSupport will complement the WP_Block_Supports::register method, but you still have to use the latter API for dynamic blocks.

[draganescu]

I think this is a good devex improvement, hunting down all the filters is harder and even documenting a how to is a lot more intricate compared to the proposal here. Does this take anything away from what filters offer in terms of flexibility?

[gziolo]

I'm sure that filters are there to stay for backward compatibility, so folks will have a choice depending on what their use case is. We should learn over time how to evolve the API so the need for using hooks becomes less relevant.

[Mamaduka]

It depends on what you mean by flexibility.

Some filters allow you to override the whole component, like BlockEdit. You won't be able to do that with the API because that's not the goal here. If you still want to do that, use the filters.

The API will allow devs to update block attribute definition, add props to block node(s) and render custom controls.

[gaambo]

This looks great. It would make registering core block supports simpler but also gives 3rd party developers an easy way to provide new block supports (eg for things that may never make it into core). Parity with PHP api is definately interesting. But this looks really good to me 👍

[tellthemachines]

Thanks for taking the time to write this up @Mamaduka ! To clarify, is the main goal of this proposal to improve editor performance (and developer experience) or is there intention to provide a public API so extenders can add custom tooling to the editor?

Also, would the current PHP implementation be unchanged, using WP_Block_Supports::get_instance()->register as well as the render_block filters?

[Mamaduka]

To clarify, is the main goal of this proposal to improve editor performance (and developer experience) or is there intention to provide a public API so extenders can add custom tooling to the editor?

Eventually, both. The API would be private while migrating "core" supports features and exploring its limitations. Then, if/when folks are pleased with the results, we can make it public.

There's no plan to change the WP_Block_Supports PHP implementation (at the moment). However, I hope we'll better understand what's missing as we finalize the client-side API.

[dmsnell]

@Mamaduka there's an inherent value in separating some of the UI work from the Edit function. still, when I squint at the before/after code, registerBlockSupport doesn't look that much different from the chain of addFilter calls in the example.

Makes me wonder if this is more or less a sign that we got some of the filter interfaces wrong, but the general filter concepts right. For example, useBlockProps could somehow use a single filter that operates on the props and not on the Edit function.

Don't have many thoughts on this; it's hard to evaluate the context and reach of the changes, and I wonder how much this changes things vs. just moves them around a bit. Will continue to stew on it; thanks for the proposal!

[widoz]

This looks very promising. I've often found my self with the impossibility to reuse the block supports due too the closed way of handling the attributes, the rendering of the controls and the way the data is persisted. Would this allow developers to step into and modify every part of the implementation if not even rewrite it from scratch?

[gziolo]

@Mamaduka, this proposal received a ton of valuable feedback. Do you think we have enough insights to convert it into something actionable?

[Mamaduka]

I do. I plan to start working on implementation as soon as I finish with items that need to ship with WP 6.4.

Meanwhile, I think it would be good if we could land this improvement #52888.

[ramonjd]

Very interesting, thanks for proposing!

Where would you think block.json configurations might be considered, e.g., skipSerialization (example in border hook) - in the EditControls method? Could we back that into the API somehow? I'm just thinking aloud, so sorry if it's already obvious.

Also we could get the rendered styles via another method or in the background somehow (example border hook) - I'm happy to help massage the style engine if necessary. 🙇🏻

[ellatrix]

The last remaining PR regarding the portals is merged (Block styles: remove __unstableElementContext in favour of useStyleOverride), so we're in a good spot now to attempt this.

[gziolo]

More work is happening toward establishing a new public API:

• One hook to rule them all: preparation for a block supports API #56862
• Block editor: hooks: manage BlockListBlock filters in one place #56875