feat: add onSettleCurrent to useSpring

Author: ktsn

README.ja.md

@@ -324,7 +324,7 @@ const { style, realValue, realVelocity } = useSpring(
 </template>
 ```
 
-`useSpring` が返す値には、現在のアニメーションが完了するまで待つ `onFinishCurrent` 関数があります。この関数には、進行中のアニメーションが完了したときに呼ばれるコールバック関数を登録できます。
+`useSpring` が返す値には、現在のアニメーションが完了、もしくは、settle するまで待つ `onFinishCurrent`、`onSettleCurrent` 関数があります。この関数には、進行中のアニメーションが完了・settle したときに呼ばれるコールバック関数を登録できます。
 
 ```vue
 <script setup>
@@ -343,11 +343,16 @@ function move() {
   // 100px まで移動
   position.value = 100
 
-  // 上記の position の更新によってトリガーされたアニメーションが完了するまで待つ
+  // 上記の position の更新によってトリガーされたアニメーションが完了（duration が経過）するまで待つ
   onFinishCurrent(() => {
     // 0px まで移動
     position.value = 0
   })
+
+  // 上記の position の更新によってトリガーされたアニメーションが settle（見た目が停止）するまで待つ
+  onSettleCurrent(() => {
+    console.log('settled')
+  })
 }
 </script>
 ```

README.md

@@ -324,7 +324,7 @@ const { style, realValue, realVelocity } = useSpring(
 </template>
 ```
 
-`useSpring` provides `onFinishCurrent` function that is for waiting until the current animation is finished. You can register a callback function that will be called when an ongoing animation is finished.
+`useSpring` provides `onFinishCurrent` and `onSettleCurrent` functions for waiting until the current animation is finished or settled. You can register a callback function that will be called when an ongoing animation is finished/settled.
 
 ```vue
 <script setup>
@@ -343,11 +343,16 @@ function move() {
   // Move to 100px
   position.value = 100
 
-  // Wait for the animation is finished triggered by the above position update
+  // Wait for the animation is finished (duration passed) triggered by the above position update
   onFinishCurrent(() => {
     // Move to 0px
     position.value = 0
   })
+
+  // Wait for the animation is settled (visually stopped) triggered by the above position update
+  onSettleCurrent(() => {
+    console.log('settled')
+  })
 }
 </script>
 ```

src/core/controller.ts

@@ -33,6 +33,7 @@ export interface AnimationController<
   stop: (options?: StopOptions) => void
 
   onFinishCurrent: (fn: (data: { stopped: boolean }) => void) => void
+  onSettleCurrent: (fn: (data: { stopped: boolean }) => void) => void
 }
 
 interface ValueHistoryItem<Key extends keyof any> {
@@ -193,6 +194,20 @@ export function createAnimateController<
     })
   }
 
+  function onSettleCurrent(fn: (data: { stopped: boolean }) => void): void {
+    if (!ctx) {
+      fn({ stopped: false })
+      return
+    }
+
+    // Must store ctx to local variable because ctx in the callback of `then` can be
+    // different from when the time onFinishCurrent
+    const _ctx = ctx
+    _ctx.settlingPromise.then(() => {
+      fn({ stopped: _ctx.stoppedDuration !== undefined })
+    })
+  }
+
   return {
     get realValue() {
       if (ctx) {
@@ -220,6 +235,7 @@ export function createAnimateController<
     setStyle,
     setOptions,
     onFinishCurrent,
+    onSettleCurrent,
   }
 }
 

src/vue/use-spring.ts

@@ -27,6 +27,7 @@ export interface UseSpringResult<Values extends Record<string, number[]>> {
   realValue: DeepReadonly<Ref<Values>>
   realVelocity: DeepReadonly<Ref<Values>>
   onFinishCurrent: (fn: (data: { stopped: boolean }) => void) => void
+  onSettleCurrent: (fn: (data: { stopped: boolean }) => void) => void
 }
 
 export function useSpring<Style extends Record<string, AnimateValue>>(
@@ -64,6 +65,19 @@ export function useSpring<Style extends Record<string, AnimateValue>>(
     })
   }
 
+  function onSettleCurrent(fn: (data: { stopped: boolean }) => void): void {
+    // Wait for the next tick to ensure that input changes in the same tick
+    // triggers a new animation that is a case like:
+    //
+    // springStyle.value = { width: '100px' }
+    // onSettleCurrent(() => {
+    //   ...
+    // })
+    nextTick().then(() => {
+      controller.onSettleCurrent(fn)
+    })
+  }
+
   watch(
     [stopped, () => ({ ...input.value }), () => ({ ...optionsRef.value })],
     ([stopped, input, options], [prevStopped, prevInput]) => {
@@ -86,5 +100,6 @@ export function useSpring<Style extends Record<string, AnimateValue>>(
     realValue: readonly(realValue),
     realVelocity: readonly(realVelocity),
     onFinishCurrent,
+    onSettleCurrent,
   }
 }

test/core/controller.test.ts

@@ -235,7 +235,25 @@ describe('AnimationController', () => {
     })
   })
 
-  test('stopped == true when animation is stopped by stop()', () => {
+  test('register settle listener for the current animation', () => {
+    let style: any
+    const controller = createAnimateController((_style) => {
+      style = _style
+    })
+    controller.setOptions({ duration: 100 })
+    controller.setStyle({ width: '100px' }, { animate: false })
+    controller.setStyle({ width: '200px' })
+
+    return new Promise<void>((resolve) => {
+      controller.onSettleCurrent(({ stopped }) => {
+        expect(stopped).toBe(false)
+        expect(style.width).toBe('200px')
+        resolve()
+      })
+    })
+  })
+
+  test('stopped == true in onFinishCurrent when animation is stopped by stop()', () => {
     let style: any
     const controller = createAnimateController((_style) => {
       style = _style
@@ -254,7 +272,7 @@ describe('AnimationController', () => {
     })
   })
 
-  test('stopped == true when animation is stopped by a new animation', () => {
+  test('stopped == true in onFinishCurrent when animation is stopped by a new animation', () => {
     const controller = createAnimateController(() => {})
     controller.setOptions({ duration: 100 })
     controller.setStyle({ width: '100px' }, { animate: false })
@@ -268,4 +286,38 @@ describe('AnimationController', () => {
       controller.setStyle({ width: '300px' })
     })
   })
+
+  test('stopped == true in onSettleCurrent when animation is stopped by stop()', () => {
+    let style: any
+    const controller = createAnimateController((_style) => {
+      style = _style
+    })
+    controller.setOptions({ duration: 100 })
+    controller.setStyle({ width: '100px' }, { animate: false })
+    controller.setStyle({ width: '200px' })
+
+    return new Promise<void>((resolve) => {
+      controller.onSettleCurrent(({ stopped }) => {
+        expect(stopped).toBe(true)
+        expect(style.width).toBe(controller.realValue.width![0] + 'px')
+        resolve()
+      })
+      controller.stop()
+    })
+  })
+
+  test('stopped == true in onSettleCurrent when animation is stopped by a new animation', () => {
+    const controller = createAnimateController(() => {})
+    controller.setOptions({ duration: 100 })
+    controller.setStyle({ width: '100px' }, { animate: false })
+    controller.setStyle({ width: '200px' })
+
+    return new Promise<void>((resolve) => {
+      controller.onSettleCurrent(({ stopped }) => {
+        expect(stopped).toBe(true)
+        resolve()
+      })
+      controller.setStyle({ width: '300px' })
+    })
+  })
 })

test/vue/use-spring.test.ts

@@ -249,7 +249,29 @@ describe('useSpring', () => {
     })
   })
 
-  test('stopped == true when animation is stopped', () => {
+  test('register settle listener for the current animation', () => {
+    const value = ref(10)
+
+    const { style, onSettleCurrent } = useSpring(
+      () => ({
+        width: `${value.value}px`,
+      }),
+      {
+        duration: 100,
+      },
+    )
+
+    return new Promise<void>((resolve) => {
+      value.value = 20
+      onSettleCurrent(({ stopped }) => {
+        expect(stopped).toBe(false)
+        expect(style.value.width).toBe('20px')
+        resolve()
+      })
+    })
+  })
+
+  test('stopped == true in onFinishCurrent when animation is stopped', () => {
     const value = ref(10)
     const disabled = ref(false)
 
@@ -274,4 +296,30 @@ describe('useSpring', () => {
       })
     })
   })
+
+  test('stopped == true in onSettleCurrent when animation is stopped', () => {
+    const value = ref(10)
+    const disabled = ref(false)
+
+    const { style, realValue, onSettleCurrent } = useSpring(
+      () => ({
+        width: `${value.value}px`,
+      }),
+      () => ({
+        duration: 100,
+        disabled: disabled.value,
+      }),
+    )
+
+    value.value = 20
+
+    return new Promise<void>((resolve) => {
+      disabled.value = true
+      onSettleCurrent(({ stopped }) => {
+        expect(stopped).toBe(true)
+        expect(style.value.width).toBe(realValue.value.width[0] + 'px')
+        resolve()
+      })
+    })
+  })
 })