@elenajs/core 1.0.0-rc.7 → 1.0.0

package/src/elena.js

@@ -13,7 +13,7 @@
  */
 
 import { setProps, getProps, getPropValue, syncAttribute } from "./common/props.js";
-import { defineElement, html, unsafeHTML, nothing } from "./common/utils.js";
+import { defineElement, html, unsafeHTML, nothing, warn, prefix } from "./common/utils.js";
 import { renderTemplate } from "./common/render.js";
 
 export { html, unsafeHTML, nothing };
@@ -40,7 +40,7 @@ function elementResolver(selector) {
  */
 
 /**
- * @typedef {{ text: string, element: HTMLElement | null, render(): void, willUpdate(): void, firstUpdated(): void, updated(): void, connectedCallback(): void, disconnectedCallback(): void }} ElenaInstanceMembers
+ * @typedef {{ text: string, element: HTMLElement | null, updateComplete: Promise<void>, render(): void, willUpdate(): void, firstUpdated(): void, updated(): void, requestUpdate(): void, connectedCallback(): void, disconnectedCallback(): void, adoptedCallback(): void, attributeChangedCallback(prop: string, oldValue: string | null, newValue: string | null): void }} ElenaInstanceMembers
  */
 
 /**
@@ -49,7 +49,7 @@ function elementResolver(selector) {
 
 /**
  * @typedef {(new (...args: any[]) => HTMLElement & ElenaInstanceMembers) & {
- *   define(): void,
+ *   define(registry?: CustomElementRegistry): void,
  *   readonly observedAttributes: string[],
  *   tagName?: string,
  *   props?: (string | ElenaPropObject)[],
@@ -57,11 +57,13 @@ function elementResolver(selector) {
  *   element?: string,
  *   shadow?: "open" | "closed",
  *   styles?: CSSStyleSheet | string | (CSSStyleSheet | string)[],
+ *   registry?: CustomElementRegistry,
  * }} ElenaElementConstructor
  */
 
 // Tracks which component classes have already been set up.
 const setupRegistry = new WeakSet();
+const hasOwn = (obj, key) => Object.prototype.hasOwnProperty.call(obj, key);
 
 /**
  * Creates an Elena component class by extending `superClass`.
@@ -90,8 +92,8 @@ export function Elena(superClass) {
      * Updates the matching prop and re-renders if needed.
      *
      * @param {string} prop
-     * @param {string} oldValue
-     * @param {string} newValue
+     * @param {string | null} oldValue
+     * @param {string | null} newValue
      */
     attributeChangedCallback(prop, oldValue, newValue) {
       super.attributeChangedCallback?.(prop, oldValue, newValue);
@@ -101,17 +103,29 @@ export function Elena(superClass) {
         return;
       }
 
-      // Set flag so the property setter skips redundant attribute reflection:
-      // the attribute is already at the new value, no need to set it again.
-      this._syncing = true;
-      getProps(this, prop, oldValue, newValue);
-      this._syncing = false;
+      if (oldValue === newValue) {
+        return;
+      }
 
-      // Re-render when attributes change (after initial render).
-      // Guard against re-entrant renders: if render() itself mutates an observed
-      // attribute, skip the recursive call to prevent an infinite loop.
-      if (this._hydrated && oldValue !== newValue && !this._isRendering) {
+      if (this._hydrated && !this._isRendering) {
+        // The attribute is already set and we just need the coerced
+        // prop value stored for the next render.
+        const current = this._props.get(prop);
+        const type = typeof current;
+        const coerced =
+          type === "string" ? (newValue ?? "") : getPropValue(type, newValue, "toProp");
+
+        if (coerced !== current) {
+          this._props.set(prop, coerced);
+        }
         this._safeRender();
+
+        // Runs pre-hydration or during render.
+        // Goes through the setter so _props is initialized correctly.
+      } else {
+        this._syncing = true;
+        getProps(this, prop, oldValue, newValue);
+        this._syncing = false;
       }
     }
 
@@ -136,8 +150,20 @@ export function Elena(superClass) {
       super.connectedCallback?.();
       this._setupStaticProps();
       this._captureClassFieldDefaults();
-      this._captureText();
+      if (!this._hydrated && this._text === undefined) {
+        this.text = this.textContent.trim();
+      }
       this._attachShadow();
+      this._root = this._shadow ?? this.shadowRoot ?? this;
+
+      this._runUpdate ??= () => {
+        try {
+          this._performUpdate();
+        } catch (e) {
+          console.error(prefix, e);
+        }
+      };
+
       this.willUpdate();
       this._applyRender();
       this._syncProps();
@@ -181,7 +207,7 @@ export function Elena(superClass) {
         }
 
         if (names.includes("text")) {
-          console.warn('░█ [ELENA]: "text" is reserved.');
+          warn('"text" is reserved.');
         }
 
         setProps(component.prototype, names, noRef);
@@ -193,7 +219,7 @@ export function Elena(superClass) {
 
       if (component._elenaEvents) {
         for (const e of component._elenaEvents) {
-          if (!Object.prototype.hasOwnProperty.call(component.prototype, e)) {
+          if (!hasOwn(component.prototype, e)) {
             component.prototype[e] = function (...args) {
               return this.element[e](...args);
             };
@@ -215,7 +241,7 @@ export function Elena(superClass) {
       this._syncing = true;
 
       for (const name of this.constructor._propNames) {
-        if (Object.prototype.hasOwnProperty.call(this, name)) {
+        if (hasOwn(this, name)) {
           const value = this[name];
           delete this[name];
           this[name] = value;
@@ -225,27 +251,6 @@ export function Elena(superClass) {
       this._syncing = false;
     }
 
-    /**
-     * Saves any text inside the element before the first render.
-     *
-     * @internal
-     */
-    _captureText() {
-      if (!this._hydrated && this._text === undefined) {
-        this.text = this.textContent.trim();
-      }
-    }
-
-    /**
-     * The root node to render into. Returns the shadow root when shadow mode
-     * is enabled, otherwise the host element itself.
-     *
-     * @type {ShadowRoot | HTMLElement}
-     */
-    get _renderRoot() {
-      return this._shadow ?? this.shadowRoot ?? this;
-    }
-
     /**
      * Attaches a shadow root and adopts styles on first connect.
      * Only runs when `static shadow` is set on the component class.
@@ -263,7 +268,11 @@ export function Elena(superClass) {
       // In that case skip attachShadow() but still adopt styles below.
       // Store the reference so closed shadow roots remain accessible.
       if (!this._shadow && !this.shadowRoot) {
-        this._shadow = this.attachShadow({ mode: component.shadow });
+        const options = { mode: component.shadow };
+        if (component.registry) {
+          options.customElementRegistry = component.registry;
+        }
+        this._shadow = this.attachShadow(options);
       }
 
       const shadowRoot = this._shadow ?? this.shadowRoot;
@@ -275,7 +284,7 @@ export function Elena(superClass) {
       // Normalize to array and cache converted CSSStyleSheet instances on the class.
       // Avoids re-parsing CSS strings on every element instance.
       if (!component._adoptedSheets) {
-        const stylesList = Array.isArray(component.styles) ? component.styles : [component.styles];
+        const stylesList = [component.styles].flat();
 
         component._adoptedSheets = stylesList.map(s => {
           if (typeof s === "string") {
@@ -297,22 +306,23 @@ export function Elena(superClass) {
      * @internal
      */
     _applyRender() {
+      const constructor = this.constructor;
+      const root = this._root;
       const result = this.render();
 
       if (result && result.strings) {
-        const root = this._renderRoot;
         const rebuilt = renderTemplate(root, result.strings, result.values);
 
         // Re-resolve element ref when the DOM was fully rebuilt.
-        // Fast-path text node patching leaves the DOM structure intact,
+        // patch() and morph() leave the DOM structure intact,
         // so the existing ref is still valid.
         if (rebuilt) {
           const oldElement = this.element;
-          this.element = this.constructor._resolver(root);
+          this.element = constructor._resolver(root);
 
           // Re-bind event listeners when the inner element was replaced.
           if (this._events && oldElement && this.element !== oldElement) {
-            const events = this.constructor._elenaEvents;
+            const events = constructor._elenaEvents;
 
             for (const e of events) {
               oldElement.removeEventListener(e, this);
@@ -324,12 +334,11 @@ export function Elena(superClass) {
 
       // Resolve inner element on first render
       if (!this.element) {
-        const root = this._renderRoot;
-        this.element = this.constructor._resolver(root);
+        this.element = constructor._resolver(root);
 
         if (!this.element) {
-          if (this.constructor.element) {
-            console.warn("░█ [ELENA]: Element not found.");
+          if (constructor.element) {
+            warn("Element not found.");
           }
           this.element = root.firstElementChild;
         }
@@ -373,7 +382,7 @@ export function Elena(superClass) {
 
       if (!this._events && events?.length) {
         if (!this.element) {
-          console.warn("░█ [ELENA]: Cannot add events.");
+          warn("Cannot add events.");
         } else {
           this._events = true;
 
@@ -438,6 +447,7 @@ export function Elena(superClass) {
      * events in Shadow DOM (change, submit, reset).
      * Composed bubbling events (click, input) pass through on their own.
      *
+     * @param {Event} event
      * @internal
      */
     handleEvent(event) {
@@ -445,7 +455,7 @@ export function Elena(superClass) {
         return;
       }
 
-      if (!event.bubbles || (!event.composed && this._renderRoot !== this)) {
+      if (!event.bubbles || (!event.composed && this._root !== this)) {
         /** @internal */
         this.dispatchEvent(new Event(event.type, { bubbles: event.bubbles }));
       }
@@ -475,12 +485,16 @@ export function Elena(superClass) {
      * Registers the component as a custom element using `static tagName`.
      * Call this on your component class after the class body is defined,
      * not on the Elena mixin itself.
+     *
+     * @param {CustomElementRegistry} [registry] - A scoped registry to register in.
+     *   When omitted, registers in the global `customElements` registry.
      */
-    static define() {
-      if (this.tagName) {
-        defineElement(this.tagName, this);
+    static define(registry) {
+      const tag = this.tagName;
+      if (tag) {
+        defineElement(tag, this, registry);
       } else {
-        console.warn("░█ [ELENA]: define() without a tagName.");
+        warn("define() without a tagName.");
       }
     }
 
@@ -496,16 +510,7 @@ export function Elena(superClass) {
       }
       if (!this._renderPending) {
         this._renderPending = true;
-        this._updateComplete = new Promise(resolve => {
-          this._resolveUpdate = resolve;
-        });
-        queueMicrotask(() => {
-          try {
-            this._performUpdate();
-          } catch (e) {
-            console.error("░█ [ELENA]:", e);
-          }
-        });
+        queueMicrotask(this._runUpdate);
       }
     }
 
@@ -530,7 +535,7 @@ export function Elena(superClass) {
         this.updated();
       } finally {
         this._updateComplete = null;
-        resolve();
+        resolve?.();
       }
     }
 
@@ -541,10 +546,15 @@ export function Elena(superClass) {
      * @type {Promise<void>}
      */
     get updateComplete() {
-      if (this._updateComplete) {
-        return this._updateComplete;
+      if (!this._renderPending) {
+        return Promise.resolve();
+      }
+      if (!this._updateComplete) {
+        this._updateComplete = new Promise(resolve => {
+          this._resolveUpdate = resolve;
+        });
       }
-      return Promise.resolve();
+      return this._updateComplete;
     }
 
     /**