@wordpress/components 21.3.0 → 22.1.0

package/src/toggle-group-control/test/index.tsx

@@ -1,7 +1,8 @@
 /**
  * External dependencies
  */
-import { render, fireEvent, screen } from '@testing-library/react';
+import { render, screen, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
 
 /**
  * WordPress dependencies
@@ -48,7 +49,7 @@ describe( 'ToggleGroupControl', () => {
 				</ToggleGroupControl>
 			);
 
-			expect( container.firstChild ).toMatchSnapshot();
+			expect( container ).toMatchSnapshot();
 		} );
 		it( 'with icons', () => {
 			const { container } = render(
@@ -69,10 +70,13 @@ describe( 'ToggleGroupControl', () => {
 				</ToggleGroupControl>
 			);
 
-			expect( container.firstChild ).toMatchSnapshot();
+			expect( container ).toMatchSnapshot();
 		} );
 	} );
-	it( 'should call onChange with proper value', () => {
+	it( 'should call onChange with proper value', async () => {
+		const user = userEvent.setup( {
+			advanceTimers: jest.advanceTimersByTime,
+		} );
 		const mockOnChange = jest.fn();
 
 		render(
@@ -85,13 +89,15 @@ describe( 'ToggleGroupControl', () => {
 			</ToggleGroupControl>
 		);
 
-		const firstRadio = screen.getByRole( 'radio', { name: 'R' } );
-
-		fireEvent.click( firstRadio );
+		await user.click( screen.getByRole( 'radio', { name: 'R' } ) );
 
 		expect( mockOnChange ).toHaveBeenCalledWith( 'rigas' );
 	} );
-	it( 'should render tooltip where `showTooltip` === `true`', () => {
+
+	it( 'should render tooltip where `showTooltip` === `true`', async () => {
+		const user = userEvent.setup( {
+			advanceTimers: jest.advanceTimersByTime,
+		} );
 		render(
 			<ToggleGroupControl label="Test Toggle Group Control">
 				{ optionsWithTooltip }
@@ -102,14 +108,19 @@ describe( 'ToggleGroupControl', () => {
 			'Click for Delicious Gnocchi'
 		);
 
-		fireEvent.focus( firstRadio );
+		await user.hover( firstRadio );
 
-		expect(
-			screen.getByText( 'Click for Delicious Gnocchi' )
-		).toBeInTheDocument();
+		await waitFor( () =>
+			expect(
+				screen.getByText( 'Click for Delicious Gnocchi' )
+			).toBeVisible()
+		);
 	} );
 
-	it( 'should not render tooltip', () => {
+	it( 'should not render tooltip', async () => {
+		const user = userEvent.setup( {
+			advanceTimers: jest.advanceTimersByTime,
+		} );
 		render(
 			<ToggleGroupControl label="Test Toggle Group Control">
 				{ optionsWithTooltip }
@@ -120,10 +131,138 @@ describe( 'ToggleGroupControl', () => {
 			'Click for Sumptuous Caponata'
 		);
 
-		fireEvent.focus( secondRadio );
+		await user.hover( secondRadio );
+
+		await waitFor( () =>
+			expect(
+				screen.queryByText( 'Click for Sumptuous Caponata' )
+			).not.toBeInTheDocument()
+		);
+	} );
+
+	describe( 'isDeselectable', () => {
+		describe( 'isDeselectable = false', () => {
+			it( 'should not be deselectable', async () => {
+				const mockOnChange = jest.fn();
+				const user = userEvent.setup( {
+					advanceTimers: jest.advanceTimersByTime,
+				} );
+
+				render(
+					<ToggleGroupControl
+						value="rigas"
+						label="Test"
+						onChange={ mockOnChange }
+					>
+						{ options }
+					</ToggleGroupControl>
+				);
+
+				const rigas = screen.getByRole( 'radio', {
+					name: 'R',
+					checked: true,
+				} );
+				await user.click( rigas );
+				expect( mockOnChange ).toHaveBeenCalledTimes( 0 );
+			} );
+
+			it( 'should not tab to next radio option', async () => {
+				const user = userEvent.setup( {
+					advanceTimers: jest.advanceTimersByTime,
+				} );
 
-		expect(
-			screen.queryByText( 'Click for Sumptuous Caponata' )
-		).not.toBeInTheDocument();
+				render(
+					<ToggleGroupControl value="rigas" label="Test">
+						{ options }
+					</ToggleGroupControl>
+				);
+
+				const rigas = screen.getByRole( 'radio', {
+					name: 'R',
+				} );
+
+				await user.tab();
+				expect( rigas ).toHaveFocus();
+
+				await user.tab();
+				expect( rigas.ownerDocument.body ).toHaveFocus();
+			} );
+		} );
+
+		describe( 'isDeselectable = true', () => {
+			it( 'should be deselectable', async () => {
+				const mockOnChange = jest.fn();
+				const user = userEvent.setup( {
+					advanceTimers: jest.advanceTimersByTime,
+				} );
+
+				render(
+					<ToggleGroupControl
+						value="rigas"
+						label="Test"
+						onChange={ mockOnChange }
+						isDeselectable
+					>
+						{ options }
+					</ToggleGroupControl>
+				);
+
+				await user.click(
+					screen.getByRole( 'button', {
+						name: 'R',
+						pressed: true,
+					} )
+				);
+				expect( mockOnChange ).toHaveBeenCalledTimes( 1 );
+				expect( mockOnChange ).toHaveBeenCalledWith( undefined );
+				expect(
+					screen.getByRole( 'button', {
+						name: 'R',
+						pressed: false,
+					} )
+				).toBeVisible();
+			} );
+
+			it( 'should tab to the next option button', async () => {
+				const user = userEvent.setup( {
+					advanceTimers: jest.advanceTimersByTime,
+				} );
+
+				render(
+					<ToggleGroupControl
+						isDeselectable
+						value="rigas"
+						label="Test"
+					>
+						{ options }
+					</ToggleGroupControl>
+				);
+
+				await user.tab();
+				expect(
+					screen.getByRole( 'button', {
+						name: 'R',
+						pressed: true,
+					} )
+				).toHaveFocus();
+
+				await user.tab();
+				expect(
+					screen.getByRole( 'button', {
+						name: 'J',
+						pressed: false,
+					} )
+				).toHaveFocus();
+
+				// Focus should not move with arrow keys
+				await user.keyboard( '{ArrowLeft}' );
+				expect(
+					screen.getByRole( 'button', {
+						name: 'J',
+						pressed: false,
+					} )
+				).toHaveFocus();
+			} );
+		} );
 	} );
 } );

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

@@ -50,9 +50,16 @@ Determines if segments should be rendered with equal widths.
 -   Required: No
 -   Default: `false`
 
+### `isDeselectable`: `boolean`
+
+Whether an option can be deselected by clicking it again.
+
+-   Required: No
+-   Default: `false`
+
 ### `isBlock`: `boolean`
 
-Renders `ToggleGroupControl` as a (CSS) block element.
+Renders `ToggleGroupControl` as a (CSS) block element, spanning the entire width of the available space. This is the recommended style when the options are text-based and not icons.
 
 -   Required: No
 -   Default: `false`

package/src/toggle-group-control/toggle-group-control/as-button-group.tsx

@@ -0,0 +1,103 @@
+/**
+ * External dependencies
+ */
+import type { ForwardedRef } from 'react';
+
+/**
+ * WordPress dependencies
+ */
+import {
+	useMergeRefs,
+	useInstanceId,
+	usePrevious,
+	useResizeObserver,
+} from '@wordpress/compose';
+import { forwardRef, useRef, useState } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import { View } from '../../view';
+import ToggleGroupControlBackdrop from './toggle-group-control-backdrop';
+import ToggleGroupControlContext from '../context';
+import { useUpdateEffect } from '../../utils/hooks';
+import type { WordPressComponentProps } from '../../ui/context';
+import type { ToggleGroupControlMainControlProps } from '../types';
+
+function UnforwardedToggleGroupControlAsButtonGroup(
+	{
+		children,
+		isAdaptiveWidth,
+		label,
+		onChange,
+		size,
+		value,
+		...otherProps
+	}: WordPressComponentProps<
+		ToggleGroupControlMainControlProps,
+		'div',
+		false
+	>,
+	forwardedRef: ForwardedRef< HTMLDivElement >
+) {
+	const containerRef = useRef();
+	const [ resizeListener, sizes ] = useResizeObserver();
+	const baseId = useInstanceId(
+		ToggleGroupControlAsButtonGroup,
+		'toggle-group-control-as-button-group'
+	).toString();
+	const [ selectedValue, setSelectedValue ] = useState( value );
+	const groupContext = {
+		baseId,
+		state: selectedValue,
+		setState: setSelectedValue,
+	};
+	const previousValue = usePrevious( value );
+
+	// Propagate groupContext.state change.
+	useUpdateEffect( () => {
+		// Avoid calling onChange if groupContext state changed
+		// from incoming value.
+		if ( previousValue !== groupContext.state ) {
+			onChange( groupContext.state );
+		}
+	}, [ groupContext.state ] );
+
+	// Sync incoming value with groupContext.state.
+	useUpdateEffect( () => {
+		if ( value !== groupContext.state ) {
+			groupContext.setState( value );
+		}
+	}, [ value ] );
+
+	return (
+		<ToggleGroupControlContext.Provider
+			value={ {
+				...groupContext,
+				isBlock: ! isAdaptiveWidth,
+				isDeselectable: true,
+				size,
+			} }
+		>
+			<View
+				aria-label={ label }
+				{ ...otherProps }
+				ref={ useMergeRefs( [ containerRef, forwardedRef ] ) }
+				role="group"
+			>
+				{ resizeListener }
+				<ToggleGroupControlBackdrop
+					state={ groupContext.state }
+					containerRef={ containerRef }
+					containerWidth={ sizes.width }
+					isAdaptiveWidth={ isAdaptiveWidth }
+				/>
+				{ children }
+			</View>
+		</ToggleGroupControlContext.Provider>
+	);
+}
+
+export const ToggleGroupControlAsButtonGroup = forwardRef(
+	UnforwardedToggleGroupControlAsButtonGroup
+);

package/src/toggle-group-control/toggle-group-control/as-radio-group.tsx

@@ -0,0 +1,99 @@
+/**
+ * External dependencies
+ */
+import type { ForwardedRef } from 'react';
+// eslint-disable-next-line no-restricted-imports
+import { RadioGroup, useRadioState } from 'reakit';
+
+/**
+ * WordPress dependencies
+ */
+import {
+	useMergeRefs,
+	useInstanceId,
+	usePrevious,
+	useResizeObserver,
+} from '@wordpress/compose';
+import { forwardRef, useRef } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import { View } from '../../view';
+import ToggleGroupControlBackdrop from './toggle-group-control-backdrop';
+import ToggleGroupControlContext from '../context';
+import { useUpdateEffect } from '../../utils/hooks';
+import type { WordPressComponentProps } from '../../ui/context';
+import type { ToggleGroupControlMainControlProps } from '../types';
+
+function UnforwardedToggleGroupControlAsRadioGroup(
+	{
+		children,
+		isAdaptiveWidth,
+		label,
+		onChange,
+		size,
+		value,
+		...otherProps
+	}: WordPressComponentProps<
+		ToggleGroupControlMainControlProps,
+		'div',
+		false
+	>,
+	forwardedRef: ForwardedRef< HTMLDivElement >
+) {
+	const containerRef = useRef();
+	const [ resizeListener, sizes ] = useResizeObserver();
+	const baseId = useInstanceId(
+		ToggleGroupControlAsRadioGroup,
+		'toggle-group-control-as-radio-group'
+	).toString();
+	const radio = useRadioState( {
+		baseId,
+		state: value,
+	} );
+	const previousValue = usePrevious( value );
+
+	// Propagate radio.state change.
+	useUpdateEffect( () => {
+		// Avoid calling onChange if radio state changed
+		// from incoming value.
+		if ( previousValue !== radio.state ) {
+			onChange( radio.state );
+		}
+	}, [ radio.state ] );
+
+	// Sync incoming value with radio.state.
+	useUpdateEffect( () => {
+		if ( value !== radio.state ) {
+			radio.setState( value );
+		}
+	}, [ value ] );
+
+	return (
+		<ToggleGroupControlContext.Provider
+			value={ { ...radio, isBlock: ! isAdaptiveWidth, size } }
+		>
+			<RadioGroup
+				{ ...radio }
+				aria-label={ label }
+				as={ View }
+				{ ...otherProps }
+				ref={ useMergeRefs( [ containerRef, forwardedRef ] ) }
+			>
+				{ resizeListener }
+				<ToggleGroupControlBackdrop
+					state={ radio.state }
+					containerRef={ containerRef }
+					containerWidth={ sizes.width }
+					isAdaptiveWidth={ isAdaptiveWidth }
+				/>
+				{ children }
+			</RadioGroup>
+		</ToggleGroupControlContext.Provider>
+	);
+}
+
+export const ToggleGroupControlAsRadioGroup = forwardRef(
+	UnforwardedToggleGroupControlAsRadioGroup
+);

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

@@ -2,20 +2,11 @@
  * External dependencies
  */
 import type { ForwardedRef } from 'react';
-// eslint-disable-next-line no-restricted-imports
-import { RadioGroup, useRadioState } from 'reakit';
-
 /**
  * WordPress dependencies
  */
 import { __ } from '@wordpress/i18n';
-import { useRef, useMemo } from '@wordpress/element';
-import {
-	useMergeRefs,
-	useInstanceId,
-	usePrevious,
-	useResizeObserver,
-} from '@wordpress/compose';
+import { useMemo } from '@wordpress/element';
 
 /**
  * Internal dependencies
@@ -25,19 +16,18 @@ import {
 	useContextSystem,
 	WordPressComponentProps,
 } from '../../ui/context';
-import { useUpdateEffect, useCx } from '../../utils/hooks';
-import { View } from '../../view';
+import { useCx } from '../../utils/hooks';
 import BaseControl from '../../base-control';
 import type { ToggleGroupControlProps } from '../types';
-import ToggleGroupControlBackdrop from './toggle-group-control-backdrop';
-import ToggleGroupControlContext from '../context';
 import { VisualLabelWrapper } from './styles';
 import * as styles from './styles';
+import { ToggleGroupControlAsRadioGroup } from './as-radio-group';
+import { ToggleGroupControlAsButtonGroup } from './as-button-group';
 
 const noop = () => {};
 
 function UnconnectedToggleGroupControl(
-	props: WordPressComponentProps< ToggleGroupControlProps, 'input', false >,
+	props: WordPressComponentProps< ToggleGroupControlProps, 'div', false >,
 	forwardedRef: ForwardedRef< any >
 ) {
 	const {
@@ -45,7 +35,7 @@ function UnconnectedToggleGroupControl(
 		className,
 		isAdaptiveWidth = false,
 		isBlock = false,
-		__experimentalIsBorderless = false,
+		isDeselectable = false,
 		label,
 		hideLabelFromVision = false,
 		help,
@@ -56,77 +46,42 @@ function UnconnectedToggleGroupControl(
 		...otherProps
 	} = useContextSystem( props, 'ToggleGroupControl' );
 	const cx = useCx();
-	const containerRef = useRef();
-	const [ resizeListener, sizes ] = useResizeObserver();
-	const baseId = useInstanceId(
-		ToggleGroupControl,
-		'toggle-group-control'
-	).toString();
-	const radio = useRadioState( {
-		baseId,
-		state: value,
-	} );
-	const previousValue = usePrevious( value );
-
-	// Propagate radio.state change.
-	useUpdateEffect( () => {
-		// Avoid calling onChange if radio state changed
-		// from incoming value.
-		if ( previousValue !== radio.state ) {
-			onChange( radio.state );
-		}
-	}, [ radio.state ] );
-
-	// Sync incoming value with radio.state.
-	useUpdateEffect( () => {
-		if ( value !== radio.state ) {
-			radio.setState( value );
-		}
-	}, [ value ] );
 
 	const classes = useMemo(
 		() =>
 			cx(
-				styles.ToggleGroupControl( { size } ),
-				! __experimentalIsBorderless && styles.border,
+				styles.ToggleGroupControl( { isBlock, isDeselectable, size } ),
 				isBlock && styles.block,
 				className
 			),
-		[ className, cx, isBlock, __experimentalIsBorderless, size ]
+		[ className, cx, isBlock, isDeselectable, size ]
 	);
+
+	const MainControl = isDeselectable
+		? ToggleGroupControlAsButtonGroup
+		: ToggleGroupControlAsRadioGroup;
+
 	return (
 		<BaseControl
 			help={ help }
 			__nextHasNoMarginBottom={ __nextHasNoMarginBottom }
 		>
-			<ToggleGroupControlContext.Provider
-				value={ { ...radio, isBlock: ! isAdaptiveWidth, size } }
-			>
-				{ ! hideLabelFromVision && (
-					<VisualLabelWrapper>
-						<BaseControl.VisualLabel>
-							{ label }
-						</BaseControl.VisualLabel>
-					</VisualLabelWrapper>
-				) }
-				<RadioGroup
-					{ ...radio }
-					aria-label={ label }
-					as={ View }
-					className={ classes }
-					{ ...otherProps }
-					ref={ useMergeRefs( [ containerRef, forwardedRef ] ) }
-				>
-					{ resizeListener }
-					<ToggleGroupControlBackdrop
-						{ ...radio }
-						containerRef={ containerRef }
-						containerWidth={ sizes.width }
-						isAdaptiveWidth={ isAdaptiveWidth }
-					/>
-					{ children }
-				</RadioGroup>
-			</ToggleGroupControlContext.Provider>
+			{ ! hideLabelFromVision && (
+				<VisualLabelWrapper>
+					<BaseControl.VisualLabel>{ label }</BaseControl.VisualLabel>
+				</VisualLabelWrapper>
+			) }
+			<MainControl
+				{ ...otherProps }
+				children={ children }
+				className={ classes }
+				isAdaptiveWidth={ isAdaptiveWidth }
+				label={ label }
+				onChange={ onChange }
+				ref={ forwardedRef }
+				size={ size }
+				value={ value }
+			/>
 		</BaseControl>
 	);
 }

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

@@ -11,8 +11,10 @@ import { CONFIG, COLORS, reduceMotion } from '../../utils';
 import type { ToggleGroupControlProps } from '../types';
 
 export const ToggleGroupControl = ( {
+	isBlock,
+	isDeselectable,
 	size,
-}: {
+}: Pick< ToggleGroupControlProps, 'isBlock' | 'isDeselectable' > & {
 	size: NonNullable< ToggleGroupControlProps[ 'size' ] >;
 } ) => css`
 	background: ${ COLORS.ui.background };
@@ -26,22 +28,29 @@ export const ToggleGroupControl = ( {
 	${ reduceMotion( 'transition' ) }
 
 	${ toggleGroupControlSize( size ) }
-
-	&:focus-within {
-		border-color: ${ COLORS.ui.borderFocus };
-		box-shadow: ${ CONFIG.controlBoxShadowFocus };
-		outline: none;
-		z-index: 1;
-	}
+	${ ! isDeselectable && enclosingBorders( isBlock ) }
 `;
 
-export const border = css`
-	border-color: ${ COLORS.ui.border };
+const enclosingBorders = ( isBlock: ToggleGroupControlProps[ 'isBlock' ] ) => {
+	const enclosingBorder = css`
+		border-color: ${ COLORS.ui.border };
+	`;
 
-	&:hover {
-		border-color: ${ COLORS.ui.borderHover };
-	}
-`;
+	return css`
+		${ isBlock && enclosingBorder }
+
+		&:hover {
+			border-color: ${ COLORS.ui.borderHover };
+		}
+
+		&:focus-within {
+			border-color: ${ COLORS.ui.borderFocus };
+			box-shadow: ${ CONFIG.controlBoxShadowFocus };
+			outline: none;
+			z-index: 1;
+		}
+	`;
+};
 
 export const toggleGroupControlSize = (
 	size: NonNullable< ToggleGroupControlProps[ 'size' ] >
@@ -64,7 +73,6 @@ export const block = css`
 export const BackdropView = styled.div`
 	background: ${ COLORS.gray[ 900 ] };
 	border-radius: ${ CONFIG.controlBorderRadius };
-	box-shadow: ${ CONFIG.toggleGroupControlBackdropBoxShadow };
 	left: 0;
 	position: absolute;
 	top: 2px;