@wordpress/components 21.3.0 → 22.0.0

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>

package/src/color-palette/style.scss

@@ -14,9 +14,9 @@
 	background-image:
 		repeating-linear-gradient(45deg, $gray-200 25%, transparent 25%, transparent 75%, $gray-200 75%, $gray-200),
 		repeating-linear-gradient(45deg, $gray-200 25%, transparent 25%, transparent 75%, $gray-200 75%, $gray-200);
-	background-position: 0 0, 25px 25px;
+	background-position: 0 0, 24px 24px;
 	/*rtl:end:ignore*/
-	background-size: calc(2 * 25px) calc(2 * 25px);
+	background-size: calc(2 * 24px) calc(2 * 24px);
 	box-sizing: border-box;
 	color: $white;
 	cursor: pointer;

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

@@ -7,7 +7,7 @@ import userEvent from '@testing-library/user-event';
 /**
  * Internal dependencies
  */
-import ColorPalette from '../';
+import ColorPalette from '..';
 
 describe( 'ColorPalette', () => {
 	const colors = [

package/src/color-palette/types.ts

@@ -0,0 +1,93 @@
+/**
+ * External dependencies
+ */
+import type { CSSProperties, MouseEventHandler, ReactNode } from 'react';
+
+type OnColorChange = ( newColor?: string ) => void;
+
+export type ColorObject = {
+	name: string;
+	color: NonNullable< CSSProperties[ 'color' ] >;
+};
+
+export type PaletteObject = {
+	name: string;
+	colors: ColorObject[];
+};
+
+type PaletteProps = {
+	className?: string;
+	clearColor: () => void;
+	onChange: OnColorChange;
+	value?: string;
+	actions?: ReactNode;
+};
+
+export type SinglePaletteProps = PaletteProps & {
+	colors: ColorObject[];
+};
+
+export type MultiplePalettesProps = PaletteProps & {
+	colors: PaletteObject[];
+};
+
+// TODO: should extend `Dropdown`'s props once it gets refactored to TypeScript
+export type CustomColorPickerDropdownProps = {
+	isRenderedInSidebar: boolean;
+	renderContent: () => ReactNode;
+	popoverProps?: string[];
+	renderToggle: ( props: {
+		isOpen: boolean;
+		onToggle: MouseEventHandler< HTMLButtonElement >;
+	} ) => ReactNode;
+};
+
+export type ColorPaletteProps = {
+	/**
+	 * Whether the palette should have a clearing button.
+	 *
+	 * @default true
+	 */
+	clearable?: boolean;
+	/**
+	 * 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.
+	 *
+	 * @default []
+	 */
+	colors?: ( PaletteObject | ColorObject )[];
+	/**
+	 * Whether to allow the user to pick a custom color on top of the predefined
+	 * choices (defined via the `colors` prop).
+	 *
+	 * @default false
+	 */
+	disableCustomColors?: boolean;
+	/**
+	 * Whether the color picker should display the alpha channel
+	 * both in the bottom inputs as well as in the color picker itself.
+	 */
+	enableAlpha?: boolean;
+	/**
+	 * Callback called when a color is selected.
+	 */
+	onChange: OnColorChange;
+	/**
+	 * Currently active value.
+	 */
+	value?: string;
+	/**
+	 * Whether the colors prop is an array of color palettes,
+	 * rather than an array of color objects.
+	 *
+	 * @default false
+	 */
+	__experimentalHasMultipleOrigins?: boolean;
+	/**
+	 * Whether this is rendered in the sidebar.
+	 *
+	 * @default false
+	 */
+	__experimentalIsRenderedInSidebar?: boolean;
+};

package/src/color-picker/input-with-slider.tsx

@@ -45,7 +45,7 @@ export const InputWithSlider = ( {
 						{ abbreviation }
 					</Spacer>
 				}
-				hideHTMLArrows
+				spinControls="none"
 				size="__unstable-large"
 			/>
 			<RangeControl