@wordpress/components 19.4.1 → 19.5.0

package/src/navigator/types.ts

@@ -43,3 +43,29 @@ export type NavigatorScreenProps = {
 	 */
 	children: ReactNode;
 };
+
+type ButtonProps = {
+	// TODO: should also extend `Button` prop types once the `Button` component
+	// is refactored to TypeScript.
+};
+export type NavigatorBackButtonProps = Omit< ButtonProps, 'href' > & {
+	/**
+	 * The children elements.
+	 */
+	children: ReactNode;
+};
+
+export type NavigatorButtonProps = NavigatorBackButtonProps & {
+	/**
+	 * The path of the screen to navigate to. The value of this prop needs to be
+	 * a valid value for an HTML attribute.
+	 */
+	path: string;
+	/**
+	 * The HTML attribute used to identify the `NavigatorButton`, which is used
+	 * by `Navigator` to restore focus.
+	 *
+	 * @default 'id'
+	 */
+	attributeName?: string;
+};

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

@@ -14,7 +14,7 @@ import { useState } from '@wordpress/element';
 import NumberControl from '../';
 
 export default {
-	title: 'Components/NumberControl',
+	title: 'Components (Experimental)/NumberControl',
 	component: NumberControl,
 	parameters: {
 		knobs: { disable: false },

package/src/radio/stories/index.js

@@ -4,7 +4,7 @@
 import RadioGroup from '../../radio-group';
 import Radio from '../';
 
-export default { title: 'Components/Radio', component: Radio };
+export default { title: 'Components (Experimental)/Radio', component: Radio };
 
 export const _default = () => {
 	// Radio components must be a descendent of a RadioGroup component.

package/src/radio-group/stories/index.js

@@ -9,7 +9,10 @@ import { useState } from '@wordpress/element';
 import Radio from '../../radio';
 import RadioGroup from '../';
 
-export default { title: 'Components/RadioGroup', component: RadioGroup };
+export default {
+	title: 'Components (Experimental)/RadioGroup',
+	component: RadioGroup,
+};
 
 export const _default = () => {
 	/* eslint-disable no-restricted-syntax */

package/src/resizable-box/index.tsx

@@ -9,7 +9,7 @@ import { forwardRef } from '@wordpress/element';
 import classnames from 'classnames';
 import { Resizable } from 're-resizable';
 import type { ResizableProps } from 're-resizable';
-import type { ReactNode, Ref } from 'react';
+import type { ReactNode, ForwardedRef } from 'react';
 
 /**
  * Internal dependencies
@@ -104,7 +104,7 @@ function ResizableBox(
 		__experimentalTooltipProps: tooltipProps = {},
 		...props
 	}: ResizableBoxProps,
-	ref: Ref< Resizable >
+	ref: ForwardedRef< Resizable >
 ): JSX.Element {
 	return (
 		<Resizable

package/src/resizable-box/resize-tooltip/index.tsx

@@ -3,7 +3,7 @@
  */
 import { noop } from 'lodash';
 import classnames from 'classnames';
-import type { Ref } from 'react';
+import type { Ref, ForwardedRef } from 'react';
 
 /**
  * WordPress dependencies
@@ -43,7 +43,7 @@ function ResizeTooltip(
 		zIndex = 1000,
 		...props
 	}: ResizeTooltipProps,
-	ref: Ref< HTMLDivElement >
+	ref: ForwardedRef< HTMLDivElement >
 ): JSX.Element | null {
 	const { label, resizeListener } = useResizeLabel( {
 		axis,

package/src/resizable-box/resize-tooltip/label.tsx

@@ -1,7 +1,7 @@
 /**
  * External dependencies
  */
-import type { Ref } from 'react';
+import type { ForwardedRef } from 'react';
 
 /**
  * WordPress dependencies
@@ -33,7 +33,7 @@ type LabelProps = React.DetailedHTMLProps<
 
 function Label(
 	{ label, position = POSITIONS.corner, zIndex = 1000, ...props }: LabelProps,
-	ref: Ref< HTMLDivElement >
+	ref: ForwardedRef< HTMLDivElement >
 ): JSX.Element | null {
 	const showLabel = !! label;
 

package/src/scrollable/component.js

@@ -7,7 +7,7 @@ import { useScrollable } 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 Scrollable( props, forwardedRef ) {
 	const scrollableProps = useScrollable( props );

package/src/select-control/index.tsx

@@ -3,8 +3,7 @@
  */
 import { isEmpty, noop } from 'lodash';
 import classNames from 'classnames';
-// eslint-disable-next-line no-restricted-imports
-import type { ChangeEvent, FocusEvent, ReactNode, Ref } from 'react';
+import type { ChangeEvent, FocusEvent, ReactNode, ForwardedRef } from 'react';
 
 /**
  * WordPress dependencies
@@ -74,7 +73,7 @@ function SelectControl(
 		suffix,
 		...props
 	}: WordPressComponentProps< SelectControlProps, 'select', false >,
-	ref: Ref< HTMLSelectElement >
+	ref: ForwardedRef< HTMLSelectElement >
 ) {
 	const [ isFocused, setIsFocused ] = useState( false );
 	const id = useUniqueId( idProp );

package/src/spacer/component.tsx

@@ -1,7 +1,7 @@
 /**
  * External dependencies
  */
-import type { Ref } from 'react';
+import type { ForwardedRef } from 'react';
 
 /**
  * Internal dependencies
@@ -13,7 +13,7 @@ import type { Props } from './types';
 
 function Spacer(
 	props: WordPressComponentProps< Props, 'div' >,
-	forwardedRef: Ref< any >
+	forwardedRef: ForwardedRef< any >
 ) {
 	const spacerProps = useSpacer( props );
 

package/src/surface/component.js

@@ -7,7 +7,7 @@ import { useSurface } 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 Surface( props, forwardedRef ) {
 	const surfaceProps = useSurface( props );

package/src/text/component.js

@@ -7,7 +7,7 @@ import useText 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 Text( props, forwardedRef ) {
 	const textProps = useText( props );

package/src/text-control/index.js

@@ -24,8 +24,8 @@ import BaseControl from '../base-control';
 
 /**
  *
- * @param {Props}                                 props Props
- * @param {import('react').Ref<HTMLInputElement>} [ref]
+ * @param {Props}                                          props Props
+ * @param {import('react').ForwardedRef<HTMLInputElement>} ref
  */
 function TextControl(
 	{

package/src/toggle-group-control/stories/index.js

@@ -17,7 +17,7 @@ import Button from '../../button';
 
 export default {
 	component: ToggleGroupControl,
-	title: 'Components/ToggleGroupControl',
+	title: 'Components (Experimental)/ToggleGroupControl',
 	parameters: {
 		knobs: { disable: false },
 	},

package/src/toggle-group-control/toggle-group-control/component.tsx

@@ -1,7 +1,7 @@
 /**
  * External dependencies
  */
-import type { Ref } from 'react';
+import type { ForwardedRef } from 'react';
 // eslint-disable-next-line no-restricted-imports
 import { RadioGroup, useRadioState } from 'reakit';
 
@@ -31,7 +31,7 @@ const noop = () => {};
 
 function ToggleGroupControl(
 	props: WordPressComponentProps< ToggleGroupControlProps, 'input' >,
-	forwardedRef: Ref< any >
+	forwardedRef: ForwardedRef< any >
 ) {
 	const {
 		className,

package/src/toggle-group-control/toggle-group-control-option/component.tsx

@@ -1,7 +1,7 @@
 /**
  * External dependencies
  */
-import type { Ref } from 'react';
+import type { ForwardedRef } from 'react';
 // eslint-disable-next-line no-restricted-imports
 import { Radio } from 'reakit';
 
@@ -39,7 +39,7 @@ const WithToolTip = ( { showTooltip, text, children }: WithToolTipProps ) => {
 
 function ToggleGroupControlOption(
 	props: WordPressComponentProps< ToggleGroupControlOptionProps, 'button' >,
-	forwardedRef: Ref< any >
+	forwardedRef: ForwardedRef< any >
 ) {
 	const toggleGroupControlContext = useToggleGroupControlContext();
 	const id = useInstanceId(

package/src/tools-panel/stories/index.js

@@ -467,7 +467,6 @@ export const WithConditionallyRenderedControl = () => {
 	);
 };
 
-export { TypographyPanel } from './typography-panel';
 export { ToolsPanelWithItemGroupSlot } from './tools-panel-with-item-group-slot';
 
 const PanelWrapperView = styled.div`

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>"`;