Tooltip: add placement prop to replace position

WordPress · Sep 7, 2023 · 7e12bac · 7e12bac
1 parent 69132c4
commit 7e12bac
Show file tree

Hide file tree

Showing 3 changed files with 52 additions and 5 deletions.
diff --git a/packages/components/src/tooltip/README.md b/packages/components/src/tooltip/README.md
@@ -35,12 +35,21 @@ The amount of time in milliseconds to wait before showing the tooltip.
 -   Required: No
 -   Default: `700`
 
+#### `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
@@ -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
@@ -25,7 +26,8 @@ function Tooltip( props: TooltipProps ) {
 	const {
 		children,
 		delay = TOOLTIP_DELAY,
-		position = 'bottom',
+		placement,
+		position,
 		shortcut,
 		text,
 	} = props;
@@ -44,8 +46,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
@@ -1,3 +1,8 @@
+/**
+ * External dependencies
+ */
+import type { Placement } from '@floating-ui/react-dom';
+
 /**
  * Internal dependencies
  */
@@ -18,9 +23,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
 	 */