@wordpress/components 23.3.2 → 23.4.0

package/src/combobox-control/{index.js → index.tsx}

@@ -30,25 +30,83 @@ import { FlexBlock, FlexItem } from '../flex';
 import withFocusOutside from '../higher-order/with-focus-outside';
 import { useControlledValue } from '../utils/hooks';
 import { normalizeTextString } from '../utils/strings';
+import type { ComboboxControlOption, ComboboxControlProps } from './types';
+import type { TokenInputProps } from '../form-token-field/types';
 
 const noop = () => {};
 
 const DetectOutside = withFocusOutside(
 	class extends Component {
+		// @ts-expect-error - TODO: Should be resolved when `withFocusOutside` is refactored to TypeScript
 		handleFocusOutside( event ) {
+			// @ts-expect-error - TODO: Should be resolved when `withFocusOutside` is refactored to TypeScript
 			this.props.onFocusOutside( event );
 		}
 
 		render() {
+			// @ts-expect-error - TODO: Should be resolved when `withFocusOutside` is refactored to TypeScript
 			return this.props.children;
 		}
 	}
 );
 
+const getIndexOfMatchingSuggestion = (
+	selectedSuggestion: ComboboxControlOption | null,
+	matchingSuggestions: ComboboxControlOption[]
+) =>
+	selectedSuggestion === null
+		? -1
+		: matchingSuggestions.indexOf( selectedSuggestion );
+
+/**
+ * `ComboboxControl` is an enhanced version of a [`SelectControl`](../select-control/README.md) with the addition of
+ * being able to search for options using a search input.
+ *
+ * ```jsx
+ * import { ComboboxControl } from '@wordpress/components';
+ * import { useState } from '@wordpress/element';
+ *
+ * const options = [
+ * 	{
+ * 		value: 'small',
+ * 		label: 'Small',
+ * 	},
+ * 	{
+ * 		value: 'normal',
+ * 		label: 'Normal',
+ * 	},
+ * 	{
+ * 		value: 'large',
+ * 		label: 'Large',
+ * 	},
+ * ];
+ *
+ * function MyComboboxControl() {
+ * 	const [ fontSize, setFontSize ] = useState();
+ * 	const [ filteredOptions, setFilteredOptions ] = useState( options );
+ * 	return (
+ * 		<ComboboxControl
+ * 			label="Font Size"
+ * 			value={ fontSize }
+ * 			onChange={ setFontSize }
+ * 			options={ filteredOptions }
+ * 			onFilterValueChange={ ( inputValue ) =>
+ * 				setFilteredOptions(
+ * 					options.filter( ( option ) =>
+ * 						option.label
+ * 							.toLowerCase()
+ * 							.startsWith( inputValue.toLowerCase() )
+ * 					)
+ * 				)
+ * 			}
+ * 		/>
+ * 	);
+ * }
+ * ```
+ */
 function ComboboxControl( {
-	/** Start opting into the new margin-free styles that will become the default in a future version. */
 	__nextHasNoMarginBottom = false,
-	__next36pxDefaultSize,
+	__next36pxDefaultSize = false,
 	value: valueProp,
 	label,
 	options,
@@ -62,7 +120,7 @@ function ComboboxControl( {
 		selected: __( 'Item selected.' ),
 	},
 	__experimentalRenderItem,
-} ) {
+}: ComboboxControlProps ) {
 	const [ value, setValue ] = useControlledValue( {
 		value: valueProp,
 		onChange: onChangeProp,
@@ -80,11 +138,11 @@ function ComboboxControl( {
 	const [ isExpanded, setIsExpanded ] = useState( false );
 	const [ inputHasFocus, setInputHasFocus ] = useState( false );
 	const [ inputValue, setInputValue ] = useState( '' );
-	const inputContainer = useRef();
+	const inputContainer = useRef< HTMLInputElement >( null );
 
 	const matchingSuggestions = useMemo( () => {
-		const startsWithMatch = [];
-		const containsMatch = [];
+		const startsWithMatch: ComboboxControlOption[] = [];
+		const containsMatch: ComboboxControlOption[] = [];
 		const match = normalizeTextString( inputValue );
 		options.forEach( ( option ) => {
 			const index = normalizeTextString( option.label ).indexOf( match );
@@ -98,7 +156,9 @@ function ComboboxControl( {
 		return startsWithMatch.concat( containsMatch );
 	}, [ inputValue, options ] );
 
-	const onSuggestionSelected = ( newSelectedSuggestion ) => {
+	const onSuggestionSelected = (
+		newSelectedSuggestion: ComboboxControlOption
+	) => {
 		setValue( newSelectedSuggestion.value );
 		speak( messages.selected, 'assertive' );
 		setSelectedSuggestion( newSelectedSuggestion );
@@ -107,7 +167,10 @@ function ComboboxControl( {
 	};
 
 	const handleArrowNavigation = ( offset = 1 ) => {
-		const index = matchingSuggestions.indexOf( selectedSuggestion );
+		const index = getIndexOfMatchingSuggestion(
+			selectedSuggestion,
+			matchingSuggestions
+		);
 		let nextIndex = index + offset;
 		if ( nextIndex < 0 ) {
 			nextIndex = matchingSuggestions.length - 1;
@@ -118,7 +181,9 @@ function ComboboxControl( {
 		setIsExpanded( true );
 	};
 
-	const onKeyDown = ( event ) => {
+	const onKeyDown: React.KeyboardEventHandler< HTMLDivElement > = (
+		event
+	) => {
 		let preventDefault = false;
 
 		if (
@@ -177,7 +242,7 @@ function ComboboxControl( {
 		setIsExpanded( false );
 	};
 
-	const onInputChange = ( event ) => {
+	const onInputChange: TokenInputProps[ 'onChange' ] = ( event ) => {
 		const text = event.value;
 		setInputValue( text );
 		onFilterValueChange( text );
@@ -188,14 +253,17 @@ function ComboboxControl( {
 
 	const handleOnReset = () => {
 		setValue( null );
-		inputContainer.current.focus();
+		inputContainer.current?.focus();
 	};
 
 	// Update current selections when the filter input changes.
 	useEffect( () => {
 		const hasMatchingSuggestions = matchingSuggestions.length > 0;
 		const hasSelectedMatchingSuggestions =
-			matchingSuggestions.indexOf( selectedSuggestion ) > 0;
+			getIndexOfMatchingSuggestion(
+				selectedSuggestion,
+				matchingSuggestions
+			) > 0;
 
 		if ( hasMatchingSuggestions && ! hasSelectedMatchingSuggestions ) {
 			// If the current selection isn't present in the list of suggestions, then automatically select the first item from the list of suggestions.
@@ -235,7 +303,6 @@ function ComboboxControl( {
 					className,
 					'components-combobox-control'
 				) }
-				tabIndex="-1"
 				label={ label }
 				id={ `components-form-token-input-${ instanceId }` }
 				hideLabelFromVision={ hideLabelFromVision }
@@ -243,7 +310,7 @@ function ComboboxControl( {
 			>
 				<div
 					className="components-combobox-control__suggestions-container"
-					tabIndex="-1"
+					tabIndex={ -1 }
 					onKeyDown={ onKeyDown }
 				>
 					<InputWrapperFlex
@@ -258,8 +325,9 @@ function ComboboxControl( {
 								onFocus={ onFocus }
 								onBlur={ onBlur }
 								isExpanded={ isExpanded }
-								selectedSuggestionIndex={ matchingSuggestions.indexOf(
-									selectedSuggestion
+								selectedSuggestionIndex={ getIndexOfMatchingSuggestion(
+									selectedSuggestion,
+									matchingSuggestions
 								) }
 								onChange={ onInputChange }
 							/>
@@ -279,13 +347,17 @@ function ComboboxControl( {
 					{ isExpanded && (
 						<SuggestionsList
 							instanceId={ instanceId }
-							match={ { label: inputValue } }
+							// The empty string for `value` here is not actually used, but is
+							// just a quick way to satisfy the TypeScript requirements of SuggestionsList.
+							// See: https://github.com/WordPress/gutenberg/pull/47581/files#r1091089330
+							match={ { label: inputValue, value: '' } }
 							displayTransform={ ( suggestion ) =>
 								suggestion.label
 							}
 							suggestions={ matchingSuggestions }
-							selectedIndex={ matchingSuggestions.indexOf(
-								selectedSuggestion
+							selectedIndex={ getIndexOfMatchingSuggestion(
+								selectedSuggestion,
+								matchingSuggestions
 							) }
 							onHover={ setSelectedSuggestion }
 							onSelect={ onSuggestionSelected }

package/src/combobox-control/stories/index.tsx

@@ -0,0 +1,114 @@
+/**
+ * External dependencies
+ */
+import type { ComponentMeta, ComponentStory } from '@storybook/react';
+
+/**
+ * WordPress dependencies
+ */
+import { useState } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import ComboboxControl from '..';
+import type { ComboboxControlProps } from '../types';
+
+const countries = [
+	{ name: 'Afghanistan', code: 'AF' },
+	{ name: 'Åland Islands', code: 'AX' },
+	{ name: 'Albania', code: 'AL' },
+	{ name: 'Algeria', code: 'DZ' },
+	{ name: 'American Samoa', code: 'AS' },
+];
+
+const meta: ComponentMeta< typeof ComboboxControl > = {
+	title: 'Components/ComboboxControl',
+	component: ComboboxControl,
+	argTypes: {
+		value: { control: { type: null } },
+	},
+	parameters: {
+		actions: { argTypesRegex: '^on.*' },
+		controls: { expanded: true },
+		docs: { source: { state: 'open' } },
+	},
+};
+export default meta;
+
+const mapCountryOption = ( country: typeof countries[ number ] ) => ( {
+	value: country.code,
+	label: country.name,
+} );
+
+const countryOptions = countries.map( mapCountryOption );
+
+const Template: ComponentStory< typeof ComboboxControl > = ( {
+	onChange,
+	...args
+} ) => {
+	const [ value, setValue ] =
+		useState< ComboboxControlProps[ 'value' ] >( null );
+
+	return (
+		<>
+			<ComboboxControl
+				{ ...args }
+				value={ value }
+				onChange={ ( ...changeArgs ) => {
+					setValue( ...changeArgs );
+					onChange?.( ...changeArgs );
+				} }
+			/>
+		</>
+	);
+};
+export const Default = Template.bind( {} );
+Default.args = {
+	__next36pxDefaultSize: false,
+	allowReset: false,
+	label: 'Select a country',
+	options: countryOptions,
+};
+
+/**
+ * The rendered output of each suggestion can be customized by passing a
+ * render function to the `__experimentalRenderItem` prop. (This is still an experimental feature
+ * and is subject to change.)
+ */
+export const WithCustomRenderItem = Template.bind( {} );
+WithCustomRenderItem.args = {
+	...Default.args,
+	label: 'Select an author',
+	options: [
+		{
+			value: 'parsley',
+			label: 'Parsley Montana',
+			age: 48,
+			country: 'Germany',
+		},
+		{
+			value: 'cabbage',
+			label: 'Cabbage New York',
+			age: 44,
+			country: 'France',
+		},
+		{
+			value: 'jake',
+			label: 'Jake Weary',
+			age: 41,
+			country: 'United Kingdom',
+		},
+	],
+	__experimentalRenderItem: ( { item } ) => {
+		const { label, age, country } = item;
+		return (
+			<div>
+				<div style={ { marginBottom: '0.2rem' } }>{ label }</div>
+				<small>
+					Age: { age }, Country: { country }
+				</small>
+			</div>
+		);
+	},
+};

package/src/combobox-control/styles.ts

@@ -9,8 +9,11 @@ import { css } from '@emotion/react';
  */
 import { Flex } from '../flex';
 import { space } from '../ui/utils/space';
+import type { ComboboxControlProps } from './types';
 
-const deprecatedDefaultSize = ( { __next36pxDefaultSize } ) =>
+const deprecatedDefaultSize = ( {
+	__next36pxDefaultSize,
+}: Pick< ComboboxControlProps, '__next36pxDefaultSize' > ) =>
 	! __next36pxDefaultSize &&
 	css`
 		height: 28px; // 30px - 2px vertical borders on parent container

package/src/combobox-control/test/{index.js → index.tsx}

@@ -12,7 +12,8 @@ import { useState } from '@wordpress/element';
 /**
  * Internal dependencies
  */
-import ComboboxControl from '../';
+import ComboboxControl from '..';
+import type { ComboboxControlOption, ComboboxControlProps } from '../types';
 
 const timezones = [
 	{ label: 'Greenwich Mean Time', value: 'GMT' },
@@ -49,20 +50,21 @@ const timezones = [
 ];
 
 const defaultLabelText = 'Select a timezone';
-const getLabel = ( labelText ) => screen.getByText( labelText );
-const getInput = ( name ) => screen.getByRole( 'combobox', { name } );
-const getOption = ( name ) => screen.getByRole( 'option', { name } );
+const getLabel = ( labelText: string ) => screen.getByText( labelText );
+const getInput = ( name: string ) => screen.getByRole( 'combobox', { name } );
+const getOption = ( name: string ) => screen.getByRole( 'option', { name } );
 const getAllOptions = () => screen.getAllByRole( 'option' );
-const getOptionSearchString = ( option ) => option.label.substring( 0, 11 );
+const getOptionSearchString = ( option: ComboboxControlOption ) =>
+	option.label.substring( 0, 11 );
 const setupUser = () => userEvent.setup();
 
 const ControlledComboboxControl = ( {
 	value: valueProp,
 	onChange,
 	...props
-} ) => {
+}: ComboboxControlProps ) => {
 	const [ value, setValue ] = useState( valueProp );
-	const handleOnChange = ( newValue ) => {
+	const handleOnChange: ComboboxControlProps[ 'onChange' ] = ( newValue ) => {
 		setValue( newValue );
 		onChange?.( newValue );
 	};

package/src/combobox-control/types.ts

@@ -0,0 +1,69 @@
+/**
+ * Internal dependencies
+ */
+import type { BaseControlProps } from '../base-control/types';
+
+export type ComboboxControlOption = {
+	label: string;
+	value: string;
+	[ key: string ]: any;
+};
+
+export type ComboboxControlProps = Pick<
+	BaseControlProps,
+	| '__nextHasNoMarginBottom'
+	| 'className'
+	| 'label'
+	| 'hideLabelFromVision'
+	| 'help'
+> & {
+	/**
+	 * Custom renderer invoked for each option in the suggestion list.
+	 * The render prop receives as its argument an object containing, under the `item` key,
+	 * the single option's data (directly from the array of data passed to the `options` prop).
+	 */
+	__experimentalRenderItem?: ( args: {
+		item: ComboboxControlOption;
+	} ) => React.ReactNode;
+	/**
+	 * Start opting into the larger default height that will become the default size in a future version.
+	 *
+	 * @default false
+	 */
+	__next36pxDefaultSize?: boolean;
+	/**
+	 * Show a reset button to clear the input.
+	 *
+	 * @default true
+	 */
+	allowReset?: boolean;
+	/**
+	 * Customizable UI messages.
+	 */
+	messages?: {
+		/**
+		 * The message to announce to screen readers when a suggestion is selected.
+		 *
+		 * @default `__( 'Item selected.' )`
+		 */
+		selected: string;
+	};
+	/**
+	 * Function called with the selected value changes.
+	 */
+	onChange?: ( value: ComboboxControlProps[ 'value' ] ) => void;
+	/**
+	 * Function called when the control's search input value changes. The argument contains the next input value.
+	 *
+	 * @default noop
+	 */
+	onFilterValueChange?: ( value: string ) => void;
+	/**
+	 * The options that can be chosen from.
+	 */
+	options: ComboboxControlOption[];
+	/**
+	 * The current value of the control.
+	 */
+	value?: string | null;
+};

package/src/custom-gradient-picker/index.js

@@ -53,7 +53,6 @@ const GradientAnglePicker = ( { gradientAST, hasGradient, onChange } ) => {
 		<AnglePickerControl
 			__nextHasNoMarginBottom
 			onChange={ onAngleChange }
-			labelPosition="top"
 			value={ hasGradient ? angle : '' }
 		/>
 	);

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

@@ -10,9 +10,9 @@ export default {
 		__next36pxDefaultSize: { control: { type: 'boolean' } },
 		__experimentalShowSelectedHint: { control: { type: 'boolean' } },
 		size: {
+			options: [ 'small', 'default', '__unstable-large' ],
 			control: {
 				type: 'radio',
-				options: [ 'small', 'default', '__unstable-large' ],
 			},
 		},
 	},

package/src/date-time/time/index.tsx

@@ -51,7 +51,7 @@ function from12hTo24h( hours: number, isPm: boolean ) {
  * given width. For example, the hours and minutes inputs are padded to 2 so
  * that '4' appears as '04'.
  *
- * @param  pad How many digits the value should be.
+ * @param pad How many digits the value should be.
  */
 function buildPadInputStateReducer( pad: number ) {
 	return ( state: InputState, action: InputAction ) => {

package/src/date-time/utils.ts

@@ -7,7 +7,7 @@ import { toDate } from 'date-fns';
  * Like date-fn's toDate, but tries to guess the format when a string is
  * given.
  *
- * @param  input Value to turn into a date.
+ * @param input Value to turn into a date.
  */
 export function inputToDate( input: Date | string | number ): Date {
 	if ( typeof input === 'string' ) {

package/src/draggable/index.tsx

@@ -75,7 +75,7 @@ export function Draggable( {
 	/**
 	 * Removes the element clone, resets cursor, and removes drag listener.
 	 *
-	 * @param  event The non-custom DragEvent.
+	 * @param event The non-custom DragEvent.
 	 */
 	function end( event: DragEvent ) {
 		event.preventDefault();
@@ -94,7 +94,7 @@ export function Draggable( {
 	 * - Sets transfer data.
 	 * - Adds dragover listener.
 	 *
-	 * @param  event The non-custom DragEvent.
+	 * @param event The non-custom DragEvent.
 	 */
 	function start( event: DragEvent ) {
 		const { ownerDocument } = event.target as HTMLElement;

package/src/dropdown-menu/test/index.js

@@ -1,7 +1,7 @@
 /**
  * External dependencies
  */
-import { act, render, screen, waitFor, within } from '@testing-library/react';
+import { render, screen, waitFor, within } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 
 /**
@@ -63,10 +63,6 @@ describe( 'DropdownMenu', () => {
 
 		await user.keyboard( '[ArrowDown]' );
 
-		// Wait for the `floating-ui` effects in `Dropdown`/`Popover` to finish running
-		// See also: https://floating-ui.com/docs/react-dom#testing
-		await act( () => Promise.resolve() );
-
 		const menu = screen.getByRole( 'menu' );
 
 		// we need to wait because showing the dropdown is animated
@@ -86,15 +82,11 @@ describe( 'DropdownMenu', () => {
 			/>
 		);
 
-		const button = screen.getByRole( 'button' );
-		act( () => button.focus() );
+		// Move focus on the toggle button
+		await user.tab();
 
 		await user.keyboard( '[ArrowDown]' );
 
-		// Wait for the `floating-ui` effects in `Dropdown`/`Popover` to finish running
-		// See also: https://floating-ui.com/docs/react-dom#testing
-		await act( () => Promise.resolve() );
-
 		const menu = screen.getByRole( 'menu' );
 
 		// we need to wait because showing the dropdown is animated

package/src/focal-point-picker/utils.ts

@@ -19,7 +19,7 @@ const VIDEO_EXTENSIONS = [
 /**
  * Gets the extension of a file name.
  *
- * @param  filename The file name.
+ * @param filename The file name.
  * @return  The extension of the file name.
  */
 export function getExtension( filename = '' ): string {
@@ -30,7 +30,7 @@ export function getExtension( filename = '' ): string {
 /**
  * Checks if a file is a video.
  *
- * @param  filename The file name.
+ * @param filename The file name.
  * @return Whether the file is a video.
  */
 export function isVideoType( filename: string = '' ): boolean {
@@ -44,7 +44,7 @@ export function isVideoType( filename: string = '' ): boolean {
 /**
  * Transforms a fraction value to a percentage value.
  *
- * @param  fraction The fraction value.
+ * @param fraction The fraction value.
  * @return A percentage value.
  */
 export function fractionToPercentage( fraction: number ): number {

package/src/font-size-picker/utils.ts

@@ -13,7 +13,7 @@ import { parseQuantityAndUnitFromRawValue } from '../unit-control';
  * Some themes use css vars for their font sizes, so until we
  * have the way of calculating them don't display them.
  *
- * @param  value The value that is checked.
+ * @param value The value that is checked.
  * @return Whether the value is a simple css value.
  */
 export function isSimpleCssValue(
@@ -27,7 +27,7 @@ export function isSimpleCssValue(
  * If all of the given font sizes have the same unit (e.g. 'px'), return that
  * unit. Otherwise return null.
  *
- * @param  fontSizes List of font sizes.
+ * @param fontSizes List of font sizes.
  * @return The common unit, or null.
  */
 export function getCommonSizeUnit( fontSizes: FontSize[] ) {

package/src/gradient-picker/README.md

@@ -101,3 +101,11 @@ Start opting into the new margin-free styles that will become the default in a f
 -   Type: `Boolean`
 -   Required: No
 -   Default: `false`
+
+### headingLevel
+
+The heading level.
+
+-   Type: `1 | 2 | 3 | 4 | 5 | 6 | '1' | '2' | '3' | '4' | '5' | '6'`
+-   Required: No
+-   Default: `2`

package/src/gradient-picker/index.js

@@ -77,13 +77,16 @@ function MultipleOrigin( {
 	onChange,
 	value,
 	actions,
+	headingLevel,
 } ) {
 	return (
 		<VStack spacing={ 3 } className={ className }>
 			{ gradients.map( ( { name, gradients: gradientSet }, index ) => {
 				return (
 					<VStack spacing={ 2 } key={ index }>
-						<ColorHeading>{ name }</ColorHeading>
+						<ColorHeading level={ headingLevel }>
+							{ name }
+						</ColorHeading>
 						<SingleOrigin
 							clearGradient={ clearGradient }
 							gradients={ gradientSet }
@@ -112,6 +115,7 @@ export default function GradientPicker( {
 	clearable = true,
 	disableCustomGradients = false,
 	__experimentalIsRenderedInSidebar,
+	headingLevel = 2,
 } ) {
 	const clearGradient = useCallback(
 		() => onChange( undefined ),
@@ -168,6 +172,7 @@ export default function GradientPicker( {
 								</CircularOptionPicker.ButtonAction>
 							)
 						}
+						headingLevel={ headingLevel }
 					/>
 				) }
 			</VStack>

package/src/input-control/reducer/reducer.ts

@@ -23,7 +23,7 @@ import type { InputChangeCallback } from '../types';
 /**
  * Prepares initialState for the reducer.
  *
- * @param  initialState The initial state.
+ * @param initialState The initial state.
  * @return Prepared initialState for the reducer
  */
 function mergeInitialState(
@@ -45,7 +45,7 @@ function mergeInitialState(
  * exception for CONTROL actions is because they represent controlled updates
  * from props and no case has yet presented for their specialization.
  *
- * @param  composedStateReducers A reducer to specialize state changes.
+ * @param composedStateReducers A reducer to specialize state changes.
  * @return The reducer.
  */
 function inputControlStateReducer(
@@ -140,9 +140,9 @@ function inputControlStateReducer(
  * This technique uses the "stateReducer" design pattern:
  * https://kentcdodds.com/blog/the-state-reducer-pattern/
  *
- * @param  stateReducer    An external state reducer.
- * @param  initialState    The initial state for the reducer.
- * @param  onChangeHandler A handler for the onChange event.
+ * @param stateReducer    An external state reducer.
+ * @param initialState    The initial state for the reducer.
+ * @param onChangeHandler A handler for the onChange event.
  * @return State, dispatch, and a collection of actions.
  */
 export function useInputControlStateReducer(

package/src/input-control/utils.ts

@@ -21,7 +21,7 @@ import type { InputChangeCallback } from './types';
 /**
  * Gets a CSS cursor value based on a drag direction.
  *
- * @param  dragDirection The drag direction.
+ * @param dragDirection The drag direction.
  * @return  The CSS cursor value.
  */
 export function getDragCursor( dragDirection: string ): string {