@splendidlabz/utils 1.5.0 → 1.6.0

package/dom/accessibility.js

@@ -1,23 +1,56 @@
-export function stopBodyScroll() {
-  const top = document.documentElement.scrollTop
+// export function stopBodyScroll(element) {
+//   if (!element) element = document.body
+//   const top = document.documentElement.scrollTop
+//   element.style.top = -1 * top + 'px'
+//   element.style.overflow = 'hidden'
+// }
 
-  element.style.top = -1 * top + 'px'
-  element.style.overflow = 'hidden'
-}
+// export function allowBodyScroll() {
+//   const top = parseFloat(document.body.style.top) * -1
+//   document.body.style.top = null
+//   document.body.style.overflow = null
+//   document.documentElement.scrollTop = top
+// }
 
-export function allowBodyScroll() {
-  const top = parseFloat(document.body.style.top) * -1
-  document.body.style.top = null
-  document.body.style.overflow = null
-  document.documentElement.scrollTop = top
+/**
+ * Checks if an element has an accessible name through label or aria-labelledby
+ * @param {string} [label] - The label text
+ * @param {string} [labelledBy] - The aria-labelledby value
+ * @returns {boolean} True if the element has an accessible name
+ */
+export function hasAccessibleName(label, labelledBy) {
+  if (label || labelledBy) return true
+  return false
 }
 
-export function inertOthers() {}
+/**
+ * Checks if an element has an accessible name and logs a warning/error if it doesn't
+ * @param {Object} [options] - Options for checking accessible name
+ * @param {string} [options.name] - The name of the element being checked
+ * @param {string} [options.ariaLabel] - The aria-label value
+ * @param {string} [options.ariaLabelledBy] - The aria-labelledby value
+ * @param {'warn'|'error'} [options.severity='warn'] - Severity level for the message
+ * @returns {boolean} True if the element has an accessible name
+ */
+export function checkForAccessibleName({
+  name,
+  ariaLabel,
+  ariaLabelledBy,
+  severity = 'warn',
+} = {}) {
+  if (ariaLabel || ariaLabelledBy) return true
 
-export function hasLabel(label, labelledBy) {
-  if (label || labelledBy) return true
+  const message = `${name} is missing an accessible name. Please provide an accessible name with 'aria-label' or 'aria-labelledby'.`
+  if (severity === 'warn') console.warn(message)
+  if (severity === 'error') console.error(message)
+  return false
 }
 
+/**
+ * Checks if an ARIA popup value is valid
+ * @param {string} value - The ARIA popup value to check
+ * @returns {boolean} True if the value is invalid
+ */
 export function isInvalidAriaPopup(value) {
   const allowedPopoupValues = ['dialog', 'menu', 'listbox', 'grid', 'tree']
   if (!allowedPopoupValues.includes(value)) return true

package/{actions → dom/actions}/index.js

@@ -1,5 +1,3 @@
 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/dom/actions/masonry.js

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

package/{actions → dom/actions}/prefer-horizontal-scroll.js

@@ -1,18 +1,18 @@
 import {
-  addListeners,
-  getCSSVar,
-  removeListeners,
-  setCSSVar,
-} from '../dom/index.js'
+    addListeners,
+    getCSSVar,
+    removeListeners,
+    setCSSVar,
+} from '../index.js'
 
-import { omitEmpty } from '../lib/index.js'
+import { omitEmpty } from '../../lib/index.js'
 
 const DEFAULT_OPTIONS = {
   scrollSnapDelay: 1000,
 }
 
 export function preferHorizontalScroll(node, props = {}) {
-  if (!node.classList.contains('scrollable-prefer-horizontal-scroll')) return
+  if (!node.classList.contains('scrollable-prefer-horizontal')) return
 
   const state = {
     origSnapType: null,
@@ -23,7 +23,7 @@ export function preferHorizontalScroll(node, props = {}) {
   const options = {
     ...DEFAULT_OPTIONS,
     ...omitEmpty({
-      scrollSnapDelay: getCSSVar(node, '--scrollSnapDelay'),
+      scrollSnapDelay: getCSSVar(node, '--scroll-snap-delay'),
     }),
     ...omitEmpty(props),
   }

package/{actions → dom/actions}/sticky.js

@@ -1,12 +1,9 @@
-import {
-  boundingBoxRelativeToAncestor,
-  findScrollContainer,
-} from '../dom/index.js'
-import { resizeObserver } from './resize-observer.js'
+import { boundingBoxRelativeToAncestor } from '../bounding-box.js'
+import { resizeObserver } from '../observers/resize-observer.js'
+import { findScrollContainer } from '../ui/scroll-container.js'
 
 export function sticky(node, props = {}) {
   const scrollContainer = findScrollContainer(node)
-
   let stickyTBLR = getComputedTBLR(node)
 
   const obs = resizeObserver(node, {

package/dom/bounding-box.js

@@ -1,6 +1,19 @@
 /**
- * Advanced boundincClientRect that contains information vertical and horizontal centers.
- * @param {HTMLElement} element
+ * Advanced boundingClientRect that contains information vertical and horizontal centers.
+ * @param {HTMLElement} element - The element to get the bounding box for
+ * @param {Object} [options] - Options for the bounding box calculation
+ * @param {boolean} [options.containsPadding=true] - Whether to include padding in the calculations
+ * @returns {Object} The bounding box object with additional center coordinates
+ * @property {number} x - The x coordinate
+ * @property {number} y - The y coordinate
+ * @property {number} width - The width
+ * @property {number} height - The height
+ * @property {number} top - The top coordinate
+ * @property {number} right - The right coordinate
+ * @property {number} bottom - The bottom coordinate
+ * @property {number} left - The left coordinate
+ * @property {number} xCenter - The horizontal center coordinate
+ * @property {number} yCenter - The vertical center coordinate
  */
 export function boundingBox(element, { containsPadding = true } = {}) {
   const box = element.getBoundingClientRect()
@@ -12,11 +25,11 @@ export function boundingBox(element, { containsPadding = true } = {}) {
   // 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)
+    // Parse padding values immediately to numbers
+    const paddingTop = parseFloat(style.paddingTop)
+    const paddingRight = parseFloat(style.paddingRight)
+    const paddingBottom = parseFloat(style.paddingBottom)
+    const paddingLeft = parseFloat(style.paddingLeft)
 
     ret.x = ret.x + paddingLeft
     ret.y = ret.y + paddingTop
@@ -33,6 +46,21 @@ export function boundingBox(element, { containsPadding = true } = {}) {
   return ret
 }
 
+/**
+ * Gets the bounding box of an element relative to its ancestor
+ * @param {Object} params - Parameters for the calculation
+ * @param {HTMLElement} params.element - The element to get the bounding box for
+ * @param {HTMLElement} [params.ancestorElement] - The ancestor element to calculate position relative to. Defaults to parent element
+ * @returns {Object} The relative bounding box with center coordinates
+ * @property {number} top - Distance from ancestor's top
+ * @property {number} right - Distance from ancestor's right
+ * @property {number} bottom - Distance from ancestor's bottom
+ * @property {number} left - Distance from ancestor's left
+ * @property {number} width - The width
+ * @property {number} height - The height
+ * @property {number} xCenter - The horizontal center coordinate relative to ancestor
+ * @property {number} yCenter - The vertical center coordinate relative to ancestor
+ */
 export function boundingBoxRelativeToAncestor({ element, ancestorElement }) {
   ancestorElement = ancestorElement || element.parentElement
 

package/dom/cookie.js

@@ -8,15 +8,16 @@ export const cookies = {
   },
 }
 
-/**
- * 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]
+  if (!match) return null
+  const decoded = decodeURIComponent(match[2])
+
+  try {
+    return JSON.parse(decoded)
+  } catch (e) {
+    return decoded
+  }
 }
 
 // By Copilot. Needs testing before confirmation.

package/dom/css-vars.js

@@ -1,5 +1,13 @@
 import { getElement } from './get-element.js'
 
+export function getCSSValue(element, prop) {
+  return getCSSVar(element, prop)
+}
+
+export function setCSSValue(element, prop, value) {
+  setCSSVar(element, prop, value)
+}
+
 export function getCSSVar(element, prop) {
   element = getElement(element)
   return getComputedStyle(element).getPropertyValue(prop)

package/dom/events.js

@@ -10,12 +10,13 @@ export function removeListeners(listeners) {
   })
 }
 
+// Dispatch a custom event from a Node.
 export function dispatchEvent(node, eventName, detail, options = {}) {
   node.dispatchEvent(
     new CustomEvent(eventName, {
       ...options,
       detail,
-    }),
+    })
   )
 }
 

package/dom/focusable.js

@@ -1,12 +1,72 @@
-export function Focusable(element = document) {
+/**
+ * @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() {
-      return [
-        ...element.querySelectorAll(
+      const elements = Array.from(
+        container.querySelectorAll(
           `a, 
             button, 
             input, 
@@ -22,35 +82,84 @@ export function Focusable(element = document) {
             video[controls], 
             [contenteditable], 
             [tabindex]
-          `
+          `,
         ),
-      ].filter(el => {
+      )
+      
+      // @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.tabIndex > -1)
+      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]
+      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]
+      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
+      return this.keyboard[index - 1] || null
     },
   }
 }
+
+// Alias of getFocusableElements
+export function Focusable(container = document.body) {
+  return getFocusableElements(container)
+}

package/dom/font-size.js

@@ -1,24 +1,35 @@
 import { splitUnit } from '../lib/index.js'
 
-/* globals getComputedStyle */
+export function getUnit(value) {
+  const [, unit] = splitUnit(value)
+  return unit
+}
+
 export function em(element = document.body, multiple = 1) {
-  const unit = parseFloat(getComputedStyle(element)['font-size'])
-  return Math.round(unit * multiple)
+  const value = parseFloat(getComputedStyle(element)['font-size'])
+  return Math.round(value * multiple)
 }
 
 export function rem(multiple = 1) {
-  const unit = parseFloat(getComputedStyle(document.body)['font-size'])
-  return Math.round(unit * multiple)
+  const value = parseFloat(getComputedStyle(document.body)['font-size'])
+  return Math.round(value * 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 [amt, unit] = splitUnit(value)
+  const [numeric, unit] = splitUnit(value)
   let finalValue = 0
 
-  if (unit === 'rem') finalValue = rem(amt)
-  if (unit === 'em') finalValue = em(element, amt)
-  if (unit === 'px') finalValue = amt
-  if (!unit) finalValue = amt // Default to px offsets
+  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/dom/get-element.js

@@ -2,12 +2,54 @@
 // 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 HTMLElement) return selector
+  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
 
@@ -16,16 +58,64 @@ export function getChildrenElements(node) {
   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,
+    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
 
@@ -47,6 +137,22 @@ export function isAncestor(ancestor, element, { searchLevels = 0 } = {}) {
   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)
@@ -61,9 +167,10 @@ export function getAncestorWithSiblings(element, { limit = false } = {}) {
   if (limit === false) return getAncestorWithSiblings(ancestor)
 
   // Limited search
-  if (limit > 0)
-    return getAncestorWithSiblings(ancestor, { searchLevels: limit - 1 })
+  if (typeof limit === 'number' && limit > 0) {
+    return getAncestorWithSiblings(ancestor, { limit: limit - 1 })
+  }
 
-  // Limit reached, end search.
+  // Limit reached, end search
   if (limit === 0) return null
 }

package/dom/index.js

@@ -1,4 +1,5 @@
 export * from './accessibility.js'
+export * from './actions/index.js'
 export * from './bounding-box.js'
 export * from './clipboard.js'
 export * from './cookie.js'
@@ -11,9 +12,11 @@ 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 './trap-focus.js'
 export * from './ui/index.js'