[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]

AI Code Review

🔶 Changes requested — one or more medium-severity items must be addressed

---

What was reviewed

File	Change
src/ImageCropper.xml	New widget manifest
typings/ImageCropperProps.d.ts	Generated container/preview prop types
src/ImageCropper.tsx	Widget entry point
src/components/ImageCropperContainer.tsx	Main container — wires all hooks, handles crop/rotate/reset
src/components/CropArea.tsx	Renders react-image-crop + zoom + safeImageUri guard
src/components/CropToolbar.tsx	Toolbar (rotate, grayscale, zoom slider, reset)
src/components/PreviewPane.tsx	Canvas-based live crop preview pane
src/hooks/useAutoApplyCrop.ts	Debounced auto-commit hook
src/hooks/useImageCropperState.ts	State container hook
src/hooks/useOriginalImage.ts	Captures original bytes for Reset
src/hooks/usePreviewSrc.ts	Blob URL bridge for deferred Mendix commits
src/utils/cropImage.ts	Canvas crop export
src/utils/rotateImage.ts	Canvas rotation export
src/utils/safeImageUri.ts	URI allowlist guard
src/utils/cropGuard.ts	Stray-click filter
src/utils/initialCrop.ts	Default 80%-centered crop box
src/utils/describeConfig.ts	Studio Pro caption formatter
src/ImageCropper.editorConfig.ts	Studio Pro structure/design-mode preview
src/ImageCropper.editorPreview.tsx	Design-mode preview component
src/__tests__/*.spec.tsx	Container/integration tests
src/components/__tests__/*.spec.tsx	Component unit tests
src/hooks/__tests__/*.spec.ts	Hook unit tests
src/utils/__tests__/*.spec.ts	Utility unit tests
src/ui/ImageCropper.scss	Widget SCSS
jest.config.js	Jest config (extends base)
CHANGELOG.md	Changelog — "Initial release" entry present

Skipped (out of scope): dist/, pnpm-lock.yaml, PNG/SVG assets, openspec/

---

Findings

🔶 Medium — 3 unit tests failing in CI

File: src/__tests__/ImageCropper.editor.spec.tsx lines 55, 60, 72
Problem: The CI "Run code quality check" job exits with code 1. Three tests in ImageCropper.editor.spec.tsx fail because the actual structure-preview output doesn't match what the spec expects.

Test 1 expects the text node "Image cropper" but the component returns "[Configure Image Cropper]".
Test 2 expects "[No attribute selected]" but receives "[Configure Image Cropper]".
Test 3 expects "Circle · 1:1 · JPEG · Viewport" but receives "[Circle · 1:1 · JPEG · Viewport] Image Cropper" — the whole string is wrapped with a widget-title prefix instead of being a standalone body text.

The mismatch is between editorConfig.ts's getPreview implementation (which wraps the caption inside "[…] Image Cropper") and the collectText helper in the spec that expects the caption and title to be separate Text nodes. Either the structure-preview tree layout doesn't match the assertions, or the caption strings changed during development and the tests were never updated.

Fix: Bring the spec into sync with the actual getPreview output. Based on what CI reports, the simplest fix is:

// test 1 — title is embedded in the body string, not a separate node
expect(texts.some(t => t.includes("Image Cropper"))).toBe(true);

// test 2 — placeholder is different
expect(texts).toContain("[Configure Image Cropper]");

// test 3 — full caption string, not just the config part
expect(texts).toContain("Circle · 1:1 · JPEG · Viewport");  // this one only needs the full string to be present as a sub-item — check whether collectText splits it

Alternatively, align the spec assertions to "[Configure Image Cropper]" and "[Circle · 1:1 · JPEG · Viewport] Image Cropper" if those are the intended strings. Do not merge until tests are green.

---

🔶 Medium — Lint warning (import order) in CI

File: src/components/CropArea.tsx line 6
Problem: CI lint step reports:

warning  `../utils/cropGuard` import should occur before import of `../utils/cropImage`  import/order

While this is a warning not an error, it contributes to the failed CI job and will accumulate technical debt. The auto-format hook does not fix import ordering.

Fix: Move the cropGuard import above the cropImage import:

import { isStrayCrop, MIN_CROP_PX } from "../utils/cropGuard";
import { CENTER_ANCHOR, type ZoomAnchor } from "../utils/cropImage";

---

⚠️ Low — editorPreview.tsx: createRef used inside a function component

File: src/ImageCropper.editorPreview.tsx line 22
Note: createRef is used inside StaticCropPreview instead of useRef. createRef creates a new ref object on every render — for a functional component useRef is the correct API. In the editor context this is unlikely to cause visible problems (the preview re-renders infrequently), but it's a latent misuse of the ref API.

// Replace
const imageRef = createRef<HTMLImageElement>();
// With
const imageRef = useRef<HTMLImageElement>(null);

---

⚠️ Low — usePreviewSrc: state mutation during render

File: src/hooks/usePreviewSrc.ts lines 38–44
Note: The prevUri comparison and the revoke()/setPreviewSrc(undefined) calls happen unconditionally during render (not inside a useEffect or useMemo). Calling setPreviewSrc during render is allowed by React as a synchronous bail-out, but mixing revoke() (a side-effect on a Ref) with the state update makes the pattern fragile and will trigger warnings in React Strict Mode's double-invoke behaviour. Consider wrapping this in a useEffect that reacts to committedUri changes instead.

---

Positives

• safeImageUri correctly allowlists only https?:, blob:, and data:image/ URIs with a tested unit spec — good defense-in-depth against XSS via Mendix image attributes.
• onCropAction.canExecute is properly checked before execute() — Mendix API contract honoured.
• props.image.status and props.image.readOnly are checked in both applyCrop and handleRotate before any setValue call — correct guard against read-only and loading states.
• The useAutoApplyCrop / userDraggedRef pattern cleanly separates layout-driven onCropComplete from genuine user drags, preventing unintended auto-commits in list views — the multi-instance test suite confirms this.
• useOriginalImage's async fetch sets a cancelled flag and returns a cleanup function — correct async-effect guard against state updates after unmount.
• computeSourceRect is shared between cropImage and PreviewPane, ensuring the preview and the exported file always frame the same pixels.
• Jest config correctly extends @mendix/pluggable-widgets-tools/test-config/jest.config, and setupFilesAfterEnv is properly extended rather than replaced.
• 115 tests across 18 suites, with real scenario coverage (grayscale reversibility, multi-instance isolation, reset, zoom debounce).