Merge pull request #17 from microcipcip/feature/useSize

feat(useSize): Adding useSize feature

Author: microcipcip

Diff for: README.md

@@ -88,6 +88,8 @@ export default Vue.extend({
     [![Demo](https://img.shields.io/badge/demo-🚀-yellow.svg)](https://microcipcip.github.io/vue-use-kit/?path=/story/sensors-usemouseleavepage--demo)
   - [`useOrientation`](./src/functions/useOrientation/stories/useOrientation.md) — tracks state of device's screen orientation.
     [![Demo](https://img.shields.io/badge/demo-🚀-yellow.svg)](https://microcipcip.github.io/vue-use-kit/?path=/story/sensors-useorientation--demo)
+  - [`useSize`](./src/functions/useSize/stories/useSize.md) — tracks size of an HTML element.
+    [![Demo](https://img.shields.io/badge/demo-🚀-yellow.svg)](https://microcipcip.github.io/vue-use-kit/?path=/story/sensors-usesize--demo)
   - [`useScroll`](./src/functions/useScroll/stories/useScroll.md) — tracks an HTML element's scroll position.
     [![Demo](https://img.shields.io/badge/demo-🚀-yellow.svg)](https://microcipcip.github.io/vue-use-kit/?path=/story/sensors-usescroll--demo)
   - [`useSearchParams`](./src/functions/useSearchParams/stories/useSearchParams.md) — tracks browser's location search params.

Diff for: src/functions/useIntersection/stories/useIntersection.md

@@ -27,8 +27,8 @@ function useIntersection(
 ### Returns
 
 - `observedEntry: Ref<IntersectionObserverEntry | null>` the [observed entry](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserverEntry)
-- `start: Function` the function used for starting observing
-- `stop: Function` the function used for stopping observing
+- `start: Function` the function used for start observing
+- `stop: Function` the function used for stop observing
 
 ## Usage
 

Diff for: src/functions/useSize/index.ts

@@ -0,0 +1 @@
+export * from './useSize'

Diff for: src/functions/useSize/stories/UseSizeDemo.vue

@@ -0,0 +1,77 @@
+<template>
+  <div>
+    <div class="box-actions">
+      <button class="button is-primary" @click="start" v-if="!isTracking">
+        Start tracking resize
+      </button>
+      <button class="button is-danger" @click="stop" v-else>
+        Stop tracking resize
+      </button>
+    </div>
+    <div class="box" ref="elRef">
+      <div class="box__feedback">
+        {{ Math.ceil(width) }}px - {{ Math.ceil(height) }}px
+      </div>
+      <div class="box__container">
+        <div class="box__message">Resize me!</div>
+      </div>
+    </div>
+  </div>
+</template>
+
+<script lang="ts">
+import Vue from 'vue'
+import { useSize } from '@src/vue-use-kit'
+import { ref, watch } from '@src/api'
+
+export default Vue.extend({
+  name: 'UseSizeDemo',
+  setup() {
+    const elRef = ref(null)
+    const width = ref(0)
+    const height = ref(0)
+    const { observedEntry, isTracking, start, stop } = useSize(elRef)
+    watch(observedEntry, () => {
+      if (!observedEntry.value) return
+      width.value = observedEntry.value.contentRect.width
+      height.value = observedEntry.value.contentRect.height
+    })
+    return { elRef, width, height, isTracking, start, stop }
+  }
+})
+</script>
+
+<style scoped>
+.box-actions {
+  margin-bottom: 20px;
+}
+
+.box {
+  display: flex;
+  position: relative;
+  flex-direction: column;
+  justify-content: center;
+  align-items: center;
+  padding: 0;
+  resize: both;
+  overflow: auto;
+}
+
+.box__feedback {
+  position: absolute;
+  top: 10px;
+  right: 10px;
+  color: #666;
+  text-transform: uppercase;
+  font-size: 12px;
+}
+
+.box__container {
+  padding: 20px;
+}
+
+.box__message {
+  text-transform: uppercase;
+  font-weight: bold;
+}
+</style>

Diff for: src/functions/useSize/stories/useSize.md

@@ -0,0 +1,83 @@
+# useSize
+
+Vue function that tracks the size of an HTML element.
+
+This function is based on the [ResizeObserver API](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserver).
+
+Please note that **ResizeObserver does not work on certain browsers such as IE/Edge/Safari**,
+therefore you should add a polyfill such as:
+
+```js
+import { ResizeObserver } from '@juggle/resize-observer'
+window.ResizeObserver = window.ResizeObserver || ResizeObserver
+```
+
+## Reference
+
+```typescript
+function useSize(
+  elRef: Ref<null | HTMLElement>,
+  options?: ResizeObserverObserveOptions,
+  runOnMount?: boolean
+): {
+  observedEntry: Ref<ResizeObserverEntry | null>
+  isTracking: Ref<boolean>
+  start: () => void
+  stop: () => void
+}
+```
+
+### Parameters
+
+- `elRef: Ref<null | HTMLElement>` the element to observe for size changes
+- `options: ResizeObserverObserveOptions` the [ResizeObserver options](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserver/observe)
+- `runOnMount: boolean` whether to observe the element on mount, `true` by default
+
+### Returns
+
+- `observedEntry: Ref<ResizeObserverEntry | null>` the [observed entry](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserverEntry)
+- `isTracking: Ref<boolean>` whether this function observer is running or not
+- `start: Function` the function used for start observing
+- `stop: Function` the function used for stop observing
+
+## Usage
+
+```html
+<template>
+  <div class="box" ref="elRef">
+    <div class="box__msg">Resize me!</div>
+    <div class="box__info">{{ width }} {{ height }}</div>
+  </div>
+</template>
+
+<script lang="ts">
+  import Vue from 'vue'
+  import { useSize } from 'vue-use-kit'
+  import { ref, watch } from '@src/api'
+
+  export default Vue.extend({
+    name: 'UseSizeDemo',
+    setup() {
+      const elRef = ref(null)
+      const width = ref(0)
+      const height = ref(0)
+      const { observedEntry } = useSize(elRef)
+
+      watch(observedEntry, () => {
+        if (!observedEntry.value) return
+        const { width, height } = observedEntry.value.contentRect
+        width.value = width
+        height.value = height
+      })
+      return { elRef, width, height }
+    }
+  })
+</script>
+
+<style scoped>
+  .box {
+    resize: both;
+    overflow: auto;
+  }
+</style>
+```

Diff for: src/functions/useSize/stories/useSize.story.ts

@@ -0,0 +1,32 @@
+import { storiesOf } from '@storybook/vue'
+import path from 'path'
+import StoryTitle from '@src/helpers/StoryTitle.vue'
+import UseSizeDemo from './UseSizeDemo.vue'
+
+const functionName = 'useSize'
+const functionPath = path.resolve(__dirname, '..')
+const notes = require(`./${functionName}.md`).default
+
+const basicDemo = () => ({
+  components: { StoryTitle, demo: UseSizeDemo },
+  template: `
+    <div class="container">
+      <story-title 
+        function-path="${functionPath}" 
+        source-name="${functionName}" 
+        demo-name="UseSizeDemo.vue"
+      >
+        <template v-slot:title></template>
+        <template v-slot:intro>
+          <p>
+            <strong>Try to resize the box below by dragging the handle</strong> in the bottom right hand corner.
+          </p>
+        </template>
+      </story-title>
+      <demo />
+    </div>`
+})
+
+storiesOf('sensors|useSize', module)
+  .addParameters({ notes })
+  .add('Demo', basicDemo)

Diff for: src/functions/useSize/useSize.spec.ts

@@ -0,0 +1,12 @@
+// import { mount } from '@src/helpers/test'
+// import { useSize } from '@src/vue-use-kit'
+
+afterEach(() => {
+  jest.clearAllMocks()
+})
+
+describe('useSize', () => {
+  it('should do something', () => {
+    // Add test here
+  })
+})

Diff for: src/functions/useSize/useSize.ts

@@ -0,0 +1,49 @@
+import { ref, onMounted, onUnmounted, Ref } from '@src/api'
+import {
+  ResizeObserver as ResizeObserverInterface,
+  ResizeObserverEntry,
+  ResizeObserverObserveOptions
+} from '@src/types/ResizeObserver'
+
+const errorMsg = 'ResizeObserver is not supported, please install a polyfill'
+
+export function useSize(
+  elRef: Ref<null | HTMLElement>,
+  options: ResizeObserverObserveOptions = {},
+  runOnMount = true
+) {
+  const isTracking = ref(false)
+  const observedEntry: Ref<ResizeObserverEntry | null> = ref(null)
+
+  const handleObserver = (entries: ResizeObserverEntry[]) => {
+    observedEntry.value = entries[0]
+  }
+
+  let observer: ResizeObserverInterface | null = null
+
+  const start = () => {
+    if (isTracking.value) return
+    if (!('ResizeObserver' in window)) throw new Error(errorMsg)
+
+    // Do not start if the observer is already initialized
+    // or the elRef does not exist
+    if (!elRef.value) return
+    observer = new (window as any).ResizeObserver(
+      handleObserver
+    ) as ResizeObserverInterface
+    observer.observe(elRef.value, options)
+    isTracking.value = true
+  }
+
+  const stop = () => {
+    if (!isTracking.value) return
+    if (!observer) return
+    observer.disconnect()
+    isTracking.value = false
+  }
+
+  onMounted(() => runOnMount && start())
+  onUnmounted(stop)
+
+  return { observedEntry, isTracking, start, stop }
+}

Diff for: src/types/ResizeObserver.ts

@@ -0,0 +1,27 @@
+export declare class ResizeObserver {
+  constructor(callback: ResizeObserverCallback)
+  disconnect: () => void
+  observe: (target: Element, options?: ResizeObserverObserveOptions) => void
+  unobserve: (target: Element) => void
+}
+
+export interface ResizeObserverEntry {
+  readonly borderBoxSize: ResizeObserverEntryBoxSize
+  readonly contentBoxSize: ResizeObserverEntryBoxSize
+  readonly contentRect: DOMRectReadOnly
+  readonly target: Element
+}
+
+export interface ResizeObserverObserveOptions {
+  box?: 'content-box' | 'border-box'
+}
+
+export type ResizeObserverCallback = (
+  entries: ResizeObserverEntry[],
+  observer: ResizeObserver
+) => void
+
+export interface ResizeObserverEntryBoxSize {
+  blockSize: number
+  inlineSize: number
+}

Diff for: src/vue-use-kit.ts

@@ -15,6 +15,7 @@ export * from './functions/useMouse'
 export * from './functions/useMouseElement'
 export * from './functions/useMouseLeavePage'
 export * from './functions/useOrientation'
+export * from './functions/useSize'
 export * from './functions/useSearchParams'
 export * from './functions/useScroll'
 // Animations