feat: add useDocumentVisibility composable function (#23)

* Make scripts executable

* Add event listener helpers

* Add useDocumentVisibility function

* Add docs for useDocumentVisibility

* Allow additional options for useEventListener

* Refactor event listener helpers

Author: studnitz

docs/.vuepress/config.js

@@ -60,6 +60,7 @@ module.exports = {
         'device-light',
         'device-motion',
         'device-orientation',
+        'document-visibility',
         'fetch',
         'fullscreen',
         'geolocation',

docs/README.md

@@ -42,6 +42,7 @@ npm install @vue/composition-api vue-use-web
 - [Device Light](./guide/device-light.md).
 - [Device Motion](./guide/device-motion.md).
 - [Device Orientation](./guide/device-orientation.md).
+- [Document Visibility](./document-visibility.md)
 - [Fetch API](./guide/fetch.md).
 - [Full-screen](./guide/fullscreen.md).
 - [Geo-location API](./guide/geolocation.md).

docs/guide/README.md

@@ -26,6 +26,7 @@ These are the currently implemented Web APIs and the planned ones.
 - [Device Light](./device-light.md).
 - [Device Motion](./device-motion.md).
 - [Device Orientation](./device-orientation.md).
+- [Document Visibility](./document-visibility.md)
 - [Fetch API](./fetch.md).
 - [Full-screen](./fullscreen.md).
 - [Geo-location API](./geolocation.md).

docs/guide/document-visibility.md

@@ -0,0 +1,45 @@
+# Media Query
+
+> The [`Document.visibilityState`](https://developer.mozilla.org/en-US/docs/Web/API/Document/visibilityState) read-only property returns the visibility of the document, that is in which context this element is now visible. It is useful to know if the document is in the background or an invisible tab, or only loaded for pre-rendering. Possible values are:
+
+## State
+
+```js
+import { useDocumentVisibility } from 'vue-use-web';
+
+const pageIsVisible = useDocumentVisibility();
+```
+
+`useDocumentVisibility` only returns a single value which is a boolean.
+
+| State     | Type           | Description                                                |
+| --------- | -------------- | ---------------------------------------------------------- |
+| isVisible | `Ref<boolean>` | If the page is currently visible (not in a background tab) |
+
+## Example
+
+```vue
+<template>
+  <h1>Page is currently visible: {{ isVisible }}</h1>
+</template>
+
+<script>
+import { useMedia } from 'vue-use-web';
+import { watch } from '@vue/composition-api'
+
+
+export default {
+  setup() {
+    const isVisible = useDocumentVisibility()
+
+    watch(() => console.log(isVisible.value))
+
+    return { isVisible }
+  }
+};
+</script>
+```
+
+## Demo
+
+TODO: Add cool live example!

scripts/defs.sh

@@ -0,0 +1,26 @@
+import { ref, Ref } from '@vue/composition-api';
+import { hasWindow, useDocumentEventListener } from './utils';
+
+/**
+ * Tracks visibility of the page.
+ *
+ * @returns True if the document is currently visible.
+ *
+ * @example
+ * setup() {
+ *  const isVisible = useDocumentVisibility()
+ *  watch(() => console.log(isVisible))
+ * }
+ *
+ */
+export function useDocumentVisibility(): Ref<boolean> {
+  const documentIsVisible = () => document.visibilityState === 'visible';
+
+  const isVisible: Ref<boolean> = ref(hasWindow ? documentIsVisible() : true);
+
+  useDocumentEventListener('visibilitychange', () => {
+    isVisible.value = documentIsVisible();
+  });
+
+  return isVisible;
+}

scripts/deploy.sh

@@ -3,6 +3,7 @@ export * from './Clipboard';
 export * from './DeviceLight';
 export * from './DeviceMotion';
 export * from './DeviceOrientation';
+export * from './DocumentVisibility';
 export * from './Fetch';
 export * from './FullScreen';
 export * from './Geolocation';

src/DocumentVisibility.ts

@@ -1,3 +1,5 @@
+import { onMounted, onUnmounted } from '@vue/composition-api';
+
 export function throttle<T extends (...args: any[]) => void>(wait: number, fn: T): T {
   if (wait === 0) {
     return fn;
@@ -17,3 +19,30 @@ export function throttle<T extends (...args: any[]) => void>(wait: number, fn: T
     timeout = setTimeout(later, wait) as any;
   }) as T;
 }
+
+export const hasWindow = typeof window !== 'undefined';
+
+export function useEventListener(
+  element: EventTarget,
+  type: string,
+  listener: EventListenerOrEventListenerObject,
+  options?: EventListenerOptions
+) {
+  onMounted(() => {
+    element.addEventListener(type, listener, options);
+  });
+
+  onUnmounted(() => {
+    element.removeEventListener(type, listener, options);
+  });
+}
+
+const eventListenerFor = (element: EventTarget) => (
+  type: string,
+  listener: EventListenerOrEventListenerObject,
+  options?: EventListenerOptions
+) => useEventListener(element, type, listener, options);
+
+export const useDocumentEventListener = eventListenerFor(document);
+
+export const useWindowEventListener = eventListenerFor(window);