fix: debounce onCropComplete/onCropAreaChange during resize bursts (#653)

* fix: debounce onCropComplete/onCropAreaChange during resize bursts

Fixes #309. recomputeCropPosition() always called emitCropData()
unconditionally, and computeSizes() now runs on every ResizeObserver
tick, so dragging the window/container edge fired onCropComplete and
onCropAreaChange dozens of times during a single resize.

Resize-triggered computeSizes() calls are now flagged, and their
resulting emitCropData() call is debounced (250ms), while all other
callers (rotation/aspect/zoom/cropSize changes, media load, etc.)
keep firing immediately as before. The crop area itself still updates
visually in real time during the resize; only the completion
callbacks are debounced.

* fix: cancel pending resize debounce timer on immediate crop emit

Addresses Copilot review feedback on PR #653: if a resize burst
schedules debouncedEmitCropData() and then a non-resize completion
(e.g. drag stop, keyboard end) calls emitCropData() immediately, the
still-pending resize timer would later fire and call emitCropData()
again, causing a duplicate onCropComplete/onCropAreaChange after the
user interaction. Clearing the pending timer whenever an immediate
emit happens fixes this.

* refactor: use named param for isResizeTriggered

Per @ValentinH's review, computeSizes and recomputeCropPosition now
take { isResizeTriggered } instead of a positional boolean, so call
sites are self-documenting.

Author: HyeryongChoi

cypress/integration/basic_spec.js

@@ -70,4 +70,48 @@ describe('Basic assertions', function () {
     cy.get('#crop-area-y').should('contain', '25')
     cy.percySnapshot()
   })
+
+  it('should debounce onCropComplete during a burst of window resizes', function () {
+    // let a real frame elapse so the ResizeObserver notification for this
+    // resize has actually been delivered (mirrors cy.setViewportStable above)
+    const settle = () =>
+      cy.window().then(
+        (win) =>
+          new Cypress.Promise((resolve) => {
+            win.requestAnimationFrame(() => win.requestAnimationFrame(() => resolve()))
+          })
+      )
+    const countOnCropComplete = (spy) =>
+      spy.getCalls().filter((call) => call.args[0] === 'onCropComplete!').length
+
+    // let the initial mount settle first so its own onCropComplete call
+    // doesn't get counted as part of the resize burst below
+    settle()
+    cy.window().then((win) => {
+      cy.spy(win.console, 'log').as('consoleLog')
+    })
+    // freeze only the debounce timer itself (not rAF/Date), so ResizeObserver
+    // notifications are still delivered for real via the settle() waits below,
+    // but the resulting debounce timeout only fires when we call cy.tick
+    cy.clock(Date.now(), ['setTimeout', 'clearTimeout'])
+
+    // several resizes in a row, simulating dragging the window edge
+    cy.viewport(700, 600)
+    settle()
+    cy.viewport(800, 650)
+    settle()
+    cy.viewport(900, 700)
+    settle()
+
+    // right after the burst, onCropComplete should still be debounced (not fired yet)
+    cy.get('@consoleLog').should((spy) => {
+      expect(countOnCropComplete(spy)).to.eq(0)
+    })
+
+    // once the debounce window elapses, it should have fired exactly once for the whole burst
+    cy.tick(260)
+    cy.get('@consoleLog').should((spy) => {
+      expect(countOnCropComplete(spy)).to.eq(1)
+    })
+  })
 })

src/Cropper.tsx

@@ -15,6 +15,11 @@ import {
 } from './helpers'
 import cssStyles from './styles.css?raw'
 
+// how long to wait after the last resize-triggered size recompute before
+// firing onCropComplete/onCropAreaChange, so a window/container resize
+// doesn't spam consumers with callbacks on every frame
+const RESIZE_EMIT_DEBOUNCE_TIME = 250
+
 export type CropperProps = {
   image?: string
   video?: string | VideoSrc[]
@@ -123,6 +128,7 @@ class Cropper extends React.Component<CropperProps, State> {
   rafDragTimeout: number | null = null
   rafPinchTimeout: number | null = null
   wheelTimer: number | null = null
+  resizeEmitTimer: number | null = null
   currentDoc: Document | null = typeof document !== 'undefined' ? document : null
   currentWindow: Window | null = typeof window !== 'undefined' ? window : null
   resizeObserver: ResizeObserver | null = null
@@ -148,7 +154,7 @@ class Cropper extends React.Component<CropperProps, State> {
       this.initResizeObserver()
       // only add window resize listener if ResizeObserver is not supported. Otherwise, it would be redundant
       if (typeof window.ResizeObserver === 'undefined') {
-        this.currentWindow.addEventListener('resize', this.computeSizes)
+        this.currentWindow.addEventListener('resize', this.onWindowResize)
       }
       this.props.zoomWithScroll &&
         this.containerRef.addEventListener('wheel', this.onWheel, { passive: false })
@@ -189,9 +195,12 @@ class Cropper extends React.Component<CropperProps, State> {
   componentWillUnmount() {
     if (!this.currentDoc || !this.currentWindow) return
     if (typeof window.ResizeObserver === 'undefined') {
-      this.currentWindow.removeEventListener('resize', this.computeSizes)
+      this.currentWindow.removeEventListener('resize', this.onWindowResize)
     }
     this.resizeObserver?.disconnect()
+    if (this.resizeEmitTimer) {
+      clearTimeout(this.resizeEmitTimer)
+    }
     if (this.containerRef) {
       this.containerRef.removeEventListener('gesturestart', this.preventZoomSafari)
     }
@@ -250,11 +259,15 @@ class Cropper extends React.Component<CropperProps, State> {
         isFirstResize = false // observe() is called on mount, we don't want to trigger a recompute on mount
         return
       }
-      this.computeSizes()
+      this.computeSizes({ isResizeTriggered: true })
     })
     this.resizeObserver.observe(this.containerRef)
   }
 
+  onWindowResize = () => {
+    this.computeSizes({ isResizeTriggered: true })
+  }
+
   // this is to prevent Safari on iOS >= 10 to zoom the page
   preventZoomSafari = (e: Event) => e.preventDefault()
 
@@ -348,7 +361,7 @@ class Cropper extends React.Component<CropperProps, State> {
     return this.props.objectFit
   }
 
-  computeSizes = () => {
+  computeSizes = ({ isResizeTriggered = false }: { isResizeTriggered?: boolean } = {}) => {
     const mediaRef = this.imageRef.current || this.videoRef.current
 
     if (mediaRef && this.containerRef) {
@@ -435,7 +448,7 @@ class Cropper extends React.Component<CropperProps, State> {
         this.props.onCropSizeChange && this.props.onCropSizeChange(cropSize)
       }
 
-      this.setState({ cropSize }, this.recomputeCropPosition)
+      this.setState({ cropSize }, () => this.recomputeCropPosition({ isResizeTriggered }))
 
       // pass crop size to parent
       if (this.props.setCropSize) {
@@ -705,6 +718,11 @@ class Cropper extends React.Component<CropperProps, State> {
   }
 
   emitCropData = () => {
+    if (this.resizeEmitTimer) {
+      clearTimeout(this.resizeEmitTimer)
+      this.resizeEmitTimer = null
+    }
+
     const cropData = this.getCropData()
     if (!cropData) return
 
@@ -728,7 +746,7 @@ class Cropper extends React.Component<CropperProps, State> {
     }
   }
 
-  recomputeCropPosition = () => {
+  recomputeCropPosition = ({ isResizeTriggered = false }: { isResizeTriggered?: boolean } = {}) => {
     if (!this.state.cropSize) return
 
     let adjustedCrop = this.props.crop
@@ -763,7 +781,24 @@ class Cropper extends React.Component<CropperProps, State> {
     this.previousCropSize = this.state.cropSize
 
     this.props.onCropChange(newPosition)
-    this.emitCropData()
+    if (isResizeTriggered) {
+      this.debouncedEmitCropData()
+    } else {
+      this.emitCropData()
+    }
+  }
+
+  // Same as emitCropData but debounced, so that a burst of resize-triggered
+  // recomputations (e.g. dragging the window edge) only fires
+  // onCropComplete/onCropAreaChange once, after the resize settles.
+  debouncedEmitCropData = () => {
+    if (!this.currentWindow) return
+    if (this.resizeEmitTimer) {
+      clearTimeout(this.resizeEmitTimer)
+    }
+    this.resizeEmitTimer = this.currentWindow.setTimeout(() => {
+      this.emitCropData()
+    }, RESIZE_EMIT_DEBOUNCE_TIME)
   }
 
   onKeyDown = (event: React.KeyboardEvent<HTMLDivElement>) => {