[WC-3435]: Image Cropper Design and feats

[rahmanunver]

Pull request type

New feature (non-breaking change which adds functionality)

---

Description

Initial development of the Image Cropper widget. This is a pre-release widget; the items below describe its current capabilities, not changes to a shipped version.

Cropping

• Interactive crop with configurable shape (rectangle / circle) and aspect ratio (free or custom)
• Zoom via inline slider and optional mouse-wheel zoom
• Output configuration: format, quality, and size (original or viewport)

Toolbar

• Single-row toolbar: flip-left, flip-right, grayscale, zoom slider, reset
• Flip controls (90° rotation under the hood) rendered as SVG icon buttons
• Grayscale toggle
• Reset to the original image
• Always-on native tooltips on every toolbar button

Editor experience (Studio Pro)

• Structure-mode and design-mode previews
• Design-mode preview renders the real crop area against the configured image
• Studio Pro toolbox category and icons

Layout

• Widget sizes to its image and renders block-level, so sibling widgets stack below it
• Editor preview fills the available width

Behavior

• Grayscale stays reversible after a flip; grayscale is baked into the saved file only when the toggle is on
• Crop auto-commit is gated on a genuine user drag, so editing one cropper instance does not commit others in a list
• Crop alignment preserved across flips via a live blob preview
• Image source guarded through a safeImageUri allowlist

Testing

• Unit/integration specs for flip, grayscale, zoom, crop commit, grayscale reversibility, multi-instance commit isolation, and editor previews (103 tests)

What should be covered while testing?

• Crop, zoom, flip, grayscale, and reset on a bound image attribute
• Grayscale ON -> flip -> grayscale OFF restores color; grayscale ON -> flip -> save with no further crop persists grayscale
• Two croppers in a list: editing one and saving commits only that instance

[github-actions]

⚠️ Low — External side effect (URL.revokeObjectURL) called during render

revoke() triggers URL.revokeObjectURL, which is a side effect with an observable external result. React allows calling setState during render as a derived-state bailout, but external side effects in render violate render-purity. In React 18 concurrent mode an interrupted render can leave the blobRef mutation in place without completing the paired setPreviewSrc(undefined) call on the abandoned pass.

A useLayoutEffect keyed on committedUri avoids the issue — it fires synchronously after paint, like a synchronous effect, but keeps render pure:

Suggested change

	if (prevUri.current !== committedUri) {
	prevUri.current = committedUri;
	if (blobRef.current) {
	revoke();
	setPreviewSrc(undefined);
	}
	}
	useLayoutEffect(() => {
	if (prevUri.current !== committedUri) {
	prevUri.current = committedUri;
	if (blobRef.current) {
	revoke();
	setPreviewSrc(undefined);
	}
	}
	// eslint-disable-next-line react-hooks/exhaustive-deps
	}, [committedUri]); // revoke is stable — intentionally omitted

[github-actions]

⚠️ Low — Renders "null:null" when custom dimensions are not yet set

ImageCropperPreviewProps.customAspectWidth / customAspectHeight are typed number | null. Before the user fills in values in Studio Pro the interpolation produces the string "null:null". The null case is not covered by any spec.

Suggested change

	return `${values.customAspectWidth}:${values.customAspectHeight}`;
	return `${values.customAspectWidth ?? 1}:${values.customAspectHeight ?? 1}`;