@wordpress/components 22.1.0 → 23.0.0

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

@@ -77,6 +77,7 @@ export function TabPanel( {
 	className,
 	children,
 	tabs,
+	selectOnMove = true,
 	initialTabName,
 	orientation = 'horizontal',
 	activeClass = 'is-active',
@@ -93,7 +94,12 @@ 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 } );
@@ -110,7 +116,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 +135,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

@@ -34,7 +34,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 +211,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.
+		} );
+	} );
 } );

package/src/tab-panel/types.ts

@@ -3,6 +3,11 @@
  */
 import type { ReactNode } from 'react';
 
+/**
+ * Internal dependencies
+ */
+import type { IconType } from '../icon';
+
 type Tab = {
 	/**
 	 * The key of the tab.
@@ -18,11 +23,14 @@ type Tab = {
 	className?: string;
 } & Record< any, any >;
 
-export type TabButtonProps = {
+export type TabButtonProps< IconProps = unknown > = {
 	children: ReactNode;
 	className?: string;
+	icon?: IconType< IconProps >;
+	label?: string;
 	onClick: ( event: MouseEvent ) => void;
 	selected: boolean;
+	showTooltip?: boolean;
 	tabId: string;
 };
 
@@ -62,4 +70,15 @@ export type TabPanelProps = {
 	 * Array of tab objects. Each tab object should contain at least a `name` and a `title`.
 	 */
 	tabs: Tab[];
+	/**
+	 * 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 for more info.
+	 * .
+	 *
+	 * @default true
+	 *
+	 * @see https://www.w3.org/WAI/ARIA/apg/patterns/tabpanel/
+	 */
+	selectOnMove?: boolean;
 };

package/src/text/test/__snapshots__/index.tsx.snap

@@ -36,6 +36,7 @@ exports[`Text should render highlighted words with highlightCaseSensitive 1`] =
     class="components-truncate components-text emotion-0 emotion-1"
     data-wp-c16t="true"
     data-wp-component="Text"
+    role="heading"
   >
     <span
       class=""