@skirbi/sugar 0.1.2 → 0.1.3

package/Changes

@@ -1,5 +1,40 @@
 Revision history for @skirbi/sugar
 
+0.1.3       2026-06-05 23:23:43Z
+
+  * Add Livewire integration module
+
+    Add @skirbi/sugar/livewire.mjs. An optional side-effect module that
+    fixes structural mismatches between Livewire's morphing algorithm and
+    Sugar web components.
+
+    Problem? Yes.
+    Livewire sends new HTML in its authored (dehydrated) state. Custom
+    elements in that HTML have not yet run connectedCallback, so their
+    DOM structure differs from the current rendered (hydrated) DOM.
+    Alpine's morph algorithm compares these two structurally different
+    trees, sees mismatches, and calls swapElements — replacing entire
+    subtrees, disconnecting all custom element descendants, triggering
+    cascading connectedCallback re-renders, and causing focus loss on
+    every Livewire update.
+
+    Fix, days:
+    Before Livewire's morph runs, parse the new HTML into a hidden
+    staging element and wait two microtasks for custom elements to
+    hydrate. Alpine then morphs two fully hydrated trees — apples to
+    apples — no structural mismatches, no swaps, no cascade, no focus
+    loss.
+
+    Usage:
+      import '@skirbi/sugar/livewire';
+
+    Only import when using Sugar/Semtic/Skirbi components inside a Livewire
+    application. The guard on typeof document makes it safe in SSR/Node
+    environments.
+
+    This fix is a candidate for upstreaming to Livewire once it has been
+    validated.
+
 0.1.2       2026-06-05 13:39:51Z
 
   * Add replaceChildrenSugarSafe to allow repaints without focus loss

package/lib/index.mjs

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

package/lib/livewire.mjs

@@ -0,0 +1,42 @@
+// SPDX-FileCopyrightText: 2026 Wesley Schwengle <wesleys@opperschaap.net>
+//
+// SPDX-License-Identifier: MIT
+
+/**
+ * @skirbi/sugar — Livewire integration
+ *
+ * Hydrates custom elements in Livewire's new HTML before morphing starts.
+ * This ensures Alpine morphs hydrated vs hydrated trees — apples to apples —
+ * preventing structural mismatches that cause swapElements cascades,
+ * disconnected/reconnected custom elements, and focus loss on every update.
+ *
+ * Usage:
+ *   import '@skirbi/sugar/livewire';
+ *
+ * Only import this when using Sugar components inside a Livewire application.
+ */
+
+if (typeof document !== 'undefined') {
+  document.addEventListener('livewire:init', () => {
+    window.Livewire.hook('component.init', ({ component }) => {
+      const original = component.processEffects.bind(component);
+
+      component.processEffects = function(effects) {
+        if (!effects.html) return original(effects);
+        if (effects._sugarHydrated) return original(effects);
+
+        const staging = document.createElement('div');
+        staging.style.display = 'none';
+        document.body.appendChild(staging);
+        staging.innerHTML = effects.html;
+
+        Promise.resolve().then(() => Promise.resolve().then(() => {
+          effects.html = staging.innerHTML;
+          effects._sugarHydrated = true;
+          staging.remove();
+          original(effects);
+        }));
+      };
+    });
+  });
+}

package/package.json

@@ -24,6 +24,7 @@
     "./htmlelement": "./lib/htmlelement.mjs",
     "./htmlelement-input": "./lib/htmlelement-input.mjs",
     "./htmlelement-select": "./lib/htmlelement-select.mjs",
+    "./livewire": "./lib/livewire.mjs",
     "./testing": "./lib/testing.mjs",
     "./with-connected-sugar": "./lib/with-connected-sugar.mjs"
   },
@@ -52,5 +53,5 @@
   },
   "sideEffects": false,
   "type": "module",
-  "version": "0.1.2"
+  "version": "0.1.3"
 }