@wordpress/components 23.1.0 → 23.3.0

package/src/item-group/test/__snapshots__/index.js.snap

@@ -11,8 +11,8 @@ Snapshot Diff:
         role="listitem"
       >
         <div
--         class="components-item css-1uo9kmu-View-medium-item-spacedAround e19lxcc00"
-+         class="components-item css-10mizr-View-large-item-spacedAround e19lxcc00"
+-         class="components-item css-ufjlmj-View-medium-item-spacedAround e19lxcc00"
++         class="components-item css-17haj95-View-large-item-spacedAround e19lxcc00"
           data-wp-c16t="true"
           data-wp-component="Item"
         >
@@ -24,8 +24,8 @@ Snapshot Diff:
         role="listitem"
       >
         <div
--         class="components-item css-1uo9kmu-View-medium-item-spacedAround e19lxcc00"
-+         class="components-item css-10mizr-View-large-item-spacedAround e19lxcc00"
+-         class="components-item css-ufjlmj-View-medium-item-spacedAround e19lxcc00"
++         class="components-item css-17haj95-View-large-item-spacedAround e19lxcc00"
           data-wp-c16t="true"
           data-wp-component="Item"
         >
@@ -44,8 +44,8 @@ Snapshot Diff:
       role="listitem"
     >
       <div
--       class="components-item css-bsdqin-View-medium-item e19lxcc00"
-+       class="components-item css-1ohjtsa-View-large-item e19lxcc00"
+-       class="components-item css-cl593w-View-medium-item e19lxcc00"
++       class="components-item css-1yvqxd-View-large-item e19lxcc00"
         data-wp-c16t="true"
         data-wp-component="Item"
       >
@@ -75,6 +75,7 @@ exports[`ItemGroup ItemGroup component should render correctly 1`] = `
 
 .emotion-3 {
   padding: calc((36px - calc(13px * 1.2) - 2px) / 2) 12px;
+  box-sizing: border-box;
   width: 100%;
   display: block;
   margin: 0;
@@ -124,8 +125,8 @@ Snapshot Diff:
         role="listitem"
       >
         <div
--         class="components-item css-1uo9kmu-View-medium-item-spacedAround e19lxcc00"
-+         class="components-item css-bsdqin-View-medium-item e19lxcc00"
+-         class="components-item css-ufjlmj-View-medium-item-spacedAround e19lxcc00"
++         class="components-item css-cl593w-View-medium-item e19lxcc00"
           data-wp-c16t="true"
           data-wp-component="Item"
         >
@@ -152,8 +153,8 @@ Snapshot Diff:
         role="listitem"
       >
         <div
--         class="components-item css-1uo9kmu-View-medium-item-spacedAround e19lxcc00"
-+         class="components-item css-bsdqin-View-medium-item e19lxcc00"
+-         class="components-item css-ufjlmj-View-medium-item-spacedAround e19lxcc00"
++         class="components-item css-cl593w-View-medium-item e19lxcc00"
           data-wp-c16t="true"
           data-wp-component="Item"
         >

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

package/src/navigation/test/index.js

@@ -16,8 +16,6 @@ import Navigation from '..';
 import NavigationItem from '../item';
 import NavigationMenu from '../menu';
 
-jest.useFakeTimers();
-
 const TestNavigation = ( { activeItem, rootTitle, showBadge } = {} ) => (
 	<Navigation activeItem={ activeItem }>
 		<NavigationMenu title={ rootTitle }>
@@ -192,9 +190,7 @@ describe( 'Navigation', () => {
 	} );
 
 	it( 'should set an active category on click', async () => {
-		const user = userEvent.setup( {
-			advanceTimers: jest.advanceTimersByTime,
-		} );
+		const user = userEvent.setup();
 
 		render( <TestNavigation /> );
 
@@ -236,9 +232,7 @@ describe( 'Navigation', () => {
 	} );
 
 	it( 'should navigate up a level when clicking the back button', async () => {
-		const user = userEvent.setup( {
-			advanceTimers: jest.advanceTimersByTime,
-		} );
+		const user = userEvent.setup();
 
 		render( <TestNavigation rootTitle="Home" /> );
 
@@ -252,9 +246,7 @@ describe( 'Navigation', () => {
 	} );
 
 	it( 'should navigate correctly when controlled', async () => {
-		const user = userEvent.setup( {
-			advanceTimers: jest.advanceTimersByTime,
-		} );
+		const user = userEvent.setup();
 
 		render( <TestNavigationControlled /> );
 

package/src/navigator/test/index.tsx

@@ -20,8 +20,6 @@ import {
 	NavigatorBackButton,
 } from '..';
 
-jest.useFakeTimers();
-
 jest.mock( 'framer-motion', () => {
 	const actual = jest.requireActual( 'framer-motion' );
 	return {
@@ -304,9 +302,7 @@ describe( 'Navigator', () => {
 	it( 'should navigate across screens', async () => {
 		const spy = jest.fn();
 
-		const user = userEvent.setup( {
-			advanceTimers: jest.advanceTimersByTime,
-		} );
+		const user = userEvent.setup();
 
 		render( <MyNavigation onNavigatorButtonClick={ spy } /> );
 
@@ -376,9 +372,7 @@ describe( 'Navigator', () => {
 	it( 'should not rended anything if the path does not match any available screen', async () => {
 		const spy = jest.fn();
 
-		const user = userEvent.setup( {
-			advanceTimers: jest.advanceTimersByTime,
-		} );
+		const user = userEvent.setup();
 
 		render( <MyNavigation onNavigatorButtonClick={ spy } /> );
 
@@ -402,9 +396,7 @@ describe( 'Navigator', () => {
 	} );
 
 	it( 'should escape the value of the `path` prop', async () => {
-		const user = userEvent.setup( {
-			advanceTimers: jest.advanceTimersByTime,
-		} );
+		const user = userEvent.setup();
 
 		render( <MyNavigation /> );
 
@@ -437,9 +429,7 @@ describe( 'Navigator', () => {
 
 	describe( 'focus management', () => {
 		it( 'should restore focus correctly', async () => {
-			const user = userEvent.setup( {
-				advanceTimers: jest.advanceTimersByTime,
-			} );
+			const user = userEvent.setup();
 
 			render( <MyNavigation /> );
 
@@ -469,9 +459,7 @@ describe( 'Navigator', () => {
 		} );
 
 		it( 'should keep focus on an active element inside navigator, while re-rendering', async () => {
-			const user = userEvent.setup( {
-				advanceTimers: jest.advanceTimersByTime,
-			} );
+			const user = userEvent.setup();
 
 			render( <MyNavigation /> );
 
@@ -489,9 +477,7 @@ describe( 'Navigator', () => {
 		} );
 
 		it( 'should keep focus on an active element outside navigator, while re-rendering', async () => {
-			const user = userEvent.setup( {
-				advanceTimers: jest.advanceTimersByTime,
-			} );
+			const user = userEvent.setup();
 
 			render( <MyNavigation /> );