@wordpress/components 19.7.0 → 19.8.0

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';

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

@@ -0,0 +1,252 @@
+/**
+ * External dependencies
+ */
+import type { CSSProperties } from 'react';
+
+/**
+ * WordPress dependencies
+ */
+import { __, sprintf } from '@wordpress/i18n';
+import { closeSmall } from '@wordpress/icons';
+
+/**
+ * Internal dependencies
+ */
+import BorderControlStylePicker from '../border-control-style-picker';
+import Button from '../../button';
+import ColorIndicator from '../../color-indicator';
+import ColorPalette from '../../color-palette';
+import Dropdown from '../../dropdown';
+import { HStack } from '../../h-stack';
+import { VStack } from '../../v-stack';
+import { contextConnect, WordPressComponentProps } from '../../ui/context';
+import { useBorderControlDropdown } from './hook';
+import { StyledLabel } from '../../base-control/styles/base-control-styles';
+
+import type {
+	Color,
+	ColorOrigin,
+	Colors,
+	DropdownProps,
+	PopoverProps,
+} from '../types';
+
+const noop = () => undefined;
+const getColorObject = (
+	colorValue: CSSProperties[ 'borderColor' ],
+	colors: Colors | undefined,
+	hasMultipleColorOrigins: boolean
+) => {
+	if ( ! colorValue || ! colors ) {
+		return;
+	}
+
+	if ( hasMultipleColorOrigins ) {
+		let matchedColor;
+
+		( colors as ColorOrigin[] ).some( ( origin ) =>
+			origin.colors.some( ( color ) => {
+				if ( color.color === colorValue ) {
+					matchedColor = color;
+					return true;
+				}
+
+				return false;
+			} )
+		);
+
+		return matchedColor;
+	}
+
+	return ( colors as Color[] ).find(
+		( color ) => color.color === colorValue
+	);
+};
+
+const getToggleAriaLabel = (
+	colorValue: CSSProperties[ 'borderColor' ],
+	colorObject: Color | undefined,
+	style: CSSProperties[ 'borderStyle' ],
+	isStyleEnabled: boolean
+) => {
+	if ( isStyleEnabled ) {
+		if ( colorObject ) {
+			return style
+				? sprintf(
+						// translators: %1$s: The name of the color e.g. "vivid red". %2$s: The color's hex code e.g.: "#f00:". %3$s: The current border style selection e.g. "solid".
+						'Border color and style picker. The currently selected color is called "%1$s" and has a value of "%2$s". The currently selected style is "%3$s".',
+						colorObject.name,
+						colorObject.color,
+						style
+				  )
+				: sprintf(
+						// translators: %1$s: The name of the color e.g. "vivid red". %2$s: The color's hex code e.g.: "#f00:".
+						'Border color and style picker. The currently selected color is called "%1$s" and has a value of "%2$s".',
+						colorObject.name,
+						colorObject.color
+				  );
+		}
+
+		if ( colorValue ) {
+			return style
+				? sprintf(
+						// translators: %1$s: The color's hex code e.g.: "#f00:". %2$s: The current border style selection e.g. "solid".
+						'Border color and style picker. The currently selected color has a value of "%1$s". The currently selected style is "%2$s".',
+						colorValue,
+						style
+				  )
+				: sprintf(
+						// translators: %1$s: The color's hex code e.g.: "#f00:".
+						'Border color and style picker. The currently selected color has a value of "%1$s".',
+						colorValue
+				  );
+		}
+
+		return __( 'Border color and style picker.' );
+	}
+
+	if ( colorObject ) {
+		return sprintf(
+			// translators: %1$s: The name of the color e.g. "vivid red". %2$s: The color's hex code e.g.: "#f00:".
+			'Border color picker. The currently selected color is called "%1$s" and has a value of "%2$s".',
+			colorObject.name,
+			colorObject.color
+		);
+	}
+
+	if ( colorValue ) {
+		return sprintf(
+			// translators: %1$s: The color's hex code e.g.: "#f00:".
+			'Border color picker. The currently selected color has a value of "%1$s".',
+			colorValue
+		);
+	}
+
+	return __( 'Border color picker.' );
+};
+
+const BorderControlDropdown = (
+	props: WordPressComponentProps< DropdownProps, 'div' >,
+	forwardedRef: React.ForwardedRef< any >
+) => {
+	const {
+		__experimentalHasMultipleOrigins,
+		__experimentalIsRenderedInSidebar,
+		border,
+		colors,
+		disableCustomColors,
+		enableAlpha,
+		indicatorClassName,
+		indicatorWrapperClassName,
+		onReset,
+		onColorChange,
+		onStyleChange,
+		popoverClassName,
+		popoverContentClassName,
+		popoverControlsClassName,
+		resetButtonClassName,
+		showDropdownHeader,
+		enableStyle = true,
+		...otherProps
+	} = useBorderControlDropdown( props );
+
+	const { color, style } = border || {};
+	const colorObject = getColorObject(
+		color,
+		colors,
+		!! __experimentalHasMultipleOrigins
+	);
+
+	const toggleAriaLabel = getToggleAriaLabel(
+		color,
+		colorObject,
+		style,
+		enableStyle
+	);
+
+	const dropdownPosition = __experimentalIsRenderedInSidebar
+		? 'bottom left'
+		: undefined;
+
+	const renderToggle = ( { onToggle = noop } ) => (
+		<Button
+			onClick={ onToggle }
+			variant="tertiary"
+			aria-label={ toggleAriaLabel }
+			position={ dropdownPosition }
+		>
+			<span className={ indicatorWrapperClassName }>
+				<ColorIndicator
+					className={ indicatorClassName }
+					colorValue={ color }
+				/>
+			</span>
+		</Button>
+	);
+
+	const renderContent = ( { onClose }: PopoverProps ) => (
+		<>
+			<VStack className={ popoverControlsClassName } spacing={ 6 }>
+				{ showDropdownHeader ? (
+					<HStack>
+						<StyledLabel>{ __( 'Border color' ) }</StyledLabel>
+						<Button
+							isSmall
+							label={ __( 'Close border color' ) }
+							icon={ closeSmall }
+							onClick={ onClose }
+						/>
+					</HStack>
+				) : undefined }
+				<ColorPalette
+					className={ popoverContentClassName }
+					value={ color }
+					onChange={ onColorChange }
+					{ ...{ colors, disableCustomColors } }
+					__experimentalHasMultipleOrigins={
+						__experimentalHasMultipleOrigins
+					}
+					__experimentalIsRenderedInSidebar={
+						__experimentalIsRenderedInSidebar
+					}
+					clearable={ false }
+					enableAlpha={ enableAlpha }
+				/>
+				{ enableStyle && (
+					<BorderControlStylePicker
+						label={ __( 'Style' ) }
+						value={ style }
+						onChange={ onStyleChange }
+					/>
+				) }
+			</VStack>
+			<Button
+				className={ resetButtonClassName }
+				variant="tertiary"
+				onClick={ () => {
+					onReset();
+					onClose();
+				} }
+			>
+				{ __( 'Reset to default' ) }
+			</Button>
+		</>
+	);
+
+	return (
+		<Dropdown
+			renderToggle={ renderToggle }
+			renderContent={ renderContent }
+			contentClassName={ popoverClassName }
+			{ ...otherProps }
+			ref={ forwardedRef }
+		/>
+	);
+};
+
+const ConnectedBorderControlDropdown = contextConnect(
+	BorderControlDropdown,
+	'BorderControlDropdown'
+);
+
+export default ConnectedBorderControlDropdown;