@wordpress/components 26.0.1 → 27.0.0

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

@@ -0,0 +1,29 @@
+/**
+ * WordPress dependencies
+ */
+import { useContext } from '@wordpress/element';
+import { Icon, check } from '@wordpress/icons';
+/**
+ * Internal dependencies
+ */
+import type { CustomSelectItemProps } from './types';
+import type { WordPressComponentProps } from '../context';
+import * as Styled from './styles';
+import { CustomSelectContext } from './custom-select';
+
+export function CustomSelectItem( {
+	children,
+	...props
+}: WordPressComponentProps< CustomSelectItemProps, 'div', false > ) {
+	const customSelectContext = useContext( CustomSelectContext );
+	return (
+		<Styled.SelectItem store={ customSelectContext?.store } { ...props }>
+			{ children ?? props.value }
+			<Styled.SelectedItemCheck>
+				<Icon icon={ check } />
+			</Styled.SelectedItemCheck>
+		</Styled.SelectItem>
+	);
+}
+
+export default CustomSelectItem;

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

@@ -0,0 +1,122 @@
+/**
+ * WordPress dependencies
+ */
+import { createContext, useMemo } from '@wordpress/element';
+import { __, sprintf } from '@wordpress/i18n';
+import { Icon, chevronDown } from '@wordpress/icons';
+
+/**
+ * Internal dependencies
+ */
+import { VisuallyHidden } from '..';
+import * as Styled from './styles';
+import type {
+	CustomSelectContext as CustomSelectContextType,
+	CustomSelectStore,
+	CustomSelectButtonProps,
+	_CustomSelectProps,
+} from './types';
+import {
+	contextConnectWithoutRef,
+	useContextSystem,
+	type WordPressComponentProps,
+} from '../context';
+
+export const CustomSelectContext =
+	createContext< CustomSelectContextType >( undefined );
+
+function defaultRenderSelectedValue(
+	value: CustomSelectButtonProps[ 'value' ]
+) {
+	const isValueEmpty = Array.isArray( value )
+		? value.length === 0
+		: value === undefined || value === null;
+
+	if ( isValueEmpty ) {
+		return __( 'Select an item' );
+	}
+
+	if ( Array.isArray( value ) ) {
+		return value.length === 1
+			? value[ 0 ]
+			: // translators: %s: number of items selected (it will always be 2 or more items)
+			  sprintf( __( '%s items selected' ), value.length );
+	}
+
+	return value;
+}
+
+const UnconnectedCustomSelectButton = (
+	props: Omit<
+		WordPressComponentProps<
+			CustomSelectButtonProps & CustomSelectStore,
+			'button',
+			false
+		>,
+		'onChange'
+	>
+) => {
+	const {
+		renderSelectedValue,
+		size = 'default',
+		store,
+		...restProps
+	} = useContextSystem( props, 'CustomSelectControlButton' );
+
+	const { value: currentValue } = store.useState();
+
+	const computedRenderSelectedValue = useMemo(
+		() => renderSelectedValue ?? defaultRenderSelectedValue,
+		[ renderSelectedValue ]
+	);
+
+	return (
+		<Styled.Select
+			{ ...restProps }
+			size={ size }
+			hasCustomRenderProp={ !! renderSelectedValue }
+			store={ store }
+			// to match legacy behavior where using arrow keys
+			// move selection rather than open the popover
+			showOnKeyDown={ false }
+		>
+			<div>{ computedRenderSelectedValue( currentValue ) }</div>
+			<Icon icon={ chevronDown } size={ 18 } />
+		</Styled.Select>
+	);
+};
+
+const CustomSelectButton = contextConnectWithoutRef(
+	UnconnectedCustomSelectButton,
+	'CustomSelectControlButton'
+);
+
+function _CustomSelect( props: _CustomSelectProps & CustomSelectStore ) {
+	const {
+		children,
+		hideLabelFromVision = false,
+		label,
+		store,
+		...restProps
+	} = props;
+
+	return (
+		<>
+			{ hideLabelFromVision ? ( // TODO: Replace with BaseControl
+				<VisuallyHidden as="label">{ label }</VisuallyHidden>
+			) : (
+				<Styled.SelectLabel store={ store }>
+					{ label }
+				</Styled.SelectLabel>
+			) }
+			<CustomSelectButton { ...restProps } store={ store } />
+			<Styled.SelectPopover gutter={ 12 } store={ store } sameWidth>
+				<CustomSelectContext.Provider value={ { store } }>
+					{ children }
+				</CustomSelectContext.Provider>
+			</Styled.SelectPopover>
+		</>
+	);
+}
+
+export default _CustomSelect;

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

@@ -0,0 +1,24 @@
+/**
+ * External dependencies
+ */
+// eslint-disable-next-line no-restricted-imports
+import * as Ariakit from '@ariakit/react';
+/**
+ * Internal dependencies
+ */
+import _CustomSelect from '../custom-select';
+import type { CustomSelectProps } from '../types';
+
+function CustomSelect( props: CustomSelectProps ) {
+	const { defaultValue, onChange, value, ...restProps } = props;
+	// Forward props + store from v2 implementation
+	const store = Ariakit.useSelectStore( {
+		setValue: ( nextValue ) => onChange?.( nextValue ),
+		defaultValue,
+		value,
+	} );
+
+	return <_CustomSelect { ...restProps } store={ store } />;
+}
+
+export default CustomSelect;

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

@@ -1,105 +1,5 @@
-/**
- * External dependencies
- */
-// eslint-disable-next-line no-restricted-imports
-import * as Ariakit from '@ariakit/react';
-/**
- * WordPress dependencies
- */
-import { createContext, useContext } from '@wordpress/element';
-import { __, sprintf } from '@wordpress/i18n';
-
 /**
  * Internal dependencies
  */
-import * as Styled from './styles';
-import type {
-	CustomSelectProps,
-	CustomSelectItemProps,
-	CustomSelectContext as CustomSelectContextType,
-} from './types';
-import type { WordPressComponentProps } from '../context';
-
-export const CustomSelectContext =
-	createContext< CustomSelectContextType >( undefined );
-
-function defaultRenderSelectedValue( value: CustomSelectProps[ 'value' ] ) {
-	const isValueEmpty = Array.isArray( value )
-		? value.length === 0
-		: value === undefined || value === null;
-
-	if ( isValueEmpty ) {
-		return __( 'Select an item' );
-	}
-
-	if ( Array.isArray( value ) ) {
-		return value.length === 1
-			? value[ 0 ]
-			: // translators: %s: number of items selected (it will always be 2 or more items)
-			  sprintf( __( '%s items selected' ), value.length );
-	}
-
-	return value;
-}
-
-export function CustomSelect( {
-	children,
-	defaultValue,
-	label,
-	onChange,
-	size = 'default',
-	value,
-	renderSelectedValue,
-	...props
-}: WordPressComponentProps< CustomSelectProps, 'button', false > ) {
-	const store = Ariakit.useSelectStore( {
-		setValue: ( nextValue ) => onChange?.( nextValue ),
-		defaultValue,
-		value,
-		// fix for Safari bug: https://github.com/WordPress/gutenberg/issues/55023#issuecomment-1834035917
-		virtualFocus: false,
-	} );
-
-	const { value: currentValue } = store.useState();
-
-	const computedRenderSelectedValue =
-		renderSelectedValue ?? defaultRenderSelectedValue;
-
-	return (
-		<>
-			<Styled.CustomSelectLabel store={ store }>
-				{ label }
-			</Styled.CustomSelectLabel>
-			<Styled.CustomSelectButton
-				{ ...props }
-				size={ size }
-				hasCustomRenderProp={ !! renderSelectedValue }
-				store={ store }
-			>
-				{ computedRenderSelectedValue( currentValue ) }
-				<Ariakit.SelectArrow />
-			</Styled.CustomSelectButton>
-			<Styled.CustomSelectPopover gutter={ 12 } store={ store } sameWidth>
-				<CustomSelectContext.Provider value={ { store } }>
-					{ children }
-				</CustomSelectContext.Provider>
-			</Styled.CustomSelectPopover>
-		</>
-	);
-}
-
-export function CustomSelectItem( {
-	children,
-	...props
-}: WordPressComponentProps< CustomSelectItemProps, 'div', false > ) {
-	const customSelectContext = useContext( CustomSelectContext );
-	return (
-		<Styled.CustomSelectItem
-			store={ customSelectContext?.store }
-			{ ...props }
-		>
-			{ children ?? props.value }
-			<Ariakit.SelectItemCheck />
-		</Styled.CustomSelectItem>
-	);
-}
+export { default as CustomSelect } from './legacy-adapter';
+export { default as CustomSelectItem } from './custom-select-item';

package/src/custom-select-control-v2/legacy-adapter.tsx

@@ -0,0 +1,25 @@
+/**
+ * Internal dependencies
+ */
+import _LegacyCustomSelect from './legacy-component';
+import _NewCustomSelect from './default-component';
+import type { CustomSelectProps, LegacyCustomSelectProps } from './types';
+import type { WordPressComponentProps } from '../context';
+
+function isLegacy( props: any ): props is LegacyCustomSelectProps {
+	return typeof props.options !== 'undefined';
+}
+
+function CustomSelect(
+	props:
+		| LegacyCustomSelectProps
+		| WordPressComponentProps< CustomSelectProps, 'button', false >
+) {
+	if ( isLegacy( props ) ) {
+		return <_LegacyCustomSelect { ...props } />;
+	}
+
+	return <_NewCustomSelect { ...props } />;
+}
+
+export default CustomSelect;

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

@@ -0,0 +1,133 @@
+/**
+ * External dependencies
+ */
+// eslint-disable-next-line no-restricted-imports
+import * as Ariakit from '@ariakit/react';
+/**
+ * WordPress dependencies
+ */
+import { useMemo } from '@wordpress/element';
+/**
+ * Internal dependencies
+ */
+import _CustomSelect from '../custom-select';
+import type { LegacyCustomSelectProps } from '../types';
+import { CustomSelectItem } from '..';
+import * as Styled from '../styles';
+import { ContextSystemProvider } from '../../context';
+
+function CustomSelect( props: LegacyCustomSelectProps ) {
+	const {
+		__experimentalShowSelectedHint,
+		__next40pxDefaultSize = false,
+		options,
+		onChange,
+		size = 'default',
+		value,
+		...restProps
+	} = props;
+
+	// Forward props + store from v2 implementation
+	const store = Ariakit.useSelectStore( {
+		async setValue( nextValue ) {
+			if ( ! onChange ) return;
+
+			// Executes the logic in a microtask after the popup is closed.
+			// This is simply to ensure the isOpen state matches that in Downshift.
+			await Promise.resolve();
+			const state = store.getState();
+
+			const changeObject = {
+				highlightedIndex: state.renderedItems.findIndex(
+					( item ) => item.value === nextValue
+				),
+				inputValue: '',
+				isOpen: state.open,
+				selectedItem: {
+					name: nextValue as string,
+					key: nextValue as string,
+				},
+				type: '',
+			};
+			onChange( changeObject );
+		},
+	} );
+
+	const children = options.map(
+		( { name, key, __experimentalHint, ...rest } ) => {
+			const withHint = (
+				<Styled.WithHintWrapper>
+					<span>{ name }</span>
+					<Styled.ExperimentalHintItem className="components-custom-select-control__item-hint">
+						{ __experimentalHint }
+					</Styled.ExperimentalHintItem>
+				</Styled.WithHintWrapper>
+			);
+
+			return (
+				<CustomSelectItem
+					key={ key }
+					value={ name }
+					children={
+						__experimentalShowSelectedHint ? withHint : name
+					}
+					{ ...rest }
+				/>
+			);
+		}
+	);
+
+	const renderSelectedValueHint = () => {
+		const { value: currentValue } = store.getState();
+
+		const currentHint = options?.find(
+			( { name } ) => currentValue === name
+		);
+
+		return (
+			<>
+				{ currentValue }
+				<Styled.SelectedExperimentalHintItem className="components-custom-select-control__hint">
+					{ currentHint?.__experimentalHint }
+				</Styled.SelectedExperimentalHintItem>
+			</>
+		);
+	};
+
+	// translate legacy button sizing
+	const contextSystemValue = useMemo( () => {
+		let selectedSize;
+
+		if (
+			( __next40pxDefaultSize && size === 'default' ) ||
+			size === '__unstable-large'
+		) {
+			selectedSize = 'default';
+		} else if ( ! __next40pxDefaultSize && size === 'default' ) {
+			selectedSize = 'compact';
+		} else {
+			selectedSize = size;
+		}
+
+		return {
+			CustomSelectControlButton: { _overrides: { size: selectedSize } },
+		};
+	}, [ __next40pxDefaultSize, size ] );
+
+	const translatedProps = {
+		'aria-describedby': props.describedBy,
+		children,
+		renderSelectedValue: __experimentalShowSelectedHint
+			? renderSelectedValueHint
+			: undefined,
+		...restProps,
+	};
+
+	return (
+		<ContextSystemProvider value={ contextSystemValue }>
+			<_CustomSelect { ...translatedProps } store={ store } />
+		</ContextSystemProvider>
+	);
+}
+
+export default CustomSelect;

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

@@ -11,10 +11,11 @@ import { useState } from '@wordpress/element';
 /**
  * Internal dependencies
  */
-import { CustomSelect, CustomSelectItem } from '..';
+import CustomSelect from '../default-component';
+import { CustomSelectItem } from '..';
 
 const meta: Meta< typeof CustomSelect > = {
-	title: 'Components (Experimental)/CustomSelectControl v2',
+	title: 'Components (Experimental)/CustomSelectControl v2/Default',
 	component: CustomSelect,
 	subcomponents: {
 		// @ts-expect-error - See https://github.com/storybookjs/storybook/issues/23170
@@ -22,15 +23,14 @@ const meta: Meta< typeof CustomSelect > = {
 	},
 	argTypes: {
 		children: { control: { type: null } },
-		renderSelectedValue: { control: { type: null } },
 		value: { control: { type: null } },
 	},
+	tags: [ 'status-wip' ],
 	parameters: {
 		badges: [ 'wip' ],
 		actions: { argTypesRegex: '^on.*' },
 		controls: { expanded: true },
 		docs: {
-			canvas: { sourceState: 'shown' },
 			source: { excludeDecorators: true },
 		},
 	},
@@ -49,15 +49,11 @@ const meta: Meta< typeof CustomSelect > = {
 export default meta;
 
 const Template: StoryFn< typeof CustomSelect > = ( props ) => {
-	return <CustomSelect { ...props } />;
-};
-
-const ControlledTemplate: StoryFn< typeof CustomSelect > = ( props ) => {
 	const [ value, setValue ] = useState< string | string[] >();
 	return (
 		<CustomSelect
 			{ ...props }
-			onChange={ ( nextValue ) => {
+			onChange={ ( nextValue: string | string[] ) => {
 				setValue( nextValue );
 				props.onChange?.( nextValue );
 			} }
@@ -68,14 +64,18 @@ const ControlledTemplate: StoryFn< typeof CustomSelect > = ( props ) => {
 
 export const Default = Template.bind( {} );
 Default.args = {
-	label: 'Label',
+	label: 'Label text',
+	defaultValue: 'Select a color...',
 	children: (
 		<>
-			<CustomSelectItem value="Small">
-				<span style={ { fontSize: '75%' } }>Small</span>
+			<CustomSelectItem value="Blue">
+				<span style={ { color: 'blue' } }>Blue</span>
 			</CustomSelectItem>
-			<CustomSelectItem value="Something bigger">
-				<span style={ { fontSize: '200%' } }>Something bigger</span>
+			<CustomSelectItem value="Purple">
+				<span style={ { color: 'purple' } }>Purple</span>
+			</CustomSelectItem>
+			<CustomSelectItem value="Pink">
+				<span style={ { color: 'deeppink' } }>Pink</span>
 			</CustomSelectItem>
 		</>
 	),
@@ -83,21 +83,13 @@ Default.args = {
 
 /**
  * Multiple selection can be enabled by using an array for the `value` and
- * `defaultValue` props. The argument of the `onChange` function will also
+ * `defaultValue` props. The argument type of the `onChange` function will also
  * change accordingly.
  */
-export const MultiSelect = Template.bind( {} );
-MultiSelect.args = {
-	defaultValue: [ 'lavender', 'tangerine' ],
+export const MultipleSelection = Template.bind( {} );
+MultipleSelection.args = {
 	label: 'Select Colors',
-	renderSelectedValue: ( currentValue: string | string[] ) => {
-		if ( ! Array.isArray( currentValue ) ) {
-			return currentValue;
-		}
-		if ( currentValue.length === 0 ) return 'No colors selected';
-		if ( currentValue.length === 1 ) return currentValue[ 0 ];
-		return `${ currentValue.length } colors selected`;
-	},
+	defaultValue: [ 'lavender', 'tangerine' ],
 	children: (
 		<>
 			{ [
@@ -116,32 +108,34 @@ MultiSelect.args = {
 	),
 };
 
-const renderControlledValue = ( gravatar: string | string[] ) => {
+const renderItem = ( gravatar: string | string[] ) => {
 	const avatar = `https://gravatar.com/avatar?d=${ gravatar }`;
 	return (
 		<div style={ { display: 'flex', alignItems: 'center' } }>
 			<img
 				style={ { maxHeight: '75px', marginRight: '10px' } }
-				key={ avatar }
 				src={ avatar }
 				alt=""
-				aria-hidden="true"
 			/>
 			<span>{ gravatar }</span>
 		</div>
 	);
 };
 
-export const Controlled = ControlledTemplate.bind( {} );
-Controlled.args = {
+/**
+ * The `renderSelectedValue` prop can be used to customize how the selected value
+ * is rendered in the dropdown trigger.
+ */
+export const CustomSelectedValue = Template.bind( {} );
+CustomSelectedValue.args = {
 	label: 'Default Gravatars',
-	renderSelectedValue: renderControlledValue,
+	renderSelectedValue: renderItem,
 	children: (
 		<>
 			{ [ 'mystery-person', 'identicon', 'wavatar', 'retro' ].map(
 				( option ) => (
 					<CustomSelectItem key={ option } value={ option }>
-						{ renderControlledValue( option ) }
+						{ renderItem( option ) }
 					</CustomSelectItem>
 				)
 			) }

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

@@ -0,0 +1,88 @@
+/**
+ * External dependencies
+ */
+import type { Meta, StoryFn } from '@storybook/react';
+
+/**
+ * WordPress dependencies
+ */
+import { useState } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import _LegacyCustomSelect from '../legacy-component';
+import { CustomSelect } from '..';
+
+const meta: Meta< typeof _LegacyCustomSelect > = {
+	title: 'Components (Experimental)/CustomSelectControl v2/Legacy',
+	component: _LegacyCustomSelect,
+	argTypes: {
+		onChange: { control: { type: null } },
+		value: { control: { type: null } },
+	},
+	parameters: {
+		badges: [ 'wip' ],
+		actions: { argTypesRegex: '^on.*' },
+		controls: { expanded: true },
+		docs: {
+			source: { excludeDecorators: true },
+		},
+	},
+	decorators: [
+		( Story ) => (
+			<div
+				style={ {
+					minHeight: '150px',
+				} }
+			>
+				<Story />
+			</div>
+		),
+	],
+};
+export default meta;
+
+const Template: StoryFn< typeof _LegacyCustomSelect > = ( props ) => {
+	const [ fontSize, setFontSize ] = useState( props.options[ 0 ] );
+
+	const onChange: React.ComponentProps<
+		typeof _LegacyCustomSelect
+	>[ 'onChange' ] = ( changeObject ) => {
+		setFontSize( changeObject.selectedItem );
+		props.onChange?.( changeObject );
+	};
+
+	return (
+		<CustomSelect { ...props } onChange={ onChange } value={ fontSize } />
+	);
+};
+
+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%' },
+		},
+	],
+};