@skirbi/sugar 0.0.6

package/lib/htmlelement-input.mjs

@@ -0,0 +1,197 @@
+// SPDX-FileCopyrightText: 2026 Wesley Schwengle <wesleys@opperschaap.net>
+//
+// SPDX-License-Identifier: MIT
+
+import { HTMLElementSugar } from './htmlelement.mjs';
+import { parseBoolean } from './boolean.mjs';
+
+/**
+ * HTMLElementSugarInput
+ *
+ * Sugar-layer for "real" form controls rendered in the *light DOM*.
+ *
+ * Contract:
+ * - Subclass HtmlTemplate contains exactly one element matching `controlSelector`
+ *   (default: [wc-control]) which is the actual <input>/<select>/<textarea>.
+ * - Host attributes not part of the component's attributeDefs are forwarded to the
+ *   control element (e.g. wire:model.*, x-model, hx-*, aria-*, data-*, etc).
+ * - Native input/change events are re-emitted from the host.
+ * - Optional attribute mirroring (MutationObserver) is enabled via boolean
+ *   attribute `data-sync` (parsed by parseBoolean).
+ */
+export class HTMLElementSugarInput extends HTMLElementSugar {
+
+  static controlSelector = '[wc-control]';
+  static valueAttr = 'value';
+
+  // NOTE: this gets merged with subclass attributeDefs. If it doesn't, we
+  // still treat it as a reserved config key via deny-set collection.
+  static attributeDefs = {
+    'data-sync': { parser: parseBoolean, default: false },
+  };
+
+  // Collect attributeDefs keys across the inheritance chain
+  static _collectAttributeDefKeys(ctor) {
+    const keys = new Set();
+    let c = ctor;
+    while (c && c !== HTMLElementSugar) {
+      const defs = c.attributeDefs;
+      if (defs && typeof defs === 'object') {
+        for (const k of Object.keys(defs)) keys.add(k);
+      }
+      c = Object.getPrototypeOf(c);
+    }
+    return keys;
+  }
+
+  /**
+   * Deny forwarding of:
+   * - all attributeDefs keys across the class chain
+   * - plus any keys present in getConfig() (extra safety if defs are not merged)
+   */
+  getForwardDenySet() {
+    const keys = this.constructor._collectAttributeDefKeys(this.constructor);
+
+    // If Sugar's getConfig includes parsed attrs, treat those as config too.
+    // This makes deny-set robust even if base attributeDefs aren't merged.
+    const cfg = this.getConfig?.();
+    if (cfg && typeof cfg === 'object') {
+      for (const k of Object.keys(cfg)) keys.add(k);
+    }
+
+    return keys;
+  }
+
+  // Which attributes should never be forwarded by default
+  getForwardSkipSet() {
+    return new Set(['id', 'class', 'style']);
+  }
+
+  // Whether we should mirror host attributes to the control after initial
+  // render.
+  shouldMirrorAttributes() {
+    const cfg = this.getConfig?.();
+    if (cfg && cfg['data-sync'] === true) return true;
+
+    // Fallback if attributeDefs inheritance/merge doesn't include data-sync:
+    const raw = this.getAttribute('data-sync');
+    if (raw === null) return false;
+    return parseBoolean(raw);
+  }
+
+  // Find the control inside a rendered fragment.
+  findControl(frag) {
+    const sel = this.constructor.controlSelector || '[wc-control]';
+    const el = frag.querySelector(sel);
+    if (!el) {
+      const tag = this.constructor.tag || this.constructor.name;
+      throw new Error(`${tag}: template missing control ${sel}`);
+    }
+    return el;
+  }
+
+  /** Forward current host attributes to the control, excluding deny/skip. */
+  forwardAttrsTo(control, deny = this.getForwardDenySet(), skip = this.getForwardSkipSet()) {
+    for (const { name, value } of Array.from(this.attributes)) {
+      if (deny.has(name)) continue;
+      if (skip.has(name)) continue;
+      control.setAttribute(name, value);
+    }
+  }
+
+  // Re-emit native events from the control on the host and keep host valueAttr
+  // in sync.
+  setupFormControl(control) {
+    const valueAttr = this.constructor.valueAttr || 'value';
+
+    const syncHostValue = () => {
+      if ('value' in control) {
+        this.setAttribute(valueAttr, control.value ?? '');
+      }
+    };
+
+    control.addEventListener('input', () => {
+      syncHostValue();
+      this.dispatchEvent(new Event('input', { bubbles: true, composed: true }));
+    });
+
+    control.addEventListener('change', () => {
+      syncHostValue();
+      this.dispatchEvent(new Event('change', { bubbles: true,
+                                               composed: true }));
+    });
+  }
+
+  // Start mirroring host attribute changes to the control.
+  setupAttributeMirroring(control, deny = this.getForwardDenySet(), skip = this.getForwardSkipSet()) {
+
+    // Resolve MutationObserver from the current runtime
+    // (jsdom exposes it on window, not always on globalThis)
+    const MO = globalThis.MutationObserver || globalThis.window?.MutationObserver;
+    if (!MO) {
+      // data-sync requested but MutationObserver is unavailable; no-op
+      return;
+    }
+    const valueAttr = this.constructor.valueAttr || 'value';
+
+    // Avoid double observers on reconnect (HTMLElementSugar encourages
+    // idempotent connectedCallback)
+    this._attrObserver?.disconnect?.();
+
+    this._attrObserver = new MO((mutations) => {
+      for (const m of mutations) {
+        if (m.type !== 'attributes') continue;
+        const name = m.attributeName;
+        if (!name) continue;
+
+        // Mirror value as a property even if it's part of component config
+        // (e.g. value is usually in attributeDefs, so it's in the deny set).
+        if (name === valueAttr && 'value' in control) {
+          const newVal = this.getAttribute(name);
+          control.value = newVal ?? '';
+          continue;
+        }
+
+        if (deny.has(name)) continue;
+        if (skip.has(name)) continue;
+
+        const newVal = this.getAttribute(name);
+
+        if (newVal === null) control.removeAttribute(name);
+        else control.setAttribute(name, newVal);
+      }
+    });
+
+    this._attrObserver.observe(this, { attributes: true });
+  }
+
+  /**
+   * One-liner for subclasses:
+   * - find control in fragment
+   * - forward attrs
+   * - hook events
+   * - optionally mirror attrs (data-sync)
+   *
+   * Returns the control element.
+   */
+  enhanceControl(frag) {
+    const control = this.findControl(frag);
+
+    const deny = this.getForwardDenySet();
+    const skip = this.getForwardSkipSet();
+
+    this.forwardAttrsTo(control, deny, skip);
+    this.setupFormControl(control);
+
+    if (this.shouldMirrorAttributes()) {
+      this.setupAttributeMirroring(control, deny, skip);
+    }
+
+    return control;
+  }
+
+  disconnectedCallback() {
+    super.disconnectedCallback?.();
+    this._attrObserver?.disconnect?.();
+  }
+}

package/lib/htmlelement-select.mjs

@@ -0,0 +1,251 @@
+// SPDX-FileCopyrightText: 2026 Wesley Schwengle <wesleys@opperschaap.net>
+//
+// SPDX-License-Identifier: MIT
+
+import { HTMLElementSugarInput } from './htmlelement-input.mjs';
+import { parseBoolean } from './boolean.mjs';
+
+// Parse integer attributes with a default.
+function parseIntOr(def) {
+  return (v) => {
+    if (v == null || v === '') return def;
+    const n = Number.parseInt(String(v), 10);
+    return Number.isFinite(n) ? n : def;
+  };
+}
+
+// Tiny dotted-path getter: "a.b.c".
+function getByPath(obj, path) {
+  if (!path) return obj;
+  const parts = String(path).split('.').filter(Boolean);
+  let cur = obj;
+  for (const p of parts) {
+    if (cur == null) return undefined;
+    cur = cur[p];
+  }
+  return cur;
+}
+
+// Tiny template interpolation: "{foo} ({bar})".
+// Supports dotted paths: "{user.email}".
+function renderTemplate(str, item) {
+  return String(str).replace(/\{([^}]+)\}/g, (_, key) => {
+    const v = getByPath(item, key.trim());
+    return v == null ? '' : String(v);
+  });
+}
+
+/**
+ * HTMLElementSugarSelect
+ *
+ * Waya-style select authoring base.
+ *
+ * Contract:
+ * - Template must contain exactly one <select wc-control>.
+ * - Always uses a real <select> in the light DOM. Options are real <option>s.
+ * - Mapping supports jpath + label/value paths and optional templates.
+ * - Templates win over jpath-label/jpath-value (no fail-fast).
+ *
+ * Notes:
+ * - Canonical static source attribute is `options` (JSON array).
+ * - `data-options` is accepted as a compatibility alias.
+ */
+export class HTMLElementSugarSelect extends HTMLElementSugarInput {
+  static controlSelector = 'select[wc-control]';
+
+  static attributeDefs = {
+    // Sources
+    endpoint: { default: '' },
+    method: { default: 'GET' },
+    param: { default: 'q' },
+
+    // Static options (JSON string)
+    options: { default: '' },
+    // Compatibility alias (not canonical)
+    'data-options': { default: '' },
+
+    // Search
+    searchable: { parser: parseBoolean, default: false },
+    'min-chars': { parser: parseIntOr(1), default: 1 },
+    debounce: { parser: parseIntOr(250), default: 250 },
+    'search-min': { parser: parseIntOr(0), default: 0 },
+    'nosearch-initial': { parser: parseBoolean, default: false },
+
+    // Mapping
+    jpath: { default: '' },
+    'jpath-label': { default: '' },
+    'jpath-value': { default: '' },
+    'jpath-label-template': { default: '' },
+    'jpath-value-template': { default: '' },
+
+    // Control-ish
+    value: { default: '' },
+    placeholder: { default: '' },
+  };
+
+  // Keep this self-contained (no external <template> required).
+  static HtmlTemplate = this.tpl(`
+    <div skirbi-select>
+      <input skirbi-search type="search">
+      <select wc-control></select>
+    </div>
+  `);
+
+  connectedCallback() {
+    super.connectedCallback();
+
+    if (this._rendered) return;
+    this._rendered = true;
+
+    const frag = this.renderFromTemplate();
+    const cfg = this.getConfig();
+
+    const searchEl = frag.querySelector('[skirbi-search]');
+    const select = this.enhanceControl(frag);
+
+    const hasEndpoint = !!cfg.endpoint;
+    const rawOptions = cfg.options || cfg['data-options'] || '';
+    const hasStatic = !!rawOptions;
+
+    // Only show a search box if asked and there's something to search.
+    if (!(cfg.searchable && (hasEndpoint || hasStatic))) {
+      searchEl?.remove();
+    }
+
+    // Placeholder option (optional).
+    if (cfg.placeholder) this._addPlaceholder(select, cfg.placeholder);
+
+    if (hasStatic) {
+      this._setOptionsFromOptions(select, rawOptions, cfg);
+      if (searchEl) this._setupLocalSearch(select, searchEl);
+    } else if (hasEndpoint) {
+      this._setupRemote(select, searchEl, cfg);
+    }
+
+    // Apply initial value after options exist.
+    if (cfg.value != null && cfg.value !== '') select.value = String(cfg.value);
+
+    this.replaceChildren(frag);
+  }
+
+  _addPlaceholder(select, text) {
+    const opt = document.createElement('option');
+    opt.value = '';
+    opt.textContent = text;
+    opt.disabled = true;
+    opt.selected = true;
+    select.appendChild(opt);
+  }
+
+  _clearOptions(select) {
+    while (select.firstChild) select.removeChild(select.firstChild);
+  }
+
+  _setOptions(select, opts) {
+    this._clearOptions(select);
+    for (const o of opts) {
+      const opt = document.createElement('option');
+      opt.value = o.value == null ? '' : String(o.value);
+      opt.textContent = o.label == null ? '' : String(o.label);
+      if (o.disabled) opt.disabled = true;
+      select.appendChild(opt);
+    }
+  }
+
+  // TODO: getByPath(x, json) might want to return a console.warn when it
+  // returns undefined. This would help developers spot mistakes? Yes/no/maybe?
+
+  // Templates win over path mapping. No fail-fast on overlap.
+  _mapItemToOption(item, cfg) {
+    const lt = cfg['jpath-label-template'];
+    const vt = cfg['jpath-value-template'];
+    const lp = cfg['jpath-label'];
+    const vp = cfg['jpath-value'];
+
+    const label = lt
+      ? renderTemplate(lt, item)
+      : (lp ? getByPath(item, lp) : (item?.label ?? item?.name ?? item));
+
+    const value = vt
+      ? renderTemplate(vt, item)
+      : (vp ? getByPath(item, vp) : (item?.value ?? item?.id ?? item));
+
+    return { value, label };
+  }
+
+  _itemsFromJson(json, cfg) {
+    const arr = cfg.jpath ? getByPath(json, cfg.jpath) : json;
+    return Array.isArray(arr) ? arr : [];
+  }
+
+  _setOptionsFromOptions(select, raw, cfg) {
+    let data;
+    try {
+      data = JSON.parse(raw);
+    } catch {
+      console.warn(`Unable to parse JSON from ${raw}`);
+      data = [];
+    }
+
+    const items = Array.isArray(data) ? data : [];
+    const opts = items.map((it) => this._mapItemToOption(it, cfg));
+    this._setOptions(select, opts);
+  }
+
+  _setupLocalSearch(select, searchEl) {
+    // Filter options by label using hidden=. Keep it minimal and stock.
+    const all = Array.from(select.querySelectorAll('option'));
+    searchEl.addEventListener('input', () => {
+      const q = (searchEl.value || '').toLowerCase();
+      for (const opt of all) {
+        const label = (opt.textContent || '').toLowerCase();
+        opt.hidden = q ? !label.includes(q) : false;
+      }
+    });
+  }
+
+  _setupRemote(select, searchEl, cfg) {
+    const doFetch = async (q) => {
+      const url = new URL(cfg.endpoint, window.location.href);
+      if (q && cfg.param) url.searchParams.set(cfg.param, q);
+
+      this._abort?.abort?.();
+      this._abort = new AbortController();
+
+      const res = await fetch(url.toString(), {
+        method: cfg.method || 'GET',
+        signal: this._abort.signal,
+      });
+
+      const json = await res.json();
+      const items = this._itemsFromJson(json, cfg);
+      const opts = items.map((it) => this._mapItemToOption(it, cfg));
+      this._setOptions(select, opts);
+
+      // search-min: hide the search UI for small results.
+      if (searchEl && cfg['search-min'] > 0) {
+        searchEl.hidden = opts.length <= cfg['search-min'];
+      }
+    };
+
+    if (!searchEl) {
+      if (!cfg['nosearch-initial']) {
+        void doFetch('');
+      }
+      return;
+    }
+
+    let t = null;
+    searchEl.addEventListener('input', () => {
+      const q = searchEl.value || '';
+      if (q.length < cfg['min-chars']) return;
+
+      if (t) clearTimeout(t);
+      t = setTimeout(() => void doFetch(q), cfg.debounce);
+    });
+
+    if (!cfg['nosearch-initial']) {
+      void doFetch('');
+    }
+  }
+}