From c26f863f10ec7c70692691f9280533e62cfde430 Mon Sep 17 00:00:00 2001
From: brookewp <brooke.kaminski@automattic.com>
Date: Thu, 14 Sep 2023 16:36:25 -0700
Subject: [PATCH] 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 6431a62038c26..249280eaada5a 100644
--- a/packages/components/CHANGELOG.md
+++ b/packages/components/CHANGELOG.md
@@ -39,6 +39,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' ];