@wordpress/components 27.1.0 → 27.3.0

package/src/color-picker/picker.tsx

@@ -7,118 +7,34 @@ import { colord } from 'colord';
 /**
  * WordPress dependencies
  */
-import { useMemo, useEffect, useRef } from '@wordpress/element';
+import { useMemo } from '@wordpress/element';
 /**
  * Internal dependencies
  */
 import type { PickerProps } from './types';
 
-/**
- * Track the start and the end of drag pointer events related to controlling
- * the picker's saturation / hue / alpha, and fire the corresponding callbacks.
- * This is particularly useful to implement synergies like the one with the
- * `Popover` component, where a pointer events "trap" is rendered while
- * the user is dragging the pointer to avoid potential interference with iframe
- * elements.
- *
- * @param props
- * @param props.containerEl
- * @param props.onDragStart
- * @param props.onDragEnd
- */
-const useOnPickerDrag = ( {
-	containerEl,
-	onDragStart,
-	onDragEnd,
-}: Pick< PickerProps, 'containerEl' | 'onDragStart' | 'onDragEnd' > ) => {
-	const isDragging = useRef( false );
-	const leftWhileDragging = useRef( false );
-	useEffect( () => {
-		if ( ! containerEl || ( ! onDragStart && ! onDragEnd ) ) {
-			return;
-		}
-		const interactiveElements = [
-			containerEl.querySelector( '.react-colorful__saturation' ),
-			containerEl.querySelector( '.react-colorful__hue' ),
-			containerEl.querySelector( '.react-colorful__alpha' ),
-		].filter( ( el ) => !! el ) as Element[];
-
-		if ( interactiveElements.length === 0 ) {
-			return;
-		}
-
-		const doc = containerEl.ownerDocument;
-
-		const onPointerUp: EventListener = ( event ) => {
-			isDragging.current = false;
-			leftWhileDragging.current = false;
-			onDragEnd?.( event as MouseEvent );
-		};
-
-		const onPointerDown: EventListener = ( event ) => {
-			isDragging.current = true;
-			onDragStart?.( event as MouseEvent );
-		};
-
-		const onPointerLeave: EventListener = () => {
-			leftWhileDragging.current = isDragging.current;
-		};
-
-		// Try to detect if the user released the pointer while away from the
-		// current window. If the check is successfull, the dragEnd callback will
-		// called as soon as the pointer re-enters the window (better late than never)
-		const onPointerEnter: EventListener = ( event ) => {
-			const noPointerButtonsArePressed =
-				( event as PointerEvent ).buttons === 0;
-
-			if ( leftWhileDragging.current && noPointerButtonsArePressed ) {
-				onPointerUp( event );
-			}
-		};
-
-		// The pointerdown event is added on the interactive elements,
-		// while the remaining events are added on the document object since
-		// the pointer wouldn't necessarily be hovering the initial interactive
-		// element at that point.
-		interactiveElements.forEach( ( el ) =>
-			el.addEventListener( 'pointerdown', onPointerDown )
-		);
-		doc.addEventListener( 'pointerup', onPointerUp );
-		doc.addEventListener( 'pointerenter', onPointerEnter );
-		doc.addEventListener( 'pointerleave', onPointerLeave );
-
-		return () => {
-			interactiveElements.forEach( ( el ) =>
-				el.removeEventListener( 'pointerdown', onPointerDown )
-			);
-			doc.removeEventListener( 'pointerup', onPointerUp );
-			doc.removeEventListener( 'pointerenter', onPointerEnter );
-			doc.removeEventListener( 'pointerleave', onPointerUp );
-		};
-	}, [ onDragStart, onDragEnd, containerEl ] );
-};
-
-export const Picker = ( {
-	color,
-	enableAlpha,
-	onChange,
-	onDragStart,
-	onDragEnd,
-	containerEl,
-}: PickerProps ) => {
+export const Picker = ( { color, enableAlpha, onChange }: PickerProps ) => {
 	const Component = enableAlpha
 		? RgbaStringColorPicker
 		: RgbStringColorPicker;
 	const rgbColor = useMemo( () => color.toRgbString(), [ color ] );
 
-	useOnPickerDrag( { containerEl, onDragStart, onDragEnd } );
-
 	return (
 		<Component
 			color={ rgbColor }
 			onChange={ ( nextColor ) => {
 				onChange( colord( nextColor ) );
 			} }
+			// Pointer capture fortifies drag gestures so that they continue to
+			// work while dragging outside the component over objects like
+			// iframes. If a newer version of react-colorful begins to employ
+			// pointer capture this will be redundant and should be removed.
+			onPointerDown={ ( { currentTarget, pointerId } ) => {
+				currentTarget.setPointerCapture( pointerId );
+			} }
+			onPointerUp={ ( { currentTarget, pointerId } ) => {
+				currentTarget.releasePointerCapture( pointerId );
+			} }
 		/>
 	);
 };

package/src/color-picker/types.ts

@@ -59,9 +59,6 @@ export interface PickerProps {
 	color: Colord;
 	enableAlpha: boolean;
 	onChange: ( nextColor: Colord ) => void;
-	containerEl: HTMLElement | null;
-	onDragStart?: ( event: MouseEvent ) => void;
-	onDragEnd?: ( event: MouseEvent ) => void;
 }
 
 export interface ColorInputProps {

package/src/confirm-dialog/README.md

@@ -138,3 +138,10 @@ The optional custom text to display as the confirmation button's label
 -   Default: "Cancel"
 
 The optional custom text to display as the cancellation button's label
+
+## Best practices
+
+The ConfirmDialog component should:
+
+-   Be used only for short confirmation messages where a cancel and confirm actions are provided.
+-   Use a descriptive text for the _confirm_ button. Default is "OK".

package/src/custom-select-control/stories/{index.story.js → index.story.tsx}

@@ -1,3 +1,8 @@
+/**
+ * External dependencies
+ */
+import type { StoryFn } from '@storybook/react';
+
 /**
  * Internal dependencies
  */
@@ -18,7 +23,7 @@ export default {
 	},
 };
 
-export const Default = CustomSelectControl.bind( {} );
+export const Default: StoryFn = CustomSelectControl.bind( {} );
 Default.args = {
 	label: 'Label',
 	options: [
@@ -46,7 +51,7 @@ Default.args = {
 	],
 };
 
-export const WithLongLabels = CustomSelectControl.bind( {} );
+export const WithLongLabels: StoryFn = CustomSelectControl.bind( {} );
 WithLongLabels.args = {
 	...Default.args,
 	options: [
@@ -65,7 +70,7 @@ WithLongLabels.args = {
 	],
 };
 
-export const WithHints = CustomSelectControl.bind( {} );
+export const WithHints: StoryFn = CustomSelectControl.bind( {} );
 WithHints.args = {
 	...Default.args,
 	options: [

package/src/custom-select-control/test/index.js

@@ -238,6 +238,30 @@ describe.each( [
 		).toHaveTextContent( 'Hint' );
 	} );
 
+	it( 'shows selected hint in list of options when added, regardless of __experimentalShowSelectedHint prop', async () => {
+		const user = userEvent.setup();
+
+		render(
+			<Component
+				{ ...props }
+				label="Custom select"
+				options={ [
+					{
+						key: 'one',
+						name: 'One',
+						__experimentalHint: 'Hint',
+					},
+				] }
+			/>
+		);
+
+		await user.click(
+			screen.getByRole( 'button', { name: 'Custom select' } )
+		);
+
+		expect( screen.getByRole( 'option', { name: /hint/i } ) ).toBeVisible();
+	} );
+
 	describe( 'Keyboard behavior and accessibility', () => {
 		it( 'Captures the keypress event and does not let it propagate', async () => {
 			const user = userEvent.setup();

package/src/custom-select-control-v2/README.md

@@ -1,4 +1,4 @@
-# CustomSelect
+# CustomSelectControlV2
 
 <div class="callout callout-alert">
 This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
@@ -12,31 +12,31 @@ Used to render a customizable select control component.
 
 #### Uncontrolled Mode
 
-CustomSelect can be used in an uncontrolled mode, where the component manages its own state. In this mode, the `defaultValue` prop can be used to set the initial selected value. If this prop is not set, the first value from the children will be selected by default.
+`CustomSelectControlV2` can be used in an uncontrolled mode, where the component manages its own state. In this mode, the `defaultValue` prop can be used to set the initial selected value. If this prop is not set, the first value from the children will be selected by default.
 
 ```jsx
-const UncontrolledCustomSelect = () => (
-	<CustomSelect label="Colors">
-		<CustomSelectItem value="Blue">
+const UncontrolledCustomSelectControlV2 = () => (
+	<CustomSelectControlV2 label="Colors">
+		<CustomSelectControlV2.Item value="Blue">
 			{ /* The `defaultValue` since it wasn't defined */ }
 			<span style={ { color: 'blue' } }>Blue</span>
-		</CustomSelectItem>
-		<CustomSelectItem value="Purple">
+		</CustomSelectControlV2.Item>
+		<CustomSelectControlV2.Item value="Purple">
 			<span style={ { color: 'purple' } }>Purple</span>
-		</CustomSelectItem>
-		<CustomSelectItem value="Pink">
+		</CustomSelectControlV2.Item>
+		<CustomSelectControlV2.Item value="Pink">
 			<span style={ { color: 'deeppink' } }>Pink</span>
-		</CustomSelectItem>
-	</CustomSelect>
+		</CustomSelectControlV2.Item>
+	</CustomSelectControlV2>
 );
 ```
 
 #### Controlled Mode
 
-CustomSelect can also be used in a controlled mode, where the parent component specifies the `value` and the `onChange` props to control selection.
+`CustomSelectControlV2` can also be used in a controlled mode, where the parent component specifies the `value` and the `onChange` props to control selection.
 
 ```jsx
-const ControlledCustomSelect = () => {
+const ControlledCustomSelectControlV2 = () => {
 	const [ value, setValue ] = useState< string | string[] >();
 
     const renderControlledValue = ( renderValue: string | string[] ) => (
@@ -46,7 +46,7 @@ const ControlledCustomSelect = () => {
     );
 
 	return (
-		<CustomSelect
+		<CustomSelectControlV2
 			{ ...props }
 			onChange={ ( nextValue ) => {
 				setValue( nextValue );
@@ -55,11 +55,11 @@ const ControlledCustomSelect = () => {
 			value={ value }
 		>
 			{ [ 'blue', 'purple', 'pink' ].map( ( option ) => (
-				<CustomSelectItem key={ option } value={ option }>
+				<CustomSelectControlV2.Item key={ option } value={ option }>
 					{ renderControlledValue( option ) }
-				</CustomSelectItem>
+				</CustomSelectControlV2.Item>
 			) ) }
-		</CustomSelect>
+		</CustomSelectControlV2>
 	);
 };
 ```
@@ -70,23 +70,23 @@ Multiple selection can be enabled by using an array for the `value` and
 `defaultValue` props. The argument of the `onChange` function will also change accordingly.
 
 ```jsx
-const MultiSelectCustomSelect = () => (
-	<CustomSelect defaultValue={ [ 'blue', 'pink' ] } label="Colors">
+const MultiSelectCustomSelectControlV2 = () => (
+	<CustomSelectControlV2 defaultValue={ [ 'blue', 'pink' ] } label="Colors">
 		{ [ 'blue', 'purple', 'pink' ].map( ( item ) => (
-			<CustomSelectItem key={ item } value={ item }>
+			<CustomSelectControlV2.Item key={ item } value={ item }>
 				{ item }
-			</CustomSelectItem>
+			</CustomSelectControlV2.Item>
 		) ) }
-	</CustomSelect>
+	</CustomSelectControlV2>
 );
 ```
 
 ### Components and Sub-components
 
-CustomSelect is comprised of two individual components:
+`CustomSelectControlV2` is comprised of two individual components:
 
--   `CustomSelect`: a wrapper component and context provider. It is responsible for managing the state of the `CustomSelectItem` children.
--   `CustomSelectItem`: renders a single select item. The first `CustomSelectItem` child will be used as the `defaultValue` when `defaultValue` is undefined.
+-   `CustomSelectControlV2`: a wrapper component and context provider. It is responsible for managing the state of the `CustomSelectControlV2.Item` children.
+-   `CustomSelectControlV2.Item`: renders a single select item. The first `CustomSelectControlV2.Item` child will be used as the `defaultValue` when `defaultValue` is undefined.
 
 #### Props
 
@@ -94,7 +94,7 @@ The component accepts the following props:
 
 ##### `children`: `React.ReactNode`
 
-The child elements. This should be composed of CustomSelect.Item components.
+The child elements. This should be composed of `CustomSelectControlV2.Item` components.
 
 -   Required: yes
 
@@ -142,7 +142,7 @@ Can be used to externally control the value of the control.
 
 -   Required: no
 
-### `CustomSelectItem`
+### `CustomSelectControlV2.Item`
 
 Used to render a select item.
 

package/src/custom-select-control-v2/default-component/index.tsx

@@ -9,8 +9,9 @@ import * as Ariakit from '@ariakit/react';
 import _CustomSelect from '../custom-select';
 import type { CustomSelectProps } from '../types';
 import type { WordPressComponentProps } from '../../context';
+import Item from '../item';
 
-function CustomSelect(
+function CustomSelectControlV2(
 	props: WordPressComponentProps< CustomSelectProps, 'button', false >
 ) {
 	const { defaultValue, onChange, value, ...restProps } = props;
@@ -24,4 +25,6 @@ function CustomSelect(
 	return <_CustomSelect { ...restProps } store={ store } />;
 }
 
-export default CustomSelect;
+CustomSelectControlV2.Item = Item;
+
+export default CustomSelectControlV2;

package/src/custom-select-control-v2/index.tsx

@@ -1,5 +1,4 @@
 /**
  * Internal dependencies
  */
-export { default as CustomSelect } from './default-component';
-export { default as CustomSelectItem } from './custom-select-item';
+export { default } from './default-component';

package/src/custom-select-control-v2/{custom-select-item.tsx → item.tsx}

@@ -26,4 +26,6 @@ export function CustomSelectItem( {
 	);
 }
 
+CustomSelectItem.displayName = 'CustomSelectControlV2.Item';
+
 export default CustomSelectItem;

package/src/custom-select-control-v2/legacy-component/index.tsx

@@ -11,12 +11,12 @@ import { useMemo } from '@wordpress/element';
  * Internal dependencies
  */
 import _CustomSelect from '../custom-select';
+import CustomSelectItem from '../item';
 import type { LegacyCustomSelectProps } from '../types';
-import { CustomSelectItem } from '..';
 import * as Styled from '../styles';
 import { ContextSystemProvider } from '../../context';
 
-function CustomSelect( props: LegacyCustomSelectProps ) {
+function CustomSelectControl( props: LegacyCustomSelectProps ) {
 	const {
 		__experimentalShowSelectedHint,
 		__next40pxDefaultSize = false,
@@ -68,9 +68,7 @@ function CustomSelect( props: LegacyCustomSelectProps ) {
 				<CustomSelectItem
 					key={ key }
 					value={ name }
-					children={
-						__experimentalShowSelectedHint ? withHint : name
-					}
+					children={ __experimentalHint ? withHint : name }
 					{ ...rest }
 				/>
 			);
@@ -130,4 +128,4 @@ function CustomSelect( props: LegacyCustomSelectProps ) {
 	);
 }
 
-export default CustomSelect;
+export default CustomSelectControl;

package/src/custom-select-control-v2/legacy-component/test/index.tsx

@@ -12,7 +12,7 @@ import { useState } from '@wordpress/element';
 /**
  * Internal dependencies
  */
-import UncontrolledCustomSelect from '..';
+import UncontrolledCustomSelectControl from '..';
 
 const customClass = 'amber-skies';
 
@@ -48,14 +48,14 @@ const legacyProps = {
 	],
 };
 
-const LegacyControlledCustomSelect = ( {
+const ControlledCustomSelectControl = ( {
 	options,
 	onChange,
 	...restProps
-}: React.ComponentProps< typeof UncontrolledCustomSelect > ) => {
+}: React.ComponentProps< typeof UncontrolledCustomSelectControl > ) => {
 	const [ value, setValue ] = useState( options[ 0 ] );
 	return (
-		<UncontrolledCustomSelect
+		<UncontrolledCustomSelectControl
 			{ ...restProps }
 			options={ options }
 			onChange={ ( args: any ) => {
@@ -70,8 +70,8 @@ const LegacyControlledCustomSelect = ( {
 };
 
 describe.each( [
-	[ 'Uncontrolled', UncontrolledCustomSelect ],
-	[ 'Controlled', LegacyControlledCustomSelect ],
+	[ 'Uncontrolled', UncontrolledCustomSelectControl ],
+	[ 'Controlled', ControlledCustomSelectControl ],
 ] )( 'CustomSelectControl (%s)', ( ...modeAndComponent ) => {
 	const [ , Component ] = modeAndComponent;
 
@@ -248,7 +248,7 @@ describe.each( [
 		);
 	} );
 
-	it( 'shows selected hint in list of options when added', async () => {
+	it( 'shows selected hint in list of options when added, regardless of __experimentalShowSelectedHint prop', async () => {
 		render(
 			<Component
 				{ ...legacyProps }
@@ -260,7 +260,6 @@ describe.each( [
 						__experimentalHint: 'Hint',
 					},
 				] }
-				__experimentalShowSelectedHint
 			/>
 		);
 
@@ -388,8 +387,10 @@ describe.each( [
 			await sleep();
 			await press.Tab();
 			expect( currentSelectedItem ).toHaveFocus();
+			expect( currentSelectedItem ).toHaveTextContent( 'violets' );
 
-			await type( 'aq' );
+			// Ideally we would test a multi-character typeahead, but anything more than a single character is flaky
+			await type( 'a' );
 
 			expect(
 				screen.queryByRole( 'listbox', {
@@ -398,8 +399,10 @@ describe.each( [
 				} )
 			).not.toBeInTheDocument();
 
+			// This Enter is a workaround for flakiness, and shouldn't be necessary in an actual browser
 			await press.Enter();
-			expect( currentSelectedItem ).toHaveTextContent( 'aquamarine' );
+
+			expect( currentSelectedItem ).toHaveTextContent( 'amber' );
 		} );
 
 		it( 'Should have correct aria-selected value for selections', async () => {

package/src/custom-select-control-v2/stories/default.story.tsx

@@ -11,15 +11,14 @@ import { useState } from '@wordpress/element';
 /**
  * Internal dependencies
  */
-import CustomSelect from '../default-component';
-import { CustomSelectItem } from '..';
+import CustomSelectControlV2 from '..';
 
-const meta: Meta< typeof CustomSelect > = {
+const meta: Meta< typeof CustomSelectControlV2 > = {
 	title: 'Components (Experimental)/CustomSelectControl v2/Default',
-	component: CustomSelect,
+	component: CustomSelectControlV2,
 	subcomponents: {
 		// @ts-expect-error - See https://github.com/storybookjs/storybook/issues/23170
-		CustomSelectItem,
+		'CustomSelectControlV2.Item': CustomSelectControlV2.Item,
 	},
 	argTypes: {
 		children: { control: { type: null } },
@@ -48,10 +47,10 @@ const meta: Meta< typeof CustomSelect > = {
 };
 export default meta;
 
-const Template: StoryFn< typeof CustomSelect > = ( props ) => {
+const Template: StoryFn< typeof CustomSelectControlV2 > = ( props ) => {
 	const [ value, setValue ] = useState< string | string[] >();
 	return (
-		<CustomSelect
+		<CustomSelectControlV2
 			{ ...props }
 			onChange={ ( nextValue: string | string[] ) => {
 				setValue( nextValue );
@@ -68,15 +67,15 @@ Default.args = {
 	defaultValue: 'Select a color...',
 	children: (
 		<>
-			<CustomSelectItem value="Blue">
+			<CustomSelectControlV2.Item value="Blue">
 				<span style={ { color: 'blue' } }>Blue</span>
-			</CustomSelectItem>
-			<CustomSelectItem value="Purple">
+			</CustomSelectControlV2.Item>
+			<CustomSelectControlV2.Item value="Purple">
 				<span style={ { color: 'purple' } }>Purple</span>
-			</CustomSelectItem>
-			<CustomSelectItem value="Pink">
+			</CustomSelectControlV2.Item>
+			<CustomSelectControlV2.Item value="Pink">
 				<span style={ { color: 'deeppink' } }>Pink</span>
-			</CustomSelectItem>
+			</CustomSelectControlV2.Item>
 		</>
 	),
 };
@@ -100,9 +99,9 @@ MultipleSelection.args = {
 				'maroon',
 				'tangerine',
 			].map( ( item ) => (
-				<CustomSelectItem key={ item } value={ item }>
+				<CustomSelectControlV2.Item key={ item } value={ item }>
 					{ item }
-				</CustomSelectItem>
+				</CustomSelectControlV2.Item>
 			) ) }
 		</>
 	),
@@ -134,9 +133,9 @@ CustomSelectedValue.args = {
 		<>
 			{ [ 'mystery-person', 'identicon', 'wavatar', 'retro' ].map(
 				( option ) => (
-					<CustomSelectItem key={ option } value={ option }>
+					<CustomSelectControlV2.Item key={ option } value={ option }>
 						{ renderItem( option ) }
-					</CustomSelectItem>
+					</CustomSelectControlV2.Item>
 				)
 			) }
 		</>

package/src/custom-select-control-v2/stories/legacy.story.tsx

@@ -11,11 +11,12 @@ import { useState } from '@wordpress/element';
 /**
  * Internal dependencies
  */
-import CustomSelect from '../legacy-component';
+import CustomSelectControl from '../legacy-component';
+import * as V1Story from '../../custom-select-control/stories/index.story';
 
-const meta: Meta< typeof CustomSelect > = {
+const meta: Meta< typeof CustomSelectControl > = {
 	title: 'Components (Experimental)/CustomSelectControl v2/Legacy',
-	component: CustomSelect,
+	component: CustomSelectControl,
 	argTypes: {
 		onChange: { control: { type: null } },
 		value: { control: { type: null } },
@@ -42,46 +43,30 @@ const meta: Meta< typeof CustomSelect > = {
 };
 export default meta;
 
-const Template: StoryFn< typeof CustomSelect > = ( props ) => {
-	const [ fontSize, setFontSize ] = useState( props.options[ 0 ] );
+const Template: StoryFn< typeof CustomSelectControl > = ( props ) => {
+	const [ value, setValue ] = useState( props.options[ 0 ] );
 
 	const onChange: React.ComponentProps<
-		typeof CustomSelect
+		typeof CustomSelectControl
 	>[ 'onChange' ] = ( changeObject ) => {
-		setFontSize( changeObject.selectedItem );
+		setValue( changeObject.selectedItem );
 		props.onChange?.( changeObject );
 	};
 
 	return (
-		<CustomSelect { ...props } onChange={ onChange } value={ fontSize } />
+		<CustomSelectControl
+			{ ...props }
+			onChange={ onChange }
+			value={ value }
+		/>
 	);
 };
 
 export const Default = Template.bind( {} );
-Default.args = {
-	label: 'Label text',
-	options: [
-		{
-			key: 'small',
-			name: 'Small',
-			style: { fontSize: '50%' },
-			__experimentalHint: '50%',
-		},
-		{
-			key: 'normal',
-			name: 'Normal',
-			style: { fontSize: '100%' },
-			className: 'can-apply-custom-class-to-option',
-		},
-		{
-			key: 'large',
-			name: 'Large',
-			style: { fontSize: '200%' },
-		},
-		{
-			key: 'huge',
-			name: 'Huge',
-			style: { fontSize: '300%' },
-		},
-	],
-};
+Default.args = V1Story.Default.args;
+
+export const WithLongLabels = Template.bind( {} );
+WithLongLabels.args = V1Story.WithLongLabels.args;
+
+export const WithHints = Template.bind( {} );
+WithHints.args = V1Story.WithHints.args;