@wordpress/data: Introduce new custom useDispatch react hook

packages/data/README.md

@@ -486,6 +486,52 @@ _Parameters_
 
 -   _plugin_ `Object`: Plugin object.
 
+<a name="useDispatch" href="#useDispatch">#</a> **useDispatch**
+
+A custom react hook returning the current registry dispatch actions creators.
+
+Note: The component using this hook must be within the context of a
+RegistryProvider.
+
+_Usage_
+
+This illustrates a pattern where you may need to retrieve dynamic data from
+the server via the `useSelect` hook to use in combination with the dispatch
+action.
+
+```jsx
+const { useDispatch, useSelect } = wp.data;
+const { useCallback } = wp.element;
+
+function Button( { onClick, children } ) {
+  return <button type="button" onClick={ onClick }>{ children }</button>
+}
+
+const SaleButton = ( { children } ) => {
+  const { stockNumber } = useSelect(
+  	( select ) => select( 'my-shop' ).getStockNumber()
+  );
+  const { startSale } = useDispatch( 'my-shop' );
+	 const onClick = useCallback( () => {
+	   const discountPercent = stockNumber > 50 ? 10: 20;
+	   startSale( discountPercent );
+	 }, [ stockNumber ] );
+	 return <Button onClick={ onClick }>{ children }</Button>
+}
+
+// Rendered somewhere in the application:
+//
+// <SaleButton>Start Sale!</SaleButton>
+```
+
+_Parameters_
+
+-   _storeName_ `?string`: Optionally provide the name of the store from which to retrieve action creators. If not provided, the registry.dispatch function is returned instead.
+
+_Returns_
+
+-   `Function`: A custom react hook.
+
 <a name="useRegistry" href="#useRegistry">#</a> **useRegistry**
 
 A custom react hook exposing the registry context for use.

packages/data/src/components/use-dispatch/index.js

@@ -0,0 +1,2 @@
+export { default as useDispatch } from './use-dispatch';
+export { default as useDispatchWithMap } from './use-dispatch-with-map';

packages/data/src/components/use-dispatch/use-dispatch-with-map.js

@@ -0,0 +1,71 @@
+/**
+ * External dependencies
+ */
+import { mapValues } from 'lodash';
+
+/**
+ * WordPress dependencies
+ */
+import { useMemo, useRef, useEffect, useLayoutEffect } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import useRegistry from '../registry-provider/use-registry';
+
+/**
+ * Favor useLayoutEffect to ensure the store subscription callback always has
+ * the dispatchMap from the latest render. If a store update happens between
+ * render and the effect, this could cause missed/stale updates or
+ * inconsistent state.
+ *
+ * Fallback to useEffect for server rendered components because currently React
+ * throws a warning when using useLayoutEffect in that environment.
+ */
+const useIsomorphicLayoutEffect =
+	typeof window !== 'undefined' ? useLayoutEffect : useEffect;
+
+/**
+ * Custom react hook for returning aggregate dispatch actions using the provided
+ * dispatchMap.
+ *
+ * Currently this is an internal api only and is implemented by `withDispatch`
+ *
+ * @param {Function} dispatchMap  Receives the `registry.dispatch` function as
+ *                                the first argument and the `registry` object
+ *                                as the second argument.  Should return an
+ *                                object mapping props to functions.
+ * @param {Array}    deps         An array of dependencies for the hook.
+ * @return {Object}  An object mapping props to functions created by the passed
+ *                   in dispatchMap.
+ */
+const useDispatchWithMap = ( dispatchMap, deps ) => {
+	const registry = useRegistry();
+	const currentDispatchMap = useRef( dispatchMap );
+
+	useIsomorphicLayoutEffect( () => {
+		currentDispatchMap.current = dispatchMap;
+	} );
+
+	return useMemo( () => {
+		const currentDispatchProps = currentDispatchMap.current(
+			registry.dispatch,
+			registry
+		);
+		return mapValues(
+			currentDispatchProps,
+			( dispatcher, propName ) => {
+				if ( typeof dispatcher !== 'function' ) {
+					// eslint-disable-next-line no-console
+					console.warn(
+						`Property ${ propName } returned from dispatchMap in useDispatchWithMap must be a function.`
+					);
+				}
+				return ( ...args ) => currentDispatchMap
+					.current( registry.dispatch, registry )[ propName ]( ...args );
+			}
+		);
+	}, [ registry, ...deps ] );
+};
+
+export default useDispatchWithMap;

packages/data/src/components/use-dispatch/use-dispatch.js

@@ -0,0 +1,53 @@
+/**
+ * Internal dependencies
+ */
+import useRegistry from '../registry-provider/use-registry';
+
+/**
+ * A custom react hook returning the current registry dispatch actions creators.
+ *
+ * Note: The component using this hook must be within the context of a
+ * RegistryProvider.
+ *
+ * @param {?string} storeName  Optionally provide the name of the store from
+ *                             which to retrieve action creators. If not
+ *                             provided, the registry.dispatch function is
+ *                             returned instead.
+ *
+ * @example
+ * This illustrates a pattern where you may need to retrieve dynamic data from
+ * the server via the `useSelect` hook to use in combination with the dispatch
+ * action.
+ *
+ * ```jsx
+ * const { useDispatch, useSelect } = wp.data;
+ * const { useCallback } = wp.element;
+ *
+ * function Button( { onClick, children } ) {
+ *   return <button type="button" onClick={ onClick }>{ children }</button>
+ * }
+ *
+ * const SaleButton = ( { children } ) => {
+ *   const { stockNumber } = useSelect(
+ *   	( select ) => select( 'my-shop' ).getStockNumber()
+ *   );
+ *   const { startSale } = useDispatch( 'my-shop' );
+ * 	 const onClick = useCallback( () => {
+ * 	   const discountPercent = stockNumber > 50 ? 10: 20;
+ * 	   startSale( discountPercent );
+ * 	 }, [ stockNumber ] );
+ * 	 return <Button onClick={ onClick }>{ children }</Button>
+ * }
+ *
+ * // Rendered somewhere in the application:
+ * //
+ * // <SaleButton>Start Sale!</SaleButton>
+ * ```
+ * @return {Function}  A custom react hook.
+ */
+const useDispatch = ( storeName ) => {
+	const { dispatch } = useRegistry();
+	return storeName === void 0 ? dispatch : dispatch( storeName );
+};
+
+export default useDispatch;

packages/data/src/components/with-dispatch/index.js

@@ -1,18 +1,12 @@
-/**
- * External dependencies
- */
-import { mapValues } from 'lodash';
-
 /**
  * WordPress dependencies
  */
-import { Component } from '@wordpress/element';
-import { createHigherOrderComponent } from '@wordpress/compose';
+import { pure, createHigherOrderComponent } from '@wordpress/compose';
 
 /**
  * Internal dependencies
  */
-import { RegistryConsumer } from '../registry-provider';
+import { useDispatchWithMap } from '../use-dispatch';
 
 /**
  * Higher-order component used to add dispatch props using registered action creators.
@@ -79,61 +73,17 @@ import { RegistryConsumer } from '../registry-provider';
  * @return {Component} Enhanced component with merged dispatcher props.
  */
 const withDispatch = ( mapDispatchToProps ) => createHigherOrderComponent(
-	( WrappedComponent ) => {
-		class ComponentWithDispatch extends Component {
-			constructor( props ) {
-				super( ...arguments );
-
-				this.proxyProps = {};
-
-				this.setProxyProps( props );
-			}
-
-			proxyDispatch( propName, ...args ) {
-				// Original dispatcher is a pre-bound (dispatching) action creator.
-				mapDispatchToProps( this.props.registry.dispatch, this.props.ownProps, this.props.registry )[ propName ]( ...args );
-			}
-
-			setProxyProps( props ) {
-				// Assign as instance property so that in subsequent render
-				// reconciliation, the prop values are referentially equal.
-				// Importantly, note that while `mapDispatchToProps` is
-				// called, it is done only to determine the keys for which
-				// proxy functions should be created. The actual registry
-				// dispatch does not occur until the function is called.
-				const propsToDispatchers = mapDispatchToProps( this.props.registry.dispatch, props.ownProps, this.props.registry );
-				this.proxyProps = mapValues( propsToDispatchers, ( dispatcher, propName ) => {
-					if ( typeof dispatcher !== 'function' ) {
-						// eslint-disable-next-line no-console
-						console.warn( `Property ${ propName } returned from mapDispatchToProps in withDispatch must be a function.` );
-					}
-					// Prebind with prop name so we have reference to the original
-					// dispatcher to invoke. Track between re-renders to avoid
-					// creating new function references every render.
-					if ( this.proxyProps.hasOwnProperty( propName ) ) {
-						return this.proxyProps[ propName ];
-					}
-
-					return this.proxyDispatch.bind( this, propName );
-				} );
-			}
-
-			render() {
-				return <WrappedComponent { ...this.props.ownProps } { ...this.proxyProps } />;
-			}
+	( WrappedComponent ) => pure(
+		( ownProps ) => {
+			const mapDispatch = ( dispatch, registry ) => mapDispatchToProps(
+				dispatch,
+				ownProps,
+				registry
+			);
+			const dispatchProps = useDispatchWithMap( mapDispatch, [] );
+			return <WrappedComponent { ...ownProps } { ...dispatchProps } />;
 		}
-
-		return ( ownProps ) => (
-			<RegistryConsumer>
-				{ ( registry ) => (
-					<ComponentWithDispatch
-						ownProps={ ownProps }
-						registry={ registry }
-					/>
-				) }
-			</RegistryConsumer>
-		);
-	},
+	),
 	'withDispatch'
 );
 

packages/data/src/index.js

@@ -18,6 +18,7 @@ export {
 	useRegistry,
 } from './components/registry-provider';
 export { default as useSelect } from './components/use-select';
+export { useDispatch } from './components/use-dispatch';
 export {
 	AsyncModeProvider as __experimentalAsyncModeProvider,
 } from './components/async-mode-provider';