feat(usePointer): new function (vitest-dev#728)

README.md

@@ -7,7 +7,7 @@ Collection of essential Vue Composition Utilities
 <a href="https://www.npmjs.com/package/@vueuse/core" target="__blank"><img src="https://img.shields.io/npm/v/@vueuse/core?color=a1b858&label=" alt="NPM version"></a>
 <a href="https://www.npmjs.com/package/@vueuse/core" target="__blank"><img alt="NPM Downloads" src="https://img.shields.io/npm/dm/@vueuse/core?color=50a36f&label="></a>
 <a href="https://vueuse.org" target="__blank"><img src="https://img.shields.io/static/v1?label=&message=docs%20%26%20demos&color=1e8a7a" alt="Docs & Demos"></a>
-<img alt="Function Count" src="https://img.shields.io/badge/-140%20functions-13708a">
+<img alt="Function Count" src="https://img.shields.io/badge/-141%20functions-13708a">
 <br>
 <a href="https://github.com/vueuse/vueuse" target="__blank"><img alt="GitHub stars" src="https://img.shields.io/github/stars/vueuse/vueuse?style=social"></a>
 </p>

indexes.json

@@ -792,6 +792,14 @@
       "category": "Browser",
       "description": "reactive [Permissions API](https://developer.mozilla.org/en-US/docs/Web/API/Permissions_API)"
     },
+    {
+      "name": "usePointer",
+      "package": "core",
+      "component": true,
+      "docs": "https://vueuse.org/core/usePointer/",
+      "category": "Sensors",
+      "description": "reactive pointer state"
+    },
     {
       "name": "usePointerSwipe",
       "package": "core",

packages/components/index.ts

@@ -22,6 +22,7 @@ export * from '../core/useNetwork/component'
 export * from '../core/useNow/component'
 export * from '../core/useOnline/component'
 export * from '../core/usePageLeave/component'
+export * from '../core/usePointer/component'
 export * from '../core/usePreferredColorScheme/component'
 export * from '../core/usePreferredDark/component'
 export * from '../core/usePreferredLanguages/component'

packages/core/index.ts

@@ -47,6 +47,7 @@ export * from './useOnline'
 export * from './usePageLeave'
 export * from './useParallax'
 export * from './usePermission'
+export * from './usePointer'
 export * from './usePointerSwipe'
 export * from './usePreferredColorScheme'
 export * from './usePreferredDark'

packages/core/usePointer/component.ts

@@ -0,0 +1,17 @@
+import { defineComponent, reactive } from 'vue-demi'
+import { usePointer, UsePointerOptions } from '@vueuse/core'
+
+export const UsePointer = defineComponent<UsePointerOptions>({
+  name: 'UsePointer',
+  props: [
+    'pointerTypes',
+    'initialValue',
+  ] as unknown as undefined,
+  setup(props, { slots }) {
+    const data = reactive(usePointer(props))
+    return () => {
+      if (slots.default)
+        return slots.default(data)
+    }
+  },
+})

packages/core/usePointer/demo.vue

@@ -0,0 +1,11 @@
+<script setup lang="ts">
+import { reactive } from 'vue-demi'
+import { stringify } from '@vueuse/docs-utils'
+import { usePointer } from '.'
+
+const pointer = reactive(usePointer())
+</script>
+
+<template>
+  <pre class="select-none" style="touch-action: none">{{ pointer }}</pre>
+</template>

packages/core/usePointer/index.md

@@ -0,0 +1,23 @@
+---
+category: Sensors
+---
+
+# usePointer
+
+Reactive [pointer state](https://developer.mozilla.org/en-US/docs/Web/API/Pointer_events).
+
+## Basic Usage
+
+```js
+import { usePointer } from '@vueuse/core'
+
+const { x, y, pressure, pointerType } = usePointer()
+```
+
+## Component
+```html
+<UsePointer v-slot="{ x, y }">
+  x: {{ x }}
+  y: {{ y }}
+</UsePointer>
+```

packages/core/usePointer/index.ts

@@ -0,0 +1,75 @@
+import { MaybeRef, objectPick, toRefs } from '@vueuse/shared'
+import { ref, Ref } from 'vue-demi'
+import { useEventListener } from '../useEventListener'
+import { ConfigurableWindow, defaultWindow } from '../_configurable'
+import { PointerType, Position } from '../_types'
+
+export interface UsePointerState extends Position {
+  pressure: number
+  pointerId: number
+  tiltX: number
+  tiltY: number
+  width: number
+  height: number
+  twist: number
+  pointerType: PointerType | null
+}
+
+export interface UsePointerOptions extends ConfigurableWindow {
+  /**
+   * Pointer types that listen to.
+   *
+   * @default ['mouse', 'touch', 'pen']
+   */
+  pointerTypes?: PointerType[]
+
+  /**
+   * Initial values
+   */
+  initialValue?: MaybeRef<Partial<UsePointerState>>
+}
+
+const defaultState: UsePointerState = /* #__PURE__ */ {
+  x: 0,
+  y: 0,
+  pointerId: 0,
+  pressure: 0,
+  tiltX: 0,
+  tiltY: 0,
+  width: 0,
+  height: 0,
+  twist: 0,
+  pointerType: null,
+}
+const keys = /* #__PURE__ */ Object.keys(defaultState) as (keyof UsePointerState)[]
+
+/**
+ * Reactive pointer state.
+ *
+ * @see https://vueuse.org/usePointer
+ * @param options
+ */
+export function usePointer(options: UsePointerOptions = {}) {
+  const {
+    window = defaultWindow,
+  } = options
+
+  const state = ref(options.initialValue || {}) as unknown as Ref<UsePointerState>
+  Object.assign(state.value, defaultState, state.value)
+
+  const handler = (event: PointerEvent) => {
+    if (options.pointerTypes && !options.pointerTypes.includes(event.pointerType as PointerType))
+      return
+
+    state.value = objectPick(event, keys, false) as UsePointerState
+  }
+
+  if (window) {
+    useEventListener(window, 'pointerdown', handler, { passive: true })
+    useEventListener(window, 'pointermove', handler, { passive: true })
+  }
+
+  return {
+    ...toRefs(state),
+  }
+}

packages/functions.md

@@ -86,6 +86,7 @@
   - [`useOnline`](https://vueuse.org/core/useOnline/) — reactive online state
   - [`usePageLeave`](https://vueuse.org/core/usePageLeave/) — reactive state to show whether the mouse leaves the page
   - [`useParallax`](https://vueuse.org/core/useParallax/) — create parallax effect easily
+  - [`usePointer`](https://vueuse.org/core/usePointer/) — reactive pointer state
   - [`usePointerSwipe`](https://vueuse.org/core/usePointerSwipe/) — reactive swipe detection based on [PointerEvents](https://developer.mozilla.org/en-US/docs/Web/API/PointerEvent)
   - [`useResizeObserver`](https://vueuse.org/core/useResizeObserver/) — reports changes to the dimensions of an Element's content or the border-box
   - [`useSpeechRecognition`](https://vueuse.org/core/useSpeechRecognition/) — reactive [SpeechRecognition](https://developer.mozilla.org/en-US/docs/Web/API/SpeechRecognition)

packages/shared/utils/index.ts

@@ -85,3 +85,16 @@ export function increaseWithUnit(target: string | number, delta: number): string
     return target
   return result + unit
 }
+
+/**
+ * Create a new subset object by giving keys
+ *
+ * @category Object
+ */
+export function objectPick<O, T extends keyof O>(obj: O, keys: T[], omitUndefined = false) {
+  return keys.reduce((n, k) => {
+    if (k in obj)
+      if (!omitUndefined || !obj[k] === undefined) n[k] = obj[k]
+    return n
+  }, {} as Pick<O, T>)
+}