@wordpress/components 21.3.0 → 22.1.0

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,49 @@ 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.
+
+### `clearable`: `boolean`
+
+Whether the palette should have a clearing button.
+
+-   Required: No
+-   Default: `true`
+
+### `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`
+
+This controls whether the alpha channel will be offered when selecting custom
+colors.
+
+-   Required: No
+-   Default: `false`
+
+### `value`: `string`
+
+Currently active value.
+
+-   Required: No
+
+### `onChange`: `OnColorChange`
+
+Callback called when a color is selected.
+
+-   Required: Yes

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 = false,
+		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;
@@ -25,7 +25,7 @@
 	outline: 1px solid transparent;
 
 	&:focus {
-		box-shadow: inset 0 0 0 var(--wp-admin-border-width-focus) var(--wp-admin-theme-color);
+		box-shadow: inset 0 0 0 var(--wp-admin-border-width-focus) $components-color-accent;
 		// Show a outline in Windows high contrast mode.
 		outline-width: 2px;
 	}

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,97 @@
+/**
+ * External dependencies
+ */
+import type { CSSProperties, MouseEventHandler, ReactNode } from 'react';
+
+/**
+ * Internal dependencies
+ */
+import type { PopoverProps } from '../popover/types';
+
+export type ColorObject = {
+	name: string;
+	color: NonNullable< CSSProperties[ 'color' ] >;
+};
+
+export type PaletteObject = {
+	name: string;
+	colors: ColorObject[];
+};
+
+type PaletteProps = {
+	className?: string;
+	clearColor: () => void;
+	/**
+	 * Callback called when a color is selected.
+	 */
+	onChange: ( newColor?: string ) => void;
+	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?: Omit< PopoverProps, 'children' >;
+	renderToggle: ( props: {
+		isOpen: boolean;
+		onToggle: MouseEventHandler< HTMLButtonElement >;
+	} ) => ReactNode;
+};
+
+export type ColorPaletteProps = Pick< PaletteProps, 'onChange' > & {
+	/**
+	 * 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;
+	/**
+	 * This controls whether the alpha channel will be offered when selecting
+	 * custom colors.
+	 *
+	 * @default false
+	 */
+	enableAlpha?: boolean;
+	/**
+	 * 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

@@ -25,6 +25,18 @@ export const InputWithSlider = ( {
 	onChange,
 	value,
 }: InputWithSliderProps ) => {
+	const onNumberControlChange = ( newValue?: number | string ) => {
+		if ( ! newValue ) {
+			onChange( 0 );
+			return;
+		}
+		if ( typeof newValue === 'string' ) {
+			onChange( parseInt( newValue, 10 ) );
+			return;
+		}
+		onChange( newValue );
+	};
+
 	return (
 		<HStack spacing={ 4 }>
 			<NumberControlWrapper
@@ -33,8 +45,7 @@ export const InputWithSlider = ( {
 				label={ label }
 				hideLabelFromVision
 				value={ value }
-				// @ts-expect-error TODO: Resolve discrepancy in NumberControl
-				onChange={ onChange }
+				onChange={ onNumberControlChange }
 				prefix={
 					<Spacer
 						as={ Text }
@@ -45,7 +56,7 @@ export const InputWithSlider = ( {
 						{ abbreviation }
 					</Spacer>
 				}
-				hideHTMLArrows
+				spinControls="none"
 				size="__unstable-large"
 			/>
 			<RangeControl

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

@@ -1,8 +1,6 @@
 /**
  * External dependencies
  */
-
-import { some } from 'lodash';
 import classnames from 'classnames';
 
 /**
@@ -91,7 +89,7 @@ export default function CustomGradientBar( {
 
 		// If the insert point is close to an existing control point don't show it.
 		if (
-			some( controlPoints, ( { position } ) => {
+			controlPoints.some( ( { position } ) => {
 				return (
 					Math.abs( insertPosition - position ) <
 					MINIMUM_DISTANCE_BETWEEN_INSERTER_AND_POINT