@zeyos/zx 2.1.0 → 2.2.0

package/docs/api.json

@@ -4119,6 +4119,18 @@
         "default": "true",
         "description": "Whether column headers stick while scrolling."
       },
+      {
+        "name": "growing",
+        "type": "false|number",
+        "default": "false",
+        "description": "Number of rows to render at first, with a control that appends the next batch on demand. A result set an ERP query returns happily — tens of thousands of rows — costs more to lay out than anyone will ever scroll through."
+      },
+      {
+        "name": "responsive",
+        "type": "false|'sm'|'md'|'lg'|'xl'",
+        "default": "false",
+        "description": "Width below which each row stacks into a card of label/value pairs instead of scrolling sideways. Measured on the table's own container, not the viewport, so a table inside a split pane stacks when *it* is narrow."
+      },
       {
         "name": "height",
         "type": "number|string|null",
@@ -4127,9 +4139,9 @@
       },
       {
         "name": "emptyText",
-        "type": "string|null",
+        "type": "string|Node|(() => Node|string)|null",
         "default": "null",
-        "description": "Empty message; null resolves `table.empty`."
+        "description": "What to show when there are no rows; null resolves `table.empty`. A Node — an `emptyState()` with an action in it, say — is placed as given, and a function is called on each render, which is what to use when the placeholder holds live controls."
       },
       {
         "name": "rowClass",
@@ -4176,6 +4188,16 @@
         "payload": "{rows}",
         "description": ""
       },
+      {
+        "name": "stackedchange",
+        "payload": "{stacked: boolean}",
+        "description": "Fired when the table crosses its `responsive` width in either direction."
+      },
+      {
+        "name": "grow",
+        "payload": "{rendered: number, total: number}",
+        "description": "Fired after more rows are rendered."
+      },
       {
         "name": "editstart",
         "payload": "{row, id, column, columnId, value}",
@@ -4258,6 +4280,30 @@
         "returns": "this",
         "description": "Opens the editor for a cell. No-op unless the table runs with `editMode` and the column resolves to an editable type for that row. In `'row'` mode every editable cell of the row is opened and `columnId` only decides which editor receives focus. Any other open edit is committed first."
       },
+      {
+        "name": "growBy",
+        "signature": "growBy([count])",
+        "returns": "TableRow[]",
+        "description": "The rows currently rendered — all of them unless `growing` is on."
+      },
+      {
+        "name": "showAll",
+        "signature": "showAll()",
+        "returns": "this",
+        "description": "Renders every remaining row."
+      },
+      {
+        "name": "getRenderedCount",
+        "signature": "getRenderedCount()",
+        "returns": "number",
+        "description": "How many rows are currently rendered."
+      },
+      {
+        "name": "isStacked",
+        "signature": "isStacked(key, fallback, args, stacked, stacked)",
+        "returns": "void",
+        "description": "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."
+      },
       {
         "name": "destroy",
         "signature": "destroy()",

package/docs/llms.md

@@ -38,6 +38,9 @@ const t = new Table(target, options);
 ## Entry points
 
 - ESM: `import { … } from '/assets/zx.esm.js'` (or `../src/index.js` in-repo, no build).
+- Granular: `import { Slider } from '@zeyos/zx/src/components/slider/slider.js'` — one component
+  rather than the whole library, for consumers running a bundler. Two components bundle 26 kB
+  minified against 157 kB through the package entry. The stylesheet is still loaded whole.
 - Global: `<script src="/assets/zx.global.js">` → `window.zx.*`.
 - Styles: load `/assets/zx.css` once.
 - Build bundles with `npm run build` (esbuild). No build is needed to develop against `src/`.
@@ -770,6 +773,23 @@ horizontally, and multi-select adds a tri-state header checkbox plus Shift+click
   editable cell (Shift+Tab the previous), wrapping across rows, and tabbing past the last editable
   cell commits and leaves the table normally. Clicking outside the editor commits rather than
   discarding what was typed.
+- **Growing** — `growing: <number>` renders that many rows and offers a control for the next batch,
+  instead of laying out a result set nobody will scroll through. `growBy(count?)`, `showAll()`,
+  `getRenderedCount()`, and `grow {rendered, total}`. `setData()` starts the batch over, since a new
+  result set is not the old one grown. Row indices stay absolute — a row's index is its place in the
+  data, not in what is on screen.
+- **Responsive stacking** — `responsive: false|'sm'|'md'|'lg'|'xl'` stacks each row into a card of
+  label/value pairs below that width, instead of leaving a horizontal scrollbar with the data
+  hidden behind it. The width measured is **the table's own container**, not the viewport, so this
+  triggers inside a narrow split pane on a wide screen. A column with `popin: false` leads the card
+  instead of becoming another labelled line — the identifying column usually wants that. Every cell
+  carries `data-label`, so the labels are there whether or not the option is on. `isStacked()`
+  reports the current state and `stackedchange {stacked}` fires on each crossing. Stacking drops
+  `display: table`, which drops the implicit ARIA roles, so the component states
+  `table`/`rowgroup`/`row`/`cell`/`columnheader` explicitly for exactly as long as the mode is on.
+- **Empty state** — `emptyText` takes a string, a Node, or a function returning one, so an empty
+  table can carry an icon, an explanation, and the action that resolves it (`emptyState({…})`).
+  A function is re-called on every render, which is what to use when the placeholder holds controls.
 <!-- /doc -->
 
 <!-- doc:data-filter -->
@@ -1312,4 +1332,12 @@ colour literals and tier-1 references in component CSS.
   `--zx-radius-sm/md/lg/full`, the type scale, shadows, and motion.
 - **Tier 2** — the semantic set, the only tokens components may use: `--zx-color-*`,
   `--zx-control-*`, `--zx-focus-ring`, `--zx-overlay-shadow`.
+- **Component styling hooks** — a short, deliberately small set of component-level custom
+  properties for restyling one component without touching its internals. Each falls back to the
+  semantic token it replaces, so setting none of them changes nothing:
+  `--zx-table-header-bg`, `--zx-table-row-hover-bg`, `--zx-table-row-selected-bg`,
+  `--zx-table-border-color`, `--zx-button-radius`, `--zx-panel-header-bg`.
+  Reach for the least specific override that works: a global semantic token first, one of these
+  second, an internal selector never. Component CSS declares many other `--zx-<component>-*`
+  properties — those are internal geometry, not API, and will change without notice.
 <!-- /doc -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeyos/zx",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "Dependency-free, accessible UI component library for ZeyOS business applications.",
   "type": "module",
   "license": "MIT",
@@ -30,13 +30,33 @@
     "./dist/zx-compat.global.min.js"
   ],
   "exports": {
-    ".": "./dist/zx.esm.js",
-    "./zeyos": "./dist/zx-zeyos.esm.js",
-    "./compat": "./dist/zx-compat.esm.js",
-    "./global": "./dist/zx.global.js",
-    "./compat-global": "./dist/zx-compat.global.js",
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "default": "./dist/zx.esm.js"
+    },
+    "./zeyos": {
+      "types": "./dist/types/zeyos/index.d.ts",
+      "default": "./dist/zx-zeyos.esm.js"
+    },
+    "./compat": {
+      "types": "./dist/types/compat/index.d.ts",
+      "default": "./dist/zx-compat.esm.js"
+    },
+    "./global": {
+      "types": "./dist/types/index.d.ts",
+      "default": "./dist/zx.global.js"
+    },
+    "./compat-global": {
+      "types": "./dist/types/compat/index.d.ts",
+      "default": "./dist/zx-compat.global.js"
+    },
     "./zx.css": "./dist/zx.css",
     "./zx.min.css": "./dist/zx.min.css",
+    "./src/*.js": {
+      "types": "./dist/types/*.d.ts",
+      "default": "./src/*.js"
+    },
+    "./styles/*": "./styles/*",
     "./dist/*": "./dist/*",
     "./package.json": "./package.json"
   },
@@ -45,6 +65,9 @@
   "style": "./dist/zx.css",
   "files": [
     "dist",
+    "dist/types",
+    "styles",
+    "src",
     "docs/llms.md",
     "docs/llms.txt",
     "docs/api.json",
@@ -66,9 +89,14 @@
     "build:site": "node tools/build-api.js && node tools/build-site.js",
     "test": "node --test && node tests/lint-tokens.js",
     "prepublishOnly": "npm test && npm run build",
-    "build:api": "node tools/build-api.js"
+    "build:api": "node tools/build-api.js",
+    "build:types": "tsc --project tsconfig.json",
+    "test:browser": "node tools/run-smoke.js"
   },
   "devDependencies": {
-    "esbuild": "latest"
-  }
+    "esbuild": "latest",
+    "playwright-core": "^1.62.1",
+    "typescript": "^7.0.2"
+  },
+  "types": "./dist/types/index.d.ts"
 }

package/src/compat/base.js

@@ -0,0 +1,291 @@
+import { installElementStorage } from './globals.js';
+
+/** @typedef {(detail: Record<string, any>, event: Event) => unknown[]} LegacyArgumentMapper */
+/**
+ * @typedef {Object} LegacyEventMapping
+ * @property {string} type Zx event name.
+ * @property {LegacyArgumentMapper} [args] Legacy positional argument adapter.
+ * @property {(detail: Record<string, any>, event: Event) => boolean} [filter] Optional event filter.
+ */
+/** @typedef {Record<string, string|LegacyEventMapping>} LegacyEventMap */
+/**
+ * @typedef {Object} WrapperConfiguration
+ * @property {LegacyEventMap} [events]
+ * @property {Record<string, string|Element|(() => Element|null)>} [ui]
+ * @property {Record<string, string|((value: unknown) => void)>} [setters]
+ */
+
+/**
+ * MooTools-flavoured façade shared by compatibility component wrappers.
+ * @fires GxWrapper#legacy-event
+ */
+export class GxWrapper {
+  /** Fully qualified legacy class name shown in migration warnings. */
+  static legacyName = 'gx.ui.Container';
+
+  /**
+   * Initializes legacy options and callback-style `onEvent` options.
+   * Subclasses call `_attach()` after constructing their Zx implementation.
+   * @param {Record<string, any>} [options={}] Legacy options.
+   * @param {Record<string, any>} [defaults={}] Legacy defaults.
+   */
+  constructor(options = {}, defaults = {}) {
+    warnClassOnce(this.constructor);
+    this.gx = this.constructor.legacyName;
+    this.options = { ...defaults, ...(options && typeof options === 'object' ? options : {}) };
+    this._events = new Map();
+    this._mappedListeners = [];
+    this._domAbort = new AbortController();
+    this._zx = null;
+    this._ui = {};
+    this._display = this._ui;
+    this._uiMap = {};
+    this._optionSetters = {};
+    this._destroyed = false;
+    for (const [key, value] of Object.entries(this.options)) {
+      if (/^on[A-Z]/.test(key) && typeof value === 'function') this.addEvent(key, value);
+    }
+  }
+
+  /**
+   * Subscribes a legacy callback.
+   * @param {string} type Legacy event name, with or without an `on` prefix.
+   * @param {Function} fn Callback receiving legacy positional arguments.
+   * @returns {this}
+   */
+  addEvent(type, fn) {
+    if (typeof fn !== 'function') return this;
+    const name = normalizeEventName(type);
+    const handlers = this._events.get(name) ?? new Set();
+    handlers.add(fn);
+    this._events.set(name, handlers);
+    return this;
+  }
+
+  /**
+   * Removes one callback, or all callbacks of a type when omitted.
+   * @param {string} type Legacy event name.
+   * @param {Function} [fn] Callback to remove.
+   * @returns {this}
+   */
+  removeEvent(type, fn) {
+    const name = normalizeEventName(type);
+    if (fn === undefined) this._events.delete(name);
+    else {
+      const handlers = this._events.get(name);
+      handlers?.delete(fn);
+      if (handlers?.size === 0) this._events.delete(name);
+    }
+    return this;
+  }
+
+  /**
+   * Fires a legacy event synchronously.
+   * @param {string} type Legacy event name.
+   * @param {unknown|unknown[]} [args=[]] Positional argument array or one argument.
+   * @returns {this}
+   * @fires GxWrapper#legacy-event
+   */
+  fireEvent(type, args = []) {
+    const values = Array.isArray(args) ? args : [args];
+    const handlers = [...(this._events.get(normalizeEventName(type)) ?? [])];
+    for (const handler of handlers) handler.apply(this, values);
+    return this;
+  }
+
+  /**
+   * Applies multiple post-construction legacy options.
+   * @param {Record<string, unknown>} options Option values.
+   * @returns {this}
+   */
+  setOptions(options) {
+    if (!options || typeof options !== 'object') return this;
+    for (const [name, value] of Object.entries(options)) this.setOption(name, value);
+    return this;
+  }
+
+  /**
+   * Applies one post-construction option through a declared setter.
+   * Unsupported dynamic options are retained on `options` and warn once per class/key.
+   * @param {string} option Legacy option name.
+   * @param {unknown} value New value.
+   * @returns {this}
+   */
+  setOption(option, value) {
+    const name = String(option);
+    this.options[name] = value;
+    if (/^on[A-Z]/.test(name) && typeof value === 'function') {
+      this.addEvent(name, value);
+      return this;
+    }
+    const setter = this._optionSetters[name];
+    if (typeof setter === 'function') setter.call(this, value);
+    else if (typeof setter === 'string' && typeof this[setter] === 'function') this[setter](value);
+    else warnOptionOnce(this.constructor, name);
+    return this;
+  }
+
+  /**
+   * Returns the wrapped component root.
+   * @returns {Element|null}
+   */
+  toElement() {
+    return this._zx?.toElement?.() ?? this._zx?.el ?? null;
+  }
+
+  /**
+   * Resolves a legacy `_ui` key, falling back to the component root.
+   * @param {string} [key='root'] Legacy display key.
+   * @returns {Element|null}
+   */
+  display(key = 'root') {
+    const name = key || 'root';
+    if (name === 'root') return this.toElement();
+    const mapped = this._uiMap[name];
+    if (typeof mapped === 'function') return mapped.call(this) ?? this.toElement();
+    if (typeof mapped === 'string') return this._zx?.refs?.[mapped] ?? this.toElement();
+    if (mapped?.nodeType === 1) return mapped;
+    return this._ui[name] ?? this.toElement();
+  }
+
+  /**
+   * Returns the supported legacy coordinate subset.
+   * @returns {{width: number, height: number, top: number, left: number}}
+   */
+  getCoordinates() {
+    const rectangle = this.toElement()?.getBoundingClientRect?.();
+    return rectangle ? {
+      width: rectangle.width,
+      height: rectangle.height,
+      top: rectangle.top,
+      left: rectangle.left
+    } : { width: 0, height: 0, top: 0, left: 0 };
+  }
+
+  /**
+   * Updates one root style property.
+   * @param {string} property CSS property.
+   * @param {unknown} value CSS value.
+   * @returns {this}
+   */
+  setStyle(property, value) {
+    const element = /** @type {HTMLElement|null} */ (this.toElement());
+    if (!element) return this;
+    if (String(property).startsWith('--') || String(property).includes('-')) {
+      element.style.setProperty(String(property), String(value));
+    } else {
+      element.style[property] = value;
+    }
+    return this;
+  }
+
+  /**
+   * Updates supported root coordinates.
+   * @param {Record<string, unknown>} coordinates Coordinate styles.
+   * @returns {this}
+   */
+  setCoordinates(coordinates = {}) {
+    for (const key of ['width', 'height', 'top', 'right', 'bottom', 'left']) {
+      if (coordinates[key] == null) continue;
+      const value = typeof coordinates[key] === 'number' ? `${coordinates[key]}px` : coordinates[key];
+      this.setStyle(key, value);
+    }
+    return this;
+  }
+
+  /**
+   * Destroys the wrapped component and legacy event subscriptions.
+   * @returns {void}
+   */
+  destroy() {
+    if (this._destroyed) return;
+    this._destroyed = true;
+    this._domAbort.abort();
+    const root = this.toElement();
+    if (root?.retrieve?.('com') === this) root.eliminate('com');
+    for (const [type, listener] of this._mappedListeners) this._zx?.off?.(type, listener);
+    this._mappedListeners.length = 0;
+    this._events.clear();
+    this._zx?.destroy?.();
+  }
+
+  /**
+   * Attaches a constructed Zx component and its translation metadata.
+   * @param {any} component Wrapped Zx component.
+   * @param {WrapperConfiguration} [configuration={}] Event, display, and setter maps.
+   * @returns {this}
+   */
+  _attach(component, configuration = {}) {
+    this._zx = component;
+    this._uiMap = { ...(configuration.ui ?? {}) };
+    this._optionSetters = { ...(configuration.setters ?? {}) };
+    const root = this.toElement();
+    if (root) {
+      installElementStorage(globalThis);
+      root.store?.('com', this);
+      this._ui.root = root;
+      for (const key of Object.keys(this._uiMap)) this._ui[key] = this.display(key);
+    }
+    for (const [legacyType, declaration] of Object.entries(configuration.events ?? {})) {
+      const mapping = typeof declaration === 'string' ? { type: declaration } : declaration;
+      const listener = (event) => {
+        const detail = event.detail ?? {};
+        if (mapping.filter && !mapping.filter.call(this, detail, event)) return;
+        const args = mapping.args ? mapping.args.call(this, detail, event) : [];
+        this.fireEvent(legacyType, args);
+      };
+      component.on?.(mapping.type, listener);
+      this._mappedListeners.push([mapping.type, listener]);
+    }
+    return this;
+  }
+
+  /**
+   * Adds a DOM listener owned by this wrapper.
+   * @param {EventTarget} target Event target.
+   * @param {string} type Event type.
+   * @param {EventListenerOrEventListenerObject} listener Listener.
+   * @param {AddEventListenerOptions} [options={}] Listener options.
+   * @returns {this}
+   */
+  _listen(target, type, listener, options = {}) {
+    target.addEventListener(type, listener, { ...options, signal: this._domAbort.signal });
+    return this;
+  }
+
+  /** @param {Element|null} element @param {boolean} active @returns {void} */
+  _mirrorAct(element, active) {
+    element?.classList.toggle('act', Boolean(active));
+  }
+}
+
+/** Generic legacy event dispatched by a mapped Zx event. @event GxWrapper#legacy-event */
+
+/** @param {typeof GxWrapper} constructor @returns {void} */
+function warnClassOnce(constructor) {
+  if (Object.hasOwn(constructor, '_compatWarned') && constructor._compatWarned) return;
+  Object.defineProperty(constructor, '_compatWarned', { configurable: true, value: true, writable: true });
+  console.warn(`${constructor.legacyName} is running on the Zx compat layer — migrate to ${replacementName(constructor.legacyName)}`);
+}
+
+/** @param {typeof GxWrapper} constructor @param {string} option @returns {void} */
+function warnOptionOnce(constructor, option) {
+  if (!Object.hasOwn(constructor, '_compatOptionWarnings')) {
+    Object.defineProperty(constructor, '_compatOptionWarnings', { configurable: true, value: new Set() });
+  }
+  if (constructor._compatOptionWarnings.has(option)) return;
+  constructor._compatOptionWarnings.add(option);
+  console.warn(`${constructor.legacyName}.setOption("${option}") cannot update the wrapped Zx component dynamically`);
+}
+
+/** @param {string} name @returns {string} */
+function replacementName(name) {
+  const className = name.split('.').at(-1);
+  return `zx.${className}`;
+}
+
+/** @param {string} type @returns {string} */
+function normalizeEventName(type) {
+  const value = String(type ?? '');
+  return (/^on[A-Z]/.test(value) ? value.slice(2) : value).toLowerCase();
+}

package/src/compat/globals.js

@@ -0,0 +1,165 @@
+import { h, htmlEscape } from '../core/dom.js';
+import { translate } from '../core/i18n.js';
+
+/** @type {WeakMap<object, Map<unknown, unknown>>} */
+const elementStorage = new WeakMap();
+
+/**
+ * Installs the small WeakMap-backed MooTools Element storage surface.
+ * Existing implementations are never overwritten.
+ * @param {typeof globalThis} [host=globalThis] Realm whose Element prototype is extended.
+ * @returns {void}
+ */
+export function installElementStorage(host = globalThis) {
+  const prototype = host?.Element?.prototype;
+  if (!prototype) return;
+  if (typeof prototype.store !== 'function') {
+    Object.defineProperty(prototype, 'store', {
+      configurable: true,
+      writable: true,
+      value: function store(key, value) {
+        let values = elementStorage.get(this);
+        if (!values) {
+          values = new Map();
+          elementStorage.set(this, values);
+        }
+        values.set(key, value);
+        return this;
+      }
+    });
+  }
+  if (typeof prototype.retrieve !== 'function') {
+    Object.defineProperty(prototype, 'retrieve', {
+      configurable: true,
+      writable: true,
+      value: function retrieve(key, fallback = null) {
+        let values = elementStorage.get(this);
+        if (values?.has(key)) return values.get(key);
+        if (arguments.length > 1) {
+          if (!values) {
+            values = new Map();
+            elementStorage.set(this, values);
+          }
+          values.set(key, fallback);
+        }
+        return fallback;
+      }
+    });
+  }
+  if (typeof prototype.eliminate !== 'function') {
+    Object.defineProperty(prototype, 'eliminate', {
+      configurable: true,
+      writable: true,
+      value: function eliminate(key) {
+        elementStorage.get(this)?.delete(key);
+        return this;
+      }
+    });
+  }
+}
+
+/**
+ * Parses the legacy gx object-literal DOM dialect.
+ * `html` is intentionally treated as trusted legacy markup via `h.raw()`.
+ * @param {unknown} source Legacy tree value.
+ * @returns {Node|false} Parsed node, or false for unsupported input.
+ */
+export function parse(source) {
+  if (source && typeof source === 'object' && typeof source.toElement === 'function') {
+    return source.toElement() ?? false;
+  }
+  if (source && typeof source === 'object' && typeof source.nodeType === 'number') return source;
+  if (typeof source === 'string' || typeof source === 'number') return document.createTextNode(String(source));
+  if (!source || typeof source !== 'object' || Array.isArray(source)) return false;
+
+  const descriptor = source;
+  const props = {};
+  const events = [];
+  const reserved = new Set(['tag', 'html', 'styles', 'classes', 'child', 'children', '_adopt', 'events']);
+  for (const [key, value] of Object.entries(descriptor)) {
+    if (reserved.has(key)) continue;
+    if (/^on[A-Z]/.test(key) && typeof value === 'function') {
+      events.push([key.slice(2).toLowerCase(), value]);
+    } else if (key === 'class') {
+      props.class = value;
+    } else if (key === 'text') {
+      props.textContent = value == null ? '' : String(value);
+    } else {
+      props[key] = value;
+    }
+  }
+  if (descriptor.styles && typeof descriptor.styles === 'object') props.style = descriptor.styles;
+  if (descriptor.classes != null) {
+    const classes = Array.isArray(descriptor.classes) ? descriptor.classes : [descriptor.classes];
+    props.class = [props.class, ...classes].flat().filter(Boolean);
+  }
+  const element = h(String(descriptor.tag ?? 'div'), props);
+  for (const [type, listener] of events) element.addEventListener(type, listener);
+  if (descriptor.events && typeof descriptor.events === 'object') {
+    for (const [type, listener] of Object.entries(descriptor.events)) {
+      if (typeof listener === 'function') element.addEventListener(type, listener);
+    }
+  }
+  if (descriptor.html != null) element.append(h.raw(String(descriptor.html)));
+  appendParsed(element, descriptor._adopt);
+  appendParsed(element, descriptor.child);
+  if (Array.isArray(descriptor.children)) {
+    for (const child of descriptor.children) appendParsed(element, child);
+  } else if (descriptor.children && typeof descriptor.children === 'object') {
+    const names = [];
+    for (const [name, childSource] of Object.entries(descriptor.children)) {
+      const child = parse(childSource);
+      if (!child) continue;
+      element.append(child);
+      element[`_${name}`] = child.retrieve?.('com') ?? child;
+      names.push(name);
+    }
+    element.store?.('children', names);
+  }
+  return element;
+}
+
+/**
+ * Explicitly installs legacy globals and prototype conveniences.
+ * @param {typeof globalThis} [host=globalThis] Realm to modify.
+ * @returns {typeof globalThis} The supplied realm.
+ */
+export function installGlobals(host = globalThis) {
+  installElementStorage(host);
+  host.__ = parse;
+  const stringPrototype = host.String?.prototype;
+  if (stringPrototype && typeof stringPrototype.htmlSpecialChars !== 'function') {
+    Object.defineProperty(stringPrototype, 'htmlSpecialChars', {
+      configurable: true,
+      writable: true,
+      value: function htmlSpecialChars() { return htmlEscape(String(this)); }
+    });
+  }
+  const arrayPrototype = host.Array?.prototype;
+  if (arrayPrototype && typeof arrayPrototype.findBy !== 'function') {
+    Object.defineProperty(arrayPrototype, 'findBy', {
+      configurable: true,
+      writable: true,
+      value: function findBy(matcher, value) {
+        const predicate = typeof matcher === 'string' ? (item) => item?.[matcher] === value : matcher;
+        if (typeof predicate !== 'function') return null;
+        for (let index = this.length - 1; index >= 0; index -= 1) {
+          if (predicate(this[index]) === true) return this[index];
+        }
+        return null;
+      }
+    });
+  }
+  if (host._ === undefined) host._ = (key, args) => translate(String(key), args);
+  return host;
+}
+
+/** @param {Node} parent @param {unknown} source @returns {void} */
+function appendParsed(parent, source) {
+  if (source == null) return;
+  const list = Array.isArray(source) ? source : [source];
+  for (const item of list) {
+    const child = parse(item);
+    if (child) parent.append(child);
+  }
+}