Docs: Add Block List Readme - #69432
Conversation
|
The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message. To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook. |
im3dabasia
left a comment
There was a problem hiding this comment.
Thanks for picking up this issue! @dhruvikpatel18 . Left a few feedbacks.
| ### Example | ||
|
|
||
| ```jsx | ||
| import BlockList from '@wordpress/block-editor/components/block-list'; |
There was a problem hiding this comment.
It’d be nice to replace this with the one below.
import { BlockList } from '@wordpress/block-editor';
| |---------------------------|------------|-------------| | ||
| | `rootClientId` | `string?` | The client ID of the root block whose inner blocks will be rendered. If omitted, renders the top-level blocks. | | ||
| | `placeholder` | `ReactNode?` | Placeholder content displayed when no blocks are present. | | ||
| | `renderAppender` | `Function?` | Custom function to render an appender component (e.g., the "+" button for adding new blocks). Defaults to the standard block appender. | |
There was a problem hiding this comment.
renderAppender accepts false to suppress the appender entirely . Currently the table only describes the function form. It'd be a nice idea to mention this as well.
Ref usage in style-book
There was a problem hiding this comment.
We also have a missing className prop. Please add it here, as it is directly consumed by the BlockList component.
| ## Related Components | ||
|
|
||
| - [`BlockListBlock`](./block) - Renders individual blocks within the `BlockList`. | ||
| - [`BlockListAppender`](../block-list-appender) - Provides UI for adding new blocks. |
There was a problem hiding this comment.
BlockListBlock and BlockListAppender don't have READMEs of their own, so these would end up as dead links once this is published.
Might be better to mention them as plain text for now, and link them up if/when those READMEs get added.
| ```jsx | ||
| import BlockList from '@wordpress/block-editor/components/block-list'; | ||
|
|
||
| function MyEditorComponent( props ) { |
There was a problem hiding this comment.
This example can be misleading because it doesn’t show the full picture of how this component can be used. Perhaps we could present it as just one example. What do you think?
import { BlockCanvas, BlockEditorProvider, BlockList } from '@wordpress/block-editor';
<BlockEditorProvider value={ blocks } onChange={ setBlocks }>
<BlockCanvas height="400px">
<BlockList className="my-editor-block-list" />
</BlockCanvas>
</BlockEditorProvider>;
Picked from here
| ## Notes | ||
|
|
||
| The `BlockList` component plays a crucial role in structuring the block editor. While it is used internally, developers working on extending or modifying the editor interface may need to interact with it for advanced customization. | ||
|
|
There was a problem hiding this comment.
Notes isn't a heading used anywhere else in this package, and the content here mostly repeats the opening of Usage above. Could the one new bit be folded into the intro paragraph and the section dropped?
Same thought for Features, most of the READMEs here use Development guidelines for that kind of prose.
im3dabasia
left a comment
There was a problem hiding this comment.
Thanks for the quick turnaround!
- The general structure of the README.md is incorrect. Could you switch it to follow our usual convention? This would keep the documentation consistent. Please update the PR accordingly.
# Component
## Development guidelines
### Usage
### Props
#### `exampleProp`
## Related components
| } from '@wordpress/block-editor'; | ||
|
|
||
| function MyEditor() { | ||
| const [ blocks, setBlocks ] = useState( [] ); |
There was a problem hiding this comment.
Nit: import { useState } from 'react';
| const [ blocks, setBlocks ] = useState( [] ); | ||
|
|
||
| return ( | ||
| <BlockEditorProvider value={ blocks } onChange={ setBlocks }> |
There was a problem hiding this comment.
With only onChange, non-persistent changes (typing inside a block) never reach blocks, so the parent state goes stale. Every canonical example passes both, WDYT about matching?
<BlockEditorProvider value={ blocks } onInput={ setBlocks } onChange={ setBlocks }>
| } | ||
| ``` | ||
|
|
||
| ## Props |
There was a problem hiding this comment.
Could we switch from the tabular format to per-prop subheadings with type/default bullets? This would help us achieve consistency!
|
|
||
| - `BlockListBlock` - Renders individual blocks within the `BlockList`. | ||
| - `BlockListAppender` - Provides UI for adding new blocks. | ||
| - [`useInnerBlocksProps`](../inner-blocks) - Hook for managing inner blocks and their props. |
There was a problem hiding this comment.
Let's remove the link altogether here. It points to the folder as of now, which makes little sense.
| | `rootClientId` | `string?` | The client ID of the root block whose inner blocks will be rendered. If omitted, renders the top-level blocks. | | ||
| | `placeholder` | `ReactNode?` | Placeholder content displayed when no blocks are present. | | ||
| | `renderAppender` | `Function \| false?` | Custom function to render an appender component (e.g., the "+" button for adding new blocks). Pass `false` to suppress the appender entirely. Defaults to the standard block appender. | | ||
| | `__experimentalAppenderTagName` | `string?` | Tag name for the appender element. | |
There was a problem hiding this comment.
Worth a short "experimental, may change without notice" note?
Minor, feel free to skip.
* Docs: Add Block List Readme. * Docs: Update Block List README with usage examples and prop descriptions * Docs: Restructure Block List README to match package conventions Co-authored-by: dhruvikpatel18 <dhruvik18@git.wordpress.org> Co-authored-by: im3dabasia <im3dabasia1@git.wordpress.org>
What?
Part of: #22891
Why?
This PR adds the README for Block List component
Testing Instructions
none
Screenshots or screencast
none