refactor(image-cropper-web): drive container from ImageCropperStore

Wire ImageCropperContainer to the MobX store via the mobx-kit gate
pattern (GateProvider + useConst + useSetup) and wrap it in observer.
Crop operations become plain store method calls.

Remove the five state-mirroring refs (committedCropRef, zoomRef,
grayscaleRef, liveCropRef, zoomAnchorRef) and the two callback mirrors
(markInternalRef, showPreviewRef); the store reads its own observable
state, so stable-identity closures no longer need them. Config and the
controlled image value are read live through the gate; the bound uri is
synced inbound via a single effect calling store.onImageChanged.

usePreviewSrc, useOriginalImage and the DOM image ref stay in React and
are injected into the store through setDeps. Delete useAutoApplyCrop and
useImageCropperState, now subsumed by the store.

Author: rahmanunver

packages/pluggableWidgets/image-cropper-web/src/components/CropArea.tsx

@@ -2,8 +2,8 @@ import { Dispatch, ReactElement, Ref, SetStateAction, SyntheticEvent, useCallbac
 import { default as ReactCrop, type Crop, type PixelCrop } from "react-image-crop";
 import { ZoomContainer } from "./ZoomContainer";
 import { WheelZoomModeEnum } from "../../typings/ImageCropperProps";
-import { CENTER_ANCHOR, type ZoomAnchor } from "../utils/cropImage";
 import { isStrayCrop, MIN_CROP_PX } from "../utils/cropGuard";
+import { CENTER_ANCHOR, type ZoomAnchor } from "../utils/cropImage";
 import { buildInitialCrop } from "../utils/initialCrop";
 import { safeImageUri } from "../utils/safeImageUri";
 

packages/pluggableWidgets/image-cropper-web/src/components/ImageCropperContainer.tsx

@@ -1,254 +1,54 @@
 import classNames from "classnames";
 import { ValueStatus } from "mendix";
-import { ReactElement, SetStateAction, useCallback, useEffect, useRef, useState } from "react";
-import { type Crop, type PixelCrop } from "react-image-crop";
+import { observer } from "mobx-react-lite";
+import { ReactElement, useEffect, useRef } from "react";
+import { GateProvider } from "@mendix/widget-plugin-mobx-kit/main";
+import { useConst } from "@mendix/widget-plugin-mobx-kit/react/useConst";
+import { useSetup } from "@mendix/widget-plugin-mobx-kit/react/useSetup";
 import { CropArea } from "./CropArea";
 import { CropToolbar } from "./CropToolbar";
 import { ImageCropperContainerProps } from "../../typings/ImageCropperProps";
-import { useAutoApplyCrop } from "../hooks/useAutoApplyCrop";
-import { useImageCropperState } from "../hooks/useImageCropperState";
 import { useOriginalImage } from "../hooks/useOriginalImage";
 import { usePreviewSrc } from "../hooks/usePreviewSrc";
-import { resolveAspectRatio } from "../utils/aspectRatio";
-import { cropImage, CropError, CENTER_ANCHOR, type ZoomAnchor } from "../utils/cropImage";
-import { buildInitialCrop } from "../utils/initialCrop";
-import { rotateImage } from "../utils/rotateImage";
+import { ImageCropperStore } from "../stores/ImageCropperStore";
 
-export function ImageCropperContainer(props: ImageCropperContainerProps): ReactElement | null {
-    const state = useImageCropperState(Number(props.minZoom));
+export const ImageCropperContainer = observer(function ImageCropperContainer(
+    props: ImageCropperContainerProps
+): ReactElement | null {
+    const gateProvider = useConst(() => new GateProvider<ImageCropperContainerProps>(props));
+    const store = useSetup(() => new ImageCropperStore(gateProvider.gate));
 
-    const { setZoom, setLiveCrop, setCommittedCrop, setGrayscale } = state;
-
-    const committedCropRef = useRef<PixelCrop | undefined>(undefined);
-    committedCropRef.current = state.committedCrop;
-    const zoomRef = useRef(state.zoom);
-    zoomRef.current = state.zoom;
-    const grayscaleRef = useRef(state.grayscale);
-    grayscaleRef.current = state.grayscale;
-    const userDraggedRef = useRef(false);
-    // Live crop mirror so handleZoomChange (stable identity) can read the box's current center.
-    const liveCropRef = useRef<Crop | undefined>(undefined);
-    liveCropRef.current = state.liveCrop;
-
-    // Fixed point of the zoom, captured from the box center when zoom changes and frozen while the
-    // box moves/draws (so the image stays stable). State drives CropArea's transformOrigin; the ref
-    // mirror lets applyCrop's stable closure read it for the matching export math.
-    const [zoomAnchor, setZoomAnchor] = useState<ZoomAnchor>(CENTER_ANCHOR);
-    const zoomAnchorRef = useRef(zoomAnchor);
-    zoomAnchorRef.current = zoomAnchor;
-
-    const applyCrop = useCallback(async () => {
-        const img = state.imageRef.current;
-        const committedCrop = committedCropRef.current;
-        if (
-            !img ||
-            !committedCrop ||
-            props.image.readOnly ||
-            props.image.status !== ValueStatus.Available ||
-            !props.image.value
-        ) {
-            return;
-        }
-        try {
-            const file = await cropImage({
-                image: img,
-                pixelCrop: committedCrop,
-                zoom: zoomRef.current,
-                zoomAnchor: zoomAnchorRef.current,
-                outputFormat: props.outputFormat,
-                outputQuality: Number(props.outputQuality),
-                outputSize: props.outputSize,
-                cropShape: props.cropShape,
-                viewportWidth: props.boundaryWidth,
-                viewportHeight: props.boundaryHeight,
-                grayscale: grayscaleRef.current,
-                originalName: props.image.value.name
-            });
-            if (props.outputSize === "viewport") {
-                props.image.setThumbnailSize(props.boundaryWidth, props.boundaryHeight);
-            }
-            markInternalRef.current();
-            props.image.setValue(file);
-            if (props.onCropAction?.canExecute) {
-                props.onCropAction.execute();
-            }
-        } catch (err) {
-            if (err instanceof CropError) {
-                console.error("[image-cropper-web] CropError:", err.message);
-            } else {
-                console.error("[image-cropper-web] unexpected error:", err);
-                throw err;
-            }
-        }
-    }, [
-        state.imageRef,
-        props.image,
-        props.outputFormat,
-        props.outputQuality,
-        props.outputSize,
-        props.cropShape,
-        props.boundaryWidth,
-        props.boundaryHeight,
-        props.onCropAction
-    ]);
+    // Push fresh Mendix props into the gate every render (config + image read live off it).
+    useEffect(() => {
+        gateProvider.setProps(props);
+    });
 
-    const auto = useAutoApplyCrop(applyCrop);
-    const { armed } = auto;
-
-    const handleImageLoad = useCallback(
-        (percentCrop: Crop, pixelCrop: PixelCrop) => {
-            setZoom(Number(props.minZoom));
-            setZoomAnchor(CENTER_ANCHOR);
-            setLiveCrop(percentCrop);
-            setCommittedCrop(pixelCrop);
-            armed();
-        },
-        [setZoom, setLiveCrop, setCommittedCrop, props.minZoom, armed]
-    );
+    const imageRef = useRef<HTMLImageElement>(null);
 
     const uri = props.image.status === ValueStatus.Available ? props.image.value?.uri : undefined;
     const original = useOriginalImage(
         uri,
         props.image.status === ValueStatus.Available ? props.image.value?.name : undefined
     );
-
-    // Ref mirror so applyCrop's stable identity is untouched (same reason zoomRef exists).
-    const markInternalRef = useRef(original.markInternalChange);
-    markInternalRef.current = original.markInternalChange;
-
-    // Live preview for baked rotations: setValue defers the commit, so show a local
+    // Live preview for baked rotations/reset: setValue defers the commit, so show a local
     // blob URL until the bound uri catches up on Save.
     const { previewSrc, showPreview } = usePreviewSrc(uri);
-    const showPreviewRef = useRef(showPreview);
-    showPreviewRef.current = showPreview;
 
+    // Feed the store its imperative React-owned deps. getImage/getOriginal close over refs, so
+    // re-inject every render; assigning plain (non-observable) fields triggers no reactions.
     useEffect(() => {
-        setLiveCrop(undefined);
-        setCommittedCrop(undefined);
-        armed();
-    }, [uri, setLiveCrop, setCommittedCrop, armed]);
-
-    const handleCropComplete = useCallback(
-        (pixelCrop: PixelCrop) => {
-            committedCropRef.current = pixelCrop;
-            setCommittedCrop(pixelCrop);
-            if (userDraggedRef.current) {
-                userDraggedRef.current = false;
-                auto.applyNow();
-            }
-        },
-        [setCommittedCrop, auto]
-    );
-
-    const handleZoomChange = useCallback(
-        (next: SetStateAction<number>) => {
-            // Freeze the zoom anchor at the current box center. Recomputing it only here (not while
-            // the box moves) keeps the image stable during drags/draws but still zooms into the box.
-            const live = liveCropRef.current;
-            if (live && live.unit === "%") {
-                setZoomAnchor({ x: (live.x + live.width / 2) / 100, y: (live.y + live.height / 2) / 100 });
-            }
-            setZoom(next);
-            auto.applyDebounced();
-        },
-        [setZoom, auto]
-    );
-
-    const handleRotate = useCallback(
-        async (deltaDeg: number) => {
-            const img = state.imageRef.current;
-            if (!img || props.image.readOnly || props.image.status !== ValueStatus.Available || !props.image.value) {
-                return;
-            }
-            try {
-                // Working image is ALWAYS color so toggling grayscale OFF stays reversible.
-                const working = await rotateImage({
-                    image: img,
-                    rotation: deltaDeg,
-                    outputFormat: props.outputFormat,
-                    outputQuality: Number(props.outputQuality),
-                    grayscale: false,
-                    originalName: props.image.value.name
-                });
-                // Commit a baked B&W file only while the toggle is ON, so a rotate-then-Save
-                // with no further crop still persists grayscale.
-                const committed = grayscaleRef.current
-                    ? await rotateImage({
-                          image: img,
-                          rotation: deltaDeg,
-                          outputFormat: props.outputFormat,
-                          outputQuality: Number(props.outputQuality),
-                          grayscale: true,
-                          originalName: props.image.value.name
-                      })
-                    : working;
-                setLiveCrop(undefined);
-                setCommittedCrop(undefined);
-                committedCropRef.current = undefined;
-                armed();
-                // Show COLOR working pixels; CropArea reloads from this blob and rebuilds
-                // a fresh crop against the swapped dimensions on its onLoad.
-                // The CSS grayscale filter from state.grayscale still renders gray on screen.
-                showPreviewRef.current(working);
-                markInternalRef.current();
-                props.image.setValue(committed);
-            } catch (err) {
-                if (err instanceof CropError) {
-                    console.error("[image-cropper-web] CropError:", err.message);
-                } else {
-                    throw err;
-                }
-            }
-        },
-        [state.imageRef, props.image, props.outputFormat, props.outputQuality, setLiveCrop, setCommittedCrop, armed]
-    );
-
-    const handleToggleGrayscale = useCallback(() => {
-        setGrayscale(prev => !prev);
-        auto.applyDebounced();
-    }, [setGrayscale, auto]);
-
-    const handleReset = useCallback(() => {
-        setZoom(Number(props.minZoom));
-        setZoomAnchor(CENTER_ANCHOR);
-        setGrayscale(false);
-        armed(); // do not auto-apply the reset itself
-        const file = original.getOriginal();
-        if (file && !props.image.readOnly && props.image.status === ValueStatus.Available) {
-            // Mirror handleRotate: setValue defers the commit, so drive the live preview with the
-            // original bytes too — otherwise a stale rotated blob keeps rendering after Reset.
-            showPreviewRef.current(file);
-            markInternalRef.current();
-            props.image.setValue(file);
-        }
-        // Re-seed the default cropbox to its initial state. If restoring original bytes changed
-        // the uri (e.g. after a rotation), CropArea's onLoad re-seeds again against the correct
-        // dimensions; when no edit occurred the uri is unchanged and onLoad won't refire, so this
-        // direct re-seed is what puts the box back.
-        const img = state.imageRef.current;
-        if (img && img.naturalWidth) {
-            const aspect = resolveAspectRatio(props.aspectRatio, props.customAspectWidth, props.customAspectHeight);
-            const { percentCrop, pixelCrop } = buildInitialCrop(img, aspect);
-            setLiveCrop(percentCrop);
-            setCommittedCrop(pixelCrop);
-        } else {
-            setLiveCrop(undefined);
-            setCommittedCrop(undefined);
-        }
-    }, [
-        setZoom,
-        props.minZoom,
-        props.image,
-        props.aspectRatio,
-        props.customAspectWidth,
-        props.customAspectHeight,
-        setGrayscale,
-        setLiveCrop,
-        setCommittedCrop,
-        armed,
-        original,
-        state.imageRef
-    ]);
+        store.setDeps({
+            getImage: () => imageRef.current,
+            showPreview,
+            markInternalChange: original.markInternalChange,
+            getOriginal: original.getOriginal
+        });
+    });
+
+    // Inbound image sync: a new bound uri means the source changed — clear the crop and disarm.
+    useEffect(() => {
+        store.onImageChanged();
+    }, [uri, store]);
 
     if (props.image.status === ValueStatus.Loading) {
         return (
@@ -291,41 +91,37 @@ export function ImageCropperContainer(props: ImageCropperContainerProps): ReactE
         );
     }
 
-    const aspect = resolveAspectRatio(props.aspectRatio, props.customAspectWidth, props.customAspectHeight);
-
     return (
         <div className={classNames("widget-image-cropper", props.class)} style={props.style} tabIndex={props.tabIndex}>
             <CropArea
                 src={previewSrc ?? props.image.value.uri}
-                crop={state.liveCrop}
-                onCropChange={state.setLiveCrop}
-                onCropComplete={handleCropComplete}
-                onUserInteractStart={() => {
-                    userDraggedRef.current = true;
-                }}
-                aspect={aspect}
+                crop={store.liveCrop}
+                onCropChange={crop => store.setLiveCrop(crop)}
+                onCropComplete={pixelCrop => store.commitCrop(pixelCrop)}
+                onUserInteractStart={() => store.markUserDragged()}
+                aspect={store.aspect}
                 circular={props.cropShape === "circle"}
                 resizable={props.resizableEnabled}
                 boundaryWidth={props.boundaryWidth}
                 boundaryHeight={props.boundaryHeight}
-                onImageLoad={handleImageLoad}
-                zoom={state.zoom}
+                onImageLoad={(percentCrop, pixelCrop) => store.initFromImageLoad(percentCrop, pixelCrop)}
+                zoom={store.zoom}
                 minZoom={Number(props.minZoom)}
                 maxZoom={Number(props.maxZoom)}
-                setZoom={handleZoomChange}
-                zoomAnchor={zoomAnchor}
+                setZoom={next => store.setZoom(typeof next === "function" ? next(store.zoom) : next)}
+                zoomAnchor={store.zoomAnchor}
                 wheelZoomMode={props.zoomEnabled ? props.wheelZoomMode : "off"}
-                grayscale={state.grayscale}
-                imageRef={state.imageRef}
+                grayscale={store.grayscale}
+                imageRef={imageRef}
             />
             <CropToolbar
                 showRotation={props.enableRotation}
                 showGrayscale={props.enableGrayscale}
                 showZoom={props.zoomEnabled && props.showZoomSlider}
                 showReset={props.showResetButton}
-                grayscale={state.grayscale}
+                grayscale={store.grayscale}
                 canReset={original.canRestore}
-                zoom={state.zoom}
+                zoom={store.zoom}
                 minZoom={Number(props.minZoom)}
                 maxZoom={Number(props.maxZoom)}
                 rotateLeftLabel={props.rotateLeftLabel?.value ?? "Rotate left"}
@@ -336,12 +132,12 @@ export function ImageCropperContainer(props: ImageCropperContainerProps): ReactE
                 resetAriaLabel={props.resetAriaLabel?.value ?? "Reset crop"}
                 zoomCaption={props.zoomCaption?.value ?? "Zoom"}
                 zoomAriaLabel={props.zoomAriaLabel?.value ?? "Zoom"}
-                onZoomChange={handleZoomChange}
-                onRotateLeft={() => handleRotate(-90)}
-                onRotateRight={() => handleRotate(90)}
-                onToggleGrayscale={handleToggleGrayscale}
-                onReset={handleReset}
+                onZoomChange={zoom => store.setZoom(zoom)}
+                onRotateLeft={() => store.rotate(-90)}
+                onRotateRight={() => store.rotate(90)}
+                onToggleGrayscale={() => store.toggleGrayscale()}
+                onReset={() => store.reset()}
             />
         </div>
     );
-}
+});