@splendidlabz/utils 1.11.2 → 1.11.4

package/src/dom/observers/mutation-observer.js

@@ -1,51 +0,0 @@
-/* eslint-env browser */
-import { dispatchEvent } from '../events.js'
-import { useObserverMethodOnTarget } from './observer.js'
-
-// 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. Adding them here simply because it's easier to refer them here than reading the docs.
-const defaultOptions = {
-  attributes: false,
-  childList: false,
-  subtree: false,
-}
-
-export function mutationObserver(target, options) {
-  options = { ...defaultOptions, ...options }
-  const { callback, ...opts } = options
-  const observer = new MutationObserver(observerFn)
-
-  if (target === window) target = document.body
-  useObserverMethodOnTarget(target, observer, 'observe', opts)
-
-  function observerFn(entries) {
-    for (const entry of entries) {
-      if (callback) callback({ entry, entries, observer })
-      else dispatchEvent(target, 'mutate', { entry, entries, observer })
-    }
-  }
-
-  return {
-    observer,
-    observe(target) {
-      useObserverMethodOnTarget(target, observer, 'observe', options)
-    },
-
-    takeRecords() {
-      return observer.takeRecords()
-    },
-
-    disconnect() {
-      // Take records before disconnecting.
-      // https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver/takeRecords
-      const records = observer.takeRecords()
-      observer.disconnect()
-      if (records.length > 0) observerFn(records)
-    },
-
-    destroy() {
-      observer.disconnect()
-    },
-  }
-}

package/src/dom/observers/observer.js

@@ -1,18 +0,0 @@
-import { getNodeType } from '../get-element.js'
-
-export function useObserverMethodOnTarget(
-  target,
-  observer,
-  method = 'observe',
-  options = undefined
-) {
-  const targetType = getNodeType(target)
-  if (targetType === 'element') observer[method](target, options)
-  if (targetType === 'nodelist') {
-    const elements = Array.from(target)
-    elements.forEach(element => observer[method](element, options))
-  }
-  if (targetType === 'array') {
-    target.forEach(element => observer[method](element, options))
-  }
-}

package/src/dom/observers/resize-observer.js

@@ -1,66 +0,0 @@
-/* eslint-env browser */
-import { dispatchEvent } from '../events.js'
-import { useObserverMethodOnTarget } from './observer.js'
-
-/**
- * Creates and manages a ResizeObserver instance to monitor size changes of a target element.
- *
- * @param {Element|Window|Document|NodeList|Element[]} target - The element(s) to observe.
- *   - If window or document is provided, document.documentElement will be observed instead.
- *   - If NodeList or Array of elements is provided, all elements will be observed.
- * @param {Object} options - Configuration options for the resize observer
- * @param {boolean} [options.observe=true] - Whether to start observing immediately. If false, the observer won't be created.
- * @param {Function} [options.callback] - Optional callback function that will be called when resize changes are detected.
- *                                          If not provided, a 'resize-obs' event will be dispatched on the target.
- * @param {Object} [options.observerOptions] - Additional options to pass to ResizeObserver.observe()
- *
- * @returns {Object} An object with methods to control the observer:
- *   - observe(target, options): Start observing a new target element
- *   - unobserve(target): Stop observing a target element
- *   - disconnect(): Disconnect the observer and stop all observations
- *   - destroy(): Alias for disconnect()
- *
- * @example
- * // Basic usage with callback
- * resizeObserver(element, {
- *   callback: ({ entry, entries, observer }) => {
- *     console.log('Element resized:', entry.contentRect);
- *   }
- * });
- *
- * @example
- * // Usage with event listener
- * resizeObserver(element);
- * element.addEventListener('resize-obs', ({ detail }) => {
- *   console.log('Element resized:', detail.entry.contentRect);
- * });
- */
-export function resizeObserver(target, options) {
-  const { callback, ...opts } = options
-  const observer = new ResizeObserver(observerFn)
-
-  if (target === window || target === document)
-    target = document.documentElement
-  useObserverMethodOnTarget(target, observer, 'observe', opts)
-
-  function observerFn(entries) {
-    for (const entry of entries) {
-      if (callback) callback({ entry, entries, observer })
-      else
-        dispatchEvent(entry.target, 'resize-obs', { entry, entries, observer })
-    }
-  }
-
-  return {
-    observe(target) {
-      useObserverMethodOnTarget(target, observer, 'observe', options)
-    },
-
-    unobserve(target) {
-      useObserverMethodOnTarget(target, observer, 'unobserve')
-    },
-
-    disconnect: _ => observer.disconnect(),
-    destroy: _ => observer.disconnect(),
-  }
-}

package/src/dom/observers/scroll-observer.js

@@ -1,146 +0,0 @@
-/* eslint-env browser */
-import { resizeObserver } from './resize-observer.js'
-
-const defaultOptions = {
-  threshold: 0, // Float between 0 to 1.
-  tolerance: 0.1, // Float between 0 to 1. Tolerance for event firing
-  once: false, // Only fire threshold callback once
-}
-
-/**
- * @typedef {Object} ScrollObserverOptions
- * @property {number} [threshold] - Float between 0 to 1. When to trigger callback (0.75 = 75% down page)
- * @property {number} [tolerance] - Float between 0 to 1. Tolerance zone around threshold
- * @property {boolean} [once] - Only fire threshold callback once (default: false)
- * @property {Function} [callback] - Called on every scroll with scrollPercent
- * @property {Function} [onScrollDown] - Called when scrolling down
- * @property {Function} [onScrollUp] - Called when scrolling up
- * @property {Function} [onEnterThreshold] - Called when entering threshold zone
- */
-
-/**
- * @param {Element | Document | Window} node
- * @returns {Element}
- */
-function getScrollElement(node) {
-  if (
-    node === document ||
-    node === window ||
-    node === document.documentElement
-  ) {
-    return document.documentElement
-  }
-  return /** @type {Element} */ (node)
-}
-
-/**
- * Scroll Observer - Optimized for performance
- * @param {Element | Document | Window} node - The element to observe scroll events on
- * @param {ScrollObserverOptions} [options] - Configuration options
- */
-export function scrollObserver(node, options = {}) {
-  const { callback, onScrollDown, onScrollUp, onEnterThreshold, ...userOpts } =
-    options
-  const opts = { ...defaultOptions, ...userOpts }
-  const { threshold, tolerance, once } = opts
-
-  let prevScrollDirection = null
-  let prevScrollTop = 0
-  let prevScrollPercent = 0
-  let thresholdFired = false
-  let rafId = null
-
-  // Determine scroll context once at initialization
-  const isDocumentScroll =
-    node === document || node === window || node === document.documentElement
-  const scrollElement = getScrollElement(node)
-  const eventTarget = isDocumentScroll ? window : node
-
-  // Cache DOM references and expensive calculations
-  let cachedScrollHeight = 0
-  let cachedClientHeight = 0
-
-  // Initialize cache and start observing for changes
-  updateCache()
-  const cacheObserver = resizeObserver(scrollElement, {
-    callback: updateCache,
-  })
-
-  eventTarget.addEventListener('scroll', throttledObserve, { passive: true })
-
-  function throttledObserve() {
-    rafId = requestAnimationFrame(observe)
-  }
-
-  function updateCache() {
-    cachedScrollHeight = scrollElement.scrollHeight
-    cachedClientHeight = scrollElement.clientHeight
-  }
-
-  function observe() {
-    const scrollTop = scrollElement.scrollTop
-
-    // Skip if scroll position hasn't changed meaningfully
-    if (Math.abs(scrollTop - prevScrollTop) < 1) return
-
-    const scrollDirection = scrollTop > prevScrollTop ? 'down' : 'up'
-    const maxScroll = Math.max(1, cachedScrollHeight - cachedClientHeight)
-    const scrollPercent = Math.min(1, Math.max(0, scrollTop / maxScroll))
-
-    // Check threshold crossing (e.g., 75% ± tolerance)
-    const thresholdMin = threshold - tolerance / 2
-    const thresholdMax = threshold + tolerance / 2
-    const wasInThreshold =
-      prevScrollPercent >= thresholdMin && prevScrollPercent <= thresholdMax
-    const isInThreshold =
-      scrollPercent >= thresholdMin && scrollPercent <= thresholdMax
-    const hasEnteredThreshold =
-      !wasInThreshold && isInThreshold && (!once || !thresholdFired)
-
-    if (hasEnteredThreshold && once) {
-      thresholdFired = true
-    }
-
-    // Prepare common data for all callbacks
-    const callbackData = {
-      scrollTop,
-      scrollDirection,
-      scrollPercent,
-      directionChanged: scrollDirection !== prevScrollDirection,
-      hasEnteredThreshold,
-      isInThreshold,
-    }
-
-    // Call specific callbacks
-    if (typeof callback === 'function') {
-      callback(callbackData)
-    }
-
-    // Only fire direction callbacks when direction actually changes
-    if (scrollDirection !== prevScrollDirection) {
-      if (scrollDirection === 'down' && typeof onScrollDown === 'function') {
-        onScrollDown(callbackData)
-      }
-      if (scrollDirection === 'up' && typeof onScrollUp === 'function') {
-        onScrollUp(callbackData)
-      }
-    }
-
-    // Fire threshold callback when entering threshold zone
-    if (hasEnteredThreshold && typeof onEnterThreshold === 'function') {
-      onEnterThreshold(callbackData)
-    }
-
-    prevScrollTop = scrollTop
-    prevScrollPercent = scrollPercent
-    prevScrollDirection = scrollDirection
-  }
-
-  return {
-    destroy() {
-      eventTarget.removeEventListener('scroll', throttledObserve)
-      if (rafId) cancelAnimationFrame(rafId)
-      cacheObserver.destroy()
-    },
-  }
-}

package/src/dom/pkce.js

@@ -1,34 +0,0 @@
-// Browser only
-// Check the node version for usage in servers
-import { randomString } from './random-string.js'
-
-export async function PKCE() {
-  const codeVerifier = await randomString()
-  const codeChallenge = await getCodeChallenge(codeVerifier)
-
-  return {
-    state: await randomString(),
-    code_verifier: codeVerifier,
-    code_challenge: codeChallenge,
-    code_challenge_method: 'S256',
-  }
-}
-
-/**
- * Generates code challenge in browser
- * @param {string} verifier
- * @returns promise
- */
-async function getCodeChallenge(verifier) {
-  // Hash the code verifier with SHA-256
-  const encoder = new TextEncoder()
-  const data = encoder.encode(verifier)
-  const hashed = await window.crypto.subtle.digest('SHA-256', data)
-
-  // Base64url encode the hash
-  return window
-    .btoa(String.fromCharCode.apply(null, new Uint8Array(hashed)))
-    .replace(/\+/g, '-')
-    .replace(/\//g, '_')
-    .replace(/=+$/, '')
-}

package/src/dom/query-params.js

@@ -1,14 +0,0 @@
-// ========================
-// Query Params
-// ========================
-export const queryParams = {
-  get(key) {
-    const searchParams = new URLSearchParams(location.search)
-    return searchParams.get(key)
-  },
-
-  stringify(params) {
-    const searchParams = new URLSearchParams(location.search)
-    return searchParams.toString()
-  },
-}

package/src/dom/random-string.js

@@ -1,18 +0,0 @@
-/**
- * Generates a random string.
- * Ensures first character is a letter so it can be used in HTML ids and classes
- * This can actually be used everywhere, not just in the browser.
- */
-export function randomString(length = 10) {
-  const firstLetter = String.fromCharCode(65 + Math.floor(Math.random() * 26))
-  const others = Math.random()
-    .toString(36)
-    .substring(2, 2 + length - 1)
-
-  return firstLetter + others
-}
-
-// For browsers only
-export function uuid() {
-  return crypto.randomUUID()
-}

package/src/dom/random-string.test.js

@@ -1,13 +0,0 @@
-import { describe, expect, it } from 'vitest'
-import { randomString } from './random-string.js'
-
-describe('randomString', () => {
-  it('should generate a random string', () => {
-    const str = randomString()
-    expect(str).toBeDefined()
-    expect(str.length).toBe(10)
-
-    // Ensure the first character is a letter
-    expect(str[0]).toMatch(/[a-zA-Z]/)
-  })
-})

package/src/dom/sanitize.js

@@ -1,16 +0,0 @@
-import DOMPurify from 'dompurify'
-import { sanitize as sanitizeLib } from '../lib/form/sanitize.js'
-
-// Need to test if possible.
-// We can't test browser on node. So, unless we do like playwright or some form of browser testing, we can't actually verify this works every time.
-// Node version works already.
-/**
- * Sanitizes values using DOMPurify
- * @param {*} value - Value to sanitize (string, array, or object)
- * @param {Object} [options={}] - DOMPurify options
- * @returns {*} Sanitized value
- * @throws {Error} If input is a string but DOMPurify fails
- */
-export function sanitize(value, options = {}) {
-  return sanitizeLib(value, { sanitizer: DOMPurify.sanitize, ...options })
-}

package/src/dom/session-store.js

@@ -1,29 +0,0 @@
-// ========================
-// Session Storage
-// ========================
-export const sessionStore = {
-  get(key) {
-    const value = sessionStorage.getItem(key)
-    if (!value) return
-
-    try {
-      // Returns an object if stored value is JSON
-      return JSON.parse(value)
-    } catch (error) {
-      // Returns plain string if stored value is not JSON
-      return value
-    }
-  },
-
-  set(key, value) {
-    if (typeof value === 'string') {
-      sessionStorage.setItem(key, value)
-    } else {
-      sessionStorage.setItem(key, JSON.stringify(value))
-    }
-  },
-
-  remove(key) {
-    sessionStorage.removeItem(key)
-  },
-}

package/src/dom/spam-prevention.js

@@ -1,40 +0,0 @@
-/**
- * Enhances a form element with spam detection capabilities
- * @param {HTMLFormElement} form - The form element to enhance
- * @param {Object} [options] - Configuration options
- * @param {string} [options.honeypotField] - Name of the honeypot field (default: 'hp')
- * @param {number} [options.honeypotDuration] - Minimum time in ms for legitimate form fill (default: 2000)
- * @returns {void}
- */
-export function preventSpam(
-  form,
-  { honeypotField = 'hp', honeypotDuration = 2000 } = {},
-) {
-  const startTime = Date.now()
-  let hasInteraction = false
-
-  function checkForInteraction() {
-    hasInteraction = true
-  }
-
-  const events = ['keydown', 'mousemove', 'touchstart', 'click']
-  events.forEach(event => {
-    form.addEventListener(event, checkForInteraction, { once: true })
-  })
-
-  form.containsSpam = function () {
-    const fillTime = Date.now() - startTime
-    const isTooFast = fillTime < honeypotDuration
-    /** @type {HTMLInputElement | null} */
-    const honeypotInput = form.querySelector(`[name="${honeypotField}"]`)
-    const hasHoneypotValue = honeypotInput?.value?.trim()
-    const noInteraction = !hasInteraction
-
-    // Clean up event listeners after use
-    events.forEach(event =>
-      form.removeEventListener(event, checkForInteraction),
-    )
-
-    return isTooFast || !!hasHoneypotValue || noInteraction
-  }
-}

package/src/dom/trap-focus.js

@@ -1,70 +0,0 @@
-import { getFocusableElements } from './focusable.js'
-import { isShiftTab, isTab } from './keyboard.js'
-
-/**
- * Traps focus within a set of focusable elements, creating a circular tab order
- * @param {Object} params
- * @param {KeyboardEvent} params.event - The keyboard event to handle
- * @param {import('./focusable.js').Focusables} params.focusables - Object containing focusable elements
- */
-export function trapFocus({ event, focusables }) {
-  if (event.key !== 'Tab') return
-  if (isTab(event) && document.activeElement === focusables.last) {
-    event.preventDefault()
-    focusables.first.focus()
-  }
-
-  // User presses shift + tab from the first focusable element.
-  // Redirects to the last focusable element.
-  if (isShiftTab(event) && document.activeElement === focusables.first) {
-    event.preventDefault()
-    focusables.last.focus()
-  }
-}
-
-/**
- * Manages focus behavior when tabbing through content, with options to control focus on exit
- * @param {Object} params
- * @param {KeyboardEvent} params.event - The keyboard event to handle
- * @param {HTMLElement} params.triggerNode - Element that triggered the focus trap
- * @param {HTMLElement} params.contentNode - Container element that holds focusable content
- * @param {import('./focusable.js').Focusables} params.focusables - Object containing focusable elements
- * @param {'next'|'trigger'} [params.tabOutFocus='next'] - Where to focus when tabbing out: 'next' element or back to trigger
- * @param {Function} [params.onLeave=()=>{}] - Callback when focus leaves content, receives 'forward' or 'back' direction
- */
-export function manageFocus({
-  event,
-  triggerNode,
-  contentNode,
-  focusables,
-  tabOutFocus = 'next', // 'trigger'
-  onLeave = function () {},
-}) {
-  const activeEl = document.activeElement
-
-  if (activeEl === contentNode && isShiftTab(event)) return backFocus()
-  if (activeEl === contentNode && focusables.length === 0 && isTab(event))
-    return nextFocus()
-
-  if (activeEl === focusables.last && isTab(event)) return nextFocus()
-  if (activeEl === focusables.first && isShiftTab(event)) return backFocus()
-
-  function backFocus() {
-    event.preventDefault()
-    triggerNode.focus()
-    onLeave('back')
-  }
-
-  function nextFocus() {
-    if (tabOutFocus === 'trigger') triggerNode.focus()
-    if (tabOutFocus === 'next') {
-      event.preventDefault()
-      const DOMFocusables = getFocusableElements().keyboard
-      const index = DOMFocusables.findIndex(e => e === triggerNode)
-      const next = DOMFocusables[index + 1]
-      if (next) next.focus()
-      else triggerNode.focus()
-    }
-    onLeave('forward')
-  }
-}

package/src/dom/ui/aria-current.js

@@ -1,20 +0,0 @@
-export function markActiveAnchorIn(container, anchorType = 'page') {
-  if (!container) return
-
-  const { pathname } = window.location
-  const element = container.querySelector(`[href="${pathname}"]`)
-  if (!element) return
-
-  // Mark the active element
-  element.setAttribute('aria-current', 'page')
-  return element
-}
-
-export function scrollToElement(
-  element,
-  { scrollBehaviour = 'instant', scrollMargin = '3rem' } = {},
-) {
-  if (!element) return
-  element.style.scrollMarginTop = scrollMargin
-  element.scrollIntoView({ behavior: scrollBehaviour })
-}

package/src/dom/ui/inconsistent-button-fix.js

@@ -1,20 +0,0 @@
-/**
- * Fixes inconsistent button focus behavior across browsers.
- * 
- * In some browsers (like Firefox), clicking a button doesn't focus it.
- * This function ensures buttons are focused when clicked, making behavior consistent.
- * 
- * @see {@link https://zellwk.com/blog/inconsistent-button-behavior/|Source}
- * @example
- * // Add the fix to your app
- * inconsistentButtonFix()
- */
-export function inconsistentButtonFix() {
-  // https://zellwk.com/blog/inconsistent-button-behavior/
-  /** @param {MouseEvent} event */
-  document.addEventListener('click', event => {
-    if (event.target instanceof HTMLButtonElement) {
-      event.target.focus()
-    }
-  })
-}

package/src/dom/ui/index.js

@@ -1,4 +0,0 @@
-export * from './aria-current.js'
-export * from './inconsistent-button-fix.js'
-export * from './scroll-container.js'
-export * from './traverse-and-scramble.js'

package/src/dom/ui/scroll-container.js

@@ -1,25 +0,0 @@
-export function findScrollContainer(element, direction = 'both') {
-  if (!element) return
-
-  let parent = element.parentElement
-  while (parent) {
-    const { overflow, overflowX, overflowY } = getComputedStyle(parent)
-
-    if (direction === 'both') {
-      if (overflow.includes('auto') || overflow.includes('scroll'))
-        return parent
-    }
-
-    if (direction === 'horizontal') {
-      if (overflowX === 'auto' || overflowX === 'scroll') return parent
-    }
-
-    if (direction === 'vertical') {
-      if (overflowY === 'auto' || overflowY === 'scroll') return parent
-    }
-
-    parent = parent.parentElement
-  }
-
-  return document.documentElement
-}

package/src/dom/ui/traverse-and-scramble.js

@@ -1,61 +0,0 @@
-/**
- * Traverses a DOM node and scrambles its text content, excluding specified elements.
- * Useful for creating placeholder/loading states or privacy features.
- * 
- * @param {Element|ChildNode} node - The root element or node to start traversal from
- * @param {Object} [options] - Options for traversal
- * @param {string[]} [options.excludes=[]] - Array of CSS selectors to exclude from scrambling
- * @example
- * // Scramble all text in a container
- * traverseAndScramble(document.querySelector('.container'))
- * 
- * // Scramble text but exclude certain elements
- * traverseAndScramble(document.body, {
- *   excludes: ['.no-scramble', '[data-no-scramble]']
- * })
- */
-export function traverseAndScramble(node, { excludes = [] } = {}) {
-  // Check if the current node matches any of the exclude selectors
-  if (node instanceof Element && excludes.some(selector => node.matches(selector))) {
-    return // Skip this node and its children
-  }
-
-  node.childNodes.forEach(child => {
-    if (child.nodeType === 3) {
-      // Node.TEXT_NODE
-      child.nodeValue = scrambleText(child.nodeValue)
-    } else if (child.nodeType === 1 && child instanceof Element) {
-      // Node.ELEMENT_NODE
-      traverseAndScramble(child, { excludes }) // Recurse into child elements with excludes
-    }
-  })
-}
-
-/**
- * Scrambles text by replacing alphanumeric characters with random ones.
- * Preserves case, punctuation, and other symbols.
- * 
- * @param {string} text - The text to scramble
- * @returns {string} The scrambled text
- * @private
- * @example
- * scrambleText('Hello123!') // Returns something like 'Xk9mP2q!'
- */
-function scrambleText(text) {
-  return text
-    .split('')
-    .map(char => {
-      if (/^[A-Za-z0-9]$/.test(char)) {
-        const randomCharCode =
-          Math.random() < 26 / 36
-            ? Math.floor(Math.random() * 26) +
-              (char === char.toUpperCase() ? 65 : 97) // A-Z
-            : Math.floor(Math.random() * 10) + 48 // 0-9
-        return String.fromCharCode(randomCharCode)
-      } else {
-        // Keep punctuations and other symbols intact
-        return char
-      }
-    })
-    .join('')
-}

package/src/lib/arrays/index.js

@@ -1,6 +0,0 @@
-export * from './item-position.js'
-export * from './join.js'
-export * from './shuffle.js'
-export * from './sort.js'
-export * from './split-array.js'
-export * from './unique.js'