@wordpress/components 19.1.2 → 19.2.1-next.33ec3857e2.0

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

@@ -7,6 +7,10 @@ import styled from '@emotion/styled';
  * WordPress dependencies
  */
 import { useState } from '@wordpress/element';
+import {
+	__experimentalToggleGroupControl as ToggleGroupControl,
+	__experimentalToggleGroupControlOption as ToggleGroupControlOption,
+} from '@wordpress/components';
 
 /**
  * Internal dependencies
@@ -81,6 +85,56 @@ export const _default = () => {
 	);
 };
 
+export const WithNonToolsPanelItems = () => {
+	const [ height, setHeight ] = useState();
+	const [ width, setWidth ] = useState();
+
+	const resetAll = () => {
+		setHeight( undefined );
+		setWidth( undefined );
+	};
+
+	return (
+		<PanelWrapperView>
+			<Panel>
+				<ToolsPanel
+					label="ToolsPanel (with non-menu items)"
+					resetAll={ resetAll }
+				>
+					<IntroText>
+						This text illustrates not all items must be wrapped in a
+						ToolsPanelItem and represented in the panel menu.
+					</IntroText>
+					<SingleColumnItem
+						hasValue={ () => !! width }
+						label="Width"
+						onDeselect={ () => setWidth( undefined ) }
+						isShownByDefault={ true }
+					>
+						<UnitControl
+							label="Width"
+							value={ width }
+							onChange={ ( next ) => setWidth( next ) }
+						/>
+					</SingleColumnItem>
+					<SingleColumnItem
+						hasValue={ () => !! height }
+						label="Height"
+						onDeselect={ () => setHeight( undefined ) }
+						isShownByDefault={ true }
+					>
+						<UnitControl
+							label="Height"
+							value={ height }
+							onChange={ ( next ) => setHeight( next ) }
+						/>
+					</SingleColumnItem>
+				</ToolsPanel>
+			</Panel>
+		</PanelWrapperView>
+	);
+};
+
 export const WithOptionalItemsPlusIcon = () => {
 	const [ height, setHeight ] = useState();
 	const [ width, setWidth ] = useState();
@@ -215,6 +269,185 @@ export const WithSlotFillItems = () => {
 	);
 };
 
+export const WithConditionalDefaultControl = () => {
+	const [ attributes, setAttributes ] = useState( {} );
+	const { height, scale } = attributes;
+
+	const resetAll = ( resetFilters = [] ) => {
+		let newAttributes = {};
+
+		resetFilters.forEach( ( resetFilter ) => {
+			newAttributes = {
+				...newAttributes,
+				...resetFilter( newAttributes ),
+			};
+		} );
+
+		setAttributes( newAttributes );
+	};
+
+	const updateAttribute = ( name, value ) => {
+		setAttributes( {
+			...attributes,
+			[ name ]: value,
+		} );
+	};
+
+	return (
+		<SlotFillProvider>
+			<ToolsPanelItems>
+				<SingleColumnItem
+					hasValue={ () => !! height }
+					label="Injected Height"
+					onDeselect={ () => updateAttribute( 'height', undefined ) }
+					resetAllFilter={ () => ( { height: undefined } ) }
+					panelId={ panelId }
+					isShownByDefault={ true }
+				>
+					<UnitControl
+						label="Injected Height"
+						value={ height }
+						onChange={ ( next ) =>
+							updateAttribute( 'height', next )
+						}
+					/>
+				</SingleColumnItem>
+				<ToolsPanelItem
+					hasValue={ () => !! scale }
+					label="Scale"
+					onDeselect={ () => updateAttribute( 'scale', undefined ) }
+					resetAllFilter={ () => ( { scale: undefined } ) }
+					panelId={ panelId }
+					isShownByDefault={ !! height }
+				>
+					<ToggleGroupControl
+						label="Scale"
+						value={ scale }
+						onChange={ ( next ) =>
+							updateAttribute( 'scale', next )
+						}
+						isBlock
+					>
+						<ToggleGroupControlOption value="cover" label="Cover" />
+						<ToggleGroupControlOption
+							value="contain"
+							label="Contain"
+						/>
+						<ToggleGroupControlOption value="fill" label="Fill" />
+					</ToggleGroupControl>
+				</ToolsPanelItem>
+			</ToolsPanelItems>
+			<PanelWrapperView>
+				<Panel>
+					<ToolsPanel
+						label="Tools Panel With Conditional Default via SlotFill"
+						resetAll={ resetAll }
+						panelId={ panelId }
+					>
+						<Slot />
+					</ToolsPanel>
+				</Panel>
+			</PanelWrapperView>
+		</SlotFillProvider>
+	);
+};
+
+export const WithConditionallyRenderedControl = () => {
+	const [ attributes, setAttributes ] = useState( {} );
+	const { height, scale } = attributes;
+
+	const resetAll = ( resetFilters = [] ) => {
+		let newAttributes = {};
+
+		resetFilters.forEach( ( resetFilter ) => {
+			newAttributes = {
+				...newAttributes,
+				...resetFilter( newAttributes ),
+			};
+		} );
+
+		setAttributes( newAttributes );
+	};
+
+	const updateAttribute = ( name, value ) => {
+		setAttributes( {
+			...attributes,
+			[ name ]: value,
+		} );
+	};
+
+	return (
+		<SlotFillProvider>
+			<ToolsPanelItems>
+				<SingleColumnItem
+					hasValue={ () => !! height }
+					label="Injected Height"
+					onDeselect={ () => {
+						updateAttribute( 'scale', undefined );
+						updateAttribute( 'height', undefined );
+					} }
+					resetAllFilter={ () => ( { height: undefined } ) }
+					panelId={ panelId }
+					isShownByDefault={ true }
+				>
+					<UnitControl
+						label="Injected Height"
+						value={ height }
+						onChange={ ( next ) =>
+							updateAttribute( 'height', next )
+						}
+					/>
+				</SingleColumnItem>
+				{ !! height && (
+					<ToolsPanelItem
+						hasValue={ () => !! scale }
+						label="Scale"
+						onDeselect={ () =>
+							updateAttribute( 'scale', undefined )
+						}
+						resetAllFilter={ () => ( { scale: undefined } ) }
+						panelId={ panelId }
+						isShownByDefault={ true }
+					>
+						<ToggleGroupControl
+							label="Scale"
+							value={ scale }
+							onChange={ ( next ) =>
+								updateAttribute( 'scale', next )
+							}
+							isBlock
+						>
+							<ToggleGroupControlOption
+								value="cover"
+								label="Cover"
+							/>
+							<ToggleGroupControlOption
+								value="contain"
+								label="Contain"
+							/>
+							<ToggleGroupControlOption
+								value="fill"
+								label="Fill"
+							/>
+						</ToggleGroupControl>
+					</ToolsPanelItem>
+				) }
+			</ToolsPanelItems>
+			<PanelWrapperView>
+				<Panel>
+					<ToolsPanel
+						label="Tools Panel With Conditionally Rendered Item via SlotFill"
+						resetAll={ resetAll }
+						panelId={ panelId }
+					>
+						<Slot />
+					</ToolsPanel>
+				</Panel>
+			</PanelWrapperView>
+		</SlotFillProvider>
+	);
+};
+
 export { TypographyPanel } from './typography-panel';
 
 const PanelWrapperView = styled.div`
@@ -229,3 +462,7 @@ const PanelWrapperView = styled.div`
 const SingleColumnItem = styled( ToolsPanelItem )`
 	grid-column: span 1;
 `;
+
+const IntroText = styled.div`
+	grid-column: span 2;
+`;

package/src/tools-panel/styles.ts

@@ -8,8 +8,11 @@ import { css } from '@emotion/react';
  */
 import {
 	StyledField as BaseControlField,
+	StyledHelp as BaseControlHelp,
+	StyledLabel as BaseControlLabel,
 	Wrapper as BaseControlWrapper,
 } from '../base-control/styles/base-control-styles';
+import { LabelWrapper } from '../input-control/styles/input-control-styles';
 import { COLORS, CONFIG } from '../utils';
 import { space } from '../ui/utils/space';
 
@@ -69,6 +72,7 @@ export const ToolsPanelHeader = css`
 	 */
 	.components-dropdown-menu {
 		margin: ${ space( -1 ) } 0;
+		line-height: 0;
 	}
 	&&&& .components-dropdown-menu__toggle {
 		padding: 0;
@@ -103,10 +107,46 @@ export const ToolsPanelItem = css`
 	&& ${ BaseControlWrapper } {
 		margin-bottom: 0;
 
-		${ BaseControlField } {
+		/**
+		 * To maintain proper spacing within a base control, the field's bottom
+		 * margin should only be removed when there is no help text included and
+		 * it is therefore the last-child.
+		 */
+		${ BaseControlField }:last-child {
 			margin-bottom: 0;
 		}
 	}
+
+	${ BaseControlHelp } {
+		margin-bottom: 0;
+	}
+
+	/**
+	 * Standardize InputControl and BaseControl labels with other labels when
+	 * inside ToolsPanel.
+	 *
+	 * This is a temporary fix until the different control components have their
+	 * labels normalized.
+	 */
+	&& ${ LabelWrapper } {
+		label {
+			margin-bottom: ${ space( 2 ) };
+			padding-bottom: 0;
+			line-height: 1.4em;
+		}
+	}
+
+	/**
+	 * The targeting of .components-custom-select-control__label here is a
+	 * temporary measure only.
+	 *
+	 * It should be replaced once CustomSelectControl component has been
+	 * refactored and can be targeted via component interpolation.
+	 */
+	.components-custom-select-control__label,
+	${ BaseControlLabel } {
+		line-height: 1.4em;
+	}
 `;
 
 export const ToolsPanelItemPlaceholder = css`

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

@@ -1,7 +1,7 @@
 /**
  * External dependencies
  */
-import { render, screen, fireEvent } from '@testing-library/react';
+import { render, screen, fireEvent, within } from '@testing-library/react';
 
 /**
  * Internal dependencies
@@ -168,6 +168,7 @@ const selectMenuItem = async ( label ) => {
 describe( 'ToolsPanel', () => {
 	afterEach( () => {
 		controlProps.attributes.value = true;
+		altControlProps.attributes.value = false;
 	} );
 
 	describe( 'basic rendering', () => {
@@ -348,6 +349,238 @@ describe( 'ToolsPanel', () => {
 			// there.
 			expect( optionalItem ).not.toBeInTheDocument();
 		} );
+
+		it( 'should render default controls with conditional isShownByDefault', async () => {
+			const linkedControlProps = {
+				attributes: { value: false },
+				hasValue: jest.fn().mockImplementation( () => {
+					return !! linkedControlProps.attributes.value;
+				} ),
+				label: 'Linked',
+				onDeselect: jest.fn(),
+				onSelect: jest.fn(),
+			};
+
+			const TestPanel = () => (
+				<ToolsPanel { ...defaultProps }>
+					<ToolsPanelItem
+						{ ...altControlProps }
+						isShownByDefault={ true }
+					>
+						<div>Default control</div>
+					</ToolsPanelItem>
+					<ToolsPanelItem
+						{ ...linkedControlProps }
+						isShownByDefault={ !! altControlProps.attributes.value }
+					>
+						<div>Linked control</div>
+					</ToolsPanelItem>
+				</ToolsPanel>
+			);
+
+			const { rerender } = render( <TestPanel /> );
+
+			// The linked control should start out as an optional control and is
+			// not rendered because it does not have a value.
+			let linkedItem = screen.queryByText( 'Linked control' );
+			expect( linkedItem ).not.toBeInTheDocument();
+
+			openDropdownMenu();
+
+			// The linked control should initially appear in the optional controls
+			// menu group. There should be three menu groups: default controls,
+			// optional controls, and the group to reset all options.
+			let menuGroups = screen.getAllByRole( 'group' );
+			expect( menuGroups.length ).toEqual( 3 );
+
+			// The linked control should be in the second group, of optional controls.
+			let optionalItem = within( menuGroups[ 1 ] ).getByText( 'Linked' );
+			expect( optionalItem ).toBeInTheDocument();
+
+			// Simulate the main control having a value set which should
+			// trigger the linked control becoming a default control via the
+			// conditional `isShownByDefault` prop.
+			altControlProps.attributes.value = true;
+
+			rerender( <TestPanel /> );
+
+			// The linked control should now be a default control and rendered
+			// despite not having a value.
+			linkedItem = screen.getByText( 'Linked control' );
+			expect( linkedItem ).toBeInTheDocument();
+
+			// The linked control should now appear in the default controls
+			// menu group and have been removed from the optional group.
+			menuGroups = screen.getAllByRole( 'group' );
+
+			// There should now only be two groups. The default controls and
+			// and the group for the reset all option.
+			expect( menuGroups.length ).toEqual( 2 );
+
+			// The new default control item for the Linked control should be
+			// within the first menu group.
+			const defaultItem = within( menuGroups[ 0 ] ).getByText( 'Linked' );
+			expect( defaultItem ).toBeInTheDocument();
+
+			// Optional controls have an additional aria-label. This can be used
+			// to confirm the conditional default control has been removed from
+			// the optional menu item group.
+			optionalItem = screen.queryByRole( 'menuitemcheckbox', {
+				name: 'Show Linked',
+			} );
+			expect( optionalItem ).not.toBeInTheDocument();
+		} );
+
+		it( 'should handle conditionally rendered default control', async () => {
+			const conditionalControlProps = {
+				attributes: { value: false },
+				hasValue: jest.fn().mockImplementation( () => {
+					return !! conditionalControlProps.attributes.value;
+				} ),
+				label: 'Conditional',
+				onDeselect: jest.fn(),
+				onSelect: jest.fn(),
+			};
+
+			const TestPanel = () => (
+				<ToolsPanel { ...defaultProps }>
+					<ToolsPanelItem
+						{ ...altControlProps }
+						isShownByDefault={ true }
+					>
+						<div>Default control</div>
+					</ToolsPanelItem>
+					{ !! altControlProps.attributes.value && (
+						<ToolsPanelItem
+							{ ...conditionalControlProps }
+							isShownByDefault={ true }
+						>
+							<div>Conditional control</div>
+						</ToolsPanelItem>
+					) }
+				</ToolsPanel>
+			);
+
+			const { rerender } = render( <TestPanel /> );
+
+			// The conditional control should not yet be rendered.
+			let conditionalItem = screen.queryByText( 'Conditional control' );
+			expect( conditionalItem ).not.toBeInTheDocument();
+
+			// The conditional control should not yet appear in the default controls
+			// menu group.
+			openDropdownMenu();
+			let menuGroups = screen.getAllByRole( 'group' );
+			let defaultItem = within( menuGroups[ 0 ] ).queryByText(
+				'Conditional'
+			);
+			expect( defaultItem ).not.toBeInTheDocument();
+
+			// Simulate the main control having a value set which will now
+			// render the new default control into the ToolsPanel.
+			altControlProps.attributes.value = true;
+
+			rerender( <TestPanel /> );
+
+			// The conditional control should now be rendered and included in
+			// the panel's menu.
+			conditionalItem = screen.getByText( 'Conditional control' );
+			expect( conditionalItem ).toBeInTheDocument();
+
+			// The conditional control should now appear in the default controls
+			// menu group.
+			menuGroups = screen.getAllByRole( 'group' );
+
+			// The new default control item for the Conditional control should
+			// be within the first menu group.
+			defaultItem = within( menuGroups[ 0 ] ).getByText( 'Conditional' );
+			expect( defaultItem ).toBeInTheDocument();
+		} );
+	} );
+
+	describe( 'registration of panel items', () => {
+		it( 'should register and deregister items when panelId changes', () => {
+			// This test simulates switching block selection, which causes the
+			// `ToolsPanel` to rerender with a new panelId, necessitating the
+			// registration and deregistration of appropriate `ToolsPanelItem`
+			// children.
+			//
+			// When the `panelId` changes, only items matching the new ID register
+			// themselves, while those for the old panelId deregister.
+			//
+			// See: https://github.com/WordPress/gutenberg/pull/36588
+
+			const noop = () => undefined;
+			const context = {
+				panelId: '1234',
+				menuItems: {
+					default: {},
+					optional: { [ altControlProps.label ]: true },
+				},
+				hasMenuItems: false,
+				isResetting: false,
+				shouldRenderPlaceholderItems: false,
+				registerPanelItem: jest.fn(),
+				deregisterPanelItem: jest.fn(),
+				flagItemCustomization: noop,
+				areAllOptionalControlsHidden: true,
+			};
+
+			const TestPanel = () => (
+				<ToolsPanelContext.Provider value={ context }>
+					<ToolsPanelItem { ...altControlProps } panelId="1234">
+						<div>Item</div>
+					</ToolsPanelItem>
+				</ToolsPanelContext.Provider>
+			);
+
+			// On the initial render of the panel, the ToolsPanelItem should
+			// be registered.
+			const { rerender } = render( <TestPanel /> );
+
+			expect( context.registerPanelItem ).toHaveBeenCalledWith(
+				expect.objectContaining( {
+					label: altControlProps.label,
+					panelId: '1234',
+				} )
+			);
+			expect( context.deregisterPanelItem ).not.toHaveBeenCalled();
+
+			// Simulate a change in panel, e.g. a switch of block selection.
+			context.panelId = '4321';
+			context.menuItems.optional[ altControlProps.label ] = false;
+
+			// Rerender the panel item. Because we have a new panelId, this
+			// panelItem should NOT be registered, but it SHOULD be
+			// deregistered.
+			rerender( <TestPanel /> );
+
+			// registerPanelItem has still only been called once.
+			expect( context.registerPanelItem ).toHaveBeenCalledTimes( 1 );
+			// deregisterPanelItem is called, given that we have switched panels.
+			expect( context.deregisterPanelItem ).toBeCalledWith(
+				altControlProps.label
+			);
+
+			// Simulate switching back to the original panelId, e.g. by selecting
+			// the original block again.
+			context.panelId = '1234';
+			context.menuItems.optional[ altControlProps.label ] = true;
+
+			// Rerender the panel and ensure that the panelItem is registered
+			// again, and it is not de-registered.
+			rerender( <TestPanel /> );
+
+			expect( context.registerPanelItem ).toHaveBeenCalledWith(
+				expect.objectContaining( {
+					label: altControlProps.label,
+					panelId: '1234',
+				} )
+			);
+			expect( context.registerPanelItem ).toHaveBeenCalledTimes( 2 );
+			// deregisterPanelItem has still only been called once.
+			expect( context.deregisterPanelItem ).toHaveBeenCalledTimes( 1 );
+		} );
 	} );
 
 	describe( 'callbacks on menu item selection', () => {

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

@@ -24,14 +24,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 }