@wordpress/components 19.7.0 → 19.9.0

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/toolbar-group/style.scss

@@ -5,6 +5,8 @@
 	display: inline-flex;
 	flex-shrink: 0;
 	flex-wrap: wrap;
+	padding-left: $grid-unit-15 * 0.5; // 6px.
+	padding-right: $grid-unit-15 * 0.5;
 
 	// Unset for nested toolbar groups. Increase specificity.
 	& .components-toolbar-group.components-toolbar-group {
@@ -13,6 +15,24 @@
 	}
 
 	line-height: 0;
+
+	// Size multiple sequential buttons to be optically balanced.
+	// Icons are 36px, as set by a 24px icon and 12px padding.
+	.components-button.components-button, // This needs specificity to override padding values inherited from the button component.
+	.components-button.has-icon.has-icon {
+		min-width: $block-toolbar-height - $grid-unit-15;
+		padding-left: $grid-unit-15 * 0.5; // 6px.
+		padding-right: $grid-unit-15 * 0.5;
+
+		svg {
+			min-width: $button-size-small; // This is the optimal icon size, and we size the whole button after this.
+		}
+
+		&::before {
+			left: 2px;
+			right: 2px;
+		}
+	}
 }
 
 // Legacy toolbar group

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

@@ -64,7 +64,7 @@ exports[`ToolsPanel first and last panel items should apply first/last classes t
   color: #1e1e1e;
   line-height: 1.2;
   margin: 0;
-  color: #050505;
+  color: #1e1e1e;
   font-size: calc(1.95 * 13px);
   font-weight: 600;
   display: block;
@@ -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/ui/spinner/component.js

@@ -21,7 +21,7 @@ import { COLORS } from '../../utils/colors-values';
  */
 function Spinner( props, forwardedRef ) {
 	const {
-		color = COLORS.black,
+		color = COLORS.gray[ 900 ],
 		size = BASE_SIZE,
 		...otherProps
 	} = useContextSystem( props, 'Spinner' );

package/src/ui/spinner/test/__snapshots__/index.js.snap

@@ -12,7 +12,7 @@ Snapshot Diff:
       <div
         class="css-tada40-BarsView e1s9yo7h0"
 -       style="color: blue;"
-+       style="color: rgb(0, 0, 0);"
++       style="color: rgb(30, 30, 30);"
       >
         <div
           class="InnerBar1"
@@ -193,7 +193,7 @@ exports[`props should render correctly 1`] = `
   >
     <div
       class="emotion-4 emotion-5"
-      style="color: rgb(0, 0, 0);"
+      style="color: rgb(30, 30, 30);"
     >
       <div
         class="InnerBar1"
@@ -258,6 +258,6 @@ Snapshot Diff:
     >
       <div
         class="css-tada40-BarsView e1s9yo7h0"
-        style="color: rgb(0, 0, 0);"
+        style="color: rgb(30, 30, 30);"
       >
 `;

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', () => {