Block Bindings: Open the stable editor APIs (#65713)

* Try use select and dispatch instead of registry * Fix `setValues` * Open `useBlockBindingsUtils` * Open registration APIs * Restrict `getFieldsList` API * Update `useBlockBindingsUtils` docs * Update register/unregister bindings docs * Simplify API functions examples Co-authored-by: Greg Ziółkowski <[email protected]> * Update docs * Update comments --------- Co-authored-by: Carlos Bravo <[email protected]> Co-authored-by: Greg Ziółkowski <[email protected]> Co-authored-by: cbravobernal <[email protected]> Co-authored-by: SantosGuillamot <[email protected]> Co-authored-by: gziolo <[email protected]>
WordPress · Oct 2, 2024 · cfabf03 · cfabf03
1 parent 4443474
commit cfabf03
Show file tree

Hide file tree

Showing 18 changed files with 199 additions and 63 deletions.
diff --git a/packages/block-editor/README.md b/packages/block-editor/README.md
@@ -839,6 +839,48 @@ _Related_
 
 -   <https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/url-popover/README.md>
 
+### useBlockBindingsUtils
+
+Retrieves the existing utils needed to update the block `bindings` metadata. They can be used to create, modify, or remove connections from the existing block attributes.
+
+It contains the following utils:
+
+-   `updateBlockBindings`: Updates the value of the bindings connected to block attributes. It can be used to remove a specific binding by setting the value to `undefined`.
+-   `removeAllBlockBindings`: Removes the bindings property of the `metadata` attribute.
+
+_Usage_
+
+```js
+import { useBlockBindingsUtils } from '@wordpress/block-editor';
+const { updateBlockBindings, removeAllBlockBindings } = useBlockBindingsUtils();
+
+// Update url and alt attributes.
+updateBlockBindings( {
+	url: {
+		source: 'core/post-meta',
+		args: {
+			key: 'url_custom_field',
+		},
+	},
+	alt: {
+		source: 'core/post-meta',
+		args: {
+			key: 'text_custom_field',
+		},
+	},
+} );
+
+// Remove binding from url attribute.
+updateBlockBindings( { url: undefined } );
+
+// Remove bindings from all attributes.
+removeAllBlockBindings();
+```
+
+_Returns_
+
+-   `?WPBlockBindingsUtils`: Object containing the block bindings utils.
+
 ### useBlockCommands
 
 Undocumented declaration.

diff --git a/packages/block-editor/src/components/rich-text/index.js b/packages/block-editor/src/components/rich-text/index.js
@@ -20,7 +20,7 @@ import {
 	removeFormat,
 } from '@wordpress/rich-text';
 import { Popover } from '@wordpress/components';
-import { store as blocksStore } from '@wordpress/blocks';
+import { getBlockBindingsSource } from '@wordpress/blocks';
 import deprecated from '@wordpress/deprecated';
 import { __, sprintf } from '@wordpress/i18n';
 
@@ -39,7 +39,6 @@ import FormatEdit from './format-edit';
 import { getAllowedFormats } from './utils';
 import { Content, valueToHTMLString } from './content';
 import { withDeprecations } from './with-deprecations';
-import { unlock } from '../../lock-unlock';
 import { canBindBlock } from '../../hooks/use-bindings-attributes';
 import BlockContext from '../block-context';
 
@@ -175,7 +174,6 @@ export function RichTextWrapper(
 			}
 
 			const relatedBinding = blockBindings[ identifier ];
-			const { getBlockBindingsSource } = unlock( select( blocksStore ) );
 			const blockBindingsSource = getBlockBindingsSource(
 				relatedBinding.source
 			);

diff --git a/packages/block-editor/src/hooks/block-bindings.js b/packages/block-editor/src/hooks/block-bindings.js
@@ -2,7 +2,10 @@
  * WordPress dependencies
  */
 import { __ } from '@wordpress/i18n';
-import { privateApis as blocksPrivateApis } from '@wordpress/blocks';
+import {
+	getBlockBindingsSource,
+	getBlockBindingsSources,
+} from '@wordpress/blocks';
 import {
 	__experimentalItemGroup as ItemGroup,
 	__experimentalItem as Item,
@@ -47,7 +50,6 @@ const useToolsPanelDropdownMenuProps = () => {
 };
 
 function BlockBindingsPanelDropdown( { fieldsList, attribute, binding } ) {
-	const { getBlockBindingsSources } = unlock( blocksPrivateApis );
 	const registeredSources = getBlockBindingsSources();
 	const { updateBlockBindings } = useBlockBindingsUtils();
 	const currentKey = binding?.args?.key;
@@ -96,8 +98,7 @@ function BlockBindingsPanelDropdown( { fieldsList, attribute, binding } ) {
 
 function BlockBindingsAttribute( { attribute, binding, fieldsList } ) {
 	const { source: sourceName, args } = binding || {};
-	const sourceProps =
-		unlock( blocksPrivateApis ).getBlockBindingsSource( sourceName );
+	const sourceProps = getBlockBindingsSource( sourceName );
 	const isSourceInvalid = ! sourceProps;
 	return (
 		<VStack className="block-editor-bindings__item" spacing={ 0 }>
@@ -200,7 +201,6 @@ export const BlockBindingsPanel = ( { name: blockName, metadata } ) => {
 			if ( ! bindableAttributes || bindableAttributes.length === 0 ) {
 				return EMPTY_OBJECT;
 			}
-			const { getBlockBindingsSources } = unlock( blocksPrivateApis );
 			const registeredSources = getBlockBindingsSources();
 			Object.entries( registeredSources ).forEach(
 				( [ sourceName, { getFieldsList, usesContext } ] ) => {

diff --git a/packages/block-editor/src/private-apis.js b/packages/block-editor/src/private-apis.js
@@ -47,7 +47,6 @@ import { PrivatePublishDateTimePicker } from './components/publish-date-time-pic
 import useSpacingSizes from './components/spacing-sizes-control/hooks/use-spacing-sizes';
 import useBlockDisplayTitle from './components/block-title/use-block-display-title';
 import TabbedSidebar from './components/tabbed-sidebar';
-import { useBlockBindingsUtils } from './utils/block-bindings';
 
 /**
  * Private @wordpress/block-editor APIs.
@@ -92,6 +91,5 @@ lock( privateApis, {
 	useBlockDisplayTitle,
 	__unstableBlockStyleVariationOverridesWithConfig,
 	setBackgroundStyleDefaults,
-	useBlockBindingsUtils,
 	sectionRootClientIdKey,
 } );
diff --git a/packages/block-editor/src/utils/block-bindings.js b/packages/block-editor/src/utils/block-bindings.js
@@ -13,6 +13,53 @@ function isObjectEmpty( object ) {
 	return ! object || Object.keys( object ).length === 0;
 }
 
+/**
+ * Contains utils to update the block `bindings` metadata.
+ *
+ * @typedef {Object} WPBlockBindingsUtils
+ *
+ * @property {Function} updateBlockBindings    Updates the value of the bindings connected to block attributes.
+ * @property {Function} removeAllBlockBindings Removes the bindings property of the `metadata` attribute.
+ */
+
+/**
+ * Retrieves the existing utils needed to update the block `bindings` metadata.
+ * They can be used to create, modify, or remove connections from the existing block attributes.
+ *
+ * It contains the following utils:
+ * - `updateBlockBindings`: Updates the value of the bindings connected to block attributes. It can be used to remove a specific binding by setting the value to `undefined`.
+ * - `removeAllBlockBindings`: Removes the bindings property of the `metadata` attribute.
+ *
+ * @return {?WPBlockBindingsUtils} Object containing the block bindings utils.
+ *
+ * @example
+ * ```js
+ * import { useBlockBindingsUtils } from '@wordpress/block-editor'
+ * const { updateBlockBindings, removeAllBlockBindings } = useBlockBindingsUtils();
+ *
+ * // Update url and alt attributes.
+ * updateBlockBindings( {
+ *     url: {
+ *         source: 'core/post-meta',
+ *         args: {
+ *             key: 'url_custom_field',
+ *         },
+ *     },
+ *     alt: {
+ *         source: 'core/post-meta',
+ *         args: {
+ *             key: 'text_custom_field',
+ *         },
+ *     },
+ * } );
+ *
+ * // Remove binding from url attribute.
+ * updateBlockBindings( { url: undefined } );
+ *
+ * // Remove bindings from all attributes.
+ * removeAllBlockBindings();
+ * ```
+ */
 export function useBlockBindingsUtils() {
 	const { clientId } = useBlockEditContext();
 	const { updateBlockAttributes } = useDispatch( blockEditorStore );

diff --git a/packages/block-editor/src/utils/index.js b/packages/block-editor/src/utils/index.js
@@ -1,2 +1,3 @@
 export { default as transformStyles } from './transform-styles';
 export { default as getPxFromCssUnit } from './get-px-from-css-unit';
+export { useBlockBindingsUtils } from './block-bindings';
diff --git a/packages/block-library/src/block/edit.js b/packages/block-library/src/block/edit.js
@@ -32,7 +32,7 @@ import {
 	InnerBlocks,
 } from '@wordpress/block-editor';
 import { privateApis as patternsPrivateApis } from '@wordpress/patterns';
-import { store as blocksStore } from '@wordpress/blocks';
+import { getBlockBindingsSource } from '@wordpress/blocks';
 
 /**
  * Internal dependencies
@@ -196,7 +196,6 @@ function ReusableBlockEdit( {
 		( select ) => {
 			const { getBlocks, getSettings, getBlockEditingMode } =
 				select( blockEditorStore );
-			const { getBlockBindingsSource } = unlock( select( blocksStore ) );
 			// For editing link to the site editor if the theme and user permissions support it.
 			return {
 				innerBlocks: getBlocks( patternClientId ),

diff --git a/packages/block-library/src/button/edit.js b/packages/block-library/src/button/edit.js
@@ -9,7 +9,6 @@ import clsx from 'clsx';
 import { NEW_TAB_TARGET, NOFOLLOW_REL } from './constants';
 import { getUpdatedLinkAttributes } from './get-updated-link-attributes';
 import removeAnchorTag from '../utils/remove-anchor-tag';
-import { unlock } from '../lock-unlock';
 
 /**
  * WordPress dependencies
@@ -45,7 +44,7 @@ import {
 	createBlock,
 	cloneBlock,
 	getDefaultBlockName,
-	store as blocksStore,
+	getBlockBindingsSource,
 } from '@wordpress/blocks';
 import { useMergeRefs, useRefEffect } from '@wordpress/compose';
 import { useSelect, useDispatch } from '@wordpress/data';
@@ -240,9 +239,9 @@ function ButtonEdit( props ) {
 				return {};
 			}
 
-			const blockBindingsSource = unlock(
-				select( blocksStore )
-			).getBlockBindingsSource( metadata?.bindings?.url?.source );
+			const blockBindingsSource = getBlockBindingsSource(
+				metadata?.bindings?.url?.source
+			);
 
 			return {
 				lockUrlControls:

diff --git a/packages/block-library/src/image/edit.js b/packages/block-library/src/image/edit.js
@@ -7,7 +7,7 @@ import clsx from 'clsx';
  * WordPress dependencies
  */
 import { isBlobURL, createBlobURL } from '@wordpress/blob';
-import { store as blocksStore, createBlock } from '@wordpress/blocks';
+import { createBlock, getBlockBindingsSource } from '@wordpress/blocks';
 import { Placeholder } from '@wordpress/components';
 import { useDispatch, useSelect } from '@wordpress/data';
 import {
@@ -28,7 +28,6 @@ import { useResizeObserver } from '@wordpress/compose';
 /**
  * Internal dependencies
  */
-import { unlock } from '../lock-unlock';
 import { useUploadMediaFromBlobURL } from '../utils/hooks';
 import Image from './image';
 import { isValidFileType } from './utils';
@@ -372,9 +371,9 @@ export function ImageEdit( {
 				return {};
 			}
 
-			const blockBindingsSource = unlock(
-				select( blocksStore )
-			).getBlockBindingsSource( metadata?.bindings?.url?.source );
+			const blockBindingsSource = getBlockBindingsSource(
+				metadata?.bindings?.url?.source
+			);
 
 			return {
 				lockUrlControls:

diff --git a/packages/block-library/src/image/image.js b/packages/block-library/src/image/image.js
@@ -34,7 +34,7 @@ import { useEffect, useMemo, useState, useRef } from '@wordpress/element';
 import { __, _x, sprintf, isRTL } from '@wordpress/i18n';
 import { DOWN } from '@wordpress/keycodes';
 import { getFilename } from '@wordpress/url';
-import { switchToBlockType, store as blocksStore } from '@wordpress/blocks';
+import { getBlockBindingsSource, switchToBlockType } from '@wordpress/blocks';
 import { crop, overlayText, upload } from '@wordpress/icons';
 import { store as noticesStore } from '@wordpress/notices';
 import { store as coreStore } from '@wordpress/core-data';
@@ -476,7 +476,6 @@ export default function Image( {
 			if ( ! isSingleSelected ) {
 				return {};
 			}
-			const { getBlockBindingsSource } = unlock( select( blocksStore ) );
 			const {
 				url: urlBinding,
 				alt: altBinding,

diff --git a/packages/blocks/README.md b/packages/blocks/README.md
@@ -115,6 +115,26 @@ _Returns_
 
 -   `string[]`: The attribute names that have the provided role.
 
+### getBlockBindingsSource
+
+Returns a registered block bindings source by its name.
+
+_Parameters_
+
+-   _name_ `string`: Block bindings source name.
+
+_Returns_
+
+-   `?Object`: Block bindings source.
+
+### getBlockBindingsSources
+
+Returns all registered block bindings sources.
+
+_Returns_
+
+-   `Array`: Block bindings sources.
+
 ### getBlockContent
 
 Given a block object, returns the Block's Inner HTML markup.
@@ -492,6 +512,36 @@ _Returns_
 
 -   `Array`: A list of blocks.
 
+### registerBlockBindingsSource
+
+Registers a new block bindings source with an object defining its behavior. Once registered, the source is available to be connected to the supported block attributes.
+
+_Usage_
+
+```js
+import { _x } from '@wordpress/i18n';
+import { registerBlockBindingsSource } from '@wordpress/blocks';
+
+registerBlockBindingsSource( {
+	name: 'plugin/my-custom-source',
+	label: _x( 'My Custom Source', 'block bindings source' ),
+	usesContext: [ 'postType' ],
+	getValues: getSourceValues,
+	setValues: updateMyCustomValuesInBatch,
+	canUserEditValue: () => true,
+} );
+```
+
+_Parameters_
+
+-   _source_ `Object`: Properties of the source to be registered.
+-   _source.name_ `string`: The unique and machine-readable name.
+-   _source.label_ `[string]`: Human-readable label. Optional when it is defined in the server.
+-   _source.usesContext_ `[Array]`: Optional array of context needed by the source only in the editor.
+-   _source.getValues_ `[Function]`: Optional function to get the values from the source.
+-   _source.setValues_ `[Function]`: Optional function to update multiple values connected to the source.
+-   _source.canUserEditValue_ `[Function]`: Optional function to determine if the user can edit the value.
+
 ### registerBlockCollection
 
 Registers a new block collection to group blocks in the same namespace in the inserter.
@@ -793,6 +843,22 @@ _Returns_
 
 -   `Array`: Updated Block list.
 
+### unregisterBlockBindingsSource
+
+Unregisters a block bindings source by providing its name.
+
+_Usage_
+
+```js
+import { unregisterBlockBindingsSource } from '@wordpress/blocks';
+
+unregisterBlockBindingsSource( 'plugin/my-custom-source' );
+```
+
+_Parameters_
+
+-   _name_ `string`: The name of the block bindings source to unregister.
+
 ### unregisterBlockStyle
 
 Unregisters a block style for the given block.