[PoC] Bindings API: handling data sync in the Model context

docs/manifest.json

@@ -1397,6 +1397,12 @@
 		"markdown_source": "../packages/base-styles/README.md",
 		"parent": "packages"
 	},
+	{
+		"title": "@wordpress/bindings",
+		"slug": "packages-bindings",
+		"markdown_source": "../packages/bindings/README.md",
+		"parent": "packages"
+	},
 	{
 		"title": "@wordpress/blob",
 		"slug": "packages-blob",

docs/reference-guides/data/data-core-block-editor.md

@@ -1555,6 +1555,36 @@ _Returns_
 
 -   `Object`: Action object.
 
+### resetBindingBlocks
+
+Creates an action to register a block's attribute binding to an external property.
+
+It registers a specific block attribute to be updated based on the value of an external property, identified by a unique key.
+
+_Parameters_
+
+-   _clientId_ `string`: - Block client ID.
+-   _attribute_ `string`: - The name of the block attribute to bind.
+-   _key_ `string`: - The key representing the external property.
+
+_Returns_
+
+-   `Object`: Redux 'RESET_BINDING_CONNECTION_BLOCKS' type action.
+
+### resetBlockBindingConnections
+
+Connect blocks with bound attributes to external data sources.
+
+Attributes specified in block metadata bindings are updated according to the corresponding external values.
+
+_Parameters_
+
+-   _blocks_ `Object`: - Blocks list.
+
+_Returns_
+
+-   `Function`: Returns a Redux thunk function that processes blocks and sets up bindings.
+
 ### resetBlocks
 
 Action that resets blocks state to the specified array of blocks, taking precedence over any other content reflected as an edit in state.
@@ -1796,6 +1826,10 @@ _Returns_
 
 -   `Object`: Action object.
 
+### unregisterBlockBinding
+
+Undocumented declaration.
+
 ### unsetBlockEditingMode
 
 Clears the block editing mode for a given block.
@@ -1839,6 +1873,10 @@ _Returns_
 
 -   `Object`: Action object.
 
+### updateBlockBoundAttributes
+
+Undocumented declaration.
+
 ### updateBlockListSettings
 
 Action that changes the nested settings of a given block.

package.json

@@ -26,6 +26,7 @@
 		"@wordpress/annotations": "file:packages/annotations",
 		"@wordpress/api-fetch": "file:packages/api-fetch",
 		"@wordpress/autop": "file:packages/autop",
+		"@wordpress/bindings": "file:packages/bindings",
 		"@wordpress/blob": "file:packages/blob",
 		"@wordpress/block-directory": "file:packages/block-directory",
 		"@wordpress/block-editor": "file:packages/block-editor",

packages/bindings/CHANGELOG.md

@@ -0,0 +1,3 @@
+<!-- Learn how to maintain this file at https://github.com/WordPress/gutenberg/tree/HEAD/packages#maintaining-changelogs. -->
+
+Initial release.

packages/bindings/README.md

@@ -0,0 +1 @@
+# Bindings API

packages/bindings/package.json

@@ -0,0 +1,39 @@
+{
+	"name": "@wordpress/bindings",
+	"version": "0.23.0",
+	"description": "Connect to external sources by using the Bindings API.",
+	"author": "The WordPress Contributors",
+	"license": "GPL-2.0-or-later",
+	"keywords": [
+		"wordpress",
+		"gutenberg",
+		"bindings"
+	],
+	"homepage": "https://github.com/WordPress/gutenberg/tree/HEAD/packages/bindings/README.md",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/WordPress/gutenberg.git",
+		"directory": "packages/bindings"
+	},
+	"bugs": {
+		"url": "https://github.com/WordPress/gutenberg/issues"
+	},
+	"engines": {
+		"node": ">=12"
+	},
+	"main": "build/index.js",
+	"module": "build-module/index.js",
+	"react-native": "src/index",
+	"dependencies": {
+		"@babel/runtime": "^7.16.0",
+		"@wordpress/data": "file:../data",
+		"@wordpress/private-apis": "file:../private-apis"
+	},
+	"peerDependencies": {
+		"react": "^18.0.0",
+		"react-dom": "^18.0.0"
+	},
+	"publishConfig": {
+		"access": "public"
+	}
+}

packages/bindings/src/index.js

@@ -0,0 +1 @@
+export { store } from './store';

packages/bindings/src/lock-unlock.js

@@ -0,0 +1,10 @@
+/**
+ * WordPress dependencies
+ */
+import { __dangerousOptInToUnstableAPIsOnlyForCoreModules } from '@wordpress/private-apis';
+
+export const { lock, unlock } =
+	__dangerousOptInToUnstableAPIsOnlyForCoreModules(
+		'I know using unstable features means my theme or plugin will inevitably break in the next version of WordPress.',
+		'@wordpress/commands'
+	);

packages/bindings/src/store/index.js

@@ -0,0 +1,37 @@
+/**
+ * WordPress dependencies
+ */
+import { createReduxStore, register } from '@wordpress/data';
+
+/**
+ * Internal dependencies
+ */
+import reducer from './reducer';
+import * as privateActions from './private-actions';
+import * as privateSelectors from './private-selectors';
+import { unlock } from '../lock-unlock';
+
+const STORE_NAME = 'core/bindings';
+
+/**
+ * Store definition for the bindings namespace.
+ *
+ * @see https://github.com/WordPress/gutenberg/blob/HEAD/packages/data/README.md#createReduxStore
+ *
+ * @type {Object}
+ *
+ * @example
+ * ```js
+ * import { store as bindingsStore } from '@wordpress/bindings';
+ * import { dispatch } from '@wordpress/data';
+ *
+ * const { registerBindingsSource } = dispatch( bindingsStore );
+ * ```
+ */
+export const store = createReduxStore( STORE_NAME, {
+	reducer,
+} );
+
+register( store );
+unlock( store ).registerPrivateActions( privateActions );
+unlock( store ).registerPrivateSelectors( privateSelectors );

packages/bindings/src/store/private-actions.js

@@ -0,0 +1,107 @@
+/**
+ * Internal dependencies
+ */
+import { generateBindingsConnectionKey } from './utils';
+
+/**
+ * Register an external source
+ *
+ * @param {string} source Name of the source to register.
+ */
+export function registerBindingsSource( source ) {
+	return {
+		type: 'REGISTER_BINDINGS_SOURCE',
+		...source,
+	};
+}
+
+/**
+ * Sets up a subscription to monitor changes
+ * in a specified bindings connection.
+ *
+ * @param {string}   key              - The key identifying the bindings connection to observe.
+ * @param {Function} [updateCallback] - Optional callback invoked when the observed property changes.
+ * @return {Function}                   Thunk.
+ */
+export function observeBindingsConnectionChange( key, updateCallback ) {
+	return ( { select, registry, dispatch } ) => {
+		const handler = select.getBindingsConnectionHandler( key );
+		let currentValue = handler.get();
+
+		function watchValueChanges() {
+			const value = select.getBindingsConnectionValue( key );
+			if ( value === currentValue ) {
+				return;
+			}
+
+			currentValue = value;
+			updateCallback?.( value );
+		}
+
+		dispatch( {
+			type: 'UPDATE_BINDINGS_CONNECTION',
+			key,
+			unsubscribe: registry.subscribe( watchValueChanges ),
+		} );
+	};
+}
+
+/**
+ * Registers a connection to a bindings source.
+ * The connection is established by a combination
+ * of the source handler name and the binding arguments.
+ *
+ * @param {Object}   settings        - Settings.
+ * @param {string}   settings.source - The source handler name.
+ * @param {Object}   settings.args   - The binding arguments.
+ * @param {Function} updateCallback  - Callback invoked when the connection value changes.
+ * @return {Function}                  Thunk function for Redux dispatch, registers the connection.
+ */
+export function registerBindingsConnection( { source, args }, updateCallback ) {
+	return ( { dispatch, select } ) => {
+		const settings = select.getBindingsSource( source );
+		if ( ! settings ) {
+			return;
+		}
+
+		// Do not register if it's already registered.
+		const key = generateBindingsConnectionKey( { source, args } );
+		if ( select.getBindingsConnectionHandler( key ) ) {
+			return;
+		}
+
+		const { connect } = settings;
+		const handler = connect( args );
+
+		dispatch( {
+			type: 'REGISTER_BINDINGS_CONNECTION',
+			key,
+			...handler,
+		} );
+
+		/*
+		 * Observe the external property to monitor changes.
+		 * To do: scale this to register multiple callbacks.
+		 */
+		dispatch.observeBindingsConnectionChange( key, updateCallback );
+	};
+}
+
+/**
+ * Updates the value of a bindings connection.
+ * The connection is identified by the connection key.
+ *
+ * @param {string} key   - The connection key.
+ * @param {*}      value - The new value.
+ * @return {Function}     Thunk function for Redux dispatch, updates the connection value.
+ */
+export function updateBindingsConnectionValue( key, value ) {
+	return ( { select } ) => {
+		const bindingsConnection = select.getBindingsConnectionHandler( key );
+		if ( ! bindingsConnection ) {
+			return;
+		}
+
+		bindingsConnection.update( value );
+	};
+}