Reusable blocks: Mark API as experimental (#11230)

* Reusable blocks: Mark API as experimental

The reusable block selectors and actions will need to change in the
future. Give ourselves some breathing room to make these changes after
Gutenberg 4.2 by marking them as experimental.

* Add notes about deprecations added for Reusable Blocks Data API

Author: noisysocks

docs/data/data-core-editor.md

@@ -1120,7 +1120,7 @@ Items are returned ordered descendingly by their 'utility' and 'frecency'.
 
 Items that appear in inserter.
 
-### getReusableBlock
+### __experimentalGetReusableBlock
 
 Returns the reusable block with the given ID.
 
@@ -1133,7 +1133,7 @@ Returns the reusable block with the given ID.
 
 The reusable block, or null if none exists.
 
-### isSavingReusableBlock
+### __experimentalIsSavingReusableBlock
 
 Returns whether or not the reusable block with the given ID is being saved.
 
@@ -1146,7 +1146,7 @@ Returns whether or not the reusable block with the given ID is being saved.
 
 Whether or not the reusable block is being saved.
 
-### isFetchingReusableBlock
+### __experimentalIsFetchingReusableBlock
 
 Returns true if the reusable block with the given ID is being fetched, or
 false otherwise.
@@ -1160,7 +1160,7 @@ false otherwise.
 
 Whether the reusable block is being fetched.
 
-### getReusableBlocks
+### __experimentalGetReusableBlocks
 
 Returns an array of all reusable blocks.
 
@@ -1649,7 +1649,7 @@ Returns an action object used to lock the editor.
 
  * lock: Details about the post lock status, user, and nonce.
 
-### fetchReusableBlocks
+### __experimentalFetchReusableBlocks
 
 Returns an action object used to fetch a single reusable block or all
 reusable blocks from the REST API into the store.
@@ -1659,7 +1659,7 @@ reusable blocks from the REST API into the store.
  * id: If given, only a single reusable block with this ID will
                     be fetched.
 
-### receiveReusableBlocks
+### __experimentalReceiveReusableBlocks
 
 Returns an action object used in signalling that reusable blocks have been
 received. `results` is an array of objects containing:
@@ -1670,7 +1670,7 @@ received. `results` is an array of objects containing:
 
  * results: Reusable blocks received.
 
-### saveReusableBlock
+### __experimentalSaveReusableBlock
 
 Returns an action object used to save a reusable block that's in the store to
 the REST API.
@@ -1679,15 +1679,15 @@ the REST API.
 
  * id: The ID of the reusable block to save.
 
-### deleteReusableBlock
+### __experimentalDeleteReusableBlock
 
 Returns an action object used to delete a reusable block via the REST API.
 
 *Parameters*
 
  * id: The ID of the reusable block to delete.
 
-### updateReusableBlockTitle
+### __experimentalUpdateReusableBlockTitle
 
 Returns an action object used in signalling that a reusable block's title is
 to be updated.
@@ -1697,15 +1697,15 @@ to be updated.
  * id: The ID of the reusable block to update.
  * title: The new title.
 
-### convertBlockToStatic
+### __experimentalConvertBlockToStatic
 
 Returns an action object used to convert a reusable block into a static block.
 
 *Parameters*
 
  * clientId: The client ID of the block to attach.
 
-### convertBlockToReusable
+### __experimentalConvertBlockToReusable
 
 Returns an action object used to convert a static block into a reusable block.
 
@@ -1776,4 +1776,6 @@ Returns an action object signaling that a new term is added to the edited post.
  * slug: Taxonomy slug.
  * term: Term object.
 
-### createNotice
+### createNotice
+
+### fetchReusableBlocks

docs/reference/deprecated.md

@@ -31,6 +31,7 @@ Gutenberg's deprecation policy is intended to support backwards-compatibility fo
 - `wp.components.CodeEditor` has been removed. Used `wp.codeEditor` directly instead.
 - `wp.blocks.setUnknownTypeHandlerName` has been removed. Please use `setFreeformContentHandlerName` and `setUnregisteredTypeHandlerName` instead.
 - `wp.blocks.getUnknownTypeHandlerName` has been removed. Please use `getFreeformContentHandlerName` and `getUnregisteredTypeHandlerName` instead.
+- The Reusable Blocks Data API was marked as experimental as it's subject to change in the future.
 
 ## 4.1.0
 

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

@@ -146,9 +146,9 @@ class ReusableBlockEdit extends Component {
 export default compose( [
 	withSelect( ( select, ownProps ) => {
 		const {
-			getReusableBlock,
-			isFetchingReusableBlock,
-			isSavingReusableBlock,
+			__experimentalGetReusableBlock: getReusableBlock,
+			__experimentalIsFetchingReusableBlock: isFetchingReusableBlock,
+			__experimentalIsSavingReusableBlock: isSavingReusableBlock,
 			getBlock,
 		} = select( 'core/editor' );
 		const { ref } = ownProps.attributes;
@@ -163,10 +163,10 @@ export default compose( [
 	} ),
 	withDispatch( ( dispatch, ownProps ) => {
 		const {
-			fetchReusableBlocks,
+			__experimentalFetchReusableBlocks: fetchReusableBlocks,
 			updateBlockAttributes,
-			updateReusableBlockTitle,
-			saveReusableBlock,
+			__experimentalUpdateReusableBlockTitle: updateReusableBlockTitle,
+			__experimentalSaveReusableBlock: saveReusableBlock,
 		} = dispatch( 'core/editor' );
 		const { ref } = ownProps.attributes;
 

packages/editor/CHANGELOG.md

@@ -1,3 +1,9 @@
+## 6.1.0 (Unreleased)
+
+### Deprecations
+
+- The Reusable Blocks Data API is marked as experimental as it's subject to change in the future ([#11230](https://github.com/WordPress/gutenberg/pull/11230)).
+
 ## 6.0.1 (2018-10-30)
 
 ### Bug Fixes

packages/editor/src/components/block-settings-menu/reusable-block-convert-button.js

@@ -49,7 +49,11 @@ export function ReusableBlockConvertButton( {
 
 export default compose( [
 	withSelect( ( select, { clientIds } ) => {
-		const { getBlock, canInsertBlockType, getReusableBlock } = select( 'core/editor' );
+		const {
+			getBlock,
+			canInsertBlockType,
+			__experimentalGetReusableBlock: getReusableBlock,
+		} = select( 'core/editor' );
 		const {
 			getFreeformFallbackBlockName,
 			getUnregisteredFallbackBlockName,
@@ -85,8 +89,8 @@ export default compose( [
 	} ),
 	withDispatch( ( dispatch, { clientIds, onToggle = noop } ) => {
 		const {
-			convertBlockToReusable,
-			convertBlockToStatic,
+			__experimentalConvertBlockToReusable: convertBlockToReusable,
+			__experimentalConvertBlockToStatic: convertBlockToStatic,
 		} = dispatch( 'core/editor' );
 
 		return {

packages/editor/src/components/block-settings-menu/reusable-block-delete-button.js

@@ -31,15 +31,18 @@ export function ReusableBlockDeleteButton( { reusableBlock, onDelete } ) {
 
 export default compose( [
 	withSelect( ( select, { clientId } ) => {
-		const { getBlock, getReusableBlock } = select( 'core/editor' );
+		const {
+			getBlock,
+			__experimentalGetReusableBlock: getReusableBlock,
+		} = select( 'core/editor' );
 		const block = getBlock( clientId );
 		return {
 			reusableBlock: block && isReusableBlock( block ) ? getReusableBlock( block.attributes.ref ) : null,
 		};
 	} ),
 	withDispatch( ( dispatch, { onToggle = noop } ) => {
 		const {
-			deleteReusableBlock,
+			__experimentalDeleteReusableBlock: deleteReusableBlock,
 		} = dispatch( 'core/editor' );
 
 		return {

packages/editor/src/components/inserter/menu.js

@@ -351,7 +351,7 @@ export default compose(
 		};
 	} ),
 	withDispatch( ( dispatch ) => ( {
-		fetchReusableBlocks: dispatch( 'core/editor' ).fetchReusableBlocks,
+		fetchReusableBlocks: dispatch( 'core/editor' ).__experimentalFetchReusableBlocks,
 		showInsertionPoint: dispatch( 'core/editor' ).showInsertionPoint,
 		hideInsertionPoint: dispatch( 'core/editor' ).hideInsertionPoint,
 	} ) ),

packages/editor/src/hooks/default-autocompleters.js

@@ -17,7 +17,7 @@ import { blockAutocompleter, userAutocompleter } from '../components';
 
 const defaultAutocompleters = [ userAutocompleter ];
 
-const fetchReusableBlocks = once( () => dispatch( 'core/editor' ).fetchReusableBlocks() );
+const fetchReusableBlocks = once( () => dispatch( 'core/editor' ).__experimentalFetchReusableBlocks() );
 
 function setDefaultCompleters( completers, blockName ) {
 	if ( ! completers ) {

packages/editor/src/store/actions.js

@@ -578,7 +578,7 @@ export function updatePostLock( lock ) {
  *
  * @return {Object} Action object.
  */
-export function fetchReusableBlocks( id ) {
+export function __experimentalFetchReusableBlocks( id ) {
 	return {
 		type: 'FETCH_REUSABLE_BLOCKS',
 		id,
@@ -595,7 +595,7 @@ export function fetchReusableBlocks( id ) {
  *
  * @return {Object} Action object.
  */
-export function receiveReusableBlocks( results ) {
+export function __experimentalReceiveReusableBlocks( results ) {
 	return {
 		type: 'RECEIVE_REUSABLE_BLOCKS',
 		results,
@@ -610,7 +610,7 @@ export function receiveReusableBlocks( results ) {
  *
  * @return {Object} Action object.
  */
-export function saveReusableBlock( id ) {
+export function __experimentalSaveReusableBlock( id ) {
 	return {
 		type: 'SAVE_REUSABLE_BLOCK',
 		id,
@@ -624,7 +624,7 @@ export function saveReusableBlock( id ) {
  *
  * @return {Object} Action object.
  */
-export function deleteReusableBlock( id ) {
+export function __experimentalDeleteReusableBlock( id ) {
 	return {
 		type: 'DELETE_REUSABLE_BLOCK',
 		id,
@@ -640,7 +640,7 @@ export function deleteReusableBlock( id ) {
  *
  * @return {Object} Action object.
  */
-export function updateReusableBlockTitle( id, title ) {
+export function __experimentalUpdateReusableBlockTitle( id, title ) {
 	return {
 		type: 'UPDATE_REUSABLE_BLOCK_TITLE',
 		id,
@@ -655,7 +655,7 @@ export function updateReusableBlockTitle( id, title ) {
  *
  * @return {Object} Action object.
  */
-export function convertBlockToStatic( clientId ) {
+export function __experimentalConvertBlockToStatic( clientId ) {
 	return {
 		type: 'CONVERT_BLOCK_TO_STATIC',
 		clientId,
@@ -669,7 +669,7 @@ export function convertBlockToStatic( clientId ) {
  *
  * @return {Object} Action object.
  */
-export function convertBlockToReusable( clientIds ) {
+export function __experimentalConvertBlockToReusable( clientIds ) {
 	return {
 		type: 'CONVERT_BLOCK_TO_REUSABLE',
 		clientIds: castArray( clientIds ),
@@ -821,3 +821,80 @@ export const createSuccessNotice = partial( createNotice, 'success' );
 export const createInfoNotice = partial( createNotice, 'info' );
 export const createErrorNotice = partial( createNotice, 'error' );
 export const createWarningNotice = partial( createNotice, 'warning' );
+
+//
+// Deprecated
+//
+
+export function fetchReusableBlocks( id ) {
+	deprecated( "wp.data.dispatch( 'core/editor' ).fetchReusableBlocks( id )", {
+		alternative: "wp.data.select( 'core' ).getEntityRecords( 'postType', 'wp_block' )",
+		plugin: 'Gutenberg',
+		version: '4.4.0',
+	} );
+
+	return __experimentalFetchReusableBlocks( id );
+}
+
+export function receiveReusableBlocks( results ) {
+	deprecated( "wp.data.dispatch( 'core/editor' ).receiveReusableBlocks( results )", {
+		alternative: "wp.data.select( 'core' ).getEntityRecords( 'postType', 'wp_block' )",
+		plugin: 'Gutenberg',
+		version: '4.4.0',
+	} );
+
+	return __experimentalReceiveReusableBlocks( results );
+}
+
+export function saveReusableBlock( id ) {
+	deprecated( "wp.data.dispatch( 'core/editor' ).saveReusableBlock( id )", {
+		alternative: "wp.data.dispatch( 'core' ).saveEntityRecord( 'postType', 'wp_block', reusableBlock )",
+		plugin: 'Gutenberg',
+		version: '4.4.0',
+	} );
+
+	return __experimentalSaveReusableBlock( id );
+}
+
+export function deleteReusableBlock( id ) {
+	deprecated( 'deleteReusableBlock action (`core/editor` store)', {
+		alternative: '__experimentalDeleteReusableBlock action (`core/edtior` store)',
+		plugin: 'Gutenberg',
+		version: '4.4.0',
+		hint: 'Using experimental APIs is strongly discouraged as they are subject to removal without notice.',
+	} );
+
+	return __experimentalDeleteReusableBlock( id );
+}
+
+export function updateReusableBlockTitle( id, title ) {
+	deprecated( "wp.data.dispatch( 'core/editor' ).updateReusableBlockTitle( id, title )", {
+		alternative: "wp.data.dispatch( 'core' ).saveEntityRecord( 'postType', 'wp_block', reusableBlock )",
+		plugin: 'Gutenberg',
+		version: '4.4.0',
+	} );
+
+	return __experimentalUpdateReusableBlockTitle( id, title );
+}
+
+export function convertBlockToStatic( id ) {
+	deprecated( 'convertBlockToStatic action (`core/editor` store)', {
+		alternative: '__experimentalConvertBlockToStatic action (`core/edtior` store)',
+		plugin: 'Gutenberg',
+		version: '4.4.0',
+		hint: 'Using experimental APIs is strongly discouraged as they are subject to removal without notice.',
+	} );
+
+	return __experimentalConvertBlockToStatic( id );
+}
+
+export function convertBlockToReusable( id ) {
+	deprecated( 'convertBlockToReusable action (`core/editor` store)', {
+		alternative: '__experimentalConvertBlockToReusable action (`core/edtior` store)',
+		plugin: 'Gutenberg',
+		version: '4.4.0',
+		hint: 'Using experimental APIs is strongly discouraged as they are subject to removal without notice.',
+	} );
+
+	return __experimentalConvertBlockToReusable( id );
+}

packages/editor/src/store/effects/reusable-blocks.js

@@ -26,14 +26,14 @@ import { dispatch as dataDispatch } from '@wordpress/data';
  */
 import { resolveSelector } from './utils';
 import {
-	receiveReusableBlocks as receiveReusableBlocksAction,
+	__experimentalReceiveReusableBlocks as receiveReusableBlocksAction,
 	removeBlocks,
 	replaceBlocks,
 	receiveBlocks,
-	saveReusableBlock,
+	__experimentalSaveReusableBlock as saveReusableBlock,
 } from '../actions';
 import {
-	getReusableBlock,
+	__experimentalGetReusableBlock as getReusableBlock,
 	getBlock,
 	getBlocks,
 	getBlocksByClientId,