Block editor: Stabilise RecursionProvider and useHasRecursion APIs

packages/block-editor/CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## Unreleased
 
+- Deprecated `__experimentalRecursionProvider` and `__experimentalUseHasRecursion` in favor of their new stable counterparts `RecursionProvider` and `useHasRecursion`.
+
 ## 12.17.0 (2024-01-10)
 
 ## 12.16.0 (2023-12-13)

packages/block-editor/README.md

@@ -707,6 +707,23 @@ _Related_
 
 Private @wordpress/block-editor APIs.
 
+### RecursionProvider
+
+A React context provider for use with the `useHasRecursion` hook to prevent recursive renders.
+
+Wrap block content with this provider and provide the same `uniqueId` prop as used with `useHasRecursion`.
+
+_Parameters_
+
+-   _props_ `Object`:
+-   _props.uniqueId_ `*`: Any value that acts as a unique identifier for a block instance.
+-   _props.blockName_ `string`: Optional block name.
+-   _props.children_ `JSX.Element`: React children.
+
+_Returns_
+
+-   `JSX.Element`: A React element.
+
 ### ReusableBlocksRenameHint
 
 Undocumented declaration.
@@ -941,6 +958,21 @@ _Returns_
 
 -   `any`: value
 
+### useHasRecursion
+
+A React hook for keeping track of blocks previously rendered up in the block tree. Blocks susceptible to recursion can use this hook in their `Edit` function to prevent said recursion.
+
+Use this with the `RecursionProvider` component, using the same `uniqueId` value for both the hook and the provider.
+
+_Parameters_
+
+-   _uniqueId_ `*`: Any value that acts as a unique identifier for a block instance.
+-   _blockName_ `string`: Optional block name.
+
+_Returns_
+
+-   `boolean`: A boolean describing whether the provided id has already been rendered.
+
 ### useInnerBlocksProps
 
 This hook is used to lightly mark an element as an inner blocks wrapper element. Call this hook and pass the returned props to the element to mark as an inner blocks wrapper, automatically rendering inner blocks as children. If you define a ref for the element, it is important to pass the ref to this hook, which the hook in turn will pass to the component through the props it returns. Optionally, you can also pass any other props through this hook, and they will be merged and returned.

packages/block-editor/src/components/index.js

@@ -152,8 +152,10 @@ export { default as WritingFlow } from './writing-flow';
 export { default as useBlockDisplayInformation } from './use-block-display-information';
 export { default as __unstableIframe } from './iframe';
 export {
-	RecursionProvider as __experimentalRecursionProvider,
-	useHasRecursion as __experimentalUseHasRecursion,
+	RecursionProvider,
+	DeprecatedExperimentalRecursionProvider as __experimentalRecursionProvider,
+	useHasRecursion,
+	DeprecatedExperimentalUseHasRecursion as __experimentalUseHasRecursion,
 } from './recursion-provider';
 export { default as __experimentalBlockPatternsList } from './block-patterns-list';
 export { default as __experimentalPublishDateTimePicker } from './publish-date-time-picker';

packages/block-editor/src/components/index.native.js

@@ -61,8 +61,10 @@ export { default as PanelColorSettings } from './panel-color-settings';
 export { default as __experimentalPanelColorGradientSettings } from './colors-gradients/panel-color-gradient-settings';
 export { useSettings, default as useSetting } from './use-settings';
 export {
-	RecursionProvider as __experimentalRecursionProvider,
-	useHasRecursion as __experimentalUseHasRecursion,
+	RecursionProvider,
+	DeprecatedExperimentalRecursionProvider as __experimentalRecursionProvider,
+	useHasRecursion,
+	DeprecatedExperimentalUseHasRecursion as __experimentalUseHasRecursion,
 } from './recursion-provider';
 export { default as Warning } from './warning';
 export { default as ContrastChecker } from './contrast-checker';

packages/block-editor/src/components/recursion-provider/README.md

@@ -11,8 +11,8 @@ To help with detecting infinite loops on the client, the `RecursionProvider` com
  * WordPress dependencies
  */
 import {
-	__experimentalRecursionProvider as RecursionProvider,
-	__experimentalUseHasRecursion as useHasRecursion,
+	RecursionProvider,
+	useHasRecursion,
 	useBlockProps,
 	Warning,
 } from '@wordpress/block-editor';

packages/block-editor/src/components/recursion-provider/index.js

@@ -2,6 +2,7 @@
  * WordPress dependencies
  */
 import { createContext, useContext, useMemo } from '@wordpress/element';
+import deprecated from '@wordpress/deprecated';
 
 /**
  * Internal dependencies
@@ -82,3 +83,19 @@ export function useHasRecursion( uniqueId, blockName = '' ) {
 	blockName = blockName || name;
 	return Boolean( previouslyRenderedBlocks[ blockName ]?.has( uniqueId ) );
 }
+
+export const DeprecatedExperimentalRecursionProvider = ( props ) => {
+	deprecated( 'wp.blockEditor.__experimentalRecursionProvider', {
+		since: '6.5',
+		alternative: 'wp.blockEditor.RecursionProvider',
+	} );
+	return <RecursionProvider { ...props } />;
+};
+
+export const DeprecatedExperimentalUseHasRecursion = ( props ) => {
+	deprecated( 'wp.blockEditor.__experimentalUseHasRecursion', {
+		since: '6.5',
+		alternative: 'wp.blockEditor.useHasRecursion',
+	} );
+	return useHasRecursion( ...props );
+};

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

@@ -18,8 +18,8 @@ import {
 import { __ } from '@wordpress/i18n';
 import {
 	useInnerBlocksProps,
-	__experimentalRecursionProvider as RecursionProvider,
-	__experimentalUseHasRecursion as useHasRecursion,
+	RecursionProvider,
+	useHasRecursion,
 	InnerBlocks,
 	useBlockProps,
 	Warning,

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

@@ -20,8 +20,8 @@ import {
 import { __ } from '@wordpress/i18n';
 import {
 	useInnerBlocksProps,
-	__experimentalRecursionProvider as RecursionProvider,
-	__experimentalUseHasRecursion as useHasRecursion,
+	RecursionProvider,
+	useHasRecursion,
 	InnerBlocks,
 	InspectorControls,
 	useBlockProps,

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

@@ -27,8 +27,8 @@ import {
 import { useSelect, useDispatch } from '@wordpress/data';
 import { __, sprintf } from '@wordpress/i18n';
 import {
-	__experimentalRecursionProvider as RecursionProvider,
-	__experimentalUseHasRecursion as useHasRecursion,
+	RecursionProvider,
+	useHasRecursion,
 	InnerBlocks,
 	Warning,
 	store as blockEditorStore,

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

@@ -16,8 +16,8 @@ import {
 import {
 	InspectorControls,
 	useBlockProps,
-	__experimentalRecursionProvider as RecursionProvider,
-	__experimentalUseHasRecursion as useHasRecursion,
+	RecursionProvider,
+	useHasRecursion,
 	store as blockEditorStore,
 	withColors,
 	ContrastChecker,

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

@@ -5,8 +5,8 @@ import { __ } from '@wordpress/i18n';
 import {
 	useBlockProps,
 	useInnerBlocksProps,
-	__experimentalRecursionProvider as RecursionProvider,
-	__experimentalUseHasRecursion as useHasRecursion,
+	RecursionProvider,
+	useHasRecursion,
 	Warning,
 } from '@wordpress/block-editor';
 import {

packages/block-library/src/template-part/edit/index.js

@@ -7,8 +7,8 @@ import {
 	useBlockProps,
 	Warning,
 	store as blockEditorStore,
-	__experimentalRecursionProvider as RecursionProvider,
-	__experimentalUseHasRecursion as useHasRecursion,
+	RecursionProvider,
+	useHasRecursion,
 	InspectorControls,
 } from '@wordpress/block-editor';
 import { Spinner, Modal, MenuItem } from '@wordpress/components';

packages/editor/src/components/editor-canvas/index.js

@@ -12,7 +12,7 @@ import {
 	__unstableUseTypewriter as useTypewriter,
 	__unstableUseTypingObserver as useTypingObserver,
 	useSettings,
-	__experimentalRecursionProvider as RecursionProvider,
+	RecursionProvider,
 	privateApis as blockEditorPrivateApis,
 	__experimentalUseResizeCanvas as useResizeCanvas,
 } from '@wordpress/block-editor';