@wordpress/components 23.9.0 → 24.0.0

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

package/src/palette-edit/index.tsx

@@ -1,12 +1,19 @@
 /**
  * External dependencies
  */
+import classnames from 'classnames';
 import { paramCase as kebabCase } from 'change-case';
 
 /**
  * WordPress dependencies
  */
-import { useState, useRef, useEffect, useCallback } from '@wordpress/element';
+import {
+	useState,
+	useRef,
+	useEffect,
+	useCallback,
+	useMemo,
+} from '@wordpress/element';
 import { __, sprintf } from '@wordpress/i18n';
 import { lineSolid, moreVertical, plus } from '@wordpress/icons';
 import {
@@ -106,15 +113,26 @@ function ColorPickerPopover< T extends Color | Gradient >( {
 	isGradient,
 	element,
 	onChange,
+	popoverProps: receivedPopoverProps,
 	onClose = () => {},
 }: ColorPickerPopoverProps< T > ) {
+	const popoverProps: ColorPickerPopoverProps< T >[ 'popoverProps' ] =
+		useMemo(
+			() => ( {
+				shift: true,
+				offset: 20,
+				placement: 'left-start',
+				...receivedPopoverProps,
+				className: classnames(
+					'components-palette-edit__popover',
+					receivedPopoverProps?.className
+				),
+			} ),
+			[ receivedPopoverProps ]
+		);
+
 	return (
-		<Popover
-			placement="left-start"
-			offset={ 20 }
-			className="components-palette-edit__popover"
-			onClose={ onClose }
-		>
+		<Popover { ...popoverProps } onClose={ onClose }>
 			{ ! isGradient && (
 				<ColorPicker
 					color={ element.color }
@@ -154,17 +172,31 @@ function Option< T extends Color | Gradient >( {
 	onStartEditing,
 	onRemove,
 	onStopEditing,
+	popoverProps: receivedPopoverProps,
 	slugPrefix,
 	isGradient,
 }: OptionProps< T > ) {
 	const focusOutsideProps = useFocusOutside( onStopEditing );
 	const value = isGradient ? element.gradient : element.color;
 
+	// Use internal state instead of a ref to make sure that the component
+	// re-renders when the popover's anchor updates.
+	const [ popoverAnchor, setPopoverAnchor ] = useState( null );
+	const popoverProps = useMemo(
+		() => ( {
+			...receivedPopoverProps,
+			// Use the custom palette color item as the popover anchor.
+			anchor: popoverAnchor,
+		} ),
+		[ popoverAnchor, receivedPopoverProps ]
+	);
+
 	return (
 		<PaletteItem
 			className={ isEditing ? 'is-selected' : undefined }
 			as="div"
 			onClick={ onStartEditing }
+			ref={ setPopoverAnchor }
 			{ ...( isEditing
 				? { ...focusOutsideProps }
 				: {
@@ -218,6 +250,7 @@ function Option< T extends Color | Gradient >( {
 					isGradient={ isGradient }
 					onChange={ onChange }
 					element={ element }
+					popoverProps={ popoverProps }
 				/>
 			) }
 		</PaletteItem>
@@ -244,6 +277,7 @@ function PaletteEditListView< T extends Color | Gradient >( {
 	canOnlyChangeValues,
 	slugPrefix,
 	isGradient,
+	popoverProps,
 }: PaletteEditListViewProps< T > ) {
 	// When unmounting the component if there are empty elements (the user did not complete the insertion) clean them.
 	const elementsReference = useRef< typeof elements >();
@@ -317,6 +351,7 @@ function PaletteEditListView< T extends Color | Gradient >( {
 							}
 						} }
 						slugPrefix={ slugPrefix }
+						popoverProps={ popoverProps }
 					/>
 				) ) }
 			</ItemGroup>
@@ -356,6 +391,7 @@ export function PaletteEdit( {
 	canOnlyChangeValues,
 	canReset,
 	slugPrefix = '',
+	popoverProps,
 }: PaletteEditProps ) {
 	const isGradient = !! gradients;
 	const elements = isGradient ? gradients : colors;
@@ -541,6 +577,7 @@ export function PaletteEdit( {
 							setEditingElement={ setEditingElement }
 							slugPrefix={ slugPrefix }
 							isGradient={ isGradient }
+							popoverProps={ popoverProps }
 						/>
 					) }
 					{ ! isEditing && editingElement !== null && (
@@ -568,6 +605,7 @@ export function PaletteEdit( {
 								);
 							} }
 							element={ elements[ editingElement ?? -1 ] }
+							popoverProps={ popoverProps }
 						/>
 					) }
 					{ ! isEditing &&

package/src/palette-edit/stories/index.tsx

@@ -59,6 +59,10 @@ Default.args = {
 	],
 	paletteLabel: 'Colors',
 	emptyMessage: 'Colors are empty',
+	popoverProps: {
+		placement: 'bottom-start',
+		offset: 8,
+	},
 };
 
 export const Gradients = Template.bind( {} );

package/src/palette-edit/types.ts

@@ -6,6 +6,7 @@ import type { Key, MouseEventHandler } from 'react';
 /**
  * Internal dependencies
  */
+import type Popover from '../popover';
 import type { HeadingSize } from '../heading/types';
 
 export type Color = {
@@ -58,6 +59,13 @@ export type BasePaletteEdit = {
 	 * @default ''
 	 */
 	slugPrefix?: string;
+	/**
+	 * Props to pass through to the underlying Popover component.
+	 */
+	popoverProps?: Omit<
+		React.ComponentPropsWithoutRef< typeof Popover >,
+		'children'
+	>;
 };
 
 type PaletteEditColors = {
@@ -94,6 +102,7 @@ export type ColorPickerPopoverProps< T extends Color | Gradient > = {
 	onChange: ( newElement: T ) => void;
 	isGradient?: T extends Gradient ? true : false;
 	onClose?: () => void;
+	popoverProps?: PaletteEditProps[ 'popoverProps' ];
 };
 
 export type NameInputProps = {
@@ -112,6 +121,7 @@ export type OptionProps< T extends Color | Gradient > = {
 	onRemove: MouseEventHandler< HTMLButtonElement >;
 	onStartEditing: () => void;
 	onStopEditing: () => void;
+	popoverProps?: PaletteEditProps[ 'popoverProps' ];
 	slugPrefix: string;
 };
 
@@ -121,6 +131,7 @@ export type PaletteEditListViewProps< T extends Color | Gradient > = {
 	isGradient: T extends Gradient ? true : false;
 	canOnlyChangeValues: PaletteEditProps[ 'canOnlyChangeValues' ];
 	editingElement?: EditingElement;
+	popoverProps?: PaletteEditProps[ 'popoverProps' ];
 	setEditingElement: ( newEditingElement?: EditingElement ) => void;
 	slugPrefix: string;
 };