From 0e96bf0613600833965a3baefd8c65afb9f16114 Mon Sep 17 00:00:00 2001
From: Marco Ciampini <marco.ciampo@gmail.com>
Date: Wed, 2 Oct 2024 10:51:27 +0200
Subject: [PATCH 1/6] Composite: add "With Tooltip" storybook example

---
 .../src/composite/stories/index.story.tsx     | 48 +++++++++++++++++++
 1 file changed, 48 insertions(+)

diff --git a/packages/components/src/composite/stories/index.story.tsx b/packages/components/src/composite/stories/index.story.tsx
index d6e4999407e993..d9cfee8b5a6826 100644
--- a/packages/components/src/composite/stories/index.story.tsx
+++ b/packages/components/src/composite/stories/index.story.tsx
@@ -13,6 +13,7 @@ import { useContext, useMemo } from '@wordpress/element';
  */
 import { createSlotFill, Provider as SlotFillProvider } from '../../slot-fill';
 import { Composite } from '..';
+import { Tooltip } from '../../tooltip';
 
 const meta: Meta< typeof Composite > = {
 	title: 'Components/Composite',
@@ -353,3 +354,50 @@ const Fill = ( { children } ) => {
 		},
 	},
 };
+
+/**
+ * Combining the `Tooltip` and `Composite` component has a few caveats.
+ * For example, the following code won't work as expected:
+ *
+ * ```jsx
+ * <Composite.Item
+ *   render={
+ *   <Tooltip text="Tooltip">
+ *     <button>Button</button>
+ *   </Tooltip>
+ * ```
+ *
+ * Take a look at this story's source code to see how to correctly compose
+ * these two components.
+ */
+export const WithTooltips: StoryObj< typeof Composite > = {
+	...Default,
+	args: {
+		...Default.args,
+		children: (
+			<>
+				<Tooltip text="Tooltip one">
+					<Composite.Item render={ <button /> }>
+						Item one
+					</Composite.Item>
+				</Tooltip>
+				<Composite.Item
+					render={ ( props ) => (
+						<Tooltip text="Tooltip two">
+							<button { ...props }>Item two</button>
+						</Tooltip>
+					) }
+				/>
+				<Composite.Item
+					render={ ( props ) => (
+						<Tooltip text="Tooltip three">
+							<button { ...props } />
+						</Tooltip>
+					) }
+				>
+					Item three
+				</Composite.Item>
+			</>
+		),
+	},
+};

From b31764828cdd835fbffd39251d8c0ab22d65b978 Mon Sep 17 00:00:00 2001
From: Marco Ciampini <marco.ciampo@gmail.com>
Date: Wed, 2 Oct 2024 18:04:38 +0200
Subject: [PATCH 2/6] Only use one way to compose Tooltip and Composite

---
 .../src/composite/stories/index.story.tsx     | 26 +++++++------------
 1 file changed, 10 insertions(+), 16 deletions(-)

diff --git a/packages/components/src/composite/stories/index.story.tsx b/packages/components/src/composite/stories/index.story.tsx
index d9cfee8b5a6826..b77768b98bf2b4 100644
--- a/packages/components/src/composite/stories/index.story.tsx
+++ b/packages/components/src/composite/stories/index.story.tsx
@@ -381,22 +381,16 @@ export const WithTooltips: StoryObj< typeof Composite > = {
 						Item one
 					</Composite.Item>
 				</Tooltip>
-				<Composite.Item
-					render={ ( props ) => (
-						<Tooltip text="Tooltip two">
-							<button { ...props }>Item two</button>
-						</Tooltip>
-					) }
-				/>
-				<Composite.Item
-					render={ ( props ) => (
-						<Tooltip text="Tooltip three">
-							<button { ...props } />
-						</Tooltip>
-					) }
-				>
-					Item three
-				</Composite.Item>
+				<Tooltip text="Tooltip two">
+					<Composite.Item render={ <button /> }>
+						Item two
+					</Composite.Item>
+				</Tooltip>
+				<Tooltip text="Tooltip three">
+					<Composite.Item render={ <button /> }>
+						Item three
+					</Composite.Item>
+				</Tooltip>
 			</>
 		),
 	},

From 9e31128548344b85da769fc7b2bb5b936d5b88b6 Mon Sep 17 00:00:00 2001
From: Marco Ciampini <marco.ciampo@gmail.com>
Date: Wed, 2 Oct 2024 18:25:24 +0200
Subject: [PATCH 3/6] Simplify code (no need for custom render)

---
 .../components/src/composite/stories/index.story.tsx | 12 +++---------
 1 file changed, 3 insertions(+), 9 deletions(-)

diff --git a/packages/components/src/composite/stories/index.story.tsx b/packages/components/src/composite/stories/index.story.tsx
index b77768b98bf2b4..572b863524039f 100644
--- a/packages/components/src/composite/stories/index.story.tsx
+++ b/packages/components/src/composite/stories/index.story.tsx
@@ -377,19 +377,13 @@ export const WithTooltips: StoryObj< typeof Composite > = {
 		children: (
 			<>
 				<Tooltip text="Tooltip one">
-					<Composite.Item render={ <button /> }>
-						Item one
-					</Composite.Item>
+					<Composite.Item>Item one</Composite.Item>
 				</Tooltip>
 				<Tooltip text="Tooltip two">
-					<Composite.Item render={ <button /> }>
-						Item two
-					</Composite.Item>
+					<Composite.Item>Item two</Composite.Item>
 				</Tooltip>
 				<Tooltip text="Tooltip three">
-					<Composite.Item render={ <button /> }>
-						Item three
-					</Composite.Item>
+					<Composite.Item>Item three</Composite.Item>
 				</Tooltip>
 			</>
 		),

From c0a624607de9587ed3491afa3e607da403001ba8 Mon Sep 17 00:00:00 2001
From: Marco Ciampini <marco.ciampo@gmail.com>
Date: Wed, 2 Oct 2024 18:25:39 +0200
Subject: [PATCH 4/6] Rewrite Story JSDocs

---
 .../src/composite/stories/index.story.tsx     | 22 ++++++++++++-------
 1 file changed, 14 insertions(+), 8 deletions(-)

diff --git a/packages/components/src/composite/stories/index.story.tsx b/packages/components/src/composite/stories/index.story.tsx
index 572b863524039f..c5518375df8a6f 100644
--- a/packages/components/src/composite/stories/index.story.tsx
+++ b/packages/components/src/composite/stories/index.story.tsx
@@ -356,19 +356,25 @@ const Fill = ( { children } ) => {
 };
 
 /**
- * Combining the `Tooltip` and `Composite` component has a few caveats.
- * For example, the following code won't work as expected:
+ * Combining the `Tooltip` and `Composite` component has a few caveats. And while there are a few ways to compose these two components, our recommendation is to render `Composite.Item` as a child of `Tooltip`.
  *
  * ```jsx
+ * // 🔴 Does not work
  * <Composite.Item
  *   render={
- *   <Tooltip text="Tooltip">
- *     <button>Button</button>
- *   </Tooltip>
- * ```
+ *     <Tooltip text="Tooltip">
+ *       <button>Item</button>
+ *     </Tooltip>
+ *   }
+ * />
  *
- * Take a look at this story's source code to see how to correctly compose
- * these two components.
+ * // 🟢 Good
+ * <Tooltip text="Tooltip one">
+ *   <Composite.Item>
+ *     Item one
+ *   </Composite.Item>
+ * </Tooltip>
+ * ```
  */
 export const WithTooltips: StoryObj< typeof Composite > = {
 	...Default,

From ad4f4f33182c1b0f0ad8983565303b1d662c235d Mon Sep 17 00:00:00 2001
From: Marco Ciampini <marco.ciampo@gmail.com>
Date: Wed, 2 Oct 2024 18:25:58 +0200
Subject: [PATCH 5/6] Use third item as an example to render with a custom
 component

---
 packages/components/src/composite/stories/index.story.tsx | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/packages/components/src/composite/stories/index.story.tsx b/packages/components/src/composite/stories/index.story.tsx
index c5518375df8a6f..ecafcca7141bb6 100644
--- a/packages/components/src/composite/stories/index.story.tsx
+++ b/packages/components/src/composite/stories/index.story.tsx
@@ -14,6 +14,7 @@ import { useContext, useMemo } from '@wordpress/element';
 import { createSlotFill, Provider as SlotFillProvider } from '../../slot-fill';
 import { Composite } from '..';
 import { Tooltip } from '../../tooltip';
+import Button from '../../button';
 
 const meta: Meta< typeof Composite > = {
 	title: 'Components/Composite',
@@ -389,7 +390,9 @@ export const WithTooltips: StoryObj< typeof Composite > = {
 					<Composite.Item>Item two</Composite.Item>
 				</Tooltip>
 				<Tooltip text="Tooltip three">
-					<Composite.Item>Item three</Composite.Item>
+					<Composite.Item render={ <Button /> }>
+						Item three
+					</Composite.Item>
 				</Tooltip>
 			</>
 		),

From 50466a8fe255603705ec62f4e42b8ee4eb6398c6 Mon Sep 17 00:00:00 2001
From: Marco Ciampini <marco.ciampo@gmail.com>
Date: Thu, 3 Oct 2024 01:15:39 +0200
Subject: [PATCH 6/6] Do not use Button for thir composite item

---
 packages/components/src/composite/stories/index.story.tsx | 5 +----
 1 file changed, 1 insertion(+), 4 deletions(-)

diff --git a/packages/components/src/composite/stories/index.story.tsx b/packages/components/src/composite/stories/index.story.tsx
index ecafcca7141bb6..c5518375df8a6f 100644
--- a/packages/components/src/composite/stories/index.story.tsx
+++ b/packages/components/src/composite/stories/index.story.tsx
@@ -14,7 +14,6 @@ import { useContext, useMemo } from '@wordpress/element';
 import { createSlotFill, Provider as SlotFillProvider } from '../../slot-fill';
 import { Composite } from '..';
 import { Tooltip } from '../../tooltip';
-import Button from '../../button';
 
 const meta: Meta< typeof Composite > = {
 	title: 'Components/Composite',
@@ -390,9 +389,7 @@ export const WithTooltips: StoryObj< typeof Composite > = {
 					<Composite.Item>Item two</Composite.Item>
 				</Tooltip>
 				<Tooltip text="Tooltip three">
-					<Composite.Item render={ <Button /> }>
-						Item three
-					</Composite.Item>
+					<Composite.Item>Item three</Composite.Item>
 				</Tooltip>
 			</>
 		),