@wordpress/components 19.6.1 → 19.8.0

package/src/border-box-control/border-box-control-visualizer/component.tsx

@@ -0,0 +1,28 @@
+/**
+ * WordPress dependencies
+ */
+import { __ } from '@wordpress/i18n';
+
+/**
+ * Internal dependencies
+ */
+import { View } from '../../view';
+import { contextConnect, WordPressComponentProps } from '../../ui/context';
+import { useBorderBoxControlVisualizer } from './hook';
+
+import type { VisualizerProps } from '../types';
+
+const BorderBoxControlVisualizer = (
+	props: WordPressComponentProps< VisualizerProps, 'div' >,
+	forwardedRef: React.ForwardedRef< any >
+) => {
+	const { value, ...otherProps } = useBorderBoxControlVisualizer( props );
+
+	return <View { ...otherProps } ref={ forwardedRef } />;
+};
+
+const ConnectedBorderBoxControlVisualizer = contextConnect(
+	BorderBoxControlVisualizer,
+	'BorderBoxControlVisualizer'
+);
+export default ConnectedBorderBoxControlVisualizer;

package/src/border-box-control/border-box-control-visualizer/hook.ts

@@ -0,0 +1,30 @@
+/**
+ * WordPress dependencies
+ */
+import { useMemo } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import * as styles from '../styles';
+import { useContextSystem, WordPressComponentProps } from '../../ui/context';
+import { useCx, rtl } from '../../utils';
+
+import type { VisualizerProps } from '../types';
+
+export function useBorderBoxControlVisualizer(
+	props: WordPressComponentProps< VisualizerProps, 'div' >
+) {
+	const { className, value, ...otherProps } = useContextSystem(
+		props,
+		'BorderBoxControlVisualizer'
+	);
+
+	// Generate class names.
+	const cx = useCx();
+	const classes = useMemo( () => {
+		return cx( styles.BorderBoxControlVisualizer( value ), className );
+	}, [ className, value, rtl.watch() ] );
+
+	return { ...otherProps, className: classes, value };
+}

package/src/border-box-control/border-box-control-visualizer/index.ts

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

package/src/border-box-control/index.ts

@@ -0,0 +1,3 @@
+export { default as BorderBoxControl } from './border-box-control/component';
+export { useBorderBoxControl } from './border-box-control/hook';
+export { hasSplitBorders, isEmptyBorder, isDefinedBorder } from './utils';

package/src/border-box-control/stories/index.js

@@ -0,0 +1,104 @@
+/**
+ * External dependencies
+ */
+import styled from '@emotion/styled';
+
+/**
+ * WordPress dependencies
+ */
+import { useEffect, useState } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import Button from '../../button';
+import Popover from '../../popover';
+import { BorderBoxControl } from '../';
+import { Provider as SlotFillProvider } from '../../slot-fill';
+
+// Available border colors.
+const colors = [
+	{ name: 'Gray 0', color: '#f6f7f7' },
+	{ name: 'Gray 5', color: '#dcdcde' },
+	{ name: 'Gray 20', color: '#a7aaad' },
+	{ name: 'Gray 70', color: '#3c434a' },
+	{ name: 'Gray 100', color: '#101517' },
+	{ name: 'Blue 20', color: '#72aee6' },
+	{ name: 'Blue 40', color: '#3582c4' },
+	{ name: 'Blue 70', color: '#0a4b78' },
+	{ name: 'Red 40', color: '#e65054' },
+	{ name: 'Red 70', color: '#8a2424' },
+	{ name: 'Green 10', color: '#68de7c' },
+	{ name: 'Green 40', color: '#00a32a' },
+	{ name: 'Green 60', color: '#007017' },
+	{ name: 'Yellow 10', color: '#f2d675' },
+	{ name: 'Yellow 40', color: '#bd8600' },
+];
+
+export default {
+	title: 'Components (Experimental)/BorderBoxControl',
+	component: BorderBoxControl,
+	parameters: {
+		knobs: { disable: false },
+	},
+};
+
+const _default = ( props ) => {
+	const { defaultBorder } = props;
+	const [ borders, setBorders ] = useState( defaultBorder );
+
+	useEffect( () => setBorders( defaultBorder ), [ defaultBorder ] );
+
+	return (
+		<SlotFillProvider>
+			<WrapperView>
+				<BorderBoxControl
+					colors={ colors }
+					label="Borders"
+					onChange={ ( newBorders ) => setBorders( newBorders ) }
+					value={ borders }
+					{ ...props }
+				/>
+			</WrapperView>
+			<Separator />
+			<HelpText>
+				The BorderBoxControl is intended to be used within a component
+				that will provide reset controls. The button below is only for
+				convenience.
+			</HelpText>
+			<Button variant="primary" onClick={ () => setBorders( undefined ) }>
+				Reset
+			</Button>
+			<Popover.Slot />
+		</SlotFillProvider>
+	);
+};
+
+export const Default = _default.bind( {} );
+Default.args = {
+	disableCustomColors: false,
+	enableAlpha: true,
+	enableStyle: true,
+	defaultBorder: {
+		color: '#72aee6',
+		style: 'dashed',
+		width: '1px',
+	},
+};
+
+const WrapperView = styled.div`
+	max-width: 280px;
+	padding: 16px;
+`;
+
+const Separator = styled.hr`
+	margin-top: 100px;
+	border-color: #ddd;
+	border-style: solid;
+	border-bottom: none;
+`;
+
+const HelpText = styled.p`
+	color: #aaa;
+	font-size: 0.9em;
+`;

package/src/border-box-control/styles.ts

@@ -0,0 +1,69 @@
+/**
+ * External dependencies
+ */
+import { css } from '@emotion/react';
+
+/**
+ * Internal dependencies
+ */
+import { COLORS, CONFIG, rtl } from '../utils';
+import { space } from '../ui/utils/space';
+
+import type { Border } from '../border-control/types';
+import type { Borders } from './types';
+
+export const BorderBoxControl = css``;
+
+export const LinkedBorderControl = css`
+	flex: 1;
+`;
+
+export const BorderBoxControlLinkedButton = css`
+	flex: 0;
+	flex-basis: 36px;
+	margin-top: 7px;
+`;
+
+const BorderBoxStyleWithFallback = ( border?: Border ) => {
+	const {
+		color = COLORS.gray[ 200 ],
+		style = 'solid',
+		width = CONFIG.borderWidth,
+	} = border || {};
+
+	const clampedWidth =
+		width !== CONFIG.borderWidth ? `clamp(1px, ${ width }, 10px)` : width;
+	const hasVisibleBorder = ( !! width && width !== '0' ) || !! color;
+	const borderStyle = hasVisibleBorder ? style || 'solid' : style;
+
+	return `${ color } ${ borderStyle } ${ clampedWidth }`;
+};
+
+export const BorderBoxControlVisualizer = ( borders?: Borders ) => {
+	return css`
+		position: absolute;
+		top: 20px;
+		right: 30px;
+		bottom: 20px;
+		left: 30px;
+		border-top: ${ BorderBoxStyleWithFallback( borders?.top ) };
+		border-bottom: ${ BorderBoxStyleWithFallback( borders?.bottom ) };
+		${ rtl( {
+			borderLeft: BorderBoxStyleWithFallback( borders?.left ),
+		} )() }
+		${ rtl( {
+			borderRight: BorderBoxStyleWithFallback( borders?.right ),
+		} )() }
+	`;
+};
+
+export const BorderBoxControlSplitControls = css`
+	position: relative;
+	flex: 1;
+	${ rtl( { marginRight: space( 3 ) }, { marginLeft: space( 3 ) } )() }
+`;
+
+export const CenteredBorderControl = css`
+	grid-column: span 2;
+	margin: 0 auto;
+`;

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

@@ -0,0 +1,354 @@
+/**
+ * External dependencies
+ */
+import { fireEvent, render, screen } from '@testing-library/react';
+
+/**
+ * Internal dependencies
+ */
+import { BorderBoxControl } 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 defaultBorders = {
+	top: defaultBorder,
+	right: defaultBorder,
+	bottom: defaultBorder,
+	left: defaultBorder,
+};
+
+const mixedBorders = {
+	top: { color: '#f6f7f7', style: 'solid', width: '1px' },
+	right: { color: '#e65054', style: 'dashed', width: undefined },
+	bottom: { color: undefined, style: 'dotted', width: '2rem' },
+	left: { color: '#bd8600', style: undefined, width: '0.75em' },
+};
+
+const props = {
+	colors,
+	label: 'Border Box',
+	onChange: jest.fn().mockImplementation( ( newValue ) => {
+		props.value = newValue;
+	} ),
+	value: undefined,
+};
+
+const toggleLabelRegex = /Border color( and style)* picker/;
+const colorPickerRegex = /Border color picker/;
+
+const renderBorderBoxControl = ( customProps ) => {
+	return render( <BorderBoxControl { ...{ ...props, ...customProps } } /> );
+};
+
+const clickButton = ( name ) => {
+	fireEvent.click( screen.getByRole( 'button', { name } ) );
+};
+
+const queryButton = ( name ) => {
+	return screen.queryByRole( 'button', { name } );
+};
+
+const updateLinkedWidthInput = ( value ) => {
+	const widthInput = screen.getByRole( 'spinbutton' );
+	widthInput.focus();
+	fireEvent.change( widthInput, { target: { value } } );
+};
+
+const updateSplitWidthInput = ( value, index = 0 ) => {
+	const splitInputs = screen.getAllByRole( 'spinbutton' );
+	splitInputs[ index ].focus();
+	fireEvent.change( splitInputs[ index ], { target: { value } } );
+};
+
+describe( 'BorderBoxControl', () => {
+	describe( 'Linked view rendering', () => {
+		it( 'should render correctly when no value provided', () => {
+			renderBorderBoxControl();
+
+			const label = screen.getByText( props.label );
+			const colorButton = screen.getByLabelText( toggleLabelRegex );
+			const widthInput = screen.getByRole( 'spinbutton' );
+			const unitSelect = screen.getByRole( 'combobox' );
+			const slider = screen.getByRole( 'slider' );
+			const linkedButton = screen.getByLabelText( 'Unlink sides' );
+
+			expect( label ).toBeInTheDocument();
+			expect( colorButton ).toBeInTheDocument();
+			expect( widthInput ).toBeInTheDocument();
+			expect( widthInput ).not.toHaveAttribute( 'placeholder' );
+			expect( unitSelect ).toBeInTheDocument();
+			expect( slider ).toBeInTheDocument();
+			expect( linkedButton ).toBeInTheDocument();
+		} );
+
+		it( 'should hide label', () => {
+			renderBorderBoxControl( { 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 show correct width value when flat border value provided', () => {
+			renderBorderBoxControl( { value: defaultBorder } );
+			const widthInput = screen.getByRole( 'spinbutton' );
+
+			expect( widthInput.value ).toBe( '1' );
+		} );
+
+		it( 'should show correct width value when consistent split borders provided', () => {
+			renderBorderBoxControl( { value: defaultBorders } );
+			const widthInput = screen.getByRole( 'spinbutton' );
+
+			expect( widthInput.value ).toBe( '1' );
+		} );
+
+		it( 'should render placeholder when border values are mixed', () => {
+			renderBorderBoxControl( { value: mixedBorders } );
+
+			// First render of control with mixed values should show split view.
+			clickButton( 'Link sides' );
+
+			const widthInput = screen.getByRole( 'spinbutton' );
+			expect( widthInput ).toHaveAttribute( 'placeholder', 'Mixed' );
+		} );
+
+		it( 'should render shared border width when switching to linked view', async () => {
+			// Render control with mixed border values but consistent widths.
+			renderBorderBoxControl( {
+				value: {
+					top: { color: 'red', width: '5px', style: 'solid' },
+					right: { color: 'blue', width: '5px', style: 'dashed' },
+					bottom: { color: 'green', width: '5px', style: 'solid' },
+					left: { color: 'yellow', width: '5px', style: 'dotted' },
+				},
+			} );
+
+			// First render of control with mixed values should show split view.
+			clickButton( 'Link sides' );
+			const linkedInput = screen.getByRole( 'spinbutton' );
+
+			expect( linkedInput.value ).toBe( '5' );
+		} );
+
+		it( 'should omit style options when requested', () => {
+			renderBorderBoxControl( { enableStyle: false } );
+
+			const colorButton = screen.getByLabelText( colorPickerRegex );
+			fireEvent.click( colorButton );
+
+			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( 'Split view rendering', () => {
+		it( 'should render split view by default when mixed values provided', () => {
+			renderBorderBoxControl( { value: mixedBorders } );
+
+			const colorButtons = screen.getAllByLabelText( toggleLabelRegex );
+			const widthInputs = screen.getAllByRole( 'spinbutton' );
+			const unitSelects = screen.getAllByRole( 'combobox' );
+			const sliders = screen.queryAllByRole( 'slider' );
+			const linkedButton = screen.getByLabelText( 'Link sides' );
+
+			expect( colorButtons.length ).toBe( 4 );
+			expect( widthInputs.length ).toBe( 4 );
+			expect( unitSelects.length ).toBe( 4 );
+			expect( sliders.length ).toBe( 0 );
+			expect( linkedButton ).toBeInTheDocument();
+		} );
+
+		it( 'should render correct width values in appropriate inputs', () => {
+			renderBorderBoxControl( { value: mixedBorders } );
+
+			const widthInputs = screen.getAllByRole( 'spinbutton' );
+
+			expect( widthInputs[ 0 ].value ).toBe( '1' ); // Top.
+			expect( widthInputs[ 1 ].value ).toBe( '0.75' ); // Left.
+			expect( widthInputs[ 2 ].value ).toBe( '' ); // Right.
+			expect( widthInputs[ 3 ].value ).toBe( '2' ); // Bottom.
+		} );
+
+		it( 'should render split view correctly when starting with flat border', () => {
+			renderBorderBoxControl( { value: defaultBorders } );
+			clickButton( 'Unlink sides' );
+
+			const widthInputs = screen.getAllByRole( 'spinbutton' );
+			expect( widthInputs[ 0 ].value ).toBe( '1' ); // Top.
+			expect( widthInputs[ 1 ].value ).toBe( '1' ); // Left.
+			expect( widthInputs[ 2 ].value ).toBe( '1' ); // Right.
+			expect( widthInputs[ 3 ].value ).toBe( '1' ); // Bottom.
+		} );
+
+		it( 'should omit style options when requested', () => {
+			renderBorderBoxControl( { enableStyle: false } );
+			clickButton( 'Unlink sides' );
+
+			const colorButtons = screen.getAllByLabelText( colorPickerRegex );
+
+			colorButtons.forEach( ( button ) => {
+				fireEvent.click( button );
+
+				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();
+
+				fireEvent.click( button );
+			} );
+		} );
+	} );
+
+	describe( 'onChange handling', () => {
+		beforeEach( () => {
+			jest.clearAllMocks();
+			props.value = undefined;
+		} );
+
+		describe( 'Linked value change handling', () => {
+			it( 'should set undefined when new border is empty', () => {
+				renderBorderBoxControl( { value: { width: '1px' } } );
+				updateLinkedWidthInput( '' );
+
+				expect( props.onChange ).toHaveBeenCalledWith( undefined );
+			} );
+
+			it( 'should update with complete flat border', () => {
+				renderBorderBoxControl( { value: defaultBorder } );
+				updateLinkedWidthInput( '3' );
+
+				expect( props.onChange ).toHaveBeenCalledWith( {
+					...defaultBorder,
+					width: '3px',
+				} );
+			} );
+
+			it( 'should maintain mixed values if not explicitly set via linked control', () => {
+				renderBorderBoxControl( {
+					value: {
+						top: { color: '#72aee6' },
+						right: { color: '#f6f7f7', style: 'dashed' },
+						bottom: { color: '#e65054', style: 'dotted' },
+						left: { color: undefined },
+					},
+				} );
+
+				clickButton( 'Link sides' );
+				updateLinkedWidthInput( '4' );
+
+				expect( props.onChange ).toHaveBeenCalledWith( {
+					top: { color: '#72aee6', width: '4px' },
+					right: { color: '#f6f7f7', style: 'dashed', width: '4px' },
+					bottom: { color: '#e65054', style: 'dotted', width: '4px' },
+					left: { color: undefined, width: '4px' },
+				} );
+			} );
+
+			it( 'should update with consistent split borders', () => {
+				renderBorderBoxControl( { value: defaultBorders } );
+				updateLinkedWidthInput( '10' );
+
+				expect( props.onChange ).toHaveBeenCalledWith( {
+					...defaultBorder,
+					width: '10px',
+				} );
+			} );
+
+			it( 'should set undefined borders when change results in empty borders', () => {
+				renderBorderBoxControl( {
+					value: {
+						top: { width: '1px' },
+						right: { width: '1px' },
+						bottom: { width: '1px' },
+						left: { width: '1px' },
+					},
+				} );
+				updateLinkedWidthInput( '' );
+
+				expect( props.onChange ).toHaveBeenCalledWith( undefined );
+			} );
+
+			it( 'should set flat border when change results in consistent split borders', () => {
+				renderBorderBoxControl( {
+					value: {
+						top: { ...defaultBorder, width: '1px' },
+						right: { ...defaultBorder, width: '2px' },
+						bottom: { ...defaultBorder, width: '3px' },
+						left: { ...defaultBorder, width: '4px' },
+					},
+				} );
+
+				clickButton( 'Link sides' );
+				updateLinkedWidthInput( '10' );
+
+				expect( props.onChange ).toHaveBeenCalledWith( {
+					...defaultBorder,
+					width: '10px',
+				} );
+			} );
+		} );
+
+		describe( 'Split value change handling', () => {
+			it( 'should set split borders when the updated borders are mixed', () => {
+				const borders = {
+					top: { ...defaultBorder, width: '1px' },
+					right: { ...defaultBorder, width: '2px' },
+					bottom: { ...defaultBorder, width: '3px' },
+					left: { ...defaultBorder, width: '4px' },
+				};
+
+				renderBorderBoxControl( { value: borders } );
+				updateSplitWidthInput( '5' );
+
+				expect( props.onChange ).toHaveBeenCalledWith( {
+					...borders,
+					top: { ...defaultBorder, width: '5px' },
+				} );
+			} );
+
+			it( 'should set flat border when updated borders are consistent', () => {
+				const borders = {
+					top: { ...defaultBorder, width: '4px' },
+					right: { ...defaultBorder, width: '1px' },
+					bottom: { ...defaultBorder, width: '1px' },
+					left: { ...defaultBorder, width: '1px' },
+				};
+
+				renderBorderBoxControl( { value: borders } );
+				updateSplitWidthInput( '1' );
+
+				expect( props.onChange ).toHaveBeenCalledWith( defaultBorder );
+			} );
+		} );
+	} );
+} );