ToolTip: refactor using ariakit

packages/base-styles/_z-index.scss

@@ -164,9 +164,6 @@ $z-layers: (
 	// And block manager sticky disabled block count is higher still
 	".edit-post-block-manager__disabled-blocks-count": 2,
 
-	// Needs to be higher than any other element as this is an overlay to catch all events
-	".components-tooltip .event-catcher": 100002,
-
 	// Needs to appear below other color circular picker related UI elements.
 	".components-circular-option-picker__option-wrapper::before": -1,
 

packages/block-editor/src/components/color-palette/test/__snapshots__/control.js.snap

@@ -208,6 +208,7 @@ exports[`ColorPaletteControl matches the snapshot 1`] = `
                     class="components-circular-option-picker__option-wrapper"
                   >
                     <button
+                      aria-describedby="tooltip-0"
                       aria-label="Color: red"
                       aria-pressed="true"
                       class="components-button components-circular-option-picker__option is-pressed"

packages/components/CHANGELOG.md

@@ -4,6 +4,7 @@
 
 ### Enhancements
 
+-   `Tooltip`: Replace the existing tooltip to simplify the implementation and improve accessibility while maintaining the same behaviors and API ([#48440](https://github.com/WordPress/gutenberg/pull/48440)).
 -   Make the `Popover.Slot` optional and render popovers at the bottom of the document's body by default. ([#53889](https://github.com/WordPress/gutenberg/pull/53889)).
 -   `ProgressBar`: Add transition to determinate indicator ([#53877](https://github.com/WordPress/gutenberg/pull/53877)).
 -   Prevent nested `SlotFillProvider` from rendering ([#53940](https://github.com/WordPress/gutenberg/pull/53940)).

packages/components/src/button/test/index.tsx

@@ -15,6 +15,7 @@ import { plusCircle } from '@wordpress/icons';
  */
 import Button from '..';
 import Tooltip from '../../tooltip';
+import cleanupTooltip from '../../tooltip/test/utils';
 
 jest.mock( '../../icon', () => () => <div data-testid="test-icon" /> );
 
@@ -193,7 +194,7 @@ describe( 'Button', () => {
 
 			render( <Button icon={ plusCircle } label="WordPress" /> );
 
-			expect( screen.queryByText( 'WordPress' ) ).not.toBeInTheDocument();
+			expect( screen.queryByText( 'WordPress' ) ).not.toBeVisible();
 
 			// Move focus to the button
 			await user.tab();
@@ -230,12 +231,14 @@ describe( 'Button', () => {
 				/>
 			);
 
-			expect( screen.queryByText( 'Label' ) ).not.toBeInTheDocument();
+			expect( screen.queryByText( 'Label' ) ).not.toBeVisible();
 
 			// Move focus to the button
 			await user.tab();
 
 			expect( screen.getByText( 'Label' ) ).toBeVisible();
+
+			await cleanupTooltip( user );
 		} );
 
 		it( 'should populate tooltip with description content for buttons with visible labels (buttons with children)', async () => {
@@ -287,12 +290,14 @@ describe( 'Button', () => {
 				<Button icon={ plusCircle } label="WordPress" children={ [] } />
 			);
 
-			expect( screen.queryByText( 'WordPress' ) ).not.toBeInTheDocument();
+			expect( screen.queryByText( 'WordPress' ) ).not.toBeVisible();
 
 			// Move focus to the button
 			await user.tab();
 
 			expect( screen.getByText( 'WordPress' ) ).toBeVisible();
+
+			await cleanupTooltip( user );
 		} );
 
 		it( 'should not show the tooltip when icon and children defined', async () => {
@@ -321,12 +326,14 @@ describe( 'Button', () => {
 				</Button>
 			);
 
-			expect( screen.queryByText( 'WordPress' ) ).not.toBeInTheDocument();
+			expect( screen.queryByText( 'WordPress' ) ).not.toBeVisible();
 
 			// Move focus to the button
 			await user.tab();
 
 			expect( screen.getByText( 'WordPress' ) ).toBeVisible();
+
+			await cleanupTooltip( user );
 		} );
 	} );
 

packages/components/src/color-palette/test/__snapshots__/index.tsx.snap

@@ -40,6 +40,7 @@ exports[`ColorPalette should allow disabling custom color picker 1`] = `
           class="components-circular-option-picker__option-wrapper"
         >
           <button
+            aria-describedby="tooltip-15"
             aria-label="Color: red"
             aria-pressed="true"
             class="components-button components-circular-option-picker__option is-pressed"
@@ -64,6 +65,7 @@ exports[`ColorPalette should allow disabling custom color picker 1`] = `
           class="components-circular-option-picker__option-wrapper"
         >
           <button
+            aria-describedby="tooltip-16"
             aria-label="Color: green"
             aria-pressed="false"
             class="components-button components-circular-option-picker__option"
@@ -75,6 +77,7 @@ exports[`ColorPalette should allow disabling custom color picker 1`] = `
           class="components-circular-option-picker__option-wrapper"
         >
           <button
+            aria-describedby="tooltip-17"
             aria-label="Color: blue"
             aria-pressed="false"
             class="components-button components-circular-option-picker__option"
@@ -229,6 +232,7 @@ exports[`ColorPalette should render a dynamic toolbar of colors 1`] = `
           class="components-circular-option-picker__option-wrapper"
         >
           <button
+            aria-describedby="tooltip-0"
             aria-label="Color: red"
             aria-pressed="true"
             class="components-button components-circular-option-picker__option is-pressed"
@@ -253,6 +257,7 @@ exports[`ColorPalette should render a dynamic toolbar of colors 1`] = `
           class="components-circular-option-picker__option-wrapper"
         >
           <button
+            aria-describedby="tooltip-1"
             aria-label="Color: green"
             aria-pressed="false"
             class="components-button components-circular-option-picker__option"
@@ -264,6 +269,7 @@ exports[`ColorPalette should render a dynamic toolbar of colors 1`] = `
           class="components-circular-option-picker__option-wrapper"
         >
           <button
+            aria-describedby="tooltip-2"
             aria-label="Color: blue"
             aria-pressed="false"
             class="components-button components-circular-option-picker__option"

packages/components/src/color-palette/test/index.tsx

@@ -258,7 +258,11 @@ describe( 'ColorPalette', () => {
 		// Clear the color, confirm that the relative values are cleared/updated.
 		await user.click( screen.getByRole( 'button', { name: 'Clear' } ) );
 		expect( screen.getByText( 'No color selected' ) ).toBeVisible();
-		expect( screen.queryByText( colorName ) ).not.toBeInTheDocument();
+		expect(
+			screen.queryByText( colorName, {
+				selector: '.components-color-palette__custom-color-name',
+			} )
+		).not.toBeInTheDocument();
 		expect( screen.queryByText( colorCode ) ).not.toBeInTheDocument();
 		expect(
 			screen.getByRole( 'button', {

packages/components/src/tab-panel/test/index.tsx

@@ -13,6 +13,7 @@ import { wordpress, category, media } from '@wordpress/icons';
  * Internal dependencies
  */
 import TabPanel from '..';
+import cleanupTooltip from '../../tooltip/test/utils';
 
 const TABS = [
 	{
@@ -116,7 +117,7 @@ describe.each( [
 			for ( let i = 0; i < allTabs.length; i++ ) {
 				expect(
 					screen.queryByText( TABS_WITH_ICON[ i ].title )
-				).not.toBeInTheDocument();
+				).not.toBeVisible();
 
 				await user.hover( allTabs[ i ] );
 
@@ -128,6 +129,8 @@ describe.each( [
 
 				await user.unhover( allTabs[ i ] );
 			}
+
+			await cleanupTooltip( user );
 		} );
 
 		it( 'should display a tooltip when moving the selection via the keyboard on tabs provided with an icon', async () => {
@@ -157,38 +160,40 @@ describe.each( [
 
 			// Tab to focus the tablist. Make sure alpha is focused, and that the
 			// corresponding tooltip is shown.
-			expect( screen.queryByText( 'Alpha' ) ).not.toBeInTheDocument();
+			expect( screen.queryByText( 'Alpha' ) ).not.toBeVisible();
 			await user.keyboard( '[Tab]' );
 			expect( mockOnSelect ).toHaveBeenCalledTimes( 1 );
-			expect( screen.getByText( 'Alpha' ) ).toBeInTheDocument();
+			expect( screen.getByText( 'Alpha' ) ).toBeVisible();
 			expect( await getSelectedTab() ).toHaveFocus();
 
 			// Move selection with arrow keys. Make sure beta is focused, and that
 			// the corresponding tooltip is shown.
-			expect( screen.queryByText( 'Beta' ) ).not.toBeInTheDocument();
+			expect( screen.queryByText( 'Beta' ) ).not.toBeVisible();
 			await user.keyboard( '[ArrowRight]' );
 			expect( mockOnSelect ).toHaveBeenCalledTimes( 2 );
 			expect( mockOnSelect ).toHaveBeenLastCalledWith( 'beta' );
-			expect( screen.getByText( 'Beta' ) ).toBeInTheDocument();
+			expect( screen.getByText( 'Beta' ) ).toBeVisible();
 			expect( await getSelectedTab() ).toHaveFocus();
 
 			// Move selection with arrow keys. Make sure gamma is focused, and that
 			// the corresponding tooltip is shown.
-			expect( screen.queryByText( 'Gamma' ) ).not.toBeInTheDocument();
+			expect( screen.queryByText( 'Gamma' ) ).not.toBeVisible();
 			await user.keyboard( '[ArrowRight]' );
 			expect( mockOnSelect ).toHaveBeenCalledTimes( 3 );
 			expect( mockOnSelect ).toHaveBeenLastCalledWith( 'gamma' );
-			expect( screen.getByText( 'Gamma' ) ).toBeInTheDocument();
+			expect( screen.getByText( 'Gamma' ) ).toBeVisible();
 			expect( await getSelectedTab() ).toHaveFocus();
 
 			// Move selection with arrow keys. Make sure beta is focused, and that
 			// the corresponding tooltip is shown.
-			expect( screen.queryByText( 'Beta' ) ).not.toBeInTheDocument();
+			expect( screen.queryByText( 'Beta' ) ).not.toBeVisible();
 			await user.keyboard( '[ArrowLeft]' );
 			expect( mockOnSelect ).toHaveBeenCalledTimes( 4 );
 			expect( mockOnSelect ).toHaveBeenLastCalledWith( 'beta' );
-			expect( screen.getByText( 'Beta' ) ).toBeInTheDocument();
+			expect( screen.getByText( 'Beta' ) ).toBeVisible();
 			expect( await getSelectedTab() ).toHaveFocus();
+
+			await cleanupTooltip( user );
 		} );
 	} );
 

packages/components/src/toggle-group-control/test/__snapshots__/index.tsx.snap

@@ -273,6 +273,7 @@ exports[`ToggleGroupControl should render correctly with icons 1`] = `
         >
           <button
             aria-checked="true"
+            aria-describedby="tooltip-0"
             aria-label="Uppercase"
             class="emotion-14 components-toggle-group-control-option-base"
             data-value="uppercase"
@@ -305,6 +306,7 @@ exports[`ToggleGroupControl should render correctly with icons 1`] = `
         >
           <button
             aria-checked="false"
+            aria-describedby="tooltip-1"
             aria-label="Lowercase"
             class="emotion-19 components-toggle-group-control-option-base"
             data-value="lowercase"

packages/components/src/toggle-group-control/test/index.tsx

@@ -17,10 +17,7 @@ import {
 	ToggleGroupControlOption,
 	ToggleGroupControlOptionIcon,
 } from '../index';
-
-function getWrappingPopoverElement( element: HTMLElement ) {
-	return element.closest( '.components-popover' );
-}
+import cleanupTooltip from '../../tooltip/test/utils';
 
 describe( 'ToggleGroupControl', () => {
 	const options = (
@@ -115,13 +112,9 @@ describe( 'ToggleGroupControl', () => {
 			'Click for Delicious Gnocchi'
 		);
 
-		await waitFor( () =>
-			expect(
-				getWrappingPopoverElement( tooltip )
-			).toBePositionedPopover()
-		);
+		await waitFor( () => expect( tooltip ).toBeVisible() );
 
-		expect( tooltip ).toBeVisible();
+		await cleanupTooltip( user );
 	} );
 
 	it( 'should not render tooltip', async () => {

packages/components/src/toggle-group-control/types.ts

@@ -9,6 +9,7 @@ import type { RadioStateReturn } from 'reakit';
  * Internal dependencies
  */
 import type { BaseControlProps } from '../base-control/types';
+import type { TooltipProps } from '../tooltip/types';
 
 export type ToggleGroupControlOptionBaseProps = {
 	children: ReactNode;
@@ -58,7 +59,7 @@ export type WithToolTipProps = {
 	/**
 	 * React children
 	 */
-	children: ReactNode;
+	children: TooltipProps[ 'children' ];
 	/**
 	 * Label for the Tooltip component.
 	 */

packages/components/src/tooltip/README.md

@@ -1,8 +1,8 @@
-# Tooltip
+# ToolTip
 
-Tooltip is a React component to render floating help text relative to a node when it receives focus or when the user places the mouse cursor atop it. If the tooltip exceeds the bounds of the page in the direction it opens, its position will be flipped automatically.
+Tooltip is a React component to render floating help text relative to a node when it receives focus or it is hovered upon by a mouse. If the tooltip exceeds the bounds of the page in the direction it opens, its position will be flipped automatically.
 
-Accessibility note: the tooltip text is hidden from screen readers and assistive technologies that understand ARIA. To make it accessible, use an `aria-label` attribute on the same element the tooltip is applied to, preferably using the same text used for the tooltip.
+This component utilizes [Ariakit's tooltip](https://ariakit.org/components/tooltip) which is based on the [WAI-ARIA Tooltip Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tooltip/).
 
 ## Usage
 
@@ -22,49 +22,38 @@ const MyTooltip = () => (
 
 The component accepts the following props:
 
-### position
-
-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"`, `"bottom"` y axis, and `"left"`, `"center"`, `"right"` x axis.
-
--   Type: `String`
--   Required: No
--   Default: `"bottom"`
-
-### children
+#### `children`: `Element`
 
 The element to which the tooltip should anchor.
 
-**NOTE:** You must pass only a single child. Tooltip renders itself as a clone of `children` with a [`Popover`](/packages/components/src/popover/README.md) added as an additional child.
+**NOTE:** Accepts only one child element.
 
--   Type: `Element`
 -   Required: Yes
 
-### text
+#### `delay`: `number`
 
-The tooltip text to show on focus or hover.
+The amount of time in milliseconds to wait before showing the tooltip.
 
--   Type: `String`
 -   Required: No
+-   Default: `700`
+
+#### `position`: `string`
 
-### shortcut (web only)
+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"`, `"bottom"` y axis, and `"left"`, `"center"`, `"right"` x axis.
 
--   Type: `string` or `object`
 -   Required: No
+-   Default: `"bottom"`
 
-If shortcut is a string, it is expecting the display text. If shortcut is an object, it will accept the properties of `display` (string) and `ariaLabel` (string).
+#### `shortcut`: `string` | `object`
 
-### delay (web only)
+An option for adding accessible keyboard shortcuts.
 
-Time in milliseconds to wait before showing tooltip after the tooltip's visibility is toggled. This prop is currently only available for the web platforms.
+If shortcut is a string, it is expecting the display text. If shortcut is an object, it will accept the properties of `display`: `string` and `ariaLabel`: `string`.
 
--   Type: `Number`
 -   Required: No
--   Default: 700
 
-### visible (native only)
+#### `text`: `string`
 
-Whether the tooltip should be displayed on initial render. This prop is currently only available for the native mobile app built with React Native.
+The text shown in the tooltip when anchor element is focused or hovered.
 
--   Type: `Boolean`
 -   Required: No
--   Default: `false`