Skip to content

Commit e2fd7f7

Browse files
microcipcipmicrocipcip
committed
docs: Improve documentation and standarize variable names
1 parent bd4933b commit e2fd7f7

File tree

7 files changed

+154
-61
lines changed

7 files changed

+154
-61
lines changed

‎src/components/useHover/stories/useHover.story.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ const basicDemo = () => ({
1414
<story-title function-path="${functionPath}" source-name="${functionName}" demo-name="UseHoverDemo.vue">
1515
<template v-slot:title></template>
1616
<template v-slot:intro>
17-
Try to move the mouse hover the box below to see the emoji change of expression.
17+
<strong> Try to move the mouse hover the box below</strong> to see the emoji change of expression.
1818
</template>
1919
</story-title>
2020
<demo />

‎src/components/useMouse/stories/UseMouseDemo.vue‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,6 @@
2525

2626
<script lang="ts">
2727
import Vue from 'vue'
28-
import { ref } from '../../../api'
2928
import { useMouse } from '../../../vue-use-kit'
3029
3130
const toInt = (n: number) => Math.round(n)

‎src/components/useRafFn/stories/UseRafFnDemo.vue‎

Lines changed: 79 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -1,43 +1,57 @@
11
<template>
2-
<table class="table is-fullwidth">
3-
<thead>
4-
<tr>
5-
<th>Prop</th>
6-
<th>Description</th>
7-
<th>Value</th>
8-
</tr>
9-
</thead>
10-
<tbody>
11-
<tr>
12-
<td>callbackCounter</td>
13-
<td>Raf callback counter</td>
14-
<td>
15-
<span>{{ callbackCounter }}</span>
16-
</td>
17-
</tr>
18-
<tr>
19-
<td>animDuration</td>
20-
<td>Raf callback counter</td>
21-
<td>
22-
<span>{{ animDuration }}s</span>
23-
</td>
24-
</tr>
25-
<tr>
26-
<td colspan="2">
27-
<button class="button is-primary" @click="start" v-if="!isRunning">
28-
Resume animation
29-
</button>
30-
<button class="button is-danger" @click="stop" v-else>
31-
Stop animation
32-
</button>
33-
<br />
34-
<br />
35-
<br />
36-
<input type="number" min="1" max="121" v-model="fpsRef" />
37-
</td>
38-
</tr>
39-
</tbody>
40-
</table>
2+
<div>
3+
<table class="table is-fullwidth">
4+
<thead>
5+
<tr>
6+
<th>Prop</th>
7+
<th>Description</th>
8+
<th>Value</th>
9+
</tr>
10+
</thead>
11+
<tbody>
12+
<tr>
13+
<td>callbackCounter</td>
14+
<td>
15+
Counter showing how many times the callback was called within the
16+
Raf loop
17+
</td>
18+
<td>
19+
<span>{{ callbackCounter }}</span>
20+
</td>
21+
</tr>
22+
<tr>
23+
<td>timeElapsed</td>
24+
<td>Total time elapsed</td>
25+
<td>
26+
<span>{{ timeElapsed }}ms</span>
27+
</td>
28+
</tr>
29+
</tbody>
30+
</table>
31+
<div class="form">
32+
<div class="field">
33+
<label class="label">Frames per second (fps)</label>
34+
<div class="control">
35+
<input class="input" type="number" min="1" max="121" v-model="fps" />
36+
</div>
37+
</div>
38+
<div class="field">
39+
<button
40+
class="button is-primary"
41+
@click="
42+
start()
43+
init()
44+
"
45+
v-if="!isRunning"
46+
>
47+
{{ isInit ? 'Resume timer' : 'Start timer' }}
48+
</button>
49+
<button class="button is-danger" @click="stop" v-else>
50+
Stop timer
51+
</button>
52+
</div>
53+
</div>
54+
</div>
4155
</template>
4256

4357
<script lang="ts">
@@ -48,16 +62,37 @@ import { useRafFn } from '../../../vue-use-kit'
4862
export default Vue.extend({
4963
name: 'UseRafFnDemo',
5064
setup() {
51-
const animDuration = ref(0)
65+
const isInit = ref(false)
66+
const timeElapsed = ref(0)
5267
const callbackCounter = ref(0)
53-
const fpsRef = ref(120)
68+
const fps = ref(120)
5469
const animHandler = (t: number) => {
5570
callbackCounter.value = callbackCounter.value + 1
56-
animDuration.value = Math.ceil(t)
71+
timeElapsed.value = Math.ceil(t)
5772
}
5873
59-
const { isRunning, start, stop } = useRafFn(animHandler, fpsRef, false)
60-
return { isRunning, start, stop, callbackCounter, animDuration, fpsRef }
74+
const init = () => {
75+
isInit.value = true
76+
}
77+
78+
const { isRunning, start, stop } = useRafFn(animHandler, fps, false)
79+
80+
return {
81+
init,
82+
isInit,
83+
isRunning,
84+
start,
85+
stop,
86+
callbackCounter,
87+
timeElapsed,
88+
fps
89+
}
6190
}
6291
})
6392
</script>
93+
94+
<style>
95+
.form {
96+
max-width: 400px;
97+
}
98+
</style>

‎src/components/useRafFn/stories/useRafFn.md‎

Lines changed: 59 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,77 @@
11
# useRafFn
22

3-
Vue function that...
3+
Vue function that calls given callback inside the RAF loop.
4+
5+
You can optionally specify how many times the callback should
6+
run in a second by specifying the `fps` value.
47

58
## Reference
69

710
```typescript
8-
// useRafFn()
11+
type TFps = number | Ref<number>;
12+
13+
useRafFn(
14+
callback: Function,
15+
fps?: TFps,
16+
runOnMount?: boolean
17+
): {
18+
isRunning: Ref<boolean>;
19+
start: () => void;
20+
stop: () => void;
21+
}
922
```
1023

1124
### Parameters
1225

13-
- `value: string` lorem ipsa
26+
- `callback: Function` the function to call inside the Raf loop
27+
- `fps: number | Ref<number>` the amount of times per second that the callback should run.
28+
Please note that when a value greater than `120` is defined, the `fps` logic will be skipped completely
29+
therefore the callback will run at full speed. By default the value is set to `121` so it will indeed
30+
run at full speed
31+
- `runOnMount: boolean` whether to run the Raf loop on mount, `true` by default.
32+
If `false`, you'll have to start the Raf with the `start` function
1433

1534
### Returns
1635

17-
- `value: string` lorem ipsa
36+
- `isRunning: boolean` the Raf status
37+
- `false` when the Raf loop is paused
38+
- `true` when the Raf loop is running
39+
- `start: Function` the function used for starting the Raf loop
40+
- `stop: Function` the function used for stopping the Raf loop
1841

1942
## Usage
2043

2144
```html
22-
<template></template>
45+
<template>
46+
<div>
47+
<div>Elapsed: {{ timeElapsed }}</div>
48+
<div><button @click="start">Start loop</button></div>
49+
<div><button @click="stop">Stop loop</button></div>
50+
</div>
51+
</template>
52+
53+
<script lang="ts">
54+
import Vue from 'vue'
55+
import { ref } from '../../../api'
56+
import { useRafFn } from 'vue-use-kit'
57+
58+
export default Vue.extend({
59+
name: 'UseRafFnDemo',
60+
setup() {
61+
const fps = 60
62+
const timeElapsed = ref(0)
63+
const animHandler = timeElapsed => {
64+
timeElapsed.value = Math.ceil(timeElapsed)
65+
}
66+
67+
const { start, stop } = useRafFn(animHandler, fps)
68+
69+
return {
70+
start,
71+
stop,
72+
timeElapsed
73+
}
74+
}
75+
})
76+
</script>
2377
```

‎src/components/useRafFn/stories/useRafFn.story.ts‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,12 @@ const basicDemo = () => ({
1313
<div class="container">
1414
<story-title function-path="${functionPath}" source-name="${functionName}" demo-name="UseRafFnDemo.vue">
1515
<template v-slot:title></template>
16-
<template v-slot:intro></template>
16+
<template v-slot:intro>
17+
<p>
18+
<strong>Click the button below</strong> to start the Raf loop. <strong>Change the fps value</strong>
19+
in the input below to see the animation speed change on the fly.
20+
</p>
21+
</template>
1722
</story-title>
1823
<demo />
1924
</div>`

‎src/components/useRafFn/useRafFn.ts‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -13,10 +13,10 @@ export function useRafFn(
1313
fps: TFps = fpsLimit + 1,
1414
runOnMount = true
1515
) {
16-
const isRunningRef = ref(false)
16+
const isRunning = ref(false)
1717
// Using a computed here allows us to update fps
1818
// dynamically from user's input
19-
const fpsIntervalRef = computed(() => calcFpsInterval(getFps(fps)))
19+
const fpsInterval = computed(() => calcFpsInterval(getFps(fps)))
2020

2121
let isPausedGuard = false
2222
let startTime = 0
@@ -25,7 +25,7 @@ export function useRafFn(
2525
let timeDelta = 0
2626
const loop = (timeStamp: number) => {
2727
if (!startTime) startTime = timeStamp
28-
if (!isRunningRef.value) return
28+
if (!isRunning.value) return
2929

3030
if (isPausedGuard) {
3131
// Save the time when we pause the loop so that later we can
@@ -49,7 +49,7 @@ export function useRafFn(
4949
// and the given fps matches the lapsed time
5050
if (!callbackShouldAlwaysRun) {
5151
const elapsedTime = Math.ceil(timeNow - timeDelta)
52-
if (elapsedTime > fpsIntervalRef.value) {
52+
if (elapsedTime > fpsInterval.value) {
5353
// Store timeDelta for future computations
5454
timeDelta = timeNow
5555
callback(timeNow)
@@ -61,20 +61,20 @@ export function useRafFn(
6161
}
6262

6363
const start = () => {
64-
isRunningRef.value = true
64+
isRunning.value = true
6565
requestAnimationFrame(loop)
6666
}
6767

6868
const stop = () => {
69-
isRunningRef.value = false
69+
isRunning.value = false
7070
isPausedGuard = true
7171
}
7272

7373
onMounted(() => runOnMount && start())
7474
onUnmounted(stop)
7575

7676
return {
77-
isRunning: isRunningRef,
77+
isRunning,
7878
start,
7979
stop
8080
}

‎src/helpers/StoryTitle.vue‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
11
<template>
22
<div>
33
<div class="columns">
4-
<div class="column is-four-fifths">
4+
<div class="column is-three-fifths">
55
<h1 class="title"><slot name="title">Demo</slot></h1>
66
</div>
7-
<div class="column is-one-fifth story-link" v-if="demoName || sourceName">
7+
<div class="column is-two-fifth story-link" v-if="demoName || sourceName">
88
<a :href="demoUrl" target="_blank" v-if="demoName">
99
Demo
1010
<span class="icon is-small story-ico"

0 commit comments

Comments
 (0)