@splendidlabz/utils 1.6.0 → 1.7.0

package/dist/esm/dom/trap-focus.js

@@ -0,0 +1,170 @@
+// src/dom/focusable.js
+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() {
+      const elements = Array.from(
+        container.querySelectorAll(
+          `a, 
+            button, 
+            input, 
+            textarea, 
+            select, 
+            details, 
+            iframe, 
+            embed, 
+            object, 
+            summary, 
+            dialog, 
+            audio[controls], 
+            video[controls], 
+            [contenteditable], 
+            [tabindex]
+          `
+        )
+      );
+      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 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] || 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] || 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;
+    }
+  };
+}
+
+// src/dom/keyboard.js
+function isTab(event) {
+  return !event.shiftKey && event.key === "Tab";
+}
+function isShiftTab(event) {
+  return event.shiftKey && event.key === "Tab";
+}
+
+// src/dom/trap-focus.js
+function trapFocus({ event, focusables }) {
+  if (event.key !== "Tab") return;
+  if (isTab(event) && document.activeElement === focusables.last) {
+    event.preventDefault();
+    focusables.first.focus();
+  }
+  if (isShiftTab(event) && document.activeElement === focusables.first) {
+    event.preventDefault();
+    focusables.last.focus();
+  }
+}
+function manageFocus({
+  event,
+  triggerNode,
+  contentNode,
+  focusables,
+  tabOutFocus = "next",
+  // 'trigger'
+  onLeave = function() {
+  }
+}) {
+  const activeEl = document.activeElement;
+  if (activeEl === contentNode && isShiftTab(event)) return backFocus();
+  if (activeEl === contentNode && focusables.length === 0 && isTab(event))
+    return nextFocus();
+  if (activeEl === focusables.last && isTab(event)) return nextFocus();
+  if (activeEl === focusables.first && isShiftTab(event)) return backFocus();
+  function backFocus() {
+    event.preventDefault();
+    triggerNode.focus();
+    onLeave("back");
+  }
+  function nextFocus() {
+    if (tabOutFocus === "trigger") triggerNode.focus();
+    if (tabOutFocus === "next") {
+      event.preventDefault();
+      const DOMFocusables = getFocusableElements().keyboard;
+      const index = DOMFocusables.findIndex((e) => e === triggerNode);
+      const next = DOMFocusables[index + 1];
+      if (next) next.focus();
+      else triggerNode.focus();
+    }
+    onLeave("forward");
+  }
+}
+export {
+  manageFocus,
+  trapFocus
+};

package/dist/esm/dom/ui/aria-current.js

@@ -0,0 +1,18 @@
+// src/dom/ui/aria-current.js
+function markActiveAnchorIn(container, anchorType = "page") {
+  if (!container) return;
+  const { pathname } = window.location;
+  const element = container.querySelector(`[href="${pathname}"]`);
+  if (!element) return;
+  element.setAttribute("aria-current", "page");
+  return element;
+}
+function scrollToElement(element, { scrollBehaviour = "instant", scrollMargin = "3rem" } = {}) {
+  if (!element) return;
+  element.style.scrollMarginTop = scrollMargin;
+  element.scrollIntoView({ behavior: scrollBehaviour });
+}
+export {
+  markActiveAnchorIn,
+  scrollToElement
+};

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

@@ -0,0 +1,11 @@
+// src/dom/ui/inconsistent-button-fix.js
+function inconsistentButtonFix() {
+  document.addEventListener("click", (event) => {
+    if (event.target instanceof HTMLButtonElement) {
+      event.target.focus();
+    }
+  });
+}
+export {
+  inconsistentButtonFix
+};

package/dist/esm/dom/ui/index.js

@@ -0,0 +1,75 @@
+// src/dom/ui/aria-current.js
+function markActiveAnchorIn(container, anchorType = "page") {
+  if (!container) return;
+  const { pathname } = window.location;
+  const element = container.querySelector(`[href="${pathname}"]`);
+  if (!element) return;
+  element.setAttribute("aria-current", "page");
+  return element;
+}
+function scrollToElement(element, { scrollBehaviour = "instant", scrollMargin = "3rem" } = {}) {
+  if (!element) return;
+  element.style.scrollMarginTop = scrollMargin;
+  element.scrollIntoView({ behavior: scrollBehaviour });
+}
+
+// src/dom/ui/inconsistent-button-fix.js
+function inconsistentButtonFix() {
+  document.addEventListener("click", (event) => {
+    if (event.target instanceof HTMLButtonElement) {
+      event.target.focus();
+    }
+  });
+}
+
+// src/dom/ui/scroll-container.js
+function findScrollContainer(element, direction = "both") {
+  if (!element) return;
+  let parent = element.parentElement;
+  while (parent) {
+    const { overflow, overflowX, overflowY } = getComputedStyle(parent);
+    if (direction === "both") {
+      if (overflow.includes("auto") || overflow.includes("scroll"))
+        return parent;
+    }
+    if (direction === "horizontal") {
+      if (overflowX === "auto" || overflowX === "scroll") return parent;
+    }
+    if (direction === "vertical") {
+      if (overflowY === "auto" || overflowY === "scroll") return parent;
+    }
+    parent = parent.parentElement;
+  }
+  return document.documentElement;
+}
+
+// src/dom/ui/traverse-and-scramble.js
+function traverseAndScramble(node, { excludes = [] } = {}) {
+  if (node instanceof Element && excludes.some((selector) => node.matches(selector))) {
+    return;
+  }
+  node.childNodes.forEach((child) => {
+    if (child.nodeType === 3) {
+      child.nodeValue = scrambleText(child.nodeValue);
+    } else if (child.nodeType === 1 && child instanceof Element) {
+      traverseAndScramble(child, { excludes });
+    }
+  });
+}
+function scrambleText(text) {
+  return text.split("").map((char) => {
+    if (/^[A-Za-z0-9]$/.test(char)) {
+      const randomCharCode = Math.random() < 26 / 36 ? Math.floor(Math.random() * 26) + (char === char.toUpperCase() ? 65 : 97) : Math.floor(Math.random() * 10) + 48;
+      return String.fromCharCode(randomCharCode);
+    } else {
+      return char;
+    }
+  }).join("");
+}
+export {
+  findScrollContainer,
+  inconsistentButtonFix,
+  markActiveAnchorIn,
+  scrollToElement,
+  traverseAndScramble
+};

package/dist/esm/dom/ui/scroll-container.js

@@ -0,0 +1,23 @@
+// src/dom/ui/scroll-container.js
+function findScrollContainer(element, direction = "both") {
+  if (!element) return;
+  let parent = element.parentElement;
+  while (parent) {
+    const { overflow, overflowX, overflowY } = getComputedStyle(parent);
+    if (direction === "both") {
+      if (overflow.includes("auto") || overflow.includes("scroll"))
+        return parent;
+    }
+    if (direction === "horizontal") {
+      if (overflowX === "auto" || overflowX === "scroll") return parent;
+    }
+    if (direction === "vertical") {
+      if (overflowY === "auto" || overflowY === "scroll") return parent;
+    }
+    parent = parent.parentElement;
+  }
+  return document.documentElement;
+}
+export {
+  findScrollContainer
+};

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

@@ -0,0 +1,26 @@
+// src/dom/ui/traverse-and-scramble.js
+function traverseAndScramble(node, { excludes = [] } = {}) {
+  if (node instanceof Element && excludes.some((selector) => node.matches(selector))) {
+    return;
+  }
+  node.childNodes.forEach((child) => {
+    if (child.nodeType === 3) {
+      child.nodeValue = scrambleText(child.nodeValue);
+    } else if (child.nodeType === 1 && child instanceof Element) {
+      traverseAndScramble(child, { excludes });
+    }
+  });
+}
+function scrambleText(text) {
+  return text.split("").map((char) => {
+    if (/^[A-Za-z0-9]$/.test(char)) {
+      const randomCharCode = Math.random() < 26 / 36 ? Math.floor(Math.random() * 26) + (char === char.toUpperCase() ? 65 : 97) : Math.floor(Math.random() * 10) + 48;
+      return String.fromCharCode(randomCharCode);
+    } else {
+      return char;
+    }
+  }).join("");
+}
+export {
+  traverseAndScramble
+};

package/dist/esm/lib/arrays/index.js

@@ -0,0 +1,106 @@
+// src/lib/arrays/item-position.js
+function last(array, index) {
+  console.warn("last is deprecated. Use isLastItem instead.");
+  return index === array.length - 1;
+}
+function isLastItem(array, index) {
+  return index === array.length - 1;
+}
+function lastArrayItem(array) {
+  return array[array.length - 1];
+}
+
+// src/lib/arrays/join.js
+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}`;
+}
+
+// src/lib/arrays/shuffle.js
+function shuffle(array) {
+  const clone = array.slice();
+  let currentIndex = array.length;
+  let temporaryValue;
+  let randomIndex;
+  while (currentIndex !== 0) {
+    randomIndex = Math.floor(Math.random() * currentIndex);
+    currentIndex -= 1;
+    temporaryValue = clone[currentIndex];
+    clone[currentIndex] = clone[randomIndex];
+    clone[randomIndex] = temporaryValue;
+  }
+  return clone;
+}
+
+// src/lib/objects/nested-property.js
+function getNestedValue(object, path) {
+  return path.split(".").reduce((acc, part) => acc?.[part], object);
+}
+
+// src/lib/arrays/sort.js
+function sort(array, { props = null, reverse = false } = {}) {
+  const clone = array.slice();
+  if (props === null) {
+    return clone.sort((a, b) => {
+      const comparison = compareValues(a, b);
+      return reverse ? -comparison : comparison;
+    });
+  }
+  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);
+      if (aValue === bValue) continue;
+      if (aValue == null) return 1;
+      if (bValue == null) return -1;
+      const comparison = compareValues(aValue, bValue);
+      return reverse ? -comparison : comparison;
+    }
+    return 0;
+  });
+}
+function compareValues(a, b) {
+  if (typeof a === "number" && typeof b === "number") return a - b;
+  if (typeof a === "string" && typeof b === "string") return a.localeCompare(b);
+  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;
+  return String(a).localeCompare(String(b));
+}
+
+// src/lib/arrays/split-array.js
+function splitArray(array, predicate) {
+  const ret = {
+    picked: [],
+    omitted: []
+  };
+  array.forEach((item, index, arr) => {
+    if (predicate(item, index, arr)) ret.picked.push(item);
+    else ret.omitted.push(item);
+  });
+  ret.p = ret.picked;
+  ret.o = ret.omitted;
+  return ret;
+}
+
+// src/lib/arrays/unique.js
+function uniqueArray(array) {
+  return Array.from(new Set(array));
+}
+export {
+  isLastItem,
+  joinWithConjunction,
+  last,
+  lastArrayItem,
+  shuffle,
+  sort,
+  splitArray,
+  uniqueArray
+};

package/dist/esm/lib/arrays/item-position.js

@@ -0,0 +1,16 @@
+// src/lib/arrays/item-position.js
+function last(array, index) {
+  console.warn("last is deprecated. Use isLastItem instead.");
+  return index === array.length - 1;
+}
+function isLastItem(array, index) {
+  return index === array.length - 1;
+}
+function lastArrayItem(array) {
+  return array[array.length - 1];
+}
+export {
+  isLastItem,
+  last,
+  lastArrayItem
+};

package/dist/esm/lib/arrays/join.js

@@ -0,0 +1,17 @@
+// src/lib/arrays/item-position.js
+function lastArrayItem(array) {
+  return array[array.length - 1];
+}
+
+// src/lib/arrays/join.js
+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}`;
+}
+export {
+  joinWithConjunction
+};

package/dist/esm/lib/arrays/shuffle.js

@@ -0,0 +1,18 @@
+// src/lib/arrays/shuffle.js
+function shuffle(array) {
+  const clone = array.slice();
+  let currentIndex = array.length;
+  let temporaryValue;
+  let randomIndex;
+  while (currentIndex !== 0) {
+    randomIndex = Math.floor(Math.random() * currentIndex);
+    currentIndex -= 1;
+    temporaryValue = clone[currentIndex];
+    clone[currentIndex] = clone[randomIndex];
+    clone[randomIndex] = temporaryValue;
+  }
+  return clone;
+}
+export {
+  shuffle
+};

package/dist/esm/lib/arrays/sort.js

@@ -0,0 +1,41 @@
+// src/lib/objects/nested-property.js
+function getNestedValue(object, path) {
+  return path.split(".").reduce((acc, part) => acc?.[part], object);
+}
+
+// src/lib/arrays/sort.js
+function sort(array, { props = null, reverse = false } = {}) {
+  const clone = array.slice();
+  if (props === null) {
+    return clone.sort((a, b) => {
+      const comparison = compareValues(a, b);
+      return reverse ? -comparison : comparison;
+    });
+  }
+  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);
+      if (aValue === bValue) continue;
+      if (aValue == null) return 1;
+      if (bValue == null) return -1;
+      const comparison = compareValues(aValue, bValue);
+      return reverse ? -comparison : comparison;
+    }
+    return 0;
+  });
+}
+function compareValues(a, b) {
+  if (typeof a === "number" && typeof b === "number") return a - b;
+  if (typeof a === "string" && typeof b === "string") return a.localeCompare(b);
+  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;
+  return String(a).localeCompare(String(b));
+}
+export {
+  sort
+};

package/dist/esm/lib/arrays/split-array.js

@@ -0,0 +1,17 @@
+// src/lib/arrays/split-array.js
+function splitArray(array, predicate) {
+  const ret = {
+    picked: [],
+    omitted: []
+  };
+  array.forEach((item, index, arr) => {
+    if (predicate(item, index, arr)) ret.picked.push(item);
+    else ret.omitted.push(item);
+  });
+  ret.p = ret.picked;
+  ret.o = ret.omitted;
+  return ret;
+}
+export {
+  splitArray
+};

package/dist/esm/lib/arrays/unique.js

@@ -0,0 +1,7 @@
+// src/lib/arrays/unique.js
+function uniqueArray(array) {
+  return Array.from(new Set(array));
+}
+export {
+  uniqueArray
+};

package/dist/esm/lib/auth/index.js

@@ -0,0 +1,26 @@
+// src/lib/auth/route-manager.js
+function RouteManager(config) {
+  const { protectedRoutes, bypassRoutes } = config;
+  return {
+    isProtectedRoute(pathname) {
+      return isMatch(protectedRoutes, pathname);
+    },
+    isBypassRoute(pathname) {
+      return isMatch(bypassRoutes, pathname);
+    }
+  };
+}
+function AuthManager(config) {
+  return RouteManager(config);
+}
+function isMatch(routeConfig, pathname) {
+  const { is, startsWith, includes } = routeConfig;
+  const isExactMatch = is && is.some((u) => pathname === u);
+  const startsWithMatch = startsWith && startsWith.some((u) => pathname.startsWith(u));
+  const includesMatch = includes && includes.some((u) => pathname.includes(u));
+  return isExactMatch || startsWithMatch || includesMatch;
+}
+export {
+  AuthManager,
+  RouteManager
+};

package/dist/esm/lib/auth/route-manager.js

@@ -0,0 +1,26 @@
+// src/lib/auth/route-manager.js
+function RouteManager(config) {
+  const { protectedRoutes, bypassRoutes } = config;
+  return {
+    isProtectedRoute(pathname) {
+      return isMatch(protectedRoutes, pathname);
+    },
+    isBypassRoute(pathname) {
+      return isMatch(bypassRoutes, pathname);
+    }
+  };
+}
+function AuthManager(config) {
+  return RouteManager(config);
+}
+function isMatch(routeConfig, pathname) {
+  const { is, startsWith, includes } = routeConfig;
+  const isExactMatch = is && is.some((u) => pathname === u);
+  const startsWithMatch = startsWith && startsWith.some((u) => pathname.startsWith(u));
+  const includesMatch = includes && includes.some((u) => pathname.includes(u));
+  return isExactMatch || startsWithMatch || includesMatch;
+}
+export {
+  AuthManager,
+  RouteManager
+};

package/dist/esm/lib/checks.js

@@ -0,0 +1,31 @@
+// src/lib/checks.js
+function isObject(x) {
+  return typeof x === "object" && !Array.isArray(x) && x !== null;
+}
+function isArray(x) {
+  return Array.isArray(x);
+}
+function notObject(x) {
+  return !isObject(x);
+}
+function getType(x) {
+  if (typeof x === "string") return "string";
+  if (typeof x === "number") {
+    if (Number.isInteger(x)) return "integer";
+    return "float";
+  }
+  if (typeof x === "boolean") return "boolean";
+  if (typeof x === "function") return "function";
+  if (typeof x === "undefined") return "undefined";
+  if (typeof x === "symbol") return "symbol";
+  if (typeof x === "bigint") return "bigint";
+  if (Array.isArray(x)) return "array";
+  if (typeof x === "object") return "object";
+  return "unknown";
+}
+export {
+  getType,
+  isArray,
+  isObject,
+  notObject
+};

package/dist/esm/lib/date/days.js

@@ -0,0 +1,13 @@
+// src/lib/date/days.js
+var DAYS = [
+  { short: "Sun", long: "Sunday", numeric: 1 },
+  { short: "Mon", long: "Monday", numeric: 2 },
+  { short: "Tue", long: "Tuesday", numeric: 3 },
+  { short: "Wed", long: "Wednesday", numeric: 4 },
+  { short: "Thu", long: "Thursday", numeric: 5 },
+  { short: "Fri", long: "Friday", numeric: 6 },
+  { short: "Sat", long: "Saturday", numeric: 7 }
+];
+export {
+  DAYS
+};