@zeyos/zx 2.1.0 → 2.2.0

package/src/core/breakpoint.js

@@ -0,0 +1,150 @@
+// @ts-check
+/**
+ * Named width thresholds, and a way to react to one being crossed.
+ *
+ * The scale lives here rather than in the token layer because a CSS custom property cannot be
+ * used inside a media query, so a `--zx-bp-*` token would be a value no stylesheet could read.
+ * Zx's own layout utilities avoid the problem entirely — `.zx-grid` reflows on intrinsic track
+ * widths, not on breakpoints — which leaves this module for the cases only script can decide:
+ * rendering a Table as cards below a width, collapsing a MasterPanel, choosing a chart density.
+ * @module zx/core/breakpoint
+ */
+
+import { isElement } from './util.js';
+
+/** @typedef {'xs'|'sm'|'md'|'lg'|'xl'} BreakpointName */
+
+/**
+ * Lower bound of each named breakpoint, in pixels. A width below `sm` is `xs`.
+ * @type {Readonly<Record<Exclude<BreakpointName, 'xs'>, number>>}
+ */
+export const breakpoints = Object.freeze({ sm: 480, md: 768, lg: 1024, xl: 1280 });
+
+/** Names from widest to narrowest, which is the order a lookup has to test them in. */
+const ORDER = /** @type {const} */ (['xl', 'lg', 'md', 'sm']);
+
+/**
+ * The breakpoint a width falls into.
+ * @param {number} width Width in pixels.
+ * @returns {BreakpointName}
+ */
+export function breakpointOf(width) {
+  const value = Number(width);
+  if (!Number.isFinite(value)) return 'xs';
+  for (const name of ORDER) {
+    if (value >= breakpoints[name]) return name;
+  }
+  return 'xs';
+}
+
+/**
+ * Whether a width has reached a named breakpoint. `matchBreakpoint('md', 900)` is the script
+ * equivalent of `@media (min-width: 768px)`.
+ * @param {BreakpointName} name Breakpoint to test against.
+ * @param {number} width Width in pixels.
+ * @returns {boolean}
+ */
+export function matchBreakpoint(name, width) {
+  if (name === 'xs') return true;
+  const min = breakpoints[name];
+  if (min === undefined) throw new RangeError(`Unknown breakpoint "${name}"`);
+  return Number(width) >= min;
+}
+
+/**
+ * @typedef {Object} BreakpointOptions
+ * @property {Element|Window} [target=window] What to measure. An Element is watched with a
+ *   `ResizeObserver`, which is what a component inside a split pane or a modal needs — the
+ *   viewport width says nothing about the space it actually has.
+ */
+
+/**
+ * @typedef {Object} BreakpointController
+ * @property {() => BreakpointName} current The breakpoint as last measured.
+ * @property {() => void} destroy Stops observing.
+ */
+
+/**
+ * Calls back whenever the observed width crosses into another breakpoint, and once immediately
+ * with the current one.
+ * @param {(name: BreakpointName, width: number) => void} handler Called on every change.
+ * @param {BreakpointOptions} [options={}] What to observe.
+ * @returns {BreakpointController}
+ */
+export function onBreakpoint(handler, options = {}) {
+  if (typeof handler !== 'function') throw new TypeError('onBreakpoint requires a handler');
+  /*
+   * An explicitly passed target that is not an element is a mistake worth shouting about. Falling
+   * back to the window looks like it works — the callback fires, the values are plausible — while
+   * measuring something entirely different from what the caller asked for. Table hit exactly this:
+   * it passed `this.el` before the base constructor had assigned it, and quietly watched the
+   * viewport instead of itself.
+   */
+  if ('target' in options && !isElement(options.target)
+    && /** @type {unknown} */ (options.target) !== /** @type {unknown} */ (globalThis)) {
+    throw new TypeError('onBreakpoint target must be an Element or the window');
+  }
+  const target = options.target ?? globalThis;
+  const element = isElement(target) ? /** @type {Element} */ (target) : null;
+  /** Null until the first real measurement — see `update()` on why 0 is not a band. */
+  let name = /** @type {BreakpointName|null} */ (null);
+  let destroyed = false;
+  let observer = null;
+
+  const measure = () => (element
+    ? element.getBoundingClientRect().width
+    : Number(globalThis.innerWidth) || 0);
+
+  const update = () => {
+    if (destroyed) return;
+    const width = measure();
+    /*
+     * A zero width is not the `xs` band — it is no measurement at all, which is what an element
+     * that has not been laid out yet reports. Recording it as a band silently disarms the whole
+     * watcher: the next real width lands in the same band and never notifies. Table hit exactly
+     * this, rendering before it was inserted, measuring 0, and then sitting at 154px inside a
+     * narrow pane without ever being told it should stack.
+     */
+    if (element && width === 0) return;
+    const next = breakpointOf(width);
+    if (next === name) return;
+    name = next;
+    handler(name, width);
+  };
+
+  update();
+
+  /*
+   * Resize notifications are answered on the next frame rather than inside the observer callback.
+   * A handler that reacts to a width by changing layout — which is the entire point of this
+   * module; Table restyles itself — resizes the very element being observed, and the browser
+   * reports that as "ResizeObserver loop completed with undelivered notifications". Deferring
+   * breaks the cycle, and coalesces a burst of notifications into one.
+   */
+  let frame = 0;
+  const schedule = () => {
+    if (frame || destroyed) return;
+    frame = requestAnimationFrame(() => {
+      frame = 0;
+      update();
+    });
+  };
+
+  if (element && typeof ResizeObserver === 'function') {
+    observer = new ResizeObserver(schedule);
+    observer.observe(element);
+  } else {
+    globalThis.addEventListener?.('resize', update, { passive: true });
+  }
+
+  return {
+    current: () => name ?? breakpointOf(measure()),
+    destroy: () => {
+      if (destroyed) return;
+      destroyed = true;
+      if (frame) cancelAnimationFrame(frame);
+      observer?.disconnect();
+      globalThis.removeEventListener?.('resize', update);
+    }
+  };
+}

package/src/core/component.js

@@ -0,0 +1,292 @@
+// @ts-check
+import { h, resolveElement } from './dom.js';
+import { getLanguage, printf, translate } from './i18n.js';
+import { deepMerge, isElement } from './util.js';
+
+/** @typedef {Record<string, any>} ComponentOptions */
+/** @typedef {(event: Event & {detail?: Record<string, unknown>}) => void} ComponentListener */
+
+/** @type {WeakMap<Element, Component>} */
+const registry = new WeakMap();
+
+/**
+ * Base class for lifecycle-safe Zx components.
+ *
+ * Generic over its own options type so a subclass can bind its `XOptions` typedef with
+ * `@extends {Component<XOptions>}`. That is what types `new Select(target, { … })` for editors and
+ * for TypeScript consumers: a subclass declares no constructor of its own, so it inherits this
+ * signature, and without the binding every component would accept any object at all.
+ *
+ * @template {ComponentOptions} [TOptions=ComponentOptions]
+ * @fires Component#event
+ */
+export class Component extends EventTarget {
+  /** @type {ComponentOptions} */
+  static defaults = {};
+
+  /**
+   * BEM block a subclass wants on its root, without the `zx-` prefix. Empty on the base, which is
+   * the same falsy answer the undeclared property gave — declared so the statics are visible to
+   * `this.constructor` and to the generated declarations.
+   * @type {string}
+   */
+  static cssName = '';
+
+  /** @type {Element} Root element. */
+  el;
+
+  /** @type {Record<string, Element>} Elements captured by `h()` ref properties. */
+  refs;
+
+  /** @type {Readonly<TOptions>} Merged component options. */
+  options;
+
+  #abort = new AbortController();
+  #created = false;
+  #destroyed = false;
+  #addedRootClass = false;
+
+  /**
+   * Creates a component around an existing target, or asks `render()` to create its root.
+   * @param {Element|string|null} target Existing element, selector, or null.
+   * @param {TOptions} [options={}] Component options.
+   */
+  constructor(target, options = /** @type {TOptions} */ ({})) {
+    super();
+    /** `this.constructor` is typed `Function`, which hides the statics this class declares. */
+    const self = /** @type {typeof Component} */ (this.constructor);
+    this.#created = target === null;
+    const resolved = resolveElement(target);
+    if (target !== null && !resolved) throw new TypeError('Component target could not be resolved');
+    this.el = /** @type {Element} */ (resolved);
+    this.refs = {};
+
+    const merged = /** @type {TOptions} */ (mergeOptions(self, options));
+    const eventOptions = [];
+    for (const [key, value] of Object.entries(merged)) {
+      if (/^on[a-z]/.test(key) && typeof value === 'function') {
+        eventOptions.push([key.slice(2), value]);
+        delete merged[key];
+      }
+    }
+    if (merged.msg && typeof merged.msg === 'object') Object.freeze(merged.msg);
+    this.options = Object.freeze(merged);
+    for (const [type, listener] of eventOptions) this.on(type, listener);
+
+    let rendered;
+    try {
+      rendered = h.scope(this.refs, () => this.render());
+    } catch (error) {
+      this.#abort.abort();
+      throw error;
+    }
+    if (this.#created) {
+      const root = isElement(rendered) ? rendered : this.el;
+      if (!isElement(root)) {
+        this.#abort.abort();
+        throw new TypeError('render() must return an Element (or assign this.el) when target is null');
+      }
+      this.el = root;
+    }
+    if (!isElement(this.el)) {
+      this.#abort.abort();
+      throw new TypeError('Component requires a root Element');
+    }
+
+    const cssName = self.cssName;
+    if (typeof cssName === 'string' && cssName) {
+      const className = `zx-${cssName}`;
+      this.#addedRootClass = !this.el.classList.contains(className);
+      this.el.classList.add(className);
+    }
+    registry.set(this.el, this);
+  }
+
+  /**
+   * Renders or enhances the component root. Subclasses creating a root must return it.
+   * @returns {Element|null}
+   */
+  render() {
+    return this.el ?? null;
+  }
+
+  /**
+   * Subscribes to a component-level event for this component's lifetime.
+   * @param {string} type Lowercase event name.
+   * @param {ComponentListener|EventListenerObject} fn Listener.
+   * @returns {this}
+   */
+  on(type, fn) {
+    this.addEventListener(type, fn, { signal: this.#abort.signal });
+    return this;
+  }
+
+  /**
+   * Removes a component-level event listener.
+   * @param {string} type Event name.
+   * @param {ComponentListener|EventListenerObject} fn Listener.
+   * @returns {this}
+   */
+  off(type, fn) {
+    this.removeEventListener(type, fn);
+    return this;
+  }
+
+  /**
+   * Subscribes to one component-level event occurrence.
+   * @param {string} type Event name.
+   * @param {ComponentListener|EventListenerObject} fn Listener.
+   * @returns {this}
+   */
+  once(type, fn) {
+    this.addEventListener(type, fn, { once: true, signal: this.#abort.signal });
+    return this;
+  }
+
+  /**
+   * MooTools-compatible alias of `on()`.
+   * @param {string} type Event name.
+   * @param {ComponentListener|EventListenerObject} fn Listener.
+   * @returns {this}
+   */
+  addEvent(type, fn) {
+    return this.on(type, fn);
+  }
+
+  /**
+   * Dispatches a component event and a bubbling, composed `zx-*` DOM event.
+   * @param {string} type Lowercase event name.
+   * @param {Record<string, unknown>} [detail={}] Single event detail object.
+   * @returns {Event & {detail: Record<string, unknown>}}
+   * @fires Component#event
+   */
+  emit(type, detail = {}) {
+    if (detail === null || typeof detail !== 'object' || Array.isArray(detail)) {
+      throw new TypeError('Event detail must be an object');
+    }
+    const componentEvent = createCustomEvent(type, detail, { cancelable: true });
+    this.dispatchEvent(componentEvent);
+    if (this.el) {
+      this.el.dispatchEvent(createCustomEvent(`zx-${type}`, detail, {
+        bubbles: true,
+        composed: true,
+        cancelable: true
+      }));
+    }
+    return componentEvent;
+  }
+
+  /**
+   * Adds an automatically cleaned-up DOM event listener.
+   * @param {EventTarget} element DOM event target.
+   * @param {string} type Event name.
+   * @param {EventListenerOrEventListenerObject} fn Listener.
+   * @param {boolean|AddEventListenerOptions} [opts={}] Listener options.
+   * @returns {this}
+   */
+  listen(element, type, fn, opts = {}) {
+    const options = typeof opts === 'boolean' ? { capture: opts } : { ...opts };
+    element.addEventListener(type, fn, { ...options, signal: this.#abort.signal });
+    return this;
+  }
+
+  /**
+   * Returns the component's root element.
+   * @returns {Element}
+   */
+  toElement() {
+    return this.el;
+  }
+
+  /**
+   * Resolves and interpolates a component-local or global translation.
+   * @param {string} key Message key.
+   * @param {...unknown} args Positional interpolation values.
+   * @returns {string}
+   */
+  msg(key, ...args) {
+    const messages = this.options.msg;
+    const lang = this.options.lang ?? this.options.language ?? getLanguage();
+    const localized = messages?.[lang]?.[key];
+    if (localized != null) return printf(String(localized), args);
+    const direct = messages?.[key];
+    if (direct != null) return printf(String(direct), args);
+    return translate(key, args);
+  }
+
+  /**
+   * Aborts listeners, unregisters the component, and removes roots created by the component.
+   * Safe to call repeatedly.
+   * @returns {void}
+   */
+  destroy() {
+    if (this.#destroyed) return;
+    this.#destroyed = true;
+    this.#abort.abort();
+    if (registry.get(this.el) === this) registry.delete(this.el);
+    const cssName = /** @type {typeof Component} */ (this.constructor).cssName;
+    if (this.#addedRootClass && typeof cssName === 'string' && this.el) {
+      this.el.classList.remove(`zx-${cssName}`);
+    }
+    if (this.#created && this.el) this.el.remove();
+  }
+
+  /**
+   * Retrieves the component currently registered for an element.
+   * @param {Element} element Root element.
+   * @returns {Component|null}
+   */
+  static from(element) {
+    return registry.get(element) ?? null;
+  }
+}
+
+/**
+ * Generic component event emitted under the name passed to `emit()`.
+ * @event Component#event
+ * @type {CustomEvent<Record<string, unknown>>}
+ */
+
+/** @param {typeof Component} constructor @param {ComponentOptions} options @returns {ComponentOptions} */
+function mergeOptions(constructor, options) {
+  const chain = [];
+  let current = constructor;
+  while (current && current !== Function.prototype) {
+    if (Object.prototype.hasOwnProperty.call(current, 'defaults')) chain.unshift(current.defaults);
+    current = Object.getPrototypeOf(current);
+  }
+
+  const result = {};
+  let messages = {};
+  let hasMessages = false;
+  for (const defaults of chain) {
+    if (!defaults || typeof defaults !== 'object') continue;
+    Object.assign(result, defaults);
+    if (defaults.msg && typeof defaults.msg === 'object') {
+      hasMessages = true;
+      messages = deepMerge(messages, defaults.msg);
+    }
+  }
+  Object.assign(result, options && typeof options === 'object' ? options : {});
+  if (options?.msg && typeof options.msg === 'object') {
+    hasMessages = true;
+    messages = deepMerge(messages, options.msg);
+  }
+  if (hasMessages) result.msg = messages;
+  return result;
+}
+
+/**
+ * @param {string} type
+ * @param {Record<string, unknown>} detail
+ * @param {CustomEventInit<Record<string, unknown>>} init
+ * @returns {Event & {detail: Record<string, unknown>}}
+ */
+function createCustomEvent(type, detail, init) {
+  if (typeof CustomEvent === 'function') {
+    return new CustomEvent(type, { ...init, detail });
+  }
+  const event = new Event(type, init);
+  Object.defineProperty(event, 'detail', { configurable: true, enumerable: true, value: detail });
+  return /** @type {Event & {detail: Record<string, unknown>}} */ (event);
+}

package/src/core/date.js

@@ -0,0 +1,216 @@
+// @ts-check
+import { getLanguage, translate } from './i18n.js';
+
+const MONTHS = [
+  'January', 'February', 'March', 'April', 'May', 'June',
+  'July', 'August', 'September', 'October', 'November', 'December'
+];
+const WEEKDAYS = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'];
+const TOKEN_PATTERN = /%[demYyHMSaAbBs]/g;
+
+/**
+ * Formats a local Date using strftime-style kernel tokens.
+ * @param {Date} date Date to format.
+ * @param {string} fmt Format containing `%d %e %m %Y %y %H %M %S %a %A %b %B %s` tokens.
+ * @returns {string}
+ */
+export function formatDate(date, fmt) {
+  if (!(date instanceof Date) || Number.isNaN(date.getTime())) return '';
+  return String(fmt).replace(TOKEN_PATTERN, (token) => {
+    switch (token) {
+      case '%d': return pad(date.getDate());
+      case '%e': return String(date.getDate());
+      case '%m': return pad(date.getMonth() + 1);
+      case '%Y': return String(date.getFullYear()).padStart(4, '0');
+      case '%y': return pad(date.getFullYear() % 100);
+      case '%H': return pad(date.getHours());
+      case '%M': return pad(date.getMinutes());
+      case '%S': return pad(date.getSeconds());
+      case '%a': return localizedShortName('weekday', date.getDay(), WEEKDAYS[date.getDay()]);
+      case '%A': return localizedName('weekday', date.getDay(), WEEKDAYS[date.getDay()]);
+      case '%b': return localizedShortName('month', date.getMonth(), MONTHS[date.getMonth()]);
+      case '%B': return localizedName('month', date.getMonth(), MONTHS[date.getMonth()]);
+      case '%s': return String(Math.floor(date.getTime() / 1000));
+      default: return token;
+    }
+  });
+}
+
+/**
+ * Parses numeric date tokens from a string, returning null for mismatches or invalid dates.
+ * Unspecified fields default to 1970-01-01 00:00:00 local time.
+ * @param {string} str Date text.
+ * @param {string} fmt Matching numeric format.
+ * @returns {Date|null}
+ */
+export function parseDate(str, fmt) {
+  const fields = [];
+  let pattern = '^';
+  let cursor = 0;
+
+  for (const match of String(fmt).matchAll(TOKEN_PATTERN)) {
+    pattern += escapeRegExp(String(fmt).slice(cursor, match.index));
+    const token = match[0];
+    const tokenPattern = numericPattern(token);
+    if (tokenPattern === null) return null;
+    pattern += `(${tokenPattern})`;
+    fields.push(token);
+    cursor = match.index + token.length;
+  }
+  pattern += escapeRegExp(String(fmt).slice(cursor)) + '$';
+
+  const matched = new RegExp(pattern).exec(String(str));
+  if (!matched) return null;
+  const values = Object.create(null);
+  fields.forEach((field, index) => {
+    values[field] = Number(matched[index + 1]);
+  });
+
+  if (values['%s'] !== undefined) {
+    const timestamp = values['%s'] * 1000;
+    const parsed = new Date(timestamp);
+    return Number.isNaN(parsed.getTime()) ? null : parsed;
+  }
+
+  const year = values['%Y'] ?? yearFromTwoDigits(values['%y']) ?? 1970;
+  const month = (values['%m'] ?? 1) - 1;
+  const day = values['%d'] ?? values['%e'] ?? 1;
+  const hour = values['%H'] ?? 0;
+  const minute = values['%M'] ?? 0;
+  const second = values['%S'] ?? 0;
+  const parsed = new Date(0);
+  parsed.setHours(0, 0, 0, 0);
+  parsed.setFullYear(year, month, day);
+  parsed.setHours(hour, minute, second, 0);
+
+  if (Number.isNaN(parsed.getTime())) return null;
+  if (values['%Y'] !== undefined && parsed.getFullYear() !== values['%Y']) return null;
+  if (values['%y'] !== undefined && parsed.getFullYear() % 100 !== values['%y']) return null;
+  if (values['%m'] !== undefined && parsed.getMonth() !== month) return null;
+  if (values['%d'] !== undefined && parsed.getDate() !== day) return null;
+  if (values['%e'] !== undefined && parsed.getDate() !== day) return null;
+  if (values['%H'] !== undefined && parsed.getHours() !== hour) return null;
+  if (values['%M'] !== undefined && parsed.getMinutes() !== minute) return null;
+  if (values['%S'] !== undefined && parsed.getSeconds() !== second) return null;
+  return parsed;
+}
+
+/**
+ * Clamps a date to optional inclusive bounds and returns a new Date.
+ * @param {Date} date Date to clamp.
+ * @param {Date|null|undefined} min Minimum date.
+ * @param {Date|null|undefined} max Maximum date.
+ * @returns {Date}
+ */
+export function clampDate(date, min, max) {
+  const value = date.getTime();
+  const minimum = min instanceof Date ? min.getTime() : -Infinity;
+  const maximum = max instanceof Date ? max.getTime() : Infinity;
+  return new Date(Math.min(maximum, Math.max(minimum, value)));
+}
+
+/**
+ * Reports whether two dates share the same local calendar day.
+ * @param {Date} a First date.
+ * @param {Date} b Second date.
+ * @returns {boolean}
+ */
+export function isSameDay(a, b) {
+  return a.getFullYear() === b.getFullYear() &&
+    a.getMonth() === b.getMonth() &&
+    a.getDate() === b.getDate();
+}
+
+/**
+ * Adds local calendar days without mutating the input.
+ * @param {Date} date Base date.
+ * @param {number} n Number of days.
+ * @returns {Date}
+ */
+export function addDays(date, n) {
+  const result = new Date(date.getTime());
+  result.setDate(result.getDate() + n);
+  return result;
+}
+
+/**
+ * Adds local calendar months without mutating the input, clamping to the target month's end.
+ * @param {Date} date Base date.
+ * @param {number} n Number of months.
+ * @returns {Date}
+ */
+export function addMonths(date, n) {
+  const result = new Date(date.getTime());
+  const day = result.getDate();
+  result.setDate(1);
+  result.setMonth(result.getMonth() + n);
+  const lastDay = new Date(result.getFullYear(), result.getMonth() + 1, 0).getDate();
+  result.setDate(Math.min(day, lastDay));
+  return result;
+}
+
+/**
+ * Returns the locale's first weekday (`0` Sunday through `6` Saturday), Monday by default.
+ * @param {string} [lang=getLanguage()] BCP 47 language tag.
+ * @returns {number}
+ */
+export function getWeekStart(lang = getLanguage()) {
+  if (!lang) return 1;
+  if (lang.toLowerCase() === 'en') return 1;
+  try {
+    /** `getWeekInfo()` and `weekInfo` are newer Intl surface than the bundled lib types know. */
+    const locale = /** @type {Intl.Locale & {getWeekInfo?: () => {firstDay?: number}, weekInfo?: {firstDay?: number}}} */
+      (new Intl.Locale(lang));
+    const weekInfo = locale.getWeekInfo?.() ?? locale.weekInfo;
+    if (weekInfo?.firstDay) return weekInfo.firstDay % 7;
+  } catch {
+    // Invalid or unsupported locale data uses the APG-friendly Monday default.
+  }
+  return 1;
+}
+
+/** @param {number} value @returns {string} */
+function pad(value) {
+  return String(value).padStart(2, '0');
+}
+
+/** @param {'month'|'weekday'} type @param {number} index @param {string} fallback @returns {string} */
+function localizedName(type, index, fallback) {
+  const key = `date.${type}.${index}`;
+  const value = translate(key);
+  return value === key ? fallback : value;
+}
+
+/** @param {'month'|'weekday'} type @param {number} index @param {string} fallback @returns {string} */
+function localizedShortName(type, index, fallback) {
+  const shortKey = `date.${type}.short.${index}`;
+  const shortValue = translate(shortKey);
+  if (shortValue !== shortKey) return shortValue;
+  return localizedName(type, index, fallback).slice(0, 3);
+}
+
+/** @param {string} token @returns {string|null} */
+function numericPattern(token) {
+  return {
+    '%d': '\\d{1,2}',
+    '%e': '\\d{1,2}',
+    '%m': '\\d{1,2}',
+    '%Y': '\\d{4}',
+    '%y': '\\d{2}',
+    '%H': '\\d{1,2}',
+    '%M': '\\d{1,2}',
+    '%S': '\\d{1,2}',
+    '%s': '-?\\d+'
+  }[token] ?? null;
+}
+
+/** @param {number|undefined} year @returns {number|undefined} */
+function yearFromTwoDigits(year) {
+  if (year === undefined) return undefined;
+  return year >= 69 ? 1900 + year : 2000 + year;
+}
+
+/** @param {string} value @returns {string} */
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}