@wordpress/components 23.3.1 → 23.4.0

package/src/tree-grid/{index.js → index.tsx}

@@ -9,24 +9,22 @@ import { UP, DOWN, LEFT, RIGHT, HOME, END } from '@wordpress/keycodes';
  * Internal dependencies
  */
 import RovingTabIndexContainer from './roving-tab-index';
+import type { TreeGridProps } from './types';
+import type { WordPressComponentProps } from '../ui/context';
 
 /**
  * Return focusables in a row element, excluding those from other branches
  * nested within the row.
  *
- * @param {Element} rowElement The DOM element representing the row.
+ * @param rowElement The DOM element representing the row.
  *
- * @return {Array | undefined} The array of focusables in the row.
+ * @return The array of focusables in the row.
  */
-function getRowFocusables( rowElement ) {
+function getRowFocusables( rowElement: HTMLElement ) {
 	const focusablesInRow = focus.focusable.find( rowElement, {
 		sequential: true,
 	} );
 
-	if ( ! focusablesInRow || ! focusablesInRow.length ) {
-		return;
-	}
-
 	return focusablesInRow.filter( ( focusable ) => {
 		return focusable.closest( '[role="row"]' ) === rowElement;
 	} );
@@ -35,16 +33,8 @@ function getRowFocusables( rowElement ) {
 /**
  * Renders both a table and tbody element, used to create a tree hierarchy.
  *
- * @see https://github.com/WordPress/gutenberg/blob/HEAD/packages/components/src/tree-grid/README.md
- * @param {Object}    props                      Component props.
- * @param {WPElement} props.children             Children to be rendered.
- * @param {Function}  props.onExpandRow          Callback to fire when row is expanded.
- * @param {Function}  props.onCollapseRow        Callback to fire when row is collapsed.
- * @param {Function}  props.onFocusRow           Callback to fire when moving focus to a different row.
- * @param {string}    props.applicationAriaLabel Label to use for the application role.
- * @param {Object}    ref                        A ref to the underlying DOM table element.
  */
-function TreeGrid(
+function UnforwardedTreeGrid(
 	{
 		children,
 		onExpandRow = () => {},
@@ -52,11 +42,12 @@ function TreeGrid(
 		onFocusRow = () => {},
 		applicationAriaLabel,
 		...props
-	},
-	ref
+	}: WordPressComponentProps< TreeGridProps, 'table', false >,
+	/** A ref to the underlying DOM table element. */
+	ref: React.ForwardedRef< HTMLTableElement >
 ) {
 	const onKeyDown = useCallback(
-		( event ) => {
+		( event: React.KeyboardEvent< HTMLTableElement > ) => {
 			const { keyCode, metaKey, ctrlKey, altKey } = event;
 
 			// The shift key is intentionally absent from the following list,
@@ -65,7 +56,9 @@ function TreeGrid(
 
 			if (
 				hasModifierKeyPressed ||
-				! [ UP, DOWN, LEFT, RIGHT, HOME, END ].includes( keyCode )
+				! ( [ UP, DOWN, LEFT, RIGHT, HOME, END ] as number[] ).includes(
+					keyCode
+				)
 			) {
 				return;
 			}
@@ -75,21 +68,33 @@ function TreeGrid(
 
 			const { activeElement } = document;
 			const { currentTarget: treeGridElement } = event;
-			if ( ! treeGridElement.contains( activeElement ) ) {
+
+			if (
+				! activeElement ||
+				! treeGridElement.contains( activeElement )
+			) {
 				return;
 			}
 
 			// Calculate the columnIndex of the active element.
-			const activeRow = activeElement.closest( '[role="row"]' );
+			const activeRow =
+				activeElement.closest< HTMLElement >( '[role="row"]' );
+
+			if ( ! activeRow ) {
+				return;
+			}
+
 			const focusablesInRow = getRowFocusables( activeRow );
-			const currentColumnIndex = focusablesInRow.indexOf( activeElement );
+			const currentColumnIndex = focusablesInRow.indexOf(
+				activeElement as HTMLElement
+			);
 			const canExpandCollapse = 0 === currentColumnIndex;
 			const cannotFocusNextColumn =
 				canExpandCollapse &&
 				activeRow.getAttribute( 'aria-expanded' ) === 'false' &&
 				keyCode === RIGHT;
 
-			if ( [ LEFT, RIGHT ].includes( keyCode ) ) {
+			if ( ( [ LEFT, RIGHT ] as number[] ).includes( keyCode ) ) {
 				// Calculate to the next element.
 				let nextIndex;
 				if ( keyCode === LEFT ) {
@@ -116,22 +121,25 @@ function TreeGrid(
 						// If a row is focused, and it is collapsed, moves to the parent row (if there is one).
 						const level = Math.max(
 							parseInt(
-								activeRow?.getAttribute( 'aria-level' ) ?? 1,
+								activeRow?.getAttribute( 'aria-level' ) ?? '1',
 								10
 							) - 1,
 							1
 						);
 						const rows = Array.from(
-							treeGridElement.querySelectorAll( '[role="row"]' )
+							treeGridElement.querySelectorAll< HTMLElement >(
+								'[role="row"]'
+							)
 						);
 						let parentRow = activeRow;
 						const currentRowIndex = rows.indexOf( activeRow );
 						for ( let i = currentRowIndex; i >= 0; i-- ) {
+							const ariaLevel =
+								rows[ i ].getAttribute( 'aria-level' );
+
 							if (
-								parseInt(
-									rows[ i ].getAttribute( 'aria-level' ),
-									10
-								) === level
+								ariaLevel !== null &&
+								parseInt( ariaLevel, 10 ) === level
 							) {
 								parentRow = rows[ i ];
 								break;
@@ -172,10 +180,12 @@ function TreeGrid(
 				// Prevent key use for anything else. This ensures Voiceover
 				// doesn't try to handle key navigation.
 				event.preventDefault();
-			} else if ( [ UP, DOWN ].includes( keyCode ) ) {
+			} else if ( ( [ UP, DOWN ] as number[] ).includes( keyCode ) ) {
 				// Calculate the rowIndex of the next row.
 				const rows = Array.from(
-					treeGridElement.querySelectorAll( '[role="row"]' )
+					treeGridElement.querySelectorAll< HTMLElement >(
+						'[role="row"]'
+					)
 				);
 				const currentRowIndex = rows.indexOf( activeRow );
 				let nextRowIndex;
@@ -226,10 +236,12 @@ function TreeGrid(
 				// Prevent key use for anything else. This ensures Voiceover
 				// doesn't try to handle key navigation.
 				event.preventDefault();
-			} else if ( [ HOME, END ].includes( keyCode ) ) {
+			} else if ( ( [ HOME, END ] as number[] ).includes( keyCode ) ) {
 				// Calculate the rowIndex of the next row.
 				const rows = Array.from(
-					treeGridElement.querySelectorAll( '[role="row"]' )
+					treeGridElement.querySelectorAll< HTMLElement >(
+						'[role="row"]'
+					)
 				);
 				const currentRowIndex = rows.indexOf( activeRow );
 				let nextRowIndex;
@@ -306,7 +318,71 @@ function TreeGrid(
 	/* eslint-enable jsx-a11y/no-noninteractive-element-to-interactive-role */
 }
 
-export default forwardRef( TreeGrid );
+/**
+ * `TreeGrid` is used to create a tree hierarchy.
+ * It is not a visually styled component, but instead helps with adding
+ * keyboard navigation and roving tab index behaviors to tree grid structures.
+ *
+ * A tree grid is a hierarchical 2 dimensional UI component, for example it could be
+ * used to implement a file system browser.
+ *
+ * A tree grid allows the user to navigate using arrow keys.
+ * Up/down to navigate vertically across rows, and left/right to navigate horizontally
+ * between focusables in a row.
+ *
+ * The `TreeGrid` renders both a `table` and `tbody` element, and is intended to be used
+ * with `TreeGridRow` (`tr`) and `TreeGridCell` (`td`) to build out a grid.
+ *
+ * ```jsx
+ * function TreeMenu() {
+ * 	return (
+ * 		<TreeGrid>
+ * 			<TreeGridRow level={ 1 } positionInSet={ 1 } setSize={ 2 }>
+ * 				<TreeGridCell>
+ * 					{ ( props ) => (
+ * 						<Button onClick={ onSelect } { ...props }>Select</Button>
+ * 					) }
+ * 				</TreeGridCell>
+ * 				<TreeGridCell>
+ * 					{ ( props ) => (
+ * 						<Button onClick={ onMove } { ...props }>Move</Button>
+ * 					) }
+ * 				</TreeGridCell>
+ * 			</TreeGridRow>
+ * 			<TreeGridRow level={ 1 } positionInSet={ 2 } setSize={ 2 }>
+ * 				<TreeGridCell>
+ * 					{ ( props ) => (
+ * 						<Button onClick={ onSelect } { ...props }>Select</Button>
+ * 					) }
+ * 				</TreeGridCell>
+ * 				<TreeGridCell>
+ * 					{ ( props ) => (
+ * 						<Button onClick={ onMove } { ...props }>Move</Button>
+ * 					) }
+ * 				</TreeGridCell>
+ * 			</TreeGridRow>
+ * 			<TreeGridRow level={ 2 } positionInSet={ 1 } setSize={ 1 }>
+ * 				<TreeGridCell>
+ * 					{ ( props ) => (
+ * 						<Button onClick={ onSelect } { ...props }>Select</Button>
+ * 					) }
+ * 				</TreeGridCell>
+ * 				<TreeGridCell>
+ * 					{ ( props ) => (
+ * 						<Button onClick={ onMove } { ...props }>Move</Button>
+ * 					) }
+ * 				</TreeGridCell>
+ * 			</TreeGridRow>
+ * 		</TreeGrid>
+ * 	);
+ * }
+ * ```
+ *
+ * @see {@link https://www.w3.org/TR/wai-aria-practices/examples/treegrid/treegrid-1.html}
+ */
+export const TreeGrid = forwardRef( UnforwardedTreeGrid );
+
+export default TreeGrid;
 export { default as TreeGridRow } from './row';
 export { default as TreeGridCell } from './cell';
 export { default as TreeGridItem } from './item';

package/src/tree-grid/item.tsx

@@ -0,0 +1,32 @@
+/**
+ * WordPress dependencies
+ */
+import { forwardRef } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import RovingTabIndexItem from './roving-tab-index-item';
+import type { RovingTabIndexItemProps } from './types';
+
+function UnforwardedTreeGridItem(
+	{ children, ...props }: RovingTabIndexItemProps,
+	ref: React.ForwardedRef< any >
+) {
+	return (
+		<RovingTabIndexItem ref={ ref } { ...props }>
+			{ children }
+		</RovingTabIndexItem>
+	);
+}
+
+/**
+ * `TreeGridItem` is used to create a tree hierarchy.
+ * It is not a visually styled component, but instead helps with adding
+ * keyboard navigation and roving tab index behaviors to tree grid structures.
+ *
+ * @see {@link https://www.w3.org/TR/wai-aria-practices/examples/treegrid/treegrid-1.html}
+ */
+export const TreeGridItem = forwardRef( UnforwardedTreeGridItem );
+
+export default TreeGridItem;

package/src/tree-grid/{roving-tab-index-context.js → roving-tab-index-context.ts}

@@ -3,7 +3,15 @@
  */
 import { createContext, useContext } from '@wordpress/element';
 
-const RovingTabIndexContext = createContext();
+const RovingTabIndexContext = createContext<
+	| {
+			lastFocusedElement: HTMLElement | undefined;
+			setLastFocusedElement: React.Dispatch<
+				React.SetStateAction< HTMLElement | undefined >
+			>;
+	  }
+	| undefined
+>( undefined );
 export const useRovingTabIndexContext = () =>
 	useContext( RovingTabIndexContext );
 export const RovingTabIndexProvider = RovingTabIndexContext.Provider;

package/src/tree-grid/roving-tab-index-item.tsx

@@ -0,0 +1,50 @@
+/**
+ * WordPress dependencies
+ */
+import { useRef, forwardRef } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import { useRovingTabIndexContext } from './roving-tab-index-context';
+import type { RovingTabIndexItemProps } from './types';
+
+export const RovingTabIndexItem = forwardRef(
+	function UnforwardedRovingTabIndexItem(
+		{ children, as: Component, ...props }: RovingTabIndexItemProps,
+		forwardedRef: React.ForwardedRef< any >
+	) {
+		const localRef = useRef< any >();
+		const ref = forwardedRef || localRef;
+		// @ts-expect-error - We actually want to throw an error if this is undefined.
+		const { lastFocusedElement, setLastFocusedElement } =
+			useRovingTabIndexContext();
+		let tabIndex;
+
+		if ( lastFocusedElement ) {
+			tabIndex =
+				lastFocusedElement ===
+				// TODO: The original implementation simply used `ref.current` here, assuming
+				// that a forwarded ref would always be an object, which is not necessarily true.
+				// This workaround maintains the original runtime behavior in a type-safe way,
+				// but should be revisited.
+				( 'current' in ref ? ref.current : undefined )
+					? 0
+					: -1;
+		}
+
+		const onFocus: React.FocusEventHandler< HTMLElement > = ( event ) =>
+			setLastFocusedElement?.( event.target );
+		const allProps = { ref, tabIndex, onFocus, ...props };
+
+		if ( typeof children === 'function' ) {
+			return children( allProps );
+		}
+
+		if ( ! Component ) return null;
+
+		return <Component { ...allProps }>{ children }</Component>;
+	}
+);
+
+export default RovingTabIndexItem;

package/src/tree-grid/{roving-tab-index.js → roving-tab-index.tsx}

@@ -12,12 +12,14 @@ import { RovingTabIndexProvider } from './roving-tab-index-context';
  * Provider for adding roving tab index behaviors to tree grid structures.
  *
  * @see https://github.com/WordPress/gutenberg/blob/HEAD/packages/components/src/tree-grid/README.md
- *
- * @param {Object}    props          Component props.
- * @param {WPElement} props.children Children to be rendered
  */
-export default function RovingTabIndex( { children } ) {
-	const [ lastFocusedElement, setLastFocusedElement ] = useState();
+export default function RovingTabIndex( {
+	children,
+}: {
+	children: React.ReactNode;
+} ) {
+	const [ lastFocusedElement, setLastFocusedElement ] =
+		useState< HTMLElement >();
 
 	// Use `useMemo` to avoid creation of a new object for the providerValue
 	// on every render. Only create a new object when the `lastFocusedElement`

package/src/tree-grid/row.tsx

@@ -0,0 +1,47 @@
+/**
+ * WordPress dependencies
+ */
+import { forwardRef } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import type { WordPressComponentProps } from '../ui/context';
+import type { TreeGridRowProps } from './types';
+
+function UnforwardedTreeGridRow(
+	{
+		children,
+		level,
+		positionInSet,
+		setSize,
+		isExpanded,
+		...props
+	}: WordPressComponentProps< TreeGridRowProps, 'tr', false >,
+	ref: React.ForwardedRef< HTMLTableRowElement >
+) {
+	return (
+		<tr
+			{ ...props }
+			ref={ ref }
+			role="row"
+			aria-level={ level }
+			aria-posinset={ positionInSet }
+			aria-setsize={ setSize }
+			aria-expanded={ isExpanded }
+		>
+			{ children }
+		</tr>
+	);
+}
+
+/**
+ * `TreeGridRow` is used to create a tree hierarchy.
+ * It is not a visually styled component, but instead helps with adding
+ * keyboard navigation and roving tab index behaviors to tree grid structures.
+ *
+ * @see {@link https://www.w3.org/TR/wai-aria-practices/examples/treegrid/treegrid-1.html}
+ */
+export const TreeGridRow = forwardRef( UnforwardedTreeGridRow );
+
+export default TreeGridRow;

package/src/tree-grid/stories/index.tsx

@@ -0,0 +1,144 @@
+/**
+ * External dependencies
+ */
+import type { ComponentMeta, ComponentStory } from '@storybook/react';
+
+/**
+ * WordPress dependencies
+ */
+import { Fragment } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import TreeGrid, { TreeGridRow, TreeGridCell } from '..';
+import { Button } from '../../button';
+import InputControl from '../../input-control';
+
+const meta: ComponentMeta< typeof TreeGrid > = {
+	title: 'Components (Experimental)/TreeGrid',
+	component: TreeGrid,
+	subcomponents: { TreeGridRow, TreeGridCell },
+	argTypes: {
+		children: { control: { type: null } },
+	},
+	parameters: {
+		actions: { argTypesRegex: '^on.*' },
+		controls: { expanded: true },
+	},
+};
+export default meta;
+
+const groceries = [
+	{
+		name: 'Fruit',
+		types: [
+			{
+				name: 'Apple',
+			},
+			{
+				name: 'Orange',
+			},
+			{
+				name: 'Pear',
+			},
+		],
+	},
+	{
+		name: 'Vegetable',
+		types: [
+			{
+				name: 'Cucumber',
+			},
+			{
+				name: 'Parsnip',
+			},
+			{
+				name: 'Pumpkin',
+			},
+		],
+	},
+];
+
+const Descender = ( { level }: { level: number } ) => {
+	if ( level === 1 ) {
+		return null;
+	}
+	const indentation = '\u00A0'.repeat( ( level - 1 ) * 4 );
+
+	return <span aria-hidden="true">{ indentation + '├ ' }</span>;
+};
+
+type Item = {
+	name: string;
+	types?: Item[];
+};
+
+const Rows = ( {
+	items = [],
+	level = 1,
+}: {
+	items?: Item[];
+	level?: number;
+} ) => {
+	return (
+		<>
+			{ items.map( ( item, index ) => {
+				const hasChildren = !! item.types && !! item.types.length;
+				return (
+					<Fragment key={ item.name }>
+						<TreeGridRow
+							positionInSet={ index + 1 }
+							setSize={ items.length }
+							level={ level }
+							isExpanded
+						>
+							<TreeGridCell>
+								{ ( props ) => (
+									<>
+										<Descender level={ level } />
+										<Button variant="primary" { ...props }>
+											{ item.name }
+										</Button>
+									</>
+								) }
+							</TreeGridCell>
+							<TreeGridCell>
+								{ ( props ) => (
+									<InputControl
+										label="Description"
+										hideLabelFromVision
+										placeholder="Description"
+										{ ...props }
+									/>
+								) }
+							</TreeGridCell>
+							<TreeGridCell>
+								{ ( props ) => (
+									<InputControl
+										label="Notes"
+										hideLabelFromVision
+										placeholder="Notes"
+										{ ...props }
+									/>
+								) }
+							</TreeGridCell>
+						</TreeGridRow>
+						{ hasChildren && (
+							<Rows items={ item.types } level={ level + 1 } />
+						) }
+					</Fragment>
+				);
+			} ) }
+		</>
+	);
+};
+
+const Template: ComponentStory< typeof TreeGrid > = ( args ) => (
+	<TreeGrid { ...args } />
+);
+
+export const Default = Template.bind( {} );
+Default.args = {
+	children: <Rows items={ groceries } />,
+};

package/src/tree-grid/test/{cell.js → cell.tsx}

@@ -11,12 +11,15 @@ import { forwardRef } from '@wordpress/element';
 /**
  * Internal dependencies
  */
-import TreeGrid from '../';
+import TreeGrid from '..';
 import TreeGridCell from '../cell';
 
-const TestButton = forwardRef( ( { ...props }, ref ) => (
-	<button { ...props } ref={ ref }></button>
-) );
+const TestButton = forwardRef(
+	(
+		{ ...props }: React.ComponentPropsWithoutRef< 'button' >,
+		ref: React.ForwardedRef< HTMLButtonElement >
+	) => <button { ...props } ref={ ref }></button>
+);
 
 describe( 'TreeGridCell', () => {
 	it( 'requires TreeGrid to be declared as a parent component somewhere in the component hierarchy', () => {

package/src/tree-grid/test/{index.js → index.tsx}

@@ -12,13 +12,16 @@ import { forwardRef } from '@wordpress/element';
 /**
  * Internal dependencies
  */
-import TreeGrid from '../';
+import TreeGrid from '..';
 import TreeGridRow from '../row';
 import TreeGridCell from '../cell';
 
-const TestButton = forwardRef( ( { ...props }, ref ) => (
-	<button { ...props } ref={ ref }></button>
-) );
+const TestButton = forwardRef(
+	(
+		{ ...props }: React.ComponentPropsWithoutRef< 'button' >,
+		ref: React.ForwardedRef< HTMLButtonElement >
+	) => <button { ...props } ref={ ref }></button>
+);
 
 describe( 'TreeGrid', () => {
 	const originalGetClientRects = window.Element.prototype.getClientRects;
@@ -35,6 +38,7 @@ describe( 'TreeGrid', () => {
 	] );
 
 	beforeAll( () => {
+		// @ts-expect-error - This is just a mock
 		window.Element.prototype.getClientRects =
 			jest.fn( mockedGetClientRects );
 	} );
@@ -162,7 +166,11 @@ describe( 'TreeGrid', () => {
 	} );
 
 	describe( 'onFocusRow', () => {
-		const TestTree = ( { onFocusRow } ) => (
+		const TestTree = ( {
+			onFocusRow,
+		}: {
+			onFocusRow: React.ComponentProps< typeof TreeGrid >[ 'onFocusRow' ];
+		} ) => (
 			<TreeGrid onFocusRow={ onFocusRow }>
 				<TreeGridRow level={ 1 } positionInSet={ 1 } setSize={ 3 }>
 					<TreeGridCell withoutGridItem>

package/src/tree-grid/test/{roving-tab-index-item.js → roving-tab-index-item.tsx}

@@ -14,9 +14,12 @@ import { forwardRef } from '@wordpress/element';
 import RovingTabIndex from '../roving-tab-index';
 import RovingTabIndexItem from '../roving-tab-index-item';
 
-const TestButton = forwardRef( ( { ...props }, ref ) => (
-	<button { ...props } ref={ ref }></button>
-) );
+const TestButton = forwardRef(
+	(
+		{ ...props }: React.ComponentPropsWithoutRef< 'button' >,
+		ref: React.ForwardedRef< HTMLButtonElement >
+	) => <button { ...props } ref={ ref }></button>
+);
 
 describe( 'RovingTabIndexItem', () => {
 	it( 'requires RovingTabIndex to be declared as a parent component somewhere in the component hierarchy', () => {
@@ -52,7 +55,7 @@ describe( 'RovingTabIndexItem', () => {
 		const { container } = render(
 			<RovingTabIndex>
 				<RovingTabIndexItem>
-					{ ( props ) => (
+					{ ( props: React.ComponentProps< typeof TestButton > ) => (
 						<TestButton className="my-button" { ...props }>
 							Click Me!
 						</TestButton>

package/src/tree-grid/test/{row.js → row.tsx}

@@ -13,7 +13,7 @@ describe( 'TreeGridRow', () => {
 		const { container } = render(
 			<table>
 				<tbody>
-					<TreeGridRow level="1" positionInSet="1" setSize="1">
+					<TreeGridRow level={ 1 } positionInSet={ 1 } setSize={ 1 }>
 						<td>Test</td>
 					</TreeGridRow>
 				</tbody>
@@ -29,9 +29,9 @@ describe( 'TreeGridRow', () => {
 				<tbody>
 					<TreeGridRow
 						className="my-row"
-						level="1"
-						positionInSet="1"
-						setSize="1"
+						level={ 1 }
+						positionInSet={ 1 }
+						setSize={ 1 }
 					>
 						<td>Test</td>
 					</TreeGridRow>