@wordpress/components 23.3.5 → 23.5.0

package/src/circular-option-picker/stories/index.tsx

@@ -0,0 +1,134 @@
+/**
+ * External dependencies
+ */
+import type { ComponentMeta, ComponentStory } from '@storybook/react';
+/**
+ * WordPress dependencies
+ */
+import { useState, createContext, useContext } from '@wordpress/element';
+/**
+ * Internal dependencies
+ */
+import {
+	default as CircularOptionPicker,
+	ButtonAction,
+	DropdownLinkAction,
+	Option,
+} from '..';
+
+const CircularOptionPickerStoryContext = createContext< {
+	currentColor?: string;
+	setCurrentColor?: ( v: string | undefined ) => void;
+} >( {} );
+
+const meta: ComponentMeta< typeof CircularOptionPicker > = {
+	title: 'Components/CircularOptionPicker',
+	component: CircularOptionPicker,
+	subcomponents: {
+		'CircularOptionPicker.Option': Option,
+		'CircularOptionPicker.ButtonAction': ButtonAction,
+		'CircularOptionPicker.DropdownLinkAction': DropdownLinkAction,
+	},
+	argTypes: {
+		actions: { control: { type: null } },
+		options: { control: { type: null } },
+		children: { control: { type: 'text' } },
+	},
+	parameters: {
+		actions: { argTypesRegex: '^on.*' },
+		controls: { expanded: true },
+		docs: { source: { state: 'open', excludeDecorators: true } },
+	},
+	decorators: [
+		// Share current color state between main component, `actions` and `options`
+		( Story ) => {
+			const [ currentColor, setCurrentColor ] = useState< string >();
+
+			return (
+				<CircularOptionPickerStoryContext.Provider
+					value={ {
+						currentColor,
+						setCurrentColor,
+					} }
+				>
+					<Story />
+				</CircularOptionPickerStoryContext.Provider>
+			);
+		},
+	],
+};
+export default meta;
+
+const colors = [
+	{ color: '#f00', name: 'Red' },
+	{ color: '#0f0', name: 'Green' },
+	{ color: '#0af', name: 'Blue' },
+];
+
+const DefaultOptions = () => {
+	const { currentColor, setCurrentColor } = useContext(
+		CircularOptionPickerStoryContext
+	);
+
+	return (
+		<>
+			{ colors.map( ( { color, name }, index ) => {
+				return (
+					<CircularOptionPicker.Option
+						key={ `${ color }-${ index }` }
+						tooltipText={ name }
+						style={ { backgroundColor: color, color } }
+						isSelected={ color === currentColor }
+						onClick={ () => {
+							setCurrentColor?.( color );
+						} }
+						aria-label={ name }
+					/>
+				);
+			} ) }
+		</>
+	);
+};
+
+const DefaultActions = () => {
+	const { setCurrentColor } = useContext( CircularOptionPickerStoryContext );
+
+	return (
+		<CircularOptionPicker.ButtonAction
+			onClick={ () => setCurrentColor?.( undefined ) }
+		>
+			{ 'Clear' }
+		</CircularOptionPicker.ButtonAction>
+	);
+};
+
+const Template: ComponentStory< typeof CircularOptionPicker > = ( props ) => (
+	<CircularOptionPicker { ...props } />
+);
+
+export const Default = Template.bind( {} );
+Default.args = { options: <DefaultOptions /> };
+
+export const WithButtonAction = Template.bind( {} );
+WithButtonAction.args = {
+	...Default.args,
+	actions: <DefaultActions />,
+};
+WithButtonAction.storyName = 'With ButtonAction';
+
+export const WithDropdownLinkAction = Template.bind( {} );
+WithDropdownLinkAction.args = {
+	...Default.args,
+	actions: (
+		<CircularOptionPicker.DropdownLinkAction
+			dropdownProps={ {
+				popoverProps: { position: 'top right' },
+				renderContent: () => (
+					<div>This is an example of a DropdownLinkAction.</div>
+				),
+			} }
+			linkText="Learn More"
+		></CircularOptionPicker.DropdownLinkAction>
+	),
+};
+WithDropdownLinkAction.storyName = 'With DropdownLinkAction';

package/src/circular-option-picker/types.ts

@@ -0,0 +1,69 @@
+/**
+ * External dependencies
+ */
+import type { ReactNode } from 'react';
+
+/**
+ * WordPress dependencies
+ */
+import type { Icon } from '@wordpress/icons';
+
+/**
+ * Internal dependencies
+ */
+import type { ButtonAsButtonProps } from '../button/types';
+import type Dropdown from '../dropdown';
+import type { WordPressComponentProps } from '../ui/context';
+
+export type CircularOptionPickerProps = {
+	/**
+	 * A CSS class to apply to the wrapper element.
+	 */
+	className?: string;
+	/**
+	 * The action(s) to be rendered after the options,
+	 * such as a 'clear' button as seen in `ColorPalette`.
+	 * Usually a `CircularOptionPicker.ButtonAction` or
+	 * `CircularOptionPicker.DropdownLinkAction` component.
+	 */
+	actions?: ReactNode;
+	/**
+	 * The options to be rendered, such as color swatches.
+	 * Usually a `CircularOptionPicker.Option` component.
+	 */
+	options: ReactNode;
+	/**
+	 * The child elements.
+	 */
+	children?: ReactNode;
+};
+
+export type DropdownLinkActionProps = {
+	buttonProps?: Omit<
+		WordPressComponentProps< ButtonAsButtonProps, 'button', false >,
+		'children'
+	>;
+	linkText: string;
+	dropdownProps: Omit<
+		React.ComponentProps< typeof Dropdown >,
+		'className' | 'renderToggle'
+	>;
+	className?: string;
+};
+
+export type OptionProps = Omit<
+	WordPressComponentProps< ButtonAsButtonProps, 'button', false >,
+	'isPressed' | 'className'
+> & {
+	className?: string;
+	tooltipText?: string;
+	isSelected: boolean;
+	// `icon` is explicitly defined as 'check' by CircleOptionPicker.Option
+	// and is not intended to be overridden.
+	// `size` relies on the `Icon` component's default size of `24` to fit
+	// `CircularOptionPicker`'s design, and should not be explicitly set.
+	selectedIconProps?: Omit<
+		React.ComponentProps< typeof Icon >,
+		'icon' | 'size'
+	>;
+};

package/src/color-palette/README.md

@@ -66,6 +66,13 @@ colors.
 -   Required: No
 -   Default: `false`
 
+### `headingLevel`: `1 | 2 | 3 | 4 | 5 | 6 | '1' | '2' | '3' | '4' | '5' | '6'`
+
+The heading level.
+
+-   Required: No
+-   Default: `2`
+
 ### `value`: `string`
 
 Currently active value.

package/src/color-palette/index.tsx

@@ -107,6 +107,7 @@ function MultiplePalettes( {
 	onChange,
 	value,
 	actions,
+	headingLevel,
 }: MultiplePalettesProps ) {
 	if ( colors.length === 0 ) {
 		return null;
@@ -117,7 +118,9 @@ function MultiplePalettes( {
 			{ colors.map( ( { name, colors: colorPalette }, index ) => {
 				return (
 					<VStack spacing={ 2 } key={ index }>
-						<ColorHeading>{ name }</ColorHeading>
+						<ColorHeading level={ headingLevel }>
+							{ name }
+						</ColorHeading>
 						<SinglePalette
 							clearColor={ clearColor }
 							colors={ colorPalette }
@@ -182,6 +185,7 @@ function UnforwardedColorPalette(
 		onChange,
 		value,
 		__experimentalIsRenderedInSidebar = false,
+		headingLevel = 2,
 		...otherProps
 	} = props;
 	const [ normalizedColorValue, setNormalizedColorValue ] = useState( value );
@@ -243,6 +247,7 @@ function UnforwardedColorPalette(
 				{ __( 'Clear' ) }
 			</CircularOptionPicker.ButtonAction>
 		),
+		headingLevel,
 	};
 
 	return (

package/src/color-palette/test/__snapshots__/index.tsx.snap

@@ -179,7 +179,7 @@ exports[`ColorPalette should render a dynamic toolbar of colors 1`] = `
       <button
         aria-expanded="false"
         aria-haspopup="true"
-        aria-label="Custom color picker. The currently selected color is called \\"red\\" and has a value of \\"f00\\"."
+        aria-label="Custom color picker. The currently selected color is called "red" and has a value of "f00"."
         class="components-flex components-color-palette__custom-color emotion-2 emotion-1"
         data-wp-c16t="true"
         data-wp-component="Flex"

package/src/color-palette/types.ts

@@ -7,6 +7,7 @@ import type { CSSProperties, ReactNode } from 'react';
  * Internal dependencies
  */
 import type { DropdownProps } from '../dropdown/types';
+import type { HeadingSize } from '../heading/types';
 
 export type ColorObject = {
 	name: string;
@@ -27,6 +28,7 @@ type PaletteProps = {
 	onChange: ( newColor?: string, index?: number ) => void;
 	value?: string;
 	actions?: ReactNode;
+	headingLevel?: HeadingSize;
 };
 
 export type SinglePaletteProps = PaletteProps & {
@@ -70,6 +72,12 @@ export type ColorPaletteProps = Pick< PaletteProps, 'onChange' > & {
 	 * @default false
 	 */
 	enableAlpha?: boolean;
+	/**
+	 * The heading level.
+	 *
+	 * @default 2
+	 */
+	headingLevel?: HeadingSize;
 	/**
 	 * Currently active value.
 	 */

package/src/combobox-control/README.md

@@ -17,9 +17,6 @@ These are the same as [the ones for `SelectControl`s](/packages/components/src/s
 ### Usage
 
 ```jsx
-/**
- * WordPress dependencies
- */
 import { ComboboxControl } from '@wordpress/components';
 import { useState } from '@wordpress/element';
 
@@ -36,10 +33,6 @@ const options = [
 		value: 'large',
 		label: 'Large',
 	},
-	{
-		value: 'huge',
-		label: 'Huge',
-	},
 ];
 
 function MyComboboxControl() {
@@ -92,35 +85,35 @@ If this property is added, a help text will be generated using help property as
 
 The options that can be chosen from.
 
--   Type: `Array<{ value: String, label: String }>`
+-   Type: `Array<{ value: string, label: string }>`
 -   Required: Yes
 
 #### onFilterValueChange
 
-Function called with the control's search input value changes. The argument contains the next input value.
+Function called when the control's search input value changes. The argument contains the next input value.
 
--   Type: `Function`
+-   Type: `( value: string ) => void`
 -   Required: No
 
 #### onChange
 
 Function called with the selected value changes.
 
--   Type: `Function`
+-   Type: `( value: string | null | undefined ) => void`
 -   Required: No
 
 #### value
 
-The current value of the input.
+The current value of the control.
 
--   Type: `mixed`
--   Required: Yes
+-   Type: `string | null`
+-   Required: No
 
 #### __experimentalRenderItem
 
 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).
 
--   Type: `Function` - `( args: { item: object } ) => ReactNode`
+-   Type: `( args: { item: object } ) => ReactNode`
 -   Required: No
 
 ## Related components

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