@wordpress/components 23.5.0 → 23.7.0

package/src/select-control/types.ts

@@ -9,19 +9,46 @@ import type { ChangeEvent, FocusEvent, ReactNode } from 'react';
 import type { InputBaseProps } from '../input-control/types';
 import type { BaseControlProps } from '../base-control/types';
 
-export interface SelectControlProps
-	extends Pick<
-			InputBaseProps,
-			| '__next36pxDefaultSize'
-			| 'disabled'
-			| 'hideLabelFromVision'
-			| 'label'
-			| 'labelPosition'
-			| 'prefix'
-			| 'size'
-			| 'suffix'
-		>,
-		Pick< BaseControlProps, 'help' | '__nextHasNoMarginBottom' > {
+type SelectControlBaseProps = Pick<
+	InputBaseProps,
+	| '__next36pxDefaultSize'
+	| 'disabled'
+	| 'hideLabelFromVision'
+	| 'label'
+	| 'labelPosition'
+	| 'prefix'
+	| 'size'
+	| 'suffix'
+> &
+	Pick< BaseControlProps, 'help' | '__nextHasNoMarginBottom' > & {
+		onBlur?: ( event: FocusEvent< HTMLSelectElement > ) => void;
+		onFocus?: ( event: FocusEvent< HTMLSelectElement > ) => void;
+		options?: {
+			/**
+			 * The label to be shown to the user.
+			 */
+			label: string;
+			/**
+			 * The internal value used to choose the selected value.
+			 * This is also the value passed to `onChange` when the option is selected.
+			 */
+			value: string;
+			id?: string;
+			/**
+			 * Whether or not the option should have the disabled attribute.
+			 *
+			 * @default false
+			 */
+			disabled?: boolean;
+		}[];
+		/**
+		 * As an alternative to the `options` prop, `optgroup`s and `options` can be
+		 * passed in as `children` for more customizability.
+		 */
+		children?: ReactNode;
+	};
+
+export type SelectControlSingleSelectionProps = SelectControlBaseProps & {
 	/**
 	 * If this property is added, multiple values can be selected. The `value` passed should be an array.
 	 *
@@ -29,9 +56,8 @@ export interface SelectControlProps
 	 *
 	 * @default false
 	 */
-	multiple?: boolean;
-	onBlur?: ( event: FocusEvent< HTMLSelectElement > ) => void;
-	onFocus?: ( event: FocusEvent< HTMLSelectElement > ) => void;
+	multiple?: false;
+	value?: string;
 	/**
 	 * A function that receives the value of the new option that is being selected as input.
 	 *
@@ -39,31 +65,33 @@ export interface SelectControlProps
 	 * Otherwise, the value received is a single value with the new selected value.
 	 */
 	onChange?: (
-		value: string | string[],
+		value: string,
 		extra?: { event?: ChangeEvent< HTMLSelectElement > }
 	) => void;
-	options?: {
-		/**
-		 * The label to be shown to the user.
-		 */
-		label: string;
-		/**
-		 * The internal value used to choose the selected value.
-		 * This is also the value passed to `onChange` when the option is selected.
-		 */
-		value: string;
-		id?: string;
-		/**
-		 * Whether or not the option should have the disabled attribute.
-		 *
-		 * @default false
-		 */
-		disabled?: boolean;
-	}[];
-	value?: string | string[];
+};
+
+export type SelectControlMultipleSelectionProps = SelectControlBaseProps & {
 	/**
-	 * As an alternative to the `options` prop, `optgroup`s and `options` can be
-	 * passed in as `children` for more customizability.
+	 * If this property is added, multiple values can be selected. The `value` passed should be an array.
+	 *
+	 * In most cases, it is preferable to use the `FormTokenField` or `CheckboxControl` components instead.
+	 *
+	 * @default false
+	 */
+	multiple: true;
+	value?: string[];
+	/**
+	 * A function that receives the value of the new option that is being selected as input.
+	 *
+	 * If `multiple` is `true`, the value received is an array of the selected value.
+	 * Otherwise, the value received is a single value with the new selected value.
 	 */
-	children?: ReactNode;
-}
+	onChange?: (
+		value: string[],
+		extra?: { event?: ChangeEvent< HTMLSelectElement > }
+	) => void;
+};
+
+export type SelectControlProps =
+	| SelectControlSingleSelectionProps
+	| SelectControlMultipleSelectionProps;

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

@@ -1,7 +1,8 @@
 /**
  * External dependencies
  */
-import { render, fireEvent, screen } from '@testing-library/react';
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
 
 /**
  * Internal dependencies
@@ -92,9 +93,9 @@ describe( 'Slot', () => {
 		expect( container ).toMatchSnapshot();
 	} );
 
-	it( 'calls the functions passed as the Slot’s fillProps in the Fill', () => {
+	it( 'calls the functions passed as the Slot’s fillProps in the Fill', async () => {
 		const onClose = jest.fn();
-
+		const user = userEvent.setup();
 		render(
 			<Provider>
 				<Slot name="chicken" fillProps={ { onClose } } />
@@ -108,7 +109,7 @@ describe( 'Slot', () => {
 			</Provider>
 		);
 
-		fireEvent.click( screen.getByText( 'Click me' ) );
+		await user.click( screen.getByText( 'Click me' ) );
 
 		expect( onClose ).toHaveBeenCalledTimes( 1 );
 	} );
@@ -149,7 +150,8 @@ describe( 'Slot', () => {
 		expect( container ).toMatchSnapshot();
 	} );
 
-	it( 'should re-render Slot when not bubbling virtually', () => {
+	it( 'should re-render Slot when not bubbling virtually', async () => {
+		const user = userEvent.setup();
 		const { container } = render(
 			<Provider>
 				<div>
@@ -161,7 +163,7 @@ describe( 'Slot', () => {
 
 		expect( container ).toMatchSnapshot();
 
-		fireEvent.click( screen.getByRole( 'button' ) );
+		await user.click( screen.getByRole( 'button' ) );
 
 		expect( container ).toMatchSnapshot();
 	} );

package/src/style.scss

@@ -11,7 +11,6 @@
 @import "./palette-edit/style.scss";
 @import "./color-indicator/style.scss";
 @import "./combobox-control/style.scss";
-@import "./color-list-picker/style.scss";
 @import "./color-palette/style.scss";
 @import "./custom-gradient-picker/style.scss";
 @import "./custom-select-control/style.scss";
@@ -21,6 +20,7 @@
 @import "./dropdown/style.scss";
 @import "./dropdown-menu/style.scss";
 @import "./duotone-picker/style.scss";
+@import "./duotone-picker/color-list-picker/style.scss";
 @import "./form-toggle/style.scss";
 @import "./form-token-field/style.scss";
 @import "./guide/style.scss";

package/src/tab-panel/index.tsx

@@ -6,7 +6,12 @@ import classnames from 'classnames';
 /**
  * WordPress dependencies
  */
-import { useState, useEffect, useCallback } from '@wordpress/element';
+import {
+	useState,
+	useEffect,
+	useLayoutEffect,
+	useCallback,
+} from '@wordpress/element';
 import { useInstanceId } from '@wordpress/compose';
 
 /**
@@ -104,7 +109,7 @@ export function TabPanel( {
 	const selectedId = `${ instanceId }-${ selectedTab?.name ?? 'none' }`;
 
 	// Handle selecting the initial tab.
-	useEffect( () => {
+	useLayoutEffect( () => {
 		// If there's a selected tab, don't override it.
 		if ( selectedTab ) {
 			return;

package/src/tab-panel/types.ts

@@ -8,7 +8,7 @@ import type { MouseEvent, ReactNode } from 'react';
  */
 import type { IconType } from '../icon';
 
-type Tab< IconProps = unknown > = {
+type Tab = {
 	/**
 	 * The key of the tab.
 	 */
@@ -24,21 +24,21 @@ type Tab< IconProps = unknown > = {
 	/**
 	 * The icon used for the tab button.
 	 */
-	icon?: IconType< IconProps >;
+	icon?: IconType;
 	/**
 	 * Determines if the tab button should be disabled.
 	 */
 	disabled?: boolean;
 } & Record< any, any >;
 
-export type TabButtonProps< IconProps = unknown > = {
+export type TabButtonProps = {
 	children: ReactNode;
 	label?: string;
 	onClick: ( event: MouseEvent ) => void;
 	selected: boolean;
 	showTooltip?: boolean;
 	tabId: string;
-} & Pick< Tab< IconProps >, 'className' | 'icon' | 'disabled' >;
+} & Pick< Tab, 'className' | 'icon' | 'disabled' >;
 
 export type TabPanelProps = {
 	/**

package/src/toolbar/toolbar-button/README.md

@@ -51,7 +51,19 @@ function Edit() {
 
 ## Props
 
-This component accepts [the same API of the Button](/packages/components/src/button/README.md#props) component.
+This component accepts [the same API of the Button](/packages/components/src/button/README.md#props) component in addition to:
+
+#### `containerClassName`: `string`
+
+An optional additional class name to apply to the button container.
+
+-   Required: No
+
+#### `subscript`: `string`
+
+An optional subscript for the button.
+
+-   Required: No
 
 ## Related components
 

package/src/toolbar/toolbar-button/{index.js → index.tsx}

@@ -1,13 +1,14 @@
-// @ts-nocheck
-
 /**
  * External dependencies
  */
 import classnames from 'classnames';
+import type { ForwardedRef } from 'react';
+
 /**
  * WordPress dependencies
  */
 import { useContext, forwardRef } from '@wordpress/element';
+
 /**
  * Internal dependencies
  */
@@ -15,19 +16,22 @@ import Button from '../../button';
 import ToolbarItem from '../toolbar-item';
 import ToolbarContext from '../toolbar-context';
 import ToolbarButtonContainer from './toolbar-button-container';
+import type { ToolbarButtonProps } from './types';
+import type { WordPressComponentProps } from '../../ui/context';
+import type React from 'react';
 
-function ToolbarButton(
+function UnforwardedToolbarButton(
 	{
-		containerClassName,
+		children,
 		className,
+		containerClassName,
 		extraProps,
-		children,
-		title,
 		isActive,
 		isDisabled,
+		title,
 		...props
-	},
-	ref
+	}: WordPressComponentProps< ToolbarButtonProps, typeof Button, false >,
+	ref: ForwardedRef< any >
 ) {
 	const accessibleToolbarState = useContext( ToolbarContext );
 
@@ -40,8 +44,14 @@ function ToolbarButton(
 					label={ title }
 					shortcut={ props.shortcut }
 					data-subscript={ props.subscript }
-					onClick={ ( event ) => {
+					onClick={ (
+						event: React.MouseEvent<
+							HTMLButtonElement & HTMLAnchorElement,
+							MouseEvent
+						>
+					) => {
 						event.stopPropagation();
+						// TODO: Possible bug; maybe use onClick instead of props.onClick.
 						if ( props.onClick ) {
 							props.onClick( event );
 						}
@@ -72,18 +82,43 @@ function ToolbarButton(
 			{ ...props }
 			ref={ ref }
 		>
-			{ ( toolbarItemProps ) => (
-				<Button
-					label={ title }
-					isPressed={ isActive }
-					disabled={ isDisabled }
-					{ ...toolbarItemProps }
-				>
-					{ children }
-				</Button>
-			) }
+			{
+				// @ts-expect-error
+				( toolbarItemProps ) => (
+					<Button
+						label={ title }
+						isPressed={ isActive }
+						disabled={ isDisabled }
+						{ ...toolbarItemProps }
+					>
+						{ children }
+					</Button>
+				)
+			}
 		</ToolbarItem>
 	);
 }
 
-export default forwardRef( ToolbarButton );
+/**
+ * ToolbarButton can be used to add actions to a toolbar, usually inside a Toolbar
+ * or ToolbarGroup when used to create general interfaces.
+ *
+ * ```jsx
+ * import { Toolbar, ToolbarButton } from '@wordpress/components';
+ * import { edit } from '@wordpress/icons';
+ *
+ * function MyToolbar() {
+ *   return (
+ *		<Toolbar label="Options">
+ *			<ToolbarButton
+ *				icon={ edit }
+ *				label="Edit"
+ *				onClick={ () => alert( 'Editing' ) }
+ *			/>
+ *		</Toolbar>
+ *   );
+ * }
+ * ```
+ */
+export const ToolbarButton = forwardRef( UnforwardedToolbarButton );
+export default ToolbarButton;

package/src/toolbar/toolbar-button/toolbar-button-container.tsx

@@ -0,0 +1,13 @@
+/**
+ * Internal dependencies
+ */
+import type { ToolbarButtonContainerProps } from './types';
+
+const ToolbarButtonContainer = ( {
+	children,
+	className,
+}: ToolbarButtonContainerProps ) => (
+	<div className={ className }>{ children }</div>
+);
+
+export default ToolbarButtonContainer;

package/src/toolbar/toolbar-button/types.ts

@@ -0,0 +1,46 @@
+/**
+ * External dependencies
+ */
+import type { ReactNode } from 'react';
+
+export type ToolbarButtonProps = {
+	/**
+	 * Children to be rendered inside the button.
+	 */
+	children?: ReactNode;
+	/**
+	 * An optional class name for the button container.
+	 */
+	containerClassName?: string;
+	/**
+	 * Additional props to be passed alongside props.
+	 */
+	extraProps?: any;
+	/**
+	 * Indicates if the button is active.
+	 */
+	isActive?: boolean;
+	/**
+	 * Indicates if the button is disabled.
+	 */
+	isDisabled?: boolean;
+	/**
+	 * An optional subscript for the button.
+	 */
+	subscript?: string;
+	/**
+	 * An optional title/label for the button.
+	 */
+	title?: string;
+};
+
+export type ToolbarButtonContainerProps = {
+	/**
+	 * Children to be rendered inside the button container.
+	 */
+	children?: ReactNode;
+	/**
+	 * An optional class name for the button container.
+	 */
+	className?: string;
+};

package/src/toolbar/toolbar-context/index.ts

@@ -0,0 +1,15 @@
+/**
+ * External dependencies
+ */
+import type { ToolbarStateReturn } from 'reakit/Toolbar';
+
+/**
+ * WordPress dependencies
+ */
+import { createContext } from '@wordpress/element';
+
+const ToolbarContext = createContext< ToolbarStateReturn | undefined >(
+	undefined
+);
+
+export default ToolbarContext;

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

@@ -954,6 +954,92 @@ describe( 'ToolsPanel', () => {
 			expect( items[ 1 ] ).toHaveTextContent( 'Item 2' );
 		} );
 
+		it( 'should maintain menu item order', async () => {
+			const InconsistentItems = () => (
+				<ToolsPanelItems>
+					<ToolsPanelItem
+						label="Item 1"
+						hasValue={ () => false }
+						isShownByDefault
+					>
+						<div>Item 1</div>
+					</ToolsPanelItem>
+					<ToolsPanelItem
+						label="Item 2"
+						hasValue={ () => false }
+						isShownByDefault
+					>
+						<div>Item 2</div>
+					</ToolsPanelItem>
+				</ToolsPanelItems>
+			);
+
+			const { rerender } = render(
+				<SlotFillProvider>
+					<InconsistentItems key="order-test-step-1" />
+					<ToolsPanelItems>
+						<ToolsPanelItem
+							label="Item 3"
+							hasValue={ () => false }
+							isShownByDefault
+						>
+							<div>Item 3</div>
+						</ToolsPanelItem>
+					</ToolsPanelItems>
+					<ToolsPanel { ...defaultProps }>
+						<Slot />
+					</ToolsPanel>
+				</SlotFillProvider>
+			);
+
+			// Open dropdown menu.
+			const user = userEvent.setup();
+			let menuButton = getMenuButton();
+			await user.click( menuButton );
+
+			// Confirm all the existing menu items are present and in the
+			// expected order.
+			let menuItems = await screen.findAllByRole( 'menuitemcheckbox' );
+
+			expect( menuItems.length ).toEqual( 3 );
+			expect( menuItems[ 0 ] ).toHaveTextContent( 'Item 1' );
+			expect( menuItems[ 1 ] ).toHaveTextContent( 'Item 2' );
+			expect( menuItems[ 2 ] ).toHaveTextContent( 'Item 3' );
+
+			// Close the dropdown menu.
+			await user.click( menuButton );
+
+			rerender(
+				<SlotFillProvider>
+					<InconsistentItems key="order-test-step-2" />
+					<ToolsPanelItems>
+						<ToolsPanelItem
+							label="Item 3"
+							hasValue={ () => false }
+							isShownByDefault
+						>
+							<div>Item 3</div>
+						</ToolsPanelItem>
+					</ToolsPanelItems>
+					<ToolsPanel { ...defaultProps }>
+						<Slot />
+					</ToolsPanel>
+				</SlotFillProvider>
+			);
+
+			// Reopen dropdown menu.
+			menuButton = getMenuButton();
+			await user.click( menuButton );
+
+			// Confirm the menu item order has been maintained.
+			menuItems = await screen.findAllByRole( 'menuitemcheckbox' );
+
+			expect( menuItems.length ).toEqual( 3 );
+			expect( menuItems[ 0 ] ).toHaveTextContent( 'Item 1' );
+			expect( menuItems[ 1 ] ).toHaveTextContent( 'Item 2' );
+			expect( menuItems[ 2 ] ).toHaveTextContent( 'Item 3' );
+		} );
+
 		it( 'should not trigger callback when fill has not updated yet when panel has', () => {
 			// Fill provided controls can update independently to the panel.
 			// A `panelId` prop was added to both panels and items

package/src/tools-panel/tools-panel/hook.ts

@@ -30,7 +30,9 @@ const generateMenuItems = ( {
 	panelItems,
 	shouldReset,
 	currentMenuItems,
+	menuItemOrder,
 }: ToolsPanelMenuItemsConfig ) => {
+	const newMenuItems: ToolsPanelMenuItems = { default: {}, optional: {} };
 	const menuItems: ToolsPanelMenuItems = { default: {}, optional: {} };
 
 	panelItems.forEach( ( { hasValue, isShownByDefault, label } ) => {
@@ -42,7 +44,31 @@ const generateMenuItems = ( {
 		const existingItemValue = currentMenuItems?.[ group ]?.[ label ];
 		const value = existingItemValue ? existingItemValue : hasValue();
 
-		menuItems[ group ][ label ] = shouldReset ? false : value;
+		newMenuItems[ group ][ label ] = shouldReset ? false : value;
+	} );
+
+	// Loop the known, previously registered items first to maintain menu order.
+	menuItemOrder.forEach( ( key ) => {
+		if ( newMenuItems.default.hasOwnProperty( key ) ) {
+			menuItems.default[ key ] = newMenuItems.default[ key ];
+		}
+
+		if ( newMenuItems.optional.hasOwnProperty( key ) ) {
+			menuItems.optional[ key ] = newMenuItems.optional[ key ];
+		}
+	} );
+
+	// Loop newMenuItems object adding any that aren't in the known items order.
+	Object.keys( newMenuItems.default ).forEach( ( key ) => {
+		if ( ! menuItems.default.hasOwnProperty( key ) ) {
+			menuItems.default[ key ] = newMenuItems.default[ key ];
+		}
+	} );
+
+	Object.keys( newMenuItems.optional ).forEach( ( key ) => {
+		if ( ! menuItems.optional.hasOwnProperty( key ) ) {
+			menuItems.optional[ key ] = newMenuItems.optional[ key ];
+		}
 	} );
 
 	return menuItems;
@@ -82,12 +108,14 @@ export function useToolsPanel(
 
 	// Allow panel items to register themselves.
 	const [ panelItems, setPanelItems ] = useState< ToolsPanelItem[] >( [] );
+	const [ menuItemOrder, setMenuItemOrder ] = useState< string[] >( [] );
 	const [ resetAllFilters, setResetAllFilters ] = useState<
 		ResetAllFilter[]
 	>( [] );
 
 	const registerPanelItem = useCallback(
 		( item: ToolsPanelItem ) => {
+			// Add item to panel items.
 			setPanelItems( ( items ) => {
 				const newItems = [ ...items ];
 				// If an item with this label has already been registered, remove it
@@ -101,8 +129,18 @@ export function useToolsPanel(
 				}
 				return [ ...newItems, item ];
 			} );
+
+			// Track the initial order of item registration. This is used for
+			// maintaining menu item order later.
+			setMenuItemOrder( ( items ) => {
+				if ( items.includes( item.label ) ) {
+					return items;
+				}
+
+				return [ ...items, item.label ];
+			} );
 		},
-		[ setPanelItems ]
+		[ setPanelItems, setMenuItemOrder ]
 	);
 
 	// Panels need to deregister on unmount to avoid orphans in menu state.
@@ -160,10 +198,11 @@ export function useToolsPanel(
 				panelItems,
 				shouldReset: false,
 				currentMenuItems: prevState,
+				menuItemOrder,
 			} );
 			return items;
 		} );
-	}, [ panelItems, setMenuItems ] );
+	}, [ panelItems, setMenuItems, menuItemOrder ] );
 
 	// Force a menu item to be checked.
 	// This is intended for use with default panel items. They are displayed
@@ -267,10 +306,11 @@ export function useToolsPanel(
 		// Turn off display of all non-default items.
 		const resetMenuItems = generateMenuItems( {
 			panelItems,
+			menuItemOrder,
 			shouldReset: true,
 		} );
 		setMenuItems( resetMenuItems );
-	}, [ panelItems, resetAllFilters, resetAll, setMenuItems ] );
+	}, [ panelItems, resetAllFilters, resetAll, setMenuItems, menuItemOrder ] );
 
 	// Assist ItemGroup styling when there are potentially hidden placeholder
 	// items by identifying first & last items that are toggled on for display.

package/src/tools-panel/types.ts

@@ -187,4 +187,5 @@ export type ToolsPanelMenuItemsConfig = {
 	panelItems: ToolsPanelItem[];
 	shouldReset: boolean;
 	currentMenuItems?: ToolsPanelMenuItems;
+	menuItemOrder: string[];
 };