@zeyos/zx 2.1.0 → 2.2.1

package/src/core/dom.js

@@ -0,0 +1,260 @@
+// @ts-check
+import { escapeRegExp, isElement } from './util.js';
+
+/** @typedef {{toElement: () => Node|null}} ElementProvider */
+/** @typedef {Node|string|number|ElementProvider|null|undefined|Array<DomChild>} DomChild */
+/**
+ * @typedef {Object} HProps
+ * @property {string|string[]} [class] Class name or names.
+ * @property {string|Record<string, string|number>} [style] Inline styles.
+ * @property {Record<string, unknown>} [dataset] Data properties.
+ * @property {string} [ref] Ref name collected by `h.scope()`.
+ */
+
+/** @type {Record<string, Element>|null} */
+let activeRefs = null;
+
+/**
+ * Creates an element and appends normalized children.
+ * @param {string} tag Element tag name.
+ * @param {(HProps & Record<string, any>)|DomChild} [props] Properties and attributes, or the first child.
+ * @param {...DomChild} children Child values.
+ * @returns {HTMLElement}
+ */
+export function h(tag, props, ...children) {
+  const element = document.createElement(tag);
+  let properties = props;
+  if (!isPropsObject(properties)) {
+    children.unshift(/** @type {DomChild} */ (properties));
+    properties = {};
+  }
+
+  for (const [key, value] of Object.entries(properties)) {
+    applyProperty(element, key, value);
+  }
+  appendChildren(element, children);
+  return element;
+}
+
+/**
+ * Runs a render operation with a ref collector active.
+ * @template T
+ * @param {Record<string, Element>} refs Object populated by `ref` properties.
+ * @param {() => T} fn Synchronous render operation.
+ * @returns {T}
+ */
+h.scope = function scope(refs, fn) {
+  const previous = activeRefs;
+  activeRefs = refs;
+  try {
+    return fn();
+  } finally {
+    activeRefs = previous;
+  }
+};
+
+/**
+ * Parses explicitly trusted component-generated HTML into a document fragment.
+ * User and server content must never be passed to this function.
+ * @param {string} html Trusted HTML string.
+ * @returns {DocumentFragment}
+ */
+h.raw = function raw(html) {
+  const template = document.createElement('template');
+  template.innerHTML = String(html);
+  return template.content;
+};
+
+/** @typedef {{children: Node[], attributes: [string, string][]}} TargetSnapshot */
+
+/**
+ * Captures an enhanced target's children and attributes so `destroy()` can put it back exactly as
+ * it was found.
+ * @param {Element} element Target being taken over.
+ * @returns {TargetSnapshot}
+ */
+export function snapshotTarget(element) {
+  return {
+    children: Array.from(element.childNodes),
+    attributes: Array.from(element.attributes, (attribute) => [attribute.name, attribute.value])
+  };
+}
+
+/**
+ * Restores a target captured by `snapshotTarget()`.
+ * @param {Element} element Target to restore.
+ * @param {TargetSnapshot|null} snapshot Snapshot taken before the takeover, or null to do nothing.
+ * @returns {void}
+ */
+export function restoreTarget(element, snapshot) {
+  if (!snapshot) return;
+  for (const attribute of Array.from(element.attributes)) element.removeAttribute(attribute.name);
+  for (const [name, value] of snapshot.attributes) element.setAttribute(name, value);
+  element.replaceChildren(...snapshot.children);
+}
+
+/**
+ * Escapes text for safe insertion into an HTML string.
+ * @param {unknown} str Value to escape.
+ * @returns {string}
+ */
+export function htmlEscape(str) {
+  return String(str).replace(/[&<>"']/g, (character) => ({
+    '&': '&amp;',
+    '<': '&lt;',
+    '>': '&gt;',
+    '"': '&quot;',
+    "'": '&#39;'
+  })[character]);
+}
+
+/**
+ * @typedef {Object} HighlightOptions
+ * @property {string} [className='zx-mark'] Class applied to each generated `<mark>`.
+ */
+
+/**
+ * Wraps every case-insensitive occurrence of a query in a `<mark>` element and returns the result
+ * as a fragment. The text is placed in text nodes and the marks are built element by element, so
+ * this is safe for user and server data — no HTML is ever parsed. An empty or whitespace-only
+ * query yields the text unchanged in a single text node.
+ * @param {unknown} text Text to search.
+ * @param {unknown} query Search term, matched literally.
+ * @param {HighlightOptions} [options={}] Marking options.
+ * @returns {DocumentFragment}
+ */
+export function highlightMatch(text, query, options = {}) {
+  const { className = 'zx-mark' } = options;
+  const source = text == null ? '' : String(text);
+  const needle = query == null ? '' : String(query).trim();
+  const fragment = document.createDocumentFragment();
+
+  if (needle === '' || source === '') {
+    fragment.append(document.createTextNode(source));
+    return fragment;
+  }
+
+  const pattern = new RegExp(escapeRegExp(needle), 'gi');
+  let cursor = 0;
+  for (const match of source.matchAll(pattern)) {
+    if (match.index > cursor) {
+      fragment.append(document.createTextNode(source.slice(cursor, match.index)));
+    }
+    const mark = document.createElement('mark');
+    if (className) mark.className = String(className);
+    mark.append(document.createTextNode(match[0]));
+    fragment.append(mark);
+    cursor = match.index + match[0].length;
+  }
+  if (cursor < source.length) fragment.append(document.createTextNode(source.slice(cursor)));
+  return fragment;
+}
+
+/**
+ * Resolves an Element, selector, or object exposing `toElement()`.
+ * @param {Element|string|ElementProvider|null|undefined} target Target to resolve.
+ * @returns {Element|null}
+ */
+export function resolveElement(target) {
+  if (target == null) return null;
+  if (isElement(target)) return target;
+  if (typeof target === 'string') return document.querySelector(target);
+  if (typeof target.toElement === 'function') {
+    const resolved = target.toElement();
+    return isElement(resolved) ? resolved : null;
+  }
+  return null;
+}
+
+/** @param {unknown} value @returns {value is Record<string, any>} */
+function isPropsObject(value) {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) return false;
+  // Duck-typed on purpose: a Node or a component is a child, anything else is the props object.
+  const candidate = /** @type {Record<string, unknown>} */ (value);
+  if (typeof candidate.nodeType === 'number') return false;
+  return typeof candidate.toElement !== 'function';
+}
+
+/** @param {HTMLElement} element @param {string} key @param {any} value @returns {void} */
+function applyProperty(element, key, value) {
+  if (key === 'ref') {
+    if (activeRefs && typeof value === 'string') activeRefs[value] = element;
+    return;
+  }
+  if (key === 'class') {
+    element.className = Array.isArray(value) ? value.flat(Infinity).filter(Boolean).join(' ') : String(value ?? '');
+    return;
+  }
+  if (key === 'style') {
+    if (typeof value === 'string') element.style.cssText = value;
+    else if (value && typeof value === 'object') {
+      for (const [property, styleValue] of Object.entries(value)) {
+        if (property.startsWith('--') || property.includes('-')) {
+          element.style.setProperty(property, String(styleValue));
+        } else {
+          element.style[property] = styleValue;
+        }
+      }
+    }
+    return;
+  }
+  if (key === 'dataset' && value && typeof value === 'object') {
+    for (const [name, datasetValue] of Object.entries(value)) {
+      if (datasetValue == null) delete element.dataset[name];
+      else element.dataset[name] = String(datasetValue);
+    }
+    return;
+  }
+  if (/^on[a-z]/.test(key) && typeof value === 'function') {
+    element.addEventListener(key.slice(2), value);
+    return;
+  }
+  if (value == null) return;
+
+  const attribute = ariaAttribute(key);
+  if (attribute !== null) {
+    element.setAttribute(attribute, String(value));
+  } else if (key in element) {
+    try {
+      element[key] = value;
+    } catch {
+      element.setAttribute(key, String(value));
+    }
+  } else if (typeof value === 'boolean') {
+    if (value) element.setAttribute(key, '');
+    else element.removeAttribute(key);
+  } else {
+    element.setAttribute(key, String(value));
+  }
+}
+
+/** @param {string} key @returns {string|null} */
+function ariaAttribute(key) {
+  if (key.startsWith('aria-')) return key;
+  if (!/^aria[A-Z]/.test(key)) return null;
+  // ARIAMixin reflection: ariaHasPopup -> aria-haspopup, ariaValueMin -> aria-valuemin.
+  return 'aria-' + key.slice(4).toLowerCase();
+}
+
+/** @param {Node} parent @param {DomChild[]} children @returns {void} */
+function appendChildren(parent, children) {
+  // `flat(Infinity)` erases the element type, and `append` lives on ParentNode rather than Node.
+  const host = /** @type {ParentNode} */ (parent);
+  // Cast before flattening: `DomChild` is recursive, and flattening it to an unbounded depth is a
+  // type the compiler gives up on ("excessively deep") though the runtime behaviour is trivial.
+  for (const raw of /** @type {any[]} */ (children).flat(Infinity)) {
+    if (raw == null) continue;
+    if (typeof raw === 'string' || typeof raw === 'number') {
+      host.append(document.createTextNode(String(raw)));
+      continue;
+    }
+    if (typeof raw !== 'object') continue;
+    const child = /** @type {{nodeType?: number, toElement?: () => Node|null}} */ (raw);
+    if (typeof child.nodeType === 'number') {
+      host.append(/** @type {Node} */ (raw));
+    } else if (typeof child.toElement === 'function') {
+      const element = child.toElement();
+      if (element) host.append(element);
+    }
+  }
+}

package/src/core/export.js

@@ -0,0 +1,204 @@
+// @ts-check
+/**
+ * @typedef {Object} CsvColumn
+ * @property {string} id Row property read when no `value` accessor is given, and the default label.
+ * @property {string} [label] Header text; defaults to `id`.
+ * @property {(row: any) => unknown} [value] Accessor returning the cell value for a row.
+ */
+
+/**
+ * @typedef {Object} CsvOptions
+ * @property {string} [delimiter=','] Field separator; use `';'` for German Excel locales.
+ * @property {boolean} [header=true] Whether to emit the header row.
+ * @property {string} [newline='\r\n'] Record separator; RFC 4180 uses CRLF.
+ */
+
+/**
+ * @typedef {Object} DownloadOptions
+ * @property {string} [type='text/plain;charset=utf-8'] MIME type of the generated blob.
+ */
+
+/** Characters that make a spreadsheet treat a text cell as a formula. */
+const FORMULA_STARTERS = ['=', '+', '-', '@'];
+/** Object URLs are revoked late so the browser has started the download before they disappear. */
+const REVOKE_DELAY = 1000;
+
+/**
+ * Serialises rows to RFC 4180 CSV text.
+ *
+ * Fields containing the delimiter, a double quote, CR, or LF are quoted with inner quotes doubled.
+ * Dates become ISO strings, null and undefined become empty fields, and text that starts with
+ * `=`, `+`, `-`, or `@` is prefixed with a tab so spreadsheets treat it as text rather than a
+ * formula. Numbers are never prefixed, so negative amounts survive intact.
+ *
+ * @param {Iterable<any>|null|undefined} rows Row objects.
+ * @param {Array<string|CsvColumn>} columns Column ids, or descriptors with a label and accessor.
+ * @param {CsvOptions} [options={}] Serialisation options.
+ * @returns {string}
+ */
+export function toCsv(rows, columns, options = {}) {
+  const { delimiter = ',', header = true, newline = '\r\n' } = options;
+  const definitions = normalizeColumns(columns);
+  const lines = [];
+
+  if (header) {
+    lines.push(definitions
+      .map((column) => escapeField(column.label, delimiter, needsFormulaGuard(column.label)))
+      .join(delimiter));
+  }
+  for (const row of rows ?? []) {
+    const fields = definitions.map((column) => {
+      const value = typeof column.value === 'function' ? column.value(row) : readProperty(row, column.id);
+      return escapeField(formatValue(value), delimiter, needsFormulaGuard(value));
+    });
+    lines.push(fields.join(delimiter));
+  }
+  return lines.join(newline);
+}
+
+/**
+ * Saves data to the user's downloads through a temporary object URL and anchor click.
+ * A UTF-8 BOM is prepended to CSV strings so Excel reads them as UTF-8.
+ * @param {string} filename Suggested file name including its extension.
+ * @param {string|Blob|ArrayBuffer|ArrayBufferView} data Payload to save.
+ * @param {DownloadOptions} [options={}] Blob options.
+ * @returns {void}
+ */
+export function downloadBlob(filename, data, options = {}) {
+  const { type = 'text/plain;charset=utf-8' } = options;
+  const blob = toBlob(data, type);
+  const url = URL.createObjectURL(blob);
+  const anchor = document.createElement('a');
+
+  anchor.href = url;
+  anchor.download = String(filename ?? 'download');
+  anchor.rel = 'noopener';
+  anchor.style.display = 'none';
+  document.body.append(anchor);
+  anchor.click();
+  anchor.remove();
+  setTimeout(() => URL.revokeObjectURL(url), REVOKE_DELAY);
+}
+
+/**
+ * Copies text to the clipboard, falling back to a hidden textarea when the async Clipboard API is
+ * unavailable or blocked. Never rejects.
+ * @param {string} text Text to copy.
+ * @returns {Promise<boolean>} Whether the copy succeeded.
+ */
+export async function copyToClipboard(text) {
+  const value = String(text ?? '');
+  if (globalThis.navigator?.clipboard?.writeText) {
+    try {
+      await navigator.clipboard.writeText(value);
+      return true;
+    } catch {
+      // Denied permission or a non-secure context falls through to the legacy path.
+    }
+  }
+  return legacyCopy(value);
+}
+
+/**
+ * Copies through a hidden textarea and `document.execCommand`, restoring focus afterwards.
+ * @param {string} value Text to copy.
+ * @returns {boolean}
+ */
+function legacyCopy(value) {
+  if (typeof document === 'undefined' || !document.body) return false;
+  const active = document.activeElement;
+  const textarea = document.createElement('textarea');
+
+  textarea.value = value;
+  textarea.setAttribute('readonly', '');
+  textarea.setAttribute('aria-hidden', 'true');
+  textarea.style.cssText = 'position:fixed;inset-block-start:-1000px;opacity:0;pointer-events:none';
+  document.body.append(textarea);
+
+  let copied = false;
+  try {
+    textarea.select();
+    textarea.setSelectionRange(0, value.length);
+    copied = document.execCommand?.('copy') === true;
+  } catch {
+    copied = false;
+  } finally {
+    textarea.remove();
+    if (active instanceof HTMLElement) active.focus({ preventScroll: true });
+  }
+  return copied;
+}
+
+/**
+ * @param {Array<string|CsvColumn>} columns Column ids or descriptors.
+ * @returns {Array<{id: string, label: string, value?: (row: any) => unknown}>}
+ */
+function normalizeColumns(columns) {
+  return (columns ?? []).map((column) => {
+    if (typeof column === 'string') return { id: column, label: column };
+    const id = String(column?.id ?? '');
+    return { id, label: String(column?.label ?? id), value: column?.value };
+  });
+}
+
+/** @param {any} row @param {string} id @returns {unknown} */
+function readProperty(row, id) {
+  return row == null ? undefined : row[id];
+}
+
+/**
+ * Converts a cell value to its CSV text form.
+ * @param {unknown} value Cell value.
+ * @returns {string}
+ */
+function formatValue(value) {
+  if (value === null || value === undefined) return '';
+  if (value instanceof Date) return Number.isNaN(value.getTime()) ? '' : value.toISOString();
+  if (typeof value === 'number') return Number.isFinite(value) ? String(value) : '';
+  if (typeof value === 'boolean') return value ? 'true' : 'false';
+  if (typeof value === 'object') {
+    try {
+      return JSON.stringify(value);
+    } catch {
+      return String(value);
+    }
+  }
+  return String(value);
+}
+
+/**
+ * Reports whether a value is text that a spreadsheet could execute as a formula.
+ * @param {unknown} value Cell value.
+ * @returns {boolean}
+ */
+function needsFormulaGuard(value) {
+  if (typeof value !== 'string') return false;
+  return FORMULA_STARTERS.includes(value.charAt(0));
+}
+
+/**
+ * @param {string} field Text form of a cell.
+ * @param {string} delimiter Active field separator.
+ * @param {boolean} [guard=false] Whether to defuse a leading formula character.
+ * @returns {string}
+ */
+function escapeField(field, delimiter, guard = false) {
+  const text = guard ? `\t${field}` : field;
+  const mustQuote = text.includes(delimiter) || text.includes('"') ||
+    text.includes('\n') || text.includes('\r');
+  return mustQuote ? `"${text.replaceAll('"', '""')}"` : text;
+}
+
+/**
+ * @param {string|Blob|ArrayBuffer|ArrayBufferView} data Payload.
+ * @param {string} type MIME type.
+ * @returns {Blob}
+ */
+function toBlob(data, type) {
+  if (typeof Blob === 'function' && data instanceof Blob) return data;
+  // Excel only recognises UTF-8 CSV when the file opens with a byte-order mark.
+  const parts = /** @type {BlobPart[]} */ (
+    typeof data === 'string' && /^text\/csv\b/i.test(type) ? ['\uFEFF', data] : [data]
+  );
+  return new Blob(parts, { type });
+}

package/src/core/fontawesome.js

@@ -0,0 +1,177 @@
+// @ts-check
+/**
+ * Font Awesome knowledge for the icon layer: style/family class names, the built-in glyph
+ * name → Font Awesome name map, icon-spec parsing, and kit loading.
+ *
+ * Nothing here is imported by a component. `icons.js` uses it only after an application opts in
+ * with `useFontAwesome()` / `loadFontAwesome()`, so the zero-dependency default is untouched: Zx
+ * never fetches a kit, a stylesheet, or a webfont on its own.
+ */
+
+/**
+ * Font Awesome style names mapped to their CSS class. `kit` is the pseudo-style for custom icons
+ * uploaded to a kit (`fa-kit fa-zeyos-notes`).
+ * @type {Readonly<Record<string, string>>}
+ */
+export const faStyles = Object.freeze({
+  solid: 'fa-solid',
+  regular: 'fa-regular',
+  light: 'fa-light',
+  thin: 'fa-thin',
+  duotone: 'fa-duotone',
+  brands: 'fa-brands',
+  kit: 'fa-kit'
+});
+
+/**
+ * Font Awesome families mapped to their CSS class. `classic` is the default and adds no class.
+ * @type {Readonly<Record<string, string>>}
+ */
+export const faFamilies = Object.freeze({
+  classic: '',
+  sharp: 'fa-sharp',
+  'sharp-duotone': 'fa-sharp-duotone'
+});
+
+/** Short prefixes accepted in an icon spec (`fas:user`), mapped to a style name. */
+const stylePrefixes = Object.freeze({
+  fa: null, fas: 'solid', far: 'regular', fal: 'light', fat: 'thin', fad: 'duotone',
+  fab: 'brands', fak: 'kit', solid: 'solid', regular: 'regular', light: 'light', thin: 'thin',
+  duotone: 'duotone', brands: 'brands', kit: 'kit', custom: 'kit'
+});
+
+/**
+ * Built-in Zx glyph names mapped to their Font Awesome 6/7 counterpart, so the same component
+ * code renders either provider. Names not listed here are passed to Font Awesome unchanged.
+ * @type {Readonly<Record<string, string>>}
+ */
+export const faNames = Object.freeze({
+  x: 'xmark',
+  search: 'magnifying-glass',
+  calendar: 'calendar-days',
+  reload: 'arrows-rotate',
+  dots: 'ellipsis',
+  info: 'circle-info',
+  warning: 'triangle-exclamation',
+  error: 'circle-exclamation',
+  success: 'circle-check',
+  drag: 'grip-vertical'
+});
+
+/** @type {Map<string, Promise<void>>} In-flight and settled kit loads, keyed by URL. */
+const kitLoads = new Map();
+
+/**
+ * @typedef {Object} IconSpec
+ * @property {'fa'|'builtin'|null} provider Renderer the spec named, null when it named none.
+ * @property {string} name Bare icon name (`'user'`, `'zeyos-notes'`), empty for literal specs.
+ * @property {string|null} style Style named by the spec, if any.
+ * @property {string[]|null} classes Literal class list when the spec was already CSS classes.
+ */
+
+/**
+ * Parses an icon spec into the renderer it names and the icon name it carries. Recognised forms:
+ *
+ * - `'fa-solid fa-user'`, `'fa-kit fa-zeyos-notes'` — a literal class list, used as given.
+ * - `'fa:user'`, `'fas:user'`, `'duotone:user'`, `'kit:zeyos-notes'` — prefix plus icon name.
+ * - `'builtin:check'` — forces one of the bundled inline SVG glyphs.
+ * - `'user'` — a bare name, left for the caller's active provider to interpret.
+ *
+ * @param {string} spec Icon spec.
+ * @returns {IconSpec}
+ */
+export function parseIconSpec(spec) {
+  const text = String(spec).trim();
+  if (/\s/.test(text) || text.startsWith('fa-')) {
+    const classes = text.split(/\s+/).filter(Boolean);
+    return { provider: 'fa', name: '', style: null, classes };
+  }
+
+  const separator = text.indexOf(':');
+  if (separator > 0) {
+    const prefix = text.slice(0, separator).toLowerCase();
+    const name = text.slice(separator + 1);
+    if (prefix === 'builtin' || prefix === 'zx') {
+      return { provider: 'builtin', name, style: null, classes: null };
+    }
+    if (Object.hasOwn(stylePrefixes, prefix)) {
+      return { provider: 'fa', name, style: stylePrefixes[prefix], classes: null };
+    }
+  }
+
+  return { provider: null, name: text, style: null, classes: null };
+}
+
+/**
+ * @typedef {Object} FaClassOptions
+ * @property {string} [style='solid'] Style name from `faStyles`.
+ * @property {string} [family='classic'] Family name from `faFamilies`.
+ * @property {boolean} [fixedWidth=false] Adds `fa-fw` for column-aligned glyphs.
+ * @property {boolean} [translate=true] Maps built-in Zx glyph names through `faNames`.
+ */
+
+/**
+ * Builds the Font Awesome class list for an icon name.
+ * @param {string} name Font Awesome icon name, with or without the `fa-` prefix.
+ * @param {FaClassOptions} [options={}] Style, family, and modifiers.
+ * @returns {string[]} Class names, style/family first.
+ */
+export function faIconClasses(name, options = {}) {
+  const { style = 'solid', family = 'classic', fixedWidth = false, translate = true } = options;
+  const bare = String(name).replace(/^fa-/, '');
+  const resolved = translate ? faNames[bare] ?? bare : bare;
+  const classes = [];
+  const familyClass = faFamilies[family];
+  if (familyClass) classes.push(familyClass);
+  classes.push(faStyles[style] ?? faStyles.solid, `fa-${resolved}`);
+  if (fixedWidth) classes.push('fa-fw');
+  return classes;
+}
+
+/**
+ * Expands a kit token into its script URL. Full URLs and paths are returned unchanged.
+ * @param {string} kit Kit token (`'ae8320b210'`) or script URL.
+ * @returns {string}
+ */
+export function kitUrl(kit) {
+  const value = String(kit).trim();
+  if (/^(https?:)?\/\//.test(value) || value.startsWith('/') || value.endsWith('.js')) return value;
+  if (!/^[a-z0-9]+$/.test(value)) throw new RangeError(`Invalid Font Awesome kit token: ${kit}`);
+  return `https://kit.fontawesome.com/${value}.js`;
+}
+
+/**
+ * Loads a Font Awesome kit script once per URL. Repeat calls return the first promise, and a kit
+ * the host page already embedded is adopted rather than loaded twice.
+ * @param {string} kit Kit token or script URL.
+ * @returns {Promise<void>} Resolves when the kit has loaded.
+ */
+export function loadFontAwesomeKit(kit) {
+  const url = kitUrl(kit);
+  const pending = kitLoads.get(url);
+  if (pending) return pending;
+
+  const promise = /** @type {Promise<void>} */ (new Promise((resolve, reject) => {
+    const absolute = new URL(url, document.baseURI).href;
+    const existing = [...document.scripts].find((script) => script.src === absolute);
+    if (existing && globalThis.FontAwesomeKitConfig) {
+      resolve();
+      return;
+    }
+
+    const script = existing ?? document.createElement('script');
+    script.addEventListener('load', () => resolve(), { once: true });
+    script.addEventListener('error', () => {
+      kitLoads.delete(url);
+      reject(new Error(`Font Awesome kit failed to load: ${url}`));
+    }, { once: true });
+    if (existing) return;
+    script.src = url;
+    script.async = true;
+    script.crossOrigin = 'anonymous';
+    document.head.append(script);
+  }));
+
+  kitLoads.set(url, promise);
+  return promise;
+}