@splendidlabz/utils 1.3.0

package/.eslintrc.cjs

@@ -0,0 +1,3 @@
+module.exports = {
+  extends: ['@splendidlabz/eslint-config'],
+}

package/.turbo/turbo-lint.log

@@ -0,0 +1,10 @@
+
+> @splendidlabs/utils@1.0.3 lint
+> eslint . --fix
+
+
+/Users/zellwk/projects/@splendidlabs/packages/utils/lib/index.test.js
+  4:10  error  'expect' is defined but never used  no-unused-vars
+
+✖ 1 problem (1 error, 0 warnings)
+

package/.turbo/turbo-test.log

@@ -0,0 +1,10 @@
+
+> @splendidlabs/utils@1.0.3 test
+> vitest run
+
+sh: vitest: command not found
+npm ERR! Lifecycle script `test` failed with error: 
+npm ERR! Error: command failed 
+npm ERR!   in workspace: @splendidlabs/utils@1.0.3 
+npm ERR!   at location: /Users/zellwk/projects/@splendidlabs/packages/utils 
+

package/CHANGELOG.md

@@ -0,0 +1,37 @@
+# @splendidlabz/utils
+
+## 1.3.0
+
+### Minor Changes
+
+- a9128f4: Add Debounce and Throttle functions
+
+## 1.2.0
+
+### Minor Changes
+
+- a9128f4: - Add `uuid` to `utils/node`
+  - Add `uuid` to `utils/dom`
+  - Add `MONTHS` constant to `utils`
+
+### Patch Changes
+
+- a9128f4: - Change `randomString` in `utils/dom` to produce a HTML-usable string
+
+## 1.1.2
+
+### Patch Changes
+
+- Add query params path
+
+## 1.1.1
+
+### Patch Changes
+
+- Fix session store path
+
+## 1.1.0
+
+### Minor Changes
+
+- 2d5789f: New and better cache utility

package/actions/index.js

@@ -0,0 +1,5 @@
+export * from './masonry.js'
+export * from './mutation-observer.js'
+export * from './prefer-horizontal-scroll.js'
+export * from './resize-observer.js'
+export * from './sticky.js'

package/actions/masonry.js

@@ -0,0 +1,38 @@
+import { getChildrenElements, mediaLoaded } from '../dom/index.js'
+import { resizeObserver } from './resize-observer.js'
+
+export async function masonry(node) {
+  if (nativeMasonrySupport(node)) return
+
+  let items
+  let gap
+
+  node.style.setProperty('row-gap', '1px', 'important')
+  node.style.gridAutoRows = '0px'
+  await mediaLoaded(node)
+
+  const obs = resizeObserver(node, {
+    async callback(opts) {
+      items = getChildrenElements(node)
+      gap = parseFloat(getComputedStyle(node).columnGap)
+      layout(node)
+    },
+  })
+
+  async function layout() {
+    items.forEach(item => {
+      const itemBox = item.getBoundingClientRect()
+      item.style.gridRowEnd = `span ${Math.round(itemBox.height + gap)}`
+    })
+  }
+
+  return {
+    destroy() {
+      obs.disconnect()
+    },
+  }
+}
+
+function nativeMasonrySupport(node) {
+  return getComputedStyle(node).gridTemplateRows === 'masonry'
+}

package/actions/mutation-observer.js

@@ -0,0 +1,43 @@
+/* eslint-env browser */
+
+// https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver/observe
+
+// These are simply options that will often be used. Check the docs for other options.
+const defaultOptions = {
+  attributes: false,
+  childList: false,
+  subtree: false,
+}
+
+export function mutationObserver(node, options) {
+  options = { ...defaultOptions, ...options }
+  const { callback, ...opts } = options
+  const observer = new MutationObserver(observerFn)
+
+  function observerFn(entries) {
+    for (const entry of entries) {
+      if (callback) callback({ node, entry, observer })
+      else {
+        node.dispatchEvent(
+          new CustomEvent('mutate', {
+            detail: { node, entry, observer },
+          }),
+        )
+      }
+    }
+  }
+
+  if (node === window) node = document.body
+  observer.observe(node, opts)
+
+  return {
+    disconnect() {
+      observer.disconnect()
+    },
+
+    // Destroy is used for Svelte actions
+    destroy() {
+      observer.disconnect()
+    },
+  }
+}

package/actions/prefer-horizontal-scroll.js

@@ -0,0 +1,125 @@
+import {
+  addListeners,
+  getCSSVar,
+  removeListeners,
+  setCSSVar,
+} from '../dom/index.js'
+import { omitEmpty } from '../lib/index.js'
+
+const DEFAULT_OPTIONS = {
+  scrollSnapDelay: 1000,
+}
+
+export function preferHorizontalScroll(node, props = {}) {
+  if (!node.classList.contains('Scrollable-preferHorizontalScroll')) return
+
+  const state = {
+    origSnapType: null,
+    currentSnapType: null,
+    snapTimeoutID: null,
+  }
+
+  const options = {
+    ...DEFAULT_OPTIONS,
+    ...omitEmpty({
+      scrollSnapDelay: getCSSVar(node, '--scrollSnapDelay'),
+    }),
+    ...omitEmpty(props),
+  }
+
+  const listeners = [
+    {
+      event: 'wheel',
+      node,
+      handler: handleWheel,
+    },
+
+    {
+      event: 'pointerenter',
+      node,
+      handler: handlePointerEnter,
+    },
+
+    {
+      event: 'pointerleave',
+      node,
+      handler: handlePointerLeave,
+    },
+  ]
+
+  addListeners(listeners)
+
+  function handleWheel(event) {
+    const direction = event.deltaY > 0 ? 'down' : 'up'
+    const updatedDelta = event.deltaY
+
+    // Only handle mouse wheel
+    // Trackpad users can scroll horizontally themselves
+    if (isTrackpad(event)) return false
+
+    setCSSVar(node, '--snap-type', 'none')
+
+    const scrolledAmount = node.scrollLeft
+    const scrollWidth = node.scrollWidth
+    const clientWidth = node.clientWidth
+    const scrollableAmount = scrollWidth - clientWidth // Maximum scrollable width to the right
+
+    // Hijack downwards scroll
+    if (direction === 'down' && scrolledAmount < scrollableAmount) {
+      node.scrollLeft += updatedDelta
+      event.preventDefault()
+    }
+
+    // Hijack upwards scroll
+    if (direction === 'up' && scrolledAmount > 0) {
+      node.scrollLeft += updatedDelta
+      event.preventDefault()
+    }
+
+    // Restore snap type after a delay
+    const { snapTimeoutID } = state
+    if (snapTimeoutID) clearTimeout(snapTimeoutID)
+    state.snapTimeoutID = setTimeout(_ => {
+      restoreHijackedState(node, state)
+    }, options.scrollSnapDelay)
+  }
+
+  function handlePointerEnter(event) {
+    state.origSnapType = getCSSVar(node, '--snap-type') || 'proximity'
+  }
+
+  function handlePointerLeave(event) {
+    restoreHijackedState(node, state)
+  }
+
+  return {
+    destroy() {
+      removeListeners(listeners)
+    },
+  }
+}
+
+function restoreHijackedState(node, state) {
+  const scrollLeft = node.scrollLeft
+
+  // Get the final scroll position
+  setCSSVar(node, '--snap-type', state.origSnapType)
+  const finalScrollLeft = node.scrollLeft
+
+  // Scroll back to original position before replacing snap
+  setCSSVar(node, '--snap-type', 'none')
+  node.scrollTo({ left: scrollLeft, behavior: 'instant' })
+
+  // Scroll back to the final position smoothly
+  node.scrollTo({ left: finalScrollLeft, behavior: 'smooth' })
+
+  setTimeout(_ => {
+    setCSSVar(node, '--snap-type', state.origSnapType)
+  }, 250)
+}
+
+// https://stackoverflow.com/questions/10744645/detect-touchpad-vs-mouse-in-javascript/62415754#62415754
+function isTrackpad(event) {
+  // if (event.deltaMode === 0) return true // Deltamode no longer works in Chrome
+  if (event.wheelDeltaY === event.deltaY * -3) return true
+}

package/actions/resize-observer.js

@@ -0,0 +1,38 @@
+/* eslint-env browser */
+
+const DEFAULT_OBSERVER_OPTIONS = {
+  observe: true,
+}
+
+export function resizeObserver(node, options) {
+  // We set the option here to prevent observer from being created unless necessary.
+  options = { ...DEFAULT_OBSERVER_OPTIONS, ...options }
+  if (!options.observe) return
+
+  const observer = new ResizeObserver(observerFn)
+
+  function observerFn(entries) {
+    for (const entry of entries) {
+      if (options.callback) options.callback({ node, entry, observer })
+      else {
+        node.dispatchEvent(
+          new CustomEvent('resize', {
+            detail: { node, entry, observer },
+          }),
+        )
+      }
+    }
+  }
+
+  observer.observe(node)
+
+  return {
+    disconnect() {
+      observer.unobserve(node)
+    },
+
+    destroy() {
+      observer.unobserve(node)
+    },
+  }
+}

package/actions/sticky.js

@@ -0,0 +1,88 @@
+import {
+  boundingBoxRelativeToAncestor,
+  findScrollContainer,
+} from '../dom/index.js'
+import { resizeObserver } from './resize-observer.js'
+
+export function sticky(node, props = {}) {
+  const scrollContainer = findScrollContainer(node)
+
+  let stickyTBLR = getComputedTBLR(node)
+
+  const obs = resizeObserver(node, {
+    callback: ({ entry }) => {
+      stickyTBLR = getComputedTBLR(node)
+      isSticking()
+
+      // Arguably, one can use a single container to check for all Sticky elements, but that is unnecessarily complicated to code. This adds more listeners to the scroll containers (assuming many), but it shouldn't be have enough listeners to break performance in any way.
+      scrollContainer === document.documentElement
+        ? window.addEventListener('scroll', scrollEventListener)
+        : scrollContainer.addEventListener('scroll', scrollEventListener)
+    },
+  })
+
+  function scrollEventListener(event) {
+    isSticking()
+  }
+
+  function isSticking() {
+    const { top, bottom, left, right } = stickyTBLR
+    const relativeRect = boundingBoxRelativeToAncestor({
+      element: node,
+      ancestorElement: scrollContainer,
+    })
+
+    // Sticky Top
+    if (!isNaN(top)) {
+      if (relativeRect.top - top <= 1) {
+        node.classList.add('sticking')
+      } else {
+        node.classList.remove('sticking')
+      }
+    }
+
+    // Sticky Bottom
+    if (!isNaN(bottom)) {
+      if (relativeRect.bottom + bottom >= -1) {
+        node.classList.add('sticking')
+      } else {
+        node.classList.remove('sticking')
+      }
+    }
+
+    // Sticky Left
+    if (!isNaN(left)) {
+      if (relativeRect.left - left <= 1) {
+        node.classList.add('sticking')
+      } else {
+        node.classList.remove('sticking')
+      }
+    }
+
+    // Sticky Right
+    if (!isNaN(right)) {
+      if (relativeRect.right + right >= -1) {
+        node.classList.add('sticking')
+      } else {
+        node.classList.remove('sticking')
+      }
+    }
+  }
+
+  return {
+    destroy() {
+      obs.disconnect()
+      scrollContainer.removeEventListener('scroll', scrollEventListener)
+    },
+  }
+}
+
+function getComputedTBLR(element) {
+  const style = getComputedStyle(element)
+  return {
+    top: parseFloat(style.top),
+    bottom: parseFloat(style.bottom),
+    left: parseFloat(style.left),
+    right: parseFloat(style.right),
+  }
+}

package/dom/bounding-box.js

@@ -0,0 +1,54 @@
+/**
+ * Advanced boundincClientRect that contains information vertical and horizontal centers.
+ * @param {HTMLElement} element
+ */
+export function boundingBox(element, { containsPadding = true } = {}) {
+  const box = element.getBoundingClientRect()
+
+  // Spread original properties into the return object
+  const ret = {}
+  for (const prop in box) ret[prop] = box[prop]
+
+  // Gets boundingClientRect value without padding
+  if (!containsPadding) {
+    const style = getComputedStyle(element)
+    let { paddingTop, paddingRight, paddingBottom, paddingLeft } = style
+    paddingTop = parseFloat(paddingTop)
+    paddingRight = parseFloat(paddingRight)
+    paddingBottom = parseFloat(paddingBottom)
+    paddingLeft = parseFloat(paddingLeft)
+
+    ret.x = ret.x + paddingLeft
+    ret.y = ret.y + paddingTop
+    ret.width = ret.width - paddingLeft - paddingRight
+    ret.height = ret.height - paddingTop - paddingBottom
+    ret.top = ret.top + paddingTop
+    ret.bottom = ret.bottom - paddingBottom
+    ret.right = ret.right - paddingRight
+    ret.left = ret.left + paddingLeft
+  }
+
+  ret.xCenter = (ret.left + ret.right) / 2
+  ret.yCenter = (ret.top + ret.bottom) / 2
+  return ret
+}
+
+export function boundingBoxRelativeToAncestor({ element, ancestorElement }) {
+  ancestorElement = ancestorElement || element.parentElement
+
+  const box = boundingBox(element)
+  const ancestorBox = boundingBox(ancestorElement, {
+    containsPadding: false,
+  })
+
+  return {
+    top: box.top - ancestorBox.top,
+    right: box.right - ancestorBox.right,
+    bottom: box.bottom - ancestorBox.bottom,
+    left: box.left - ancestorBox.left,
+    width: box.width,
+    height: box.height,
+    xCenter: (box.left + box.right) / 2 - ancestorBox.left,
+    yCenter: (box.top + box.bottom) / 2 - ancestorBox.top,
+  }
+}

package/dom/clipboard.js

@@ -0,0 +1,14 @@
+/**
+ * Copies rich text from an element to the clipboard
+ * @param HTMLElement element - Element to copy
+ */
+export function copyRichText(element) {
+  const range = document.createRange()
+  range.selectNode(element)
+
+  const selection = window.getSelection()
+  selection.removeAllRanges()
+  selection.addRange(range)
+  document.execCommand('copy')
+  selection.removeAllRanges()
+}

package/dom/cookie.js

@@ -0,0 +1,31 @@
+export const cookies = {
+  get(name) {
+    return getCookie(name)
+  },
+
+  set(name, value, days) {
+    setCookie(name, value, days)
+  },
+}
+
+/**
+ * Gets a cookie by name
+ * Thanks to https://stackoverflow.com/a/21125098
+ * @param {string} name Cookie name
+ * @returns string Cookie value
+ */
+export function getCookie(name) {
+  const match = document.cookie.match(new RegExp('(^| )' + name + '=([^;]+)'))
+  if (match) return match[2]
+}
+
+// By Copilot. Needs testing before confirmation.
+function setCookie(name, value, days) {
+  let expires = ''
+  if (days) {
+    const date = new Date()
+    date.setTime(date.getTime() + days * 24 * 60 * 60 * 1000)
+    expires = '; expires=' + date.toUTCString()
+  }
+  document.cookie = name + '=' + (value || '') + expires + '; path=/'
+}

package/dom/css-vars.js

@@ -0,0 +1,11 @@
+import { getElement } from './get-element.js'
+
+export function getCSSVar(element, prop) {
+  element = getElement(element)
+  return getComputedStyle(element).getPropertyValue(prop)
+}
+
+export function setCSSVar(element, prop, value) {
+  element = getElement(element)
+  element.style.setProperty(prop, value)
+}

package/dom/events.js

@@ -0,0 +1,76 @@
+export function addListeners(listeners) {
+  listeners.forEach(({ node, event, handler }) => {
+    node.addEventListener(event, handler)
+  })
+}
+
+export function removeListeners(listeners) {
+  listeners.forEach(({ node, event, handler }) => {
+    node.removeEventListener(event, handler)
+  })
+}
+
+export function dispatchEvent(node, eventName, detail, options = {}) {
+  node.dispatchEvent(
+    new CustomEvent(eventName, {
+      ...options,
+      detail,
+    }),
+  )
+}
+
+// Updates an event with new properties
+export function updateEvent(event, updates) {
+  const { type, ...rest } = event
+  return new CustomEvent(event.type, {
+    ...rest,
+    ...updates,
+  })
+}
+
+// Doesn't seem to be used anywhere now.
+// Switch to addListeners and removeListeners instead
+export function createListeners(listeners) {
+  listeners = listeners || []
+
+  listeners.forEach(listener => {
+    const { node, event, handler } = listener
+    node.addEventListener(event, handler)
+  })
+
+  return {
+    get list() {
+      return listeners
+    },
+
+    add({ node, event, handler }) {
+      listeners.push({ node, event, handler })
+      node.addEventListener(event, handler)
+    },
+
+    remove({ node, event, handler }) {
+      const index = listeners.findIndex(listener => {
+        if (
+          listener.node === node &&
+          listener.event === event &&
+          listener.handler === handler
+        ) {
+          return true
+        }
+        return false
+      })
+
+      if (index !== -1) {
+        listeners.splice(index, 1)
+        node.removeEventListener(event, handler)
+      }
+    },
+
+    clear() {
+      listeners.forEach(({ node, event, handler }) => {
+        listeners = []
+        node.removeEventListener(event, handler)
+      })
+    },
+  }
+}

package/dom/events.test.js

@@ -0,0 +1,99 @@
+// @vitest-environment jsdom
+import { describe, expect, it } from 'vitest'
+
+import { createListeners } from './events.js'
+
+describe('Listeners Factory', _ => {
+  it('Empty', _ => {
+    const listeners = createListeners()
+    expect(listeners.list).toEqual([])
+  })
+
+  it('Begins with some listeners', _ => {
+    const node1 = document.createElement('div')
+    const node2 = document.createElement('p')
+    const event1 = 'click'
+    const event2 = 'keydown'
+    const cb1 = _ => {}
+    const cb2 = _ => {}
+
+    const listeners = createListeners([
+      { node: node1, event: event1, handler: cb1 },
+      { node: node2, event: event2, handler: cb2 },
+    ])
+
+    expect(listeners.list).toEqual([
+      { node: node1, event: event1, handler: cb1 },
+      { node: node2, event: event2, handler: cb2 },
+    ])
+  })
+
+  it('Add', _ => {
+    const node = document.createElement('div')
+    const event = 'click'
+    const handler = _ => {
+      node.setAttribute('clicked', true)
+    }
+
+    const listeners = createListeners()
+    listeners.add({ node, event, handler })
+
+    // Ensures the listener was added to the list
+    expect(listeners.list.length).toBe(1)
+
+    // Ensures the listener works
+    node.click()
+    expect(node.getAttribute('clicked')).toBe('true')
+  })
+
+  it('Remove', _ => {
+    const node = document.createElement('div')
+    const event = 'click'
+    const handler = _ => {
+      const count = node.getAttribute('count') || 0
+      node.setAttribute('count', count + 1)
+    }
+
+    const listener = { node, event, handler }
+    const listeners = createListeners([listener])
+
+    node.click()
+    expect(node.getAttribute('count')).toBe('1')
+
+    listeners.remove(listener)
+
+    // Ensures listener has been removed
+    node.click()
+
+    expect(listeners.list.length).toBe(0)
+    expect(node.getAttribute('count')).toBe('1')
+  })
+
+  it('Clears all listeners from', _ => {
+    const node1 = document.createElement('div')
+    const node2 = document.createElement('p')
+    const event1 = 'click'
+    const event2 = 'click'
+    const cb1 = _ => {
+      node1.setAttribute('clicked', true)
+    }
+    const cb2 = _ => {
+      node2.setAttribute('clicked', true)
+    }
+
+    const listeners = createListeners([
+      { node: node1, event: event1, handler: cb1 },
+      { node: node2, event: event2, handler: cb2 },
+    ])
+
+    listeners.clear()
+    expect(listeners.list).toEqual([])
+
+    // Ensures none of the listeners work anymore
+    node1.click()
+    node2.click()
+
+    expect(node1.getAttribute('clicked')).toBe(null)
+    expect(node2.getAttribute('clicked')).toBe(null)
+  })
+})