WordPress · brookewp · Sep 18, 2023 · Sep 7, 2023 · Sep 12, 2023 · Sep 12, 2023
@@ -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 }

@@ -220,7 +220,7 @@ const MediaReplaceFlow = ( {
  { __( 'Current media URL:' ) }
  </span>
 
- <Tooltip text={ mediaURL } position="bottom">
+ <Tooltip text={ mediaURL }>
  <div>
  <LinkControl
  value={ { url: mediaURL } }

@@ -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)).
 
@@ -42,6 +41,11 @@
 
 - `DropdownMenu` v2: Fix submenu chevron direction in RTL languages ([#54036](https://github.com/WordPress/gutenberg/pull/54036).
 
+### 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)
 
 ### Breaking changes

@@ -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>
  );

@@ -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>
  );
 
+ // 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 ) {
+ computedPlacement = positionToPlacement( tooltipPosition );
+ }
+
  if ( ! shouldShowTooltip ) {
  return (
  <>
@@ -248,7 +256,7 @@ export function UnforwardedButton(
  : label
  }
  shortcut={ shortcut }
- position={ tooltipPosition }
+ placement={ computedPlacement }
  >
  { element }
  </Tooltip>

@@ -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>

@@ -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>
  );

@@ -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 placement 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`
 

@@ -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,24 @@ 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: 'bottom'
+ let computedPlacement;
+ if ( placement !== undefined ) {
+ computedPlacement = placement;
+ } else if ( position !== undefined ) {
+ computedPlacement = positionToPlacement( position );
+ deprecated( '`position` prop in wp.components.tooltip', {
+ since: '6.4',
+ alternative: '`placement` prop',
+ } );
+ }
+ computedPlacement = computedPlacement || 'bottom';
+
  const tooltipStore = Ariakit.useTooltipStore( {
- placement: positionToPlacement( position ),
+ placement: computedPlacement,
  timeout: delay,
  } );
 

@@ -1,3 +1,8 @@
+/**
+ * External dependencies
+ */
+import type { Placement } from '@floating-ui/react-dom';
+
 /**
  * Internal dependencies
  */
@@ -24,10 +29,20 @@ 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.
  *
+ * @deprecated
  * @default bottom
  */
  position?: PopoverProps[ 'position' ];

diff --git 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