@wordpress/components 19.6.1 → 19.8.0

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

@@ -0,0 +1,305 @@
+/**
+ * Internal dependencies
+ */
+import {
+	getBorderDiff,
+	getCommonBorder,
+	getShorthandBorderStyle,
+	getSplitBorders,
+	hasMixedBorders,
+	hasSplitBorders,
+	isCompleteBorder,
+	isDefinedBorder,
+	isEmptyBorder,
+} from '../utils';
+
+const completeBorder = { color: '#000', style: 'solid', width: '1px' };
+const partialBorder = { color: undefined, style: undefined, width: '2px' };
+const partialWithExtraProp = { color: '#fff', unrelated: true };
+const nonBorder = { unrelatedProperty: true };
+
+const splitBorders = {
+	top: completeBorder,
+	right: completeBorder,
+	bottom: completeBorder,
+	left: completeBorder,
+};
+const undefinedSplitBorders = {
+	top: undefined,
+	right: undefined,
+	bottom: undefined,
+	left: undefined,
+};
+const mixedBorders = {
+	top: completeBorder,
+	right: completeBorder,
+	bottom: completeBorder,
+	left: { color: '#fff', style: 'dashed', width: '10px' },
+};
+const mixedBordersWithUndefined = {
+	top: undefined,
+	right: undefined,
+	bottom: completeBorder,
+	left: partialBorder,
+};
+
+describe( 'BorderBoxControl Utils', () => {
+	describe( 'isEmptyBorder', () => {
+		it( 'should determine a undefined, null, and {} to be empty', () => {
+			expect( isEmptyBorder( undefined ) ).toBe( true );
+			expect( isEmptyBorder( null ) ).toBe( true );
+			expect( isEmptyBorder( {} ) ).toBe( true );
+		} );
+
+		it( 'should determine object missing all border props to be empty', () => {
+			expect( isEmptyBorder( nonBorder ) ).toBe( true );
+		} );
+
+		it( 'should determine that a border object with all properties is not empty', () => {
+			expect( isEmptyBorder( completeBorder ) ).toBe( false );
+		} );
+
+		it( 'should determine object with at least one border property as non-empty', () => {
+			expect( isEmptyBorder( partialWithExtraProp ) ).toBe( false );
+		} );
+	} );
+
+	describe( 'isDefinedBorder', () => {
+		it( 'should determine undefined is not a defined border', () => {
+			expect( isDefinedBorder( undefined ) ).toBe( false );
+		} );
+
+		it( 'should determine an empty object to be an undefined border', () => {
+			expect( isDefinedBorder( {} ) ).toBe( false );
+		} );
+
+		it( 'should determine an border object with undefined properties to be an undefined border', () => {
+			const emptyBorder = {
+				color: undefined,
+				style: undefined,
+				width: undefined,
+			};
+			expect( isDefinedBorder( emptyBorder ) ).toBe( false );
+		} );
+
+		it( 'should class an object with at least one side border as defined', () => {
+			expect( isDefinedBorder( mixedBordersWithUndefined ) ).toBe( true );
+		} );
+
+		it( 'should determine complete split borders object is defined border', () => {
+			expect( isDefinedBorder( splitBorders ) ).toBe( true );
+		} );
+
+		it( 'should determine border is not defined when all sides are empty', () => {
+			const mixedUndefinedBorders = {
+				top: undefined,
+				right: undefined,
+				bottom: {},
+				left: {
+					color: undefined,
+					style: undefined,
+					width: undefined,
+				},
+			};
+
+			expect( isDefinedBorder( undefinedSplitBorders ) ).toBe( false );
+			expect( isDefinedBorder( mixedUndefinedBorders ) ).toBe( false );
+		} );
+	} );
+
+	describe( 'isCompleteBorder', () => {
+		it( 'should determine a undefined, null, and {} to be incomplete', () => {
+			expect( isCompleteBorder( undefined ) ).toBe( false );
+			expect( isCompleteBorder( null ) ).toBe( false );
+			expect( isCompleteBorder( {} ) ).toBe( false );
+		} );
+
+		it( 'should determine objects missing border props to be incomplete', () => {
+			expect( isCompleteBorder( nonBorder ) ).toBe( false );
+			expect( isCompleteBorder( partialBorder ) ).toBe( false );
+			expect( isCompleteBorder( partialWithExtraProp ) ).toBe( false );
+		} );
+
+		it( 'should determine that a border object with all properties is complete', () => {
+			expect( isCompleteBorder( completeBorder ) ).toBe( true );
+		} );
+	} );
+
+	describe( 'hasSplitBorders', () => {
+		it( 'should determine empty or undefined borders as not being split', () => {
+			expect( hasSplitBorders( undefined ) ).toBe( false );
+			expect( hasSplitBorders( {} ) ).toBe( false );
+		} );
+
+		it( 'should determine flat border object as not being split', () => {
+			expect( hasSplitBorders( completeBorder ) ).toBe( false );
+		} );
+
+		it( 'should determine object with at least one side property as split', () => {
+			expect( hasSplitBorders( splitBorders ) ).toBe( true );
+			expect( hasSplitBorders( { top: completeBorder } ) ).toBe( true );
+		} );
+
+		it( 'should determine object with undefined sides but containing properties as split', () => {
+			expect( hasSplitBorders( undefinedSplitBorders ) ).toBe( true );
+		} );
+	} );
+
+	describe( 'hasMixedBorders', () => {
+		it( 'should determine undefined, non-border or empty object as not being mixed', () => {
+			expect( hasMixedBorders( undefined ) ).toBe( false );
+			expect( hasMixedBorders( {} ) ).toBe( false );
+			expect( hasMixedBorders( nonBorder ) ).toBe( false );
+		} );
+
+		it( 'should determine flat border object as not being mixed', () => {
+			expect( hasMixedBorders( completeBorder ) ).toBe( false );
+		} );
+
+		it( 'should determine split border object with some undefined side borders as mixed', () => {
+			expect( hasMixedBorders( mixedBordersWithUndefined ) ).toBe( true );
+		} );
+
+		it( 'should determine split border object with different side borders as mixed', () => {
+			expect( hasMixedBorders( mixedBorders ) ).toBe( true );
+		} );
+	} );
+
+	describe( 'getSplitBorders', () => {
+		it( 'should return undefined when no border provided', () => {
+			expect( getSplitBorders( undefined ) ).toEqual( undefined );
+			expect( getSplitBorders( null ) ).toEqual( undefined );
+		} );
+
+		it( 'should return undefined when supplied border is empty', () => {
+			expect( getSplitBorders( {} ) ).toEqual( undefined );
+			expect( getSplitBorders( nonBorder ) ).toEqual( undefined );
+		} );
+
+		it( 'should return object with all sides populated when given valid border', () => {
+			expect( getSplitBorders( completeBorder ) ).toEqual( {
+				top: completeBorder,
+				right: completeBorder,
+				bottom: completeBorder,
+				left: completeBorder,
+			} );
+		} );
+	} );
+
+	describe( 'getBorderDiff', () => {
+		it( 'should return empty object when there are no differences', () => {
+			const diff = getBorderDiff( completeBorder, completeBorder );
+			expect( diff ).toEqual( {} );
+		} );
+
+		it( 'should only return differences for border related properties', () => {
+			const diff = getBorderDiff( nonBorder, { caffeine: 'coffee' } );
+			expect( diff ).toEqual( {} );
+		} );
+
+		it( 'should return object with only border properties that have changed', () => {
+			const diff = getBorderDiff( completeBorder, {
+				...completeBorder,
+				color: '#21759b',
+				caffeine: 'cola',
+			} );
+			expect( diff ).toEqual( { color: '#21759b' } );
+		} );
+	} );
+
+	describe( 'getCommonBorder', () => {
+		it( 'should return undefined when no borders supplied', () => {
+			expect( getCommonBorder( undefined ) ).toEqual( undefined );
+		} );
+
+		it( 'should return border object with undefined properties when undefined borders given', () => {
+			const undefinedBorder = {
+				color: undefined,
+				style: undefined,
+				width: undefined,
+			};
+
+			expect( getCommonBorder( {} ) ).toEqual( undefinedBorder );
+			expect( getCommonBorder( undefinedSplitBorders ) ).toEqual(
+				undefinedBorder
+			);
+		} );
+
+		it( 'should return flat border object when split borders are the same', () => {
+			expect( getCommonBorder( splitBorders ) ).toEqual( completeBorder );
+		} );
+
+		it( 'should only set properties where every side border shares the same value', () => {
+			const sideBorders = {
+				top: { color: '#fff', style: 'solid', width: '1px' },
+				right: { color: '#000', style: 'solid', width: '1px' },
+				bottom: { color: '#000', style: 'solid', width: '1px' },
+				left: { color: '#000', style: undefined, width: '1px' },
+			};
+			const commonBorder = {
+				color: undefined,
+				style: undefined,
+				width: '1px',
+			};
+
+			expect( getCommonBorder( sideBorders ) ).toEqual( commonBorder );
+		} );
+	} );
+
+	describe( 'getShorthandBorderStyle', () => {
+		it( 'should return undefined when no border provided', () => {
+			expect( getShorthandBorderStyle( undefined ) ).toEqual( undefined );
+			expect( getShorthandBorderStyle( {} ) ).toEqual( undefined );
+			expect( getShorthandBorderStyle( nonBorder ) ).toEqual( undefined );
+		} );
+
+		it( 'should generate correct shorthand style from valid border', () => {
+			const style = getShorthandBorderStyle( completeBorder );
+			expect( style ).toEqual( '1px solid #000' );
+		} );
+
+		it( 'should generate correct style from partial border', () => {
+			const style = getShorthandBorderStyle( {
+				style: 'dashed',
+				width: '2px',
+			} );
+			expect( style ).toEqual( '2px dashed' );
+		} );
+
+		it( 'should default borders with either color or width to solid style', () => {
+			const widthOnlyStyle = getShorthandBorderStyle( { width: '5px' } );
+			const colorOnlyStyle = getShorthandBorderStyle( { color: '#000' } );
+
+			expect( widthOnlyStyle ).toEqual( '5px solid' );
+			expect( colorOnlyStyle ).toEqual( 'solid #000' );
+		} );
+
+		it( 'should not default border style to solid for zero width border', () => {
+			const zeroWidthStyle = getShorthandBorderStyle( { width: '0' } );
+			expect( zeroWidthStyle ).toEqual( '0' );
+		} );
+
+		it( 'should return undefined when no border or fallback supplied', () => {
+			expect( getShorthandBorderStyle() ).toBe( undefined );
+		} );
+
+		it( 'should return fallback border when border is undefined', () => {
+			const result = getShorthandBorderStyle( undefined, completeBorder );
+			expect( result ).toEqual( completeBorder );
+		} );
+
+		it( 'should return fallback border when empty border supplied', () => {
+			const result = getShorthandBorderStyle( {}, completeBorder );
+			expect( result ).toEqual( completeBorder );
+		} );
+
+		it( 'should use fallback border properties if missing from border', () => {
+			const result = getShorthandBorderStyle(
+				{ width: '1em' },
+				{ width: '5px', style: 'dashed', color: '#72aee6' }
+			);
+
+			expect( result ).toEqual( `1em dashed #72aee6` );
+		} );
+	} );
+} );

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

@@ -0,0 +1,98 @@
+/**
+ * Internal dependencies
+ */
+import type { Border, ColorProps, LabelProps } from '../border-control/types';
+
+export type Borders = {
+	top?: Border;
+	right?: Border;
+	bottom?: Border;
+	left?: Border;
+};
+
+export type AnyBorder = Border | Borders | undefined;
+export type BorderProp = keyof Border;
+export type BorderSide = keyof Borders;
+
+export type PopoverClassNames = {
+	linked?: string;
+	top?: string;
+	right?: string;
+	bottom?: string;
+	left?: string;
+};
+
+export type BorderBoxControlProps = ColorProps &
+	LabelProps & {
+		/**
+		 * This controls whether to support border style selections.
+		 */
+		enableStyle?: boolean;
+		/**
+		 * A callback function invoked when any border value is changed. The value
+		 * received may be a "flat" border object, one that has properties defining
+		 * individual side borders, or `undefined`.
+		 */
+		onChange: ( value: AnyBorder ) => void;
+		/**
+		 * An object defining CSS classnames for all the inner `BorderControl`
+		 * popover content.
+		 */
+		popoverClassNames?: PopoverClassNames;
+		/**
+		 * An object representing the current border configuration.
+		 *
+		 * This may be a "flat" border where the object has `color`, `style`, and
+		 * `width` properties or a "split" border which defines the previous
+		 * properties but for each side; `top`, `right`, `bottom`, and `left`.
+		 */
+		value: AnyBorder;
+	};
+
+export type LinkedButtonProps = {
+	/**
+	 * This prop allows the `LinkedButton` to reflect whether the parent
+	 * `BorderBoxControl` is currently displaying "linked" or "unlinked"
+	 * border controls.
+	 */
+	isLinked: boolean;
+	/**
+	 * A callback invoked when this `LinkedButton` is clicked. It is used to
+	 * toggle display between linked or split border controls within the parent
+	 * `BorderBoxControl`.
+	 */
+	onClick: () => void;
+};
+
+export type VisualizerProps = {
+	/**
+	 * An object representing the current border configuration. It contains
+	 * properties for each side, with each side an object reflecting the border
+	 * color, style, and width.
+	 */
+	value?: Borders;
+};
+
+export type SplitControlsProps = ColorProps & {
+	/**
+	 * This controls whether to include border style options within the
+	 * individual `BorderControl` components.
+	 */
+	enableStyle?: boolean;
+	/**
+	 * A callback that is invoked whenever an individual side's border has
+	 * changed.
+	 */
+	onChange: ( value: Border | undefined, side: BorderSide ) => void;
+	/**
+	 * An object defining CSS classnames for the split side `BorderControl`s'
+	 * popover content.
+	 */
+	popoverClassNames?: PopoverClassNames;
+	/**
+	 * An object representing the current border configuration. It contains
+	 * properties for each side, with each side an object reflecting the border
+	 * color, style, and width.
+	 */
+	value?: Borders;
+};

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

@@ -0,0 +1,151 @@
+/**
+ * External dependencies
+ */
+import type { CSSProperties } from 'react';
+
+/**
+ * Internal dependencies
+ */
+import type { Border } from '../border-control/types';
+import type { AnyBorder, Borders, BorderProp, BorderSide } from './types';
+
+const sides: BorderSide[] = [ 'top', 'right', 'bottom', 'left' ];
+const borderProps: BorderProp[] = [ 'color', 'style', 'width' ];
+
+export const isEmptyBorder = ( border?: Border ) => {
+	if ( ! border ) {
+		return true;
+	}
+	return ! borderProps.some( ( prop ) => border[ prop ] !== undefined );
+};
+
+export const isDefinedBorder = ( border: AnyBorder ) => {
+	// No border, no worries :)
+	if ( ! border ) {
+		return false;
+	}
+
+	// If we have individual borders per side within the border object we
+	// need to check whether any of those side borders have been set.
+	if ( hasSplitBorders( border ) ) {
+		const allSidesEmpty = sides.every( ( side ) =>
+			isEmptyBorder( ( border as Borders )[ side ] )
+		);
+
+		return ! allSidesEmpty;
+	}
+
+	// If we have a top-level border only, check if that is empty. e.g.
+	// { color: undefined, style: undefined, width: undefined }
+	// Border radius can still be set within the border object as it is
+	// handled separately.
+	return ! isEmptyBorder( border as Border );
+};
+
+export const isCompleteBorder = ( border?: Border ) => {
+	if ( ! border ) {
+		return false;
+	}
+
+	return borderProps.every( ( prop ) => border[ prop ] !== undefined );
+};
+
+export const hasSplitBorders = ( border: AnyBorder = {} ) => {
+	return Object.keys( border ).some(
+		( side ) => sides.indexOf( side as BorderSide ) !== -1
+	);
+};
+
+export const hasMixedBorders = ( borders: AnyBorder ) => {
+	if ( ! hasSplitBorders( borders ) ) {
+		return false;
+	}
+
+	const shorthandBorders = sides.map( ( side: BorderSide ) =>
+		getShorthandBorderStyle( ( borders as Borders )?.[ side ] )
+	);
+
+	return ! shorthandBorders.every(
+		( border ) => border === shorthandBorders[ 0 ]
+	);
+};
+
+export const getSplitBorders = ( border?: Border ) => {
+	if ( ! border || isEmptyBorder( border ) ) {
+		return undefined;
+	}
+
+	return {
+		top: border,
+		right: border,
+		bottom: border,
+		left: border,
+	};
+};
+
+export const getBorderDiff = ( original: Border, updated: Border ) => {
+	const diff: Border = {};
+
+	if ( original.color !== updated.color ) {
+		diff.color = updated.color;
+	}
+
+	if ( original.style !== updated.style ) {
+		diff.style = updated.style;
+	}
+
+	if ( original.width !== updated.width ) {
+		diff.width = updated.width;
+	}
+
+	return diff;
+};
+
+export const getCommonBorder = ( borders?: Borders ) => {
+	if ( ! borders ) {
+		return undefined;
+	}
+
+	const colors: ( CSSProperties[ 'borderColor' ] | undefined )[] = [];
+	const styles: ( CSSProperties[ 'borderStyle' ] | undefined )[] = [];
+	const widths: ( CSSProperties[ 'borderWidth' ] | undefined )[] = [];
+
+	sides.forEach( ( side ) => {
+		colors.push( borders[ side ]?.color );
+		styles.push( borders[ side ]?.style );
+		widths.push( borders[ side ]?.width );
+	} );
+
+	const allColorsMatch = colors.every( ( value ) => value === colors[ 0 ] );
+	const allStylesMatch = styles.every( ( value ) => value === styles[ 0 ] );
+	const allWidthsMatch = widths.every( ( value ) => value === widths[ 0 ] );
+
+	return {
+		color: allColorsMatch ? colors[ 0 ] : undefined,
+		style: allStylesMatch ? styles[ 0 ] : undefined,
+		width: allWidthsMatch ? widths[ 0 ] : undefined,
+	};
+};
+
+export const getShorthandBorderStyle = (
+	border?: Border,
+	fallbackBorder?: Border
+) => {
+	if ( isEmptyBorder( border ) ) {
+		return fallbackBorder;
+	}
+
+	const { color: fallbackColor, style: fallbackStyle, width: fallbackWidth } =
+		fallbackBorder || {};
+
+	const {
+		color = fallbackColor,
+		style = fallbackStyle,
+		width = fallbackWidth,
+	} = border as Border;
+
+	const hasVisibleBorder = ( !! width && width !== '0' ) || !! color;
+	const borderStyle = hasVisibleBorder ? style || 'solid' : style;
+
+	return [ width, borderStyle, color ].filter( Boolean ).join( ' ' );
+};