@wordpress/components 19.13.0 → 19.16.0

package/src/flex/flex-block/README.md

@@ -1,9 +1,5 @@
 # FlexBlock
 
-<div class="callout callout-alert">
-This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
-</div>
-
 A layout component to contain items of a fixed width within `Flex`.
 
 ## Usage

package/src/flex/flex-block/component.js

@@ -20,9 +20,15 @@ function FlexBlock( props, forwardedRef ) {
  *
  * @example
  * ```jsx
- * <Flex>
- * 	<FlexBlock>...</FlexBlock>
- * </Flex>
+ * import { Flex, FlexBlock } from '@wordpress/components';
+ *
+ * function Example() {
+ *   return (
+ *     <Flex>
+ *       <FlexBlock>...</FlexBlock>
+ *     </Flex>
+ *   );
+ * }
  * ```
  */
 const ConnectedFlexBlock = contextConnect( FlexBlock, 'FlexBlock' );

package/src/flex/flex-item/README.md

@@ -1,14 +1,10 @@
 # FlexItem
 
-<div class="callout callout-alert">
-This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
-</div>
-
 A layout component to contain items of a fixed width within `Flex`.
 
 ## Usage
 
-See [`flex/README.md#usage`](/packages/components/src/flex/README.md#usage) for how to use `FlexItem`.
+See [`flex/README.md#usage`](/packages/components/src/flex/flex/README.md#usage) for how to use `FlexItem`.
 
 ## Props
 

package/src/flex/flex-item/component.js

@@ -20,9 +20,15 @@ function FlexItem( props, forwardedRef ) {
  *
  * @example
  * ```jsx
- * <Flex>
- * 	<FlexItem>...</FlexItem>
- * </Flex>
+ * import { Flex, FlexItem } from '@wordpress/components';
+ *
+ * function Example() {
+ *   return (
+ *     <Flex>
+ *       <FlexItem>...</FlexItem>
+ *     </Flex>
+ *   );
+ * }
  * ```
  */
 const ConnectedFlexItem = contextConnect( FlexItem, 'FlexItem' );

package/src/flex/stories/index.js

@@ -6,7 +6,7 @@ import { View } from '../../view';
 
 export default {
 	component: Flex,
-	title: 'Components (Experimental)/Flex',
+	title: 'Components/Flex',
 };
 
 export const _default = () => {

package/src/flex/types.ts

@@ -35,7 +35,10 @@ export type FlexProps = {
 	 */
 	expanded?: boolean;
 	/**
-	 * Spacing in between each child can be adjusted by using `gap`. The value of `gap` works as a multiplier to the library's grid system (base of `4px`).
+	 * Spacing in between each child can be adjusted by using `gap`.
+	 *
+	 * Can either be a number (which will act as a multiplier to the library's grid system base of 4px),
+	 * or a literal CSS value string.
 	 *
 	 * @default 2
 	 */

package/src/focal-point-picker/grid.js

@@ -13,9 +13,6 @@ import {
 } from './styles/focal-point-picker-style';
 import { useUpdateEffect } from '../utils/hooks';
 
-const { clearTimeout, setTimeout } =
-	typeof window !== 'undefined' ? window : {};
-
 export default function FocalPointPickerGrid( {
 	bounds = {},
 	value,
@@ -52,11 +49,11 @@ function useRevealAnimation( value ) {
 
 	useUpdateEffect( () => {
 		setIsActive( true );
-		const timeout = setTimeout( () => {
+		const timeout = window.setTimeout( () => {
 			setIsActive( false );
 		}, 600 );
 
-		return () => clearTimeout( timeout );
+		return () => window.clearTimeout( timeout );
 	}, [ value ] );
 
 	return {

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

@@ -3,7 +3,6 @@
  */
 import { Animated, PanResponder, View } from 'react-native';
 import Video from 'react-native-video';
-import { clamp } from 'lodash';
 
 /**
  * WordPress dependencies
@@ -24,6 +23,7 @@ import FocalPoint from './focal-point';
 import Tooltip from './tooltip';
 import styles from './style.scss';
 import { isVideoType } from './utils';
+import { clamp } from '../utils/math';
 
 const MIN_POSITION_VALUE = 0;
 const MAX_POSITION_VALUE = 100;
@@ -40,8 +40,8 @@ function FocalPointPicker( props ) {
 	const [ videoNaturalSize, setVideoNaturalSize ] = useState( null );
 	const [ tooltipVisible, setTooltipVisible ] = useState( false );
 
-	let locationPageOffsetX = useRef().current;
-	let locationPageOffsetY = useRef().current;
+	const locationPageOffsetX = useRef();
+	const locationPageOffsetY = useRef();
 	const videoRef = useRef( null );
 
 	useEffect( () => {
@@ -67,7 +67,7 @@ function FocalPointPicker( props ) {
 				y: focalPoint.y * containerSize.height,
 			} );
 		}
-	}, [ focalPoint, containerSize ] );
+	}, [ focalPoint, containerSize, pan ] );
 
 	// Pan responder to manage drag handle interactivity.
 	const panResponder = useMemo(
@@ -86,8 +86,8 @@ function FocalPointPicker( props ) {
 						pageX,
 						pageY,
 					} = event.nativeEvent;
-					locationPageOffsetX = pageX - x;
-					locationPageOffsetY = pageY - y;
+					locationPageOffsetX.current = pageX - x;
+					locationPageOffsetY.current = pageY - y;
 					pan.setValue( { x, y } ); // Set cursor to tap location.
 					pan.extractOffset(); // Set offset to current value.
 				},
@@ -106,8 +106,8 @@ function FocalPointPicker( props ) {
 					// Specifically, dragging the handle outside the bounds of the image
 					// results in inaccurate locationX and locationY coordinates to be
 					// reported. https://github.com/facebook/react-native/issues/15290#issuecomment-435494944
-					const x = pageX - locationPageOffsetX;
-					const y = pageY - locationPageOffsetY;
+					const x = pageX - locationPageOffsetX.current;
+					const y = pageY - locationPageOffsetY.current;
 					onChange( {
 						x: clamp( x / containerSize?.width, 0, 1 ).toFixed( 2 ),
 						y: clamp( y / containerSize?.height, 0, 1 ).toFixed(
@@ -120,7 +120,7 @@ function FocalPointPicker( props ) {
 					setSliderKey( ( prevState ) => prevState + 1 );
 				},
 			} ),
-		[ containerSize ]
+		[ containerSize, pan, onChange, shouldEnableBottomSheetScroll ]
 	);
 
 	const mediaBackground = usePreferredColorSchemeStyle(

package/src/focal-point-picker/tooltip/index.native.js

@@ -66,18 +66,17 @@ function Label( { align, text, xOffset, yOffset } ) {
 	}
 
 	useEffect( () => {
+		const startAnimation = () => {
+			Animated.timing( animationValue, {
+				toValue: visible ? 1 : 0,
+				duration: visible ? 300 : 150,
+				useNativeDriver: true,
+				delay: visible ? 500 : 0,
+				easing: Easing.out( Easing.quad ),
+			} ).start();
+		};
 		startAnimation();
-	}, [ visible ] );
-
-	const startAnimation = () => {
-		Animated.timing( animationValue, {
-			toValue: visible ? 1 : 0,
-			duration: visible ? 300 : 150,
-			useNativeDriver: true,
-			delay: visible ? 500 : 0,
-			easing: Easing.out( Easing.quad ),
-		} ).start();
-	};
+	}, [ animationValue, visible ] );
 
 	// Transforms rely upon onLayout to enable custom offsets additions.
 	let tooltipTransforms;

package/src/form-toggle/README.md

@@ -60,10 +60,12 @@ import { useState } from '@wordpress/element';
 const MyFormToggle = () => {
 	const [ isChecked, setChecked ] = useState( true );
 
-	<FormToggle
-		checked={ isChecked }
-		onChange={ () => setChecked( ( state ) => ! state ) }
-	/>
+	return (
+		<FormToggle
+			checked={ isChecked }
+			onChange={ () => setChecked( ( state ) => ! state ) }
+		/>
+	);
 };
 ```
 
@@ -71,26 +73,23 @@ const MyFormToggle = () => {
 
 The component accepts the following props:
 
-#### checked
+#### `checked`: `boolean`
 
 If checked is true the toggle will be checked. If checked is false the toggle will be unchecked.
 If no value is passed the toggle will be unchecked.
 
--   Type: `Boolean`
 -   Required: No
 
-#### disabled
+#### `disabled`: `boolean`
 
 If disabled is true the toggle will be disabled and apply the appropriate styles.
 
--   Type: `Boolean`
 -   Required: No
 
-#### onChange
+#### `onChange`: `( event: ChangeEvent<HTMLInputElement> ) => void`
 
-A function that receives the checked state (boolean) as input.
+A callback function invoked when the toggle is clicked.
 
--   Type: `function`
 -   Required: Yes
 
 ## Related components

package/src/form-toggle/index.tsx

@@ -0,0 +1,71 @@
+/**
+ * External dependencies
+ */
+import classnames from 'classnames';
+
+/**
+ * Internal dependencies
+ */
+import type { FormToggleProps } from './types';
+import type { WordPressComponentProps } from '../ui/context';
+
+export const noop = () => {};
+
+/**
+ * FormToggle switches a single setting on or off.
+ *
+ * ```jsx
+ * import { FormToggle } from '@wordpress/components';
+ * import { useState } from '@wordpress/element';
+ *
+ * const MyFormToggle = () => {
+ *   const [ isChecked, setChecked ] = useState( true );
+ *
+ *   return (
+ *     <FormToggle
+ *       checked={ isChecked }
+ *       onChange={ () => setChecked( ( state ) => ! state ) }
+ *     />
+ *   );
+ * };
+ * ```
+ */
+export function FormToggle(
+	// ref is omitted until we have `WordPressComponentPropsWithoutRef` or add
+	// ref forwarding to FormToggle.
+	props: Omit<
+		WordPressComponentProps< FormToggleProps, 'input', false >,
+		'ref'
+	>
+) {
+	const {
+		className,
+		checked,
+		id,
+		disabled,
+		onChange = noop,
+		...additionalProps
+	} = props;
+	const wrapperClasses = classnames( 'components-form-toggle', className, {
+		'is-checked': checked,
+		'is-disabled': disabled,
+	} );
+
+	return (
+		<span className={ wrapperClasses }>
+			<input
+				className="components-form-toggle__input"
+				id={ id }
+				type="checkbox"
+				checked={ checked }
+				onChange={ onChange }
+				disabled={ disabled }
+				{ ...additionalProps }
+			/>
+			<span className="components-form-toggle__track"></span>
+			<span className="components-form-toggle__thumb"></span>
+		</span>
+	);
+}
+
+export default FormToggle;

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

@@ -0,0 +1,52 @@
+/**
+ * External dependencies
+ */
+import type { ComponentMeta, ComponentStory } from '@storybook/react';
+
+/**
+ * WordPress dependencies
+ */
+import { useState } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import { FormToggle } from '..';
+
+const meta: ComponentMeta< typeof FormToggle > = {
+	component: FormToggle,
+	title: 'Components/FormToggle',
+	argTypes: {
+		onChange: {
+			action: 'onChange',
+		},
+	},
+	parameters: {
+		controls: {
+			expanded: true,
+		},
+		docs: { source: { state: 'open' } },
+	},
+};
+export default meta;
+
+const Template: ComponentStory< typeof FormToggle > = ( {
+	onChange,
+	...args
+} ) => {
+	const [ isChecked, setChecked ] = useState( true );
+
+	return (
+		<FormToggle
+			{ ...args }
+			checked={ isChecked }
+			onChange={ ( e ) => {
+				setChecked( ( state ) => ! state );
+				onChange( e );
+			} }
+		/>
+	);
+};
+
+export const Default: ComponentStory< typeof FormToggle > = Template.bind( {} );
+Default.args = {};

package/src/form-toggle/test/__snapshots__/index.tsx.snap

@@ -0,0 +1,54 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`FormToggle basic rendering should render a span element with an unchecked checkbox 1`] = `
+<span
+  class="components-form-toggle"
+>
+  <input
+    class="components-form-toggle__input"
+    type="checkbox"
+  />
+  <span
+    class="components-form-toggle__track"
+  />
+  <span
+    class="components-form-toggle__thumb"
+  />
+</span>
+`;
+
+exports[`FormToggle basic rendering should render an id prop for the input checkbox 1`] = `
+Snapshot Diff:
+- First value
++ Second value
+
+@@ -2,10 +2,11 @@
+    <span
+      class="components-form-toggle"
+    >
+      <input
+        class="components-form-toggle__input"
++       id="test"
+        type="checkbox"
+      />
+      <span
+        class="components-form-toggle__track"
+      />
+`;
+
+exports[`FormToggle basic rendering should render with an additional className 1`] = `
+Snapshot Diff:
+- First value
++ Second value
+
+@@ -1,8 +1,8 @@
+  <div>
+    <span
+-     class="components-form-toggle"
++     class="components-form-toggle testing"
+    >
+      <input
+        class="components-form-toggle__input"
+        type="checkbox"
+      />
+`;

package/src/form-toggle/test/index.tsx

@@ -0,0 +1,102 @@
+/**
+ * External dependencies
+ */
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+
+/**
+ * WordPress dependencies
+ */
+import { useState } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import FormToggle, { noop } from '..';
+import type { FormToggleProps } from '../types';
+
+const getInput = () => screen.getByRole( 'checkbox' ) as HTMLInputElement;
+
+const ControlledFormToggle = ( { onChange }: FormToggleProps ) => {
+	const [ isChecked, setChecked ] = useState( false );
+	return (
+		<FormToggle
+			checked={ isChecked }
+			onChange={ ( value ) => {
+				setChecked( ( state ) => ! state );
+				onChange( value );
+			} }
+		/>
+	);
+};
+
+describe( 'FormToggle', () => {
+	describe( 'basic rendering', () => {
+		it( 'should render a span element with an unchecked checkbox', () => {
+			const { container } = render( <FormToggle onChange={ noop } /> );
+
+			expect( getInput() ).not.toBeChecked();
+			expect( container.firstChild ).toMatchSnapshot();
+		} );
+
+		it( 'should render a checked checkbox when providing checked prop', () => {
+			render( <FormToggle onChange={ noop } checked /> );
+
+			expect( getInput() ).toBeChecked();
+		} );
+
+		it( 'should render with an additional className', () => {
+			const { container: containerDefault } = render(
+				<FormToggle onChange={ noop } />
+			);
+
+			const { container: containerWithClassName } = render(
+				<FormToggle onChange={ noop } className="testing" />
+			);
+
+			// Expect the diff snapshot to be mostly about the className.
+			expect( containerDefault ).toMatchDiffSnapshot(
+				containerWithClassName
+			);
+		} );
+
+		it( 'should render an id prop for the input checkbox', () => {
+			const { container: containerDefault } = render(
+				<FormToggle onChange={ noop } />
+			);
+
+			const { container: containerWithID } = render(
+				// Disabled because of our rule restricting literal IDs, preferring
+				// `withInstanceId`. In this case, it's fine to use literal IDs.
+				// eslint-disable-next-line no-restricted-syntax
+				<FormToggle onChange={ noop } id="test" />
+			);
+
+			// Expect the diff snapshot to be mostly about the ID.
+			expect( containerDefault ).toMatchDiffSnapshot( containerWithID );
+		} );
+	} );
+
+	describe( 'Value', () => {
+		it( 'should flip the checked property when clicked', async () => {
+			const user = userEvent.setup( {
+				advanceTimers: jest.advanceTimersByTime,
+			} );
+
+			const onChange = jest.fn();
+			render( <ControlledFormToggle onChange={ onChange } /> );
+
+			const input = getInput();
+
+			await user.click( input );
+			expect( onChange.mock.calls[ 0 ][ 0 ].target ).toBeInTheDocument();
+			expect( input ).toBeChecked();
+
+			await user.click( input );
+			expect( onChange.mock.calls[ 1 ][ 0 ].target ).toBeInTheDocument();
+			expect( input ).not.toBeChecked();
+
+			expect( onChange ).toHaveBeenCalledTimes( 2 );
+		} );
+	} );
+} );

package/src/form-toggle/types.ts

@@ -0,0 +1,22 @@
+/**
+ * External dependencies
+ */
+import type { ChangeEvent } from 'react';
+
+export type FormToggleProps = {
+	/**
+	 * If checked is true the toggle will be checked. If checked is false the
+	 * toggle will be unchecked. If no value is passed the toggle will be
+	 * unchecked.
+	 */
+	checked?: boolean;
+	/**
+	 * If disabled is true the toggle will be disabled and apply the appropriate
+	 * styles.
+	 */
+	disabled?: boolean;
+	/**
+	 * A callback function invoked when the toggle is clicked.
+	 */
+	onChange: ( event: ChangeEvent< HTMLInputElement > ) => void;
+};

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

@@ -1,7 +1,7 @@
 /**
  * External dependencies
  */
-import { last, clone, uniq, map, difference, identity, some } from 'lodash';
+import { last, clone, uniq, map, difference, some } from 'lodash';
 import classnames from 'classnames';
 import type { KeyboardEvent, MouseEvent, TouchEvent } from 'react';
 
@@ -30,8 +30,12 @@ import isShallowEqual from '@wordpress/is-shallow-equal';
  */
 import Token from './token';
 import TokenInput from './token-input';
+import { TokensAndInputWrapperFlex } from './styles';
 import SuggestionsList from './suggestions-list';
 import type { FormTokenFieldProps, TokenItem } from './types';
+import { FlexItem } from '../flex';
+
+const identity = ( value: string ) => value;
 
 /**
  * A `FormTokenField` is a field similar to the tags and categories fields in the interim editor chrome,
@@ -71,6 +75,7 @@ export function FormTokenField( props: FormTokenFieldProps ) {
 		__experimentalExpandOnFocus = false,
 		__experimentalValidateInput = () => true,
 		__experimentalShowHowTo = true,
+		__next36pxDefaultSize = false,
 	} = props;
 
 	const instanceId = useInstanceId( FormTokenField );
@@ -566,28 +571,35 @@ export function FormTokenField( props: FormTokenFieldProps ) {
 		const termsCount = tokens.length;
 
 		return (
-			<Token
-				key={ 'token-' + _value }
-				value={ _value }
-				status={ status }
-				title={ typeof token !== 'string' ? token.title : undefined }
-				displayTransform={ displayTransform }
-				onClickRemove={ onTokenClickRemove }
-				isBorderless={
-					( typeof token !== 'string' && token.isBorderless ) ||
-					isBorderless
-				}
-				onMouseEnter={
-					typeof token !== 'string' ? token.onMouseEnter : undefined
-				}
-				onMouseLeave={
-					typeof token !== 'string' ? token.onMouseLeave : undefined
-				}
-				disabled={ 'error' !== status && disabled }
-				messages={ messages }
-				termsCount={ termsCount }
-				termPosition={ termPosition }
-			/>
+			<FlexItem key={ 'token-' + _value }>
+				<Token
+					value={ _value }
+					status={ status }
+					title={
+						typeof token !== 'string' ? token.title : undefined
+					}
+					displayTransform={ displayTransform }
+					onClickRemove={ onTokenClickRemove }
+					isBorderless={
+						( typeof token !== 'string' && token.isBorderless ) ||
+						isBorderless
+					}
+					onMouseEnter={
+						typeof token !== 'string'
+							? token.onMouseEnter
+							: undefined
+					}
+					onMouseLeave={
+						typeof token !== 'string'
+							? token.onMouseLeave
+							: undefined
+					}
+					disabled={ 'error' !== status && disabled }
+					messages={ messages }
+					termsCount={ termsCount }
+					termPosition={ termPosition }
+				/>
+			</FlexItem>
 		);
 	}
 
@@ -660,7 +672,16 @@ export function FormTokenField( props: FormTokenFieldProps ) {
 				onMouseDown={ onContainerTouched }
 				onTouchStart={ onContainerTouched }
 			>
-				{ renderTokensAndInput() }
+				<TokensAndInputWrapperFlex
+					justify="flex-start"
+					align="center"
+					gap={ 1 }
+					wrap={ true }
+					__next36pxDefaultSize={ __next36pxDefaultSize }
+					hasTokens={ !! value.length }
+				>
+					{ renderTokensAndInput() }
+				</TokensAndInputWrapperFlex>
 				{ isExpanded && (
 					<SuggestionsList
 						instanceId={ instanceId }