From e0d8c9dfc0e48c5415892ba83782d14c1c9f2f1f Mon Sep 17 00:00:00 2001 From: Miguel Fonseca <150562+mcsf@users.noreply.github.com> Date: Tue, 23 Jan 2024 12:09:24 +0000 Subject: [PATCH] Block editor: Stabilize RecursionProvider and useHasRecursion APIs Addresses #57672 --- packages/block-editor/CHANGELOG.md | 2 ++ packages/block-editor/README.md | 32 +++++++++++++++++++ packages/block-editor/src/components/index.js | 6 ++-- .../src/components/index.native.js | 6 ++-- .../components/recursion-provider/README.md | 4 +-- .../components/recursion-provider/index.js | 17 ++++++++++ packages/block-library/src/block/edit.js | 4 +-- packages/block-library/src/block/v1/edit.js | 4 +-- .../block-library/src/block/v1/edit.native.js | 4 +-- .../src/navigation/edit/index.js | 4 +-- .../block-library/src/post-content/edit.js | 4 +-- .../src/template-part/edit/index.js | 4 +-- .../src/components/editor-canvas/index.js | 2 +- 13 files changed, 74 insertions(+), 19 deletions(-) diff --git a/packages/block-editor/CHANGELOG.md b/packages/block-editor/CHANGELOG.md index a66143dd30ac9..ec4793ec970ee 100644 --- a/packages/block-editor/CHANGELOG.md +++ b/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) diff --git a/packages/block-editor/README.md b/packages/block-editor/README.md index 5917ac235505c..6fc51d8451212 100644 --- a/packages/block-editor/README.md +++ b/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. diff --git a/packages/block-editor/src/components/index.js b/packages/block-editor/src/components/index.js index 08247d8cdb014..5263ca3332b25 100644 --- a/packages/block-editor/src/components/index.js +++ b/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'; diff --git a/packages/block-editor/src/components/index.native.js b/packages/block-editor/src/components/index.native.js index 21a9b1114ce5f..ac4b45af3609c 100644 --- a/packages/block-editor/src/components/index.native.js +++ b/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'; diff --git a/packages/block-editor/src/components/recursion-provider/README.md b/packages/block-editor/src/components/recursion-provider/README.md index 4538fd6a7d350..37af15d75c191 100644 --- a/packages/block-editor/src/components/recursion-provider/README.md +++ b/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'; diff --git a/packages/block-editor/src/components/recursion-provider/index.js b/packages/block-editor/src/components/recursion-provider/index.js index 2c38087a8731d..4f462cb33ef2a 100644 --- a/packages/block-editor/src/components/recursion-provider/index.js +++ b/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 ; +}; + +export const DeprecatedExperimentalUseHasRecursion = ( props ) => { + deprecated( 'wp.blockEditor.__experimentalUseHasRecursion', { + since: '6.5', + alternative: 'wp.blockEditor.useHasRecursion', + } ); + return useHasRecursion( ...props ); +}; diff --git a/packages/block-library/src/block/edit.js b/packages/block-library/src/block/edit.js index c53f52bfb703e..cd04e09605ff4 100644 --- a/packages/block-library/src/block/edit.js +++ b/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, diff --git a/packages/block-library/src/block/v1/edit.js b/packages/block-library/src/block/v1/edit.js index 5975711376c65..aa8f680c83792 100644 --- a/packages/block-library/src/block/v1/edit.js +++ b/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, diff --git a/packages/block-library/src/block/v1/edit.native.js b/packages/block-library/src/block/v1/edit.native.js index 3a649921b3dda..9077988456b70 100644 --- a/packages/block-library/src/block/v1/edit.native.js +++ b/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, diff --git a/packages/block-library/src/navigation/edit/index.js b/packages/block-library/src/navigation/edit/index.js index 5589e8ea9e60f..14ef6fc73d48f 100644 --- a/packages/block-library/src/navigation/edit/index.js +++ b/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, diff --git a/packages/block-library/src/post-content/edit.js b/packages/block-library/src/post-content/edit.js index ae3bb938c90ee..041a3b4fa02f6 100644 --- a/packages/block-library/src/post-content/edit.js +++ b/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 { diff --git a/packages/block-library/src/template-part/edit/index.js b/packages/block-library/src/template-part/edit/index.js index ec92996978bd6..72fc06338e780 100644 --- a/packages/block-library/src/template-part/edit/index.js +++ b/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'; diff --git a/packages/editor/src/components/editor-canvas/index.js b/packages/editor/src/components/editor-canvas/index.js index d6084ef922805..a06c8096134cf 100644 --- a/packages/editor/src/components/editor-canvas/index.js +++ b/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';