@skirbi/sugar 0.0.8 → 0.0.10

package/Changes

@@ -1,5 +1,72 @@
 Revision history for @skirbi/sugar
 
+0.0.10       2026-02-24 03:09:34Z
+
+  * Improve Livewire/morphdom support in withConnectedSugar
+
+    In certain morph scenarios the host element instance remains the same
+    while its child nodes are replaced. In that case `connectedCallback`
+    is not triggered again.
+
+    The mixin now provides `_observeChildListOnce(when, fn)` which allows
+    components to react to child mutations and re-apply their compile logic
+    when necessary.
+
+    This keeps DOM-compiling components (e.g. semtic-steps in @skirbi/semtic)
+    stable even when morphing frameworks replace their internal markup without
+    recreating the custom element instance.
+
+    The pattern for a `connectedCallbackSugar` now becomes:
+
+      connectedCallbackSugar() {
+        this._compile();
+
+        this._observeChildListOnce(
+          () => this.querySelector(':scope > your-tag-here'),
+          () => this._compile()
+        );
+      }
+
+    Where `your-tag-here` represents the authored child element that
+    indicates the component has been reverted to its pre-compiled state.
+
+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:

package/lib/index.mjs

@@ -2,7 +2,7 @@
 //
 // SPDX-License-Identifier: MIT
 
-const VERSION = "0.0.8";
+const VERSION = "0.0.10";
 
 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

@@ -56,23 +56,21 @@ export async function setupDomForTesting(
  *
  * This helper verifies:
  *
- * 1. `Class.exampleHTML` matches the provided `example` snippet.
- * 2. After mounting and lifecycle execution, the rendered output
- *    matches `Class.exampleRenderedHTML`.
+ * 1. `Class.exampleHTML` matches the provided `options.example` snippet.
+ * 2. After mounting and lifecycle execution, the rendered output matches
+ *    `Class.exampleRenderedHTML`.
  *
- * The component must define:
+ * The component class must define:
  *
- * - `static exampleHTML`
- * - `static exampleRenderedHTML`
+ * - `static exampleHTML` (string)
+ * - `static exampleRenderedHTML` (string)
  *
- * @template {typeof HTMLElement} T
+ * It may also define:
  *
- * @param {T & {
- *   register?: () => void,
- *   init?: () => void,
- *   exampleHTML: string,
- *   exampleRenderedHTML: string
- * }} Class
+ * - `static register()` (optional)
+ * - `static init()` (optional)
+ *
+ * @param {Function} Class
  *   The component class under test.
  *
  * @param {Object} options
@@ -82,7 +80,7 @@ export async function setupDomForTesting(
  * @param {string} options.example
  *   Expected authoring HTML to compare against `Class.exampleHTML`.
  *
- * @param {import('tap').Test} options.tap
+ * @param {Object} options.tap
  *   Tap test instance used for assertions.
  *
  * @returns {Promise<void>}
@@ -116,6 +114,8 @@ export async function assertComponentContract(Class, example) {
     needle.isEqualNode(haystack),
     'connectedCallback works',
   );
+
+  if (el.isConnected) document.body.removeChild(el);
 }
 
 /**
@@ -133,3 +133,39 @@ function htmlToFragment(html) {
   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,56 @@
+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;
+    }
+
+    /**
+     * 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) {
+      if (this._sugarMo) return;
+
+      this._sugarMo = new MutationObserver(() => {
+        if (when()) fn();
+      });
+
+      this._sugarMo.observe(this, { childList: true });
+    }
+
+    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

@@ -4,7 +4,7 @@
     "name": "Wesley Schwengle"
   },
   "bugs": {
-    "url": "https://gitlab.com/skirbi/sugar/-/issues"
+    "url": "https://gitlab.com/skirbi/skirbi/-/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/skirbi/sugar",
+  "homepage": "https://gitlab.com/skirbi/skirbi",
   "keywords": [
     "custom elements",
     "web components",
@@ -41,7 +42,7 @@
   "name": "@skirbi/sugar",
   "repository": {
     "type": "git",
-    "url": "git+https://gitlab.com/skirbi/sugar.git"
+    "url": "git+https://gitlab.com/skirbi/skirbi.git"
   },
   "scripts": {
     "build": "rzil build",
@@ -52,5 +53,5 @@
   },
   "sideEffects": false,
   "type": "module",
-  "version": "0.0.8"
+  "version": "0.0.10"
 }