@wordpress/components 33.0.1-next.v.202604201441.0 → 33.1.0

package/src/color-palette/test/utils.ts

@@ -23,6 +23,24 @@ describe( 'ColorPalette: Utils', () => {
 			] );
 			expect( result ).toBe( 'Blue' );
 		} );
+
+		test( 'should prefer selectedSlug over color matching when duplicate colors exist', () => {
+			const result = extractColorNameFromCurrentValue(
+				'#000',
+				[
+					{
+						name: 'Dark Background',
+						slug: 'dark-background',
+						color: '#000',
+					},
+					{ name: 'Dark Text', slug: 'dark-text', color: '#000' },
+				],
+				false,
+				'dark-text'
+			);
+
+			expect( result ).toBe( 'Dark Text' );
+		} );
 	} );
 
 	describe( 'normalizeColorValue', () => {

package/src/color-palette/types.ts

@@ -12,6 +12,7 @@ import type { HeadingSize } from '../heading/types';
 export type ColorObject = {
 	name: string;
 	color: NonNullable< CSSProperties[ 'color' ] >;
+	slug?: string;
 };
 
 export type PaletteObject = {
@@ -24,9 +25,22 @@ type PaletteProps = {
 	clearColor: () => void;
 	/**
 	 * Callback called when a color is selected.
+	 * The third argument is the slug of the selected palette entry, when available.
 	 */
-	onChange: ( newColor?: string, index?: number ) => void;
+	onChange: ( newColor?: string, index?: number, slug?: string ) => void;
 	value?: string;
+	/**
+	 * The slug of the currently selected palette entry.
+	 *
+	 * When set to a non-empty string, selection is determined by slug rather
+	 * than by color value — this correctly handles palettes where two entries
+	 * share the same color. Palette entries without a slug will not appear
+	 * selected in this mode, even if their color value matches `value`.
+	 *
+	 * An empty string is treated the same as `undefined`: selection falls
+	 * back to matching by color value.
+	 */
+	selectedSlug?: string;
 	actions?: ReactNode;
 	headingLevel?: HeadingSize;
 };
@@ -43,7 +57,10 @@ export type CustomColorPickerDropdownProps = DropdownProps & {
 	isRenderedInSidebar: boolean;
 };
 
-export type ColorPaletteProps = Pick< PaletteProps, 'onChange' > & {
+export type ColorPaletteProps = Pick<
+	PaletteProps,
+	'onChange' | 'selectedSlug'
+> & {
 	/**
 	 * Whether the palette should have a clearing button.
 	 *

package/src/color-palette/utils.ts

@@ -32,7 +32,8 @@ const isSimpleCSSColor = ( value: string ): boolean => {
 export const extractColorNameFromCurrentValue = (
 	currentValue?: ColorPaletteProps[ 'value' ],
 	colors: ColorPaletteProps[ 'colors' ] = [],
-	showMultiplePalettes: boolean = false
+	showMultiplePalettes: boolean = false,
+	selectedSlug?: ColorPaletteProps[ 'selectedSlug' ]
 ) => {
 	if ( ! currentValue ) {
 		return '';
@@ -50,7 +51,18 @@ export const extractColorNameFromCurrentValue = (
 		? ( colors as PaletteObject[] )
 		: [ { colors: colors as ColorObject[] } ];
 	for ( const { colors: paletteColors } of colorPalettes ) {
-		for ( const { name: colorName, color: colorValue } of paletteColors ) {
+		for ( const {
+			name: colorName,
+			color: colorValue,
+			slug,
+		} of paletteColors ) {
+			if ( selectedSlug ) {
+				if ( slug === selectedSlug ) {
+					return colorName;
+				}
+				continue;
+			}
+
 			const normalizedColorValue = currentValueIsSimpleColor
 				? colord( colorValue ).toHex()
 				: colorValue;

package/src/color-picker/hex-input.tsx

@@ -20,7 +20,7 @@ import InputControlPrefixWrapper from '../input-control/input-prefix-wrapper';
 
 export const HexInput = ( { color, onChange, enableAlpha }: HexInputProps ) => {
 	const handleChange = ( nextValue: string | undefined ) => {
-		if ( ! nextValue ) {
+		if ( nextValue === undefined ) {
 			return;
 		}
 		const hexValue = nextValue.startsWith( '#' )

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

@@ -27,7 +27,7 @@ const meta: Meta< typeof ColorPicker > = {
 		},
 		docs: { canvas: { sourceState: 'shown' } },
 		componentStatus: {
-			status: 'stable',
+			status: 'recommended',
 			whereUsed: 'global',
 		},
 	},

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

@@ -95,7 +95,7 @@ describe( 'ColorPicker', () => {
 			await user.clear( hexInput );
 			await user.type( hexInput, '1ab' );
 
-			expect( onChangeComplete ).toHaveBeenCalledTimes( 3 );
+			expect( onChangeComplete ).toHaveBeenCalledTimes( 4 );
 			expect( onChangeComplete ).toHaveBeenLastCalledWith(
 				legacyColorMatcher
 			);
@@ -126,9 +126,31 @@ describe( 'ColorPicker', () => {
 			await user.clear( hexInput );
 			await user.type( hexInput, '1ab' );
 
-			expect( onChange ).toHaveBeenCalledTimes( 3 );
+			expect( onChange ).toHaveBeenCalledTimes( 4 );
 			expect( onChange ).toHaveBeenLastCalledWith( '#11aabb' );
 		} );
+
+		it( 'should reset color to black when the hex input is completely cleared', async () => {
+			const user = userEvent.setup();
+			const onChange = jest.fn();
+			const color = '#11aabb';
+
+			render(
+				<ColorPicker
+					onChange={ onChange }
+					color={ color }
+					enableAlpha={ false }
+				/>
+			);
+
+			const formatSelector = screen.getByRole( 'combobox' );
+			await user.selectOptions( formatSelector, 'hex' );
+
+			const hexInput = screen.getByRole( 'textbox' );
+			await user.clear( hexInput );
+
+			expect( onChange ).toHaveBeenLastCalledWith( '#000000' );
+		} );
 	} );
 
 	describe.each( [

package/src/combobox-control/stories/index.story.tsx

@@ -50,7 +50,7 @@ const meta: Meta< typeof ComboboxControl > = {
 		controls: { expanded: true },
 		docs: { canvas: { sourceState: 'shown' } },
 		componentStatus: {
-			status: 'stable',
+			status: 'recommended',
 			whereUsed: 'global',
 			notes: 'Will be superseded by `SearchableSelectControl` in `@wordpress/ui`, but continue using for now.',
 		},

package/src/composite/legacy/test/index.tsx

@@ -341,7 +341,7 @@ describe.each( [
 ] )( '%s', ( _when, rtl ) => {
 	const { previous, next, first, last } = getKeys( rtl );
 
-	async function useOneDimensionalTest( initialState?: InitialState ) {
+	async function renderOneDimensionalTest( initialState?: InitialState ) {
 		const Test = () => (
 			<OneDimensionalTest
 				state={ useCompositeState( { rtl, ...initialState } ) }
@@ -351,7 +351,7 @@ describe.each( [
 		return getOneDimensionalItems();
 	}
 
-	async function useTwoDimensionalTest( initialState?: InitialState ) {
+	async function renderTwoDimensionalTest( initialState?: InitialState ) {
 		const Test = () => (
 			<TwoDimensionalTest
 				state={ useCompositeState( { rtl, ...initialState } ) }
@@ -361,7 +361,7 @@ describe.each( [
 		return getTwoDimensionalItems();
 	}
 
-	async function useShiftTest( shift: boolean ) {
+	async function renderShiftTest( shift: boolean ) {
 		const Test = () => (
 			<ShiftTest state={ useCompositeState( { rtl, shift } ) } />
 		);
@@ -371,7 +371,7 @@ describe.each( [
 
 	describe( 'In one dimension', () => {
 		test( 'All directions work with no orientation', async () => {
-			const { item1, item2, item3 } = await useOneDimensionalTest();
+			const { item1, item2, item3 } = await renderOneDimensionalTest();
 
 			await press.Tab();
 			expect( item1 ).toHaveFocus();
@@ -406,7 +406,7 @@ describe.each( [
 		} );
 
 		test( 'Only left/right work with horizontal orientation', async () => {
-			const { item1, item2, item3 } = await useOneDimensionalTest( {
+			const { item1, item2, item3 } = await renderOneDimensionalTest( {
 				orientation: 'horizontal',
 			} );
 
@@ -435,7 +435,7 @@ describe.each( [
 		} );
 
 		test( 'Only up/down work with vertical orientation', async () => {
-			const { item1, item2, item3 } = await useOneDimensionalTest( {
+			const { item1, item2, item3 } = await renderOneDimensionalTest( {
 				orientation: 'vertical',
 			} );
 
@@ -464,7 +464,7 @@ describe.each( [
 		} );
 
 		test( 'Focus wraps with loop enabled', async () => {
-			const { item1, item2, item3 } = await useOneDimensionalTest( {
+			const { item1, item2, item3 } = await renderOneDimensionalTest( {
 				loop: true,
 			} );
 
@@ -488,7 +488,7 @@ describe.each( [
 	describe( 'In two dimensions', () => {
 		test( 'All directions work as standard', async () => {
 			const { itemA1, itemA2, itemA3, itemB1, itemB2, itemC1, itemC3 } =
-				await useTwoDimensionalTest();
+				await renderTwoDimensionalTest();
 
 			await press.Tab();
 			expect( itemA1 ).toHaveFocus();
@@ -524,7 +524,7 @@ describe.each( [
 
 		test( 'Focus wraps around rows/columns with loop enabled', async () => {
 			const { itemA1, itemA2, itemA3, itemB1, itemC1, itemC3 } =
-				await useTwoDimensionalTest( { loop: true } );
+				await renderTwoDimensionalTest( { loop: true } );
 
 			await press.Tab();
 			expect( itemA1 ).toHaveFocus();
@@ -548,7 +548,7 @@ describe.each( [
 
 		test( 'Focus moves between rows/columns with wrap enabled', async () => {
 			const { itemA1, itemA2, itemA3, itemB1, itemC1, itemC3 } =
-				await useTwoDimensionalTest( { wrap: true } );
+				await renderTwoDimensionalTest( { wrap: true } );
 
 			await press.Tab();
 			expect( itemA1 ).toHaveFocus();
@@ -577,7 +577,7 @@ describe.each( [
 		} );
 
 		test( 'Focus wraps around start/end with loop and wrap enabled', async () => {
-			const { itemA1, itemC3 } = await useTwoDimensionalTest( {
+			const { itemA1, itemC3 } = await renderTwoDimensionalTest( {
 				loop: true,
 				wrap: true,
 			} );
@@ -596,7 +596,7 @@ describe.each( [
 
 		test( 'Focus shifts if vertical neighbour unavailable when shift enabled', async () => {
 			const { itemA1, itemB1, itemB2, itemC1 } =
-				await useShiftTest( true );
+				await renderShiftTest( true );
 
 			await press.Tab();
 			expect( itemA1 ).toHaveFocus();
@@ -617,7 +617,7 @@ describe.each( [
 		} );
 
 		test( 'Focus does not shift if vertical neighbour unavailable when shift not enabled', async () => {
-			const { itemA1, itemB1, itemB2 } = await useShiftTest( false );
+			const { itemA1, itemB1, itemB2 } = await renderShiftTest( false );
 
 			await press.Tab();
 			expect( itemA1 ).toHaveFocus();

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

@@ -49,7 +49,7 @@ const meta: Meta< typeof Composite > = {
 			canvas: { sourceState: 'shown' },
 		},
 		componentStatus: {
-			status: 'stable',
+			status: 'recommended',
 			whereUsed: 'global',
 		},
 	},

package/src/confirm-dialog/stories/index.story.tsx

@@ -34,7 +34,7 @@ const meta: Meta< typeof ConfirmDialog > = {
 			expanded: true,
 		},
 		componentStatus: {
-			status: 'stable',
+			status: 'recommended',
 			whereUsed: 'global',
 		},
 		docs: { canvas: { sourceState: 'shown' } },

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

@@ -76,7 +76,6 @@ const GradientTypePicker = ( {
 	);
 
 	if ( type === 'linear-gradient' && gradientAST.orientation ) {
-		// eslint-disable-next-line react-compiler/react-compiler -- false positive, see https://github.com/facebook/react/issues/29196
 		lastLinearOrientationAngle.current = Number(
 			gradientAST.orientation.value
 		);

package/src/custom-select-control/stories/index.story.tsx

@@ -32,7 +32,7 @@ const meta: Meta< typeof CustomSelectControl > = {
 			source: { excludeDecorators: true },
 		},
 		componentStatus: {
-			status: 'stable',
+			status: 'recommended',
 			whereUsed: 'global',
 			notes: 'Will be superseded by `SelectControl` in `@wordpress/ui`, but continue using for now.',
 		},

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

@@ -32,7 +32,7 @@ const meta: Meta< typeof Disabled > = {
 		},
 		docs: { canvas: { sourceState: 'shown' } },
 		componentStatus: {
-			status: 'stable',
+			status: 'recommended',
 			whereUsed: 'global',
 		},
 	},

package/src/drop-zone/stories/index.story.tsx

@@ -37,7 +37,7 @@ const meta: Meta< typeof DropZone > = {
 		controls: { expanded: true },
 		docs: { canvas: { sourceState: 'shown' } },
 		componentStatus: {
-			status: 'stable',
+			status: 'recommended',
 			whereUsed: 'global',
 		},
 	},

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

@@ -43,7 +43,7 @@ const meta: Meta< typeof Dropdown > = {
 			expanded: true,
 		},
 		componentStatus: {
-			status: 'stable',
+			status: 'recommended',
 			whereUsed: 'global',
 		},
 	},

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

@@ -25,7 +25,7 @@ const meta: Meta< typeof DuotonePicker > = {
 		controls: { expanded: true },
 		docs: { canvas: { sourceState: 'shown' } },
 		componentStatus: {
-			status: 'stable',
+			status: 'recommended',
 			whereUsed: 'editor',
 		},
 	},

package/src/duotone-picker/stories/duotone-swatch.story.tsx

@@ -15,7 +15,7 @@ const meta: Meta< typeof DuotoneSwatch > = {
 		controls: { expanded: true },
 		docs: { canvas: { sourceState: 'shown' } },
 		componentStatus: {
-			status: 'stable',
+			status: 'recommended',
 			whereUsed: 'editor',
 		},
 	},

package/src/external-link/stories/index.story.tsx

@@ -9,7 +9,6 @@ import type { Meta, StoryFn } from '@storybook/react-vite';
 import ExternalLink from '..';
 
 const meta: Meta< typeof ExternalLink > = {
-	tags: [ 'manifest' ],
 	component: ExternalLink,
 	title: 'Components/Navigation/ExternalLink',
 	id: 'components-externallink',
@@ -22,8 +21,9 @@ const meta: Meta< typeof ExternalLink > = {
 		},
 		docs: { canvas: { sourceState: 'shown' } },
 		componentStatus: {
-			status: 'stable',
+			status: 'not-recommended',
 			whereUsed: 'global',
+			notes: 'Use `Link` from `@wordpress/ui` instead, with the `openInNewTab` prop set.',
 		},
 	},
 };

package/src/external-link/style.scss

@@ -1,12 +1,44 @@
 .components-external-link {
+	color: var(--wpds-color-fg-interactive-brand);
 	text-decoration: none;
+
+	// Match the `outset-ring--focus` utility used by `Link` in `@wordpress/ui`.
+	@media not ( prefers-reduced-motion ) {
+		transition: outline 0.1s ease-out;
+	}
+	// Outline width must be kept at 0 even with a transparent color,
+	// or else the outline will be visible in forced-colors mode.
+	outline: 0 solid transparent;
+	outline-offset: 1px;
+
+	&:visited {
+		color: var(--wpds-color-fg-interactive-brand);
+	}
+
+	&:hover,
+	&:active {
+		color: var(--wpds-color-fg-interactive-brand-active);
+	}
+
+	&:focus {
+		outline:
+			var(--wpds-border-width-focus) solid
+			var(--wpds-color-stroke-focus-brand);
+		// Override style from wp-admin common.css.
+		box-shadow: none;
+		border-radius: 0;
+	}
 }
 
 .components-external-link__contents {
 	text-decoration: underline;
+	text-underline-offset: 0.2em;
+	text-decoration-thickness: from-font;
 }
 
 .components-external-link__icon {
-	margin-left: 0.5ch;
-	font-weight: 400;
+	line-height: 1;
+	display: inline-block;
+	margin-inline-start: var(--wpds-dimension-padding-xs);
+	font-weight: var(--wpds-typography-font-weight-regular);
 }

package/src/focal-point-picker/README.md

@@ -1,28 +1,32 @@
 # FocalPointPicker
 
-Focal Point Picker is a component which creates a UI for identifying the most important visual point of an image. This component addresses a specific problem: with large background images it is common to see undesirable crops, especially when viewing on smaller viewports such as mobile phones. This component allows the selection of the point with the most important visual information and returns it as a pair of numbers between 0 and 1. This value can be easily converted into the CSS `background-position` attribute, and will ensure that the focal point is never cropped out, regardless of viewport.
+Focal Point Picker is a component which creates a UI for identifying the most important visual point of an image.
 
-- Example focal point picker value: `{ x: 0.5, y: 0.1 }`
-- Corresponding CSS: `background-position: 50% 10%;`
+It addresses two common issues when displaying images in cropped containers. First, large background images can be cropped in undesirable ways, especially on smaller viewports such as mobile devices. Second, the CSS aspect-ratio property can inadvertently crop out the area of highest visual interest. This component allows the selection of the point with the most important visual information and returns it as a pair of numbers between 0 and 1. The output value can be applied to either CSS `background-position` (for elements with `background-image`) or `object-position` (for `<img>` / `<video>` elements rendered with `object-fit: cover`).
+
+-   Example focal point picker value: `{ x: 0.5, y: 0.1 }`;
+-   Corresponding CSS: `object-position: 50% 10%`;
 
 ## Usage
 
 ```jsx
-import { useState } from 'react';
 import { FocalPointPicker } from '@wordpress/components';
+import { useState } from '@wordpress/element';
 
 const Example = () => {
 	const [ focalPoint, setFocalPoint ] = useState( {
 		x: 0.5,
-		y: 0.5,
+		y: 0.1,
 	} );
 
 	const url = '/path/to/image';
 
 	/* Example function to render the CSS styles based on Focal Point Picker value */
 	const style = {
-		backgroundImage: `url(${ url })`,
-		backgroundPosition: `${ focalPoint.x * 100 }% ${ focalPoint.y * 100 }%`,
+		width: '100%',
+		aspectRatio: '16 / 9',
+		objectFit: 'cover',
+		objectPosition: `${ focalPoint.x * 100 }% ${ focalPoint.y * 100 }%`,
 	};
 
 	return (
@@ -34,7 +38,7 @@ const Example = () => {
 				onDrag={ setFocalPoint }
 				onChange={ setFocalPoint }
 			/>
-			<div style={ style } />
+			<img src={ url } alt="" style={ style } />
 		</>
 	);
 };

package/src/focal-point-picker/index.tsx

@@ -44,14 +44,17 @@ const GRID_OVERLAY_TIMEOUT = 600;
 /**
  * Focal Point Picker is a component which creates a UI for identifying the most important visual point of an image.
  *
- * This component addresses a specific problem: with large background images it is common to see undesirable crops,
- * especially when viewing on smaller viewports such as mobile phones. This component allows the selection of
- * the point with the most important visual information and returns it as a pair of numbers between 0 and 1.
- * This value can be easily converted into the CSS `background-position` attribute, and will ensure that the
- * focal point is never cropped out, regardless of viewport.
+ * It addresses two common issues when displaying images in cropped containers. First, large
+ * background images can be cropped in undesirable ways, especially on smaller viewports such as
+ * mobile devices. Second, the CSS aspect-ratio property can inadvertently crop out the area of
+ * highest visual interest. This component allows the selection of the point with the most
+ * important visual information and returns it as a pair of numbers between 0 and 1.
+ * The output value can be applied to either CSS `background-position` (for elements with
+ * `background-image`) or `object-position` (for `<img>` / `<video>` elements rendered with
+ * `object-fit: cover`).
  *
- * - Example focal point picker value: `{ x: 0.5, y: 0.1 }`
- * - Corresponding CSS: `background-position: 50% 10%;`
+ * - Example focal point picker value: `{ x: 0.5, y: 0.1 }`;
+ * - Corresponding CSS: `object-position: 50% 10%`;
  *
  * ```jsx
  * import { FocalPointPicker } from '@wordpress/components';
@@ -60,15 +63,17 @@ const GRID_OVERLAY_TIMEOUT = 600;
  * const Example = () => {
  * 	const [ focalPoint, setFocalPoint ] = useState( {
  * 		x: 0.5,
- * 		y: 0.5,
+ * 		y: 0.1,
  * 	} );
  *
  * 	const url = '/path/to/image';
  *
  * 	// Example function to render the CSS styles based on Focal Point Picker value
  * 	const style = {
- * 		backgroundImage: `url(${ url })`,
- * 		backgroundPosition: `${ focalPoint.x * 100 }% ${ focalPoint.y * 100 }%`,
+ * 		width: '100%',
+ * 		aspectRatio: '16 / 9',
+ * 		objectFit: 'cover',
+ * 		objectPosition: `${ focalPoint.x * 100 }% ${ focalPoint.y * 100 }%`,
  * 	};
  *
  * 	return (
@@ -80,7 +85,7 @@ const GRID_OVERLAY_TIMEOUT = 600;
  * 				onDrag={ setFocalPoint }
  * 				onChange={ setFocalPoint }
  * 			/>
- * 			<div style={ style } />
+ * 			<img src={ url } alt="" style={ style } />
  * 		</>
  * 	);
  * };

package/src/focal-point-picker/stories/index.story.tsx

@@ -30,7 +30,7 @@ const meta: Meta< typeof FocalPointPicker > = {
 		controls: { expanded: true },
 		docs: { canvas: { sourceState: 'shown' } },
 		componentStatus: {
-			status: 'stable',
+			status: 'recommended',
 			whereUsed: 'editor',
 		},
 	},

package/src/font-size-picker/stories/index.story.tsx

@@ -31,7 +31,7 @@ const meta: Meta< typeof FontSizePicker > = {
 		controls: { expanded: true },
 		docs: { canvas: { sourceState: 'shown' } },
 		componentStatus: {
-			status: 'stable',
+			status: 'recommended',
 			whereUsed: 'editor',
 		},
 	},

package/src/form-file-upload/stories/index.story.tsx

@@ -27,7 +27,7 @@ const meta: Meta< typeof FormFileUpload > = {
 		controls: { expanded: true },
 		docs: { canvas: { sourceState: 'shown' } },
 		componentStatus: {
-			status: 'stable',
+			status: 'recommended',
 			whereUsed: 'global',
 		},
 	},

package/src/form-toggle/stories/index.story.tsx

@@ -28,7 +28,7 @@ const meta: Meta< typeof FormToggle > = {
 		},
 		docs: { canvas: { sourceState: 'shown' } },
 		componentStatus: {
-			status: 'stable',
+			status: 'recommended',
 			whereUsed: 'global',
 			notes: 'For standard toggles with labels, use `ToggleControl` instead.',
 		},

package/src/form-toggle/style.scss

@@ -2,7 +2,6 @@
 @use "@wordpress/base-styles/colors" as *;
 @use "@wordpress/base-styles/mixins" as *;
 @use "@wordpress/base-styles/variables" as *;
-@use "@wordpress/base-styles/z-index" as *;
 @use "../utils/theme-variables" as *;
 
 $toggle-width: $grid-unit-40;
@@ -14,6 +13,7 @@ $transition-duration: 0.2s;
 
 .components-form-toggle {
 	position: relative;
+	isolation: isolate;
 	display: inline-block;
 	height: $toggle-height;
 
@@ -151,7 +151,8 @@ $transition-duration: 0.2s;
 	opacity: 0;
 	margin: 0;
 	padding: 0;
-	z-index: z-index(".components-form-toggle__input");
+	// Sit above the visual track and thumb so the invisible input receives pointer events.
+	z-index: 1;
 
 	// This overrides a border style that is inherited from parent checkbox styles.
 	border: none;

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

@@ -51,6 +51,7 @@ The `value` property is handled in a manner similar to controlled form component
 -   `maxLength` - If passed, `TokenField` will disable ability to add new tokens once number of tokens is greater than or equal to `maxLength`.
 -   `disabled` - When true, tokens are not able to be added or removed.
 -   `placeholder` - If passed, the `TokenField` input will show a placeholder string if no value tokens are present.
+-   `help` - Additional description for the control. Only use for meaningful description or instructions for the control. An element containing the description will be programmatically associated to the `FormTokenField` via `aria-describedby`. Defaults to a how-to message (e.g. _Separate with commas or the Enter key._); pass an empty string to hide it.
 -   `messages` - Allows customizing the messages presented by screen readers in different occasions:
     -   `added` - The user added a new token.
     -   `removed` - The user removed an existing token.
@@ -58,7 +59,7 @@ The `value` property is handled in a manner similar to controlled form component
     -   `__experimentalInvalid` - The user tried to add a token that didn't pass the validation.
 -   `__experimentalRenderItem` - Custom renderer invoked for each option in the suggestion list. The render prop receives as its argument an object containing, under the `item` key, the single option's data (directly from the array of data passed to the `options` prop).
 -   `__experimentalExpandOnFocus` - If true, the suggestions list will be always expanded when the input field has the focus.
--   `__experimentalShowHowTo` - If false, the text on how to use the select (ie: _Separate with commas or the Enter key._) will be hidden.
+-   `__experimentalShowHowTo` - **Deprecated.** Use the `help` prop instead. The `help` prop now defaults to the previous how-to text; if you were passing `__experimentalShowHowTo={ false }` to hide it, pass an empty string to `help` instead.
 -   `__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).
 -   `__next40pxDefaultSize` - Start opting into the larger default height that will become the default size in a future version.