@wordpress/components 37.0.1-next.v.202607070741.0 → 39.0.0

package/src/gradient-picker/index.tsx

@@ -1,13 +1,6 @@
-/**
- * WordPress dependencies
- */
 import { __, sprintf } from '@wordpress/i18n';
 import { useInstanceId } from '@wordpress/compose';
 import { useCallback, useMemo } from '@wordpress/element';
-
-/**
- * Internal dependencies
- */
 import CircularOptionPicker, {
 	getComputeCircularOptionPickerCommonProps,
 } from '../circular-option-picker';
@@ -41,35 +34,48 @@ function SingleOrigin( {
 	gradients,
 	onChange,
 	value,
+	selectedSlug,
 	...additionalProps
 }: PickerProps< GradientObject > ) {
 	const gradientOptions = useMemo( () => {
-		return gradients.map( ( { gradient, name, slug }, index ) => (
-			<CircularOptionPicker.Option
-				key={ slug }
-				value={ gradient }
-				isSelected={ value === gradient }
-				tooltipText={
-					name ||
-					// translators: %s: gradient code e.g: "linear-gradient(90deg, rgba(98,16,153,1) 0%, rgba(172,110,22,1) 100%);".
-					sprintf( __( 'Gradient code: %s' ), gradient )
-				}
-				style={ { color: 'rgba( 0,0,0,0 )', background: gradient } }
-				onClick={
-					value === gradient
-						? clearGradient
-						: () => onChange( gradient, index )
-				}
-				aria-label={
-					name
-						? // translators: %s: The name of the gradient e.g: "Angular red to blue".
-						  sprintf( __( 'Gradient: %s' ), name )
-						: // translators: %s: gradient code e.g: "linear-gradient(90deg, rgba(98,16,153,1) 0%, rgba(172,110,22,1) 100%);".
-						  sprintf( __( 'Gradient code: %s' ), gradient )
-				}
-			/>
-		) );
-	}, [ gradients, value, onChange, clearGradient ] );
+		return gradients.map( ( { gradient, name, slug }, index ) => {
+			// When a non-empty selectedSlug is provided, selection is decided
+			// strictly by slug, which keeps two entries with the same gradient
+			// value apart. Otherwise selection falls back to matching the
+			// gradient value.
+			const isSelected = selectedSlug
+				? slug === selectedSlug
+				: value === gradient;
+			return (
+				<CircularOptionPicker.Option
+					key={ slug }
+					value={ gradient }
+					isSelected={ isSelected }
+					tooltipText={
+						name ||
+						// translators: %s: gradient code e.g: "linear-gradient(90deg, rgba(98,16,153,1) 0%, rgba(172,110,22,1) 100%);".
+						sprintf( __( 'Gradient code: %s' ), gradient )
+					}
+					style={ {
+						color: 'rgba( 0,0,0,0 )',
+						background: gradient,
+					} }
+					onClick={
+						isSelected
+							? clearGradient
+							: () => onChange( gradient, index, slug )
+					}
+					aria-label={
+						name
+							? // translators: %s: The name of the gradient e.g: "Angular red to blue".
+							  sprintf( __( 'Gradient: %s' ), name )
+							: // translators: %s: gradient code e.g: "linear-gradient(90deg, rgba(98,16,153,1) 0%, rgba(172,110,22,1) 100%);".
+							  sprintf( __( 'Gradient code: %s' ), gradient )
+					}
+				/>
+			);
+		} );
+	}, [ gradients, value, onChange, clearGradient, selectedSlug ] );
 	return (
 		<CircularOptionPicker.OptionGroup
 			className={ className }
@@ -85,6 +91,7 @@ function MultipleOrigin( {
 	gradients,
 	onChange,
 	value,
+	selectedSlug,
 	headingLevel,
 }: PickerProps< OriginObject > ) {
 	const instanceId = useInstanceId( MultipleOrigin );
@@ -101,10 +108,11 @@ function MultipleOrigin( {
 						<SingleOrigin
 							clearGradient={ clearGradient }
 							gradients={ gradientSet }
-							onChange={ ( gradient ) =>
-								onChange( gradient, index )
+							onChange={ ( gradient, _index, slug ) =>
+								onChange( gradient, index, slug )
 							}
 							value={ value }
+							selectedSlug={ selectedSlug }
 							aria-labelledby={ id }
 						/>
 					</VStack>

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

@@ -1,17 +1,6 @@
-/**
- * External dependencies
- */
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import { fn } from 'storybook/test';
-
-/**
- * WordPress dependencies
- */
 import { useState } from '@wordpress/element';
-
-/**
- * Internal dependencies
- */
 import GradientPicker from '..';
 
 const meta: Meta< typeof GradientPicker > = {
@@ -31,6 +20,7 @@ const meta: Meta< typeof GradientPicker > = {
 		onChange: fn(),
 	},
 	argTypes: {
+		selectedSlug: { control: false },
 		value: { control: false },
 	},
 };
@@ -91,17 +81,23 @@ const GRADIENTS = [
 
 const Template = ( {
 	onChange,
+	value,
+	selectedSlug,
 	...props
 }: React.ComponentProps< typeof GradientPicker > ) => {
-	const [ gradient, setGradient ] =
-		useState< ( typeof props )[ 'value' ] >( null );
+	const [ gradient, setGradient ] = useState<
+		React.ComponentProps< typeof GradientPicker >[ 'value' ]
+	>( value ?? null );
+	const [ slug, setSlug ] = useState< string | undefined >( selectedSlug );
 	return (
 		<GradientPicker
 			{ ...props }
 			value={ gradient }
-			onChange={ ( ...changeArgs ) => {
-				setGradient( ...changeArgs );
-				onChange?.( ...changeArgs );
+			selectedSlug={ slug }
+			onChange={ ( currentGradient, index, newSlug ) => {
+				setGradient( currentGradient );
+				setSlug( newSlug );
+				onChange?.( currentGradient, index, newSlug );
 			} }
 		/>
 	);
@@ -121,6 +117,35 @@ export const WithNoExistingGradients: GradientPickerStory = {
 	},
 };
 
+export const DuplicateGradients: GradientPickerStory = {
+	render: Template,
+	args: {
+		gradients: [
+			{
+				name: 'Dark Background',
+				slug: 'dark-background',
+				gradient:
+					'linear-gradient(135deg,rgba(6,147,227,1) 0%,rgb(155,81,224) 100%)',
+			},
+			{
+				name: 'Dark Text',
+				slug: 'dark-text',
+				gradient:
+					'linear-gradient(135deg,rgba(6,147,227,1) 0%,rgb(155,81,224) 100%)',
+			},
+			{
+				name: 'Brand',
+				slug: 'brand',
+				gradient:
+					'linear-gradient(135deg,rgb(122,220,180) 0%,rgb(0,208,130) 100%)',
+			},
+		],
+		value: 'linear-gradient(135deg,rgba(6,147,227,1) 0%,rgb(155,81,224) 100%)',
+		selectedSlug: 'dark-text',
+		disableCustomGradients: true,
+	},
+};
+
 export const MultipleOrigins: GradientPickerStory = {
 	render: Template,
 	args: {

package/src/gradient-picker/test/index.tsx

@@ -0,0 +1,141 @@
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import GradientPicker from '..';
+
+const GRADIENT_A =
+	'linear-gradient(135deg,rgba(6,147,227,1) 0%,rgb(155,81,224) 100%)';
+const GRADIENT_B =
+	'linear-gradient(135deg,rgb(122,220,180) 0%,rgb(0,208,130) 100%)';
+
+const DUPLICATE_GRADIENTS = [
+	{ name: 'Dark Background', slug: 'dark-background', gradient: GRADIENT_A },
+	{ name: 'Dark Text', slug: 'dark-text', gradient: GRADIENT_A },
+];
+
+describe( 'GradientPicker', () => {
+	describe( 'duplicate gradients in palette', () => {
+		it( 'should render all swatches even when two entries share the same gradient value', () => {
+			render(
+				<GradientPicker
+					aria-label="Gradient"
+					gradients={ DUPLICATE_GRADIENTS }
+					value={ undefined }
+					onChange={ jest.fn() }
+					disableCustomGradients
+				/>
+			);
+
+			expect( screen.getAllByRole( 'option' ) ).toHaveLength( 2 );
+		} );
+
+		it( 'should select by slug when selectedSlug is provided, marking only the matching entry', () => {
+			render(
+				<GradientPicker
+					aria-label="Gradient"
+					gradients={ DUPLICATE_GRADIENTS }
+					value={ GRADIENT_A }
+					selectedSlug="dark-text"
+					onChange={ jest.fn() }
+					disableCustomGradients
+				/>
+			);
+
+			const options = screen.getAllByRole( 'option' );
+			// "dark-background" is index 0, "dark-text" is index 1.
+			expect( options[ 0 ] ).toHaveAttribute( 'aria-selected', 'false' );
+			expect( options[ 1 ] ).toHaveAttribute( 'aria-selected', 'true' );
+		} );
+
+		it( 'should fall back to value selection and mark all matching duplicates when no selectedSlug is provided', () => {
+			render(
+				<GradientPicker
+					aria-label="Gradient"
+					gradients={ DUPLICATE_GRADIENTS }
+					value={ GRADIENT_A }
+					onChange={ jest.fn() }
+					disableCustomGradients
+				/>
+			);
+
+			const options = screen.getAllByRole( 'option' );
+			expect( options[ 0 ] ).toHaveAttribute( 'aria-selected', 'true' );
+			expect( options[ 1 ] ).toHaveAttribute( 'aria-selected', 'true' );
+		} );
+
+		it( 'should treat an empty-string selectedSlug as no slug and fall back to value selection', () => {
+			render(
+				<GradientPicker
+					aria-label="Gradient"
+					gradients={ DUPLICATE_GRADIENTS }
+					value={ GRADIENT_A }
+					selectedSlug=""
+					onChange={ jest.fn() }
+					disableCustomGradients
+				/>
+			);
+
+			const options = screen.getAllByRole( 'option' );
+			expect( options[ 0 ] ).toHaveAttribute( 'aria-selected', 'true' );
+			expect( options[ 1 ] ).toHaveAttribute( 'aria-selected', 'true' );
+		} );
+
+		it( 'should pass slug as third argument to onChange when a swatch is clicked', async () => {
+			const user = userEvent.setup();
+			const onChange = jest.fn();
+
+			render(
+				<GradientPicker
+					aria-label="Gradient"
+					gradients={ DUPLICATE_GRADIENTS }
+					value={ undefined }
+					onChange={ onChange }
+					disableCustomGradients
+				/>
+			);
+
+			await user.click(
+				screen.getByRole( 'option', { name: 'Gradient: Dark Text' } )
+			);
+
+			expect( onChange ).toHaveBeenCalledWith(
+				GRADIENT_A,
+				1,
+				'dark-text'
+			);
+		} );
+
+		it( 'should pass slug as third argument to onChange for multiple-origin gradients', async () => {
+			const user = userEvent.setup();
+			const onChange = jest.fn();
+
+			render(
+				<GradientPicker
+					aria-label="Gradient"
+					gradients={ [
+						{
+							name: 'Theme',
+							gradients: [
+								{
+									name: 'Blush',
+									slug: 'blush',
+									gradient: GRADIENT_B,
+								},
+							],
+						},
+					] }
+					value={ undefined }
+					onChange={ onChange }
+					disableCustomGradients
+				/>
+			);
+
+			await user.click(
+				screen.getByRole( 'option', { name: 'Gradient: Blush' } )
+			);
+
+			// The second argument is the origin index, mirroring the existing
+			// multiple-origin behavior.
+			expect( onChange ).toHaveBeenCalledWith( GRADIENT_B, 0, 'blush' );
+		} );
+	} );
+} );

package/src/gradient-picker/types.ts

@@ -1,6 +1,3 @@
-/**
- * Internal dependencies
- */
 import type { HeadingSize } from '../heading/types';
 
 export type GradientObject = {
@@ -17,10 +14,16 @@ type GradientPickerBaseProps = {
 	 */
 	className?: string;
 	/**
-	 * The function called when a new gradient has been defined. It is passed to
-	 * the `currentGradient` as an argument.
+	 * The function called when a new gradient has been defined. It is passed
+	 * the `currentGradient` as an argument. When a predefined gradient is
+	 * selected, the second argument is its index (or, for multiple-origin
+	 * gradients, the origin index) and the third argument is its slug.
 	 */
-	onChange: ( currentGradient: string | undefined ) => void;
+	onChange: (
+		currentGradient: string | undefined,
+		index?: number,
+		slug?: string
+	) => void;
 	/**
 	 * 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.
@@ -28,6 +31,19 @@ type GradientPickerBaseProps = {
 	 * @default 'linear-gradient(135deg,rgba(6,147,227,1) 0%,rgb(155,81,224) 100%)'
 	 */
 	value?: GradientObject[ 'gradient' ] | null;
+	/**
+	 * The slug of the currently selected predefined gradient.
+	 *
+	 * When set to a non-empty string, selection is determined by slug rather
+	 * than by gradient value, which correctly handles palettes where two
+	 * entries share the same gradient. Entries whose slug does not match will
+	 * not appear selected in this mode, even if their gradient value matches
+	 * `value`.
+	 *
+	 * An empty string is treated the same as `undefined`: selection falls
+	 * back to matching by gradient value.
+	 */
+	selectedSlug?: string;
 	/**
 	 * Whether the palette should have a clearing button or not.
 	 *
@@ -121,7 +137,8 @@ export type PickerProps< TOriginType extends GradientObject | OriginObject > =
 		clearGradient: () => void;
 		onChange: (
 			currentGradient: string | undefined,
-			index: number
+			index: number,
+			slug?: string
 		) => void;
 		actions?: React.ReactNode;
 		gradients: TOriginType[];

package/src/grid/README.md

@@ -1,8 +1,6 @@
 # Grid
 
-<div class="callout callout-alert">
-This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
-</div>
+<p class="callout callout-alert">This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.</p>
 
 `Grid` is a primitive layout component that can arrange content in a grid configuration.
 

package/src/grid/component.tsx

@@ -1,11 +1,4 @@
-/**
- * External dependencies
- */
 import type { ForwardedRef } from 'react';
-
-/**
- * Internal dependencies
- */
 import type { WordPressComponentProps } from '../context';
 import { contextConnect } from '../context';
 import { View } from '../view';

package/src/grid/hook.ts

@@ -1,16 +1,5 @@
-/**
- * External dependencies
- */
 import { css } from '@emotion/react';
-
-/**
- * WordPress dependencies
- */
 import { useMemo } from '@wordpress/element';
-
-/**
- * Internal dependencies
- */
 import type { WordPressComponentProps } from '../context';
 import { useContextSystem } from '../context';
 import { getAlignmentProps } from './utils';

package/src/grid/stories/index.story.tsx

@@ -1,11 +1,4 @@
-/**
- * External dependencies
- */
 import type { Meta, StoryFn } from '@storybook/react-vite';
-
-/**
- * Internal dependencies
- */
 import { View } from '../../view';
 import { Grid } from '..';
 

package/src/grid/test/grid.tsx

@@ -1,11 +1,4 @@
-/**
- * External dependencies
- */
 import { render, screen } from '@testing-library/react';
-
-/**
- * Internal dependencies
- */
 import { View } from '../../view';
 import { Grid } from '..';
 import CONFIG from '../../utils/config-values';

package/src/grid/types.ts

@@ -1,11 +1,4 @@
-/**
- * External dependencies
- */
 import type { CSSProperties, ReactNode } from 'react';
-
-/**
- * Internal dependencies
- */
 import type { ResponsiveCSSValue } from '../utils/types';
 
 type GridAlignment =

package/src/grid/utils.ts

@@ -1,6 +1,3 @@
-/**
- * External dependencies
- */
 import type { CSSProperties } from 'react';
 
 const ALIGNMENTS = {

package/src/guide/icons.tsx

@@ -1,6 +1,3 @@
-/**
- * WordPress dependencies
- */
 import { SVG, Circle } from '@wordpress/primitives';
 
 export const PageControlIcon = () => (

package/src/guide/index.tsx

@@ -1,18 +1,7 @@
-/**
- * External dependencies
- */
 import clsx from 'clsx';
-
-/**
- * WordPress dependencies
- */
 import { useState, useEffect, Children, useRef } from '@wordpress/element';
 import deprecated from '@wordpress/deprecated';
 import { __ } from '@wordpress/i18n';
-
-/**
- * Internal dependencies
- */
 import Modal from '../modal';
 import Button from '../button';
 import PageControl from './page-control';

package/src/guide/page-control.tsx

@@ -1,11 +1,4 @@
-/**
- * WordPress dependencies
- */
 import { __, sprintf } from '@wordpress/i18n';
-
-/**
- * Internal dependencies
- */
 import Button from '../button';
 import { PageControlIcon } from './icons';
 import type { PageControlProps } from './types';

package/src/guide/page.tsx

@@ -1,12 +1,5 @@
-/**
- * WordPress dependencies
- */
 import { useEffect } from '@wordpress/element';
 import deprecated from '@wordpress/deprecated';
-
-/**
- * Internal dependencies
- */
 import type { WordPressComponentProps } from '../context';
 
 export default function GuidePage(

package/src/guide/stories/index.story.tsx

@@ -1,16 +1,5 @@
-/**
- * External dependencies
- */
 import type { Meta, StoryFn } from '@storybook/react-vite';
-
-/**
- * WordPress dependencies
- */
 import { useState } from '@wordpress/element';
-
-/**
- * Internal dependencies
- */
 import Button from '../../button';
 import Guide from '..';
 

package/src/guide/test/index.tsx

@@ -1,12 +1,5 @@
-/**
- * External dependencies
- */
 import { render, screen, within } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
-
-/**
- * Internal dependencies
- */
 import Guide from '..';
 
 const defaultProps = {

package/src/guide/types.ts

@@ -1,11 +1,4 @@
-/**
- * External dependencies
- */
 import type { ReactNode } from 'react';
-
-/**
- * Internal dependencies
- */
 import type { ModalProps } from '../modal/types';
 
 export type Page = {

package/src/h-stack/README.md

@@ -1,8 +1,6 @@
 # HStack
 
-<div class="callout callout-alert">
-This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
-</div>
+<p class="callout callout-alert">This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.</p>
 
 `HStack` (Horizontal Stack) arranges child elements in a horizontal line.
 

package/src/h-stack/component.tsx

@@ -1,6 +1,3 @@
-/**
- * Internal dependencies
- */
 import type { WordPressComponentProps } from '../context';
 import { contextConnect } from '../context';
 import { View } from '../view';

package/src/h-stack/hook.tsx

@@ -1,11 +1,4 @@
-/**
- * External dependencies
- */
 import type { ReactElement } from 'react';
-
-/**
- * Internal dependencies
- */
 import type { WordPressComponentProps } from '../context';
 import { hasConnectNamespace, useContextSystem } from '../context';
 import { FlexItem, useFlex } from '../flex';

package/src/h-stack/stories/e2e/index.story.tsx

@@ -1,11 +1,4 @@
-/**
- * External dependencies
- */
 import type { StoryFn, Meta } from '@storybook/react-vite';
-
-/**
- * Internal dependencies
- */
 import { View } from '../../../view';
 import { HStack } from '../..';
 

package/src/h-stack/stories/index.story.tsx

@@ -1,10 +1,4 @@
-/**
- * External dependencies
- */
 import type { StoryFn, Meta } from '@storybook/react-vite';
-/**
- * Internal dependencies
- */
 import { View } from '../../view';
 import { HStack } from '..';
 
@@ -77,7 +71,7 @@ const meta: Meta< typeof HStack > = {
 		componentStatus: {
 			status: 'not-recommended',
 			whereUsed: 'global',
-			notes: 'Use `Stack` from `@wordpress/ui` instead.',
+			notes: 'Use [`Stack`](?path=/docs/design-system-components-stack--docs) from `@wordpress/ui` instead.',
 		},
 	},
 };

package/src/h-stack/test/__snapshots__/index.tsx.snap

@@ -1,4 +1,4 @@
-// Jest Snapshot v1, https://goo.gl/fbAQLP
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
 
 exports[`props should render alignment 1`] = `
 <div>

package/src/h-stack/test/index.tsx

@@ -1,11 +1,4 @@
-/**
- * External dependencies
- */
 import { render } from '@testing-library/react';
-
-/**
- * Internal dependencies
- */
 import { View } from '../../view';
 import { HStack } from '..';