@skirbi/sugar 0.0.6

package/lib/htmlelement.mjs

@@ -0,0 +1,331 @@
+// SPDX-FileCopyrightText: 2025, 2026 Wesley Schwengle <wesleys@opperschaap.net>
+//
+// SPDX-License-Identifier: MIT
+
+/**
+ * Lightweight base class for authoring Web Components.
+ *
+ * Provides:
+ * - Declarative attribute -> config mapping via static `attributeMap`
+ * - Automatic attribute observation via `observedAttributes`
+ * - Utility methods to register the element and define aliases
+ *
+ * @example
+ * class MyComponent extends HTMLElementSugar {
+ *   static tag = 'opndev-my-component';
+ *   static observedAttributes = ['foo'];
+ *   static attributeMap = { foo: parseBoolean };
+ *   static defaultConfig = { foo: 'bar' };
+ * }
+ *
+ * MyComponent.register();
+ * MyComponent.alias('my-alias', { foo: 'true' });
+ */
+
+import { defined } from '@opndev/util/defined';
+import { registerDevAlias } from './aliases.mjs';
+
+export class HTMLElementSugar extends HTMLElement {
+
+  /**
+   * Register the element using its static `tag` name.
+   * Should be called once per component.
+   */
+  static register() {
+    if (!customElements.get(this.tag)) {
+      this.init();
+      customElements.define(this.tag, this);
+    }
+  }
+
+  /**
+   * Sets up the element and transforms `attributeDefs` to
+   * `observedAttributes`, `attributeMap` and `defaultConfig`. Calling this
+   * multiple times on the component is ok, but discouraged.
+   */
+  static init() {
+    this.checkTag();
+    this.checkAttributes();
+    this.checkTemplate();
+  }
+
+  static deriveTagFromClass() {
+    return this.name
+      .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+      .replace(/([A-Z])([A-Z][a-z])/g, '$1-$2')
+      .toLowerCase();
+  }
+
+  static checkTag() {
+    if (!this.tag) {
+      this.tag = this.deriveTagFromClass();
+    }
+  }
+
+  static checkAttributes() {
+    const hasDefs = !!this.attributeDefs;
+    const hasManualObserved = !!this.observedAttributes;
+    const hasManualMap = !!this.attributeMap;
+    const hasManualDefaults = !!this.defaultConfig;
+
+    if (!hasDefs) {
+      if (!hasManualObserved) this.observedAttributes = [];
+      if (!hasManualMap) this.attributeMap = {};
+      if (!hasManualDefaults) this.defaultConfig = {};
+      return;
+    }
+
+    const hasManual = hasManualObserved || hasManualMap || hasManualDefaults;
+
+    if (hasDefs && hasManual) {
+      throw new Error(
+        `${this.name}: Do not mix 'attributeDefs' with manual fields: ` +
+        `observedAttributes, attributeMap, defaultConfig`
+      );
+    }
+
+    const defs = this.attributeDefs;
+
+    this.observedAttributes = [];
+    this.attributeMap = {};
+    this.defaultConfig = {};
+
+    for (const [key, spec] of Object.entries(defs)) {
+      if (!defined(spec)) {
+        this.observedAttributes.push(key);
+        continue;
+      }
+
+      if (Array.isArray(spec)|| typeof spec !== 'object') {
+        throw new Error(
+          `${this.name}: 'attributeDefs' for key ${key} has an invalid spec`
+        );
+      }
+
+      if (!('observed' in spec) || spec.observed)
+        this.observedAttributes.push(key);
+
+      if ('default' in spec && defined(spec.default))
+        this.defaultConfig[key] = spec.default;
+
+      if ('parser' in spec && defined(spec.parser)) {
+        if (typeof spec.parser !== 'function')
+          throw new Error(`${this.name}: parser for ${key} must be a function`);
+
+        this.attributeMap[key] = spec.parser;
+      }
+
+    }
+    // This delete is intentional. We cannot keep it because it would otherwise
+    // break any subsequent init()/register() calls. For those coming from Perl
+    // this is a JS workaround for a Moose initarg. We essentially forbid both
+    // attributeDefs and formal HTMLElement
+    // observedAttributes/defaultConfig/attributeMap to coexist
+    delete this.attributeDefs;
+  }
+
+  static checkTemplate() {
+    const HT = this.HtmlTemplate;
+    if (!HT) return;
+
+    let tpl;
+
+    // Tuple form: [externalRef, fallback]
+    if (Array.isArray(HT)) {
+      const [externalRef, fallback] = HT;
+
+      // external
+      if (typeof externalRef === 'string') {
+        tpl = document.getElementById(externalRef);
+      } else if (externalRef instanceof HTMLTemplateElement) {
+        tpl = externalRef;
+      } else {
+        throw new Error(`${this.name}: tuple[0] must be string or HTMLTemplateElement`);
+      }
+
+      // fallback
+      if (!(tpl instanceof HTMLTemplateElement)) {
+        if (typeof fallback === 'function') {
+          tpl = fallback.call(this);
+        } else if (fallback instanceof HTMLTemplateElement) {
+          tpl = fallback;
+        } else {
+          throw new Error(`${this.name}: tuple[1] must be function or HTMLTemplateElement`);
+        }
+      }
+
+    // Single string id
+    } else if (typeof HT === 'string') {
+      tpl = document.getElementById(HT);
+
+    // Single template element
+    } else if (HT instanceof HTMLTemplateElement) {
+      tpl = HT;
+
+    // Single factory function
+    } else if (typeof HT === 'function') {
+      tpl = HT.call(this);
+
+    } else {
+      throw new Error(`${this.name}: invalid HtmlTemplate spec`);
+    }
+
+    if (!(tpl instanceof HTMLTemplateElement)) {
+      throw new Error(`${this.name}: resolved HtmlTemplate is not a HTMLTemplateElement`);
+    }
+
+    this._tpl = tpl;
+  }
+
+  static renderFromTemplate() {
+    if (!this._tpl) {
+      throw new Error(this.name + ": no template configured");
+    }
+    return this._tpl.content.cloneNode(true);
+  }
+
+  renderFromTemplate() {
+    return this.constructor.renderFromTemplate();
+  }
+  /**
+   * Define an alias tag name that maps to this element with optional default attributes.
+   *
+   * Useful for semantic shorthand like <side> => <chapter type="side">.
+   *
+   * @param {string} tagName - The alias tag name to define
+   * @param {Object<string, string>} [defaultAttributes={}] - Default attributes to apply if not present
+   */
+  static alias(tagName, defaultAttributes = {}) {
+    // Dev alias: no hyphen → rewrite-only (don’t define)
+    if (!String(tagName).includes('-')) {
+      // Make sure canonical tag exists
+      this.checkTag?.();
+      registerDevAlias(tagName, this.tag, defaultAttributes);
+      return;
+    }
+
+    // Real alias: existing behavior (define a CE alias)
+    const Base = this;
+
+    class AliasElement extends Base {
+      connectedCallback() {
+        for (const [key, val] of Object.entries(defaultAttributes)) {
+          if (!this.hasAttribute(key)) {
+            this.setAttribute(key, val);
+          }
+        }
+        super.connectedCallback?.();
+      }
+    }
+
+    if (!customElements.get(tagName)) {
+      customElements.define(tagName, AliasElement);
+    }
+  }
+
+  /**
+   * Create a HTMLTemplateElement from a string.
+   * @param {string} html
+   * @returns {HTMLTemplateElement}
+   */
+  static tpl(html) {
+    const t = document.createElement('template');
+    t.innerHTML = html.trim();
+    return t;
+  }
+
+  constructor() {
+    super();
+    /**
+     * Internal config object derived from attributes.
+     * @type {Record<string, any>}
+     */
+    this.config = {
+      ...(this.constructor.defaultConfig ?? {})
+    };
+  }
+
+  /**
+   * Called when the element is inserted into the DOM.
+   * Applies initial attributes to config.
+   */
+  connectedCallback() {
+    for (const attr of this.constructor.observedAttributes) {
+      const val = this.getAttribute(attr);
+      if (val !== null) {
+        this._applyAttribute(attr, val);
+      }
+    }
+  }
+
+  /**
+   * Called when an observed attribute changes.
+   * @param {string} name - The attribute name
+   * @param {string|null} _oldVal - Previous value (unused)
+   * @param {string|null} newVal - New value
+   */
+  attributeChangedCallback(name, _oldVal, newVal) {
+    this._applyAttribute(name, newVal);
+  }
+
+  /**
+   * Internal method to apply a mapped attribute to config.
+   * @param {string} name - Attribute name
+   * @param {string|null} value - Raw attribute value
+   */
+  _applyAttribute(name, value) {
+    const map = this.constructor.attributeMap;
+    const handler = map[name];
+
+    if (typeof handler === 'function') {
+      this.config[name] = handler(value);
+    }
+    else {
+      this.config[name] = value;
+    }
+  }
+
+  /**
+   * Find and return the config from the nearest matching ancestor.
+   * Respects optional `get-config-selector` or XPath overrides, via
+   * `get-config-xpath`.
+   *
+   * @returns {object} merged config object from a parent element
+   */
+  getNearestConfig() {
+
+    if (this.hasAttribute('get-config-xpath')) {
+      const xpath = this.getAttribute('get-config-xpath');
+      const result = document.evaluate(xpath, this, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null).singleNodeValue;
+      if (result?.getConfig) return result.getConfig();
+    }
+
+    let selector = this.getAttribute('get-config-selector')
+                || this.constructor.getConfigSelector;
+
+    if (!selector) {
+      throw new Error(`${this.tag} did not define a get-config-selector attribute or static getConfigSelector`);
+    }
+
+    selector = selector.toLowerCase();
+
+    let el = this.parentElement;
+    while (el) {
+      if (el.matches?.(selector) && typeof el.getConfig === 'function') {
+        return el.getConfig();
+      }
+      el = el.parentElement;
+    }
+
+    throw new Error(`${this.tag} could not find a matching ancestor for selector "${selector}"`);
+  }
+
+  /**
+   * Returns a shallow copy of the current config.
+   * @returns {Record<string, any>}
+   */
+  getConfig() {
+    return { ...this.config };
+  }
+}
+

package/lib/index.mjs

@@ -0,0 +1,7 @@
+// SPDX-FileCopyrightText: 2025, 2026 Wesley Schwengle <wesleys@opperschaap.net>
+//
+// SPDX-License-Identifier: MIT
+
+const VERSION = "0.0.6";
+export { HTMLElementSugar } from './htmlelement.mjs';
+export { parseBoolean } from './boolean.mjs';

package/lib/testing.mjs

@@ -0,0 +1,35 @@
+// SPDX-FileCopyrightText: 2025, 2026 Wesley Schwengle <wesleys@opperschaap.net>
+//
+// SPDX-License-Identifier: MIT
+
+import { JSDOM } from 'jsdom';
+import { fileURLToPath, pathToFileURL } from 'url';
+import path from 'path';
+
+/**
+ * Set up a jsdom environment and load one or more modules.
+ *
+ * @param  {...string} modulePaths - relative paths to modules to import
+ */
+export async function setupDomForTesting(
+  html = '<!doctype html><html><body></body></html>',
+  ...modulePaths) {
+  const dom = new JSDOM(html);
+
+  global.DocumentFragment = dom.window.DocumentFragment;
+  global.HTMLElement = dom.window.HTMLElement;
+  global.HTMLTemplateElement = dom.window.HTMLTemplateElement;
+  global.Node = dom.window.Node
+  global.customElements = dom.window.customElements;
+  global.document = dom.window.document;
+  global.window = dom.window;
+  global.MutationObserver = dom.window.MutationObserver;
+
+
+  const projectRoot = process.cwd();
+
+  for (const relPath of modulePaths) {
+    const absURL = pathToFileURL(path.resolve(projectRoot, relPath));
+    await import(absURL.href);
+  }
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "author": {
+    "email": "wesleys@opperschaap.net",
+    "name": "Wesley Schwengle"
+  },
+  "bugs": {
+    "url": "https://gitlab.com/opndev/javascript/skirbi/-/issues"
+  },
+  "dependencies": {
+    "@opndev/util": "latest"
+  },
+  "description": "Lightweight base layer for writing custom elements with declarative attributes and template sugar.",
+  "devDependencies": {
+    "jsdoc": "latest",
+    "jsdom": "latest",
+    "tap": "latest"
+  },
+  "exports": {
+    ".": "./lib/index.mjs",
+    "./aliases": "./lib/aliases.mjs",
+    "./aliases-register": "./lib/aliases-register.mjs",
+    "./boolean": "./lib/boolean.mjs",
+    "./htmlelement": "./lib/htmlelement.mjs",
+    "./htmlelement-input": "./lib/htmlelement-input.mjs",
+    "./htmlelement-select": "./lib/htmlelement-select.mjs",
+    "./testing": "./lib/testing.mjs"
+  },
+  "homepage": "https://gitlab.com/opndev/javascript/skirbi",
+  "keywords": [
+    "custom elements",
+    "web components",
+    "semantic",
+    "htmlelementsugar",
+    "html",
+    "authoring"
+  ],
+  "license": "MIT",
+  "name": "@skirbi/sugar",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.com/opndev/javascript/skirbi.git"
+  },
+  "scripts": {
+    "build": "rzil build",
+    "jsdoc": "jsdoc -c .jsdoc.json",
+    "pkg": "rzil pkg",
+    "release": "rzil release",
+    "test": "tap"
+  },
+  "sideEffects": false,
+  "type": "module",
+  "version": "0.0.6"
+}