@wordpress/components 21.2.0 → 22.0.0

package/src/card/stories/index.tsx

@@ -40,36 +40,32 @@ const meta: ComponentMeta< typeof Card > = {
 
 export default meta;
 
-const Template: ComponentStory< typeof Card > = ( args ) => {
-	return (
-		<div style={ { maxWidth: '280px' } }>
-			<Card { ...args }>
-				<CardHeader>
-					<Heading>CardHeader</Heading>
-				</CardHeader>
-				<CardBody>
-					<Text>CardBody</Text>
-				</CardBody>
-				<CardBody>
-					<Text>CardBody (before CardDivider)</Text>
-				</CardBody>
-				<CardDivider />
-				<CardBody>
-					<Text>CardBody (after CardDivider)</Text>
-				</CardBody>
-				<CardMedia>
-					<img
-						alt="Card Media"
-						src="https://images.unsplash.com/photo-1566125882500-87e10f726cdc?ixlib=rb-1.2.1&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=1867&q=80"
-					/>
-				</CardMedia>
-				<CardFooter>
-					<Text>CardFooter</Text>
-					<Button variant="secondary">Action Button</Button>
-				</CardFooter>
-			</Card>
-		</div>
-	);
-};
+const Template: ComponentStory< typeof Card > = ( args ) => (
+	<Card { ...args }>
+		<CardHeader>
+			<Heading>CardHeader</Heading>
+		</CardHeader>
+		<CardBody>
+			<Text>CardBody</Text>
+		</CardBody>
+		<CardBody>
+			<Text>CardBody (before CardDivider)</Text>
+		</CardBody>
+		<CardDivider />
+		<CardBody>
+			<Text>CardBody (after CardDivider)</Text>
+		</CardBody>
+		<CardMedia>
+			<img
+				alt="Card Media"
+				src="https://images.unsplash.com/photo-1566125882500-87e10f726cdc?ixlib=rb-1.2.1&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=1867&q=80"
+			/>
+		</CardMedia>
+		<CardFooter>
+			<Text>CardFooter</Text>
+			<Button variant="secondary">Action Button</Button>
+		</CardFooter>
+	</Card>
+);
 
 export const Default: ComponentStory< typeof Card > = Template.bind( {} );

package/src/card/test/__snapshots__/index.tsx.snap

@@ -90,27 +90,27 @@ Snapshot Diff:
 - First value
 + Second value
 
-@@ -5,18 +5,18 @@
-  >
-    <div
-      class="css-mgwsf4-View-Content e19lxcc00"
+@@ -6,18 +6,18 @@
     >
       <div
--       class="components-flex components-card__header components-card-header css-3fkkv8-View-Flex-base-ItemsRow-Header-borderRadius-borderColor-medium e19lxcc00"
-+       class="components-flex components-card__header components-card-header css-2feznw-View-Flex-base-ItemsRow-Header-borderRadius-borderColor-large e19lxcc00"
-        data-wp-c16t="true"
-        data-wp-component="CardHeader"
-      >
-        Header
-      </div>
-      <div
--       class="components-card__body components-card-body css-1nwhnu3-View-Body-borderRadius-medium e19lxcc00"
-+       class="components-card__body components-card-body css-1nonx1n-View-Body-borderRadius-large e19lxcc00"
-        data-wp-c16t="true"
-        data-wp-component="CardBody"
+        class="css-mgwsf4-View-Content e19lxcc00"
       >
-        Code is Poetry
-      </div>
+        <div
+-         class="components-flex components-card__header components-card-header css-3fkkv8-View-Flex-base-ItemsRow-Header-borderRadius-borderColor-medium e19lxcc00"
++         class="components-flex components-card__header components-card-header css-2feznw-View-Flex-base-ItemsRow-Header-borderRadius-borderColor-large e19lxcc00"
+          data-wp-c16t="true"
+          data-wp-component="CardHeader"
+        >
+          Header
+        </div>
+        <div
+-         class="components-card__body components-card-body css-1nwhnu3-View-Body-borderRadius-medium e19lxcc00"
++         class="components-card__body components-card-body css-1nonx1n-View-Body-borderRadius-large e19lxcc00"
+          data-wp-c16t="true"
+          data-wp-component="CardBody"
+        >
+          Code is Poetry
+        </div>
 `;
 
 exports[`Card Card component should add rounded border when the isRounded prop is true 1`] = `
@@ -768,24 +768,25 @@ Snapshot Diff:
 - First value
 + Second value
 
-@@ -8,16 +8,16 @@
-    >
-      Code is Poetry
+@@ -9,17 +9,17 @@
+      >
+        Code is Poetry
+      </div>
+      <div
+        aria-hidden="true"
+-       class="components-elevation css-1lsfy80-View-Elevation-sx-Base-elevationClassName e19lxcc00"
++       class="components-elevation css-15t1t3g-View-Elevation-sx-Base-elevationClassName e19lxcc00"
+        data-wp-c16t="true"
+        data-wp-component="Elevation"
+      />
+      <div
+        aria-hidden="true"
+-       class="components-elevation css-18cl04p-View-Elevation-sx-Base-elevationClassName e19lxcc00"
++       class="components-elevation css-15t1t3g-View-Elevation-sx-Base-elevationClassName e19lxcc00"
+        data-wp-c16t="true"
+        data-wp-component="Elevation"
+      />
     </div>
-    <div
-      aria-hidden="true"
--     class="components-elevation css-1lsfy80-View-Elevation-sx-Base-elevationClassName e19lxcc00"
-+     class="components-elevation css-15t1t3g-View-Elevation-sx-Base-elevationClassName e19lxcc00"
-      data-wp-c16t="true"
-      data-wp-component="Elevation"
-    />
-    <div
-      aria-hidden="true"
--     class="components-elevation css-18cl04p-View-Elevation-sx-Base-elevationClassName e19lxcc00"
-+     class="components-elevation css-15t1t3g-View-Elevation-sx-Base-elevationClassName e19lxcc00"
-      data-wp-c16t="true"
-      data-wp-component="Elevation"
-    />
   </div>
 `;
 

package/src/card/test/index.tsx

@@ -70,9 +70,7 @@ describe( 'Card', () => {
 				<Card>Code is Poetry</Card>
 			);
 
-			expect( withElevation.firstChild ).toMatchDiffSnapshot(
-				withoutElevation.firstChild
-			);
+			expect( withElevation ).toMatchDiffSnapshot( withoutElevation );
 		} );
 
 		it( 'should add different amounts of white space when using the size prop', () => {
@@ -90,9 +88,7 @@ describe( 'Card', () => {
 				</Card>
 			);
 
-			expect( withSizeDefault.firstChild ).toMatchDiffSnapshot(
-				withSizeLarge.firstChild
-			);
+			expect( withSizeDefault ).toMatchDiffSnapshot( withSizeLarge );
 		} );
 
 		it( 'should warn when the isElevated prop is passed', () => {

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;