feat(useTransition): transitions and onStarted/onFinished callbacks (vueuse#268)

Author: scottbedard

packages/core/useTransition/index.md

@@ -64,3 +64,18 @@ useTransition(baseNumber, {
   transition: easeOutElastic,
 })
 ```
+
+To choreograph behavior around a transition, define `onStarted` or `onFinished` callbacks.
+
+```js
+useTransition(baseNumber, {
+  duration: 1000,
+  transition: easeOutElastic,
+  onStarted() {
+    // called after the transition starts
+  },
+  onFinished() {
+    // called after the transition ends
+  },
+})
+```

packages/core/useTransition/index.test.ts

@@ -86,6 +86,41 @@ describe('useTransition', () => {
     expect(vm.transitionedValue).toBe(1)
   })
 
+  it('supports dynamic transitions', async() => {
+    const linear = jest.fn(n => n)
+    const easeInQuad = jest.fn(n => n * n)
+    const vm = useSetup(() => {
+      const baseValue = ref(0)
+      const transition = ref(linear)
+
+      const transitionedValue = useTransition(baseValue, {
+        duration: 100,
+        transition,
+      })
+
+      return {
+        baseValue,
+        transition,
+        transitionedValue,
+      }
+    })
+
+    expect(linear).not.toHaveBeenCalled()
+    expect(easeInQuad).not.toHaveBeenCalled()
+
+    vm.baseValue++
+    await vm.$nextTick()
+
+    expect(linear).toHaveBeenCalled()
+    expect(easeInQuad).not.toHaveBeenCalled()
+
+    vm.transition = easeInQuad
+    vm.baseValue++
+    await vm.$nextTick()
+
+    expect(easeInQuad).toHaveBeenCalled()
+  })
+
   it('support dynamic transition durations', async() => {
     const vm = useSetup(() => {
       const baseValue = ref(0)
@@ -119,4 +154,38 @@ describe('useTransition', () => {
     await promiseTimeout(100)
     expect(vm.transitionedValue).toBe(2)
   })
+
+  it('calls onStarted and onFinished callbacks', async() => {
+    const onStarted = jest.fn()
+    const onFinished = jest.fn()
+
+    const vm = useSetup(() => {
+      const baseValue = ref(0)
+
+      const transitionedValue = useTransition(baseValue, {
+        duration: 100,
+        onFinished,
+        onStarted,
+        transition: n => n,
+      })
+
+      return {
+        baseValue,
+        transitionedValue,
+      }
+    })
+
+    expect(onStarted).not.toHaveBeenCalled()
+    expect(onFinished).not.toHaveBeenCalled()
+
+    vm.baseValue = 1
+    await vm.$nextTick()
+
+    expect(onStarted).toHaveBeenCalled()
+    expect(onFinished).not.toHaveBeenCalled()
+
+    await promiseTimeout(150)
+    expect(onStarted.mock.calls.length).toBe(1)
+    expect(onFinished.mock.calls.length).toBe(1)
+  })
 })

packages/core/useTransition/index.ts

@@ -1,14 +1,25 @@
 import { useRafFn } from '../useRafFn'
-import { Ref, ref, unref, watch } from 'vue-demi'
-import { clamp, isFunction, MaybeRef } from '@vueuse/shared'
+import { computed, Ref, ref, unref, watch } from 'vue-demi'
+import { clamp, isFunction, MaybeRef, noop } from '@vueuse/shared'
 
+/**
+ * Cubic bezier points
+ */
 type CubicBezierPoints = [number, number, number, number]
 
-type EasingFunction = (x: number) => number
+/**
+ * Easing function
+ */
+type EasingFunction = (n: number) => number
 
+/**
+ * Transition options
+ */
 interface TransitionOptions {
   duration?: MaybeRef<number>
-  transition?: EasingFunction | CubicBezierPoints
+  onFinished?: () => unknown
+  onStarted?: () => unknown
+  transition?: MaybeRef<EasingFunction | CubicBezierPoints>
 }
 
 /**
@@ -81,14 +92,17 @@ export const TransitionPresets: Record<string, CubicBezierPoints> = {
 export function useTransition(source: Ref<number>, options: TransitionOptions = {}) {
   const {
     duration = 500,
+    onFinished = noop,
+    onStarted = noop,
     transition = (n: number) => n,
   } = options
 
   const output = ref(source.value)
 
-  const getValue = isFunction<EasingFunction>(transition)
-    ? transition
-    : createEasingFunction(transition)
+  const currentTransition = computed(() => {
+    const t = unref(transition)
+    return isFunction(t) ? t : createEasingFunction(t)
+  })
 
   let currentDuration = 0
   let diff = 0
@@ -100,10 +114,12 @@ export function useTransition(source: Ref<number>, options: TransitionOptions =
     const now = Date.now()
     const progress = clamp(1 - ((endAt - now) / currentDuration), 0, 1)
 
-    output.value = startValue + (diff * getValue(progress))
+    output.value = startValue + (diff * currentTransition.value(progress))
 
-    if (progress >= 1)
+    if (progress >= 1) {
       pause()
+      onFinished()
+    }
   }, { immediate: false })
 
   watch(source, () => {
@@ -116,6 +132,7 @@ export function useTransition(source: Ref<number>, options: TransitionOptions =
     endAt = startAt + currentDuration
 
     resume()
+    onStarted()
   })
 
   return output

packages/shared/utils/is.ts

@@ -5,7 +5,7 @@ export const assert = (condition: boolean, ...infos: any[]) => {
 }
 const toString = Object.prototype.toString
 export const isBoolean = (val: any): val is boolean => typeof val === 'boolean'
-export const isFunction = <T = Function> (val: any): val is T => typeof val === 'function'
+export const isFunction = <T extends Function> (val: any): val is T => typeof val === 'function'
 export const isNumber = (val: any): val is number => typeof val === 'number'
 export const isString = (val: unknown): val is string => typeof val === 'string'
 export const isObject = (val: any): val is object =>