@zeyos/zx 2.1.0 → 2.2.0

package/dist/zx-compat.esm.js

@@ -23,7 +23,8 @@ function deepMerge(a, b) {
   );
 }
 function isElement(value) {
-  return Boolean(value && typeof value === "object" && value.nodeType === 1);
+  return Boolean(value && typeof value === "object" && /** @type {{nodeType?: unknown}} */
+  value.nodeType === 1);
 }
 function clamp(n, min, max) {
   return Math.min(max, Math.max(min, n));
@@ -112,8 +113,12 @@ function resolveElement(target) {
 }
 function isPropsObject(value) {
   if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
-  if (typeof value.nodeType === "number") return false;
-  return typeof value.toElement !== "function";
+  const candidate = (
+    /** @type {Record<string, unknown>} */
+    value
+  );
+  if (typeof candidate.nodeType === "number") return false;
+  return typeof candidate.toElement !== "function";
 }
 function applyProperty(element, key, value) {
   if (key === "ref") {
@@ -171,15 +176,33 @@ function ariaAttribute(key) {
   return "aria-" + key.slice(4).toLowerCase();
 }
 function appendChildren(parent, children) {
-  for (const child of children.flat(Infinity)) {
-    if (child == null) continue;
-    if (typeof child === "string" || typeof child === "number") {
-      parent.append(document.createTextNode(String(child)));
-    } else if (child && typeof child === "object" && typeof child.nodeType === "number") {
-      parent.append(child);
-    } else if (typeof child === "object" && typeof child.toElement === "function") {
+  const host = (
+    /** @type {ParentNode} */
+    parent
+  );
+  for (
+    const raw2 of
+    /** @type {any[]} */
+    children.flat(Infinity)
+  ) {
+    if (raw2 == null) continue;
+    if (typeof raw2 === "string" || typeof raw2 === "number") {
+      host.append(document.createTextNode(String(raw2)));
+      continue;
+    }
+    if (typeof raw2 !== "object") continue;
+    const child = (
+      /** @type {{nodeType?: number, toElement?: () => Node|null}} */
+      raw2
+    );
+    if (typeof child.nodeType === "number") {
+      host.append(
+        /** @type {Node} */
+        raw2
+      );
+    } else if (typeof child.toElement === "function") {
       const element = child.toElement();
-      if (element) parent.append(element);
+      if (element) host.append(element);
     }
   }
 }
@@ -617,11 +640,18 @@ var registry = /* @__PURE__ */ new WeakMap();
 var Component = class 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<ComponentOptions>} Merged component options. */
+  /** @type {Readonly<TOptions>} Merged component options. */
   options;
   #abort = new AbortController();
   #created = false;
@@ -630,17 +660,27 @@ var Component = class extends EventTarget {
   /**
    * 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 {ComponentOptions} [options={}] Component options.
+   * @param {TOptions} [options={}] Component options.
    */
-  constructor(target, options = {}) {
+  constructor(target, options = (
+    /** @type {TOptions} */
+    {}
+  )) {
     super();
+    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 = mergeOptions(this.constructor, options);
+    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") {
@@ -670,7 +710,7 @@ var Component = class extends EventTarget {
       this.#abort.abort();
       throw new TypeError("Component requires a root Element");
     }
-    const cssName = this.constructor.cssName;
+    const cssName = self.cssName;
     if (typeof cssName === "string" && cssName) {
       const className = `zx-${cssName}`;
       this.#addedRootClass = !this.el.classList.contains(className);
@@ -791,7 +831,10 @@ var Component = class extends EventTarget {
     this.#destroyed = true;
     this.#abort.abort();
     if (registry.get(this.el) === this) registry.delete(this.el);
-    const cssName = this.constructor.cssName;
+    const cssName = (
+      /** @type {typeof Component} */
+      this.constructor.cssName
+    );
     if (this.#addedRootClass && typeof cssName === "string" && this.el) {
       this.el.classList.remove(`zx-${cssName}`);
     }
@@ -1775,7 +1818,10 @@ function getWeekStart(lang = getLanguage()) {
   if (!lang) return 1;
   if (lang.toLowerCase() === "en") return 1;
   try {
-    const locale = new Intl.Locale(lang);
+    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 {
@@ -3111,9 +3157,11 @@ function updateFallback(anchor, floating, { placement, offset, flip, matchWidth
   const topY = anchorRect.top - offset - floatingRect.height;
   if (flip) {
     if (prefersBottom && bottomY + floatingRect.height > viewportHeight && topY >= 0) {
-      actualPlacement = placement.replace("bottom", "top");
+      actualPlacement = /** @type {typeof placement} */
+      placement.replace("bottom", "top");
     } else if (!prefersBottom && topY < 0 && bottomY + floatingRect.height <= viewportHeight) {
-      actualPlacement = placement.replace("top", "bottom");
+      actualPlacement = /** @type {typeof placement} */
+      placement.replace("top", "bottom");
     }
   }
   let left;
@@ -6087,10 +6135,13 @@ function rovingTabindex(container, itemSelector, { orientation = "vertical", wra
   const originals = /* @__PURE__ */ new Map();
   let destroyed = false;
   function items() {
-    return Array.from(container.querySelectorAll(itemSelector)).filter((item) => {
-      remember(item);
-      return isAvailable(item);
-    });
+    return (
+      /** @type {HTMLElement[]} */
+      Array.from(container.querySelectorAll(itemSelector)).filter((item) => {
+        remember(item);
+        return isAvailable(item);
+      })
+    );
   }
   function remember(item) {
     if (!originals.has(item)) originals.set(item, item.getAttribute("tabindex"));
@@ -6105,7 +6156,11 @@ function rovingTabindex(container, itemSelector, { orientation = "vertical", wra
   }
   function onKeydown(event) {
     const available = items();
-    const current = event.target?.closest?.(itemSelector);
+    const current = (
+      /** @type {HTMLElement|null} */
+      /** @type {Element|null} */
+      event.target?.closest?.(itemSelector) ?? null
+    );
     const index = available.indexOf(current);
     if (index < 0) return;
     const previousKey = orientation === "horizontal" ? "ArrowLeft" : "ArrowUp";
@@ -6123,7 +6178,11 @@ function rovingTabindex(container, itemSelector, { orientation = "vertical", wra
     available[nextIndex].focus();
   }
   function onFocus(event) {
-    const item = event.target?.closest?.(itemSelector);
+    const item = (
+      /** @type {HTMLElement|null} */
+      /** @type {Element|null} */
+      event.target?.closest?.(itemSelector) ?? null
+    );
     if (item && container.contains(item)) update(item);
   }
   container.addEventListener("keydown", onKeydown, { signal: controller.signal });
@@ -6193,7 +6252,11 @@ function itemText(item) {
     return String(item.textContent ?? "").trim().toLocaleLowerCase();
   }
   if (item && typeof item === "object") {
-    const value = item.label ?? item.text ?? item.value;
+    const shape = (
+      /** @type {{label?: unknown, text?: unknown, value?: unknown}} */
+      item
+    );
+    const value = shape.label ?? shape.text ?? shape.value;
     if (value != null) return String(value).trim().toLocaleLowerCase();
   }
   return String(item ?? "").trim().toLocaleLowerCase();
@@ -8654,6 +8717,75 @@ function registerValueListFieldAdapter() {
   });
 }
 
+// src/core/breakpoint.js
+var breakpoints = Object.freeze({ sm: 480, md: 768, lg: 1024, xl: 1280 });
+var ORDER = (
+  /** @type {const} */
+  ["xl", "lg", "md", "sm"]
+);
+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";
+}
+function onBreakpoint(handler, options = {}) {
+  if (typeof handler !== "function") throw new TypeError("onBreakpoint requires a handler");
+  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;
+  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();
+    if (element && width === 0) return;
+    const next = breakpointOf(width);
+    if (next === name) return;
+    name = next;
+    handler(name, width);
+  };
+  update();
+  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);
+    }
+  };
+}
+
 // src/core/http.js
 var Http = class {
   /** @type {string} */
@@ -8714,7 +8846,10 @@ var Http = class {
         try {
           json = JSON.parse(text3);
         } catch (cause) {
-          const error = new Error("Invalid JSON response", { cause });
+          const error = (
+            /** @type {Error & {response?: Response}} */
+            new Error("Invalid JSON response", { cause })
+          );
           error.response = response;
           throw error;
         }
@@ -8726,7 +8861,10 @@ var Http = class {
           error2.response = response;
           throw error2;
         }
-        const error = new Error(`HTTP ${response.status} ${response.statusText}`.trim());
+        const error = (
+          /** @type {Error & {response?: Response}} */
+          new Error(`HTTP ${response.status} ${response.statusText}`.trim())
+        );
         error.response = response;
         throw error;
       }
@@ -8834,7 +8972,10 @@ function appendFormValue2(form, key, value) {
     for (const item of value) appendFormValue2(form, key, item);
   } else {
     const isBlob = typeof Blob === "function" && value instanceof Blob;
-    form.append(key, typeof value === "object" && !isBlob ? JSON.stringify(value) : value);
+    form.append(key, typeof value === "object" && !isBlob ? JSON.stringify(value) : (
+      /** @type {string|Blob} */
+      value
+    ));
   }
 }
 function isFileList(value) {
@@ -10226,6 +10367,8 @@ var Table = class extends Component {
     sortMode: "local",
     selectable: false,
     stickyHeader: true,
+    responsive: false,
+    growing: false,
     height: null,
     emptyText: null,
     rowClass: null,
@@ -10246,6 +10389,7 @@ var Table = class extends Component {
       /** @type {HTMLElement} */
       this.el ?? h("div")
     );
+    this.el = root;
     this._originalChildren = this.el ? Array.from(this.el.childNodes) : null;
     this._columns = Array.isArray(this.options.columns) ? this.options.columns.map((column) => ({ ...column })) : [];
     this._data = Array.isArray(this.options.data) ? [...this.options.data] : [];
@@ -10258,6 +10402,11 @@ var Table = class extends Component {
     this._editMode = normalizeEditMode(this.options.editMode);
     this._edit = null;
     this._editMessage = null;
+    this._stacked = false;
+    this._width = null;
+    this._growStep = growStep(this.options.growing);
+    this._rendered = this._growStep ?? Infinity;
+    this._more = null;
     this._rovingKey = null;
     this._rovingCell = null;
     this._rovingMatched = false;
@@ -10292,6 +10441,7 @@ var Table = class extends Component {
     this._renderColumns();
     this._renderHeader();
     this._renderBody();
+    this._watchWidth();
     this.listen(this._tbody, "click", (event) => this._handleBodyClick(event));
     this.listen(this._tbody, "dblclick", (event) => this._handleBodyDoubleClick(event));
     if (this._editMode !== false) {
@@ -10325,6 +10475,7 @@ var Table = class extends Component {
    * @fires Table#editcancel
    */
   setData(rows) {
+    this._rendered = this._growStep ?? Infinity;
     this.setLoading(false);
     assertRows(rows);
     this._data = [...rows];
@@ -10599,9 +10750,150 @@ var Table = class extends Component {
   getEditing() {
     return this._edit ? { id: this._edit.id, columnId: this._edit.columnId } : null;
   }
+  /**
+   * The rows currently rendered — all of them unless `growing` is on.
+   * @returns {TableRow[]}
+   */
+  _visibleData() {
+    return this._rendered === Infinity ? this._data : this._data.slice(0, this._rendered);
+  }
+  /**
+   * Renders the next batch of rows.
+   * @param {number} [count] How many to add; defaults to the configured batch size.
+   * @returns {this}
+   * @fires Table#grow
+   */
+  growBy(count) {
+    if (!this._growStep) return this;
+    const step = Number(count) > 0 ? Math.trunc(Number(count)) : this._growStep;
+    const before = this._rendered;
+    this._rendered = Math.min(this._data.length, this._rendered + step);
+    if (this._rendered === before) return this;
+    this._renderBody();
+    this.emit("grow", { rendered: this._rendered, total: this._data.length });
+    return this;
+  }
+  /**
+   * Renders every remaining row.
+   * @returns {this}
+   * @fires Table#grow
+   */
+  showAll() {
+    return this.growBy(this._data.length);
+  }
+  /**
+   * How many rows are currently rendered.
+   * @returns {number}
+   */
+  getRenderedCount() {
+    return Math.min(this._rendered, this._data.length);
+  }
+  /**
+   * Keeps the "show more" control in step with what is rendered.
+   *
+   * The control sits outside the table rather than in a `<tfoot>` row spanning every column: it is
+   * a command, not data, and a button inside the grid would be reachable by the row navigation
+   * keys as though it were a cell.
+   * @returns {void}
+   */
+  _syncGrowing() {
+    if (!this._growStep) return;
+    const remaining = this._data.length - this.getRenderedCount();
+    if (remaining <= 0) {
+      this._more?.remove();
+      this._more = null;
+      return;
+    }
+    const label = this._message("table.more", "Show %1 more", [remaining]);
+    if (!this._more) {
+      this._more = h("button", {
+        class: "zx-table__more",
+        type: "button",
+        onclick: () => this.growBy()
+      });
+      this.el.append(this._more);
+    }
+    this._more.textContent = label;
+    this._more.setAttribute("aria-label", label);
+  }
+  /**
+   * Resolves a localized message, falling back to a built-in template.
+   * @param {string} key Message key.
+   * @param {string} fallback Template used when the host has no translation.
+   * @param {unknown[]} args Positional interpolation values.
+   * @returns {string}
+   */
+  _message(key, fallback, args) {
+    const message = this.msg(key, ...args);
+    return message === key ? printf(fallback, args) : message;
+  }
+  /**
+   * Watches the table's own width and stacks the rows below `responsive`.
+   *
+   * The width comes from `onBreakpoint` observing this element rather than the window, which is the
+   * whole point of the option: a table inside a split pane or a modal has no idea how wide the
+   * viewport is, and a media query would stack it on a phone while leaving it unreadable in a
+   * 320px pane on a desktop.
+   * @returns {void}
+   */
+  _watchWidth() {
+    this._width?.destroy();
+    this._width = null;
+    const threshold = this.options.responsive;
+    if (!threshold || !(threshold in breakpoints)) return;
+    this._width = onBreakpoint(
+      (_name, width) => this._setStacked(width > 0 && width < breakpoints[threshold]),
+      { target: this.el }
+    );
+  }
+  /**
+   * Enters or leaves stacked mode.
+   * @param {boolean} stacked Whether rows should stack.
+   * @returns {void}
+   * @fires Table#stackedchange
+   */
+  _setStacked(stacked) {
+    if (this._stacked === stacked) return;
+    this._stacked = stacked;
+    this.el.toggleAttribute("data-stacked", stacked);
+    this._applyStackedRoles(stacked);
+    this.emit("stackedchange", { stacked });
+  }
+  /**
+   * States the table roles explicitly while stacked, and removes them again on the way out.
+   *
+   * Stacking works by changing `display` on the table elements, and a table whose display is not
+   * `table` loses its implicit ARIA roles — leaving a screen reader with a pile of generic blocks
+   * where a table used to be. The roles are only asserted while the layout has taken them away.
+   * @param {boolean} stacked Whether the roles should be present.
+   * @returns {void}
+   */
+  _applyStackedRoles(stacked) {
+    const parts = [[this._table, "table"], [this._thead, "rowgroup"], [this._tbody, "rowgroup"]];
+    for (const [element, role] of parts) {
+      if (!element) continue;
+      if (stacked) element.setAttribute("role", role);
+      else element.removeAttribute("role");
+    }
+    for (const [selector, role] of [["tr", "row"], ["td", "cell"], ["th", "columnheader"]]) {
+      for (const element of this._table.querySelectorAll(selector)) {
+        if (stacked) element.setAttribute("role", role);
+        else element.removeAttribute("role");
+      }
+    }
+  }
+  /**
+   * Reports whether the rows are currently stacked.
+   * @returns {boolean}
+   */
+  isStacked() {
+    return Boolean(this._stacked);
+  }
   /** Restores an enhanced target and releases all component listeners. @returns {void} */
   destroy() {
     this._teardownEdit();
+    this._width?.destroy();
+    this._width = null;
     if (this.el) delete this.el.dataset.editMode;
     if (!this._restored && this._originalChildren) {
       this.el.replaceChildren(...this._originalChildren);
@@ -10686,17 +10978,35 @@ var Table = class extends Component {
     this._rovingCell = null;
     this._rovingMatched = false;
     if (this._data.length === 0) {
-      const text3 = this.options.emptyText == null ? this.msg("table.empty") : String(this.options.emptyText);
       fragment.append(h(
         "tr",
         { class: "zx-table__empty-row" },
-        h("td", { class: "zx-table__empty", colspan: this._columns.length + (this.options.selectable === "multi" ? 1 : 0) }, text3)
+        h("td", {
+          class: "zx-table__empty",
+          colspan: this._columns.length + (this.options.selectable === "multi" ? 1 : 0)
+        }, this._emptyContent())
       ));
     } else {
-      this._data.forEach((row, index) => fragment.append(this._createRow(row, index)));
+      this._visibleData().forEach((row, index) => fragment.append(this._createRow(row, index)));
     }
     this._tbody.replaceChildren(fragment);
     this._syncSelectAll();
+    this._syncGrowing();
+    if (this._stacked) this._applyStackedRoles(true);
+  }
+  /**
+   * What to put in the empty row.
+   *
+   * An empty table is a screen in its own right — the place to say why there is nothing and what to
+   * do about it — so this takes a node as readily as a string. A function is re-called on every
+   * render, which matters when the placeholder contains a button: reusing one node would move the
+   * same element between renders and quietly share its listeners.
+   * @returns {Node|string}
+   */
+  _emptyContent() {
+    const empty = this.options.emptyText;
+    if (empty == null) return this.msg("table.empty");
+    return typeof empty === "function" ? empty() : empty;
   }
   /** @param {TableRow} row @param {number} index @returns {HTMLTableRowElement} */
   _createRow(row, index) {
@@ -10727,6 +11037,8 @@ var Table = class extends Component {
         h("td")
       );
       if (column.align) cell.dataset.align = column.align;
+      cell.dataset.label = column.label;
+      if (column.popin === false) cell.dataset.popin = "false";
       if (this._editMode !== false) {
         cell.dataset.column = column.id;
         if (resolveEditable(column, row) !== false) {
@@ -11345,6 +11657,10 @@ function assertRows(rows) {
 function sameSet(left, right) {
   return left.size === right.size && [...left].every((value) => right.has(value));
 }
+function growStep(growing) {
+  const step = Math.trunc(Number(growing));
+  return Number.isFinite(step) && step > 0 ? step : null;
+}
 
 // src/components/button/button.js
 var defaults = Object.freeze({
@@ -15314,6 +15630,12 @@ var Datebox2 = class extends GxWrapper {
 };
 var PickerBase = class extends GxWrapper {
   static legacyName = "gx.zeyos.DatePicker";
+  /*
+   * A constructor type rather than `typeof ZxDatePicker`: each subclass points this at a different
+   * picker, and inferring the base from its own default would make every subclass's static side
+   * incompatible with it.
+   */
+  /** @type {new (target: Element|string|null, options?: any) => any} */
   static Picker = DatePicker;
   /** @param {Element|string|null} display @param {Record<string, any>} [options={}] */
   constructor(display, options = {}) {
@@ -16468,6 +16790,13 @@ function normalizeButtons(list) {
 // src/compat/map/select.js
 var SelectBase = class extends GxWrapper {
   static legacyName = "gx.zeyos.Select";
+  /*
+   * Widened deliberately: the subclasses below set `'local' | 'async' | 'priority' | 'rest'`, and
+   * a static field annotated with that union would still clash with the `string` each subclass
+   * infers from its own literal. The static sides have to agree or the emitted declarations do
+   * not type-check for a consumer running without `skipLibCheck`.
+   */
+  /** @type {string|false} */
   static filterMode = false;
   /** @param {Element|string|null} display @param {Record<string, any>} [options={}] */
   constructor(display, options = {}) {