@wordpress/components 20.0.0 → 21.0.0

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

@@ -0,0 +1,286 @@
+/**
+ * External dependencies
+ */
+import classnames from 'classnames';
+
+/**
+ * WordPress dependencies
+ */
+import { __ } from '@wordpress/i18n';
+import { useEffect, useRef, useState } from '@wordpress/element';
+import {
+	__experimentalUseDragging as useDragging,
+	useInstanceId,
+	useIsomorphicLayoutEffect,
+} from '@wordpress/compose';
+
+/**
+ * Internal dependencies
+ */
+import BaseControl from '../base-control';
+import Controls from './controls';
+import FocalPoint from './focal-point';
+import Grid from './grid';
+import Media from './media';
+import {
+	MediaWrapper,
+	MediaContainer,
+} 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;
+
+/**
+ * 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,
+	label,
+	onChange,
+	onDrag,
+	onDragEnd,
+	onDragStart,
+	resolvePoint,
+	url,
+	value: valueProp = {
+		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();
+			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 );
+		},
+		onDragMove: ( event ) => {
+			// Prevents text-selection when dragging.
+			event.preventDefault();
+			const value = getValueWithinDragArea( event );
+			if ( ! value ) return;
+			onDrag?.( value, event );
+			setPoint( value );
+		},
+		onDragEnd: () => {
+			onDragEnd?.();
+			onChange?.( point );
+		},
+	} );
+
+	// Uses the internal point while dragging or else the value from props.
+	const { x, y } = isDragging ? point : valueProp;
+
+	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
+		// give the drag area dimensions even when the media has not loaded
+		// this should only happen in unit tests (jsdom).
+		setBounds(
+			width > 0 && height > 0 ? { width, height } : { ...INITIAL_BOUNDS }
+		);
+	} );
+
+	useEffect( () => {
+		const updateBounds = refUpdateBounds.current;
+		if ( ! dragAreaRef.current ) return;
+
+		const { defaultView } = dragAreaRef.current.ownerDocument;
+		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(), [] );
+
+	// 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;
+		// Enables holding shift to jump values by 10%.
+		if ( shiftKey ) {
+			nextX = Math.round( nextX / 0.1 ) * 0.1;
+			nextY = Math.round( nextY / 0.1 ) * 0.1;
+		}
+		return getFinalValue( { x: nextX, y: nextY } );
+	};
+
+	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: roundToTwoDecimalPlaces( resolvedValue.x ),
+			y: roundToTwoDecimalPlaces( resolvedValue.y ),
+		};
+	};
+
+	const arrowKeyStep: KeyboardEventHandler< HTMLDivElement > = ( event ) => {
+		const { code, shiftKey } = event;
+		if (
+			! [ 'ArrowUp', 'ArrowDown', 'ArrowLeft', 'ArrowRight' ].includes(
+				code
+			)
+		)
+			return;
+
+		event.preventDefault();
+		const value = { x, y };
+		const step = shiftKey ? 0.1 : 0.01;
+		const delta =
+			code === 'ArrowUp' || code === 'ArrowLeft' ? -1 * step : step;
+		const axis = code === 'ArrowUp' || code === 'ArrowDown' ? 'y' : 'x';
+		value[ axis ] = value[ axis ] + delta;
+		onChange?.( getFinalValue( value ) );
+	};
+
+	const focalPointPosition = {
+		left: x * bounds.width,
+		top: y * bounds.height,
+	};
+
+	const classes = classnames(
+		'components-focal-point-picker-control',
+		className
+	);
+
+	const instanceId = useInstanceId( FocalPointPicker );
+	const id = `inspector-focal-point-picker-control-${ instanceId }`;
+
+	useUpdateEffect( () => {
+		setShowGridOverlay( true );
+		const timeout = window.setTimeout( () => {
+			setShowGridOverlay( false );
+		}, GRID_OVERLAY_TIMEOUT );
+
+		return () => window.clearTimeout( timeout );
+	}, [ x, y ] );
+
+	return (
+		<BaseControl
+			{ ...restProps }
+			__nextHasNoMarginBottom={ __nextHasNoMarginBottom }
+			label={ label }
+			id={ id }
+			help={ help }
+			className={ classes }
+		>
+			<MediaWrapper className="components-focal-point-picker-wrapper">
+				<MediaContainer
+					className="components-focal-point-picker"
+					onKeyDown={ arrowKeyStep }
+					onMouseDown={ startDrag }
+					onBlur={ () => {
+						if ( isDragging ) endDrag();
+					} }
+					ref={ dragAreaRef }
+					role="button"
+					tabIndex={ -1 }
+				>
+					<Grid bounds={ bounds } showOverlay={ showGridOverlay } />
+					<Media
+						alt={ __( 'Media preview' ) }
+						autoPlay={ autoPlay }
+						onLoad={ refUpdateBounds.current }
+						src={ url }
+					/>
+					<FocalPoint
+						{ ...focalPointPosition }
+						isDragging={ isDragging }
+					/>
+				</MediaContainer>
+			</MediaWrapper>
+			<Controls
+				__nextHasNoMarginBottom={ __nextHasNoMarginBottom }
+				hasHelpText={ !! help }
+				point={ { x, y } }
+				onChange={ ( value ) => {
+					onChange?.( getFinalValue( value ) );
+				} }
+			/>
+		</BaseControl>
+	);
+}
+
+export default FocalPointPicker;

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

@@ -1,33 +1,32 @@
 /**
- * WordPress dependencies
+ * External dependencies
  */
-import { useRef, useLayoutEffect } from '@wordpress/element';
+import type { Ref } from 'react';
 
 /**
  * Internal dependencies
  */
 import { MediaPlaceholder } from './styles/focal-point-picker-style';
 import { isVideoType } from './utils';
-
-const noop = () => {};
+import type { FocalPointPickerMediaProps } from './types';
 
 export default function Media( {
 	alt,
 	autoPlay,
 	src,
-	onLoad = noop,
+	onLoad,
 	mediaRef,
 	// Exposing muted prop for test rendering purposes
 	// https://github.com/testing-library/react-testing-library/issues/470
 	muted = true,
 	...props
-} ) {
+}: FocalPointPickerMediaProps ) {
 	if ( ! src ) {
 		return (
-			<MediaPlaceholderElement
+			<MediaPlaceholder
 				className="components-focal-point-picker__media components-focal-point-picker__media--placeholder"
-				onLoad={ onLoad }
-				mediaRef={ mediaRef }
+				ref={ mediaRef as Ref< HTMLDivElement > }
+				{ ...props }
 			/>
 		);
 	}
@@ -42,7 +41,7 @@ export default function Media( {
 			loop
 			muted={ muted }
 			onLoadedData={ onLoad }
-			ref={ mediaRef }
+			ref={ mediaRef as Ref< HTMLVideoElement > }
 			src={ src }
 		/>
 	) : (
@@ -51,25 +50,8 @@ 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 }
 		/>
 	);
 }
-
-function MediaPlaceholderElement( { mediaRef, onLoad = noop, ...props } ) {
-	const onLoadRef = useRef( onLoad );
-
-	/**
-	 * This async callback mimics the onLoad (img) / onLoadedData (video) callback
-	 * for media elements. It is used in the main <FocalPointPicker /> component
-	 * to calculate the dimensions + boundaries for positioning.
-	 */
-	useLayoutEffect( () => {
-		window.requestAnimationFrame( () => {
-			onLoadRef.current();
-		} );
-	}, [] );
-
-	return <MediaPlaceholder ref={ mediaRef } { ...props } />;
-}

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,17 @@
 /**
  * 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`
 	background-color: transparent;
@@ -41,25 +44,48 @@ export const MediaContainer = styled.div`
 `;
 
 export const MediaPlaceholder = styled.div`
-	background: ${ COLORS.lightGray[ 300 ] };
-	height: 170px;
+	background: ${ COLORS.gray[ 100 ] };
+	box-sizing: border-box;
+	height: ${ INITIAL_BOUNDS.height }px;
 	max-width: 280px;
-	min-width: 200px;
+	min-width: ${ INITIAL_BOUNDS.width }px;
 	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`
 	left: 50%;
-	opacity: 0;
 	overflow: hidden;
 	pointer-events: none;
 	position: absolute;
@@ -68,11 +94,8 @@ export const GridView = styled.div`
 	transition: opacity 120ms linear;
 	z-index: 1;
 
-	${ ( { isActive } ) =>
-		isActive &&
-		`
-		opacity: 1;
-	` }
+	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 )`

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,
 			} );
 		} );
 	} );
@@ -137,16 +137,36 @@ describe( 'FocalPointPicker', () => {
 			render(
 				<Picker value={ { x: 0.14, y: 0.62 } } onChange={ spyChange } />
 			);
-			// Click and press arrow up
+			// Focus and press arrow up
 			const dragArea = screen.getByRole( 'button' );
 
 			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' ];
+};