@wordpress/components 19.7.0 → 19.9.0

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( ' ' );
+};

package/src/border-control/border-control/README.md

@@ -0,0 +1,181 @@
+#  BorderControl
+
+<div class="callout callout-alert">
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+</div>
+<br />
+This component provides control over a border's color, style, and width.
+
+## Development guidelines
+
+The `BorderControl` brings together internal sub-components which allow users to
+set the various properties of a border. The first sub-component, a
+`BorderDropdown` contains options representing border color and style. The
+border width is controlled via a `UnitControl` and an optional `RangeControl`.
+
+Border radius is not covered by this control as it may be desired separate to
+color, style, and width. For example, the border radius may be absorbed under
+a "shape" abstraction.
+
+## Usage
+
+```jsx
+import { __experimentalBorderControl as BorderControl } from '@wordpress/components';
+import { __ } from '@wordpress/i18n';
+
+const colors = [
+	{ name: 'Blue 20', color: '#72aee6' },
+	// ...
+];
+
+const MyBorderControl = () => {
+	const [ border, setBorder ] = useState();
+	const onChange = ( newBorder ) => setBorder( newBorder );
+
+	return (
+		<BorderControl
+			colors={ colors }
+			label={ __( 'Border' ) }
+			onChange={ onChange }
+			value={ border }
+		/>
+	);
+};
+```
+
+If you're using this component outside the editor, you can
+[ensure `Tooltip` positioning](/packages/components/README.md#popovers-and-tooltips)
+for the `BorderControl`'s color and style options, by rendering your
+`BorderControl` with a `Popover.Slot` further up the element tree and within a
+`SlotFillProvider` overall.
+
+## Props
+
+### `colors`: `Array`
+
+An array of color definitions. This may also be a multi-dimensional array where
+colors are organized by multiple origins.
+
+Each color may be an object containing a `name` and `color` value.
+
+- Required: No
+
+### `disableCustomColors`: `boolean`
+
+This toggles the ability to choose custom colors.
+
+- Required: No
+
+### `enableAlpha`: `boolean`
+
+This controls whether the alpha channel will be offered when selecting
+custom colors.
+
+- Required: No
+
+### `enableStyle`: `boolean`
+
+This controls whether to include border style options within the
+`BorderDropdown` sub-component.
+
+- Required: No
+- Default: `true`
+
+### `hideLabelFromVision`: `boolean`
+
+Provides control over whether the label will only be visible to screen readers.
+
+- Required: No
+
+### `isCompact`: `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.
+
+- Required: No
+
+### `label`: `string`
+
+If provided, a label will be generated using this as the content.
+
+_Whether it is visible only to screen readers is controlled via
+`hideLabelFromVision`._
+
+- Required: No
+
+### `onChange`: `( value?: Object ) => void`
+
+A callback function invoked when the border value is changed via an interaction
+that selects or clears, border color, style, or width.
+
+_Note: the value may be `undefined` if a user clears all border properties._
+
+- Required: Yes
+
+### `popoverContentClassName`: `string`
+
+A custom CSS class name to be assigned to the `BorderControl`'s dropdown
+popover content.
+
+- Required: No
+
+### `shouldSanitizeBorder`: `boolean`
+
+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.
+
+- Required: No
+- Default: true
+
+### `showDropdownHeader`: `boolean`
+
+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.
+
+- Required: No
+
+### `value`: `Object`
+
+An object representing a border or `undefined`. Used to set the current border
+configuration for this component.
+
+Example:
+```js
+ {
+	color: '#72aee6',
+	style: 'solid',
+	width: '2px,
+}
+```
+
+- Required: No
+
+### `width`: `CSSProperties[ 'width' ]`
+
+Controls the visual width of the `BorderControl`. It has no effect if the
+`isCompact` prop is set to `true`.
+
+- Required: No
+
+### `withSlider`: `boolean`
+
+Flags whether this `BorderControl` should also render a `RangeControl` for
+additional control over a border's width.
+
+- Required: No
+
+### `__experimentalHasMultipleOrigins`: `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.
+
+- Required: No
+
+### `__experimentalIsRenderedInSidebar`: `boolean`
+
+This is passed on to the color related sub-components so they may render more
+effectively when used within a sidebar.
+
+- Required: No

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

@@ -0,0 +1,112 @@
+/**
+ * Internal dependencies
+ */
+import BorderControlDropdown from '../border-control-dropdown';
+import UnitControl from '../../unit-control';
+import RangeControl from '../../range-control';
+import { HStack } from '../../h-stack';
+import { StyledLabel } from '../../base-control/styles/base-control-styles';
+import { View } from '../../view';
+import { VisuallyHidden } from '../../visually-hidden';
+import { contextConnect, WordPressComponentProps } from '../../ui/context';
+import { useBorderControl } from './hook';
+
+import type { BorderControlProps, LabelProps } from '../types';
+
+const BorderLabel = ( props: LabelProps ) => {
+	const { label, hideLabelFromVision } = props;
+
+	if ( ! label ) {
+		return null;
+	}
+
+	return hideLabelFromVision ? (
+		<VisuallyHidden as="label">{ label }</VisuallyHidden>
+	) : (
+		<StyledLabel>{ label }</StyledLabel>
+	);
+};
+
+const BorderControl = (
+	props: WordPressComponentProps< BorderControlProps, 'div' >,
+	forwardedRef: React.ForwardedRef< any >
+) => {
+	const {
+		colors,
+		disableCustomColors,
+		enableAlpha,
+		enableStyle = true,
+		hideLabelFromVision,
+		innerWrapperClassName,
+		label,
+		onBorderChange,
+		onSliderChange,
+		onWidthChange,
+		placeholder,
+		popoverContentClassName,
+		previousStyleSelection,
+		showDropdownHeader,
+		sliderClassName,
+		value: border,
+		widthControlClassName,
+		widthUnit,
+		widthValue,
+		withSlider,
+		__experimentalHasMultipleOrigins,
+		__experimentalIsRenderedInSidebar,
+		...otherProps
+	} = useBorderControl( props );
+
+	return (
+		<View { ...otherProps } ref={ forwardedRef }>
+			<BorderLabel
+				label={ label }
+				hideLabelFromVision={ hideLabelFromVision }
+			/>
+			<HStack spacing={ 3 }>
+				<HStack className={ innerWrapperClassName } alignment="stretch">
+					<BorderControlDropdown
+						border={ border }
+						colors={ colors }
+						contentClassName={ popoverContentClassName }
+						disableCustomColors={ disableCustomColors }
+						enableAlpha={ enableAlpha }
+						enableStyle={ enableStyle }
+						onChange={ onBorderChange }
+						previousStyleSelection={ previousStyleSelection }
+						showDropdownHeader={ showDropdownHeader }
+						__experimentalHasMultipleOrigins={
+							__experimentalHasMultipleOrigins
+						}
+						__experimentalIsRenderedInSidebar={
+							__experimentalIsRenderedInSidebar
+						}
+					/>
+					<UnitControl
+						className={ widthControlClassName }
+						min={ 0 }
+						onChange={ onWidthChange }
+						value={ border?.width || '' }
+						placeholder={ placeholder }
+					/>
+				</HStack>
+				{ withSlider && (
+					<RangeControl
+						className={ sliderClassName }
+						initialPosition={ 0 }
+						max={ 100 }
+						min={ 0 }
+						onChange={ onSliderChange }
+						step={ [ 'px', '%' ].includes( widthUnit ) ? 1 : 0.1 }
+						value={ widthValue || undefined }
+						withInputField={ false }
+					/>
+				) }
+			</HStack>
+		</View>
+	);
+};
+
+const ConnectedBorderControl = contextConnect( BorderControl, 'BorderControl' );
+
+export default ConnectedBorderControl;

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

@@ -0,0 +1,145 @@
+/**
+ * WordPress dependencies
+ */
+import { useCallback, useMemo, useState } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import * as styles from '../styles';
+import { parseQuantityAndUnitFromRawValue } from '../../unit-control/utils';
+import { useContextSystem, WordPressComponentProps } from '../../ui/context';
+import { useCx } from '../../utils/hooks/use-cx';
+
+import type { Border, BorderControlProps } from '../types';
+
+const sanitizeBorder = ( border?: Border ) => {
+	const hasNoWidth = border?.width === undefined || border.width === '';
+	const hasNoColor = border?.color === undefined;
+
+	// If width and color are undefined, unset any style selection as well.
+	if ( hasNoWidth && hasNoColor ) {
+		return undefined;
+	}
+
+	return border;
+};
+
+export function useBorderControl(
+	props: WordPressComponentProps< BorderControlProps, 'div' >
+) {
+	const {
+		className,
+		isCompact,
+		onChange,
+		shouldSanitizeBorder = true,
+		value: border,
+		width,
+		...otherProps
+	} = useContextSystem( props, 'BorderControl' );
+
+	const [ widthValue, originalWidthUnit ] = parseQuantityAndUnitFromRawValue(
+		border?.width
+	);
+	const widthUnit = originalWidthUnit || 'px';
+	const hadPreviousZeroWidth = widthValue === 0;
+
+	const [ colorSelection, setColorSelection ] = useState< string >();
+	const [ styleSelection, setStyleSelection ] = useState< string >();
+
+	const onBorderChange = useCallback(
+		( newBorder?: Border ) => {
+			if ( shouldSanitizeBorder ) {
+				return onChange( sanitizeBorder( newBorder ) );
+			}
+
+			onChange( newBorder );
+		},
+		[ onChange, shouldSanitizeBorder, sanitizeBorder ]
+	);
+
+	const onWidthChange = useCallback(
+		( newWidth?: string ) => {
+			const newWidthValue = newWidth === '' ? undefined : newWidth;
+			const [ parsedValue ] = parseQuantityAndUnitFromRawValue(
+				newWidth
+			);
+			const hasZeroWidth = parsedValue === 0;
+
+			const updatedBorder = { ...border, width: newWidthValue };
+
+			// Setting the border width explicitly to zero will also set the
+			// border style to `none` and clear the border color.
+			if ( hasZeroWidth && ! hadPreviousZeroWidth ) {
+				// Before clearing the color and style selections, keep track of
+				// the current selections so they can be restored when the width
+				// changes to a non-zero value.
+				setColorSelection( border?.color );
+				setStyleSelection( border?.style );
+
+				// Clear the color and style border properties.
+				updatedBorder.color = undefined;
+				updatedBorder.style = 'none';
+			}
+
+			// Selection has changed from zero border width to non-zero width.
+			if ( ! hasZeroWidth && hadPreviousZeroWidth ) {
+				// Restore previous border color and style selections if width
+				// is now not zero.
+				if ( updatedBorder.color === undefined ) {
+					updatedBorder.color = colorSelection;
+				}
+				if ( updatedBorder.style === 'none' ) {
+					updatedBorder.style = styleSelection;
+				}
+			}
+
+			onBorderChange( updatedBorder );
+		},
+		[ border, hadPreviousZeroWidth, onBorderChange ]
+	);
+
+	const onSliderChange = useCallback(
+		( value: string ) => {
+			onWidthChange( `${ value }${ widthUnit }` );
+		},
+		[ onWidthChange, widthUnit ]
+	);
+
+	// Generate class names.
+	const cx = useCx();
+	const classes = useMemo( () => {
+		return cx( styles.borderControl, className );
+	}, [ className, cx ] );
+
+	const innerWrapperClassName = useMemo( () => {
+		const wrapperWidth = isCompact ? '90px' : width;
+		const widthStyle =
+			!! wrapperWidth && styles.wrapperWidth( wrapperWidth );
+
+		return cx( styles.innerWrapper(), widthStyle );
+	}, [ isCompact, width, cx ] );
+
+	const widthControlClassName = useMemo( () => {
+		return cx( styles.borderWidthControl() );
+	}, [ cx ] );
+
+	const sliderClassName = useMemo( () => {
+		return cx( styles.borderSlider() );
+	}, [ cx ] );
+
+	return {
+		...otherProps,
+		className: classes,
+		innerWrapperClassName,
+		onBorderChange,
+		onSliderChange,
+		onWidthChange,
+		previousStyleSelection: styleSelection,
+		sliderClassName,
+		value: border,
+		widthControlClassName,
+		widthUnit,
+		widthValue,
+	};
+}

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

@@ -0,0 +1,2 @@
+export { default as BorderControl } from './component';
+export { useBorderControl } from './hook';