@wordpress/components 23.6.0 → 23.7.0

package/src/custom-gradient-picker/types.ts

@@ -0,0 +1,137 @@
+/**
+ * External dependencies
+ */
+import type gradientParser from 'gradient-parser';
+
+export type CustomGradientPickerProps = {
+	/**
+	 * Start opting in to 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.)
+	 *
+	 * @default false
+	 */
+	__nextHasNoMargin?: boolean;
+	/**
+	 * The current value of the gradient. Pass a css gradient string (See default value for example).
+	 * Optionally pass in a `null` value to specify no gradient is currently selected.
+	 *
+	 * @default 'linear-gradient(135deg,rgba(6,147,227,1) 0%,rgb(155,81,224) 100%)'
+	 */
+	value?: string | null;
+	/**
+	 * The function called when a new gradient has been defined. It is passed to
+	 * the `currentGradient` as an argument.
+	 */
+	onChange: ( currentGradient: string ) => void;
+	/**
+	 * Whether this is rendered in the sidebar.
+	 *
+	 * @default false
+	 */
+	__experimentalIsRenderedInSidebar?: boolean;
+};
+
+export type GradientAnglePickerProps = {
+	gradientAST:
+		| gradientParser.LinearGradientNode
+		| gradientParser.RepeatingLinearGradientNode;
+	hasGradient: boolean;
+	onChange: ( gradient: string ) => void;
+};
+
+export type GradientTypePickerProps = {
+	gradientAST: gradientParser.GradientNode;
+	hasGradient: boolean;
+	onChange: ( gradient: string ) => void;
+};
+
+export type ControlPoint = { color: string; position: number };
+
+// When dealing with unions of objects, using `Pick` will result
+// in a new type where each desired prop is a union of the values for that prop
+// across all of the original union members. This does not maintain the specific
+// combinations of props present in the original union.
+// To avoid this, the `DistributivePick` type will
+// "distribute" the `Pick` across the union. This allows the `Pick`
+// to act on each member individually, maintaining the relationships between the
+// resulting props.
+// https://stackoverflow.com/questions/57103834/typescript-omit-a-property-from-all-interfaces-in-a-union-but-keep-the-union-s
+type DistributivePick< T, K extends keyof T > = T extends any
+	? Pick< T, K >
+	: never;
+
+export type ColorStopTypeAndValue = DistributivePick<
+	gradientParser.ColorStop,
+	'type' | 'value'
+>;
+
+export type CustomGradientBarProps = {
+	background: React.CSSProperties[ 'background' ];
+	hasGradient: boolean;
+	value: ControlPoint[];
+	onChange: ( newControlPoints: ControlPoint[] ) => void;
+	disableInserter?: boolean;
+	disableAlpha?: boolean;
+	__experimentalIsRenderedInSidebar?: boolean;
+};
+
+export type CustomGradientBarIdleState = { id: 'IDLE' };
+type CustomGradientBarMovingInserterState = {
+	id: 'MOVING_INSERTER';
+	insertPosition: number;
+};
+type CustomGradientBarInsertingControlPointState = {
+	id: 'INSERTING_CONTROL_POINT';
+	insertPosition: number;
+};
+type CustomGradientBarMovingControlPointState = { id: 'MOVING_CONTROL_POINT' };
+
+export type CustomGradientBarReducerState =
+	| CustomGradientBarIdleState
+	| CustomGradientBarMovingInserterState
+	| CustomGradientBarInsertingControlPointState
+	| CustomGradientBarMovingControlPointState;
+
+export type CustomGradientBarReducerAction =
+	| { type: 'MOVE_INSERTER'; insertPosition: number }
+	| { type: 'STOP_INSERTER_MOVE' }
+	| { type: 'OPEN_INSERTER' }
+	| { type: 'CLOSE_INSERTER' }
+	| { type: 'START_CONTROL_CHANGE' }
+	| { type: 'STOP_CONTROL_CHANGE' };
+
+export type ControlPointButtonProps = {
+	isOpen: boolean;
+	position: ControlPoint[ 'position' ];
+	color: string;
+};
+
+export type ControlPointsProps = {
+	disableRemove: boolean;
+	disableAlpha: boolean;
+	gradientPickerDomRef: React.RefObject< HTMLDivElement >;
+	ignoreMarkerPosition?: number;
+	value: ControlPoint[];
+	onChange: ( controlPoints: ControlPoint[] ) => void;
+	onStartControlPointChange: () => void;
+	onStopControlPointChange: () => void;
+	__experimentalIsRenderedInSidebar: boolean;
+};
+
+export type ControlPointMoveState = {
+	initialPosition: number;
+	index: number;
+	significantMoveHappened: boolean;
+	listenersActivated: boolean;
+};
+
+export type InsertPointProps = {
+	value: ControlPoint[];
+	onChange: ( controlPoints: ControlPoint[] ) => void;
+	onOpenInserter: () => void;
+	onCloseInserter: () => void;
+	insertPosition: number;
+	disableAlpha: boolean;
+	__experimentalIsRenderedInSidebar: boolean;
+};

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

@@ -1,5 +1,3 @@
-// @ts-nocheck
-
 /**
  * External dependencies
  */
@@ -16,10 +14,13 @@ import {
 	DIRECTIONAL_ORIENTATION_ANGLE_MAP,
 } from './constants';
 import { serializeGradient } from './serializer';
+import type { ControlPoint } from './types';
 
 extend( [ namesPlugin ] );
 
-export function getLinearGradientRepresentation( gradientAST ) {
+export function getLinearGradientRepresentation(
+	gradientAST: gradientParser.GradientNode
+) {
 	return serializeGradient( {
 		type: 'linear-gradient',
 		orientation: HORIZONTAL_GRADIENT_ORIENTATION,
@@ -27,29 +28,41 @@ export function getLinearGradientRepresentation( gradientAST ) {
 	} );
 }
 
-function hasUnsupportedLength( item ) {
+function hasUnsupportedLength( item: gradientParser.ColorStop ) {
 	return item.length === undefined || item.length.type !== '%';
 }
 
-export function getGradientAstWithDefault( value ) {
+export function getGradientAstWithDefault( value?: string | null ) {
 	// gradientAST will contain the gradient AST as parsed by gradient-parser npm module.
 	// More information of its structure available at https://www.npmjs.com/package/gradient-parser#ast.
-	let gradientAST;
+	let gradientAST: gradientParser.GradientNode | undefined;
+	let hasGradient = !! value;
+
+	const valueToParse = value ?? DEFAULT_GRADIENT;
 
 	try {
-		gradientAST = gradientParser.parse( value )[ 0 ];
-		gradientAST.value = value;
+		gradientAST = gradientParser.parse( valueToParse )[ 0 ];
 	} catch ( error ) {
+		// eslint-disable-next-line no-console
+		console.warn(
+			'wp.components.CustomGradientPicker failed to parse the gradient with error',
+			error
+		);
+
 		gradientAST = gradientParser.parse( DEFAULT_GRADIENT )[ 0 ];
-		gradientAST.value = DEFAULT_GRADIENT;
+		hasGradient = false;
 	}
 
-	if ( gradientAST.orientation?.type === 'directional' ) {
-		gradientAST.orientation.type = 'angular';
-		gradientAST.orientation.value =
-			DIRECTIONAL_ORIENTATION_ANGLE_MAP[
+	if (
+		! Array.isArray( gradientAST.orientation ) &&
+		gradientAST.orientation?.type === 'directional'
+	) {
+		gradientAST.orientation = {
+			type: 'angular',
+			value: DIRECTIONAL_ORIENTATION_ANGLE_MAP[
 				gradientAST.orientation.value
-			].toString();
+			].toString(),
+		};
 	}
 
 	if ( gradientAST.colorStops.some( hasUnsupportedLength ) ) {
@@ -57,19 +70,18 @@ export function getGradientAstWithDefault( value ) {
 		const step = 100 / ( colorStops.length - 1 );
 		colorStops.forEach( ( stop, index ) => {
 			stop.length = {
-				value: step * index,
+				value: `${ step * index }`,
 				type: '%',
 			};
 		} );
-		gradientAST.value = serializeGradient( gradientAST );
 	}
 
-	return gradientAST;
+	return { gradientAST, hasGradient };
 }
 
 export function getGradientAstWithControlPoints(
-	gradientAST,
-	newControlPoints
+	gradientAST: gradientParser.GradientNode,
+	newControlPoints: ControlPoint[]
 ) {
 	return {
 		...gradientAST,
@@ -81,13 +93,16 @@ export function getGradientAstWithControlPoints(
 					value: position?.toString(),
 				},
 				type: a < 1 ? 'rgba' : 'rgb',
-				value: a < 1 ? [ r, g, b, a ] : [ r, g, b ],
+				value:
+					a < 1
+						? [ `${ r }`, `${ g }`, `${ b }`, `${ a }` ]
+						: [ `${ r }`, `${ g }`, `${ b }` ],
 			};
 		} ),
-	};
+	} as gradientParser.GradientNode;
 }
 
-export function getStopCssColor( colorStop ) {
+export function getStopCssColor( colorStop: gradientParser.ColorStop ) {
 	switch ( colorStop.type ) {
 		case 'hex':
 			return `#${ colorStop.value }`;

package/src/custom-select-control/test/index.js

@@ -1,7 +1,8 @@
 /**
  * External dependencies
  */
-import { render, fireEvent, screen } from '@testing-library/react';
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
 
 /**
  * Internal dependencies
@@ -9,7 +10,8 @@ import { render, fireEvent, screen } from '@testing-library/react';
 import CustomSelectControl from '..';
 
 describe( 'CustomSelectControl', () => {
-	it( 'Captures the keypress event and does not let it propagate', () => {
+	it( 'Captures the keypress event and does not let it propagate', async () => {
+		const user = userEvent.setup();
 		const onKeyDown = jest.fn();
 		const options = [
 			{
@@ -39,10 +41,10 @@ describe( 'CustomSelectControl', () => {
 			</div>
 		);
 		const toggleButton = screen.getByRole( 'button' );
-		fireEvent.click( toggleButton );
+		await user.click( toggleButton );
 
 		const customSelect = screen.getByRole( 'listbox' );
-		fireEvent.keyDown( customSelect );
+		await user.type( customSelect, '{enter}' );
 
 		expect( onKeyDown ).toHaveBeenCalledTimes( 0 );
 	} );

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

@@ -7,11 +7,11 @@ import { swatch } from '@wordpress/icons';
 /**
  * Internal dependencies
  */
-import Button from '../button';
-import ColorPalette from '../color-palette';
-import ColorIndicator from '../color-indicator';
-import Icon from '../icon';
-import { HStack } from '../h-stack';
+import Button from '../../button';
+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( {
@@ -75,7 +75,8 @@ function ColorListPicker( {
 					disableCustomColors={ disableCustomColors }
 					enableAlpha={ enableAlpha }
 					onChange={ ( newColor ) => {
-						const newColors = value.slice();
+						const newColors: ( string | undefined )[] =
+							value.slice();
 						newColors[ index ] = newColor;
 						onChange( newColors );
 					} }

package/src/{color-list-picker → duotone-picker/color-list-picker}/types.ts

@@ -5,7 +5,7 @@ import type { CSSProperties } from 'react';
 
 export type ColorListPickerProps = {
 	/**
-	 * A list of predifened colors. Each color is an object with a `name` and a
+	 * A list of predefined 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.
@@ -21,7 +21,7 @@ export type ColorListPickerProps = {
 	/**
 	 * An array containing the currently selected colors.
 	 */
-	value?: Array< string | undefined >;
+	value?: Array< string >;
 	/**
 	 * Controls whether the custom color picker is displayed.
 	 */

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

@@ -11,7 +11,13 @@ import {
 
 const PLACEHOLDER_VALUES = [ '#333', '#CCC' ];
 
-export default function CustomDuotoneBar( { value, onChange } ) {
+export default function CustomDuotoneBar( {
+	value,
+	onChange,
+}: {
+	value?: string[];
+	onChange: ( value?: string[] ) => void;
+} ) {
 	const hasGradient = !! value;
 	const values = hasGradient ? value : PLACEHOLDER_VALUES;
 	const background = getGradientFromCSSColors( values );

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-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/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