@mintjamsinc/ichigojs 0.1.79 → 0.1.81

package/dist/ichigo.esm.js

@@ -9218,8 +9218,9 @@ class VSlotOutletDirective {
             this.#scopeBindings.setLocal(this.#entry.scopeVar, this.#buildSlotProps());
         }
         // Clone the scoped template's content and create its VNode tree BEFORE
-        // inserting into the DOM, so components inside the slot content are
-        // compiled before their connectedCallback can expand them.
+        // inserting into the DOM, so its directives run against a subtree
+        // nothing else can observe yet. Components inside are expanded
+        // afterwards, once the content is in the document.
         // (Created through the parent application to keep the VNode import
         // type-only; a direct `new VNode` here would close a module cycle
         // VNode -> VDirectiveManager -> VSlotOutletDirective -> VNode.)
@@ -9238,6 +9239,17 @@ class VSlotOutletDirective {
         slot.replaceWith(fragment);
         // Initial rendering
         this.#contentVNode.forceUpdate();
+        // Components in the slot content expand once it is in the document:
+        // now, if the outlet is connected, or — when it renders inside a
+        // detached v-if / v-for clone — through expandComponents() below, when
+        // the directive that inserts the clone walks it.
+        this.#contentVNode.expandComponents();
+    }
+    /**
+     * @inheritdoc
+     */
+    expandComponents() {
+        this.#contentVNode?.expandComponents();
     }
     /**
      * Re-evaluates the slot props (component-side change) and pushes them into
@@ -9854,6 +9866,37 @@ class VNode {
      * remove the entire fragment atomically.
      */
     #fragmentRange;
+    /**
+     * Set by {@link destroy}. A destroyed clone stays in its parent's child
+     * list (v-if / v-for render new clones under the same parent), so walks
+     * over the children must skip it.
+     */
+    #destroyed = false;
+    /**
+     * Custom element tags already reported by
+     * {@link VNode.#warnIfUnknownCustomElement}.
+     */
+    static #warnedUnknownTags = new Set();
+    /**
+     * Warns about a hyphenated tag that no one has registered — a forgotten
+     * import, a missing defineComponent() call, or a typo in the tag name.
+     * Such an element is compiled as an ordinary element and renders its own
+     * children, which looks enough like a working page to cost an afternoon.
+     * Reported once per tag; third-party custom elements are recognised
+     * through the registry the browser keeps.
+     */
+    static #warnIfUnknownCustomElement(nodeName) {
+        const tag = nodeName.toLowerCase();
+        if (!tag.includes('-') || VNode.#warnedUnknownTags.has(tag)) {
+            return;
+        }
+        if (typeof customElements !== 'undefined' && customElements.get(tag)) {
+            return;
+        }
+        VNode.#warnedUnknownTags.add(tag);
+        console.warn(`[ichigo] <${tag}>: unknown custom element — nothing has registered this tag.`
+            + ' Did you forget to import its module or call defineComponent(), or is the tag misspelled?');
+    }
     /**
      * Creates an instance of the virtual node.
      * @param args The initialization arguments for the virtual node.
@@ -9885,6 +9928,9 @@ class VNode {
             if (isComponent) {
                 element._ichigoHost = { vNode: this };
             }
+            else {
+                VNode.#warnIfUnknownCustomElement(this.#nodeName);
+            }
             // Initialize child virtual nodes
             this.#childVNodes = [];
             // Initialize directive manager
@@ -9918,16 +9964,6 @@ class VNode {
                     });
                 }
             }
-            // A component element this application compiled but that has not
-            // expanded yet — it deferred to us because an ancestor component
-            // was attaching its template, or its <template> was not loaded when
-            // it connected — is expanded now: the host context is installed,
-            // the directives above delivered the prop values, and any authored
-            // slot content was compiled in this scope. A template source
-            // (v-if / v-for) is left alone; its clones expand on insertion.
-            if (isComponent && !this.#templatized && !isExpandedComponent) {
-                element._ichigoTryExpand?.();
-            }
             // After creating child nodes, call onMounted for directives that do not templatize
             if (!this.#templatized) {
                 // animation frame to ensure DOM is updated
@@ -9953,6 +9989,58 @@ class VNode {
         // Register this node as a dependent of the parent node, if any
         this.#closers = this.#parentVNode?.addDependent(this);
     }
+    /**
+     * Expands the component elements this application compiled in this subtree
+     * but has not expanded yet, parents before their children.
+     *
+     * This is the ONLY thing that expands a component. It is deliberately a
+     * separate step from compilation rather than a call at the end of the
+     * constructor: a v-if / v-for clone is compiled while it is still detached
+     * (so that its directives run before anything can observe a half-built
+     * subtree), and expanding a detached element would mount a component
+     * application outside the document. The callers therefore compile, insert,
+     * and then call this — see VApplication.mount, VConditionalDirective,
+     * VForDirective and VSlotOutletDirective.
+     *
+     * Walking only {@link childVNodes} keeps the traversal inside this
+     * application: the internals of an expanded component were never compiled
+     * here, so they are not reachable and are left to their own application.
+     * The one exception is content a directive rendered outside its own
+     * children — scoped slot content — reached through
+     * {@link VDirective.expandComponents}.
+     *
+     * Only connected elements are expanded. v-if / v-for call this right after
+     * inserting a clone, but when that clone sits inside another clone that is
+     * still detached (nested directives, or slot content rendered by an outlet
+     * inside a component's v-if), the insertion is not into the document yet;
+     * the outer inserter's walk reaches the same nodes once it is. A
+     * templatized node (a v-if / v-for source) is not expanded itself, but its
+     * rendered clones are its children and are walked.
+     */
+    expandComponents() {
+        if (this.#destroyed) {
+            return;
+        }
+        // Expand only a connected element. A subtree compiled and inserted
+        // into a still-detached clone (a v-if / v-for nested in another
+        // clone, or in scoped slot content rendered inside one) is reached
+        // again by the walk of whoever inserts that clone into the document —
+        // and by then its elements are upgraded and ready to expand.
+        // A templatized node is a template source: never expanded itself,
+        // but its rendered clones are its child VNodes and are walked below.
+        if (!this.#templatized && this.#nodeType === Node.ELEMENT_NODE && IchigoElementRegistry.has(this.#nodeName)) {
+            const element = this.#node;
+            if (element._ichigoExpanded !== true && element.isConnected) {
+                element._ichigoExpand?.();
+            }
+        }
+        // Subtrees a directive rendered outside this VNode's children (the
+        // scoped slot content of a <slot> outlet) are expanded here too: this
+        // walk runs once the subtree is in the document, which the outlet
+        // cannot know when it renders inside a detached v-if / v-for clone.
+        this.#directiveManager?.directives?.forEach(d => d.expandComponents?.());
+        this.#childVNodes?.forEach(child => child.expandComponents());
+    }
     /**
      * The application instance associated with this virtual node.
      */
@@ -10360,6 +10448,7 @@ class VNode {
      * 6. Call onUnmounted lifecycle hooks
      */
     destroy() {
+        this.#destroyed = true;
         // If no directive requires template preservation, call onUnmount for directives that do not templatize
         if (!this.#templatized) {
             this.#directiveManager?.directives?.forEach(d => {
@@ -10753,11 +10842,10 @@ class VConditionalDirective {
         }
         // Clone the original node and create a new VNode for it
         const clone = this.#cloneNode();
-        // Create a new VNode for the cloned element BEFORE inserting into DOM.
-        // This prevents custom elements (Web Components) from having their
-        // connectedCallback fire before VNode processes their children, which
-        // would cause the parent VApplication to incorrectly adopt the custom
-        // element's internal template content as its own VNode tree.
+        // Compile the clone BEFORE inserting it, so its directives run against a
+        // subtree nothing else can observe yet (v-if inside creates anchors and
+        // detaches template sources). Components inside are expanded afterwards,
+        // once the clone is in the document — see expandComponents() below.
         // Pass the current bindings to ensure loop variables from v-for are available
         const vNode = new VNode({
             node: clone,
@@ -10772,12 +10860,16 @@ class VConditionalDirective {
             vNode.fragmentRange = VFragmentRange.insert(anchorParent, nextSibling, 'vif-fragment', clone);
             this.#renderedVNode = vNode;
             this.#renderedVNode.forceUpdate();
+            this.#renderedVNode.expandComponents();
             return;
         }
         const nodeToInsert = vNode.anchorNode || clone;
         anchorParent?.insertBefore(nodeToInsert, nextSibling);
         this.#renderedVNode = vNode;
         this.#renderedVNode.forceUpdate();
+        // Components expand once the clone is in the document and its bindings
+        // have been applied, so they mount connected and with their props set.
+        this.#renderedVNode.expandComponents();
     }
     /**
      * Removes the node from the DOM.
@@ -11234,6 +11326,7 @@ class VForDirective {
                     vNode.fragmentRange = range;
                     newRenderedItems.push({ key, vNode });
                     vNode.forceUpdate();
+                    vNode.expandComponents();
                     prevNode = range.lastNode;
                     continue;
                 }
@@ -11248,6 +11341,10 @@ class VForDirective {
                 }
                 newRenderedItems.push({ key, vNode });
                 vNode.forceUpdate();
+                // Components expand once the clone is in the document and its
+                // bindings have been applied, so they mount connected and with
+                // their props set.
+                vNode.expandComponents();
             }
             else {
                 // Reuse existing item
@@ -14817,6 +14914,10 @@ class VApplication {
         });
         // Initial rendering
         this.#vNode.update();
+        // Expand the components in the tree. Last, so every component element
+        // has been compiled and has had its prop values delivered before its
+        // template is cloned in. See VNode.expandComponents.
+        this.#vNode.expandComponents();
         // Remove v-cloak attributes after mounting
         // v-cloak is used to hide un-compiled template until the app is ready
         // Usage: Add CSS rule "[v-cloak] { display: none; }" to hide elements with v-cloak
@@ -15381,6 +15482,19 @@ class VDOM {
 /**
  * Base class for ichigo.js-backed Web Components (Light DOM, no Shadow DOM).
  *
+ * Expansion — cloning the template into this element — is driven by the
+ * application that owns the element, not by connectedCallback: VNode compiles
+ * the element first (installing the host context, delivering the prop values
+ * and compiling the authored slot content in the owner's scope) and only then
+ * calls {@link _ichigoExpand}. That leaves connectedCallback a single job,
+ * re-attachment; see there.
+ *
+ * The component's <template> must be present in the document, and
+ * defineComponent() must have run, before the owning application is mounted.
+ * That is the application's responsibility. A missing template is reported as
+ * a warning and the element is left empty — it is never silently retried,
+ * because an app that renders anyway is an app whose bug cannot be found.
+ *
  * Mount timing:
  *  - If the component declares no props, the VApplication is mounted synchronously
  *    at the end of connectedCallback (the template is known, no props to wait for).
@@ -15440,38 +15554,42 @@ class IchigoElement extends HTMLElement {
     get _ichigoScopedSlots() {
         return this.#slotCache?.scopedSlots;
     }
+    /**
+     * Handles RE-attachment, and nothing else.
+     *
+     * A first connection is not what expands this element: the owning
+     * application does that from {@link _ichigoExpand} once it has compiled the
+     * element. So a connection event on a not-yet-expanded element means the
+     * owner has not reached it yet, and the right thing to do is nothing. That
+     * covers every case the old guards enumerated one by one — a v-if / v-for
+     * template source, an element inside an enclosing component's template
+     * clone, a clone inserted before its directive expands it.
+     *
+     * An expanded element whose mount root has been torn down, on the other
+     * hand, was disconnected and is now coming back: v-for reorders relocate
+     * the host element, which disconnects and reconnects it. Its children are
+     * the previous expansion, not authored slot content, so it re-expands from
+     * the cached slot nodes. Testing the mount root rather than the expansion
+     * flag alone keeps this from firing on an element that was expanded while
+     * detached and is being inserted for the first time.
+     */
     connectedCallback() {
-        // --- 0a. Guard: do not expand a template-source element ---
-        // An element still carrying a templatizing directive attribute (v-if
-        // family / v-for) is a template source: the owning application clones it
-        // and inserts the clones (whose directive attributes are stripped during
-        // clone compilation, so the clones expand normally). Expanding the source
-        // here would bake the expansion into every clone, and the clone's
-        // internals would then be compiled in the parent scope.
-        if (this.hasAttribute(StandardDirectiveName.V_IF) ||
-            this.hasAttribute(StandardDirectiveName.V_ELSE_IF) ||
-            this.hasAttribute(StandardDirectiveName.V_ELSE) ||
-            this.hasAttribute(StandardDirectiveName.V_FOR)) {
-            return;
-        }
-        // --- 0a2. Guard: wait to be compiled by the owning application ---
-        // This element came from an enclosing component's template clone and no
-        // application has compiled it yet: the enclosing component's appendChild
-        // connected it before that component's VApplication existed. Expanding
-        // now would capture the slot content and mount before the owning
-        // application installs the host context (_ichigoHost) and delivers the
-        // prop values — scoped slot outlets would find no parent scope and
-        // silently fall back to their default content. The owning application
-        // expands this element while it compiles it (VNode ->
-        // _ichigoTryExpand()), by which time both are in place.
-        //
-        // Only template-owned elements defer: authored slot content placed
-        // inside a component by an application is not part of the template, so
-        // it keeps expanding immediately (and is redistributed by the enclosing
-        // component on every re-expansion).
-        if (this._ichigoTemplateOwned === true && !this._ichigoHost) {
-            return;
+        if (this._ichigoExpanded && !this.#mountRoot) {
+            this._ichigoExpand();
         }
+    }
+    /**
+     * Expands this element's template. Called by the application that owns the
+     * element, right after it compiled it (VNode.expandComponents): the host
+     * context is installed, the prop bindings have delivered their values and
+     * the authored slot content has been compiled in the owner's scope, so the
+     * capture below sees owner-compiled nodes and the component's own
+     * application starts with its props already in hand.
+     *
+     * Also called by {@link connectedCallback} to rebuild the expansion after a
+     * move.
+     */
+    _ichigoExpand() {
         // --- 0b. Reclaim prop values assigned before upgrade ---
         // A plain property set on the instance (e.g. by a binding delivered
         // while the element was detached or not yet upgraded) is an own data
@@ -15487,13 +15605,15 @@ class IchigoElement extends HTMLElement {
                 this[prop] = value;
             }
         }
-        // --- 0c. Guard: skip if template not yet loaded ---
-        // customElements.define() may run before loadComponent() completes (e.g. when
-        // dynamic imports are inlined by the bundler). The static placeholder element
-        // in the HTML will be removed and replaced by v-for once the template is ready,
-        // so it is safe to do nothing here.
+        // --- 0c. Resolve the template ---
+        // Having the <template> in the document by now is the application's
+        // contract (see the class doc). Report the breach and leave the element
+        // empty: rendering something plausible here would hide the bug at the
+        // one moment it is still cheap to find.
         const templateEl = document.querySelector(ctor._template);
         if (!templateEl || !(templateEl instanceof HTMLTemplateElement)) {
+            IchigoElement.#warnOncePerTag(this.tagName, `template '${ctor._template}' was not found in the document. `
+                + 'Inject the <template> and call defineComponent() before mounting the application.');
             return;
         }
         // --- 1. Capture slot content (first connection only) ---
@@ -15545,18 +15665,6 @@ class IchigoElement extends HTMLElement {
         // --- 2. Clone the component template ---
         const fragment = templateEl.content.cloneNode(true);
         const root = this.#findRootElement(fragment);
-        // Mark the component elements the template brought in, so they let this
-        // component's application compile them before they expand (guard 0a2).
-        // Marked before slot distribution, so authored slot content — which is
-        // not part of the template — keeps expanding under the application that
-        // authored it. Elements inside a nested <template> are not marked: they
-        // are inert until a directive clones them, and the clone is compiled
-        // before it is inserted.
-        for (const element of Array.from(fragment.querySelectorAll('*'))) {
-            if (IchigoElementRegistry.has(element.tagName)) {
-                element._ichigoTemplateOwned = true;
-            }
-        }
         // --- 3. Distribute named slot content ---
         for (const [name, nodes] of namedNodes) {
             const slot = root.querySelector(`slot[name="${name}"]`);
@@ -15594,21 +15702,6 @@ class IchigoElement extends HTMLElement {
             this.#app = undefined;
         }
     }
-    /**
-     * Expands this element's template on behalf of the application that owns
-     * it. Called by VNode right after it compiled this element — the host
-     * context is installed and the prop bindings have delivered their values,
-     * so a component that deferred its expansion (guard 0a2, or a template
-     * that was not loaded when it connected) can now expand in the right
-     * order. A no-op when the element is already expanded or not connected
-     * (a template-source clone expands when it is inserted).
-     */
-    _ichigoTryExpand() {
-        if (this._ichigoExpanded || !this.isConnected) {
-            return;
-        }
-        this.connectedCallback();
-    }
     /**
      * Called by the property setters generated by defineComponent().
      * Before mount: stores the value and schedules a mount microtask.
@@ -15835,6 +15928,23 @@ class IchigoElement extends HTMLElement {
     #warn(message) {
         console.warn(`[ichigo] <${this.tagName.toLowerCase()}>: ${message}`);
     }
+    /**
+     * Tags already reported by {@link #warnOncePerTag}.
+     */
+    static #warnedTags = new Set();
+    /**
+     * Reports a per-component-type problem once. A missing template breaks
+     * every instance, and a v-for over a hundred rows would otherwise print a
+     * hundred identical lines and bury the first one.
+     */
+    static #warnOncePerTag(tagName, message) {
+        const tag = tagName.toLowerCase();
+        if (IchigoElement.#warnedTags.has(tag)) {
+            return;
+        }
+        IchigoElement.#warnedTags.add(tag);
+        console.warn(`[ichigo] <${tag}>: ${message}`);
+    }
 }
 
 // Copyright (c) 2025 MintJams Inc. Licensed under MIT License.