@wordpress/components 18.0.0 → 19.0.3

package/src/tools-panel/styles.ts

@@ -6,52 +6,89 @@ import { css } from '@emotion/react';
 /**
  * Internal dependencies
  */
+import {
+	StyledField as BaseControlField,
+	Wrapper as BaseControlWrapper,
+} from '../base-control/styles/base-control-styles';
 import { COLORS, CONFIG } from '../utils';
 import { space } from '../ui/utils/space';
 
+const toolsPanelGrid = {
+	spacing: css`
+		column-gap: ${ space( 4 ) };
+		row-gap: ${ space( 6 ) };
+	`,
+	item: {
+		fullWidth: css`
+			grid-column: 1 / -1;
+		`,
+	},
+};
+
 export const ToolsPanel = css`
+	${ toolsPanelGrid.spacing };
+
 	border-top: ${ CONFIG.borderWidth } solid ${ COLORS.gray[ 200 ] };
-	column-gap: ${ space( 4 ) };
-	display: grid;
-	grid-template-columns: 1fr 1fr;
 	margin-top: -1px;
 	padding: ${ space( 4 ) };
-	row-gap: ${ space( 6 ) };
 `;
 
-export const ToolsPanelHeader = css`
-	align-items: center;
-	display: flex;
-	font-size: inherit;
-	font-weight: 500;
-	grid-column: span 2;
-	justify-content: space-between;
-	line-height: normal;
+/**
+ * Items injected into a ToolsPanel via a virtual bubbling slot will require
+ * an inner dom element to be injected. The following rule allows for the
+ * CSS grid display to be re-established.
+ */
 
-	.components-tools-panel & {
-		margin: 0;
+export const ToolsPanelWithInnerWrapper = ( columns: number ) => {
+	return css`
+		> div:not( :first-of-type ) {
+			display: grid;
+			grid-template-columns: ${ `repeat( ${ columns }, 1fr )` };
+			${ toolsPanelGrid.spacing }
+			${ toolsPanelGrid.item.fullWidth }
+		}
+	`;
+};
+
+export const ToolsPanelHiddenInnerWrapper = css`
+	> div:not( :first-of-type ) {
+		display: none;
 	}
+`;
 
+export const ToolsPanelHeader = css`
+	${ toolsPanelGrid.item.fullWidth }
+	gap: ${ space( 2 ) };
+
+	/**
+	 * The targeting of dropdown menu component classes here is a temporary
+	 * measure only.
+	 *
+	 * The following styles should be replaced once the DropdownMenu has been
+	 * refactored and can be targeted via component interpolation.
+	 */
 	.components-dropdown-menu {
-		margin-top: ${ space( -1 ) };
-		margin-bottom: ${ space( -1 ) };
-		height: ${ space( 6 ) };
+		margin: ${ space( -1 ) } 0;
 	}
-
-	.components-dropdown-menu__toggle {
+	&&&& .components-dropdown-menu__toggle {
 		padding: 0;
-		height: ${ space( 6 ) };
 		min-width: ${ space( 6 ) };
-		width: ${ space( 6 ) };
 	}
 `;
 
-export const ToolsPanelItem = css`
-	grid-column: span 2;
+export const ToolsPanelHeading = css`
+	font-size: inherit;
+	font-weight: 500;
+	line-height: normal;
 
-	&.single-column {
-		grid-column: span 1;
+	/* Required to meet specificity requirements to ensure zero margin */
+	&& {
+		margin: 0;
 	}
+`;
+
+export const ToolsPanelItem = css`
+	${ toolsPanelGrid.item.fullWidth }
 
 	/* Clear spacing in and around controls added as panel items. */
 	/* Remove when they can be addressed via context system. */
@@ -61,6 +98,19 @@ export const ToolsPanelItem = css`
 		margin-bottom: 0;
 		max-width: 100%;
 	}
+
+	/* Remove BaseControl components margins and leave spacing to grid layout */
+	&& ${ BaseControlWrapper } {
+		margin-bottom: 0;
+
+		${ BaseControlField } {
+			margin-bottom: 0;
+		}
+	}
+`;
+
+export const ToolsPanelItemPlaceholder = css`
+	display: none;
 `;
 
 export const DropdownMenu = css`

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

@@ -6,8 +6,10 @@ import { render, screen, fireEvent } from '@testing-library/react';
 /**
  * Internal dependencies
  */
-import { ToolsPanel, ToolsPanelItem } from '../';
+import { ToolsPanel, ToolsPanelContext, ToolsPanelItem } from '../';
+import { createSlotFill, Provider as SlotFillProvider } from '../../slot-fill';
 
+const { Fill: ToolsPanelItems, Slot } = createSlotFill( 'ToolsPanelSlot' );
 const resetAll = jest.fn();
 
 // Default props for the tools panel.
@@ -98,7 +100,8 @@ const renderGroupedItemsInPanel = () => {
 // to test panel item registration and rendering.
 const WrappedItem = ( { text, ...props } ) => {
 	return (
-		<div className="wrapped-panel-item-container">
+		<div>
+			<span>Wrapper</span>
 			<ToolsPanelItem { ...props }>
 				<div>{ text }</div>
 			</ToolsPanelItem>
@@ -116,10 +119,6 @@ const renderWrappedItemInPanel = () => {
 	);
 };
 
-// Attempts to find the tools panel via its CSS class.
-const getPanel = ( container ) =>
-	container.querySelector( '.components-tools-panel' );
-
 // Renders a default tools panel including children that are
 // not to be represented within the panel's menu.
 const renderPanel = () => {
@@ -137,10 +136,26 @@ const renderPanel = () => {
 	);
 };
 
-// Helper to find the menu button and simulate a user click.
+/**
+ * Retrieves the panel's dropdown menu toggle button.
+ *
+ * @return {HTMLElement} The menu button.
+ */
+const getMenuButton = () => {
+	return screen.getByRole( 'button', {
+		name: /view([\w\s]+)options/i,
+	} );
+};
+
+/**
+ * Helper to find the menu button and simulate a user click.
+ *
+ * @return {HTMLElement} The menuButton.
+ */
 const openDropdownMenu = () => {
-	const menuButton = screen.getByLabelText( defaultProps.label );
+	const menuButton = getMenuButton();
 	fireEvent.click( menuButton );
+	return menuButton;
 };
 
 // Opens dropdown then selects the menu item by label before simulating a click.
@@ -151,19 +166,23 @@ const selectMenuItem = async ( label ) => {
 };
 
 describe( 'ToolsPanel', () => {
+	afterEach( () => {
+		controlProps.attributes.value = true;
+	} );
+
 	describe( 'basic rendering', () => {
 		it( 'should render panel', () => {
-			const { container } = renderPanel();
-
-			expect( getPanel( container ) ).toBeInTheDocument();
-		} );
-
-		it( 'should render non panel item child', () => {
 			renderPanel();
 
-			const nonPanelItem = screen.queryByText( 'Visible' );
+			const menuButton = getMenuButton();
+			const label = screen.getByText( defaultProps.label );
+			const control = screen.getByText( 'Example control' );
+			const nonToolsPanelItem = screen.getByText( 'Visible' );
 
-			expect( nonPanelItem ).toBeInTheDocument();
+			expect( menuButton ).toBeInTheDocument();
+			expect( label ).toBeInTheDocument();
+			expect( control ).toBeInTheDocument();
+			expect( nonToolsPanelItem ).toBeInTheDocument();
 		} );
 
 		it( 'should render panel item flagged as default control even without value', () => {
@@ -206,7 +225,7 @@ describe( 'ToolsPanel', () => {
 		it( 'should render panel menu when at least one panel item', () => {
 			renderPanel();
 
-			const menuButton = screen.getByLabelText( defaultProps.label );
+			const menuButton = openDropdownMenu();
 			expect( menuButton ).toBeInTheDocument();
 		} );
 
@@ -282,13 +301,13 @@ describe( 'ToolsPanel', () => {
 			expect( control ).toBeInTheDocument();
 
 			await selectMenuItem( controlProps.label );
-			const resetControl = screen.queryByText( 'Default control' );
+			const resetControl = screen.getByText( 'Default control' );
 
 			expect( resetControl ).toBeInTheDocument();
 		} );
 
 		it( 'should render appropriate menu groups', async () => {
-			const { container } = render(
+			render(
 				<ToolsPanel { ...defaultProps }>
 					<ToolsPanelItem
 						{ ...controlProps }
@@ -303,19 +322,37 @@ describe( 'ToolsPanel', () => {
 			);
 			openDropdownMenu();
 
-			const menuGroups = container.querySelectorAll(
-				'.components-menu-group'
-			);
+			const menuGroups = screen.getAllByRole( 'group' );
 
 			// Groups should be: default controls, optional controls & reset all.
 			expect( menuGroups.length ).toEqual( 3 );
 		} );
+
+		it( 'should not render contents of items when in placeholder state', () => {
+			render(
+				<ToolsPanel
+					{ ...defaultProps }
+					shouldRenderPlaceholderItems={ true }
+				>
+					<ToolsPanelItem { ...altControlProps }>
+						<div>Optional control</div>
+					</ToolsPanelItem>
+				</ToolsPanel>
+			);
+
+			const optionalItem = screen.queryByText( 'Optional control' );
+
+			// When rendered as a placeholder a ToolsPanelItem will just omit
+			// all the item's children. So the container element will still be
+			// there holding its position but the inner text etc should not be
+			// there.
+			expect( optionalItem ).not.toBeInTheDocument();
+		} );
 	} );
 
 	describe( 'callbacks on menu item selection', () => {
 		beforeEach( () => {
 			jest.clearAllMocks();
-			controlProps.attributes.value = true;
 		} );
 
 		it( 'should call onDeselect callback when menu item is toggled off', async () => {
@@ -378,26 +415,30 @@ describe( 'ToolsPanel', () => {
 			openDropdownMenu();
 
 			const defaultItem = screen.getByText( 'Nested Control 1' );
-			const defaultMenuItem = defaultItem.parentNode;
+			const defaultMenuItem = screen.getByRole( 'menuitemcheckbox', {
+				name: 'Reset Nested Control 1',
+				checked: true,
+			} );
 
 			const altItem = screen.getByText( 'Nested Control 2' );
-			const altMenuItem = altItem.parentNode;
+			const altMenuItem = screen.getByRole( 'menuitemcheckbox', {
+				name: 'Show Nested Control 2',
+				checked: false,
+			} );
 
 			expect( defaultItem ).toBeInTheDocument();
-			expect( defaultMenuItem ).toHaveAttribute( 'aria-checked', 'true' );
+			expect( defaultMenuItem ).toBeInTheDocument();
 
 			expect( altItem ).toBeInTheDocument();
-			expect( altMenuItem ).toHaveAttribute( 'aria-checked', 'false' );
+			expect( altMenuItem ).toBeInTheDocument();
 		} );
 	} );
 
 	describe( 'wrapped panel items within custom components', () => {
 		it( 'should render wrapped items correctly', () => {
-			const { container } = renderWrappedItemInPanel();
+			renderWrappedItemInPanel();
 
-			const wrappers = container.querySelectorAll(
-				'.wrapped-panel-item-container'
-			);
+			const wrappers = screen.getAllByText( 'Wrapper' );
 			const defaultItem = screen.getByText( 'Wrapped 1' );
 			const altItem = screen.queryByText( 'Wrapped 2' );
 
@@ -413,16 +454,182 @@ describe( 'ToolsPanel', () => {
 			openDropdownMenu();
 
 			const defaultItem = screen.getByText( 'Nested Control 1' );
-			const defaultMenuItem = defaultItem.parentNode;
+			const defaultMenuItem = screen.getByRole( 'menuitemcheckbox', {
+				name: 'Reset Nested Control 1',
+				checked: true,
+			} );
 
 			const altItem = screen.getByText( 'Nested Control 2' );
-			const altMenuItem = altItem.parentNode;
+			const altMenuItem = screen.getByRole( 'menuitemcheckbox', {
+				name: 'Show Nested Control 2',
+				checked: false,
+			} );
 
 			expect( defaultItem ).toBeInTheDocument();
-			expect( defaultMenuItem ).toHaveAttribute( 'aria-checked', 'true' );
+			expect( defaultMenuItem ).toBeInTheDocument();
 
 			expect( altItem ).toBeInTheDocument();
-			expect( altMenuItem ).toHaveAttribute( 'aria-checked', 'false' );
+			expect( altMenuItem ).toBeInTheDocument();
+		} );
+	} );
+
+	describe( 'rendering via SlotFills', () => {
+		beforeEach( () => {
+			jest.clearAllMocks();
+		} );
+
+		it( 'should maintain visual order of controls when toggled on and off', async () => {
+			// Multiple fills are added to better simulate panel items being
+			// injected from different locations.
+			render(
+				<SlotFillProvider>
+					<ToolsPanelItems>
+						<ToolsPanelItem { ...altControlProps }>
+							<div>Item 1</div>
+						</ToolsPanelItem>
+					</ToolsPanelItems>
+					<ToolsPanelItems>
+						<ToolsPanelItem { ...controlProps }>
+							<div>Item 2</div>
+						</ToolsPanelItem>
+					</ToolsPanelItems>
+					<ToolsPanel { ...defaultProps }>
+						<Slot />
+					</ToolsPanel>
+				</SlotFillProvider>
+			);
+
+			// Only the second item should be shown initially as it has a value.
+			const firstItem = screen.queryByText( 'Item 1' );
+			const secondItem = screen.getByText( 'Item 2' );
+
+			expect( firstItem ).not.toBeInTheDocument();
+			expect( secondItem ).toBeInTheDocument();
+
+			// Toggle on the first item.
+			await selectMenuItem( altControlProps.label );
+
+			// The order of items should be as per their original source order.
+			let items = screen.getAllByText( /Item [1-2]/ );
+
+			expect( items ).toHaveLength( 2 );
+			expect( items[ 0 ] ).toHaveTextContent( 'Item 1' );
+			expect( items[ 1 ] ).toHaveTextContent( 'Item 2' );
+
+			// Then toggle off both items.
+			await selectMenuItem( controlProps.label );
+			await selectMenuItem( altControlProps.label );
+
+			// Toggle on controls again and ensure order remains.
+			await selectMenuItem( controlProps.label );
+			await selectMenuItem( altControlProps.label );
+
+			items = screen.getAllByText( /Item [1-2]/ );
+
+			expect( items ).toHaveLength( 2 );
+			expect( items[ 0 ] ).toHaveTextContent( 'Item 1' );
+			expect( items[ 1 ] ).toHaveTextContent( 'Item 2' );
+		} );
+
+		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
+			// so it could prevent erroneous registrations and calls to
+			// `onDeselect` etc.
+			//
+			// See: https://github.com/WordPress/gutenberg/pull/35375
+			//
+			// This test simulates this issue by rendering an item within a
+			// contrived `ToolsPanelContext` to reflect the changes the panel
+			// item needs to protect against.
+
+			const noop = () => undefined;
+			const context = {
+				panelId: '1234',
+				menuItems: {
+					default: {},
+					optional: { [ altControlProps.label ]: true },
+				},
+				hasMenuItems: false,
+				isResetting: false,
+				shouldRenderPlaceholderItems: false,
+				registerPanelItem: noop,
+				deregisterPanelItem: noop,
+				flagItemCustomization: noop,
+				areAllOptionalControlsHidden: true,
+			};
+
+			// This initial render gives the tools panel item a chance to
+			// set its internal state to reflect it was previously selected.
+			// This later forms part of the condition used to determine if an
+			// item is being deselected and thus call the onDeselect callback.
+			const { rerender } = render(
+				<ToolsPanelContext.Provider value={ context }>
+					<ToolsPanelItem { ...altControlProps } panelId="1234">
+						<div>Item</div>
+					</ToolsPanelItem>
+				</ToolsPanelContext.Provider>
+			);
+
+			// Simulate a change in panel separate to the rendering of fills.
+			// e.g. a switch of block selection.
+			context.panelId = '4321';
+			context.menuItems.optional[ altControlProps.label ] = false;
+
+			// Rerender the panel item and ensure that it skips any check
+			// for deselection given it still belongs to a different panelId.
+			rerender(
+				<ToolsPanelContext.Provider value={ context }>
+					<ToolsPanelItem { ...altControlProps } panelId="1234">
+						<div>Item</div>
+					</ToolsPanelItem>
+				</ToolsPanelContext.Provider>
+			);
+
+			expect( altControlProps.onDeselect ).not.toHaveBeenCalled();
+		} );
+	} );
+
+	describe( 'panel header icon toggle', () => {
+		const optionalControls = {
+			attributes: { value: false },
+			hasValue: jest.fn().mockImplementation( () => {
+				return !! optionalControls.attributes.value;
+			} ),
+			label: 'Optional',
+			onDeselect: jest.fn(),
+			onSelect: jest.fn(),
+			isShownByDefault: false,
+		};
+
+		it( 'should render appropriate icons for the dropdown menu', async () => {
+			render(
+				<ToolsPanel { ...defaultProps }>
+					<ToolsPanelItem { ...optionalControls }>
+						<div>Optional control</div>
+					</ToolsPanelItem>
+				</ToolsPanel>
+			);
+
+			// There are unactivated, optional menu items in the Tools Panel dropdown.
+			const optionsHiddenIcon = screen.getByRole( 'button', {
+				name: 'View and add options',
+			} );
+
+			expect( optionsHiddenIcon ).toBeInTheDocument();
+
+			await selectMenuItem( optionalControls.label );
+
+			// There are now NO unactivated, optional menu items in the Tools Panel dropdown.
+			expect(
+				screen.queryByRole( 'button', { name: 'View and add options' } )
+			).not.toBeInTheDocument();
+
+			const optionsDisplayedIcon = screen.getByRole( 'button', {
+				name: 'View options',
+			} );
+
+			expect( optionsDisplayedIcon ).toBeInTheDocument();
 		} );
 	} );
 } );

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

@@ -67,6 +67,13 @@ export function DimensionPanel( props ) {
 
 ## Props
 
+### `hasInnerWrapper`: `boolean`
+
+Flags that the items in this ToolsPanel will be contained within an inner
+wrapper element allowing the panel to lay them out accordingly.
+
+- Required: No
+
 ### `label`: `string`
 
 Text to be displayed within the panel's header and as the `aria-label` for the
@@ -88,3 +95,10 @@ A function to call when the `Reset all` menu option is selected. This is passed
 through to the panel's header component.
 
 - Required: Yes
+
+### `shouldRenderPlaceholderItems`: `boolean`
+
+Advises the `ToolsPanel` that all of its `ToolsPanelItem` children should render
+placeholder content (instead of `null`) when they are toggled off and hidden.
+
+- Required: No

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

@@ -10,7 +10,7 @@ import type { Ref } from 'react';
 import ToolsPanelHeader from '../tools-panel-header';
 import { ToolsPanelContext } from '../context';
 import { useToolsPanel } from './hook';
-import { View } from '../../view';
+import { Grid } from '../../grid';
 import { contextConnect, WordPressComponentProps } from '../../ui/context';
 import type { ToolsPanelProps } from '../types';
 
@@ -24,11 +24,14 @@ const ToolsPanel = (
 		panelContext,
 		resetAllItems,
 		toggleItem,
-		...toolsPanelProps
+		className,
 	} = 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 (
-		<View { ...toolsPanelProps } ref={ forwardedRef }>
+		<Grid columns={ 2 } className={ className } ref={ forwardedRef }>
 			<ToolsPanelContext.Provider value={ panelContext }>
 				<ToolsPanelHeader
 					label={ label }
@@ -37,7 +40,7 @@ const ToolsPanel = (
 				/>
 				{ children }
 			</ToolsPanelContext.Provider>
-		</View>
+		</Grid>
 	);
 };
 

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

@@ -17,6 +17,8 @@ import type {
 	ToolsPanelProps,
 } from '../types';
 
+const DEFAULT_COLUMNS = 2;
+
 const generateMenuItems = ( {
 	panelItems,
 	shouldReset,
@@ -34,15 +36,14 @@ const generateMenuItems = ( {
 export function useToolsPanel(
 	props: WordPressComponentProps< ToolsPanelProps, 'div' >
 ) {
-	const { className, resetAll, panelId, ...otherProps } = useContextSystem(
-		props,
-		'ToolsPanel'
-	);
-
-	const cx = useCx();
-	const classes = useMemo( () => {
-		return cx( styles.ToolsPanel, className );
-	}, [ className ] );
+	const {
+		className,
+		resetAll,
+		panelId,
+		hasInnerWrapper,
+		shouldRenderPlaceholderItems,
+		...otherProps
+	} = useContextSystem( props, 'ToolsPanel' );
 
 	const isResetting = useRef( false );
 	const wasResetting = isResetting.current;
@@ -110,6 +111,45 @@ export function useToolsPanel(
 		} );
 	};
 
+	// 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
+	// conditional display of a plus icon to indicate the presence of further
+	// menu items.
+	const [
+		areAllOptionalControlsHidden,
+		setAreAllOptionalControlsHidden,
+	] = useState( false );
+
+	useEffect( () => {
+		if ( menuItems.optional ) {
+			const optionalItems = Object.entries( menuItems.optional );
+			const allControlsHidden =
+				optionalItems.length > 0 &&
+				! optionalItems.some( ( [ , isSelected ] ) => isSelected );
+			setAreAllOptionalControlsHidden( allControlsHidden );
+		}
+	}, [ menuItems.optional ] );
+
+	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 &&
+			areAllOptionalControlsHidden &&
+			styles.ToolsPanelHiddenInnerWrapper;
+
+		return cx( styles.ToolsPanel, wrapperStyle, emptyStyle, className );
+	}, [
+		className,
+		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 ) => {
@@ -164,8 +204,10 @@ export function useToolsPanel(
 		registerPanelItem,
 		deregisterPanelItem,
 		flagItemCustomization,
+		areAllOptionalControlsHidden,
 		hasMenuItems: !! panelItems.length,
 		isResetting: isResetting.current,
+		shouldRenderPlaceholderItems,
 	};
 
 	return {