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

package/src/flex/test/__snapshots__/index.tsx.snap

@@ -7,25 +7,25 @@ Snapshot Diff:
 
 @@ -1,22 +1,18 @@
   <div
-    class="components-flex css-1giw1wa-View-Flex-sx-Base-sx-Items-ItemsRow em57xhy0"
+    class="components-flex css-j6raph-View-Flex-base-ItemsRow e19lxcc00"
 -   data-testid="flex"
 +   data-testid="base-flex"
     data-wp-c16t="true"
     data-wp-component="Flex"
   >
     <div
-      class="components-flex-item css-mw3lhz-View-Item-sx-Base em57xhy0"
+      class="components-flex-item css-mw3lhz-View-Item-sx-Base e19lxcc00"
       data-wp-c16t="true"
       data-wp-component="FlexItem"
     >
       Item
     </div>
 -   <div
--     class="css-1mm2cvy-View em57xhy0"
+-     class="css-1mm2cvy-View e19lxcc00"
 -   />
 -   <div />
     <div
-      class="components-flex-item components-flex-block css-14wzr73-View-Item-sx-Base-block em57xhy0"
+      class="components-flex-item components-flex-block css-14wzr73-View-Item-sx-Base-block e19lxcc00"
       data-wp-c16t="true"
       data-wp-component="FlexBlock"
     >
@@ -53,9 +53,9 @@ Snapshot Diff:
 +     "align-items": "center",
       "display": "flex",
       "flex-direction": "row",
+      "gap": "calc(4px * 2)",
       "justify-content": "space-between",
       "width": "100%",
-    },
 `;
 
 exports[`props should render correctly 1`] = `
@@ -71,16 +71,13 @@ exports[`props should render correctly 1`] = `
   -webkit-flex-direction: row;
   -ms-flex-direction: row;
   flex-direction: row;
+  gap: calc(4px * 2);
   -webkit-box-pack: justify;
   -webkit-justify-content: space-between;
   justify-content: space-between;
   width: 100%;
 }
 
-.emotion-0>*+*:not( marquee ) {
-  margin-left: calc(4px * 2);
-}
-
 .emotion-0>* {
   min-width: 0;
 }
@@ -147,6 +144,7 @@ Snapshot Diff:
       "align-items": "center",
       "display": "flex",
       "flex-direction": "row",
+      "gap": "calc(4px * 2)",
 -     "justify-content": "flex-start",
 +     "justify-content": "space-between",
       "width": "100%",
@@ -161,9 +159,6 @@ Snapshot Diff:
 
   Array [
     Object {
--     "margin-left": "calc(4px * 2)",
--   },
--   Object {
 -     "min-width": "0",
 -   },
 -   Object {
@@ -176,9 +171,6 @@ Snapshot Diff:
       "min-height": "0",
 +     "min-width": "0",
 +   },
-+   Object {
-+     "margin-left": "calc(4px * 5)",
-+   },
 +   Object {
       "min-width": "0",
     },

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

@@ -2,8 +2,8 @@
 
 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.
 
-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: `background-position: 50% 10%;`
 
 ## Usage
 

package/src/focal-point-picker/{controls.js → controls.tsx}

@@ -7,26 +7,38 @@ import { __ } from '@wordpress/i18n';
  * Internal dependencies
  */
 import {
-	UnitControl as BaseUnitControl,
+	StyledUnitControl,
 	ControlWrapper,
 } from './styles/focal-point-picker-style';
 import { fractionToPercentage } from './utils';
+import type {
+	UnitControlProps,
+	UnitControlOnChangeCallback,
+} from '../unit-control/types';
+import type { FocalPointAxis, FocalPointPickerControlsProps } from './types';
 
 const TEXTCONTROL_MIN = 0;
 const TEXTCONTROL_MAX = 100;
 const noop = () => {};
 
 export default function FocalPointPickerControls( {
+	__nextHasNoMarginBottom,
+	hasHelpText,
 	onChange = noop,
 	point = {
 		x: 0.5,
 		y: 0.5,
 	},
-} ) {
+}: FocalPointPickerControlsProps ) {
 	const valueX = fractionToPercentage( point.x );
 	const valueY = fractionToPercentage( point.y );
 
-	const handleChange = ( value, axis ) => {
+	const handleChange = (
+		value: Parameters< UnitControlOnChangeCallback >[ 0 ],
+		axis: FocalPointAxis
+	) => {
+		if ( value === undefined ) return;
+
 		const num = parseInt( value, 10 );
 
 		if ( ! isNaN( num ) ) {
@@ -35,26 +47,42 @@ export default function FocalPointPickerControls( {
 	};
 
 	return (
-		<ControlWrapper className="focal-point-picker__controls">
-			<UnitControl
+		<ControlWrapper
+			className="focal-point-picker__controls"
+			__nextHasNoMarginBottom={ __nextHasNoMarginBottom }
+			hasHelpText={ hasHelpText }
+		>
+			<FocalPointUnitControl
 				label={ __( 'Left' ) }
 				value={ [ valueX, '%' ].join( '' ) }
-				onChange={ ( next ) => handleChange( next, 'x' ) }
+				onChange={
+					( ( next ) =>
+						handleChange(
+							next,
+							'x'
+						) ) as UnitControlOnChangeCallback
+				}
 				dragDirection="e"
 			/>
-			<UnitControl
+			<FocalPointUnitControl
 				label={ __( 'Top' ) }
 				value={ [ valueY, '%' ].join( '' ) }
-				onChange={ ( next ) => handleChange( next, 'y' ) }
+				onChange={
+					( ( next ) =>
+						handleChange(
+							next,
+							'y'
+						) ) as UnitControlOnChangeCallback
+				}
 				dragDirection="s"
 			/>
 		</ControlWrapper>
 	);
 }
 
-function UnitControl( props ) {
+function FocalPointUnitControl( props: UnitControlProps ) {
 	return (
-		<BaseUnitControl
+		<StyledUnitControl
 			className="focal-point-picker__controls-position-unit-control"
 			labelPosition="top"
 			max={ TEXTCONTROL_MAX }

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

@@ -12,8 +12,14 @@ import {
  * External dependencies
  */
 import classnames from 'classnames';
+import type { FocalPointProps } from './types';
+import type { WordPressComponentProps } from '../ui/context';
 
-export default function FocalPoint( { left = '50%', top = '50%', ...props } ) {
+export default function FocalPoint( {
+	left = '50%',
+	top = '50%',
+	...props
+}: WordPressComponentProps< FocalPointProps, 'div' > ) {
 	const classes = classnames(
 		'components-focal-point-picker__icon_container'
 	);

package/src/focal-point-picker/{grid.js → grid.tsx}

@@ -6,8 +6,13 @@ import {
 	GridLineX,
 	GridLineY,
 } from './styles/focal-point-picker-style';
+import type { FocalPointPickerGridProps } from './types';
+import type { WordPressComponentProps } from '../ui/context/wordpress-component';
 
-export default function FocalPointPickerGrid( { bounds, ...props } ) {
+export default function FocalPointPickerGrid( {
+	bounds,
+	...props
+}: WordPressComponentProps< FocalPointPickerGridProps, 'div' > ) {
 	return (
 		<GridView
 			{ ...props }

package/src/focal-point-picker/{index.js → index.tsx}

@@ -28,10 +28,62 @@ import {
 } from './styles/focal-point-picker-style';
 import { INITIAL_BOUNDS } from './utils';
 import { useUpdateEffect } from '../utils/hooks';
+import type { WordPressComponentProps } from '../ui/context/wordpress-component';
+import type {
+	FocalPoint as FocalPointType,
+	FocalPointPickerProps,
+} from './types';
+import type { KeyboardEventHandler } from 'react';
 
 const GRID_OVERLAY_TIMEOUT = 600;
 
-export default function 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.
+ *
+ * - Example focal point picker value: `{ x: 0.5, y: 0.1 }`
+ * - Corresponding CSS: `background-position: 50% 10%;`
+ *
+ * ```jsx
+ * import { FocalPointPicker } from '@wordpress/components';
+ * import { useState } from '@wordpress/element';
+ *
+ * const Example = () => {
+ * 	const [ focalPoint, setFocalPoint ] = useState( {
+ * 		x: 0.5,
+ * 		y: 0.5,
+ * 	} );
+ *
+ * 	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 }%`,
+ * 	};
+ *
+ * 	return (
+ * 		<>
+ * 			<FocalPointPicker
+ * 				url={ url }
+ * 				value={ focalPoint }
+ * 				onDragStart={ setFocalPoint }
+ * 				onDrag={ setFocalPoint }
+ * 				onChange={ setFocalPoint }
+ * 			/>
+ * 			<div style={ style } />
+ * 		</>
+ * 	);
+ * };
+ * ```
+ */
+export function FocalPointPicker( {
+	__nextHasNoMarginBottom,
 	autoPlay = true,
 	className,
 	help,
@@ -46,14 +98,20 @@ export default function FocalPointPicker( {
 		x: 0.5,
 		y: 0.5,
 	},
-} ) {
+	...restProps
+}: WordPressComponentProps< FocalPointPickerProps, 'div', false > ) {
 	const [ point, setPoint ] = useState( valueProp );
 	const [ showGridOverlay, setShowGridOverlay ] = useState( false );
 
 	const { startDrag, endDrag, isDragging } = useDragging( {
 		onDragStart: ( event ) => {
-			dragAreaRef.current.focus();
+			dragAreaRef.current?.focus();
 			const value = getValueWithinDragArea( event );
+
+			// `value` can technically be undefined if getValueWithinDragArea() is
+			// called before dragAreaRef is set, but this shouldn't happen in reality.
+			if ( ! value ) return;
+
 			onDragStart?.( value, event );
 			setPoint( value );
 		},
@@ -61,11 +119,12 @@ export default function FocalPointPicker( {
 			// Prevents text-selection when dragging.
 			event.preventDefault();
 			const value = getValueWithinDragArea( event );
+			if ( ! value ) return;
 			onDrag?.( value, event );
 			setPoint( value );
 		},
-		onDragEnd: ( event ) => {
-			onDragEnd?.( event );
+		onDragEnd: () => {
+			onDragEnd?.();
 			onChange?.( point );
 		},
 	} );
@@ -73,9 +132,11 @@ export default function FocalPointPicker( {
 	// Uses the internal point while dragging or else the value from props.
 	const { x, y } = isDragging ? point : valueProp;
 
-	const dragAreaRef = useRef();
+	const dragAreaRef = useRef< HTMLDivElement >( null );
 	const [ bounds, setBounds ] = useState( INITIAL_BOUNDS );
 	const refUpdateBounds = useRef( () => {
+		if ( ! dragAreaRef.current ) return;
+
 		const { clientWidth: width, clientHeight: height } =
 			dragAreaRef.current;
 		// Falls back to initial bounds if the ref has no size. Since styles
@@ -88,15 +149,29 @@ export default function FocalPointPicker( {
 
 	useEffect( () => {
 		const updateBounds = refUpdateBounds.current;
+		if ( ! dragAreaRef.current ) return;
+
 		const { defaultView } = dragAreaRef.current.ownerDocument;
-		defaultView.addEventListener( 'resize', updateBounds );
-		return () => defaultView.removeEventListener( 'resize', updateBounds );
+		defaultView?.addEventListener( 'resize', updateBounds );
+		return () => defaultView?.removeEventListener( 'resize', updateBounds );
 	}, [] );
 
 	// Updates the bounds to cover cases of unspecified media or load failures.
 	useIsomorphicLayoutEffect( () => void refUpdateBounds.current(), [] );
 
-	const getValueWithinDragArea = ( { clientX, clientY, shiftKey } ) => {
+	// TODO: Consider refactoring getValueWithinDragArea() into a pure function.
+	// https://github.com/WordPress/gutenberg/pull/43872#discussion_r963455173
+	const getValueWithinDragArea = ( {
+		clientX,
+		clientY,
+		shiftKey,
+	}: {
+		clientX: number;
+		clientY: number;
+		shiftKey: boolean;
+	} ) => {
+		if ( ! dragAreaRef.current ) return;
+
 		const { top, left } = dragAreaRef.current.getBoundingClientRect();
 		let nextX = ( clientX - left ) / bounds.width;
 		let nextY = ( clientY - top ) / bounds.height;
@@ -108,17 +183,20 @@ export default function FocalPointPicker( {
 		return getFinalValue( { x: nextX, y: nextY } );
 	};
 
-	const getFinalValue = ( value ) => {
+	const getFinalValue = ( value: FocalPointType ): FocalPointType => {
 		const resolvedValue = resolvePoint?.( value ) ?? value;
 		resolvedValue.x = Math.max( 0, Math.min( resolvedValue.x, 1 ) );
 		resolvedValue.y = Math.max( 0, Math.min( resolvedValue.y, 1 ) );
+		const roundToTwoDecimalPlaces = ( n: number ) =>
+			Math.round( n * 1e2 ) / 1e2;
+
 		return {
-			x: parseFloat( resolvedValue.x ).toFixed( 2 ),
-			y: parseFloat( resolvedValue.y ).toFixed( 2 ),
+			x: roundToTwoDecimalPlaces( resolvedValue.x ),
+			y: roundToTwoDecimalPlaces( resolvedValue.y ),
 		};
 	};
 
-	const arrowKeyStep = ( event ) => {
+	const arrowKeyStep: KeyboardEventHandler< HTMLDivElement > = ( event ) => {
 		const { code, shiftKey } = event;
 		if (
 			! [ 'ArrowUp', 'ArrowDown', 'ArrowLeft', 'ArrowRight' ].includes(
@@ -133,7 +211,7 @@ export default function FocalPointPicker( {
 		const delta =
 			code === 'ArrowUp' || code === 'ArrowLeft' ? -1 * step : step;
 		const axis = code === 'ArrowUp' || code === 'ArrowDown' ? 'y' : 'x';
-		value[ axis ] = parseFloat( value[ axis ] ) + delta;
+		value[ axis ] = value[ axis ] + delta;
 		onChange?.( getFinalValue( value ) );
 	};
 
@@ -161,6 +239,8 @@ export default function FocalPointPicker( {
 
 	return (
 		<BaseControl
+			{ ...restProps }
+			__nextHasNoMarginBottom={ __nextHasNoMarginBottom }
 			label={ label }
 			id={ id }
 			help={ help }
@@ -176,7 +256,7 @@ export default function FocalPointPicker( {
 					} }
 					ref={ dragAreaRef }
 					role="button"
-					tabIndex="-1"
+					tabIndex={ -1 }
 				>
 					<Grid bounds={ bounds } showOverlay={ showGridOverlay } />
 					<Media
@@ -192,6 +272,8 @@ export default function FocalPointPicker( {
 				</MediaContainer>
 			</MediaWrapper>
 			<Controls
+				__nextHasNoMarginBottom={ __nextHasNoMarginBottom }
+				hasHelpText={ !! help }
 				point={ { x, y } }
 				onChange={ ( value ) => {
 					onChange?.( getFinalValue( value ) );
@@ -200,3 +282,5 @@ export default function FocalPointPicker( {
 		</BaseControl>
 	);
 }
+
+export default FocalPointPicker;

package/src/focal-point-picker/{media.js → media.tsx}

@@ -1,8 +1,14 @@
+/**
+ * External dependencies
+ */
+import type { Ref } from 'react';
+
 /**
  * Internal dependencies
  */
 import { MediaPlaceholder } from './styles/focal-point-picker-style';
 import { isVideoType } from './utils';
+import type { FocalPointPickerMediaProps } from './types';
 
 export default function Media( {
 	alt,
@@ -14,12 +20,12 @@ export default function Media( {
 	// https://github.com/testing-library/react-testing-library/issues/470
 	muted = true,
 	...props
-} ) {
+}: FocalPointPickerMediaProps ) {
 	if ( ! src ) {
 		return (
 			<MediaPlaceholder
 				className="components-focal-point-picker__media components-focal-point-picker__media--placeholder"
-				ref={ mediaRef }
+				ref={ mediaRef as Ref< HTMLDivElement > }
 				{ ...props }
 			/>
 		);
@@ -35,7 +41,7 @@ export default function Media( {
 			loop
 			muted={ muted }
 			onLoadedData={ onLoad }
-			ref={ mediaRef }
+			ref={ mediaRef as Ref< HTMLVideoElement > }
 			src={ src }
 		/>
 	) : (
@@ -44,7 +50,7 @@ export default function Media( {
 			alt={ alt }
 			className="components-focal-point-picker__media components-focal-point-picker__media--image"
 			onLoad={ onLoad }
-			ref={ mediaRef }
+			ref={ mediaRef as Ref< HTMLImageElement > }
 			src={ src }
 		/>
 	);

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

@@ -0,0 +1,93 @@
+/**
+ * External dependencies
+ */
+import type { ComponentMeta, ComponentStory } from '@storybook/react';
+
+/**
+ * WordPress dependencies
+ */
+import { useState } from '@wordpress/element';
+/**
+ * Internal dependencies
+ */
+import FocalPointPicker from '..';
+
+const meta: ComponentMeta< typeof FocalPointPicker > = {
+	title: 'Components/FocalPointPicker',
+	component: FocalPointPicker,
+	argTypes: {
+		help: { control: 'text' },
+		label: { control: 'text' },
+	},
+	parameters: {
+		actions: { argTypesRegex: '^on.*' },
+		controls: { expanded: true },
+		docs: { source: { state: 'open' } },
+	},
+};
+export default meta;
+
+const Template: ComponentStory< typeof FocalPointPicker > = ( {
+	onChange,
+	...props
+} ) => {
+	const [ focalPoint, setFocalPoint ] = useState( {
+		x: 0.5,
+		y: 0.5,
+	} );
+
+	return (
+		<FocalPointPicker
+			{ ...props }
+			value={ focalPoint }
+			onChange={ ( ...changeArgs ) => {
+				onChange( ...changeArgs );
+				setFocalPoint( ...changeArgs );
+			} }
+		/>
+	);
+};
+
+export const Default = Template.bind( {} );
+
+export const Image = Template.bind( {} );
+Image.args = {
+	...Default.args,
+	url: 'https://i0.wp.com/themes.svn.wordpress.org/twentytwenty/1.3/screenshot.png?w=572&strip=al',
+};
+
+export const Video = Template.bind( {} );
+Video.args = {
+	...Default.args,
+	url: 'https://interactive-examples.mdn.mozilla.net/media/examples/flower.webm',
+};
+
+export const Snapping = Template.bind( {} );
+Snapping.args = {
+	...Default.args,
+	resolvePoint: ( value ) => {
+		const snapValues = {
+			x: [ 0, 0.33, 0.66, 1 ],
+			y: [ 0, 0.33, 0.66, 1 ],
+		};
+
+		const threshold = 0.05;
+
+		let x = value.x;
+		let y = value.y;
+
+		snapValues.x.forEach( ( snapValue ) => {
+			if ( snapValue - threshold < x && x < snapValue + threshold ) {
+				x = snapValue;
+			}
+		} );
+
+		snapValues.y.forEach( ( snapValue ) => {
+			if ( snapValue - threshold < y && y < snapValue + threshold ) {
+				y = snapValue;
+			}
+		} );
+
+		return { x, y };
+	},
+};

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

@@ -1,14 +1,16 @@
 /**
  * External dependencies
  */
+import { css } from '@emotion/react';
 import styled from '@emotion/styled';
 
 /**
  * Internal dependencies
  */
 import { Flex } from '../../flex';
-import BaseUnitControl from '../../unit-control';
+import UnitControl from '../../unit-control';
 import { COLORS } from '../../utils';
+import type { FocalPointPickerControlsProps } from '../types';
 import { INITIAL_BOUNDS } from '../utils';
 
 export const MediaWrapper = styled.div`
@@ -42,7 +44,7 @@ export const MediaContainer = styled.div`
 `;
 
 export const MediaPlaceholder = styled.div`
-	background: ${ COLORS.lightGray[ 300 ] };
+	background: ${ COLORS.gray[ 100 ] };
 	box-sizing: border-box;
 	height: ${ INITIAL_BOUNDS.height }px;
 	max-width: 280px;
@@ -50,13 +52,36 @@ export const MediaPlaceholder = styled.div`
 	width: 100%;
 `;
 
-export const UnitControl = styled( BaseUnitControl )`
+export const StyledUnitControl = styled( UnitControl )`
 	width: 100px;
 `;
 
+const deprecatedBottomMargin = ( {
+	__nextHasNoMarginBottom,
+}: FocalPointPickerControlsProps ) => {
+	return ! __nextHasNoMarginBottom
+		? css`
+				padding-bottom: 1em;
+		  `
+		: undefined;
+};
+
+const extraHelpTextMargin = ( {
+	hasHelpText = false,
+}: FocalPointPickerControlsProps ) => {
+	return hasHelpText
+		? css`
+				padding-bottom: 1em;
+		  `
+		: undefined;
+};
+
 export const ControlWrapper = styled( Flex )`
 	max-width: 320px;
-	padding: 1em 0;
+	padding-top: 1em;
+
+	${ extraHelpTextMargin }
+	${ deprecatedBottomMargin }
 `;
 
 export const GridView = styled.div`
@@ -69,7 +94,8 @@ export const GridView = styled.div`
 	transition: opacity 120ms linear;
 	z-index: 1;
 
-	opacity: ${ ( { showOverlay } ) => ( showOverlay ? 1 : 0 ) };
+	opacity: ${ ( { showOverlay }: { showOverlay?: boolean } ) =>
+		showOverlay ? 1 : 0 };
 `;
 
 export const GridLine = styled.div`

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

@@ -25,7 +25,8 @@ export const FocalPointWrapper = styled.div`
 	will-change: transform;
 	z-index: 10000;
 
-	${ ( { isDragging } ) => isDragging && 'cursor: grabbing;' }
+	${ ( { isDragging }: { isDragging: boolean } ) =>
+		isDragging && 'cursor: grabbing;' }
 `;
 
 export const PointerIconSVG = styled( SVG )`