@wordpress/components 30.6.1-next.b8c8708f3.0 → 30.6.1

package/src/font-size-picker/test/index.tsx

@@ -145,7 +145,7 @@ describe( 'FontSizePicker', () => {
 			{
 				option: 'Default',
 				value: '8px',
-				expectedArguments: [ undefined ],
+				expectedArguments: [ undefined, undefined ],
 			},
 			{
 				option: 'Tiny 8px',
@@ -249,7 +249,7 @@ describe( 'FontSizePicker', () => {
 			{
 				option: 'Default',
 				value: '8px',
-				expectedArguments: [ undefined ],
+				expectedArguments: [ undefined, undefined ],
 			},
 			{
 				option: 'Tiny 8px',
@@ -358,6 +358,98 @@ describe( 'FontSizePicker', () => {
 
 		commonToggleGroupTests( fontSizes );
 		commonTests( fontSizes );
+
+		describe( 'valueMode prop for toggle group', () => {
+			it( 'should find font size by size value when valueMode is literal', async () => {
+				await render(
+					<FontSizePicker
+						fontSizes={ fontSizes }
+						value="16px"
+						valueMode="literal"
+					/>
+				);
+				// Should select the medium option (16px)
+				expect(
+					screen.getByRole( 'radio', { checked: true } )
+				).toHaveAccessibleName( 'Medium' );
+			} );
+
+			it( 'should find font size by slug when valueMode is slug', async () => {
+				await render(
+					<FontSizePicker
+						fontSizes={ fontSizes }
+						value="medium"
+						valueMode="slug"
+					/>
+				);
+				// Should select the medium option
+				expect(
+					screen.getByRole( 'radio', { checked: true } )
+				).toHaveAccessibleName( 'Medium' );
+			} );
+
+			it( 'should handle multiple font sizes with same value in literal mode', async () => {
+				const fontSizesWithDuplicates = [
+					{
+						slug: 'small-1',
+						name: 'Small 1',
+						size: '12px',
+					},
+					{
+						slug: 'small-2',
+						name: 'Small 2',
+						size: '12px',
+					},
+					{
+						slug: 'medium',
+						name: 'Medium',
+						size: '16px',
+					},
+				];
+				await render(
+					<FontSizePicker
+						fontSizes={ fontSizesWithDuplicates }
+						value="12px"
+						valueMode="literal"
+					/>
+				);
+				// Should have no selection when there are multiple matches
+				expect(
+					screen.queryByRole( 'radio', { checked: true } )
+				).not.toBeInTheDocument();
+			} );
+
+			it( 'should handle multiple font sizes with same value in slug mode', async () => {
+				const fontSizesWithDuplicates = [
+					{
+						slug: 'small-1',
+						name: 'Small 1',
+						size: '12px',
+					},
+					{
+						slug: 'small-2',
+						name: 'Small 2',
+						size: '12px',
+					},
+					{
+						slug: 'medium',
+						name: 'Medium',
+						size: '16px',
+					},
+				];
+				await render(
+					<FontSizePicker
+						fontSizes={ fontSizesWithDuplicates }
+						value="small-1"
+						valueMode="slug"
+					/>
+				);
+				// Should select the specific font size by slug
+				expect(
+					screen.getByRole( 'radio', { checked: true } )
+				).toHaveAccessibleName( 'Small 1' );
+			} );
+		} );
 	} );
 
 	describe( 'with ≤ 5 heterogeneous font sizes', () => {
@@ -430,6 +522,64 @@ describe( 'FontSizePicker', () => {
 
 		commonToggleGroupTests( fontSizes );
 		commonTests( fontSizes );
+
+		describe( 'valueMode prop for heterogeneous toggle group', () => {
+			it( 'should find font size by size value when valueMode is literal', async () => {
+				await render(
+					<FontSizePicker
+						fontSizes={ fontSizes }
+						value="1em"
+						valueMode="literal"
+					/>
+				);
+				// Should select the medium option (1em)
+				expect(
+					screen.getByRole( 'radio', { checked: true } )
+				).toHaveAccessibleName( 'Medium' );
+			} );
+
+			it( 'should find font size by slug when valueMode is slug', async () => {
+				await render(
+					<FontSizePicker
+						fontSizes={ fontSizes }
+						value="medium"
+						valueMode="slug"
+					/>
+				);
+				// Should select the medium option
+				expect(
+					screen.getByRole( 'radio', { checked: true } )
+				).toHaveAccessibleName( 'Medium' );
+			} );
+
+			it( 'should handle complex font size values in literal mode', async () => {
+				await render(
+					<FontSizePicker
+						fontSizes={ fontSizes }
+						value="clamp(1.75rem, 3vw, 2.25rem)"
+						valueMode="literal"
+					/>
+				);
+				// Should select the extra large option
+				expect(
+					screen.getByRole( 'radio', { checked: true } )
+				).toHaveAccessibleName( 'Extra Large' );
+			} );
+
+			it( 'should handle complex font size values in slug mode', async () => {
+				await render(
+					<FontSizePicker
+						fontSizes={ fontSizes }
+						value="x-large"
+						valueMode="slug"
+					/>
+				);
+				// Should select the extra large option
+				expect(
+					screen.getByRole( 'radio', { checked: true } )
+				).toHaveAccessibleName( 'Extra Large' );
+			} );
+		} );
 	} );
 
 	function commonToggleGroupTests( fontSizes: FontSize[] ) {
@@ -653,4 +803,312 @@ describe( 'FontSizePicker', () => {
 			expect( units[ 2 ] ).toHaveAccessibleName( 'ex' );
 		} );
 	}
+
+	describe( 'valueMode prop', () => {
+		// Use 6 font sizes to trigger select control (> 5)
+		const fontSizes = [
+			{
+				slug: 'small',
+				name: 'Small',
+				size: '12px',
+			},
+			{
+				slug: 'medium',
+				name: 'Medium',
+				size: '16px',
+			},
+			{
+				slug: 'large',
+				name: 'Large',
+				size: '20px',
+			},
+			{
+				slug: 'x-large',
+				name: 'Extra Large',
+				size: '24px',
+			},
+			{
+				slug: 'xx-large',
+				name: 'XX Large',
+				size: '28px',
+			},
+			{
+				slug: 'huge',
+				name: 'Huge',
+				size: '32px',
+			},
+		];
+
+		describe( 'valueMode="literal" (default)', () => {
+			it( 'should find font size by size value when valueMode is literal', async () => {
+				await render(
+					<FontSizePicker
+						fontSizes={ fontSizes }
+						value="16px"
+						valueMode="literal"
+					/>
+				);
+				// Should select the medium option (16px)
+				expect(
+					screen.getByRole( 'combobox', { name: 'Font size' } )
+				).toHaveTextContent( 'Medium' );
+			} );
+
+			it( 'should call onChange with size value and FontSize object when valueMode is literal', async () => {
+				const user = userEvent.setup();
+				const onChange = jest.fn();
+				await render(
+					<FontSizePicker
+						fontSizes={ fontSizes }
+						onChange={ onChange }
+						valueMode="literal"
+					/>
+				);
+				await user.click(
+					screen.getByRole( 'combobox', { name: 'Font size' } )
+				);
+				await user.click(
+					screen.getByRole( 'option', { name: 'Medium 16px' } )
+				);
+				expect( onChange ).toHaveBeenCalledWith(
+					'16px',
+					fontSizes[ 1 ]
+				);
+			} );
+		} );
+
+		describe( 'valueMode="slug"', () => {
+			it( 'should find font size by slug when valueMode is slug', async () => {
+				await render(
+					<FontSizePicker
+						fontSizes={ fontSizes }
+						value="medium"
+						valueMode="slug"
+					/>
+				);
+				// Should select the medium option
+				expect(
+					screen.getByRole( 'combobox', { name: 'Font size' } )
+				).toHaveTextContent( 'Medium' );
+			} );
+
+			it( 'should call onChange with size value and FontSize object when valueMode is slug', async () => {
+				const user = userEvent.setup();
+				const onChange = jest.fn();
+				await render(
+					<FontSizePicker
+						fontSizes={ fontSizes }
+						onChange={ onChange }
+						valueMode="slug"
+					/>
+				);
+				await user.click(
+					screen.getByRole( 'combobox', { name: 'Font size' } )
+				);
+				await user.click(
+					screen.getByRole( 'option', { name: 'Large 20px' } )
+				);
+				expect( onChange ).toHaveBeenCalledWith(
+					'20px',
+					fontSizes[ 2 ]
+				);
+			} );
+
+			it( 'should handle undefined value when valueMode is slug', async () => {
+				await render(
+					<FontSizePicker
+						fontSizes={ fontSizes }
+						value={ undefined }
+						valueMode="slug"
+					/>
+				);
+				// Should show default option
+				expect(
+					screen.getByRole( 'combobox', { name: 'Font size' } )
+				).toHaveTextContent( 'Default' );
+			} );
+
+			it( 'should handle empty string value when valueMode is slug', async () => {
+				await render(
+					<FontSizePicker
+						fontSizes={ fontSizes }
+						value=""
+						valueMode="slug"
+					/>
+				);
+				// Should show default option
+				expect(
+					screen.getByRole( 'combobox', { name: 'Font size' } )
+				).toHaveTextContent( 'Default' );
+			} );
+		} );
+
+		describe( 'edge cases with valueMode', () => {
+			// Use 6 font sizes to trigger select control (> 5)
+			const fontSizesWithDuplicates = [
+				{
+					slug: 'small-1',
+					name: 'Small 1',
+					size: '12px',
+				},
+				{
+					slug: 'small-2',
+					name: 'Small 2',
+					size: '12px',
+				},
+				{
+					slug: 'medium',
+					name: 'Medium',
+					size: '16px',
+				},
+				{
+					slug: 'large',
+					name: 'Large',
+					size: '20px',
+				},
+				{
+					slug: 'x-large',
+					name: 'Extra Large',
+					size: '24px',
+				},
+				{
+					slug: 'huge',
+					name: 'Huge',
+					size: '28px',
+				},
+			];
+
+			it( 'should handle multiple font sizes with same value in literal mode', async () => {
+				await render(
+					<FontSizePicker
+						fontSizes={ fontSizesWithDuplicates }
+						value="12px"
+						valueMode="literal"
+					/>
+				);
+				// Should show the first matching font size when there are multiple matches
+				expect(
+					screen.getByRole( 'combobox', { name: 'Font size' } )
+				).toHaveTextContent( 'Small 1' );
+			} );
+
+			it( 'should handle multiple font sizes with same value in slug mode', async () => {
+				await render(
+					<FontSizePicker
+						fontSizes={ fontSizesWithDuplicates }
+						value="small-1"
+						valueMode="slug"
+					/>
+				);
+				// Should select the specific font size by slug
+				expect(
+					screen.getByRole( 'combobox', { name: 'Font size' } )
+				).toHaveTextContent( 'Small 1' );
+			} );
+		} );
+	} );
+
+	describe( 'onChange callback signature', () => {
+		// Use 6 font sizes to trigger select control (> 5)
+		const fontSizes = [
+			{
+				slug: 'small',
+				name: 'Small',
+				size: '12px',
+			},
+			{
+				slug: 'medium',
+				name: 'Medium',
+				size: '16px',
+			},
+			{
+				slug: 'large',
+				name: 'Large',
+				size: '20px',
+			},
+			{
+				slug: 'x-large',
+				name: 'Extra Large',
+				size: '24px',
+			},
+			{
+				slug: 'xx-large',
+				name: 'XX Large',
+				size: '28px',
+			},
+			{
+				slug: 'huge',
+				name: 'Huge',
+				size: '32px',
+			},
+		];
+
+		it( 'should call onChange with FontSize object as second parameter for select control', async () => {
+			const user = userEvent.setup();
+			const onChange = jest.fn();
+			await render(
+				<FontSizePicker fontSizes={ fontSizes } onChange={ onChange } />
+			);
+			await user.click(
+				screen.getByRole( 'combobox', { name: 'Font size' } )
+			);
+			await user.click(
+				screen.getByRole( 'option', { name: 'Small 12px' } )
+			);
+			expect( onChange ).toHaveBeenCalledWith( '12px', fontSizes[ 0 ] );
+		} );
+
+		it( 'should call onChange with undefined as second parameter for default option', async () => {
+			const user = userEvent.setup();
+			const onChange = jest.fn();
+			await render(
+				<FontSizePicker
+					fontSizes={ fontSizes }
+					value="16px" // Start with a selected value
+					onChange={ onChange }
+				/>
+			);
+			await user.click(
+				screen.getByRole( 'combobox', { name: 'Font size' } )
+			);
+			await user.click(
+				screen.getByRole( 'option', { name: 'Default' } )
+			);
+			expect( onChange ).toHaveBeenCalledWith( undefined, undefined );
+		} );
+
+		it( 'should call onChange with FontSize object as second parameter for toggle group control', async () => {
+			const user = userEvent.setup();
+			const onChange = jest.fn();
+			// Use fewer font sizes to trigger toggle group (≤ 5)
+			const toggleGroupFontSizes = [
+				{
+					slug: 'small',
+					name: 'Small',
+					size: '12px',
+				},
+				{
+					slug: 'medium',
+					name: 'Medium',
+					size: '16px',
+				},
+				{
+					slug: 'large',
+					name: 'Large',
+					size: '20px',
+				},
+			];
+			await render(
+				<FontSizePicker
+					fontSizes={ toggleGroupFontSizes }
+					onChange={ onChange }
+				/>
+			);
+			await user.click( screen.getByRole( 'radio', { name: 'Small' } ) );
+			expect( onChange ).toHaveBeenCalledWith(
+				'12px',
+				toggleGroupFontSizes[ 0 ]
+			);
+		} );
+	} );
 } );

package/src/font-size-picker/types.ts

@@ -40,6 +40,14 @@ export type FontSizePickerProps = {
 	 * as a number, the component operates in "unitless mode" where the `units` property has no effect.
 	 */
 	value?: number | string;
+	/**
+	 * Determines how the `value` prop should be interpreted.
+	 * - `'literal'`: The `value` prop contains the actual font size value (number or string)
+	 * - `'slug'`: The `value` prop contains the slug of the selected font size
+	 *
+	 * @default 'literal'
+	 */
+	valueMode?: 'literal' | 'slug';
 	/**
 	 * If `true`, a slider will be displayed alongside the input field when a
 	 * custom font size is active. Has no effect when `disableCustomFontSizes`
@@ -96,17 +104,26 @@ export type FontSize = {
 	 * size. Used for the class generation process.
 	 */
 	slug: string;
+	/**
+	 * The `hint` property is an optional string that provides additional information
+	 * about the font size, such as fluid typography ranges or custom descriptions.
+	 * Consumers can use this to provide their own preferred hints.
+	 */
+	hint?: string;
 };
 
 export type FontSizePickerSelectProps = Pick<
 	FontSizePickerProps,
-	'value' | 'size'
+	'value' | 'size' | 'valueMode'
 > & {
 	fontSizes: NonNullable< FontSizePickerProps[ 'fontSizes' ] >;
 	disableCustomFontSizes: NonNullable<
 		FontSizePickerProps[ 'disableCustomFontSizes' ]
 	>;
-	onChange: NonNullable< FontSizePickerProps[ 'onChange' ] >;
+	onChange: (
+		value: number | string | undefined,
+		selectedItem?: FontSize
+	) => void;
 	onSelectCustom: () => void;
 	__next40pxDefaultSize: boolean;
 };
@@ -120,8 +137,11 @@ export type FontSizePickerSelectOption = {
 
 export type FontSizePickerToggleGroupProps = Pick<
 	FontSizePickerProps,
-	'value' | 'size' | '__next40pxDefaultSize'
+	'value' | 'size' | '__next40pxDefaultSize' | 'valueMode'
 > & {
 	fontSizes: NonNullable< FontSizePickerProps[ 'fontSizes' ] >;
-	onChange: NonNullable< FontSizePickerProps[ 'onChange' ] >;
+	onChange: (
+		value: number | string | undefined,
+		selectedItem?: FontSize
+	) => void;
 };

package/src/font-size-picker/utils.ts

@@ -1,7 +1,7 @@
 /**
  * Internal dependencies
  */
-import type { FontSizePickerProps } from './types';
+import type { FontSizePickerProps, FontSize } from './types';
 
 /**
  * Some themes use css vars for their font sizes, so until we
@@ -17,3 +17,25 @@ export function isSimpleCssValue(
 		/^[\d\.]+(px|em|rem|vw|vh|%|svw|lvw|dvw|svh|lvh|dvh|vi|svi|lvi|dvi|vb|svb|lvb|dvb|vmin|svmin|lvmin|dvmin|vmax|svmax|lvmax|dvmax)?$/i;
 	return sizeRegex.test( String( value ) );
 }
+
+/**
+ * Generates hint text for a font size.
+ * This function returns the hint provided by the consumer, if any.
+ * If no hint is provided, it falls back to showing the size value for simple CSS values.
+ *
+ * @param fontSize The font size object to generate hint text for.
+ * @return The hint text provided by the consumer, or the size value for simple CSS values, or undefined.
+ */
+export function generateFontSizeHint( fontSize: FontSize ): string | undefined {
+	// If the font size already has a hint, use it
+	if ( fontSize.hint ) {
+		return fontSize.hint;
+	}
+
+	// Fallback to showing the size value if it's a simple CSS value
+	if ( isSimpleCssValue( fontSize.size ) ) {
+		return String( fontSize.size );
+	}
+
+	return undefined;
+}