@wordpress/components 20.0.2-next.957ca95e4c.0 → 21.0.0

package/src/focal-point-picker/test/index.js

@@ -7,7 +7,7 @@ import userEvent from '@testing-library/user-event';
 /**
  * Internal dependencies
  */
-import Picker from '../index.js';
+import Picker from '..';
 
 describe( 'FocalPointPicker', () => {
 	describe( 'focus and blur', () => {
@@ -112,9 +112,9 @@ describe( 'FocalPointPicker', () => {
 			await user.keyboard( '[ArrowUp]' );
 
 			expect( spy ).toHaveBeenCalled();
-			expect( spyChange ).toHaveBeenCalledWith( {
-				x: '0.91',
-				y: '0.42',
+			expect( spyChange ).toHaveBeenLastCalledWith( {
+				x: 0.91,
+				y: 0.42,
 			} );
 		} );
 	} );
@@ -143,10 +143,30 @@ describe( 'FocalPointPicker', () => {
 			await user.click( dragArea );
 			await user.keyboard( '[ArrowDown]' );
 
-			expect( spyChange ).toHaveBeenCalledWith( {
-				x: '0.14',
-				y: '0.63',
+			expect( spyChange ).toHaveBeenLastCalledWith( {
+				x: 0.14,
+				y: 0.63,
 			} );
 		} );
 	} );
+
+	describe( 'value handling', () => {
+		it( 'should handle legacy string values', () => {
+			const onChangeSpy = jest.fn();
+			render(
+				<Picker
+					value={ { x: '0.1', y: '0.2' } }
+					onChange={ onChangeSpy }
+				/>
+			);
+
+			expect(
+				screen.getByRole( 'spinbutton', { name: 'Left' } ).value
+			).toBe( '10' );
+			expect(
+				screen.getByRole( 'spinbutton', { name: 'Top' } ).value
+			).toBe( '20' );
+			expect( onChangeSpy ).not.toHaveBeenCalled();
+		} );
+	} );
 } );

package/src/focal-point-picker/types.ts

@@ -0,0 +1,93 @@
+/**
+ * External dependencies
+ */
+import type {
+	CSSProperties,
+	ReactEventHandler,
+	Ref,
+	VideoHTMLAttributes,
+} from 'react';
+
+/**
+ * Internal dependencies
+ */
+import type { BaseControlProps } from '../base-control/types';
+
+export type FocalPoint = Record< FocalPointAxis, number >;
+export type FocalPointAxis = 'x' | 'y';
+
+export type FocalPointPickerProps = Pick<
+	BaseControlProps,
+	'help' | 'hideLabelFromVision' | 'label'
+> & {
+	/**
+	 * Start opting into the new margin-free styles that will become the default in a future version.
+	 *
+	 * @default false
+	 */
+	__nextHasNoMarginBottom?: boolean;
+	/**
+	 * Autoplays HTML5 video. This only applies to video sources (`url`).
+	 *
+	 * @default true
+	 */
+	autoPlay?: FocalPointPickerMediaProps[ 'autoPlay' ];
+	/**
+	 * Callback which is called when the focal point changes.
+	 */
+	onChange: ( value: FocalPoint ) => void;
+	onDrag?: ( value: FocalPoint, event: MouseEvent ) => void;
+	/**
+	 * Callback which is called at the end of drag operations.
+	 */
+	onDragEnd?: () => void;
+	/**
+	 * Callback which is called at the start of drag operations.
+	 */
+	onDragStart?: ( value: FocalPoint, event: React.MouseEvent ) => void;
+	/**
+	 * Function which is called before internal updates to the value state.
+	 * It receives the upcoming value and may return a modified one.
+	 */
+	resolvePoint?: ( point: FocalPoint ) => FocalPoint;
+	/**
+	 * URL of the image or video to be displayed.
+	 */
+	url: FocalPointPickerMediaProps[ 'src' ];
+	/**
+	 * The focal point. Should be an object containing `x` and `y` params.
+	 */
+	value: FocalPoint;
+};
+
+export type FocalPointPickerControlsProps = {
+	__nextHasNoMarginBottom?: boolean;
+	/**
+	 * A bit of extra bottom margin will be added if a `help` text
+	 * needs to be rendered under it.
+	 */
+	hasHelpText: boolean;
+	onChange?: ( value: FocalPoint ) => void;
+	point?: FocalPoint;
+};
+
+export type FocalPointPickerGridProps = {
+	bounds: { width: number; height: number };
+	showOverlay?: boolean;
+};
+
+export type FocalPointPickerMediaProps = Pick<
+	VideoHTMLAttributes< HTMLVideoElement >,
+	'autoPlay' | 'muted'
+> & {
+	alt: string;
+	mediaRef?: Ref< HTMLDivElement | HTMLVideoElement | HTMLImageElement >;
+	onLoad?: ReactEventHandler< HTMLVideoElement | HTMLImageElement >;
+	src: string;
+};
+
+export type FocalPointProps = {
+	isDragging: boolean;
+	left: CSSProperties[ 'left' ];
+	top: CSSProperties[ 'top' ];
+};

package/src/focal-point-picker/{utils.js → utils.ts}

@@ -19,10 +19,10 @@ const VIDEO_EXTENSIONS = [
 /**
  * Gets the extension of a file name.
  *
- * @param {string} filename The file name.
- * @return {string} The extension of the file name.
+ * @param  filename The file name.
+ * @return  The extension of the file name.
  */
-export function getExtension( filename = '' ) {
+export function getExtension( filename = '' ): string {
 	const parts = filename.split( '.' );
 	return parts[ parts.length - 1 ];
 }
@@ -30,10 +30,10 @@ export function getExtension( filename = '' ) {
 /**
  * Checks if a file is a video.
  *
- * @param {string} filename The file name.
- * @return {boolean} Whether the file is a video.
+ * @param  filename The file name.
+ * @return Whether the file is a video.
  */
-export function isVideoType( filename = '' ) {
+export function isVideoType( filename: string = '' ): boolean {
 	if ( ! filename ) return false;
 	return VIDEO_EXTENSIONS.includes( getExtension( filename ) );
 }
@@ -41,9 +41,9 @@ export function isVideoType( filename = '' ) {
 /**
  * Transforms a fraction value to a percentage value.
  *
- * @param {number} fraction The fraction value.
- * @return {number} A percentage value.
+ * @param  fraction The fraction value.
+ * @return A percentage value.
  */
-export function fractionToPercentage( fraction ) {
+export function fractionToPercentage( fraction: number ): number {
 	return Math.round( fraction * 100 );
 }

package/src/font-size-picker/README.md

@@ -29,6 +29,7 @@ const MyFontSizePicker = () => {
 
 	return (
 		<FontSizePicker
+			__nextHasNoMarginBottom
 			fontSizes={ fontSizes }
 			value={ fontSize }
 			fallbackFontSize={ fallbackFontSize }
@@ -105,3 +106,11 @@ If `true`, a reset button will be displayed alongside the input field when a cus
 -   Type: `Boolean`
 -   Required: no
 -   Default: `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.4. (The prop can be safely removed once this happens.)
+
+-   Type: `Boolean`
+-   Required: no
+-   Default: `false`

package/src/font-size-picker/index.js

@@ -6,6 +6,7 @@ import classNames from 'classnames';
 /**
  * WordPress dependencies
  */
+import deprecated from '@wordpress/deprecated';
 import { __, sprintf } from '@wordpress/i18n';
 import { settings } from '@wordpress/icons';
 import { useState, useMemo, forwardRef } from '@wordpress/element';
@@ -58,6 +59,14 @@ function FontSizePicker(
 	},
 	ref
 ) {
+	if ( ! __nextHasNoMarginBottom ) {
+		deprecated( 'Bottom margin styles for wp.components.FontSizePicker', {
+			since: '6.1',
+			version: '6.4',
+			hint: 'Set the `__nextHasNoMarginBottom` prop to true to start opting into the new styles, which will become the default in a future version.',
+		} );
+	}
+
 	const hasUnits = [ typeof value, typeof fontSizes?.[ 0 ]?.size ].includes(
 		'string'
 	);

package/src/font-size-picker/stories/index.js

@@ -12,17 +12,14 @@ export default {
 	title: 'Components/FontSizePicker',
 	component: FontSizePicker,
 	argTypes: {
-		__nextHasNoMarginBottom: { control: { type: 'boolean' } },
 		initialValue: { table: { disable: true } }, // hide prop because it's not actually part of FontSizePicker
 		fallbackFontSize: {
 			description:
 				'If no value exists, this prop defines the starting position for the font size picker slider. Only relevant if `withSlider` is `true`.',
 		},
 		size: {
-			control: {
-				type: 'radio',
-				options: [ 'default', '__unstable-large' ],
-			},
+			control: { type: 'radio' },
+			options: [ 'default', '__unstable-large' ],
 		},
 		withReset: {
 			description:
@@ -68,6 +65,7 @@ const TwoFontSizePickersWithState = ( { fontSizes, ...props } ) => {
 
 export const Default = FontSizePickerWithState.bind( {} );
 Default.args = {
+	__nextHasNoMarginBottom: true,
 	disableCustomFontSizes: false,
 	fontSizes: [
 		{

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

@@ -28,7 +28,11 @@ describe( 'FontSizePicker', () => {
 			);
 
 			render(
-				<FontSizePicker value={ fontSize } onChange={ setFontSize } />
+				<FontSizePicker
+					value={ fontSize }
+					onChange={ setFontSize }
+					__nextHasNoMarginBottom
+				/>
 			);
 
 			const unitSelect = getUnitSelect();
@@ -52,7 +56,11 @@ describe( 'FontSizePicker', () => {
 			);
 
 			render(
-				<FontSizePicker value={ fontSize } onChange={ setFontSize } />
+				<FontSizePicker
+					value={ fontSize }
+					onChange={ setFontSize }
+					__nextHasNoMarginBottom
+				/>
 			);
 
 			const unitSelect = getUnitSelect();
@@ -87,6 +95,7 @@ describe( 'FontSizePicker', () => {
 					fontSizes={ fontSizes }
 					value={ fontSize }
 					onChange={ setFontSize }
+					__nextHasNoMarginBottom
 				/>
 			);
 
@@ -123,6 +132,7 @@ describe( 'FontSizePicker', () => {
 					fontSizes={ fontSizes }
 					value={ fontSize }
 					onChange={ setFontSize }
+					__nextHasNoMarginBottom
 				/>
 			);
 
@@ -182,6 +192,7 @@ describe( 'FontSizePicker', () => {
 				<FontSizePicker
 					fontSizes={ fontSizes }
 					value={ fontSizes[ 0 ].size }
+					__nextHasNoMarginBottom
 				/>
 			);
 			// Trigger click to open the select menu and take into account
@@ -199,6 +210,7 @@ describe( 'FontSizePicker', () => {
 					<FontSizePicker
 						fontSizes={ fontSizes }
 						value={ fontSizes[ 0 ].size }
+						__nextHasNoMarginBottom
 					/>
 				);
 				const element = screen.getByLabelText( 'Large' );
@@ -218,6 +230,7 @@ describe( 'FontSizePicker', () => {
 					<FontSizePicker
 						fontSizes={ fontSizes }
 						value={ fontSizes[ 0 ].size }
+						__nextHasNoMarginBottom
 					/>
 				);
 				const largeElement = screen.getByLabelText( 'Large' );

package/src/font-size-picker/test/utils.js

@@ -103,7 +103,6 @@ describe( 'getToggleGroupOptions', () => {
 			{
 				slug: '5',
 				size: '5',
-				name: '5',
 			},
 		];
 		expect(
@@ -143,7 +142,7 @@ describe( 'getToggleGroupOptions', () => {
 				key: '5',
 				value: '5',
 				label: 'XXL',
-				name: '5',
+				name: 'XXL',
 			},
 		] );
 	} );

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

@@ -114,7 +114,7 @@ export function getToggleGroupOptions(
 			key: slug,
 			value: size,
 			label: labelAliases[ index ],
-			name,
+			name: name || labelAliases[ index ],
 		};
 	} );
 }

package/src/form-file-upload/README.md

@@ -1,5 +1,7 @@
 # FormFileUpload
 
+FormFileUpload is a component that allows users to select files from their local device.
+
 ## Usage
 
 ```jsx
@@ -8,7 +10,7 @@ import { FormFileUpload } from '@wordpress/components';
 const MyFormFileUpload = () => (
 	<FormFileUpload
 		accept="image/*"
-		onChange={ ( event ) => console.log( event.target.files ) }
+		onChange={ ( event ) => console.log( event.currentTarget.files ) }
 	>
 		Upload
 	</FormFileUpload>
@@ -54,6 +56,8 @@ Whether to allow multiple selection of files or not.
 
 Callback function passed directly to the `input` file element.
 
+Select files will be available in `event.currentTarget.files`.
+
 -   Type: `Function`
 -   Required: Yes
 
@@ -78,6 +82,7 @@ This can be useful when you want to force a `change` event to fire when the user
 ### render
 
 Optional callback function used to render the UI. If passed the component does not render any UI and calls this function to render it.
+
 This function receives an object with the property `openFileDialog`. The property is a function that when called opens the browser window to upload files.
 
 -   Type: `Function`

package/src/form-file-upload/{index.js → index.tsx}

@@ -7,8 +7,26 @@ import { useRef } from '@wordpress/element';
  * Internal dependencies
  */
 import Button from '../button';
+import type { WordPressComponentProps } from '../ui/context';
+import type { FormFileUploadProps } from './types';
 
-function FormFileUpload( {
+/**
+ * FormFileUpload is a component that allows users to select files from their local device.
+ *
+ * ```jsx
+ * import { FormFileUpload } from '@wordpress/components';
+ *
+ * const MyFormFileUpload = () => (
+ *   <FormFileUpload
+ *     accept="image/*"
+ *     onChange={ ( event ) => console.log( event.currentTarget.files ) }
+ *   >
+ *     Upload
+ *   </FormFileUpload>
+ * );
+ * ```
+ */
+export function FormFileUpload( {
 	accept,
 	children,
 	multiple = false,
@@ -16,10 +34,10 @@ function FormFileUpload( {
 	onClick,
 	render,
 	...props
-} ) {
-	const ref = useRef();
+}: WordPressComponentProps< FormFileUploadProps, 'button', false > ) {
+	const ref = useRef< HTMLInputElement >( null );
 	const openFileDialog = () => {
-		ref.current.click();
+		ref.current?.click();
 	};
 
 	const ui = render ? (

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

@@ -0,0 +1,74 @@
+/**
+ * External dependencies
+ */
+import type { ComponentMeta, ComponentStory } from '@storybook/react';
+
+/**
+ * WordPress dependencies
+ */
+import { upload as uploadIcon } from '@wordpress/icons';
+
+/**
+ * Internal dependencies
+ */
+import FormFileUpload from '..';
+
+const meta: ComponentMeta< typeof FormFileUpload > = {
+	title: 'Components/FormFileUpload',
+	component: FormFileUpload,
+	argTypes: {
+		icon: { control: { type: null } },
+		onChange: { action: 'onChange', control: { type: null } },
+		onClick: { control: { type: null } },
+	},
+	parameters: {
+		controls: { expanded: true },
+		docs: { source: { state: 'open' } },
+	},
+};
+export default meta;
+
+const Template: ComponentStory< typeof FormFileUpload > = ( props ) => {
+	return <FormFileUpload { ...props } />;
+};
+
+export const Default = Template.bind( {} );
+Default.args = {
+	children: 'Select file',
+};
+
+export const RestrictFileTypes = Template.bind( {} );
+RestrictFileTypes.args = {
+	...Default.args,
+	accept: 'image/*',
+	children: 'Select image',
+};
+
+export const AllowMultipleFiles = Template.bind( {} );
+AllowMultipleFiles.args = {
+	...Default.args,
+	children: 'Select files',
+	multiple: true,
+};
+
+export const WithIcon = Template.bind( {} );
+WithIcon.args = {
+	...Default.args,
+	children: 'Upload',
+	icon: uploadIcon,
+};
+
+/**
+ * Render a custom trigger button by passing a render function to the `render` prop.
+ *
+ * ```jsx
+ * ( { openFileDialog } ) => <button onClick={ openFileDialog }>Custom Upload Button</button>
+ * ```
+ */
+export const WithCustomRender = Template.bind( {} );
+WithCustomRender.args = {
+	...Default.args,
+	render: ( { openFileDialog } ) => (
+		<button onClick={ openFileDialog }>Custom Upload Button</button>
+	),
+};

package/src/form-file-upload/test/{index.js → index.tsx}

@@ -7,7 +7,7 @@ import userEvent from '@testing-library/user-event';
 /**
  * Internal dependencies
  */
-import FormFileUpload from '../';
+import FormFileUpload from '..';
 
 /**
  * Browser dependencies
@@ -32,7 +32,11 @@ describe( 'FormFileUpload', () => {
 	} );
 
 	it( 'should show an Icon Button and a hidden input', () => {
-		render( <FormFileUpload>My Upload Button</FormFileUpload> );
+		render(
+			<FormFileUpload onChange={ () => {} }>
+				My Upload Button
+			</FormFileUpload>
+		);
 
 		const button = screen.getByText( 'My Upload Button' );
 		const input = screen.getByTestId( 'form-file-upload-input' );
@@ -76,7 +80,7 @@ describe( 'FormFileUpload', () => {
 
 		render(
 			<FormFileUpload
-				onClick={ jest.fn( ( e ) => ( e.target.value = '' ) ) }
+				onClick={ jest.fn( ( e ) => ( e.currentTarget.value = '' ) ) }
 				onChange={ onChange }
 			>
 				My Upload Button

package/src/form-file-upload/types.ts

@@ -0,0 +1,63 @@
+/**
+ * External dependencies
+ */
+import type { ComponentProps, InputHTMLAttributes, ReactNode } from 'react';
+
+/**
+ * Internal dependencies
+ */
+import type Icon from '../icon';
+
+// TODO: Replace `children` and `icon` types with props from Button once Button is typed.
+export type FormFileUploadProps = {
+	/**
+	 * A string passed to `input` element that tells the browser which file types can be
+	 * upload to the upload by the user use. e.g: `image/*,video/*`.
+	 *
+	 * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/file#Unique_file_type_specifiers.
+	 */
+	accept?: InputHTMLAttributes< HTMLInputElement >[ 'accept' ];
+	/**
+	 * Children are passed as children of `Button`.
+	 */
+	children?: ReactNode;
+	/**
+	 * The icon to render in the `Button`.
+	 */
+	icon?: ComponentProps< typeof Icon >[ 'icon' ];
+	/**
+	 * Whether to allow multiple selection of files or not.
+	 */
+	multiple?: InputHTMLAttributes< HTMLInputElement >[ 'multiple' ];
+	/**
+	 * Callback function passed directly to the `input` file element.
+	 *
+	 * Select files will be available in `event.currentTarget.files`.
+	 */
+	onChange: InputHTMLAttributes< HTMLInputElement >[ 'onChange' ];
+	/**
+	 * Callback function passed directly to the `input` file element.
+	 *
+	 * This can be useful when you want to force a `change` event to fire when
+	 * the user chooses the same file again. To do this, set the target value to
+	 * an empty string in the `onClick` function.
+	 *
+	 * ```jsx
+	 * <FormFileUpload
+	 * 	onClick={ ( event ) => ( event.target.value = '' ) }
+	 * 	onChange={ onChange }
+	 * >
+	 * 	Upload
+	 * </FormFileUpload>
+	 * ```
+	 */
+	onClick?: InputHTMLAttributes< HTMLInputElement >[ 'onClick' ];
+	/**
+	 * Optional callback function used to render the UI.
+	 *
+	 * If passed, the component does not render any UI and calls this function to render it.
+	 * This function receives an object with the property `openFileDialog`.
+	 * The property is a function that when called opens the browser window to upload files.
+	 */
+	render?: ( arg: { openFileDialog: () => void } ) => void;
+};

package/src/form-toggle/index.tsx

@@ -31,12 +31,7 @@ export const noop = () => {};
  * ```
  */
 export function FormToggle(
-	// ref is omitted until we have `WordPressComponentPropsWithoutRef` or add
-	// ref forwarding to FormToggle.
-	props: Omit<
-		WordPressComponentProps< FormToggleProps, 'input', false >,
-		'ref'
-	>
+	props: WordPressComponentProps< FormToggleProps, 'input', false >
 ) {
 	const {
 		className,

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

@@ -1,7 +1,6 @@
 /**
  * External dependencies
  */
-import { last, clone, map, some } from 'lodash';
 import classnames from 'classnames';
 import type { KeyboardEvent, MouseEvent, TouchEvent } from 'react';
 
@@ -258,7 +257,7 @@ export function FormTokenField( props: FormTokenFieldProps ) {
 		const text = event.value;
 		const separator = tokenizeOnSpace ? /[ ,\t]+/ : /[,\t]+/;
 		const items = text.split( separator );
-		const tokenValue = last( items ) || '';
+		const tokenValue = items[ items.length - 1 ] || '';
 
 		if ( items.length > 1 ) {
 			addNewTokens( items.slice( 0, -1 ) );
@@ -413,7 +412,7 @@ export function FormTokenField( props: FormTokenFieldProps ) {
 		];
 
 		if ( tokensToAdd.length > 0 ) {
-			const newValue = clone( value );
+			const newValue = [ ...value ];
 			newValue.splice( getIndexOfInput(), 0, ...tokensToAdd );
 			onChange( newValue );
 		}
@@ -503,7 +502,7 @@ export function FormTokenField( props: FormTokenFieldProps ) {
 	}
 
 	function valueContainsToken( token: string ) {
-		return some( value, ( item ) => {
+		return value.some( ( item ) => {
 			return getTokenValue( token ) === getTokenValue( item );
 		} );
 	}
@@ -564,7 +563,7 @@ export function FormTokenField( props: FormTokenFieldProps ) {
 	}
 
 	function renderTokensAndInput() {
-		const components = map( value, renderToken );
+		const components = value.map( renderToken );
 		components.splice( getIndexOfInput(), 0, renderInput() );
 
 		return components;

package/src/form-token-field/suggestions-list.tsx

@@ -1,7 +1,6 @@
 /**
  * External dependencies
  */
-import { map } from 'lodash';
 import scrollView from 'dom-scroll-into-view';
 import classnames from 'classnames';
 import type { MouseEventHandler, ReactNode } from 'react';
@@ -114,7 +113,7 @@ export function SuggestionsList< T extends string | { value: string } >( {
 			id={ `components-form-token-suggestions-${ instanceId }` }
 			role="listbox"
 		>
-			{ map( suggestions, ( suggestion, index ) => {
+			{ suggestions.map( ( suggestion, index ) => {
 				const matchText = computeSuggestionMatch( suggestion );
 				const className = classnames(
 					'components-form-token-field__suggestion',