@wordpress/components 23.5.0 → 23.7.0

package/src/duotone-picker/{duotone-picker.js → duotone-picker.tsx}

@@ -12,14 +12,48 @@ import { __, sprintf } from '@wordpress/i18n';
 /**
  * Internal dependencies
  */
-import ColorListPicker from '../color-list-picker';
+import ColorListPicker from './color-list-picker';
 import CircularOptionPicker from '../circular-option-picker';
 import { VStack } from '../v-stack';
 
 import CustomDuotoneBar from './custom-duotone-bar';
 import { getDefaultColors, getGradientFromCSSColors } from './utils';
 import { Spacer } from '../spacer';
+import type { DuotonePickerProps } from './types';
 
+/**
+ * ```jsx
+ * import { DuotonePicker, DuotoneSwatch } from '@wordpress/components';
+ * import { useState } from '@wordpress/element';
+ *
+ * const DUOTONE_PALETTE = [
+ * 	{ colors: [ '#8c00b7', '#fcff41' ], name: 'Purple and yellow', slug: 'purple-yellow' },
+ * 	{ colors: [ '#000097', '#ff4747' ], name: 'Blue and red', slug: 'blue-red' },
+ * ];
+ *
+ * const COLOR_PALETTE = [
+ * 	{ color: '#ff4747', name: 'Red', slug: 'red' },
+ * 	{ color: '#fcff41', name: 'Yellow', slug: 'yellow' },
+ * 	{ color: '#000097', name: 'Blue', slug: 'blue' },
+ * 	{ color: '#8c00b7', name: 'Purple', slug: 'purple' },
+ * ];
+ *
+ * const Example = () => {
+ * 	const [ duotone, setDuotone ] = useState( [ '#000000', '#ffffff' ] );
+ * 	return (
+ * 		<>
+ * 			<DuotonePicker
+ * 				duotonePalette={ DUOTONE_PALETTE }
+ * 				colorPalette={ COLOR_PALETTE }
+ * 				value={ duotone }
+ * 				onChange={ setDuotone }
+ * 			/>
+ * 			<DuotoneSwatch values={ duotone } />
+ * 		</>
+ * 	);
+ * };
+ * ```
+ */
 function DuotonePicker( {
 	clearable = true,
 	unsetable = true,
@@ -29,7 +63,7 @@ function DuotonePicker( {
 	disableCustomDuotone,
 	value,
 	onChange,
-} ) {
+}: DuotonePickerProps ) {
 	const [ defaultDark, defaultLight ] = useMemo(
 		() => getDefaultColors( colorPalette ),
 		[ colorPalette ]
@@ -125,6 +159,9 @@ function DuotonePicker( {
 									newColors.length >= 2
 										? newColors
 										: undefined;
+								// @ts-expect-error TODO: The color arrays for a DuotonePicker should be a tuple of two colors,
+								// but it's currently typed as a string[].
+								// See also https://github.com/WordPress/gutenberg/pull/49060#discussion_r1136951035
 								onChange( newValue );
 							} }
 						/>

package/src/duotone-picker/{duotone-swatch.js → duotone-swatch.tsx}

@@ -9,8 +9,9 @@ import { swatch } from '@wordpress/icons';
 import ColorIndicator from '../color-indicator';
 import Icon from '../icon';
 import { getGradientFromCSSColors } from './utils';
+import type { DuotoneSwatchProps } from './types';
 
-function DuotoneSwatch( { values } ) {
+function DuotoneSwatch( { values }: DuotoneSwatchProps ) {
 	return values ? (
 		<ColorIndicator
 			colorValue={ getGradientFromCSSColors( values, '135deg' ) }

package/src/duotone-picker/stories/{duotone-picker.js → duotone-picker.tsx}

@@ -1,3 +1,8 @@
+/**
+ * External dependencies
+ */
+import type { ComponentMeta, ComponentStory } from '@storybook/react';
+
 /**
  * WordPress dependencies
  */
@@ -6,23 +11,22 @@ import { useState } from '@wordpress/element';
 /**
  * Internal dependencies
  */
-import { DuotonePicker } from '../';
+import { DuotonePicker } from '..';
+import type { DuotonePickerProps } from '../types';
 
-export default {
+const meta: ComponentMeta< typeof DuotonePicker > = {
 	title: 'Components/DuotonePicker',
 	component: DuotonePicker,
 	argTypes: {
-		clearable: { control: { type: 'boolean' } },
-		disableCustomColors: { control: { type: 'boolean' } },
-		disableCustomDuotone: { control: { type: 'boolean' } },
 		onChange: { action: 'onChange' },
-		unsetable: { control: { type: 'boolean' } },
+		value: { control: { type: null } },
 	},
 	parameters: {
 		controls: { expanded: true },
 		docs: { source: { state: 'open' } },
 	},
 };
+export default meta;
 
 const DUOTONE_PALETTE = [
 	{
@@ -44,8 +48,11 @@ const COLOR_PALETTE = [
 	{ color: '#8c00b7', name: 'Purple', slug: 'purple' },
 ];
 
-const Template = ( { onChange, ...args } ) => {
-	const [ value, setValue ] = useState();
+const Template: ComponentStory< typeof DuotonePicker > = ( {
+	onChange,
+	...args
+} ) => {
+	const [ value, setValue ] = useState< DuotonePickerProps[ 'value' ] >();
 
 	return (
 		<DuotonePicker

package/src/duotone-picker/stories/{duotone-swatch.js → duotone-swatch.tsx}

@@ -1,9 +1,14 @@
+/**
+ * External dependencies
+ */
+import type { ComponentMeta, ComponentStory } from '@storybook/react';
+
 /**
  * Internal dependencies
  */
-import { DuotoneSwatch } from '../';
+import { DuotoneSwatch } from '..';
 
-export default {
+const meta: ComponentMeta< typeof DuotoneSwatch > = {
 	title: 'Components/DuotoneSwatch',
 	component: DuotoneSwatch,
 	parameters: {
@@ -11,8 +16,9 @@ export default {
 		docs: { source: { state: 'open' } },
 	},
 };
+export default meta;
 
-const Template = ( args ) => {
+const Template: ComponentStory< typeof DuotoneSwatch > = ( args ) => {
 	return <DuotoneSwatch { ...args } />;
 };
 

package/src/duotone-picker/types.ts

@@ -0,0 +1,61 @@
+export type DuotonePickerProps = {
+	/**
+	 * Whether there should be a button to clear the duotone value.
+	 *
+	 * @default true
+	 */
+	clearable?: boolean;
+	/**
+	 * Whether there should be an `unset` option.
+	 *
+	 * @default true
+	 */
+	unsetable?: boolean;
+	/**
+	 * Array of color presets of the form `{ color: '#000000', name: 'Black', slug: 'black' }`.
+	 */
+	colorPalette: Color[];
+	/**
+	 * Array of duotone presets of the form `{ colors: [ '#000000', '#ffffff' ], name: 'Grayscale', slug: 'grayscale' }`.
+	 */
+	duotonePalette: DuotoneColor[];
+	/**
+	 * Whether custom colors should be disabled.
+	 *
+	 * @default false
+	 */
+	disableCustomColors?: boolean;
+	/**
+	 * Whether custom duotone values should be disabled.
+	 *
+	 * @default false
+	 */
+	disableCustomDuotone?: boolean;
+	/**
+	 * An array of colors for the duotone effect.
+	 */
+	value?: string[] | 'unset';
+	/**
+	 * Callback which is called when the duotone colors change.
+	 */
+	onChange: ( value: DuotonePickerProps[ 'value' ] | undefined ) => void;
+};
+
+type Color = {
+	color: string;
+	name: string;
+	slug: string;
+};
+
+type DuotoneColor = {
+	colors: string[];
+	name: string;
+	slug: string;
+};
+
+export type DuotoneSwatchProps = {
+	/**
+	 * An array of colors to show or `null` to show the placeholder swatch icon.
+	 */
+	values?: string[] | null;
+};

package/src/duotone-picker/{utils.js → utils.ts}

@@ -4,6 +4,11 @@
 import { colord, extend } from 'colord';
 import namesPlugin from 'colord/plugins/names';
 
+/**
+ * Internal dependencies
+ */
+import type { DuotonePickerProps } from './types';
+
 extend( [ namesPlugin ] );
 
 /**
@@ -18,11 +23,13 @@ extend( [ namesPlugin ] );
 /**
  * Calculate the brightest and darkest values from a color palette.
  *
- * @param {Object[]} palette Color palette for the theme.
+ * @param palette Color palette for the theme.
  *
- * @return {string[]} Tuple of the darkest color and brightest color.
+ * @return Tuple of the darkest color and brightest color.
  */
-export function getDefaultColors( palette ) {
+export function getDefaultColors(
+	palette: DuotonePickerProps[ 'colorPalette' ]
+) {
 	// A default dark and light color are required.
 	if ( ! palette || palette.length < 2 ) return [ '#000', '#fff' ];
 
@@ -38,7 +45,10 @@ export function getDefaultColors( palette ) {
 					current.brightness >= max.brightness ? current : max,
 				];
 			},
-			[ { brightness: 1 }, { brightness: 0 } ]
+			[
+				{ brightness: 1, color: '' },
+				{ brightness: 0, color: '' },
+			]
 		)
 		.map( ( { color } ) => color );
 }
@@ -46,12 +56,15 @@ export function getDefaultColors( palette ) {
 /**
  * Generate a duotone gradient from a list of colors.
  *
- * @param {string[]} colors CSS color strings.
- * @param {string}   angle  CSS gradient angle.
+ * @param colors CSS color strings.
+ * @param angle  CSS gradient angle.
  *
- * @return {string} CSS gradient string for the duotone swatch.
+ * @return  CSS gradient string for the duotone swatch.
  */
-export function getGradientFromCSSColors( colors = [], angle = '90deg' ) {
+export function getGradientFromCSSColors(
+	colors: string[] = [],
+	angle = '90deg'
+) {
 	const l = 100 / colors.length;
 
 	const stops = colors
@@ -64,11 +77,11 @@ export function getGradientFromCSSColors( colors = [], angle = '90deg' ) {
 /**
  * Convert a color array to an array of color stops.
  *
- * @param {string[]} colors CSS colors array
+ * @param colors CSS colors array
  *
- * @return {Object[]} Color stop information.
+ * @return Color stop information.
  */
-export function getColorStopsFromColors( colors ) {
+export function getColorStopsFromColors( colors: string[] ) {
 	return colors.map( ( color, i ) => ( {
 		position: ( i * 100 ) / ( colors.length - 1 ),
 		color,
@@ -78,10 +91,12 @@ export function getColorStopsFromColors( colors ) {
 /**
  * Convert a color stop array to an array colors.
  *
- * @param {Object[]} colorStops Color stop information.
+ * @param colorStops Color stop information.
  *
- * @return {string[]} CSS colors array.
+ * @return CSS colors array.
  */
-export function getColorsFromColorStops( colorStops = [] ) {
+export function getColorsFromColorStops(
+	colorStops: { position: number; color: string }[] = []
+) {
 	return colorStops.map( ( { color } ) => color );
 }

package/src/flex/flex/hook.ts

@@ -40,7 +40,7 @@ function useDeprecatedProps(
 
 export function useFlex( props: WordPressComponentProps< FlexProps, 'div' > ) {
 	const {
-		align = 'center',
+		align,
 		className,
 		direction: directionProp = 'row',
 		expanded = true,
@@ -62,7 +62,7 @@ export function useFlex( props: WordPressComponentProps< FlexProps, 'div' > ) {
 
 	const classes = useMemo( () => {
 		const base = css( {
-			alignItems: isColumn ? 'normal' : align,
+			alignItems: align ?? ( isColumn ? 'normal' : 'center' ),
 			flexDirection: direction,
 			flexWrap: wrap ? 'wrap' : undefined,
 			gap: space( gap ),

package/src/flex/flex-item/README.md

@@ -16,7 +16,7 @@ The CSS display property of `FlexItem`.
 
 ### `isBlock`: `boolean`
 
-Determins if `FlexItem` should render as an adaptive full-width block.
+Determines if `FlexItem` should render as an adaptive full-width block.
 
 -   Required: No
 -   Default: `false`

package/src/font-size-picker/README.md

@@ -49,22 +49,20 @@ const MyFontSizePicker = () => {
 
 The component accepts the following props:
 
-### disableCustomFontSizes
+### `disableCustomFontSizes`: `boolean`
 
 If `true`, it will not be possible to choose a custom fontSize. The user will be forced to pick one of the pre-defined sizes passed in fontSizes.
 
--   Type: `Boolean`
 -   Required: no
 -   Default: `false`
 
-### fallbackFontSize
+### `fallbackFontSize`: `number`
 
 If no value exists, this prop defines the starting position for the font size picker slider. Only relevant if `withSlider` is `true`.
 
--   Type: `Number`
 -   Required: No
 
-### fontSizes
+### `fontSizes`: `FontSize[]`
 
 An array of font size objects. The object should contain properties size, name, and slug.
 The property `size` contains a number with the font size value, in `px` or a string specifying the font size CSS property that should be used eg: "13px", "1em", or "clamp(12px, 5vw, 100px)".
@@ -73,44 +71,52 @@ The `slug` property is a string with a unique identifier for the font size. Used
 
 **Note:** The slugs `default` and `custom` are reserved and cannot be used.
 
--   Type: `Array`
 -   Required: No
+-   Default: `[]`
 
-### onChange
+### `onChange`: `( value: number | string | undefined, selectedItem?: FontSize ) => void`
 
 A function that receives the new font size value.
 If onChange is called without any parameter, it should reset the value, attending to what reset means in that context, e.g., set the font size to undefined or set the font size a starting value.
 
--   Type: `function`
 -   Required: Yes
 
-### value
+### `size`: `'default' | '__unstable-large'`
 
-The current font size value.
+Size of the control.
 
--   Type: `Number | String`
 -   Required: No
+-   Default: `'default'`
 
-### withSlider
+### `units`: `string[]`
 
-If `true`, a slider will be displayed alongside the input field when a custom font size is active. Has no effect when `disableCustomFontSizes` is `true`.
+Available units for custom font size selection.
 
--   Type: `Boolean`
--   Required: no
--   Default: `false`
+-   Required: No
+
+### `value`: `number | string`
+
+The current font size value.
 
-### withReset
+-   Required: No
+
+### `withReset`: `boolean`
 
 If `true`, a reset button will be displayed alongside the input field when a custom font size is active. Has no effect when `disableCustomFontSizes` is `true`.
 
--   Type: `Boolean`
 -   Required: no
 -   Default: `true`
 
-### __nextHasNoMarginBottom
+### `withSlider`: `boolean`
+
+If `true`, a slider will be displayed alongside the input field when a custom font size is active. Has no effect when `disableCustomFontSizes` is `true`.
+
+-   Required: no
+-   Default: `false`
+
+### `__nextHasNoMarginBottom`: `boolean`
 
 Start opting into the new margin-free styles that will become the default in a future version, currently scheduled to be WordPress 6.4. (The prop can be safely removed once this happens.)
 
--   Type: `Boolean`
 -   Required: no
 -   Default: `false`

package/src/font-size-picker/index.tsx

@@ -50,6 +50,7 @@ const UnforwardedFontSizePicker = (
 		disableCustomFontSizes = false,
 		onChange,
 		size = 'default',
+		units: unitsProp,
 		value,
 		withSlider = false,
 		withReset = true,
@@ -64,7 +65,7 @@ const UnforwardedFontSizePicker = (
 	}
 
 	const units = useCustomUnits( {
-		availableUnits: [ 'px', 'em', 'rem' ],
+		availableUnits: unitsProp || [ 'px', 'em', 'rem' ],
 	} );
 
 	const shouldUseSelectControl = fontSizes.length > 5;

package/src/font-size-picker/stories/index.tsx

@@ -85,6 +85,7 @@ Default.args = {
 			size: 26,
 		},
 	],
+	units: [ 'px', 'em', 'rem' ],
 	value: 16,
 	withSlider: false,
 };

package/src/font-size-picker/test/index.tsx

@@ -699,5 +699,28 @@ describe( 'FontSizePicker', () => {
 				screen.queryByRole( 'button', { name: 'Reset' } )
 			).not.toBeInTheDocument();
 		} );
+
+		it( 'applies custom units to custom font size control', async () => {
+			const user = userEvent.setup();
+
+			render(
+				<FontSizePicker
+					__nextHasNoMarginBottom
+					fontSizes={ fontSizes }
+					value={ fontSizes[ 0 ].size }
+					units={ [ 'px', 'ch', 'ex' ] }
+				/>
+			);
+
+			await user.click(
+				screen.getByRole( 'button', { name: 'Set custom size' } )
+			);
+
+			const units = screen.getAllByRole( 'option' );
+			expect( units ).toHaveLength( 3 );
+			expect( units[ 0 ] ).toHaveAccessibleName( 'px' );
+			expect( units[ 1 ] ).toHaveAccessibleName( 'ch' );
+			expect( units[ 2 ] ).toHaveAccessibleName( 'ex' );
+		} );
 	}
 } );

package/src/font-size-picker/types.ts

@@ -26,6 +26,10 @@ export type FontSizePickerProps = {
 		value: number | string | undefined,
 		selectedItem?: FontSize
 	) => void;
+	/**
+	 * Available units for custom font size selection.
+	 */
+	units?: string[];
 	/**
 	 * The current font size value.
 	 */

package/src/form-token-field/README.md

@@ -61,6 +61,7 @@ The `value` property is handled in a manner similar to controlled form component
 -   `__experimentalShowHowTo` - If false, the text on how to use the select (ie: _Separate with commas or the Enter key._) will be hidden.
 -   `__experimentalValidateInput` - If passed, all introduced values will be validated before being added as tokens.
 -   `__experimentalAutoSelectFirstMatch` - If true, the select the first matching suggestion when the user presses the Enter key (or space when tokenizeOnSpace is true).
+-   `__nextHasNoMarginBottom` - Start opting into the new margin-free styles that will become the default in a future version, currently scheduled to be WordPress 6.5. (The prop can be safely removed once this happens.)
 
 ## Usage
 

package/src/form-token-field/index.tsx

@@ -22,7 +22,11 @@ import { TokensAndInputWrapperFlex } from './styles';
 import SuggestionsList from './suggestions-list';
 import type { FormTokenFieldProps, TokenItem } from './types';
 import { FlexItem } from '../flex';
-import { StyledLabel } from '../base-control/styles/base-control-styles';
+import {
+	StyledHelp,
+	StyledLabel,
+} from '../base-control/styles/base-control-styles';
+import { Spacer } from '../spacer';
 
 const identity = ( value: string ) => value;
 
@@ -67,6 +71,7 @@ export function FormTokenField( props: FormTokenFieldProps ) {
 		__experimentalShowHowTo = true,
 		__next36pxDefaultSize = false,
 		__experimentalAutoSelectFirstMatch = false,
+		__nextHasNoMarginBottom = false,
 	} = props;
 
 	const instanceId = useInstanceId( FormTokenField );
@@ -153,7 +158,10 @@ export function FormTokenField( props: FormTokenFieldProps ) {
 	}
 
 	function onBlur() {
-		if ( inputHasValidValue() ) {
+		if (
+			inputHasValidValue() &&
+			__experimentalValidateInput( incompleteTokenValue )
+		) {
 			setIsActive( false );
 		} else {
 			// Reset to initial state
@@ -713,17 +721,19 @@ export function FormTokenField( props: FormTokenFieldProps ) {
 					/>
 				) }
 			</div>
+			{ ! __nextHasNoMarginBottom && <Spacer marginBottom={ 2 } /> }
 			{ __experimentalShowHowTo && (
-				<p
+				<StyledHelp
 					id={ `components-form-token-suggestions-howto-${ instanceId }` }
 					className="components-form-token-field__help"
+					__nextHasNoMarginBottom={ __nextHasNoMarginBottom }
 				>
 					{ tokenizeOnSpace
 						? __(
 								'Separate with commas, spaces, or the Enter key.'
 						  )
 						: __( 'Separate with commas or the Enter key.' ) }
-				</p>
+				</StyledHelp>
 			) }
 		</div>
 	);

package/src/form-token-field/stories/index.tsx

@@ -123,3 +123,16 @@ WithCustomRenderItem.args = {
 		<div>{ `${ item } — a nice place to visit` }</div>
 	),
 };
+
+/**
+ * Only values for which the `__experimentalValidateInput` function returns
+ * `true` will be tokenized. (This is still an experimental feature and is
+ * subject to change.)
+ */
+export const WithValidatedInput: ComponentStory< typeof FormTokenField > =
+	DefaultTemplate.bind( {} );
+WithValidatedInput.args = {
+	...Default.args,
+	__experimentalValidateInput: ( input: string ) =>
+		continents.includes( input ),
+};

package/src/form-token-field/style.scss

@@ -1,7 +1,6 @@
 .components-form-token-field__input-container {
 	@include input-control();
 	width: 100%;
-	margin: 0 0 $grid-unit-10 0;
 	padding: 0;
 	cursor: text;
 
@@ -48,12 +47,6 @@
 	}
 }
 
-.components-form-token-field__help {
-	font-size: $helptext-font-size;
-	font-style: normal;
-	color: $gray-700;
-}
-
 // Tokens
 .components-form-token-field__token {
 	font-size: $default-font-size;