WP 5.7 Dev Notes

[noisysocks]

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

Here are all the PRs that need a Dev Note to be written. 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 your PR. The notes should be posted before WP 5.7 RC (Feb 23), but the sooner, the better.

@jasmussen

• [x] Try: Make empty paragraphs take up the same space on the frontend, as in the editor #27995

@ajlende

• [x] Add srcset for cover image #25171

@ntsekouras

• [x] Display Block Information by matching block variations #27469
• [x] Change replaceInnerBlocks updateSelection property to false #26312

@youknowriad

• [x] Remove autoFocus prop from URLInput and from the inserter search form #27578

@gziolo

• [x] Data: Use store defintion as param for select and dispatch #26655, @wordpress/data-no-store-string-literals #28726

@ZebulanStanphill

• [x] Buttons block: overhaul alignment/justification controls #23168

@leewillis77

• [x] Make i18n functions filter their return values #27966

@nosolosw

• [x] Block supports for style properties added since 5.6. This is so themes have a heads-up on styles that users can now tweak.

[ntsekouras]

Dev note for: Change replaceInnerBlocks updateSelection property to false #26312

Inner Blocks API Changes

We noticed that the majority of block authors prefer to keep the focus on the parent block upon insertion in the editor rather than move it to one of the child blocks. Prior to the changes introduced the default behavior was the latter, so we decided to change it to follow the more popular choice that is going to simplify API usage. To accomplish that we had to change the definition of the following parts of API:

• InnerBlock component
• useInnerBlocksProps hook
• replaceInnerBlocks action

InnerBlock component and useInnerBlocksProps hook

Both handle the focus on the blocks with templateInsertUpdatesSelection property. If you want to keep the focus on the parent you can omit this property.

If you want to move the focus to the first child block you have to set this property to true. Examples:

<InnerBlocks template={ [ [ 'core/heading' ] ] } templateInsertUpdatesSelection />

const innerBlocksProps = useInnerBlocksProps(
    { className: 'wp-block-cover__inner-container' },
    {
        template: [ [ 'core/heading' ] ],
        templateInsertUpdatesSelection: true,
    }
);

replaceInnerBlocks action

Reference: https://developer.wordpress.org/block-editor/data/data-core-block-editor/#replaceInnerBlocks

This action handles focus with the third argument updateSelection. If you want to keep the focus on the parent you can skip this argument when calling replaceInnerBlocks.

If you want to move the focus to the first child block you have to pass this argument with true value. Examples:

replaceInnerBlocks( rootClientId, blocks, true )

[jasmussen]

Dev note for #27995, Make empty paragraphs take up the same space on the frontend, as in the editor

Empty paragraph changes

In 27995 the default behavior of a published empty paragraph (<p></p>) changed. Before, the tag would collapse to zero width and zero height, and be inconsistent with what users saw in the editor. Now an invisible space character is output in empty paragraphs, ensuring linebreaks in the editor correspond to linebreaks on the frontend. There is a chance of empty paragraphs accidentally published, which will now take up space. If that is the case, it is easily fixed by deleting the empty paragraphs.

[scruffian]

Comment by @nosolosw This has been surpassed by this other note below.

---

Dev note for Verse Block: Add support for Font Size #27735 and Code block: Add support for font sizes #27294

Code and Verse Blocks The Code and Verse Blocks now support custom font sizes. These can be customized by users on a per block basis using the inspector panel. Themes can also specify a default font size for these blocks using experimental-theme.json.

[ntsekouras]

Dev note for: Display Block Information by matching block variations #27469

With the new hook useBlockDisplayInformation you can now get some of the block's information, taking into account a matching block variation.

useBlockDisplayInformation is a hook that tries to find a matching block variation and returns the appropriate information for display reasons. The returned information are the block's title, icon and description.

In order to to try to find a match we need to things:

1. Block's client id to extract it's current attributes.
2. A block variation should have set isActive prop to a proper function.

If for any reason a block variation match cannot be found, the returned information come from the Block Type. If no blockType is found with the provided clientId, returns null.

Example usage:

import { useBlockDisplayInformation, BlockIcon } from '@wordpress/block-editor';
function myBlockInformation( clientId ) {
    const blockInformation = useBlockDisplayInformation( clientId );
    if ( ! blockInformation ) return null;
    const { title, icon, description } = blockInformation;
    return (
        <div>
            <BlockIcon icon={ icon } />
            <h2 className="block-title">{ title }</h2>
            <p>{ description }</p>
        </div>
    );
}

You can match a created block with one of its block variations by using the isActive new property in Block Variations API.

This can be useful for cases you want to use information from the block variation, after a block's creation. For example this API is used in useBlockDisplayInformation hook to fetch and display proper information on places like the BlockCard or Breadcrumbs.

Block Variation's settings can include the new property isActive. This optional property is a function that is used to find a block variation match from a created Block, by providing its attributes and a block variation attributes.

We need this function to be explicitly implemented by block/plugin authors, because in many cases it doesn't make sense to try to find a match by checking dynamically all block properties. An example is embed block where we might have changed the responsive attribute, so a match would not be found.

Example in a single block variation:

const variations = [
    {
        name: 'wordpress',
        title: 'WordPress',
        keywords: [ __( 'post' ), __( 'blog' ) ],
        description: __( 'Embed a WordPress post.' ),
        attributes: { providerNameSlug: 'wordpress' },
        isActive: ( blockAttributes, variationAttributes ) =>
            blockAttributes.providerNameSlug ===
            variationAttributes.providerNameSlug,
    },
];

Example when all variations use the same matching function:

const variations = [
    {
        name: 'twitter',
        title: 'Twitter',
        icon: embedTwitterIcon,
        keywords: [ 'tweet', __( 'social' ) ],
        description: __( 'Embed a tweet.' ),
        patterns: [ /^https?:\/\/(www\.)?twitter\.com\/.+/i ],
        attributes: { providerNameSlug: 'twitter', responsive: true },
    },
    {
        name: 'wordpress',
        title: 'WordPress',
        icon: embedWordPressIcon,
        keywords: [ __( 'post' ), __( 'blog' ) ],
        description: __( 'Embed a WordPress post.' ),
        attributes: { providerNameSlug: 'wordpress' },
    },
];

variations.forEach( ( variation ) => {
    if ( variation.isActive ) return;
    variation.isActive = ( blockAttributes, variationAttributes ) =>
        blockAttributes.providerNameSlug ===
        variationAttributes.providerNameSlug;
} );
export default variations;

[ajlende]

Dev note for: Add srcset for cover image #25171

Cover Block

The cover block now uses an img element instead of using CSS background-image for images that are not using fixed or repeated backgrounds. This means that, when rendering the post, a srcset attribute will be applied with the various generated image sizes, saving bandwidth by loading smaller images when possible.

[aaronrobertshaw]

Edited by @nosolosw : this shouldn't be part of the dev notes, see this comment.

---

Dev note for: Block Support: Add border radius support https://github.com/WordPress/gutenberg/pull/25791

Border Radius Support

The ability to manage a border radius style property for blocks has been added. This support is disabled by default however it can be opted into and themes can specify default border radii using experimental-theme.json.

Opting In

An individual block can opt in by setting the __experimentalBorder.radius property to true within its support configuration:

{
    ...
    "supports": {
        "__experimentalBorder": {
            "radius": true
        }
    }
}

Default Border Radius Styles

Themes can apply a default border radius for desired block contexts via experimental-theme.json:

{
    "settings": { ... },
    "styles": {
        "core/group": {
            "border": {
                "radius": "50px"
            }
        }
    }
}

Sidebar Controls

The inspector control to manage border radius values is disabled by default while the sidebar is being refined. It can still be turned on by updating the appropriate context within experimental-theme.json. For example:

{
    "settings": {
        "core/group": {
            "border": {
                "customRadius": true
            }
        }
    }
}

[gziolo]

An individual block can opt in by setting the __experimentalBorder.radius property to true within its support configuration:

The inspector control to manage border radius values is disabled by default while the sidebar is being refined. It can still be turned on by updating the appropriate context within experimental-theme.json. For example:

I don't think this is ready for prime time if it is behind the experimental flags. @nosolosw should have a better overview of where the Global Styles project is, but I don't think this is going to be possible to use this Border Radius Support in WP 5.7.

[leewillis77]

There's documentation here which can be used (as-is, or with minor tweaks) as a dev note for "Make i18n functions filter their return values #27966". I don't have the ability to create make/core posts AFAIK, but happy to write the words if any changes are required to the content as-is

https://github.com/leewillis77/gutenberg/blob/add/i18n-filter-docs/docs/designers-developers/developers/filters/i18n-filters.md

[oandregal]

@gziolo is correct here: the border radius is still experimental (as other properties we added in this cycle such as font height, etc). I'm going to remove it from the issue description.

It was me who tagged that PR with "needs dev note", though. @aaronrobertshaw I'm sorry that I made you write this note down! The good news is that we can reuse that text for when it's marked as stable.

[oandregal]

I've reviewed the existing dev notes and it looks like the ones for the code and verse block shouldn't be listed either: these are not dev-facing features (don't add, update, remove any API) but user-facing ones. Again, it was me who tagged those PRs ― it seems I've been misusing the "need dev note". Sorry about that. Hopefully, I've learned how to use it in the future! Going to delete them from the issue description.

[leewillis77]

Apologies, but I don't think the existing documentation is actually sufficient for "Make i18n functions filter their return values #27966" - there is another API change that should go in the dev note. I'll collate everything today and post here when ready!

[leewillis77]

Dev note for #27966 is here, which includes a note about the changes to instantiation of i18n instances: https://gist.github.com/leewillis77/088c47a89d3319d45f93a7a3b9774ba3

[noisysocks]

Thanks for getting in early everyone! Friendly* reminder that the due date for dev notes is 23 Feb. Ping me if you need help or can't do it.

^{* read: passive aggressive}

[adamziel]

The PR I was asked to write a note on was later reverted: https://github.com/WordPress/gutenberg/pull/26828 – you may safely cross it off the list :-)

[leewillis77]

I've had a second pair of eyes over the dev note for #27966 and it's updated based on feedback here: https://gist.github.com/leewillis77/088c47a89d3319d45f93a7a3b9774ba3

I don't have the ability to post on make core though so someone else would have to actually post it...

[noisysocks]

I don't have the ability to post on make core though so someone else would have to actually post it...

No worries I can handle that.

[kevin940726]

Dev note for: Add widget id to blocks in the widgets screen #28379

cloneBlock now only clones the attributes that are specified in the block types, follows the same logic as in createBlock.

[gziolo]

Dev note for Data: Use store definition to reference registered stored when using @wordpress/data API #26655

Changes in @wordpress/data API

As of #26655, it is now possible to pass a store definition instead of the string when referencing a given store registered with @wordpress/data API. This change impacts mostly the Gutenberg project. It is fully backward compatible, so plugin and theme authors can continue using hardcoded names when referencing data stores.

The store registration has now two new methods register that takes the store definition as a param to register a store. There is also a new helper method createReduxStore that creates a data store definition for the provided Redux store options containing properties describing reducer, actions, selectors, controls, and resolvers.

Example of the store usage before this change:

registerStore( 'my-store', {
    reducer: ( state = 'OK' ) => state,
    selectors: {
        getValue: ( state ) => state,
    },
} );

import { select } from '@wordpress/data';

const blockTypes = select( 'my-store' ).getBlockTypes();

Example of the new recommended usage:

import { createReduxStore } from '@wordpress/data';

export const store = createReduxStore( 'my-store', {
    reducer: ( state = 'OK' ) => state,
    selectors: {
        getValue: ( state ) => state,
    },
} );

register( store ); 

import { select } from '@wordpress/data';
import { store as myStore } from './store';

const blockTypes = select( myStore ). getValue();

This new capability enables additional static analysis in the Gutenberg project that improve code quality. We can ensure now that all stores used in a given module are always properly defined as dependencies. In effect, it provides the correct loading order of JavaScript files. It also opens possibilities for new store implementations that share the same high-level API.

Finally, there is a new optional ESLint rule @wordpress/data-no-store-string-literals available in @wordpress/eslint-plugin package. It ensures that string literals aren't used for accessing @wordpress/data stores when using API methods. The store definition is promoted as the preferred way of referencing registered stores.

[oandregal]

Dev note for: Block supports for style properties added since 5.6. This is so themes have a heads-up on styles that users can now tweak.

Following the initial work done for WordPress 5.6 to automatically support style properties for blocks and expose UI controls for users, in WordPress 5.7 this mechanism has been expanded to new blocks. Themes may want to review if their styles need to adjust their specificity to accommodate the user choices.

User have now the ability to update the font size of the following blocks via the inspector panel: core/code, core/list, core/preformatted, core/verse.

[youknowriad]

URLInput component

In previous versions the URLInput component available on the @wordpress/components package and script had the autoFocus prop set to true by default. The main reason for this was that the component was used as the first input in different modals/popovers (link, inserter) but most third-party usage had to explicitly disable that behavior (in blocks for instance). In WordPress 5.6, that prop is false by default. It's a better choice for most use-cases as auto-focus is often an accessibility bug, but consider checking your components if you previously relied on this behavior.

[ZebulanStanphill]

@youknowriad I spotted a little typo:

...if you previously relied no this behavior.

[talldan]

Dev note for: Buttons block: overhaul alignment/justification controls #23168

Changes to the Buttons block's alignment options

The buttons block now provides justification options for its inner button blocks (Justify items left, Justify items center, Justify items right, Space between items).

To implement this feature, the block's <div> element is now a flexbox container (display: flex)—previously it was display: block. It's recommended that theme developers check that the buttons block still displays correctly for users for the various alignment and justification options it now provides.

The left and right alignment options for the buttons block have now been deprecated. Users can achieve the same results using a combination of a full alignment and left or right justification. Any buttons blocks that were already added to posts with left and right alignment will be migrated (via the block deprecation system) to use justification in this way when a post is loaded—users should see no change in the visual appearance of buttons.

[noisysocks]

Thanks everyone!

[ZebulanStanphill]

I'd tweak the dev note to be a bit clearer:

The Buttons block now provides justification options for its inner button blocks (Justify items left, Justify items center, Justify items right, Space between items).

To implement this feature, the block's <div> element is now a flexbox container (display: flex)—previously it was display: block. It's recommended that theme developers check that the buttons block still displays correctly for users for the various alignment and justification options it now provides.

The left, right, and center block alignment options for the buttons block have now been deprecated. The center option was deemed redundant with the introduction of the "Justify items center" option, and the left and right options (which applied display: float styling) were considered confusing since most users expected them to behave like the new left and right item justification controls.

Users can achieve the same results as the center block alignment option by using the "Justify items center" option, and they can recreate the wrapping/float behavior of the left and right block alignment options by wrapping the Buttons block in a Group block and using its block alignment controls.

Since the wrapping behavior was unexpected and out of place for most use cases of the block, any Buttons blocks that were already added to posts using left, right, or center alignment will be migrated (via the block deprecation system) to use the corresponding justification options when a post is loaded in the editor—Buttons on the front-end will continue to appear as they did until their containing post is edited and updated.