diff --git a/packages/block-editor/src/components/block-types-list/index.js b/packages/block-editor/src/components/block-types-list/index.js index 0be6f82a653d18..8c6215aad0dbb3 100644 --- a/packages/block-editor/src/components/block-types-list/index.js +++ b/packages/block-editor/src/components/block-types-list/index.js @@ -18,6 +18,38 @@ function chunk( array, size ) { return chunks; } +/** + * Renders a list of block types. + * + * @example + * ```jsx + * const items = [ + * { id: 'core/paragraph', icon: paragraph, title: 'Paragraph' }, + * { id: 'core/image', title: 'Image' }, + * ]; + * + * function MyBlockTypesList() { + * return ( + * console.log( 'Selected:', item ) } + * onHover={ ( item ) => console.log( 'Hovered:', item ) } + * label="Block types" + * isDraggable={ false } + * children={
Custom content
} + * /> + * + * ``` + * @param {Object} props Component props. + * @param {Array} props.items An array of block types to display. + * @param {Function} props.onSelect Callback function to call when a block type is selected. + * @param {Function} props.onHover Callback function to call when a block type is hovered. + * @param {string} props.label A label for the list. + * @param {boolean} props.isDraggable Whether the blocks are draggable. + * @param {JSX.Element} props.children Custom content to render at the end of the list + * + * @return {Element} The block types list component. + */ function BlockTypesList( { items = [], onSelect, diff --git a/packages/block-editor/src/components/block-types-list/stories/index.story.js b/packages/block-editor/src/components/block-types-list/stories/index.story.js new file mode 100644 index 00000000000000..6963e8f80544a5 --- /dev/null +++ b/packages/block-editor/src/components/block-types-list/stories/index.story.js @@ -0,0 +1,108 @@ +/** + * Internal dependencies + */ +import BlockTypesList from '..'; + +/** + * WordPress dependencies + */ +import { paragraph } from '@wordpress/icons'; +import { registerBlockType } from '@wordpress/blocks'; + +// Register block types +registerBlockType( 'core/paragraph', { + title: 'Paragraph', +} ); + +const meta = { + title: 'Components/BlockTypesList', + component: BlockTypesList, + parameters: { + docs: { + canvas: { sourceState: 'shown' }, + description: { + component: + 'BlockTypesList component displays a list of block types.', + }, + }, + }, + argTypes: { + items: { + description: 'An array of block types to display.', + table: { + type: { summary: 'Array' }, + }, + control: { + type: 'array', + }, + }, + onSelect: { + description: + 'Callback function to call when a block type is selected.', + table: { + type: { summary: 'Function' }, + }, + control: { + type: 'function', + }, + }, + onHover: { + description: + 'Callback function to call when a block type is hovered.', + table: { + type: { summary: 'Function' }, + }, + control: { + type: 'function', + }, + }, + label: { + description: 'A label for the list.', + table: { + type: { summary: 'String' }, + }, + control: { + type: 'text', + }, + }, + isDraggable: { + description: 'Whether the block types should be draggable.', + table: { + type: { summary: 'Boolean' }, + }, + control: { + type: 'boolean', + }, + }, + }, +}; + +export default meta; + +// Array of items for BlockTypesList +const items = [ + { + id: 'core/paragraph', + name: 'core/paragraph', + title: 'Paragraph', + icon: paragraph, + initialAttributes: { placeholder: 'Write something...' }, + innerBlocks: [], + isDisabled: false, + syncStatus: 'synced', + }, +]; + +// Fixed Default Story +export const Default = { + args: { + items, + onSelect: () => {}, + onHover: () => {}, + label: 'Blocks', + isDraggable: true, + }, + render: function Template( args ) { + return ; + }, +};