@wordpress/components 19.7.0 → 19.8.2

package/src/toggle-group-control/toggle-group-control-option-base/README.md

@@ -0,0 +1,27 @@
+# `ToggleGroupControlOptionBase`
+
+<div class="callout callout-alert">
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+</div>
+
+`ToggleGroupControlOptionBase` is a form component and is meant to be used as an internal, generic component for any children of [`ToggleGroupControl`](<(/packages/components/src/toggle-group-control/toggle-group-control/README.md)>).
+
+## Props
+
+### `children`: `ReactNode`
+
+The children elements.
+
+-   Required: Yes
+
+### `value`: `string | number`
+
+The value of the `ToggleGroupControlOptionBase`.
+
+-   Required: Yes
+
+### `showTooltip`: `boolean`
+
+Whether to show a tooltip when hovering over the option. The tooltip will only show if a label for it is provided using the `aria-label` prop.
+
+-   Required: No

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

@@ -0,0 +1,129 @@
+/**
+ * External dependencies
+ */
+import type { ForwardedRef } from 'react';
+// eslint-disable-next-line no-restricted-imports
+import { Radio } from 'reakit';
+
+/**
+ * WordPress dependencies
+ */
+import { useInstanceId } from '@wordpress/compose';
+
+/**
+ * Internal dependencies
+ */
+import {
+	contextConnect,
+	useContextSystem,
+	WordPressComponentProps,
+} from '../../ui/context';
+import type {
+	ToggleGroupControlOptionBaseProps,
+	WithToolTipProps,
+} from '../types';
+import { useToggleGroupControlContext } from '../context';
+import * as styles from './styles';
+import { useCx } from '../../utils/hooks';
+import Tooltip from '../../tooltip';
+
+const { ButtonContentView, LabelView } = styles;
+
+const WithToolTip = ( { showTooltip, text, children }: WithToolTipProps ) => {
+	if ( showTooltip && text ) {
+		return (
+			<Tooltip text={ text } position="top center">
+				{ children }
+			</Tooltip>
+		);
+	}
+	return <>{ children }</>;
+};
+
+function ToggleGroupControlOptionBase(
+	props: WordPressComponentProps<
+		ToggleGroupControlOptionBaseProps,
+		'button',
+		false
+	>,
+	forwardedRef: ForwardedRef< any >
+) {
+	const toggleGroupControlContext = useToggleGroupControlContext();
+	const id = useInstanceId(
+		ToggleGroupControlOptionBase,
+		toggleGroupControlContext.baseId || 'toggle-group-control-option-base'
+	) as string;
+	const buttonProps = useContextSystem(
+		{ ...props, id },
+		'ToggleGroupControlOptionBase'
+	);
+	const {
+		className,
+		isBlock = false,
+		value,
+		children,
+		showTooltip = false,
+		...radioProps
+	} = {
+		...toggleGroupControlContext,
+		...buttonProps,
+	};
+
+	const isActive = radioProps.state === value;
+	const cx = useCx();
+	const labelViewClasses = cx( isBlock && styles.labelBlock );
+	const classes = cx(
+		styles.buttonView,
+		className,
+		isActive && styles.buttonActive
+	);
+
+	return (
+		<LabelView className={ labelViewClasses } data-active={ isActive }>
+			<WithToolTip
+				showTooltip={ showTooltip }
+				text={ radioProps[ 'aria-label' ] }
+			>
+				<Radio
+					{ ...radioProps }
+					as="button"
+					aria-label={ radioProps[ 'aria-label' ] }
+					className={ classes }
+					data-value={ value }
+					ref={ forwardedRef }
+					value={ value }
+				>
+					<ButtonContentView>{ children }</ButtonContentView>
+				</Radio>
+			</WithToolTip>
+		</LabelView>
+	);
+}
+
+/**
+ * `ToggleGroupControlOptionBase` is a form component and is meant to be used as an internal,
+ * generic component for any children of `ToggleGroupControl`.
+ *
+ * @example
+ * ```jsx
+ * import {
+ *   __experimentalToggleGroupControl as ToggleGroupControl,
+ *   __experimentalToggleGroupControlOptionBase as ToggleGroupControlOptionBase,
+ * } from '@wordpress/components';
+ *
+ * function Example() {
+ *   return (
+ *     <ToggleGroupControl label="my label" value="vertical" isBlock>
+ *       <ToggleGroupControlOption value="horizontal" label="Horizontal" />
+ *       <ToggleGroupControlOption value="vertical" label="Vertical" />
+ *     </ToggleGroupControl>
+ *   );
+ * }
+ * ```
+ */
+const ConnectedToggleGroupControlOptionBase = contextConnect(
+	ToggleGroupControlOptionBase,
+	'ToggleGroupControlOptionBase'
+);
+
+export default ConnectedToggleGroupControlOptionBase;

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

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

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

@@ -27,6 +27,7 @@ export const buttonView = css`
 	border: none;
 	border-radius: ${ CONFIG.controlBorderRadius };
 	color: ${ COLORS.gray[ 700 ] };
+	fill: currentColor;
 	cursor: pointer;
 	display: flex;
 	font-family: inherit;
@@ -55,7 +56,9 @@ export const buttonView = css`
 
 export const buttonActive = css`
 	color: ${ COLORS.white };
-	background-color: ${ COLORS.gray[ 900 ] };
+	&:active {
+		background: transparent;
+	}
 `;
 
 export const ButtonContentView = styled.div`

package/src/toggle-group-control/toggle-group-control-option-icon/README.md

@@ -0,0 +1,56 @@
+# `ToggleGroupControlOptionIcon`
+
+<div class="callout callout-alert">
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+</div>
+
+`ToggleGroupControlOptionIcon` is a form component which is meant to be used as a child of [`ToggleGroupControl`] and displays an icon(<(/packages/components/src/toggle-group-control/toggle-group-control/README.md)>).
+
+## Usage
+
+```js
+import {
+	__experimentalToggleGroupControl as ToggleGroupControl,
+	__experimentalToggleGroupControlOptionIcon as ToggleGroupControlOptionIcon,
+} from '@wordpress/components';
+import { formatLowercase, formatUppercase } from '@wordpress/icons';
+
+function Example() {
+	return (
+		<ToggleGroupControl label="my label" value="lowercase" isBlock>
+			<ToggleGroupControlOptionIcon
+				value="uppercase"
+				icon={ formatUppercase }
+				showTooltip={ true }
+				aria-label="Uppercase"
+			/>
+			<ToggleGroupControlOptionIcon
+				value="lowercase"
+				icon={ formatLowercase }
+				showTooltip={ true }
+				aria-label="Lowercase"
+			/>
+		</ToggleGroupControl>
+	);
+}
+```
+
+## Props
+
+### `value`: `string | number`
+
+The value of the `ToggleGroupControlOption`.
+
+-   Required: Yes
+
+### `icon`: `WPComponent`
+
+Icon displayed as the content of the option. Usually one of the icons from the `@wordpress/icons` package, or a custom React `<svg>` icon.
+
+-   Required: Yes
+
+### `showTooltip`: `boolean`
+
+Whether to show a tooltip when hovering over the option. The tooltip will only show if a label for it is provided using the `aria-label` prop.
+
+-   Required: No

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

@@ -0,0 +1,56 @@
+/**
+ * WordPress dependencies
+ */
+import { Icon } from '@wordpress/icons';
+
+/**
+ * Internal dependencies
+ */
+import type { WordPressComponentProps } from '../../ui/context';
+import type { ToggleGroupControlOptionIconProps } from '../types';
+import { ToggleGroupControlOptionBase } from '../toggle-group-control-option-base';
+
+export default function ToggleGroupControlOptionIcon(
+	props: WordPressComponentProps<
+		ToggleGroupControlOptionIconProps,
+		'button',
+		false
+	>
+) {
+	const { icon, ...restProps } = props;
+	return (
+		<ToggleGroupControlOptionBase { ...restProps }>
+			<Icon icon={ icon } />
+		</ToggleGroupControlOptionBase>
+	);
+}
+
+/**
+ * `ToggleGroupControlOptionIcon` is a form component which is meant to be used as a
+ * child of `ToggleGroupControl` and displays an icon.
+ *
+ * @example
+ * ```jsx
+ *
+ * import {
+ *	__experimentalToggleGroupControl as ToggleGroupControl,
+ *	__experimentalToggleGroupControlOptionIcon as ToggleGroupControlOptionIcon,
+ * from '@wordpress/components';
+ * import { formatLowercase, formatUppercase } from '@wordpress/icons';
+ *
+ * function Example() {
+ *	return (
+ *		<ToggleGroupControl label="my label" value="vertical" isBlock>
+ *			<ToggleGroupControlOptionIcon
+ *				value="uppercase"
+ *				icon={ formatUppercase }
+ *			/>
+ *			<ToggleGroupControlOptionIcon
+ *				value="lowercase"
+ *				icon={ formatLowercase }
+ *			/>
+ *		</ToggleGroupControl>
+ *	);
+ * }
+ ** ```
+ */

package/src/toggle-group-control/toggle-group-control-option-icon/index.ts

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

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

@@ -1,7 +1,7 @@
 /**
  * External dependencies
  */
-import type { ReactNode, ReactText } from 'react';
+import type { MutableRefObject, ReactNode, ReactText } from 'react';
 // eslint-disable-next-line no-restricted-imports
 import type { RadioStateReturn } from 'reakit';
 
@@ -10,13 +10,9 @@ import type { RadioStateReturn } from 'reakit';
  */
 import type { FormElementProps } from '../utils/types';
 
-export type ToggleGroupControlOptionProps = {
+export type ToggleGroupControlOptionBaseProps = {
+	children: ReactNode;
 	value: ReactText;
-	/**
-	 * Label for the option. If needed, the `aria-label` prop can be used in addition
-	 * to specify a different label for assistive technologies.
-	 */
-	label: string;
 	/**
 	 * Whether to display a Tooltip for the control option. If set to `true`, the tooltip will
 	 * show the aria-label or the label prop text.
@@ -26,6 +22,28 @@ export type ToggleGroupControlOptionProps = {
 	showTooltip?: boolean;
 };
 
+export type ToggleGroupControlOptionIconProps = Omit<
+	ToggleGroupControlOptionBaseProps,
+	'children'
+> & {
+	/**
+	 * 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;
+};
+
+export type ToggleGroupControlOptionProps = Omit<
+	ToggleGroupControlOptionBaseProps,
+	'children'
+> & {
+	/**
+	 * Label for the option. If needed, the `aria-label` prop can be used in addition
+	 * to specify a different label for assistive technologies.
+	 */
+	label: string;
+};
+
 export type WithToolTipProps = {
 	/**
 	 * React children
@@ -34,7 +52,7 @@ export type WithToolTipProps = {
 	/**
 	 * Label for the Tooltip component.
 	 */
-	text: string;
+	text?: string;
 	/**
 	 * Whether to wrap the control option in a Tooltip component.
 	 *
@@ -96,3 +114,10 @@ export type ToggleGroupControlContextProps = RadioStateReturn & {
 	 */
 	isBlock?: boolean;
 };
+
+export type ToggleGroupControlBackdropProps = {
+	containerRef: MutableRefObject< HTMLElement | undefined >;
+	containerWidth?: number | null;
+	isAdaptiveWidth?: boolean;
+	state?: any;
+};

package/src/toolbar-dropdown-menu/index.js

@@ -19,7 +19,7 @@ function ToolbarDropdownMenu( props, ref ) {
 
 	// ToobarItem will pass all props to the render prop child, which will pass
 	// all props to the toggle of DropdownMenu. This means that ToolbarDropdownMenu
-	// has the same API as DrpodownMenu.
+	// has the same API as DropdownMenu.
 	return (
 		<ToolbarItem ref={ ref } { ...props.toggleProps }>
 			{ ( toolbarItemProps ) => (

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

@@ -89,15 +89,15 @@ exports[`ToolsPanel first and last panel items should apply first/last classes t
   max-width: 100%;
 }
 
-.emotion-6.emotion-6 .e1puf3u4 {
+.emotion-6.emotion-6 .ej5x27r4 {
   margin-bottom: 0;
 }
 
-.emotion-6.emotion-6 .e1puf3u4 .e1puf3u3:last-child {
+.emotion-6.emotion-6 .ej5x27r4 .ej5x27r3:last-child {
   margin-bottom: 0;
 }
 
-.emotion-6 .e1puf3u1 {
+.emotion-6 .ej5x27r1 {
   margin-bottom: 0;
 }
 
@@ -106,7 +106,7 @@ exports[`ToolsPanel first and last panel items should apply first/last classes t
 }
 
 .emotion-6 .components-custom-select-control__label,
-.emotion-6 .e1puf3u2 {
+.emotion-6 .ej5x27r2 {
   line-height: 1.4em;
 }
 
@@ -121,15 +121,15 @@ exports[`ToolsPanel first and last panel items should apply first/last classes t
   max-width: 100%;
 }
 
-.emotion-8.emotion-8 .e1puf3u4 {
+.emotion-8.emotion-8 .ej5x27r4 {
   margin-bottom: 0;
 }
 
-.emotion-8.emotion-8 .e1puf3u4 .e1puf3u3:last-child {
+.emotion-8.emotion-8 .ej5x27r4 .ej5x27r3:last-child {
   margin-bottom: 0;
 }
 
-.emotion-8 .e1puf3u1 {
+.emotion-8 .ej5x27r1 {
   margin-bottom: 0;
 }
 
@@ -138,7 +138,7 @@ exports[`ToolsPanel first and last panel items should apply first/last classes t
 }
 
 .emotion-8 .components-custom-select-control__label,
-.emotion-8 .e1puf3u2 {
+.emotion-8 .ej5x27r2 {
   line-height: 1.4em;
 }
 

package/src/unit-control/README.md

@@ -61,6 +61,12 @@ The position of the label (`top`, `side`, `bottom`, or `edge`).
 
 -   Required: No
 
+### `onBlur`: `FocusEventHandler< HTMLInputElement | HTMLSelectElement >`
+
+Callback invoked when either the quantity or unit inputs fire the `blur` event.
+
+-   Required: No
+
 ### `onChange`: `UnitControlOnChangeCallback`
 
 Callback when the `value` changes.

package/src/unit-control/index.tsx

@@ -61,6 +61,7 @@ function UnforwardedUnitControl(
 		unit: unitProp,
 		units: unitsProp = CSS_UNITS,
 		value: valueProp,
+		onBlur: onBlurProp,
 		...props
 	} = unitControlProps;
 
@@ -187,7 +188,10 @@ function UnforwardedUnitControl(
 		}
 	};
 
-	const handleOnBlur: FocusEventHandler< HTMLInputElement > = mayUpdateUnit;
+	const handleOnBlur: FocusEventHandler< HTMLInputElement > = ( event ) => {
+		mayUpdateUnit( event );
+		onBlurProp?.( event );
+	};
 
 	const handleOnKeyDown = ( event: KeyboardEvent< HTMLInputElement > ) => {
 		const { key } = event;
@@ -242,6 +246,7 @@ function UnforwardedUnitControl(
 			size={ size }
 			unit={ unit }
 			units={ units }
+			onBlur={ onBlurProp }
 		/>
 	) : null;
 

package/src/unit-control/test/index.js

@@ -220,6 +220,91 @@ describe( 'UnitControl', () => {
 			expect( input.value ).toBe( '50' );
 			expect( state ).toBe( 50 );
 		} );
+
+		it( 'should run onBlur callback when quantity input is blurred', async () => {
+			let state = '33%';
+			const onChangeSpy = jest.fn();
+			const onBlurSpy = jest.fn();
+			const setState = ( nextState ) => {
+				onChangeSpy( nextState );
+				state = nextState;
+			};
+
+			const { user } = render(
+				<>
+					<button>Click me</button>
+					<UnitControl
+						value={ state }
+						onChange={ setState }
+						onBlur={ onBlurSpy }
+					/>
+				</>
+			);
+
+			const input = getInput();
+			await user.clear( input );
+			await user.type( input, '41' );
+
+			await waitFor( () =>
+				expect( onChangeSpy ).toHaveBeenCalledTimes( 3 )
+			);
+			expect( onChangeSpy ).toHaveBeenLastCalledWith( '41%' );
+
+			// Clicking on the button should cause the `onBlur` callback to fire.
+			const button = screen.getByRole( 'button' );
+			await user.click( button );
+
+			await waitFor( () =>
+				expect( onBlurSpy ).toHaveBeenCalledTimes( 1 )
+			);
+		} );
+
+		it( 'should invoke onChange and onUnitChange callbacks when isPressEnterToChange is true and the component is blurred with an uncommitted value', async () => {
+			let state = '15px';
+
+			const onUnitChangeSpy = jest.fn();
+			const onChangeSpy = jest.fn();
+
+			const setState = ( nextState ) => {
+				onChangeSpy( nextState );
+				state = nextState;
+			};
+
+			const { user } = render(
+				<>
+					<button>Click me</button>
+					<UnitControl
+						value={ state }
+						onChange={ setState }
+						onUnitChange={ onUnitChangeSpy }
+						isPressEnterToChange
+					/>
+				</>
+			);
+
+			const input = getInput();
+			await user.clear( input );
+			await user.type( input, '41vh' );
+
+			// This is because `isPressEnterToChange` is `true`
+			expect( onChangeSpy ).not.toHaveBeenCalled();
+
+			// Clicking on the button should cause the `onBlur` callback to fire.
+			const button = screen.getByRole( 'button' );
+			await user.click( button );
+
+			await waitFor( () =>
+				expect( onChangeSpy ).toHaveBeenCalledTimes( 1 )
+			);
+
+			expect( onChangeSpy ).toHaveBeenLastCalledWith( '41vh' );
+
+			expect( onUnitChangeSpy ).toHaveBeenCalledTimes( 1 );
+			expect( onUnitChangeSpy ).toHaveBeenLastCalledWith(
+				'vh',
+				expect.anything()
+			);
+		} );
 	} );
 
 	describe( 'Unit', () => {
@@ -384,6 +469,41 @@ describe( 'UnitControl', () => {
 
 			expect( select ).toHaveValue( 'vmax' );
 		} );
+
+		it( 'should run onBlur callback when the unit select is blurred', async () => {
+			const onUnitChangeSpy = jest.fn();
+			const onBlurSpy = jest.fn();
+
+			const { user } = render(
+				<>
+					<button>Click me</button>
+					<UnitControl
+						value="15px"
+						onUnitChange={ onUnitChangeSpy }
+						onBlur={ onBlurSpy }
+					/>
+				</>
+			);
+
+			const select = getSelect();
+			await user.selectOptions( select, [ 'em' ] );
+
+			await waitFor( () =>
+				expect( onUnitChangeSpy ).toHaveBeenCalledTimes( 1 )
+			);
+			expect( onUnitChangeSpy ).toHaveBeenLastCalledWith(
+				'em',
+				expect.anything()
+			);
+
+			// Clicking on the button should cause the `onBlur` callback to fire.
+			const button = screen.getByRole( 'button' );
+			await user.click( button );
+
+			await waitFor( () =>
+				expect( onBlurSpy ).toHaveBeenCalledTimes( 1 )
+			);
+		} );
 	} );
 
 	describe( 'Unit Parser', () => {

package/src/unit-control/types.ts

@@ -1,7 +1,7 @@
 /**
  * External dependencies
  */
-import type { CSSProperties, SyntheticEvent } from 'react';
+import type { CSSProperties, FocusEventHandler, SyntheticEvent } from 'react';
 
 /**
  * Internal dependencies
@@ -131,4 +131,8 @@ export type UnitControlProps = Omit< UnitSelectControlProps, 'unit' > &
 		 * @default 10
 		 */
 		shiftStep?: number;
+		/**
+		 * Callback when either the quantity or the unit inputs lose focus.
+		 */
+		onBlur?: FocusEventHandler< HTMLInputElement | HTMLSelectElement >;
 	};

package/src/utils/colors-values.js

@@ -166,8 +166,9 @@ export const UI = {
 	textLight: BASE.black,
 };
 
-export const COLORS = {
-	...BASE,
+// Using Object.assign instead of { ...spread } syntax helps TypeScript
+// to extract the correct type defs here.
+export const COLORS = Object.assign( {}, BASE, {
 	darkGray: merge( {}, DARK_GRAY, G2.darkGray ),
 	darkOpacity: DARK_OPACITY,
 	darkOpacityLight: DARK_OPACITY_LIGHT,
@@ -179,6 +180,6 @@ export const COLORS = {
 	alert: ALERT,
 	admin: ADMIN,
 	ui: UI,
-};
+} );
 
 export default COLORS;

package/src/utils/config-values.js

@@ -26,15 +26,20 @@ const CONTROL_PROPS = {
 	controlHeightLarge: `calc( ${ CONTROL_HEIGHT } * 1.2 )`,
 	controlHeightXLarge: `calc( ${ CONTROL_HEIGHT } * 1.4 )`,
 };
+
 const TOGGLE_GROUP_CONTROL_PROPS = {
 	toggleGroupControlBackgroundColor: CONTROL_PROPS.controlBackgroundColor,
 	toggleGroupControlBorderColor: COLORS.ui.border,
+	toggleGroupControlBackdropBackgroundColor:
+		CONTROL_PROPS.controlSurfaceColor,
+	toggleGroupControlBackdropBorderColor: COLORS.ui.border,
+	toggleGroupControlBackdropBoxShadow: 'transparent',
 	toggleGroupControlButtonColorActive: CONTROL_PROPS.controlBackgroundColor,
 };
 
-export default {
-	...CONTROL_PROPS,
-	...TOGGLE_GROUP_CONTROL_PROPS,
+// Using Object.assign to avoid creating circular references when emitting
+// TypeScript type declarations.
+export default Object.assign( {}, CONTROL_PROPS, TOGGLE_GROUP_CONTROL_PROPS, {
 	colorDivider: 'rgba(0, 0, 0, 0.1)',
 	colorScrollbarThumb: 'rgba(0, 0, 0, 0.2)',
 	colorScrollbarThumbHover: 'rgba(0, 0, 0, 0.5)',
@@ -79,4 +84,4 @@ export default {
 	transitionDurationFastest: '100ms',
 	transitionTimingFunction: 'cubic-bezier(0.08, 0.52, 0.52, 1)',
 	transitionTimingFunctionControl: 'cubic-bezier(0.12, 0.8, 0.32, 1)',
-};
+} );

package/tsconfig.json

@@ -26,9 +26,12 @@
 		"src/animate/**/*",
 		"src/base-control/**/*",
 		"src/base-field/**/*",
+		"src/border-box-control/**/*",
+		"src/border-control/**/*",
 		"src/button/**/*",
 		"src/card/**/*",
 		"src/circular-option-picker/**/*",
+		"src/color-indicator/**/*",
 		"src/color-palette/**/*",
 		"src/color-picker/**/*",
 		"src/confirm-dialog/**/*",