@skirbi/sugar 0.1.4 → 0.1.6

package/Changes

@@ -1,5 +1,26 @@
 Revision history for @skirbi/sugar
 
+0.1.6       2026-06-08 01:05:36Z
+
+  * Add attributeChangedCallback hook system
+    Extend attributeChangedCallback with a declarative hook system in
+    attributeDefs. When an observed attribute changes and the component
+    has a rendered shape, sugar automatically updates the DOM:
+
+      Convention: attribute 'foo' maps to [semtic-foo] textContent
+      String hook: CSS selector target, updates textContent
+      Function hook: full control, called with (el, newValue, oldValue)
+      Escape hatch: attributeChangedCallbackSugar(name, old, new)
+
+    Requires renderGuardSelector to be set. Hooks only fire when the
+    component has already rendered. This makes renderGuardSelector
+    effectively mandatory for components that want reactive attribute
+    updates.
+
+0.1.5       2026-06-06 18:09:56Z
+
+  * Now actually do it.. pls send coffee
+
 0.1.4       2026-06-06 16:41:57Z
 
   * Semtic already had this, but sugar in itself also has side-effects.

package/README.md

@@ -20,6 +20,8 @@ It provides:
 You can create Web Components like so:
 
 ```javascript
+import { HTMLElementSugar } from '@skirbi/sugar';
+
 class MyNewElement extends HTMLElementSugar {
   static tag = 'my-new-element';
   static attributeDefs = {
@@ -27,20 +29,21 @@ class MyNewElement extends HTMLElementSugar {
     bar: { parser: parseBoolean },
   };
 }
+MyNewElement.register();
 ```
 
 You can also create aliases:
 
 ```javascript
-TrackItem.alias('some-song', { type: 'song' });
-YourBook.alias('a-book');
+import { registerDevAlias } from '@skirbi/sugar';
+registerDevAlias('some-song', 'track-item', { type: 'song' });
+registerDevAlias('a-book', 'your-book');
 ```
 
 And to register them:
 
 ```javascript
-TrackItem.register();
-YourBook.register();
+MyNewElement.register();
 ```
 
 ## Observable patterns
@@ -288,21 +291,21 @@ HTMLElementSugarSelect extends HTMLElementSugarInput and provides a
 structured way to author `<select>`-based components.
 
 It supports:
-* Static option lists (via JSON)
-* Remote option loading (via endpoint)
-* Flexible data mapping via jpath
-* Label/value templates
-* Optional search input
-* Attribute forwarding to the underlying `<select>`
+- Static option lists (via JSON)
+- Remote option loading (via endpoint)
+- Flexible data mapping via jpath
+- Label/value templates
+- Optional search input
+- Attribute forwarding to the underlying `<select>`
 
 It always renders a real `<select>` in the light DOM.
 
 ### Contract
 
 A subclass must:
-* Extend HTMLElementSugarSelect
-* Render exactly one `<select wc-control>`
-* Optionally include a search input if searchable is enabled
+- Extend HTMLElementSugarSelect
+- Render exactly one `<select wc-control>`
+- Optionally include a search input if searchable is enabled
 
 Example:
 
@@ -336,11 +339,11 @@ You may provide options via the options attribute as a JSON array:
 ### Mapping Options
 
 Data mapping is controlled via:
-* `jpath`: path to the array in a nested JSON response
-* `jpath-label`: path for the option label
-* `jpath-value`: path for the option value
-* `jpath-label-template`: template string for label
-* `jpath-value-template`: template string for value
+- `jpath`: path to the array in a nested JSON response
+- `jpath-label`: path for the option label
+- `jpath-value`: path for the option value
+- `jpath-label-template`: template string for label
+- `jpath-value-template`: template string for value
 
 Templates take precedence over path mappings.
 
@@ -375,53 +378,77 @@ Options can be loaded from a remote endpoint:
 ```
 
 Behavior:
-* Fetches JSON from endpoint
-* Adds search query via param
-* Applies mapping rules
-* Replaces options on each fetch
+- Fetches JSON from endpoint
+- Adds search query via param
+- Applies mapping rules
+- Replaces options on each fetch
 
 If `searchable` is enabled:
-* A search input is rendered
-* Input is debounced
-* Fetch is triggered after min-chars is reached
-* By default, a remote endpoint triggers an initial fetch with an empty query
-  on connect. If `nosearch-initial` is enabled this behavior is negated.
-
-
-* No initial searches are
+- A search input is rendered
+- Input is debounced
+- Fetch is triggered after min-chars is reached
+- By default, a remote endpoint triggers an initial fetch with an empty query
+  on connect. If `nosearch-initial` is enabled this behavior is negated and no
+  initial searches are executed.
 
 ### Search Behavior (Static Mode)
 
 When using static options, enabling searchable:
-* Filters `<option>` elements in place
-* Uses case-insensitive substring matching
-* Does not modify underlying data
+- Filters `<option>` elements in place
+- Uses case-insensitive substring matching
+- Does not modify underlying data
 
 ### Value Handling
 
 The value attribute behaves consistently with `HTMLElementSugarInput`:
-* Initial value is applied after options render
-* With data-sync, updates are mirrored to the `<select>` element
-* Native input and change events are re-emitted from the host
+- Initial value is applied after options render
+- With data-sync, updates are mirrored to the `<select>` element
+- Native input and change events are re-emitted from the host
 
 ### Framework Compatibility
 
 Because it renders a real `<select>` in the light DOM, it works naturally with:
-* Livewire (`wire:*`)
-* Alpine (`x-*`)
-* HTMX (`hx-*`)
-* `aria-*`
-* `data-*`
+- Livewire (`wire:*`)
+- Alpine (`x-*`)
+- HTMX (`hx-*`)
+- `aria-*`
+- `data-*`
 
 Attributes not defined in attributeDefs are forwarded to the `<select>`
 element.
 
+#### Livewire
+
+For Livewire applications using Sugar components, import the optional
+Livewire integration:
+
+```js
+import '@skirbi/sugar/livewire';
+```
+
+This fixes a fundamental incompatibility between Livewire's morph algorithm
+and Web Components. Livewire compares its authored HTML against an already
+rendered DOM — structurally different trees cause cascade disconnects,
+reconnects, and focus loss on every update.
+
+The integration hydrates Livewire's new HTML in a staging element before
+morphing starts, so Alpine compares two fully rendered trees instead of
+authored vs rendered. No cascade, no focus loss.
+
+Import it before registering your components:
+
+```js
+import '@skirbi/sugar/livewire';
+import '@skirbi/semtic/register-semtic';
+```
+
 ### Why This Works
-* No shadow DOM
-* No custom dropdown UI
-* No CSS lock-in
-* Real `<option>` elements
-* Progressive enhancement friendly
+
+- No shadow DOM
+- No custom dropdown UI
+- No CSS lock-in
+- Real `<option>` elements
+- Progressive enhancement friendly
 
 ## Code of Conduct
 

package/lib/htmlelement.mjs

@@ -347,11 +347,31 @@ export class HTMLElementSugar extends HTMLElement {
   /**
    * Called when an observed attribute changes.
    * @param {string} name - The attribute name
-   * @param {string|null} _oldVal - Previous value (unused)
+   * @param {string|null} oldVal - Previous value (unused)
    * @param {string|null} newVal - New value
    */
-  attributeChangedCallback(name, _oldVal, newVal) {
+  attributeChangedCallback(name, oldVal, newVal) {
     this._applyAttribute(name, newVal);
+
+    if (!this.hasRenderedShape?.()) return;
+
+    const def = this.constructor.attributeDefs?.[name];
+
+    if (def?.hook) {
+      if (typeof def.hook === 'function') {
+        def.hook(this, newVal, oldVal);
+      } else if (typeof def.hook === 'string') {
+        const el = this.querySelector(def.hook);
+        if (el) el.textContent = newVal ?? '';
+      }
+    } else {
+      const el = this.querySelector(`[semtic-${name}]`);
+      if (el) el.textContent = newVal ?? '';
+    }
+
+    if (this.attributeChangedCallbackSugar) {
+      this.attributeChangedCallbackSugar(name, oldVal, newVal);
+    }
   }
 
   /**

package/lib/index.mjs

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

package/package.json

@@ -51,7 +51,7 @@
     "release": "rzil release",
     "test": "tap"
   },
-  "sideEffects": false,
+  "sideEffects": true,
   "type": "module",
-  "version": "0.1.4"
+  "version": "0.1.6"
 }