@wordpress/components 19.4.0 → 19.5.0

package/src/tools-panel/tools-panel/component.tsx

@@ -1,7 +1,7 @@
 /**
  * External dependencies
  */
-import type { Ref } from 'react';
+import type { ForwardedRef } from 'react';
 
 /**
  * Internal dependencies
@@ -15,7 +15,7 @@ import type { ToolsPanelProps } from '../types';
 
 const ToolsPanel = (
 	props: WordPressComponentProps< ToolsPanelProps, 'div' >,
-	forwardedRef: Ref< any >
+	forwardedRef: ForwardedRef< any >
 ) => {
 	const {
 		children,

package/src/tools-panel/tools-panel-header/component.tsx

@@ -1,7 +1,7 @@
 /**
  * External dependencies
  */
-import type { Ref } from 'react';
+import type { ForwardedRef } from 'react';
 
 /**
  * WordPress dependencies
@@ -114,7 +114,7 @@ const OptionalControlsGroup = ( {
 
 const ToolsPanelHeader = (
 	props: WordPressComponentProps< ToolsPanelHeaderProps, 'h2' >,
-	forwardedRef: Ref< any >
+	forwardedRef: ForwardedRef< any >
 ) => {
 	const {
 		areAllOptionalControlsHidden,

package/src/tools-panel/tools-panel-item/component.tsx

@@ -1,7 +1,7 @@
 /**
  * External dependencies
  */
-import type { Ref } from 'react';
+import type { ForwardedRef } from 'react';
 
 /**
  * Internal dependencies
@@ -15,7 +15,7 @@ import type { ToolsPanelItemProps } from '../types';
 // prevents props being applied to HTML elements that would make them invalid.
 const ToolsPanelItem = (
 	props: WordPressComponentProps< ToolsPanelItemProps, 'div' >,
-	forwardedRef: Ref< any >
+	forwardedRef: ForwardedRef< any >
 ) => {
 	const {
 		children,

package/src/tree-grid/README.md

@@ -108,10 +108,33 @@ function TreeMenu() {
 
 ##### Props
 
-`TreeGrid` accepts no specific props. Any props specified will be passed to the `table` element rendered by `TreeGrid`.
+Aside from the documented callback functions, any props specified will be passed to the `table` element rendered by `TreeGrid`.
 
 `TreeGrid` should always have children.
 
+###### onFocusRow( event: Event, startRow: HTMLElement, destinationRow: HTMLElement )
+
+Callback that fires when focus is shifted from one row to another via the UP and DOWN keys.
+The callback is passed the event, the start row element that the focus was on originally, and
+the destination row element after the focus has moved.
+
+-   Type: `Function`
+-   Required: No
+
+###### onCollapseRow( row: HTMLElement )
+
+A callback that passes in the row element to be collapsed.
+
+-   Type: `Function`
+-   Required: No
+
+###### onExpandRow( row: HTMLElement )
+
+A callback that passes in the row element to be expanded.
+
+-   Type: `Function`
+-   Required: No
+
 #### TreeGridRow
 
 ##### Props

package/src/tree-grid/index.js

@@ -8,7 +8,7 @@ import { includes } from 'lodash';
  */
 import { focus } from '@wordpress/dom';
 import { forwardRef, useCallback } from '@wordpress/element';
-import { UP, DOWN, LEFT, RIGHT } from '@wordpress/keycodes';
+import { UP, DOWN, LEFT, RIGHT, HOME, END } from '@wordpress/keycodes';
 
 /**
  * Internal dependencies
@@ -45,22 +45,30 @@ function getRowFocusables( rowElement ) {
  * @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 {Object}    ref                 A ref to the underlying DOM table element.
  */
 function TreeGrid(
-	{ children, onExpandRow = () => {}, onCollapseRow = () => {}, ...props },
+	{
+		children,
+		onExpandRow = () => {},
+		onCollapseRow = () => {},
+		onFocusRow = () => {},
+		...props
+	},
 	ref
 ) {
 	const onKeyDown = useCallback(
 		( event ) => {
-			const { keyCode, metaKey, ctrlKey, altKey, shiftKey } = event;
+			const { keyCode, metaKey, ctrlKey, altKey } = event;
 
-			const hasModifierKeyPressed =
-				metaKey || ctrlKey || altKey || shiftKey;
+			// The shift key is intentionally absent from the following list,
+			// to enable shift + up/down to select items from the list.
+			const hasModifierKeyPressed = metaKey || ctrlKey || altKey;
 
 			if (
 				hasModifierKeyPressed ||
-				! includes( [ UP, DOWN, LEFT, RIGHT ], keyCode )
+				! includes( [ UP, DOWN, LEFT, RIGHT, HOME, END ], keyCode )
 			) {
 				return;
 			}
@@ -216,12 +224,63 @@ function TreeGrid(
 				);
 				focusablesInNextRow[ nextIndex ].focus();
 
+				// Let consumers know the row that was originally focused,
+				// and the row that is now in focus.
+				onFocusRow( event, activeRow, rows[ nextRowIndex ] );
+
+				// Prevent key use for anything else. This ensures Voiceover
+				// doesn't try to handle key navigation.
+				event.preventDefault();
+			} else if ( includes( [ HOME, END ], keyCode ) ) {
+				// Calculate the rowIndex of the next row.
+				const rows = Array.from(
+					treeGridElement.querySelectorAll( '[role="row"]' )
+				);
+				const currentRowIndex = rows.indexOf( activeRow );
+				let nextRowIndex;
+
+				if ( keyCode === HOME ) {
+					nextRowIndex = 0;
+				} else {
+					nextRowIndex = rows.length - 1;
+				}
+
+				// Focus is either at the top or bottom edge of the grid. Do nothing.
+				if ( nextRowIndex === currentRowIndex ) {
+					// Prevent key use for anything else. For example, Voiceover
+					// will start navigating horizontally when reaching the vertical
+					// bounds of a table.
+					event.preventDefault();
+					return;
+				}
+
+				// Get the focusables in the next row.
+				const focusablesInNextRow = getRowFocusables(
+					rows[ nextRowIndex ]
+				);
+
+				// If for some reason there are no focusables in the next row, do nothing.
+				if ( ! focusablesInNextRow || ! focusablesInNextRow.length ) {
+					// Prevent key use for anything else. For example, Voiceover
+					// will still focus text when using arrow keys, while this
+					// component should limit navigation to focusables.
+					event.preventDefault();
+					return;
+				}
+
+				// Try to focus the element in the next row that's at a similar column to the activeElement.
+				const nextIndex = Math.min(
+					currentColumnIndex,
+					focusablesInNextRow.length - 1
+				);
+				focusablesInNextRow[ nextIndex ].focus();
+
 				// Prevent key use for anything else. This ensures Voiceover
 				// doesn't try to handle key navigation.
 				event.preventDefault();
 			}
 		},
-		[ onExpandRow, onCollapseRow ]
+		[ onExpandRow, onCollapseRow, onFocusRow ]
 	);
 
 	/* Disable reason: A treegrid is implemented using a table element. */

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

@@ -9,7 +9,10 @@ import { Fragment } from '@wordpress/element';
 import TreeGrid, { TreeGridRow, TreeGridCell } from '../';
 import { Button } from '../../';
 
-export default { title: 'Components/TreeGrid', component: TreeGrid };
+export default {
+	title: 'Components (Experimental)/TreeGrid',
+	component: TreeGrid,
+};
 
 const groceries = [
 	{

package/src/tree-grid/test/__snapshots__/index.js.snap

@@ -1,16 +1,3 @@
 // Jest Snapshot v1, https://goo.gl/fbAQLP
 
-exports[`TreeGrid renders a table, tbody and any child elements 1`] = `
-<table
-  onKeyDown={[Function]}
-  role="treegrid"
->
-  <tbody>
-    <tr>
-      <td>
-        Test
-      </td>
-    </tr>
-  </tbody>
-</table>
-`;
+exports[`TreeGrid simple rendering renders a table, tbody and any child elements 1`] = `"<table role=\\"treegrid\\"><tbody><tr><td>Test</td></tr></tbody></table>"`;

package/src/tree-grid/test/index.js

@@ -1,23 +1,242 @@
 /**
  * External dependencies
  */
-import TestRenderer from 'react-test-renderer';
+import { fireEvent, render, screen } from '@testing-library/react';
+
+/**
+ * WordPress dependencies
+ */
+import { LEFT, RIGHT, UP, DOWN } from '@wordpress/keycodes';
+import { forwardRef } from '@wordpress/element';
 
 /**
  * Internal dependencies
  */
 import TreeGrid from '../';
 
+const TestButton = forwardRef( ( { ...props }, ref ) => (
+	<button { ...props } ref={ ref }></button>
+) );
+
 describe( 'TreeGrid', () => {
-	it( 'renders a table, tbody and any child elements', () => {
-		const renderer = TestRenderer.create(
-			<TreeGrid>
-				<tr>
-					<td>Test</td>
+	const originalGetClientRects = window.Element.prototype.getClientRects;
+
+	// `getClientRects` needs to be mocked so that `isVisible` from the `@wordpress/dom`
+	// `focusable` module can pass, in a JSDOM env where the DOM elements have no width/height.
+	const mockedGetClientRects = jest.fn( () => [
+		{
+			x: 0,
+			y: 0,
+			width: 100,
+			height: 100,
+		},
+	] );
+
+	beforeAll( () => {
+		window.Element.prototype.getClientRects = jest.fn(
+			mockedGetClientRects
+		);
+	} );
+
+	afterAll( () => {
+		window.Element.prototype.getClientRects = originalGetClientRects;
+	} );
+
+	describe( 'simple rendering', () => {
+		it( 'renders a table, tbody and any child elements', () => {
+			const { container } = render(
+				<TreeGrid>
+					<tr>
+						<td>Test</td>
+					</tr>
+				</TreeGrid>
+			);
+
+			expect( container.innerHTML ).toMatchSnapshot();
+		} );
+	} );
+
+	describe( 'onExpandRow', () => {
+		it( 'should call onExpandRow when pressing Right Arrow on a collapsed row', () => {
+			const onExpandRow = jest.fn();
+
+			render(
+				<TreeGrid onExpandRow={ onExpandRow }>
+					<tr role="row" aria-expanded="true">
+						<td>
+							<TestButton>Row 1</TestButton>
+						</td>
+					</tr>
+					<tr role="row" aria-expanded="false">
+						<td>
+							<TestButton>Row 2</TestButton>
+						</td>
+					</tr>
+					<tr role="row" aria-expanded="true">
+						<td>
+							<TestButton>Row 3</TestButton>
+						</td>
+					</tr>
+				</TreeGrid>
+			);
+
+			screen.getByText( 'Row 2' ).focus();
+			const row2Element = screen.getByText( 'Row 2' ).closest( 'tr' );
+
+			fireEvent.keyDown( screen.getByText( 'Row 2' ), {
+				key: 'ArrowRight',
+				keyCode: RIGHT,
+				currentTarget: row2Element,
+			} );
+
+			expect( onExpandRow ).toHaveBeenCalledWith( row2Element );
+		} );
+	} );
+
+	describe( 'onCollapseRow', () => {
+		it( 'should call onCollapseRow when pressing Left Arrow on an expanded row', () => {
+			const onCollapseRow = jest.fn();
+
+			render(
+				<TreeGrid onCollapseRow={ onCollapseRow }>
+					<tr role="row" aria-expanded="false">
+						<td>
+							<TestButton>Row 1</TestButton>
+						</td>
+					</tr>
+					<tr role="row" aria-expanded="true">
+						<td>
+							<TestButton>Row 2</TestButton>
+						</td>
+					</tr>
+					<tr role="row" aria-expanded="false">
+						<td>
+							<TestButton>Row 3</TestButton>
+						</td>
+					</tr>
+				</TreeGrid>
+			);
+
+			screen.getByText( 'Row 2' ).focus();
+			const row2Element = screen.getByText( 'Row 2' ).closest( 'tr' );
+
+			fireEvent.keyDown( screen.getByText( 'Row 2' ), {
+				key: 'ArrowLeft',
+				keyCode: LEFT,
+				currentTarget: row2Element,
+			} );
+
+			expect( onCollapseRow ).toHaveBeenCalledWith( row2Element );
+		} );
+	} );
+
+	describe( 'onFocusRow', () => {
+		const TestTree = ( { onFocusRow } ) => (
+			<TreeGrid onFocusRow={ onFocusRow }>
+				<tr role="row" aria-expanded="false">
+					<td>
+						<TestButton>Row 1</TestButton>
+					</td>
+				</tr>
+				<tr role="row" aria-expanded="true">
+					<td>
+						<TestButton>Row 2</TestButton>
+					</td>
+				</tr>
+				<tr role="row" aria-expanded="false">
+					<td>
+						<TestButton>Row 3</TestButton>
+					</td>
 				</tr>
 			</TreeGrid>
 		);
 
-		expect( renderer.toJSON() ).toMatchSnapshot();
+		it( 'should call onFocusRow with event, start and end nodes when pressing Down Arrow', () => {
+			const onFocusRow = jest.fn();
+			render( <TestTree onFocusRow={ onFocusRow } /> );
+
+			screen.getByText( 'Row 2' ).focus();
+
+			const row2Element = screen.getByText( 'Row 2' ).closest( 'tr' );
+			const row3Element = screen.getByText( 'Row 3' ).closest( 'tr' );
+
+			fireEvent.keyDown( screen.getByText( 'Row 2' ), {
+				key: 'ArrowDown',
+				keyCode: DOWN,
+				currentTarget: row2Element,
+			} );
+
+			expect( onFocusRow ).toHaveBeenCalledWith(
+				expect.objectContaining( { key: 'ArrowDown', keyCode: DOWN } ),
+				row2Element,
+				row3Element
+			);
+		} );
+
+		it( 'should call onFocusRow with event, start and end nodes when pressing Up Arrow', () => {
+			const onFocusRow = jest.fn();
+			render( <TestTree onFocusRow={ onFocusRow } /> );
+
+			screen.getByText( 'Row 2' ).focus();
+
+			const row2Element = screen.getByText( 'Row 2' ).closest( 'tr' );
+			const row1Element = screen.getByText( 'Row 1' ).closest( 'tr' );
+
+			fireEvent.keyDown( screen.getByText( 'Row 2' ), {
+				key: 'ArrowUp',
+				keyCode: UP,
+				currentTarget: row2Element,
+			} );
+
+			expect( onFocusRow ).toHaveBeenCalledWith(
+				expect.objectContaining( { key: 'ArrowUp', keyCode: UP } ),
+				row2Element,
+				row1Element
+			);
+		} );
+
+		it( 'should call onFocusRow when shift key is held', () => {
+			const onFocusRow = jest.fn();
+			render( <TestTree onFocusRow={ onFocusRow } /> );
+
+			screen.getByText( 'Row 2' ).focus();
+
+			const row2Element = screen.getByText( 'Row 2' ).closest( 'tr' );
+			const row1Element = screen.getByText( 'Row 1' ).closest( 'tr' );
+
+			fireEvent.keyDown( screen.getByText( 'Row 2' ), {
+				key: 'ArrowUp',
+				keyCode: UP,
+				currentTarget: row2Element,
+				shiftKey: true,
+			} );
+
+			expect( onFocusRow ).toHaveBeenLastCalledWith(
+				expect.objectContaining( {
+					key: 'ArrowUp',
+					keyCode: UP,
+					shiftKey: true,
+				} ),
+				row2Element,
+				row1Element
+			);
+
+			fireEvent.keyDown( screen.getByText( 'Row 1' ), {
+				key: 'ArrowDown',
+				keyCode: DOWN,
+				currentTarget: row1Element,
+				shiftKey: true,
+			} );
+
+			expect( onFocusRow ).toHaveBeenLastCalledWith(
+				expect.objectContaining( {
+					key: 'ArrowDown',
+					keyCode: DOWN,
+					shiftKey: true,
+				} ),
+				row1Element,
+				row2Element
+			);
+		} );
 	} );
 } );

package/src/truncate/component.js

@@ -7,7 +7,7 @@ import useTruncate from './hook';
 
 /**
  * @param {import('../ui/context').WordPressComponentProps<import('./types').Props, 'span'>} props
- * @param {import('react').Ref<any>}                                                         forwardedRef
+ * @param {import('react').ForwardedRef<any>}                                                forwardedRef
  */
 function Truncate( props, forwardedRef ) {
 	const truncateProps = useTruncate( props );

package/src/ui/context/wordpress-component.ts

@@ -20,7 +20,7 @@ export type WordPressComponentProps<
 		? {
 				as?: T | keyof JSX.IntrinsicElements;
 		  }
-		: { as?: never } );
+		: {} );
 
 export type WordPressComponent<
 	T extends React.ElementType,
@@ -29,7 +29,7 @@ export type WordPressComponent<
 > = {
 	< TT extends React.ElementType >(
 		props: WordPressComponentProps< O, TT, IsPolymorphic > &
-			( IsPolymorphic extends true ? { as: TT } : { as: never } )
+			( IsPolymorphic extends true ? { as: TT } : {} )
 	): JSX.Element | null;
 	(
 		props: WordPressComponentProps< O, T, IsPolymorphic >

package/src/ui/control-group/component.js

@@ -12,7 +12,7 @@ import { contextConnect } from '../context';
 
 /**
  * @param {import('../context').WordPressComponentProps<import('./types').Props, 'div'>} props
- * @param {import('react').Ref<any>}                                                     forwardedRef
+ * @param {import('react').ForwardedRef<any>}                                            forwardedRef
  */
 function ControlGroup( props, forwardedRef ) {
 	const {

package/src/ui/control-label/component.js

@@ -7,7 +7,7 @@ import { useControlLabel } from './hook';
 
 /**
  * @param {import('../context').WordPressComponentProps<import('./types').Props, 'label', false>} props
- * @param {import('react').Ref<any>}                                                              forwardedRef
+ * @param {import('react').ForwardedRef<any>}                                                     forwardedRef
  */
 function ControlLabel( props, forwardedRef ) {
 	const controlLabelProps = useControlLabel( props );

package/src/ui/form-group/form-group.js

@@ -9,7 +9,7 @@ import { useFormGroup } from './use-form-group';
 
 /**
  * @param {import('../context').WordPressComponentProps<import('./types').FormGroupProps, 'div'>} props
- * @param {import('react').Ref<any>}                                                              forwardedRef
+ * @param {import('react').ForwardedRef<any>}                                                     forwardedRef
  */
 function FormGroup( props, forwardedRef ) {
 	const { contentProps, horizontal, ...otherProps } = useFormGroup( props );

package/src/ui/shortcut/component.tsx

@@ -1,7 +1,7 @@
 /**
  * External dependencies
  */
-import type { Ref } from 'react';
+import type { ForwardedRef } from 'react';
 
 /**
  * Internal dependencies
@@ -25,7 +25,7 @@ export interface Props {
 
 function Shortcut(
 	props: WordPressComponentProps< Props, 'span' >,
-	forwardedRef: Ref< any >
+	forwardedRef: ForwardedRef< any >
 ): JSX.Element | null {
 	const {
 		as: asProp = 'span',

package/src/ui/spinner/component.js

@@ -17,7 +17,7 @@ import { COLORS } from '../../utils/colors-values';
 /**
  *
  * @param {import('../context').WordPressComponentProps<Props, 'div'>} props
- * @param {import('react').Ref<any>}                                   forwardedRef
+ * @param {import('react').ForwardedRef<any>}                          forwardedRef
  */
 function Spinner( props, forwardedRef ) {
 	const {

package/src/ui/tooltip/component.js

@@ -19,7 +19,7 @@ import { TooltipShortcut } from './styles';
 
 /**
  * @param {import('../context').WordPressComponentProps<import('./types').Props, 'div'>} props
- * @param {import('react').Ref<any>}                                                     forwardedRef
+ * @param {import('react').ForwardedRef<any>}                                            forwardedRef
  */
 function Tooltip( props, forwardedRef ) {
 	const {

package/src/ui/tooltip/content.js

@@ -18,7 +18,7 @@ const { TooltipPopoverView } = styles;
 /**
  *
  * @param {import('../context').WordPressComponentProps<import('./types').ContentProps, 'div'>} props
- * @param {import('react').Ref<any>}                                                            forwardedRef
+ * @param {import('react').ForwardedRef<any>}                                                   forwardedRef
  */
 function TooltipContent( props, forwardedRef ) {
 	const { children, className, ...otherProps } = useContextSystem(

package/src/unit-control/index.tsx

@@ -4,7 +4,7 @@
 import type {
 	FocusEventHandler,
 	KeyboardEvent,
-	Ref,
+	ForwardedRef,
 	SyntheticEvent,
 } from 'react';
 import { noop, omit } from 'lodash';
@@ -55,7 +55,7 @@ function UnitControl(
 		value: valueProp,
 		...props
 	}: WordPressComponentProps< UnitControlProps, 'input', false >,
-	forwardedRef: Ref< any >
+	forwardedRef: ForwardedRef< any >
 ) {
 	const units = useMemo(
 		() => getUnitsWithCurrentUnit( valueProp, unitProp, unitsProp ),

package/src/unit-control/stories/index.js

@@ -16,7 +16,7 @@ import UnitControl from '../';
 import { CSS_UNITS } from '../utils';
 
 export default {
-	title: 'Components/UnitControl',
+	title: 'Components (Experimental)/UnitControl',
 	component: UnitControl,
 	parameters: {
 		knobs: { disable: false },

package/src/v-stack/component.js

@@ -7,7 +7,7 @@ import { useVStack } from './hook';
 
 /**
  * @param {import('../ui/context').WordPressComponentProps<import('./types').Props, 'div'>} props
- * @param {import('react').Ref<any>}                                                        forwardedRef
+ * @param {import('react').ForwardedRef<any>}                                               forwardedRef
  */
 function VStack( props, forwardedRef ) {
 	const vStackProps = useVStack( props );

package/src/visually-hidden/component.js

@@ -7,7 +7,7 @@ import { View } from '../view';
 
 /**
  * @param {import('../ui/context').WordPressComponentProps<{ children: import('react').ReactNode }, 'div'>} props
- * @param {import('react').Ref<any>}                                                                        forwardedRef
+ * @param {import('react').ForwardedRef<any>}                                                               forwardedRef
  */
 function VisuallyHidden( props, forwardedRef ) {
 	const { style: styleProp, ...contextProps } = useContextSystem(

package/src/z-stack/component.tsx

@@ -1,7 +1,7 @@
 /**
  * External dependencies
  */
-import type { Ref, ReactNode } from 'react';
+import type { ForwardedRef, ReactNode } from 'react';
 
 /**
  * WordPress dependencies
@@ -43,7 +43,7 @@ export interface ZStackProps {
 
 function ZStack(
 	props: WordPressComponentProps< ZStackProps, 'div' >,
-	forwardedRef: Ref< any >
+	forwardedRef: ForwardedRef< any >
 ) {
 	const {
 		children,