From 31cb1fc0c9b8d00d7896175565810a55c40ba509 Mon Sep 17 00:00:00 2001
From: Lena Morita <lena@jaguchi.com>
Date: Tue, 26 Nov 2024 03:14:15 +0900
Subject: [PATCH] Icon: Improve `icon` prop usage docs in Storybook

---
 .../src/icon/stories/index.story.tsx          | 60 ++++++++++++++++---
 1 file changed, 52 insertions(+), 8 deletions(-)

diff --git a/packages/components/src/icon/stories/index.story.tsx b/packages/components/src/icon/stories/index.story.tsx
index 7d61be8df7f3c..36d6314955666 100644
--- a/packages/components/src/icon/stories/index.story.tsx
+++ b/packages/components/src/icon/stories/index.story.tsx
@@ -47,26 +47,70 @@ FillColor.args = {
 	...Default.args,
 };
 
+/**
+ * When `icon` is a function, it will be passed the `size` prop and any other additional props.
+ */
 export const WithAFunction = Template.bind( {} );
 WithAFunction.args = {
 	...Default.args,
-	icon: () => (
-		<SVG>
-			<Path d="M5 4v3h5.5v12h3V7H19V4z" />
-		</SVG>
+	icon: ( { size }: { size?: number } ) => (
+		<img
+			width={ size }
+			height={ size }
+			src="https://s.w.org/style/images/about/WordPress-logotype-wmark.png"
+			alt="WordPress"
+		/>
 	),
 };
+WithAFunction.parameters = {
+	docs: {
+		source: {
+			code: `
+<Icon
+  icon={ ( { size } ) => (
+    <img
+      width={ size }
+      height={ size }
+      src="https://s.w.org/style/images/about/WordPress-logotype-wmark.png"
+      alt="WordPress"
+    />
+  ) }
+/>;
+		`,
+		},
+	},
+};
 
-const MyIconComponent = () => (
-	<SVG>
+const MyIconComponent = ( { size }: { size?: number } ) => (
+	<SVG width={ size } height={ size }>
 		<Path d="M5 4v3h5.5v12h3V7H19V4z" />
 	</SVG>
 );
 
+/**
+ * When `icon` is a component, it will be passed the `size` prop and any other additional props.
+ */
 export const WithAComponent = Template.bind( {} );
 WithAComponent.args = {
 	...Default.args,
-	icon: MyIconComponent,
+	icon: <MyIconComponent />,
+};
+WithAComponent.parameters = {
+	docs: {
+		source: {
+			code: `
+const MyIconComponent = ( { size } ) => (
+  <SVG width={ size } height={ size }>
+    <Path d="M5 4v3h5.5v12h3V7H19V4z" />
+  </SVG>
+);
+
+<Icon
+  icon={ <MyIconComponent /> }
+/>;
+		`,
+		},
+	},
 };
 
 export const WithAnSVG = Template.bind( {} );
@@ -80,7 +124,7 @@ WithAnSVG.args = {
 };
 
 /**
- * Although it's preferred to use icons from the `@wordpress/icons` package, Dashicons are still supported,
+ * Although it's preferred to use icons from the `@wordpress/icons` package, [Dashicons](https://developer.wordpress.org/resource/dashicons/) are still supported,
  * as long as you are in a context where the Dashicons stylesheet is loaded. To simulate that here,
  * use the Global CSS Injector in the Storybook toolbar at the top and select the "WordPress" preset.
  */