Dev Notes for WP 5.6

[cguntur]

https://github.com/WordPress/gutenberg/issues?q=label%3A%22Needs+Dev+Note%22

These are all the PRs that need Dev Notes to be written for. Please share them here as comments, see what is related, and create make/core posts accordingly. Please let me know if you're unable to write a note for our PR. The notes should be posted before WP 5.6 RC, but the sooner, the better.

@adamziel

• Refactor reusable blocks to not depend on the editor module - Refactor reusable blocks to not depend on the editor module #25853

@youknowriad

• Make the custom spacing theme support flag and block support API stable - Make the custom spacing theme support flag and block support API stable #25788
• Add/line height support flag stable - Add/line height support flag stable #25769
• Mark the font size support flag as stable - Mark the font size support flag as stable #25695
• Mark the color support flag as stable - Mark the color support flag as stable #25694
• Add Custom CSS support to the Group block - Add Custom CSS support to the Group block #25413
• Support custom units on theme.json - Support custom units on theme.json #25217
• Add generated block classname to dynamic blocks - Add generated block classname to dynamic blocks #24546
• Implement the custom classname support hook in the server - Implement the custom classname support hook in the server #24483
• Core Data: Implement _fields data reuse for entities - Core Data: Implement _fields data reuse for entities #19498

@noisysocks

• Widgets editor: Overview of documentation - Add technical documentation #25759

@ellatrix

• Block API: stabilize light block hook - Block API: stabilize light block hook #25642

@aristath

• Convert all px values in front-facing styles to relative (em) units - Convert all px values in front-facing styles to relative (em) units #24523

@jorgefilipecosta

• Fix: Media Text: Always show images on top on mobile - Fix: Media Text: Always show images on top on mobile. #24468

@diegohaz

• Make accessible toolbar stable and deprecate old usage - Make accessible toolbar stable and deprecate old usage #23316

@vindl

• Site Editor: make close button replaceable - Site Editor: make close button replaceable #22001

@ntsekouras

• Transform multiple selected blocks to Columns block Transform multiple selected blocks to Columns block #25829

[nerrad]

Convert _experimentalCreateInterpolateElement to a stable api - #20699

Pretty sure this was done for WordPress 5.5. It shouldn't be needed for the WordPress 5.6 release?

[gziolo]

Block API: Add new utility to register block types from metadata in PHP - #20794

I believe it was released in WordPress 5.5. Was the dev note never published?

I can confirm it was released in WP 5.5, related Dev Note is here: https://make.wordpress.org/core/2020/07/30/block-api-updates-in-5-5/.

[youknowriad]

I think the dev notes for 5.5 here were published but the label from the PRs were not removed.

[jorgefilipecosta]

Dev note for Fix: Media Text: Always show images on top on mobile - #24468.

Media & Text blocks on mobile now always show media on top.

Previously, if the stack on mobile behavior was not disabled, and media had the option to appear on the left (the default), on mobile, the media appeared on top and the text on the bottom. If media had the option to appear on the right on mobile when stacked media would appear at the bottom and text on top.
There was feedback that the left/right position of media should not map to top/bottom on mobile and that for a better UX on mobile, media should always appear on top. Starting with WordPress, 5.6 media text blocks will have media on top on mobile unless the stack on mobile option is disabled, and in that case, media appears at the side of text like on desktop.

[aristath]

Dev note for Convert all px values in front-facing styles to relative (em) units - #24523

Default block styles now use font-size-relative values instead of absolute pixel values.

Previously, blocks were using hardcoded pixel values for all their sizing properties (paddings, margins, font-sizes etc).
Starting with WordPress 5.6, default block-styles use font-size-relative units (em) making it easier for themes to change the default content font-size without having to rewrite/override all block-styles.

[diegohaz]

Dev notes for Make accessible toolbar stable and deprecate old usage - #23316

Toolbar shouldn't be used within other toolbars

To better reflect its semantics, the Toolbar component shouldn't be used to group a set of toolbar controls within another toolbar anymore and will show a deprecation warning if used like so. ToolbarGroup should be used instead.

Before

<BlockControls>
  <Toolbar>
    <ToolbarButton />
  </Toolbar>
</BlockControls>

After

<BlockControls>
  <ToolbarGroup>
    <ToolbarButton />
  </ToolbarGroup>
</BlockControls>

Block toolbars now require controls to be ToolbarButton or ToolbarItem elements

Rendering native <button> or other custom tabbable elements directly as toolbar items (for example, using BlockControls or BlockFormatControls) has been deprecated. In order to improve toolbar accessibility, toolbar items now should use ToolbarButton for regular buttons, or ToolbarItem for any other kind of control (for example, dropdowns).

Before

<BlockControls>
  <button />
  <Button />
  <DropdownMenu />
</BlockControls>

After

<BlockControls>
  <ToolbarItem as="button" />
  <ToolbarButton />
  <ToolbarItem>
    { ( itemProps ) => ( <DropdownMenu toggleProps={ itemProps } /> ) }
  </ToolbarItem>
</BlockControls>

[cguntur]

I didn't realize that few of them were 5.5 related.

Thank you @gziolo for the link.

[youknowriad]

@diegohaz Do you think we can have a before -> after snippet of code?

[diegohaz]

@diegohaz Do you think we can have a before -> after snippet of code?

Updated my comment. Please, let me know if it's clear enough or there's a better example/wording that could be used (the linked documentation on each component provides more detailed information).

[youknowriad]

Thanks Diego, that's perfect.

[adamziel]

Dev notes for Refactor reusable blocks to not depend on the editor module - #25853

Reusable blocks now live in @wordpress/reusable-blocks which makes them... reusable in any block editor

Reusable blocks are an experimental feature available in the post editor. To make them available in other editors, they were moved to a separate package called @wordpress/reusable-blocks. Keep in mind this feature is still experimental and may change. To enable reusable blocks in your block editor, simply change your <BlockEditorProvider /> as follows:

import { ReusableBlocksMenuItems } from '@wordpress/reusable-blocks';

const { __experimentalReusableBlocks } = useSelect(
    ( select ) => select( 'core' ).getEntityRecords(
        'postType',
        'wp_block',
    )
);

return (
    <BlockEditorProvider
        settings={ {
            ...settings,
            __experimentalReusableBlocks,
        } }
        { ...props } // value, onInput, onChange, etc.
    >
        <ReusableBlocksMenuItems />
        { children }
    </BlockEditorProvider>
);

[vindl]

Site Editor: make close button replaceable - #22001

We discussed this for the previous version and determined that it's not needed since it's still experimental.

[noisysocks]

Reusable blocks are an experimental feature available in the post editor.

@adamziel: The feature isn't experimental, just some of the APIs surrounding it 🙂

[ntsekouras]

Dev note for new Block API createBlocksFromInnerBlocksTemplate:#25829

There is a new Block API createBlocksFromInnerBlocksTemplate with which you can create blocks from InnerBlocks template.

Given an array of InnerBlocks templates or Block Objects, it returns an array of created Blocks from them.
It handles the case of having InnerBlocks as Blocks by converting them to the proper format to continue recursively.

This is especially useful for handling block variations, transformations and creation/replacement of blocks which use InnerBlocks template.

An example that would create new blocks from a block variation using InnerBlocks' template and replace the block's content is:

import { InnerBlocks } from '@wordpress/block-editor';
import { useDispatch } from '@wordpress/data';
import { __ } from '@wordpress/i18n';
import { Button, ToolbarGroup, ToolbarButton } from '@wordpress/components';
import { BlockControls, useBlockProps } from '@wordpress/block-editor';
import { createBlocksFromInnerBlocksTemplate } from '@wordpress/blocks';

function MyEditBlock( { clientId } ) {
	const { replaceInnerBlocks } = useDispatch( 'core/block-editor' );
	const variation = {
		name: 'my-variation',
		title: __( 'My variation' ),
		innerBlocks: [
			[ 'core/paragraph', { content: 'Hello' } ],
			[ 'core/paragraph', { placeholder: __( 'Write title…' ) } ],
		],
	};
	const onClick = () => {
		replaceInnerBlocks(
			clientId,
			createBlocksFromInnerBlocksTemplate( variation.innerBlocks )
		);
	};
	return (
		<div { ...useBlockProps() }>
			<BlockControls>
				<ToolbarGroup>
					<ToolbarButton onClick={ onClick }>
						<span>Change InnerBlocks</span>
					</ToolbarButton>
				</ToolbarGroup>
			</BlockControls>
			<InnerBlocks />
		</div>
	);
}