Block API: Move useOnce to supports.useOnce (#7293)

* Move `useOnce` to `supports.useOnce

* Change useOnce to multiple

* Remove empty line

* Set defaultSupports in hasBlockSupport

blocks/api/registration.js

@@ -158,6 +158,16 @@ export function registerBlockType( name, settings ) {
 		set( settings, [ 'supports', 'inserter' ], ! settings.isPrivate );
 	}
 
+	if ( 'useOnce' in settings ) {
+		deprecated( 'useOnce', {
+			version: '3.3',
+			alternative: 'supports.multiple',
+			plugin: 'Gutenberg',
+			hint: 'useOnce property in the settings param passed to wp.block.registerBlockType.',
+		} );
+		set( settings, [ 'supports', 'multiple' ], ! settings.useOnce );
+	}
+
 	dispatch( 'core/blocks' ).addBlockTypes( settings );
 
 	return settings;

core-blocks/more/index.js

@@ -26,12 +26,11 @@ export const settings = {
 
 	category: 'layout',
 
-	useOnce: true,
-
 	supports: {
 		customClassName: false,
 		className: false,
 		html: false,
+		multiple: false,
 	},
 
 	attributes: {

core-blocks/subhead/index.js

@@ -27,7 +27,9 @@ export const settings = {
 
 	category: 'common',
 
-	useOnce: true,
+	supports: {
+		multiple: false,
+	},
 
 	attributes: {
 		content: {

docs/block-api.md

@@ -267,17 +267,6 @@ transforms: {
 
 To control the priority with which a transform is applied, define a `priority` numeric property on your transform object, where a lower value will take precedence over higher values. This behaves much like a [WordPress hook](https://codex.wordpress.org/Plugin_API#Hook_to_WordPress). Like hooks, the default priority is `10` when not otherwise set.
 
-#### useOnce (optional)
-
-* **Type:** `Bool`
-* **Default:** `false`
-
-A once-only block can be inserted into each post, one time only. For example, the built-in 'More' block cannot be inserted again if it already exists in the post being edited. A once-only block's icon is automatically dimmed (unclickable) to prevent multiple instances.
-
-```js
-// Use the block just once per post
-useOnce: true,
-```
 
 #### parent (optional)
 
@@ -333,6 +322,13 @@ html: false,
 inserter: false,
 ```
 
+- `multiple` (default `true`): A non-multiple block can be inserted into each post, one time only. For example, the built-in 'More' block cannot be inserted again if it already exists in the post being edited. A non-multiple block's icon is automatically dimmed (unclickable) to prevent multiple instances.
+
+```js
+// Use the block just once per post
+multiple: false,
+```
+
 ## Edit and Save
 
 The `edit` and `save` functions define the editor interface with which a user would interact, and the markup to be serialized back when a post is saved. They are the heart of how a block operates, so they are [covered separately](../docs/block-api/block-edit-save.md).

docs/reference/deprecated.md

@@ -1,5 +1,8 @@
 Gutenberg's deprecation policy is intended to support backwards-compatibility for two minor releases, when possible. The current deprecations are listed below and are grouped by _the version at which they will be removed completely_. If your plugin depends on these behaviors, you must update to the recommended alternative before the noted version.
 
+## 3.3.0
+ - `useOnce: true` has been removed from the Block API. Please use `supports.multiple: false` instead.
+
 ## 3.2.0
 
  - `wp.data.withRehydratation` has been renamed to `wp.data.withRehydration`.

edit-post/hooks/index.js

@@ -3,4 +3,4 @@
  */
 import './blocks';
 import './more-menu';
-import './validate-use-once';
+import './validate-multiple-use';

edit-post/hooks/validate-use-once/index.js → edit-post/hooks/validate-multiple-use/index.js

@@ -6,7 +6,13 @@ import { find } from 'lodash';
 /**
  * WordPress dependencies
  */
-import { createBlock, getBlockType, findTransform, getBlockTransforms } from '@wordpress/blocks';
+import {
+	createBlock,
+	findTransform,
+	getBlockTransforms,
+	getBlockType,
+	hasBlockSupport,
+} from '@wordpress/blocks';
 import { Button } from '@wordpress/components';
 import { withSelect, withDispatch } from '@wordpress/data';
 import { Warning } from '@wordpress/editor';
@@ -16,7 +22,7 @@ import { __ } from '@wordpress/i18n';
 
 const enhance = compose(
 	/*
-	 * For blocks whose block type defines `useOnce`, provides the wrapped
+	 * For blocks whose block type doesn't support `multiple`, provides the wrapped
 	 * component with `originalBlockUid` -- a reference to the first block of
 	 * the same type in the content -- if and only if that "original" block is
 	 * not the current one. Thus, an inexisting `originalBlockUid` prop signals
@@ -28,11 +34,11 @@ const enhance = compose(
 	 */
 	withSelect( ( select, block ) => {
 		const blocks = select( 'core/editor' ).getBlocks();
-		const { useOnce } = getBlockType( block.name );
+		const multiple = hasBlockSupport( block.name, 'multiple', true );
 
-		// For block types with no `useOnce` restriction, there is no "original
+		// For block types with `multiple` support, there is no "original
 		// block" to be found in the content, as the block itself is valid.
-		if ( ! useOnce ) {
+		if ( multiple ) {
 			return {};
 		}
 
@@ -49,7 +55,7 @@ const enhance = compose(
 	} ) ),
 );
 
-const withUseOnceValidation = createHigherOrderComponent( ( BlockEdit ) => {
+const withMultipleValidation = createHigherOrderComponent( ( BlockEdit ) => {
 	return enhance( ( {
 		originalBlockUid,
 		selectFirst,
@@ -67,7 +73,7 @@ const withUseOnceValidation = createHigherOrderComponent( ( BlockEdit ) => {
 				<BlockEdit key="block-edit" { ...props } />
 			</div>,
 			<Warning
-				key="use-once-warning"
+				key="multiple-use-warning"
 				actions={ [
 					<Button key="find-original" isLarge onClick={ selectFirst }>
 						{ __( 'Find original' ) }
@@ -94,7 +100,7 @@ const withUseOnceValidation = createHigherOrderComponent( ( BlockEdit ) => {
 			</Warning>,
 		];
 	} );
-}, 'withUseOnceValidation' );
+}, 'withMultipleValidation' );
 
 /**
  * Given a base block name, returns the default block type to which to offer
@@ -120,6 +126,6 @@ function getOutboundType( blockName ) {
 
 addFilter(
 	'blocks.BlockEdit',
-	'core/validation/useOnce',
-	withUseOnceValidation
+	'core/validation/multiple',
+	withMultipleValidation
 );

editor/components/block-settings-menu/block-duplicate-button.js

@@ -10,12 +10,11 @@ import { __ } from '@wordpress/i18n';
 import { IconButton } from '@wordpress/components';
 import { compose } from '@wordpress/element';
 import { withSelect, withDispatch } from '@wordpress/data';
-import { cloneBlock, getBlockType } from '@wordpress/blocks';
+import { cloneBlock, hasBlockSupport } from '@wordpress/blocks';
 
 export function BlockDuplicateButton( { blocks, onDuplicate, onClick = noop, isLocked, small = false, role } ) {
 	const canDuplicate = every( blocks, ( block ) => {
-		const type = getBlockType( block.name );
-		return ! type.useOnce;
+		return hasBlockSupport( block.name, 'multiple', true );
 	} );
 	if ( isLocked || ! canDuplicate ) {
 		return null;

editor/store/selectors.js

@@ -1474,7 +1474,7 @@ export const getInserterItems = createSelector(
 			const id = blockType.name;
 
 			let isDisabled = false;
-			if ( blockType.useOnce ) {
+			if ( ! hasBlockSupport( blockType.name, 'multiple', true ) ) {
 				isDisabled = some( getBlocks( state ), { name: blockType.name } );
 			}
 

editor/store/test/selectors.js

@@ -125,7 +125,9 @@ describe( 'selectors', () => {
 			title: 'Test Block B',
 			icon: 'test',
 			keywords: [ 'testing' ],
-			useOnce: true,
+			supports: {
+				multiple: false,
+			},
 		} );
 
 		registerBlockType( 'core/test-block-c', {
@@ -3104,7 +3106,7 @@ describe( 'selectors', () => {
 			] );
 		} );
 
-		it( 'should set isDisabled when a block with useOnce has been used', () => {
+		it( 'should set isDisabled when a block with `multiple: false` has been used', () => {
 			const state = {
 				editor: {
 					present: {