@wordpress/components 25.7.0 → 25.8.1

package/src/duotone-picker/duotone-picker.tsx

@@ -55,6 +55,8 @@ import type { DuotonePickerProps } from './types';
  * ```
  */
 function DuotonePicker( {
+	asButtons,
+	loop,
 	clearable = true,
 	unsetable = true,
 	colorPalette,
@@ -63,6 +65,8 @@ function DuotonePicker( {
 	disableCustomDuotone,
 	value,
 	onChange,
+	'aria-label': ariaLabel,
+	'aria-labelledby': ariaLabelledby,
 }: DuotonePickerProps ) {
 	const [ defaultDark, defaultLight ] = useMemo(
 		() => getDefaultColors( colorPalette ),
@@ -120,8 +124,37 @@ function DuotonePicker( {
 		);
 	} );
 
+	let metaProps:
+		| { asButtons: false; loop?: boolean; 'aria-label': string }
+		| { asButtons: false; loop?: boolean; 'aria-labelledby': string }
+		| { asButtons: true };
+
+	if ( asButtons ) {
+		metaProps = { asButtons: true };
+	} else {
+		const _metaProps: { asButtons: false; loop?: boolean } = {
+			asButtons: false,
+			loop,
+		};
+
+		if ( ariaLabel ) {
+			metaProps = { ..._metaProps, 'aria-label': ariaLabel };
+		} else if ( ariaLabelledby ) {
+			metaProps = {
+				..._metaProps,
+				'aria-labelledby': ariaLabelledby,
+			};
+		} else {
+			metaProps = {
+				..._metaProps,
+				'aria-label': __( 'Custom color picker.' ),
+			};
+		}
+	}
+
 	return (
 		<CircularOptionPicker
+			{ ...metaProps }
 			options={ unsetable ? [ unsetOption, ...options ] : options }
 			actions={
 				!! clearable && (

package/src/duotone-picker/types.ts

@@ -39,7 +39,40 @@ export type DuotonePickerProps = {
 	 * Callback which is called when the duotone colors change.
 	 */
 	onChange: ( value: DuotonePickerProps[ 'value' ] | undefined ) => void;
-};
+	/**
+	 * Whether the control should present as a set of buttons,
+	 * each with its own tab stop.
+	 *
+	 * @default false
+	 */
+	asButtons?: boolean;
+	/**
+	 * Prevents keyboard interaction from wrapping around.
+	 * Only used when `asButtons` is not true.
+	 *
+	 * @default true
+	 */
+	loop?: boolean;
+} & (
+	| {
+			/**
+			 * A label to identify the purpose of the control.
+			 *
+			 * @todo [#54055] Either this or `aria-labelledby` should be required
+			 */
+			'aria-label'?: string;
+			'aria-labelledby'?: never;
+	  }
+	| {
+			/**
+			 * An ID of an element to provide a label for the control.
+			 *
+			 * @todo [#54055] Either this or `aria-label` should be required
+			 */
+			'aria-labelledby'?: string;
+			'aria-label'?: never;
+	  }
+);
 
 type Color = {
 	color: string;

package/src/focusable-iframe/{index.js → index.tsx}

@@ -3,12 +3,15 @@
  */
 import { useMergeRefs, useFocusableIframe } from '@wordpress/compose';
 import deprecated from '@wordpress/deprecated';
-
 /**
- * @param {Object}                                 props
- * @param {import('react').Ref<HTMLIFrameElement>} props.iframeRef
+ * Internal dependencies
  */
-export default function FocusableIframe( { iframeRef, ...props } ) {
+import type { FocusableIframeProps } from './types';
+
+export default function FocusableIframe( {
+	iframeRef,
+	...props
+}: FocusableIframeProps ) {
 	const ref = useMergeRefs( [ iframeRef, useFocusableIframe() ] );
 	deprecated( 'wp.components.FocusableIframe', {
 		since: '5.9',

package/src/focusable-iframe/types.ts

@@ -0,0 +1,9 @@
+/**
+ * External dependencies
+ */
+import type { ComponentPropsWithoutRef } from 'react';
+
+export interface FocusableIframeProps
+	extends ComponentPropsWithoutRef< 'iframe' > {
+	iframeRef: React.Ref< HTMLIFrameElement >;
+}

package/src/form-token-field/README.md

@@ -62,6 +62,7 @@ The `value` property is handled in a manner similar to controlled form component
 -   `__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.)
+-   `tokenizeOnBlur` - If true, add any incompleteTokenValue as a new token when the field loses focus.
 
 ## Usage
 

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

@@ -73,6 +73,7 @@ export function FormTokenField( props: FormTokenFieldProps ) {
 		__next40pxDefaultSize = false,
 		__experimentalAutoSelectFirstMatch = false,
 		__nextHasNoMarginBottom = false,
+		tokenizeOnBlur = false,
 	} = useDeprecated36pxDefaultSizeProp< FormTokenFieldProps >(
 		props,
 		'wp.components.FormTokenField'
@@ -167,6 +168,9 @@ export function FormTokenField( props: FormTokenFieldProps ) {
 			__experimentalValidateInput( incompleteTokenValue )
 		) {
 			setIsActive( false );
+			if ( tokenizeOnBlur && inputHasValidValue() ) {
+				addNewToken( incompleteTokenValue );
+			}
 		} else {
 			// Reset to initial state
 			setIncompleteTokenValue( '' );
@@ -451,7 +455,7 @@ export function FormTokenField( props: FormTokenFieldProps ) {
 		setSelectedSuggestionScroll( false );
 		setIsExpanded( ! __experimentalExpandOnFocus );
 
-		if ( isActive ) {
+		if ( isActive && ! tokenizeOnBlur ) {
 			focus();
 		}
 	}

package/src/form-token-field/style.scss

@@ -157,21 +157,21 @@
 .components-form-token-field__suggestions-list {
 	flex: 1 0 100%;
 	min-width: 100%;
-	max-height: 9em;
+	max-height: $grid-unit-80 * 2;
 	overflow-y: auto;
 	transition: all 0.15s ease-in-out;
 	@include reduce-motion("transition");
 	list-style: none;
-	border-top: $border-width solid $components-color-border;
+	box-shadow: inset 0 $border-width 0 0 $gray-600; // Matches the border color of the input.
 	margin: 0;
-	padding: 0;
 }
 
 .components-form-token-field__suggestion {
-	color: $gray-700;
+	color: $gray-900;
 	display: block;
 	font-size: $default-font-size;
-	padding: 4px 8px;
+	padding: $grid-unit-10 $grid-unit-15;
+	min-height: $button-size-compact;
 	margin: 0;
 	cursor: pointer;
 
@@ -180,7 +180,3 @@
 		color: $white;
 	}
 }
-
-.components-form-token-field__suggestion-match {
-	text-decoration: underline;
-}

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

@@ -205,7 +205,42 @@ describe( 'FormTokenField', () => {
 			] );
 		} );
 
-		it( "should not add a token with the input's value when pressing the tab key", async () => {
+		it( 'should add a token with the input value with onBlur when `tokenizeOnBlur` prop is `true`', async () => {
+			const user = userEvent.setup();
+
+			const onChangeSpy = jest.fn();
+
+			const { rerender } = render(
+				<FormTokenFieldWithState onChange={ onChangeSpy } />
+			);
+
+			const input = screen.getByRole( 'combobox' );
+
+			// Add 'grapefruit' token by typing it and check blur of field does not tokenize it.
+			await user.type( input, 'grapefruit' );
+			await user.click( document.body );
+			expect( onChangeSpy ).toHaveBeenCalledTimes( 0 );
+			expectTokensNotToBeInTheDocument( [ 'grapefruit' ] );
+
+			rerender(
+				<FormTokenFieldWithState
+					onChange={ onChangeSpy }
+					tokenizeOnBlur
+				/>
+			);
+			await user.clear( input );
+
+			// Add 'grapefruit' token by typing it and check blur of field tokenizes it.
+			await user.type( input, 'grapefruit' );
+
+			await user.click( document.body );
+			expect( onChangeSpy ).toHaveBeenNthCalledWith( 1, [
+				'grapefruit',
+			] );
+			expectTokensToBeInTheDocument( [ 'grapefruit' ] );
+		} );
+
+		it( "should not add a token with the input's value when tokenizeOnBlur is not set and pressing the tab key", async () => {
 			const user = userEvent.setup();
 
 			const onChangeSpy = jest.fn();

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

@@ -182,13 +182,19 @@ export interface FormTokenFieldProps
 	 * @default false
 	 */
 	__nextHasNoMarginBottom?: boolean;
+	/**
+	 * If true, add any incompleteTokenValue as a new token when the field loses focus.
+	 *
+	 * @default false
+	 */
+	tokenizeOnBlur?: boolean;
 }
 
 /**
  * `T` can be either a `string` or an object which must have a `value` prop as a string.
  */
 export interface SuggestionsListProps<
-	T = string | ( Record< string, unknown > & { value: string } )
+	T = string | ( Record< string, unknown > & { value: string } ),
 > {
 	selectedIndex: number;
 	scrollIntoView: boolean;

package/src/gradient-picker/README.md

@@ -102,3 +102,17 @@ The heading level. Only applies in cases where gradients are provided from multi
 
 -   Required: No
 -   Default: `2`
+
+### `asButtons`: `boolean`
+
+Whether the control should present as a set of buttons, each with its own tab stop.
+
+- Required: No
+- Default: `false`
+
+### `loop`: `boolean`
+
+Prevents keyboard interaction from wrapping around. Only used when `asButtons` is not true.
+
+- Required: No
+- Default: `true`

package/src/gradient-picker/index.tsx

@@ -2,6 +2,7 @@
  * WordPress dependencies
  */
 import { __, sprintf } from '@wordpress/i18n';
+import { useInstanceId } from '@wordpress/compose';
 import { useCallback, useMemo } from '@wordpress/element';
 import deprecated from '@wordpress/deprecated';
 
@@ -40,7 +41,7 @@ function SingleOrigin( {
 	gradients,
 	onChange,
 	value,
-	actions,
+	...additionalProps
 }: PickerProps< GradientObject > ) {
 	const gradientOptions = useMemo( () => {
 		return gradients.map( ( { gradient, name }, index ) => (
@@ -70,10 +71,10 @@ function SingleOrigin( {
 		) );
 	}, [ gradients, value, onChange, clearGradient ] );
 	return (
-		<CircularOptionPicker
+		<CircularOptionPicker.OptionGroup
 			className={ className }
 			options={ gradientOptions }
-			actions={ actions }
+			{ ...additionalProps }
 		/>
 	);
 }
@@ -84,15 +85,17 @@ function MultipleOrigin( {
 	gradients,
 	onChange,
 	value,
-	actions,
 	headingLevel,
 }: PickerProps< OriginObject > ) {
+	const instanceId = useInstanceId( MultipleOrigin );
+
 	return (
 		<VStack spacing={ 3 } className={ className }>
 			{ gradients.map( ( { name, gradients: gradientSet }, index ) => {
+				const id = `color-palette-${ instanceId }-${ index }`;
 				return (
 					<VStack spacing={ 2 } key={ index }>
-						<ColorHeading level={ headingLevel }>
+						<ColorHeading level={ headingLevel } id={ id }>
 							{ name }
 						</ColorHeading>
 						<SingleOrigin
@@ -102,9 +105,7 @@ function MultipleOrigin( {
 								onChange( gradient, index )
 							}
 							value={ value }
-							{ ...( gradients.length === index + 1
-								? { actions }
-								: {} ) }
+							aria-labelledby={ id }
 						/>
 					</VStack>
 				);
@@ -114,10 +115,56 @@ function MultipleOrigin( {
 }
 
 function Component( props: PickerProps< any > ) {
-	if ( isMultipleOriginArray( props.gradients ) ) {
-		return <MultipleOrigin { ...props } />;
+	const {
+		asButtons,
+		loop,
+		actions,
+		headingLevel,
+		'aria-label': ariaLabel,
+		'aria-labelledby': ariaLabelledby,
+		...additionalProps
+	} = props;
+	const options = isMultipleOriginArray( props.gradients ) ? (
+		<MultipleOrigin headingLevel={ headingLevel } { ...additionalProps } />
+	) : (
+		<SingleOrigin { ...additionalProps } />
+	);
+
+	let metaProps:
+		| { asButtons: false; loop?: boolean; 'aria-label': string }
+		| { asButtons: false; loop?: boolean; 'aria-labelledby': string }
+		| { asButtons: true };
+
+	if ( asButtons ) {
+		metaProps = { asButtons: true };
+	} else {
+		const _metaProps: { asButtons: false; loop?: boolean } = {
+			asButtons: false,
+			loop,
+		};
+
+		if ( ariaLabel ) {
+			metaProps = { ..._metaProps, 'aria-label': ariaLabel };
+		} else if ( ariaLabelledby ) {
+			metaProps = {
+				..._metaProps,
+				'aria-labelledby': ariaLabelledby,
+			};
+		} else {
+			metaProps = {
+				..._metaProps,
+				'aria-label': __( 'Custom color picker.' ),
+			};
+		}
 	}
-	return <SingleOrigin { ...props } />;
+
+	return (
+		<CircularOptionPicker
+			{ ...metaProps }
+			actions={ actions }
+			options={ options }
+		/>
+	);
 }
 
 /**
@@ -174,6 +221,7 @@ export function GradientPicker( {
 	disableCustomGradients = false,
 	__experimentalIsRenderedInSidebar,
 	headingLevel = 2,
+	...additionalProps
 }: GradientPickerComponentProps ) {
 	const clearGradient = useCallback(
 		() => onChange( undefined ),
@@ -211,6 +259,7 @@ export function GradientPicker( {
 				) }
 				{ ( gradients.length || clearable ) && (
 					<Component
+						{ ...additionalProps }
 						className={ className }
 						clearGradient={ clearGradient }
 						gradients={ gradients }

package/src/gradient-picker/types.ts

@@ -42,7 +42,40 @@ type GradientPickerBaseProps = {
 	 * @default 2
 	 */
 	headingLevel?: HeadingSize;
-};
+	/**
+	 * Whether the control should present as a set of buttons,
+	 * each with its own tab stop.
+	 *
+	 * @default false
+	 */
+	asButtons?: boolean;
+	/**
+	 * Prevents keyboard interaction from wrapping around.
+	 * Only used when `asButtons` is not true.
+	 *
+	 * @default true
+	 */
+	loop?: boolean;
+} & (
+	| {
+			/**
+			 * A label to identify the purpose of the control.
+			 *
+			 * @todo [#54055] Either this or `aria-labelledby` should be required
+			 */
+			'aria-label'?: string;
+			'aria-labelledby'?: never;
+	  }
+	| {
+			/**
+			 * An ID of an element to provide a label for the control.
+			 *
+			 * @todo [#54055] Either this or `aria-label` should be required
+			 */
+			'aria-labelledby'?: string;
+			'aria-label'?: never;
+	  }
+);
 
 export type GradientPickerComponentProps = GradientPickerBaseProps & {
 	/**

package/src/higher-order/navigate-regions/index.tsx

@@ -139,11 +139,10 @@ export function useNavigateRegions( shortcuts: Shortcuts = defaultShortcuts ) {
  */
 export default createHigherOrderComponent(
 	( Component ) =>
-		( { shortcuts, ...props } ) =>
-			(
-				<div { ...useNavigateRegions( shortcuts ) }>
-					<Component { ...props } />
-				</div>
-			),
+		( { shortcuts, ...props } ) => (
+			<div { ...useNavigateRegions( shortcuts ) }>
+				<Component { ...props } />
+			</div>
+		),
 	'navigateRegions'
 );

package/src/higher-order/with-filters/test/index.tsx

@@ -52,13 +52,12 @@ describe( 'withFilters', () => {
 		addFilter(
 			hookName,
 			'test/enhanced-component-compose',
-			( FilteredComponent ) => () =>
-				(
-					<div>
-						<FilteredComponent />
-						<ComposedComponent />
-					</div>
-				)
+			( FilteredComponent ) => () => (
+				<div>
+					<FilteredComponent />
+					<ComposedComponent />
+				</div>
+			)
 		);
 		const EnhancedComponent = withFilters( hookName )( MyComponent );
 
@@ -72,12 +71,11 @@ describe( 'withFilters', () => {
 		addFilter(
 			hookName,
 			'test/enhanced-component-spy-1',
-			( FilteredComponent ) => () =>
-				(
-					<blockquote>
-						<FilteredComponent />
-					</blockquote>
-				)
+			( FilteredComponent ) => () => (
+				<blockquote>
+					<FilteredComponent />
+				</blockquote>
+			)
 		);
 		const EnhancedComponent = withFilters( hookName )( SpiedComponent );
 
@@ -100,12 +98,11 @@ describe( 'withFilters', () => {
 		addFilter(
 			hookName,
 			'test/enhanced-component-spy-1',
-			( FilteredComponent ) => () =>
-				(
-					<blockquote>
-						<FilteredComponent />
-					</blockquote>
-				)
+			( FilteredComponent ) => () => (
+				<blockquote>
+					<FilteredComponent />
+				</blockquote>
+			)
 		);
 
 		await waitFor( () =>
@@ -125,22 +122,20 @@ describe( 'withFilters', () => {
 		addFilter(
 			hookName,
 			'test/enhanced-component-spy-1',
-			( FilteredComponent ) => () =>
-				(
-					<blockquote>
-						<FilteredComponent />
-					</blockquote>
-				)
+			( FilteredComponent ) => () => (
+				<blockquote>
+					<FilteredComponent />
+				</blockquote>
+			)
 		);
 		addFilter(
 			hookName,
 			'test/enhanced-component-spy-2',
-			( FilteredComponent ) => () =>
-				(
-					<section>
-						<FilteredComponent />
-					</section>
-				)
+			( FilteredComponent ) => () => (
+				<section>
+					<FilteredComponent />
+				</section>
+			)
 		);
 
 		await waitFor( () =>
@@ -159,12 +154,11 @@ describe( 'withFilters', () => {
 		addFilter(
 			hookName,
 			'test/enhanced-component-spy',
-			( FilteredComponent ) => () =>
-				(
-					<div>
-						<FilteredComponent />
-					</div>
-				)
+			( FilteredComponent ) => () => (
+				<div>
+					<FilteredComponent />
+				</div>
+			)
 		);
 
 		await waitFor( () =>
@@ -196,12 +190,11 @@ describe( 'withFilters', () => {
 		addFilter(
 			hookName,
 			'test/enhanced-component-spy-1',
-			( FilteredComponent ) => () =>
-				(
-					<blockquote>
-						<FilteredComponent />
-					</blockquote>
-				)
+			( FilteredComponent ) => () => (
+				<blockquote>
+					<FilteredComponent />
+				</blockquote>
+			)
 		);
 
 		await waitFor( () =>

package/src/higher-order/with-focus-outside/{index.js → index.tsx}

@@ -1,5 +1,3 @@
-//@ts-nocheck
-
 /**
  * WordPress dependencies
  */
@@ -11,9 +9,14 @@ import {
 
 export default createHigherOrderComponent(
 	( WrappedComponent ) => ( props ) => {
-		const [ handleFocusOutside, setHandleFocusOutside ] = useState();
-		const bindFocusOutsideHandler = useCallback(
-			( node ) =>
+		const [ handleFocusOutside, setHandleFocusOutside ] = useState<
+			undefined | ( ( event: React.FocusEvent ) => void )
+		>( undefined );
+
+		const bindFocusOutsideHandler = useCallback<
+			( node: React.FocusEvent ) => void
+		>(
+			( node: any ) =>
 				setHandleFocusOutside( () =>
 					node?.handleFocusOutside
 						? node.handleFocusOutside.bind( node )

package/src/higher-order/with-focus-outside/test/{index.js → index.tsx}

@@ -12,17 +12,21 @@ import { Component } from '@wordpress/element';
 /**
  * Internal dependencies
  */
-import withFocusOutside from '../';
+import withFocusOutside from '..';
 
-let onFocusOutside;
+interface TestComponentProps {
+	onFocusOutside: ( event: FocusEvent ) => void;
+}
+
+let onFocusOutside: () => void;
 
 describe( 'withFocusOutside', () => {
-	let origHasFocus;
+	let origHasFocus: typeof document.hasFocus;
 
 	const EnhancedComponent = withFocusOutside(
-		class extends Component {
+		class extends Component< TestComponentProps > {
 			handleFocusOutside() {
-				this.props.onFocusOutside();
+				this.props.onFocusOutside( new FocusEvent( 'blur' ) );
 			}
 
 			render() {
@@ -36,15 +40,13 @@ describe( 'withFocusOutside', () => {
 		}
 	);
 
-	class TestComponent extends Component {
-		render() {
-			return <EnhancedComponent { ...this.props } />;
-		}
-	}
+	const TestComponent: React.FC< TestComponentProps > = ( props ) => {
+		return <EnhancedComponent { ...props } />;
+	};
 
 	beforeEach( () => {
 		// Mock document.hasFocus() to always be true for testing
-		// note: we overide this for some tests.
+		// note: we override this for some tests.
 		origHasFocus = document.hasFocus;
 		document.hasFocus = () => true;
 

package/src/higher-order/with-notices/test/index.tsx

@@ -27,7 +27,7 @@ import withNotices from '..';
 import type { WithNoticeProps } from '../types';
 
 // Implementation detail of Notice component used to query the dismissal button.
-const stockDismissText = 'Dismiss this notice';
+const stockDismissText = 'Close';
 
 function noticesFrom( list: string[] ) {
 	return list.map( ( item ) => ( { id: item, content: item } ) );