@wordpress/components 23.9.0 → 25.0.0

package/src/navigable-container/{container.js → container.tsx}

@@ -1,14 +1,23 @@
-// @ts-nocheck
+/**
+ * External dependencies
+ */
+import type { ForwardedRef } from 'react';
+
 /**
  * WordPress dependencies
  */
 import { Component, forwardRef } from '@wordpress/element';
 import { focus } from '@wordpress/dom';
 
+/**
+ * Internal dependencies
+ */
+import type { NavigableContainerProps } from './types';
+
 const noop = () => {};
 const MENU_ITEM_ROLES = [ 'menuitem', 'menuitemradio', 'menuitemcheckbox' ];
 
-function cycleValue( value, total, offset ) {
+function cycleValue( value: number, total: number, offset: number ) {
 	const nextValue = value + offset;
 	if ( nextValue < 0 ) {
 		return total + nextValue;
@@ -19,9 +28,11 @@ function cycleValue( value, total, offset ) {
 	return nextValue;
 }
 
-class NavigableContainer extends Component {
-	constructor() {
-		super( ...arguments );
+class NavigableContainer extends Component< NavigableContainerProps > {
+	container?: HTMLDivElement;
+
+	constructor( args: NavigableContainerProps ) {
+		super( args );
 		this.onKeyDown = this.onKeyDown.bind( this );
 		this.bindContainer = this.bindContainer.bind( this );
 
@@ -30,21 +41,27 @@ class NavigableContainer extends Component {
 	}
 
 	componentDidMount() {
+		if ( ! this.container ) {
+			return;
+		}
+
 		// We use DOM event listeners instead of React event listeners
 		// because we want to catch events from the underlying DOM tree
 		// The React Tree can be different from the DOM tree when using
 		// portals. Block Toolbars for instance are rendered in a separate
 		// React Trees.
 		this.container.addEventListener( 'keydown', this.onKeyDown );
-		this.container.addEventListener( 'focus', this.onFocus );
 	}
 
 	componentWillUnmount() {
+		if ( ! this.container ) {
+			return;
+		}
+
 		this.container.removeEventListener( 'keydown', this.onKeyDown );
-		this.container.removeEventListener( 'focus', this.onFocus );
 	}
 
-	bindContainer( ref ) {
+	bindContainer( ref: HTMLDivElement ) {
 		const { forwardedRef } = this.props;
 		this.container = ref;
 
@@ -55,10 +72,14 @@ class NavigableContainer extends Component {
 		}
 	}
 
-	getFocusableContext( target ) {
+	getFocusableContext( target: Element ) {
+		if ( ! this.container ) {
+			return null;
+		}
+
 		const { onlyBrowserTabstops } = this.props;
 		const finder = onlyBrowserTabstops ? focus.tabbable : focus.focusable;
-		const focusables = finder.find( this.container );
+		const focusables = finder.find( this.container ) as HTMLElement[];
 
 		const index = this.getFocusableIndex( focusables, target );
 		if ( index > -1 && target ) {
@@ -67,14 +88,11 @@ class NavigableContainer extends Component {
 		return null;
 	}
 
-	getFocusableIndex( focusables, target ) {
-		const directIndex = focusables.indexOf( target );
-		if ( directIndex !== -1 ) {
-			return directIndex;
-		}
+	getFocusableIndex( focusables: Element[], target: Element ) {
+		return focusables.indexOf( target );
 	}
 
-	onKeyDown( event ) {
+	onKeyDown( event: KeyboardEvent ) {
 		if ( this.props.onKeyDown ) {
 			this.props.onKeyDown( event );
 		}
@@ -98,15 +116,13 @@ class NavigableContainer extends Component {
 			// from scrolling. The preventDefault also prevents Voiceover from
 			// 'handling' the event, as voiceover will try to use arrow keys
 			// for highlighting text.
-			const targetRole = event.target.getAttribute( 'role' );
+			const targetRole = (
+				event.target as HTMLDivElement | null
+			 )?.getAttribute( 'role' );
 			const targetHasMenuItemRole =
-				MENU_ITEM_ROLES.includes( targetRole );
-
-			// `preventDefault()` on tab to avoid having the browser move the focus
-			// after this component has already moved it.
-			const isTab = event.code === 'Tab';
+				!! targetRole && MENU_ITEM_ROLES.includes( targetRole );
 
-			if ( targetHasMenuItemRole || isTab ) {
+			if ( targetHasMenuItemRole ) {
 				event.preventDefault();
 			}
 		}
@@ -115,9 +131,13 @@ class NavigableContainer extends Component {
 			return;
 		}
 
-		const context = getFocusableContext(
-			event.target.ownerDocument.activeElement
-		);
+		const activeElement = ( event.target as HTMLElement | null )
+			?.ownerDocument?.activeElement;
+		if ( ! activeElement ) {
+			return;
+		}
+
+		const context = getFocusableContext( activeElement );
 		if ( ! context ) {
 			return;
 		}
@@ -126,9 +146,16 @@ class NavigableContainer extends Component {
 		const nextIndex = cycle
 			? cycleValue( index, focusables.length, offset )
 			: index + offset;
+
 		if ( nextIndex >= 0 && nextIndex < focusables.length ) {
 			focusables[ nextIndex ].focus();
 			onNavigate( nextIndex, focusables[ nextIndex ] );
+
+			// `preventDefault()` on tab to avoid having the browser move the focus
+			// after this component has already moved it.
+			if ( event.code === 'Tab' ) {
+				event.preventDefault();
+			}
 		}
 	}
 
@@ -152,7 +179,10 @@ class NavigableContainer extends Component {
 	}
 }
 
-const forwardedNavigableContainer = ( props, ref ) => {
+const forwardedNavigableContainer = (
+	props: NavigableContainerProps,
+	ref: ForwardedRef< HTMLDivElement >
+) => {
 	return <NavigableContainer { ...props } forwardedRef={ ref } />;
 };
 forwardedNavigableContainer.displayName = 'NavigableContainer';

package/src/navigable-container/{index.js → index.tsx}

@@ -1,4 +1,3 @@
-// @ts-nocheck
 /**
  * Internal Dependencies
  */

package/src/navigable-container/menu.tsx

@@ -0,0 +1,100 @@
+/**
+ * External dependencies
+ */
+import type { ForwardedRef } from 'react';
+
+/**
+ * WordPress dependencies
+ */
+import { forwardRef } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import NavigableContainer from './container';
+import type { NavigableMenuProps } from './types';
+
+export function UnforwardedNavigableMenu(
+	{ role = 'menu', orientation = 'vertical', ...rest }: NavigableMenuProps,
+	ref: ForwardedRef< any >
+) {
+	const eventToOffset = ( evt: KeyboardEvent ) => {
+		const { code } = evt;
+
+		let next = [ 'ArrowDown' ];
+		let previous = [ 'ArrowUp' ];
+
+		if ( orientation === 'horizontal' ) {
+			next = [ 'ArrowRight' ];
+			previous = [ 'ArrowLeft' ];
+		}
+
+		if ( orientation === 'both' ) {
+			next = [ 'ArrowRight', 'ArrowDown' ];
+			previous = [ 'ArrowLeft', 'ArrowUp' ];
+		}
+
+		if ( next.includes( code ) ) {
+			return 1;
+		} else if ( previous.includes( code ) ) {
+			return -1;
+		} else if (
+			[ 'ArrowDown', 'ArrowUp', 'ArrowLeft', 'ArrowRight' ].includes(
+				code
+			)
+		) {
+			// Key press should be handled, e.g. have event propagation and
+			// default behavior handled by NavigableContainer but not result
+			// in an offset.
+			return 0;
+		}
+
+		return undefined;
+	};
+
+	return (
+		<NavigableContainer
+			ref={ ref }
+			stopNavigationEvents
+			onlyBrowserTabstops={ false }
+			role={ role }
+			aria-orientation={
+				role !== 'presentation' &&
+				( orientation === 'vertical' || orientation === 'horizontal' )
+					? orientation
+					: undefined
+			}
+			eventToOffset={ eventToOffset }
+			{ ...rest }
+		/>
+	);
+}
+
+/**
+ * A container for a navigable menu.
+ *
+ *  ```jsx
+ *  import {
+ *    NavigableMenu,
+ *    Button,
+ *  } from '@wordpress/components';
+ *
+ *  function onNavigate( index, target ) {
+ *    console.log( `Navigates to ${ index }`, target );
+ *  }
+ *
+ *  const MyNavigableContainer = () => (
+ *    <div>
+ *      <span>Navigable Menu:</span>
+ *      <NavigableMenu onNavigate={ onNavigate } orientation="horizontal">
+ *        <Button variant="secondary">Item 1</Button>
+ *        <Button variant="secondary">Item 2</Button>
+ *        <Button variant="secondary">Item 3</Button>
+ *      </NavigableMenu>
+ *    </div>
+ *  );
+ *  ```
+ */
+export const NavigableMenu = forwardRef( UnforwardedNavigableMenu );
+
+export default NavigableMenu;

package/src/navigable-container/stories/{navigable-menu.js → navigable-menu.tsx}

@@ -1,25 +1,30 @@
+/**
+ * External dependencies
+ */
+import type { ComponentMeta, ComponentStory } from '@storybook/react';
+
 /**
  * Internal dependencies
  */
 import { NavigableMenu } from '..';
 
-export default {
+const meta: ComponentMeta< typeof NavigableMenu > = {
 	title: 'Components/NavigableMenu',
 	component: NavigableMenu,
 	argTypes: {
-		children: { type: null },
-		cycle: {
-			type: 'boolean',
-		},
-		onNavigate: { action: 'onNavigate' },
-		orientation: {
-			options: [ 'horizontal', 'vertical' ],
-			control: { type: 'radio' },
+		children: { control: { type: null } },
+	},
+	parameters: {
+		actions: { argTypesRegex: '^on.*' },
+		controls: {
+			expanded: true,
 		},
+		docs: { source: { state: 'open' } },
 	},
 };
+export default meta;
 
-export const Default = ( args ) => {
+export const Default: ComponentStory< typeof NavigableMenu > = ( args ) => {
 	return (
 		<>
 			<button>Before navigable menu</button>

package/src/navigable-container/stories/{tabbable-container.js → tabbable-container.tsx}

@@ -1,21 +1,30 @@
+/**
+ * External dependencies
+ */
+import type { ComponentMeta, ComponentStory } from '@storybook/react';
+
 /**
  * Internal dependencies
  */
 import { TabbableContainer } from '..';
 
-export default {
+const meta: ComponentMeta< typeof TabbableContainer > = {
 	title: 'Components/TabbableContainer',
 	component: TabbableContainer,
 	argTypes: {
-		children: { type: null },
-		cycle: {
-			type: 'boolean',
+		children: { control: { type: null } },
+	},
+	parameters: {
+		actions: { argTypesRegex: '^on.*' },
+		controls: {
+			expanded: true,
 		},
-		onNavigate: { action: 'onNavigate' },
+		docs: { source: { state: 'open' } },
 	},
 };
+export default meta;
 
-export const Default = ( args ) => {
+export const Default: ComponentStory< typeof TabbableContainer > = ( args ) => {
 	return (
 		<>
 			<button>Before tabbable container</button>

package/src/navigable-container/tabbable.tsx

@@ -0,0 +1,92 @@
+/**
+ * External dependencies
+ */
+import type { ForwardedRef } from 'react';
+
+/**
+ * WordPress dependencies
+ */
+import { forwardRef } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import NavigableContainer from './container';
+import type { TabbableContainerProps } from './types';
+
+export function UnforwardedTabbableContainer(
+	{ eventToOffset, ...props }: TabbableContainerProps,
+	ref: ForwardedRef< any >
+) {
+	const innerEventToOffset = ( evt: KeyboardEvent ) => {
+		const { code, shiftKey } = evt;
+		if ( 'Tab' === code ) {
+			return shiftKey ? -1 : 1;
+		}
+
+		// Allow custom handling of keys besides Tab.
+		//
+		// By default, TabbableContainer will move focus forward on Tab and
+		// backward on Shift+Tab. The handler below will be used for all other
+		// events. The semantics for `eventToOffset`'s return
+		// values are the following:
+		//
+		// - +1: move focus forward
+		// - -1: move focus backward
+		// -  0: don't move focus, but acknowledge event and thus stop it
+		// - undefined: do nothing, let the event propagate.
+		if ( eventToOffset ) {
+			return eventToOffset( evt );
+		}
+
+		return undefined;
+	};
+
+	return (
+		<NavigableContainer
+			ref={ ref }
+			stopNavigationEvents
+			onlyBrowserTabstops
+			eventToOffset={ innerEventToOffset }
+			{ ...props }
+		/>
+	);
+}
+
+/**
+ * A container for tabbable elements.
+ *
+ *  ```jsx
+ *  import {
+ *    TabbableContainer,
+ *    Button,
+ *  } from '@wordpress/components';
+ *
+ *  function onNavigate( index, target ) {
+ *    console.log( `Navigates to ${ index }`, target );
+ *  }
+ *
+ *  const MyTabbableContainer = () => (
+ *    <div>
+ *      <span>Tabbable Container:</span>
+ *      <TabbableContainer onNavigate={ onNavigate }>
+ *        <Button variant="secondary" tabIndex="0">
+ *          Section 1
+ *        </Button>
+ *        <Button variant="secondary" tabIndex="0">
+ *          Section 2
+ *        </Button>
+ *        <Button variant="secondary" tabIndex="0">
+ *          Section 3
+ *        </Button>
+ *        <Button variant="secondary" tabIndex="0">
+ *          Section 4
+ *        </Button>
+ *      </TabbableContainer>
+ *    </div>
+ *  );
+ *  ```
+ */
+export const TabbableContainer = forwardRef( UnforwardedTabbableContainer );
+
+export default TabbableContainer;

package/src/navigable-container/test/{navigable-menu.js → navigable-menu.tsx}

@@ -8,8 +8,9 @@ import userEvent from '@testing-library/user-event';
  * Internal dependencies
  */
 import { NavigableMenu } from '../menu';
+import type { NavigableMenuProps } from '../types';
 
-const NavigableMenuTestCase = ( props ) => (
+const NavigableMenuTestCase = ( props: NavigableMenuProps ) => (
 	<NavigableMenu { ...props }>
 		<button>Item 1</button>
 		<span>
@@ -34,6 +35,7 @@ describe( 'NavigableMenu', () => {
 		// Mocking `getClientRects()` is necessary to pass a check performed by
 		// the `focus.tabbable.find()` and by the `focus.focusable.find()` functions
 		// from the `@wordpress/dom` package.
+		// @ts-expect-error We're not trying to comply to the DOM spec, only mocking
 		window.HTMLElement.prototype.getClientRects = function () {
 			return [ 'trick-jsdom-into-having-size-for-element-rect' ];
 		};

package/src/navigable-container/test/{tababble-container.js → tababble-container.tsx}

@@ -8,20 +8,25 @@ import userEvent from '@testing-library/user-event';
  * Internal dependencies
  */
 import { TabbableContainer } from '../tabbable';
-
-const TabbableContainerTestCase = ( props ) => (
-	<TabbableContainer { ...props }>
-		<button>Item 1</button>
-		<span>
-			<span tabIndex={ -1 }>Item 2 (not tabbable)</span>
-		</span>
-		<span>
-			<span tabIndex={ 0 }>Item 3</span>
-		</span>
-		<p>I can not be tabbed</p>
-		<input type="text" disabled name="disabled-input" />
-		<a href="https://example.com">Item 4</a>
-	</TabbableContainer>
+import type { TabbableContainerProps } from '../types';
+
+const TabbableContainerTestCase = ( props: TabbableContainerProps ) => (
+	<>
+		<button>Before container</button>
+		<TabbableContainer { ...props }>
+			<button>Item 1</button>
+			<span>
+				<span tabIndex={ -1 }>Item 2 (not tabbable)</span>
+			</span>
+			<span>
+				<span tabIndex={ 0 }>Item 3</span>
+			</span>
+			<p>I can not be tabbed</p>
+			<input type="text" disabled name="disabled-input" />
+			<a href="https://example.com">Item 4</a>
+		</TabbableContainer>
+		<button>After container</button>
+	</>
 );
 
 const getTabbableContainerTabbables = () => [
@@ -37,6 +42,7 @@ describe( 'TabbableContainer', () => {
 		// Mocking `getClientRects()` is necessary to pass a check performed by
 		// the `focus.tabbable.find()` and by the `focus.focusable.find()` functions
 		// from the `@wordpress/dom` package.
+		// @ts-expect-error We're not trying to comply to the DOM spec, only mocking
 		window.HTMLElement.prototype.getClientRects = function () {
 			return [ 'trick-jsdom-into-having-size-for-element-rect' ];
 		};
@@ -55,7 +61,11 @@ describe( 'TabbableContainer', () => {
 
 		const tabbables = getTabbableContainerTabbables();
 
-		// Move focus to first item.
+		await user.tab();
+		expect(
+			screen.getByRole( 'button', { name: 'Before container' } )
+		).toHaveFocus();
+
 		await user.tab();
 		expect( tabbables[ 0 ] ).toHaveFocus();
 
@@ -89,7 +99,11 @@ describe( 'TabbableContainer', () => {
 		const lastTabbableIndex = tabbables.length - 1;
 		const lastTabbable = tabbables[ lastTabbableIndex ];
 
-		// Move focus to first item.
+		await user.tab();
+		expect(
+			screen.getByRole( 'button', { name: 'Before container' } )
+		).toHaveFocus();
+
 		await user.tab();
 		expect( firstTabbable ).toHaveFocus();
 
@@ -114,12 +128,17 @@ describe( 'TabbableContainer', () => {
 			/>
 		);
 
-		// With the `cycle` prop set to `false`, cycling is not allowed.
 		// By default, cycling from first to last and from last to first is allowed.
+		// With the `cycle` prop set to `false`, cycling is not allowed.
+		// Therefore, focus will escape the `TabbableContainer` and continue its
+		// natural path in the page.
 		await user.tab( { shift: true } );
-		expect( firstTabbable ).toHaveFocus();
+		expect(
+			screen.getByRole( 'button', { name: 'Before container' } )
+		).toHaveFocus();
 		expect( onNavigateSpy ).toHaveBeenCalledTimes( 2 );
 
+		await user.tab();
 		await user.tab();
 		await user.tab();
 		expect( lastTabbable ).toHaveFocus();
@@ -129,8 +148,12 @@ describe( 'TabbableContainer', () => {
 			lastTabbable
 		);
 
+		// Focus will move to the next natively focusable elements after
+		// `TabbableContainer`
 		await user.tab();
-		expect( lastTabbable ).toHaveFocus();
+		expect(
+			screen.getByRole( 'button', { name: 'After container' } )
+		).toHaveFocus();
 		expect( onNavigateSpy ).toHaveBeenCalledTimes( 4 );
 	} );
 
@@ -149,21 +172,27 @@ describe( 'TabbableContainer', () => {
 
 		const tabbables = getTabbableContainerTabbables();
 
-		// Move focus to first item
+		await user.tab();
+		expect(
+			screen.getByRole( 'button', { name: 'Before container' } )
+		).toHaveFocus();
+		expect( externalWrapperOnKeyDownSpy ).toHaveBeenCalledTimes( 0 );
+
 		await user.tab();
 		expect( tabbables[ 0 ] ).toHaveFocus();
+		expect( externalWrapperOnKeyDownSpy ).toHaveBeenCalledTimes( 1 );
 
 		await user.keyboard( '[Space]' );
-		expect( externalWrapperOnKeyDownSpy ).toHaveBeenCalledTimes( 1 );
+		expect( externalWrapperOnKeyDownSpy ).toHaveBeenCalledTimes( 2 );
 
 		await user.tab();
-		expect( externalWrapperOnKeyDownSpy ).toHaveBeenCalledTimes( 1 );
+		expect( externalWrapperOnKeyDownSpy ).toHaveBeenCalledTimes( 2 );
 		await user.tab( { shift: true } );
 		// This extra call is caused by the "shift" key being pressed
 		// on its own before "tab"
-		expect( externalWrapperOnKeyDownSpy ).toHaveBeenCalledTimes( 2 );
+		expect( externalWrapperOnKeyDownSpy ).toHaveBeenCalledTimes( 3 );
 
 		await user.keyboard( '[Escape]' );
-		expect( externalWrapperOnKeyDownSpy ).toHaveBeenCalledTimes( 3 );
+		expect( externalWrapperOnKeyDownSpy ).toHaveBeenCalledTimes( 4 );
 	} );
 } );

package/src/navigable-container/types.ts

@@ -0,0 +1,76 @@
+/**
+ * External dependencies
+ */
+import type { ForwardedRef, ReactNode } from 'react';
+
+/**
+ * Internal dependencies
+ */
+import type { WordPressComponentProps } from '../ui/context';
+
+type BaseProps = {
+	/**
+	 * The component children.
+	 */
+	children?: ReactNode;
+	/**
+	 * A boolean which tells the component whether or not to cycle from the end back to the beginning and vice versa.
+	 *
+	 * @default true
+	 */
+	cycle?: boolean;
+	/**
+	 * A callback invoked on the keydown event.
+	 */
+	onKeyDown?: ( event: KeyboardEvent ) => void;
+	/**
+	 * A callback invoked when the menu navigates to one of its children passing the index and child as an argument
+	 */
+	onNavigate?: ( index: number, focusable: HTMLElement ) => void;
+};
+
+export type NavigableContainerProps = WordPressComponentProps<
+	BaseProps & {
+		/**
+		 * Gets an offset, given an event.
+		 */
+		eventToOffset: ( event: KeyboardEvent ) => -1 | 0 | 1 | undefined;
+		/**
+		 * The forwarded ref.
+		 */
+		forwardedRef?: ForwardedRef< any >;
+		/**
+		 * Whether to only consider browser tab stops.
+		 *
+		 * @default false
+		 */
+		onlyBrowserTabstops: boolean;
+		/**
+		 * Whether to stop navigation events.
+		 *
+		 * @default false
+		 */
+		stopNavigationEvents: boolean;
+	},
+	'div',
+	false
+>;
+
+export type NavigableMenuProps = WordPressComponentProps<
+	BaseProps & {
+		/**
+		 * The orientation of the menu.
+		 *
+		 * @default 'vertical'
+		 */
+		orientation?: 'vertical' | 'horizontal' | 'both';
+	},
+	'div',
+	false
+>;
+
+export type TabbableContainerProps = WordPressComponentProps<
+	BaseProps & Partial< Pick< NavigableContainerProps, 'eventToOffset' > >,
+	'div',
+	false
+>;