@wordpress/components 25.6.1 → 25.8.0

package/src/tooltip/index.js

@@ -1,293 +0,0 @@
-// @ts-nocheck
-
-/**
- * External dependencies
- */
-import classNames from 'classnames';
-
-/**
- * WordPress dependencies
- */
-import {
-	Children,
-	cloneElement,
-	concatChildren,
-	useEffect,
-	useState,
-} from '@wordpress/element';
-import { useDebounce, useMergeRefs } from '@wordpress/compose';
-
-/**
- * Internal dependencies
- */
-import Popover from '../popover';
-import Shortcut from '../shortcut';
-
-/**
- * Time over children to wait before showing tooltip
- *
- * @type {number}
- */
-export const TOOLTIP_DELAY = 700;
-
-const eventCatcher = <div className="event-catcher" />;
-
-const getDisabledElement = ( {
-	eventHandlers,
-	child,
-	childrenWithPopover,
-	mergedRefs,
-} ) => {
-	return cloneElement(
-		<span className="disabled-element-wrapper">
-			{ cloneElement( eventCatcher, eventHandlers ) }
-			{ cloneElement( child, {
-				children: childrenWithPopover,
-				ref: mergedRefs,
-			} ) }
-		</span>,
-		{ ...eventHandlers }
-	);
-};
-
-const getRegularElement = ( {
-	child,
-	eventHandlers,
-	childrenWithPopover,
-	mergedRefs,
-} ) => {
-	return cloneElement( child, {
-		...eventHandlers,
-		children: childrenWithPopover,
-		ref: mergedRefs,
-	} );
-};
-
-const addPopoverToGrandchildren = ( {
-	anchor,
-	grandchildren,
-	isOver,
-	offset,
-	position,
-	shortcut,
-	text,
-	className,
-	...props
-} ) =>
-	concatChildren(
-		grandchildren,
-		isOver && (
-			<Popover
-				focusOnMount={ false }
-				position={ position }
-				className={ classNames( 'components-tooltip', className ) }
-				aria-hidden="true"
-				animate={ false }
-				offset={ offset }
-				anchor={ anchor }
-				shift
-				{ ...props }
-			>
-				{ text }
-				<Shortcut
-					className="components-tooltip__shortcut"
-					shortcut={ shortcut }
-				/>
-			</Popover>
-		)
-	);
-
-const emitToChild = ( children, eventName, event ) => {
-	if ( Children.count( children ) !== 1 ) {
-		return;
-	}
-
-	const child = Children.only( children );
-
-	// If the underlying element is disabled, do not emit the event.
-	if ( child.props.disabled ) {
-		return;
-	}
-
-	if ( typeof child.props[ eventName ] === 'function' ) {
-		child.props[ eventName ]( event );
-	}
-};
-
-function Tooltip( props ) {
-	const {
-		children,
-		position = 'bottom middle',
-		text,
-		shortcut,
-		delay = TOOLTIP_DELAY,
-		...popoverProps
-	} = props;
-	/**
-	 * Whether a mouse is currently pressed, used in determining whether
-	 * to handle a focus event as displaying the tooltip immediately.
-	 *
-	 * @type {boolean}
-	 */
-	const [ isMouseDown, setIsMouseDown ] = useState( false );
-	const [ isOver, setIsOver ] = useState( false );
-	const delayedSetIsOver = useDebounce( setIsOver, delay );
-	// Using internal state (instead of a ref) for the popover anchor to make sure
-	// that the component re-renders when the anchor updates.
-	const [ popoverAnchor, setPopoverAnchor ] = useState( null );
-
-	// Create a reference to the Tooltip's child, to be passed to the Popover
-	// so that the Tooltip can be correctly positioned. Also, merge with the
-	// existing ref for the first child, so that its ref is preserved.
-	const existingChildRef = Children.toArray( children )[ 0 ]?.ref;
-	const mergedChildRefs = useMergeRefs( [
-		setPopoverAnchor,
-		existingChildRef,
-	] );
-
-	const createMouseDown = ( event ) => {
-		// In firefox, the mouse down event is also fired when the select
-		// list is chosen.
-		// Cancel further processing because re-rendering of child components
-		// causes onChange to be triggered with the old value.
-		// See https://github.com/WordPress/gutenberg/pull/42483
-		if ( event.target.tagName === 'OPTION' ) {
-			return;
-		}
-
-		// Preserve original child callback behavior.
-		emitToChild( children, 'onMouseDown', event );
-
-		// On mouse down, the next `mouseup` should revert the value of the
-		// instance property and remove its own event handler. The bind is
-		// made on the document since the `mouseup` might not occur within
-		// the bounds of the element.
-		document.addEventListener( 'mouseup', cancelIsMouseDown );
-		setIsMouseDown( true );
-	};
-
-	const createMouseUp = ( event ) => {
-		// In firefox, the mouse up event is also fired when the select
-		// list is chosen.
-		// Cancel further processing because re-rendering of child components
-		// causes onChange to be triggered with the old value.
-		// See https://github.com/WordPress/gutenberg/pull/42483
-		if ( event.target.tagName === 'OPTION' ) {
-			return;
-		}
-
-		emitToChild( children, 'onMouseUp', event );
-		document.removeEventListener( 'mouseup', cancelIsMouseDown );
-		setIsMouseDown( false );
-	};
-
-	const createMouseEvent = ( type ) => {
-		if ( type === 'mouseUp' ) return createMouseUp;
-		if ( type === 'mouseDown' ) return createMouseDown;
-	};
-
-	/**
-	 * Prebound `isInMouseDown` handler, created as a constant reference to
-	 * assure ability to remove in component unmount.
-	 *
-	 * @type {Function}
-	 */
-	const cancelIsMouseDown = createMouseEvent( 'mouseUp' );
-
-	const createToggleIsOver = ( eventName, isDelayed ) => {
-		return ( event ) => {
-			// Preserve original child callback behavior.
-			emitToChild( children, eventName, event );
-
-			// Mouse events behave unreliably in React for disabled elements,
-			// firing on mouseenter but not mouseleave.  Further, the default
-			// behavior for disabled elements in some browsers is to ignore
-			// mouse events. Don't bother trying to handle them.
-			//
-			// See: https://github.com/facebook/react/issues/4251
-			if ( event.currentTarget.disabled ) {
-				return;
-			}
-
-			// A focus event will occur as a result of a mouse click, but it
-			// should be disambiguated between interacting with the button and
-			// using an explicit focus shift as a cue to display the tooltip.
-			if ( 'focus' === event.type && isMouseDown ) {
-				return;
-			}
-
-			// Needed in case unsetting is over while delayed set pending, i.e.
-			// quickly blur/mouseleave before delayedSetIsOver is called.
-			delayedSetIsOver.cancel();
-
-			const _isOver = [ 'focus', 'mouseenter' ].includes( event.type );
-			if ( _isOver === isOver ) {
-				return;
-			}
-
-			if ( isDelayed ) {
-				delayedSetIsOver( _isOver );
-			} else {
-				setIsOver( _isOver );
-			}
-		};
-	};
-	const clearOnUnmount = () => {
-		delayedSetIsOver.cancel();
-		document.removeEventListener( 'mouseup', cancelIsMouseDown );
-	};
-
-	// Ignore reason: updating the deps array here could cause unexpected changes in behavior.
-	// Deferring until a more detailed investigation/refactor can be performed.
-	// eslint-disable-next-line react-hooks/exhaustive-deps
-	useEffect( () => clearOnUnmount, [] );
-
-	if ( Children.count( children ) !== 1 ) {
-		if ( 'development' === process.env.NODE_ENV ) {
-			// eslint-disable-next-line no-console
-			console.error(
-				'Tooltip should be called with only a single child element.'
-			);
-		}
-
-		return children;
-	}
-
-	const eventHandlers = {
-		onMouseEnter: createToggleIsOver( 'onMouseEnter', true ),
-		onMouseLeave: createToggleIsOver( 'onMouseLeave' ),
-		onClick: createToggleIsOver( 'onClick' ),
-		onFocus: createToggleIsOver( 'onFocus' ),
-		onBlur: createToggleIsOver( 'onBlur' ),
-		onMouseDown: createMouseEvent( 'mouseDown' ),
-	};
-
-	const child = Children.only( children );
-	const { children: grandchildren, disabled } = child.props;
-	const getElementWithPopover = disabled
-		? getDisabledElement
-		: getRegularElement;
-
-	const popoverData = {
-		anchor: popoverAnchor,
-		isOver,
-		offset: 4,
-		position,
-		shortcut,
-		text,
-	};
-	const childrenWithPopover = addPopoverToGrandchildren( {
-		grandchildren,
-		...popoverData,
-		...popoverProps,
-	} );
-
-	return getElementWithPopover( {
-		child,
-		eventHandlers,
-		childrenWithPopover,
-		mergedRefs: mergedChildRefs,
-	} );
-}
-
-export default Tooltip;

package/src/tooltip/stories/index.story.js

@@ -1,85 +0,0 @@
-/**
- * Internal dependencies
- */
-import Tooltip from '../';
-
-export default {
-	title: 'Components/ToolTip',
-	component: Tooltip,
-	argTypes: {
-		delay: { control: 'number' },
-		position: {
-			control: {
-				type: 'select',
-				options: [
-					'top left',
-					'top center',
-					'top right',
-					'bottom left',
-					'bottom center',
-					'bottom right',
-				],
-			},
-		},
-		text: { control: 'text' },
-	},
-	parameters: {
-		docs: { canvas: { sourceState: 'shown' } },
-	},
-};
-
-const Template = ( args ) => {
-	return <Tooltip { ...args } />;
-};
-
-export const Default = Template.bind( {} );
-Default.args = {
-	text: 'More information',
-	children: (
-		<div
-			style={ {
-				margin: '50px auto',
-				width: '200px',
-				padding: '20px',
-				textAlign: 'center',
-				border: '1px solid #ccc',
-			} }
-		>
-			Hover for more information
-		</div>
-	),
-};
-
-export const SmallTarget = Template.bind( {} );
-SmallTarget.args = {
-	...Default.args,
-	children: (
-		<div
-			style={ {
-				margin: '50px auto',
-				width: 'min-content',
-				padding: '4px',
-				textAlign: 'center',
-				border: '1px solid #ccc',
-			} }
-		>
-			Small target
-		</div>
-	),
-};
-
-export const DisabledChild = Template.bind( {} );
-DisabledChild.args = {
-	...Default.args,
-	children: (
-		<button
-			disabled
-			onClick={ () =>
-				// eslint-disable-next-line no-alert
-				window.alert( 'This alert should not be triggered' )
-			}
-		>
-			Hover me, but I am disabled
-		</button>
-	),
-};

package/src/tooltip/test/index.js

@@ -1,323 +0,0 @@
-/**
- * External dependencies
- */
-import { render, screen, waitFor } from '@testing-library/react';
-import userEvent from '@testing-library/user-event';
-
-/**
- * Internal dependencies
- */
-import Tooltip from '../';
-import Button from '../../button';
-import { TOOLTIP_DELAY } from '../index.js';
-
-/**
- * WordPress dependencies
- */
-import { shortcutAriaLabel } from '@wordpress/keycodes';
-
-const props = {
-	text: 'tooltip text',
-	delay: TOOLTIP_DELAY,
-};
-
-function getWrappingPopoverElement( element ) {
-	return element.closest( '.components-popover' );
-}
-
-describe( 'Tooltip', () => {
-	it( 'should not render the tooltip if multiple children are passed', async () => {
-		const user = userEvent.setup();
-
-		render(
-			<Tooltip { ...props }>
-				<Button>Button 1</Button>
-				<Button>Button 2</Button>
-			</Tooltip>
-		);
-
-		await user.tab();
-
-		expect( screen.queryByText( 'tooltip text' ) ).not.toBeInTheDocument();
-	} );
-
-	it( 'should not render the tooltip if there is no focus', () => {
-		render(
-			<Tooltip { ...props }>
-				<Button>Hover Me!</Button>
-			</Tooltip>
-		);
-
-		expect(
-			screen.getByRole( 'button', { name: 'Hover Me!' } )
-		).toBeVisible();
-		expect( screen.queryByText( 'tooltip text' ) ).not.toBeInTheDocument();
-	} );
-
-	it( 'should render the tooltip when focusing the tooltip anchor via tab', async () => {
-		const user = userEvent.setup();
-
-		render(
-			<Tooltip { ...props }>
-				<Button>Hover Me!</Button>
-			</Tooltip>
-		);
-
-		await user.tab();
-
-		expect(
-			screen.getByRole( 'button', { name: /Hover me!/i } )
-		).toHaveFocus();
-
-		await waitFor( () =>
-			expect( screen.getByText( 'tooltip text' ) ).toBeVisible()
-		);
-
-		// Wait for the tooltip element to be positioned (aligned with the button)
-		await waitFor( () =>
-			expect(
-				getWrappingPopoverElement( screen.getByText( 'tooltip text' ) )
-			).toBePositionedPopover()
-		);
-	} );
-
-	it( 'should render the tooltip when the tooltip anchor is hovered', async () => {
-		const user = userEvent.setup();
-
-		render(
-			<Tooltip { ...props }>
-				<Button>Hover Me!</Button>
-			</Tooltip>
-		);
-
-		const button = screen.getByRole( 'button', { name: 'Hover Me!' } );
-
-		await user.hover( button );
-
-		await waitFor( () =>
-			expect( screen.getByText( 'tooltip text' ) ).toBeVisible()
-		);
-
-		// Wait for the tooltip element to be positioned (aligned with the button)
-		await waitFor( () =>
-			expect(
-				getWrappingPopoverElement( screen.getByText( 'tooltip text' ) )
-			).toBePositionedPopover()
-		);
-
-		await user.unhover( button );
-
-		expect( screen.queryByText( 'tooltip text' ) ).not.toBeInTheDocument();
-	} );
-
-	it( 'should not show tooltip on focus as result of mouse click', async () => {
-		const user = userEvent.setup();
-
-		render(
-			<Tooltip { ...props }>
-				<Button>Hover Me!</Button>
-			</Tooltip>
-		);
-
-		await user.click( screen.getByRole( 'button', { text: 'Hover Me!' } ) );
-
-		expect( screen.queryByText( 'tooltip text' ) ).not.toBeInTheDocument();
-	} );
-
-	it( 'should respect custom delay prop when showing tooltip', async () => {
-		const user = userEvent.setup( { delay: TOOLTIP_DELAY } );
-		const CUSTOM_DELAY = TOOLTIP_DELAY + 25;
-
-		render(
-			<Tooltip { ...props } delay={ CUSTOM_DELAY }>
-				<Button>Hover Me!</Button>
-			</Tooltip>
-		);
-
-		const button = screen.getByRole( 'button', { name: 'Hover Me!' } );
-
-		await user.hover( button );
-
-		expect( screen.queryByText( 'tooltip text' ) ).not.toBeInTheDocument();
-
-		await waitFor( () =>
-			expect( screen.getByText( 'tooltip text' ) ).toBeVisible()
-		);
-
-		// Wait for the tooltip element to be positioned (aligned with the button)
-		await waitFor( () =>
-			expect(
-				getWrappingPopoverElement( screen.getByText( 'tooltip text' ) )
-			).toBePositionedPopover()
-		);
-	} );
-
-	it( 'should show tooltip when an element is disabled', async () => {
-		const user = userEvent.setup();
-
-		render(
-			<Tooltip { ...props }>
-				<Button disabled>Click me</Button>
-			</Tooltip>
-		);
-
-		const button = screen.getByRole( 'button', { name: /Click me/i } );
-
-		expect( button ).toBeVisible();
-		expect( button ).toBeDisabled();
-
-		await user.hover( button );
-
-		await waitFor( () =>
-			expect( screen.getByText( 'tooltip text' ) ).toBeVisible()
-		);
-
-		// Wait for the tooltip element to be positioned (aligned with the button)
-		await waitFor( () =>
-			expect(
-				getWrappingPopoverElement( screen.getByText( 'tooltip text' ) )
-			).toBePositionedPopover()
-		);
-	} );
-
-	it( 'should not emit events back to children when they are disabled', async () => {
-		const user = userEvent.setup();
-		const onClickMock = jest.fn();
-
-		const { container } = render(
-			<Tooltip { ...props }>
-				<Button disabled onClick={ onClickMock }>
-					Click me
-				</Button>
-			</Tooltip>
-		);
-
-		// Note: this is testing for implementation details,
-		// but couldn't find a better way.
-		const buttonRect = screen
-			.getByRole( 'button', { name: 'Click me' } )
-			.getBoundingClientRect();
-		// eslint-disable-next-line testing-library/no-container, testing-library/no-node-access
-		const eventCatcher = container.querySelector( '.event-catcher' );
-		await user.click( eventCatcher );
-		expect( onClickMock ).not.toHaveBeenCalled();
-
-		const eventCatcherRect = eventCatcher.getBoundingClientRect();
-		expect( buttonRect ).toEqual( eventCatcherRect );
-	} );
-
-	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 }
-					>
-						Hover Me!
-					</Button>
-				</Tooltip>
-				<Button>Hover me instead!</Button>
-			</>
-		);
-
-		await user.hover(
-			screen.getByRole( 'button', {
-				name: 'Hover Me!',
-			} )
-		);
-
-		// Tooltip hasn't appeared yet
-		expect( screen.queryByText( 'tooltip text' ) ).not.toBeInTheDocument();
-		expect( onMouseEnterMock ).toHaveBeenCalledTimes( 1 );
-
-		// Advance time by MOUSE_LEAVE_DELAY time
-		await new Promise( ( resolve ) =>
-			setTimeout( resolve, MOUSE_LEAVE_DELAY )
-		);
-
-		expect( screen.queryByText( 'tooltip text' ) ).not.toBeInTheDocument();
-
-		// Hover the other button, meaning that the mouse will leave the tooltip anchor
-		await user.hover(
-			screen.getByRole( 'button', {
-				name: 'Hover me instead!',
-			} )
-		);
-
-		// Tooltip still hasn't appeared yet
-		expect( screen.queryByText( 'tooltip text' ) ).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.queryByText( 'tooltip text' ) ).not.toBeInTheDocument();
-	} );
-
-	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">
-				<Button>Hover Me!</Button>
-			</Tooltip>
-		);
-
-		await user.hover( screen.getByRole( 'button', { name: 'Hover Me!' } ) );
-
-		await waitFor( () =>
-			expect( screen.getByText( 'shortcut text' ) ).toBeVisible()
-		);
-
-		// Wait for the tooltip element to be positioned (aligned with the button)
-		await waitFor( () =>
-			expect(
-				getWrappingPopoverElement( screen.getByText( 'shortcut text' ) )
-			).toBePositionedPopover()
-		);
-	} );
-
-	it( 'should render the shortcut display text and aria-label when an object is passed as the shortcut with the correct properties', async () => {
-		const user = userEvent.setup();
-
-		render(
-			<Tooltip
-				{ ...props }
-				shortcut={ {
-					display: '⇧⌘,',
-					ariaLabel: shortcutAriaLabel.primaryShift( ',' ),
-				} }
-			>
-				<Button>Hover Me!</Button>
-			</Tooltip>
-		);
-
-		await user.hover( screen.getByRole( 'button', { name: 'Hover Me!' } ) );
-
-		await waitFor( () =>
-			expect( screen.getByText( '⇧⌘,' ) ).toBeVisible()
-		);
-
-		expect( screen.getByText( '⇧⌘,' ) ).toHaveAttribute(
-			'aria-label',
-			'Control + Shift + Comma'
-		);
-
-		// Wait for the tooltip element to be positioned (aligned with the button)
-		await waitFor( () =>
-			expect(
-				getWrappingPopoverElement( screen.getByText( '⇧⌘,' ) )
-			).toBePositionedPopover()
-		);
-	} );
-} );