@wordpress/components 19.15.0 → 20.0.0

package/src/toggle-group-control/types.ts

@@ -8,10 +8,17 @@ import type { RadioStateReturn } from 'reakit';
 /**
  * Internal dependencies
  */
+import type { BaseControlProps } from '../base-control/types';
 import type { FormElementProps } from '../utils/types';
 
 export type ToggleGroupControlOptionBaseProps = {
 	children: ReactNode;
+	/**
+	 * Style the option as an icon option.
+	 *
+	 * @default false
+	 */
+	isIcon?: boolean;
 	value: ReactText;
 	/**
 	 * Whether to display a Tooltip for the control option. If set to `true`, the tooltip will
@@ -22,20 +29,24 @@ export type ToggleGroupControlOptionBaseProps = {
 	showTooltip?: boolean;
 };
 
-export type ToggleGroupControlOptionIconProps = Omit<
+export type ToggleGroupControlOptionIconProps = Pick<
 	ToggleGroupControlOptionBaseProps,
-	'children'
+	'value'
 > & {
 	/**
 	 * Icon displayed as the content of the option. Usually one of the icons from
 	 * the `@wordpress/icons` package, or a custom React `<svg>` icon.
 	 */
 	icon: JSX.Element;
+	/**
+	 * The text to accessibly label the icon option. Will also be shown in a tooltip.
+	 */
+	label: string;
 };
 
-export type ToggleGroupControlOptionProps = Omit<
+export type ToggleGroupControlOptionProps = Pick<
 	ToggleGroupControlOptionBaseProps,
-	'children'
+	'value' | 'showTooltip'
 > & {
 	/**
 	 * Label for the option. If needed, the `aria-label` prop can be used in addition
@@ -64,56 +75,66 @@ export type WithToolTipProps = {
 export type ToggleGroupControlProps = Omit<
 	FormElementProps< any >,
 	'defaultValue'
-> & {
-	/**
-	 * Label for the form element.
-	 */
-	label: string;
-	/**
-	 * If true, the label will only be visible to screen readers.
-	 *
-	 * @default false
-	 */
-	hideLabelFromVision?: boolean;
-	/**
-	 * Determines if segments should be rendered with equal widths.
-	 *
-	 * @default false
-	 */
-	isAdaptiveWidth?: boolean;
-	/**
-	 * Renders `ToggleGroupControl` as a (CSS) block element.
-	 *
-	 * @default false
-	 */
-	isBlock?: boolean;
-	/**
-	 * Callback when a segment is selected.
-	 */
-	onChange?: ( value: ReactText | undefined ) => void;
-	/**
-	 * The value of `ToggleGroupControl`
-	 */
-	value?: ReactText;
-	/**
-	 * React children
-	 */
-	children: ReactNode;
-	/**
-	 * If this property is added, a help text will be generated
-	 * using help property as the content.
-	 */
-	help?: ReactNode;
-};
+> &
+	Pick< BaseControlProps, 'help' | '__nextHasNoMarginBottom' > & {
+		/**
+		 * Label for the form element.
+		 */
+		label: string;
+		/**
+		 * If true, the label will only be visible to screen readers.
+		 *
+		 * @default false
+		 */
+		hideLabelFromVision?: boolean;
+		/**
+		 * Determines if segments should be rendered with equal widths.
+		 *
+		 * @default false
+		 */
+		isAdaptiveWidth?: boolean;
+		/**
+		 * Renders `ToggleGroupControl` as a (CSS) block element.
+		 *
+		 * @default false
+		 */
+		isBlock?: boolean;
+		/**
+		 * Style for use with `ToggleGroupControlOptionIcon`s.
+		 *
+		 * @default false
+		 */
+		__experimentalIsIconGroup?: boolean; // TODO: Refactor so this can be private
+		/**
+		 * Callback when a segment is selected.
+		 */
+		onChange?: ( value: ReactText | undefined ) => void;
+		/**
+		 * The value of `ToggleGroupControl`
+		 */
+		value?: ReactText;
+		/**
+		 * The options to render in the `ToggleGroupControl`, using either the `ToggleGroupControlOption` or
+		 * `ToggleGroupControlOptionIcon` components.
+		 */
+		children: ReactNode;
+		/**
+		 * The size variant of the control.
+		 *
+		 * @default 'default'
+		 */
+		size?: 'default' | '__unstable-large';
+	};
 
-export type ToggleGroupControlContextProps = RadioStateReturn & {
-	/**
-	 * Renders `ToggleGroupControl` as a (CSS) block element.
-	 *
-	 * @default false
-	 */
-	isBlock?: boolean;
-};
+export type ToggleGroupControlContextProps = RadioStateReturn &
+	Pick< ToggleGroupControlProps, 'size' > & {
+		/**
+		 * Renders `ToggleGroupControl` as a (CSS) block element.
+		 *
+		 * @default false
+		 */
+		isBlock?: boolean;
+	};
 
 export type ToggleGroupControlBackdropProps = {
 	containerRef: MutableRefObject< HTMLElement | undefined >;

package/src/toolbar/test/index.js

@@ -1,7 +1,7 @@
 /**
  * External dependencies
  */
-import { render } from '@testing-library/react';
+import { render, screen } from '@testing-library/react';
 
 /**
  * Internal dependencies
@@ -12,7 +12,7 @@ import ToolbarButton from '../../toolbar-button';
 describe( 'Toolbar', () => {
 	describe( 'basic rendering', () => {
 		it( 'should render a toolbar with toolbar buttons', () => {
-			const { getByLabelText } = render(
+			render(
 				<Toolbar label="blocks">
 					<ToolbarButton label="control1" />
 					<ToolbarButton label="control2" />
@@ -20,10 +20,10 @@ describe( 'Toolbar', () => {
 			);
 
 			expect(
-				getByLabelText( 'control1', { selector: 'button' } )
+				screen.getByLabelText( 'control1', { selector: 'button' } )
 			).toBeTruthy();
 			expect(
-				getByLabelText( 'control2', { selector: 'button' } )
+				screen.getByLabelText( 'control2', { selector: 'button' } )
 			).toBeTruthy();
 		} );
 	} );

package/src/toolbar-group/test/index.js

@@ -1,7 +1,7 @@
 /**
  * External dependencies
  */
-import { fireEvent, render } from '@testing-library/react';
+import { fireEvent, render, screen } from '@testing-library/react';
 
 /**
  * Internal dependencies
@@ -33,11 +33,9 @@ describe( 'ToolbarGroup', () => {
 				},
 			];
 
-			const { getByLabelText } = render(
-				<ToolbarGroup controls={ controls } />
-			);
+			render( <ToolbarGroup controls={ controls } /> );
 
-			const toolbarButton = getByLabelText( 'WordPress' );
+			const toolbarButton = screen.getByLabelText( 'WordPress' );
 			expect( toolbarButton.getAttribute( 'aria-pressed' ) ).toBe(
 				'false'
 			);
@@ -55,11 +53,9 @@ describe( 'ToolbarGroup', () => {
 				},
 			];
 
-			const { getByLabelText } = render(
-				<ToolbarGroup controls={ controls } />
-			);
+			render( <ToolbarGroup controls={ controls } /> );
 
-			const toolbarButton = getByLabelText( 'WordPress' );
+			const toolbarButton = screen.getByLabelText( 'WordPress' );
 			expect( toolbarButton.getAttribute( 'aria-pressed' ) ).toBe(
 				'true'
 			);
@@ -84,11 +80,11 @@ describe( 'ToolbarGroup', () => {
 				],
 			];
 
-			const { container, getAllByRole } = render(
+			const { container } = render(
 				<ToolbarGroup controls={ controls } />
 			);
 
-			const buttons = getAllByRole( 'button' );
+			const buttons = screen.getAllByRole( 'button' );
 			expect( buttons ).toHaveLength( 2 );
 			expect(
 				container.querySelector( '.has-left-divider button' )
@@ -105,11 +101,9 @@ describe( 'ToolbarGroup', () => {
 					isActive: true,
 				},
 			];
-			const { getByLabelText } = render(
-				<ToolbarGroup controls={ controls } />
-			);
+			render( <ToolbarGroup controls={ controls } /> );
 
-			fireEvent.click( getByLabelText( 'WordPress' ) );
+			fireEvent.click( screen.getByLabelText( 'WordPress' ) );
 			expect( clickHandler ).toHaveBeenCalledTimes( 1 );
 		} );
 	} );

package/src/tools-panel/styles.ts

@@ -9,7 +9,6 @@ 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';
@@ -17,9 +16,12 @@ import { COLORS, CONFIG } from '../utils';
 import { space } from '../ui/utils/space';
 
 const toolsPanelGrid = {
+	columns: ( columns: number ) => css`
+		grid-template-columns: ${ `repeat( ${ columns }, minmax(0, 1fr) )` };
+	`,
 	spacing: css`
-		column-gap: ${ space( 4 ) };
-		row-gap: ${ space( 6 ) };
+		column-gap: ${ space( 2 ) };
+		row-gap: ${ space( 4 ) };
 	`,
 	item: {
 		fullWidth: css`
@@ -28,8 +30,9 @@ const toolsPanelGrid = {
 	},
 };
 
-export const ToolsPanel = css`
-	${ toolsPanelGrid.spacing };
+export const ToolsPanel = ( columns: number ) => css`
+	${ toolsPanelGrid.columns( columns ) }
+	${ toolsPanelGrid.spacing }
 
 	border-top: ${ CONFIG.borderWidth } solid ${ COLORS.gray[ 300 ] };
 	margin-top: -1px;
@@ -46,7 +49,7 @@ export const ToolsPanelWithInnerWrapper = ( columns: number ) => {
 	return css`
 		> div:not( :first-of-type ) {
 			display: grid;
-			grid-template-columns: ${ `repeat( ${ columns }, 1fr )` };
+			${ toolsPanelGrid.columns( columns ) }
 			${ toolsPanelGrid.spacing }
 			${ toolsPanelGrid.item.fullWidth }
 		}
@@ -133,18 +136,6 @@ export const ToolsPanelItem = css`
 			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

@@ -1069,7 +1069,7 @@ describe( 'ToolsPanel', () => {
 
 	describe( 'first and last panel items', () => {
 		it( 'should apply first/last classes to appropriate items', () => {
-			const { container } = render(
+			render(
 				<SlotFillProvider>
 					<ToolsPanelItems>
 						<ToolsPanelItem { ...altControlProps }>
@@ -1113,7 +1113,8 @@ describe( 'ToolsPanel', () => {
 			expect( item3 ).toBeInTheDocument();
 			expect( screen.queryByText( 'Item 4' ) ).not.toBeInTheDocument();
 
-			expect( container ).toMatchSnapshot();
+			expect( item2.parentElement ).toHaveClass( 'first' );
+			expect( item3.parentElement ).toHaveClass( 'last' );
 		} );
 	} );
 } );

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

@@ -30,45 +30,118 @@ 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.
 
+### ToolsPanel Layout
+
+The `ToolsPanel` has a two-column grid layout. By default, `ToolsPanelItem`
+components within the panel are styled to span both columns as this fits the
+majority of use-cases. Most non-control elements, such as help text, will be
+rendered as children of the related control's `ToolsPanelItem` and not require
+additional styling.
+
+Suppose an element is related to multiple controls (e.g. a contrast checker), or
+the panel itself (e.g. a panel description). In that case, these will be
+rendered into the panel without a wrapping `ToolsPanelItem`. They'll then only
+span a single column by default. If this is undesirable, those elements will
+likely need a small style tweak, e.g. `grid-column: 1 / -1;`
+
+The usage example below will illustrate a non-`ToolsPanelItem` description
+paragraph, controls that should display in a single row, and others spanning
+both columns.
+
 ## Usage
 
 ```jsx
+/**
+ * External dependencies
+ */
+import styled from '@emotion/styled';
+
+/**
+ * WordPress dependencies
+ */
 import {
+	__experimentalBoxControl as BoxControl,
 	__experimentalToolsPanel as ToolsPanel,
 	__experimentalToolsPanelItem as ToolsPanelItem,
+	__experimentalUnitControl as UnitControl,
 } from '@wordpress/components';
 import { __ } from '@wordpress/i18n';
 
-import {
-	PaddingEdit,
-	hasPaddingValue,
-	resetPadding,
-	useIsPaddingDisabled,
-} from './padding';
+const PanelDescription = styled.div`
+	grid-column: span 2;
+`;
 
+const SingleColumnItem = styled( ToolsPanelItem )`
+	grid-column: span 1;
+`;
 
-export function DimensionPanel( props ) {
-	const isPaddingDisabled = useIsPaddingDisabled( props );
+export function DimensionPanel() {
+	const [ height, setHeight ] = useState();
+	const [ width, setWidth ] = useState();
+	const [ padding, setPadding ] = useState();
+	const [ margin, setMargin ] = useState();
 
 	const resetAll = () => {
-		// Reset attributes for all block support features in this panel.
+		setHeight( undefined );
+		setWidth( undefined );
+		setPadding( undefined );
+		setMargin( undefined );
 	};
 
 	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 ) }
+			<PanelDescription>
+				Select dimensions or spacing related settings from the
+				menu for additional controls.
+			</PanelDescription>
+			<SingleColumnItem
+				hasValue={ () => !! height }
+				label={ __( 'Height' ) }
+				onDeselect={ () => setHeight( undefined ) }
+				isShownByDefault
+			>
+				<UnitControl
+					label={ __( 'Height' ) }
+					onChange={ setHeight }
+					value={ height }
+				/>
+			</SingleColumnItem>
+			<SingleColumnItem
+				hasValue={ () => !! width }
+				label={ __( 'Width' ) }
+				onDeselect={ () => setWidth( undefined ) }
+				isShownByDefault
+			>
+				<UnitControl
+					label={ __( 'Width' ) }
+					onChange={ setWidth }
+					value={ width }
+				/>
+			</SingleColumnItem>
+			<ToolsPanelItem
+				hasValue={ () => !! padding }
+				label={ __( 'Padding' ) }
+				onDeselect={ () => setPadding( undefined ) }
+			>
+				<BoxControl
 					label={ __( 'Padding' ) }
-					onDeselect={ () => resetPadding( props ) }
-				>
-					<PaddingEdit { ...props } />
-				</ToolsPanelItem>
-			) }
+					onChange={ setPadding }
+					values={ padding }
+					allowReset={ false }
+				/>
+			</ToolsPanelItem>
+			<ToolsPanelItem
+				hasValue={ () => !! margin }
+				label={ __( 'Margin' ) }
+				onDeselect={ () => setMargin( undefined ) }
+			>
+				<BoxControl
+					label={ __( 'Margin' ) }
+					onChange={ setMargin }
+					values={ margin }
+					allowReset={ false }
+				/>
+			</ToolsPanelItem>
 		</ToolsPanel>
 	);
 }

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

@@ -190,7 +190,12 @@ export function useToolsPanel(
 			areAllOptionalControlsHidden &&
 			styles.ToolsPanelHiddenInnerWrapper;
 
-		return cx( styles.ToolsPanel, wrapperStyle, emptyStyle, className );
+		return cx(
+			styles.ToolsPanel( DEFAULT_COLUMNS ),
+			wrapperStyle,
+			emptyStyle,
+			className
+		);
 	}, [
 		areAllOptionalControlsHidden,
 		className,

package/src/tooltip/index.js

@@ -1,8 +1,4 @@
 // @ts-nocheck
-/**
- * External dependencies
- */
-import { includes } from 'lodash';
 
 /**
  * WordPress dependencies
@@ -13,8 +9,9 @@ import {
 	concatChildren,
 	useEffect,
 	useState,
+	useRef,
 } from '@wordpress/element';
-import { useDebounce } from '@wordpress/compose';
+import { useDebounce, useMergeRefs } from '@wordpress/compose';
 
 /**
  * Internal dependencies
@@ -31,29 +28,45 @@ export const TOOLTIP_DELAY = 700;
 
 const eventCatcher = <div className="event-catcher" />;
 
-const getDisabledElement = ( { eventHandlers, child, childrenWithPopover } ) =>
-	cloneElement(
+const getDisabledElement = ( {
+	eventHandlers,
+	child,
+	childrenWithPopover,
+	mergedRefs,
+} ) => {
+	return cloneElement(
 		<span className="disabled-element-wrapper">
 			{ cloneElement( eventCatcher, eventHandlers ) }
 			{ cloneElement( child, {
 				children: childrenWithPopover,
+				ref: mergedRefs,
 			} ) }
 		</span>,
-		eventHandlers
+		{ ...eventHandlers }
 	);
+};
 
-const getRegularElement = ( { child, eventHandlers, childrenWithPopover } ) =>
-	cloneElement( child, {
+const getRegularElement = ( {
+	child,
+	eventHandlers,
+	childrenWithPopover,
+	mergedRefs,
+} ) => {
+	return cloneElement( child, {
 		...eventHandlers,
 		children: childrenWithPopover,
+		ref: mergedRefs,
 	} );
+};
 
 const addPopoverToGrandchildren = ( {
+	anchorRef,
 	grandchildren,
 	isOver,
+	offset,
 	position,
-	text,
 	shortcut,
+	text,
 } ) =>
 	concatChildren(
 		grandchildren,
@@ -64,7 +77,8 @@ const addPopoverToGrandchildren = ( {
 				className="components-tooltip"
 				aria-hidden="true"
 				animate={ false }
-				offset={ 12 }
+				offset={ offset }
+				anchorRef={ anchorRef }
 				__unstableShift
 			>
 				{ text }
@@ -111,7 +125,23 @@ function Tooltip( props ) {
 	const [ isOver, setIsOver ] = useState( false );
 	const delayedSetIsOver = useDebounce( setIsOver, delay );
 
+	// Create a reference to the Tooltip's child, to be passed to the Popover
+	// so that the Tooltip can be correctly positioned. Also, merge with the
+	// existing ref for the first child, so that its ref is preserved.
+	const childRef = useRef( null );
+	const existingChildRef = Children.toArray( children )[ 0 ]?.ref;
+	const mergedChildRefs = useMergeRefs( [ childRef, existingChildRef ] );
+
 	const createMouseDown = ( event ) => {
+		// In firefox, the mouse down event is also fired when the select
+		// list is chosen.
+		// Cancel further processing because re-rendering of child components
+		// causes onChange to be triggered with the old value.
+		// See https://github.com/WordPress/gutenberg/pull/42483
+		if ( event.target.tagName === 'OPTION' ) {
+			return;
+		}
+
 		// Preserve original child callback behavior.
 		emitToChild( children, 'onMouseDown', event );
 
@@ -124,6 +154,15 @@ function Tooltip( props ) {
 	};
 
 	const createMouseUp = ( event ) => {
+		// In firefox, the mouse up event is also fired when the select
+		// list is chosen.
+		// Cancel further processing because re-rendering of child components
+		// causes onChange to be triggered with the old value.
+		// See https://github.com/WordPress/gutenberg/pull/42483
+		if ( event.target.tagName === 'OPTION' ) {
+			return;
+		}
+
 		emitToChild( children, 'onMouseUp', event );
 		document.removeEventListener( 'mouseup', cancelIsMouseDown );
 		setIsMouseDown( false );
@@ -150,7 +189,7 @@ function Tooltip( props ) {
 			// Mouse events behave unreliably in React for disabled elements,
 			// firing on mouseenter but not mouseleave.  Further, the default
 			// behavior for disabled elements in some browsers is to ignore
-			// mouse events. Don't bother trying to to handle them.
+			// mouse events. Don't bother trying to handle them.
 			//
 			// See: https://github.com/facebook/react/issues/4251
 			if ( event.currentTarget.disabled ) {
@@ -168,7 +207,7 @@ function Tooltip( props ) {
 			// quickly blur/mouseleave before delayedSetIsOver is called.
 			delayedSetIsOver.cancel();
 
-			const _isOver = includes( [ 'focus', 'mouseenter' ], event.type );
+			const _isOver = [ 'focus', 'mouseenter' ].includes( event.type );
 			if ( _isOver === isOver ) {
 				return;
 			}
@@ -214,10 +253,12 @@ function Tooltip( props ) {
 		: getRegularElement;
 
 	const popoverData = {
+		anchorRef: childRef,
 		isOver,
+		offset: 4,
 		position,
-		text,
 		shortcut,
+		text,
 	};
 	const childrenWithPopover = addPopoverToGrandchildren( {
 		grandchildren,
@@ -228,6 +269,7 @@ function Tooltip( props ) {
 		child,
 		eventHandlers,
 		childrenWithPopover,
+		mergedRefs: mergedChildRefs,
 	} );
 }