Doc: Add JSDoc and update README for BlockCard component (#68114)

* Add JSDoc and update README for BlockCard component * Docs: Improve BlockCard component JSDoc documentation * docs: Improve BlockCard component JSDoc documentation * Docs: Improve indentation of BlockCard component JSDoc documentation Co-authored-by: Infinite-Null <[email protected]> Co-authored-by: t-hamano <[email protected]>
WordPress · Dec 25, 2024 · ead6fac · ead6fac · github-actions · Dec 25, 2024
1 parent f226f7b
commit ead6fac
Show file tree

Hide file tree

Showing 2 changed files with 41 additions and 5 deletions.
diff --git 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
@@ -6,26 +6,55 @@ 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 { useDispatch, useSelect } from '@wordpress/data';
+import deprecated from '@wordpress/deprecated';
 import { __, isRTL } from '@wordpress/i18n';
-import { useSelect, useDispatch } from '@wordpress/data';
+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 );
 
+/**
+ * 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 (
+ *     <BlockCard
+ *       title="My Block"
+ *       icon="smiley"
+ *       description="A simple block example"
+ *       name="Custom Block"
+ *     />
+ *   );
+ * }
+ * ```
+ *
+ * @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}        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.
+ */
 function BlockCard( { title, icon, description, blockType, className, name } ) {
 	if ( blockType ) {
 		deprecated( '`blockType` property in `BlockCard component`', {