From ead6fac91b1819d4e63db58c54e295ed0a743c4c Mon Sep 17 00:00:00 2001
From: Ankit Kumar Shah <ankit.shah@rtcamp.com>
Date: Wed, 25 Dec 2024 11:42:11 +0530
Subject: [PATCH] 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 <ankitkumarshah@git.wordpress.org>
Co-authored-by: t-hamano <wildworks@git.wordpress.org>
---
 .../src/components/block-card/README.md       |  7 ++++
 .../src/components/block-card/index.js        | 39 ++++++++++++++++---
 2 files changed, 41 insertions(+), 5 deletions(-)

diff --git a/packages/block-editor/src/components/block-card/README.md b/packages/block-editor/src/components/block-card/README.md
index 216cf4e3865a0..79a42bc20df74 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 988dcfb2216b2..525a594702e30 100644
--- 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`', {