From ad9e2fcb7de20a6e7c8e211d9e008c3b797103d9 Mon Sep 17 00:00:00 2001 From: Ankit Kumar Shah Date: Thu, 19 Dec 2024 11:46:36 +0530 Subject: [PATCH 1/4] Add JSDoc and update README for BlockCard component --- .../src/components/block-card/README.md | 7 +++++ .../src/components/block-card/index.js | 29 +++++++++++++++++++ 2 files changed, 36 insertions(+) diff --git a/packages/block-editor/src/components/block-card/README.md b/packages/block-editor/src/components/block-card/README.md index 216cf4e3865a04..79a42bc20df74a 100644 --- a/packages/block-editor/src/components/block-card/README.md +++ b/packages/block-editor/src/components/block-card/README.md @@ -21,6 +21,7 @@ const MyBlockCard = () => ( icon={ paragraph } title="Paragraph" description="Start with the basic building block of all narrative." + name="Custom Block" /> ); ``` @@ -45,6 +46,12 @@ The title of the block. The description of the block. +#### name + +- **Type:** `String` + +The custom name of the block. + ## Related components Block Editor components are components that can be used to compose the UI of your block editor. Thus, they can only be used under a [`BlockEditorProvider`](https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/provider/README.md) in the components tree. diff --git a/packages/block-editor/src/components/block-card/index.js b/packages/block-editor/src/components/block-card/index.js index cdf52ee7df0311..0ce60fc88c8bb0 100644 --- a/packages/block-editor/src/components/block-card/index.js +++ b/packages/block-editor/src/components/block-card/index.js @@ -27,6 +27,35 @@ import { unlock } from '../../lock-unlock'; const { Badge } = unlock( componentsPrivateApis ); +/** + * A card component that displays block information including title, icon, and description. + * Can be used to show block metadata and navigation controls for parent blocks. + * + * @see https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/block-card/README.md + * + * @example + * ```jsx + * function Example() { + * return ( + * + * ); + * } + * ``` + * + * @param {Object} props Component props. + * @param {string} props.title The title of the block. + * @param {string|Object} props.icon Block icon component or string identifier. + * @param {string} props.description Optional description of the block. + * @param {Object} [props.blockType] Deprecated: Object containing block type data. + * @param {string} [props.className] Additional classes to apply to the card. + * @param {string} [props.name] Custom block name to display before the title. + * @return {Element} Block card component. + */ function BlockCard( { title, icon, description, blockType, className, name } ) { if ( blockType ) { deprecated( '`blockType` property in `BlockCard component`', { From 90a01800407c0005e755c92be35745de327f173b Mon Sep 17 00:00:00 2001 From: Ankit Kumar Shah Date: Tue, 24 Dec 2024 10:15:02 +0530 Subject: [PATCH 2/4] Docs: Improve BlockCard component JSDoc documentation --- packages/block-editor/src/components/block-card/index.js | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/packages/block-editor/src/components/block-card/index.js b/packages/block-editor/src/components/block-card/index.js index 0ce60fc88c8bb0..0d0713a9f0b7bb 100644 --- a/packages/block-editor/src/components/block-card/index.js +++ b/packages/block-editor/src/components/block-card/index.js @@ -49,12 +49,12 @@ const { Badge } = unlock( componentsPrivateApis ); * * @param {Object} props Component props. * @param {string} props.title The title of the block. - * @param {string|Object} props.icon Block icon component or string identifier. - * @param {string} props.description Optional description of the block. + * @param {string|Object} props.icon The icon of the block. This can be any of[WordPress Dashicons](https://developer.wordpress.org/resource/dashicons/), or a custom `svg` element. + * @param {string} props.description The description of the block. * @param {Object} [props.blockType] Deprecated: Object containing block type data. * @param {string} [props.className] Additional classes to apply to the card. * @param {string} [props.name] Custom block name to display before the title. - * @return {Element} Block card component. + * @return {Element} Block card component. */ function BlockCard( { title, icon, description, blockType, className, name } ) { if ( blockType ) { From baa6e8d636218630fc04cf2e444a572406f9415e Mon Sep 17 00:00:00 2001 From: Ankit Kumar Shah Date: Tue, 24 Dec 2024 11:39:04 +0530 Subject: [PATCH 3/4] docs: Improve BlockCard component JSDoc documentation --- .../src/components/block-card/index.js | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/packages/block-editor/src/components/block-card/index.js b/packages/block-editor/src/components/block-card/index.js index 0d0713a9f0b7bb..03b1c7b8b35f6b 100644 --- a/packages/block-editor/src/components/block-card/index.js +++ b/packages/block-editor/src/components/block-card/index.js @@ -6,24 +6,24 @@ import clsx from 'clsx'; /** * WordPress dependencies */ -import deprecated from '@wordpress/deprecated'; import { Button, __experimentalText as Text, __experimentalVStack as VStack, privateApis as componentsPrivateApis, } from '@wordpress/components'; -import { chevronLeft, chevronRight } from '@wordpress/icons'; -import { __, _x, isRTL, sprintf } from '@wordpress/i18n'; -import { useSelect, useDispatch } from '@wordpress/data'; +import { useDispatch, useSelect } from '@wordpress/data'; +import deprecated from '@wordpress/deprecated'; import { createInterpolateElement } from '@wordpress/element'; +import { __, _x, isRTL, sprintf } from '@wordpress/i18n'; +import { chevronLeft, chevronRight } from '@wordpress/icons'; /** * Internal dependencies */ -import BlockIcon from '../block-icon'; -import { store as blockEditorStore } from '../../store'; import { unlock } from '../../lock-unlock'; +import { store as blockEditorStore } from '../../store'; +import BlockIcon from '../block-icon'; const { Badge } = unlock( componentsPrivateApis ); @@ -49,12 +49,12 @@ const { Badge } = unlock( componentsPrivateApis ); * * @param {Object} props Component props. * @param {string} props.title The title of the block. - * @param {string|Object} props.icon The icon of the block. This can be any of[WordPress Dashicons](https://developer.wordpress.org/resource/dashicons/), or a custom `svg` element. + * @param {string|Object} props.icon The icon of the block. This can be any of [WordPress' Dashicons](https://developer.wordpress.org/resource/dashicons/), or a custom `svg` element. * @param {string} props.description The description of the block. * @param {Object} [props.blockType] Deprecated: Object containing block type data. * @param {string} [props.className] Additional classes to apply to the card. * @param {string} [props.name] Custom block name to display before the title. - * @return {Element} Block card component. + * @return {Element} Block card component. */ function BlockCard( { title, icon, description, blockType, className, name } ) { if ( blockType ) { From d5402869bbedfd5f9d8a0a5f7a0c3c1c5b014218 Mon Sep 17 00:00:00 2001 From: Ankit Kumar Shah Date: Tue, 24 Dec 2024 11:41:08 +0530 Subject: [PATCH 4/4] Docs: Improve indentation of BlockCard component JSDoc documentation --- packages/block-editor/src/components/block-card/index.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/block-editor/src/components/block-card/index.js b/packages/block-editor/src/components/block-card/index.js index 03b1c7b8b35f6b..8475ea540bff1c 100644 --- a/packages/block-editor/src/components/block-card/index.js +++ b/packages/block-editor/src/components/block-card/index.js @@ -54,7 +54,7 @@ const { Badge } = unlock( componentsPrivateApis ); * @param {Object} [props.blockType] Deprecated: Object containing block type data. * @param {string} [props.className] Additional classes to apply to the card. * @param {string} [props.name] Custom block name to display before the title. - * @return {Element} Block card component. + * @return {Element} Block card component. */ function BlockCard( { title, icon, description, blockType, className, name } ) { if ( blockType ) {