@wordpress/components 23.2.0 → 23.3.0

package/src/query-controls/terms.ts

@@ -0,0 +1,57 @@
+/**
+ * External dependencies
+ */
+import { groupBy } from 'lodash';
+
+/**
+ * Internal dependencies
+ */
+import type {
+	Author,
+	Category,
+	TermWithParentAndChildren,
+	TermsByParent,
+} from './types';
+
+/**
+ * Returns terms in a tree form.
+ *
+ * @param  flatTerms Array of terms in flat format.
+ *
+ * @return Terms in tree format.
+ */
+export function buildTermsTree( flatTerms: readonly ( Author | Category )[] ) {
+	const flatTermsWithParentAndChildren: TermWithParentAndChildren[] =
+		flatTerms.map( ( term ) => {
+			return {
+				children: [],
+				parent: null,
+				...term,
+				id: String( term.id ),
+			};
+		} );
+
+	const termsByParent: TermsByParent = groupBy(
+		flatTermsWithParentAndChildren,
+		'parent'
+	);
+	if ( termsByParent.null && termsByParent.null.length ) {
+		return flatTermsWithParentAndChildren;
+	}
+	const fillWithChildren = (
+		terms: TermWithParentAndChildren[]
+	): TermWithParentAndChildren[] => {
+		return terms.map( ( term ) => {
+			const children = termsByParent[ term.id ];
+			return {
+				...term,
+				children:
+					children && children.length
+						? fillWithChildren( children )
+						: [],
+			};
+		} );
+	};
+
+	return fillWithChildren( termsByParent[ '0' ] || [] );
+}

package/src/query-controls/test/{terms.js → terms.ts}

@@ -6,38 +6,53 @@ import { buildTermsTree } from '../terms';
 describe( 'buildTermsTree()', () => {
 	it( 'Should return same array as input with null parent and empty children added if parent is never specified.', () => {
 		const input = Object.freeze( [
-			{ id: 2232, dummy: true },
-			{ id: 2245, dummy: true },
+			{ id: 2232, name: 'foo', dummy: true },
+			{ id: 2245, name: 'baz', dummy: true },
 		] );
 		const output = Object.freeze( [
-			{ id: 2232, parent: null, children: [], dummy: true },
-			{ id: 2245, parent: null, children: [], dummy: true },
+			{
+				id: '2232',
+				name: 'foo',
+				parent: null,
+				children: [],
+				dummy: true,
+			},
+			{
+				id: '2245',
+				name: 'baz',
+				parent: null,
+				children: [],
+				dummy: true,
+			},
 		] );
 		const termsTreem = buildTermsTree( input );
 		expect( termsTreem ).toEqual( output );
 	} );
 	it( 'Should return same array as input with empty children added if all the elements are top level', () => {
 		const input = Object.freeze( [
-			{ id: 2232, parent: 0, dummy: true },
-			{ id: 2245, parent: 0, dummy: false },
+			{ id: 2232, name: 'foo', parent: 0, dummy: true },
+			{ id: 2245, name: 'baz', parent: 0, dummy: false },
 		] );
 		const output = [
-			{ id: 2232, parent: 0, children: [], dummy: true },
-			{ id: 2245, parent: 0, children: [], dummy: false },
+			{ id: '2232', name: 'foo', parent: 0, children: [], dummy: true },
+			{ id: '2245', name: 'baz', parent: 0, children: [], dummy: false },
 		];
 		const termsTreem = buildTermsTree( input );
 		expect( termsTreem ).toEqual( output );
 	} );
 	it( 'Should return element with its child if a child exists', () => {
 		const input = Object.freeze( [
-			{ id: 2232, parent: 0 },
-			{ id: 2245, parent: 2232 },
+			{ id: 2232, name: 'foo', parent: 0 },
+			{ id: 2245, name: 'baz', parent: 2232 },
 		] );
 		const output = [
 			{
-				id: 2232,
+				id: '2232',
+				name: 'foo',
 				parent: 0,
-				children: [ { id: 2245, parent: 2232, children: [] } ],
+				children: [
+					{ id: '2245', name: 'baz', parent: 2232, children: [] },
+				],
 			},
 		];
 		const termsTreem = buildTermsTree( input );
@@ -45,21 +60,22 @@ describe( 'buildTermsTree()', () => {
 	} );
 	it( 'Should return elements with multiple children and elements with no children', () => {
 		const input = Object.freeze( [
-			{ id: 2232, parent: 0 },
-			{ id: 2245, parent: 2232 },
-			{ id: 2249, parent: 0 },
-			{ id: 2246, parent: 2232 },
+			{ id: 2232, name: 'a', parent: 0 },
+			{ id: 2245, name: 'b', parent: 2232 },
+			{ id: 2249, name: 'c', parent: 0 },
+			{ id: 2246, name: 'd', parent: 2232 },
 		] );
 		const output = [
 			{
-				id: 2232,
+				id: '2232',
+				name: 'a',
 				parent: 0,
 				children: [
-					{ id: 2245, parent: 2232, children: [] },
-					{ id: 2246, parent: 2232, children: [] },
+					{ id: '2245', name: 'b', parent: 2232, children: [] },
+					{ id: '2246', name: 'd', parent: 2232, children: [] },
 				],
 			},
-			{ id: 2249, parent: 0, children: [] },
+			{ id: '2249', name: 'c', parent: 0, children: [] },
 		];
 		const termsTreem = buildTermsTree( input );
 		expect( termsTreem ).toEqual( output );

package/src/query-controls/types.ts

@@ -0,0 +1,150 @@
+/**
+ * Internal dependencies
+ */
+import type { FormTokenFieldProps } from '../form-token-field/types';
+import type { TreeSelectProps } from '../tree-select/types';
+
+export type Author = {
+	id: number;
+	name: string;
+};
+
+export type Category = {
+	id: number;
+	name: string;
+	parent: number;
+};
+
+export type TermWithParentAndChildren = {
+	id: string;
+	name: string;
+	parent: number | null;
+	children: TermWithParentAndChildren[];
+};
+
+export type TermsByParent = Record< string, TermWithParentAndChildren[] >;
+
+export type CategorySelectProps = Pick<
+	TreeSelectProps,
+	'label' | 'noOptionLabel'
+> & {
+	categoriesList: Category[];
+	onChange: ( newCategory: string ) => void;
+	selectedCategoryId?: Category[ 'id' ];
+};
+
+export type AuthorSelectProps = Pick<
+	TreeSelectProps,
+	'label' | 'noOptionLabel'
+> & {
+	authorList?: Author[];
+	onChange: ( newAuthor: string ) => void;
+	selectedAuthorId?: Author[ 'id' ];
+};
+
+type Order = 'asc' | 'desc';
+type OrderBy = 'date' | 'title';
+
+type BaseQueryControlsProps = {
+	/**
+	 * An array of the authors to select from.
+	 */
+	authorList?: AuthorSelectProps[ 'authorList' ];
+	/**
+	 * The maximum number of items.
+	 *
+	 * @default 100
+	 */
+	maxItems?: number;
+	/**
+	 * The minimum number of items.
+	 *
+	 * @default 1
+	 */
+	minItems?: number;
+	/**
+	 * The selected number of items to retrieve via the query.
+	 */
+	numberOfItems?: number;
+	/**
+	 * A function that receives the new author value.
+	 * If not specified, the author controls are not rendered.
+	 */
+	onAuthorChange?: AuthorSelectProps[ 'onChange' ];
+	/**
+	 * A function that receives the new number of items.
+	 * If not specified, then the number of items
+	 * range control is not rendered.
+	 */
+	onNumberOfItemsChange?: ( newNumber?: number ) => void;
+	/**
+	 * A function that receives the new order value.
+	 * If this prop or the `onOrderByChange` prop are not specified,
+	 * then the order controls are not rendered.
+	 */
+	onOrderChange?: ( newOrder: Order ) => void;
+	/**
+	 * A function that receives the new orderby value.
+	 * If this prop or the `onOrderChange` prop are not specified,
+	 * then the order controls are not rendered.
+	 */
+	onOrderByChange?: ( newOrderBy: OrderBy ) => void;
+	/**
+	 * The order in which to retrieve posts.
+	 */
+	order?: Order;
+	/**
+	 * The meta key by which to order posts.
+	 */
+	orderBy?: OrderBy;
+	/**
+	 * The selected author ID.
+	 */
+	selectedAuthorId?: AuthorSelectProps[ 'selectedAuthorId' ];
+};
+
+export type QueryControlsWithSingleCategorySelectionProps =
+	BaseQueryControlsProps & {
+		/**
+		 * An array of categories. When passed in conjunction with the
+		 * `onCategoryChange` prop, it causes the component to render UI that allows
+		 * selecting one category at a time.
+		 */
+		categoriesList?: CategorySelectProps[ 'categoriesList' ];
+		/**
+		 * The selected category for the `categoriesList` prop.
+		 */
+		selectedCategoryId?: CategorySelectProps[ 'selectedCategoryId' ];
+		/**
+		 * A function that receives the new category value. If not specified, the
+		 * category controls are not rendered.
+		 * The function's signature changes depending on whether multiple category
+		 * selection is enabled or not.
+		 */
+		onCategoryChange?: CategorySelectProps[ 'onChange' ];
+	};
+
+export type QueryControlsWithMultipleCategorySelectionProps =
+	BaseQueryControlsProps & {
+		/**
+		 * An object of categories with the category name as the key. When passed in
+		 * conjunction with the `onCategoryChange` prop, it causes the component to
+		 * render UI that enables multiple selection.
+		 */
+		categorySuggestions?: Record< Category[ 'name' ], Category >;
+		/**
+		 * The selected categories for the `categorySuggestions` prop.
+		 */
+		selectedCategories?: Category[];
+		/**
+		 * A function that receives the new category value. If not specified, the
+		 * category controls are not rendered.
+		 * The function's signature changes depending on whether multiple category
+		 * selection is enabled or not.
+		 */
+		onCategoryChange?: FormTokenFieldProps[ 'onChange' ];
+	};
+
+export type QueryControlsProps =
+	| QueryControlsWithSingleCategorySelectionProps
+	| QueryControlsWithMultipleCategorySelectionProps;

package/src/select-control/test/select-control.tsx

@@ -9,12 +9,7 @@ import userEvent from '@testing-library/user-event';
  */
 import SelectControl from '..';
 
-jest.useFakeTimers();
-
-const setupUser = () =>
-	userEvent.setup( {
-		advanceTimers: jest.advanceTimersByTime,
-	} );
+const setupUser = () => userEvent.setup();
 
 describe( 'SelectControl', () => {
 	it( 'should not render when no options or children are provided', () => {

package/src/slot-fill/bubbles-virtually/fill.js

@@ -15,6 +15,7 @@ function useForceUpdate() {
 	const mounted = useRef( true );
 
 	useEffect( () => {
+		mounted.current = true;
 		return () => {
 			mounted.current = false;
 		};

package/src/slot-fill/slot.js

@@ -34,7 +34,7 @@ class SlotComponent extends Component {
 
 	componentDidMount() {
 		const { registerSlot } = this.props;
-
+		this.isUnmounted = false;
 		registerSlot( this.props.name, this );
 	}
 

package/src/slot-fill/use-slot.js

@@ -2,7 +2,7 @@
 /**
  * WordPress dependencies
  */
-import { useContext, useState, useEffect } from '@wordpress/element';
+import { useContext, useSyncExternalStore } from '@wordpress/element';
 
 /**
  * Internal dependencies
@@ -17,21 +17,11 @@ import SlotFillContext from './context';
  */
 const useSlot = ( name ) => {
 	const { getSlot, subscribe } = useContext( SlotFillContext );
-	const [ slot, setSlot ] = useState( getSlot( name ) );
-
-	useEffect( () => {
-		setSlot( getSlot( name ) );
-		const unsubscribe = subscribe( () => {
-			setSlot( getSlot( name ) );
-		} );
-
-		return unsubscribe;
-		// Ignore reason: Modifying this dep array could introduce unexpected changes in behavior,
-		// so we'll leave it as=is until the hook can be properly refactored for exhaustive-deps.
-		// eslint-disable-next-line react-hooks/exhaustive-deps
-	}, [ name ] );
-
-	return slot;
+	return useSyncExternalStore(
+		subscribe,
+		() => getSlot( name ),
+		() => getSlot( name )
+	);
 };
 
 export default useSlot;

package/src/snackbar/index.tsx

@@ -16,7 +16,8 @@ import warning from '@wordpress/warning';
  * Internal dependencies
  */
 import Button from '../button';
-import type { NoticeAction, SnackbarProps } from './types';
+import type { SnackbarProps } from './types';
+import type { NoticeAction } from '../notice/types';
 import type { WordPressComponentProps } from '../ui/context';
 
 const NOTICE_TIMEOUT = 10000;
@@ -73,7 +74,7 @@ function UnforwardedSnackbar(
 	}
 
 	function onActionClick(
-		event: MouseEvent,
+		event: MouseEvent< HTMLButtonElement >,
 		onClick: NoticeAction[ 'onClick' ]
 	) {
 		event.stopPropagation();
@@ -139,9 +140,9 @@ function UnforwardedSnackbar(
 							key={ index }
 							href={ url }
 							variant="tertiary"
-							onClick={ ( event: MouseEvent ) =>
-								onActionClick( event, onClick )
-							}
+							onClick={ (
+								event: MouseEvent< HTMLButtonElement >
+							) => onActionClick( event, onClick ) }
 							className="components-snackbar__action"
 						>
 							{ label }

package/src/snackbar/list.tsx

@@ -17,7 +17,7 @@ import {
 	__unstableMotion as motion,
 	__unstableAnimatePresence as AnimatePresence,
 } from '../animation';
-import type { Notice, SnackbarListProps } from './types';
+import type { SnackbarListProps } from './types';
 import type { WordPressComponentProps } from '../ui/context';
 
 const SNACKBAR_VARIANTS = {
@@ -61,7 +61,9 @@ export function SnackbarList( {
 	const listRef = useRef< HTMLDivElement | null >( null );
 	const isReducedMotion = useReducedMotion();
 	className = classnames( 'components-snackbar-list', className );
-	const removeNotice = ( notice: Notice ) => () => onRemove?.( notice.id );
+	const removeNotice =
+		( notice: SnackbarListProps[ 'notices' ][ number ] ) => () =>
+			onRemove?.( notice.id );
 	return (
 		<div className={ className } tabIndex={ -1 } ref={ listRef }>
 			{ children }

package/src/snackbar/types.ts

@@ -1,116 +1,42 @@
 /**
  * External dependencies
  */
-import type { MutableRefObject, ReactNode, SyntheticEvent } from 'react';
+import type { MutableRefObject, ReactNode } 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;
-};
+/**
+ * Internal dependencies
+ */
+import type { NoticeProps, NoticeChildren } from '../notice/types';
 
-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;
+type SnackbarOnlyProps = {
 	/**
 	 * The icon to render in the snackbar.
 	 *
 	 * @default null
 	 */
-	icon?: Notice[ 'icon' ];
+	icon?: ReactNode;
 	/**
 	 * 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' ];
+	explicitDismiss?: boolean;
 	/**
 	 * A ref to the list that contains the snackbar.
 	 */
 	listRef?: MutableRefObject< HTMLDivElement | null >;
 };
 
+export type SnackbarProps = NoticeProps & SnackbarOnlyProps;
+
 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;
+	notices: Array<
+		Omit< SnackbarProps, 'children' > & {
+			id: string;
+			content: string;
+		}
+	>;
+	onRemove: ( id: string ) => void;
+	children?: NoticeChildren | Array< NoticeChildren >;
 };

package/src/tab-panel/index.tsx

@@ -25,7 +25,7 @@ const TabButton = ( {
 }: TabButtonProps ) => (
 	<Button
 		role="tab"
-		tabIndex={ selected ? null : -1 }
+		tabIndex={ selected ? undefined : -1 }
 		aria-selected={ selected }
 		id={ tabId }
 		__experimentalIsFocusable
@@ -103,25 +103,47 @@ export function TabPanel( {
 	const selectedTab = tabs.find( ( { name } ) => name === selected );
 	const selectedId = `${ instanceId }-${ selectedTab?.name ?? 'none' }`;
 
+	// Handle selecting the initial tab.
 	useEffect( () => {
-		const firstEnabledTab = tabs.find( ( tab ) => ! tab.disabled );
+		// If there's a selected tab, don't override it.
+		if ( selectedTab ) {
+			return;
+		}
+
 		const initialTab = tabs.find( ( tab ) => tab.name === initialTabName );
-		if ( ! selectedTab?.name && firstEnabledTab ) {
-			handleTabSelection(
-				initialTab && ! initialTab.disabled
-					? initialTab.name
-					: firstEnabledTab.name
-			);
-		} else if ( selectedTab?.disabled && firstEnabledTab ) {
+
+		// Wait for the denoted initial tab to be declared before making a
+		// selection. This ensures that if a tab is declared lazily it can
+		// still receive initial selection.
+		if ( initialTabName && ! initialTab ) {
+			return;
+		}
+
+		if ( initialTab && ! initialTab.disabled ) {
+			// Select the initial tab if it's not disabled.
+			handleTabSelection( initialTab.name );
+		} else {
+			// Fallback to the first enabled tab when the initial is disabled.
+			const firstEnabledTab = tabs.find( ( tab ) => ! tab.disabled );
+			if ( firstEnabledTab ) handleTabSelection( firstEnabledTab.name );
+		}
+	}, [ tabs, selectedTab, initialTabName, handleTabSelection ] );
+
+	// Handle the currently selected tab becoming disabled.
+	useEffect( () => {
+		// This effect only runs when the selected tab is defined and becomes disabled.
+		if ( ! selectedTab?.disabled ) {
+			return;
+		}
+
+		const firstEnabledTab = tabs.find( ( tab ) => ! tab.disabled );
+
+		// If the currently selected tab becomes disabled, select the first enabled tab.
+		// (if there is one).
+		if ( firstEnabledTab ) {
 			handleTabSelection( firstEnabledTab.name );
 		}
-	}, [
-		tabs,
-		selectedTab?.name,
-		selectedTab?.disabled,
-		initialTabName,
-		handleTabSelection,
-	] );
+	}, [ tabs, selectedTab?.disabled, handleTabSelection ] );
 
 	return (
 		<div className={ className }>

package/src/tab-panel/style.scss

@@ -24,6 +24,7 @@
 	&:focus:not(:disabled) {
 		position: relative;
 		box-shadow: none;
+		outline: none;
 	}
 
 	// Tab indicator
@@ -48,6 +49,10 @@
 	// Active.
 	&.is-active::after {
 		height: calc(1 * var(--wp-admin-border-width-focus));
+
+		// Windows high contrast mode.
+		outline: 2px solid transparent;
+		outline-offset: -1px;
 	}
 
 	// Focus.
@@ -71,5 +76,8 @@
 
 	&:focus-visible::before {
 		box-shadow: 0 0 0 var(--wp-admin-border-width-focus) $components-color-accent;
+
+		// Windows high contrast mode.
+		outline: 2px solid transparent;
 	}
 }