Progress Management (#44)

This PR includes simple progress management.

There is a new state that contains progresses of loaders, it allows
user to convert an indeterminate loader to determinate loader on its way.

Author: f

README.md

@@ -133,7 +133,7 @@ Returns boolean value if any loader exists in page.
 </template>
 ```
 
-#### `.is(loader String | Matcher)`
+#### `.is(loader String | Matcher)` or `.waiting(loader String | Matcher)`
 
 Returns boolean value if given loader exists in page.
 
@@ -143,6 +143,16 @@ Returns boolean value if given loader exists in page.
 </template>
 ```
 
+You can use **`waiting`** alias instead of **`is`**.
+
+```html
+<template>
+  <div v-if="$wait.waiting('fetching users')">
+    Fetching users...
+  </div>
+</template>
+```
+
 Also you can use matcher to make it more flexible:
 
 Please see [matcher](https://github.com/sindresorhus/matcher/) library to see how to use matchers.
@@ -153,7 +163,7 @@ Please see [matcher](https://github.com/sindresorhus/matcher/) library to see ho
 </template>
 ```
 
-#### `.is(loaders Array<String | Matcher>)`
+#### `.is(loaders Array<String | Matcher>)` or `.waiting(loaders Array<String | Matcher>)`
 
 Returns boolean value if some of given loaders exists in page.
 
@@ -183,6 +193,44 @@ Stops the given loader.
 </template>
 ```
 
+#### `.progress(loader String, current [, total = 100])`
+
+Sets the progress of the given loader.
+
+```html
+<template>
+  <progress min="0" max="100" :value="$wait.percent('downloading')" />
+  <button @click="$wait.progress('downloading', 10)">Set progress to 10</button>
+  <button @click="$wait.progress('downloading', 50)">Set progress to 50</button>
+  <button @click="$wait.progress('downloading', 50, 200)">Set progress to 50 of 200 (25%)</button>
+</template>
+```
+
+##### Completing the Progress
+
+To complete the progress, `current` value should be set bigger than `100`.
+If you `total` is given, `current` must be bigger than `total`.
+
+```html
+<button @click="$wait.progress('downloading', 101)">Set as downloaded (101 of 100)</button>
+```
+
+or
+
+```html
+<button @click="$wait.progress('downloading', 5, 6)">Set as downloaded (6 of 5)</button>
+```
+
+#### `.percent(loader String)`
+
+Returns the percentage of the given loader.
+
+```html
+<template>
+  <progress min="0" max="100" :value="$wait.percent('downloading')" />
+</template>
+```
+
 ## 🏹 Directives
 
 You can use directives to make your template cleaner.
@@ -258,6 +306,16 @@ Toggles given loader on click.
 </template>
 ```
 
+#### `v-wait:click.progress='["loader name", 80]'`
+
+Sets the progress of given loader on click.
+
+```html
+<template>
+  <button v-wait:click.progress='["downloading", 80]'>Set the "downloading" loader to 80</button>
+</template>
+```
+
 ## 🔌 Loading Action and Getter Mappers
 
 **vue-wait** provides `mapWaitingActions` and `mapWaitingGetters` mapper to be used with your Vuex stores.
@@ -316,7 +374,7 @@ actions: {
 },
 ```
 
-#### `waitFor(loader String, func Function, [,force_sync = false])`
+#### `waitFor(loader String, func Function [,forceSync = false])`
 
 Decorator that wraps function, will trigger a loading and will end loader after the original function (`func` argument) is finished.
 

dist/vue-wait.js

@@ -53,6 +53,26 @@
       </v-wait>
     </button>
     <span v-if='isIncrementing'>is incrementing...</span>
+    <hr>
+    Percentage of <code>writing code</code>: <span>{{ $l.percent('writing code') }}</span>
+    <p>
+      <label>Native Progress</label><br>
+      <progress min="0" max="100" :value='$l.percent("writing code")'></progress>
+    </p>
+    <p>
+      <label>Custom Progress</label><br>
+      <span class="progress">
+        <span class="percent" :style="`width: ${$l.percent('writing code')}%`"></span>
+      </span>
+    </p>
+    <button @click='writeCode()'>
+      Start <code>writing code</code>
+    </button>
+    <button v-wait:click.progress="['writing code', 10]">Set progress to 10</button>
+    <button v-wait:click.progress="['writing code', 50]">Set progress to 50</button>
+    <button v-wait:click.progress="['writing code', 100, 100]">Set progress to 100 of 100</button>
+    <button v-wait:click.progress="['writing code', 101]">Set progress to 101 (complete)</button>
+    <button v-wait:click.progress="['writing code', 50, 200]">Set progress to 50 of 200 (25%)</button>
   </div>
 </template>
 
@@ -67,10 +87,16 @@
         loaders: ['a', 'c', 'b', 'a', 'b', 'a', 'c', 'a', 'c', 'a', 'b']
       };
     },
+    watch: {
+      isWritingCode() {
+        if (!this.isWritingCode) clearInterval(this.timer);
+      }
+    },
     computed: {
       ...mapGetters(['count']),
       ...mapWaitingGetters({
         isIncrementing: 'incrementing count',
+        isWritingCode: 'writing code',
       }),
     },
     methods: {
@@ -79,9 +105,14 @@
       }),
       writeCode() {
         this.$l.start('writing code');
+        let i = this.$l.percent('writing code');
+        this.timer = setInterval(() => {
+          this.$l.progress('writing code', i++);
+        }, 100);
       },
       end() {
         this.$l.end('writing code');
+        clearInterval(this.timer);
       },
       toggleLoader(loader) {
         if (this.$l.is(loader)) {
@@ -125,6 +156,25 @@
     padding: 50px;
   }
 
+  .progress {
+    width: 400px;
+    height: 40px;
+    background-color: #ccc;
+    border: 1px solid #999;
+    margin: 0 auto;
+    display: inline-block;
+    position: relative;
+  }
+
+  .percent {
+    position: absolute;
+    top: 0;
+    left: 0;
+    height: 40px;
+    background-color: blue;
+    transition-duration: 600ms;
+  }
+
   button {
     border: 0;
     background-color: #fff;

examples/vuex-example/main.vue

@@ -11,6 +11,10 @@ function bind(el, binding, vNode, oldVNode) {
         el.addEventListener('click', () => instance.end(value), false);
         break;
       }
+      if (modifiers.progress) {
+        el.addEventListener('click', () => instance.progress(...value), false);
+        break;
+      }
       break;
     case 'toggle':
       el.addEventListener(

src/directives/wait.js

@@ -25,6 +25,33 @@ export function end(waitingFor, waiter) {
   return uniqArray(waitingFor).filter(l => l !== waiter);
 }
 
+export function progress(progresses, waiter, current, total = 100) {
+  if (current > total) {
+    return endProgress(progresses, waiter);
+  }
+
+  return {
+    ...progresses,
+    [waiter]: {
+      current,
+      total,
+      percent: (100 * current) / total
+    }
+  };
+}
+
+export function endProgress(progresses, waiter) {
+  const { [waiter]: omit, ...omittedProgresses } = progresses;
+  return omittedProgresses;
+}
+
+export function percent(progresses, waiter) {
+  const progress = progresses[waiter];
+  if (!progress) return 0;
+
+  return progress.percent;
+}
+
 export function nodeIsDebug() {
   return process.env.NODE_ENV !== 'production';
 }

src/utils.js

@@ -1,4 +1,13 @@
-import { is, any, start, end, nodeIsDebug } from './utils';
+import {
+  is,
+  any,
+  start,
+  end,
+  progress,
+  percent,
+  endProgress,
+  nodeIsDebug
+} from './utils';
 
 // Import to export
 import { mapWaitingActions, mapWaitingGetters, waitFor } from './helpers';
@@ -61,14 +70,17 @@ export default class VueWait {
       this.stateHandler = new Vue({
         computed: {
           is: () => waiter => store.getters[`${vuexModuleName}/is`](waiter),
-          any: () => store.getters[`${vuexModuleName}/any`]
+          any: () => store.getters[`${vuexModuleName}/any`],
+          percent: () => waiter =>
+            store.getters[`${vuexModuleName}/percent`](waiter)
         }
       });
     } else {
       this.stateHandler = new Vue({
         data() {
           return {
-            waitingFor: []
+            waitingFor: [],
+            progresses: {}
           };
         },
         computed: {
@@ -77,6 +89,9 @@ export default class VueWait {
           },
           any() {
             return any(this.waitingFor);
+          },
+          percent() {
+            return waiter => percent(this.progresses, waiter);
           }
         },
         methods: {
@@ -85,6 +100,10 @@ export default class VueWait {
           },
           end(waiter) {
             this.waitingFor = end(this.waitingFor, waiter);
+            this.progresses = endProgress(this.progresses, waiter);
+          },
+          progress({ waiter, current, total }) {
+            this.progresses = progress(this.progresses, waiter, current, total);
           }
         }
       });
@@ -101,6 +120,15 @@ export default class VueWait {
     return this.stateHandler.is(waiter);
   }
 
+  // alias for `is`
+  waiting(waiter) {
+    return this.is(waiter);
+  }
+
+  percent(waiter) {
+    return this.stateHandler.percent(waiter);
+  }
+
   dispatchWaitingAction(action, waiter) {
     const { vuexModuleName } = this.options;
     this.store.dispatch(`${vuexModuleName}/${action}`, waiter, {
@@ -123,6 +151,23 @@ export default class VueWait {
     }
     this.stateHandler.end(waiter);
   }
+
+  progress(waiter, current, total = 100) {
+    if (!this.is(waiter)) {
+      this.start(waiter);
+    }
+
+    if (current > total) {
+      this.end(waiter);
+      return;
+    }
+
+    if (this.options.useVuex) {
+      this.dispatchWaitingAction('progress', { waiter, current, total });
+      return;
+    }
+    this.stateHandler.progress({ waiter, current, total });
+  }
 }
 
 export function install(Vue) {

src/vue-wait.js

@@ -1,29 +1,37 @@
-import { is, any, start, end } from '../utils';
+import { is, any, start, end, progress, percent, endProgress } from '../utils';
 
 const mutations = {
   START: 'START',
-  END: 'END'
+  END: 'END',
+  PROGRESS: 'PROGRESS'
 };
 
 export default {
   namespaced: true,
   state: {
-    waitingFor: []
+    waitingFor: [],
+    progresses: {}
   },
   getters: {
     is: state => waiter => is(state.waitingFor, waiter),
-    any: state => any(state.waitingFor)
+    any: state => any(state.waitingFor),
+    percent: state => waiter => percent(state.progresses, waiter)
   },
   actions: {
     start: ({ commit }, waiter) => commit(mutations.START, waiter),
-    end: ({ commit }, waiter) => commit(mutations.END, waiter)
+    end: ({ commit }, waiter) => commit(mutations.END, waiter),
+    progress: ({ commit }, progress) => commit(mutations.PROGRESS, progress)
   },
   mutations: {
     [mutations.START](state, waiter) {
       state.waitingFor = start(state.waitingFor, waiter);
     },
     [mutations.END](state, waiter) {
       state.waitingFor = end(state.waitingFor, waiter);
+      state.progresses = endProgress(state.progresses, waiter);
+    },
+    [mutations.PROGRESS](state, { waiter, current, total }) {
+      state.progresses = progress(state.progresses, waiter, current, total);
     }
   }
 };