MobX crop store for Image Cropper

[rahmanunver]

Pull request type

Refactoring (e.g. file rename, variable rename, etc.)

---

Description

Stacked on top of the Image Cropper PR (feat/image-cropper-polish-rotate-bw) — base is set to that branch, so this diff shows only the MobX refactor, not the base PR's changes.

Why. Review feedback flagged that the widget's state had become too coupled to React. ImageCropperContainer carried five state-mirroring refs (committedCropRef, zoomRef, grayscaleRef, liveCropRef, zoomAnchorRef) plus two callback mirrors (markInternalRef, showPreviewRef). They existed only because applyCrop was a stable-identity useCallback (kept stable for the 400ms auto-apply debouncer) and therefore couldn't read current state through its stale closure. A MobX store method reads this.zoom directly, so the refs are no longer needed.

Moved into ImageCropperStore (MobX): the crop-domain working state — liveCrop, committedCrop, zoomAnchor (observable.ref), zoom, grayscale (observable) — plus aspect (computed) and the crop operations as actions (setZoom, commitCrop, toggleGrayscale, rotate, reset, initFromImageLoad, onImageChanged). The store also owns the debounce + auto-apply gate (absorbing useAutoApplyCrop). Crop ops are now plain calls like store.setZoom(v) / store.rotate(90).

Stayed normal React state (imperative / DOM-bound): the imageRef DOM node, usePreviewSrc (blob object-URL lifecycle), useOriginalImage (fetch + unmount cleanup + internal-change flag), and CropArea's local DOM-measurement state. These are injected into the store via setDeps. Config props are read live through the mobx-kit gate, not copied into observables.

Controlled/uncontrolled unchanged. The only externally controlled value is props.image (Mendix EditableValue); zoom/rotation/grayscale/crop are internal. Inbound image changes sync through one uri-keyed effect calling store.onImageChanged(); outbound writes go markInternalChange() → setValue(), with the internal-change flag absorbing the resulting uri change so there's no feedback loop. No reactions used for prop syncing.

Preview stays an async action, not a computed — cropImage/rotateImage are async canvas operations reading a live DOM <img>, so they can't be a pure synchronous computed.

Removed: the 5 mirror refs + 2 callback mirrors, and the useAutoApplyCrop / useImageCropperState hooks (subsumed by the store). ImageCropperContainer is now an observer wired via the shared widget-plugin-mobx-kit gate pattern (GateProvider + useConst + useSetup), matching custom-chart-web.

Public API unchanged — no XML/props changes; widget behavior is identical.

[github-actions]

AI Code Review

⚠️ Approved with suggestions — low-severity items only, safe to merge

---

What was reviewed

File	Change
packages/pluggableWidgets/image-cropper-web/package.json	Added mobx, mobx-react-lite, @mendix/widget-plugin-mobx-kit dependencies
packages/pluggableWidgets/image-cropper-web/src/components/CropArea.tsx	Import reorder only
packages/pluggableWidgets/image-cropper-web/src/components/ImageCropperContainer.tsx	Replaced React-state + ref-mirror pattern with MobX store + observer
packages/pluggableWidgets/image-cropper-web/src/stores/ImageCropperStore.ts	New MobX store absorbing state, debounce, original-image capture, and preview blob lifecycle
packages/pluggableWidgets/image-cropper-web/src/stores/__tests__/ImageCropperStore.spec.ts	New comprehensive store spec
packages/pluggableWidgets/image-cropper-web/src/hooks/useAutoApplyCrop.ts	Deleted — absorbed into store
packages/pluggableWidgets/image-cropper-web/src/hooks/useImageCropperState.ts	Deleted — absorbed into store
packages/pluggableWidgets/image-cropper-web/src/hooks/useOriginalImage.ts	Deleted — absorbed into store
packages/pluggableWidgets/image-cropper-web/src/hooks/usePreviewSrc.ts	Deleted — absorbed into store
packages/pluggableWidgets/image-cropper-web/src/hooks/__tests__/useImageCropperState.spec.ts	Deleted — replaced by store spec
packages/pluggableWidgets/image-cropper-web/src/hooks/__tests__/useOriginalImage.spec.ts	Deleted — replaced by store spec
packages/pluggableWidgets/image-cropper-web/src/hooks/__tests__/usePreviewSrc.spec.ts	Deleted — replaced by store spec

Skipped (out of scope): pnpm-lock.yaml

CI check status could not be retrieved in this environment — verify checks are green before merging.

---

Findings

⚠️ Low — PR title does not follow conventional commits

File: PR metadata
Note: AGENTS.md enforces type(scope): description conventional commits. "MobX crop store for Image Cropper" has no prefix. A title like refactor(image-cropper-web): extract MobX store for crop domain state would satisfy the format.

---

⚠️ Low — makeImageProp manual mock misses the Loading/Unavailable status guard

File: packages/pluggableWidgets/image-cropper-web/src/stores/__tests__/ImageCropperStore.spec.ts line 1244
Note: makeImageProp constructs the image prop by hand (status, setValue, setThumbnailSize, …) instead of using EditableValueBuilder from @mendix/widget-plugin-test-utils. The checklist flags this as brittle — it won't warn if the Mendix API shape changes. More concretely, the applyCrop guard image.status !== ValueStatus.Available has no test: readOnly and committedCrop undefined are covered, but a Loading or Unavailable image producing a no-op is not. Consider adding one:

it("does nothing when the image is Loading", async () => {
    const { store, gate, dispose } = makeStore();
    gate.setProps(makeProps({ image: makeImageProp({ status: ValueStatus.Loading, value: undefined }) }));
    store.markUserDragged();
    store.commitCrop(PIXEL_CROP);
    await flush();
    expect(cropImage).not.toHaveBeenCalled();
    dispose();
});

And swap makeImageProp for a builder where it fits:

import { EditableValueBuilder } from "@mendix/widget-plugin-test-utils";
const imageValue = new EditableValueBuilder<WebImage>().withValue({ uri: "http://…", name: "img.png" }).build();

---

Positives

• makeObservable type-param correctly lists private method names so TypeScript accepts the annotations on private members — not a commonly known requirement, done right.
• All post-await observable mutations in rotate and captureOriginal are wrapped in runInAction, which is the correct pattern for async MobX actions in this codebase.
• fetchGeneration token pattern is a clean and testable analog of the cancelled boolean from the old hook; the stale-fetch cancellation test covers it directly.
• FakeGate in the spec uses observable.ref + action exactly as the real GateProvider does — the store's uri reaction and aspect computed will re-track correctly in tests.
• fireImmediately: true on the uri reaction correctly handles the initial image without a separate useEffect.
• The two no-dep useEffect calls in ImageCropperContainer (gate props + deps) are intentional and correct for the mobx-kit GateProvider pattern; the comments explain why.
• Debounce abort and reaction disposal are both covered in the setup() teardown, matching the blob-revoke cleanup — no leaks left behind.