@wordpress/components 23.5.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}

@@ -14,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,
@@ -25,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 ) ) {
@@ -55,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,
@@ -79,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/dimension-control/README.md

@@ -8,77 +8,46 @@ This feature is still experimental. “Experimental” means this is an early im
 
 ## Usage
 
-In a block's `edit` implementation, render a `<DimensionControl />` component.
-
 ```jsx
-import { registerBlockType } from '@wordpress/blocks';
-import { __ } from '@wordpress/i18n';
-import { DimensionControl } from '@wordpress/components';
-
-const partialRight =
-	( fn, ...partialArgs ) =>
-	( ...args ) =>
-		fn( ...args, ...partialArgs );
-
-registerBlockType( 'my-plugin/my-block', {
-	// ...
-
-	attributes: {
-		// other attributes here
-		// ...
-
-		paddingSize: {
-			type: 'string',
-		},
-	},
-
-	edit( { attributes, setAttributes, clientId } ) {
-		const { paddingSize } = attributes;
-
-		const updateSpacing = ( dimension, size, device = '' ) => {
-			setAttributes( {
-				[ `${ dimension }${ device }` ]: size,
-			} );
-		};
-
-		return (
-			<DimensionControl
-				label={ __( 'Padding' ) }
-				icon={ 'desktop' }
-				onChange={ partialRight( updateSpacing, 'paddingSize' ) }
-				value={ paddingSize }
-			/>
-		);
-	},
-} );
+import { useState } from 'react';
+import { __experimentalDimensionControl as DimensionControl } from '@wordpress/components';
+
+export default function MyCustomDimensionControl() {
+	const [ paddingSize, setPaddingSize ] = useState( '' );
+
+	return (
+		<DimensionControl
+			label={ 'Padding' }
+			icon={ 'desktop' }
+			onChange={ ( value ) => setPaddingSize( value ) }
+			value={ paddingSize }
+		/>
+	);
+}
 ```
 
-_Note:_ it is recommended to partially apply the value of the Block attribute to be updated (eg: `paddingSize`, `marginSize`...etc) to your callback functions. This avoids the need to unnecessarily couple the component to the Block attribute schema.
-
 _Note:_ by default, if you do not provide an initial `value` prop for the current dimension value, then no value will be selected (ie: there is no default dimension set).
 
 ## Props
 
 ### `label`
 
--   **Type:** `String`
--   **Default:** `undefined`
+-   **Type:** `string`
 -   **Required:** Yes
 
 The human readable label for the control.
 
 ### `value`
 
--   **Type:** `String`
--   **Default:** `''`
+-   **Type:** `string`
 -   **Required:** No
 
 The current value of the dimension UI control. If provided the UI with automatically select the value.
 
 ### `sizes`
 
--   **Type:** `Array`
--   **Default:** See `packages/block-editor/src/components/dimension-control/sizes.js`
+-   **Type:** `{ name: string; slug: string }[]`
+-   **Default:** See `packages/block-editor/src/components/dimension-control/sizes.ts`
 -   **Required:** No
 
 An optional array of size objects in the following shape:
@@ -101,16 +70,14 @@ By default a set of relative sizes (`small`, `medium`...etc) are provided. See `
 
 ### `icon`
 
--   **Type:** `String`
--   **Default:** `undefined`
+-   **Type:** `string`
 -   **Required:** No
 
 An optional dashicon to display before to the control label.
 
 ### `onChange`
 
--   **Type:** `Function`
--   **Default:** `undefined`
+-   **Type:** `( value?: string ) => void;`
 -   **Required:** No
 -   **Arguments:**:
     -   `size` - a string representing the selected size (eg: `medium`)
@@ -119,7 +86,7 @@ A callback which is triggered when a spacing size value changes (is selected/cli
 
 ### `className`
 
--   **Type:** `String`
+-   **Type:** `string`
 -   **Default:** `''`
 -   **Required:** No
 

package/src/dimension-control/index.tsx

@@ -0,0 +1,101 @@
+/**
+ * External dependencies
+ */
+import classnames from 'classnames';
+
+/**
+ * WordPress dependencies
+ */
+import { __ } from '@wordpress/i18n';
+
+/**
+ * Internal dependencies
+ */
+import Icon from '../icon';
+import SelectControl from '../select-control';
+import sizesTable, { findSizeBySlug } from './sizes';
+import type { DimensionControlProps, Size } from './types';
+import type { SelectControlSingleSelectionProps } from '../select-control/types';
+
+/**
+ * `DimensionControl` is a component designed to provide a UI to control spacing and/or dimensions.
+ *
+ * This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+ *
+ * ```jsx
+ * import { useState } from 'react';
+ * import { __experimentalDimensionControl as DimensionControl } from '@wordpress/components';
+ *
+ * export default function MyCustomDimensionControl() {
+ * 	const [ paddingSize, setPaddingSize ] = useState( '' );
+ *
+ * 	return (
+ * 		<DimensionControl
+ * 			label={ 'Padding' }
+ * 			icon={ 'desktop' }
+ * 			onChange={ ( value ) => setPaddingSize( value ) }
+ * 			value={ paddingSize }
+ * 		/>
+ * 	);
+ * }
+ * ```
+ */
+export function DimensionControl( props: DimensionControlProps ) {
+	const {
+		label,
+		value,
+		sizes = sizesTable,
+		icon,
+		onChange,
+		className = '',
+	} = props;
+
+	const onChangeSpacingSize: SelectControlSingleSelectionProps[ 'onChange' ] =
+		( val ) => {
+			const theSize = findSizeBySlug( sizes, val );
+
+			if ( ! theSize || value === theSize.slug ) {
+				onChange?.( undefined );
+			} else if ( typeof onChange === 'function' ) {
+				onChange( theSize.slug );
+			}
+		};
+
+	const formatSizesAsOptions = ( theSizes: Size[] ) => {
+		const options = theSizes.map( ( { name, slug } ) => ( {
+			label: name,
+			value: slug,
+		} ) );
+
+		return [
+			{
+				label: __( 'Default' ),
+				value: '',
+			},
+			...options,
+		];
+	};
+
+	const selectLabel = (
+		<>
+			{ icon && <Icon icon={ icon } /> }
+			{ label }
+		</>
+	);
+
+	return (
+		<SelectControl
+			className={ classnames(
+				className,
+				'block-editor-dimension-control'
+			) }
+			label={ selectLabel }
+			hideLabelFromVision={ false }
+			value={ value }
+			onChange={ onChangeSpacingSize }
+			options={ formatSizesAsOptions( sizes ) }
+		/>
+	);
+}
+
+export default DimensionControl;

package/src/dimension-control/{sizes.js → sizes.ts}

@@ -12,16 +12,19 @@
  */
 import { _x } from '@wordpress/i18n';
 
+/**
+ * Internal dependencies
+ */
+import type { Size } from './types';
+
 /**
  * Finds the correct size object from the provided sizes
  * table by size slug (eg: `medium`)
  *
- * @param {Array}  sizes containing objects for each size definition.
- * @param {string} slug  a string representation of the size (eg: `medium`).
- *
- * @return {Object} the matching size definition.
+ * @param sizes containing objects for each size definition.
+ * @param slug  a string representation of the size (eg: `medium`).
  */
-export const findSizeBySlug = ( sizes, slug ) =>
+export const findSizeBySlug = ( sizes: Size[], slug: string ) =>
 	sizes.find( ( size ) => slug === size.slug );
 
 export default [

package/src/dimension-control/stories/index.tsx

@@ -0,0 +1,48 @@
+/**
+ * External dependencies
+ */
+import type { ComponentMeta, ComponentStory } from '@storybook/react';
+/**
+ * Internal dependencies
+ */
+import { DimensionControl } from '..';
+import sizes from '../sizes';
+
+/**
+ * WordPress dependencies
+ */
+import { desktop, tablet, mobile } from '@wordpress/icons';
+
+export default {
+	component: DimensionControl,
+	title: 'Components (Experimental)/DimensionControl',
+	argTypes: {
+		onChange: { action: 'onChange' },
+		value: { control: { type: null } },
+		icon: {
+			control: { type: 'select' },
+			options: [ '-', 'desktop', 'tablet', 'mobile' ],
+			mapping: {
+				'-': undefined,
+				desktop,
+				tablet,
+				mobile,
+			},
+		},
+		parameters: {
+			controls: { expanded: true },
+			docs: { source: { state: 'open' } },
+		},
+	},
+} as ComponentMeta< typeof DimensionControl >;
+
+const Template: ComponentStory< typeof DimensionControl > = ( args ) => (
+	<DimensionControl { ...args } />
+);
+
+export const Default = Template.bind( {} );
+
+Default.args = {
+	label: 'Please select a size',
+	sizes,
+};

package/src/dimension-control/types.ts

@@ -0,0 +1,48 @@
+/**
+ * Internal dependencies
+ */
+import type { IconType } from '../icon';
+
+export type Size = {
+	/**
+	 * Human-readable name of the size.
+	 */
+	name: string;
+	/**
+	 * Short unique identifying name of the size.
+	 */
+	slug: string;
+};
+
+export type DimensionControlProps = {
+	/**
+	 * Label for the control.
+	 */
+	label: string;
+	/**
+	 * An array of sizes to choose from.
+	 *
+	 * @default DEFAULT_SIZES
+	 *
+	 * @see packages/components/src/dimension-control/sizes.ts
+	 */
+	sizes?: Size[];
+	/**
+	 * Optional icon rendered in front on the label.
+	 */
+	icon?: IconType;
+	/**
+	 * Used to externally control the current value of the control.
+	 */
+	value?: string;
+	/**
+	 * Function called with the control's internal state changes. The `value` property is equal to a given size slug.
+	 */
+	onChange?: ( value?: string ) => void;
+	/**
+	 * CSS class applied to `SelectControl`.
+	 *
+	 * @default ''
+	 */
+	className?: string;
+};

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 );