@zeyos/zx 2.1.0 → 2.2.0

package/src/core/position.js

@@ -0,0 +1,177 @@
+// @ts-check
+import { clamp, uid } from './util.js';
+
+const PLACEMENTS = new Set([
+  'bottom-start', 'bottom-end', 'top-start', 'top-end', 'bottom', 'top'
+]);
+
+/**
+ * @typedef {Object} PositionOptions
+ * @property {'bottom-start'|'bottom-end'|'top-start'|'top-end'|'bottom'|'top'} [placement='bottom-start']
+ * @property {number} [offset=4] Gap between anchor and floating element.
+ * @property {boolean} [flip=true] Flip vertically when the preferred side overflows.
+ * @property {boolean} [matchWidth=false] Set the floating element's minimum width to the anchor width.
+ */
+/**
+ * @typedef {Object} PositionController
+ * @property {() => void} update Recompute coordinates and matched width.
+ * @property {() => void} destroy Hide and clean up positioning resources.
+ */
+
+/**
+ * Anchors and opens a manual popover, using CSS anchor positioning when available.
+ * @param {Element} anchor Anchor element.
+ * @param {HTMLElement} floating Floating popover element.
+ * @param {PositionOptions} [options={}] Positioning behavior.
+ * @returns {PositionController}
+ */
+export function position(anchor, floating, options = {}) {
+  if (!(anchor instanceof Element) || !(floating instanceof HTMLElement)) {
+    throw new TypeError('position() requires an Element anchor and HTMLElement floating element');
+  }
+  const placement = PLACEMENTS.has(options.placement) ? options.placement : 'bottom-start';
+  const offset = Number(options.offset ?? 4);
+  const flip = options.flip ?? true;
+  const matchWidth = options.matchWidth ?? false;
+  const anchorStyle = anchor.getAttribute('style');
+  const floatingStyle = floating.getAttribute('style');
+  const popover = floating.getAttribute('popover');
+  let destroyed = false;
+  let observer = null;
+  let update = () => {};
+  let cleanupMode = () => {};
+
+  floating.setAttribute('popover', 'manual');
+  const supportsAnchors = typeof CSS !== 'undefined' && CSS.supports?.('anchor-name: --zx-a');
+  if (supportsAnchors) {
+    const anchorName = `--${uid('zx-a')}`;
+    /** @type {HTMLElement} */ (anchor).style.setProperty('anchor-name', anchorName);
+    floating.style.position = 'fixed';
+    floating.style.inset = 'auto';
+    floating.style.margin = '0';
+    floating.style.setProperty('position-anchor', anchorName);
+    floating.style.setProperty('position-area', positionArea(placement));
+    floating.style.setProperty('inset-area', positionArea(placement));
+    floating.style.setProperty(
+      'position-try-fallbacks',
+      flip ? 'flip-block, flip-inline, flip-block flip-inline' : 'none'
+    );
+    floating.style.setProperty(placement.startsWith('top') ? 'margin-block-end' : 'margin-block-start', `${offset}px`);
+    update = () => {
+      if (matchWidth) floating.style.minWidth = `${anchor.getBoundingClientRect().width}px`;
+    };
+    if (typeof ResizeObserver === 'function') {
+      observer = new ResizeObserver(update);
+      observer.observe(anchor);
+    }
+  } else {
+    floating.style.position = 'fixed';
+    floating.style.inset = 'auto';
+    floating.style.margin = '0';
+    update = () => updateFallback(anchor, floating, { placement, offset, flip, matchWidth });
+    window.addEventListener('scroll', update, { capture: true, passive: true });
+    window.addEventListener('resize', update, { passive: true });
+    if (typeof ResizeObserver === 'function') {
+      observer = new ResizeObserver(update);
+      observer.observe(anchor);
+    }
+    cleanupMode = () => {
+      window.removeEventListener('scroll', update, true);
+      window.removeEventListener('resize', update);
+    };
+  }
+
+  showPopover(floating);
+  update();
+
+  return {
+    /** Recomputes fallback coordinates and matched width. @returns {void} */
+    update() {
+      if (!destroyed) update();
+    },
+
+    /** Hides the popover and restores changed attributes. @returns {void} */
+    destroy() {
+      if (destroyed) return;
+      destroyed = true;
+      observer?.disconnect();
+      cleanupMode();
+      hidePopover(floating);
+      restoreAttribute(anchor, 'style', anchorStyle);
+      restoreAttribute(floating, 'style', floatingStyle);
+      restoreAttribute(floating, 'popover', popover);
+    }
+  };
+}
+
+/** @param {string} placement @returns {string} */
+function positionArea(placement) {
+  return {
+    'bottom-start': 'block-end span-inline-end',
+    'bottom-end': 'block-end span-inline-start',
+    'top-start': 'block-start span-inline-end',
+    'top-end': 'block-start span-inline-start',
+    bottom: 'block-end',
+    top: 'block-start'
+  }[placement];
+}
+
+/**
+ * @param {Element} anchor
+ * @param {HTMLElement} floating
+ * @param {Required<PositionOptions>} options
+ * @returns {void}
+ */
+function updateFallback(anchor, floating, { placement, offset, flip, matchWidth }) {
+  const anchorRect = anchor.getBoundingClientRect();
+  if (matchWidth) floating.style.minWidth = `${anchorRect.width}px`;
+  const floatingRect = floating.getBoundingClientRect();
+  const viewportWidth = document.documentElement.clientWidth || window.innerWidth;
+  const viewportHeight = document.documentElement.clientHeight || window.innerHeight;
+  let actualPlacement = placement;
+  const prefersBottom = placement.startsWith('bottom');
+  const bottomY = anchorRect.bottom + offset;
+  const topY = anchorRect.top - offset - floatingRect.height;
+
+  if (flip) {
+    if (prefersBottom && bottomY + floatingRect.height > viewportHeight && topY >= 0) {
+      actualPlacement = /** @type {typeof placement} */ (placement.replace('bottom', 'top'));
+    } else if (!prefersBottom && topY < 0 && bottomY + floatingRect.height <= viewportHeight) {
+      actualPlacement = /** @type {typeof placement} */ (placement.replace('top', 'bottom'));
+    }
+  }
+
+  let left;
+  if (actualPlacement.endsWith('-end')) left = anchorRect.right - floatingRect.width;
+  else if (actualPlacement.endsWith('-start')) left = anchorRect.left;
+  else left = anchorRect.left + (anchorRect.width - floatingRect.width) / 2;
+  const top = actualPlacement.startsWith('bottom') ? bottomY : topY;
+  floating.style.left = `${Math.round(clamp(left, 0, Math.max(0, viewportWidth - floatingRect.width)))}px`;
+  floating.style.top = `${Math.round(clamp(top, 0, Math.max(0, viewportHeight - floatingRect.height)))}px`;
+}
+
+/** @param {HTMLElement} element @returns {void} */
+function showPopover(element) {
+  if (typeof element.showPopover !== 'function') return;
+  try {
+    element.showPopover();
+  } catch {
+    // A disconnected, already-open, or transitioning popover cannot be shown.
+  }
+}
+
+/** @param {HTMLElement} element @returns {void} */
+function hidePopover(element) {
+  if (typeof element.hidePopover !== 'function') return;
+  try {
+    element.hidePopover();
+  } catch {
+    // A disconnected or already-hidden popover is absent from the top layer.
+  }
+}
+
+/** @param {Element} element @param {string} name @param {string|null} value @returns {void} */
+function restoreAttribute(element, name, value) {
+  if (value === null) element.removeAttribute(name);
+  else element.setAttribute(name, value);
+}

package/src/core/storage.js

@@ -0,0 +1,175 @@
+// @ts-check
+/**
+ * @typedef {Object} StorageOptions
+ * @property {'local'|'session'} [area='local'] Backing Web Storage area.
+ */
+
+/**
+ * @typedef {Object} NamespacedStorage
+ * @property {(key: string, fallback?: any) => any} get Reads and decodes a value.
+ * @property {(key: string, value: unknown) => void} set Encodes and writes a value.
+ * @property {(key: string) => void} remove Deletes a single key.
+ * @property {() => string[]} keys Lists the namespace's keys without their prefix.
+ * @property {() => void} clear Deletes every key in the namespace, leaving other namespaces alone.
+ */
+
+/** Every key written by this module carries this prefix plus its namespace. */
+const PREFIX = 'zx:';
+/** Written and removed once to detect an area that exists but refuses writes. */
+const PROBE_KEY = 'zx:__probe__';
+
+/**
+ * Creates a namespaced, JSON-encoded view of `localStorage` or `sessionStorage`.
+ *
+ * Every key is stored as `zx:<namespace>:<key>`, so several features can share one origin without
+ * colliding, and `clear()` only touches the namespace it belongs to. When the storage area is
+ * unavailable or refuses a write — private browsing, a full quota, cookies disabled — the view
+ * transparently falls back to an in-memory map that lives as long as the page, so callers never
+ * need a try/catch and never see an exception.
+ *
+ * @param {string} namespace Namespace segment, typically an application or feature name.
+ * @param {StorageOptions} [options={}] Area selection.
+ * @returns {NamespacedStorage}
+ */
+export function storage(namespace, options = {}) {
+  const { area = 'local' } = options;
+  const prefix = `${PREFIX}${String(namespace ?? '')}:`;
+  /** @type {Map<string, string>} */
+  const memory = new Map();
+  let backing = resolveArea(area);
+
+  /** @param {string} key @returns {string|null} */
+  const readRaw = (key) => {
+    if (backing !== null) {
+      try {
+        return backing.getItem(key);
+      } catch {
+        backing = null;
+      }
+    }
+    return memory.has(key) ? memory.get(key) : null;
+  };
+
+  /** @param {string} key @param {string} raw @returns {void} */
+  const writeRaw = (key, raw) => {
+    if (backing !== null) {
+      try {
+        backing.setItem(key, raw);
+        return;
+      } catch {
+        // A quota error mid-session degrades this view to memory rather than throwing.
+        backing = null;
+      }
+    }
+    memory.set(key, raw);
+  };
+
+  /** @param {string} key @returns {void} */
+  const removeRaw = (key) => {
+    if (backing !== null) {
+      try {
+        backing.removeItem(key);
+      } catch {
+        backing = null;
+      }
+    }
+    memory.delete(key);
+  };
+
+  /** @returns {string[]} */
+  const rawKeys = () => {
+    if (backing !== null) {
+      try {
+        const found = [];
+        for (let index = 0; index < backing.length; index += 1) {
+          const key = backing.key(index);
+          if (typeof key === 'string' && key.startsWith(prefix)) found.push(key);
+        }
+        return found;
+      } catch {
+        backing = null;
+      }
+    }
+    return [...memory.keys()].filter((key) => key.startsWith(prefix));
+  };
+
+  return {
+    /**
+     * Reads a value, returning the fallback for a missing key or unparseable JSON.
+     * @param {string} key Key within the namespace.
+     * @param {any} [fallback] Value returned when nothing usable is stored.
+     * @returns {any}
+     */
+    get(key, fallback) {
+      const raw = readRaw(prefix + key);
+      if (raw === null || raw === undefined) return fallback;
+      try {
+        return JSON.parse(raw);
+      } catch {
+        return fallback;
+      }
+    },
+
+    /**
+     * Writes a JSON-encoded value. `undefined` and values JSON cannot represent remove the key.
+     * @param {string} key Key within the namespace.
+     * @param {unknown} value Value to store.
+     * @returns {void}
+     */
+    set(key, value) {
+      let raw;
+      try {
+        raw = JSON.stringify(value);
+      } catch {
+        // Circular structures and BigInt are not storable; dropping the key beats throwing.
+        raw = undefined;
+      }
+      if (raw === undefined) removeRaw(prefix + key);
+      else writeRaw(prefix + key, raw);
+    },
+
+    /**
+     * Removes a single key.
+     * @param {string} key Key within the namespace.
+     * @returns {void}
+     */
+    remove(key) {
+      removeRaw(prefix + key);
+    },
+
+    /**
+     * Lists the namespace's keys with the prefix stripped.
+     * @returns {string[]}
+     */
+    keys() {
+      return rawKeys().map((key) => key.slice(prefix.length));
+    },
+
+    /**
+     * Removes every key in the namespace and nothing else.
+     * @returns {void}
+     */
+    clear() {
+      for (const key of rawKeys()) removeRaw(key);
+    }
+  };
+}
+
+/**
+ * Returns a usable Web Storage area, or null when it is missing or rejects writes.
+ * @param {'local'|'session'} area Area name.
+ * @returns {Storage|null}
+ */
+function resolveArea(area) {
+  const name = area === 'session' ? 'sessionStorage' : 'localStorage';
+  try {
+    const candidate = globalThis[name];
+    if (!candidate || typeof candidate.getItem !== 'function') return null;
+    // Safari's private mode exposes the API and throws on write, so probe before trusting it.
+    candidate.setItem(PROBE_KEY, '1');
+    candidate.removeItem(PROBE_KEY);
+    return candidate;
+  } catch {
+    return null;
+  }
+}

package/src/core/util.js

@@ -0,0 +1,336 @@
+// @ts-check
+/**
+ * Returns a debounced wrapper that runs after calls have stopped for the delay.
+ * @template {(...args: any[]) => any} T
+ * @param {T} fn Function to debounce.
+ * @param {number} ms Delay in milliseconds.
+ * @returns {(...args: Parameters<T>) => void}
+ */
+export function debounce(fn, ms) {
+  let timer = null;
+
+  return function debounced(...args) {
+    const context = this;
+    if (timer !== null) clearTimeout(timer);
+    timer = setTimeout(() => {
+      timer = null;
+      fn.apply(context, args);
+    }, ms);
+  };
+}
+
+/**
+ * @typedef {Object} ThrottleOptions
+ * @property {boolean} [leading=true] Whether the first call in a window runs immediately.
+ * @property {boolean} [trailing=true] Whether a call made during a window runs when it closes.
+ */
+
+/**
+ * Returns a throttled wrapper that runs at most once per interval, on the leading edge, the
+ * trailing edge, or both. The trailing call replays the most recent arguments and context.
+ * @template {(...args: any[]) => any} T
+ * @param {T} fn Function to throttle.
+ * @param {number} ms Interval in milliseconds.
+ * @param {ThrottleOptions} [options={}] Edge behaviour.
+ * @returns {(...args: Parameters<T>) => void}
+ */
+export function throttle(fn, ms, { leading = true, trailing = true } = {}) {
+  const interval = Math.max(0, Number(ms) || 0);
+  let timer = null;
+  let previous = 0;
+  /** @type {any[]|null} */
+  let pendingArgs = null;
+  let pendingContext = null;
+
+  const runTrailing = () => {
+    timer = null;
+    // Without a leading edge the next call must start a fresh window rather than fire at once.
+    previous = leading ? Date.now() : 0;
+    const args = pendingArgs;
+    const context = pendingContext;
+    pendingArgs = null;
+    pendingContext = null;
+    if (args !== null) fn.apply(context, args);
+  };
+
+  return function throttled(...args) {
+    const now = Date.now();
+    if (previous === 0 && !leading) previous = now;
+    const remaining = interval - (now - previous);
+
+    if (remaining <= 0 || remaining > interval) {
+      if (timer !== null) {
+        clearTimeout(timer);
+        timer = null;
+      }
+      previous = now;
+      pendingArgs = null;
+      pendingContext = null;
+      fn.apply(this, args);
+      return;
+    }
+
+    if (!trailing) return;
+    pendingArgs = args;
+    pendingContext = this;
+    if (timer === null) timer = setTimeout(runTrailing, remaining);
+  };
+}
+
+let uidSequence = 0;
+
+/**
+ * Creates a process-unique identifier suitable for DOM IDs and CSS names.
+ * @param {string} [prefix='zx'] Identifier prefix.
+ * @returns {string}
+ */
+export function uid(prefix = 'zx') {
+  uidSequence += 1;
+  return `${prefix}-${Date.now().toString(36)}-${uidSequence.toString(36)}`;
+}
+
+/**
+ * Recursively merges plain objects without mutating either input.
+ * Arrays and other values are replaced rather than merged.
+ * @template T
+ * @template U
+ * @param {T} a Base value.
+ * @param {U} b Overriding value.
+ * @returns {T & U}
+ */
+export function deepMerge(a, b) {
+  const result = isPlainObject(a) ? clonePlainObject(a) : {};
+  if (!isPlainObject(b)) return /** @type {T & U} */ (cloneValue(b));
+
+  for (const [key, value] of Object.entries(b)) {
+    if (isPlainObject(value) && isPlainObject(result[key])) {
+      result[key] = deepMerge(result[key], value);
+    } else {
+      result[key] = cloneValue(value);
+    }
+  }
+  return /** @type {T & U} */ (result);
+}
+
+/**
+ * Reports whether a value is a DOM Element, including elements from another realm.
+ * @param {unknown} value Value to inspect.
+ * @returns {value is Element}
+ */
+export function isElement(value) {
+  return Boolean(value && typeof value === 'object'
+    && /** @type {{nodeType?: unknown}} */ (value).nodeType === 1);
+}
+
+/**
+ * Restricts a number to an inclusive range.
+ * @param {number} n Value to restrict.
+ * @param {number} min Minimum value.
+ * @param {number} max Maximum value.
+ * @returns {number}
+ */
+export function clamp(n, min, max) {
+  return Math.min(max, Math.max(min, n));
+}
+
+/**
+ * Normalizes a nullable, scalar, iterable, or array value to a new array.
+ * @template T
+ * @param {T|Iterable<T>|ArrayLike<T>|null|undefined} value Value to normalize.
+ * @returns {T[]}
+ */
+export function toArray(value) {
+  if (value == null) return [];
+  if (Array.isArray(value)) return value.slice();
+  // Both branches are runtime feature tests; the parameter type cannot express either.
+  const candidate = /** @type {any} */ (value);
+  if (typeof value !== 'string' && typeof candidate?.[Symbol.iterator] === 'function') {
+    return Array.from(candidate);
+  }
+  if (typeof value !== 'string' && typeof candidate?.length === 'number') {
+    return Array.from(candidate);
+  }
+  return [/** @type {T} */ (value)];
+}
+
+/**
+ * @template T
+ * @typedef {string|((item: T) => unknown)} KeySelector A property name or an accessor function.
+ */
+
+/**
+ * @template T
+ * @typedef {KeySelector<T>|{key: KeySelector<T>, dir?: 'asc'|'desc'}} SortKey
+ * A property name (prefix with `-` to sort descending), an accessor, or an explicit direction.
+ */
+
+/**
+ * Groups items into a plain object of arrays, keyed by a property or accessor and ordered by first
+ * appearance.
+ * @template T
+ * @param {Iterable<T>|ArrayLike<T>|null|undefined} items Items to group.
+ * @param {KeySelector<T>} key Property name or accessor returning the group key.
+ * @returns {Record<string, T[]>}
+ */
+export function groupBy(items, key) {
+  const select = keySelector(key);
+  /** @type {Map<string, T[]>} */
+  const groups = new Map();
+
+  for (const item of toArray(items)) {
+    const name = String(select(item));
+    const bucket = groups.get(name);
+    if (bucket === undefined) groups.set(name, [item]);
+    else bucket.push(item);
+  }
+  // fromEntries defines own properties, so a group named "__proto__" stays plain data.
+  return Object.fromEntries(groups);
+}
+
+/**
+ * Sorts items by one or more keys into a NEW array, leaving the input untouched. Strings compare
+ * with `localeCompare` (digit runs compare numerically), numbers, booleans, and dates compare by
+ * value, and null, undefined, and NaN always sort last regardless of direction.
+ * @template T
+ * @param {Iterable<T>|ArrayLike<T>|null|undefined} items Items to sort.
+ * @param {...SortKey<T>} keys Sort keys applied in order.
+ * @returns {T[]}
+ */
+export function sortBy(items, ...keys) {
+  const list = toArray(items);
+  const comparators = keys.map(toComparator);
+  if (comparators.length === 0) return list;
+
+  return list.sort((a, b) => {
+    for (const compare of comparators) {
+      const result = compare(a, b);
+      if (result !== 0) return result;
+    }
+    return 0;
+  });
+}
+
+/**
+ * Removes duplicates, keeping the first occurrence, and returns a new array.
+ * @template T
+ * @param {Iterable<T>|ArrayLike<T>|null|undefined} items Items to filter.
+ * @param {KeySelector<T>} [key] Property name or accessor; the item itself when omitted.
+ * @returns {T[]}
+ */
+export function uniqueBy(items, key) {
+  const select = key == null ? (/** @type {T} */ item) => item : keySelector(key);
+  const seen = new Set();
+  const result = [];
+
+  for (const item of toArray(items)) {
+    const identity = select(item);
+    if (seen.has(identity)) continue;
+    seen.add(identity);
+    result.push(item);
+  }
+  return result;
+}
+
+/**
+ * Escapes regular-expression metacharacters so a value can be used as a literal pattern.
+ * @param {unknown} value Value to escape.
+ * @returns {string}
+ */
+export function escapeRegExp(value) {
+  return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/** @template T @param {KeySelector<T>} key @returns {(item: T) => unknown} */
+function keySelector(key) {
+  if (typeof key === 'function') return key;
+  const name = String(key);
+  return (item) => (item == null ? undefined : item[name]);
+}
+
+/** @template T @param {SortKey<T>} key @returns {(a: T, b: T) => number} */
+function toComparator(key) {
+  let select;
+  let direction = 1;
+
+  if (typeof key === 'function') {
+    select = key;
+  } else if (key !== null && typeof key === 'object') {
+    select = keySelector(key.key);
+    if (String(key.dir).toLowerCase() === 'desc') direction = -1;
+  } else {
+    let name = String(key);
+    if (name.startsWith('-')) {
+      direction = -1;
+      name = name.slice(1);
+    } else if (name.startsWith('+')) {
+      name = name.slice(1);
+    }
+    select = keySelector(name);
+  }
+
+  return (a, b) => {
+    const left = select(a);
+    const right = select(b);
+    const leftEmpty = isEmptyValue(left);
+    const rightEmpty = isEmptyValue(right);
+    // Empties are placed outside the direction flip so they stay at the end either way.
+    if (leftEmpty || rightEmpty) {
+      if (leftEmpty && rightEmpty) return 0;
+      return leftEmpty ? 1 : -1;
+    }
+    return direction * compareValues(left, right);
+  };
+}
+
+/** @param {unknown} value @returns {boolean} */
+function isEmptyValue(value) {
+  return value == null || (typeof value === 'number' && Number.isNaN(value));
+}
+
+/** @param {any} a @param {any} b @returns {number} */
+function compareValues(a, b) {
+  if (a instanceof Date || b instanceof Date) {
+    return sign(toTimestamp(a) - toTimestamp(b));
+  }
+  if (typeof a === 'boolean' || typeof b === 'boolean') {
+    return sign(Number(a) - Number(b));
+  }
+  if (typeof a === 'number' && typeof b === 'number') {
+    return sign(a - b);
+  }
+  return String(a).localeCompare(String(b), undefined, { numeric: true });
+}
+
+/** @param {any} value @returns {number} */
+function toTimestamp(value) {
+  if (value instanceof Date) return value.getTime();
+  const number = Number(value);
+  return Number.isFinite(number) ? number : 0;
+}
+
+/** @param {number} value @returns {number} */
+function sign(value) {
+  if (Number.isNaN(value)) return 0;
+  return value < 0 ? -1 : (value > 0 ? 1 : 0);
+}
+
+/** @param {unknown} value @returns {value is Record<string, any>} */
+function isPlainObject(value) {
+  if (value === null || typeof value !== 'object') return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+/** @param {Record<string, any>} value @returns {Record<string, any>} */
+function clonePlainObject(value) {
+  const result = {};
+  for (const [key, item] of Object.entries(value)) result[key] = cloneValue(item);
+  return result;
+}
+
+/** @param {any} value @returns {any} */
+function cloneValue(value) {
+  if (isPlainObject(value)) return clonePlainObject(value);
+  if (Array.isArray(value)) return value.map(cloneValue);
+  return value;
+}