@wordpress/components 23.6.0 → 23.8.0

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
 

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 );
@@ -716,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/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;

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

@@ -44,6 +44,7 @@ const FormTokenFieldWithState = ( {
 				setSelectedValue( tokens );
 				onChange?.( tokens );
 			} }
+			__nextHasNoMarginBottom
 		/>
 	);
 };

package/src/form-token-field/types.ts

@@ -169,6 +169,12 @@ export interface FormTokenFieldProps
 	 * Custom renderer for suggestions.
 	 */
 	__experimentalRenderItem?: ( args: { item: string } ) => ReactNode;
+	/**
+	 * Start opting into the new margin-free styles that will become the default in a future version.
+	 *
+	 * @default false
+	 */
+	__nextHasNoMarginBottom?: boolean;
 }
 
 /**

package/src/gradient-picker/README.md

@@ -49,63 +49,56 @@ const myGradientPicker = () => {
 
 The component accepts the following props:
 
-### value
+### `className`: `string`
+
+The class name added to the wrapper.
+
+-   Required: No
+
+### `value`: `string`
 
 The current value of the gradient. Pass a css gradient like `linear-gradient(90deg, rgb(6, 147, 227) 0%, rgb(155, 81, 224) 100%)`. Optionally pass in a `null` value to specify no gradient is currently selected.
 
--   Type: `string`
 -   Required: No
 -   Default: `linear-gradient(90deg, rgb(6, 147, 227) 0%, rgb(155, 81, 224) 100%)`
 
-### onChange
+### `onChange`: `( currentGradient: string | undefined ) => void`
 
 The function called when a new gradient has been defined. It is passed the `currentGradient` as an argument.
 
--   Type: `Function`
 -   Required: Yes
 
-### gradients
+### `gradients`: `GradientsProp[]`
 
-An array of objects of predefined gradients which show up as `CircularOptionPicker` above the gradient selector.
+An array of objects of predefined gradients displayed above the gradient selector.
 
--   Type: `array`
 -   Required: No
+-   Default: `[]`
 
-### clearable
+### `clearable`: `boolean`
 
 Whether the palette should have a clearing button or not.
 
--   Type: `Boolean`
 -   Required: No
 -   Default: true
 
-### clearGradient
-
-Called when a new gradient has been defined. It is passed the `currentGradient` as an argument.
-
--   Type: `Function`
--   Required: No
-
-### disableCustomGradients
+### `disableCustomGradients`: `boolean`
 
 If true, the gradient picker will not be displayed and only defined gradients from `gradients` are available.
 
--   Type: `Boolean`
 -   Required: No
 -   Default: false
 
-### __nextHasNoMargin
+### `__nextHasNoMargin`: `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`
 
-### headingLevel
+### `headingLevel`: `1 | 2 | 3 | 4 | 5 | 6 | '1' | '2' | '3' | '4' | '5' | '6'`
 
-The heading level.
+The heading level. Only applies in cases where gradients are provided from multiple origins (ie. when the array passed as the `gradients` prop contains two or more items).
 
--   Type: `1 | 2 | 3 | 4 | 5 | 6 | '1' | '2' | '3' | '4' | '5' | '6'`
 -   Required: No
 -   Default: `2`

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

@@ -1,5 +1,3 @@
-// @ts-nocheck
-
 /**
  * WordPress dependencies
  */
@@ -15,13 +13,21 @@ import CustomGradientPicker from '../custom-gradient-picker';
 import { VStack } from '../v-stack';
 import { ColorHeading } from '../color-palette/styles';
 import { Spacer } from '../spacer';
+import type {
+	GradientPickerComponentProps,
+	PickerProps,
+	OriginObject,
+	GradientObject,
+} from './types';
 
 // The Multiple Origin Gradients have a `gradients` property (an array of
 // gradient objects), while Single Origin ones have a `gradient` property.
-const isMultipleOriginObject = ( obj ) =>
+const isMultipleOriginObject = (
+	obj: Record< string, any >
+): obj is OriginObject =>
 	Array.isArray( obj.gradients ) && ! ( 'gradient' in obj );
 
-const isMultipleOriginArray = ( arr ) => {
+const isMultipleOriginArray = ( arr: any[] ): arr is OriginObject[] => {
 	return (
 		arr.length > 0 &&
 		arr.every( ( gradientObj ) => isMultipleOriginObject( gradientObj ) )
@@ -35,7 +41,7 @@ function SingleOrigin( {
 	onChange,
 	value,
 	actions,
-} ) {
+}: PickerProps< GradientObject > ) {
 	const gradientOptions = useMemo( () => {
 		return gradients.map( ( { gradient, name }, index ) => (
 			<CircularOptionPicker.Option
@@ -80,7 +86,7 @@ function MultipleOrigin( {
 	value,
 	actions,
 	headingLevel,
-} ) {
+}: PickerProps< OriginObject > ) {
 	return (
 		<VStack spacing={ 3 } className={ className }>
 			{ gradients.map( ( { name, gradients: gradientSet }, index ) => {
@@ -107,25 +113,72 @@ function MultipleOrigin( {
 	);
 }
 
-export default function GradientPicker( {
+function Component( props: PickerProps< any > ) {
+	if ( isMultipleOriginArray( props.gradients ) ) {
+		return <MultipleOrigin { ...props } />;
+	}
+	return <SingleOrigin { ...props } />;
+}
+
+/**
+ *  GradientPicker is a React component that renders a color gradient picker to
+ * define a multi step gradient. There's either a _linear_ or a _radial_ type
+ * available.
+ *
+ * ```jsx
+ *import { GradientPicker } from '@wordpress/components';
+ *import { useState } from '@wordpress/element';
+ *
+ *const myGradientPicker = () => {
+ *	const [ gradient, setGradient ] = useState( null );
+ *
+ *	return (
+ *		<GradientPicker
+ *			__nextHasNoMargin
+ *			value={ gradient }
+ *			onChange={ ( currentGradient ) => setGradient( currentGradient ) }
+ *			gradients={ [
+ *				{
+ *					name: 'JShine',
+ *					gradient:
+ *						'linear-gradient(135deg,#12c2e9 0%,#c471ed 50%,#f64f59 100%)',
+ *					slug: 'jshine',
+ *				},
+ *				{
+ *					name: 'Moonlit Asteroid',
+ *					gradient:
+ *						'linear-gradient(135deg,#0F2027 0%, #203A43 0%, #2c5364 100%)',
+ *					slug: 'moonlit-asteroid',
+ *				},
+ *				{
+ *					name: 'Rastafarie',
+ *					gradient:
+ *						'linear-gradient(135deg,#1E9600 0%, #FFF200 0%, #FF0000 100%)',
+ *					slug: 'rastafari',
+ *				},
+ *			] }
+ *		/>
+ *	);
+ *};
+ *```
+ *
+ */
+export function GradientPicker( {
 	/** Start opting into the new margin-free styles that will become the default in a future version. */
 	__nextHasNoMargin = false,
 	className,
-	gradients,
+	gradients = [],
 	onChange,
 	value,
 	clearable = true,
 	disableCustomGradients = false,
 	__experimentalIsRenderedInSidebar,
 	headingLevel = 2,
-} ) {
+}: GradientPickerComponentProps ) {
 	const clearGradient = useCallback(
 		() => onChange( undefined ),
 		[ onChange ]
 	);
-	const Component = isMultipleOriginArray( gradients )
-		? MultipleOrigin
-		: SingleOrigin;
 
 	if ( ! __nextHasNoMargin ) {
 		deprecated( 'Outer margin styles for wp.components.GradientPicker', {
@@ -137,7 +190,7 @@ export default function GradientPicker( {
 
 	const deprecatedMarginSpacerProps = ! __nextHasNoMargin
 		? {
-				marginTop: ! gradients?.length ? 3 : undefined,
+				marginTop: ! gradients.length ? 3 : undefined,
 				marginBottom: ! clearable ? 6 : 0,
 		  }
 		: {};
@@ -145,7 +198,7 @@ export default function GradientPicker( {
 	return (
 		// Outmost Spacer wrapper can be removed when deprecation period is over
 		<Spacer marginBottom={ 0 } { ...deprecatedMarginSpacerProps }>
-			<VStack spacing={ gradients?.length ? 4 : 0 }>
+			<VStack spacing={ gradients.length ? 4 : 0 }>
 				{ ! disableCustomGradients && (
 					<CustomGradientPicker
 						__nextHasNoMargin
@@ -156,10 +209,9 @@ export default function GradientPicker( {
 						onChange={ onChange }
 					/>
 				) }
-				{ ( gradients?.length || clearable ) && (
+				{ ( gradients.length || clearable ) && (
 					<Component
 						className={ className }
-						clearable={ clearable }
 						clearGradient={ clearGradient }
 						gradients={ gradients }
 						onChange={ onChange }
@@ -181,3 +233,5 @@ export default function GradientPicker( {
 		</Spacer>
 	);
 }
+
+export default GradientPicker;

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

@@ -1,3 +1,7 @@
+/**
+ * External dependencies
+ */
+import type { ComponentMeta, ComponentStory } from '@storybook/react';
 /**
  * WordPress dependencies
  */
@@ -6,18 +10,21 @@ import { useState } from '@wordpress/element';
 /**
  * Internal dependencies
  */
-import GradientPicker from '../';
+import GradientPicker from '..';
 
-export default {
+const meta: ComponentMeta< typeof GradientPicker > = {
 	title: 'Components/GradientPicker',
 	component: GradientPicker,
+	parameters: {
+		controls: { expanded: true },
+		docs: { source: { state: 'open' } },
+		actions: { argTypesRegex: '^on.*' },
+	},
 	argTypes: {
-		__nextHasNoMargin: { control: { type: 'boolean' } },
-		clearable: { control: { type: 'boolean' } },
-		disableCustomGradients: { control: { type: 'boolean' } },
-		onChange: { action: 'onChange' },
+		value: { control: { type: null } },
 	},
 };
+export default meta;
 
 const GRADIENTS = [
 	{
@@ -58,8 +65,12 @@ const GRADIENTS = [
 	},
 ];
 
-const Template = ( { onChange, ...props } ) => {
-	const [ gradient, setGradient ] = useState();
+const Template: ComponentStory< typeof GradientPicker > = ( {
+	onChange,
+	...props
+} ) => {
+	const [ gradient, setGradient ] =
+		useState< ( typeof props )[ 'value' ] >( null );
 	return (
 		<GradientPicker
 			{ ...props }