@mintjamsinc/ichigojs 0.1.79 → 0.1.81

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

@@ -16,6 +16,35 @@ 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.
+     * 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(): 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).
@@ -40,19 +53,6 @@ export declare class IchigoElement extends HTMLElement {
      * belong to this component's VApplication and scope).
      */
     _ichigoExpanded: boolean;
-    /**
-     * True when this element came from an enclosing component's template clone
-     * (marked by that component while it expands). Such an element connects
-     * while the enclosing component is attaching its template — before that
-     * component's VApplication exists — so it must wait to be compiled by the
-     * owning application before expanding itself (see connectedCallback guard
-     * 0a2 and {@link _ichigoTryExpand}).
-     *
-     * Declared with `declare` for the same reason as {@link _ichigoHost}: the
-     * mark is set before the element is upgraded, and a real class field would
-     * be re-defined as undefined by the upgrade.
-     */
-    _ichigoTemplateOwned?: boolean;
     /**
      * Host context installed by the parent application's VNode when it
      * compiles this element. Gives component-boundary features (e.g. scoped
@@ -76,18 +76,39 @@ 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;
-    disconnectedCallback(): void;
     /**
-     * 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).
+     * 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.
      */
-    _ichigoTryExpand(): void;
+    _ichigoExpand(): void;
+    disconnectedCallback(): void;
     /**
      * Called by the property setters generated by defineComponent().
      * Before mount: stores the value and schedules a mount microtask.

package/dist/types/ichigo/directives/VDirective.d.ts

@@ -88,6 +88,14 @@ export interface VDirective {
      * The element reference is still available at this point.
      */
     get onUnmounted(): (() => void) | undefined;
+    /**
+     * Expands the components in a subtree this directive rendered but that is
+     * not reachable through the VNode's children — the scoped slot content of
+     * a `<slot>` outlet, whose VNodes belong to the parent application.
+     * Called by VNode.expandComponents() when it walks this directive's node.
+     * Optional; most directives render nothing outside their own VNode tree.
+     */
+    expandComponents?(): void;
     /**
      * Cleans up any resources used by the directive.
      * This method is called when the directive is no longer needed.

package/dist/types/ichigo/directives/VSlotOutletDirective.d.ts

@@ -111,4 +111,8 @@ export declare class VSlotOutletDirective implements VDirective {
      * @inheritdoc
      */
     destroy(): void;
+    /**
+     * @inheritdoc
+     */
+    expandComponents(): void;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mintjamsinc/ichigojs",
-  "version": "0.1.79",
+  "version": "0.1.81",
   "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",