@splendidlabz/utils 1.11.3 → 1.11.5

package/{src/dom/get-element.js → dist/types/dom/get-element.d.cts}

@@ -1,106 +1,66 @@
-// 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'
-}
-
+declare function getNodeType(node: Node | NodeList | any[]): "element" | "nodelist" | "array" | undefined;
 /**
  * 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)
-}
-
+declare function getElement(selector: string | Element): Element | undefined;
 /**
  * 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)
-}
-
+declare function getChildrenElements(node: Element): Element[];
 /**
  * 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
-}
-
+declare function getParentElement(element: Element): Element | null;
 /**
  * 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
-  )
-}
-
+declare function getSiblingElements(element: Element): 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)
-}
-
+declare function getSelfIndex(element: Element): number;
 /**
  * Checks if an element is an ancestor of another element
  * @param {Element} ancestor - The potential ancestor element
@@ -108,69 +68,35 @@ export function getSelfIndex(element) {
  * @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
-}
-
+declare function isAncestor(ancestor: Element, element: Element, { searchLevels }?: {
+    searchLevels?: number;
+}): boolean;
 /**
  * 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 })
-  }
+declare function getAncestorWithSiblings(element: Element, { limit }?: {
+    limit?: number | boolean;
+}): Element[] | null;
 
-  // Limit reached, end search
-  if (limit === 0) return null
-}
+export { getAncestorWithSiblings, getChildrenElements, getElement, getNodeType, getParentElement, getSelfIndex, getSiblingElements, isAncestor };

package/dist/types/dom/hash.d.cts

@@ -0,0 +1,3 @@
+declare function sha256Hash(string: any): Promise<string>;
+
+export { sha256Hash };

package/dist/types/dom/index.d.cts

@@ -0,0 +1,31 @@
+export { checkForAccessibleName, hasAccessibleName, isInvalidAriaPopup } from './accessibility.cjs';
+export { masonry } from './actions/masonry.cjs';
+export { preferHorizontalScroll } from './actions/prefer-horizontal-scroll.cjs';
+export { sticky } from './actions/sticky.cjs';
+export { boundingBox, boundingBoxRelativeToAncestor } from './bounding-box.cjs';
+export { copyRichText } from './clipboard.cjs';
+export { cookies, getCookie } from './cookie.cjs';
+export { getCSSValue, getCSSVar, setCSSValue, setCSSVar } from './css-vars.cjs';
+export { CustomEventOptions, EventListener, ListenerManager, addListeners, dispatchEvent, removeListeners, updateEvent } from './events.cjs';
+export { Focusable, Focusables, getFocusableElements } from './focusable.cjs';
+export { em, getUnit, lh, rem, rlh, toPx } from './font-size.cjs';
+export { getAncestorWithSiblings, getChildrenElements, getElement, getNodeType, getParentElement, getSelfIndex, getSiblingElements, isAncestor } from './get-element.cjs';
+export { sha256Hash } from './hash.cjs';
+export { isArrowKey, isEscapeKey, isShiftTab, isTab, isTabKey } from './keyboard.cjs';
+export { localStore } from './local-store.cjs';
+export { imagesLoaded, mediaLoaded, videosLoaded } from './media.cjs';
+export { intersectionObserver } from './observers/intersection-observer.cjs';
+export { mutationObserver } from './observers/mutation-observer.cjs';
+export { resizeObserver } from './observers/resize-observer.cjs';
+export { ScrollObserverOptions, scrollObserver } from './observers/scroll-observer.cjs';
+export { PKCE } from './pkce.cjs';
+export { queryParams } from './query-params.cjs';
+export { randomString, uuid } from './random-string.cjs';
+export { sanitize } from './sanitize.cjs';
+export { sessionStore } from './session-store.cjs';
+export { preventSpam } from './spam-prevention.cjs';
+export { manageFocus, trapFocus } from './trap-focus.cjs';
+export { markActiveAnchorIn, scrollToElement } from './ui/aria-current.cjs';
+export { inconsistentButtonFix } from './ui/inconsistent-button-fix.cjs';
+export { findScrollContainer } from './ui/scroll-container.cjs';
+export { traverseAndScramble } from './ui/traverse-and-scramble.cjs';

package/{src/dom/keyboard.js → dist/types/dom/keyboard.d.cts}

@@ -3,42 +3,30 @@
  * @param {KeyboardEvent} event - The keyboard event object
  * @returns {boolean}
  */
-export function isTab(event) {
-  return !event.shiftKey && event.key === 'Tab'
-}
-
+declare function isTab(event: KeyboardEvent): boolean;
 /**
  * Event is shift + Tab
  * @param {KeyboardEvent} event - The keyboard event object
  * @returns {boolean}
  */
-export function isShiftTab(event) {
-  return event.shiftKey && event.key === 'Tab'
-}
-
+declare function isShiftTab(event: KeyboardEvent): boolean;
 /**
  * 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'
-}
-
+declare function isTabKey(key: string): boolean;
 /**
  * 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)
-}
-
+declare function isArrowKey(key: string): boolean;
 /**
  * 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'
-}
+declare function isEscapeKey(key: string): boolean;
+
+export { isArrowKey, isEscapeKey, isShiftTab, isTab, isTabKey };

package/dist/types/dom/local-store.d.cts

@@ -0,0 +1,31 @@
+declare namespace 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
+     */
+    function get(key: string): any;
+    /**
+     * 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
+     */
+    function set(key: string, value: any): void;
+    /**
+     * Stores multiple key-value pairs in localStorage
+     * @param {Object|Map} data - An object or Map containing key-value pairs to store
+     */
+    function setMultiple(data: any | Map<any, any>): void;
+    /**
+     * Removes a value from localStorage
+     * @param {string} key - The key to remove from localStorage
+     */
+    function remove(key: string): void;
+    /**
+     * Removes multiple keys from localStorage
+     * @param {string[]} keys - Array of keys to remove from localStorage
+     */
+    function removeMultiple(keys: string[]): void;
+}
+
+export { localStore };

package/dist/types/dom/media.d.cts

@@ -0,0 +1,5 @@
+declare function imagesLoaded(node: any): Promise<any[]>;
+declare function videosLoaded(node: any): Promise<any[]>;
+declare function mediaLoaded(node: any): Promise<[any[], any[]]>;
+
+export { imagesLoaded, mediaLoaded, videosLoaded };

package/dist/types/dom/observers/index.d.cts

@@ -0,0 +1,4 @@
+export { intersectionObserver } from './intersection-observer.cjs';
+export { mutationObserver } from './mutation-observer.cjs';
+export { resizeObserver } from './resize-observer.cjs';
+export { ScrollObserverOptions, scrollObserver } from './scroll-observer.cjs';

package/dist/types/dom/observers/intersection-observer.d.cts

@@ -0,0 +1,10 @@
+declare function intersectionObserver(target: any, options?: {}): {
+    observer: IntersectionObserver;
+    observe(target: any): void;
+    unobserve(target: any): void;
+    takeRecords(): IntersectionObserverEntry[];
+    disconnect(): void;
+    destroy(): void;
+};
+
+export { intersectionObserver };

package/dist/types/dom/observers/mutation-observer.d.cts

@@ -0,0 +1,9 @@
+declare function mutationObserver(target: any, options: any): {
+    observer: MutationObserver;
+    observe(target: any): void;
+    takeRecords(): MutationRecord[];
+    disconnect(): void;
+    destroy(): void;
+};
+
+export { mutationObserver };

package/dist/types/dom/observers/observer.d.cts

@@ -0,0 +1,3 @@
+declare function useObserverMethodOnTarget(target: any, observer: any, method?: string, options?: any): void;
+
+export { useObserverMethodOnTarget };

package/{src/dom/observers/resize-observer.js → dist/types/dom/observers/resize-observer.d.cts}

@@ -1,7 +1,3 @@
-/* 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.
  *
@@ -35,32 +31,10 @@ import { useObserverMethodOnTarget } from './observer.js'
  *   console.log('Element resized:', detail.entry.contentRect);
  * });
  */
-export function resizeObserver(target, options) {
-  const { callback, ...opts } = options
-  const observer = new ResizeObserver(observerFn)
-
-  if (target === window || target === document)
-    target = document.documentElement
-  useObserverMethodOnTarget(target, observer, 'observe', opts)
-
-  function observerFn(entries) {
-    for (const entry of entries) {
-      if (callback) callback({ entry, entries, observer })
-      else
-        dispatchEvent(entry.target, 'resize-obs', { entry, entries, observer })
-    }
-  }
-
-  return {
-    observe(target) {
-      useObserverMethodOnTarget(target, observer, 'observe', options)
-    },
-
-    unobserve(target) {
-      useObserverMethodOnTarget(target, observer, 'unobserve')
-    },
+declare function resizeObserver(target: Element | Window | Document | NodeList | Element[], options: {
+    observe?: boolean;
+    callback?: Function;
+    observerOptions?: any;
+}): any;
 
-    disconnect: _ => observer.disconnect(),
-    destroy: _ => observer.disconnect(),
-  }
-}
+export { resizeObserver };

package/dist/types/dom/observers/scroll-observer.d.cts

@@ -0,0 +1,40 @@
+/**
+ * Scroll Observer - Optimized for performance
+ * @param {Element | Document | Window} node - The element to observe scroll events on
+ * @param {ScrollObserverOptions} [options] - Configuration options
+ */
+declare function scrollObserver(node: Element | Document | Window, options?: ScrollObserverOptions): {
+    destroy(): void;
+};
+type ScrollObserverOptions = {
+    /**
+     * - Float between 0 to 1. When to trigger callback (0.75 = 75% down page)
+     */
+    threshold?: number;
+    /**
+     * - Float between 0 to 1. Tolerance zone around threshold
+     */
+    tolerance?: number;
+    /**
+     * - Only fire threshold callback once (default: false)
+     */
+    once?: boolean;
+    /**
+     * - Called on every scroll with scrollPercent
+     */
+    callback?: Function;
+    /**
+     * - Called when scrolling down
+     */
+    onScrollDown?: Function;
+    /**
+     * - Called when scrolling up
+     */
+    onScrollUp?: Function;
+    /**
+     * - Called when entering threshold zone
+     */
+    onEnterThreshold?: Function;
+};
+
+export { type ScrollObserverOptions, scrollObserver };

package/dist/types/dom/pkce.d.cts

@@ -0,0 +1,8 @@
+declare function PKCE(): Promise<{
+    state: string;
+    code_verifier: string;
+    code_challenge: string;
+    code_challenge_method: string;
+}>;
+
+export { PKCE };

package/dist/types/dom/query-params.d.cts

@@ -0,0 +1,6 @@
+declare namespace queryParams {
+    function get(key: any): string;
+    function stringify(params: any): string;
+}
+
+export { queryParams };

package/dist/types/dom/random-string.d.cts

@@ -0,0 +1,9 @@
+/**
+ * Generates a random string.
+ * Ensures first character is a letter so it can be used in HTML ids and classes
+ * This can actually be used everywhere, not just in the browser.
+ */
+declare function randomString(length?: number): string;
+declare function uuid(): `${string}-${string}-${string}-${string}-${string}`;
+
+export { randomString, uuid };

package/dist/types/dom/sanitize.d.cts

@@ -0,0 +1,10 @@
+/**
+ * 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
+ */
+declare function sanitize(value: any, options?: any): any;
+
+export { sanitize };

package/dist/types/dom/session-store.d.cts

@@ -0,0 +1,7 @@
+declare namespace sessionStore {
+    function get(key: any): any;
+    function set(key: any, value: any): void;
+    function remove(key: any): void;
+}
+
+export { sessionStore };

package/dist/types/dom/spam-prevention.d.cts

@@ -0,0 +1,14 @@
+/**
+ * Enhances a form element with spam detection capabilities
+ * @param {HTMLFormElement} form - The form element to enhance
+ * @param {Object} [options] - Configuration options
+ * @param {string} [options.honeypotField] - Name of the honeypot field (default: 'hp')
+ * @param {number} [options.honeypotDuration] - Minimum time in ms for legitimate form fill (default: 2000)
+ * @returns {void}
+ */
+declare function preventSpam(form: HTMLFormElement, { honeypotField, honeypotDuration }?: {
+    honeypotField?: string;
+    honeypotDuration?: number;
+}): void;
+
+export { preventSpam };

package/dist/types/dom/trap-focus.d.cts

@@ -0,0 +1,32 @@
+import { Focusables } from './focusable.cjs';
+
+/**
+ * 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
+ */
+declare function trapFocus({ event, focusables }: {
+    event: KeyboardEvent;
+    focusables: Focusables;
+}): void;
+/**
+ * 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
+ */
+declare function manageFocus({ event, triggerNode, contentNode, focusables, tabOutFocus, onLeave, }: {
+    event: KeyboardEvent;
+    triggerNode: HTMLElement;
+    contentNode: HTMLElement;
+    focusables: Focusables;
+    tabOutFocus?: "next" | "trigger";
+    onLeave?: Function;
+}): void;
+
+export { manageFocus, trapFocus };

package/dist/types/dom/ui/aria-current.d.cts

@@ -0,0 +1,7 @@
+declare function markActiveAnchorIn(container: any, anchorType?: string): any;
+declare function scrollToElement(element: any, { scrollBehaviour, scrollMargin }?: {
+    scrollBehaviour?: string;
+    scrollMargin?: string;
+}): void;
+
+export { markActiveAnchorIn, scrollToElement };

package/{src/dom/ui/inconsistent-button-fix.js → dist/types/dom/ui/inconsistent-button-fix.d.cts}

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

package/dist/types/dom/ui/index.d.cts

@@ -0,0 +1,4 @@
+export { markActiveAnchorIn, scrollToElement } from './aria-current.cjs';
+export { inconsistentButtonFix } from './inconsistent-button-fix.cjs';
+export { findScrollContainer } from './scroll-container.cjs';
+export { traverseAndScramble } from './traverse-and-scramble.cjs';

package/dist/types/dom/ui/scroll-container.d.cts

@@ -0,0 +1,3 @@
+declare function findScrollContainer(element: any, direction?: string): any;
+
+export { findScrollContainer };

package/dist/types/dom/ui/traverse-and-scramble.d.cts

@@ -0,0 +1,21 @@
+/**
+ * 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]']
+ * })
+ */
+declare function traverseAndScramble(node: Element | ChildNode, { excludes }?: {
+    excludes?: string[];
+}): void;
+
+export { traverseAndScramble };

package/dist/types/lib/arrays/index.d.cts

@@ -0,0 +1,6 @@
+export { isLastItem, last, lastArrayItem } from './item-position.cjs';
+export { joinWithConjunction } from './join.cjs';
+export { shuffle } from './shuffle.cjs';
+export { sort } from './sort.cjs';
+export { splitArray } from './split-array.cjs';
+export { uniqueArray } from './unique.cjs';

package/{src/lib/arrays/item-position.js → dist/types/lib/arrays/item-position.d.cts}

@@ -1,23 +1,16 @@
-export function last(array, index) {
-  console.warn('last is deprecated. Use isLastItem instead.')
-  return index === array.length - 1
-}
-
+declare function last(array: any, index: any): boolean;
 /**
  * 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
-}
-
+declare function isLastItem(array: any[], index: number): boolean;
 /**
  * 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]
-}
+declare function lastArrayItem(array: any[]): any;
+
+export { isLastItem, last, lastArrayItem };