@wordpress/components 23.5.0 → 23.7.0

package/src/custom-gradient-picker/gradient-bar/utils.ts

@@ -0,0 +1,193 @@
+/**
+ * Internal dependencies
+ */
+import { MINIMUM_DISTANCE_BETWEEN_POINTS } from './constants';
+import type { ControlPoint } from '../types';
+
+/**
+ * Clamps a number between 0 and 100.
+ *
+ * @param value Value to clamp.
+ *
+ * @return Value clamped between 0 and 100.
+ */
+export function clampPercent( value: number ) {
+	return Math.max( 0, Math.min( 100, value ) );
+}
+
+/**
+ * Check if a control point is overlapping with another.
+ *
+ * @param value        Array of control points.
+ * @param initialIndex Index of the position to test.
+ * @param newPosition  New position of the control point.
+ * @param minDistance  Distance considered to be overlapping.
+ *
+ * @return True if the point is overlapping.
+ */
+export function isOverlapping(
+	value: ControlPoint[],
+	initialIndex: number,
+	newPosition: number,
+	minDistance: number = MINIMUM_DISTANCE_BETWEEN_POINTS
+) {
+	const initialPosition = value[ initialIndex ].position;
+	const minPosition = Math.min( initialPosition, newPosition );
+	const maxPosition = Math.max( initialPosition, newPosition );
+
+	return value.some( ( { position }, index ) => {
+		return (
+			index !== initialIndex &&
+			( Math.abs( position - newPosition ) < minDistance ||
+				( minPosition < position && position < maxPosition ) )
+		);
+	} );
+}
+
+/**
+ * Adds a control point from an array and returns the new array.
+ *
+ * @param points   Array of control points.
+ * @param position Position to insert the new point.
+ * @param color    Color to update the control point at index.
+ *
+ * @return New array of control points.
+ */
+export function addControlPoint(
+	points: ControlPoint[],
+	position: number,
+	color: ControlPoint[ 'color' ]
+) {
+	const nextIndex = points.findIndex(
+		( point ) => point.position > position
+	);
+	const newPoint = { color, position };
+	const newPoints = points.slice();
+	newPoints.splice( nextIndex - 1, 0, newPoint );
+	return newPoints;
+}
+
+/**
+ * Removes a control point from an array and returns the new array.
+ *
+ * @param points Array of control points.
+ * @param index  Index to remove.
+ *
+ * @return New array of control points.
+ */
+export function removeControlPoint( points: ControlPoint[], index: number ) {
+	return points.filter( ( _point, pointIndex ) => {
+		return pointIndex !== index;
+	} );
+}
+/**
+ * Updates a control point from an array and returns the new array.
+ *
+ * @param points   Array of control points.
+ * @param index    Index to update.
+ * @param newPoint New control point to replace the index.
+ *
+ * @return New array of control points.
+ */
+export function updateControlPoint(
+	points: ControlPoint[],
+	index: number,
+	newPoint: ControlPoint
+) {
+	const newValue = points.slice();
+	newValue[ index ] = newPoint;
+	return newValue;
+}
+
+/**
+ * Updates the position of a control point from an array and returns the new array.
+ *
+ * @param points      Array of control points.
+ * @param index       Index to update.
+ * @param newPosition Position to move the control point at index.
+ *
+ * @return New array of control points.
+ */
+export function updateControlPointPosition(
+	points: ControlPoint[],
+	index: number,
+	newPosition: ControlPoint[ 'position' ]
+) {
+	if ( isOverlapping( points, index, newPosition ) ) {
+		return points;
+	}
+	const newPoint = {
+		...points[ index ],
+		position: newPosition,
+	};
+	return updateControlPoint( points, index, newPoint );
+}
+
+/**
+ * Updates the position of a control point from an array and returns the new array.
+ *
+ * @param points   Array of control points.
+ * @param index    Index to update.
+ * @param newColor Color to update the control point at index.
+ *
+ * @return New array of control points.
+ */
+export function updateControlPointColor(
+	points: ControlPoint[],
+	index: number,
+	newColor: ControlPoint[ 'color' ]
+) {
+	const newPoint = {
+		...points[ index ],
+		color: newColor,
+	};
+	return updateControlPoint( points, index, newPoint );
+}
+
+/**
+ * Updates the position of a control point from an array and returns the new array.
+ *
+ * @param points   Array of control points.
+ * @param position Position of the color stop.
+ * @param newColor Color to update the control point at index.
+ *
+ * @return New array of control points.
+ */
+export function updateControlPointColorByPosition(
+	points: ControlPoint[],
+	position: ControlPoint[ 'position' ],
+	newColor: ControlPoint[ 'color' ]
+) {
+	const index = points.findIndex( ( point ) => point.position === position );
+	return updateControlPointColor( points, index, newColor );
+}
+
+/**
+ * Gets the horizontal coordinate when dragging a control point with the mouse.
+ *
+ * @param mouseXcoordinate Horizontal coordinate of the mouse position.
+ * @param containerElement Container for the gradient picker.
+ *
+ * @return Whole number percentage from the left.
+ */
+export function getHorizontalRelativeGradientPosition(
+	mouseXcoordinate: number,
+	containerElement: HTMLDivElement
+): number;
+export function getHorizontalRelativeGradientPosition(
+	mouseXcoordinate: number,
+	containerElement: null
+): undefined;
+export function getHorizontalRelativeGradientPosition(
+	mouseXCoordinate: number,
+	containerElement: HTMLDivElement | null
+) {
+	if ( ! containerElement ) {
+		return;
+	}
+	const { x, width } = containerElement.getBoundingClientRect();
+	const absolutePositionValue = mouseXCoordinate - x;
+	return Math.round(
+		clampPercent( ( absolutePositionValue * 100 ) / width )
+	);
+}

package/src/custom-gradient-picker/{index.js → index.tsx}

@@ -2,6 +2,7 @@
  * External dependencies
  */
 import classnames from 'classnames';
+import type gradientParser from 'gradient-parser';
 
 /**
  * WordPress dependencies
@@ -28,23 +29,31 @@ import {
 	DEFAULT_LINEAR_GRADIENT_ANGLE,
 	HORIZONTAL_GRADIENT_ORIENTATION,
 	GRADIENT_OPTIONS,
-	DEFAULT_GRADIENT,
 } from './constants';
 import {
 	AccessoryWrapper,
 	SelectWrapper,
 } from './styles/custom-gradient-picker-styles';
+import type {
+	CustomGradientPickerProps,
+	GradientAnglePickerProps,
+	GradientTypePickerProps,
+} from './types';
 
-const GradientAnglePicker = ( { gradientAST, hasGradient, onChange } ) => {
+const GradientAnglePicker = ( {
+	gradientAST,
+	hasGradient,
+	onChange,
+}: GradientAnglePickerProps ) => {
 	const angle =
 		gradientAST?.orientation?.value ?? DEFAULT_LINEAR_GRADIENT_ANGLE;
-	const onAngleChange = ( newAngle ) => {
+	const onAngleChange = ( newAngle: number ) => {
 		onChange(
 			serializeGradient( {
 				...gradientAST,
 				orientation: {
 					type: 'angular',
-					value: newAngle,
+					value: `${ newAngle }`,
 				},
 			} )
 		);
@@ -58,17 +67,22 @@ const GradientAnglePicker = ( { gradientAST, hasGradient, onChange } ) => {
 	);
 };
 
-const GradientTypePicker = ( { gradientAST, hasGradient, onChange } ) => {
+const GradientTypePicker = ( {
+	gradientAST,
+	hasGradient,
+	onChange,
+}: GradientTypePickerProps ) => {
 	const { type } = gradientAST;
+
 	const onSetLinearGradient = () => {
 		onChange(
 			serializeGradient( {
 				...gradientAST,
-				...( gradientAST.orientation
-					? {}
-					: { orientation: HORIZONTAL_GRADIENT_ORIENTATION } ),
+				orientation: gradientAST.orientation
+					? undefined
+					: HORIZONTAL_GRADIENT_ORIENTATION,
 				type: 'linear-gradient',
-			} )
+			} as gradientParser.LinearGradientNode )
 		);
 	};
 
@@ -82,7 +96,7 @@ const GradientTypePicker = ( { gradientAST, hasGradient, onChange } ) => {
 		);
 	};
 
-	const handleOnChange = ( next ) => {
+	const handleOnChange = ( next: string ) => {
 		if ( next === 'linear-gradient' ) {
 			onSetLinearGradient();
 		}
@@ -100,30 +114,57 @@ const GradientTypePicker = ( { gradientAST, hasGradient, onChange } ) => {
 			onChange={ handleOnChange }
 			options={ GRADIENT_OPTIONS }
 			size="__unstable-large"
-			value={ hasGradient && type }
+			value={ hasGradient ? type : undefined }
 		/>
 	);
 };
 
-export default function CustomGradientPicker( {
+/**
+ * CustomGradientPicker is a React component that renders a UI for specifying
+ * linear or radial gradients. Radial gradients are displayed in the picker as
+ * a slice of the gradient from the center to the outside.
+ *
+ * ```jsx
+ * import { CustomGradientPicker } from '@wordpress/components';
+ * import { useState } from '@wordpress/element';
+ *
+ * const MyCustomGradientPicker = () => {
+ *   const [ gradient, setGradient ] = useState();
+ *
+ *   return (
+ *     <CustomGradientPicker
+ *			value={ gradient }
+ *			onChange={ setGradient }
+ *     />
+ *   );
+ * };
+ * ```
+ */
+export function CustomGradientPicker( {
 	/** Start opting into the new margin-free styles that will become the default in a future version. */
 	__nextHasNoMargin = false,
 	value,
 	onChange,
-	__experimentalIsRenderedInSidebar,
-} ) {
-	const gradientAST = getGradientAstWithDefault( value );
+	__experimentalIsRenderedInSidebar = false,
+}: CustomGradientPickerProps ) {
+	const { gradientAST, hasGradient } = getGradientAstWithDefault( value );
+
 	// On radial gradients the bar should display a linear gradient.
 	// On radial gradients the bar represents a slice of the gradient from the center until the outside.
 	// On liner gradients the bar represents the color stops from left to right independently of the angle.
 	const background = getLinearGradientRepresentation( gradientAST );
-	const hasGradient = gradientAST.value !== DEFAULT_GRADIENT;
+
 	// Control points color option may be hex from presets, custom colors will be rgb.
 	// The position should always be a percentage.
-	const controlPoints = gradientAST.colorStops.map( ( colorStop ) => ( {
-		color: getStopCssColor( colorStop ),
-		position: parseInt( colorStop.length.value ),
-	} ) );
+	const controlPoints = gradientAST.colorStops.map( ( colorStop ) => {
+		return {
+			color: getStopCssColor( colorStop ),
+			// Although it's already been checked by `hasUnsupportedLength` in `getGradientAstWithDefault`,
+			// TypeScript doesn't know that `colorStop.length` is not undefined here.
+			// @ts-expect-error
+			position: parseInt( colorStop.length.value ),
+		};
+	} );
 
 	if ( ! __nextHasNoMargin ) {
 		deprecated(
@@ -185,3 +226,5 @@ export default function CustomGradientPicker( {
 		</VStack>
 	);
 }
+
+export default CustomGradientPicker;

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

@@ -0,0 +1,82 @@
+/**
+ * External dependencies
+ */
+import type gradientParser from 'gradient-parser';
+/**
+ * Internal dependencies
+ */
+import type { ColorStopTypeAndValue } from './types';
+
+export function serializeGradientColor( {
+	type,
+	value,
+}: ColorStopTypeAndValue ) {
+	if ( type === 'literal' ) {
+		return value;
+	}
+	if ( type === 'hex' ) {
+		return `#${ value }`;
+	}
+	return `${ type }(${ value.join( ',' ) })`;
+}
+
+export function serializeGradientPosition(
+	position: gradientParser.ColorStop[ 'length' ]
+) {
+	if ( ! position ) {
+		return '';
+	}
+	const { value, type } = position;
+	return `${ value }${ type }`;
+}
+
+export function serializeGradientColorStop( {
+	type,
+	value,
+	length,
+}: gradientParser.ColorStop ) {
+	return `${ serializeGradientColor( {
+		type,
+		value,
+	} as ColorStopTypeAndValue ) } ${ serializeGradientPosition( length ) }`;
+}
+
+export function serializeGradientOrientation(
+	orientation: gradientParser.GradientNode[ 'orientation' ]
+) {
+	if (
+		Array.isArray( orientation ) ||
+		! orientation ||
+		orientation.type !== 'angular'
+	) {
+		return;
+	}
+	return `${ orientation.value }deg`;
+}
+
+export function serializeGradient( {
+	type,
+	orientation,
+	colorStops,
+}: gradientParser.GradientNode ) {
+	const serializedOrientation = serializeGradientOrientation( orientation );
+	const serializedColorStops = colorStops
+		.sort( ( colorStop1, colorStop2 ) => {
+			const getNumericStopValue = (
+				colorStop: gradientParser.ColorStop
+			) => {
+				return colorStop?.length?.value === undefined
+					? 0
+					: parseInt( colorStop.length.value );
+			};
+
+			return (
+				getNumericStopValue( colorStop1 ) -
+				getNumericStopValue( colorStop2 )
+			);
+		} )
+		.map( serializeGradientColorStop );
+	return `${ type }(${ [ serializedOrientation, ...serializedColorStops ]
+		.filter( Boolean )
+		.join( ',' ) })`;
+}

package/src/custom-gradient-picker/stories/index.tsx

@@ -0,0 +1,45 @@
+/**
+ * External dependencies
+ */
+import type { ComponentMeta, ComponentStory } from '@storybook/react';
+/**
+ * WordPress dependencies
+ */
+import { useState } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import CustomGradientPicker from '../';
+
+const meta: ComponentMeta< typeof CustomGradientPicker > = {
+	title: 'Components/CustomGradientPicker',
+	component: CustomGradientPicker,
+	parameters: {
+		actions: { argTypesRegex: '^on.*' },
+		controls: { expanded: true },
+		docs: { source: { state: 'open' } },
+	},
+};
+export default meta;
+
+const CustomGradientPickerWithState: ComponentStory<
+	typeof CustomGradientPicker
+> = ( { onChange, ...props } ) => {
+	const [ gradient, setGradient ] = useState< string >();
+	return (
+		<CustomGradientPicker
+			{ ...props }
+			value={ gradient }
+			onChange={ ( newGradient ) => {
+				setGradient( newGradient );
+				onChange( newGradient );
+			} }
+		/>
+	);
+};
+
+export const Default = CustomGradientPickerWithState.bind( {} );
+Default.args = {
+	__nextHasNoMargin: true,
+};

package/src/custom-gradient-picker/style.scss

@@ -7,14 +7,30 @@ $components-custom-gradient-picker__padding: $grid-unit-20; // 48px container, 1
 	}
 }
 
-.components-custom-gradient-picker__gradient-bar:not(.has-gradient) {
-	opacity: 0.4;
-}
-
 .components-custom-gradient-picker__gradient-bar {
 	border-radius: $radius-block-ui;
 	width: 100%;
 	height: $grid-unit-60;
+	position: relative;
+	z-index: 1;
+
+	&.has-gradient {
+		// The background image creates a checkerboard pattern. Ignore rtlcss to
+		// make it work both in LTR and RTL.
+		// See https://github.com/WordPress/gutenberg/pull/42510
+		/*rtl:begin:ignore*/
+		background-image:
+			repeating-linear-gradient(45deg, $gray-200 25%, transparent 25%, transparent 75%, $gray-200 75%, $gray-200),
+			repeating-linear-gradient(45deg, $gray-200 25%, transparent 25%, transparent 75%, $gray-200 75%, $gray-200);
+		background-position: 0 0, 12px 12px;
+		/*rtl:end:ignore*/
+		background-size: calc(2 * 12px) calc(2 * 12px);
+	}
+
+	.components-custom-gradient-picker__gradient-bar-background {
+		position: absolute;
+		inset: 0;
+	}
 
 	.components-custom-gradient-picker__markers-container {
 		position: relative;
@@ -109,3 +125,8 @@ $components-custom-gradient-picker__padding: $grid-unit-20; // 48px container, 1
 		}
 	}
 }
+
+.components-custom-gradient-picker__ui-line {
+	position: relative;
+	z-index: 0;
+}

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

@@ -12,24 +12,30 @@ import {
 describe( 'It should serialize a gradient', () => {
 	test( 'serializeGradientColor', () => {
 		expect(
-			serializeGradientColor( { type: 'rgba', value: [ 1, 2, 3, 0.5 ] } )
+			serializeGradientColor( {
+				type: 'rgba',
+				value: [ '1', '2', '3', '0.5' ],
+			} )
 		).toBe( 'rgba(1,2,3,0.5)' );
 
 		expect(
-			serializeGradientColor( { type: 'rgb', value: [ 255, 0, 0 ] } )
+			serializeGradientColor( {
+				type: 'rgb',
+				value: [ '255', '0', '0' ],
+			} )
 		).toBe( 'rgb(255,0,0)' );
 	} );
 
 	test( 'serializeGradientPosition', () => {
-		expect( serializeGradientPosition( { type: '%', value: 70 } ) ).toBe(
+		expect( serializeGradientPosition( { type: '%', value: '70' } ) ).toBe(
 			'70%'
 		);
 
-		expect( serializeGradientPosition( { type: '%', value: 0 } ) ).toBe(
+		expect( serializeGradientPosition( { type: '%', value: '0' } ) ).toBe(
 			'0%'
 		);
 
-		expect( serializeGradientPosition( { type: 'px', value: 4 } ) ).toBe(
+		expect( serializeGradientPosition( { type: 'px', value: '4' } ) ).toBe(
 			'4px'
 		);
 	} );
@@ -38,35 +44,35 @@ describe( 'It should serialize a gradient', () => {
 		expect(
 			serializeGradientColorStop( {
 				type: 'rgba',
-				value: [ 1, 2, 3, 0.5 ],
-				length: { type: '%', value: 70 },
+				value: [ '1', '2', '3', '0.5' ],
+				length: { type: '%', value: '70' },
 			} )
 		).toBe( 'rgba(1,2,3,0.5) 70%' );
 
 		expect(
 			serializeGradientColorStop( {
 				type: 'rgb',
-				value: [ 255, 0, 0 ],
-				length: { type: '%', value: 0 },
+				value: [ '255', '0', '0' ],
+				length: { type: '%', value: '0' },
 			} )
 		).toBe( 'rgb(255,0,0) 0%' );
 
 		expect(
 			serializeGradientColorStop( {
 				type: 'rgba',
-				value: [ 1, 2, 3, 0.5 ],
-				length: { type: 'px', value: 100 },
+				value: [ '1', '2', '3', '0.5' ],
+				length: { type: 'px', value: '100' },
 			} )
 		).toBe( 'rgba(1,2,3,0.5) 100px' );
 	} );
 
 	test( 'serializeGradientOrientation', () => {
 		expect(
-			serializeGradientOrientation( { type: 'angular', value: 40 } )
+			serializeGradientOrientation( { type: 'angular', value: '40' } )
 		).toBe( '40deg' );
 
 		expect(
-			serializeGradientOrientation( { type: 'angular', value: 0 } )
+			serializeGradientOrientation( { type: 'angular', value: '0' } )
 		).toBe( '0deg' );
 	} );
 
@@ -74,17 +80,17 @@ describe( 'It should serialize a gradient', () => {
 		expect(
 			serializeGradient( {
 				type: 'linear-gradient',
-				orientation: { type: 'angular', value: 40 },
+				orientation: { type: 'angular', value: '40' },
 				colorStops: [
 					{
 						type: 'rgba',
-						value: [ 1, 2, 3, 0.5 ],
-						length: { type: '%', value: 70 },
+						value: [ '1', '2', '3', '0.5' ],
+						length: { type: '%', value: '70' },
 					},
 					{
 						type: 'rgba',
-						value: [ 255, 1, 1, 0.9 ],
-						length: { type: '%', value: 40 },
+						value: [ '255', '1', '1', '0.9' ],
+						length: { type: '%', value: '40' },
 					},
 				],
 			} )
@@ -98,13 +104,13 @@ describe( 'It should serialize a gradient', () => {
 				colorStops: [
 					{
 						type: 'rgba',
-						value: [ 1, 2, 3, 0.5 ],
-						length: { type: '%', value: 70 },
+						value: [ '1', '2', '3', '0.5' ],
+						length: { type: '%', value: '70' },
 					},
 					{
 						type: 'rgba',
-						value: [ 255, 1, 1, 0.9 ],
-						length: { type: '%', value: 40 },
+						value: [ '255', '1', '1', '0.9' ],
+						length: { type: '%', value: '40' },
 					},
 				],
 			} )
@@ -117,12 +123,12 @@ describe( 'It should serialize a gradient', () => {
 					{
 						type: 'hex',
 						value: '000',
-						length: { type: '%', value: 70 },
+						length: { type: '%', value: '70' },
 					},
 					{
 						type: 'hex',
 						value: 'fff',
-						length: { type: '%', value: 40 },
+						length: { type: '%', value: '40' },
 					},
 				],
 			} )
@@ -131,27 +137,27 @@ describe( 'It should serialize a gradient', () => {
 		expect(
 			serializeGradient( {
 				type: 'linear-gradient',
-				orientation: { type: 'angular', value: 0 },
+				orientation: { type: 'angular', value: '0' },
 				colorStops: [
 					{
 						type: 'rgba',
-						value: [ 1, 2, 3, 0.5 ],
-						length: { type: '%', value: 0 },
+						value: [ '1', '2', '3', '0.5' ],
+						length: { type: '%', value: '0' },
 					},
 					{
 						type: 'rgba',
-						value: [ 255, 1, 1, 0.9 ],
-						length: { type: '%', value: 40 },
+						value: [ '255', '1', '1', '0.9' ],
+						length: { type: '%', value: '40' },
 					},
 					{
 						type: 'rgba',
-						value: [ 1, 2, 3, 0.5 ],
-						length: { type: '%', value: 100 },
+						value: [ '1', '2', '3', '0.5' ],
+						length: { type: '%', value: '100' },
 					},
 					{
 						type: 'rgba',
-						value: [ 10, 20, 30, 0.5 ],
-						length: { type: '%', value: 20 },
+						value: [ '10', '20', '30', '0.5' ],
+						length: { type: '%', value: '20' },
 					},
 				],
 			} )