Block Editor Dev Notes 5.4

[jorgefilipecosta]

For this release, the block editor had around 32 PR's needing a dev note. Writing 32 posts with dev notes would not be something viable as we would reduce the probability of the developers reading the post, so we should try to reduce the number of posts.
I checked all these PR's and tried to group the dev notes in a set of posts.

So what I propose is to group the dev notes in 7 posts:

• Block Updates
• New Block API's
• General API Updates
• Markup and Style related changes
• IconButton and Button Components Changes
• Keyboard Shortcuts Package
• Developer Experience Notes

If needed and one of the posts becomes too big, we may consider a further division.

For each of these dev note posts, I list the PR's the dev note will include. I cc people involved in the PR. The process we will try to follow is the persons involved in the PR write the dev note for the PR, taking into account the context of the post that the dev note will be part of, and share the content as a comment of this issue so that everyone could see.

If there is any feedback on this process or any suggestion for changes in the structure of dev notes, please leave a comment. If you are not able to write a dev note for a PR, you are involved please also leave a comment, so we adjust the planning.

Thank you in advance for the help in writing the dev notes together.

Block Updates

Add: Buttons block

#17352

• cc: @jorgefilipecosta
• Done

Add: Social Link Block

#16897

#19887

• cc: @mkaz, @mcsf
• Done

New Block API's

Promote block variations to stable API

#20068

• cc: @gziolo
• Done

Add block collections

#17609

• cc: @scruffian, @gziolo
• Done

General API Updates

Editor: Implement EntityProvider and use it to refactor custom sources with a backward compatibility hook for meta sources.

#17153

• cc: @epiqueras
• Done

Make the AsyncModeProvider API a stable API

#18154

• cc: @youknowriad
• In progress
• Done

Make the mediaUpload block editor setting a stable API

#18156

• cc: @youknowriad
• Done

Transforms: Shortcode: Support isMatch predicate

#18459

• cc: @mcsf
• Done

Drop zone: rewrite with hooks (useDropZone)

#19514

• cc: @ellatrix
• Done

RichText: don't set focus when applying format

#19536

• cc: @ellatrix
• Done

Deprecated Nux Package and Introduce Welcome Modal

#18041

• cc: @noisysocks
• Done

Stabilize gradient theme API's

#20107

• cc: @jorgefilipecosta
• Done

Markup and Style related changes

RichText: remove wrapper (and use Popover for inline toolbar)

#17607

• cc: @ellatrix
• Done

Try: Remove/refactor complex left/right block margins

#17877

• cc: @jasmussen
• Done

Fix the snackbar notices position

#18683

• cc: @youknowriad
• Done

Lighter block DOM: remove extra div wrapper

#19010

• cc: @ellatrix
• Done

Block Editor: Remove legacy "editor-" class name compatibility

#19050

• cc: @aduth
• Done

Block: remove inner div wrapper

#19593

• cc: @ellatrix
• Done

IconButton and Button Components Changes

• Update buttons and icons buttons size and consistency -Update buttons and icons buttons size and consistency #19058

• Merge the Button and IconButton into a single component- Merge the Button and IconButton into a single component #19193

• Deprecate IconButton and replace its usage with Button - Deprecate IconButton and replace its usage with Button #19299

• Remove components-icon-button classname - Remove components-icon-button classname #19241

• cc: @youknowriad

• Done

Keyboard Shortcuts Package

Add a new keyboard shortcut package

#19100

• cc: @youknowriad
• Done

Developer Experience Notes

Packages: New create-block package for block scaffolding

#19773

• cc: @gziolo
• Done

Add .wp-env.json support to wp-env

#20002

• cc: @noisysocks
• Done

[audrasjb]

Looks great, thanks!
Feel free to ping me on Slack if you need help/copy review or anything, as I'm in charge of WP 5.4 Documentation 😃

[scruffian]

Add block collections

Blocks are only allowed to appear in one category in the block inserter. As a consequence many developers create a new category to add their own blocks. Block collections allow you to define an additional group of blocks to appear in the block inserter; collections are like a categories, except that blocks can have both a category and a collection. This means that blocks can now appear twice in the inserter; once in their collection and once in their most appropriate category.

[aduth]

Block Editor: Remove legacy "editor-" class name compatibility

Note:

As part of the changes included in WordPress 5.2, the CSS class names assigned to many components in the block editor were updated to align with the introduction of a new block editor module. Many editor--prefixed class names were updated to use block-editor- instead. The old class names were still applied, and it was recommended that developers avoid those references or update them accordingly. In WordPress 5.4, these old editor--prefixed class names will no longer be applied to components within the block-editor scripts. If you are still referencing the editor--prefixed CSS class name of a component mentioned in the WordPress 5.2 Block Editor devnote, these must be updated to the block-editor- equivalent.

It might also be good to incorporate something here to remind about CSS classes not being part of the public API:

https://github.com/WordPress/gutenberg/blob/master/docs/designers-developers/developers/backward-compatibility/README.md#class-names-and-dom-updates

[epiqueras]

Editor: Implement EntityProvider and use it to refactor custom sources with a backward compatibility hook for meta sources.

Meta attribute sources were deprecated now that the new EntityProvider and related hooks APIs provide a more flexible and powerful way for building blocks that source data from different properties of WordPress entities and data.

[jorgefilipecosta]

New buttons block, button block is hidden.

There are several situations where multiple buttons are needed. In WordPress 5.4, a new "buttons" block is introduced. The "buttons" block is a collection of buttons; each button is represented as an individual "button" block child of the "buttons" block. The button block that existed before is not removed in fact; buttons block uses it. It will not be possible to insert a "button" block outside buttons, but all existing "button" blocks will work exactly as before.

[jorgefilipecosta]

New gradient theme API's

The ability to use gradients as background in some blocks (cover and buttons) in the block editor is introduced in WordPress 5.4.
In order to allow themes to have control of what gradients are available by default and to enable/disable to the ability to create custom gradients, some new theme APIs are included following the same ideas of the colors and fonts API.

Configure the predefined set of gradients

In order to configure the predefined set of gradients themes can use the theme support option editor-gradient-presets and pass an array representing the gradient set:

add_theme_support(
	'editor-gradient-presets',
	array(
		array(
			'name'     => __( 'Vivid cyan blue to vivid purple', 'themeLangDomain' ),
			'gradient' => 'linear-gradient(135deg,rgba(6,147,227,1) 0%,rgb(155,81,224) 100%)',
			'slug'     => 'vivid-cyan-blue-to-vivid-purple'
		),
		array(
			'name'     => __( 'Vivid green cyan to vivid cyan blue', 'themeLangDomain' ),
			'gradient' => 'linear-gradient(135deg,rgba(0,208,132,1) 0%,rgba(6,147,227,1) 100%)',
			'slug'     =>  'vivid-green-cyan-to-vivid-cyan-blue',
		),
		array(
			'name'     => __( 'Light green cyan to vivid green cyan', 'themeLangDomain' ),
			'gradient' => 'linear-gradient(135deg,rgb(122,220,180) 0%,rgb(0,208,130) 100%)',
			'slug'     => 'light-green-cyan-to-vivid-green-cyan',
		),
		array(
			'name'     => __( 'Luminous vivid amber to luminous vivid orange', 'themeLangDomain' ),
			'gradient' => 'linear-gradient(135deg,rgba(252,185,0,1) 0%,rgba(255,105,0,1) 100%)',
			'slug'     => 'luminous-vivid-amber-to-luminous-vivid-orange',
		),
		array(
			'name'     => __( 'Luminous vivid orange to vivid red', 'themeLangDomain' ),
			'gradient' => 'linear-gradient(135deg,rgba(255,105,0,1) 0%,rgb(207,46,46) 100%)',
			'slug'     => 'luminous-vivid-orange-to-vivid-red',
		),
	)
);

More details available at https://developer.wordpress.org/block-editor/developers/themes/theme-support/#block-gradient-presets.

Disable custom gradients

Themes can disable the ability to set a custom gradient with the following code:

add_theme_support( 'disable-custom-gradients' );

When set, users will be restricted to the default gradients provided in the block editor or the gradients provided via the editor-gradient-presets theme support setting.

More details available at https://developer.wordpress.org/block-editor/developers/themes/theme-support/#disabling-custom-gradients.

Disable gradient functionality

Using the previous referred API's it is possible to totally disable the gradient functionality using the following two calls together:

add_theme_support( 'disable-custom-gradients' );
add_theme_support( 'editor-gradient-presets', array() );

[noahtallen]

@jorgefilipecosta I would recommend not having a note for this item since it could introduce confusion between #18121 and #20002 (the latter is the one available to users).

Add config file support to @wordpress/env (#18121)

Its implementation was superseded by "Add .wp-env.json support to wp-env" (#20002). Both accomplish the same thing (adding a configuration file to specify options for the env command), but #20002 accomplishes it in a more robust way. Any instructions for #18121 are obsolete in favor of #20002.

[noisysocks]

Deprecated Nux Package and Introduce Welcome Modal

New Guide component

A new Guide component was added to the @wordpress/components package (wp.components.Guide). Guide allows developers to easily create a step-by-step guide to display to users. The block editor uses Guide to implement a new welcome modal which appears on first launch.

Guide is a React component that renders a user guide in a modal. The guide consists of several GuidePage components which the user can step through one by one. The guide is finished when the modal is closed or when the user clicks Finish on the last page of the guide.

function MyTutorial() {
	const [ isOpen, setIsOpen ] = useState( true );

	if ( ! isOpen ) {
		return null;
	}

	<Guide onFinish={ () => setIsOpen( false ) }>
		<GuidePage>
			<p>Welcome to the ACME Store! Select a category to begin browsing our wares.</p>
		</GuidePage>
		<GuidePage>
			<p>When you find something you love, click <i>Add to Cart</i> to add the product to your shopping cart.</p>
		</GuidePage>
	</Guide>
}

You can find documentation for this component on its Block Editor Handbook page.

Deprecation of @wordpress/nux

The @wordpress/nux package (wp.nux) has been deprecated along with the DotTip component that it contained. Importing the package will display a warning in the browser console. It is recommended that plugins using wp.nux and DotTip migrate to Guide instead.

[noisysocks]

Add .wp-env.json support to wp-env

Support for .wp-env.json

For more complex setups, the wp-env tool in @wordpress/env now supports .wp-env.json configuration files. You can customize the WordPress installation, plugins and themes that the development environment will use by creating a .wp-env.json file in the directory that you run wp-env from.

You can find documentation on .wp-env.json in the Block Editor Handbook page for @wordpress/env.

Examples

Latest production WordPress + current directory as a plugin

This is useful for plugin development.

{
  "core": null,
  "plugins": [
    "."
  ]
}

Latest development WordPress + current directory as a plugin

This is useful for plugin development when upstream Core changes need to be tested.

{
  "core": "WordPress/WordPress#master",
  "plugins": [
    "."
  ]
}

Local wordpress-develop + current directory as a plugin

This is useful for working on plugins and WordPress Core at the same time.

{
  "core": "../wordpress-develop/build",
  "plugins": [
    "."
  ]
}

A complete testing environment

This is useful for integration testing: that is, testing how old versions of WordPress and different combinations of plugins and themes impact each other.

{
  "core": "WordPress/WordPress#5.2.0",
  "plugins": [
    "WordPress/wp-lazy-loading",
    "WordPress/classic-editor",
  ],
  "themes": [
    "WordPress/theme-experiments"
  ]
}

Breaking changes to wp-env

As part of the introduction of .wp-env.json, some backwards incompatible changes to the wp-env command line interface have been made:

• wp-env start no longer accepts a WordPress branch or tag reference as its argument. Instead, create a .wp-env.json file and specify a "core" field.
• wp-env start will now download WordPress into a hidden directory located in ~/.wp-env. You may delete your {projectName}-wordpress and {projectName}-tests-wordpress directories.

[ellatrix]

RichText: remove wrapper (and use Popover for inline toolbar)
Lighter block DOM: remove extra div wrapper
Block: remove inner div wrapper

Note:

Blocks and RichText have been refactored to simplify and lighten the React and DOM tree. The key to this refactoring was to move controls out of the block and rich text elements into popovers visually positioned next to it. Moving these controls meant that a lot of div element wrappers became unnecessary, and were therefore removed. Not only did this result in a significant performance improvement, it also means that the editor content DOM resembles the front-end much more closely, making styling blocks much easier for both block and theme authors. Eventually we plan to allow blocks to render exactly the same tree in the editor as on the front-end.

In total, 4 div element wrappers were removed.

The block-editor-rich-text class has moved from the removed rich text wrapper to the editable element, unless you are still using the wrapperClasses prop. This prop should be avoided. Instead, if you really need a wrapper around the editable element, you should create your own wrapper element.

The data-block attribute, containing the block ID, has been moved to the outer block wrapper element. The block-editor-block-list__block-edit class has been removed entirely along with the div element. Selectors like .wp-block > .block-editor-block-list__block-edit > [data-block] will no longer work. You should use .wp-block or just the [data-type] attribute instead.

[ellatrix]

RichText: don't set focus when applying format

Note:

When applying a format to text in a rich text instance, focus will no longer be set back automatically to the editable element. This has been changed to allow more complex UI to interact with rich text instances, e.g. a colour control where we don’t want focus to be set back for every colour change. If you’re registering a format type, and would like to continue to set focus back, for example after a button click, you need to call the onFocus function that is now provided to the edit component.

Example: the bold format button:

gutenberg/packages/format-library/src/bold/index.js

Lines 21 to 53 in c5eb962

	edit( { isActive, value, onChange, onFocus } ) {
	function onToggle() {
	onChange( toggleFormat( value, { type: name } ) );
	}
	function onClick() {
	onToggle();
	onFocus();
	}
	return (
	<>
	<RichTextShortcut
	type="primary"
	character="b"
	onUse={ onToggle }
	/>
	<RichTextToolbarButton
	name="bold"
	icon={ formatBold }
	title={ title }
	onClick={ onClick }
	isActive={ isActive }
	shortcutType="primary"
	shortcutCharacter="b"
	/>
	<__unstableRichTextInputEvent
	inputType="formatBold"
	onInput={ onToggle }
	/>
	</>
	);
	},

[ellatrix]

Drop zone: rewrite with hooks (useDropZone)

Drop zones between blocks have been substantially improved. With this refactor, positioning classes (is-close-to-top, is-close-to-bottom, is-close-to-left and is-close-to-right) have been removed from the element rendered by the DropZone component, since they were only used by the block’s drop zones.

[mkaz]

Social Link Block

Adds a new block for creating links to external social media services in the form of the services icon, matching the proper logo and color. Social Links was introduced in WordPress 5.3 (Gutenberg 6.5) as an experimental feature; changes in WordPress 5.4 (Gutenberg 7.4) switch the implementation to use variations to create a single parent (core/social-links) and a single child block (core/social-link), replacing the experimental implementation that created a child block for each service.

cc: @mcsf (if you have anything to add)

[gziolo]

Packages: New @wordpress/create-block package for block scaffolding

Create Block is an officially supported way to scaffold a block for registering it with a WordPress plugin. It generates PHP, JS, CSS code, and everything else you need to start the project for your plugin. There is a quick start mode provided where you just need to provide the slug which is the target location for scaffolded files and the internal block name:

You don’t need to install or configure tools like webpack, Babel or ESLint yourself. They are preconfigured and hidden so that you can focus on the code.

There is also an Interactive mode that gives a chance to customize a few most important block options before the code gets generated.

$ npm init @wordpress/block

It is also possible to pick ES5 template when you don't want to deal with a modern JavaScript tooling that enables ESNext and JSX support.

[gziolo]

Promote block variations to stable API

@jorgefilipecosta, I'm working on docs for variations API in #20145. I will get back here as soon as I have everything ready.

[gziolo]

Promote block variations to stable API

Similarly to how the block's style variations can be declared when registering a block, a block type can define block variations that the user can pick from. The difference is that, rather than changing only the visual appearance, this field provides a way to apply initial custom attributes and inner blocks at the time when a block is inserted.

By default, all variations will show up in the Inserter in addition to the regular block type item. However, setting the isDefault flag for any of the variations listed will override the regular block type in the Inserter.

variations: [
    {
		name: 'wordpress',
		isDefault: true,
		title: __( 'WordPress' ),
		description: __( 'Code is poetry!' ),
		icon: WordPressIcon,
		attributes: { service: 'wordpress' },
	},
	{
		name: 'google',
		title: __( 'Google' ),
		icon: GoogleIcon,
		attributes: { service: 'google' },
	},
	{
		name: 'twitter',
		title: __( 'Twitter' ),
		icon: TwitterIcon,
		attributes: { service: 'twitter' },
	},
],

An object describing a variation defined for the block type can contain the following fields:

• name (type string) – The unique and machine-readable name.
• title (type string) – A human-readable variation title.
• description (optional, type string) – A detailed variation description.
• icon (optional, type String | Object) – An icon helping to visualize the variation. It can have the same shape as the block type.
• isDefault (optional, type boolean) – Indicates whether the current variation is the default one. Defaults to false.
• attributes (optional, type Object) – Values that override block attributes.
• innerBlocks (optional, type Array[]) – Initial configuration of nested blocks.
• example (optional, type Object) – Example provides structured data for the block preview. You can set to undefined to disable the preview shown for the block type.
• scope (optional, type String[]) - the list of scopes where the variation is applicable. When not provided, it assumes all available scopes. Available options: block, inserter.

---

I still plan to work on tutorials presenting how to register variations for existing blocks.

[mcsf]

Social Link Block

cc: @mcsf (if you have anything to add)

Thanks for the ping. Some notes:

• Both parent and child are now named Social Icon(s), and I think the note should reflect that primary purpose of the blocks.
• Did any part of Social Links make its way to WP 5.3? To my knowledge no, so we might want to clarify that too.
• The switch to block variations should be phrased in terms of what that means for the shape of content and backwards compatibility, as that would be the primary concern for anyone going through these notes.
  • Since Social Icons are dynamic blocks, this includes the server-side support provided in the plugin but not in core.

Suggested revision:

---

Social Icons Block

Adds a new block for creating links to social media sites and other popular websites in the form of recognizable logos. Social Icons, then known as Social Links, were introduced in Gutenberg 6.5 as an experimental feature, but were kept out of core at the time (WordPress 5.3). Since then, the development of the Block Variations API has allowed the simplification and stabilization of Social Icons (Gutenberg 7.5), and as such these will be included in WordPress 5.4.

This reimplementation constitutes a breaking change in the way Social Icons are saved (see details). Only sites that have run the Gutenberg plugin since September are potentially concerned. Any Social Icons blocks created prior to Gutenberg 7.5 will not be recognized by the core block editor in WordPress 5.4. There are two ways to address this:

• Keep the Gutenberg plugin installed after upgrading WordPress 5.4. The plugin will manually provide backwards compatibility for the old Social Icons.
• Manually migrate any content with old Social Icons. This can be done by loading a post in the block editor (Gutenberg 7.5 or higher) and saving the post — the block editor will automatically update its contents. (Recommended method)

---

Thoughts? /cc @mkaz @gziolo

[mcsf]

Shortcode transforms: Support isMatch predicate

In order to bring shortcodes in line with other types of block transformations, an optional isMatch function may now be provided to determine whether a given shortcode should be transformed into a specific block.

For instance, a hypothetical Antarctica Weather block is only interested in [weather] shortcodes that concern Antarctica:

transforms: {
	from: [
		{
			type: 'shortcode',
			tag: 'weather',
			isMatch( { named: { latitude } } ) {
				return parseInt( latitude, 10 ) < -70;
			},
			attributes: {
				latitude: {
					type: 'number',
					shortcode: ( { named: { latitude } } ) =>
						parseInt( latitude, 10 ),
				},
				longitude: {
					type: 'number',
					shortcode: ( { named: { longitude } } ) =>
						parseInt( longitude, 10 ),
				},
			},
		},
	],
},

If isMatch returns false, the shortcode won't be converted into an Antarctica Weather block. At that point, it can be picked up by another block type that matches the [weather] shortcode, or it may be preserved as a shortcode and encapsulated in a Shortcode block.

[gziolo]

@mcsf - I like your dev note for Social Icons a lot. It's all perfectly explained 😍

[scruffian]

Block Collections:

In addition to the above, here is a code sample to get people started:

import { registerBlockCollection } from '@wordpress/blocks';
import { Path, SVG, G } from '@wordpress/components';

registerBlockCollection( 'core', {
	title: 'WordPress.org',
	icon: ( <SVG viewBox="0 0 24 24"><G><Path d="M12.158 12.786l-2.698 7.84c.806.236 1.657.365 2.54.365 1.047 0 2.05-.18 2.986-.51-.024-.037-.046-.078-.065-.123l-2.762-7.57zM3.008 12c0 3.56 2.07 6.634 5.068 8.092L3.788 8.342c-.5 1.117-.78 2.354-.78 3.658zm15.06-.454c0-1.112-.398-1.88-.74-2.48-.456-.74-.883-1.368-.883-2.11 0-.825.627-1.595 1.51-1.595.04 0 .078.006.116.008-1.598-1.464-3.73-2.36-6.07-2.36-3.14 0-5.904 1.613-7.512 4.053.21.008.41.012.58.012.94 0 2.395-.114 2.395-.114.484-.028.54.684.057.74 0 0-.487.058-1.03.086l3.275 9.74 1.968-5.902-1.4-3.838c-.485-.028-.944-.085-.944-.085-.486-.03-.43-.77.056-.742 0 0 1.484.114 2.368.114.94 0 2.397-.114 2.397-.114.486-.028.543.684.058.74 0 0-.488.058-1.03.086l3.25 9.665.897-2.997c.456-1.17.684-2.137.684-2.907zm1.82-3.86c.04.286.06.593.06.924 0 .912-.17 1.938-.683 3.22l-2.746 7.94c2.672-1.558 4.47-4.454 4.47-7.77 0-1.564-.4-3.033-1.1-4.314zM12 22C6.486 22 2 17.514 2 12S6.486 2 12 2s10 4.486 10 10-4.486 10-10 10z"></Path></G></SVG> ),
} );

Here are some screenshots too:

[mcsf]

Here are some screenshots too:

@scruffian, any chance we could get an example with a namespace other than core? I suspect it won't do much to convey the usefulness of collections, since it results in seemingly "all the blocks" being listed in one drawer.

I understand we probably want to remain neutral and not highlight any particular provider of blocks, so maybe a collection of around three fictional blocks revolving around a theme could do the job. For instance, acme-geography/ could include a Map block, a Weather block, and a Coordinates Conversion tool. (Too contrived? 😬)

________________________________________________________________
| Geography 🌍                                                 |
|      _____________     ______________     _______________    |
|     |             |   |              |   |               |   |
|     |      🗺     |   |      ☔️       |   |       📐       |   |
|     |     Map     |   |   Weather    |   |  Coordinates  |   |
|     |_____________|   |______________|   |_______________|   |
|                                                              |
|______________________________________________________________|

[mcsf]

Further, to keep the example focused, I'd look for something in Dashicons, e.g.:

registerBlockCollection( 'core', {
	title: 'WordPress.org',
	icon: 'wordpress',
} );

[mcsf]

I worry that the intents behind Block Collections may be lost in the dev notes, so I drafted this alternative:

Block Collections

Collections allow specific block types to be grouped together for added visibility in the editor’s Inserter menu, regardless of their categories. For instance, a plugin such as CoBlocks may register a Map block of category Widgets and an Accordion block of category Layout. By registering a collection for the coblocks namespace, these blocks will appear in the Inserter under their respective categories, but also grouped under a CoBlocks collection.

The Block Collections API thus aims to improve the relationship of block discovery between users and plugin authors without compromising the semantics of block types, notably around categories (e.g. formatting, layout, widget, embed).

[scruffian]

How's this?

The snippet would be:

	registerBlockCollection( 'geography', {
		title: 'Geography',
		icon: 'admin-site-alt3',
	} );

[youknowriad]

AsyncModeProvider

To improve the typing performance in the editor, the BlockEditor uses an Async Rendering Mode: The selected block gets rerendered synchronously on each change while the unselected blocks are only refreshed when the browser becomes idle (not performing any task).

This behavior is made possible using the Async Mode implemented in the @wordpress/data package. WordPress 5.4 exposes the AsyncModeProvider component that allows you to implement similar behaviors in your own React state trees that rely on the data module. This component can also be used to opt-out of the block async rendering mode.

import { AsyncModeProvider } from '@wordpress/data';
const MyComponent = () => {
  return (
    <>
        The following component updates synchronously on data store changes
        <MySyncComponent />
        <AsyncModeProvider value={ true }>
            The following component updates asynchronously on data store changes
            <MyAsyncComponent />
        </AsyncModeProvider>
    </>
  );
}

For more details about the AsyncMode, you can check this blog post.

---

If we are allowed to link to personal blog posts from dev notes, we could consider linking to this one here https://riad.blog/2020/02/14/a-journey-towards-a-performant-web-editor/

[youknowriad]

Media Upload Block Editor Setting

The @wordpress/block-editor package can be used independently to integrate the block editor pages in custom WPAdmin Pages or any WordPress agnostic context. An example can be found on the Gutenberg Playground. In these situations, WordPress 5.4 allows you to provide a custom media upload handler as a setting to the block editor.

import { BlockEditorProvider } from '@wordpress/block-editor';

/**
 * Media Upload Handler
 *
 * @param   {Object}   $0                   Parameters object passed to the function.
 * @param   {?Object}  $0.additionalData    Additional data to include in the request.
 * @param   {string}   $0.allowedTypes      Array with the types of media that can be uploaded, if unset all types are allowed.
 * @param   {Array}    $0.filesList         List of files.
 * @param   {?number}  $0.maxUploadFileSize Maximum upload size in bytes allowed for the site.
 * @param   {Function} $0.onError           Function called when an error happens.
 * @param   {Function} $0.onFileChange      Function called each time a file or a temporary representation of the file is available.
 */
const myMediaUploadHandler = ( settings ) => {
   const mediaObject = {
      id, alt, caption, title, url,
   };    

    settings.onFileChange([mediaObject]);
}

const MyCustomEditor = () => {
  return (
        <BlockEditorProvider settings={ { mediaUpload: myMediaUploadHandler  } }>
            <MyEditorLayout />
        </AsyncModeProvider>
  );
}

Omitting the mediaUpload handler from your BlockEditor instance means that your editor doesn't support media upload or that the current user doesn't have the right permissions to allow media uploads.

Media Blocks can also have access to this setting in their edit functions in order to support uploads.

const MyBlockEdit = () => {
   const mediaUpload = useSelect( ( select ) => {
      return select( 'core/block-editor' ).getSettings().mediaUpload;
   }, [] );

   return (
      <>
           { !! mediaUpload && <MyMediaUploadComponent onUpload={ mediaUpload } /> }
       </>
   );
   <
}

[mcsf]

In AsyncModeProvider:

<SyncComponent />
<ASyncComponent />

I recommend naming these MySyncComponent and MyAsyncComponent to make it more evident. Notice also the casing at "Async".

In Media Upload Block Editor Setting:

const myMediaUploadHandler = ( settings ) => {
   const result = const mediaObject = {
      id, alt, caption, title, url,
   };    

    settings.onFileChange([result]);
}

There's a leftover const assignment of mediaObject.

[youknowriad]

Thanks :) Fixed

[jorgefilipecosta]

Dev note for "Try: Remove/refactor complex left/right block margins", as provided by @jasmussen in #17877 (comment).

In 17877 a change was made to how blocks are laid out in the block editor. Previously, every block would come with padding built in, left and right, and negative margins to compensate. These margins and paddings have been refactored away. This should drastically simplify the CSS necessary to style blocks, for block developers and for WordPress themers wanting to style the editor.

The refactor may cause issues in existing block or editor styles that have compensated for the previous margins/paddings. If your block or editor style looks off, a likely fix is to remove the styles used to compensat

[ellatrix]

Drop zone: rewrite with hooks (useDropZone)

Drop zones between blocks have been substantially improved. With this refactor, positioning classes (is-close-to-top, is-close-to-bottom, is-close-to-left and is-close-to-right) have been removed from the element rendered by the DropZone component, since they were only used by the block’s drop zones.

The editor.BlockDropZone component filter has been removed (since the block drop zone is no longer a component). The filter was originally added to filter media upload (in this case through drag and drop). If there's enough demand for it, a more appropriate filter could probably be added around media upload itself. Please let us know if you were using this filter and what for.

[jorgefilipecosta]

Closing this issue as the dev notes are published. Thank you all for this effort!