fix(useCountdown): start() should accept a custom initial value (#4554)

Author: ralacerda

packages/core/useCountdown/index.md

@@ -21,3 +21,27 @@ const { remaining, start, stop, pause, resume } = useCountdown(countdownSeconds,
   }
 })
 ```
+
+You can use a `ref` to change the initial countdown.
+`start()` and `resume()` also accept a new countdown value for the next countdown.
+
+```js
+import { ref } from 'vue'
+import { useCountdown } from '@vueuse/core'
+
+const countdown = ref(5)
+const { start, reset } = useCountdown(countdown, {
+})
+
+// change the countdown value
+countdown.value = 10
+
+// start a new countdown with 2 seconds
+start(2)
+
+// reset the countdown to 4, but do not start it
+reset(4)
+
+// start the countdown with the current value of `countdown`
+start()
+```

packages/core/useCountdown/index.test.ts

@@ -1,7 +1,7 @@
 import type { Pausable } from '@vueuse/shared'
 import type { UseCountdownOptions } from '.'
 import { beforeEach, describe, expect, it, vi } from 'vitest'
-import { effectScope } from 'vue'
+import { effectScope, ref } from 'vue'
 import { useCountdown } from '.'
 
 describe('useCountdown', () => {
@@ -110,4 +110,36 @@ describe('useCountdown', () => {
     vi.advanceTimersByTime(60)
     expect(tickCallback).toHaveBeenCalledTimes(0)
   })
+
+  it('initial interval can be changed', async () => {
+    const countdown = ref(3)
+
+    const { start } = useCountdown(countdown, { ...options, immediate: false })
+
+    countdown.value = 2
+    start()
+    vi.advanceTimersByTime(210)
+    expect(completeCallback).toHaveBeenCalledTimes(1)
+  })
+
+  it('start can provide a custom interval', async () => {
+    const { start, reset } = useCountdown(countdown, options)
+    vi.advanceTimersByTime(countdown * interval + 10)
+    expect(completeCallback).toHaveBeenCalledTimes(1)
+
+    start(1)
+    vi.advanceTimersByTime(110)
+    expect(completeCallback).toHaveBeenCalledTimes(2)
+
+    start()
+    vi.advanceTimersByTime(110)
+    expect(completeCallback).toHaveBeenCalledTimes(2)
+    vi.advanceTimersByTime(countdown * interval + 10)
+    expect(completeCallback).toHaveBeenCalledTimes(3)
+
+    start(1)
+    reset()
+    vi.advanceTimersByTime(110)
+    expect(completeCallback).toHaveBeenCalledTimes(3)
+  })
 })

packages/core/useCountdown/index.ts

@@ -32,15 +32,15 @@ export interface UseCountdownReturn extends Pausable {
   /**
    * Resets the countdown and repeatsLeft to their initial values.
    */
-  reset: () => void
+  reset: (countdown?: MaybeRefOrGetter<number>) => void
   /**
    * Stops the countdown and resets its state.
    */
   stop: () => void
   /**
    * Reset the countdown and start it again.
    */
-  start: (initialCountdown?: MaybeRefOrGetter<number>) => void
+  start: (countdown?: MaybeRefOrGetter<number>) => void
 }
 
 /**
@@ -64,8 +64,8 @@ export function useCountdown(initialCountdown: MaybeRefOrGetter<number>, options
     }
   }, options?.interval ?? 1000, { immediate: options?.immediate ?? false })
 
-  const reset = () => {
-    remaining.value = toValue(initialCountdown)
+  const reset = (countdown?: MaybeRefOrGetter<number>) => {
+    remaining.value = toValue(countdown) ?? toValue(initialCountdown)
   }
 
   const stop = () => {
@@ -81,8 +81,8 @@ export function useCountdown(initialCountdown: MaybeRefOrGetter<number>, options
     }
   }
 
-  const start = () => {
-    reset()
+  const start = (countdown?: MaybeRefOrGetter<number>) => {
+    reset(countdown)
     intervalController.resume()
   }