From b7bd1a34ba14b85b80d313e9c2b669042e8fd62e Mon Sep 17 00:00:00 2001
From: brookewp <brooke.kaminski@automattic.com>
Date: Thu, 7 Sep 2023 16:02:43 -0700
Subject: [PATCH 1/9] Tooltip: add `placement` prop to replace `position`

---
 packages/components/src/tooltip/README.md | 13 +++++++++--
 packages/components/src/tooltip/index.tsx | 27 +++++++++++++++++++++--
 packages/components/src/tooltip/types.ts  | 17 +++++++++++++-
 3 files changed, 52 insertions(+), 5 deletions(-)

diff --git a/packages/components/src/tooltip/README.md b/packages/components/src/tooltip/README.md
index 5b4caecf6d5c7..ff9f4e18fc757 100644
--- a/packages/components/src/tooltip/README.md
+++ b/packages/components/src/tooltip/README.md
@@ -42,12 +42,21 @@ Option to hide the tooltip when the anchor is clicked.
 -   Required: No
 -   Default: `true`
 
+#### `placement`: `'top' | 'top-start' | 'top-end' | 'right' | 'right-start' | 'right-end' | 'bottom' | 'bottom-start' | 'bottom-end' | 'left' | 'left-start' | 'left-end'`
+
+Used to specify the tooltip's position with respect to its anchor.
+
+-   Required: No
+-   Default: `'bottom'`
+
 #### `position`: `string`
 
-The direction in which the tooltip should open relative to its parent node. Specify y- and x-axis as a space-separated string. Supports `"top"`, `"middle"`, `"bottom"` y axis, and `"left"`, `"center"`, `"right"` x axis.
+_Note: use the `placement` prop instead when possible._
+
+Legacy way to specify the popover's position with respect to its anchor. Specify y- and x-axis as a space-separated string. Supports `'top'`, `'middle'`, `'bottom'` y axis, and `'left'`, `'center'`, `'right'` x axis.
 
 -   Required: No
--   Default: `"bottom"`
+-   Default: `'bottom'`
 
 #### `shortcut`: `string` | `object`
 
diff --git a/packages/components/src/tooltip/index.tsx b/packages/components/src/tooltip/index.tsx
index f86bd5d2ade9c..a5cb87d12a919 100644
--- a/packages/components/src/tooltip/index.tsx
+++ b/packages/components/src/tooltip/index.tsx
@@ -8,6 +8,7 @@ import * as Ariakit from '@ariakit/react/tooltip';
  */
 import { useInstanceId } from '@wordpress/compose';
 import { Children } from '@wordpress/element';
+import deprecated from '@wordpress/deprecated';
 
 /**
  * Internal dependencies
@@ -26,7 +27,8 @@ function Tooltip( props: TooltipProps ) {
 		children,
 		delay = TOOLTIP_DELAY,
 		hideOnClick = true,
-		position = 'bottom',
+		placement,
+		position,
 		shortcut,
 		text,
 	} = props;
@@ -45,8 +47,29 @@ function Tooltip( props: TooltipProps ) {
 		}
 	}
 
+	const DEFAULT_PLACEMENT = 'bottom';
+
+	// Compute tooltip's placement:
+	// - give priority to `placement` prop, if defined
+	// - otherwise, compute it from the legacy `position` prop (if defined)
+	// - finally, fallback to the DEFAULT_PLACEMENT.
+	let computedPlacement;
+	if ( placement !== undefined ) {
+		computedPlacement = placement;
+	} else if ( position !== undefined ) {
+		computedPlacement = positionToPlacement( position );
+	}
+	computedPlacement = computedPlacement || DEFAULT_PLACEMENT;
+
+	if ( position !== undefined ) {
+		deprecated( '`position` prop in wp.components.tooltip', {
+			since: '6.4',
+			alternative: '`placement` prop',
+		} );
+	}
+
 	const tooltipStore = Ariakit.useTooltipStore( {
-		placement: positionToPlacement( position ),
+		placement: computedPlacement,
 		timeout: delay,
 	} );
 
diff --git a/packages/components/src/tooltip/types.ts b/packages/components/src/tooltip/types.ts
index 1487a382ff1b8..af85dabafe6f8 100644
--- a/packages/components/src/tooltip/types.ts
+++ b/packages/components/src/tooltip/types.ts
@@ -1,3 +1,8 @@
+/**
+ * External dependencies
+ */
+import type { Placement } from '@floating-ui/react-dom';
+
 /**
  * Internal dependencies
  */
@@ -24,9 +29,19 @@ export type TooltipProps = {
 	 */
 	delay?: number;
 	/**
-	 * The direction in which the tooltip should open relative to its parent node.
+	 * Where the tooltip should be positioned relative to its parent.
+	 *
+	 * @default bottom
+	 */
+	placement?: Placement;
+	/**
+	 * _Note: this prop is deprecated. Please use the `placement` prop instead._
+	 *
+	 * Legacy way of specifying the tooltip's position relative to its parent.
+	 *
 	 * Specify y- and x-axis as a space-separated string. Supports `"top"`,
 	 * `"bottom"` y axis, and `"left"`, `"center"`, `"right"` x axis.
+	 * Where the tooltip should be positioned relative to its parent.
 	 *
 	 * @default bottom
 	 */

From c37ebe23696a90aacac5035f30f93fdd623f973e Mon Sep 17 00:00:00 2001
From: brookewp <brooke.kaminski@automattic.com>
Date: Tue, 12 Sep 2023 10:53:29 -0700
Subject: [PATCH 2/9] Refine code based on feedback

---
 packages/components/src/tooltip/index.tsx | 7 +------
 1 file changed, 1 insertion(+), 6 deletions(-)

diff --git a/packages/components/src/tooltip/index.tsx b/packages/components/src/tooltip/index.tsx
index a5cb87d12a919..b01a5ad06ee11 100644
--- a/packages/components/src/tooltip/index.tsx
+++ b/packages/components/src/tooltip/index.tsx
@@ -47,8 +47,6 @@ function Tooltip( props: TooltipProps ) {
 		}
 	}
 
-	const DEFAULT_PLACEMENT = 'bottom';
-
 	// Compute tooltip's placement:
 	// - give priority to `placement` prop, if defined
 	// - otherwise, compute it from the legacy `position` prop (if defined)
@@ -58,15 +56,12 @@ function Tooltip( props: TooltipProps ) {
 		computedPlacement = placement;
 	} else if ( position !== undefined ) {
 		computedPlacement = positionToPlacement( position );
-	}
-	computedPlacement = computedPlacement || DEFAULT_PLACEMENT;
-
-	if ( position !== undefined ) {
 		deprecated( '`position` prop in wp.components.tooltip', {
 			since: '6.4',
 			alternative: '`placement` prop',
 		} );
 	}
+	computedPlacement = computedPlacement || 'bottom';
 
 	const tooltipStore = Ariakit.useTooltipStore( {
 		placement: computedPlacement,

From 01a57ae7c6c09b813687238bbf6cc030e4c0eb07 Mon Sep 17 00:00:00 2001
From: brookewp <brooke.kaminski@automattic.com>
Date: Tue, 12 Sep 2023 10:53:45 -0700
Subject: [PATCH 3/9] Add details on floating-ui to readme

---
 packages/components/src/tooltip/README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/components/src/tooltip/README.md b/packages/components/src/tooltip/README.md
index ff9f4e18fc757..810e86562dda5 100644
--- a/packages/components/src/tooltip/README.md
+++ b/packages/components/src/tooltip/README.md
@@ -44,7 +44,7 @@ Option to hide the tooltip when the anchor is clicked.
 
 #### `placement`: `'top' | 'top-start' | 'top-end' | 'right' | 'right-start' | 'right-end' | 'bottom' | 'bottom-start' | 'bottom-end' | 'left' | 'left-start' | 'left-end'`
 
-Used to specify the tooltip's position with respect to its anchor.
+Used to specify the tooltip's placement with respect to its anchor. Further details and examples can be found in `floating-ui`'s [documentation for 'Placements'](https://floating-ui.com/docs/tutorial#placements).
 
 -   Required: No
 -   Default: `'bottom'`

From 6bf3584f6aa63e496adfd963d4cc7e8510d68036 Mon Sep 17 00:00:00 2001
From: brookewp <brooke.kaminski@automattic.com>
Date: Tue, 12 Sep 2023 13:52:43 -0700
Subject: [PATCH 4/9] Update tests to expect warning

---
 .../components/downloadable-block-list-item/test/index.js    | 4 ++++
 .../src/components/downloadable-blocks-list/test/index.js    | 3 +++
 .../src/components/media-replace-flow/test/index.js          | 5 +++++
 packages/block-library/src/cover/test/edit.js                | 4 ++++
 packages/components/src/box-control/test/index.tsx           | 4 ++++
 packages/components/src/date-time/time/test/index.tsx        | 4 ++++
 6 files changed, 24 insertions(+)

diff --git a/packages/block-directory/src/components/downloadable-block-list-item/test/index.js b/packages/block-directory/src/components/downloadable-block-list-item/test/index.js
index d98fb31f1895c..c62fbfb6a8645 100644
--- a/packages/block-directory/src/components/downloadable-block-list-item/test/index.js
+++ b/packages/block-directory/src/components/downloadable-block-list-item/test/index.js
@@ -31,6 +31,10 @@ describe( 'DownloadableBlockListItem', () => {
 		render(
 			<DownloadableBlockListItem onClick={ jest.fn() } item={ plugin } />
 		);
+
+		expect( console ).toHaveWarnedWith(
+			'`position` prop in wp.components.tooltip is deprecated since version 6.4. Please use `placement` prop instead.'
+		);
 		const author = screen.queryByText( `by ${ plugin.author }` );
 		const description = screen.queryByText( plugin.description );
 		expect( author ).toBeInTheDocument();
diff --git a/packages/block-directory/src/components/downloadable-blocks-list/test/index.js b/packages/block-directory/src/components/downloadable-blocks-list/test/index.js
index 729608ab12aca..f93edc2bc9569 100644
--- a/packages/block-directory/src/components/downloadable-blocks-list/test/index.js
+++ b/packages/block-directory/src/components/downloadable-blocks-list/test/index.js
@@ -53,6 +53,9 @@ describe( 'DownloadableBlocksList', () => {
 			);
 			const downloadableBlocks = screen.getAllByRole( 'option' );
 
+			expect( console ).toHaveWarnedWith(
+				'`position` prop in wp.components.tooltip is deprecated since version 6.4. Please use `placement` prop instead.'
+			);
 			expect( downloadableBlocks ).toHaveLength( items.length );
 		} );
 	} );
diff --git a/packages/block-editor/src/components/media-replace-flow/test/index.js b/packages/block-editor/src/components/media-replace-flow/test/index.js
index 0af3ad1db6684..adcc98f12f2e0 100644
--- a/packages/block-editor/src/components/media-replace-flow/test/index.js
+++ b/packages/block-editor/src/components/media-replace-flow/test/index.js
@@ -55,6 +55,11 @@ describe( 'General media replace flow', () => {
 				name: 'Replace',
 			} )
 		);
+
+		expect( console ).toHaveWarnedWith(
+			'`position` prop in wp.components.tooltip is deprecated since version 6.4. Please use `placement` prop instead.'
+		);
+
 		const uploadMenu = screen.getByRole( 'menu' );
 
 		await waitFor( () => expect( uploadMenu ).toBePositionedPopover() );
diff --git a/packages/block-library/src/cover/test/edit.js b/packages/block-library/src/cover/test/edit.js
index 74db754ff1696..d73c506d0cd70 100644
--- a/packages/block-library/src/cover/test/edit.js
+++ b/packages/block-library/src/cover/test/edit.js
@@ -63,6 +63,10 @@ describe( 'Cover block', () => {
 		test( 'shows placeholder if background image and color not set', async () => {
 			await setup();
 
+			expect( console ).toHaveWarnedWith(
+				'`position` prop in wp.components.tooltip is deprecated since version 6.4. Please use `placement` prop instead.'
+			);
+
 			expect(
 				screen.getByRole( 'group', {
 					name: 'To edit this block, you need permission to upload media.',
diff --git a/packages/components/src/box-control/test/index.tsx b/packages/components/src/box-control/test/index.tsx
index 8a861eff37e1b..6c2b11267d5be 100644
--- a/packages/components/src/box-control/test/index.tsx
+++ b/packages/components/src/box-control/test/index.tsx
@@ -156,6 +156,10 @@ describe( 'BoxControl', () => {
 				'100'
 			);
 
+			expect( console ).toHaveWarnedWith(
+				'`position` prop in wp.components.tooltip is deprecated since version 6.4. Please use `placement` prop instead.'
+			);
+
 			expect(
 				screen.getByRole( 'textbox', { name: 'Top' } )
 			).toHaveValue( '100' );
diff --git a/packages/components/src/date-time/time/test/index.tsx b/packages/components/src/date-time/time/test/index.tsx
index a4f7df4db2acb..102c2187350f6 100644
--- a/packages/components/src/date-time/time/test/index.tsx
+++ b/packages/components/src/date-time/time/test/index.tsx
@@ -23,6 +23,10 @@ describe( 'TimePicker', () => {
 			/>
 		);
 
+		expect( console ).toHaveWarnedWith(
+			'`position` prop in wp.components.tooltip is deprecated since version 6.4. Please use `placement` prop instead.'
+		);
+
 		const monthInput = screen.getByLabelText( 'Month' );
 		const dayInput = screen.getByLabelText( 'Day' );
 		const yearInput = screen.getByLabelText( 'Year' );

From 8ad7bd5e2ecfe0ef017422fa1f698a7084c03c53 Mon Sep 17 00:00:00 2001
From: brookewp <brooke.kaminski@automattic.com>
Date: Wed, 13 Sep 2023 12:09:34 -0700
Subject: [PATCH 5/9] Revert "Update tests to expect warning"

This reverts commit 1f6fa73b93320c64671ad739a77116253a0b33fe.
---
 .../components/downloadable-block-list-item/test/index.js    | 4 ----
 .../src/components/downloadable-blocks-list/test/index.js    | 3 ---
 .../src/components/media-replace-flow/test/index.js          | 5 -----
 packages/block-library/src/cover/test/edit.js                | 4 ----
 packages/components/src/box-control/test/index.tsx           | 4 ----
 packages/components/src/date-time/time/test/index.tsx        | 4 ----
 6 files changed, 24 deletions(-)

diff --git a/packages/block-directory/src/components/downloadable-block-list-item/test/index.js b/packages/block-directory/src/components/downloadable-block-list-item/test/index.js
index c62fbfb6a8645..d98fb31f1895c 100644
--- a/packages/block-directory/src/components/downloadable-block-list-item/test/index.js
+++ b/packages/block-directory/src/components/downloadable-block-list-item/test/index.js
@@ -31,10 +31,6 @@ describe( 'DownloadableBlockListItem', () => {
 		render(
 			<DownloadableBlockListItem onClick={ jest.fn() } item={ plugin } />
 		);
-
-		expect( console ).toHaveWarnedWith(
-			'`position` prop in wp.components.tooltip is deprecated since version 6.4. Please use `placement` prop instead.'
-		);
 		const author = screen.queryByText( `by ${ plugin.author }` );
 		const description = screen.queryByText( plugin.description );
 		expect( author ).toBeInTheDocument();
diff --git a/packages/block-directory/src/components/downloadable-blocks-list/test/index.js b/packages/block-directory/src/components/downloadable-blocks-list/test/index.js
index f93edc2bc9569..729608ab12aca 100644
--- a/packages/block-directory/src/components/downloadable-blocks-list/test/index.js
+++ b/packages/block-directory/src/components/downloadable-blocks-list/test/index.js
@@ -53,9 +53,6 @@ describe( 'DownloadableBlocksList', () => {
 			);
 			const downloadableBlocks = screen.getAllByRole( 'option' );
 
-			expect( console ).toHaveWarnedWith(
-				'`position` prop in wp.components.tooltip is deprecated since version 6.4. Please use `placement` prop instead.'
-			);
 			expect( downloadableBlocks ).toHaveLength( items.length );
 		} );
 	} );
diff --git a/packages/block-editor/src/components/media-replace-flow/test/index.js b/packages/block-editor/src/components/media-replace-flow/test/index.js
index adcc98f12f2e0..0af3ad1db6684 100644
--- a/packages/block-editor/src/components/media-replace-flow/test/index.js
+++ b/packages/block-editor/src/components/media-replace-flow/test/index.js
@@ -55,11 +55,6 @@ describe( 'General media replace flow', () => {
 				name: 'Replace',
 			} )
 		);
-
-		expect( console ).toHaveWarnedWith(
-			'`position` prop in wp.components.tooltip is deprecated since version 6.4. Please use `placement` prop instead.'
-		);
-
 		const uploadMenu = screen.getByRole( 'menu' );
 
 		await waitFor( () => expect( uploadMenu ).toBePositionedPopover() );
diff --git a/packages/block-library/src/cover/test/edit.js b/packages/block-library/src/cover/test/edit.js
index d73c506d0cd70..74db754ff1696 100644
--- a/packages/block-library/src/cover/test/edit.js
+++ b/packages/block-library/src/cover/test/edit.js
@@ -63,10 +63,6 @@ describe( 'Cover block', () => {
 		test( 'shows placeholder if background image and color not set', async () => {
 			await setup();
 
-			expect( console ).toHaveWarnedWith(
-				'`position` prop in wp.components.tooltip is deprecated since version 6.4. Please use `placement` prop instead.'
-			);
-
 			expect(
 				screen.getByRole( 'group', {
 					name: 'To edit this block, you need permission to upload media.',
diff --git a/packages/components/src/box-control/test/index.tsx b/packages/components/src/box-control/test/index.tsx
index 6c2b11267d5be..8a861eff37e1b 100644
--- a/packages/components/src/box-control/test/index.tsx
+++ b/packages/components/src/box-control/test/index.tsx
@@ -156,10 +156,6 @@ describe( 'BoxControl', () => {
 				'100'
 			);
 
-			expect( console ).toHaveWarnedWith(
-				'`position` prop in wp.components.tooltip is deprecated since version 6.4. Please use `placement` prop instead.'
-			);
-
 			expect(
 				screen.getByRole( 'textbox', { name: 'Top' } )
 			).toHaveValue( '100' );
diff --git a/packages/components/src/date-time/time/test/index.tsx b/packages/components/src/date-time/time/test/index.tsx
index 102c2187350f6..a4f7df4db2acb 100644
--- a/packages/components/src/date-time/time/test/index.tsx
+++ b/packages/components/src/date-time/time/test/index.tsx
@@ -23,10 +23,6 @@ describe( 'TimePicker', () => {
 			/>
 		);
 
-		expect( console ).toHaveWarnedWith(
-			'`position` prop in wp.components.tooltip is deprecated since version 6.4. Please use `placement` prop instead.'
-		);
-
 		const monthInput = screen.getByLabelText( 'Month' );
 		const dayInput = screen.getByLabelText( 'Day' );
 		const yearInput = screen.getByLabelText( 'Year' );

From 034159ac1cf49a1e394f976e93f4a1988ecbef87 Mon Sep 17 00:00:00 2001
From: brookewp <brooke.kaminski@automattic.com>
Date: Wed, 13 Sep 2023 13:14:03 -0700
Subject: [PATCH 6/9] Replace internal Tooltip usage of `position` with
 `placement`

---
 .../components/border-radius-control/input-controls.js |  2 +-
 .../src/components/media-replace-flow/index.js         |  2 +-
 packages/components/src/box-control/unit-control.tsx   |  2 +-
 packages/components/src/button/index.tsx               | 10 +++++++++-
 packages/components/src/date-time/time/timezone.tsx    |  2 +-
 .../toggle-group-control-option-base/component.tsx     |  2 +-
 .../src/components/page-patterns/grid-item.js          |  4 ++--
 7 files changed, 16 insertions(+), 8 deletions(-)

diff --git a/packages/block-editor/src/components/border-radius-control/input-controls.js b/packages/block-editor/src/components/border-radius-control/input-controls.js
index b33b79a482435..c0c5c672d6364 100644
--- a/packages/block-editor/src/components/border-radius-control/input-controls.js
+++ b/packages/block-editor/src/components/border-radius-control/input-controls.js
@@ -68,7 +68,7 @@ export default function BoxInputControls( {
 					: selectedUnits[ corner ] || selectedUnits.flat;
 
 				return (
-					<Tooltip text={ label } position="top" key={ corner }>
+					<Tooltip text={ label } placement="top" key={ corner }>
 						<div className="components-border-radius-control__tooltip-wrapper">
 							<UnitControl
 								{ ...props }
diff --git a/packages/block-editor/src/components/media-replace-flow/index.js b/packages/block-editor/src/components/media-replace-flow/index.js
index 9010e0a1a9004..c331761af5852 100644
--- a/packages/block-editor/src/components/media-replace-flow/index.js
+++ b/packages/block-editor/src/components/media-replace-flow/index.js
@@ -220,7 +220,7 @@ const MediaReplaceFlow = ( {
 								{ __( 'Current media URL:' ) }
 							</span>
 
-							<Tooltip text={ mediaURL } position="bottom">
+							<Tooltip text={ mediaURL }>
 								<div>
 									<LinkControl
 										value={ { url: mediaURL } }
diff --git a/packages/components/src/box-control/unit-control.tsx b/packages/components/src/box-control/unit-control.tsx
index ea724e9a82a19..24d71cf0d6cd3 100644
--- a/packages/components/src/box-control/unit-control.tsx
+++ b/packages/components/src/box-control/unit-control.tsx
@@ -67,7 +67,7 @@ function Tooltip( {
 	 * https://github.com/WordPress/gutenberg/pull/24966#issuecomment-685875026
 	 */
 	return (
-		<BaseTooltip text={ text } position="top">
+		<BaseTooltip text={ text } placement="top">
 			<div>{ children }</div>
 		</BaseTooltip>
 	);
diff --git a/packages/components/src/button/index.tsx b/packages/components/src/button/index.tsx
index cc91cf4642586..e0fd8e7c91a13 100644
--- a/packages/components/src/button/index.tsx
+++ b/packages/components/src/button/index.tsx
@@ -24,6 +24,7 @@ import Tooltip from '../tooltip';
 import Icon from '../icon';
 import { VisuallyHidden } from '../visually-hidden';
 import type { ButtonProps, DeprecatedButtonProps } from './types';
+import { positionToPlacement } from '../popover/utils';
 
 const disabledEventsOnDisabledButton = [ 'onMouseDown', 'onClick' ] as const;
 
@@ -225,6 +226,13 @@ export function UnforwardedButton(
 			</button>
 		);
 
+	// use floating-ui's `placement` instead of legacy `position`
+	let computedPlacement;
+	// if `tooltipPosition` is defined, compute value to `placement`
+	if ( tooltipPosition !== undefined ) {
+		computedPlacement = positionToPlacement( tooltipPosition );
+	}
+
 	if ( ! shouldShowTooltip ) {
 		return (
 			<>
@@ -248,7 +256,7 @@ export function UnforwardedButton(
 						: label
 				}
 				shortcut={ shortcut }
-				position={ tooltipPosition }
+				placement={ computedPlacement }
 			>
 				{ element }
 			</Tooltip>
diff --git a/packages/components/src/date-time/time/timezone.tsx b/packages/components/src/date-time/time/timezone.tsx
index f878deddaa782..9fac1ec094ed8 100644
--- a/packages/components/src/date-time/time/timezone.tsx
+++ b/packages/components/src/date-time/time/timezone.tsx
@@ -38,7 +38,7 @@ const TimeZone = () => {
 			: `(${ zoneAbbr }) ${ timezone.string.replace( '_', ' ' ) }`;
 
 	return (
-		<Tooltip position="top center" text={ timezoneDetail }>
+		<Tooltip placement="top" text={ timezoneDetail }>
 			<StyledComponent className="components-datetime__timezone">
 				{ zoneAbbr }
 			</StyledComponent>
diff --git a/packages/components/src/toggle-group-control/toggle-group-control-option-base/component.tsx b/packages/components/src/toggle-group-control/toggle-group-control-option-base/component.tsx
index 572a4b70785eb..3682aa3a5f1f6 100644
--- a/packages/components/src/toggle-group-control/toggle-group-control-option-base/component.tsx
+++ b/packages/components/src/toggle-group-control/toggle-group-control-option-base/component.tsx
@@ -38,7 +38,7 @@ const LAYOUT_ID = 'toggle-group-backdrop-shared-layout-id';
 const WithToolTip = ( { showTooltip, text, children }: WithToolTipProps ) => {
 	if ( showTooltip && text ) {
 		return (
-			<Tooltip text={ text } position="top center">
+			<Tooltip text={ text } placement="top">
 				{ children }
 			</Tooltip>
 		);
diff --git a/packages/edit-site/src/components/page-patterns/grid-item.js b/packages/edit-site/src/components/page-patterns/grid-item.js
index 25aab2646cdfd..0f6c5097590db 100644
--- a/packages/edit-site/src/components/page-patterns/grid-item.js
+++ b/packages/edit-site/src/components/page-patterns/grid-item.js
@@ -182,7 +182,7 @@ function GridItem( { categoryId, item, ...props } ) {
 				>
 					{ itemIcon && ! isNonUserPattern && (
 						<Tooltip
-							position="top center"
+							placement="top"
 							text={ __(
 								'Editing this pattern will also update anywhere it is used'
 							) }
@@ -211,7 +211,7 @@ function GridItem( { categoryId, item, ...props } ) {
 						) }
 						{ item.type === PATTERNS && (
 							<Tooltip
-								position="top center"
+								placement="top"
 								text={ __( 'This pattern cannot be edited.' ) }
 							>
 								<Icon

From 364d6118c53986be05b23f66936d5b7d8a26edd2 Mon Sep 17 00:00:00 2001
From: brookewp <brooke.kaminski@automattic.com>
Date: Thu, 14 Sep 2023 16:36:25 -0700
Subject: [PATCH 7/9] Documentation updates based on feedback

---
 packages/components/CHANGELOG.md          | 4 ++++
 packages/components/src/button/index.tsx  | 2 +-
 packages/components/src/tooltip/README.md | 2 +-
 packages/components/src/tooltip/index.tsx | 2 +-
 packages/components/src/tooltip/types.ts  | 1 +
 5 files changed, 8 insertions(+), 3 deletions(-)

diff --git a/packages/components/CHANGELOG.md b/packages/components/CHANGELOG.md
index 0aefc8941fe15..9ee10d700e84f 100644
--- a/packages/components/CHANGELOG.md
+++ b/packages/components/CHANGELOG.md
@@ -42,6 +42,10 @@
 
 -   `DropdownMenu` v2: Fix submenu chevron direction in RTL languages ([#54036](https://github.com/WordPress/gutenberg/pull/54036).
 
+### New Features
+
+-   `Tooltip`: Add `placement` prop to replace deprecated `position`([#54264](https://github.com/WordPress/gutenberg/pull/54264)).
+
 ## 25.7.0 (2023-08-31)
 
 ### Breaking changes
diff --git a/packages/components/src/button/index.tsx b/packages/components/src/button/index.tsx
index e0fd8e7c91a13..a199c1bb350cd 100644
--- a/packages/components/src/button/index.tsx
+++ b/packages/components/src/button/index.tsx
@@ -226,7 +226,7 @@ export function UnforwardedButton(
 			</button>
 		);
 
-	// use floating-ui's `placement` instead of legacy `position`
+	// Convert legacy `position` values to be used with the new `placement` prop
 	let computedPlacement;
 	// if `tooltipPosition` is defined, compute value to `placement`
 	if ( tooltipPosition !== undefined ) {
diff --git a/packages/components/src/tooltip/README.md b/packages/components/src/tooltip/README.md
index 810e86562dda5..9b214e8fc6b00 100644
--- a/packages/components/src/tooltip/README.md
+++ b/packages/components/src/tooltip/README.md
@@ -44,7 +44,7 @@ Option to hide the tooltip when the anchor is clicked.
 
 #### `placement`: `'top' | 'top-start' | 'top-end' | 'right' | 'right-start' | 'right-end' | 'bottom' | 'bottom-start' | 'bottom-end' | 'left' | 'left-start' | 'left-end'`
 
-Used to specify the tooltip's placement with respect to its anchor. Further details and examples can be found in `floating-ui`'s [documentation for 'Placements'](https://floating-ui.com/docs/tutorial#placements).
+Used to specify the tooltip's placement with respect to its anchor.
 
 -   Required: No
 -   Default: `'bottom'`
diff --git a/packages/components/src/tooltip/index.tsx b/packages/components/src/tooltip/index.tsx
index b01a5ad06ee11..f31a2a4f264d9 100644
--- a/packages/components/src/tooltip/index.tsx
+++ b/packages/components/src/tooltip/index.tsx
@@ -50,7 +50,7 @@ function Tooltip( props: TooltipProps ) {
 	// Compute tooltip's placement:
 	// - give priority to `placement` prop, if defined
 	// - otherwise, compute it from the legacy `position` prop (if defined)
-	// - finally, fallback to the DEFAULT_PLACEMENT.
+	// - finally, fallback to the default placement: 'bottom'
 	let computedPlacement;
 	if ( placement !== undefined ) {
 		computedPlacement = placement;
diff --git a/packages/components/src/tooltip/types.ts b/packages/components/src/tooltip/types.ts
index af85dabafe6f8..9d50a85ff521f 100644
--- a/packages/components/src/tooltip/types.ts
+++ b/packages/components/src/tooltip/types.ts
@@ -43,6 +43,7 @@ export type TooltipProps = {
 	 * `"bottom"` y axis, and `"left"`, `"center"`, `"right"` x axis.
 	 * Where the tooltip should be positioned relative to its parent.
 	 *
+	 * @deprecated
 	 * @default bottom
 	 */
 	position?: PopoverProps[ 'position' ];

From 60049f49e21b5f87eb5e31a49bfd3bcd59f079d0 Mon Sep 17 00:00:00 2001
From: brookewp <brooke.kaminski@automattic.com>
Date: Fri, 15 Sep 2023 12:42:07 -0700
Subject: [PATCH 8/9] Move other tooltip change to new features in changelog

---
 packages/components/CHANGELOG.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/components/CHANGELOG.md b/packages/components/CHANGELOG.md
index 9ee10d700e84f..86f8a73b43d70 100644
--- a/packages/components/CHANGELOG.md
+++ b/packages/components/CHANGELOG.md
@@ -11,7 +11,6 @@
 -   `Dropdown` and `DropdownMenu`: support controlled mode for the dropdown's open/closed state ([#54257](https://github.com/WordPress/gutenberg/pull/54257)).
 -   `BorderControl`: Apply proper metrics and simpler text ([#53998](https://github.com/WordPress/gutenberg/pull/53998)).
 -   `FormTokenField`: Update styling for consistency and increased visibility ([#54402](https://github.com/WordPress/gutenberg/pull/54402)).
--   `Tooltip`: Add new `hideOnClick` prop ([#54406](https://github.com/WordPress/gutenberg/pull/54406)).
 -   `CircularOptionPicker`: Add option to use previous non-listbox behaviour, for contexts where buttons are more appropriate than a list of options ([#54290](https://github.com/WordPress/gutenberg/pull/54290)).
 -   `DuotonePicker/ColorListPicker`: Adds appropriate labels to 'Duotone Filter' color pickers ([#54468](https://github.com/WordPress/gutenberg/pull/54468)).
 
@@ -44,6 +43,7 @@
 
 ### New Features
 
+-   `Tooltip`: Add new `hideOnClick` prop ([#54406](https://github.com/WordPress/gutenberg/pull/54406)).
 -   `Tooltip`: Add `placement` prop to replace deprecated `position`([#54264](https://github.com/WordPress/gutenberg/pull/54264)).
 
 ## 25.7.0 (2023-08-31)

From b94e1c9638eeb989df0143967a8a2eff23203cee Mon Sep 17 00:00:00 2001
From: brookewp <brooke.kaminski@automattic.com>
Date: Mon, 18 Sep 2023 10:15:48 -0700
Subject: [PATCH 9/9] Remove extra comment from types

---
 packages/components/src/tooltip/types.ts | 1 -
 1 file changed, 1 deletion(-)

diff --git a/packages/components/src/tooltip/types.ts b/packages/components/src/tooltip/types.ts
index 9d50a85ff521f..8708ae7005f5b 100644
--- a/packages/components/src/tooltip/types.ts
+++ b/packages/components/src/tooltip/types.ts
@@ -41,7 +41,6 @@ export type TooltipProps = {
 	 *
 	 * Specify y- and x-axis as a space-separated string. Supports `"top"`,
 	 * `"bottom"` y axis, and `"left"`, `"center"`, `"right"` x axis.
-	 * Where the tooltip should be positioned relative to its parent.
 	 *
 	 * @deprecated
 	 * @default bottom