@skirbi/sugar 0.0.10 → 0.0.12

package/Changes

@@ -1,5 +1,58 @@
 Revision history for @skirbi/sugar
 
+0.0.12       2026-04-13 00:51:51Z
+
+  * While checking other Semtic units, we tightened a few tests and exposed an
+    issue in how components were rendered and rerendered.
+
+    We added new test cases to separate what already worked from what did not,
+    and validated those cases against Livewire. That led to a small redesign of
+    the `connectedSugar` API.
+
+    The result is fairly clean: a consumer now defines two selectors:
+
+    * `renderGuardSelector` indicates whether the component is already fully
+    rendered.
+    * `morphTriggerSelector` indicates whether the component has been morphed back
+    to its authored state.
+
+    Based on these checks, `connectedCallbackSugar()` is called when needed, and
+    the component can normalize itself back to its canonical DOM.
+
+    The previously advised pattern for `connectedCallbackSugar()` is now
+    obsolete.
+
+    This
+
+      connectedCallbackSugar() {
+        this._compile();
+        this._observeChildListOnce(...);
+      }
+
+    Becomes:
+
+      class SugarParent extends withConnectedSugar(HTMLElementSugar) {
+        static tag = 'sugar-parent';
+
+        static renderGuardSelector = ':scope > div[data-sugar-parent]'
+        static morphTriggerSelector = ':scope > sugar-child';
+
+        static _tpl = this.tpl(`
+          <div data-sugar-parent></div>
+        `);
+
+        connectedCallbackSugar() {
+          /* Whatever you want to do here to (re-)render the component */
+        }
+      }
+
+
+0.0.11       2026-02-24 16:53:49Z
+
+  * Fix comparing HTML nodes. Whitespace text nodes are a PITA, we deal with
+    <F2>them and now you can just compare two nodes regardless how you wrote it.
+    Whitespace kinda matters in HTML I guess, until it doesn't. &nbsp;
+
 0.0.10       2026-02-24 03:09:34Z
 
   * Improve Livewire/morphdom support in withConnectedSugar
@@ -30,6 +83,28 @@ Revision history for @skirbi/sugar
     Where `your-tag-here` represents the authored child element that
     indicates the component has been reverted to its pre-compiled state.
 
+    The `_compile` function is part of the contract as it authors child
+    elements into the final DOM structure. But you are free give it any name
+    you'd like. An example implementation may look like this:
+
+      _compile() {
+        const steps = Array.from(this.children)
+          .filter(n => n.tagName?.toLowerCase() === 'x-step')
+          .map(n => n.textContent ?? '');
+
+        const frag = this.renderFromTemplate();
+        const ol = frag.querySelector('ol[data-steps]');
+
+        for (const label of steps) {
+          const li = document.createElement('li');
+          li.textContent = label;
+          ol.appendChild(li);
+        }
+
+        this.replaceChildren(frag);
+      }
+    }
+
 0.0.9       2026-02-23 10:56:27Z
 
   * Fix a bug for connectedCallbacks with Livewire

package/lib/index.mjs

@@ -2,7 +2,7 @@
 //
 // SPDX-License-Identifier: MIT
 
-const VERSION = "0.0.10";
+const VERSION = "0.0.12";
 
 export { HTMLElementSugar } from './htmlelement.mjs';
 export { HTMLElementSugarInput } from './htmlelement-input.mjs';

package/lib/testing.mjs

@@ -129,8 +129,29 @@ export async function assertComponentContract(Class, example) {
  */
 function htmlToFragment(html) {
   const tpl = document.createElement('template');
-  tpl.innerHTML = html.trim();
-  return tpl.content;
+  tpl.innerHTML = html.trim().normalize();
+  return stripWhitespaceTextNodes(tpl.content);
+}
+
+/**
+ * Strip whitespace textnodes from an HTML fragment
+ *
+ * Use primairly to sanitize HTML to compare it
+ *
+ * @param {node} node - an HTML node
+ * @returns {node}
+ */
+function stripWhitespaceTextNodes(node) {
+  for (const child of Array.from(node.childNodes)) {
+    if (child.nodeType === 3) { // TEXT_NODE
+      if (!child.nodeValue.trim()) {
+        child.remove();
+      }
+    } else {
+      stripWhitespaceTextNodes(child);
+    }
+  }
+  return node;
 }
 
 /**

package/lib/with-connected-sugar.mjs

@@ -1,6 +1,16 @@
 export const withConnectedSugar = (Base) =>
   class extends Base {
     static renderGuardSelector = '';
+    static morphTriggerSelector = '';
+
+    connectedCallback() {
+      this._syncObservedAttributesToConfig();
+      this._armMorphObserver();
+
+      if (this._shouldRenderOnConnect()) {
+        this.connectedCallbackSugar();
+      }
+    }
 
     _syncObservedAttributesToConfig() {
       for (const attr of this.constructor.observedAttributes ?? []) {
@@ -9,48 +19,43 @@ export const withConnectedSugar = (Base) =>
       }
     }
 
-    _shouldRenderOnConnect() {
-      const guard = this.constructor.renderGuardSelector;
-      if (guard) return !this.querySelector(guard);
-
-      if (this._rendered) return false;
-      this._rendered = true;
-      return true;
-    }
-
-    /**
-     * Install a single MutationObserver that calls `fn()` when direct children
-     * change and `when()` returns true.
-     *
-     * Intended for morphdom/livewire scenarios where the host stays the same
-     * instance.
-     *
-     * @param {Function} when - predicate
-     * @param {Function} fn - callback
-     */
-    _observeChildListOnce(when, fn) {
+    _armMorphObserver() {
       if (this._sugarMo) return;
 
       this._sugarMo = new MutationObserver(() => {
-        if (when()) fn();
+        if (this._shouldRenderOnMorph()) {
+          this.connectedCallbackSugar();
+        }
       });
 
       this._sugarMo.observe(this, { childList: true });
     }
 
+    _shouldRenderOnMorph() {
+      return this._hasMorphTrigger() && !this._hasRenderedShape();
+    }
+
+    _hasMorphTrigger() {
+      const sel = this.constructor.morphTriggerSelector;
+      return !!(sel && this.querySelector(sel));
+    }
+
+    _shouldRenderOnConnect() {
+      const guard = this.constructor.renderGuardSelector;
+      if (guard) return !this._hasRenderedShape();
+
+      return true;
+    }
+
+    _hasRenderedShape() {
+      const sel = this.constructor.renderGuardSelector;
+      return !!(sel && this.querySelector(sel));
+    }
+
     disconnectedCallback() {
-      // polite cleanup
       this._sugarMo?.disconnect();
       this._sugarMo = null;
     }
 
-    connectedCallback() {
-      this._syncObservedAttributesToConfig();
-      if (!this._shouldRenderOnConnect()) return;
-
-      if (typeof this.connectedCallbackSugar === 'function') {
-        this.connectedCallbackSugar();
-      }
-    }
   };
 

package/package.json

@@ -53,5 +53,5 @@
   },
   "sideEffects": false,
   "type": "module",
-  "version": "0.0.10"
+  "version": "0.0.12"
 }