feat: add useMedia composable function (#20)

* feat: impelement useMedia

* refactor: use useMedia for the color scheme composable

* docs: added useMedia to the documentation and readme

Author: logaretm

README.md

@@ -40,6 +40,7 @@ Each composition function is designed to degrade gracefully so you can safely us
 - [Geo-location API](https://logaretm.github.io/vue-use-web/guide/geolocation.html).
 - [Localstorage API](https://logaretm.github.io/vue-use-web/guide/local-storage.html)
 - [Intersection Observer](https://logaretm.github.io/vue-use-web/guide/intersection-observer.html).
+- [Mouse Query](https://logaretm.github.io/vue-use-web/guide/media-query.html)
 - [Mouse Position](https://logaretm.github.io/vue-use-web/guide/mouse-position.html)
 - [Network Information API](https://logaretm.github.io/vue-use-web/guide/network.html).
 - [Preferred Color Scheme](https://logaretm.github.io/vue-use-web/guide/preferred-color-scheme.html).

docs/.vuepress/config.js

@@ -65,6 +65,7 @@ module.exports = {
         'geolocation',
         'intersection-observer',
         'local-storage',
+        'media-query',
         'mouse-position',
         'network',
         'preferred-color-scheme',

docs/README.md

@@ -47,6 +47,7 @@ npm install @vue/composition-api vue-use-web
 - [Geo-location API](./guide/geolocation.md).
 - [Local-storage API](./guide/local-storage.md)
 - [Intersection Observer](./guide/intersection-observer.md).
+- [Media Query](./guide/media-query.md)
 - [Mouse Position](./guide/mouse-position.md)
 - [Network Information API](./guide/network.md).
 - [Preferred Color Scheme](./guide/preferred-color-scheme.md).

docs/guide/README.md

@@ -31,7 +31,8 @@ These are the currently implemented Web APIs and the planned ones.
 - [Geo-location API](./geolocation.md).
 - [Intersection Observer](./intersection-observer.md).
 - [Local storage API](./local-storage.md).
-- [Mouse Position](./guide/mouse-position.md).
+- [Media Query](./media-query.md).
+- [Mouse Position](./mouse-position.md).
 - [Network Information API](./network.md).
 - [Preferred Color Scheme](./preferred-color-scheme.md).
 - [Preferred Languages](./preferred-languages.md).

docs/guide/media-query.md

@@ -0,0 +1,41 @@
+# Media Query
+
+> he DOM provides features that can test the results of a media [query programmatically](https://developer.mozilla.org/en-US/docs/Web/CSS/Media_Queries/Testing_media_queries), via the MediaQueryList interface and its methods and properties. Once you've created a MediaQueryList object, you can check the result of the query or receive notifications when the result changes.
+
+## State
+
+```js
+import { useMedia } from 'vue-use-web';
+
+const isLg = useMedia('(min-width: 1024px)');
+```
+
+`useMedia` only returns a single value which is a boolean.
+
+| State   | Type           | Description                  |
+| ------- | -------------- | ---------------------------- |
+| matches | `Ref<boolean>` | If the query matches or not. |
+
+## Example
+
+```vue
+<template>
+  <h1>Is Desktop: {{ isLg }}</h1>
+</template>
+
+<script>
+import { useMedia } from 'vue-use-web';
+
+export default {
+  setup() {
+    const isLg = useMedia('(min-width: 1024px)');
+
+    return { isLg };
+  }
+};
+</script>
+```
+
+## Demo
+
+TODO: Add cool live example!

docs/guide/preferred-color-scheme.md

@@ -2,6 +2,8 @@
 
 > The [matchMedia preferred-color-scheme](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme) is used to detect the user's preference for a `light` or `dark` theme. This can be useful when you should adapt your UI depending on the user preference.
 
+## State
+
 ```js
 import { usePreferredColorScheme } from 'vue-use-web';
 
@@ -12,6 +14,10 @@ const scheme = usePreferredColorScheme();
 | ----- | ------------- | ---------------------------------------------------------------------------------------- |
 | theme | `Ref<String>` | Current user color scheme preference, will be one of 'dark', 'light' and 'no-preference' |
 
+:::tip
+This composable function uses [`useMedia`](./media-query.md) internally.
+:::
+
 ## Example
 
 ```vue

src/Media.ts

@@ -0,0 +1,30 @@
+import { ref, onMounted, onUnmounted } from '@vue/composition-api';
+
+export function useMedia(query: string) {
+  let mediaQuery!: MediaQueryList;
+
+  // try to fetch initial value (avoid SSR issues)
+  if (typeof window !== 'undefined') {
+    mediaQuery = window.matchMedia(query);
+  }
+
+  const matches = ref(mediaQuery ? mediaQuery.matches : false);
+  function handler(event: MediaQueryListEvent) {
+    matches.value = event.matches;
+  }
+
+  onMounted(() => {
+    if (!mediaQuery) {
+      mediaQuery = window.matchMedia(query);
+    }
+
+    matches.value = mediaQuery.matches;
+    mediaQuery.addListener(handler);
+  });
+
+  onUnmounted(() => {
+    mediaQuery.removeListener(handler);
+  });
+
+  return matches;
+}

src/PreferredColorScheme.ts

@@ -1,41 +1,27 @@
-import { ref, onMounted, onUnmounted } from '@vue/composition-api';
-
-export function usePreferredColorScheme() {
-  const themesObj: Record<string, MediaQueryList> = {
-    light: window.matchMedia('(prefers-color-scheme: light)'),
-    dark: window.matchMedia('(prefers-color-scheme: dark)'),
-    'no-preference': window.matchMedia('(prefers-color-scheme: no-preference)')
+import { computed, Ref } from '@vue/composition-api';
+import { useMedia } from './Media';
+
+export function usePreferredColorScheme(): Ref<'dark' | 'light' | 'no-preference'> {
+  const queries = {
+    light: '(prefers-color-scheme: light)',
+    dark: '(prefers-color-scheme: dark)',
+    'no-preference': '(prefers-color-scheme: no-preference)'
   };
 
-  const value = ref(getTheme());
+  const isDark = useMedia(queries.dark);
+  const isLight = useMedia(queries.light);
 
-  function getTheme() {
-    let theme = null;
-    for (const key in themesObj) {
-      if (themesObj[key].matches) {
-        theme = key;
-        break;
-      }
+  const theme = computed(() => {
+    if (isDark.value) {
+      return 'dark';
     }
 
-    return theme;
-  }
-
-  function handler() {
-    value.value = getTheme();
-  }
-
-  onMounted(() => {
-    Object.values(themesObj).forEach(theme => {
-      theme.addListener(handler);
-    });
-  });
+    if (isLight.value) {
+      return 'light';
+    }
 
-  onUnmounted(() => {
-    Object.values(themesObj).forEach(themeMedia => {
-      themeMedia.removeListener(handler);
-    });
+    return 'no-preference';
   });
 
-  return value;
+  return theme;
 }

src/index.ts

@@ -8,6 +8,7 @@ export * from './FullScreen';
 export * from './Geolocation';
 export * from './IntersectionObserver';
 export * from './LocalStorage';
+export * from './Media';
 export * from './MousePosition';
 export * from './Network';
 export * from './PreferredColorScheme';