Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Block Editor: Add README for RecursionProvider #52334

Merged
merged 2 commits into from
Jul 5, 2023
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
101 changes: 101 additions & 0 deletions packages/block-editor/src/components/recursion-provider/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,101 @@
# RecursionProvider

According to Gutenberg's block rendering architecture, any block type capable of recursion should be responsible for handling its own infinite loops.

To help with detecting infinite loops on the client, the `RecursionProvider` component and the `useHasRecursion()` hook are used to identify if a block has already been rendered.

## Usage

```jsx
/**
* WordPress dependencies
*/
import {
__experimentalRecursionProvider as RecursionProvider,
__experimentalUseHasRecursion as useHasRecursion,
useBlockProps,
Warning,
} from '@wordpress/block-editor';
import { __ } from '@wordpress/i18n';

export default function MyRecursiveBlockEdit( { attributes: { ref } } ) {
const hasAlreadyRendered = useHasRecursion( ref );
const blockProps = useBlockProps( {
className: 'my-block__custom-class',
} );

if ( hasAlreadyRendered ) {
return (
<div { ...blockProps }>
<Warning>
{ __( 'Block cannot be rendered inside itself.' ) }
</Warning>
</div>
);
}

return (
<RecursionProvider uniqueId={ ref }>
Block editing code here....
</RecursionProvider>
);
}

/// ...

<MyRecursiveBlockEdit />;
```

## Props

The component accepts the following props:

### uniqueId

Any value that acts as a unique identifier for a block instance.

- Type: `any`
- Required: Yes

### children

Components to be rendered as content.

- Type: `Element`
- Required: Yes.

### blockName

Optional block name.

- Type: `String`
- Required: No
- Default: ''

# `useHasRecursion()`

Used in conjunction with `RecursionProvider`, this hook is used to identify if a block has already been rendered.

## Usage

For example usage, refer to the example above.

## Props

The component accepts the following props:

### uniqueId

Any value that acts as a unique identifier for a block instance.

- Type: `any`
- Required: Yes

### blockName

Optional block name.

- Type: `String`
- Required: No
- Default: ''