@wordpress/components 25.7.0 → 25.8.0

package/src/tooltip/test/index.tsx

@@ -0,0 +1,335 @@
+/**
+ * External dependencies
+ */
+import { render, screen, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+
+/**
+ * WordPress dependencies
+ */
+import { shortcutAriaLabel } from '@wordpress/keycodes';
+
+/**
+ * Internal dependencies
+ */
+import Button from '../../button';
+import Modal from '../../modal';
+import Tooltip, { TOOLTIP_DELAY } from '..';
+import cleanupTooltip from './utils/';
+
+const props = {
+	children: <Button>Button</Button>,
+	text: 'tooltip text',
+};
+
+describe( 'Tooltip', () => {
+	it( 'should not render the tooltip if multiple children are passed', async () => {
+		render(
+			// expected TS error since Tooltip cannot have more than one child element
+			// @ts-expect-error
+			<Tooltip { ...props }>
+				<Button>This is a button</Button>
+				<Button>This is another button</Button>
+			</Tooltip>
+		);
+
+		expect(
+			screen.queryByRole( 'tooltip', { name: /tooltip text/i } )
+		).not.toBeInTheDocument();
+	} );
+
+	it( 'should not render the tooltip if there is no focus', () => {
+		render( <Tooltip { ...props } /> );
+
+		expect(
+			screen.getByRole( 'button', { name: /Button/i } )
+		).toBeVisible();
+
+		expect(
+			screen.queryByRole( 'tooltip', { name: /tooltip text/i } )
+		).not.toBeInTheDocument();
+	} );
+
+	it( 'should render the tooltip when focusing on the tooltip anchor via tab', async () => {
+		const user = userEvent.setup();
+
+		render( <Tooltip { ...props } /> );
+
+		await user.tab();
+
+		expect(
+			screen.getByRole( 'button', { name: /Button/i } )
+		).toHaveFocus();
+
+		expect(
+			await screen.findByRole( 'tooltip', { name: /tooltip text/i } )
+		).toBeVisible();
+
+		await cleanupTooltip( user );
+	} );
+
+	it( 'should render the tooltip when the tooltip anchor is hovered', async () => {
+		const user = userEvent.setup();
+
+		render( <Tooltip { ...props } /> );
+
+		await user.hover( screen.getByRole( 'button', { name: /Button/i } ) );
+
+		expect(
+			await screen.findByRole( 'tooltip', { name: /tooltip text/i } )
+		).toBeVisible();
+
+		await cleanupTooltip( user );
+	} );
+
+	it( 'should not show tooltip on focus as result of mouse click', async () => {
+		const user = userEvent.setup();
+
+		render( <Tooltip { ...props } /> );
+
+		await user.click( screen.getByRole( 'button', { name: /Button/i } ) );
+
+		expect(
+			screen.queryByRole( 'tooltip', { name: /tooltip text/i } )
+		).not.toBeInTheDocument();
+
+		await cleanupTooltip( user );
+	} );
+
+	it( 'should respect custom delay prop when showing tooltip', async () => {
+		const user = userEvent.setup();
+		const ADDITIONAL_DELAY = 100;
+
+		render(
+			<Tooltip { ...props } delay={ TOOLTIP_DELAY + ADDITIONAL_DELAY } />
+		);
+
+		await user.hover( screen.getByRole( 'button', { name: /Button/i } ) );
+
+		// Advance time by default delay
+		await new Promise( ( resolve ) =>
+			setTimeout( resolve, TOOLTIP_DELAY )
+		);
+
+		// Tooltip hasn't appeared yet
+		expect(
+			screen.queryByRole( 'tooltip', { name: /tooltip text/i } )
+		).not.toBeInTheDocument();
+
+		// wait for additional delay for tooltip to appear
+		await waitFor(
+			() =>
+				new Promise( ( resolve ) =>
+					setTimeout( resolve, ADDITIONAL_DELAY )
+				)
+		);
+
+		expect(
+			screen.getByRole( 'tooltip', { name: /tooltip text/i } )
+		).toBeVisible();
+
+		await cleanupTooltip( user );
+	} );
+
+	it( 'should show tooltip when an element is disabled', async () => {
+		const user = userEvent.setup();
+
+		render(
+			<Tooltip { ...props }>
+				<Button aria-disabled>Button</Button>
+			</Tooltip>
+		);
+
+		const button = screen.getByRole( 'button', { name: /Button/i } );
+
+		expect( button ).toBeVisible();
+		expect( button ).toHaveAttribute( 'aria-disabled' );
+
+		await user.hover( button );
+
+		expect(
+			await screen.findByRole( 'tooltip', { name: /tooltip text/i } )
+		).toBeVisible();
+
+		await cleanupTooltip( user );
+	} );
+
+	it( 'should not show tooltip if the mouse leaves the tooltip anchor before set delay', async () => {
+		const user = userEvent.setup();
+		const onMouseEnterMock = jest.fn();
+		const onMouseLeaveMock = jest.fn();
+		const MOUSE_LEAVE_DELAY = TOOLTIP_DELAY - 200;
+
+		render(
+			<>
+				<Tooltip { ...props }>
+					<Button
+						onMouseEnter={ onMouseEnterMock }
+						onMouseLeave={ onMouseLeaveMock }
+					>
+						Button 1
+					</Button>
+				</Tooltip>
+				<Button>Button 2</Button>
+			</>
+		);
+
+		await user.hover(
+			screen.getByRole( 'button', {
+				name: 'Button 1',
+			} )
+		);
+
+		// Tooltip hasn't appeared yet
+		expect(
+			screen.queryByRole( 'tooltip', { name: /tooltip text/i } )
+		).not.toBeInTheDocument();
+		expect( onMouseEnterMock ).toHaveBeenCalledTimes( 1 );
+
+		// Advance time by MOUSE_LEAVE_DELAY time
+		await new Promise( ( resolve ) =>
+			setTimeout( resolve, MOUSE_LEAVE_DELAY )
+		);
+
+		expect(
+			screen.queryByRole( 'tooltip', { name: /tooltip text/i } )
+		).not.toBeInTheDocument();
+
+		// Hover the other button, meaning that the mouse will leave the tooltip anchor
+		await user.hover(
+			screen.getByRole( 'button', {
+				name: 'Button 2',
+			} )
+		);
+
+		// Tooltip still hasn't appeared yet
+		expect(
+			screen.queryByRole( 'tooltip', { name: /tooltip text/i } )
+		).not.toBeInTheDocument();
+		expect( onMouseEnterMock ).toHaveBeenCalledTimes( 1 );
+		expect( onMouseLeaveMock ).toHaveBeenCalledTimes( 1 );
+
+		// Advance time again, so that we reach the full TOOLTIP_DELAY time
+		await new Promise( ( resolve ) =>
+			setTimeout( resolve, TOOLTIP_DELAY )
+		);
+
+		// Tooltip won't show, since the mouse has left the tooltip anchor
+		expect(
+			screen.queryByRole( 'tooltip', { name: /tooltip text/i } )
+		).not.toBeInTheDocument();
+
+		await cleanupTooltip( user );
+	} );
+
+	it( 'should render the shortcut display text when a string is passed as the shortcut', async () => {
+		const user = userEvent.setup();
+
+		render( <Tooltip { ...props } shortcut="shortcut text" /> );
+
+		await user.hover( screen.getByRole( 'button', { name: /Button/i } ) );
+
+		await waitFor( () =>
+			expect( screen.getByText( 'shortcut text' ) ).toBeVisible()
+		);
+
+		await cleanupTooltip( user );
+	} );
+
+	it( 'should render the keyboard shortcut display text and aria-label when an object is passed as the shortcut', async () => {
+		const user = userEvent.setup();
+
+		render(
+			<Tooltip
+				{ ...props }
+				shortcut={ {
+					display: '⇧⌘,',
+					ariaLabel: shortcutAriaLabel.primaryShift( ',' ),
+				} }
+			/>
+		);
+
+		await user.hover( screen.getByRole( 'button', { name: /Button/i } ) );
+
+		await waitFor( () =>
+			expect( screen.getByText( '⇧⌘,' ) ).toBeVisible()
+		);
+
+		expect( screen.getByText( '⇧⌘,' ) ).toHaveAttribute(
+			'aria-label',
+			'Control + Shift + Comma'
+		);
+
+		await cleanupTooltip( user );
+	} );
+
+	it( 'esc should close modal even when tooltip is visible', async () => {
+		const user = userEvent.setup();
+		const onRequestClose = jest.fn();
+		render(
+			<Modal onRequestClose={ onRequestClose }>
+				<p>Modal content</p>
+			</Modal>
+		);
+
+		expect(
+			screen.queryByRole( 'tooltip', { name: /close/i } )
+		).not.toBeInTheDocument();
+
+		await user.hover(
+			screen.getByRole( 'button', {
+				name: /Close/i,
+			} )
+		);
+
+		await waitFor( () =>
+			expect(
+				screen.getByRole( 'tooltip', { name: /close/i } )
+			).toBeVisible()
+		);
+
+		await user.keyboard( '[Escape]' );
+
+		expect( onRequestClose ).toHaveBeenCalled();
+
+		await cleanupTooltip( user );
+	} );
+
+	it( 'should associate the tooltip text with its anchor via the accessible description when visible', async () => {
+		const user = userEvent.setup();
+
+		render( <Tooltip { ...props } /> );
+
+		await user.hover(
+			screen.getByRole( 'button', {
+				name: /Button/i,
+			} )
+		);
+
+		expect(
+			await screen.findByRole( 'button', { description: 'tooltip text' } )
+		).toBeInTheDocument();
+	} );
+
+	it( 'should not hide tooltip when the anchor is clicked if hideOnClick is false', async () => {
+		const user = userEvent.setup();
+
+		render( <Tooltip { ...props } hideOnClick={ false } /> );
+
+		const button = screen.getByRole( 'button', { name: /Button/i } );
+
+		await user.hover( button );
+
+		expect(
+			await screen.findByRole( 'tooltip', { name: /tooltip text/i } )
+		).toBeVisible();
+
+		await user.click( button );
+
+		expect(
+			screen.getByRole( 'tooltip', { name: /tooltip text/i } )
+		).toBeVisible();
+
+		await cleanupTooltip( user );
+	} );
+} );

package/src/tooltip/test/utils/index.tsx

@@ -0,0 +1,20 @@
+/**
+ * External dependencies
+ */
+import type { UserEvent } from '@testing-library/user-event/dist/types/setup/setup';
+
+// TODO: may need to be tested with Playwright; further context:
+// https://github.com/WordPress/gutenberg/pull/52133#issuecomment-1613691258
+// below workaround ensures tooltip is umounted after each test to prevent leaking
+// similarly to ariakit tooltip tests: https://github.com/ariakit/ariakit/blob/249d376e41115e6d4ceba244e231a95fa457bd04/examples/tooltip/test.ts#L12-L14
+
+/**
+ * Ensures the async behaviors and animations in tooltip complete
+ * to avoid leaking into other tests
+ *
+ */
+export default async function cleanupTooltip( user: UserEvent ) {
+	await user.tab();
+	await user.tab();
+	await user.click( document.body );
+}

package/src/tooltip/types.ts

@@ -0,0 +1,61 @@
+/**
+ * External dependencies
+ */
+import type { Placement } from '@floating-ui/react-dom';
+
+/**
+ * Internal dependencies
+ */
+import type { PopoverProps } from '../popover/types';
+import type { ShortcutProps } from '../shortcut/types';
+
+export type TooltipProps = {
+	/**
+	 * The anchor for the tooltip.
+	 *
+	 * **Note**: Accepts only one child element.
+	 */
+	children: React.ReactElement;
+	/**
+	 * Option to hide the tooltip when the anchor is clicked.
+	 *
+	 * @default true
+	 */
+	hideOnClick?: boolean;
+	/**
+	 * The amount of time in milliseconds to wait before showing the tooltip.
+	 *
+	 * @default 700
+	 */
+	delay?: number;
+	/**
+	 * 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' ];
+	/**
+	 * An option for adding accessible keyboard shortcuts.
+	 *
+	 * 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?: ShortcutProps[ 'shortcut' ];
+	/**
+	 * The text shown in the tooltip when anchor element is focused or hovered.
+	 */
+	text?: string;
+};

package/src/ui/context/context-connect.ts

@@ -18,7 +18,7 @@ import type { WordPressComponentFromProps } from '.';
 
 type AcceptsTwoArgs<
 	F extends ( ...args: any ) => any,
-	ErrorMessage = never
+	ErrorMessage = never,
 > = Parameters< F >[ 'length' ] extends 2 ? {} : ErrorMessage;
 
 type ContextConnectOptions = {
@@ -34,7 +34,7 @@ type ContextConnectOptions = {
  * @return The connected WordPressComponent
  */
 export function contextConnect<
-	C extends ( props: any, ref: ForwardedRef< any > ) => JSX.Element | null
+	C extends ( props: any, ref: ForwardedRef< any > ) => JSX.Element | null,
 >(
 	Component: C &
 		AcceptsTwoArgs<
@@ -66,7 +66,7 @@ export function contextConnectWithoutRef< P >(
 // component wrappers.
 function _contextConnect<
 	C extends ( props: any, ref: ForwardedRef< any > ) => JSX.Element | null,
-	O extends ContextConnectOptions
+	O extends ContextConnectOptions,
 >(
 	Component: C,
 	namespace: string,

package/src/ui/context/wordpress-component.ts

@@ -10,11 +10,11 @@ export type WordPressComponentProps<
 	/** The HTML element to inherit props from. */
 	T extends React.ElementType,
 	/** Supports polymorphism through the `as` prop. */
-	IsPolymorphic extends boolean = true
+	IsPolymorphic extends boolean = true,
 > = P &
 	// The `children` prop is being explicitly omitted since it is otherwise implicitly added
 	// by `ComponentPropsWithRef`. The context is that components should require the `children`
-	// prop explicitely when needed (see https://github.com/WordPress/gutenberg/pull/31817).
+	// prop explicitly when needed (see https://github.com/WordPress/gutenberg/pull/31817).
 	Omit< React.ComponentPropsWithoutRef< T >, 'as' | keyof P | 'children' > &
 	( IsPolymorphic extends true
 		? {
@@ -26,7 +26,7 @@ export type WordPressComponentProps<
 export type WordPressComponent<
 	T extends React.ElementType,
 	O,
-	IsPolymorphic extends boolean
+	IsPolymorphic extends boolean,
 > = {
 	< TT extends React.ElementType >(
 		props: WordPressComponentProps< O, TT, IsPolymorphic > &
@@ -49,7 +49,7 @@ export type WordPressComponent<
 
 export type WordPressComponentFromProps<
 	Props,
-	ForwardsRef extends boolean = true
+	ForwardsRef extends boolean = true,
 > = Props extends WordPressComponentProps< infer P, infer T, infer I >
 	? WordPressComponent<
 			T,

package/src/unit-control/index.tsx

@@ -76,10 +76,15 @@ function UnforwardedUnitControl(
 			unitsProp
 		);
 		const [ { value: firstUnitValue = '' } = {}, ...rest ] = list;
-		const firstCharacters = rest.reduce( ( carry, { value } ) => {
-			const first = escapeRegExp( value?.substring( 0, 1 ) || '' );
-			return carry.includes( first ) ? carry : `${ carry }|${ first }`;
-		}, escapeRegExp( firstUnitValue.substring( 0, 1 ) ) );
+		const firstCharacters = rest.reduce(
+			( carry, { value } ) => {
+				const first = escapeRegExp( value?.substring( 0, 1 ) || '' );
+				return carry.includes( first )
+					? carry
+					: `${ carry }|${ first }`;
+			},
+			escapeRegExp( firstUnitValue.substring( 0, 1 ) )
+		);
 		return [ list, new RegExp( `^(?:${ firstCharacters })$`, 'i' ) ];
 	}, [ nonNullValueProp, unitProp, unitsProp ] );
 	const [ parsedQuantity, parsedUnit ] = getParsedQuantityAndUnit(

package/src/unit-control/styles/unit-control-styles.ts

@@ -82,7 +82,9 @@ const unitSelectSizes = ( { selectSize = 'default' }: SelectProps ) => {
 		default: css`
 			height: 100%;
 			border: 1px solid transparent;
-			transition: box-shadow 0.1s linear, border 0.1s linear;
+			transition:
+				box-shadow 0.1s linear,
+				border 0.1s linear;
 
 			${ rtl( { borderTopLeftRadius: 0, borderBottomLeftRadius: 0 } )() }
 

package/src/unit-control/test/utils.ts

@@ -248,7 +248,7 @@ describe( 'UnitControl utils', () => {
 		const cases: [
 			number | string | undefined,
 			number | undefined,
-			string | undefined
+			string | undefined,
 		][] = [
 			// Test undefined.
 			[ undefined, undefined, undefined ],

package/src/utils/colors-values.js

@@ -41,7 +41,7 @@ const UI = {
 	backgroundDisabled: GRAY[ 100 ],
 	border: GRAY[ 600 ],
 	borderHover: GRAY[ 700 ],
-	borderFocus: ADMIN.themeDark10,
+	borderFocus: ADMIN.theme,
 	borderDisabled: GRAY[ 400 ],
 	textDisabled: GRAY[ 600 ],
 	textDark: white,

package/src/utils/use-deprecated-props.ts

@@ -7,7 +7,7 @@ export function useDeprecated36pxDefaultSizeProp<
 	P extends Record< string, any > & {
 		__next36pxDefaultSize?: boolean;
 		__next40pxDefaultSize?: boolean;
-	}
+	},
 >(
 	props: P,
 	/** The component identifier in dot notation, e.g. `wp.components.ComponentName`. */