@mintjamsinc/ichigojs 0.1.78 → 0.1.80

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,8 @@ class VSlotOutletDirective {
         slot.replaceWith(fragment);
         // Initial rendering
         this.#contentVNode.forceUpdate();
+        // Components in the slot content expand once it is in the document.
+        this.#contentVNode.expandComponents();
     }
     /**
      * Re-evaluates the slot props (component-side change) and pushes them into
@@ -9854,6 +9857,31 @@ class VNode {
      * remove the entire fragment atomically.
      */
     #fragmentRange;
+    /**
+     * 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 +9913,9 @@ class VNode {
             if (isComponent) {
                 element._ichigoHost = { vNode: this };
             }
+            else {
+                VNode.#warnIfUnknownCustomElement(this.#nodeName);
+            }
             // Initialize child virtual nodes
             this.#childVNodes = [];
             // Initialize directive manager
@@ -9943,6 +9974,37 @@ 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.
+     * A templatized node is skipped whole — it is a template source, and its
+     * clones expand when they are inserted.
+     */
+    expandComponents() {
+        if (this.#templatized) {
+            return;
+        }
+        if (this.#nodeType === Node.ELEMENT_NODE && IchigoElementRegistry.has(this.#nodeName)) {
+            const element = this.#node;
+            if (element._ichigoExpanded !== true) {
+                element._ichigoExpand?.();
+            }
+        }
+        this.#childVNodes?.forEach(child => child.expandComponents());
+    }
     /**
      * The application instance associated with this virtual node.
      */
@@ -10743,11 +10805,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,
@@ -10762,12 +10823,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.
@@ -11224,6 +11289,7 @@ class VForDirective {
                     vNode.fragmentRange = range;
                     newRenderedItems.push({ key, vNode });
                     vNode.forceUpdate();
+                    vNode.expandComponents();
                     prevNode = range.lastNode;
                     continue;
                 }
@@ -11238,6 +11304,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
@@ -14807,6 +14877,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
@@ -15371,6 +15445,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).
@@ -15422,13 +15509,6 @@ class IchigoElement extends HTMLElement {
      * belong to this component's VApplication and scope).
      */
     _ichigoExpanded = false;
-    /**
-     * Host context installed by the parent application's VNode when it
-     * compiles this element. Gives component-boundary features (e.g. scoped
-     * slot outlets) access to the parent scope. Undefined when the element is
-     * placed outside any ichigo application.
-     */
-    _ichigoHost;
     /**
      * The scoped slot templates captured from this element's children, keyed
      * by slot name ('default' for `v-slot` without a name). Read by
@@ -15437,20 +15517,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;
+        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
@@ -15466,13 +15568,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) ---
@@ -15787,6 +15891,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.