feat(useMutationObserver): init (#13)

indexes.json

@@ -23,6 +23,7 @@
     "Animation",
     "Browser",
     "Component",
+    "Sensors",
     "Utilities"
   ],
   "functions": [
@@ -80,6 +81,13 @@
       "category": "Browser",
       "description": "reactive [Media Query](https://developer.mozilla.org/en-US/docs/Web/CSS/Media_Queries/Testing_media_queries)"
     },
+    {
+      "name": "useMutationObserver",
+      "package": "core",
+      "docs": "/core/useMutationObserver/",
+      "category": "Sensors",
+      "description": "watch for changes being made to the DOM tree"
+    },
     {
       "name": "usePreferredDark",
       "package": "core",

packages/core/index.ts

@@ -1,5 +1,6 @@
 export * from './useEventListener'
 export * from './useMediaQuery'
+export * from './useMutationObserver'
 export * from './usePreferredDark'
 export * from './useStorage'
 export * from '@svelte-use/shared'

packages/core/indexes.json

@@ -23,6 +23,7 @@
     "Animation",
     "Browser",
     "Component",
+    "Sensors",
     "Utilities"
   ],
   "functions": [
@@ -80,6 +81,13 @@
       "category": "Browser",
       "description": "reactive [Media Query](https://developer.mozilla.org/en-US/docs/Web/CSS/Media_Queries/Testing_media_queries)"
     },
+    {
+      "name": "useMutationObserver",
+      "package": "core",
+      "docs": "/core/useMutationObserver/",
+      "category": "Sensors",
+      "description": "watch for changes being made to the DOM tree"
+    },
     {
       "name": "usePreferredDark",
       "package": "core",

packages/core/useMutationObserver/demo.svelte

@@ -0,0 +1,36 @@
+<script lang="ts">
+  import { onMount } from 'svelte'
+  import { useMutationObserver } from '.'
+
+  let el: HTMLDivElement
+  let messages: string[] = []
+  let className = ''
+  let style = ''
+
+  onMount(() => {
+    useMutationObserver(el, mutations => {
+      const mutation = mutations[0]
+
+      if (!mutation) {
+        return
+      }
+
+      messages.push(mutation.attributeName!)
+      messages = messages
+    }, { attributes: true })
+  })
+
+  setTimeout(() => {
+    className = 'test test2'
+  }, 1000)
+
+  setTimeout(() => {
+    style = 'color: red'
+  }, 1550)
+</script>
+
+<div bind:this={el} class={className} style={style}>
+  {#each messages as text}
+    <div>Mutation Attribute: { text }</div>
+  {/each}
+</div>

packages/core/useMutationObserver/index.md

@@ -0,0 +1,31 @@
+---
+category: Sensors
+---
+
+# useMutationObserver
+
+Watch for changes being made to the DOM tree. [MutationObserver MDN](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver)
+
+## Usage
+
+```html
+<script>
+  import { useMutationObserver } from '@svelte-use/core'
+
+  let el
+  let messages = []
+
+  onMount(() => {
+    useMutationObserver(
+      el,
+      (mutations) => {
+        if (!mutations[0]) {
+          messages.push(mutations[0].attributeName)
+          messages = messages
+        }
+      },
+      { attributes: true },
+    )
+  })
+</script>
+```

packages/core/useMutationObserver/index.ts

@@ -0,0 +1,56 @@
+import { MaybeReadable, toReadable, tryOnDestroy } from '@svelte-use/shared'
+import { ConfigurableWindow, defaultWindow } from '../_configurable'
+
+export interface MutationObserverOptions
+  extends MutationObserverInit,
+    ConfigurableWindow {}
+
+/**
+ * Watch for changes being made to the DOM tree.
+ *
+ * @see https://svelte-use.vercel.app/core/useMutationObserver
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver MutationObserver MDN
+ * @param target
+ * @param callback
+ * @param options
+ */
+export function useMutationObserver(
+  target: MaybeReadable<Element | undefined | null>,
+  callback: MutationCallback,
+  options: MutationObserverOptions = {},
+) {
+  const { window = defaultWindow, ...mutationOptions } = options
+  let observer: MutationObserver | undefined
+  const isSupported = window && 'IntersectionObserver' in window
+
+  const cleanup = () => {
+    if (observer) {
+      observer.disconnect()
+      observer = undefined
+    }
+  }
+
+  const unsubscribe = toReadable(target).subscribe((el) => {
+    cleanup()
+
+    if (isSupported && window && el) {
+      // @ts-expect-error missing type
+      observer = new window.MutationObserver(callback)
+      observer!.observe(el, mutationOptions)
+    }
+  })
+
+  const stop = () => {
+    cleanup()
+    unsubscribe()
+  }
+
+  tryOnDestroy(stop)
+
+  return {
+    isSupported,
+    stop,
+  }
+}
+
+export type UseMutationObserverReturn = ReturnType<typeof useMutationObserver>

packages/functions.md

@@ -19,6 +19,9 @@
   - [`tryOnDestroy`](/shared/tryOnDestroy/) — safe `onDestroy`
   - [`tryOnMount`](/shared/tryOnMount/) — safe `onMount`
 
+### Sensors
+  - [`useMutationObserver`](/core/useMutationObserver/) — watch for changes being made to the DOM tree
+
 ### Utilities
   - [`whenever`](/shared/whenever/) — shorthand for watching value to be truthy
 

packages/shared/utils/index.ts

@@ -1,4 +1,8 @@
 import { get_current_component } from 'svelte/internal'
+import { get, readable } from '@svelte-use/store'
+import { MaybeReadable } from './types'
+import { isReadable } from './is'
+import { Readable } from 'svelte/store'
 
 export * from './is'
 export * from './types'
@@ -30,3 +34,11 @@ export function promiseTimeout(
     }
   })
 }
+
+export function unReadable<T>(val: MaybeReadable<T>): T {
+  return isReadable(val) ? get(val) : val
+}
+
+export function toReadable<T>(val: MaybeReadable<T>): Readable<T> {
+  return isReadable(val) ? val : readable(val)
+}

packages/shared/utils/is.ts

@@ -17,7 +17,8 @@ export const isObject = (val: any): val is object =>
   toString.call(val) === '[object Object]'
 export const isWindow = (val: any): val is Window =>
   typeof window !== 'undefined' && toString.call(val) === '[object Window]'
-export const isReadable = <T>(val: any): val is Readable<T> => 'subscribe' in val
+export const isReadable = <T>(val: any): val is Readable<T> =>
+  'subscribe' in (val || {})
 export const now = () => Date.now()
 export const timestamp = () => +Date.now()
 export const clamp = (n: number, min: number, max: number) =>