feat: Added useTimeout function

Author: microcipcip

src/components/useTimeout/index.ts

@@ -0,0 +1 @@
+export * from './useTimeout'

src/components/useTimeout/stories/UseTimeoutDemo.vue

@@ -0,0 +1,60 @@
+<template>
+  <table class="table is-fullwidth">
+    <thead>
+      <tr>
+        <th>Prop</th>
+        <th>Value</th>
+      </tr>
+    </thead>
+    <tbody>
+      <tr>
+        <td>timerStatus</td>
+        <td>
+          <span>{{ timerStatus }}</span>
+        </td>
+      </tr>
+      <tr>
+        <td colspan="3">
+          <button
+            class="button is-primary"
+            @click="resetTimer"
+            v-text="btnResetMsg"
+          />
+          <button class="button is-danger" @click="cancelTimer">
+            Cancel Timer
+          </button>
+        </td>
+      </tr>
+    </tbody>
+  </table>
+</template>
+
+<script lang="ts">
+import Vue from 'vue'
+import { computed, ref } from '../../../api'
+import { useTimeout } from '../../../vue-use-kit'
+
+export default Vue.extend({
+  name: 'UseTimeoutDemo',
+  setup() {
+    const timerDuration = 3000
+    const { isReady, isIdle, cancelTimer, resetTimer } = useTimeout(
+      timerDuration,
+      false
+    )
+
+    const btnResetMsg = computed(() => {
+      return isIdle.value ? 'Start timer' : 'Reset Timer'
+    })
+
+    const timerStatus = computed(() => {
+      if (isIdle.value) return 'Idle'
+      if (isReady.value === false) return 'Pending...'
+      if (isReady.value === null) return 'Cancelled'
+      return 'Completed'
+    })
+
+    return { btnResetMsg, timerStatus, cancelTimer, resetTimer }
+  }
+})
+</script>

src/components/useTimeout/stories/useTimeout.md

@@ -0,0 +1,59 @@
+# useTimeout
+
+Vue function that returns `isReady` value as `true` after a specified `ms` amount of time.
+
+## Reference
+
+```typescript
+useTimeout(
+    ms?: number,
+    runOnMount?: boolean
+): {
+    isReady: Ref<boolean | null>;
+    isIdle: Ref<boolean>;
+    cancelTimer: () => void;
+    resetTimer: () => void;
+}
+```
+
+### Parameters
+
+- `ms: number` how many milliseconds to wait before the timer is completed
+- `runOnMount: boolean` whether to run the timeout on mount, `true` by default
+
+### Returns
+
+- `isReady: boolean | null` the timer status
+  - `false` when the timer is executing 
+  - `true` when the timer is completed
+  - `null` when the timer is cancelled
+- `isIdle: boolean` this value is `true` if the timer has ever been called, `false` otherwise
+- `cancelTimer: Function` the function used to cancel the timer
+- `resetTimer: Function` the function used for resetting the timer
+
+## Usage
+
+```html
+<template>
+  <div>
+    <p>Timer status: {{ isReady ? 'Called!' : 'Pending...' }}</p>
+
+    <button @click="resetTimer">Reset Timer</button>
+    <button @click="cancelTimer">Cancel Timer</button>
+  </div>
+</template>
+
+<script lang="ts">
+  import Vue from 'vue'
+  import { useTimeout } from 'vue-use-kit'
+
+  export default Vue.extend({
+    name: 'UseTimeoutDemo',
+    setup() {
+      const timerDuration = 3000
+      const { isReady, cancelTimer, resetTimer } = useTimeout(timerDuration)
+      return { isReady, cancelTimer, resetTimer }
+    }
+  })
+</script>
+```

src/components/useTimeout/stories/useTimeout.story.ts

@@ -0,0 +1,22 @@
+import { storiesOf } from '@storybook/vue'
+import StoryTitle from '../../../helpers/StoryTitle.vue'
+import UseTimeoutDemo from './UseTimeoutDemo.vue'
+
+const storiesPath = __dirname
+const notes = require('./useTimeout.md').default
+
+const basicDemo = () => ({
+  components: { StoryTitle, demo: UseTimeoutDemo },
+  template: `
+    <div class="container">
+      <story-title stories-path="${storiesPath}" file-name="UseTimeoutDemo.vue">
+        <template v-slot:title></template>
+        <template v-slot:intro></template>
+      </story-title>
+      <demo />
+    </div>`
+})
+
+storiesOf('animations|useTimeout', module)
+  .addParameters({ notes })
+  .add('Demo', basicDemo)

src/components/useTimeout/useTimeout.spec.ts

@@ -0,0 +1,35 @@
+import { mount } from '../../helpers/test'
+import { useTimeout } from '../../vue-use-kit'
+
+beforeEach(() => {
+  jest.useFakeTimers()
+})
+
+afterEach(() => {
+  jest.clearAllTimers()
+})
+
+const testComponent = () => ({
+  template: `
+    <div>
+      <div id="isIdle" v-if="isIdle"></div>
+      <div id="isReady" v-if="isReady"></div>
+    </div>
+  `,
+  setup() {
+    const { isReady, isIdle } = useTimeout(1000)
+    return { isReady, isIdle }
+  }
+})
+
+describe('useTimeout', () => {
+  it('should display #isReady when the timers are called, but not #isIdle', async () => {
+    const wrapper = mount(testComponent())
+    jest.runAllTimers()
+
+    // Wait for Vue to append #isReady in the DOM
+    await wrapper.vm.$nextTick()
+    expect(wrapper.find('#isReady').exists()).toBe(true)
+    expect(wrapper.find('#isIdle').exists()).toBe(false)
+  })
+})

src/components/useTimeout/useTimeout.ts

@@ -0,0 +1,11 @@
+import { useTimeoutFn } from '../../vue-use-kit'
+
+const noop = () => null
+export function useTimeout(ms = 0, runOnMount = true) {
+  const { isReady, isIdle, cancelTimer, resetTimer } = useTimeoutFn(
+    noop,
+    ms,
+    runOnMount
+  )
+  return { isReady, isIdle, cancelTimer, resetTimer }
+}

src/components/useTimeoutFn/stories/UseTimeoutFnDemo.vue

@@ -3,35 +3,33 @@
     <thead>
       <tr>
         <th>Prop</th>
-        <th>Description</th>
-        <th>Message</th>
+        <th>Value</th>
       </tr>
     </thead>
     <tbody>
       <tr>
-        <td>isReadyStatus</td>
-        <td>Timeout status</td>
+        <td>timerStatus</td>
         <td>
-          <span>{{ isReadyStatus }}</span>
+          <span>{{ timerStatus }}</span>
         </td>
       </tr>
       <tr>
-        <td>timerFnMsg</td>
-        <td>Timer function callback message</td>
+        <td>timerCallbackMsg</td>
         <td>
-          <span>{{ timerFnMsg }}</span>
+          <span>{{ timerCallbackMsg }}</span>
         </td>
       </tr>
       <tr>
-        <td>
-          <button class="button is-primary" @click="resetTimer">
-            Reset Timer
-          </button>
+        <td colspan="3">
+          <button
+            class="button is-primary"
+            @click="resetTimer"
+            v-text="btnResetMsg"
+          />
           <button class="button is-danger" @click="cancelTimer">
             Cancel Timer
           </button>
         </td>
-        <td></td>
       </tr>
     </tbody>
   </table>
@@ -45,28 +43,40 @@ import { useTimeoutFn } from '../../../vue-use-kit'
 export default Vue.extend({
   name: 'UseTimeoutFnDemo',
   setup() {
-    const timerFnMsg = ref('Timer not completed')
+    const timerCallbackMsg = ref('Timer not completed')
     const timerDuration = 3000
     const timerHandler = () => {
-      timerFnMsg.value = 'Timer completed!'
+      timerCallbackMsg.value = 'Timer completed!'
     }
-    const { isReady, cancelTimer, resetTimer } = useTimeoutFn(
+    const { isReady, isIdle, cancelTimer, resetTimer } = useTimeoutFn(
       timerHandler,
-      timerDuration
+      timerDuration,
+      false
     )
 
-    const isReadyStatus = computed(() => {
+    const btnResetMsg = computed(() => {
+      return isIdle.value ? 'Start timer' : 'Reset Timer'
+    })
+
+    const timerStatus = computed(() => {
+      if (isIdle.value) return 'Idle'
       if (isReady.value === false) return 'Pending...'
       if (isReady.value === null) return 'Cancelled'
-      return 'Called!'
+      return 'Completed'
     })
 
     watch(isReady, newVal => {
-      if (newVal === false) timerFnMsg.value = 'Timer not completed'
-      if (newVal === null) timerFnMsg.value = 'Timer cancelled!'
+      if (newVal === false) timerCallbackMsg.value = 'Timer not completed'
+      if (newVal === null) timerCallbackMsg.value = 'Timer cancelled!'
     })
 
-    return { timerFnMsg, isReadyStatus, cancelTimer, resetTimer }
+    return {
+      timerCallbackMsg,
+      btnResetMsg,
+      timerStatus,
+      cancelTimer,
+      resetTimer
+    }
   }
 })
 </script>

src/components/useTimeoutFn/stories/useTimeoutFn.md

@@ -1,15 +1,17 @@
 # useTimeoutFn
 
-Vue function that calls given callback function after a specified amount of milliseconds.
+Vue function that calls given callback function after a specified `ms` amount of time.
 
 ## Reference
 
 ```typescript
 useTimeoutFn(
     callback: Function,
-    ms?: number
+    ms?: number,
+    runOnMount?: boolean
 ): {
     isReady: Ref<boolean | null>;
+    isIdle: Ref<boolean>;
     cancelTimer: () => void;
     resetTimer: () => void;
 }
@@ -19,19 +21,24 @@ useTimeoutFn(
 
 - `callback: Function` the function to call when the timer finishes
 - `ms: number` how many milliseconds to wait before running the callback function
+- `runOnMount: boolean` whether to run the timeout on mount, `true` by default
 
 ### Returns
 
 - `isReady: boolean | null` the timer status
-- `cancelTimer: Function` the function used for canceling the timer
+  - `false` when the timer is executing 
+  - `true` when the timer is completed
+  - `null` when the timer is cancelled
+- `isIdle: boolean` this value is `true` if the timer has ever been called, `false` otherwise
+- `cancelTimer: Function` the function used to cancel the timer
 - `resetTimer: Function` the function used for resetting the timer
 
 ## Usage
 
 ```html
 <template>
   <div>
-    <p>Timeout status: {{ isReady ? 'Called!' : 'Pending...' }}</p>
+    <p>Timer status: {{ isReady ? 'Called!' : 'Pending...' }}</p>
     <p>Timeout Callback msg: {{ timerFnMsg }}</p>
 
     <button @click="resetTimer">Reset Timer</button>