@wordpress/components 23.2.0 → 23.3.0

package/src/h-stack/component.tsx

@@ -20,7 +20,6 @@ function UnconnectedHStack(
  *
  * `HStack` can render anything inside.
  *
- * @example
  * ```jsx
  * import {
  * 	__experimentalHStack as HStack,

package/src/higher-order/with-filters/test/index.js

@@ -1,7 +1,7 @@
 /**
  * External dependencies
  */
-import { act, render } from '@testing-library/react';
+import { render, waitFor } from '@testing-library/react';
 
 /**
  * WordPress dependencies
@@ -13,8 +13,6 @@ import { addFilter, removeAllFilters, removeFilter } from '@wordpress/hooks';
  */
 import withFilters from '..';
 
-jest.useFakeTimers();
-
 describe( 'withFilters', () => {
 	const hookName = 'EnhancedComponent';
 	const MyComponent = () => <div>My component</div>;
@@ -65,7 +63,7 @@ describe( 'withFilters', () => {
 		expect( container ).toMatchSnapshot();
 	} );
 
-	it( 'should not re-render component when new filter added before component was mounted', () => {
+	it( 'should not re-render component when new filter added before component was mounted', async () => {
 		const SpiedComponent = jest.fn( () => <div>Spied component</div> );
 		addFilter(
 			hookName,
@@ -81,13 +79,13 @@ describe( 'withFilters', () => {
 
 		const { container } = render( <EnhancedComponent /> );
 
-		act( () => jest.runAllTimers() );
-
-		expect( SpiedComponent ).toHaveBeenCalledTimes( 1 );
+		await waitFor( () =>
+			expect( SpiedComponent ).toHaveBeenCalledTimes( 1 )
+		);
 		expect( container ).toMatchSnapshot();
 	} );
 
-	it( 'should re-render component once when new filter added after component was mounted', () => {
+	it( 'should re-render component once when new filter added after component was mounted', async () => {
 		const SpiedComponent = jest.fn( () => <div>Spied component</div> );
 		const EnhancedComponent = withFilters( hookName )( SpiedComponent );
 
@@ -106,13 +104,13 @@ describe( 'withFilters', () => {
 				)
 		);
 
-		act( () => jest.runAllTimers() );
-
-		expect( SpiedComponent ).toHaveBeenCalledTimes( 1 );
+		await waitFor( () =>
+			expect( SpiedComponent ).toHaveBeenCalledTimes( 1 )
+		);
 		expect( container ).toMatchSnapshot();
 	} );
 
-	it( 'should re-render component once when two filters added in the same animation frame', () => {
+	it( 'should re-render component once when two filters added in the same animation frame', async () => {
 		const SpiedComponent = jest.fn( () => <div>Spied component</div> );
 		const EnhancedComponent = withFilters( hookName )( SpiedComponent );
 
@@ -141,13 +139,13 @@ describe( 'withFilters', () => {
 				)
 		);
 
-		act( () => jest.runAllTimers() );
-
-		expect( SpiedComponent ).toHaveBeenCalledTimes( 1 );
+		await waitFor( () =>
+			expect( SpiedComponent ).toHaveBeenCalledTimes( 1 )
+		);
 		expect( container ).toMatchSnapshot();
 	} );
 
-	it( 'should re-render component twice when new filter added and removed in two different animation frames', () => {
+	it( 'should re-render component twice when new filter added and removed in two different animation frames', async () => {
 		const SpiedComponent = jest.fn( () => <div>Spied component</div> );
 		const EnhancedComponent = withFilters( hookName )( SpiedComponent );
 		const { container } = render( <EnhancedComponent /> );
@@ -165,17 +163,19 @@ describe( 'withFilters', () => {
 				)
 		);
 
-		act( () => jest.runAllTimers() );
+		await waitFor( () =>
+			expect( SpiedComponent ).toHaveBeenCalledTimes( 1 )
+		);
 
 		removeFilter( hookName, 'test/enhanced-component-spy' );
 
-		act( () => jest.runAllTimers() );
-
-		expect( SpiedComponent ).toHaveBeenCalledTimes( 2 );
+		await waitFor( () =>
+			expect( SpiedComponent ).toHaveBeenCalledTimes( 2 )
+		);
 		expect( container ).toMatchSnapshot();
 	} );
 
-	it( 'should re-render both components once each when one filter added', () => {
+	it( 'should re-render both components once each when one filter added', async () => {
 		const SpiedComponent = jest.fn( () => <div>Spied component</div> );
 		const EnhancedComponent = withFilters( hookName )( SpiedComponent );
 
@@ -200,9 +200,9 @@ describe( 'withFilters', () => {
 				)
 		);
 
-		act( () => jest.runAllTimers() );
-
-		expect( SpiedComponent ).toHaveBeenCalledTimes( 2 );
+		await waitFor( () =>
+			expect( SpiedComponent ).toHaveBeenCalledTimes( 2 )
+		);
 		expect( container ).toMatchSnapshot();
 	} );
 } );

package/src/higher-order/with-focus-outside/test/index.js

@@ -1,7 +1,7 @@
 /**
  * External dependencies
  */
-import { render, screen } from '@testing-library/react';
+import { render, screen, waitFor } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 
 /**
@@ -14,8 +14,6 @@ import { Component } from '@wordpress/element';
  */
 import withFocusOutside from '../';
 
-jest.useFakeTimers();
-
 let onFocusOutside;
 
 describe( 'withFocusOutside', () => {
@@ -57,7 +55,7 @@ describe( 'withFocusOutside', () => {
 		document.hasFocus = origHasFocus;
 	} );
 
-	it( 'should not call handler if focus shifts to element within component', () => {
+	it( 'should not call handler if focus shifts to element within component', async () => {
 		render( <TestComponent onFocusOutside={ onFocusOutside } /> );
 
 		const input = screen.getByRole( 'textbox' );
@@ -67,15 +65,11 @@ describe( 'withFocusOutside', () => {
 		input.blur();
 		button.focus();
 
-		jest.runAllTimers();
-
-		expect( onFocusOutside ).not.toHaveBeenCalled();
+		await waitFor( () => expect( onFocusOutside ).not.toHaveBeenCalled() );
 	} );
 
 	it( 'should not call handler if focus transitions via click to button', async () => {
-		const user = userEvent.setup( {
-			advanceTimers: jest.advanceTimersByTime,
-		} );
+		const user = userEvent.setup();
 		render( <TestComponent onFocusOutside={ onFocusOutside } /> );
 
 		const input = screen.getByRole( 'textbox' );
@@ -84,24 +78,20 @@ describe( 'withFocusOutside', () => {
 		input.focus();
 		await user.click( button );
 
-		jest.runAllTimers();
-
-		expect( onFocusOutside ).not.toHaveBeenCalled();
+		await waitFor( () => expect( onFocusOutside ).not.toHaveBeenCalled() );
 	} );
 
-	it( 'should call handler if focus doesn’t shift to element within component', () => {
+	it( 'should call handler if focus doesn’t shift to element within component', async () => {
 		render( <TestComponent onFocusOutside={ onFocusOutside } /> );
 
 		const input = screen.getByRole( 'textbox' );
 		input.focus();
 		input.blur();
 
-		jest.runAllTimers();
-
-		expect( onFocusOutside ).toHaveBeenCalled();
+		await waitFor( () => expect( onFocusOutside ).toHaveBeenCalled() );
 	} );
 
-	it( 'should not call handler if focus shifts outside the component when the document does not have focus', () => {
+	it( 'should not call handler if focus shifts outside the component when the document does not have focus', async () => {
 		render( <TestComponent onFocusOutside={ onFocusOutside } /> );
 
 		// Force document.hasFocus() to return false to simulate the window/document losing focus
@@ -112,12 +102,10 @@ describe( 'withFocusOutside', () => {
 		input.focus();
 		input.blur();
 
-		jest.runAllTimers();
-
-		expect( onFocusOutside ).not.toHaveBeenCalled();
+		await waitFor( () => expect( onFocusOutside ).not.toHaveBeenCalled() );
 	} );
 
-	it( 'should cancel check when unmounting while queued', () => {
+	it( 'should cancel check when unmounting while queued', async () => {
 		const { rerender } = render(
 			<TestComponent onFocusOutside={ onFocusOutside } />
 		);
@@ -128,8 +116,6 @@ describe( 'withFocusOutside', () => {
 
 		rerender( <div /> );
 
-		jest.runAllTimers();
-
-		expect( onFocusOutside ).not.toHaveBeenCalled();
+		await waitFor( () => expect( onFocusOutside ).not.toHaveBeenCalled() );
 	} );
 } );

package/src/higher-order/with-focus-return/test/index.js

@@ -14,8 +14,6 @@ import { Component } from '@wordpress/element';
  */
 import withFocusReturn from '../';
 
-jest.useFakeTimers();
-
 class Test extends Component {
 	render() {
 		const { className, focusHistory } = this.props;
@@ -86,9 +84,7 @@ describe( 'withFocusReturn()', () => {
 		} );
 
 		it( 'should switch focus back when unmounted while having focus', async () => {
-			const user = userEvent.setup( {
-				advanceTimers: jest.advanceTimersByTime,
-			} );
+			const user = userEvent.setup();
 
 			const { unmount } = render( <Composite />, {
 				container: document.body.appendChild(

package/src/input-control/input-field.tsx

@@ -226,7 +226,9 @@ function InputField(
 			onMouseDown={ handleOnMouseDown }
 			ref={ ref }
 			inputSize={ size }
-			value={ value }
+			// Fallback to `''` to avoid "uncontrolled to controlled" warning.
+			// See https://github.com/WordPress/gutenberg/pull/47250 for details.
+			value={ value ?? '' }
 			type={ type }
 		/>
 	);

package/src/input-control/test/index.js

@@ -14,12 +14,7 @@ import { useState } from '@wordpress/element';
  */
 import BaseInputControl from '../';
 
-jest.useFakeTimers();
-
-const setupUser = () =>
-	userEvent.setup( {
-		advanceTimers: jest.advanceTimersByTime,
-	} );
+const setupUser = () => userEvent.setup();
 
 const getInput = () => screen.getByTestId( 'input' );
 

package/src/isolated-event-container/test/index.js

@@ -9,13 +9,9 @@ import userEvent from '@testing-library/user-event';
  */
 import IsolatedEventContainer from '../';
 
-jest.useFakeTimers();
-
 describe( 'IsolatedEventContainer', () => {
 	it( 'should pass props to container', async () => {
-		const user = userEvent.setup( {
-			advanceTimers: jest.advanceTimersByTime,
-		} );
+		const user = userEvent.setup();
 		const clickHandler = jest.fn();
 		render(
 			<IsolatedEventContainer
@@ -47,9 +43,7 @@ describe( 'IsolatedEventContainer', () => {
 	} );
 
 	it( 'should stop event propagation only for mousedown, but not for keydown', async () => {
-		const user = userEvent.setup( {
-			advanceTimers: jest.advanceTimersByTime,
-		} );
+		const user = userEvent.setup();
 
 		const mousedownHandler = jest.fn();
 		const keydownHandler = jest.fn();

package/src/keyboard-shortcuts/README.md

@@ -41,7 +41,7 @@ The component accepts the following props:
 
 Elements to render, upon whom key events are to be monitored.
 
--   Type: `Element` | `Element[]`
+-   Type: `ReactNode`
 -   Required: No
 
 ### shortcuts

package/src/keyboard-shortcuts/index.tsx

@@ -0,0 +1,93 @@
+/**
+ * WordPress dependencies
+ */
+import { useRef, Children } from '@wordpress/element';
+import { useKeyboardShortcut } from '@wordpress/compose';
+
+/**
+ * Internal dependencies
+ */
+import type { KeyboardShortcutProps, KeyboardShortcutsProps } from './types';
+
+function KeyboardShortcut( {
+	target,
+	callback,
+	shortcut,
+	bindGlobal,
+	eventName,
+}: KeyboardShortcutProps ) {
+	useKeyboardShortcut( shortcut, callback, {
+		bindGlobal,
+		target,
+		eventName,
+	} );
+
+	return null;
+}
+
+/**
+ * `KeyboardShortcuts` is a component which handles keyboard sequences during the lifetime of the rendering element.
+ *
+ * When passed children, it will capture key events which occur on or within the children. If no children are passed, events are captured on the document.
+ *
+ * It uses the [Mousetrap](https://craig.is/killing/mice) library to implement keyboard sequence bindings.
+ *
+ * ```jsx
+ * import { KeyboardShortcuts } from '@wordpress/components';
+ * import { useState } from '@wordpress/element';
+ *
+ * const MyKeyboardShortcuts = () => {
+ * 	const [ isAllSelected, setIsAllSelected ] = useState( false );
+ * 	const selectAll = () => {
+ * 		setIsAllSelected( true );
+ * 	};
+ *
+ * 	return (
+ * 		<div>
+ * 			<KeyboardShortcuts
+ * 				shortcuts={ {
+ * 					'mod+a': selectAll,
+ * 				} }
+ * 			/>
+ * 			[cmd/ctrl + A] Combination pressed? { isAllSelected ? 'Yes' : 'No' }
+ * 		</div>
+ * 	);
+ * };
+ * ```
+ */
+function KeyboardShortcuts( {
+	children,
+	shortcuts,
+	bindGlobal,
+	eventName,
+}: KeyboardShortcutsProps ) {
+	const target = useRef( null );
+
+	const element = Object.entries( shortcuts ?? {} ).map(
+		( [ shortcut, callback ] ) => (
+			<KeyboardShortcut
+				key={ shortcut }
+				shortcut={ shortcut }
+				callback={ callback }
+				bindGlobal={ bindGlobal }
+				eventName={ eventName }
+				target={ target }
+			/>
+		)
+	);
+
+	// Render as non-visual if there are no children pressed. Keyboard
+	// events will be bound to the document instead.
+	if ( ! Children.count( children ) ) {
+		return <>{ element }</>;
+	}
+
+	return (
+		<div ref={ target }>
+			{ element }
+			{ children }
+		</div>
+	);
+}
+
+export default KeyboardShortcuts;

package/src/keyboard-shortcuts/stories/index.tsx

@@ -0,0 +1,60 @@
+/**
+ * External dependencies
+ */
+import type { ComponentMeta, ComponentStory } from '@storybook/react';
+
+/**
+ * Internal dependencies
+ */
+import KeyboardShortcuts from '..';
+
+const meta: ComponentMeta< typeof KeyboardShortcuts > = {
+	component: KeyboardShortcuts,
+	title: 'Components/KeyboardShortcuts',
+	parameters: {
+		controls: { expanded: true },
+		docs: { source: { state: 'open' } },
+	},
+};
+export default meta;
+
+const Template: ComponentStory< typeof KeyboardShortcuts > = ( props ) => (
+	<KeyboardShortcuts { ...props } />
+);
+
+export const Default = Template.bind( {} );
+Default.args = {
+	shortcuts: {
+		// eslint-disable-next-line no-alert
+		a: () => window.alert( 'You hit "a"!' ),
+		// eslint-disable-next-line no-alert
+		b: () => window.alert( 'You hit "b"!' ),
+	},
+	children: (
+		<div>
+			<p>{ `Hit the "a" or "b" key in this textarea:` }</p>
+			<textarea />
+		</div>
+	),
+};
+Default.parameters = {
+	docs: {
+		source: {
+			code: `
+<KeyboardShortcuts
+  shortcuts={{
+    a: () => window.alert('You hit "a"!'),
+    b: () => window.alert('You hit "b"!'),
+  }}
+>
+  <div>
+    <p>
+      Hit the "a" or "b" key in this textarea:
+    </p>
+    <textarea />
+  </div>
+</KeyboardShortcuts>
+			`,
+		},
+	},
+};

package/src/keyboard-shortcuts/test/{index.js → index.tsx}

@@ -1,19 +1,29 @@
 /**
  * External dependencies
  */
-import { fireEvent, render, screen } from '@testing-library/react';
+import { createEvent, fireEvent, render, screen } from '@testing-library/react';
 
 /**
  * Internal dependencies
  */
-import KeyboardShortcuts from '../';
+import KeyboardShortcuts from '..';
 
 describe( 'KeyboardShortcuts', () => {
-	function keyPress( which, target ) {
+	function keyPress(
+		which: KeyboardEvent[ 'which' ],
+		target: Parameters< typeof fireEvent >[ 0 ]
+	) {
 		[ 'keydown', 'keypress', 'keyup' ].forEach( ( eventName ) => {
-			const event = new window.Event( eventName, { bubbles: true } );
-			event.keyCode = which;
-			event.which = which;
+			const event = createEvent(
+				eventName,
+				target,
+				{
+					bubbles: true,
+					keyCode: which,
+					which,
+				},
+				{ EventType: 'KeyboardEvent' }
+			);
 			fireEvent( target, event );
 		} );
 	}

package/src/keyboard-shortcuts/types.ts

@@ -0,0 +1,51 @@
+/**
+ * WordPress dependencies
+ */
+import type { useKeyboardShortcut } from '@wordpress/compose';
+
+// TODO: We wouldn't have to do this if this type was exported from `@wordpress/compose`.
+type WPKeyboardShortcutConfig = NonNullable<
+	Parameters< typeof useKeyboardShortcut >[ 2 ]
+>;
+
+export type KeyboardShortcutProps = {
+	shortcut: string | string[];
+	/**
+	 * @see {@link https://craig.is/killing/mice Mousetrap documentation}
+	 */
+	callback: ( event: Mousetrap.ExtendedKeyboardEvent, combo: string ) => void;
+} & Pick< WPKeyboardShortcutConfig, 'bindGlobal' | 'eventName' | 'target' >;
+
+export type KeyboardShortcutsProps = {
+	/**
+	 * Elements to render, upon whom key events are to be monitored.
+	 */
+	children?: React.ReactNode;
+	/**
+	 * An object of shortcut bindings, where each key is a keyboard combination,
+	 * the value of which is the callback to be invoked when the key combination is pressed.
+	 *
+	 * The value of each shortcut should be a consistent function reference, not an anonymous function.
+	 * Otherwise, the callback will not be correctly unbound when the component unmounts.
+	 *
+	 * The `KeyboardShortcuts` component will not update to reflect a changed `shortcuts` prop.
+	 * If you need to change shortcuts, mount a separate `KeyboardShortcuts` element,
+	 * which can be achieved by assigning a unique `key` prop.
+	 *
+	 * @see {@link https://craig.is/killing/mice Mousetrap documentation}
+	 */
+	shortcuts: Record< string, KeyboardShortcutProps[ 'callback' ] >;
+	/**
+	 * By default, a callback will not be invoked if the key combination occurs in an editable field.
+	 * Pass `bindGlobal` as `true` if the key events should be observed globally, including within editable fields.
+	 *
+	 * Tip: If you need some but not all keyboard events to be observed globally,
+	 * simply render two distinct `KeyboardShortcuts` elements, one with and one without the `bindGlobal` prop.
+	 */
+	bindGlobal?: KeyboardShortcutProps[ 'bindGlobal' ];
+	/**
+	 * By default, a callback is invoked in response to the `keydown` event.
+	 * To override this, pass `eventName` with the name of a specific keyboard event.
+	 */
+	eventName?: KeyboardShortcutProps[ 'eventName' ];
+};

package/src/modal/index.tsx

@@ -202,8 +202,7 @@ function UnforwardedModal(
 										onClick={ onRequestClose }
 										icon={ close }
 										label={
-											closeButtonLabel ||
-											__( 'Close dialog' )
+											closeButtonLabel || __( 'Close' )
 										}
 									/>
 								) }

package/src/navigable-container/test/navigable-menu.js

@@ -9,8 +9,6 @@ import userEvent from '@testing-library/user-event';
  */
 import { NavigableMenu } from '../menu';
 
-jest.useFakeTimers();
-
 const NavigableMenuTestCase = ( props ) => (
 	<NavigableMenu { ...props }>
 		<button>Item 1</button>
@@ -46,9 +44,7 @@ describe( 'NavigableMenu', () => {
 	} );
 
 	it( 'moves focus on its focusable children by using the up/down arrow keys', async () => {
-		const user = userEvent.setup( {
-			advanceTimers: jest.advanceTimersByTime,
-		} );
+		const user = userEvent.setup();
 
 		const onNavigateSpy = jest.fn();
 
@@ -87,9 +83,7 @@ describe( 'NavigableMenu', () => {
 	} );
 
 	it( 'moves focus on its focusable children by using the left/right arrow keys when the `orientation`prop is set to `horizontal', async () => {
-		const user = userEvent.setup( {
-			advanceTimers: jest.advanceTimersByTime,
-		} );
+		const user = userEvent.setup();
 
 		const onNavigateSpy = jest.fn();
 
@@ -133,9 +127,7 @@ describe( 'NavigableMenu', () => {
 	} );
 
 	it( 'should stop at the edges when the `cycle` prop is set to `false`', async () => {
-		const user = userEvent.setup( {
-			advanceTimers: jest.advanceTimersByTime,
-		} );
+		const user = userEvent.setup();
 
 		const onNavigateSpy = jest.fn();
 
@@ -193,9 +185,7 @@ describe( 'NavigableMenu', () => {
 	} );
 
 	it( 'stops keydown event propagation when arrow keys are pressed, regardless of the `orientation` prop', async () => {
-		const user = userEvent.setup( {
-			advanceTimers: jest.advanceTimersByTime,
-		} );
+		const user = userEvent.setup();
 
 		const externalWrapperOnKeyDownSpy = jest.fn();
 
@@ -224,9 +214,7 @@ describe( 'NavigableMenu', () => {
 	} );
 
 	it( 'skips its internal logic when the tab key is pressed', async () => {
-		const user = userEvent.setup( {
-			advanceTimers: jest.advanceTimersByTime,
-		} );
+		const user = userEvent.setup();
 
 		render(
 			<>

package/src/navigable-container/test/tababble-container.js

@@ -9,8 +9,6 @@ import userEvent from '@testing-library/user-event';
  */
 import { TabbableContainer } from '../tabbable';
 
-jest.useFakeTimers();
-
 const TabbableContainerTestCase = ( props ) => (
 	<TabbableContainer { ...props }>
 		<button>Item 1</button>
@@ -49,9 +47,7 @@ describe( 'TabbableContainer', () => {
 	} );
 
 	it( 'moves focus on its tabbable children by using the tab key', async () => {
-		const user = userEvent.setup( {
-			advanceTimers: jest.advanceTimersByTime,
-		} );
+		const user = userEvent.setup();
 
 		const onNavigateSpy = jest.fn();
 
@@ -80,9 +76,7 @@ describe( 'TabbableContainer', () => {
 	} );
 
 	it( 'should stop at the edges when the `cycle` prop is set to `false`', async () => {
-		const user = userEvent.setup( {
-			advanceTimers: jest.advanceTimersByTime,
-		} );
+		const user = userEvent.setup();
 
 		const onNavigateSpy = jest.fn();
 
@@ -141,9 +135,7 @@ describe( 'TabbableContainer', () => {
 	} );
 
 	it( 'stops keydown event propagation when the tab key is pressed', async () => {
-		const user = userEvent.setup( {
-			advanceTimers: jest.advanceTimersByTime,
-		} );
+		const user = userEvent.setup();
 
 		const externalWrapperOnKeyDownSpy = jest.fn();