@wordpress/components 23.1.0 → 23.3.0

package/src/button/types.ts

@@ -0,0 +1,138 @@
+/**
+ * External dependencies
+ */
+import type { ReactNode } from 'react';
+
+/**
+ * Internal dependencies
+ */
+import type { Props as IconProps } from '../icon';
+import type { PopoverProps } from '../popover/types';
+import type { WordPressComponentProps } from '../ui/context/wordpress-component';
+
+export type ButtonProps =
+	| WordPressComponentProps< BaseButtonProps & _ButtonProps, 'button', false >
+	| WordPressComponentProps< BaseButtonProps & AnchorProps, 'a', false >;
+
+type BaseButtonProps = {
+	/**
+	 * The button's children.
+	 */
+	children?: ReactNode;
+	/**
+	 * An accessible description for the button.
+	 */
+	describedBy?: string;
+	/**
+	 * Whether the button is focused.
+	 */
+	focus?: boolean;
+	/**
+	 * If provided, renders an Icon component inside the button.
+	 */
+	icon?: IconProps< unknown >[ 'icon' ];
+	/**
+	 * If provided with `icon`, sets the position of icon relative to the `text`.
+	 *
+	 * @default 'left'
+	 */
+	iconPosition?: 'left' | 'right';
+	/**
+	 * If provided with `icon`, sets the icon size.
+	 * Please refer to the Icon component for more details regarding
+	 * the default value of its `size` prop.
+	 */
+	iconSize?: IconProps< unknown >[ 'size' ];
+	/**
+	 * Indicates activity while a action is being performed.
+	 */
+	isBusy?: boolean;
+	/**
+	 * Renders a red text-based button style to indicate destructive behavior.
+	 */
+	isDestructive?: boolean;
+	/**
+	 * Renders a pressed button style.
+	 */
+	isPressed?: boolean;
+	/**
+	 * Decreases the size of the button.
+	 */
+	isSmall?: boolean;
+	/**
+	 * Sets the `aria-label` of the component, if none is provided.
+	 * Sets the Tooltip content if `showTooltip` is provided.
+	 */
+	label?: string;
+	/**
+	 * If provided with `showTooltip`, appends the Shortcut label to the tooltip content.
+	 * If an object is provided, it should contain `display` and `ariaLabel` keys.
+	 */
+	shortcut?: string | { display: string; ariaLabel: string };
+	/**
+	 * If provided, renders a Tooltip component for the button.
+	 */
+	showTooltip?: boolean;
+	/**
+	 * If provided, displays the given text inside the button. If the button contains children elements, the text is displayed before them.
+	 */
+	text?: string;
+	/**
+	 * If provided with `showTooltip`, sets the position of the tooltip.
+	 * Please refer to the Tooltip component for more details regarding the defaults.
+	 */
+	tooltipPosition?: PopoverProps[ 'position' ];
+	/**
+	 * Specifies the button's style.
+	 * The accepted values are:
+	 * 'primary' (the primary button styles)
+	 * 'secondary' (the default button styles)
+	 * 'tertiary' (the text-based button styles)
+	 * 'link' (the link button styles)
+	 */
+	variant?: 'primary' | 'secondary' | 'tertiary' | 'link';
+	/**
+	 * Whether this is focusable.
+	 */
+	__experimentalIsFocusable?: boolean;
+};
+
+type _ButtonProps = {
+	/**
+	 * Whether the button is disabled.
+	 * If `true`, this will force a `button` element to be rendered.
+	 */
+	disabled?: boolean;
+};
+
+type AnchorProps = {
+	/**
+	 * Whether the button is disabled.
+	 * If `true`, this will force a `button` element to be rendered.
+	 */
+	disabled?: false;
+	/**
+	 * If provided, renders `a` instead of `button`.
+	 */
+	href: string;
+	/**
+	 * If provided with `href`, sets the `target` attribute to the `a`.
+	 */
+	target?: string;
+};
+
+export type DeprecatedButtonProps = {
+	isDefault?: boolean;
+	isLink?: boolean;
+	isPrimary?: boolean;
+	isSecondary?: boolean;
+	isTertiary?: boolean;
+};
+
+export type DeprecatedIconButtonProps = {
+	labelPosition: ButtonProps[ 'tooltipPosition' ];
+	showTooltip?: boolean;
+	size: ButtonProps[ 'iconSize' ];
+	label: ButtonProps[ 'label' ];
+	tooltip: ButtonProps[ 'label' ];
+};

package/src/checkbox-control/test/index.tsx

@@ -15,8 +15,6 @@ import { useState } from '@wordpress/element';
 import BaseCheckboxControl from '..';
 import type { CheckboxControlProps } from '../types';
 
-jest.useFakeTimers();
-
 const noop = () => {};
 
 const getInput = () => screen.getByRole( 'checkbox' ) as HTMLInputElement;
@@ -85,9 +83,7 @@ describe( 'CheckboxControl', () => {
 
 	describe( 'Value', () => {
 		it( 'should flip the checked property when clicked', async () => {
-			const user = userEvent.setup( {
-				advanceTimers: jest.advanceTimersByTime,
-			} );
+			const user = userEvent.setup();
 
 			let state = false;
 			const setState = jest.fn(

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

@@ -12,6 +12,7 @@ import ColorPalette from '../color-palette';
 import ColorIndicator from '../color-indicator';
 import Icon from '../icon';
 import { HStack } from '../h-stack';
+import type { ColorListPickerProps, ColorOptionProps } from './types';
 
 function ColorOption( {
 	label,
@@ -20,7 +21,7 @@ function ColorOption( {
 	disableCustomColors,
 	enableAlpha,
 	onChange,
-} ) {
+}: ColorOptionProps ) {
 	const [ isOpen, setIsOpen ] = useState( false );
 	return (
 		<>
@@ -62,7 +63,7 @@ function ColorListPicker( {
 	disableCustomColors,
 	enableAlpha,
 	onChange,
-} ) {
+}: ColorListPickerProps ) {
 	return (
 		<div className="components-color-list-picker">
 			{ labels.map( ( label, index ) => (

package/src/color-list-picker/types.ts

@@ -0,0 +1,46 @@
+/**
+ * External dependencies
+ */
+import type { CSSProperties } from 'react';
+
+export type ColorListPickerProps = {
+	/**
+	 * A list of predifened colors. Each color is an object with a `name` and a
+	 * `color` value.
+	 * The `name` is a string used to identify the color in the UI.
+	 * The `color` is a valid CSS color string.
+	 */
+	colors: Array< {
+		name: string;
+		color: NonNullable< CSSProperties[ 'color' ] >;
+	} >;
+	/**
+	 * A list of labels for each of the options displayed in the UI.
+	 */
+	labels: Array< string >;
+	/**
+	 * An array containing the currently selected colors.
+	 */
+	value?: Array< string | undefined >;
+	/**
+	 * Controls whether the custom color picker is displayed.
+	 */
+	disableCustomColors?: boolean;
+	/**
+	 * Controls whether the ColorPalette should show an alpha channel control.
+	 */
+	enableAlpha?: boolean;
+	/**
+	 * A function that receives the updated color value.
+	 */
+	onChange: ( newValue: Array< string | undefined > ) => void;
+};
+
+export type ColorOptionProps = Pick<
+	ColorListPickerProps,
+	'colors' | 'disableCustomColors' | 'enableAlpha'
+> & {
+	label: ColorListPickerProps[ 'labels' ][ number ];
+	value: string | undefined;
+	onChange: ( newValue: string | undefined ) => void;
+};

package/src/color-palette/README.md

@@ -43,7 +43,7 @@ Whether the palette should have a clearing button.
 -   Required: No
 -   Default: `true`
 
-### `colors`: `( PaletteObject | ColorObject )[]`
+### `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.
 

package/src/color-palette/index.native.js

@@ -11,7 +11,6 @@ import {
 	Platform,
 	Text,
 } from 'react-native';
-import { map } from 'lodash';
 
 /**
  * WordPress dependencies
@@ -64,13 +63,21 @@ function ColorPalette( {
 	const opacity = useRef( new Animated.Value( 1 ) ).current;
 
 	const defaultColors = [
-		...new Set( map( defaultSettings.colors, 'color' ) ),
+		...new Set(
+			( defaultSettings.colors ?? [] ).map( ( { color } ) => color )
+		),
 	];
 	const mergedColors = [
-		...new Set( map( defaultSettings.allColors, 'color' ) ),
+		...new Set(
+			( defaultSettings.allColors ?? [] ).map( ( { color } ) => color )
+		),
 	];
 	const defaultGradientColors = [
-		...new Set( map( defaultSettings.gradients, 'gradient' ) ),
+		...new Set(
+			( defaultSettings.gradients ?? [] ).map(
+				( { gradient } ) => gradient
+			)
+		),
 	];
 	const colors = isGradientSegment ? defaultGradientColors : defaultColors;
 

package/src/color-palette/index.tsx

@@ -10,7 +10,7 @@ import a11yPlugin from 'colord/plugins/a11y';
  * WordPress dependencies
  */
 import { __, sprintf } from '@wordpress/i18n';
-import { useCallback, useMemo, forwardRef } from '@wordpress/element';
+import { useCallback, useRef, useMemo, forwardRef } from '@wordpress/element';
 
 /**
  * Internal dependencies
@@ -33,6 +33,12 @@ import type {
 } from './types';
 import type { WordPressComponentProps } from '../ui/context';
 import type { DropdownProps } from '../dropdown/types';
+import {
+	extractColorNameFromCurrentValue,
+	isMultiplePaletteArray,
+	normalizeColorValue,
+	showTransparentBackground,
+} from './utils';
 
 extend( [ namesPlugin, a11yPlugin ] );
 
@@ -164,60 +170,11 @@ export function CustomColorPickerDropdown( {
 	);
 }
 
-export const extractColorNameFromCurrentValue = (
-	currentValue?: ColorPaletteProps[ 'value' ],
-	colors: ColorPaletteProps[ 'colors' ] = [],
-	showMultiplePalettes: boolean = false
-) => {
-	if ( ! currentValue ) {
-		return '';
-	}
-
-	const currentValueIsCssVariable = /^var\(/.test( currentValue );
-	const normalizedCurrentValue = currentValueIsCssVariable
-		? currentValue
-		: colord( currentValue ).toHex();
-
-	// Normalize format of `colors` to simplify the following loop
-	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
-				? colorValue
-				: colord( colorValue ).toHex();
-
-			if ( normalizedCurrentValue === normalizedColorValue ) {
-				return colorName;
-			}
-		}
-	}
-
-	// translators: shown when the user has picked a custom color (i.e not in the palette of colors).
-	return __( 'Custom' );
-};
-
-export const showTransparentBackground = ( currentValue?: string ) => {
-	if ( typeof currentValue === 'undefined' ) {
-		return true;
-	}
-	return colord( currentValue ).alpha() === 0;
-};
-
-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 customColorPaletteRef = useRef< HTMLElement | null >( null );
 	const {
 		clearable = true,
 		colors = [],
@@ -230,9 +187,7 @@ function UnforwardedColorPalette(
 	} = props;
 	const clearColor = useCallback( () => onChange( undefined ), [ onChange ] );
 
-	const hasMultipleColorOrigins =
-		colors.length > 0 &&
-		( colors as PaletteObject[] )[ 0 ].colors !== undefined;
+	const hasMultipleColorOrigins = isMultiplePaletteArray( colors );
 	const buttonLabelName = useMemo(
 		() =>
 			extractColorNameFromCurrentValue(
@@ -243,22 +198,10 @@ function UnforwardedColorPalette(
 		[ value, colors, hasMultipleColorOrigins ]
 	);
 
-	// Make sure that the `colors` array has a valid format.
-	if (
-		colors.length > 0 &&
-		hasMultipleColorOrigins !== areColorsMultiplePalette( colors )
-	) {
-		// eslint-disable-next-line no-console
-		console.warn(
-			'wp.components.ColorPalette: please specify a valid format for the `colors` prop. '
-		);
-		return null;
-	}
-
 	const renderCustomColorPicker = () => (
 		<DropdownContentWrapper paddingSize="none">
 			<ColorPicker
-				color={ value }
+				color={ normalizeColorValue( value, customColorPaletteRef ) }
 				onChange={ ( color ) => onChange( color ) }
 				enableAlpha={ enableAlpha }
 			/>
@@ -303,6 +246,7 @@ function UnforwardedColorPalette(
 					renderToggle={ ( { isOpen, onToggle } ) => (
 						<Flex
 							as={ 'button' }
+							ref={ customColorPaletteRef }
 							justify="space-between"
 							align="flex-start"
 							className="components-color-palette__custom-color"

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

@@ -9,8 +9,6 @@ import userEvent from '@testing-library/user-event';
  */
 import ColorPalette from '..';
 
-jest.useFakeTimers();
-
 const EXAMPLE_COLORS = [
 	{ name: 'red', color: '#f00' },
 	{ name: 'green', color: '#0f0' },
@@ -54,9 +52,7 @@ describe( 'ColorPalette', () => {
 	} );
 
 	it( 'should call onClick on an active button with undefined', async () => {
-		const user = userEvent.setup( {
-			advanceTimers: jest.advanceTimersByTime,
-		} );
+		const user = userEvent.setup();
 		const onChange = jest.fn();
 
 		render(
@@ -76,9 +72,7 @@ describe( 'ColorPalette', () => {
 	} );
 
 	it( 'should call onClick on an inactive button', async () => {
-		const user = userEvent.setup( {
-			advanceTimers: jest.advanceTimersByTime,
-		} );
+		const user = userEvent.setup();
 		const onChange = jest.fn();
 
 		render(
@@ -104,9 +98,7 @@ describe( 'ColorPalette', () => {
 	} );
 
 	it( 'should call onClick with undefined, when the clearButton onClick is triggered', async () => {
-		const user = userEvent.setup( {
-			advanceTimers: jest.advanceTimersByTime,
-		} );
+		const user = userEvent.setup();
 		const onChange = jest.fn();
 
 		render(
@@ -139,9 +131,7 @@ describe( 'ColorPalette', () => {
 	} );
 
 	it( 'should render dropdown and its content', async () => {
-		const user = userEvent.setup( {
-			advanceTimers: jest.advanceTimersByTime,
-		} );
+		const user = userEvent.setup();
 		const onChange = jest.fn();
 
 		render(

package/src/color-palette/test/utils.ts

@@ -4,7 +4,7 @@
 import {
 	extractColorNameFromCurrentValue,
 	showTransparentBackground,
-} from '../';
+} from '../utils';
 
 describe( 'ColorPalette: Utils', () => {
 	describe( 'extractColorNameFromCurrentValue', () => {

package/src/color-palette/types.ts

@@ -55,7 +55,7 @@ export type ColorPaletteProps = Pick< PaletteProps, 'onChange' > & {
 	 *
 	 * @default []
 	 */
-	colors?: ( PaletteObject | ColorObject )[];
+	colors?: PaletteObject[] | ColorObject[];
 	/**
 	 * Whether to allow the user to pick a custom color on top of the predefined
 	 * choices (defined via the `colors` prop).

package/src/color-palette/utils.ts

@@ -0,0 +1,98 @@
+/**
+ * External dependencies
+ */
+import type { RefObject } from 'react';
+import { colord, extend } from 'colord';
+import namesPlugin from 'colord/plugins/names';
+import a11yPlugin from 'colord/plugins/a11y';
+
+/**
+ * WordPress dependencies
+ */
+import { __ } from '@wordpress/i18n';
+
+/**
+ * Internal dependencies
+ */
+import type { ColorObject, ColorPaletteProps, PaletteObject } from './types';
+
+extend( [ namesPlugin, a11yPlugin ] );
+
+export const extractColorNameFromCurrentValue = (
+	currentValue?: ColorPaletteProps[ 'value' ],
+	colors: ColorPaletteProps[ 'colors' ] = [],
+	showMultiplePalettes: boolean = false
+) => {
+	if ( ! currentValue ) {
+		return '';
+	}
+
+	const currentValueIsCssVariable = /^var\(/.test( currentValue );
+	const normalizedCurrentValue = currentValueIsCssVariable
+		? currentValue
+		: colord( currentValue ).toHex();
+
+	// Normalize format of `colors` to simplify the following loop
+	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
+				? colorValue
+				: colord( colorValue ).toHex();
+
+			if ( normalizedCurrentValue === normalizedColorValue ) {
+				return colorName;
+			}
+		}
+	}
+
+	// translators: shown when the user has picked a custom color (i.e not in the palette of colors).
+	return __( 'Custom' );
+};
+
+export const showTransparentBackground = ( currentValue?: string ) => {
+	if ( typeof currentValue === 'undefined' ) {
+		return true;
+	}
+	return colord( currentValue ).alpha() === 0;
+};
+
+// The PaletteObject type has a `colors` property (an array of ColorObject),
+// while the ColorObject type has a `color` property (the CSS color value).
+export const isMultiplePaletteObject = (
+	obj: PaletteObject | ColorObject
+): obj is PaletteObject =>
+	Array.isArray( ( obj as PaletteObject ).colors ) && ! ( 'color' in obj );
+
+export const isMultiplePaletteArray = (
+	arr: ( PaletteObject | ColorObject )[]
+): arr is PaletteObject[] => {
+	return (
+		arr.length > 0 &&
+		arr.every( ( colorObj ) => isMultiplePaletteObject( colorObj ) )
+	);
+};
+
+export const normalizeColorValue = (
+	value: string | undefined,
+	ref: RefObject< HTMLElement > | null
+) => {
+	const currentValueIsCssVariable = /^var\(/.test( value ?? '' );
+
+	if ( ! currentValueIsCssVariable || ! ref?.current ) {
+		return value;
+	}
+
+	const { ownerDocument } = ref.current;
+	const { defaultView } = ownerDocument;
+	const computedBackgroundColor = defaultView?.getComputedStyle(
+		ref.current
+	).backgroundColor;
+
+	return computedBackgroundColor
+		? colord( computedBackgroundColor ).toHex()
+		: value;
+};

package/src/color-picker/component.tsx

@@ -97,6 +97,7 @@ const ColorPicker = (
 			<AuxiliaryColorArtefactWrapper>
 				<AuxiliaryColorArtefactHStackHeader justify="space-between">
 					<SelectControl
+						__nextHasNoMarginBottom
 						options={ options }
 						value={ colorType }
 						onChange={ ( nextColorType ) =>

package/src/color-picker/stories/index.js

@@ -1,8 +1,3 @@
-/**
- * External dependencies
- */
-import { boolean, select } from '@storybook/addon-knobs';
-
 /**
  * WordPress dependencies
  */
@@ -12,70 +7,35 @@ import { useState } from '@wordpress/element';
  * Internal dependencies
  */
 import { ColorPicker } from '..';
-import { Flex } from '../../flex';
-import { Spacer } from '../../spacer';
-import { space } from '../../ui/utils/space';
 
 export default {
 	component: ColorPicker,
 	title: 'Components/ColorPicker',
-	parameters: {
-		knobs: { disable: false },
+	argTypes: {
+		color: { control: { type: null } },
+		copyFormat: {
+			control: { type: 'select' },
+			options: [ 'rgb', 'hsl', 'hex', undefined ],
+		},
+		// We can't use a `on*` regex because this component will switch to
+		// legacy mode when an onChangeComplete prop is passed.
+		onChange: { action: 'onChange' },
 	},
 };
 
-const PROP_UNSET = 'unset';
-
-const Example = () => {
-	const [ color, setColor ] = useState( undefined );
-	const props = {
-		enableAlpha: boolean( 'enableAlpha', false ),
-		copyFormat: select(
-			'copyFormat',
-			[ PROP_UNSET, 'rgb', 'hsl', 'hex' ],
-			PROP_UNSET
-		),
-	};
-
-	if ( props.copyFormat === PROP_UNSET ) {
-		delete props.copyFormat;
-	}
-
-	return (
-		<Flex
-			as={ Spacer }
-			gap={ space( 2 ) }
-			justify="space-around"
-			align="flex-start"
-			marginTop={ space( 10 ) }
-		>
-			<ColorPicker { ...props } color={ color } onChange={ setColor } />
-			<div style={ { width: 200, textAlign: 'center' } }>{ color }</div>
-			<ColorPicker { ...props } color={ color } onChange={ setColor } />
-		</Flex>
-	);
-};
-
-export const _default = () => {
-	return <Example />;
-};
-
-const LegacyExample = () => {
-	const [ legacyColor, setLegacyColor ] = useState( '#fff' );
-	const legacyProps = {
-		color: legacyColor,
-		onChangeComplete: setLegacyColor,
-		disableAlpha: boolean( 'disableAlpha', true ),
-	};
+const Template = ( { onChange, ...props } ) => {
+	const [ color, setColor ] = useState();
 
 	return (
-		<Flex align="flex-start" justify="flex-start">
-			<ColorPicker { ...legacyProps } />
-			<pre style={ { width: '20em' } }>
-				{ JSON.stringify( legacyColor, undefined, 4 ) }
-			</pre>
-		</Flex>
+		<ColorPicker
+			{ ...props }
+			color={ color }
+			onChange={ ( ...changeArgs ) => {
+				onChange( ...changeArgs );
+				setColor( ...changeArgs );
+			} }
+		/>
 	);
 };
 
-export const legacy = () => <LegacyExample />;
+export const Default = Template.bind( {} );