@splendidlabz/utils 1.11.2 → 1.11.4

package/src/dom/events.js

@@ -1,71 +0,0 @@
-/**
- * @typedef {Object} EventListener
- * @property {Element} node - The DOM element to attach the event listener to
- * @property {string} event - The event type (e.g., 'click', 'keydown')
- * @property {EventListenerOrEventListenerObject} handler - The event handler function
- */
-
-/**
- * @typedef {Object} ListenerManager
- * @property {EventListener[]} list - Array of current event listeners
- * @property {function(EventListener): void} add - Add a new event listener
- * @property {function(EventListener): void} remove - Remove an event listener
- * @property {function(): void} clear - Remove all event listeners
- */
-
-/**
- * @typedef {Object} CustomEventOptions
- * @property {boolean} [bubbles=false] - Whether the event bubbles up through the DOM
- * @property {boolean} [cancelable=false] - Whether the event can be canceled
- * @property {boolean} [composed=false] - Whether the event will trigger listeners outside of a shadow root
- */
-
-/**
- * Adds multiple event listeners to their respective DOM elements
- * @param {EventListener[]} listeners - Array of listener objects
- */
-export function addListeners(listeners) {
-  listeners.forEach(({ node, event, handler }) => {
-    node.addEventListener(event, handler)
-  })
-}
-
-/**
- * Removes multiple event listeners from their respective DOM elements
- * @param {EventListener[]} listeners - Array of listener objects
- */
-export function removeListeners(listeners) {
-  listeners.forEach(({ node, event, handler }) => {
-    node.removeEventListener(event, handler)
-  })
-}
-
-/**
- * Dispatches a custom event from a DOM node
- * @param {Element} node - The DOM element to dispatch the event from
- * @param {string} eventName - The name of the custom event
- * @param {*} detail - The detail data to include with the event
- * @param {CustomEventOptions} [options={}] - Additional event options
- */
-export function dispatchEvent(node, eventName, detail, options = {}) {
-  node.dispatchEvent(
-    new CustomEvent(eventName, {
-      ...options,
-      detail,
-    }),
-  )
-}
-
-/**
- * Creates a new CustomEvent with updated properties from an existing event
- * @param {Event} event - The original event object
- * @param {Object} updates - Properties to update in the new event
- * @return {CustomEvent} A new CustomEvent with updated properties
- */
-export function updateEvent(event, updates) {
-  const { type, ...rest } = event
-  return new CustomEvent(event.type, {
-    ...rest,
-    ...updates,
-  })
-}

package/src/dom/focusable.js

@@ -1,165 +0,0 @@
-/**
- * @typedef {Object} Focusables
- * @property {number} length - Number of keyboard focusable elements
- * @property {Array} all - All focusable elements that are visible and enabled
- * @property {Array} keyboard - Elements that can be focused via keyboard (tabIndex > -1)
- * @property {Array} keyboardOnly - Alias for keyboard focusable elements
- * @property {HTMLElement|null} first - First keyboard focusable element
- * @property {HTMLElement|null} last - Last keyboard focusable element
- * @property {function(number): HTMLElement|null} next - Get next focusable element after the given index
- * @property {function(number): HTMLElement|null} prev - Get previous focusable element before the given index
- */
-
-/**
- * Gets all focusable elements within a container and provides methods to navigate between them.
- * This is useful for implementing keyboard navigation, focus trapping, and accessibility features.
- * 
- * @param {HTMLElement} [container=document.body] - The container element to search within. Only elements inside this container will be included.
- * @returns {Focusables} Object containing focusable elements and navigation methods
- * @example
- * // Get focusable elements in a modal
- * const modal = document.querySelector('.modal')
- * const focusable = getFocusableElements(modal)
- * 
- * // Get all focusable elements in document
- * const allFocusable = getFocusableElements()
- * 
- * // Focus the first element when modal opens
- * focusable.first?.focus()
- * 
- * // Handle tab key to trap focus
- * modal.addEventListener('keydown', e => {
- *   if (e.key === 'Tab') {
- *     e.preventDefault()
- *     const currentIndex = focusable.keyboard.indexOf(document.activeElement)
- *     const nextElement = e.shiftKey 
- *       ? focusable.prev(currentIndex) 
- *       : focusable.next(currentIndex)
- *     nextElement?.focus()
- *   }
- * })
- */
-export function getFocusableElements(container = document.body) {
-  return {
-    /**
-     * Gets the number of keyboard focusable elements.
-     * This is useful for checking if there are any focusable elements
-     * before attempting to focus them.
-     * 
-     * @returns {number} The number of keyboard focusable elements
-     */
-    get length() {
-      return this.keyboard.length
-    },
-
-    /**
-     * Gets all focusable elements within the container that are visible and enabled.
-     * This includes elements that can be focused via mouse or programmatically,
-     * but may not be keyboard focusable.
-     * 
-     * Elements are considered focusable if they:
-     * - Are not disabled
-     * - Are not hidden
-     * - Are not display:none
-     * 
-     * @returns {HTMLElement[]} Array of focusable elements that are visible and enabled
-     */
-    get all() {
-      const elements = Array.from(
-        container.querySelectorAll(
-          `a, 
-            button, 
-            input, 
-            textarea, 
-            select, 
-            details, 
-            iframe, 
-            embed, 
-            object, 
-            summary, 
-            dialog, 
-            audio[controls], 
-            video[controls], 
-            [contenteditable], 
-            [tabindex]
-          `,
-        ),
-      )
-      
-      // @ts-ignore - we check instanceof HTMLElement at runtime
-      return elements.filter(el => {
-        if (el.hasAttribute('disabled')) return false
-        if (el.hasAttribute('hidden')) return false
-        if (window.getComputedStyle(el).display === 'none') return false
-        return true
-      })
-    },
-
-    /**
-     * Gets elements that can be focused via keyboard (tabIndex > -1).
-     * These are the elements that will be focused when using the Tab key.
-     * 
-     * @returns {HTMLElement[]} Array of keyboard focusable elements
-     */
-    get keyboard() {
-      return this.all.filter(el => el instanceof HTMLElement && el.tabIndex > -1)
-    },
-
-    /**
-     * Alias for keyboard focusable elements.
-     * This is provided for semantic clarity in certain contexts.
-     * 
-     * @returns {HTMLElement[]} Array of keyboard focusable elements
-     */
-    get keyboardOnly() {
-      return this.keyboard
-    },
-
-    /**
-     * Gets the first keyboard focusable element.
-     * This is useful for setting initial focus when opening a modal or dialog.
-     * 
-     * @returns {HTMLElement|null} The first focusable element or null if none exist
-     */
-    get first() {
-      return this.keyboard[0] || null
-    },
-
-    /**
-     * Gets the last keyboard focusable element.
-     * This is useful for focus trapping when using Shift+Tab.
-     * 
-     * @returns {HTMLElement|null} The last focusable element or null if none exist
-     */
-    get last() {
-      return this.keyboard[this.length - 1] || null
-    },
-
-    /**
-     * Gets the next focusable element after the given index.
-     * This is useful for implementing custom tab order or focus management.
-     * 
-     * @param {number} index - The current element's index in the keyboard focusable array
-     * @returns {HTMLElement|null} The next focusable element or null if none exists
-     */
-    next(index) {
-      return this.keyboard[index + 1] || null
-    },
-
-    /**
-     * Gets the previous focusable element before the given index.
-     * This is useful for implementing custom tab order or focus management.
-     * 
-     * @param {number} index - The current element's index in the keyboard focusable array
-     * @returns {HTMLElement|null} The previous focusable element or null if none exists
-     */
-    prev(index) {
-      return this.keyboard[index - 1] || null
-    },
-  }
-}
-
-// Alias of getFocusableElements
-export function Focusable(container = document.body) {
-  return getFocusableElements(container)
-}

package/src/dom/font-size.js

@@ -1,40 +0,0 @@
-import { splitUnit } from '../lib/numbers/index.js'
-
-export function getUnit(value) {
-  const [, unit] = splitUnit(value)
-  return unit
-}
-
-export function rem(multiple = 1) {
-  const value = parseFloat(getComputedStyle(document.body)['font-size'])
-  return Math.round(value * multiple)
-}
-
-export function em(element = document.body, multiple = 1) {
-  const value = parseFloat(getComputedStyle(element)['font-size'])
-  return Math.round(value * multiple)
-}
-
-export function rlh(multiple = 1) {
-  const lineHeight = parseFloat(getComputedStyle(document.body)['line-height'])
-  return Math.round(lineHeight * multiple)
-}
-
-export function lh(element = document.body, multiple = 1) {
-  const lineHeight = getComputedStyle(element)['line-height']
-  const value = parseFloat(lineHeight)
-  return Math.round(value * multiple)
-}
-
-export function toPx(value, element = null) {
-  const [numeric, unit] = splitUnit(value)
-  let finalValue = 0
-
-  if (unit === 'rem') finalValue = rem(numeric)
-  if (unit === 'em') finalValue = em(element, numeric)
-  if (unit === 'lh') finalValue = lh(element, numeric)
-  if (unit === 'px') finalValue = numeric
-  if (!unit) finalValue = numeric // Default to px offsets
-
-  return finalValue
-}

package/src/dom/get-element.js

@@ -1,176 +0,0 @@
-// Returns the target HTMLElement.
-// If the selector is already an HTMLElement, it will return the selector itself.
-// Otherwise, it will return the first element that matches the selector.
-
-/**
- * List of Astro-specific node names that need special handling
- * @type {string[]}
- */
-const astroNodes = ['ASTRO-SLOT', 'ASTRO-ISLAND']
-
-/**
- * Gets the type of a DOM node
- * @param {Node|NodeList|Array} node - The node to check
- * @returns {'element'|'nodelist'|'array'|undefined} The type of the node
- */
-export function getNodeType(node) {
-  if (node instanceof Element) return 'element'
-  if (node instanceof NodeList) return 'nodelist'
-  if (Array.isArray(node)) return 'array'
-}
-
-/**
- * Gets an element from a selector or returns the element if it's already an Element
- * @param {string|Element} selector - CSS selector or Element
- * @returns {Element|undefined} The matching element or undefined if not found
- * 
- * @example
- * // Get element by selector
- * const button = getElement('.button')
- * 
- * // Pass through Element
- * const element = document.querySelector('.button')
- * const sameElement = getElement(element) // Returns element directly
- */
-export function getElement(selector) {
-  if (!selector) return
-  if (selector instanceof Element) return selector
-  return document.querySelector(selector)
-}
-
-/**
- * Gets all child elements of a node, handling Astro slots
- * @param {Element} node - The parent node
- * @returns {Element[]} Array of child elements
- * 
- * @example
- * // Get children of a div
- * const children = getChildrenElements(div)
- * 
- * // Works with Astro slots
- * const slotChildren = getChildrenElements(astroSlot)
- */
-export function getChildrenElements(node) {
-  let children = node.children
-
-  // Compensate for Astro Slots
-  if (children[0]?.nodeName === 'ASTRO-SLOT') children = children[0].children
-  return Array.from(children)
-}
-
-/**
- * Gets the parent element, skipping Astro-specific nodes
- * @param {Element} element - The element to get the parent of
- * @returns {Element|null} The parent element, or null if no parent exists
- * 
- * @example
- * // Get parent, skipping Astro slots
- * const parent = getParentElement(element)
- */
-export function getParentElement(element) {
-  const parent = element.parentElement
-  if (astroNodes.includes(parent.nodeName)) return getParentElement(parent)
-  return parent
-}
-
-/**
- * Gets all sibling elements of an element (excluding the element itself)
- * @param {Element} element - The element to get siblings of
- * @returns {Element[]} Array of sibling elements
- * 
- * @example
- * // Get all siblings of an element
- * const siblings = getSiblingElements(element)
- */
-export function getSiblingElements(element) {
-  return Array.from(element.parentElement.children).filter(
-    child => child !== element
-  )
-}
-
-/**
- * Gets the index of an element among its siblings
- * @param {Element} element - The element to get the index of
- * @returns {number} The index of the element (0-based)
- * 
- * @example
- * // Get position of element among siblings
- * const index = getSelfIndex(element)
- */
-export function getSelfIndex(element) {
-  return Array.from(element.parentElement.children).indexOf(element)
-}
-
-/**
- * Checks if an element is an ancestor of another element
- * @param {Element} ancestor - The potential ancestor element
- * @param {Element} element - The element to check
- * @param {Object} [options] - Options for the search
- * @param {number} [options.searchLevels=0] - Number of levels to search up, 0 for unlimited
- * @returns {boolean} True if ancestor is an ancestor of element
- * 
- * @example
- * // Check if div is an ancestor of button
- * const isParent = isAncestor(div, button)
- * 
- * // Check if div is an ancestor within 2 levels
- * const isCloseAncestor = isAncestor(div, button, { searchLevels: 2 })
- */
-export function isAncestor(ancestor, element, { searchLevels = 0 } = {}) {
-  if (ancestor === element) return true
-
-  let parent = element.parentElement
-  // Infinite Search
-  if (searchLevels === 0) {
-    while (parent) {
-      if (ancestor === parent) return true
-      parent = parent.parentElement
-    }
-  } else {
-    // Search X levels upwards
-    for (let i = 0; i < searchLevels; i++) {
-      if (ancestor === parent) return true
-      parent = parent.parentElement
-    }
-  }
-
-  return false
-}
-
-/**
- * Gets ancestor elements with their siblings, optionally limiting the search depth.
- * Useful for finding the nearest ancestor that has siblings.
- * 
- * @param {Element} element - The element to start searching from
- * @param {Object} [options] - Options for the search
- * @param {number|boolean} [options.limit=false] - Number of levels to search up, or false for unlimited
- * @returns {Element[]|null} Array of sibling elements, or null if none found
- * 
- * @example
- * // Get siblings of nearest ancestor that has siblings
- * const ancestorSiblings = getAncestorWithSiblings(element)
- * 
- * // Search up to 2 levels
- * const limitedSiblings = getAncestorWithSiblings(element, { limit: 2 })
- */
-export function getAncestorWithSiblings(element, { limit = false } = {}) {
-  const ancestor = element.parentElement
-  const siblings = getSiblingElements(ancestor)
-
-  // Found
-  if (siblings.length) return siblings
-
-  // No more ancestors
-  if (!ancestor) return null
-
-  // Unlimited upwards search
-  if (limit === false) return getAncestorWithSiblings(ancestor)
-
-  // Limited search
-  if (typeof limit === 'number' && limit > 0) {
-    return getAncestorWithSiblings(ancestor, { limit: limit - 1 })
-  }
-
-  // Limit reached, end search
-  if (limit === 0) return null
-}

package/src/dom/hash.js

@@ -1,9 +0,0 @@
-export async function sha256Hash(string) {
-  const utf8 = new TextEncoder().encode(string)
-  const hashBuffer = await crypto.subtle.digest('SHA-256', utf8)
-  const hashArray = Array.from(new Uint8Array(hashBuffer))
-  const hashHex = hashArray
-    .map(bytes => bytes.toString(16).padStart(2, '0'))
-    .join('')
-  return hashHex
-}

package/src/dom/index.js

@@ -1,23 +0,0 @@
-export * from './accessibility.js'
-export * from './actions/index.js'
-export * from './bounding-box.js'
-export * from './clipboard.js'
-export * from './cookie.js'
-export * from './css-vars.js'
-export * from './events.js'
-export * from './focusable.js'
-export * from './font-size.js'
-export * from './get-element.js'
-export * from './hash.js'
-export * from './keyboard.js'
-export * from './local-store.js'
-export * from './media.js'
-export * from './observers/index.js'
-export * from './pkce.js'
-export * from './query-params.js'
-export * from './random-string.js'
-export * from './sanitize.js'
-export * from './session-store.js'
-export * from './spam-prevention.js'
-export * from './trap-focus.js'
-export * from './ui/index.js'

package/src/dom/keyboard.js

@@ -1,44 +0,0 @@
-/**
- * Event is Tab (without shift)
- * @param {KeyboardEvent} event - The keyboard event object
- * @returns {boolean}
- */
-export function isTab(event) {
-  return !event.shiftKey && event.key === 'Tab'
-}
-
-/**
- * Event is shift + Tab
- * @param {KeyboardEvent} event - The keyboard event object
- * @returns {boolean}
- */
-export function isShiftTab(event) {
-  return event.shiftKey && event.key === 'Tab'
-}
-
-/**
- * Matches both Tab and Shift+Tab
- * @param {string} key - The keyboard key to check
- * @returns {boolean} Whether the key is Tab
- */
-export function isTabKey(key) {
-  return key === 'Tab'
-}
-
-/**
- * Event is an arrow key
- * @param {string} key - The keyboard key to check
- * @returns {boolean} Whether the key is an arrow key (Up, Down, Left, Right)
- */
-export function isArrowKey(key) {
-  return ['ArrowUp', 'ArrowDown', 'ArrowLeft', 'ArrowRight'].includes(key)
-}
-
-/**
- * Event is Escape key
- * @param {string} key - The keyboard key to check
- * @returns {boolean} Whether the key is Escape
- */
-export function isEscapeKey(key) {
-  return key === 'Escape'
-}

package/src/dom/local-store.js

@@ -1,66 +0,0 @@
-// ========================
-// Local Storage
-// ========================
-
-/**
- * Utility object for managing localStorage operations with JSON support
- * @namespace localStore
- */
-export const localStore = {
-  /**
-   * Retrieves a value from localStorage
-   * @param {string} key - The key to retrieve from localStorage
-   * @returns {any} The stored value. Returns parsed JSON if the value was stored as JSON. Returns the original string if not JSON, or undefined if key doesn't exist
-   */
-  get(key) {
-    const value = localStorage.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
-    }
-  },
-
-  /**
-   * Stores a value in localStorage
-   * @param {string} key - The key to store the value under
-   * @param {any} value - The value to store. Objects will be stringified to JSON
-   */
-  set(key, value) {
-    if (typeof value === 'string') {
-      localStorage.setItem(key, value)
-    } else {
-      localStorage.setItem(key, JSON.stringify(value))
-    }
-  },
-
-  /**
-   * Stores multiple key-value pairs in localStorage
-   * @param {Object|Map} data - An object or Map containing key-value pairs to store
-   */
-  setMultiple(data) {
-    for (const [key, value] of Object.entries(data)) {
-      this.set(key, value)
-    }
-  },
-
-  /**
-   * Removes a value from localStorage
-   * @param {string} key - The key to remove from localStorage
-   */
-  remove(key) {
-    localStorage.removeItem(key)
-  },
-
-  /**
-   * Removes multiple keys from localStorage
-   * @param {string[]} keys - Array of keys to remove from localStorage
-   */
-  removeMultiple(keys) {
-    keys.forEach(key => this.remove(key))
-  },
-}

package/src/dom/media.js

@@ -1,30 +0,0 @@
-export async function imagesLoaded(node) {
-  const images = Array.from(node.querySelectorAll('img'))
-  const promises = images.map(img => {
-    return new Promise((resolve, reject) => {
-      if (img.complete) return resolve()
-      img.onload = resolve
-      img.onerror = e => {
-        // eslint-disable-next-line prefer-promise-reject-errors
-        reject('Image failed to load')
-      }
-    })
-  })
-  return Promise.all(promises)
-}
-
-export async function videosLoaded(node) {
-  const videos = Array.from(node.querySelectorAll('video'))
-  const promises = videos.map(video => {
-    return new Promise((resolve, reject) => {
-      if (video.readyState === 4) return resolve() // HAVE_ENOUGH_DATA
-      video.onloadedmetadata = resolve
-      video.onerror = reject
-    })
-  })
-  return Promise.all(promises)
-}
-
-export async function mediaLoaded(node) {
-  return Promise.all([imagesLoaded(node), videosLoaded(node)])
-}

package/src/dom/observers/index.js

@@ -1,4 +0,0 @@
-export * from './intersection-observer.js'
-export * from './mutation-observer.js'
-export * from './resize-observer.js'
-export * from './scroll-observer.js'

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

@@ -1,43 +0,0 @@
-import { dispatchEvent } from '../events.js'
-import { useObserverMethodOnTarget } from './observer.js'
-
-// See https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver/IntersectionObserver#options for options
-export function intersectionObserver(target, options = {}) {
-  const { callback, ...opts } = options
-  const observer = new IntersectionObserver(observerFn, opts)
-
-  useObserverMethodOnTarget(target, observer, 'observe')
-
-  function observerFn(entries) {
-    for (const entry of entries) {
-      if (callback) callback({ entry, entries, observer })
-      else dispatchEvent(target, 'intersect', { entry, entries, observer })
-    }
-  }
-
-  return {
-    observer,
-    observe(target) {
-      useObserverMethodOnTarget(target, observer, 'observe', options)
-    },
-
-    unobserve(target) {
-      useObserverMethodOnTarget(target, observer, 'unobserve')
-    },
-
-    takeRecords() {
-      return observer.takeRecords()
-    },
-
-    disconnect() {
-      // Take records before disconnecting.
-      const records = observer.takeRecords()
-      observer.disconnect()
-      if (records.length > 0) observerFn(records)
-    },
-
-    destroy() {
-      observer.disconnect()
-    },
-  }
-}