@wordpress/components 19.11.0 → 19.14.0

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

@@ -0,0 +1,178 @@
+/**
+ * External dependencies
+ */
+import type { ComponentPropsWithRef, MouseEventHandler } from 'react';
+
+type Messages = {
+	/**
+	 * The user added a new token.
+	 */
+	added: string;
+	/**
+	 * The user removed an existing token.
+	 */
+	removed: string;
+	/**
+	 * The user focused the button to remove the token.
+	 */
+	remove: string;
+	/**
+	 * The user tried to add a token that didn't pass the validation.
+	 */
+	__experimentalInvalid: string;
+};
+
+export interface TokenItem {
+	/**
+	 *  The value of the token.
+	 */
+	value: string;
+	/**
+	 * One of 'error', 'validating', or 'success'. Applies styles to token.
+	 */
+	status?: 'error' | 'success' | 'validating';
+	/**
+	 * If not falsey, will add a title to the token.
+	 */
+	title?: string;
+	/**
+	 * When true, renders tokens as without a background.
+	 */
+	isBorderless?: boolean;
+	/**
+	 * Function to call when onMouseEnter event triggered on token.
+	 */
+	onMouseEnter?: MouseEventHandler< HTMLSpanElement >;
+	/**
+	 *  Function to call when onMouseLeave is triggered on token.
+	 */
+	onMouseLeave?: MouseEventHandler< HTMLSpanElement >;
+}
+
+export interface FormTokenFieldProps
+	extends Pick<
+		ComponentPropsWithRef< 'input' >,
+		'autoCapitalize' | 'autoComplete' | 'className'
+	> {
+	label?: string;
+	/**
+	 * An array of strings to present to the user as suggested tokens.
+	 */
+	suggestions?: string[];
+	/**
+	 * The maximum number of suggestions to display at a time.
+	 *
+	 * @default 100
+	 */
+	maxSuggestions?: number;
+	/**
+	 * An array of strings or objects to display as tokens in the field.
+	 * If objects are present in the array, they **must** have a property of `value`.
+	 */
+	value?: ( string | TokenItem )[];
+	/**
+	 * Function to call to transform tokens for display.
+	 * (In the editor, this is needed to decode HTML entities embedded in tags
+	 * - otherwise entities like `&` in tag names are double-encoded like `&amp;`,
+	 * once by the REST API and once by React).
+	 */
+	displayTransform?: ( token: string ) => string;
+	/**
+	 * Function to call to transform tokens for saving. The default is to trim the token value.
+	 * This function is also applied when matching suggestions against the current value
+	 * so that matching works correctly with leading or trailing spaces. (In the editor,
+	 * this is needed to remove leading and trailing spaces from tag names, like wp-admin does.
+	 * Otherwise the REST API won't save them.)
+	 *
+	 * @default ( token: string ) => token.trim()
+	 */
+	saveTransform?: ( token: string ) => string;
+	/**
+	 * Function to call when the tokens have changed. An array of new tokens is passed to the callback.
+	 *
+	 */
+	onChange?: ( tokens: ( string | TokenItem )[] ) => void;
+	/**
+	 * Function to call when the users types in the input field. It can be used to trigger autocomplete requests.
+	 *
+	 */
+	onInputChange?: ( input: string ) => void;
+	/**
+	 * Function to call when the TokenField has been focused on. The event is passed to the callback. Useful for analytics.
+	 *
+	 */
+	onFocus?: ( event: FocusEvent ) => void;
+	/**
+	 *  When true, renders tokens as without a background.
+	 */
+	isBorderless?: boolean;
+	/**
+	 * If passed, `TokenField` will disable ability to add new tokens once number of tokens is greater than or equal to `maxLength`.
+	 */
+	maxLength?: number;
+	/**
+	 * When true, tokens are not able to be added or removed.
+	 */
+	disabled?: boolean;
+	/**
+	 * If passed, the `TokenField` input will show a placeholder string if no value tokens are present.
+	 */
+	placeholder?: string;
+	/**
+	 * If true, will add a token when `TokenField` is focused and `space` is pressed.
+	 */
+	tokenizeOnSpace?: boolean;
+	/**
+	 * 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.
+	 * -   `remove` : The user focused the button to remove the token.
+	 * -   `__experimentalInvalid`: The user tried to add a token that didn't pass the validation.
+	 */
+	messages?: Messages;
+	/**
+	 * If true, the suggestions list will be always expanded when the input field has the focus.
+	 */
+	__experimentalExpandOnFocus?: boolean;
+	/**
+	 * If passed, all introduced values will be validated before being added as tokens.
+	 *
+	 * @default () => true
+	 */
+	__experimentalValidateInput?: ( token: string ) => boolean;
+	/**
+	 * If false, the text on how to use the select (ie: _Separate with commas or the Enter key._) will be hidden.
+	 *
+	 * @default true
+	 */
+	__experimentalShowHowTo?: boolean;
+}
+
+export interface SuggestionsListProps< T = string | { value: string } > {
+	selectedIndex: number;
+	scrollIntoView: boolean;
+	match: T;
+	onHover: ( suggestion: T ) => void;
+	onSelect: ( suggestion: T ) => void;
+	suggestions: T[];
+	displayTransform: ( value: T ) => string;
+	instanceId: string | number;
+}
+
+export interface TokenProps extends TokenItem {
+	displayTransform: ( value: string ) => string;
+	disabled: boolean;
+	onClickRemove: ( { value }: { value: string } ) => void;
+	messages: Messages;
+	termPosition: number;
+	termsCount: number;
+}
+
+export interface TokenInputProps {
+	isExpanded: boolean;
+	instanceId: string | number;
+	selectedSuggestionIndex: number;
+	onChange?: ( { value }: { value: string } ) => void;
+	value: string;
+}

package/src/gradient-picker/index.js

@@ -108,9 +108,10 @@ export default function GradientPicker( {
 	__experimentalHasMultipleOrigins,
 	__experimentalIsRenderedInSidebar,
 } ) {
-	const clearGradient = useCallback( () => onChange( undefined ), [
-		onChange,
-	] );
+	const clearGradient = useCallback(
+		() => onChange( undefined ),
+		[ onChange ]
+	);
 	const Component =
 		__experimentalHasMultipleOrigins && gradients?.length
 			? MultipleOrigin

package/src/h-stack/utils.js

@@ -1,7 +1,7 @@
 /**
- * External dependencies
+ * Internal dependencies
  */
-import { isNil } from 'lodash';
+import { isValueDefined } from '../utils/values';
 
 /** @type {import('./types').Alignments} */
 const ALIGNMENTS = {
@@ -41,7 +41,7 @@ const V_ALIGNMENTS = {
  */
 /* eslint-enable jsdoc/valid-types */
 export function getAlignmentProps( alignment, direction = 'row' ) {
-	if ( isNil( alignment ) ) {
+	if ( ! isValueDefined( alignment ) ) {
 		return {};
 	}
 	const isVertical = direction === 'column';

package/src/heading/README.md

@@ -20,8 +20,9 @@ function Example() {
 
 `Heading` uses `Text` underneath, so we have access to all of `Text`'s props except for `size` which is replaced by `level`. For a complete list of those props, check out [`Text`](/packages/components/src/text/README.md#props).
 
-##### level
-
-**Type**: `1 | 2 | 3 | 4 | 5 | 6`
+##### `level`: `1 | 2 | 3 | 4 | 5 | 6 | '1' | '2' | '3' | '4' | '5' | '6'`
 
 Passing any of the heading levels to `level` will both render the correct typographic text size as well as the semantic element corresponding to the level (`h1` for `1` for example).
+
+-   Required: No
+-   Default: `2`

package/src/heading/component.tsx

@@ -8,7 +8,8 @@ import type { ForwardedRef } from 'react';
  */
 import { contextConnect, WordPressComponentProps } from '../ui/context';
 import { View } from '../view';
-import { useHeading, HeadingProps } from './hook';
+import { useHeading } from './hook';
+import type { HeadingProps } from './types';
 
 function UnconnectedHeading(
 	props: WordPressComponentProps< HeadingProps, 'h1' >,
@@ -22,7 +23,6 @@ function UnconnectedHeading(
 /**
  * `Heading` renders headings and titles using the library's typography system.
  *
- * @example
  * ```jsx
  * import { __experimentalHeading as Heading } from "@wordpress/components";
  *

package/src/heading/hook.ts

@@ -2,59 +2,19 @@
  * Internal dependencies
  */
 import { useContextSystem, WordPressComponentProps } from '../ui/context';
-import type { Props as TextProps } from '../text/types';
 import { useText } from '../text';
 import { getHeadingFontSize } from '../ui/utils/font-size';
 import { CONFIG, COLORS } from '../utils';
-
-export type HeadingSize =
-	| 1
-	| 2
-	| 3
-	| 4
-	| 5
-	| 6
-	| '1'
-	| '2'
-	| '3'
-	| '4'
-	| '5'
-	| '6';
-
-export interface HeadingProps extends Omit< TextProps, 'size' > {
-	/**
-	 * `Heading` will typically render the sizes `1`, `2`, `3`, `4`, `5`, or `6`, which map to `h1`-`h6`.
-	 *
-	 * @default 2
-	 *
-	 * @example
-	 * ```jsx
-	 * import { __experimentalHeading as Heading } from `@wordpress/components`
-	 *
-	 * function Example() {
-	 *   return (
-	 *     <div>
-	 *       <Heading level="1">Code is Poetry</Heading>
-	 *       <Heading level="2">Code is Poetry</Heading>
-	 *       <Heading level="3">Code is Poetry</Heading>
-	 *       <Heading level="4">Code is Poetry</Heading>
-	 *       <Heading level="5">Code is Poetry</Heading>
-	 *       <Heading level="6">Code is Poetry</Heading>
-	 *     </div>
-	 *   );
-	 * }
-	 * ```
-	 */
-	level: HeadingSize;
-}
+import type { HeadingProps } from './types';
 
 export function useHeading(
 	props: WordPressComponentProps< HeadingProps, 'h1' >
 ) {
-	const { as: asProp, level = 2, ...otherProps } = useContextSystem(
-		props,
-		'Heading'
-	);
+	const {
+		as: asProp,
+		level = 2,
+		...otherProps
+	} = useContextSystem( props, 'Heading' );
 
 	const as = ( asProp || `h${ level }` ) as keyof JSX.IntrinsicElements;
 

package/src/heading/stories/index.tsx

@@ -19,7 +19,11 @@ const meta: ComponentMeta< typeof Heading > = {
 		letterSpacing: { control: { type: 'text' } },
 		lineHeight: { control: { type: 'text' } },
 		optimizeReadabilityFor: { control: { type: 'color' } },
-		variant: { control: { type: 'radio' }, options: [ 'muted' ] },
+		variant: {
+			control: { type: 'radio' },
+			options: [ 'undefined', 'muted' ],
+			mapping: { undefined, muted: 'muted' },
+		},
 		weight: { control: { type: 'text' } },
 	},
 	parameters: {

package/src/heading/test/index.tsx

@@ -0,0 +1,68 @@
+/**
+ * External dependencies
+ */
+import { render, screen } from '@testing-library/react';
+
+/**
+ * Internal dependencies
+ */
+import { Heading } from '../';
+
+describe( 'props', () => {
+	test( 'should render correctly', () => {
+		render( <Heading>Code is Poetry</Heading> );
+		expect( screen.getByRole( 'heading' ) ).toMatchSnapshot();
+	} );
+
+	test( 'should render level as a number', () => {
+		render( <Heading>Code is Poetry</Heading> );
+		render( <Heading level={ 4 }>Code is Poetry</Heading> );
+		expect(
+			screen.getByRole( 'heading', { level: 4 } )
+		).toMatchStyleDiffSnapshot(
+			screen.getByRole( 'heading', { level: 2 } )
+		);
+	} );
+
+	test( 'should render level as a string', () => {
+		render( <Heading>Code is Poetry</Heading> );
+		render( <Heading level="4">Code is Poetry</Heading> );
+		expect(
+			screen.getByRole( 'heading', { level: 4 } )
+		).toMatchStyleDiffSnapshot(
+			screen.getByRole( 'heading', { level: 2 } )
+		);
+	} );
+
+	test( 'should allow as prop', () => {
+		render(
+			<Heading level="1" as="span">
+				Code is Poetry
+			</Heading>
+		);
+		expect( screen.getByRole( 'heading' ).tagName ).toBe( 'SPAN' );
+	} );
+
+	test( 'should render a11y props when not using a semantic element', () => {
+		render(
+			<Heading level="3" as="div">
+				Code is Poetry
+			</Heading>
+		);
+		expect(
+			screen.getByRole( 'heading', { level: 3 } )
+		).toBeInTheDocument();
+	} );
+
+	test( 'should not render a11y props when using a semantic element', () => {
+		render(
+			<Heading level="1" as="h4">
+				Code is Poetry
+			</Heading>
+		);
+		expect( screen.getByRole( 'heading' ) ).not.toHaveAttribute( 'role' );
+		expect( screen.getByRole( 'heading' ) ).not.toHaveAttribute(
+			'aria-level'
+		);
+	} );
+} );

package/src/heading/types.ts

@@ -0,0 +1,29 @@
+/**
+ * Internal dependencies
+ */
+import type { Props as TextProps } from '../text/types';
+
+export type HeadingSize =
+	| 1
+	| 2
+	| 3
+	| 4
+	| 5
+	| 6
+	| '1'
+	| '2'
+	| '3'
+	| '4'
+	| '5'
+	| '6';
+
+export type HeadingProps = Omit< TextProps, 'size' > & {
+	/**
+	 * Passing any of the heading levels to `level` will both render the correct
+	 * typographic text size as well as the semantic element corresponding to
+	 * the level (`h1` for `1` for example).
+	 *
+	 * @default 2
+	 */
+	level?: HeadingSize;
+};

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

@@ -95,10 +95,12 @@ export function useNavigateRegions( shortcuts = defaultShortcuts ) {
 }
 
 export default createHigherOrderComponent(
-	( Component ) => ( { shortcuts, ...props } ) => (
-		<div { ...useNavigateRegions( shortcuts ) }>
-			<Component { ...props } />
-		</div>
-	),
+	( Component ) =>
+		( { shortcuts, ...props } ) =>
+			(
+				<div { ...useNavigateRegions( shortcuts ) }>
+					<Component { ...props } />
+				</div>
+			),
 	'navigateRegions'
 );

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

@@ -81,12 +81,13 @@ describe( 'withFilters', () => {
 		addFilter(
 			hookName,
 			'test/enhanced-component-compose',
-			( FilteredComponent ) => () => (
-				<div>
-					<FilteredComponent />
-					<ComposedComponent />
-				</div>
-			)
+			( FilteredComponent ) => () =>
+				(
+					<div>
+						<FilteredComponent />
+						<ComposedComponent />
+					</div>
+				)
 		);
 		const EnhancedComponent = withFilters( hookName )( MyComponent );
 
@@ -106,11 +107,12 @@ describe( 'withFilters', () => {
 		addFilter(
 			hookName,
 			'test/enhanced-component-spy-1',
-			( FilteredComponent ) => () => (
-				<blockquote>
-					<FilteredComponent />
-				</blockquote>
-			)
+			( FilteredComponent ) => () =>
+				(
+					<blockquote>
+						<FilteredComponent />
+					</blockquote>
+				)
 		);
 		const EnhancedComponent = withFilters( hookName )( SpiedComponent );
 
@@ -143,11 +145,12 @@ describe( 'withFilters', () => {
 		addFilter(
 			hookName,
 			'test/enhanced-component-spy-1',
-			( FilteredComponent ) => () => (
-				<blockquote>
-					<FilteredComponent />
-				</blockquote>
-			)
+			( FilteredComponent ) => () =>
+				(
+					<blockquote>
+						<FilteredComponent />
+					</blockquote>
+				)
 		);
 		jest.runAllTimers();
 
@@ -174,20 +177,22 @@ 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>
+				)
 		);
 		jest.runAllTimers();
 
@@ -213,11 +218,12 @@ describe( 'withFilters', () => {
 		addFilter(
 			hookName,
 			'test/enhanced-component-spy',
-			( FilteredComponent ) => () => (
-				<div>
-					<FilteredComponent />
-				</div>
-			)
+			( FilteredComponent ) => () =>
+				(
+					<div>
+						<FilteredComponent />
+					</div>
+				)
 		);
 		jest.runAllTimers();
 
@@ -249,11 +255,12 @@ describe( 'withFilters', () => {
 		addFilter(
 			hookName,
 			'test/enhanced-component-spy-1',
-			( FilteredComponent ) => () => (
-				<blockquote>
-					<FilteredComponent />
-				</blockquote>
-			)
+			( FilteredComponent ) => () =>
+				(
+					<blockquote>
+						<FilteredComponent />
+					</blockquote>
+				)
 		);
 		jest.runAllTimers();
 

package/src/higher-order/with-focus-return/index.js

@@ -31,18 +31,20 @@ function isComponentLike( object ) {
  * @return {Function} Higher Order Component with the focus restauration behaviour.
  */
 export default createHigherOrderComponent( ( options ) => {
-	const HoC = ( { onFocusReturn } = {} ) => ( WrappedComponent ) => {
-		const WithFocusReturn = ( props ) => {
-			const ref = useFocusReturn( onFocusReturn );
-			return (
-				<div ref={ ref }>
-					<WrappedComponent { ...props } />
-				</div>
-			);
-		};
+	const HoC =
+		( { onFocusReturn } = {} ) =>
+		( WrappedComponent ) => {
+			const WithFocusReturn = ( props ) => {
+				const ref = useFocusReturn( onFocusReturn );
+				return (
+					<div ref={ ref }>
+						<WrappedComponent { ...props } />
+					</div>
+				);
+			};
 
-		return WithFocusReturn;
-	};
+			return WithFocusReturn;
+		};
 
 	if ( isComponentLike( options ) ) {
 		const WrappedComponent = options;
@@ -55,8 +57,7 @@ export default createHigherOrderComponent( ( options ) => {
 export const Provider = ( { children } ) => {
 	deprecated( 'wp.components.FocusReturnProvider component', {
 		since: '5.7',
-		hint:
-			'This provider is not used anymore. You can just remove it from your codebase',
+		hint: 'This provider is not used anymore. You can just remove it from your codebase',
 	} );
 
 	return children;

package/src/higher-order/with-spoken-messages/index.js

@@ -15,12 +15,13 @@ import { speak } from '@wordpress/a11y';
  * @return {WPComponent} The wrapped component.
  */
 export default createHigherOrderComponent(
-	( Component ) => ( props ) => (
-		<Component
-			{ ...props }
-			speak={ speak }
-			debouncedSpeak={ useDebounce( speak, 500 ) }
-		/>
-	),
+	( Component ) => ( props ) =>
+		(
+			<Component
+				{ ...props }
+				speak={ speak }
+				debouncedSpeak={ useDebounce( speak, 500 ) }
+			/>
+		),
 	'withSpokenMessages'
 );

package/src/higher-order/with-spoken-messages/test/index.js

@@ -2,7 +2,6 @@
  * External dependencies
  */
 import { render } from 'enzyme';
-import { isFunction } from 'lodash';
 
 /**
  * Internal dependencies
@@ -13,6 +12,7 @@ describe( 'withSpokenMessages', () => {
 	it( 'should generate speak and debouncedSpeak props', () => {
 		const testSpeak = jest.fn();
 		const testDebouncedSpeak = jest.fn();
+		const isFunction = ( maybeFunc ) => typeof maybeFunc === 'function';
 		const DumpComponent = withSpokenMessages(
 			( { speak, debouncedSpeak } ) => {
 				testSpeak( isFunction( speak ) );

package/src/icon/index.tsx

@@ -68,10 +68,10 @@ function Icon< P >( {
 
 	if ( 'function' === typeof icon ) {
 		if ( icon.prototype instanceof Component ) {
-			return createElement( icon, ( {
+			return createElement( icon, {
 				size,
 				...additionalProps,
-			} as unknown ) as P );
+			} as unknown as P );
 		}
 
 		return ( icon as ( ...args: any[] ) => JSX.Element )( {