feat(useKey): Adding useKey function

Author: microcipcip

README.md

@@ -72,6 +72,8 @@ Vue.use(VueCompositionAPI)
   - [`useIntersection`](./src/functions/useIntersection/stories/useIntersection.md) — tracks intersection of target element with an ancestor element.
     [![Demo](https://img.shields.io/badge/demo-🚀-yellow.svg)](https://microcipcip.github.io/vue-use-kit/?path=/story/sensors-useintersection--demo)
     [![Demo](https://img.shields.io/badge/advanced_demo-🚀-yellow.svg)](https://microcipcip.github.io/vue-use-kit/?path=/story/sensors-useintersection--advanced-demo)
+  - [`useKey`](./src/functions/useKey/stories/useKey.md) — executes a handler when a keyboard key is used.
+    [![Demo](https://img.shields.io/badge/demo-🚀-yellow.svg)](https://microcipcip.github.io/vue-use-kit/?path=/story/sensors-usekey--demo)
   - [`useLocation`](./src/functions/useLocation/stories/useLocation.md) — tracks bar navigation location state.
     [![Demo](https://img.shields.io/badge/demo-🚀-yellow.svg)](https://microcipcip.github.io/vue-use-kit/?path=/story/sensors-uselocation--demo)
   - [`useMedia`](./src/functions/useMedia/stories/useMedia.md) — tracks state of a CSS media query.

src/functions/useKey/index.ts

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

src/functions/useKey/stories/UseKeyDemo.vue

@@ -0,0 +1,48 @@
+<template>
+  <table class="table is-fullwidth">
+    <thead>
+      <tr>
+        <th>Prop</th>
+        <th>Value</th>
+      </tr>
+    </thead>
+    <tbody>
+      <tr>
+        <td>isPressed</td>
+        <td>{{ isPressed }}</td>
+      </tr>
+      <tr>
+        <td>keyPressCount</td>
+        <td>{{ keyPressCount }}</td>
+      </tr>
+      <tr>
+        <td colspan="2">
+          <button class="button is-primary" @click="start" v-if="!isTracking">
+            Start tracking key press
+          </button>
+          <button class="button is-danger" @click="stop" v-else>
+            Stop tracking key press
+          </button>
+        </td>
+      </tr>
+    </tbody>
+  </table>
+</template>
+
+<script lang="ts">
+import Vue from 'vue'
+import { watch, ref } from '@src/api'
+import { useKey } from '@src/vue-use-kit'
+
+export default Vue.extend({
+  name: 'UseKeyDemo',
+  setup() {
+    const keyPressCount = ref(0)
+    const { isPressed, isTracking, start, stop } = useKey('g')
+
+    watch(isPressed, isPress => isPress && keyPressCount.value++)
+
+    return { keyPressCount, isPressed, isTracking, start, stop }
+  }
+})
+</script>

src/functions/useKey/stories/useKey.md

@@ -0,0 +1,23 @@
+# useKey
+
+Vue function that executes a handler when a keyboard key is used.
+
+## Reference
+
+```typescript
+// function useKey()
+```
+
+### Parameters
+
+- `value: string` lorem ipsa
+
+### Returns
+
+- `value: Ref<string>` lorem ipsa
+
+## Usage
+
+```html
+<template></template>
+```

src/functions/useKey/stories/useKey.story.ts

@@ -0,0 +1,28 @@
+import { storiesOf } from '@storybook/vue'
+import path from 'path'
+import StoryTitle from '@src/helpers/StoryTitle.vue'
+import UseKeyDemo from './UseKeyDemo.vue'
+
+const functionName = 'useKey'
+const functionPath = path.resolve(__dirname, '..')
+const notes = require(`./${functionName}.md`).default
+
+const basicDemo = () => ({
+  components: { StoryTitle, demo: UseKeyDemo },
+  template: `
+    <div class="container">
+      <story-title 
+        function-path="${functionPath}" 
+        source-name="${functionName}" 
+        demo-name="UseKeyDemo.vue"
+      >
+        <template v-slot:title></template>
+        <template v-slot:intro></template>
+      </story-title>
+      <demo />
+    </div>`
+})
+
+storiesOf('sensors|useKey', module)
+  .addParameters({ notes })
+  .add('Demo', basicDemo)

src/functions/useKey/useKey.spec.ts

@@ -0,0 +1,12 @@
+// import { mount } from '@src/helpers/test'
+// import { useKey } from '@src/vue-use-kit'
+
+afterEach(() => {
+  jest.clearAllMocks()
+})
+
+describe('useKey', () => {
+  it('should do something', () => {
+    // Add test here
+  })
+})

src/functions/useKey/useKey.ts

@@ -0,0 +1,75 @@
+import { ref, onMounted, onUnmounted, Ref } from '@src/api'
+
+export type UseKeyFilter = string | ((event: KeyboardEvent) => boolean)
+export type UseKeyCallback = (event: KeyboardEvent) => void
+
+export interface UseKeyOptions {
+  callback?: UseKeyCallback
+  triggerRef?: Ref<null | HTMLElement>
+  triggerOnce?: boolean
+}
+
+const defaultOptions = {
+  callback: () => ``,
+  triggerRef: { value: null },
+  triggerOnce: false
+}
+
+export function useKey(
+  filter: UseKeyFilter,
+  options?: UseKeyOptions,
+  runOnMount = true
+) {
+  const { callback, triggerRef, triggerOnce } = Object.assign(
+    {},
+    defaultOptions,
+    options
+  )
+  const isTracking = ref(false)
+  const isPressed = ref(false)
+
+  const getTriggerRef = (): any => triggerRef.value || document
+
+  const getFilter = () => {
+    if (typeof filter === 'function') return filter
+    return (event: KeyboardEvent) => event.key === filter
+  }
+
+  const handleKeyDown = (event: KeyboardEvent) => {
+    const filterFn = getFilter()
+    if (!filterFn(event)) return
+
+    if (triggerOnce && isPressed.value) return
+    isPressed.value = true
+    callback(event)
+  }
+
+  const handleKeyUp = (event: KeyboardEvent) => {
+    const filterFn = getFilter()
+    if (!filterFn(event)) return
+
+    isPressed.value = false
+    callback(event)
+  }
+
+  const start = () => {
+    if (isTracking.value) return
+    const $el = getTriggerRef()
+    $el.addEventListener('keydown', handleKeyDown)
+    $el.addEventListener('keyup', handleKeyUp)
+    isTracking.value = true
+  }
+
+  const stop = () => {
+    if (!isTracking.value) return
+    const $el = getTriggerRef()
+    $el.removeEventListener('keydown', handleKeyDown)
+    $el.removeEventListener('keyup', handleKeyUp)
+    isTracking.value = false
+  }
+
+  onMounted(() => runOnMount && start())
+  onUnmounted(stop)
+
+  return { isPressed, isTracking, start, stop }
+}

src/vue-use-kit.ts

@@ -8,6 +8,7 @@ export * from './functions/useGeolocation'
 export * from './functions/useHover'
 export * from './functions/useIdle'
 export * from './functions/useIntersection'
+export * from './functions/useKey'
 export * from './functions/useLocation'
 export * from './functions/useMedia'
 export * from './functions/useMediaDevices'