@wordpress/components 19.13.0 → 19.16.0

package/src/toggle-group-control/stories/index.js

@@ -23,6 +23,12 @@ import Button from '../../button';
 export default {
 	component: ToggleGroupControl,
 	title: 'Components (Experimental)/ToggleGroupControl',
+	argTypes: {
+		size: {
+			control: 'select',
+			options: [ 'default', '__unstable-large' ],
+		},
+	},
 	parameters: {
 		knobs: { disable: false },
 	},
@@ -33,7 +39,7 @@ const KNOBS_GROUPS = {
 	ToggleGroupControlOption: 'ToggleGroupControlOption',
 };
 
-const _default = ( { options } ) => {
+const _default = ( { options, ...props } ) => {
 	const [ value, setValue ] = useState( options[ 0 ].value );
 	const label = text(
 		`${ KNOBS_GROUPS.ToggleGroupControl }: label`,
@@ -87,6 +93,7 @@ const _default = ( { options } ) => {
 	return (
 		<View>
 			<ToggleGroupControl
+				{ ...props }
 				onChange={ setValue }
 				value={ value }
 				label={ label }
@@ -109,6 +116,7 @@ Default.args = {
 		{ value: 'right', label: 'Right' },
 		{ value: 'justify', label: 'Justify' },
 	],
+	size: 'default',
 };
 
 export const WithTooltip = _default.bind( {} );
@@ -130,10 +138,11 @@ WithAriaLabel.args = {
 	],
 };
 
-export const WithIcons = () => {
+export const WithIcons = ( props ) => {
 	const [ state, setState ] = useState();
 	return (
 		<ToggleGroupControl
+			{ ...props }
 			onChange={ setState }
 			value={ state }
 			label={ 'With icons' }
@@ -154,8 +163,11 @@ export const WithIcons = () => {
 		</ToggleGroupControl>
 	);
 };
+WithIcons.args = {
+	...Default.args,
+};
 
-export const WithReset = () => {
+export const WithReset = ( props ) => {
 	const [ alignState, setAlignState ] = useState();
 	const aligns = [ 'Left', 'Center', 'Right' ];
 	const alignOptions = aligns.map( ( key, index ) => (
@@ -172,6 +184,7 @@ export const WithReset = () => {
 	return (
 		<View>
 			<ToggleGroupControl
+				{ ...props }
 				onChange={ setAlignState }
 				value={ alignState }
 				label={ 'Toggle Group Control' }
@@ -185,3 +198,6 @@ export const WithReset = () => {
 		</View>
 	);
 };
+WithReset.args = {
+	...Default.args,
+};

package/src/toggle-group-control/test/__snapshots__/index.js.snap

@@ -28,12 +28,12 @@ exports[`ToggleGroupControl should render correctly with icons 1`] = `
   display: -webkit-inline-flex;
   display: -ms-inline-flexbox;
   display: inline-flex;
-  min-height: 36px;
   min-width: 0;
   padding: 2px;
   position: relative;
   -webkit-transition: -webkit-transform 100ms linear;
   transition: transform 100ms linear;
+  min-height: 36px;
 }
 
 @media ( prefers-reduced-motion: reduce ) {
@@ -167,7 +167,7 @@ exports[`ToggleGroupControl should render correctly with icons 1`] = `
     </div>
     <div
       aria-label="Test Toggle Group Control"
-      class="medium components-toggle-group-control emotion-6 emotion-7"
+      class="components-toggle-group-control emotion-6 emotion-7"
       data-wp-c16t="true"
       data-wp-component="ToggleGroupControl"
       id="toggle-group-control-1"
@@ -281,12 +281,12 @@ exports[`ToggleGroupControl should render correctly with text options 1`] = `
   display: -webkit-inline-flex;
   display: -ms-inline-flexbox;
   display: inline-flex;
-  min-height: 36px;
   min-width: 0;
   padding: 2px;
   position: relative;
   -webkit-transition: -webkit-transform 100ms linear;
   transition: transform 100ms linear;
+  min-height: 36px;
 }
 
 @media ( prefers-reduced-motion: reduce ) {
@@ -393,7 +393,7 @@ exports[`ToggleGroupControl should render correctly with text options 1`] = `
     </div>
     <div
       aria-label="Test Toggle Group Control"
-      class="medium components-toggle-group-control emotion-6 emotion-7"
+      class="components-toggle-group-control emotion-6 emotion-7"
       data-wp-c16t="true"
       data-wp-component="ToggleGroupControl"
       id="toggle-group-control-0"

package/src/toggle-group-control/toggle-group-control/component.tsx

@@ -47,6 +47,7 @@ function ToggleGroupControl(
 		hideLabelFromVision = false,
 		help,
 		onChange = noop,
+		size = 'default',
 		value,
 		children,
 		...otherProps
@@ -83,12 +84,11 @@ function ToggleGroupControl(
 	const classes = useMemo(
 		() =>
 			cx(
-				styles.ToggleGroupControl,
+				styles.ToggleGroupControl( { size } ),
 				isBlock && styles.block,
-				'medium',
 				className
 			),
-		[ className, cx, isBlock ]
+		[ className, cx, isBlock, size ]
 	);
 	return (
 		<BaseControl help={ help }>

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

@@ -8,19 +8,26 @@ import styled from '@emotion/styled';
  * Internal dependencies
  */
 import { CONFIG, COLORS, reduceMotion } from '../../utils';
+import type { ToggleGroupControlProps } from '../types';
 
-export const ToggleGroupControl = css`
+export const ToggleGroupControl = ( {
+	size,
+}: {
+	size: NonNullable< ToggleGroupControlProps[ 'size' ] >;
+} ) => css`
 	background: ${ COLORS.ui.background };
 	border: 1px solid;
 	border-color: ${ COLORS.ui.border };
 	border-radius: ${ CONFIG.controlBorderRadius };
 	display: inline-flex;
-	min-height: ${ CONFIG.controlHeight };
 	min-width: 0;
 	padding: 2px;
 	position: relative;
 	transition: transform ${ CONFIG.transitionDurationFastest } linear;
 	${ reduceMotion( 'transition' ) }
+
+	${ toggleGroupControlSize( size ) }
+
 	&:hover {
 		border-color: ${ COLORS.ui.borderHover };
 	}
@@ -33,6 +40,19 @@ export const ToggleGroupControl = css`
 	}
 `;
 
+export const toggleGroupControlSize = (
+	size: NonNullable< ToggleGroupControlProps[ 'size' ] >
+) => {
+	const heights = {
+		default: '36px',
+		'__unstable-large': '40px',
+	};
+
+	return css`
+		min-height: ${ heights[ size ] };
+	`;
+};
+
 export const block = css`
 	display: flex;
 	width: 100%;

package/src/toggle-group-control/toggle-group-control-option-base/styles.ts

@@ -69,7 +69,3 @@ export const ButtonContentView = styled.div`
 export const separatorActive = css`
 	background: transparent;
 `;
-
-export const medium = css`
-	min-height: ${ CONFIG.controlHeight };
-`;

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

@@ -104,6 +104,12 @@ export type ToggleGroupControlProps = Omit<
 	 * using help property as the content.
 	 */
 	help?: ReactNode;
+	/**
+	 * The size variant of the control.
+	 *
+	 * @default 'default'
+	 */
+	size?: 'default' | '__unstable-large';
 };
 
 export type ToggleGroupControlContextProps = RadioStateReturn & {

package/src/toolbar-group/index.js

@@ -2,7 +2,6 @@
  * External dependencies
  */
 import classnames from 'classnames';
-import { flatMap } from 'lodash';
 
 /**
  * WordPress dependencies
@@ -92,7 +91,7 @@ function ToolbarGroup( {
 
 	return (
 		<ToolbarGroupContainer className={ finalClassName } { ...props }>
-			{ flatMap( controlSets, ( controlSet, indexOfSet ) =>
+			{ controlSets?.flatMap( ( controlSet, indexOfSet ) =>
 				controlSet.map( ( control, indexOfControl ) => (
 					<ToolbarButton
 						key={ [ indexOfSet, indexOfControl ].join() }

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/tooltip/index.js

@@ -13,8 +13,9 @@ import {
 	concatChildren,
 	useEffect,
 	useState,
+	useRef,
 } from '@wordpress/element';
-import { useDebounce } from '@wordpress/compose';
+import { useDebounce, useMergeRefs } from '@wordpress/compose';
 
 /**
  * Internal dependencies
@@ -31,29 +32,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 +81,8 @@ const addPopoverToGrandchildren = ( {
 				className="components-tooltip"
 				aria-hidden="true"
 				animate={ false }
-				offset={ 12 }
+				offset={ offset }
+				anchorRef={ anchorRef }
 				__unstableShift
 			>
 				{ text }
@@ -111,7 +129,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 +158,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 +193,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 ) {
@@ -214,10 +257,12 @@ function Tooltip( props ) {
 		: getRegularElement;
 
 	const popoverData = {
+		anchorRef: childRef,
 		isOver,
+		offset: 4,
 		position,
-		text,
 		shortcut,
+		text,
 	};
 	const childrenWithPopover = addPopoverToGrandchildren( {
 		grandchildren,
@@ -228,6 +273,7 @@ function Tooltip( props ) {
 		child,
 		eventHandlers,
 		childrenWithPopover,
+		mergedRefs: mergedChildRefs,
 	} );
 }
 

package/src/tooltip/stories/index.js

@@ -35,19 +35,34 @@ export const _default = () => {
 	const position = select( 'Position', positionOptions, 'top center' );
 	const delay = number( 'Delay', 700 );
 	return (
-		<Tooltip text={ tooltipText } position={ position } delay={ delay }>
-			<div
-				style={ {
-					margin: '50px auto',
-					width: '200px',
-					padding: '20px',
-					textAlign: 'center',
-					border: '1px solid #ccc',
-				} }
-			>
-				Hover for more information
-			</div>
-		</Tooltip>
+		<>
+			<Tooltip text={ tooltipText } position={ position } delay={ delay }>
+				<div
+					style={ {
+						margin: '50px auto',
+						width: '200px',
+						padding: '20px',
+						textAlign: 'center',
+						border: '1px solid #ccc',
+					} }
+				>
+					Hover for more information
+				</div>
+			</Tooltip>
+			<Tooltip text={ tooltipText } position={ position } delay={ delay }>
+				<div
+					style={ {
+						margin: '50px auto',
+						width: 'min-content',
+						padding: '4px',
+						textAlign: 'center',
+						border: '1px solid #ccc',
+					} }
+				>
+					Small target
+				</div>
+			</Tooltip>
+		</>
 	);
 };
 

package/src/tooltip/style.scss

@@ -2,7 +2,7 @@
 	z-index: z-index(".components-tooltip");
 
 	.components-popover__content {
-		min-width: 0;
+		min-width: min-content;
 	}
 }
 

package/src/tree-select/index.tsx

@@ -1,7 +1,7 @@
 /**
  * External dependencies
  */
-import { unescape as unescapeString, repeat, flatMap, compact } from 'lodash';
+import { unescape as unescapeString } from 'lodash';
 
 /**
  * WordPress dependencies
@@ -11,14 +11,14 @@ import { useMemo } from '@wordpress/element';
  * Internal dependencies
  */
 import { SelectControl } from '../select-control';
-import type { TreeSelectProps, Tree, SelectOptions } from './types';
+import type { TreeSelectProps, Tree, SelectOptions, Truthy } from './types';
 
 function getSelectOptions( tree: Tree[], level = 0 ): SelectOptions {
-	return flatMap( tree, ( treeNode ) => [
+	return tree.flatMap( ( treeNode ) => [
 		{
 			value: treeNode.id,
 			label:
-				repeat( '\u00A0', level * 3 ) + unescapeString( treeNode.name ),
+				'\u00A0'.repeat( level * 3 ) + unescapeString( treeNode.name ),
 		},
 		...getSelectOptions( treeNode.children || [], level + 1 ),
 	] );
@@ -72,6 +72,7 @@ function getSelectOptions( tree: Tree[], level = 0 ): SelectOptions {
  * }
  * ```
  */
+
 export function TreeSelect( {
 	label,
 	noOptionLabel,
@@ -81,10 +82,10 @@ export function TreeSelect( {
 	...props
 }: TreeSelectProps ) {
 	const options = useMemo( () => {
-		return compact( [
+		return [
 			noOptionLabel && { value: '', label: noOptionLabel },
 			...getSelectOptions( tree ),
-		] );
+		].filter( < T, >( option: T ): option is Truthy< T > => !! option );
 	}, [ noOptionLabel, tree ] );
 
 	return (

package/src/tree-select/types.ts

@@ -9,6 +9,10 @@ import type { ComponentProps } from 'react';
 import type SelectControl from '../select-control';
 import type { SelectControlProps } from '../select-control/types';
 
+export type Truthy< T > = T extends false | '' | 0 | null | undefined
+	? never
+	: T;
+
 export type SelectOptions = Required<
 	ComponentProps< typeof SelectControl >
 >[ 'options' ];

package/src/truncate/README.md

@@ -24,15 +24,14 @@ function Example() {
 
 ## Props
 
-##### ellipsis
+##### `ellipsis`: `string`
 
-**Type**: `string`
+The ellipsis string when truncating the text by the `limit` prop's value.
 
-The ellipsis string when `truncate` is set.
+-   Required: No
+-   Default: `…`
 
-##### ellipsizeMode
-
-**Type**: `"auto"`,`"head"`,`"tail"`,`"middle"`
+##### `ellipsizeMode`: `'auto' | 'head' | 'tail' | 'middle' | 'none'`
 
 Determines where to truncate. For example, we can truncate text right in the middle. To do this, we need to set `ellipsizeMode` to `middle` and a text `limit`.
 
@@ -41,17 +40,22 @@ Determines where to truncate. For example, we can truncate text right in the mid
 -   `middle`: Trims content in the middle. Requires a `limit`.
 -   `tail`: Trims content at the end. Requires a `limit`.
 
-##### limit
+-   Required: No
+-   Default: `auto`
+
+##### `limit`: `number`
 
-**Type**: `number`
+Determines the max number of characters to be displayed before the rest of the text gets truncated. Requires `ellipsizeMode` to assume values different from `auto` and `none`.
 
-Determines the max characters when `truncate` is set.
+-   Required: No
+-   Default: `0`
 
-##### numberOfLines
+##### `numberOfLines`: `number`
 
-**Type**: `number`
+Clamps the text content to the specified `numberOfLines`, adding an ellipsis at the end. Note: this feature ignores the value of the `ellipsis` prop and always displays the default `…` ellipsis.
 
-Clamps the text content to the specifiec `numberOfLines`, adding the `ellipsis` at the end.
+-   Required: No
+-   Default: `0`
 
 ```jsx
 import { __experimentalTruncate as Truncate } from '@wordpress/components';