feat: add useMatchMedia and useBreakpoint (#14)

* feat: add useBreakpoint * feat: add useMatchMedia and allow to describe match media * test: test the usage of matchMedia * add matchMedia to the docs * move matchMedia and breakpoint and localstorage to `misc/`
pikax · Dec 28, 2019 · a519c45 · a519c45
1 parent a741a99
commit a519c45
Show file tree

Hide file tree

Showing 19 changed files with 470 additions and 6 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -8,6 +8,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 ### Added
 - [IntersectionObserver](composable/web/intersectionObserver) - Provides functionality to IntersectionObserver #27
+- [breakpoint](https://pikax.me/vue-composable/composable/web/breakpoint) - reactive `breakpoints` based on `window.innerWidth`
 
 ## 0.2.2
 ------------------------------

diff --git a/docs/.vuepress/components/BreakpointExample.vue b/docs/.vuepress/components/BreakpointExample.vue
@@ -0,0 +1,21 @@
+<template>
+  <div>
+    <div>Current breakpoint {{ current || "none" }}</div>
+    <div>valid breakpoints:</div>
+    <p><b v-if="S">Small</b></p>
+    <p><b v-if="L">Large</b></p>
+    <p><b v-if="XL">Extra Large</b></p>
+  </div>
+</template>
+
+<script>
+import { useBreakpoint } from "vue-composable";
+
+export default {
+  name: "breakpoint-example",
+  setup() {
+    // it will return object with reactive properties {XL: boolean, L: boolean, S: boolean}
+    return useBreakpoint({ XL: 1280, L: 768, S: "(min-width: 320px)" });
+  }
+};
+</script>
diff --git a/docs/.vuepress/components/MatchMediaExample.vue b/docs/.vuepress/components/MatchMediaExample.vue
@@ -0,0 +1,16 @@
+<template>
+  <div>
+    <p>Screen less than 600px: <b>{{ matches }}</b></p>
+  </div>
+</template>
+
+<script>
+import { useMatchMedia } from "vue-composable";
+
+export default {
+  name: "match-media-example",
+  setup() {
+    return useMatchMedia("(max-width: 600px)");
+  }
+};
+</script>
diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js
@@ -170,7 +170,11 @@ module.exports = {
           title: "Misc",
           sidebarDepth: 1,
           collapsable: false,
-          children: [["composable/misc/localStorage", "localStorage"]]
+          children: [
+            ["composable/misc/localStorage", "localStorage"],
+            ["composable/web/matchMedia", "matchMedia"],
+            ["composable/event/breakpoint", "breakpoint"]
+          ]
         },
         {
           title: "Pagination",
@@ -198,7 +202,6 @@ module.exports = {
             ["composable/web/fetch", "fetch"],
             ["composable/web/webSocket", "webSocket"],
             ["composable/web/intersectionObserver", "IntersectionObserver"]
-
           ]
         },
         {
@@ -215,7 +218,7 @@ module.exports = {
         selectText: "Languages",
         editLinkText: "Help us improve this page!",
         nav: [
-          { text: "Composable", link: "/composable/" },
+          { text: "Composable", link: "/composable/" }
           // { text: "Examples", link: "/examples/" }
         ]
       }

diff --git a/docs/README.md b/docs/README.md
@@ -55,6 +55,8 @@ Check out the [examples folder](examples) or start hacking on [codesandbox](http
 ### MISC
 
 - [localStorage](composable/misc/localStorage) - Reactive access to a `localStorage`
+- [MatchMedia](composable/misc/matchMedia) - reactive `MatchMedia`
+- [Breakpoint](composable/misc/breakpoint) - reactive `breakpoints` based on `window.innerWidth`
 
 ### Pagination
 
@@ -118,4 +120,6 @@ export default {
 
 ### Pagination example
 
+<ClientOnly>
 <array-pagination-example/>
+</ClientOnly>
diff --git a/docs/composable/_template.md b/docs/composable/_template.md
@@ -1,7 +1,17 @@
-# 
+#
 
 > The [mousemove event](https://developer.mozilla.org/en-US/docs/Web/API/Document/scroll_event).
 
+## Parameters
+
+```js
+import { useOnScroll } from "vue-composable";
+
+const scroll = useOnScroll(options);
+```
+
+| Parameters | Type | Description |
+
 ## State
 
 The `useOnScroll` function exposes the following reactive state:
@@ -39,4 +49,6 @@ const { remove } = useOnScroll();
 
 ### Code
 
+<ClientOnly>
 <on-scroll-example/>
+</ClientOnly>
diff --git a/docs/composable/misc/breakpoint.md b/docs/composable/misc/breakpoint.md
@@ -0,0 +1,73 @@
+# Breakpoint
+
+Allows to get reactive object on the current windows size.
+
+::: warning
+If `Number` it checks the defined breakpoint against window.innerWidth.
+`bp >= window.innerWidth`
+If `MediaQuery` is passed it will not be able to resolve the current breakpoint
+:::
+
+## State
+
+The `useBreakpoint` function exposes the following reactive state:
+
+```js
+import { useBreakpoint } from "vue-composable";
+
+const { current, /* properties from the arguments */ L, XL } = useBreakpoint({
+  L: 720,
+  XL: 1280,
+  S: "(min-width: 320px)" // also supports media query - it uses `useMatchMedia`
+});
+```
+
+| State   | Type     | Description                                                           |
+| ------- | -------- | --------------------------------------------------------------------- |
+| current | `String` | Smallest breakpoint key. where the breakpoint is an `Number`          |
+| ...args | `Args`   | returns the object with the same keys but with reactive boolean value |
+
+## Methods
+
+The `useBreakpoint` function exposes the following methods:
+
+```js
+import { useBreakpoint } from "vue-composable";
+
+const { remove } = useBreakpoint();
+```
+
+| Signature | Description                         |
+| --------- | ----------------------------------- |
+| `remove`  | Manually removes the event listener |
+
+## Example
+
+```vue
+<template>
+  <div>
+    <div>Current breakpoint {{ current || "none" }}</div>
+    <div>valid breakpoints:</div>
+    <p><b v-if="S">Small</b></p>
+    <p><b v-if="L">Large</b></p>
+    <p><b v-if="XL">Extra Large</b></p>
+  </div>
+</template>
+
+<script>
+import { useBreakpoint } from "vue-composable";
+export default {
+  name: "breakpoint-example",
+  setup() {
+    // it will return object with reactive properties {XL: boolean, L: boolean, S: boolean}
+    return useBreakpoint({ XL: 1280, L: 768, S: "(min-width: 320px)" });
+  }
+};
+</script>
+```
+
+### Code
+
+<ClientOnly>
+<breakpoint-example/>
+</ClientOnly>
diff --git a/docs/composable/misc/matchMedia.md b/docs/composable/misc/matchMedia.md
@@ -0,0 +1,71 @@
+# MatchMedia
+
+> The [matchMedia](https://developer.mozilla.org/en-US/docs/Web/API/Window/matchMedia).
+
+## Parameters
+
+```js
+import { useMatchMedia } from "vue-composable";
+
+const matchMedia = useMatchMedia(mediaQueryString);
+```
+
+| Parameters       | Type     | Description                                     |
+| ---------------- | -------- | ----------------------------------------------- |
+| mediaQueryString | `String` | A string representing the media query to parse. |
+
+## State
+
+The `useMatchMedia` function exposes the following reactive state:
+
+```js
+import { useMatchMedia } from "vue-composable";
+
+const { scrollTop, matches } = useMatchMedia();
+```
+
+| State          | Type                                                                              | Description                                                                                          |
+| -------------- | --------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| mediaQueryList | [MediaQueryList](https://developer.mozilla.org/en-US/docs/Web/API/MediaQueryList) | List of objects stores information on a media query                                                  |
+| matches        | `Boolean`                                                                         | A Boolean that returns true if the document currently matches the media query list, or false if not. |
+
+## Methods
+
+The `useMatchMedia` function exposes the following methods:
+
+```js
+import { useMatchMedia } from "vue-composable";
+
+const { remove } = useMatchMedia();
+```
+
+| Signature | Description                         |
+| --------- | ----------------------------------- |
+| `remove`  | Manually removes the event listener |
+
+## Example
+
+```vue
+<template>
+  <div>
+    <p>Screen less than 600px: <b>{{ matches }}</b></p>
+  </div>
+</template>
+
+<script>
+import { useMatchMedia } from "vue-composable";
+
+export default {
+  name: "match-media-example",
+  setup() {
+    return useMatchMedia("(max-width: 600px)");
+  }
+};
+</script>
+```
+
+### Code
+
+<ClientOnly>
+<match-media-example/>
+</ClientOnly>