@wordpress/components 21.3.0 → 22.0.0

package/src/autocomplete/autocompleter-ui.js

@@ -7,7 +7,7 @@ import { map } from 'lodash';
 /**
  * WordPress dependencies
  */
-import { useLayoutEffect } from '@wordpress/element';
+import { useLayoutEffect, useRef, useEffect } from '@wordpress/element';
 import { useAnchor } from '@wordpress/rich-text';
 
 /**
@@ -31,6 +31,7 @@ export function getAutoCompleterUI( autocompleter ) {
 		onChangeOptions,
 		onSelect,
 		onReset,
+		reset,
 		value,
 		contentRef,
 	} ) {
@@ -40,6 +41,10 @@ export function getAutoCompleterUI( autocompleter ) {
 			value,
 		} );
 
+		const popoverRef = useRef();
+
+		useOnClickOutside( popoverRef, reset );
+
 		useLayoutEffect( () => {
 			onChangeOptions( items );
 			// Temporarily disabling exhaustive-deps to avoid introducing unexpected side effecst.
@@ -55,9 +60,10 @@ export function getAutoCompleterUI( autocompleter ) {
 			<Popover
 				focusOnMount={ false }
 				onClose={ onReset }
-				position="top right"
+				placement="top-start"
 				className="components-autocomplete__popover"
 				anchor={ popoverAnchor }
+				ref={ popoverRef }
 			>
 				<div
 					id={ listBoxId }
@@ -90,3 +96,24 @@ export function getAutoCompleterUI( autocompleter ) {
 
 	return AutocompleterUI;
 }
+
+function useOnClickOutside( ref, handler ) {
+	useEffect( () => {
+		const listener = ( event ) => {
+			// Do nothing if clicking ref's element or descendent elements, or if the ref is not referencing an element
+			if ( ! ref.current || ref.current.contains( event.target ) ) {
+				return;
+			}
+			handler( event );
+		};
+		document.addEventListener( 'mousedown', listener );
+		document.addEventListener( 'touchstart', listener );
+		return () => {
+			document.removeEventListener( 'mousedown', listener );
+			document.removeEventListener( 'touchstart', listener );
+		};
+		// Disable reason: `ref` is a ref object and should not be included in a
+		// hook's dependency list.
+		// eslint-disable-next-line react-hooks/exhaustive-deps
+	}, [ handler ] );
+}

package/src/autocomplete/test/index.js

@@ -0,0 +1,89 @@
+/**
+ * External dependencies
+ */
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+
+/**
+ * WordPress dependencies
+ */
+import { useRef } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import { getAutoCompleterUI } from '../autocompleter-ui';
+
+describe( 'AutocompleterUI', () => {
+	describe( 'click outside behavior', () => {
+		it( 'should call reset function when a click on another element occurs', async () => {
+			const user = userEvent.setup( {
+				advanceTimers: jest.advanceTimersByTime,
+			} );
+
+			const resetSpy = jest.fn();
+
+			const autocompleter = {
+				name: 'fruit',
+				// The prefix that triggers this completer
+				triggerPrefix: '~',
+				// Mock useItems function to return a autocomplete item.
+				useItems: () => {
+					return [
+						[
+							{
+								isDisabled: false,
+								key: 'Apple',
+								value: 'Apple',
+								label: (
+									<span>
+										<span className="icon">🍎</span>
+										{ 'Apple' }
+									</span>
+								),
+							},
+						],
+					];
+				},
+			};
+
+			const AutocompleterUI = getAutoCompleterUI( autocompleter );
+
+			const OtherElement = <div>Other Element</div>;
+
+			const Container = () => {
+				const contentRef = useRef();
+
+				return (
+					<div>
+						<AutocompleterUI
+							className={ 'test' }
+							filterValue={ '~' }
+							instanceId={ '1' }
+							listBoxId={ '1' }
+							selectedIndex={ 0 }
+							onChangeOptions={ () => {} }
+							onSelect={ () => {} }
+							value={ { visual: '🍎', name: 'Apple', id: 1 } }
+							contentRef={ contentRef }
+							reset={ resetSpy }
+						/>
+						{ OtherElement }
+					</div>
+				);
+			};
+
+			render( <Container /> );
+
+			// Click on autocompleter.
+			await user.click( screen.getByText( 'Apple' ) );
+
+			expect( resetSpy ).toHaveBeenCalledTimes( 0 );
+
+			// Click on other element out side of the tree.
+			await user.click( screen.getByText( 'Other Element' ) );
+
+			expect( resetSpy ).toHaveBeenCalledTimes( 1 );
+		} );
+	} );
+} );

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

@@ -138,6 +138,14 @@ Works in conjunctions with `popoverPlacement` and allows leaving a space between
 
 - Required: No
 
+### `size`: `string`
+
+Size of the control.
+
+- Required: No
+- Default: `default`
+- Allowed values: `default`, `__unstable-large`
+
 ### `value`: `Object`
 
 An object representing the current border configuration.

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

@@ -11,7 +11,6 @@ import { useMergeRefs } from '@wordpress/compose';
 import BorderBoxControlLinkedButton from '../border-box-control-linked-button';
 import BorderBoxControlSplitControls from '../border-box-control-split-controls';
 import { BorderControl } from '../../border-control';
-import { HStack } from '../../h-stack';
 import { StyledLabel } from '../../base-control/styles/base-control-styles';
 import { View } from '../../view';
 import { VisuallyHidden } from '../../visually-hidden';
@@ -38,8 +37,8 @@ const BorderLabel = ( props: LabelProps ) => {
 	);
 };
 
-const BorderBoxControl = (
-	props: WordPressComponentProps< BorderBoxControlProps, 'div' >,
+const UnconnectedBorderBoxControl = (
+	props: WordPressComponentProps< BorderBoxControlProps, 'div', false >,
 	forwardedRef: React.ForwardedRef< any >
 ) => {
 	const {
@@ -59,11 +58,12 @@ const BorderBoxControl = (
 		onSplitChange,
 		popoverPlacement,
 		popoverOffset,
+		size = 'default',
 		splitValue,
 		toggleLinked,
+		wrapperClassName,
 		__experimentalHasMultipleOrigins,
 		__experimentalIsRenderedInSidebar,
-		__next36pxDefaultSize = false,
 		...otherProps
 	} = useBorderBoxControl( props );
 
@@ -96,7 +96,7 @@ const BorderBoxControl = (
 				label={ label }
 				hideLabelFromVision={ hideLabelFromVision }
 			/>
-			<HStack alignment={ 'start' } expanded={ true } spacing={ 0 }>
+			<View className={ wrapperClassName }>
 				{ isLinked ? (
 					<BorderControl
 						className={ linkedControlClassName }
@@ -113,14 +113,16 @@ const BorderBoxControl = (
 						shouldSanitizeBorder={ false } // This component will handle that.
 						value={ linkedValue }
 						withSlider={ true }
-						width={ '110px' }
+						width={
+							size === '__unstable-large' ? '116px' : '110px'
+						}
 						__experimentalHasMultipleOrigins={
 							__experimentalHasMultipleOrigins
 						}
 						__experimentalIsRenderedInSidebar={
 							__experimentalIsRenderedInSidebar
 						}
-						__next36pxDefaultSize={ __next36pxDefaultSize }
+						size={ size }
 					/>
 				) : (
 					<BorderBoxControlSplitControls
@@ -138,22 +140,71 @@ const BorderBoxControl = (
 						__experimentalIsRenderedInSidebar={
 							__experimentalIsRenderedInSidebar
 						}
-						__next36pxDefaultSize={ __next36pxDefaultSize }
+						size={ size }
 					/>
 				) }
 				<BorderBoxControlLinkedButton
 					onClick={ toggleLinked }
 					isLinked={ isLinked }
-					__next36pxDefaultSize={ __next36pxDefaultSize }
+					size={ size }
 				/>
-			</HStack>
+			</View>
 		</View>
 	);
 };
 
-const ConnectedBorderBoxControl = contextConnect(
-	BorderBoxControl,
+/**
+ * The `BorderBoxControl` effectively has two view states. The first, a "linked"
+ * view, allows configuration of a flat border via a single `BorderControl`.
+ * The second, a "split" view, contains a `BorderControl` for each side
+ * as well as a visualizer for the currently selected borders. Each view also
+ * contains a button to toggle between the two.
+ *
+ * When switching from the "split" view to "linked", if the individual side
+ * borders are not consistent, the "linked" view will display any border
+ * properties selections that are consistent while showing a mixed state for
+ * those that aren't. For example, if all borders had the same color and style
+ * but different widths, then the border dropdown in the "linked" view's
+ * `BorderControl` would show that consistent color and style but the "linked"
+ * view's width input would show "Mixed" placeholder text.
+ *
+ * ```jsx
+ * import { __experimentalBorderBoxControl as BorderBoxControl } from '@wordpress/components';
+ * import { __ } from '@wordpress/i18n';
+ *
+ * const colors = [
+ * 	{ name: 'Blue 20', color: '#72aee6' },
+ * 	// ...
+ * ];
+ *
+ * const MyBorderBoxControl = () => {
+ * 	const defaultBorder = {
+ * 		color: '#72aee6',
+ * 		style: 'dashed',
+ * 		width: '1px',
+ * 	};
+ * 	const [ borders, setBorders ] = useState( {
+ * 		top: defaultBorder,
+ * 		right: defaultBorder,
+ * 		bottom: defaultBorder,
+ * 		left: defaultBorder,
+ * 	} );
+ * 	const onChange = ( newBorders ) => setBorders( newBorders );
+ *
+ * 	return (
+ * 		<BorderBoxControl
+ * 			colors={ colors }
+ * 			label={ __( 'Borders' ) }
+ * 			onChange={ onChange }
+ * 			value={ borders }
+ * 		/>
+ * 	);
+ * };
+ * ```
+ */
+export const BorderBoxControl = contextConnect(
+	UnconnectedBorderBoxControl,
 	'BorderBoxControl'
 );
 
-export default ConnectedBorderBoxControl;
+export default BorderBoxControl;

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

@@ -100,11 +100,15 @@ export function useBorderBoxControl(
 
 	const cx = useCx();
 	const classes = useMemo( () => {
-		return cx( styles.BorderBoxControl, className );
+		return cx( styles.borderBoxControl, className );
 	}, [ cx, className ] );
 
 	const linkedControlClassName = useMemo( () => {
-		return cx( styles.LinkedBorderControl );
+		return cx( styles.linkedBorderControl() );
+	}, [ cx ] );
+
+	const wrapperClassName = useMemo( () => {
+		return cx( styles.wrapper );
 	}, [ cx ] );
 
 	return {
@@ -119,5 +123,6 @@ export function useBorderBoxControl(
 		toggleLinked,
 		linkedValue,
 		splitValue,
+		wrapperClassName,
 	};
 }

package/src/border-box-control/border-box-control-linked-button/hook.ts

@@ -17,18 +17,15 @@ export function useBorderBoxControlLinkedButton(
 ) {
 	const {
 		className,
-		__next36pxDefaultSize = false,
+		size = 'default',
 		...otherProps
 	} = useContextSystem( props, 'BorderBoxControlLinkedButton' );
 
 	// Generate class names.
 	const cx = useCx();
 	const classes = useMemo( () => {
-		return cx(
-			styles.BorderBoxControlLinkedButton( __next36pxDefaultSize ),
-			className
-		);
-	}, [ className, cx, __next36pxDefaultSize ] );
+		return cx( styles.borderBoxControlLinkedButton( size ), className );
+	}, [ className, cx, size ] );
 
 	return { ...otherProps, className: classes };
 }

package/src/border-box-control/border-box-control-split-controls/component.tsx

@@ -31,10 +31,10 @@ const BorderBoxControlSplitControls = (
 		popoverPlacement,
 		popoverOffset,
 		rightAlignedClassName,
+		size = 'default',
 		value,
 		__experimentalHasMultipleOrigins,
 		__experimentalIsRenderedInSidebar,
-		__next36pxDefaultSize,
 		...otherProps
 	} = useBorderBoxControlSplitControls( props );
 
@@ -67,17 +67,14 @@ const BorderBoxControlSplitControls = (
 		isCompact: true,
 		__experimentalHasMultipleOrigins,
 		__experimentalIsRenderedInSidebar,
-		__next36pxDefaultSize,
+		size,
 	};
 
 	const mergedRef = useMergeRefs( [ setPopoverAnchor, forwardedRef ] );
 
 	return (
 		<Grid { ...otherProps } ref={ mergedRef } gap={ 4 }>
-			<BorderBoxControlVisualizer
-				value={ value }
-				__next36pxDefaultSize={ __next36pxDefaultSize }
-			/>
+			<BorderBoxControlVisualizer value={ value } size={ size } />
 			<BorderControl
 				className={ centeredClassName }
 				hideLabelFromVision={ true }

package/src/border-box-control/border-box-control-split-controls/hook.ts

@@ -8,41 +8,38 @@ import { useMemo } from '@wordpress/element';
  */
 import * as styles from '../styles';
 import { useContextSystem, WordPressComponentProps } from '../../ui/context';
-import { useCx, rtl } from '../../utils/';
+import { useCx } from '../../utils/';
 
 import type { SplitControlsProps } from '../types';
 
 export function useBorderBoxControlSplitControls(
 	props: WordPressComponentProps< SplitControlsProps, 'div' >
 ) {
-	const { className, ...otherProps } = useContextSystem(
-		props,
-		'BorderBoxControlSplitControls'
-	);
+	const {
+		className,
+		size = 'default',
+		...otherProps
+	} = useContextSystem( props, 'BorderBoxControlSplitControls' );
 
 	// Generate class names.
 	const cx = useCx();
-	const rtlWatchResult = rtl.watch();
 	const classes = useMemo( () => {
-		return cx( styles.borderBoxControlSplitControls(), className );
-		// rtlWatchResult is needed to refresh styles when the writing direction changes
-		// eslint-disable-next-line react-hooks/exhaustive-deps
-	}, [ cx, className, rtlWatchResult ] );
+		return cx( styles.borderBoxControlSplitControls( size ), className );
+	}, [ cx, className, size ] );
 
 	const centeredClassName = useMemo( () => {
-		return cx( styles.CenteredBorderControl, className );
+		return cx( styles.centeredBorderControl, className );
 	}, [ cx, className ] );
 
 	const rightAlignedClassName = useMemo( () => {
 		return cx( styles.rightBorderControl(), className );
-		// rtlWatchResult is needed to refresh styles when the writing direction changes
-		// eslint-disable-next-line react-hooks/exhaustive-deps
-	}, [ cx, className, rtlWatchResult ] );
+	}, [ cx, className ] );
 
 	return {
 		...otherProps,
 		centeredClassName,
 		className: classes,
 		rightAlignedClassName,
+		size,
 	};
 }

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

@@ -8,7 +8,7 @@ import { useMemo } from '@wordpress/element';
  */
 import * as styles from '../styles';
 import { useContextSystem, WordPressComponentProps } from '../../ui/context';
-import { useCx, rtl } from '../../utils';
+import { useCx } from '../../utils';
 
 import type { VisualizerProps } from '../types';
 
@@ -18,21 +18,18 @@ export function useBorderBoxControlVisualizer(
 	const {
 		className,
 		value,
-		__next36pxDefaultSize = false,
+		size = 'default',
 		...otherProps
 	} = useContextSystem( props, 'BorderBoxControlVisualizer' );
 
 	// Generate class names.
 	const cx = useCx();
-	const rtlWatchResult = rtl.watch();
 	const classes = useMemo( () => {
 		return cx(
-			styles.borderBoxControlVisualizer( value, __next36pxDefaultSize ),
+			styles.borderBoxControlVisualizer( value, size ),
 			className
 		);
-		// rtlWatchResult is needed to refresh styles when the writing direction changes
-		// eslint-disable-next-line react-hooks/exhaustive-deps
-	}, [ cx, className, value, __next36pxDefaultSize, rtlWatchResult ] );
+	}, [ cx, className, value, size ] );
 
 	return { ...otherProps, className: classes, value };
 }

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

@@ -0,0 +1,90 @@
+/**
+ * External dependencies
+ */
+import type { ComponentMeta, ComponentStory } from '@storybook/react';
+import type { ComponentProps } from 'react';
+
+/**
+ * WordPress dependencies
+ */
+import { useState } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import Button from '../../button';
+import Popover from '../../popover';
+import { BorderBoxControl } from '../';
+import { Provider as SlotFillProvider } from '../../slot-fill';
+
+const meta: ComponentMeta< typeof BorderBoxControl > = {
+	title: 'Components (Experimental)/BorderBoxControl',
+	component: BorderBoxControl,
+	argTypes: {
+		onChange: { action: 'onChange' },
+		value: { control: { type: null } },
+	},
+	parameters: {
+		controls: { expanded: true },
+		docs: { source: { state: 'open' } },
+	},
+};
+export default meta;
+
+// Available border colors.
+const colors = [
+	{ name: 'Blue 20', color: '#72aee6' },
+	{ name: 'Blue 40', color: '#3582c4' },
+	{ name: 'Red 40', color: '#e65054' },
+	{ name: 'Red 70', color: '#8a2424' },
+	{ name: 'Yellow 10', color: '#f2d675' },
+	{ name: 'Yellow 40', color: '#bd8600' },
+];
+
+const Template: ComponentStory< typeof BorderBoxControl > = ( props ) => {
+	const { onChange, ...otherProps } = props;
+	const [ borders, setBorders ] = useState< typeof props[ 'value' ] >();
+
+	const onChangeMerged: ComponentProps<
+		typeof BorderBoxControl
+	>[ 'onChange' ] = ( newBorders ) => {
+		setBorders( newBorders );
+		onChange( newBorders );
+	};
+
+	return (
+		<SlotFillProvider>
+			<BorderBoxControl
+				{ ...otherProps }
+				onChange={ onChangeMerged }
+				value={ borders }
+			/>
+			<hr
+				style={ {
+					marginTop: '100px',
+					borderColor: '#ddd',
+					borderStyle: 'solid',
+					borderBottom: 'none',
+				} }
+			/>
+			<p style={ { color: '#aaa', fontSize: '0.9em' } }>
+				The BorderBoxControl is intended to be used within a component
+				that will provide reset controls. The button below is only for
+				convenience.
+			</p>
+			<Button
+				variant="primary"
+				onClick={ () => onChangeMerged( undefined ) }
+			>
+				Reset
+			</Button>
+			{ /* @ts-expect-error Ignore until Popover.Slot is converted to TS */ }
+			<Popover.Slot />
+		</SlotFillProvider>
+	);
+};
+export const Default = Template.bind( {} );
+Default.args = {
+	colors,
+	label: 'Borders',
+};

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

@@ -7,29 +7,33 @@ 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 borderBoxControl = css``;
 
-export const LinkedBorderControl = css`
+export const linkedBorderControl = () => css`
 	flex: 1;
+	${ rtl( { marginRight: '24px' } )() }
 `;
 
-export const BorderBoxControlLinkedButton = (
-	__next36pxDefaultSize?: boolean
+export const wrapper = css`
+	position: relative;
+`;
+
+export const borderBoxControlLinkedButton = (
+	size?: 'default' | '__unstable-large'
 ) => {
 	return css`
-		flex: 0;
-		flex-basis: 24px;
+		position: absolute;
+		top: ${ size === '__unstable-large' ? '8px' : '3px' };
+		${ rtl( { right: 0 } )() }
 		line-height: 0;
-		margin-top: ${ __next36pxDefaultSize ? '6px' : '3px' };
 	`;
 };
 
-const BorderBoxStyleWithFallback = ( border?: Border ) => {
+const borderBoxStyleWithFallback = ( border?: Border ) => {
 	const {
 		color = COLORS.gray[ 200 ],
 		style = 'solid',
@@ -46,36 +50,38 @@ const BorderBoxStyleWithFallback = ( border?: Border ) => {
 
 export const borderBoxControlVisualizer = (
 	borders?: Borders,
-	__next36pxDefaultSize?: boolean
+	size?: 'default' | '__unstable-large'
 ) => {
 	return css`
 		position: absolute;
-		top: ${ __next36pxDefaultSize ? '18px' : '15px' };
-		right: 30px;
-		bottom: ${ __next36pxDefaultSize ? '18px' : '15px' };
-		left: 30px;
-		border-top: ${ BorderBoxStyleWithFallback( borders?.top ) };
-		border-bottom: ${ BorderBoxStyleWithFallback( borders?.bottom ) };
+		top: ${ size === '__unstable-large' ? '20px' : '15px' };
+		right: ${ size === '__unstable-large' ? '39px' : '29px' };
+		bottom: ${ size === '__unstable-large' ? '20px' : '15px' };
+		left: ${ size === '__unstable-large' ? '39px' : '29px' };
+		border-top: ${ borderBoxStyleWithFallback( borders?.top ) };
+		border-bottom: ${ borderBoxStyleWithFallback( borders?.bottom ) };
 		${ rtl( {
-			borderLeft: BorderBoxStyleWithFallback( borders?.left ),
+			borderLeft: borderBoxStyleWithFallback( borders?.left ),
 		} )() }
 		${ rtl( {
-			borderRight: BorderBoxStyleWithFallback( borders?.right ),
+			borderRight: borderBoxStyleWithFallback( borders?.right ),
 		} )() }
 	`;
 };
 
-export const borderBoxControlSplitControls = () => css`
+export const borderBoxControlSplitControls = (
+	size?: 'default' | '__unstable-large'
+) => css`
 	position: relative;
 	flex: 1;
-	${ rtl( { marginRight: space( 3 ) }, { marginLeft: space( 3 ) } )() }
+	width: ${ size === '__unstable-large' ? undefined : '80%' };
 `;
 
-export const CenteredBorderControl = css`
+export const centeredBorderControl = css`
 	grid-column: span 2;
 	margin: 0 auto;
 `;
 
 export const rightBorderControl = () => css`
-	${ rtl( { marginLeft: 'auto' }, { marginRight: 'auto' } )() }
+	${ rtl( { marginLeft: 'auto' } )() }
 `;