@wordpress/components 22.1.0 → 23.1.0

package/src/snackbar/{list.js → list.tsx}

@@ -12,13 +12,14 @@ import { useRef } from '@wordpress/element';
 /**
  * Internal dependencies
  */
-import Snackbar from './';
+import Snackbar from '.';
 import {
 	__unstableMotion as motion,
 	__unstableAnimatePresence as AnimatePresence,
 } from '../animation';
+import type { Notice, SnackbarListProps } from './types';
+import type { WordPressComponentProps } from '../ui/context';
 
-const noop = () => {};
 const SNACKBAR_VARIANTS = {
 	init: {
 		height: 0,
@@ -39,28 +40,28 @@ const SNACKBAR_VARIANTS = {
 	},
 };
 
-const SNACKBAR_REDUCE_MOTION_VARIANTS = {
-	init: false,
-	open: false,
-	exit: false,
-};
-
 /**
  * Renders a list of notices.
  *
- * @param {Object}   $0           Props passed to the component.
- * @param {Array}    $0.notices   Array of notices to render.
- * @param {Function} $0.onRemove  Function called when a notice should be removed / dismissed.
- * @param {Object}   $0.className Name of the class used by the component.
- * @param {Object}   $0.children  Array of children to be rendered inside the notice list.
- *
- * @return {Object} The rendered notices list.
+ * ```jsx
+ * const MySnackbarListNotice = () => (
+ *   <SnackbarList
+ *     notices={ notices }
+ *     onRemove={ removeNotice }
+ *   />
+ * );
+ * ```
  */
-function SnackbarList( { notices, className, children, onRemove = noop } ) {
-	const listRef = useRef();
+export function SnackbarList( {
+	notices,
+	className,
+	children,
+	onRemove,
+}: WordPressComponentProps< SnackbarListProps, 'div' > ) {
+	const listRef = useRef< HTMLDivElement | null >( null );
 	const isReducedMotion = useReducedMotion();
 	className = classnames( 'components-snackbar-list', className );
-	const removeNotice = ( notice ) => () => onRemove( notice.id );
+	const removeNotice = ( notice: Notice ) => () => onRemove?.( notice.id );
 	return (
 		<div className={ className } tabIndex={ -1 } ref={ listRef }>
 			{ children }
@@ -76,9 +77,7 @@ function SnackbarList( { notices, className, children, onRemove = noop } ) {
 							exit={ 'exit' }
 							key={ notice.id }
 							variants={
-								isReducedMotion
-									? SNACKBAR_REDUCE_MOTION_VARIANTS
-									: SNACKBAR_VARIANTS
+								isReducedMotion ? undefined : SNACKBAR_VARIANTS
 							}
 						>
 							<div className="components-snackbar-list__notice-container">

package/src/snackbar/stories/index.tsx

@@ -0,0 +1,96 @@
+/**
+ * External dependencies
+ */
+import type { ComponentMeta, ComponentStory } from '@storybook/react';
+
+/**
+ * Internal dependencies
+ */
+import Snackbar from '..';
+
+const meta: ComponentMeta< typeof Snackbar > = {
+	title: 'Components/Snackbar',
+	component: Snackbar,
+	argTypes: {
+		as: { control: { type: null } },
+		onRemove: {
+			action: 'onRemove',
+			control: { type: null },
+		},
+		onDismiss: {
+			action: 'onDismiss',
+			control: { type: null },
+		},
+		listRef: {
+			control: { type: null },
+		},
+	},
+	parameters: {
+		controls: {
+			expanded: true,
+		},
+		docs: { source: { state: 'open' } },
+	},
+};
+export default meta;
+
+const DefaultTemplate: ComponentStory< typeof Snackbar > = ( {
+	children,
+	...props
+} ) => {
+	return <Snackbar { ...props }>{ children }</Snackbar>;
+};
+
+export const Default: ComponentStory< typeof Snackbar > = DefaultTemplate.bind(
+	{}
+);
+Default.args = {
+	children:
+		'Use Snackbars to communicate low priority, non-interruptive messages to the user.',
+};
+
+export const WithActions: ComponentStory< typeof Snackbar > =
+	DefaultTemplate.bind( {} );
+WithActions.args = {
+	actions: [
+		{
+			label: 'Open WP.org',
+			url: 'https://wordpress.org',
+		},
+	],
+	children: 'Use Snackbars with an action link to an external page.',
+};
+
+export const WithIcon: ComponentStory< typeof Snackbar > = DefaultTemplate.bind(
+	{}
+);
+WithIcon.args = {
+	children: 'Add an icon to make your snackbar stand out',
+	icon: (
+		<span role="img" aria-label="Icon" style={ { fontSize: 21 } }>
+			🌮
+		</span>
+	),
+};
+
+export const WithExplicitDismiss: ComponentStory< typeof Snackbar > =
+	DefaultTemplate.bind( {} );
+WithExplicitDismiss.args = {
+	children:
+		'Add a cross to explicitly close the snackbar, and do not hide it automatically',
+	explicitDismiss: true,
+};
+
+export const WithActionAndExplicitDismiss: ComponentStory< typeof Snackbar > =
+	DefaultTemplate.bind( {} );
+WithActionAndExplicitDismiss.args = {
+	actions: [
+		{
+			label: 'Open WP.org',
+			url: 'https://wordpress.org',
+		},
+	],
+	children:
+		'Add an action and a cross to explicitly close the snackbar, and do not hide it automatically',
+	explicitDismiss: true,
+};

package/src/snackbar/stories/list.tsx

@@ -0,0 +1,98 @@
+/**
+ * External dependencies
+ */
+import type { ComponentMeta, ComponentStory } from '@storybook/react';
+
+/**
+ * WordPress dependencies
+ */
+import { useState } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import SnackbarList from '../list';
+
+const meta: ComponentMeta< typeof SnackbarList > = {
+	title: 'Components/SnackbarList',
+	component: SnackbarList,
+	argTypes: {
+		as: { control: { type: null } },
+		onRemove: {
+			action: 'onRemove',
+			control: { type: null },
+		},
+	},
+	parameters: {
+		controls: {
+			expanded: true,
+		},
+		docs: { source: { state: 'open' } },
+	},
+};
+export default meta;
+
+export const Default: ComponentStory< typeof SnackbarList > = ( {
+	children,
+	notices: noticesProp,
+	...props
+} ) => {
+	const [ notices, setNotices ] = useState( noticesProp );
+
+	const onRemove = ( id: string ) => {
+		const matchIndex = notices.findIndex( ( n ) => n.id === id );
+		if ( matchIndex > -1 ) {
+			setNotices( [
+				...notices.slice( 0, matchIndex ),
+				...notices.slice( matchIndex + 1 ),
+			] );
+		}
+	};
+
+	return (
+		<SnackbarList { ...props } notices={ notices } onRemove={ onRemove }>
+			{ children }
+		</SnackbarList>
+	);
+};
+
+Default.args = {
+	children:
+		'Use SnackbarList to communicate multiple low priority, non-interruptive messages to the user.',
+	notices: [
+		{
+			id: 'SAVE_POST_NOTICE_ID_1',
+			spokenMessage: 'Post published.',
+			actions: [
+				{
+					label: 'View Post',
+					url: 'https://example.com/?p=522',
+				},
+			],
+			content: 'Post published.',
+			isDismissible: true,
+			explicitDismiss: false,
+		},
+		{
+			id: 'SAVE_POST_NOTICE_ID_2',
+			spokenMessage: 'Post updated',
+			actions: [
+				{
+					label: 'View Post',
+					url: 'https://example.com/?p=522',
+				},
+			],
+			content: 'Post updated.',
+			isDismissible: true,
+			explicitDismiss: false,
+		},
+		{
+			id: 'global1',
+			spokenMessage: 'All content copied.',
+			actions: [],
+			content: 'All content copied.',
+			isDismissible: true,
+			explicitDismiss: false,
+		},
+	],
+};

package/src/snackbar/types.ts

@@ -0,0 +1,116 @@
+/**
+ * External dependencies
+ */
+import type { MutableRefObject, ReactNode, SyntheticEvent } from 'react';
+
+export type NoticeActionWithURL = {
+	label: string;
+	url: string;
+	onClick?: ( event: SyntheticEvent ) => void;
+};
+
+type NoticeActionWithOnClick = {
+	label: string;
+	url?: string;
+	onClick: ( event: SyntheticEvent ) => void;
+};
+
+// TODO: move this type to the Notice component once it gets typed.
+export type NoticeAction = NoticeActionWithURL | NoticeActionWithOnClick;
+
+export type Notice = {
+	id: string;
+	spokenMessage: string;
+	actions: NoticeAction[];
+	icon?: ReactNode;
+	onDismiss?: () => void;
+	content: string;
+	isDismissible: boolean;
+	explicitDismiss: boolean;
+};
+
+export type SnackbarProps = {
+	/**
+	 * The displayed message of a notice.
+	 *
+	 * Also used as the spoken message for assistive technology,
+	 * unless `spokenMessage` is provided as an alternative message.
+	 */
+	children: string;
+	/**
+	 * Used to provide a custom spoken message.
+	 *
+	 * @default children
+	 */
+	spokenMessage?: Notice[ 'spokenMessage' ];
+	/**
+	 * A politeness level for the notice's spoken message. Should be provided as
+	 * one of the valid options for an `aria-live` attribute value. Note that this
+	 * value should be considered a suggestion; assistive technologies may
+	 * override it based on internal heuristics.
+	 *
+	 * A value of `'assertive'` is to be used for important, and usually
+	 * time-sensitive, information. It will interrupt anything else the screen
+	 * reader is announcing in that moment.
+	 * A value of `'polite'` is to be used for advisory information. It should
+	 * not interrupt what the screen reader is announcing in that moment
+	 * (the "speech queue") or interrupt the current task.
+	 *
+	 * @see https://www.w3.org/TR/wai-aria-1.1/#aria-live
+	 *
+	 * @default 'polite'
+	 */
+	politeness?: 'polite' | 'assertive';
+	/**
+	 * An array of action objects.
+	 *
+	 * Each member object should contain
+	 * a `label` and either a `url` link string or `onClick` callback function.
+	 *
+	 * @default []
+	 */
+	actions?: Notice[ 'actions' ];
+	/**
+	 * Called to remove the snackbar from the UI.
+	 */
+	onRemove?: () => void;
+	/**
+	 * The icon to render in the snackbar.
+	 *
+	 * @default null
+	 */
+	icon?: Notice[ 'icon' ];
+	/**
+	 * Whether to require user action to dismiss the snackbar.
+	 * By default, this is dismissed on a timeout, without user interaction.
+	 *
+	 * @default false
+	 */
+	explicitDismiss?: Notice[ 'explicitDismiss' ];
+	/**
+	 * A callback executed when the snackbar is dismissed.
+	 *
+	 * It is distinct from onRemove, which _looks_ like a callback but is
+	 * actually the function to call to remove the snackbar from the UI.
+	 */
+	onDismiss?: Notice[ 'onDismiss' ];
+	/**
+	 * A ref to the list that contains the snackbar.
+	 */
+	listRef?: MutableRefObject< HTMLDivElement | null >;
+};
+
+export type SnackbarListProps = {
+	/**
+	 * Array of notices to render.
+	 */
+	notices: Notice[];
+	/**
+	 * Children to be rendered inside the notice list.
+	 */
+	children?: ReactNode;
+	/**
+	 * Function called when a notice should be removed / dismissed.
+	 */
+	onRemove?: ( id: Notice[ 'id' ] ) => void;
+};

package/src/tab-panel/README.md

@@ -120,6 +120,7 @@ An array of objects containing the following properties:
 -   `name`: `(string)` Defines the key for the tab.
 -   `title`:`(string)` Defines the translated text for the tab.
 -   `className`:`(string)` Optional. Defines the class to put on the tab.
+-   `icon`:`(ReactNode)` Optional. When set, displays the icon in place of the tab title. The title is then rendered as an aria-label and tooltip.
 
 > > **Note:** Other fields may be added to the object and accessed from the child function if desired.
 
@@ -142,6 +143,14 @@ The name of the tab to be selected upon mounting of component. If this prop is n
 -   Required: No
 -   Default: none
 
+#### selectOnMove
+
+When `true`, the tab will be selected when receiving focus (automatic tab activation). When `false`, the tab will be selected only when clicked (manual tab activation). See the [official W3C docs](https://www.w3.org/WAI/ARIA/apg/patterns/tabpanel/) for more info.
+
+-   Type: `boolean`
+-   Required: No
+-   Default: `true`
+
 #### children
 
 A function which renders the tabviews given the selected tab. The function is passed the active tab object as an argument as defined the tabs prop.

package/src/tab-panel/index.tsx

@@ -2,7 +2,6 @@
  * External dependencies
  */
 import classnames from 'classnames';
-import { find } from 'lodash';
 
 /**
  * WordPress dependencies
@@ -77,6 +76,7 @@ export function TabPanel( {
 	className,
 	children,
 	tabs,
+	selectOnMove = true,
 	initialTabName,
 	orientation = 'horizontal',
 	activeClass = 'is-active',
@@ -93,10 +93,15 @@ export function TabPanel( {
 		[ onSelect ]
 	);
 
-	const onNavigate = ( _childIndex: number, child: HTMLButtonElement ) => {
+	// Simulate a click on the newly focused tab, which causes the component
+	// to show the `tab-panel` associated with the clicked tab.
+	const activateTabAutomatically = (
+		_childIndex: number,
+		child: HTMLButtonElement
+	) => {
 		child.click();
 	};
-	const selectedTab = find( tabs, { name: selected } );
+	const selectedTab = tabs.find( ( { name } ) => name === selected );
 	const selectedId = `${ instanceId }-${ selectedTab?.name ?? 'none' }`;
 
 	useEffect( () => {
@@ -110,7 +115,9 @@ export function TabPanel( {
 			<NavigableMenu
 				role="tablist"
 				orientation={ orientation }
-				onNavigate={ onNavigate }
+				onNavigate={
+					selectOnMove ? activateTabAutomatically : undefined
+				}
 				className="components-tab-panel__tabs"
 			>
 				{ tabs.map( ( tab ) => (
@@ -127,8 +134,11 @@ export function TabPanel( {
 						selected={ tab.name === selected }
 						key={ tab.name }
 						onClick={ () => handleTabSelection( tab.name ) }
+						label={ tab.icon && tab.title }
+						icon={ tab.icon }
+						showTooltip={ !! tab.icon }
 					>
-						{ tab.title }
+						{ ! tab.icon && tab.title }
 					</TabButton>
 				) ) }
 			</NavigableMenu>

package/src/tab-panel/style.scss

@@ -7,57 +7,69 @@
 	}
 }
 
+// This tab style CSS is duplicated verbatim in
+// /packages/edit-post/src/components/sidebar/settings-header/style.scss
 .components-tab-panel__tabs-item {
+	position: relative;
+	border-radius: 0;
+	height: $grid-unit-60;
 	background: transparent;
 	border: none;
 	box-shadow: none;
-	border-radius: 0;
 	cursor: pointer;
-	height: $grid-unit-60;
 	padding: 3px $grid-unit-20; // Use padding to offset the is-active border, this benefits Windows High Contrast mode
 	margin-left: 0;
 	font-weight: 500;
-	transition: box-shadow 0.1s linear;
-	box-sizing: border-box;
 
-	// This pseudo-element "duplicates" the tab label and sets the text to bold.
-	// This ensures that the tab doesn't change width when selected.
-	// See: https://github.com/WordPress/gutenberg/pull/9793
+	&:focus:not(:disabled) {
+		position: relative;
+		box-shadow: none;
+	}
+
+	// Tab indicator
 	&::after {
-		content: attr(data-label);
-		display: block;
-		height: 0;
-		overflow: hidden;
-		speak: none;
-		visibility: hidden;
+		content: "";
+		position: absolute;
+		right: 0;
+		bottom: 0;
+		left: 0;
+		pointer-events: none;
+
+		// Draw the indicator.
+		background: $components-color-accent;
+		height: calc(0 * var(--wp-admin-border-width-focus));
+		border-radius: 0;
+
+		// Animation
+		transition: all 0.1s linear;
+		@include reduce-motion("transition");
 	}
 
-	&:focus:not(:disabled) {
-		box-shadow: inset 0 var(--wp-admin-border-width-focus) $components-color-accent;
+	// Active.
+	&.is-active::after {
+		height: calc(1 * var(--wp-admin-border-width-focus));
 	}
 
-	&.is-active {
-		// The transparent shadow ensures no jumpiness when focus animates on an active tab.
-		box-shadow: inset 0 0 0 var(--wp-admin-border-width-focus) transparent, inset 0 0 -$border-width-tab 0 0 $components-color-accent;
-		position: relative;
+	// Focus.
+	&::before {
+		content: "";
+		position: absolute;
+		top: $grid-unit-15;
+		right: $grid-unit-15;
+		bottom: $grid-unit-15;
+		left: $grid-unit-15;
+		pointer-events: none;
 
-		// This border appears in Windows High Contrast mode instead of the box-shadow.
-		&::before {
-			content: "";
-			position: absolute;
-			top: 0;
-			bottom: 1px;
-			right: 0;
-			left: 0;
-			border-bottom: $border-width-tab solid transparent;
-		}
-	}
+		// Draw the indicator.
+		box-shadow: 0 0 0 0 transparent;
+		border-radius: $radius-block-ui;
 
-	&:focus {
-		box-shadow: inset 0 0 0 var(--wp-admin-border-width-focus) $components-color-accent;
+		// Animation
+		transition: all 0.1s linear;
+		@include reduce-motion("transition");
 	}
 
-	&.is-active:focus {
-		box-shadow: inset 0 0 0 var(--wp-admin-border-width-focus) $components-color-accent, inset 0 -#{$border-width-tab * 2} 0 0 $components-color-accent;
+	&:focus-visible::before {
+		box-shadow: 0 0 0 var(--wp-admin-border-width-focus) $components-color-accent;
 	}
 }

package/src/tab-panel/test/index.tsx

@@ -9,6 +9,8 @@ import userEvent from '@testing-library/user-event';
  */
 import TabPanel from '..';
 
+jest.useFakeTimers();
+
 const setupUser = () =>
 	userEvent.setup( {
 		advanceTimers: jest.advanceTimersByTime,
@@ -34,7 +36,24 @@ const TABS = [
 
 const getSelectedTab = () => screen.getByRole( 'tab', { selected: true } );
 
+let originalGetClientRects: () => DOMRectList;
+
 describe( 'TabPanel', () => {
+	beforeAll( () => {
+		originalGetClientRects = window.HTMLElement.prototype.getClientRects;
+		// 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' ];
+		};
+	} );
+
+	afterAll( () => {
+		window.HTMLElement.prototype.getClientRects = originalGetClientRects;
+	} );
+
 	it( 'should render a tabpanel, and clicking should change tabs', async () => {
 		const user = setupUser();
 		const panelRenderFunction = jest.fn();
@@ -194,4 +213,98 @@ describe( 'TabPanel', () => {
 			expect( mockOnSelect ).toHaveBeenLastCalledWith( 'beta' );
 		} );
 	} );
+
+	describe( 'tab activation', () => {
+		it( 'defaults to automatic tab activation', async () => {
+			const user = setupUser();
+			const mockOnSelect = jest.fn();
+
+			render(
+				<TabPanel
+					tabs={ TABS }
+					children={ () => undefined }
+					onSelect={ mockOnSelect }
+				/>
+			);
+
+			// onSelect gets called on the initial render.
+			expect( mockOnSelect ).toHaveBeenCalledTimes( 1 );
+
+			// Click on Alpha, make sure Alpha is selected
+			await user.click( screen.getByRole( 'tab', { name: 'Alpha' } ) );
+			expect( mockOnSelect ).toHaveBeenCalledTimes( 2 );
+			expect( mockOnSelect ).toHaveBeenLastCalledWith( 'alpha' );
+
+			// Navigate forward with arrow keys,
+			// make sure Beta is selected automatically.
+			await user.keyboard( '[ArrowRight]' );
+			expect( mockOnSelect ).toHaveBeenCalledTimes( 3 );
+			expect( mockOnSelect ).toHaveBeenLastCalledWith( 'beta' );
+
+			// Navigate forward with arrow keys,
+			// make sure Gamma (last tab) is selected automatically.
+			await user.keyboard( '[ArrowRight]' );
+			expect( mockOnSelect ).toHaveBeenCalledTimes( 4 );
+			expect( mockOnSelect ).toHaveBeenLastCalledWith( 'gamma' );
+
+			// Navigate forward with arrow keys,
+			// make sure Alpha (first tab) is selected automatically.
+			await user.keyboard( '[ArrowRight]' );
+			expect( mockOnSelect ).toHaveBeenCalledTimes( 5 );
+			expect( mockOnSelect ).toHaveBeenLastCalledWith( 'alpha' );
+
+			// Navigate backwards with arrow keys,
+			// make sure Gamma (last tab) is selected automatically
+			await user.keyboard( '[ArrowLeft]' );
+			expect( mockOnSelect ).toHaveBeenCalledTimes( 6 );
+			expect( mockOnSelect ).toHaveBeenLastCalledWith( 'gamma' );
+		} );
+
+		it( 'switches to manual tab activation when the `selectOnMove` prop is set to `false`', async () => {
+			const user = setupUser();
+			const mockOnSelect = jest.fn();
+
+			render(
+				<TabPanel
+					tabs={ TABS }
+					children={ () => undefined }
+					onSelect={ mockOnSelect }
+					selectOnMove={ false }
+				/>
+			);
+
+			// onSelect gets called on the initial render.
+			expect( mockOnSelect ).toHaveBeenCalledTimes( 1 );
+
+			// Click on Alpha, make sure Alpha is selected
+			await user.click( screen.getByRole( 'tab', { name: 'Alpha' } ) );
+			expect( mockOnSelect ).toHaveBeenCalledTimes( 2 );
+			expect( mockOnSelect ).toHaveBeenLastCalledWith( 'alpha' );
+
+			// Navigate forward with arrow keys.
+			// Make sure Beta is focused, but that the tab selection happens only when
+			// pressing the spacebar or the enter key.
+			await user.keyboard( '[ArrowRight]' );
+			expect( mockOnSelect ).toHaveBeenCalledTimes( 2 );
+			expect( screen.getByRole( 'tab', { name: 'Beta' } ) ).toHaveFocus();
+			await user.keyboard( '[Enter]' );
+			expect( mockOnSelect ).toHaveBeenCalledTimes( 3 );
+			expect( mockOnSelect ).toHaveBeenLastCalledWith( 'beta' );
+
+			// Navigate forward with arrow keys.
+			// Make sure Gamma (last tab) is focused, but that the tab selection
+			// happens only when pressing the spacebar or the enter key.
+			await user.keyboard( '[ArrowRight]' );
+			expect( mockOnSelect ).toHaveBeenCalledTimes( 3 );
+			expect(
+				screen.getByRole( 'tab', { name: 'Gamma' } )
+			).toHaveFocus();
+			await user.keyboard( '[Space]' );
+			expect( mockOnSelect ).toHaveBeenCalledTimes( 4 );
+			expect( mockOnSelect ).toHaveBeenLastCalledWith( 'gamma' );
+
+			// No need to test the "wrap-around" behavior, as it's being tested in the
+			// "automatic tab activation" test above.
+		} );
+	} );
 } );