feat(usePointerLock): new function

packages/components/index.ts

@@ -37,6 +37,7 @@ export * from '../core/useOffsetPagination/component'
 export * from '../core/useOnline/component'
 export * from '../core/usePageLeave/component'
 export * from '../core/usePointer/component'
+export * from '../core/usePointerLock/component'
 export * from '../core/usePreferredColorScheme/component'
 export * from '../core/usePreferredContrast/component'
 export * from '../core/usePreferredDark/component'

packages/core/index.ts

@@ -80,6 +80,7 @@ export * from './usePageLeave'
 export * from './useParallax'
 export * from './usePermission'
 export * from './usePointer'
+export * from './usePointerLock'
 export * from './usePointerSwipe'
 export * from './usePreferredColorScheme'
 export * from './usePreferredContrast'

packages/core/useMouse/index.ts

@@ -7,11 +7,12 @@ import type { Position } from '../types'
 
 export interface UseMouseOptions extends ConfigurableWindow, ConfigurableEventFilter {
   /**
-   * Mouse position based by page or client
+   * Mouse position based by page, client, or relative to previous position
    *
    * @default 'page'
    */
-  type?: 'page' | 'client'
+  type?: 'page' | 'client' | 'movement'
+
   /**
    * Listen to `touchmove` events
    *
@@ -63,6 +64,10 @@ export function useMouse(options: UseMouseOptions = {}) {
       x.value = event.clientX
       y.value = event.clientY
     }
+    else if (type === 'movement') {
+      x.value = event.movementX
+      y.value = event.movementY
+    }
     sourceType.value = 'mouse'
   }
   const reset = () => {
@@ -95,7 +100,7 @@ export function useMouse(options: UseMouseOptions = {}) {
   if (window) {
     useEventListener(window, 'mousemove', mouseHandlerWrapper, { passive: true })
     useEventListener(window, 'dragover', mouseHandlerWrapper, { passive: true })
-    if (touch) {
+    if (touch && type !== 'movement') {
       useEventListener(window, 'touchstart', touchHandlerWrapper, { passive: true })
       useEventListener(window, 'touchmove', touchHandlerWrapper, { passive: true })
       if (resetOnTouchEnds)

packages/core/usePointerLock/component.ts

@@ -0,0 +1,17 @@
+import { defineComponent, h, reactive, ref } from 'vue-demi'
+import { usePointerLock } from '@vueuse/core'
+import type { RenderableComponent } from '../types'
+
+export const UsePointerLock = defineComponent<RenderableComponent>({
+  name: 'UsePointerLock',
+  props: ['as'] as unknown as undefined,
+  setup(props, { slots }) {
+    const target = ref()
+    const data = reactive(usePointerLock(target))
+
+    return () => {
+      if (slots.default)
+        return h(props.as || 'div', { ref: target }, slots.default(data))
+    }
+  },
+})

packages/core/usePointerLock/demo.vue

@@ -0,0 +1,97 @@
+<script setup>
+import { ref, watch } from 'vue-demi'
+import { useMouse, usePointerLock, useRafFn } from '@vueuse/core'
+
+const { lock, unlock, element } = usePointerLock()
+const { x, y } = useMouse({ type: 'movement' })
+const rotY = ref(-45)
+const rotX = ref(0)
+
+watch([x, y], ([x, y]) => {
+  if (!element.value)
+    return
+  rotY.value += x / 2
+  rotX.value -= y / 2
+})
+
+useRafFn(() => {
+  // v-bind doesn't work with custom CSS properties for some reason
+  document.documentElement.style.setProperty('--rotY', rotY.value.toString())
+  document.documentElement.style.setProperty('--rotX', rotX.value.toString())
+})
+</script>
+
+<template>
+  <div class="scene">
+    <div class="cube" @mousedown.capture="lock" @mouseup="unlock">
+      <div class="bases">
+        <span style="--i: 1" />
+        <span style="--i: -1" />
+      </div>
+      <div class="sides">
+        <span style="--i: 0" />
+        <span style="--i: 1" />
+        <span style="--i: 2" />
+        <span style="--i: 3" />
+      </div>
+    </div>
+  </div>
+</template>
+
+<style scoped>
+:root {
+  --rotY: 0; /*v-bind(rotY);*/
+  --rotX: 0; /*v-bind(rotX);*/
+}
+
+.scene {
+  display: flex;
+  justify-content: center;
+  align-items: center;
+  box-sizing: border-box;
+  perspective: 300px;
+}
+
+.cube {
+  cursor: all-scroll;
+  position: relative;
+  width: 100px;
+  height: 100px;
+  transform-style: preserve-3d;
+  transform: rotateY(calc(var(--rotY) * 1deg)) rotateX(calc(var(--rotX) * 1deg));
+}
+
+.cube div, .cube span {
+  position: absolute;
+  top: 0;
+  left: 0;
+  width: 100%;
+  height: 100%;
+}
+
+.cube div {
+  transform-style: preserve-3d;
+}
+
+.cube span {
+  border: 1px solid;
+  backface-visibility: hidden;
+  background: rgba(77, 186, 135, .2) center / 75% no-repeat;
+}
+
+.cube .bases span {
+  transform: rotateX(calc(90deg * var(--i))) translateZ(50px);
+}
+
+.cube .sides span {
+  transform: rotateY(calc(90deg * var(--i))) translateZ(50px);
+}
+
+.cube span:nth-child(odd) {
+  background-image: url(/vue.svg);
+}
+
+.cube span:nth-child(even) {
+  background-image: url(/favicon.svg);
+}
+</style>

packages/core/usePointerLock/index.md

@@ -0,0 +1,26 @@
+---
+category: Sensors
+---
+
+# usePointerLock
+
+Reactive [pointer lock](https://developer.mozilla.org/en-US/docs/Web/API/Pointer_Lock_API).
+
+## Basic Usage
+
+```js
+import { usePointerLock } from '@vueuse/core'
+
+const { isSupported, lock, unlock, element } = usePointerLock()
+```
+
+## Component Usage
+
+```html
+<UsePointerLock v-slot="{ lock }">
+  <canvas />
+  <button @click="lock">
+    Lock Pointer on Canvas
+  </button>
+</UsePointerLock>
+```

packages/core/usePointerLock/index.ts

@@ -0,0 +1,74 @@
+import { ref } from 'vue-demi'
+import { until } from '@vueuse/shared'
+import { useEventListener } from '../useEventListener'
+import { useSupported } from '../useSupported'
+import { unrefElement } from '../unrefElement'
+import type { MaybeElementRef } from '../unrefElement'
+import type { ConfigurableDocument } from '../_configurable'
+import { defaultDocument } from '../_configurable'
+
+type MaybeHTMLElement = HTMLElement | undefined | null
+
+/**
+ * Reactive pointer lock.
+ *
+ * @see https://vueuse.org/usePointerLock
+ * @param target
+ * @param options
+ */
+export function usePointerLock(target?: MaybeElementRef<MaybeHTMLElement>, options: ConfigurableDocument = {}) {
+  const { document = defaultDocument } = options
+
+  const isSupported = useSupported(() => document && 'pointerLockElement' in document)
+
+  const element = ref<MaybeHTMLElement>()
+
+  let targetElement: MaybeHTMLElement
+
+  if (isSupported.value) {
+    useEventListener(document, 'pointerlockchange', () => {
+      const currentElement = document!.pointerLockElement ?? element.value
+      if (targetElement && currentElement === targetElement)
+        element.value = document!.pointerLockElement as MaybeHTMLElement
+    })
+
+    useEventListener(document, 'pointerlockerror', () => {
+      const currentElement = document!.pointerLockElement ?? element.value
+      if (targetElement && currentElement === targetElement) {
+        const action = document!.pointerLockElement ? 'release' : 'acquire'
+        throw new Error(`Failed to ${action} pointer lock.`)
+      }
+    })
+  }
+
+  async function lock(e: MaybeElementRef<MaybeHTMLElement> | Event) {
+    if (!isSupported.value)
+      throw new Error('Pointer Lock API is not supported by your browser.')
+
+    targetElement = e instanceof Event ? unrefElement(target) ?? <HTMLElement>e.currentTarget : unrefElement(e)
+    if (!targetElement)
+      throw new Error('Target element undefined.')
+    targetElement.requestPointerLock()
+
+    return await until(element).toBe(targetElement)
+  }
+
+  async function unlock() {
+    if (!element.value)
+      return false
+
+    document!.exitPointerLock()
+
+    targetElement = await until(element).toBeNull()
+    return true
+  }
+
+  return {
+    isSupported,
+    element,
+    lock,
+    unlock,
+  }
+}
+
+export type UsePointerLockReturn = ReturnType<typeof usePointerLock>