@wordpress/components 23.3.1 → 23.4.0

package/src/toolbar/toolbar-group/toolbar-group-container.js

@@ -1,3 +1,5 @@
+// @ts-nocheck
+
 const ToolbarGroupContainer = ( { className, children, ...props } ) => (
 	<div className={ className } { ...props }>
 		{ children }

package/src/toolbar/toolbar-item/index.js

@@ -1,3 +1,5 @@
+// @ts-nocheck
+
 /**
  * External dependencies
  */

package/src/tools-panel/stories/{index.js → index.tsx}

@@ -1,50 +1,73 @@
 /**
  * External dependencies
  */
+import type { ComponentMeta, ComponentStory } from '@storybook/react';
 import styled from '@emotion/styled';
 
 /**
  * WordPress dependencies
  */
 import { useState } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
 import {
-	__experimentalToggleGroupControl as ToggleGroupControl,
-	__experimentalToggleGroupControlOption as ToggleGroupControlOption,
-} from '@wordpress/components';
+	ToggleGroupControl,
+	ToggleGroupControlOption,
+} from '../../toggle-group-control';
 
 /**
  * Internal dependencies
  */
-import { ToolsPanel, ToolsPanelItem } from '../';
+import { ToolsPanel, ToolsPanelItem } from '..';
 import Panel from '../../panel';
 import UnitControl from '../../unit-control';
 import { createSlotFill, Provider as SlotFillProvider } from '../../slot-fill';
 
-export default {
+const meta: ComponentMeta< typeof ToolsPanel > = {
 	title: 'Components (Experimental)/ToolsPanel',
 	component: ToolsPanel,
+	subcomponents: {
+		ToolsPanelItem,
+	},
+	argTypes: {
+		as: { control: { type: null } },
+		children: { control: { type: null } },
+		panelId: { control: { type: null } },
+		resetAll: { action: 'resetAll' },
+	},
+	parameters: {
+		actions: { argTypesRegex: '^on.*' },
+		controls: {
+			expanded: true,
+		},
+		docs: { source: { state: 'open' } },
+	},
 };
-
-export const _default = () => {
-	const [ height, setHeight ] = useState();
-	const [ minHeight, setMinHeight ] = useState();
-	const [ width, setWidth ] = useState();
-	const [ scale, setScale ] = useState();
-
-	const resetAll = () => {
+export default meta;
+
+export const Default: ComponentStory< typeof ToolsPanel > = ( {
+	resetAll: resetAllProp,
+	...props
+} ) => {
+	const [ height, setHeight ] = useState< string | undefined >();
+	const [ minHeight, setMinHeight ] = useState< string | undefined >();
+	const [ width, setWidth ] = useState< string | undefined >();
+	const [ scale, setScale ] = useState< React.ReactText | undefined >();
+
+	const resetAll: typeof resetAllProp = ( filters ) => {
 		setHeight( undefined );
 		setWidth( undefined );
 		setMinHeight( undefined );
 		setScale( undefined );
+		resetAllProp( filters );
 	};
 
 	return (
 		<PanelWrapperView>
 			<Panel>
-				<ToolsPanel
-					label="Tools Panel (default example)"
-					resetAll={ resetAll }
-				>
+				<ToolsPanel { ...props } resetAll={ resetAll }>
 					<SingleColumnItem
 						hasValue={ () => !! width }
 						label="Width"
@@ -112,23 +135,27 @@ export const _default = () => {
 		</PanelWrapperView>
 	);
 };
+Default.args = {
+	label: 'Tools Panel (default example)',
+};
 
-export const WithNonToolsPanelItems = () => {
-	const [ height, setHeight ] = useState();
-	const [ width, setWidth ] = useState();
+export const WithNonToolsPanelItems: ComponentStory< typeof ToolsPanel > = ( {
+	resetAll: resetAllProp,
+	...props
+} ) => {
+	const [ height, setHeight ] = useState< string | undefined >();
+	const [ width, setWidth ] = useState< string | undefined >();
 
-	const resetAll = () => {
+	const resetAll: typeof resetAllProp = ( filters ) => {
 		setHeight( undefined );
 		setWidth( undefined );
+		resetAllProp( filters );
 	};
 
 	return (
 		<PanelWrapperView>
 			<Panel>
-				<ToolsPanel
-					label="ToolsPanel (with non-menu items)"
-					resetAll={ resetAll }
-				>
+				<ToolsPanel { ...props } resetAll={ resetAll }>
 					<IntroText>
 						This text illustrates not all items must be wrapped in a
 						ToolsPanelItem and represented in the panel menu.
@@ -162,81 +189,127 @@ export const WithNonToolsPanelItems = () => {
 		</PanelWrapperView>
 	);
 };
+WithNonToolsPanelItems.args = {
+	...Default.args,
+	label: 'ToolsPanel (with non-menu items)',
+};
 
-export const WithOptionalItemsPlusIcon = ( { isShownByDefault } ) => {
-	const [ height, setHeight ] = useState();
-	const [ width, setWidth ] = useState();
-	const [ minWidth, setMinWidth ] = useState();
-
-	const resetAll = () => {
+export const WithOptionalItemsPlusIcon: ComponentStory<
+	typeof ToolsPanel
+> = ( { resetAll: resetAllProp, ...props } ) => {
+	const [
+		isFirstToolsPanelItemShownByDefault,
+		setIsFirstToolsPanelItemShownByDefault,
+	] = useState( false );
+	const [ height, setHeight ] = useState< string | undefined >();
+	const [ width, setWidth ] = useState< string | undefined >();
+	const [ minWidth, setMinWidth ] = useState< string | undefined >();
+
+	const resetAll: typeof resetAllProp = ( filters ) => {
 		setHeight( undefined );
 		setWidth( undefined );
 		setMinWidth( undefined );
+		resetAllProp( filters );
 	};
 
 	return (
-		<PanelWrapperView>
-			<Panel>
-				<ToolsPanel
-					label="Tools Panel (optional items only)"
-					resetAll={ resetAll }
-					key={ isShownByDefault }
-				>
-					<SingleColumnItem
-						hasValue={ () => !! minWidth }
-						label="Minimum width"
-						onDeselect={ () => setMinWidth( undefined ) }
-						isShownByDefault={ isShownByDefault }
+		<>
+			<PanelWrapperView>
+				<Panel>
+					<ToolsPanel
+						{ ...props }
+						resetAll={ resetAll }
+						// `key` property here is used as a hack to force `ToolsPanel` to re-render
+						// See https://github.com/WordPress/gutenberg/pull/38262/files#r793422991
+						key={
+							isFirstToolsPanelItemShownByDefault
+								? 'true'
+								: 'false'
+						}
 					>
-						<UnitControl
+						<SingleColumnItem
+							hasValue={ () => !! minWidth }
 							label="Minimum width"
-							value={ minWidth }
-							onChange={ ( next ) => setMinWidth( next ) }
-						/>
-					</SingleColumnItem>
-					<SingleColumnItem
-						hasValue={ () => !! width }
-						label="Width"
-						onDeselect={ () => setWidth( undefined ) }
-						isShownByDefault={ false }
-					>
-						<UnitControl
+							onDeselect={ () => setMinWidth( undefined ) }
+							isShownByDefault={
+								isFirstToolsPanelItemShownByDefault
+							}
+						>
+							<UnitControl
+								label="Minimum width"
+								value={ minWidth }
+								onChange={ ( next ) => setMinWidth( next ) }
+							/>
+						</SingleColumnItem>
+						<SingleColumnItem
+							hasValue={ () => !! width }
 							label="Width"
-							value={ width }
-							onChange={ ( next ) => setWidth( next ) }
-						/>
-					</SingleColumnItem>
-					<SingleColumnItem
-						hasValue={ () => !! height }
-						label="Height"
-						onDeselect={ () => setHeight( undefined ) }
-						isShownByDefault={ false }
-					>
-						<UnitControl
+							onDeselect={ () => setWidth( undefined ) }
+							isShownByDefault={ false }
+						>
+							<UnitControl
+								label="Width"
+								value={ width }
+								onChange={ ( next ) => setWidth( next ) }
+							/>
+						</SingleColumnItem>
+						<SingleColumnItem
+							hasValue={ () => !! height }
 							label="Height"
-							value={ height }
-							onChange={ ( next ) => setHeight( next ) }
-						/>
-					</SingleColumnItem>
-				</ToolsPanel>
-			</Panel>
-		</PanelWrapperView>
+							onDeselect={ () => setHeight( undefined ) }
+							isShownByDefault={ false }
+						>
+							<UnitControl
+								label="Height"
+								value={ height }
+								onChange={ ( next ) => setHeight( next ) }
+							/>
+						</SingleColumnItem>
+					</ToolsPanel>
+				</Panel>
+			</PanelWrapperView>
+
+			<button
+				onClick={ () =>
+					setIsFirstToolsPanelItemShownByDefault(
+						! isFirstToolsPanelItemShownByDefault
+					)
+				}
+				aria-pressed={
+					isFirstToolsPanelItemShownByDefault ? 'true' : 'false'
+				}
+				style={ {
+					marginTop: '2rem',
+				} }
+			>
+				{ isFirstToolsPanelItemShownByDefault
+					? 'Make first PanelItem hidden by default'
+					: 'Make first PanelItem shown by default' }
+			</button>
+		</>
 	);
 };
 
 WithOptionalItemsPlusIcon.args = {
-	isShownByDefault: false,
+	...Default.args,
+	label: 'Tools Panel (optional items only)',
 };
 
 const { Fill: ToolsPanelItems, Slot } = createSlotFill( 'ToolsPanelSlot' );
-const panelId = 'unique-tools-panel-id';
 
-export const WithSlotFillItems = () => {
-	const [ attributes, setAttributes ] = useState( {} );
+export const WithSlotFillItems: ComponentStory< typeof ToolsPanel > = ( {
+	resetAll: resetAllProp,
+	panelId,
+	...props
+} ) => {
+	const [ attributes, setAttributes ] = useState< {
+		width?: string;
+		height?: string;
+	} >( {} );
 	const { width, height } = attributes;
 
-	const resetAll = ( resetFilters = [] ) => {
-		let newAttributes = {};
+	const resetAll: typeof resetAllProp = ( resetFilters = [] ) => {
+		let newAttributes: typeof attributes = {};
 
 		resetFilters.forEach( ( resetFilter ) => {
 			newAttributes = {
@@ -246,9 +319,10 @@ export const WithSlotFillItems = () => {
 		} );
 
 		setAttributes( newAttributes );
+		resetAllProp( resetFilters );
 	};
 
-	const updateAttribute = ( name, value ) => {
+	const updateAttribute = ( name: string, value?: any ) => {
 		setAttributes( {
 			...attributes,
 			[ name ]: value,
@@ -304,7 +378,7 @@ export const WithSlotFillItems = () => {
 			<PanelWrapperView>
 				<Panel>
 					<ToolsPanel
-						label="Tools Panel With SlotFill Items"
+						{ ...props }
 						resetAll={ resetAll }
 						panelId={ panelId }
 					>
@@ -315,13 +389,23 @@ export const WithSlotFillItems = () => {
 		</SlotFillProvider>
 	);
 };
+WithSlotFillItems.args = {
+	...Default.args,
+	label: 'Tools Panel With SlotFill Items',
+	panelId: 'unique-tools-panel-id',
+};
 
-export const WithConditionalDefaultControl = () => {
-	const [ attributes, setAttributes ] = useState( {} );
+export const WithConditionalDefaultControl: ComponentStory<
+	typeof ToolsPanel
+> = ( { resetAll: resetAllProp, panelId, ...props } ) => {
+	const [ attributes, setAttributes ] = useState< {
+		height?: string;
+		scale?: React.ReactText;
+	} >( {} );
 	const { height, scale } = attributes;
 
-	const resetAll = ( resetFilters = [] ) => {
-		let newAttributes = {};
+	const resetAll: typeof resetAllProp = ( resetFilters = [] ) => {
+		let newAttributes: typeof attributes = {};
 
 		resetFilters.forEach( ( resetFilter ) => {
 			newAttributes = {
@@ -331,9 +415,11 @@ export const WithConditionalDefaultControl = () => {
 		} );
 
 		setAttributes( newAttributes );
+
+		resetAllProp( resetFilters );
 	};
 
-	const updateAttribute = ( name, value ) => {
+	const updateAttribute = ( name: string, value?: any ) => {
 		setAttributes( {
 			...attributes,
 			[ name ]: value,
@@ -388,7 +474,7 @@ export const WithConditionalDefaultControl = () => {
 			<PanelWrapperView>
 				<Panel>
 					<ToolsPanel
-						label="Tools Panel With Conditional Default via SlotFill"
+						{ ...props }
 						resetAll={ resetAll }
 						panelId={ panelId }
 					>
@@ -399,13 +485,23 @@ export const WithConditionalDefaultControl = () => {
 		</SlotFillProvider>
 	);
 };
+WithConditionalDefaultControl.args = {
+	...Default.args,
+	label: 'Tools Panel With Conditional Default via SlotFill',
+	panelId: 'unique-tools-panel-id',
+};
 
-export const WithConditionallyRenderedControl = () => {
-	const [ attributes, setAttributes ] = useState( {} );
+export const WithConditionallyRenderedControl: ComponentStory<
+	typeof ToolsPanel
+> = ( { resetAll: resetAllProp, panelId, ...props } ) => {
+	const [ attributes, setAttributes ] = useState< {
+		height?: string;
+		scale?: React.ReactText;
+	} >( {} );
 	const { height, scale } = attributes;
 
-	const resetAll = ( resetFilters = [] ) => {
-		let newAttributes = {};
+	const resetAll: typeof resetAllProp = ( resetFilters = [] ) => {
+		let newAttributes: typeof attributes = {};
 
 		resetFilters.forEach( ( resetFilter ) => {
 			newAttributes = {
@@ -415,9 +511,11 @@ export const WithConditionallyRenderedControl = () => {
 		} );
 
 		setAttributes( newAttributes );
+
+		resetAllProp( resetFilters );
 	};
 
-	const updateAttribute = ( name, value ) => {
+	const updateAttribute = ( name: string, value?: any ) => {
 		setAttributes( {
 			...attributes,
 			[ name ]: value,
@@ -485,7 +583,7 @@ export const WithConditionallyRenderedControl = () => {
 			<PanelWrapperView>
 				<Panel>
 					<ToolsPanel
-						label="Tools Panel With Conditionally Rendered Item via SlotFill"
+						{ ...props }
 						resetAll={ resetAll }
 						panelId={ panelId }
 					>
@@ -496,8 +594,11 @@ export const WithConditionallyRenderedControl = () => {
 		</SlotFillProvider>
 	);
 };
-
-export { ToolsPanelWithItemGroupSlot } from './utils/tools-panel-with-item-group-slot';
+WithConditionallyRenderedControl.args = {
+	...Default.args,
+	label: 'Tools Panel With Conditionally Rendered Item via SlotFill',
+	panelId: 'unique-tools-panel-id',
+};
 
 const PanelWrapperView = styled.div`
 	font-size: 13px;

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

@@ -1,8 +1,8 @@
 /**
  * External dependencies
  */
-import { render, screen, fireEvent, within } from '@testing-library/react';
-import { act } from 'react-test-renderer';
+import { render, screen, within } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
 
 /**
  * Internal dependencies
@@ -169,19 +169,19 @@ const getMenuButton = () => {
 /**
  * Helper to find the menu button and simulate a user click.
  *
- * @return {HTMLElement} The menuButton.
  */
 const openDropdownMenu = async () => {
+	const user = userEvent.setup();
 	const menuButton = getMenuButton();
-	fireEvent.click( menuButton );
-	await act( () => Promise.resolve() );
+	await user.click( menuButton );
 	return menuButton;
 };
 
 // Opens dropdown then selects the menu item by label before simulating a click.
 const selectMenuItem = async ( label ) => {
+	const user = userEvent.setup();
 	const menuItem = await screen.findByText( label );
-	fireEvent.click( menuItem );
+	await user.click( menuItem );
 };
 
 describe( 'ToolsPanel', () => {
@@ -316,6 +316,71 @@ describe( 'ToolsPanel', () => {
 			expect( announcement ).toHaveAttribute( 'aria-live', 'assertive' );
 		} );
 
+		it( 'should render optional panel item when value is updated externally and panel has an ID', async () => {
+			const ToolsPanelOptional = ( { toolsPanelItemValue } ) => {
+				const itemProps = {
+					attributes: { value: toolsPanelItemValue },
+					hasValue: () => !! toolsPanelItemValue,
+					label: 'Alt',
+					onDeselect: jest.fn(),
+					onSelect: jest.fn(),
+				};
+
+				return (
+					<ToolsPanel { ...defaultProps }>
+						<ToolsPanelItem { ...itemProps }>
+							<div>Optional control</div>
+						</ToolsPanelItem>
+					</ToolsPanel>
+				);
+			};
+			const { rerender } = render( <ToolsPanelOptional /> );
+
+			const control = screen.queryByText( 'Optional control' );
+
+			expect( control ).not.toBeInTheDocument();
+
+			rerender( <ToolsPanelOptional toolsPanelItemValue={ 100 } /> );
+
+			const controlRerendered = screen.getByText( 'Optional control' );
+
+			expect( controlRerendered ).toBeInTheDocument();
+		} );
+
+		it( 'should render optional item when value is updated externally and panelId is null', async () => {
+			// This test partially covers: https://github.com/WordPress/gutenberg/issues/47368
+			const ToolsPanelOptional = ( { toolsPanelItemValue } ) => {
+				const itemProps = {
+					attributes: { value: toolsPanelItemValue },
+					hasValue: () => !! toolsPanelItemValue,
+					label: 'Alt',
+					onDeselect: jest.fn(),
+					onSelect: jest.fn(),
+				};
+
+				// The null panelId below simulates the panel prop when there
+				// are multiple blocks selected.
+				return (
+					<ToolsPanel { ...defaultProps } panelId={ null }>
+						<ToolsPanelItem { ...itemProps }>
+							<div>Optional control</div>
+						</ToolsPanelItem>
+					</ToolsPanel>
+				);
+			};
+
+			const { rerender } = render( <ToolsPanelOptional /> );
+			const control = screen.queryByText( 'Optional control' );
+
+			expect( control ).not.toBeInTheDocument();
+
+			rerender( <ToolsPanelOptional toolsPanelItemValue={ 99 } /> );
+
+			const controlRerendered = screen.getByText( 'Optional control' );
+
+			expect( controlRerendered ).toBeInTheDocument();
+		} );
+
 		it( 'should continue to render shown by default item after it is toggled off via menu item', async () => {
 			render(
 				<ToolsPanel { ...defaultProps }>

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

@@ -155,6 +155,14 @@ 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
+- Default: `false`
+
+### `headingLevel`: `1 | 2 | 3 | 4 | 5 | 6 | '1' | '2' | '3' | '4' | '5' | '6'`
+
+The heading level of the panel's header.
+
+-   Required: No
+-   Default: `2`
 
 ### `label`: `string`
 
@@ -163,7 +171,7 @@ panel's dropdown menu.
 
 - Required: Yes
 
-### `panelId`: `string`
+### `panelId`: `string | null`
 
 If a `panelId` is set, it is passed through the `ToolsPanelContext` and used
 to restrict panel items. When a `panelId` is set, items can only register
@@ -172,10 +180,9 @@ exactly.
 
 - Required: No
 
-### `resetAll`: `() => void`
+### `resetAll`: `( filters?: ResetAllFilter[] ) => void`
 
-A function to call when the `Reset all` menu option is selected. This is passed
-through to the panel's header component.
+A function to call when the `Reset all` menu option is selected. As an argument, it receives an array containing the `resetAllFilter` callbacks of all the valid registered `ToolsPanelItems`.
 
 - Required: Yes
 
@@ -185,3 +192,4 @@ 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
+- Default: `false`

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

@@ -13,7 +13,7 @@ import { Grid } from '../../grid';
 import { contextConnect, WordPressComponentProps } from '../../ui/context';
 import type { ToolsPanelProps } from '../types';
 
-const ToolsPanel = (
+const UnconnectedToolsPanel = (
 	props: WordPressComponentProps< ToolsPanelProps, 'div' >,
 	forwardedRef: ForwardedRef< any >
 ) => {
@@ -23,6 +23,7 @@ const ToolsPanel = (
 		panelContext,
 		resetAllItems,
 		toggleItem,
+		headingLevel,
 		...toolsPanelProps
 	} = useToolsPanel( props );
 
@@ -33,6 +34,7 @@ const ToolsPanel = (
 					label={ label }
 					resetAll={ resetAllItems }
 					toggleItem={ toggleItem }
+					headingLevel={ headingLevel }
 				/>
 				{ children }
 			</ToolsPanelContext.Provider>
@@ -40,6 +42,58 @@ const ToolsPanel = (
 	);
 };
 
-const ConnectedToolsPanel = contextConnect( ToolsPanel, 'ToolsPanel' );
+/**
+ * The `ToolsPanel` is a container component that displays its children preceded
+ * by a header. The header includes a dropdown menu which is automatically
+ * generated from the panel's inner `ToolsPanelItems`.
+ *
+ * @example
+ * ```jsx
+ * import { __ } from '@wordpress/i18n';
+ * import {
+ *   __experimentalToolsPanel as ToolsPanel,
+ *   __experimentalToolsPanelItem as ToolsPanelItem,
+ *   __experimentalUnitControl as UnitControl
+ * } from '@wordpress/components';
+ *
+ * function Example() {
+ *   const [ height, setHeight ] = useState();
+ *   const [ width, setWidth ] = useState();
+ *
+ *   const resetAll = () => {
+ *     setHeight();
+ *     setWidth();
+ *   }
+ *
+ *   return (
+ *     <ToolsPanel label={ __( 'Dimensions' ) } resetAll={ resetAll }>
+ *       <ToolsPanelItem
+ *         hasValue={ () => !! height }
+ *         label={ __( 'Height' ) }
+ *         onDeselect={ () => setHeight() }
+ *       >
+ *         <UnitControl
+ *           label={ __( 'Height' ) }
+ *           onChange={ setHeight }
+ *           value={ height }
+ *         />
+ *       </ToolsPanelItem>
+ *       <ToolsPanelItem
+ *         hasValue={ () => !! width }
+ *         label={ __( 'Width' ) }
+ *         onDeselect={ () => setWidth() }
+ *       >
+ *         <UnitControl
+ *           label={ __( 'Width' ) }
+ *           onChange={ setWidth }
+ *           value={ width }
+ *         />
+ *       </ToolsPanelItem>
+ *     </ToolsPanel>
+ *   );
+ * }
+ * ```
+ */
+export const ToolsPanel = contextConnect( UnconnectedToolsPanel, 'ToolsPanel' );
 
-export default ConnectedToolsPanel;
+export default ToolsPanel;