@skirbi/sugar 0.1.10 → 0.1.12

package/Changes

@@ -1,5 +1,110 @@
 Revision history for @skirbi/sugar
 
+0.1.12       2026-07-01 16:53:26Z
+
+  * Due to a change in an upstream project the morphing behaviour came under
+    scrutiny again (0.1.10/11). This caused a regroup moment on my part where
+    all the hooks and knobs of withConnectedSugar were re-examened and I
+    decided to rewrite them into a consistent new state that leverages over the
+    past iterations. I probably should have done it a bit earlier if honest.
+
+    We now introduce: withConnectSuccu.
+
+    With withConnectSuccu, a second-generation connected-lifecycle mixin,
+    alongside the existing withConnectedSugar. It is built and tested in
+    parallel so existing components can migrate one at a time rather than all
+    at once.
+
+    This documents the full API a component gets when it opts into morph
+    support via withConnectSuccu.
+
+    ## Required
+
+    - `static renderGuardSelector`: CSS selector proving "I have already
+      rendered." Unchanged from withConnectedSugar. Required for any
+      render-guarding, attribute reactivity, or morph reactivity to work
+      at all; a component with no renderGuardSelector renders once and
+      never reacts to anything.
+
+    - `connectedCallbackSugar()`: the component's render implementation.
+      Called on first connect, and again on any morph that matches
+      `morphTriggerSelector` (see below) while renderGuardSelector is not
+      yet satisfied.
+
+      As of withConnectSuccu, every call to connectedCallbackSugar,
+      initial or morph-triggered, is automatically wrapped in an
+      observer pause. A component's own render mutates its own children;
+      previously that mutation could be seen by the component's own
+      MutationObserver and misread as an external morph, silently
+      triggering morphedCallbackSugar as a side effect of the component
+      simply rendering itself. This is no longer something component
+      authors need to think about or guard against manually.
+
+    ## Attribute reactivity
+
+    - `static attributeDefs[attrName].hook`: unchanged. String selector
+      or function, fires on any observed attribute change once rendered,
+      for simple "put this value somewhere in my DOM" cases.
+
+    - `updatedAttributeSugar(name, oldVal, newVal)`: new. Escape hatch
+      for attribute changes that need real logic, not just a textContent
+      swap: refetching data, rebuilding a sub-structure, branching per
+      attribute. One method, all reactive attributes; branch on `name`
+      if different attributes need different handling.
+
+      Named after Livewire's own `updatedXyz` convention, deliberately
+      this is the method component authors reach for instead of doing
+      nothing, which was the actual production bug that motivated this
+      whole change (semtic-table never reacted to its own `data`
+      attribute changing after first render).
+
+      Replaces attributeChangedCallbackSugar, which will be removed outright in
+      a future release. No existing (skirbi) component consumed it, so no
+      migration path was needed.
+
+    ## Children / shape reactivity
+
+    - `static morphTriggerSelector`: CSS selector matched against the
+      component's own children. If a morph adds matching content while
+      renderGuardSelector is not yet satisfied, connectedCallbackSugar
+      runs again.
+
+      This selector MUST match only the component's authored/pre-render
+      shape, never its own rendered output. A wildcard like `:scope > *`
+      will also match the component's own rendered children once
+      renderGuardSelector is satisfied, which is exactly what produced
+      the doubled `<footer>` bug found via a production Livewire trace on
+      semtic-actions. Prefer a specific tag or attribute selector that
+      stops matching once the component has rendered.
+
+    - `morphedCallbackSugar()`: unchanged. Called when the component is
+      already rendered and the observer sees a mutation that isn't a
+      fresh morphTriggerSelector match, i.e. existing rendered structure
+      was morphed in place rather than replaced. Now genuinely only fires
+      for real external morphs; see the self-render protection note
+      above.
+
+    ## Not declarative, and not opt-in
+
+    - Self-render protection (the observer pause around connectedCallbackSugar)
+      is unconditional for every component using withConnectSuccu. It was
+      considered as a declarative flag, but there's no real case where a
+      component wants its own render visible to its own observer, so it isn't
+      part of the configurable surface at all.
+
+    withConnectSuccu remains a mixin, not a base class. Composability
+    with other traits was weighed against making it the HTMLElementSugar
+    default; for now @skirbi/sugar stays a general-purpose layer that
+    doesn't mandate morph-awareness for consumers outside the @skirbi
+    ecosystem, even though within @skirbi (semtic, dibuho) it is the
+    de facto convention almost everywhere.
+
+0.1.11       2026-07-01 04:10:34Z
+
+  *  Debugging session start. There is a weird case of it works via local file
+     and not via npm. So I can't really rely on the local file mounts. Ship the
+     debug.
+
 0.1.10       2026-07-01 01:54:46Z
 
   * Add tests to semtic-select

package/lib/index.mjs

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

package/lib/livewire.mjs

@@ -15,30 +15,28 @@
  *
  * Only import this when using Sugar components inside a Livewire application.
  */
+console.log('[sugar-livewire] eval', performance.now())
 
-/*
 console.log('[sugar-livewire] module loaded', {
   hasLivewire: !!window.Livewire,
   hasHook: !!window.Livewire?.hook,
 });
-*/
 
 let registered = false;
 
-
 /**
  * Registers the Sugar Livewire hydration hook.
  *
  * @returns {void}
  */
+
 function registerSugarLivewire() {
-/*
   console.log('[sugar-livewire] register called', {
     registered,
     hasLivewire: !!window.Livewire,
     hasHook: !!window.Livewire?.hook,
+    perf: performance.now(),
   });
-*/
 
   if (registered) return;
   if (!window.Livewire?.hook) return;
@@ -47,74 +45,69 @@ function registerSugarLivewire() {
 
   window.Livewire.hook('component.init', ({ component }) => {
 
- //   console.log('[sugar-livewire] component.init hit', component.id);
+    console.log('[sugar-livewire] component.init hit', component.id);
 
     const original = component.processEffects.bind(component);
-
-component.processEffects = function processSugarEffects(effects) {
-/*
-  console.log('[sugar-livewire] definitions', {
-    dibuho: !!customElements.get('dibuho-container-panel'),
-    panel: !!customElements.get('semtic-panel'),
-    header: !!customElements.get('semtic-header'),
-  });
-
-  console.log('[sugar-livewire] processEffects hit', {
-    hasHtml: !!effects.html,
-    sugarHydrated: !!effects._sugarHydrated,
-  });
-*/
-
-  if (!effects.html) return original(effects);
-  if (effects._sugarHydrated) return original(effects);
-
-  const before = effects.html;
-
-  const staging = document.createElement('div');
-  staging.style.display = 'none';
-  document.body.appendChild(staging);
-
-  try {
-    staging.innerHTML = before;
-
-    const after = staging.innerHTML;
-
-    effects.html = after;
-    effects._sugarHydrated = true;
-
-/*
-    console.group('[sugar-livewire] html');
-    console.log('before:\n', before);
-    console.log('after:\n', after);
-    console.log('changed:', before !== after);
-    console.log('handoff:\n', effects.html);
-    console.log('handoff is after:', effects.html === after);
-    console.groupEnd();
-*/
-
-    return original(effects);
-  } finally {
-    staging.remove();
-  }
-};
-
+    component.processEffects = function processSugarEffects(effects) {
+
+      console.log('[sugar-livewire] definitions', {
+        dibuho: !!customElements.get('dibuho-container-panel'),
+        panel: !!customElements.get('semtic-panel'),
+        header: !!customElements.get('semtic-header'),
+        perf: performance.now(),
+      });
+
+      console.log('[sugar-livewire] processEffects hit', {
+        hasHtml: !!effects.html,
+        sugarHydrated: !!effects._sugarHydrated,
+        perf: performance.now(),
+      });
+
+      if (!effects.html) return original(effects);
+      if (effects._sugarHydrated) return original(effects);
+
+      const before = effects.html;
+      const staging = document.createElement('div');
+      staging.style.display = 'none';
+      document.body.appendChild(staging);
+
+      try {
+        staging.innerHTML = before;
+        const after = staging.innerHTML;
+        effects.html = after;
+        effects._sugarHydrated = true;
+
+        console.group('[sugar-livewire] html');
+        console.log('perf:\n',performance.now());
+        console.log('before:\n', before);
+        console.log('after:\n', after);
+        console.log('changed:', before !== after);
+        console.log('handoff:\n', effects.html);
+        console.log('handoff is after:', effects.html === after);
+        console.groupEnd();
+
+        return original(effects);
+      }
+      finally {
+        staging.remove();
+      }
+    };
   });
 }
 
 if (typeof document !== 'undefined') {
   document.addEventListener('livewire:init', registerSugarLivewire);
-
   queueMicrotask(() => {
     registerSugarLivewire();
   });
 }
 
 document.addEventListener('livewire:init', () => {
-  ///console.log('[sugar-livewire] livewire:init heard');
+  console.log('[sugar-livewire] livewire:init heard');
   registerSugarLivewire();
 });
 
 queueMicrotask(() => {
-  //console.log('[sugar-livewire] microtask fallback');
+  console.log('[sugar-livewire] microtask fallback');
   registerSugarLivewire();
 });

package/lib/with-connected-succu.mjs

@@ -0,0 +1,196 @@
+// SPDX-FileCopyrightText: 2026 Wesley Schwengle <wesleys@opperschaap.net>
+//
+// SPDX-License-Identifier: MIT
+
+/**
+ * withConnectSuccu
+ *
+ * Second-generation connected-lifecycle mixin. Built and tested alongside
+ * withConnectedSugar so existing components can migrate one at a time.
+ *
+ * Changes vs withConnectedSugar:
+ * - Self-render protection is unconditional. Every call to
+ *   connectedCallbackSugar (initial render or morph-triggered re-render)
+ *   is automatically wrapped in an observer pause, so a component's own
+ *   render can never self-trigger morphedCallbackSugar. Component authors
+ *   no longer call withMorphObserverPaused themselves for this.
+ * - attributeChangedCallbackSugar is removed. Use updatedAttributeSugar
+ *   (wired up in htmlelement.mjs's attributeChangedCallback) instead.
+ */
+
+const succuState = new WeakMap();
+
+export const withConnectSuccu = (Base) =>
+  class extends Base {
+    static morphTriggerSelector = '';
+
+    connectedCallback() {
+      if (!succuState.has(this)) {
+        succuState.set(this, {
+          rendered: false,
+          firstUpdatedCalled: false,
+        });
+      }
+      const state = succuState.get(this);
+
+      this._syncObservedAttributesToConfig();
+      this._armMorphObserver();
+
+      if (this.connectedCallbackSugarOnce) {
+        this.connectedCallbackSugarOnce();
+      }
+
+      if (this._shouldRenderOnConnect()) {
+        const wcParent = this._findWcParent();
+
+        const render = () => {
+          this._renderProtected();
+          state.rendered = true;
+
+          const event = new CustomEvent('wc:rendered', { bubbles: false });
+          this.dispatchEvent(event);
+
+          if (!state.firstUpdatedCalled) {
+            Promise.resolve().then(() => {
+              state.firstUpdatedCalled = true;
+              this.firstUpdatedSugar?.();
+            });
+          }
+        };
+
+        this.renderIfParent(wcParent, render);
+      }
+    }
+
+    /**
+     * Runs connectedCallbackSugar with the observer paused. Shared by both
+     * the initial-connect render and the morph-triggered re-render, so a
+     * component's own render mutation is never mistaken for an external
+     * morph by its own MutationObserver.
+     */
+    _renderProtected() {
+      this.withMorphObserverPaused(() => {
+        this.connectedCallbackSugar();
+      });
+    }
+
+    renderIfParent(parent = null, cb) {
+      if (!parent || !succuState.has(parent)) {
+        cb();
+        return;
+      }
+      const parentState = succuState.get(parent);
+      if (parentState.rendered) {
+        cb();
+        return;
+      }
+
+      const timeout = setTimeout(cb, 1000);
+      parent.addEventListener('wc:rendered', () => {
+        clearTimeout(timeout);
+        cb();
+      }, { once: true });
+    }
+
+    _findWcParent() {
+      let el = this.parentElement;
+      while (el) {
+        if (el.tagName?.includes('-')) {
+          if (el._internals || el._sugarRendered !== undefined) {
+            return el;
+          }
+          return null;
+        }
+        el = el.parentElement;
+      }
+      return null;
+    }
+
+    _syncObservedAttributesToConfig() {
+      for (const attr of this.constructor.observedAttributes ?? []) {
+        const val = this.getAttribute(attr);
+        if (val !== null) this._applyAttribute(attr, val);
+      }
+    }
+
+    _armMorphObserver() {
+      if (this._succuMo) return;
+      if (this.hasAttribute('morph-ignore')) return;
+
+      const hasExplicit = this.hasAttribute('morph-child') ||
+                          this.hasAttribute('morph-attribute') ||
+                          this.hasAttribute('morph-subtree');
+
+      this._morphObserveOptions = hasExplicit ? {
+        childList: this.hasAttribute('morph-child'),
+        attributes: this.hasAttribute('morph-attribute'),
+        subtree: this.hasAttribute('morph-subtree'),
+      } : {
+        childList: true,
+      };
+
+      this._succuMo = new MutationObserver((mutations) => {
+
+        if (this.hasAttribute('morph-debug')) {
+          console.group(`[succu-morph] ${this.tagName}${this.id ? '#' + this.id : ''}${this.getAttribute('label') ? `[label="${this.getAttribute('label')}"]` : ''}${this.getAttribute('title') ? `[title="${this.getAttribute('title')}"]` : ''}`);
+          console.log('parent:', this.parentElement?.tagName);
+          console.log('mutations:', mutations.map(m => ({
+            type: m.type,
+            added: Array.from(m.addedNodes).map(n => n.nodeName),
+            removed: Array.from(m.removedNodes).map(n => n.nodeName)
+          })));
+          console.log('hasRenderedShape:', this.hasRenderedShape());
+          console.log('shouldRenderOnMorph:', this._shouldRenderOnMorph());
+          setTimeout(() => console.log('innerHTML after:', this.innerHTML), 0);
+          console.groupEnd();
+        }
+
+        queueMicrotask(() => {
+          if (this._shouldRenderOnMorph()) {
+            this._renderProtected();
+            return;
+          }
+          if (this.hasRenderedShape() && this.morphedCallbackSugar) {
+            this.morphedCallbackSugar();
+            return;
+          }
+        });
+
+      });
+
+      this._succuMo.observe(this, this._morphObserveOptions);
+    }
+
+    _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;
+    }
+
+    withMorphObserverPaused(fn) {
+      this._succuMo?.disconnect();
+      try {
+        fn();
+      } finally {
+        if (this._morphObserveOptions) {
+          this._succuMo?.observe(this, this._morphObserveOptions);
+        }
+      }
+    }
+
+    disconnectedCallback() {
+      this._succuMo?.disconnect();
+      this._succuMo = null;
+    }
+
+  };

package/package.json

@@ -62,5 +62,5 @@
     "./aliases-register"
   ],
   "type": "module",
-  "version": "0.1.10"
+  "version": "0.1.12"
 }