@wordpress/components 21.0.5 → 21.0.7

package/src/autocomplete/index.js

@@ -14,6 +14,15 @@ import {
 	useRef,
 	useMemo,
 } from '@wordpress/element';
+import {
+	ENTER,
+	ESCAPE,
+	UP,
+	DOWN,
+	LEFT,
+	RIGHT,
+	BACKSPACE,
+} from '@wordpress/keycodes';
 import { __, _n, sprintf } from '@wordpress/i18n';
 import {
 	useInstanceId,
@@ -212,7 +221,7 @@ function useAutocomplete( {
 	}
 
 	function handleKeyDown( event ) {
-		backspacing.current = event.code === 'Backspace';
+		backspacing.current = event.keyCode === BACKSPACE;
 
 		if ( ! autocompleter ) {
 			return;
@@ -223,8 +232,8 @@ function useAutocomplete( {
 		if ( event.defaultPrevented ) {
 			return;
 		}
-		switch ( event.code ) {
-			case 'ArrowUp':
+		switch ( event.keyCode ) {
+			case UP:
 				setSelectedIndex(
 					( selectedIndex === 0
 						? filteredOptions.length
@@ -232,24 +241,24 @@ function useAutocomplete( {
 				);
 				break;
 
-			case 'ArrowDown':
+			case DOWN:
 				setSelectedIndex(
 					( selectedIndex + 1 ) % filteredOptions.length
 				);
 				break;
 
-			case 'Escape':
+			case ESCAPE:
 				setAutocompleter( null );
 				setAutocompleterUI( null );
 				event.preventDefault();
 				break;
 
-			case 'Enter':
+			case ENTER:
 				select( filteredOptions[ selectedIndex ] );
 				break;
 
-			case 'ArrowLeft':
-			case 'ArrowRight':
+			case LEFT:
+			case RIGHT:
 				reset();
 				return;
 
@@ -257,7 +266,7 @@ function useAutocomplete( {
 				return;
 		}
 
-		// Any handled key should prevent original behavior. This relies on
+		// Any handled keycode should prevent original behavior. This relies on
 		// the early return in the default case.
 		event.preventDefault();
 	}

package/src/border-control/types.ts

@@ -16,7 +16,7 @@ export type Border = {
 
 export type Color = {
 	name: string;
-	color: CSSProperties[ 'color' ];
+	color: NonNullable< CSSProperties[ 'color' ] >;
 };
 
 export type ColorOrigin = {

package/src/circular-option-picker/index.js

@@ -16,13 +16,14 @@ import Button from '../button';
 import Dropdown from '../dropdown';
 import Tooltip from '../tooltip';
 
-function Option( {
-	className,
-	isSelected,
-	selectedIconProps,
-	tooltipText,
-	...additionalProps
-} ) {
+function Option( props ) {
+	const {
+		className,
+		isSelected,
+		selectedIconProps,
+		tooltipText,
+		...additionalProps
+	} = props;
 	const optionButton = (
 		<Button
 			isPressed={ isSelected }
@@ -52,12 +53,8 @@ function Option( {
 	);
 }
 
-function DropdownLinkAction( {
-	buttonProps,
-	className,
-	dropdownProps,
-	linkText,
-} ) {
+function DropdownLinkAction( props ) {
+	const { buttonProps, className, dropdownProps, linkText } = props;
 	return (
 		<Dropdown
 			className={ classnames(
@@ -80,7 +77,8 @@ function DropdownLinkAction( {
 	);
 }
 
-function ButtonAction( { className, children, ...additionalProps } ) {
+function ButtonAction( props ) {
+	const { className, children, ...additionalProps } = props;
 	return (
 		<Button
 			className={ classnames(
@@ -95,12 +93,8 @@ function ButtonAction( { className, children, ...additionalProps } ) {
 	);
 }
 
-export default function CircularOptionPicker( {
-	actions,
-	className,
-	options,
-	children,
-} ) {
+export default function CircularOptionPicker( props ) {
+	const { actions, className, options, children } = props;
 	return (
 		<div
 			className={ classnames(

package/src/color-palette/README.md

@@ -1,54 +1,6 @@
 # ColorPalette
 
-## Props
-
-The component accepts the following props.
-
-{ colors, disableCustomColors = false, value, onChange, className, clearable = true }
-
-### colors
-
-Array with the colors to be shown.
-
--   Type: `Array`
--   Required: Yes
-
-### disableCustomColors
-
-Whether to allow custom color or not.
-
--   Type: `Boolean`
--   Required: No
--   Default: false
-
-### value
-
-currently active value
-
--   Type: `String`
--   Required: No
-
-### onChange
-
-Callback called when a color is selected.
-
--   Type: `Function`
--   Required: Yes
-
-### className
-
-classes to be applied to the container.
-
--   Type: `String`
--   Required: No
-
-### clearable
-
-Whether the palette should have a clearing button or not.
-
--   Type: `Boolean`
--   Required: No
--   Default: true
+`ColorPalette` allows the user to pick a color from a list of pre-defined color entries.
 
 ## Usage
 
@@ -79,3 +31,53 @@ If you're using this component outside the editor, you can
 for the `ColorPalette`'s color swatches, by rendering your `ColorPalette` with a
 `Popover.Slot` further up the element tree and within a
 `SlotFillProvider` overall.
+
+## Props
+
+The component accepts the following props.
+
+### `colors`: `( PaletteObject | ColorObject )[]`
+
+Array with the colors to be shown. When displaying multiple color palettes to choose from, the format of the array changes from an array of colors objects, to an array of color palettes.
+
+-   Required: No
+-   Default: `[]`
+
+### `disableCustomColors`: `boolean`
+
+Whether to allow the user to pick a custom color on top of the predefined choices (defined via the `colors` prop).
+
+-   Required: No
+-   Default: `false`
+
+### `enableAlpha`: `boolean`
+
+Whether the color picker should display the alpha channel both in the bottom inputs as well as in the color picker itself.
+
+-   Required: No
+-   Default: `false`
+
+### `value`: `string`
+
+currently active value
+
+-   Required: No
+
+### `onChange`: `OnColorChange`
+
+Callback called when a color is selected.
+
+-   Required: Yes
+
+### `className`: `string`
+
+classes to be applied to the container.
+
+-   Required: No
+
+### `clearable`: `boolean`
+
+Whether the palette should have a clearing button.
+
+-   Required: No
+-   Default: `true`

package/src/color-palette/{index.js → index.tsx}

@@ -1,7 +1,7 @@
-// @ts-nocheck
 /**
  * External dependencies
  */
+import type { ForwardedRef } from 'react';
 import { colord, extend } from 'colord';
 import namesPlugin from 'colord/plugins/names';
 import a11yPlugin from 'colord/plugins/a11y';
@@ -10,7 +10,7 @@ import a11yPlugin from 'colord/plugins/a11y';
  * WordPress dependencies
  */
 import { __, sprintf } from '@wordpress/i18n';
-import { useCallback, useMemo } from '@wordpress/element';
+import { useCallback, useMemo, forwardRef } from '@wordpress/element';
 
 /**
  * Internal dependencies
@@ -23,6 +23,15 @@ import { Flex, FlexItem } from '../flex';
 import { Truncate } from '../truncate';
 import { ColorHeading } from './styles';
 import DropdownContentWrapper from '../dropdown/dropdown-content-wrapper';
+import type {
+	ColorObject,
+	ColorPaletteProps,
+	CustomColorPickerDropdownProps,
+	MultiplePalettesProps,
+	PaletteObject,
+	SinglePaletteProps,
+} from './types';
+import type { WordPressComponentProps } from '../ui/context';
 
 extend( [ namesPlugin, a11yPlugin ] );
 
@@ -33,7 +42,7 @@ function SinglePalette( {
 	onChange,
 	value,
 	actions,
-} ) {
+}: SinglePaletteProps ) {
 	const colorOptions = useMemo( () => {
 		return colors.map( ( { color, name }, index ) => {
 			const colordColor = colord( color );
@@ -74,6 +83,11 @@ function SinglePalette( {
 			);
 		} );
 	}, [ colors, value, onChange, clearColor ] );
+
+	if ( colors.length === 0 ) {
+		return null;
+	}
+
 	return (
 		<CircularOptionPicker
 			className={ className }
@@ -90,7 +104,11 @@ function MultiplePalettes( {
 	onChange,
 	value,
 	actions,
-} ) {
+}: MultiplePalettesProps ) {
+	if ( colors.length === 0 ) {
+		return null;
+	}
+
 	return (
 		<VStack spacing={ 3 } className={ className }>
 			{ colors.map( ( { name, colors: colorPalette }, index ) => {
@@ -117,7 +135,7 @@ export function CustomColorPickerDropdown( {
 	isRenderedInSidebar,
 	popoverProps: receivedPopoverProps,
 	...props
-} ) {
+}: CustomColorPickerDropdownProps ) {
 	const popoverProps = useMemo(
 		() => ( {
 			shift: true,
@@ -148,9 +166,9 @@ export function CustomColorPickerDropdown( {
 }
 
 export const extractColorNameFromCurrentValue = (
-	currentValue,
-	colors = [],
-	showMultiplePalettes = false
+	currentValue?: ColorPaletteProps[ 'value' ],
+	colors: ColorPaletteProps[ 'colors' ] = [],
+	showMultiplePalettes: ColorPaletteProps[ '__experimentalHasMultipleOrigins' ] = false
 ) => {
 	if ( ! currentValue ) {
 		return '';
@@ -162,7 +180,10 @@ export const extractColorNameFromCurrentValue = (
 		: colord( currentValue ).toHex();
 
 	// Normalize format of `colors` to simplify the following loop
-	const colorPalettes = showMultiplePalettes ? colors : [ { colors } ];
+	type normalizedPaletteObject = { colors: ColorObject[] };
+	const colorPalettes: normalizedPaletteObject[] = showMultiplePalettes
+		? ( colors as PaletteObject[] )
+		: [ { colors: colors as ColorObject[] } ];
 	for ( const { colors: paletteColors } of colorPalettes ) {
 		for ( const { name: colorName, color: colorValue } of paletteColors ) {
 			const normalizedColorValue = currentValueIsCssVariable
@@ -179,28 +200,62 @@ export const extractColorNameFromCurrentValue = (
 	return __( 'Custom' );
 };
 
-export const showTransparentBackground = ( currentValue ) => {
+export const showTransparentBackground = ( currentValue?: string ) => {
 	if ( typeof currentValue === 'undefined' ) {
 		return true;
 	}
 	return colord( currentValue ).alpha() === 0;
 };
 
-export default function ColorPalette( {
-	clearable = true,
-	className,
-	colors,
-	disableCustomColors = false,
-	enableAlpha,
-	onChange,
-	value,
-	__experimentalHasMultipleOrigins = false,
-	__experimentalIsRenderedInSidebar = false,
-} ) {
+const areColorsMultiplePalette = (
+	colors: NonNullable< ColorPaletteProps[ 'colors' ] >
+): colors is PaletteObject[] => {
+	return colors.every( ( colorObj ) =>
+		Array.isArray( ( colorObj as PaletteObject ).colors )
+	);
+};
+
+function UnforwardedColorPalette(
+	props: WordPressComponentProps< ColorPaletteProps, 'div' >,
+	forwardedRef: ForwardedRef< any >
+) {
+	const {
+		clearable = true,
+		colors = [],
+		disableCustomColors = false,
+		enableAlpha,
+		onChange,
+		value,
+		__experimentalHasMultipleOrigins = false,
+		__experimentalIsRenderedInSidebar = false,
+		...otherProps
+	} = props;
 	const clearColor = useCallback( () => onChange( undefined ), [ onChange ] );
-	const showMultiplePalettes =
-		__experimentalHasMultipleOrigins && colors?.length;
-	const Component = showMultiplePalettes ? MultiplePalettes : SinglePalette;
+
+	const buttonLabelName = useMemo(
+		() =>
+			extractColorNameFromCurrentValue(
+				value,
+				colors,
+				__experimentalHasMultipleOrigins
+			),
+		[ value, colors, __experimentalHasMultipleOrigins ]
+	);
+
+	// Make sure that the `colors` array has a format (single/multiple) that is
+	// compatible with the `__experimentalHasMultipleOrigins` flag. This is true
+	// when __experimentalHasMultipleOrigins and areColorsMultiplePalette() are
+	// either both `true` or both `false`.
+	if (
+		colors.length > 0 &&
+		__experimentalHasMultipleOrigins !== areColorsMultiplePalette( colors )
+	) {
+		// eslint-disable-next-line no-console
+		console.warn(
+			'wp.components.ColorPalette: please specify a format for the `colors` prop that is compatible with the `__experimentalHasMultipleOrigins` prop.'
+		);
+		return null;
+	}
 
 	const renderCustomColorPicker = () => (
 		<DropdownContentWrapper paddingSize="none">
@@ -212,20 +267,11 @@ export default function ColorPalette( {
 		</DropdownContentWrapper>
 	);
 
-	const colordColor = colord( value );
+	const colordColor = colord( value ?? '' );
 
 	const valueWithoutLeadingHash = value?.startsWith( '#' )
 		? value.substring( 1 )
 		: value ?? '';
-	const buttonLabelName = useMemo(
-		() =>
-			extractColorNameFromCurrentValue(
-				value,
-				colors,
-				showMultiplePalettes
-			),
-		[ value, colors, showMultiplePalettes ]
-	);
 
 	const customColorAccessibleLabel = !! valueWithoutLeadingHash
 		? sprintf(
@@ -238,8 +284,20 @@ export default function ColorPalette( {
 		  )
 		: __( 'Custom color picker.' );
 
+	const paletteCommonProps = {
+		clearable,
+		clearColor,
+		onChange,
+		value,
+		actions: !! clearable && (
+			<CircularOptionPicker.ButtonAction onClick={ clearColor }>
+				{ __( 'Clear' ) }
+			</CircularOptionPicker.ButtonAction>
+		),
+	};
+
 	return (
-		<VStack spacing={ 3 } className={ className }>
+		<VStack spacing={ 3 } ref={ forwardedRef } { ...otherProps }>
 			{ ! disableCustomColors && (
 				<CustomColorPickerDropdown
 					isRenderedInSidebar={ __experimentalIsRenderedInSidebar }
@@ -284,22 +342,45 @@ export default function ColorPalette( {
 					) }
 				/>
 			) }
-			<Component
-				clearable={ clearable }
-				clearColor={ clearColor }
-				colors={ colors }
-				onChange={ onChange }
-				value={ value }
-				actions={
-					!! clearable && (
-						<CircularOptionPicker.ButtonAction
-							onClick={ clearColor }
-						>
-							{ __( 'Clear' ) }
-						</CircularOptionPicker.ButtonAction>
-					)
-				}
-			/>
+			{ __experimentalHasMultipleOrigins ? (
+				<MultiplePalettes
+					{ ...paletteCommonProps }
+					colors={ colors as PaletteObject[] }
+				/>
+			) : (
+				<SinglePalette
+					{ ...paletteCommonProps }
+					colors={ colors as ColorObject[] }
+				/>
+			) }
 		</VStack>
 	);
 }
+
+/**
+ * Allows the user to pick a color from a list of pre-defined color entries.
+ *
+ * ```jsx
+ * import { ColorPalette } from '@wordpress/components';
+ * import { useState } from '@wordpress/element';
+ *
+ * const MyColorPalette = () => {
+ *   const [ color, setColor ] = useState ( '#f00' )
+ *   const colors = [
+ *     { name: 'red', color: '#f00' },
+ *     { name: 'white', color: '#fff' },
+ *     { name: 'blue', color: '#00f' },
+ *   ];
+ *   return (
+ *     <ColorPalette
+ *       colors={ colors }
+ *       value={ color }
+ *       onChange={ ( color ) => setColor( color ) }
+ *     />
+ *   );
+ * } );
+ * ```
+ */
+export const ColorPalette = forwardRef( UnforwardedColorPalette );
+
+export default ColorPalette;

package/src/color-palette/stories/{index.js → index.tsx}

@@ -1,3 +1,9 @@
+/**
+ * External dependencies
+ */
+import type { CSSProperties } from 'react';
+import type { ComponentMeta, ComponentStory } from '@storybook/react';
+
 /**
  * WordPress dependencies
  */
@@ -6,34 +12,25 @@ import { useState } from '@wordpress/element';
 /**
  * Internal dependencies
  */
-import ColorPalette from '../';
+import ColorPalette from '..';
 import Popover from '../../popover';
 import { Provider as SlotFillProvider } from '../../slot-fill';
+import type { ColorObject, PaletteObject } from '../types';
 
-const meta = {
+const meta: ComponentMeta< typeof ColorPalette > = {
 	title: 'Components/ColorPalette',
 	component: ColorPalette,
 	argTypes: {
+		// Removing the control because setting this prop without changing the
+		// format of the `colors` prop can break the component.
 		__experimentalHasMultipleOrigins: {
 			control: {
 				type: null,
 			},
 		},
-		__experimentalIsRenderedInSidebar: {
-			control: {
-				type: 'boolean',
-			},
-		},
-		clearable: {
-			control: {
-				type: 'boolean',
-			},
-		},
-		disableCustomColors: {
-			control: {
-				type: 'boolean',
-			},
-		},
+		as: { control: { type: null } },
+		onChange: { action: 'onChange', control: { type: null } },
+		value: { control: { type: null } },
 	},
 	parameters: {
 		controls: { expanded: true },
@@ -42,14 +39,26 @@ const meta = {
 };
 export default meta;
 
-const Template = ( args ) => {
+const Template: ComponentStory< typeof ColorPalette > = ( {
+	onChange,
+	...args
+} ) => {
 	const firstColor =
-		args.colors[ 0 ].color || args.colors[ 0 ].colors[ 0 ].color;
-	const [ color, setColor ] = useState( firstColor );
+		( args.colors as ColorObject[] )[ 0 ].color ||
+		( args.colors as PaletteObject[] )[ 0 ].colors[ 0 ].color;
+	const [ color, setColor ] = useState< string | undefined >( firstColor );
 
 	return (
 		<SlotFillProvider>
-			<ColorPalette { ...args } value={ color } onChange={ setColor } />
+			<ColorPalette
+				{ ...args }
+				value={ color }
+				onChange={ ( newColor ) => {
+					setColor( newColor );
+					onChange?.( newColor );
+				} }
+			/>
+			{ /* @ts-expect-error The 'Slot' component hasn't been typed yet. */ }
 			<Popover.Slot />
 		</SlotFillProvider>
 	);
@@ -92,14 +101,16 @@ MultipleOrigins.args = {
 	],
 };
 
-export const CSSVariables = ( args ) => {
+export const CSSVariables: ComponentStory< typeof ColorPalette > = ( args ) => {
 	return (
 		<div
-			style={ {
-				'--red': '#f00',
-				'--yellow': '#ff0',
-				'--blue': '#00f',
-			} }
+			style={
+				{
+					'--red': '#f00',
+					'--yellow': '#ff0',
+					'--blue': '#00f',
+				} as CSSProperties
+			}
 		>
 			<Template { ...args } />
 		</div>