@wordpress/image-cropper 1.0.1-next.6deb34194.0

package/src/provider/index.tsx

@@ -0,0 +1,57 @@
+/**
+ * WordPress dependencies
+ */
+import { createContext, useContext, useMemo } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import useCropper from './use-image-cropper';
+import type { ImageCropperContextValue } from '../types';
+import { MIN_ZOOM } from '../constants';
+
+export const ImageCropperContext = createContext< ImageCropperContextValue >( {
+	cropperState: {
+		crop: { x: 0, y: 0 },
+		croppedArea: { x: 0, y: 0, width: 100, height: 100 },
+		croppedAreaPixels: null,
+		zoom: MIN_ZOOM,
+		rotation: 0,
+		aspectRatio: 1,
+		flip: { horizontal: false, vertical: false },
+		mediaSize: null,
+	},
+	setCropperState: () => {},
+	resetState: null,
+	setResetState: () => {},
+	isDirty: false,
+	reset: () => {},
+	getCroppedImage: () => Promise.resolve( null ),
+} );
+
+export default function ImageCropperProvider( {
+	children,
+}: {
+	children: React.ReactNode;
+} ) {
+	const cropperApi = useCropper();
+	const contextValue = useMemo( () => {
+		return {
+			...cropperApi,
+		};
+	}, [ cropperApi ] );
+
+	return (
+		<ImageCropperContext.Provider value={ contextValue }>
+			{ children }
+		</ImageCropperContext.Provider>
+	);
+}
+
+export const useImageCropper = () => {
+	const context = useContext( ImageCropperContext );
+	if ( ! context ) {
+		throw new Error( 'Missing ImageCropperContext' );
+	}
+	return context;
+};

package/src/provider/use-image-cropper.ts

@@ -0,0 +1,220 @@
+/**
+ * External dependencies
+ */
+import { dequal } from 'dequal';
+
+/**
+ * WordPress dependencies
+ */
+import { useMemo, useState, useCallback } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import type { Point, ImageCropperState, CropperState } from '../types';
+import { MIN_ZOOM } from '../constants';
+import {
+	getCroppedImage as getCroppedImageUtil,
+	normalizeRotation,
+} from '../utils';
+
+export const DEFAULT_INITIAL_STATE: Required< ImageCropperState > = {
+	crop: {
+		x: 0,
+		y: 0,
+		width: 100,
+		height: 100,
+	},
+	zoom: MIN_ZOOM,
+	rotation: 0,
+	aspectRatio: 1,
+	flip: {
+		horizontal: false,
+		vertical: false,
+	},
+};
+
+const DEFAULT_CROP_MEDIA_POSITION: Point = {
+	x: 0,
+	y: 0,
+};
+
+const DEFAULT_CROPPER_STATE: CropperState = {
+	crop: DEFAULT_CROP_MEDIA_POSITION,
+	croppedArea: DEFAULT_INITIAL_STATE.crop,
+	croppedAreaPixels: null,
+	zoom: DEFAULT_INITIAL_STATE.zoom,
+	rotation: DEFAULT_INITIAL_STATE.rotation,
+	flip: DEFAULT_INITIAL_STATE.flip,
+	aspectRatio: DEFAULT_INITIAL_STATE.aspectRatio,
+	mediaSize: null,
+};
+
+export default function useCropper() {
+	const [ cropperState, setInternalCropperState ] = useState< CropperState >(
+		DEFAULT_CROPPER_STATE
+	);
+	const [ resetState, setInternalResetState ] =
+		useState< ImageCropperState | null >( null );
+
+	// Unified setter that supports both partial updates and function updates
+	const setCropperState = useCallback(
+		(
+			newState:
+				| Partial< CropperState >
+				| ( ( prev: CropperState ) => Partial< CropperState > )
+		) => {
+			setInternalCropperState( ( prev ) => {
+				const updates =
+					typeof newState === 'function'
+						? newState( prev )
+						: newState;
+
+				// Apply normalization to rotation if it's being updated
+				const normalizedUpdates = { ...updates };
+				if (
+					'rotation' in normalizedUpdates &&
+					normalizedUpdates.rotation !== undefined
+				) {
+					normalizedUpdates.rotation = normalizeRotation(
+						normalizedUpdates.rotation
+					);
+				}
+
+				return { ...prev, ...normalizedUpdates };
+			} );
+		},
+		[]
+	);
+
+	const setResetState = useCallback(
+		( newResetState: Partial< ImageCropperState > | null = null ) => {
+			// If null, wipe the reset state and reset the cropper state to the default state.
+			if ( ! newResetState ) {
+				setInternalResetState( null );
+				setCropperState( DEFAULT_CROPPER_STATE );
+				return;
+			}
+			if ( typeof newResetState === 'object' ) {
+				const initialState = {
+					...DEFAULT_INITIAL_STATE,
+					...newResetState,
+				};
+				setInternalResetState( initialState );
+				setCropperState( initialState );
+			}
+		},
+		[ setCropperState, setInternalResetState ]
+	);
+
+	/*
+	 * Resets the cropper state.
+	 */
+	const reset = useCallback( () => {
+		if ( resetState ) {
+			// Convert ImageCropperState to CropperState updates
+			const resetUpdates: Partial< CropperState > = {
+				// Reset media position to center
+				crop: { x: 0, y: 0 },
+				// Reset cropped area pixels (will be recalculated)
+				croppedAreaPixels: null,
+			};
+
+			// Set the cropped area from resetState (this is the target crop area)
+			if ( resetState.crop ) {
+				resetUpdates.croppedArea = resetState.crop;
+			}
+			if ( resetState.zoom !== undefined ) {
+				resetUpdates.zoom = resetState.zoom;
+			}
+			if ( resetState.rotation !== undefined ) {
+				resetUpdates.rotation = resetState.rotation;
+			}
+			if ( resetState.aspectRatio !== undefined ) {
+				resetUpdates.aspectRatio = resetState.aspectRatio;
+			}
+			if ( resetState.flip !== undefined ) {
+				resetUpdates.flip = resetState.flip;
+			}
+
+			setCropperState( resetUpdates );
+		} else {
+			setCropperState( { ...DEFAULT_CROPPER_STATE } );
+		}
+	}, [ resetState, setCropperState ] );
+
+	/*
+	 * Returns true if the cropper state is dirty.
+	 * Compare against reset state if available, otherwise against default state.
+	 */
+	const isDirty = useMemo( () => {
+		if ( resetState ) {
+			// Compare the relevant cropper properties against reset state
+			const currentState = {
+				crop:
+					cropperState.croppedAreaPixels || cropperState.croppedArea,
+				zoom: cropperState.zoom,
+				rotation: normalizeRotation( cropperState.rotation ),
+				aspectRatio: cropperState.aspectRatio,
+				flip: cropperState.flip,
+			};
+			return false === dequal( currentState, resetState );
+		}
+
+		// Compare against default state using percentage values
+		const currentState = {
+			crop: cropperState.croppedArea,
+			zoom: cropperState.zoom,
+			rotation: normalizeRotation( cropperState.rotation ),
+			aspectRatio: cropperState.aspectRatio,
+			flip: cropperState.flip,
+		};
+		return false === dequal( currentState, DEFAULT_INITIAL_STATE );
+	}, [ cropperState, resetState ] );
+
+	/**
+	 * Returns the cropped image.
+	 *
+	 * @param {string} src - The source of the image to crop.
+	 * @return {Promise<string | null>} A promise that resolves to the cropped image.
+	 */
+	const getCroppedImage = useCallback(
+		async ( src: string ) => {
+			if ( ! cropperState.croppedAreaPixels ) {
+				return null;
+			}
+			return getCroppedImageUtil(
+				src,
+				cropperState.croppedAreaPixels,
+				cropperState.rotation,
+				cropperState.flip
+			);
+		},
+		[
+			cropperState.croppedAreaPixels,
+			cropperState.rotation,
+			cropperState.flip,
+		]
+	);
+
+	return useMemo(
+		() => ( {
+			cropperState,
+			setCropperState,
+			resetState,
+			setResetState,
+			isDirty,
+			reset,
+			getCroppedImage,
+		} ),
+		[
+			cropperState,
+			setCropperState,
+			resetState,
+			setResetState,
+			isDirty,
+			reset,
+			getCroppedImage,
+		]
+	);
+}

package/src/stories/index.story.tsx

@@ -0,0 +1,351 @@
+/**
+ * WordPress dependencies
+ */
+import { useCallback, useRef, useState } from '@wordpress/element';
+import { __, sprintf } from '@wordpress/i18n';
+import {
+	__experimentalHStack as HStack,
+	__experimentalVStack as VStack,
+	__experimentalHeading as Heading,
+	SelectControl,
+} from '@wordpress/components';
+
+/**
+ * Internal dependencies
+ */
+import ImageCropper from '../components/image-cropper';
+import ImageCropperProvider, { useImageCropper } from '../provider';
+import type { ImageCropperProps, MediaSize } from '../types';
+import { MIN_ZOOM, MAX_ZOOM } from '../constants';
+import './style.css';
+
+export default {
+	title: 'ImageCropper/ImageCropper',
+	component: ImageCropper,
+};
+
+const DefaultComponent = ( args: ImageCropperProps ) => {
+	return (
+		<ImageCropperProvider>
+			<div className="image-cropper__container-wrapper-story">
+				<div className="image-cropper__container-story">
+					<ImageCropper { ...args } />
+				</div>
+			</div>
+		</ImageCropperProvider>
+	);
+};
+
+export const Default = {
+	render: DefaultComponent,
+	args: {
+		src: 'https://s.w.org/images/core/5.3/MtBlanc1.jpg',
+		minZoom: 1,
+		maxZoom: 5,
+	},
+};
+
+const WithControlsComponent = ( args: ImageCropperProps ) => {
+	return (
+		<ImageCropperProvider>
+			<WithControlsContent { ...args } />
+		</ImageCropperProvider>
+	);
+};
+
+const WithControlsContent = ( args: ImageCropperProps ) => {
+	const { cropperState, setCropperState } = useImageCropper();
+	const containerRef = useRef< HTMLDivElement | null >( null );
+	const { containerStyle, handleOnload } = useHandleOnload( containerRef );
+	const handleRotateLeft = useCallback( () => {
+		setCropperState( { rotation: cropperState.rotation - 90 } );
+	}, [ cropperState.rotation, setCropperState ] );
+
+	const handleRotateRight = useCallback( () => {
+		setCropperState( { rotation: cropperState.rotation + 90 } );
+	}, [ cropperState.rotation, setCropperState ] );
+
+	const handleFlipHorizontal = useCallback( () => {
+		setCropperState( {
+			flip: {
+				horizontal: ! cropperState.flip.horizontal,
+				vertical: cropperState.flip.vertical,
+			},
+		} );
+	}, [
+		cropperState.flip.vertical,
+		cropperState.flip.horizontal,
+		setCropperState,
+	] );
+
+	const handleFlipVertical = useCallback( () => {
+		setCropperState( {
+			flip: {
+				horizontal: cropperState.flip.horizontal,
+				vertical: ! cropperState.flip.vertical,
+			},
+		} );
+	}, [
+		cropperState.flip.vertical,
+		cropperState.flip.horizontal,
+		setCropperState,
+	] );
+
+	const handleZoomChange = useCallback(
+		( event: React.ChangeEvent< HTMLInputElement > ) => {
+			setCropperState( { zoom: parseFloat( event.target.value ) } );
+		},
+		[ setCropperState ]
+	);
+
+	const handleAspectRatioChange = useCallback(
+		( value: string ) => {
+			setCropperState( { aspectRatio: parseFloat( value ) } );
+		},
+		[ setCropperState ]
+	);
+
+	const reset = useCallback( () => {
+		setCropperState( {
+			rotation: 0,
+			zoom: MIN_ZOOM,
+			aspectRatio: 1,
+			flip: { horizontal: false, vertical: false },
+			crop: { x: 0, y: 0 },
+		} );
+	}, [ setCropperState ] );
+
+	const aspectRatioOptions = [
+		{ label: __( '1:1 (Square)' ), value: '1' },
+		{ label: __( '16:9 (Widescreen)' ), value: ( 16 / 9 ).toString() },
+		{ label: __( '9:16 (Portrait)' ), value: ( 9 / 16 ).toString() },
+		{ label: __( '4:3 (Standard)' ), value: ( 4 / 3 ).toString() },
+		{ label: __( '3:4 (Portrait)' ), value: ( 3 / 4 ).toString() },
+	];
+
+	return (
+		<>
+			<VStack spacing={ 4 }>
+				<VStack spacing={ 2 }>
+					<Heading level={ 5 }>
+						{ ' ' }
+						{ sprintf(
+							/* translators: %d: rotation anglein degrees */
+							__( 'Rotation: %d' ),
+							cropperState.rotation
+						) }
+					</Heading>
+					<HStack justify="flex-start" spacing={ 4 }>
+						<button onClick={ handleRotateLeft }>
+							{ __( 'Rotate left' ) }
+						</button>
+						<button onClick={ handleRotateRight }>
+							{ __( 'Rotate right' ) }
+						</button>
+					</HStack>
+				</VStack>
+				<VStack spacing={ 2 }>
+					<Heading level={ 5 }>
+						{ ' ' }
+						{ sprintf(
+							/* translators: 1: horizontal flip, 2: vertical flip */
+							__( 'Flip: %1$s / %2$s' ),
+							cropperState.flip.horizontal
+								? __( 'Horizontal' )
+								: __( 'None' ),
+							cropperState.flip.vertical
+								? __( 'Vertical' )
+								: __( 'None' )
+						) }
+					</Heading>
+					<HStack justify="flex-start" spacing={ 4 }>
+						<button onClick={ handleFlipHorizontal }>
+							{ __( 'Flip horizontal' ) }
+						</button>
+						<button onClick={ handleFlipVertical }>
+							{ __( 'Flip vertical' ) }
+						</button>
+					</HStack>
+				</VStack>
+				<VStack spacing={ 2 }>
+					<Heading level={ 5 }>
+						{ sprintf(
+							/* translators: %s: zoom level */
+							__( 'Zoom: %s' ),
+							cropperState.zoom.toFixed( 2 )
+						) }
+					</Heading>
+					<VStack spacing={ 2 }>
+						<input
+							type="range"
+							min={ MIN_ZOOM }
+							max={ MAX_ZOOM }
+							step="0.1"
+							value={ cropperState.zoom }
+							onChange={ handleZoomChange }
+						/>
+					</VStack>
+				</VStack>
+				<VStack spacing={ 2 }>
+					<Heading level={ 5 }>
+						{ sprintf(
+							/* translators: %s: aspect ratio */
+							__( 'Aspect Ratio: %s' ),
+							cropperState.aspectRatio.toFixed( 2 )
+						) }
+					</Heading>
+					<SelectControl
+						value={ cropperState.aspectRatio.toString() }
+						options={ aspectRatioOptions }
+						onChange={ handleAspectRatioChange }
+						__next40pxDefaultSize
+						__nextHasNoMarginBottom
+					/>
+				</VStack>
+				<HStack style={ { marginBottom: '20px' } } spacing={ 2 }>
+					<button onClick={ reset }>{ __( 'Reset' ) }</button>
+				</HStack>
+			</VStack>
+
+			<div className="image-cropper__container-wrapper-story">
+				<div
+					className="image-cropper__container-story"
+					ref={ containerRef }
+					style={ {
+						...containerStyle,
+					} }
+				>
+					<ImageCropper { ...args } onLoad={ handleOnload } />
+				</div>
+			</div>
+		</>
+	);
+};
+
+export const WithControls = {
+	render: WithControlsComponent,
+	args: {
+		src: 'https://s.w.org/images/core/5.3/MtBlanc1.jpg',
+		minZoom: 1,
+		maxZoom: 5,
+	},
+};
+
+// Utils.
+
+/**
+ * Handles the onload event of the image cropper, calculating the maximum scale that can be used to fit the image into the container.
+ *
+ * @param containerRef - The ref to the container element.
+ * @return The container style and the handleOnload function.
+ */
+function useHandleOnload( containerRef: React.RefObject< HTMLDivElement > ) {
+	const [ containerStyle, setContainerStyle ] = useState< {
+		minHeight?: string;
+		minWidth?: string;
+		maxWidth?: string;
+		maxHeight?: string;
+	} | null >( null );
+	const handleOnload = useCallback(
+		( mediaSize: MediaSize ) => {
+			/*
+			 * Because rotation is performed using CSS transforms, the media is outside the flow
+			 * of the container. The cropper lib does not handle dynamic resize by default,
+			 * so the solution is just to adjust the container so that the image will fit
+			 * inside the crop area regardless of the rotation.
+			 */
+			if (
+				containerRef &&
+				containerRef.current?.offsetWidth &&
+				containerRef.current?.offsetHeight
+			) {
+				const { scaledWidth, scaledHeight } =
+					getMaximumScaledDimensions(
+						mediaSize.width,
+						mediaSize.height,
+						containerRef.current.offsetWidth,
+						containerRef.current.offsetHeight
+					);
+				/*
+				 * Depending on the image's aspect ration, allow scaling with window.
+				 * Set minHeight/maxHeight to the container width to ensure that the image
+				 * fits into the crop area, even when the image is rotated.
+				 */
+				if ( mediaSize.width > containerRef.current.offsetHeight ) {
+					setContainerStyle( {
+						maxWidth: `${ scaledWidth }px`,
+						minHeight: `${ scaledWidth }px`,
+					} );
+				} else if (
+					mediaSize.height > containerRef.current.offsetWidth
+				) {
+					setContainerStyle( {
+						maxHeight: `${ scaledHeight }px`,
+						minWidth: `${ scaledHeight }px`,
+					} );
+				}
+			}
+		},
+		[ containerRef ]
+	);
+	return { containerStyle, handleOnload };
+}
+
+/**
+ * Calculates the maximum scale that can be used to fit the image into the container.
+ * To maximize the bounding box, this function assumes 90° rotations (0°, 90°, 180°, 270°) only.
+ *
+ * Later, if 0-360° rotations are supported, this function will need to be updated
+ * to account for the maximum diagonal dimensions. E.g.,
+ *
+ * ```
+ * 	 // The maximum bounding box dimensions occur at 45° for rectangles.
+ * 	 // Max bounding width/height = (width + height) / √2 * √2 = width + height
+ * 	 // But this is only true for squares. For rectangles, we need to be more precise.
+ * 	 const diagonal = Math.sqrt(
+ * 	 	imageWidth * imageWidth + imageHeight * imageHeight
+ * 	 );
+ *
+ * 	// Scale to fit this maximum bounding square in the container.
+ * 	const scale = Math.min(
+ * 		containerWidth / diagonal,
+ * 		containerHeight / diagonal
+ * 	);
+ * ```
+ *
+ * @param imageWidth      - The width of the image.
+ * @param imageHeight     - The height of the image.
+ * @param containerWidth  - The width of the container.
+ * @param containerHeight - The height of the container.
+ */
+function getMaximumScaledDimensions(
+	imageWidth: number,
+	imageHeight: number,
+	containerWidth: number,
+	containerHeight: number
+): {
+	scale: number;
+	scaledWidth: number;
+	scaledHeight: number;
+} {
+	// Calculate scale for original orientation.
+	const scaleOriginal = Math.min(
+		containerWidth / imageWidth,
+		containerHeight / imageHeight
+	);
+
+	// Calculate scale for 90° rotated orientation.
+	const scaleRotated = Math.min(
+		containerWidth / imageHeight, // Rotated width is original height.
+		containerHeight / imageWidth // Rotated height is original width.
+	);
+
+	// Use the smaller scale to ensure it fits in both orientations
+	const scale = Math.min( scaleOriginal, scaleRotated );
+
+	return {
+		scale,
+		scaledWidth: imageWidth * scale,
+		scaledHeight: imageHeight * scale,
+	};
+}

package/src/stories/style.css

@@ -0,0 +1,17 @@
+.image-cropper__container-wrapper-story {
+    background: rgba( 0, 0, 0, 0.1 ) !important;
+    height: 500px;
+    width: 100%;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    box-sizing: border-box;
+}
+.image-cropper__container-story {
+    position: relative;
+    height: 100%;
+    width: 100%;
+}
+.image-cropper__crop-area {
+    box-shadow: unset !important;
+}

package/src/types.ts

@@ -0,0 +1,54 @@
+/**
+ * External dependencies
+ */
+import type { Point, Area, MediaSize } from 'react-easy-crop';
+
+// Re-export types for convenience.
+export type { Point, Area, MediaSize };
+
+export type Flip = {
+	horizontal: boolean;
+	vertical: boolean;
+};
+
+export interface ImageCropperState {
+	rotation?: number;
+	crop?: Area;
+	zoom?: number;
+	flip?: Flip;
+	aspectRatio?: number;
+}
+
+export interface CropperState {
+	crop: Point;
+	croppedArea?: Area;
+	croppedAreaPixels?: Area | null;
+	zoom: number;
+	rotation: number;
+	flip: Flip;
+	aspectRatio: number;
+	mediaSize: MediaSize | null;
+}
+
+export interface ImageCropperProps {
+	src: string;
+	onLoad?: ( mediaSize: MediaSize ) => void;
+	minZoom?: number;
+	maxZoom?: number;
+}
+
+export interface ImageCropperContextValue {
+	cropperState: CropperState;
+	setCropperState: (
+		newState:
+			| Partial< CropperState >
+			| ( ( prev: CropperState ) => Partial< CropperState > )
+	) => void;
+	resetState: ImageCropperState | null;
+	setResetState: (
+		newResetState: Partial< ImageCropperState > | null
+	) => void;
+	isDirty: boolean;
+	reset: () => void;
+	getCroppedImage: ( src: string ) => Promise< string | null >;
+}