Block API: stabilize light block hook (#25642)

* Block API: stabilize light block hook

* Rename

* Fix typo

* lightBlockWrapper => apiVersion

* 2

* Fix rebase

* typo

* Fix for deprecations

docs/designers-developers/developers/block-api/block-metadata.md

@@ -11,6 +11,7 @@ To register a new block type using metadata that can be shared between codebase
 
 ```json
 {
+	"apiVersion": 2,
 	"name": "my-plugin/notice",
 	"title": "Notice",
 	"category": "text",
@@ -32,7 +33,6 @@ To register a new block type using metadata that can be shared between codebase
 	"usesContext": [ "groupId" ],
 	"supports": {
 		"align": true,
-		"lightBlockWrapper": true
 	},
 	"styles": [
 		{ "name": "default", "label": "Default", "isDefault": true },

packages/block-editor/README.md

@@ -562,6 +562,26 @@ _Related_
 
 Undocumented declaration.
 
+<a name="useBlockProps" href="#useBlockProps">#</a> **useBlockProps**
+
+This hook is used to lightly mark an element as a block element. The element
+should be the outermost element of a block. Call this hook and pass the
+returned props to the element to mark as a block. If you define a ref for the
+element, it is important to pass the ref to this hook, which the hook in turn
+will pass to the component through the props it returns. Optionally, you can
+also pass any other props through this hook, and they will be merged and
+returned.
+
+_Parameters_
+
+-   _props_ `Object`: Optional. Props to pass to the element. Must contain the ref if one is defined.
+-   _options_ `Object`: Options for internal use only.
+-   _options.\_\_unstableIsHtml_ `boolean`: 
+
+_Returns_
+
+-   `Object`: Props to pass to the element to mark as a block.
+
 <a name="validateThemeColors" href="#validateThemeColors">#</a> **validateThemeColors**
 
 Given an array of theme colors checks colors for validity

packages/block-editor/src/components/block-edit/edit.js

@@ -50,13 +50,11 @@ export const Edit = ( props ) => {
 	// with which a block is displayed. If `blockType` is valid, assign
 	// them preferentially as the render value for the block.
 	const Component = blockType.edit || blockType.save;
-	const lightBlockWrapper = hasBlockSupport(
-		blockType,
-		'lightBlockWrapper',
-		false
-	);
 
-	if ( lightBlockWrapper ) {
+	if (
+		blockType.apiVersion > 1 ||
+		hasBlockSupport( blockType, 'lightBlockWrapper', false )
+	) {
 		return <Component { ...props } context={ context } />;
 	}
 

packages/block-editor/src/components/block-edit/test/edit.js

@@ -104,12 +104,10 @@ describe( 'Edit', () => {
 		it( 'should assign context', () => {
 			const edit = ( { context } ) => context.value;
 			registerBlockType( 'core/test-block', {
+				apiVersion: 2,
 				category: 'text',
 				title: 'block title',
 				usesContext: [ 'value' ],
-				supports: {
-					lightBlockWrapper: true,
-				},
 				edit,
 				save: noop,
 			} );

packages/block-editor/src/components/block-list/block-wrapper.js

@@ -31,12 +31,13 @@ import { BlockListBlockContext } from './block';
 import ELEMENTS from './block-wrapper-elements';
 
 /**
- * This hook is used to lighly mark an element as a block element. Call this
- * hook and pass the returned props to the element to mark as a block. If you
- * define a ref for the element, it is important to pass the ref to this hook,
- * which the hooks in turn will pass to the component through the props it
- * returns. Optionally, you can also pass any other props through this hook, and
- * they will be merged and returned.
+ * This hook is used to lightly mark an element as a block element. The element
+ * should be the outermost element of a block. Call this hook and pass the
+ * returned props to the element to mark as a block. If you define a ref for the
+ * element, it is important to pass the ref to this hook, which the hook in turn
+ * will pass to the component through the props it returns. Optionally, you can
+ * also pass any other props through this hook, and they will be merged and
+ * returned.
  *
  * @param {Object}  props   Optional. Props to pass to the element. Must contain
  *                          the ref if one is defined.
@@ -45,7 +46,7 @@ import ELEMENTS from './block-wrapper-elements';
  *
  * @return {Object} Props to pass to the element to mark as a block.
  */
-export function useBlockWrapperProps( props = {}, { __unstableIsHtml } = {} ) {
+export function useBlockProps( props = {}, { __unstableIsHtml } = {} ) {
 	const fallbackRef = useRef();
 	const ref = props.ref || fallbackRef;
 	const onSelectionStart = useContext( Context );
@@ -306,15 +307,15 @@ export function useBlockWrapperProps( props = {}, { __unstableIsHtml } = {} ) {
  *
  * @param {Object} props Optional. Props to pass to the element.
  */
-useBlockWrapperProps.save = getBlockProps;
+useBlockProps.save = getBlockProps;
 
 const BlockComponent = forwardRef(
 	( { children, tagName: TagName = 'div', ...props }, ref ) => {
 		deprecated( 'wp.blockEditor.__experimentalBlock', {
-			alternative: 'wp.blockEditor.__experimentalUseBlockWrapperProps',
+			alternative: 'wp.blockEditor.useBlockProps',
 		} );
-		const blockWrapperProps = useBlockWrapperProps( { ...props, ref } );
-		return <TagName { ...blockWrapperProps }>{ children }</TagName>;
+		const blockProps = useBlockProps( { ...props, ref } );
+		return <TagName { ...blockProps }>{ children }</TagName>;
 	}
 );
 

packages/block-editor/src/components/block-list/block-wrapper.native.js

@@ -8,11 +8,11 @@ import { __unstableGetBlockProps as getBlockProps } from '@wordpress/blocks';
  */
 import ELEMENTS from './block-wrapper-elements';
 
-export function useBlockWrapperProps( props = {} ) {
+export function useBlockProps( props = {} ) {
 	return props;
 }
 
-useBlockWrapperProps.save = getBlockProps;
+useBlockProps.save = getBlockProps;
 
 const ExtendedBlockComponent = ELEMENTS.reduce( ( acc, element ) => {
 	acc[ element ] = element;

packages/block-editor/src/components/block-list/block.js

@@ -40,7 +40,7 @@ import BlockInvalidWarning from './block-invalid-warning';
 import BlockCrashWarning from './block-crash-warning';
 import BlockCrashBoundary from './block-crash-boundary';
 import BlockHtml from './block-html';
-import { useBlockWrapperProps } from './block-wrapper';
+import { useBlockProps } from './block-wrapper';
 
 export const BlockListBlockContext = createContext();
 
@@ -70,7 +70,7 @@ function mergeWrapperProps( propsA, propsB ) {
 
 function Block( { children, isHtml, ...props } ) {
 	return (
-		<div { ...useBlockWrapperProps( props, { __unstableIsHtml: isHtml } ) }>
+		<div { ...useBlockProps( props, { __unstableIsHtml: isHtml } ) }>
 			{ children }
 		</div>
 	);
@@ -126,11 +126,9 @@ function BlockListBlock( {
 	const onBlockError = () => setErrorState( true );
 
 	const blockType = getBlockType( name );
-	const lightBlockWrapper = hasBlockSupport(
-		blockType,
-		'lightBlockWrapper',
-		false
-	);
+	const lightBlockWrapper =
+		blockType.apiVersion > 1 ||
+		hasBlockSupport( blockType, 'lightBlockWrapper', false );
 	const isUnregisteredBlock = name === getUnregisteredTypeHandlerName();
 
 	// Determine whether the block has props to apply to the wrapper.

packages/block-editor/src/components/index.js

@@ -70,7 +70,7 @@ export { default as BlockInspector } from './block-inspector';
 export { default as BlockList } from './block-list';
 export {
 	Block as __experimentalBlock,
-	useBlockWrapperProps as __experimentalUseBlockWrapperProps,
+	useBlockProps,
 } from './block-list/block-wrapper';
 export { default as BlockMover } from './block-mover';
 export { default as BlockPreview } from './block-preview';

packages/block-editor/src/components/index.native.js

@@ -59,7 +59,7 @@ export { default as __unstableEditorStyles } from './editor-styles';
 export { default as Inserter } from './inserter';
 export {
 	Block as __experimentalBlock,
-	useBlockWrapperProps as __experimentalUseBlockWrapperProps,
+	useBlockProps,
 } from './block-list/block-wrapper';
 export { default as FloatingToolbar } from './floating-toolbar';
 

packages/block-library/src/audio/block.json

@@ -1,4 +1,5 @@
 {
+	"apiVersion": 2,
 	"name": "core/audio",
 	"category": "media",
 	"attributes": {
@@ -37,7 +38,6 @@
 	},
 	"supports": {
 		"anchor": true,
-		"align": true,
-		"lightBlockWrapper": true
+		"align": true
 	}
 }

packages/block-library/src/audio/edit.js

@@ -16,7 +16,7 @@ import {
 	MediaPlaceholder,
 	MediaReplaceFlow,
 	RichText,
-	__experimentalUseBlockWrapperProps as useBlockWrapperProps,
+	useBlockProps,
 } from '@wordpress/block-editor';
 import { useEffect } from '@wordpress/element';
 import { __ } from '@wordpress/i18n';
@@ -41,7 +41,7 @@ function AudioEdit( {
 	insertBlocksAfter,
 } ) {
 	const { id, autoplay, caption, loop, preload, src } = attributes;
-	const blockWrapperProps = useBlockWrapperProps();
+	const blockProps = useBlockProps();
 	const mediaUpload = useSelect( ( select ) => {
 		const { getSettings } = select( 'core/block-editor' );
 		return getSettings().mediaUpload;
@@ -116,7 +116,7 @@ function AudioEdit( {
 	}
 	if ( ! src ) {
 		return (
-			<div { ...blockWrapperProps }>
+			<div { ...blockProps }>
 				<MediaPlaceholder
 					icon={ <BlockIcon icon={ icon } /> }
 					onSelect={ onSelectAudio }
@@ -175,7 +175,7 @@ function AudioEdit( {
 					/>
 				</PanelBody>
 			</InspectorControls>
-			<figure { ...blockWrapperProps }>
+			<figure { ...blockProps }>
 				{ /*
 					Disable the audio tag so the user clicking on it won't play the
 					file or change the position slider when the controls are enabled.

packages/block-library/src/audio/save.js

@@ -1,17 +1,14 @@
 /**
  * WordPress dependencies
  */
-import {
-	RichText,
-	__experimentalUseBlockWrapperProps as useBlockWrapperProps,
-} from '@wordpress/block-editor';
+import { RichText, useBlockProps } from '@wordpress/block-editor';
 
 export default function save( { attributes } ) {
 	const { autoplay, caption, loop, preload, src } = attributes;
 
 	return (
 		src && (
-			<figure { ...useBlockWrapperProps.save() }>
+			<figure { ...useBlockProps.save() }>
 				<audio
 					controls="controls"
 					src={ src }

packages/block-library/src/button/block.json

@@ -1,4 +1,5 @@
 {
+	"apiVersion": 2,
 	"name": "core/button",
 	"category": "design",
 	"parent": [
@@ -57,7 +58,6 @@
 		"anchor": true,
 		"align": true,
 		"alignWide": false,
-		"reusable": false,
-		"lightBlockWrapper": true
+		"reusable": false
 	}
 }

packages/block-library/src/button/edit.js

@@ -22,7 +22,7 @@ import {
 	BlockControls,
 	InspectorControls,
 	RichText,
-	__experimentalUseBlockWrapperProps as useBlockWrapperProps,
+	useBlockProps,
 	__experimentalLinkControl as LinkControl,
 	__experimentalUseEditorFeature as useEditorFeature,
 } from '@wordpress/block-editor';
@@ -197,12 +197,12 @@ function ButtonEdit( props ) {
 	);
 
 	const colorProps = getColorAndStyleProps( attributes, colors, true );
-	const blockWrapperProps = useBlockWrapperProps();
+	const blockProps = useBlockProps();
 
 	return (
 		<>
 			<ColorEdit { ...props } />
-			<div { ...blockWrapperProps }>
+			<div { ...blockProps }>
 				<RichText
 					placeholder={ placeholder || __( 'Add text…' ) }
 					value={ text }

packages/block-library/src/button/save.js

@@ -6,10 +6,7 @@ import classnames from 'classnames';
 /**
  * WordPress dependencies
  */
-import {
-	RichText,
-	__experimentalUseBlockWrapperProps as useBlockWrapperProps,
-} from '@wordpress/block-editor';
+import { RichText, useBlockProps } from '@wordpress/block-editor';
 
 /**
  * Internal dependencies
@@ -36,7 +33,7 @@ export default function save( { attributes } ) {
 	// A title will no longer be assigned for new or updated button block links.
 
 	return (
-		<div { ...useBlockWrapperProps.save() }>
+		<div { ...useBlockProps.save() }>
 			<RichText.Content
 				tagName="a"
 				className={ buttonClasses }

packages/block-library/src/buttons/block.json

@@ -1,10 +1,10 @@
 {
+	"apiVersion": 2,
 	"name": "core/buttons",
 	"category": "design",
 	"supports": {
 		"anchor": true,
 		"align": true,
-		"alignWide": false,
-		"lightBlockWrapper": true
+		"alignWide": false
 	}
 }

packages/block-library/src/buttons/edit.js

@@ -4,7 +4,7 @@
 import {
 	__experimentalAlignmentHookSettingsProvider as AlignmentHookSettingsProvider,
 	InnerBlocks,
-	__experimentalUseBlockWrapperProps as useBlockWrapperProps,
+	useBlockProps,
 } from '@wordpress/block-editor';
 
 /**
@@ -21,12 +21,12 @@ const alignmentHooksSetting = {
 };
 
 function ButtonsEdit() {
-	const blockWrapperProps = useBlockWrapperProps();
+	const blockProps = useBlockProps();
 	return (
 		<AlignmentHookSettingsProvider value={ alignmentHooksSetting }>
 			<InnerBlocks
 				allowedBlocks={ ALLOWED_BLOCKS }
-				__experimentalPassedProps={ blockWrapperProps }
+				__experimentalPassedProps={ blockProps }
 				__experimentalTagName="div"
 				template={ BUTTONS_TEMPLATE }
 				orientation="horizontal"

packages/block-library/src/buttons/save.js

@@ -1,14 +1,11 @@
 /**
  * WordPress dependencies
  */
-import {
-	InnerBlocks,
-	__experimentalUseBlockWrapperProps as useBlockWrapperProps,
-} from '@wordpress/block-editor';
+import { InnerBlocks, useBlockProps } from '@wordpress/block-editor';
 
 export default function save() {
 	return (
-		<div { ...useBlockWrapperProps.save() }>
+		<div { ...useBlockProps.save() }>
 			<InnerBlocks.Content />
 		</div>
 	);

packages/block-library/src/code/block.json

@@ -1,4 +1,5 @@
 {
+	"apiVersion": 2,
 	"name": "core/code",
 	"category": "text",
 	"attributes": {
@@ -9,7 +10,6 @@
 		}
 	},
 	"supports": {
-		"anchor": true,
-		"lightBlockWrapper": true
+		"anchor": true
 	}
 }