@splendidlabz/utils 1.5.0 → 1.5.1

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/local-store.js

@@ -1,7 +1,17 @@
 // ========================
 // 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
@@ -15,6 +25,11 @@ export const localStore = {
     }
   },
 
+  /**
+   * 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)
@@ -23,7 +38,29 @@ export const localStore = {
     }
   },
 
+  /**
+   * 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/dom/media.js

@@ -5,6 +5,7 @@ export async function imagesLoaded(node) {
       if (img.complete) return resolve()
       img.onload = resolve
       img.onerror = e => {
+        // eslint-disable-next-line prefer-promise-reject-errors
         reject('Image failed to load')
       }
     })

package/dom/observers/index.js

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

package/dom/observers/intersection-observer.js

@@ -0,0 +1,43 @@
+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()
+    },
+  }
+}

package/dom/observers/mutation-observer.js

@@ -0,0 +1,51 @@
+/* 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/dom/observers/observer.js

@@ -0,0 +1,18 @@
+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/dom/observers/resize-observer.js

@@ -0,0 +1,64 @@
+/* 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|NodeList|Element[]} target - The element(s) to observe. 
+ *   - If window is provided, document.body 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.body
+  useObserverMethodOnTarget(target, observer, 'observe', opts)
+
+  function observerFn(entries) {
+    for (const entry of entries) {
+      if (callback) callback({ entry, entries, observer })
+      else dispatchEvent(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/dom/sanitize.js

@@ -0,0 +1,16 @@
+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/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/eslint.config.js

@@ -0,0 +1,2 @@
+import config from '@splendidlabz/eslint-config'
+export default config

package/lib/arrays/index.js

@@ -1,62 +1,5 @@
-export function last(array, index) {
-  return index === array.length - 1
-}
-
-// Fisher Yates Shuffle without mutating the original array
-export function shuffle(array) {
-  const clone = array.slice()
-  let currentIndex = array.length
-  let temporaryValue
-  let randomIndex
-
-  // While there remain elements to shuffle...
-  while (currentIndex !== 0) {
-    // Pick a remaining element...
-    randomIndex = Math.floor(Math.random() * currentIndex)
-    currentIndex -= 1
-
-    // And swap it with the current element.
-    temporaryValue = clone[currentIndex]
-    clone[currentIndex] = clone[randomIndex]
-    clone[randomIndex] = temporaryValue
-  }
-
-  return clone
-}
-
-/**
- * Sorts an array of objects or strings without mutating the array
- */
-export function sort(
-  array,
-  {
-    property, // Property to sort by. Used when sorting array of objects.
-    order = 'asc', // 'asc' or 'desc'
-  },
-) {
-  const clone = array.slice()
-  const sorted = clone.sort((a, b) => {
-    let one = a
-    let two = b
-
-    // Use the `sortBy` property if sorting by objects
-    if (property) {
-      one = a[property]
-      two = b[property]
-    }
-
-    if (order === 'asc') {
-      if (one < two) return -1
-      if (one > two) return 1
-    }
-
-    if (order === 'desc') {
-      if (one < two) return 1
-      if (one > two) return -1
-    }
-
-    return 0
-  })
-
-  return sorted
-}
+export * from './item-position.js'
+export * from './join.js'
+export * from './shuffle.js'
+export * from './sort.js'
+export * from './unique.js'

package/lib/arrays/item-position.js

@@ -0,0 +1,23 @@
+export function last(array, index) {
+  console.warn('last is deprecated. Use isLastItem instead.')
+  return index === array.length - 1
+}
+
+/**
+ * Checks if the given index is the last item in the array
+ * @param {Array} array - The array to check
+ * @param {number} index - The index to check
+ * @returns {boolean} True if the index is the last item, false otherwise
+ */
+export function isLastItem(array, index) {
+  return index === array.length - 1
+}
+
+/**
+ * Returns the last item in the array
+ * @param {Array} array - The array to get the last item from
+ * @returns {*} The last item in the array
+ */
+export function lastArrayItem(array) {
+  return array[array.length - 1]
+}

package/lib/arrays/join.js

@@ -0,0 +1,20 @@
+import { lastArrayItem } from './item-position.js'
+/**
+ * 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 ''
+  if (array.length === 1) return array[0]
+  if (array.length === 2) return `${array[0]} ${conjunction} ${array[1]}`
+
+  const lastItem = lastArrayItem(array)
+  const rest = array.slice(0, -1)
+  return `${rest.join(', ')} ${conjunction} ${lastItem}`
+}

package/lib/arrays/shuffle.js

@@ -0,0 +1,21 @@
+// Fisher Yates Shuffle without mutating the original array
+export function shuffle(array) {
+  const clone = array.slice()
+  let currentIndex = array.length
+  let temporaryValue
+  let randomIndex
+
+  // While there remain elements to shuffle...
+  while (currentIndex !== 0) {
+    // Pick a remaining element...
+    randomIndex = Math.floor(Math.random() * currentIndex)
+    currentIndex -= 1
+
+    // And swap it with the current element.
+    temporaryValue = clone[currentIndex]
+    clone[currentIndex] = clone[randomIndex]
+    clone[randomIndex] = temporaryValue
+  }
+
+  return clone
+}

package/lib/arrays/sort.js

@@ -0,0 +1,88 @@
+import { getNestedValue } from '../objects/nested-property.js'
+
+/**
+ * Sorts an array of objects, numbers, or strings without mutating the original array.
+ * Supports nested properties, multiple sort keys, and various data types.
+ * 
+ * @template T
+ * @param {T[]} array - Array to sort
+ * @param {Object} [options] - Sort options
+ * @param {string|string[]|null} [options.props=null] - Property or array of properties to sort by. If null, sorts simple arrays
+ * @param {boolean} [options.reverse=false] - Whether to sort in reverse order
+ * @returns {T[]} New sorted array
+ * @example
+ * // Sort simple array
+ * sort([3, 1, 2]) // [1, 2, 3]
+ * 
+ * // Sort objects by single property
+ * sort(users, { props: 'name' })
+ * 
+ * // Sort objects by multiple properties
+ * sort(users, { props: ['age', 'name'] })
+ * 
+ * // Sort in reverse order
+ * sort(users, { props: 'age', reverse: true })
+ * 
+ * // Sort by nested property
+ * sort(users, { props: 'address.city' })
+ */
+export function sort(array, { props = null, reverse = false } = {}) {
+  const clone = array.slice()
+
+  // Handle simple arrays (numbers or strings)
+  if (props === null) {
+    return clone.sort((a, b) => {
+      const comparison = compareValues(a, b)
+      return reverse ? -comparison : comparison
+    })
+  }
+
+  // Handle objects in arrays
+  const properties = Array.isArray(props) ? props : [props]
+
+  return clone.sort((a, b) => {
+    for (const property of properties) {
+      const aValue = getNestedValue(a, property)
+      const bValue = getNestedValue(b, property)
+
+      // Skip if values are equal
+      if (aValue === bValue) continue
+
+      // Push null/undefined values to the end
+      if (aValue == null) return 1
+      if (bValue == null) return -1
+
+      // Compare values and handle reverse sort
+      const comparison = compareValues(aValue, bValue)
+      return reverse ? -comparison : comparison
+    }
+    return 0
+  })
+}
+
+/**
+ * Compares two values for sorting, handling different data types.
+ * Supports numbers, strings, dates, and falls back to string comparison.
+ * 
+ * @param {*} a - First value to compare
+ * @param {*} b - Second value to compare
+ * @returns {number} -1 if a < b, 0 if a === b, 1 if a > b
+ * @private
+ */
+function compareValues(a, b) {
+  // Compare numbers
+  if (typeof a === 'number' && typeof b === 'number') return a - b
+
+  // Compare strings
+  if (typeof a === 'string' && typeof b === 'string') return a.localeCompare(b)
+
+  // Compare dates
+  const aDate = new Date(a)
+  const bDate = new Date(b)
+  const aTime = aDate.getTime()
+  const bTime = bDate.getTime()
+  if (!isNaN(aTime) && !isNaN(bTime)) return aTime - bTime
+
+  // Convert into strings and compare
+  return String(a).localeCompare(String(b))
+}