@wordpress/components 19.6.1 → 19.8.0

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

@@ -0,0 +1,436 @@
+/**
+ * External dependencies
+ */
+import { fireEvent, render, screen } from '@testing-library/react';
+
+/**
+ * Internal dependencies
+ */
+import { BorderControl } from '../';
+
+const colors = [
+	{ name: 'Gray', color: '#f6f7f7' },
+	{ name: 'Blue', color: '#72aee6' },
+	{ name: 'Red', color: '#e65054' },
+	{ name: 'Green', color: '#00a32a' },
+	{ name: 'Yellow', color: '#bd8600' },
+];
+
+const defaultBorder = {
+	color: '#72aee6',
+	style: 'solid',
+	width: '1px',
+};
+
+const props = {
+	colors,
+	label: 'Border',
+	onChange: jest.fn().mockImplementation( ( newValue ) => {
+		props.value = newValue;
+	} ),
+	value: defaultBorder,
+};
+
+const toggleLabelRegex = /Border color( and style)* picker/;
+
+const renderBorderControl = ( customProps ) => {
+	return render( <BorderControl { ...{ ...props, ...customProps } } /> );
+};
+
+const rerenderBorderControl = ( rerender, customProps ) => {
+	return rerender( <BorderControl { ...{ ...props, ...customProps } } /> );
+};
+
+const openPopover = () => {
+	const toggleButton = screen.getByLabelText( toggleLabelRegex );
+	fireEvent.click( toggleButton );
+};
+
+const getButton = ( name ) => {
+	return screen.getByRole( 'button', { name } );
+};
+
+const queryButton = ( name ) => {
+	return screen.queryByRole( 'button', { name } );
+};
+
+const clickButton = ( name ) => {
+	fireEvent.click( getButton( name ) );
+};
+
+const setWidthInput = ( value ) => {
+	const widthInput = screen.getByRole( 'spinbutton' );
+	widthInput.focus();
+	fireEvent.change( widthInput, { target: { value } } );
+};
+
+const clearWidthInput = () => setWidthInput( '' );
+
+describe( 'BorderControl', () => {
+	describe( 'basic rendering', () => {
+		it( 'should render standard border control', () => {
+			renderBorderControl();
+
+			const label = screen.getByText( props.label );
+			const colorButton = screen.getByLabelText( toggleLabelRegex );
+			const widthInput = screen.getByRole( 'spinbutton' );
+			const unitSelect = screen.getByRole( 'combobox' );
+			const slider = screen.queryByRole( 'slider' );
+
+			expect( label ).toBeInTheDocument();
+			expect( colorButton ).toBeInTheDocument();
+			expect( widthInput ).toBeInTheDocument();
+			expect( unitSelect ).toBeInTheDocument();
+			expect( slider ).not.toBeInTheDocument();
+		} );
+
+		it( 'should hide label', () => {
+			renderBorderControl( { hideLabelFromVision: true } );
+			const label = screen.getByText( props.label );
+
+			// As visually hidden labels are still included in the document
+			// and do not have `display: none` styling, we can't rely on
+			// `.toBeInTheDocument()` or `.toBeVisible()` assertions.
+			expect( label ).toHaveAttribute(
+				'data-wp-component',
+				'VisuallyHidden'
+			);
+		} );
+
+		it( 'should render with slider', () => {
+			renderBorderControl( { withSlider: true } );
+
+			const slider = screen.getByRole( 'slider' );
+			expect( slider ).toBeInTheDocument();
+		} );
+
+		it( 'should render placeholder in UnitControl', () => {
+			renderBorderControl( { placeholder: 'Mixed' } );
+			const widthInput = screen.getByRole( 'spinbutton' );
+
+			expect( widthInput ).toHaveAttribute( 'placeholder', 'Mixed' );
+		} );
+
+		it( 'should render color and style popover', () => {
+			renderBorderControl();
+			openPopover();
+
+			const customColorPicker = getButton( /Custom color picker/ );
+			const colorSwatchButtons = screen.getAllByRole( 'button', {
+				name: /^Color:/,
+			} );
+			const styleLabel = screen.getByText( 'Style' );
+			const solidButton = getButton( 'Solid' );
+			const dashedButton = getButton( 'Dashed' );
+			const dottedButton = getButton( 'Dotted' );
+			const resetButton = getButton( 'Reset to default' );
+
+			expect( customColorPicker ).toBeInTheDocument();
+			expect( colorSwatchButtons.length ).toEqual( colors.length );
+			expect( styleLabel ).toBeInTheDocument();
+			expect( solidButton ).toBeInTheDocument();
+			expect( dashedButton ).toBeInTheDocument();
+			expect( dottedButton ).toBeInTheDocument();
+			expect( resetButton ).toBeInTheDocument();
+		} );
+
+		it( 'should render color and style popover header', () => {
+			renderBorderControl( { showDropdownHeader: true } );
+			openPopover();
+
+			const headerLabel = screen.getByText( 'Border color' );
+			const closeButton = getButton( 'Close border color' );
+
+			expect( headerLabel ).toBeInTheDocument();
+			expect( closeButton ).toBeInTheDocument();
+		} );
+
+		it( 'should not render style options when opted out of', () => {
+			renderBorderControl( { enableStyle: false } );
+			openPopover();
+
+			const styleLabel = screen.queryByText( 'Style' );
+			const solidButton = queryButton( 'Solid' );
+			const dashedButton = queryButton( 'Dashed' );
+			const dottedButton = queryButton( 'Dotted' );
+
+			expect( styleLabel ).not.toBeInTheDocument();
+			expect( solidButton ).not.toBeInTheDocument();
+			expect( dashedButton ).not.toBeInTheDocument();
+			expect( dottedButton ).not.toBeInTheDocument();
+		} );
+	} );
+
+	describe( 'color and style picker aria labels', () => {
+		describe( 'with style selection enabled', () => {
+			it( 'should include both color and style in label', () => {
+				renderBorderControl( { value: undefined } );
+
+				expect(
+					screen.getByLabelText( 'Border color and style picker.' )
+				).toBeInTheDocument();
+			} );
+
+			it( 'should correctly describe named color selection', () => {
+				renderBorderControl( { value: { color: '#72aee6' } } );
+
+				expect(
+					screen.getByLabelText(
+						'Border color and style picker. The currently selected color is called "Blue" and has a value of "#72aee6".'
+					)
+				).toBeInTheDocument();
+			} );
+
+			it( 'should correctly describe custom color selection', () => {
+				renderBorderControl( { value: { color: '#4b1d80' } } );
+
+				expect(
+					screen.getByLabelText(
+						'Border color and style picker. The currently selected color has a value of "#4b1d80".'
+					)
+				).toBeInTheDocument();
+			} );
+
+			it( 'should correctly describe named color and style selections', () => {
+				renderBorderControl( {
+					value: { color: '#72aee6', style: 'dotted' },
+				} );
+
+				expect(
+					screen.getByLabelText(
+						'Border color and style picker. The currently selected color is called "Blue" and has a value of "#72aee6". The currently selected style is "dotted".'
+					)
+				).toBeInTheDocument();
+			} );
+
+			it( 'should correctly describe custom color and style selections', () => {
+				renderBorderControl( {
+					value: { color: '#4b1d80', style: 'dashed' },
+				} );
+
+				expect(
+					screen.getByLabelText(
+						'Border color and style picker. The currently selected color has a value of "#4b1d80". The currently selected style is "dashed".'
+					)
+				).toBeInTheDocument();
+			} );
+		} );
+
+		describe( 'with style selection disabled', () => {
+			it( 'should only include color in the label', () => {
+				renderBorderControl( { value: undefined, enableStyle: false } );
+
+				expect(
+					screen.getByLabelText( 'Border color picker.' )
+				).toBeInTheDocument();
+			} );
+
+			it( 'should correctly describe named color selection', () => {
+				renderBorderControl( {
+					value: { color: '#72aee6' },
+					enableStyle: false,
+				} );
+
+				expect(
+					screen.getByLabelText(
+						'Border color picker. The currently selected color is called "Blue" and has a value of "#72aee6".'
+					)
+				).toBeInTheDocument();
+			} );
+
+			it( 'should correctly describe custom color selection', () => {
+				renderBorderControl( {
+					value: { color: '#4b1d80' },
+					enableStyle: false,
+				} );
+
+				expect(
+					screen.getByLabelText(
+						'Border color picker. The currently selected color has a value of "#4b1d80".'
+					)
+				).toBeInTheDocument();
+			} );
+		} );
+	} );
+
+	describe( 'onChange handling', () => {
+		beforeEach( () => {
+			jest.clearAllMocks();
+			props.value = defaultBorder;
+		} );
+
+		it( 'should update width with slider value', () => {
+			const { rerender } = renderBorderControl( { withSlider: true } );
+
+			const slider = screen.getByRole( 'slider' );
+			fireEvent.change( slider, { target: { value: '5' } } );
+
+			expect( props.onChange ).toHaveBeenNthCalledWith( 1, {
+				...defaultBorder,
+				width: '5px',
+			} );
+
+			rerenderBorderControl( rerender, { withSlider: true } );
+			const widthInput = screen.getByRole( 'spinbutton' );
+
+			expect( widthInput.value ).toEqual( '5' );
+		} );
+
+		it( 'should update color selection', () => {
+			renderBorderControl();
+			openPopover();
+			clickButton( 'Color: Green' );
+
+			expect( props.onChange ).toHaveBeenNthCalledWith( 1, {
+				...defaultBorder,
+				color: '#00a32a',
+			} );
+		} );
+
+		it( 'should clear color selection when toggling swatch off', () => {
+			renderBorderControl();
+			openPopover();
+			clickButton( 'Color: Blue' );
+
+			expect( props.onChange ).toHaveBeenNthCalledWith( 1, {
+				...defaultBorder,
+				color: undefined,
+			} );
+		} );
+
+		it( 'should update style selection', () => {
+			renderBorderControl();
+			openPopover();
+			clickButton( 'Dashed' );
+
+			expect( props.onChange ).toHaveBeenNthCalledWith( 1, {
+				...defaultBorder,
+				style: 'dashed',
+			} );
+		} );
+
+		it( 'should take no action when color and style popover is closed', () => {
+			renderBorderControl( { showDropdownHeader: true } );
+			openPopover();
+			clickButton( 'Close border color' );
+
+			expect( props.onChange ).not.toHaveBeenCalled();
+		} );
+
+		it( 'should reset color and style only when popover reset button clicked', () => {
+			renderBorderControl();
+			openPopover();
+			clickButton( 'Reset to default' );
+
+			expect( props.onChange ).toHaveBeenNthCalledWith( 1, {
+				color: undefined,
+				style: undefined,
+				width: defaultBorder.width,
+			} );
+		} );
+
+		it( 'should sanitize border when width and color are undefined', () => {
+			const { rerender } = renderBorderControl();
+			clearWidthInput();
+			rerenderBorderControl( rerender );
+			openPopover();
+			clickButton( 'Color: Blue' );
+
+			expect( props.onChange ).toHaveBeenCalledWith( undefined );
+		} );
+
+		it( 'should not sanitize border when requested', () => {
+			const { rerender } = renderBorderControl( {
+				shouldSanitizeBorder: false,
+			} );
+			clearWidthInput();
+			rerenderBorderControl( rerender, { shouldSanitizeBorder: false } );
+			openPopover();
+			clickButton( 'Color: Blue' );
+
+			expect( props.onChange ).toHaveBeenNthCalledWith( 2, {
+				color: undefined,
+				style: defaultBorder.style,
+				width: undefined,
+			} );
+		} );
+
+		it( 'should clear color and set style to `none` when setting zero width', () => {
+			renderBorderControl();
+			openPopover();
+			clickButton( 'Color: Green' );
+			clickButton( 'Dotted' );
+			setWidthInput( '0' );
+
+			expect( props.onChange ).toHaveBeenNthCalledWith( 3, {
+				color: undefined,
+				style: 'none',
+				width: '0px',
+			} );
+		} );
+
+		it( 'should reselect color and style selections when changing to non-zero width', () => {
+			const { rerender } = renderBorderControl();
+			openPopover();
+			clickButton( 'Color: Green' );
+			rerenderBorderControl( rerender );
+			clickButton( 'Dotted' );
+			rerenderBorderControl( rerender );
+			setWidthInput( '0' );
+			setWidthInput( '5' );
+
+			expect( props.onChange ).toHaveBeenNthCalledWith( 4, {
+				color: '#00a32a',
+				style: 'dotted',
+				width: '5px',
+			} );
+		} );
+
+		it( 'should set a non-zero width when applying color to zero width border', () => {
+			const { rerender } = renderBorderControl( { value: undefined } );
+			openPopover();
+			clickButton( 'Color: Yellow' );
+
+			expect( props.onChange ).toHaveBeenCalledWith( {
+				color: '#bd8600',
+				style: undefined,
+				width: undefined,
+			} );
+
+			setWidthInput( '0' );
+			rerenderBorderControl( rerender );
+			clickButton( 'Color: Green' );
+
+			expect( props.onChange ).toHaveBeenCalledWith( {
+				color: '#00a32a',
+				style: undefined,
+				width: '1px',
+			} );
+		} );
+
+		it( 'should set a non-zero width when applying style to zero width border', () => {
+			const { rerender } = renderBorderControl( {
+				value: undefined,
+				shouldSanitizeBorder: false,
+			} );
+			openPopover();
+			clickButton( 'Dashed' );
+
+			expect( props.onChange ).toHaveBeenCalledWith( {
+				color: undefined,
+				style: 'dashed',
+				width: undefined,
+			} );
+
+			setWidthInput( '0' );
+			rerenderBorderControl( rerender, { shouldSanitizeBorder: false } );
+			clickButton( 'Dotted' );
+
+			expect( props.onChange ).toHaveBeenCalledWith( {
+				color: undefined,
+				style: 'dotted',
+				width: '1px',
+			} );
+		} );
+	} );
+} );

package/src/border-control/types.ts

@@ -0,0 +1,173 @@
+/**
+ * External dependencies
+ */
+import type { CSSProperties } from 'react';
+
+export type Border = {
+	color?: CSSProperties[ 'borderColor' ];
+	style?: CSSProperties[ 'borderStyle' ];
+	width?: CSSProperties[ 'borderWidth' ];
+};
+
+export type Color = {
+	name: string;
+	color: CSSProperties[ 'color' ];
+};
+
+export type ColorOrigin = {
+	name: string;
+	colors: Color[];
+};
+
+export type Colors = ColorOrigin[] | Color[];
+
+export type ColorProps = {
+	/**
+	 * An array of color definitions. This may also be a multi-dimensional array
+	 * where colors are organized by multiple origins.
+	 */
+	colors?: Colors;
+	/**
+	 * This toggles the ability to choose custom colors.
+	 */
+	disableCustomColors?: boolean;
+	/**
+	 * This controls whether the alpha channel will be offered when selecting
+	 * custom colors.
+	 */
+	enableAlpha?: boolean;
+	/**
+	 * This is passed on to the color related sub-components which need to be
+	 * made aware of whether the colors prop contains multiple origins.
+	 */
+	__experimentalHasMultipleOrigins?: boolean;
+	/**
+	 * This is passed on to the color related sub-components so they may render
+	 * more effectively when used within a sidebar.
+	 */
+	__experimentalIsRenderedInSidebar?: boolean;
+};
+
+export type LabelProps = {
+	/**
+	 * Provides control over whether the label will only be visible to
+	 * screen readers.
+	 */
+	hideLabelFromVision?: boolean;
+	/**
+	 * If provided, a label will be generated using this as the content.
+	 */
+	label?: string;
+};
+
+export type BorderControlProps = ColorProps &
+	LabelProps & {
+		/**
+		 * This controls whether to include border style options within the
+		 * `BorderDropdown` sub-component.
+		 *
+		 * @default true
+		 */
+		enableStyle?: boolean;
+		/**
+		 * This flags the `BorderControl` to render with a more compact
+		 * appearance. It restricts the width of the control and prevents it
+		 * from expanding to take up additional space.
+		 */
+		isCompact?: boolean;
+		/**
+		 * A callback function invoked when the border value is changed via an
+		 * interaction that selects or clears, border color, style, or width.
+		 */
+		onChange: ( value?: Border ) => void;
+		/**
+		 * A custom CSS class name to be assigned to the border control's
+		 * dropdown popover content.
+		 */
+		popoverContentClassName?: string;
+		/**
+		 * If opted into, sanitizing the border means that if no width or color
+		 * have been selected, the border style is also cleared and `undefined`
+		 * is returned as the new border value.
+		 *
+		 * @default true
+		 */
+		shouldSanitizeBorder?: boolean;
+		/**
+		 * Whether or not to show the header for the border color and style
+		 * picker dropdown. The header includes a label for the color picker
+		 * and a close button.
+		 */
+		showDropdownHeader?: boolean;
+		/**
+		 * An object representing a border or `undefined`. Used to set the
+		 * current border configuration for this component.
+		 */
+		value?: Border;
+		/**
+		 * Controls the visual width of the `BorderControl`. It has no effect if
+		 * the `isCompact` prop is set to `true`.
+		 */
+		width?: CSSProperties[ 'width' ];
+		/**
+		 * Flags whether this `BorderControl` should also render a
+		 * `RangeControl` for additional control over a border's width.
+		 */
+		withSlider?: boolean;
+	};
+
+export type DropdownProps = ColorProps & {
+	/**
+	 * An object representing a border or `undefined`. This component will
+	 * extract the border color and style selections from this object to use as
+	 * values for its popover controls.
+	 */
+	border?: Border;
+	/**
+	 * A custom CSS class name to be assigned to the border control's
+	 * dropdown popover content.
+	 */
+	contentClassName?: string;
+	/**
+	 * This controls whether to render border style options.
+	 *
+	 * @default true
+	 */
+	enableStyle?: boolean;
+	/**
+	 * A callback invoked when the border color or style selections change.
+	 */
+	onChange: ( newBorder?: Border ) => void;
+	/**
+	 * Any previous style selection made by the user. This can be used to
+	 * reapply that previous selection when, for example, a zero border width is
+	 * to a non-zero value.
+	 */
+	previousStyleSelection?: string;
+	/**
+	 * Whether or not to render a header for the border color and style picker
+	 * dropdown. The header includes a label for the color picker and a
+	 * close button.
+	 */
+	showDropdownHeader?: boolean;
+};
+
+export type StylePickerProps = LabelProps & {
+	/**
+	 * A callback function invoked when a border style is selected or cleared.
+	 */
+	onChange: ( style?: string ) => void;
+	/**
+	 * The currently selected border style if there is one. Styles available via
+	 * this control are `solid`, `dashed` & `dotted`, however the possibility
+	 * to store other valid CSS values is maintained e.g. `none`, `inherit` etc.
+	 */
+	value?: string;
+};
+
+export type PopoverProps = {
+	/**
+	 * Callback function to invoke when closing the border dropdown's popover.
+	 */
+	onClose: () => void;
+};

package/src/box-control/all-input-control.js

@@ -10,7 +10,6 @@ import {
 	ALL_SIDES,
 	LABELS,
 	getAllValue,
-	getAllUnitFallback,
 	isValuesMixed,
 	isValuesDefined,
 } from './utils';
@@ -26,17 +25,11 @@ export default function AllInputControl( {
 	setSelectedUnits,
 	...props
 } ) {
-	const allValue = getAllValue( values, sides );
+	const allValue = getAllValue( values, selectedUnits, sides );
 	const hasValues = isValuesDefined( values );
-	const isMixed = hasValues && isValuesMixed( values, sides );
+	const isMixed = hasValues && isValuesMixed( values, selectedUnits, sides );
 	const allPlaceholder = isMixed ? LABELS.mixed : null;
 
-	// Set meaningful unit selection if no allValue and user has previously
-	// selected units without assigning values while controls were unlinked.
-	const allUnitFallback = ! allValue
-		? getAllUnitFallback( selectedUnits )
-		: undefined;
-
 	const handleOnFocus = ( event ) => {
 		onFocus( event, { side: 'all' } );
 	};
@@ -104,7 +97,6 @@ export default function AllInputControl( {
 			disableUnits={ isMixed }
 			isOnly
 			value={ allValue }
-			unit={ allUnitFallback }
 			onChange={ handleOnChange }
 			onUnitChange={ handleOnUnitChange }
 			onFocus={ handleOnFocus }

package/src/box-control/axial-input-controls.js

@@ -1,6 +1,7 @@
 /**
  * Internal dependencies
  */
+import { parseQuantityAndUnitFromRawValue } from '../unit-control/utils';
 import UnitControl from './unit-control';
 import { LABELS } from './utils';
 import { Layout } from './styles/box-control-styles';
@@ -113,27 +114,37 @@ export default function AxialInputControls( {
 			align="top"
 			className="component-box-control__vertical-horizontal-input-controls"
 		>
-			{ filteredSides.map( ( side ) => (
-				<UnitControl
-					{ ...props }
-					isFirst={ first === side }
-					isLast={ last === side }
-					isOnly={ only === side }
-					value={ side === 'vertical' ? values.top : values.left }
-					unit={
-						side === 'vertical'
-							? selectedUnits.top
-							: selectedUnits.left
-					}
-					onChange={ createHandleOnChange( side ) }
-					onUnitChange={ createHandleOnUnitChange( side ) }
-					onFocus={ createHandleOnFocus( side ) }
-					onHoverOn={ createHandleOnHoverOn( side ) }
-					onHoverOff={ createHandleOnHoverOff( side ) }
-					label={ LABELS[ side ] }
-					key={ side }
-				/>
-			) ) }
+			{ filteredSides.map( ( side ) => {
+				const [
+					parsedQuantity,
+					parsedUnit,
+				] = parseQuantityAndUnitFromRawValue(
+					side === 'vertical' ? values.top : values.left
+				);
+				const selectedUnit =
+					side === 'vertical'
+						? selectedUnits.top
+						: selectedUnits.left;
+				return (
+					<UnitControl
+						{ ...props }
+						isFirst={ first === side }
+						isLast={ last === side }
+						isOnly={ only === side }
+						value={ [
+							parsedQuantity,
+							selectedUnit ?? parsedUnit,
+						].join( '' ) }
+						onChange={ createHandleOnChange( side ) }
+						onUnitChange={ createHandleOnUnitChange( side ) }
+						onFocus={ createHandleOnFocus( side ) }
+						onHoverOn={ createHandleOnHoverOn( side ) }
+						onHoverOff={ createHandleOnHoverOff( side ) }
+						label={ LABELS[ side ] }
+						key={ side }
+					/>
+				);
+			} ) }
 		</Layout>
 	);
 }