@skirbi/sugar 0.1.11 → 0.1.12

package/Changes

@@ -1,5 +1,104 @@
 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

package/lib/index.mjs

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

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