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 1 commit
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 us used to identify if a block has already been rendered.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Minor typo:

this hook us is used to identify

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good catch, thanks 🙌 Fixed in 6ff3fa5


## 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: ''