@skirbi/sugar 0.0.7 → 0.0.9

package/Changes

@@ -1,5 +1,97 @@
 Revision history for @skirbi/sugar
 
+0.0.9       2026-02-23 10:56:27Z
+
+  * Fix a bug for connectedCallbacks with Livewire
+
+    In tests with livewire we found out that the connectedCallback doesn't
+    always work when others do DOM manipulation. The solution is an optional
+    mixin that solves the problem for those cases when you need more logic
+    applied to your system.
+
+    The idea is such, you define `renderGuardSelector`, eg `footer`, we look
+    for this element in the DOM under your custom element. If we cannot find
+    it, we know we must rerender. So we do that, the only thing you need to
+    define if the how. You do that by implementing `connectedCallbackSugar()`.
+
+    Example:
+    class XActions extends withConnectedSugar(HTMLElementSugar) {
+      static tag = 'x-actions';
+      static renderGuardSelector = 'footer';
+
+      static _tpl = this.tpl(`
+        <footer>
+          <div semtic-body></div>
+        </footer>
+      `);
+
+      connectedCallbackSugar() {
+        const frag = this.renderFromTemplate();
+        const body = frag.querySelector('[semtic-body]');
+
+        // move children into body
+        while (this.firstChild) body.appendChild(this.firstChild);
+
+        this.replaceChildren(frag);
+      }
+    }
+    XActions.register();
+
+0.0.8       2026-02-23 03:32:55Z
+
+  * Add assertComponentContract testing method.  The idea is this:
+
+    class FooBar extends HTMLElementSugar {
+      ...
+      static exampleHTML = '<foo-bar attrs="here"></foo-bar>";
+      static exampleRenderedHTML = '<some-thing></some-thing>';
+
+      // your connected callback code here
+    }
+
+    Now you can test the component to adhere to the contract by using
+    assertComponentContract:
+
+      import { setupDomForTesting, assertComponentContract } from
+        '@skirbi/sugar/testing';
+
+      // test setup here
+
+      t.test('Test exampleHTML and friends', t => {
+
+        class TestExampleHTML extends HTMLElementSugar {
+         static HtmlTemplate = 'track-item-template';
+          static exampleHTML = '<test-example-html></test-example-html>';
+          static exampleRenderedHTML = `
+              <div class="track-row"><div class="track-info">ok</div></div>
+          `;
+
+          connectedCallback() {
+            if (this._rendered) return;
+            this._rendered = true;
+            this.appendChild(this.renderFromTemplate());
+          }
+        }
+        document.body.innerHTML = `
+          <template id="track-item-template">
+            <div class="track-row"><div class="track-info">ok</div></div>
+          </template>
+       `;
+
+        TestExampleHTML.register();
+        t.equal(TestExampleHTML.tag, 'test-example-html');
+        assertComponentContract(TestExampleHTML,
+          '<test-example-html></test-example-html>');
+        t.end();
+
+      });
+
+    While the test system has been setup in @skirbi/sugar we do *not*
+    enforce it. Component authors are free to use the infrastructure. It is
+    build as an nice to have feature. Be aware, that the testing framework
+    is tap, so in case a component author uses a different testframework you
+    may need to roll your own solution.
+
 0.0.7       2026-02-20 16:54:59Z
 
   * Fix exports in lib/index.mjs: allow SugarInput and SugarSelect to be

package/lib/index.mjs

@@ -2,7 +2,7 @@
 //
 // SPDX-License-Identifier: MIT
 
-const VERSION = "0.0.7";
+const VERSION = "0.0.9";
 
 export { HTMLElementSugar } from './htmlelement.mjs';
 export { HTMLElementSugarInput } from './htmlelement-input.mjs';
@@ -10,3 +10,4 @@ export { HTMLElementSugarSelect } from './htmlelement-select.mjs';
 export { parseBoolean } from './boolean.mjs';
 export { registerDevAlias, applyDevAliases } from './aliases.mjs';
 export { registerAliases } from './aliases-register.mjs';
+export { withConnectedSugar } from './with-connected-sugar.mjs';

package/lib/testing.mjs

@@ -4,32 +4,170 @@
 
 import { JSDOM } from 'jsdom';
 import { fileURLToPath, pathToFileURL } from 'url';
+import t from 'tap';
 import path from 'path';
 
 /**
- * Set up a jsdom environment and load one or more modules.
+ * Initialize a jsdom-based DOM environment for component testing.
  *
- * @param  {...string} modulePaths - relative paths to modules to import
+ * This function:
+ * - Creates a new JSDOM instance
+ * - Exposes common DOM globals on `global`
+ * - Optionally imports one or more modules after the DOM is ready
+ *
+ * It is intended for use in test files before mounting custom elements.
+ *
+ * @param {string} [html='<!doctype html><html><body></body></html>']
+ *   Initial HTML document to load into jsdom.
+ *
+ * @param {...string} modulePaths
+ *   Relative paths (from project root) to modules that should be imported
+ *   after the DOM environment is initialized.
+ *
+ * @returns {Promise<void>}
  */
 export async function setupDomForTesting(
   html = '<!doctype html><html><body></body></html>',
-  ...modulePaths) {
+  ...modulePaths
+) {
   const dom = new JSDOM(html);
 
+  // Expose minimal DOM globals required for custom elements.
   global.DocumentFragment = dom.window.DocumentFragment;
   global.HTMLElement = dom.window.HTMLElement;
   global.HTMLTemplateElement = dom.window.HTMLTemplateElement;
-  global.Node = dom.window.Node
+  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();
 
+  // Import modules after DOM is ready.
   for (const relPath of modulePaths) {
     const absURL = pathToFileURL(path.resolve(projectRoot, relPath));
     await import(absURL.href);
   }
 }
+
+/**
+ * Test a component's example contract.
+ *
+ * This helper verifies:
+ *
+ * 1. `Class.exampleHTML` matches the provided `example` snippet.
+ * 2. After mounting and lifecycle execution, the rendered output
+ *    matches `Class.exampleRenderedHTML`.
+ *
+ * The component must define:
+ *
+ * - `static exampleHTML`
+ * - `static exampleRenderedHTML`
+ *
+ * @template {typeof HTMLElement} T
+ *
+ * @param {T & {
+ *   register?: () => void,
+ *   init?: () => void,
+ *   exampleHTML: string,
+ *   exampleRenderedHTML: string
+ * }} Class
+ *   The component class under test.
+ *
+ * @param {Object} options
+ * @param {boolean} [options.register=true]
+ *   Whether to call `Class.register()` (default) or `Class.init()`.
+ *
+ * @param {string} options.example
+ *   Expected authoring HTML to compare against `Class.exampleHTML`.
+ *
+ * @param {import('tap').Test} options.tap
+ *   Tap test instance used for assertions.
+ *
+ * @returns {Promise<void>}
+ */
+export async function assertComponentContract(Class, example) {
+  Class.init();
+
+  t.type(Class.exampleHTML, 'string', 'Has exampleHTML');
+
+  // Compare authoring example.
+  let needle = htmlToFragment(example);
+  let haystack = htmlToFragment(Class.exampleHTML);
+
+  t.ok(
+    needle.isEqualNode(haystack),
+    'Provided example is correct',
+  );
+
+  t.equal(haystack.childElementCount, 1, '.. and has exactly one root element');
+  const el = haystack.firstElementChild;
+  t.ok(el, "... and produced such element");
+  document.body.appendChild(el);
+
+  await new Promise(r => setTimeout(r, 0));
+
+  t.type(Class.exampleRenderedHTML, 'string', '.. and has example rendered');
+  needle = htmlToFragment(Class.exampleRenderedHTML);
+  haystack = htmlToFragment(el.innerHTML);
+
+  t.ok(
+    needle.isEqualNode(haystack),
+    'connectedCallback works',
+  );
+
+  if (el.isConnected) document.body.removeChild(el);
+}
+
+/**
+ * Convert an HTML string into a DocumentFragment.
+ *
+ * The fragment is not connected to the document and does not
+ * trigger custom element lifecycle callbacks.
+ *
+ * @param {string} html - HTML string to parse.
+ * @returns {DocumentFragment}
+ */
+function htmlToFragment(html) {
+  const tpl = document.createElement('template');
+  tpl.innerHTML = html.trim();
+  return tpl.content;
+}
+
+/**
+ * Wait for the DOM lifecycle to settle.
+ *
+ * Resolves after one microtask and one macrotask tick.
+ *
+ * Useful in tests to ensure:
+ * - customElements upgrades have completed
+ * - connectedCallback has run
+ * - DOM mutations triggered by innerHTML have flushed
+ *
+ * @param {number} [times=1] - Number of ticks to wait.
+ * @returns {Promise<void>}
+ */
+export async function tick(times = 1) {
+  for (let i = 0; i < times; i++) {
+    await Promise.resolve(); // microtask
+    await new Promise(r => setTimeout(r, 0)); // macrotask
+  }
+}
+
+/**
+ * Simulate a morph-style DOM replacement (e.g. Livewire / morphdom).
+ *
+ * Replaces the element's innerHTML and waits for lifecycle hooks
+ * and custom element upgrades to complete.
+ *
+ * Intended for testing idempotent connectedCallback behavior.
+ *
+ * @param {Element} el - The container element to replace content in.
+ * @param {string} html - The HTML string to inject.
+ * @returns {Promise<void>}
+ */
+export async function morphReplace(el, html) {
+  el.innerHTML = html;
+  await tick();
+}

package/lib/with-connected-sugar.mjs

@@ -0,0 +1,35 @@
+export const withConnectedSugar = (Base) =>
+  class extends Base {
+    static renderGuardSelector = '';
+
+    _syncObservedAttributesToConfig() {
+      for (const attr of this.constructor.observedAttributes ?? []) {
+        const val = this.getAttribute(attr);
+        if (val !== null) this._applyAttribute(attr, val);
+      }
+    }
+
+    _shouldRenderOnConnect() {
+      const guard = this.constructor.renderGuardSelector;
+
+      if (guard) {
+        return !this.querySelector(guard);
+      }
+
+      if (this._rendered) return false;
+
+      this._rendered = true;
+      return true;
+    }
+
+    connectedCallback() {
+      this._syncObservedAttributesToConfig();
+
+      if (!this._shouldRenderOnConnect()) return;
+
+      if (typeof this.connectedCallbackSugar === 'function') {
+        this.connectedCallbackSugar();
+      }
+    }
+  };
+

package/package.json

@@ -4,7 +4,7 @@
     "name": "Wesley Schwengle"
   },
   "bugs": {
-    "url": "https://gitlab.com/opndev/javascript/skirbi/-/issues"
+    "url": "https://gitlab.com/skirbi/sugar/-/issues"
   },
   "dependencies": {
     "@opndev/util": "latest"
@@ -26,9 +26,10 @@
     "./htmlelement": "./lib/htmlelement.mjs",
     "./htmlelement-input": "./lib/htmlelement-input.mjs",
     "./htmlelement-select": "./lib/htmlelement-select.mjs",
-    "./testing": "./lib/testing.mjs"
+    "./testing": "./lib/testing.mjs",
+    "./with-connected-sugar": "./lib/with-connected-sugar.mjs"
   },
-  "homepage": "https://gitlab.com/opndev/javascript/skirbi",
+  "homepage": "https://gitlab.com/skirbi/sugar",
   "keywords": [
     "custom elements",
     "web components",
@@ -41,7 +42,7 @@
   "name": "@skirbi/sugar",
   "repository": {
     "type": "git",
-    "url": "git+https://gitlab.com/opndev/javascript/skirbi.git"
+    "url": "git+https://gitlab.com/skirbi/sugar.git"
   },
   "scripts": {
     "build": "rzil build",
@@ -52,5 +53,5 @@
   },
   "sideEffects": false,
   "type": "module",
-  "version": "0.0.7"
+  "version": "0.0.9"
 }