@skirbi/sugar 0.0.11 → 0.0.13

package/Changes

@@ -1,9 +1,63 @@
 Revision history for @skirbi/sugar
 
+0.0.13       2026-04-16 13:27:59Z
+
+  * Fix jsdoc build issue
+  * Retro actively fix Changelog for v0.0.9, we missed two small additions in
+    testing.mjs
+  * Add assertQuerySelector() method
+
+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
-    them and now you can just compare two nodes regardless how you wrote it.
+    <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
@@ -95,6 +149,8 @@ Revision history for @skirbi/sugar
     }
     XActions.register();
 
+  * Add `tick` and `morphReplace` methods in `testing.mjs`.
+
 0.0.8       2026-02-23 03:32:55Z
 
   * Add assertComponentContract testing method.  The idea is this:

package/lib/htmlelement.mjs

@@ -327,5 +327,11 @@ export class HTMLElementSugar extends HTMLElement {
   getConfig() {
     return { ...this.config };
   }
+
+  static assertQuerySelector(haystack, needle, msg) {
+    const item = haystack.querySelector(needle)
+    if (!item) throw new Error(msg);
+    return item;
+  }
 }
 

package/lib/index.mjs

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

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.11"
+  "version": "0.0.13"
 }