add usePositionStickyObserver

src/index.ts

@@ -13,6 +13,7 @@ export * from './useMutationObserver'
 export * from './useNow'
 export * from './usePatchRef'
 export * from './useResizeObserver'
+export * from './usePositionStickyObserver'
 export * from './useRouteParam'
 export * from './useRouteQuery'
 export * from './useRouteQueryParam'

src/usePositionStickyObserver/README.md

@@ -0,0 +1,34 @@
+# usePositionStickyObserver
+
+This composition is abstracts away the logic necessary to determine if a `position: sticky;` element has gone into it's "stuck" mode. This is useful when you want to style the element differently when it's stuck, like if you want to add a background color.
+
+## Example
+
+```typescript
+const stickyHeader = ref<HTMLElement>()
+const { stuck } = usePositionStickyObserver(stickyHeader)
+
+const classes = computed(() ({
+  header: {
+    'header--stuck': stuck.value,
+  }
+}))
+```
+
+## Arguments
+
+| Name    | Type                                           |
+| ------- | ---------------------------------------------- |
+| element | `HTMLElement \| Ref<HTMLElement \| undefined>` |
+| options | '{}'                                           |
+
+### Options
+
+| Name            | Type                                                                                                   |
+| --------------- | ------------------------------------------------------------------------------------------------------ |
+| rootMargin      | `string`, [MDN DOcs](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver/rootMargin) |
+| boundingElement | `HTMLElement \| Ref<HTMLElement \| undefined>`. The scroll container, defaults to the body.            |
+
+## Returns
+
+`UsePositionStickyObserverResponse`

src/usePositionStickyObserver/index.ts

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

src/usePositionStickyObserver/usePositionStickyObserver.ts

@@ -0,0 +1,57 @@
+import { Ref, computed, onMounted, ref, toValue } from 'vue'
+import { MaybeRefOrGetter } from '@/types/maybe'
+import { useIntersectionObserver } from '@/useIntersectionObserver'
+
+export type UsePositionStickyObserverResponse = {
+  stuck: Ref<boolean>,
+}
+
+export type UsePositionStickyObserverOptions = {
+  rootMargin?: string,
+  boundingElement?: MaybeRefOrGetter<HTMLElement | undefined>,
+}
+
+const usePositionStickyObserverDefaultOptions = {
+  rootMargin: '-1px 0px 0px 0px',
+  boundingElement: document.body,
+}
+
+export function usePositionStickyObserver(
+  element: MaybeRefOrGetter<HTMLElement | undefined>,
+  options?: MaybeRefOrGetter<UsePositionStickyObserverOptions>,
+): UsePositionStickyObserverResponse {
+  const elementRef = computed(() => toValue(element))
+  const optionsRef = computed(() => {
+    if (!options) {
+      return usePositionStickyObserverDefaultOptions
+    }
+
+    const { rootMargin, boundingElement } = toValue(options)
+    const boundingElementRef = toValue(boundingElement)
+
+    return {
+      rootMargin: rootMargin ?? usePositionStickyObserverDefaultOptions.rootMargin,
+      boundingElement: boundingElementRef ?? usePositionStickyObserverDefaultOptions.boundingElement,
+    }
+  })
+
+  const stuck = ref(false)
+
+  function intersect(entries: IntersectionObserverEntry[]): void {
+    entries.forEach(entry => {
+      stuck.value = entry.intersectionRatio < 1
+    })
+  }
+
+  const { observe } = useIntersectionObserver(intersect, computed(() => ({
+    threshold: [1],
+    rootMargin: optionsRef.value.rootMargin,
+    root: optionsRef.value.boundingElement,
+  })))
+
+  onMounted(() => observe(elementRef))
+
+  return {
+    stuck,
+  }
+}