@mintjamsinc/ichigojs 0.1.78 → 0.1.80

package/dist/types/ichigo/VNode.d.ts

@@ -16,6 +16,26 @@ export declare class VNode {
      * @param args The initialization arguments for the virtual node.
      */
     constructor(args: VNodeInit);
+    /**
+     * 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(): void;
     /**
      * The application instance associated with this virtual node.
      */

package/dist/types/ichigo/components/IchigoElement.d.ts

@@ -14,6 +14,19 @@ export interface ScopedSlotEntry {
 /**
  * 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).
@@ -45,6 +58,14 @@ export declare class IchigoElement extends HTMLElement {
      * 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.
+     *
+     * Declared with `declare` on purpose: the application installs it BEFORE
+     * the element is upgraded whenever the element comes from a `<template>`
+     * (v-if / v-for on a `<template>` clones `content`, whose owner document
+     * has no browsing context, so custom elements there stay uncustomized
+     * until the clone is inserted). A real class field would be re-defined as
+     * undefined by the upgrade — erasing the host context and leaving scoped
+     * slot outlets without a parent scope.
      */
     _ichigoHost?: {
         vNode: VNode;
@@ -55,7 +76,38 @@ export declare class IchigoElement extends HTMLElement {
      * VSlotOutletDirective when the component template renders a `<slot>`.
      */
     get _ichigoScopedSlots(): Map<string, ScopedSlotEntry> | undefined;
+    /**
+     * 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(): void;
+    /**
+     * 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(): void;
     disconnectedCallback(): void;
     /**
      * Called by the property setters generated by defineComponent().

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mintjamsinc/ichigojs",
-  "version": "0.1.78",
+  "version": "0.1.80",
   "description": "ichigo.js - Simple and intuitive reactive framework. Lightweight, fast, and user-friendly virtual DOM library",
   "main": "./dist/ichigo.cjs",
   "module": "./dist/ichigo.esm.js",