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/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,91 @@
+<script setup>
+import { ref, watch } from 'vue-demi'
+import { useMouse, usePointerLock } 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
+})
+</script>
+
+<template>
+  <div class="scene">
+    <div id="demo-cube" 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>
+#demo-cube {
+  --rotY: v-bind(rotY);
+  --rotX: v-bind(rotX);
+  transform: rotateY(calc(var(--rotY) * 1deg)) rotateX(calc(var(--rotX) * 1deg));
+}
+
+.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;
+}
+
+.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, triggerElement } = 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,95 @@
+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'
+
+declare global {
+  interface PointerLockOptions {
+    unadjustedMovement?: boolean
+  }
+
+  interface Element {
+    requestPointerLock(options?: PointerLockOptions): Promise<void> | void
+  }
+}
+
+type MaybeHTMLElement = HTMLElement | undefined | null
+
+export interface UsePointerLockOptions extends ConfigurableDocument {
+  pointerLockOptions?: PointerLockOptions
+}
+
+/**
+ * Reactive pointer lock.
+ *
+ * @see https://vueuse.org/usePointerLock
+ * @param target
+ * @param options
+ */
+export function usePointerLock(target?: MaybeElementRef<MaybeHTMLElement>, options: UsePointerLockOptions = {}) {
+  const { document = defaultDocument, pointerLockOptions } = options
+
+  const isSupported = useSupported(() => document && 'pointerLockElement' in document)
+
+  const element = ref<MaybeHTMLElement>()
+
+  const triggerElement = 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
+        if (!element.value)
+          targetElement = triggerElement.value = null
+      }
+    })
+
+    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, options?: PointerLockOptions) {
+    if (!isSupported.value)
+      throw new Error('Pointer Lock API is not supported by your browser.')
+
+    triggerElement.value = e instanceof Event ? <HTMLElement>e.currentTarget : null
+    targetElement = e instanceof Event ? unrefElement(target) ?? triggerElement.value : unrefElement(e)
+    if (!targetElement)
+      throw new Error('Target element undefined.')
+    targetElement.requestPointerLock(options ?? pointerLockOptions)
+
+    return await until(element).toBe(targetElement)
+  }
+
+  async function unlock() {
+    if (!element.value)
+      return false
+
+    document!.exitPointerLock()
+
+    await until(element).toBeNull()
+    return true
+  }
+
+  return {
+    isSupported,
+    element,
+    triggerElement,
+    lock,
+    unlock,
+  }
+}
+
+export type UsePointerLockReturn = ReturnType<typeof usePointerLock>