@splendidlabz/utils 1.5.0-beta.6 → 1.5.1

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/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/get-element.js

@@ -2,21 +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']
 
-// Returns the type of the node.
+/**
+ * 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
 
@@ -25,22 +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
   )
 }
 
+/**
+ * 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
 
@@ -62,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)
@@ -76,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/keyboard.js

@@ -1,7 +1,7 @@
 /**
  * Event is Tab (without shift)
- * @param {Object} event - The event object
- * @returns {Boolean}
+ * @param {KeyboardEvent} event - The keyboard event object
+ * @returns {boolean}
  */
 export function isTab(event) {
   return !event.shiftKey && event.key === 'Tab'
@@ -9,8 +9,8 @@ export function isTab(event) {
 
 /**
  * Event is shift + Tab
- * @param {Object} event - The event object
- * @returns {Boolean}
+ * @param {KeyboardEvent} event - The keyboard event object
+ * @returns {boolean}
  */
 export function isShiftTab(event) {
   return event.shiftKey && event.key === 'Tab'
@@ -18,8 +18,8 @@ export function isShiftTab(event) {
 
 /**
  * Matches both Tab and Shift+Tab
- * @param {Object} event - The event object
- * @returns
+ * @param {string} key - The keyboard key to check
+ * @returns {boolean} Whether the key is Tab
  */
 export function isTabKey(key) {
   return key === 'Tab'
@@ -27,13 +27,18 @@ export function isTabKey(key) {
 
 /**
  * Event is an arrow key
- * @param {Object} event - The event object
- * @returns {Boolean}
+ * @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/dom/observers/intersection-observer.js

@@ -17,7 +17,7 @@ export function intersectionObserver(target, options = {}) {
 
   return {
     observer,
-    observe(target, options) {
+    observe(target) {
       useObserverMethodOnTarget(target, observer, 'observe', options)
     },
 

package/dom/observers/mutation-observer.js

@@ -28,7 +28,7 @@ export function mutationObserver(target, options) {
 
   return {
     observer,
-    observe(target, options) {
+    observe(target) {
       useObserverMethodOnTarget(target, observer, 'observe', options)
     },
 

package/dom/observers/resize-observer.js

@@ -12,7 +12,7 @@ import { useObserverMethodOnTarget } from './observer.js'
  * @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...] - Additional options to pass to ResizeObserver.observe()
+ * @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
@@ -50,7 +50,7 @@ export function resizeObserver(target, options) {
   }
 
   return {
-    observe(target, options) {
+    observe(target) {
       useObserverMethodOnTarget(target, observer, 'observe', options)
     },
 

package/dom/sanitize.js

@@ -12,5 +12,5 @@ import { sanitize as sanitizeLib } from '../lib/form/sanitize.js'
  * @throws {Error} If input is a string but DOMPurify fails
  */
 export function sanitize(value, options = {}) {
-  return sanitizeLib(value, { sanitizer: DOMPurify.sanitize })
+  return sanitizeLib(value, { sanitizer: DOMPurify.sanitize, ...options })
 }

package/dom/trap-focus.js

@@ -1,6 +1,12 @@
-import { Focusable } from './focusable.js'
+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) {
@@ -16,7 +22,16 @@ export function trapFocus({ event, focusables }) {
   }
 }
 
-/* Returns focus back to trigger node when user is done tabbing through the content */
+/**
+ * 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,
@@ -44,7 +59,7 @@ export function manageFocus({
     if (tabOutFocus === 'trigger') triggerNode.focus()
     if (tabOutFocus === 'next') {
       event.preventDefault()
-      const DOMFocusables = Focusable().keyboard
+      const DOMFocusables = getFocusableElements().keyboard
       const index = DOMFocusables.findIndex(e => e === triggerNode)
       const next = DOMFocusables[index + 1]
       if (next) next.focus()

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

@@ -1,7 +1,19 @@
+/**
+ * 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/
-  document.addEventListener('click', function (event) {
-    if (event.target.matches('button')) {
+  /** @param {MouseEvent} event */
+  document.addEventListener('click', event => {
+    if (event.target instanceof HTMLButtonElement) {
       event.target.focus()
     }
   })

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

@@ -1,10 +1,22 @@
-// Adjusted function to take excludes as an argument
-export function traverseAndScramble(node, { excludes } = {}) {
+/**
+ * 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 (
-    excludes &&
-    excludes.some(selector => node.matches && node.matches(selector))
-  ) {
+  if (node instanceof Element && excludes.some(selector => node.matches(selector))) {
     return // Skip this node and its children
   }
 
@@ -12,14 +24,23 @@ export function traverseAndScramble(node, { excludes } = {}) {
     if (child.nodeType === 3) {
       // Node.TEXT_NODE
       child.nodeValue = scrambleText(child.nodeValue)
-    } else if (child.nodeType === 1) {
+    } else if (child.nodeType === 1 && child instanceof Element) {
       // Node.ELEMENT_NODE
       traverseAndScramble(child, { excludes }) // Recurse into child elements with excludes
     }
   })
 }
 
-// Function to scramble text remains unchanged
+/**
+ * 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('')

package/lib/arrays/join.js

@@ -1,10 +1,13 @@
 import { lastArrayItem } from './item-position.js'
 /**
- * Joins an array of strings with commas and a conjunction for the last item
- * @param {string[]} array - Array of strings to join
- * @param {Object} options - Join options
- * @param {string} options.conjunction - Conjunction to use ('and' or 'or')
+ * Joins an array with a conjunction (and/or)
+ * @param {Array<string>} array - Array of strings to join
+ * @param {Object} [options] - Options for joining
+ * @param {string} [options.conjunction='and'] - Conjunction to use ('and' or 'or')
  * @returns {string} Joined string
+ * @example
+ * joinWithConjunction(['a', 'b', 'c']) // 'a, b, and c'
+ * joinWithConjunction(['a', 'b'], { conjunction: 'or' }) // 'a or b'
  */
 export function joinWithConjunction(array, { conjunction = 'and' } = {}) {
   if (!array?.length) return ''