@wordpress/components 28.3.0 → 28.4.0

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

@@ -63,81 +63,83 @@ function MyControlledCustomSelectControl() {
 
 ### Props
 
-#### className
+#### `className`: `string`
 
-A custom class name to append to the outer `<div>`.
+Optional classname for the component.
 
--   Type: `String`
 -   Required: No
 
-#### hideLabelFromVision
+#### `hideLabelFromVision`: `boolean`
 
-Used to visually hide the label. It will always be visible to screen readers.
+Hide the label visually, while keeping available to assistive technology.
 
--   Type: `Boolean`
 -   Required: No
 
-#### label
+#### `describedBy`: `string`
 
-The label for the control.
+Description for the select trigger button used by assistive technology. If no value is passed, the text "Currently selected: selectedItem.name" will be used fully translated.
+
+-   Required: No
+
+#### `label`: `string`
+
+Label for the control.
 
--   Type: `String`
 -   Required: Yes
 
-#### describedBy
+#### `onChange`: `( newValue: ChangeObject ) => void`
 
-Pass in a description that will be shown to screen readers associated with the select trigger button. If no value is passed, the text "Currently selected: selectedItem.name" will be used fully translated.
+Function called with the control's internal state changes. The `selectedItem` property contains the next selected item.
 
--   Type: `String`
 -   Required: No
 
-#### options
+#### `options`: `Array< Option >`
 
-The options that can be chosen from.
+The list of options that can be chosen from.
 
--   Type: `Array<{ key: String, name: String, style: ?{}, className: ?String, ...rest }>`
 -   Required: Yes
 
-#### onChange
+#### `size`: `'default' | 'small' | '\_\_unstable-large'`
 
-Function called with the control's internal state changes. The `selectedItem` property contains the next selected item.
+The size of the control.
+
+-   Default: `'default'`
+-   Required: No
+
+#### `showSelectedHint`: `boolean`
+
+Show the hint of the selected item in the trigger button.
 
--   Type: `Function`
 -   Required: No
 
-#### value
+#### `value`: `Option`
 
 Can be used to externally control the value of the control, like in the `MyControlledCustomSelectControl` example above.
 
--   Type: `Object`
 -   Required: No
 
-#### onMouseOver
+#### `onMouseOver`: `MouseEventHandler< HTMLButtonElement >`
 
-A handler for onMouseOver events.
+A handler for `mouseover` events on the trigger button.
 
--   Type: `Function`
 -   Required: No
 
-#### onMouseOut
+#### `onMouseOut`: `MouseEventHandler< HTMLButtonElement >`
 
-A handler for onMouseOut events.
+A handler for `mouseout` events on the trigger button.
 
--   Type: `Function`
 -   Required: No
 
-#### onFocus
+#### `onFocus`: `FocusEventHandler< HTMLButtonElement >`
 
-A handler for onFocus events.
+A handler for `focus` events on the trigger button.
 
--   Type: `Function`
 -   Required: No
 
-#### onBlur
+#### `onBlur`: `FocusEventHandler< HTMLButtonElement >`
 
-A handler for onBlur events.
+A handler for `blur` events on the trigger button.
 
--   Type: `Function`
 -   Required: No
 
 ## Related components

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

@@ -7,14 +7,36 @@ import clsx from 'clsx';
 /**
  * Internal dependencies
  */
-import _CustomSelect from '../custom-select';
-import CustomSelectItem from '../item';
-import type { LegacyCustomSelectProps } from '../types';
-import * as Styled from '../styles';
+import _CustomSelect from '../custom-select-control-v2/custom-select';
+import CustomSelectItem from '../custom-select-control-v2/item';
+import * as Styled from '../custom-select-control-v2/styles';
+import type { CustomSelectProps } from './types';
 
-function CustomSelectControl( props: LegacyCustomSelectProps ) {
+function useDeprecatedProps( {
+	__experimentalShowSelectedHint,
+	...otherProps
+}: CustomSelectProps ) {
+	return {
+		showSelectedHint: __experimentalShowSelectedHint,
+		...otherProps,
+	};
+}
+
+// The removal of `__experimentalHint` in favour of `hint` doesn't happen in
+// the `useDeprecatedProps` hook in order not to break consumers that rely
+// on object identity (see https://github.com/WordPress/gutenberg/pull/63248#discussion_r1672213131)
+function applyOptionDeprecations( {
+	__experimentalHint,
+	...rest
+}: CustomSelectProps[ 'options' ][ number ] ) {
+	return {
+		hint: __experimentalHint,
+		...rest,
+	};
+}
+
+function CustomSelectControl( props: CustomSelectProps ) {
 	const {
-		__experimentalShowSelectedHint = false,
 		__next40pxDefaultSize = false,
 		describedBy,
 		options,
@@ -22,8 +44,9 @@ function CustomSelectControl( props: LegacyCustomSelectProps ) {
 		size = 'default',
 		value,
 		className: classNameProp,
+		showSelectedHint = false,
 		...restProps
-	} = props;
+	} = useDeprecatedProps( props );
 
 	// Forward props + store from v2 implementation
 	const store = Ariakit.useSelectStore( {
@@ -37,7 +60,8 @@ function CustomSelectControl( props: LegacyCustomSelectProps ) {
 			}
 
 			// Executes the logic in a microtask after the popup is closed.
-			// This is simply to ensure the isOpen state matches that in Downshift.
+			// This is simply to ensure the isOpen state matches the one from the
+			// previous legacy implementation.
 			await Promise.resolve();
 			const state = store.getState();
 
@@ -60,16 +84,17 @@ function CustomSelectControl( props: LegacyCustomSelectProps ) {
 		defaultValue: options[ 0 ]?.name,
 	} );
 
-	const children = options.map(
-		( { name, key, __experimentalHint, style, className } ) => {
+	const children = options
+		.map( applyOptionDeprecations )
+		.map( ( { name, key, hint, style, className } ) => {
 			const withHint = (
 				<Styled.WithHintItemWrapper>
 					<span>{ name }</span>
 					<Styled.WithHintItemHint
-					// TODO: Legacy classname. Add V1 styles are removed from the codebase
-					// className="components-custom-select-control__item-hint"
+						// Keeping the classname for legacy reasons
+						className="components-custom-select-control__item-hint"
 					>
-						{ __experimentalHint }
+						{ hint }
 					</Styled.WithHintItemHint>
 				</Styled.WithHintItemWrapper>
 			);
@@ -78,38 +103,38 @@ function CustomSelectControl( props: LegacyCustomSelectProps ) {
 				<CustomSelectItem
 					key={ key }
 					value={ name }
-					children={ __experimentalHint ? withHint : name }
+					children={ hint ? withHint : name }
 					style={ style }
 					className={ clsx(
-						// TODO: Legacy classname. Add V1 styles are removed from the codebase
-						// 'components-custom-select-control__item',
-						className
-						// TODO: Legacy classname. Add V1 styles are removed from the codebase
-						// {
-						// 	'has-hint': __experimentalHint,
-						// }
+						className,
+						// Keeping the classnames for legacy reasons
+						'components-custom-select-control__item',
+						{
+							'has-hint': hint,
+						}
 					) }
 				/>
 			);
-		}
-	);
+		} );
 
 	const renderSelectedValueHint = () => {
 		const { value: currentValue } = store.getState();
 
-		const currentHint = options?.find(
-			( { name } ) => currentValue === name
-		);
+		const selectedOptionHint = options
+			?.map( applyOptionDeprecations )
+			?.find( ( { name } ) => currentValue === name )?.hint;
 
 		return (
 			<Styled.SelectedExperimentalHintWrapper>
 				{ currentValue }
-				<Styled.SelectedExperimentalHintItem
-				// TODO: Legacy classname. Add V1 styles are removed from the codebase
-				// className="components-custom-select-control__hint"
-				>
-					{ currentHint?.__experimentalHint }
-				</Styled.SelectedExperimentalHintItem>
+				{ selectedOptionHint && (
+					<Styled.SelectedExperimentalHintItem
+						// Keeping the classname for legacy reasons
+						className="components-custom-select-control__hint"
+					>
+						{ selectedOptionHint }
+					</Styled.SelectedExperimentalHintItem>
+				) }
 			</Styled.SelectedExperimentalHintWrapper>
 		);
 	};
@@ -131,15 +156,13 @@ function CustomSelectControl( props: LegacyCustomSelectProps ) {
 		<_CustomSelect
 			aria-describedby={ describedBy }
 			renderSelectedValue={
-				__experimentalShowSelectedHint
-					? renderSelectedValueHint
-					: undefined
+				showSelectedHint ? renderSelectedValueHint : undefined
 			}
 			size={ translatedSize }
 			store={ store }
 			className={ clsx(
-				// TODO: Legacy classname. Add V1 styles are removed from the codebase
-				// 'components-custom-select-control',
+				// Keeping the classname for legacy reasons
+				'components-custom-select-control',
 				classNameProp
 			) }
 			isLegacy

package/src/custom-select-control/stories/index.story.tsx

@@ -1,7 +1,7 @@
 /**
  * External dependencies
  */
-import type { StoryFn } from '@storybook/react';
+import type { Meta, StoryFn } from '@storybook/react';
 
 /**
  * WordPress dependencies
@@ -13,32 +13,40 @@ import { useState } from '@wordpress/element';
  */
 import CustomSelectControl from '..';
 
-export default {
+const meta: Meta< typeof CustomSelectControl > = {
 	title: 'Components/CustomSelectControl',
 	component: CustomSelectControl,
 	argTypes: {
-		__next40pxDefaultSize: { control: { type: 'boolean' } },
-		__experimentalShowSelectedHint: { control: { type: 'boolean' } },
-		size: {
-			options: [ 'small', 'default', '__unstable-large' ],
-			control: {
-				type: 'radio',
-			},
-		},
 		onChange: { control: { type: null } },
 		value: { control: { type: null } },
 	},
 	parameters: {
 		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 CustomSelectControl > = ( props ) => {
 	const [ value, setValue ] = useState( props.options[ 0 ] );
 
 	const onChange: React.ComponentProps<
 		typeof CustomSelectControl
-	>[ 'onChange' ] = ( changeObject: { selectedItem: any } ) => {
+	>[ 'onChange' ] = ( changeObject ) => {
 		setValue( changeObject.selectedItem );
 		props.onChange?.( changeObject );
 	};
@@ -52,7 +60,7 @@ const Template: StoryFn< typeof CustomSelectControl > = ( props ) => {
 	);
 };
 
-export const Default: StoryFn = Template.bind( {} );
+export const Default = Template.bind( {} );
 Default.args = {
 	label: 'Label',
 	options: [
@@ -80,7 +88,7 @@ Default.args = {
 	],
 };
 
-export const WithLongLabels: StoryFn = Template.bind( {} );
+export const WithLongLabels = Template.bind( {} );
 WithLongLabels.args = {
 	...Default.args,
 	options: [
@@ -99,29 +107,29 @@ WithLongLabels.args = {
 	],
 };
 
-export const WithHints: StoryFn = Template.bind( {} );
+export const WithHints = Template.bind( {} );
 WithHints.args = {
 	...Default.args,
 	options: [
 		{
 			key: 'thumbnail',
 			name: 'Thumbnail',
-			__experimentalHint: '150x150',
+			hint: '150x150',
 		},
 		{
 			key: 'medium',
 			name: 'Medium',
-			__experimentalHint: '250x250',
+			hint: '250x250',
 		},
 		{
 			key: 'large',
 			name: 'Large',
-			__experimentalHint: '1024x1024',
+			hint: '1024x1024',
 		},
 		{
 			key: 'full',
 			name: 'Full Size',
-			__experimentalHint: '1600x1600',
+			hint: '1600x1600',
 		},
 	],
 };