WordPress · ciampo · Apr 27, 2023 · Mar 22, 2023 · Mar 22, 2023 · Mar 22, 2023
@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+### Internal
+
+-   `NavigableContainer`: Convert to TypeScript ([#49377](https://github.com/WordPress/gutenberg/pull/49377)).
+
 ## 23.9.0 (2023-04-26)
 
 ### Internal

@@ -2,38 +2,49 @@
 
 `NavigableContainer` is a React component to render a container navigable using the keyboard. Only things that are focusable can be navigated to. It will currently always be a `div`.
 
-`NavigableContainer` is exported as two classes: `NavigableMenu` and `TabbableContainer`. `NavigableContainer` itself is **not** exported. `NavigableMenu` and `TabbableContainer` have the props listed below. Any other props will be passed through to the `div`.
+`NavigableContainer` is exported as two components: `NavigableMenu` and `TabbableContainer`. `NavigableContainer` itself is **not** exported. `NavigableMenu` and `TabbableContainer` have the props listed below. Any other props will be passed through to the `div`.
 
 ---
 
 ## Props
 
-These are the props that `NavigableMenu` and `TabbableContainer`. Any props which are specific to one class are labelled appropriately.
+These are the props that `NavigableMenu` and `TabbableContainer`. Any props which are specific to one component are labelled appropriately.
 
-### onNavigate
+### `cycle`: `boolean`
 
-A callback invoked when the menu navigates to one of its children passing the index and child as an argument
+A boolean which tells the component whether or not to cycle from the end back to the beginning and vice versa.
 
--   Type: `Function`
 -   Required: No
+-   default: `true`
 
-### cycle
+### `eventToOffset`: `( event: KeyboardEvent ) => -1 | 0 | 1 | undefined`
 
-A boolean which tells the component whether or not to cycle from the end back to the beginning and vice versa.
+(TabbableContainer only)
+Gets an offset, given an event.
+
+-   Required: No
+
+### `onKeydown`: `( event: KeyboardEvent ) => void`
+
+A callback invoked on the keydown event.
+
+-   Required: No
+
+### `onNavigate`: `( index: number, focusable: HTMLElement ) => void`
+
+A callback invoked when the menu navigates to one of its children passing the index and child as an argument
 
--   Type: `Boolean`
 -   Required: No
--   default: true
 
-### orientation (NavigableMenu only)
+### `orientation`: `'vertical' | 'horizontal' | 'both'`
 
-The orientation of the menu. It could be "vertical", "horizontal" or "both"
+(NavigableMenu only)
+The orientation of the menu. It could be "vertical", "horizontal", or "both".
 
--   Type: `String`
 -   Required: No
 -   Default: `"vertical"`
 
-## Classes
+## Components
 
 ### NavigableMenu
 

@@ -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,9 +116,11 @@ 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 );
+				!! targetRole && MENU_ITEM_ROLES.includes( targetRole );
 
 			// `preventDefault()` on tab to avoid having the browser move the focus
 			// after this component has already moved it.
@@ -115,9 +135,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;
 		}
@@ -152,7 +176,10 @@ class NavigableContainer extends Component {
 	}
 }
 
-const forwardedNavigableContainer = ( props, ref ) => {
+const forwardedNavigableContainer = (
+	props: NavigableContainerProps,
+	ref: ForwardedRef< HTMLDivElement >
+) => {
 	return <NavigableContainer { ...props } forwardedRef={ ref } />;
 };
 forwardedNavigableContainer.displayName = 'NavigableContainer';

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

@@ -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;