@splendidlabz/utils 1.11.3 → 1.11.4

package/dist/esm/node/file-cache.js

@@ -0,0 +1,121 @@
+import fs from "fs/promises";
+import { glob } from "glob";
+import path from "node:path";
+import { sort } from "../lib/arrays/sort.js";
+function resolveDirPath(dirPath) {
+  return path.isAbsolute(dirPath) ? dirPath : path.join(process.cwd(), dirPath);
+}
+async function createCache(dir) {
+  const absDirpath = resolveDirPath(dir);
+  await fs.mkdir(absDirpath, { recursive: true });
+  return {
+    async cacheAt(file) {
+      if (file) {
+        const absFilepath = path.join(absDirpath, file);
+        try {
+          const stat = await fs.stat(absFilepath);
+          return stat.mtimeMs;
+        } catch (error) {
+          return 0;
+        }
+      } else {
+        return getLastModifiedTime(absDirpath + "/**/*");
+      }
+    },
+    getAbsPath(file) {
+      return path.join(absDirpath, file);
+    },
+    async hasFile(file) {
+      const absFilepath = path.join(absDirpath, file);
+      try {
+        await fs.stat(absFilepath);
+        return true;
+      } catch (e) {
+        return false;
+      }
+    },
+    async loadFile(file) {
+      try {
+        const absFilepath = path.join(absDirpath, file);
+        return fs.readFile(absFilepath);
+      } catch (error) {
+        console.warn(`File not found: ${file}`);
+      }
+    },
+    async saveFile(file, data) {
+      const absfilepath = path.join(absDirpath, file);
+      await fs.writeFile(absfilepath, data);
+    },
+    async loadJSON(file) {
+      const data = await this.loadFile(file);
+      try {
+        return JSON.parse(data.toString());
+      } catch (err) {
+        console.warn(`Error parsing JSON: ${file}`);
+        return {};
+      }
+    },
+    async saveJSON(file, data) {
+      await this.saveFile(file, JSON.stringify(data));
+    }
+  };
+}
+async function fileCache({ dir, file }) {
+  const absDirpath = resolveDirPath(dir);
+  await fs.mkdir(absDirpath, { recursive: true });
+  const cachePath = path.join(absDirpath, `${file}`);
+  let modifiedAt = 0;
+  try {
+    const stat = await fs.stat(cachePath);
+    modifiedAt = stat.mtimeMs;
+  } catch (error) {
+  }
+  return {
+    modifiedAt,
+    async load() {
+      return fs.readFile(cachePath);
+    },
+    async save(data) {
+      await fs.writeFile(cachePath, data);
+    },
+    async loadJSON() {
+      const data = await fs.readFile(cachePath);
+      return JSON.parse(data.toString());
+    },
+    async saveJSON(data) {
+      await fs.writeFile(cachePath, JSON.stringify(data));
+    }
+  };
+}
+async function getLastModifiedTime(globPath) {
+  let files;
+  if (typeof globPath === "string") {
+    files = await glob(removeFirstSlash(globPath));
+  }
+  if (Array.isArray(globPath)) {
+    const a = await Promise.all(
+      globPath.map((path2) => glob(removeFirstSlash(path2)))
+    );
+    files = a.flat();
+  }
+  const stats = await Promise.all(files.map((file) => fs.stat(file)));
+  const timestamps = stats.map((stat) => Number(stat.mtimeMs));
+  const sorted = sort(timestamps, { props: "mtimeMs", reverse: true });
+  return sorted[0] || 0;
+}
+async function getLatestModifiedTime(globPath) {
+  console.warn(
+    "`getLatestModifiedTime` has been renamed to `getLastModifiedTime` and will be deprecated in future versions. Please use `getLastModifiedTime` instead."
+  );
+  return getLastModifiedTime(globPath);
+}
+function removeFirstSlash(x) {
+  return x.startsWith("/") ? x.slice(1) : x;
+}
+export {
+  createCache,
+  fileCache,
+  getLastModifiedTime,
+  getLatestModifiedTime,
+  removeFirstSlash
+};

package/dist/esm/node/file.js

@@ -0,0 +1,14 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+async function mkdir(path2) {
+  return fs.mkdir(path2, { recursive: true });
+}
+async function copyFile(from, to) {
+  const dir = path.dirname(to);
+  await mkdir(dir);
+  await fs.copyFile(from, to);
+}
+export {
+  copyFile,
+  mkdir
+};

package/dist/esm/node/hash.js

@@ -0,0 +1,7 @@
+import crypto from "node:crypto";
+function sha256Hash(string) {
+  return crypto.createHash("sha256").update(string).digest("hex");
+}
+export {
+  sha256Hash
+};

package/dist/esm/node/index.js

@@ -0,0 +1,7 @@
+export * from "./dirname.js";
+export * from "./file-cache.js";
+export * from "./hash.js";
+export * from "./pkce.js";
+export * from "./random-string.js";
+export * from "./sanitize.js";
+export * from "./uuid.js";

package/dist/esm/node/pkce.js

@@ -0,0 +1,20 @@
+import crypto from "node:crypto";
+import { randomString } from "./random-string.js";
+async function PKCE() {
+  const codeVerifier = await randomString();
+  const codeChallenge = await getCodeChallenge(codeVerifier);
+  return {
+    state: await randomString(),
+    code_verifier: codeVerifier,
+    code_challenge: codeChallenge,
+    code_challenge_method: "S256"
+  };
+}
+function getCodeChallenge(verifier) {
+  const hash = crypto.createHash("sha256").update(verifier).digest();
+  return hash.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
+}
+export {
+  PKCE,
+  getCodeChallenge
+};

package/dist/esm/node/random-string.js

@@ -0,0 +1,8 @@
+import crypto from "node:crypto";
+function randomString(length = 32) {
+  const bytesNeeded = Math.ceil(length * 3 / 4) + 3;
+  return crypto.randomBytes(bytesNeeded).toString("base64").slice(0, length);
+}
+export {
+  randomString
+};

package/dist/esm/node/sanitize.js

@@ -0,0 +1,8 @@
+import sanitizeHtml from "sanitize-html";
+import { sanitize as sanitizeLib } from "../lib/form/sanitize.js";
+function sanitize(value, options = {}) {
+  return sanitizeLib(value, { sanitizer: sanitizeHtml, ...options });
+}
+export {
+  sanitize
+};

package/dist/esm/node/uuid.js

@@ -0,0 +1,7 @@
+import crypto from "crypto";
+function uuid() {
+  return crypto.randomUUID();
+}
+export {
+  uuid
+};

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

@@ -0,0 +1,30 @@
+/**
+ * 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
+ */
+declare function hasAccessibleName(label?: string, labelledBy?: string): boolean;
+/**
+ * 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
+ */
+declare function checkForAccessibleName({ name, ariaLabel, ariaLabelledBy, severity, }?: {
+    name?: string;
+    ariaLabel?: string;
+    ariaLabelledBy?: string;
+    severity?: "warn" | "error";
+}): boolean;
+/**
+ * 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
+ */
+declare function isInvalidAriaPopup(value: string): boolean;
+
+export { checkForAccessibleName, hasAccessibleName, isInvalidAriaPopup };

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

@@ -0,0 +1,3 @@
+export { masonry } from './masonry.cjs';
+export { preferHorizontalScroll } from './prefer-horizontal-scroll.cjs';
+export { sticky } from './sticky.cjs';

package/dist/types/dom/actions/masonry.d.cts

@@ -0,0 +1,5 @@
+declare function masonry(node: any): Promise<{
+    destroy(): void;
+}>;
+
+export { masonry };

package/dist/types/dom/actions/prefer-horizontal-scroll.d.cts

@@ -0,0 +1,5 @@
+declare function preferHorizontalScroll(node: any, props?: {}): {
+    destroy(): void;
+};
+
+export { preferHorizontalScroll };

package/dist/types/dom/actions/sticky.d.cts

@@ -0,0 +1,5 @@
+declare function sticky(node: any, props?: {}): {
+    destroy(): void;
+};
+
+export { sticky };

package/{src/dom/bounding-box.js → dist/types/dom/bounding-box.d.cts}

@@ -15,37 +15,9 @@
  * @property {number} xCenter - The horizontal center coordinate
  * @property {number} yCenter - The vertical center coordinate
  */
-export function boundingBox(element, { containsPadding = true } = {}) {
-  const box = element.getBoundingClientRect()
-
-  // Spread original properties into the return object
-  const ret = {}
-  for (const prop in box) ret[prop] = box[prop]
-
-  // Gets boundingClientRect value without padding
-  if (!containsPadding) {
-    const style = getComputedStyle(element)
-    // 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
-    ret.width = ret.width - paddingLeft - paddingRight
-    ret.height = ret.height - paddingTop - paddingBottom
-    ret.top = ret.top + paddingTop
-    ret.bottom = ret.bottom - paddingBottom
-    ret.right = ret.right - paddingRight
-    ret.left = ret.left + paddingLeft
-  }
-
-  ret.xCenter = (ret.left + ret.right) / 2
-  ret.yCenter = (ret.top + ret.bottom) / 2
-  return ret
-}
-
+declare function boundingBox(element: HTMLElement, { containsPadding }?: {
+    containsPadding?: boolean;
+}): any;
 /**
  * Gets the bounding box of an element relative to its ancestor
  * @param {Object} params - Parameters for the calculation
@@ -61,22 +33,9 @@ export function boundingBox(element, { containsPadding = true } = {}) {
  * @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
-
-  const box = boundingBox(element)
-  const ancestorBox = boundingBox(ancestorElement, {
-    containsPadding: false,
-  })
+declare function boundingBoxRelativeToAncestor({ element, ancestorElement }: {
+    element: HTMLElement;
+    ancestorElement?: HTMLElement;
+}): any;
 
-  return {
-    top: box.top - ancestorBox.top,
-    right: box.right - ancestorBox.right,
-    bottom: box.bottom - ancestorBox.bottom,
-    left: box.left - ancestorBox.left,
-    width: box.width,
-    height: box.height,
-    xCenter: (box.left + box.right) / 2 - ancestorBox.left,
-    yCenter: (box.top + box.bottom) / 2 - ancestorBox.top,
-  }
-}
+export { boundingBox, boundingBoxRelativeToAncestor };

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

@@ -0,0 +1,7 @@
+/**
+ * Copies rich text from an element to the clipboard
+ * @param HTMLElement element - Element to copy
+ */
+declare function copyRichText(element: any): void;
+
+export { copyRichText };

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

@@ -0,0 +1,7 @@
+declare function getCookie(name: any): any;
+declare namespace cookies {
+    function get(name: any): any;
+    function set(name: any, value: any, days: any): void;
+}
+
+export { cookies, getCookie };

package/dist/types/dom/css-vars.d.cts

@@ -0,0 +1,6 @@
+declare function getCSSValue(element: any, prop: any): string;
+declare function setCSSValue(element: any, prop: any, value: any): void;
+declare function getCSSVar(element: any, prop: any): string;
+declare function setCSSVar(element: any, prop: any, value: any): void;
+
+export { getCSSValue, getCSSVar, setCSSValue, setCSSVar };

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

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

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

@@ -0,0 +1,78 @@
+/**
+ * @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()
+ *   }
+ * })
+ */
+declare function getFocusableElements(container?: HTMLElement): Focusables;
+declare function Focusable(container?: HTMLElement): Focusables;
+type Focusables = {
+    /**
+     * - Number of keyboard focusable elements
+     */
+    length: number;
+    /**
+     * - All focusable elements that are visible and enabled
+     */
+    all: any[];
+    /**
+     * - Elements that can be focused via keyboard (tabIndex > -1)
+     */
+    keyboard: any[];
+    /**
+     * - Alias for keyboard focusable elements
+     */
+    keyboardOnly: any[];
+    /**
+     * - First keyboard focusable element
+     */
+    first: HTMLElement | null;
+    /**
+     * - Last keyboard focusable element
+     */
+    last: HTMLElement | null;
+    /**
+     * - Get next focusable element after the given index
+     */
+    next: (arg0: number) => HTMLElement | null;
+    /**
+     * - Get previous focusable element before the given index
+     */
+    prev: (arg0: number) => HTMLElement | null;
+};
+
+export { Focusable, type Focusables, getFocusableElements };

package/dist/types/dom/font-size.d.cts

@@ -0,0 +1,8 @@
+declare function getUnit(value: any): any;
+declare function rem(multiple?: number): number;
+declare function em(element?: HTMLElement, multiple?: number): number;
+declare function rlh(multiple?: number): number;
+declare function lh(element?: HTMLElement, multiple?: number): number;
+declare function toPx(value: any, element?: any): number;
+
+export { em, getUnit, lh, rem, rlh, toPx };