@wordpress/components 19.2.3 → 19.4.1-next.f435e9e01b.0

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

@@ -942,6 +942,17 @@ describe( 'ToolsPanel', () => {
 	} );
 
 	describe( 'panel header icon toggle', () => {
+		const defaultControls = {
+			attributes: { value: false },
+			hasValue: jest.fn().mockImplementation( () => {
+				return !! defaultControls.attributes.value;
+			} ),
+			label: 'Default',
+			onDeselect: jest.fn(),
+			onSelect: jest.fn(),
+			isShownByDefault: true,
+		};
+
 		const optionalControls = {
 			attributes: { value: false },
 			hasValue: jest.fn().mockImplementation( () => {
@@ -953,7 +964,26 @@ describe( 'ToolsPanel', () => {
 			isShownByDefault: false,
 		};
 
-		it( 'should render appropriate icons for the dropdown menu', async () => {
+		it( 'should render appropriate icon for the dropdown menu where there are default controls', async () => {
+			render(
+				<ToolsPanel { ...defaultProps }>
+					<ToolsPanelItem { ...defaultControls }>
+						<div>Default control</div>
+					</ToolsPanelItem>
+					<ToolsPanelItem { ...optionalControls }>
+						<div>Optional control</div>
+					</ToolsPanelItem>
+				</ToolsPanel>
+			);
+
+			const optionsDisplayedIcon = screen.getByRole( 'button', {
+				name: 'View options',
+			} );
+
+			expect( optionsDisplayedIcon ).toBeInTheDocument();
+		} );
+
+		it( 'should render appropriate icons for the dropdown menu where there are no default controls', async () => {
 			render(
 				<ToolsPanel { ...defaultProps }>
 					<ToolsPanelItem { ...optionalControls }>
@@ -983,4 +1013,54 @@ describe( 'ToolsPanel', () => {
 			expect( optionsDisplayedIcon ).toBeInTheDocument();
 		} );
 	} );
+
+	describe( 'first and last panel items', () => {
+		it( 'should apply first/last classes to appropriate items', () => {
+			const { container } = render(
+				<SlotFillProvider>
+					<ToolsPanelItems>
+						<ToolsPanelItem { ...altControlProps }>
+							<div>Item 1</div>
+						</ToolsPanelItem>
+						<ToolsPanelItem { ...controlProps }>
+							<div>Item 2</div>
+						</ToolsPanelItem>
+					</ToolsPanelItems>
+					<ToolsPanelItems>
+						<ToolsPanelItem
+							{ ...altControlProps }
+							label="Item 3"
+							isShownByDefault={ true }
+						>
+							<div>Item 3</div>
+						</ToolsPanelItem>
+					</ToolsPanelItems>
+					<ToolsPanelItems>
+						<ToolsPanelItem { ...altControlProps } label="Item 4">
+							<div>Item 4</div>
+						</ToolsPanelItem>
+					</ToolsPanelItems>
+					<ToolsPanel
+						{ ...defaultProps }
+						hasInnerWrapper={ true }
+						shouldRenderPlaceholderItems={ true }
+						__experimentalFirstVisibleItemClass="first"
+						__experimentalLastVisibleItemClass="last"
+					>
+						<Slot />
+					</ToolsPanel>
+				</SlotFillProvider>
+			);
+
+			const item2 = screen.getByText( 'Item 2' );
+			const item3 = screen.getByText( 'Item 3' );
+
+			expect( screen.queryByText( 'Item 1' ) ).not.toBeInTheDocument();
+			expect( item2 ).toBeInTheDocument();
+			expect( item3 ).toBeInTheDocument();
+			expect( screen.queryByText( 'Item 4' ) ).not.toBeInTheDocument();
+
+			expect( container ).toMatchSnapshot();
+		} );
+	} );
 } );

package/src/tools-panel/tools-panel/README.md

@@ -25,6 +25,11 @@ displaying by default through the `isShownByDefault` prop. Determining whether a
 child has a value is done via the `hasValue` function provided through the
 child's props.
 
+Components that are not wrapped within a `ToolsPanelItem` are still rendered
+however they will not be represented within, or controlled by, the `ToolsPanel`
+menu. An example scenario that benefits from this could be displaying
+introduction or help text within a panel.
+
 ## Usage
 
 ```jsx
@@ -51,6 +56,10 @@ export function DimensionPanel( props ) {
 
 	return (
 		<ToolsPanel label={ __( 'Dimensions' ) } resetAll={ resetAll }>
+			<p>
+				Select dimensions or spacing related settings from the menu for
+				additional controls.
+			</p>
 			{ ! isPaddingDisabled && (
 				<ToolsPanelItem
 					hasValue={ () => hasPaddingValue( props ) }

package/src/tools-panel/tools-panel/component.tsx

@@ -1,7 +1,6 @@
 /**
  * External dependencies
  */
-// eslint-disable-next-line no-restricted-imports
 import type { Ref } from 'react';
 
 /**
@@ -24,14 +23,11 @@ const ToolsPanel = (
 		panelContext,
 		resetAllItems,
 		toggleItem,
-		className,
+		...toolsPanelProps
 	} = useToolsPanel( props );
 
-	// Props are not directly passed through to avoid exposing Grid props
-	// until agreement has been reached on how ToolsPanel layout should be
-	// handled.
 	return (
-		<Grid columns={ 2 } className={ className } ref={ forwardedRef }>
+		<Grid { ...toolsPanelProps } columns={ 2 } ref={ forwardedRef }>
 			<ToolsPanelContext.Provider value={ panelContext }>
 				<ToolsPanelHeader
 					label={ label }

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

@@ -1,7 +1,13 @@
 /**
  * WordPress dependencies
  */
-import { useEffect, useMemo, useRef, useState } from '@wordpress/element';
+import {
+	useCallback,
+	useEffect,
+	useMemo,
+	useRef,
+	useState,
+} from '@wordpress/element';
 
 /**
  * Internal dependencies
@@ -42,6 +48,10 @@ const generateMenuItems = ( {
 	return menuItems;
 };
 
+const isMenuItemTypeEmpty = (
+	obj?: ToolsPanelMenuItems[ ToolsPanelMenuItemKey ]
+) => obj && Object.keys( obj ).length === 0;
+
 export function useToolsPanel(
 	props: WordPressComponentProps< ToolsPanelProps, 'div' >
 ) {
@@ -51,6 +61,8 @@ export function useToolsPanel(
 		panelId,
 		hasInnerWrapper,
 		shouldRenderPlaceholderItems,
+		__experimentalFirstVisibleItemClass,
+		__experimentalLastVisibleItemClass,
 		...otherProps
 	} = useContextSystem( props, 'ToolsPanel' );
 
@@ -70,40 +82,46 @@ export function useToolsPanel(
 	// Allow panel items to register themselves.
 	const [ panelItems, setPanelItems ] = useState< ToolsPanelItem[] >( [] );
 
-	const registerPanelItem = ( item: ToolsPanelItem ) => {
-		setPanelItems( ( items ) => {
-			const newItems = [ ...items ];
-			// If an item with this label is already registered, remove it first.
-			// This can happen when an item is moved between the default and optional
-			// groups.
-			const existingIndex = newItems.findIndex(
-				( oldItem ) => oldItem.label === item.label
-			);
-			if ( existingIndex !== -1 ) {
-				newItems.splice( existingIndex, 1 );
-			}
-			return [ ...newItems, item ];
-		} );
-	};
+	const registerPanelItem = useCallback(
+		( item: ToolsPanelItem ) => {
+			setPanelItems( ( items ) => {
+				const newItems = [ ...items ];
+				// If an item with this label has already been registered, remove it
+				// first. This can happen when an item is moved between the default
+				// and optional groups.
+				const existingIndex = newItems.findIndex(
+					( oldItem ) => oldItem.label === item.label
+				);
+				if ( existingIndex !== -1 ) {
+					newItems.splice( existingIndex, 1 );
+				}
+				return [ ...newItems, item ];
+			} );
+		},
+		[ setPanelItems ]
+	);
 
 	// Panels need to deregister on unmount to avoid orphans in menu state.
 	// This is an issue when panel items are being injected via SlotFills.
-	const deregisterPanelItem = ( label: string ) => {
-		// When switching selections between components injecting matching
-		// controls, e.g. both panels have a "padding" control, the
-		// deregistration of the first panel doesn't occur until after the
-		// registration of the next.
-		setPanelItems( ( items ) => {
-			const newItems = [ ...items ];
-			const index = newItems.findIndex(
-				( item ) => item.label === label
-			);
-			if ( index !== -1 ) {
-				newItems.splice( index, 1 );
-			}
-			return newItems;
-		} );
-	};
+	const deregisterPanelItem = useCallback(
+		( label: string ) => {
+			// When switching selections between components injecting matching
+			// controls, e.g. both panels have a "padding" control, the
+			// deregistration of the first panel doesn't occur until after the
+			// registration of the next.
+			setPanelItems( ( items ) => {
+				const newItems = [ ...items ];
+				const index = newItems.findIndex(
+					( item ) => item.label === label
+				);
+				if ( index !== -1 ) {
+					newItems.splice( index, 1 );
+				}
+				return newItems;
+			} );
+		},
+		[ setPanelItems ]
+	);
 
 	// Manage and share display state of menu items representing child controls.
 	const [ menuItems, setMenuItems ] = useState< ToolsPanelMenuItems >( {
@@ -121,27 +139,27 @@ export function useToolsPanel(
 			} );
 			return items;
 		} );
-	}, [ panelItems ] );
+	}, [ generateMenuItems, panelItems, setMenuItems ] );
 
 	// Force a menu item to be checked.
 	// This is intended for use with default panel items. They are displayed
 	// separately to optional items and have different display states,
 	// we need to update that when their value is customized.
-	const flagItemCustomization = (
-		label: string,
-		group: ToolsPanelMenuItemKey = 'default'
-	) => {
-		setMenuItems( ( items ) => {
-			const newState = {
-				...items,
-				[ group ]: {
-					...items[ group ],
-					[ label ]: true,
-				},
-			};
-			return newState;
-		} );
-	};
+	const flagItemCustomization = useCallback(
+		( label: string, group: ToolsPanelMenuItemKey = 'default' ) => {
+			setMenuItems( ( items ) => {
+				const newState = {
+					...items,
+					[ group ]: {
+						...items[ group ],
+						[ label ]: true,
+					},
+				};
+				return newState;
+			} );
+		},
+		[ setMenuItems ]
+	);
 
 	// Whether all optional menu items are hidden or not must be tracked
 	// in order to later determine if the panel display is empty and handle
@@ -153,73 +171,79 @@ export function useToolsPanel(
 	] = useState( false );
 
 	useEffect( () => {
-		if ( menuItems.optional ) {
-			const optionalItems = Object.entries( menuItems.optional );
-			const allControlsHidden =
-				optionalItems.length > 0 &&
-				! optionalItems.some( ( [ , isSelected ] ) => isSelected );
+		if (
+			isMenuItemTypeEmpty( menuItems?.default ) &&
+			! isMenuItemTypeEmpty( menuItems?.optional )
+		) {
+			const allControlsHidden = ! Object.entries(
+				menuItems.optional
+			).some( ( [ , isSelected ] ) => isSelected );
 			setAreAllOptionalControlsHidden( allControlsHidden );
 		}
-	}, [ menuItems.optional ] );
+	}, [ menuItems, setAreAllOptionalControlsHidden ] );
 
 	const cx = useCx();
 	const classes = useMemo( () => {
-		const hasDefaultMenuItems =
-			menuItems?.default && !! Object.keys( menuItems?.default ).length;
 		const wrapperStyle =
 			hasInnerWrapper &&
 			styles.ToolsPanelWithInnerWrapper( DEFAULT_COLUMNS );
 		const emptyStyle =
-			! hasDefaultMenuItems &&
+			isMenuItemTypeEmpty( menuItems?.default ) &&
 			areAllOptionalControlsHidden &&
 			styles.ToolsPanelHiddenInnerWrapper;
 
 		return cx( styles.ToolsPanel, wrapperStyle, emptyStyle, className );
 	}, [
+		areAllOptionalControlsHidden,
 		className,
+		cx,
 		hasInnerWrapper,
 		menuItems,
-		areAllOptionalControlsHidden,
 	] );
 
 	// Toggle the checked state of a menu item which is then used to determine
 	// display of the item within the panel.
-	const toggleItem = ( label: string ) => {
-		const currentItem = panelItems.find( ( item ) => item.label === label );
-
-		if ( ! currentItem ) {
-			return;
-		}
-
-		const menuGroup = currentItem.isShownByDefault ? 'default' : 'optional';
+	const toggleItem = useCallback(
+		( label: string ) => {
+			const currentItem = panelItems.find(
+				( item ) => item.label === label
+			);
 
-		const newMenuItems = {
-			...menuItems,
-			[ menuGroup ]: {
-				...menuItems[ menuGroup ],
-				[ label ]: ! menuItems[ menuGroup ][ label ],
-			},
-		};
+			if ( ! currentItem ) {
+				return;
+			}
 
-		setMenuItems( newMenuItems );
-	};
+			const menuGroup = currentItem.isShownByDefault
+				? 'default'
+				: 'optional';
 
-	const getResetAllFilters = () => {
-		const filters: Array< () => void > = [];
+			const newMenuItems = {
+				...menuItems,
+				[ menuGroup ]: {
+					...menuItems[ menuGroup ],
+					[ label ]: ! menuItems[ menuGroup ][ label ],
+				},
+			};
 
-		panelItems.forEach( ( item ) => {
-			if ( item.resetAllFilter ) {
-				filters.push( item.resetAllFilter );
-			}
-		} );
-		return filters;
-	};
+			setMenuItems( newMenuItems );
+		},
+		[ menuItems, panelItems, setMenuItems ]
+	);
 
 	// Resets display of children and executes resetAll callback if available.
-	const resetAllItems = () => {
+	const resetAllItems = useCallback( () => {
 		if ( typeof resetAll === 'function' ) {
 			isResetting.current = true;
-			resetAll( getResetAllFilters() );
+
+			// Collect available reset filters from panel items.
+			const filters: Array< () => void > = [];
+			panelItems.forEach( ( item ) => {
+				if ( item.resetAllFilter ) {
+					filters.push( item.resetAllFilter );
+				}
+			} );
+
+			resetAll( filters );
 		}
 
 		// Turn off display of all non-default items.
@@ -228,20 +252,63 @@ export function useToolsPanel(
 			shouldReset: true,
 		} );
 		setMenuItems( resetMenuItems );
-	};
+	}, [
+		generateMenuItems,
+		isResetting.current,
+		panelItems,
+		resetAll,
+		setMenuItems,
+	] );
 
-	const panelContext = {
-		panelId,
-		menuItems,
-		registerPanelItem,
-		deregisterPanelItem,
-		flagItemCustomization,
-		areAllOptionalControlsHidden,
-		hasMenuItems: !! panelItems.length,
-		isResetting: isResetting.current,
-		shouldRenderPlaceholderItems,
+	// Assist ItemGroup styling when there are potentially hidden placeholder
+	// items by identifying first & last items that are toggled on for display.
+	const getFirstVisibleItemLabel = ( items: ToolsPanelItem[] ) => {
+		const optionalItems = menuItems.optional || {};
+		const firstItem = items.find(
+			( item ) => item.isShownByDefault || !! optionalItems[ item.label ]
+		);
+
+		return firstItem?.label;
 	};
 
+	const firstDisplayedItem = getFirstVisibleItemLabel( panelItems );
+	const lastDisplayedItem = getFirstVisibleItemLabel(
+		[ ...panelItems ].reverse()
+	);
+
+	const panelContext = useMemo(
+		() => ( {
+			areAllOptionalControlsHidden,
+			deregisterPanelItem,
+			firstDisplayedItem,
+			flagItemCustomization,
+			hasMenuItems: !! panelItems.length,
+			isResetting: isResetting.current,
+			lastDisplayedItem,
+			menuItems,
+			panelId,
+			registerPanelItem,
+			shouldRenderPlaceholderItems,
+			__experimentalFirstVisibleItemClass,
+			__experimentalLastVisibleItemClass,
+		} ),
+		[
+			areAllOptionalControlsHidden,
+			deregisterPanelItem,
+			firstDisplayedItem,
+			flagItemCustomization,
+			isResetting.current,
+			lastDisplayedItem,
+			menuItems,
+			panelId,
+			panelItems,
+			registerPanelItem,
+			shouldRenderPlaceholderItems,
+			__experimentalFirstVisibleItemClass,
+			__experimentalLastVisibleItemClass,
+		]
+	);
+
 	return {
 		...otherProps,
 		panelContext,

package/src/tools-panel/tools-panel-header/component.tsx

@@ -1,7 +1,6 @@
 /**
  * External dependencies
  */
-// eslint-disable-next-line no-restricted-imports
 import type { Ref } from 'react';
 
 /**

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

@@ -23,15 +23,15 @@ export function useToolsPanelHeader(
 	const cx = useCx();
 	const classes = useMemo( () => {
 		return cx( styles.ToolsPanelHeader, className );
-	}, [ className ] );
+	}, [ className, cx ] );
 
 	const dropdownMenuClassName = useMemo( () => {
 		return cx( styles.DropdownMenu );
-	}, [] );
+	}, [ cx ] );
 
 	const headingClassName = useMemo( () => {
 		return cx( styles.ToolsPanelHeading );
-	}, [] );
+	}, [ cx ] );
 
 	const {
 		menuItems,

package/src/tools-panel/tools-panel-item/component.tsx

@@ -1,7 +1,6 @@
 /**
  * External dependencies
  */
-// eslint-disable-next-line no-restricted-imports
 import type { Ref } from 'react';
 
 /**

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

@@ -36,6 +36,10 @@ export function useToolsPanelItem(
 		flagItemCustomization,
 		isResetting,
 		shouldRenderPlaceholderItems: shouldRenderPlaceholder,
+		firstDisplayedItem,
+		lastDisplayedItem,
+		__experimentalFirstVisibleItemClass,
+		__experimentalLastVisibleItemClass,
 	} = useToolsPanelContext();
 
 	const hasValueCallback = useCallback( hasValue, [ panelId ] );
@@ -129,8 +133,27 @@ export function useToolsPanelItem(
 			shouldRenderPlaceholder &&
 			! isShown &&
 			styles.ToolsPanelItemPlaceholder;
-		return cx( styles.ToolsPanelItem, placeholderStyle, className );
-	}, [ isShown, shouldRenderPlaceholder, className ] );
+		const firstItemStyle =
+			firstDisplayedItem === label && __experimentalFirstVisibleItemClass;
+		const lastItemStyle =
+			lastDisplayedItem === label && __experimentalLastVisibleItemClass;
+		return cx(
+			styles.ToolsPanelItem,
+			placeholderStyle,
+			className,
+			firstItemStyle,
+			lastItemStyle
+		);
+	}, [
+		isShown,
+		shouldRenderPlaceholder,
+		className,
+		cx,
+		firstDisplayedItem,
+		lastDisplayedItem,
+		__experimentalFirstVisibleItemClass,
+		__experimentalLastVisibleItemClass,
+	] );
 
 	return {
 		...otherProps,

package/src/tools-panel/types.ts

@@ -1,7 +1,6 @@
 /**
  * External dependencies
  */
-// eslint-disable-next-line no-restricted-imports
 import type { ReactNode } from 'react';
 
 type ResetAllFilter = () => void;
@@ -38,6 +37,16 @@ export type ToolsPanelProps = {
 	 * placeholder content instead of null when they are toggled off and hidden.
 	 */
 	shouldRenderPlaceholderItems: boolean;
+	/**
+	 * Experimental prop allowing for a custom CSS class to be applied to the
+	 * first visible `ToolsPanelItem` within the `ToolsPanel`.
+	 */
+	__experimentalFirstVisibleItemClass?: string;
+	/**
+	 * Experimental prop allowing for a custom CSS class to be applied to the
+	 * last visible `ToolsPanelItem` within the `ToolsPanel`.
+	 */
+	__experimentalLastVisibleItemClass?: string;
 };
 
 export type ToolsPanelHeaderProps = {
@@ -131,6 +140,10 @@ export type ToolsPanelContext = {
 	isResetting: boolean;
 	shouldRenderPlaceholderItems: boolean;
 	areAllOptionalControlsHidden: boolean;
+	firstDisplayedItem?: string;
+	lastDisplayedItem?: string;
+	__experimentalFirstVisibleItemClass?: string;
+	__experimentalLastVisibleItemClass?: string;
 };
 
 export type ToolsPanelControlsGroupProps = {

package/src/tooltip/stories/index.js

@@ -18,7 +18,7 @@ export default {
 	title: 'Components/ToolTip',
 	component: Tooltip,
 	parameters: {
-		knobs: { disabled: false },
+		knobs: { disable: false },
 	},
 };
 

package/src/tooltip/test/index.native.js

@@ -54,7 +54,9 @@ it( 'displays the message', () => {
 	expect( screen.getByText( 'A helpful message' ) ).toBeTruthy();
 } );
 
-it( 'dismisses when the screen is tapped', () => {
+// Skipped until `pointerEvents: 'box-none'` no longer erroneously prevents
+// triggering `onTouch*` on the element: https://git.io/JSHZt
+it.skip( 'dismisses when the screen is tapped', () => {
 	const screen = render(
 		<TooltipSlot>
 			<Tooltip visible={ true } text="A helpful message">