@mintjamsinc/ichigojs 0.1.79 → 0.1.81

package/README.md

@@ -957,6 +957,18 @@ defineComponent('my-list', {
 </my-list>
 ```
 
+> **Ordering:** a component's `<template>` must be in the document, and
+> `defineComponent()` must have run, before the application that uses the
+> component is mounted. The application expands a component while it compiles
+> it — after installing the host context, delivering the prop values and
+> compiling the projected slot content in the parent scope — so a component
+> compiled without its template is reported as a console warning and left
+> empty. It is never retried: an app that renders anyway is an app whose bug
+> cannot be found. A hyphenated tag that nothing has registered (a forgotten
+> import, a typo) is reported the same way. Components therefore have to live
+> inside a mounted application; one placed outside any application is never
+> expanded.
+
 **Props:**
 
 - Declared via the `props` array, or as a record with per-prop options:

package/dist/ichigo.cjs

@@ -9224,8 +9224,9 @@
                 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.)
@@ -9244,6 +9245,17 @@
             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
@@ -9860,6 +9872,37 @@
          * 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.
@@ -9891,6 +9934,9 @@
                 if (isComponent) {
                     element._ichigoHost = { vNode: this };
                 }
+                else {
+                    VNode.#warnIfUnknownCustomElement(this.#nodeName);
+                }
                 // Initialize child virtual nodes
                 this.#childVNodes = [];
                 // Initialize directive manager
@@ -9924,16 +9970,6 @@
                         });
                     }
                 }
-                // 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
@@ -9959,6 +9995,58 @@
             // 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.
          */
@@ -10366,6 +10454,7 @@
          * 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 => {
@@ -10759,11 +10848,10 @@
             }
             // 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,
@@ -10778,12 +10866,16 @@
                 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.
@@ -11240,6 +11332,7 @@
                         vNode.fragmentRange = range;
                         newRenderedItems.push({ key, vNode });
                         vNode.forceUpdate();
+                        vNode.expandComponents();
                         prevNode = range.lastNode;
                         continue;
                     }
@@ -11254,6 +11347,10 @@
                     }
                     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
@@ -14823,6 +14920,10 @@
             });
             // 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
@@ -15387,6 +15488,19 @@
     /**
      * 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).
@@ -15446,38 +15560,42 @@
         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
@@ -15493,13 +15611,15 @@
                     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) ---
@@ -15551,18 +15671,6 @@
             // --- 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}"]`);
@@ -15600,21 +15708,6 @@
                 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.
@@ -15841,6 +15934,23 @@
         #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.