@wordpress/components 17.0.0 → 19.0.2

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

@@ -0,0 +1,220 @@
+/**
+ * WordPress dependencies
+ */
+import { useEffect, useMemo, useRef, useState } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import * as styles from '../styles';
+import { useContextSystem, WordPressComponentProps } from '../../ui/context';
+import { useCx } from '../../utils/hooks/use-cx';
+import type {
+	ToolsPanelItem,
+	ToolsPanelMenuItemKey,
+	ToolsPanelMenuItems,
+	ToolsPanelMenuItemsConfig,
+	ToolsPanelProps,
+} from '../types';
+
+const DEFAULT_COLUMNS = 2;
+
+const generateMenuItems = ( {
+	panelItems,
+	shouldReset,
+}: ToolsPanelMenuItemsConfig ) => {
+	const menuItems: ToolsPanelMenuItems = { default: {}, optional: {} };
+
+	panelItems.forEach( ( { hasValue, isShownByDefault, label } ) => {
+		const group = isShownByDefault ? 'default' : 'optional';
+		menuItems[ group ][ label ] = shouldReset ? false : hasValue();
+	} );
+
+	return menuItems;
+};
+
+export function useToolsPanel(
+	props: WordPressComponentProps< ToolsPanelProps, 'div' >
+) {
+	const {
+		className,
+		resetAll,
+		panelId,
+		hasInnerWrapper,
+		shouldRenderPlaceholderItems,
+		...otherProps
+	} = useContextSystem( props, 'ToolsPanel' );
+
+	const isResetting = useRef( false );
+	const wasResetting = isResetting.current;
+
+	// `isResetting` is cleared via this hook to effectively batch together
+	// the resetAll task. Without this, the flag is cleared after the first
+	// control updates and forces a rerender with subsequent controls then
+	// believing they need to reset, unfortunately using stale data.
+	useEffect( () => {
+		if ( wasResetting ) {
+			isResetting.current = false;
+		}
+	}, [ wasResetting ] );
+
+	// Allow panel items to register themselves.
+	const [ panelItems, setPanelItems ] = useState< ToolsPanelItem[] >( [] );
+
+	const registerPanelItem = ( item: ToolsPanelItem ) => {
+		setPanelItems( ( items ) => [ ...items, item ] );
+	};
+
+	// 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.
+		const index = panelItems.findIndex( ( item ) => item.label === label );
+
+		if ( index !== -1 ) {
+			setPanelItems( ( items ) => items.splice( index, 1 ) );
+		}
+	};
+
+	// Manage and share display state of menu items representing child controls.
+	const [ menuItems, setMenuItems ] = useState< ToolsPanelMenuItems >( {
+		default: {},
+		optional: {},
+	} );
+
+	// Setup menuItems state as panel items register themselves.
+	useEffect( () => {
+		const items = generateMenuItems( {
+			panelItems,
+			shouldReset: false,
+		} );
+		setMenuItems( items );
+	}, [ panelItems ] );
+
+	// 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( {
+			...menuItems,
+			[ group ]: {
+				...menuItems[ group ],
+				[ label ]: true,
+			},
+		} );
+	};
+
+	// 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 ) => {
+		const currentItem = panelItems.find( ( item ) => item.label === label );
+
+		if ( ! currentItem ) {
+			return;
+		}
+
+		const menuGroup = currentItem.isShownByDefault ? 'default' : 'optional';
+
+		const newMenuItems = {
+			...menuItems,
+			[ menuGroup ]: {
+				...menuItems[ menuGroup ],
+				[ label ]: ! menuItems[ menuGroup ][ label ],
+			},
+		};
+
+		setMenuItems( newMenuItems );
+	};
+
+	const getResetAllFilters = () => {
+		const filters: Array< () => void > = [];
+
+		panelItems.forEach( ( item ) => {
+			if ( item.resetAllFilter ) {
+				filters.push( item.resetAllFilter );
+			}
+		} );
+		return filters;
+	};
+
+	// Resets display of children and executes resetAll callback if available.
+	const resetAllItems = () => {
+		if ( typeof resetAll === 'function' ) {
+			isResetting.current = true;
+			resetAll( getResetAllFilters() );
+		}
+
+		// Turn off display of all non-default items.
+		const resetMenuItems = generateMenuItems( {
+			panelItems,
+			shouldReset: true,
+		} );
+		setMenuItems( resetMenuItems );
+	};
+
+	const panelContext = {
+		panelId,
+		menuItems,
+		registerPanelItem,
+		deregisterPanelItem,
+		flagItemCustomization,
+		areAllOptionalControlsHidden,
+		hasMenuItems: !! panelItems.length,
+		isResetting: isResetting.current,
+		shouldRenderPlaceholderItems,
+	};
+
+	return {
+		...otherProps,
+		panelContext,
+		resetAllItems,
+		toggleItem,
+		className: classes,
+	};
+}

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

@@ -18,27 +18,22 @@ This component is generated automatically by its parent
 
 ## Props
 
-### `header`: `string`
+### `label`: `string`
 
-Text to be displayed within the panel header.
+Text to be displayed within the panel header. It is also passed along as the
+`label` for the panel header's `DropdownMenu`.
 
 -   Required: Yes
 
-### `menuLabel`: `string`
-
-This is passed along as the `label` for the panel header's `DropdownMenu`.
-
--   Required: No
-
-### `resetAll`: `function`
+### `resetAll`: `() => void`
 
 The `resetAll` prop provides the callback to execute when the "Reset all" menu
-item is selected. It's purpose is to facilitate resetting any control values
+item is selected. Its purpose is to facilitate resetting any control values
 for items contained within this header's panel.
 
 -   Required: Yes
 
-### `toggleItem`: `function`
+### `toggleItem`: `( label: string ) => void`
 
 This is executed when an individual control's menu item is toggled. It
 will update the panel's menu item state and call the panel item's `onSelect` or

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

@@ -0,0 +1,194 @@
+/**
+ * External dependencies
+ */
+// eslint-disable-next-line no-restricted-imports
+import type { Ref } from 'react';
+
+/**
+ * WordPress dependencies
+ */
+import { check, reset, moreVertical, plus } from '@wordpress/icons';
+import { __, _x, sprintf } from '@wordpress/i18n';
+
+/**
+ * Internal dependencies
+ */
+import DropdownMenu from '../../dropdown-menu';
+import MenuGroup from '../../menu-group';
+import MenuItem from '../../menu-item';
+import { HStack } from '../../h-stack';
+import { Heading } from '../../heading';
+import { useToolsPanelHeader } from './hook';
+import { contextConnect, WordPressComponentProps } from '../../ui/context';
+import type {
+	ToolsPanelControlsGroupProps,
+	ToolsPanelHeaderProps,
+} from '../types';
+
+const noop = () => {};
+
+const DefaultControlsGroup = ( {
+	items,
+	onClose,
+	toggleItem,
+}: ToolsPanelControlsGroupProps ) => {
+	if ( ! items.length ) {
+		return null;
+	}
+
+	return (
+		<MenuGroup>
+			{ items.map( ( [ label, hasValue ] ) => {
+				const icon = hasValue ? reset : check;
+				const itemLabel = hasValue
+					? sprintf(
+							// translators: %s: The name of the control being reset e.g. "Padding".
+							__( 'Reset %s' ),
+							label
+					  )
+					: undefined;
+
+				return (
+					<MenuItem
+						key={ label }
+						icon={ icon }
+						isSelected={ true }
+						disabled={ ! hasValue }
+						label={ itemLabel }
+						onClick={ () => {
+							toggleItem( label );
+							onClose();
+						} }
+						role="menuitemcheckbox"
+					>
+						{ label }
+					</MenuItem>
+				);
+			} ) }
+		</MenuGroup>
+	);
+};
+
+const OptionalControlsGroup = ( {
+	items,
+	onClose,
+	toggleItem,
+}: ToolsPanelControlsGroupProps ) => {
+	if ( ! items.length ) {
+		return null;
+	}
+
+	return (
+		<MenuGroup>
+			{ items.map( ( [ label, isSelected ] ) => {
+				const itemLabel = isSelected
+					? sprintf(
+							// translators: %s: The name of the control being hidden and reset e.g. "Padding".
+							__( 'Hide and reset %s' ),
+							label
+					  )
+					: sprintf(
+							// translators: %s: The name of the control to display e.g. "Padding".
+							__( 'Show %s' ),
+							label
+					  );
+
+				return (
+					<MenuItem
+						key={ label }
+						icon={ isSelected && check }
+						isSelected={ isSelected }
+						label={ itemLabel }
+						onClick={ () => {
+							toggleItem( label );
+							onClose();
+						} }
+						role="menuitemcheckbox"
+					>
+						{ label }
+					</MenuItem>
+				);
+			} ) }
+		</MenuGroup>
+	);
+};
+
+const ToolsPanelHeader = (
+	props: WordPressComponentProps< ToolsPanelHeaderProps, 'h2' >,
+	forwardedRef: Ref< any >
+) => {
+	const {
+		areAllOptionalControlsHidden,
+		dropdownMenuClassName,
+		hasMenuItems,
+		headingClassName,
+		label: labelText,
+		menuItems,
+		resetAll,
+		toggleItem,
+		...headerProps
+	} = useToolsPanelHeader( props );
+
+	if ( ! labelText ) {
+		return null;
+	}
+
+	const defaultItems = Object.entries( menuItems?.default || {} );
+	const optionalItems = Object.entries( menuItems?.optional || {} );
+	const dropDownMenuIcon = areAllOptionalControlsHidden ? plus : moreVertical;
+	const dropDownMenuLabelText = areAllOptionalControlsHidden
+		? _x(
+				'View and add options',
+				'Button label to reveal tool panel options'
+		  )
+		: _x( 'View options', 'Button label to reveal tool panel options' );
+
+	return (
+		<HStack { ...headerProps } ref={ forwardedRef }>
+			<Heading level={ 2 } className={ headingClassName }>
+				{ labelText }
+			</Heading>
+			{ hasMenuItems && (
+				<DropdownMenu
+					icon={ dropDownMenuIcon }
+					label={ dropDownMenuLabelText }
+					menuProps={ { className: dropdownMenuClassName } }
+					toggleProps={ { isSmall: true } }
+				>
+					{ ( { onClose = noop } ) => (
+						<>
+							<DefaultControlsGroup
+								items={ defaultItems }
+								onClose={ onClose }
+								toggleItem={ toggleItem }
+							/>
+							<OptionalControlsGroup
+								items={ optionalItems }
+								onClose={ onClose }
+								toggleItem={ toggleItem }
+							/>
+							<MenuGroup>
+								<MenuItem
+									variant={ 'tertiary' }
+									onClick={ () => {
+										resetAll();
+										onClose();
+									} }
+								>
+									{ __( 'Reset all' ) }
+								</MenuItem>
+							</MenuGroup>
+						</>
+					) }
+				</DropdownMenu>
+			) }
+		</HStack>
+	);
+};
+
+const ConnectedToolsPanelHeader = contextConnect(
+	ToolsPanelHeader,
+	'ToolsPanelHeader'
+);
+
+export default ConnectedToolsPanelHeader;

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

@@ -0,0 +1,51 @@
+/**
+ * WordPress dependencies
+ */
+import { useMemo } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import * as styles from '../styles';
+import { useToolsPanelContext } from '../context';
+import { useContextSystem, WordPressComponentProps } from '../../ui/context';
+import { useCx } from '../../utils/hooks/use-cx';
+import type { ToolsPanelHeaderProps } from '../types';
+
+export function useToolsPanelHeader(
+	props: WordPressComponentProps< ToolsPanelHeaderProps, 'h2' >
+) {
+	const { className, ...otherProps } = useContextSystem(
+		props,
+		'ToolsPanelHeader'
+	);
+
+	const cx = useCx();
+	const classes = useMemo( () => {
+		return cx( styles.ToolsPanelHeader, className );
+	}, [ className ] );
+
+	const dropdownMenuClassName = useMemo( () => {
+		return cx( styles.DropdownMenu );
+	}, [] );
+
+	const headingClassName = useMemo( () => {
+		return cx( styles.ToolsPanelHeading );
+	}, [] );
+
+	const {
+		menuItems,
+		hasMenuItems,
+		areAllOptionalControlsHidden,
+	} = useToolsPanelContext();
+
+	return {
+		...otherProps,
+		areAllOptionalControlsHidden,
+		dropdownMenuClassName,
+		hasMenuItems,
+		headingClassName,
+		menuItems,
+		className: classes,
+	};
+}

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

@@ -0,0 +1 @@
+export { default } from './component';

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

@@ -6,7 +6,7 @@ implementation subject to drastic and breaking changes.
 </div>
 <br />
 
-This component acts a wrapper and controls the display of items to be contained
+This component acts as a wrapper and controls the display of items to be contained
 within a ToolsPanel. An item is displayed if it is flagged as a default control
 or the corresponding panel menu item, provided via context, is toggled on for
 this item.
@@ -18,6 +18,13 @@ for how to use `ToolsPanelItem`.
 
 ## Props
 
+### `hasValue`: `() => boolean`
+
+This is called when building the `ToolsPanel` menu to determine the item's
+initial checked state.
+
+-   Required: Yes
+
 ### `isShownByDefault`: `boolean`
 
 This prop identifies the current item as being displayed by default. This means
@@ -30,10 +37,39 @@ panel's menu.
 
 The supplied label is dual purpose.
 It is used as:
-1. the human readable label for the panel's dropdown menu
+1. the human-readable label for the panel's dropdown menu
 2. a key to locate the corresponding item in the panel's menu context to
 determine if the panel item should be displayed.
 
 A panel item's `label` should be unique among all items within a single panel.
 
 -   Required: Yes
+
+### `onDeselect`: `() => void`
+
+Called when this item is deselected in the `ToolsPanel` menu. This is normally
+used to reset the panel item control's value.
+
+-   Required: No
+
+### `onSelect`: `() => void`
+
+A callback to take action when this item is selected in the `ToolsPanel` menu.
+
+-   Required: No
+
+### `panelId`: `string`
+
+Panel items will ensure they are only registering with their intended panel by
+comparing the `panelId` props set on both the item and the panel itself. This
+allows items to be injected from a shared source.
+
+-   Required: No
+
+### `resetAllFilter`: `() => void`
+
+A `ToolsPanel` will collect each item's `resetAllFilter` and pass an array of
+these functions through to the panel's `resetAll` callback. They can then be
+iterated over to perform additional tasks.
+
+-   Required: No

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

@@ -0,0 +1,46 @@
+/**
+ * External dependencies
+ */
+// eslint-disable-next-line no-restricted-imports
+import type { Ref } from 'react';
+
+/**
+ * Internal dependencies
+ */
+import { useToolsPanelItem } from './hook';
+import { View } from '../../view';
+import { contextConnect, WordPressComponentProps } from '../../ui/context';
+import type { ToolsPanelItemProps } from '../types';
+
+// This wraps controls to be conditionally displayed within a tools panel. It
+// prevents props being applied to HTML elements that would make them invalid.
+const ToolsPanelItem = (
+	props: WordPressComponentProps< ToolsPanelItemProps, 'div' >,
+	forwardedRef: Ref< any >
+) => {
+	const {
+		children,
+		isShown,
+		shouldRenderPlaceholder,
+		...toolsPanelItemProps
+	} = useToolsPanelItem( props );
+
+	if ( ! isShown ) {
+		return shouldRenderPlaceholder ? (
+			<View { ...toolsPanelItemProps } ref={ forwardedRef } />
+		) : null;
+	}
+
+	return (
+		<View { ...toolsPanelItemProps } ref={ forwardedRef }>
+			{ children }
+		</View>
+	);
+};
+
+const ConnectedToolsPanelItem = contextConnect(
+	ToolsPanelItem,
+	'ToolsPanelItem'
+);
+
+export default ConnectedToolsPanelItem;