@jqhtml/core 2.3.71 → 2.3.72

package/dist/jqhtml-core.esm.js

@@ -1,5 +1,5 @@
 /**
- * JQHTML Core v2.3.71
+ * JQHTML Core v2.3.72
  * (c) 2025 JQHTML Team
  * Released under the MIT License
  */
@@ -219,12 +219,17 @@ class LifecycleManager {
         return LifecycleManager.instance;
     }
     constructor() {
-        this.active_components = new Set();
-        // No automatic cleanup on DOM removal - components stop explicitly via:
-        // 1. Parent component re-render (calls .empty() which stops children)
-        // 2. Manual .empty(), .html(), .text() calls (overridden to stop children)
+        // Components stop explicitly via:
+        // 1. Parent component re-render (stops descendants before clearing innerHTML)
+        // 2. Any jQuery removal that reaches jQuery.cleanData (.remove(), .empty(),
+        //    .html(x), .text(x), .replaceWith(), .replaceAll()) - hooked in jquery-plugin.ts
         // 3. Explicit .stop() call
-        // This allows components to be moved in DOM without lifecycle interruption
+        // Native DOM removal is NOT observed for stop; 'detach' (dom-attachment.ts) is the
+        // signal for that. Moving a component within the document never stops it.
+        //
+        // There is deliberately no registry of live components here. The DOM (via
+        // element.data('_component')) is the only owner; a registry would pin every
+        // component that left the document without being stopped.
     }
     /**
      * Boot a component - run its full lifecycle
@@ -235,7 +240,6 @@ class LifecycleManager {
      * - _load_render_only: on_create + render + on_load + re-render. No on_render, no on_loaded, no on_ready.
      */
     async boot_component(component) {
-        this.active_components.add(component);
         try {
             // Create phase - SYNCHRONOUS, runs BEFORE first render
             component.create();
@@ -396,12 +400,6 @@ class LifecycleManager {
             }
         }
     }
-    /**
-     * Unregister a component (called on destroy)
-     */
-    unregister_component(component) {
-        this.active_components.delete(component);
-    }
 }
 
 /**
@@ -1620,7 +1618,7 @@ function serialize_for_cache_key(value) {
 const class_registry = Object.create(null);
 // Markers for serialized class instances (unique to avoid collisions with user data)
 // Replaced at build time by rollup (see rollup.config.js).
-const CORE_VERSION = '2.3.71';
+const CORE_VERSION = '2.3.72';
 const CLASS_MARKER = '__jqhtml_class__';
 const PROPS_MARKER = '__jqhtml_props__';
 /**
@@ -3181,6 +3179,85 @@ async function execute_on_load_detached(component, dedup_key = null) {
     };
 }
 
+/**
+ * JQHTML DOM Attachment Tracking
+ *
+ * Backs the component 'attach' / 'detach' lifecycle events.
+ *
+ * One document-level MutationObserver (childList + subtree) is installed the first
+ * time any component expresses interest in attachment, and disconnected when the
+ * last interested component is stopped or collected. The observer never inspects
+ * mutation records: it is only a "the tree changed" tick. On each batch it walks
+ * the tracked components and asks each to compare its root's isConnected against
+ * its own recorded attachment state (Jqhtml_Component._attachment_check()). Cost is
+ * O(tracked components) per mutation batch, independent of how much of the page
+ * changed, and zero when nothing has opted in.
+ *
+ * Because MutationObserver delivers per microtask, a node moved synchronously
+ * (remove + insert in one task, e.g. appendTo) never shows a transition. Only a
+ * component whose root is actually off-document when the batch flushes is detached.
+ *
+ * Tracked components are held by WeakRef. A component that is removed from the
+ * document natively (never stopped) and then dropped by everything else is therefore
+ * collectable: the tracker pins nothing. Dead refs are pruned on the next batch.
+ */
+const tracked = new Set();
+const ref_of = new WeakMap();
+let observer = null;
+function on_mutation() {
+    for (const ref of tracked) {
+        const component = ref.deref();
+        if (!component || component._stopped) {
+            tracked.delete(ref);
+            continue;
+        }
+        component._attachment_check();
+    }
+    if (tracked.size === 0)
+        disconnect();
+}
+function connect() {
+    if (observer !== null)
+        return;
+    if (typeof MutationObserver === 'undefined' || typeof document === 'undefined')
+        return;
+    observer = new MutationObserver(on_mutation);
+    observer.observe(document.documentElement, { childList: true, subtree: true });
+}
+function disconnect() {
+    if (observer === null)
+        return;
+    observer.disconnect();
+    observer = null;
+}
+/** Start watching a component's root for attach/detach transitions. Idempotent. */
+function track_attachment(component) {
+    if (ref_of.has(component))
+        return;
+    const ref = new WeakRef(component);
+    ref_of.set(component, ref);
+    tracked.add(ref);
+    connect();
+}
+/** Stop watching a component (called from _stop()). Idempotent. */
+function untrack_attachment(component) {
+    const ref = ref_of.get(component);
+    if (!ref)
+        return;
+    ref_of.delete(component);
+    tracked.delete(ref);
+    if (tracked.size === 0)
+        disconnect();
+}
+/** Number of components currently tracked (diagnostics / tests). */
+function tracked_attachment_count() {
+    return tracked.size;
+}
+/** Whether the document observer is currently installed (diagnostics / tests). */
+function attachment_observer_active() {
+    return observer !== null;
+}
+
 /**
  * JQHTML Component Cache Integration
  *
@@ -4089,6 +4166,12 @@ class Jqhtml_Component {
         this.__load_gates = []; // Pending gates (cleared once the first load begins)
         this.__first_load_started = false; // Latch: true once the first load phase begins (enforces one-shot + throw-after)
         this.__gate_resume = null; // Resolver to release an in-progress gate wait early (reload/refresh/stop)
+        // DOM attachment state machine - see _attachment_check() / dom-attachment.ts.
+        // _attached is the component's OWN belief about whether it is in the document;
+        // it flips at most once per direction, and 'attach' / 'detach' fire only on a flip.
+        this._attached = false;
+        this._attachment_checked = false; // First check has run (after the first 'ready' dispatch)
+        this._attachment_tracking = false; // Something is interested: on_attach/on_detach overridden, or .on('attach'|'detach')
         // Detect custom on_load() override immediately
         // Prototype chain is set up before constructor runs, so this.on_load
         // correctly resolves to child class override if one exists
@@ -4162,6 +4245,12 @@ class Jqhtml_Component {
         // Initialize this.state as an empty object (convention for arbitrary component state)
         // No special meaning to framework - mutable anywhere, not cached, not frozen
         this.state = {};
+        // Overriding on_attach()/on_detach() is interest in attachment tracking. Tracking
+        // itself only starts after the first 'ready' dispatch (see _attachment_check()).
+        if (this.on_attach !== Jqhtml_Component.prototype.on_attach ||
+            this.on_detach !== Jqhtml_Component.prototype.on_detach) {
+            this._attachment_tracking = true;
+        }
         this._log_lifecycle('construct', 'complete');
     }
     /**
@@ -4175,7 +4264,9 @@ class Jqhtml_Component {
             on_render: 'Use render() to trigger a re-render.',
             on_load: 'Use reload() to refresh data.',
             on_ready: 'Called automatically when ready.',
-            on_stop: 'Use stop() to stop the component.'
+            on_stop: 'Use stop() to stop the component.',
+            on_attach: 'Called automatically when the component enters the document.',
+            on_detach: 'Called automatically when the component leaves the document.'
         };
         const impls = {};
         const self = this;
@@ -5529,8 +5620,13 @@ class Jqhtml_Component {
         // stopped children into the parent's registry.
         this._log_lifecycle('destroy', 'start');
         this.$.addClass('_Component_Stopped');
-        // Unregister from lifecycle manager
-        this._lifecycle_manager.unregister_component(this);
+        // A component that believes it is attached is detached first, so 'detach' always
+        // precedes 'stop' and subscribers can rely on strict attach/detach alternation.
+        // A component that never fired 'attach' (stopped before ready, or born and kept
+        // off-document) fires no 'detach' either. Either way it leaves the tracker.
+        if (this._attached)
+            this._transition_attachment(false);
+        untrack_attachment(this);
         // Call user's on_stop() hook with authorization (sync) - only when actually
         // overridden, since _call_lifecycle_sync() on the base no-op costs per child
         // on every re-render.
@@ -5575,6 +5671,89 @@ class Jqhtml_Component {
     on_loaded() { } // Override to process loaded data (e.g., clone this.data to this.state)
     async on_ready() { }
     on_stop() { }
+    on_attach() { } // Sync. Root entered the document (first checked after 'ready')
+    on_detach() { } // Sync. Root left the document, or the component is being stopped while attached
+    // -------------------------------------------------------------------------
+    // DOM attachment state machine
+    // -------------------------------------------------------------------------
+    /**
+     * Whether this component currently considers itself attached to the document.
+     *
+     * This is the component's recorded state, not a live isConnected read: it is
+     * false until the first check after 'ready', and from then on flips only when a
+     * transition is observed (or on stop()). It is exactly the state 'attach' and
+     * 'detach' have reported.
+     */
+    is_attached() {
+        return this._attached;
+    }
+    /**
+     * Flip the recorded state and fire the matching hook + event. The opposite
+     * sticky event is invalidated first, so a late subscriber only ever sees the
+     * current state. Hook errors are isolated; the event still fires.
+     * @private
+     */
+    _transition_attachment(attached) {
+        this._attached = attached;
+        const event_name = attached ? 'attach' : 'detach';
+        const hook_name = attached ? 'on_attach' : 'on_detach';
+        this.invalidate(attached ? 'detach' : 'attach');
+        if (this[hook_name] !== Jqhtml_Component.prototype[hook_name]) {
+            try {
+                const result = this._call_lifecycle_sync(hook_name);
+                if (result && typeof result.then === 'function') {
+                    console.warn(`[JQHTML] Component "${this.component_name()}" returned a Promise from ${hook_name}(). ` +
+                        `${hook_name}() must be synchronous code. Remove 'async' from the function declaration.`);
+                }
+            }
+            catch (error) {
+                console.error(`[JQHTML] Error in ${hook_name}() for ${this.component_name()}:`, error);
+            }
+        }
+        this.trigger(event_name);
+    }
+    /**
+     * Compare the root's live connectivity with the recorded state and transition
+     * on a difference. Idempotent. Called by the document observer on every
+     * mutation batch for tracked components, and directly by the framework after
+     * 'ready' and when interest is registered late.
+     * @private
+     */
+    _attachment_check() {
+        if (this._stopped)
+            return;
+        const connected = !!this.$[0].isConnected;
+        if (connected !== this._attached)
+            this._transition_attachment(connected);
+    }
+    /**
+     * The first check, run once the 'ready' handlers have completed. Fires 'attach'
+     * if the component was born attached, even with no listener, so a later
+     * .on('attach') gets the sticky fire. Deferred interest starts tracking here.
+     * @private
+     */
+    _attachment_first_check() {
+        const first = !this._attachment_checked;
+        this._attachment_checked = true;
+        this._attachment_check();
+        if (first && this._attachment_tracking)
+            track_attachment(this);
+    }
+    /**
+     * Register interest in attach/detach. Before the first ready check this only
+     * records the interest; after it, tracking starts immediately and a check runs
+     * at once, so a late subscriber on a natively-removed component sees 'detach'.
+     * @private
+     */
+    _watch_attachment() {
+        if (this._attachment_tracking)
+            return;
+        this._attachment_tracking = true;
+        if (this._attachment_checked && !this._stopped) {
+            track_attachment(this);
+            this._attachment_check();
+        }
+    }
     /**
      * Called with the viewport width in CSS pixels:
      *   - after every on_render()
@@ -5639,6 +5818,8 @@ class Jqhtml_Component {
      * @see component-events.ts for full documentation
      */
     on(event_name, callback) {
+        if (event_name === 'attach' || event_name === 'detach')
+            this._watch_attachment();
         return event_on(this, event_name, callback);
     }
     /**
@@ -5647,14 +5828,24 @@ class Jqhtml_Component {
      * @see component-events.ts for full documentation
      */
     once(event_name, callback) {
+        if (event_name === 'attach' || event_name === 'detach')
+            this._watch_attachment();
         return event_once(this, event_name, callback);
     }
     /**
      * Trigger a lifecycle event - delegates to component-events.ts
      * @see component-events.ts for full documentation
+     *
+     * 'ready' is special: once its handlers have run, the component runs its first
+     * attachment check (and every later one, idempotently). Doing it here rather than
+     * at each of the call sites that trigger 'ready' guarantees the order
+     * on_ready() -> 'ready' handlers -> 'attach', so everything on_ready() set up is
+     * complete before anyone learns the component is in the document.
      */
     trigger(event_name, data) {
         event_trigger(this, event_name, data);
+        if (event_name === 'ready' && !this._stopped)
+            this._attachment_first_check();
     }
     /**
      * Check if any callbacks are registered for a given event
@@ -7088,9 +7279,42 @@ function init_jquery_plugin(jQuery) {
         return jQuery(results);
     };
     // Store original jQuery methods
-    const originalEmpty = jQuery.fn.empty;
     const originalHtml = jQuery.fn.html;
-    const originalText = jQuery.fn.text;
+    // ---------------------------------------------------------------------------
+    // Stop components on every jQuery-driven removal by hooking jQuery.cleanData.
+    //
+    // jQuery routes .remove(), .empty(), .html(x), .text(x), .replaceWith() and
+    // .replaceAll() through jQuery.cleanData(elems) to drop the data store and
+    // handlers of every element about to leave the tree - and `elems` is already the
+    // flattened subtree, in document order (parent before child). Stopping here is
+    // therefore one classList check per removed element, no extra traversal, and
+    // covers every jQuery removal path at once. It is the same hook jQuery UI's
+    // widget factory uses for the same reason.
+    //
+    // It MUST be installed on the original jQuery object: jQuery's own code calls
+    // cleanData through its closure-local reference, not through our wrapper. The
+    // wrapper's copied static is updated below so both names agree.
+    //
+    // .detach() does NOT call cleanData, by jQuery's own design (it keeps data for
+    // reinsertion), and native DOM removal (el.remove(), innerHTML = '') bypasses
+    // jQuery entirely. Neither stops a component; the 'detach' lifecycle event is
+    // the signal for those. Moving a component (.appendTo) is not a removal.
+    // ---------------------------------------------------------------------------
+    const originalCleanData = _jqhtml_original_jquery.cleanData;
+    const cleanDataWithComponentStop = function (elems) {
+        for (let i = 0; i < elems.length; i++) {
+            const el = elems[i];
+            if (el.nodeType !== 1 || !el.classList.contains('Component'))
+                continue;
+            const component = _jqhtml_original_jquery.data(el, '_component');
+            if (component && !component._stopped) {
+                component._stop(); // Not recursive: every descendant is in elems too
+            }
+        }
+        return originalCleanData(elems);
+    };
+    _jqhtml_original_jquery.cleanData = cleanDataWithComponentStop;
+    jQuery.cleanData = cleanDataWithComponentStop;
     // ---------------------------------------------------------------------------
     // Guard against hand-creating elements with data-sid via jQuery.
     //
@@ -7147,53 +7371,15 @@ function init_jquery_plugin(jQuery) {
             `  • <div class="MyComponent__${sid}"> → .find('.MyComponent__${sid}')`);
     };
     /**
-     * Override jQuery.fn.empty() to stop child components before clearing DOM
-     * This ensures component cleanup hooks fire when DOM is cleared
-     */
-    jQuery.fn.empty = function () {
-        return this.each(function () {
-            // Stop all child components before clearing DOM
-            jQuery(this).find('.Component').each(function () {
-                const component = jQuery(this).data('_component');
-                if (component && !component._stopped) {
-                    component._stop(); // Stop just the component, DOM will be cleared anyway
-                }
-            });
-            // Call original empty
-            originalEmpty.call(jQuery(this));
-        });
-    };
-    /**
-     * Override jQuery.fn.html() to stop child components when setting new content
-     * When used as setter, calls .empty() first to properly cleanup components
+     * Override jQuery.fn.html() setter to reject hand-written data-sid before the
+     * DOM is mutated. Component stopping is handled by the cleanData hook above.
      */
     jQuery.fn.html = function (value) {
-        // Getter - just pass through
         if (arguments.length === 0) {
             return originalHtml.call(this);
         }
-        // Reject hand-written data-sid before mutating the DOM
         assert_no_manual_sid(value, '.html()');
-        // Setter - empty first (which stops components), then set content
-        return this.each(function () {
-            jQuery(this).empty();
-            originalHtml.call(jQuery(this), value);
-        });
-    };
-    /**
-     * Override jQuery.fn.text() to stop child components when setting new content
-     * When used as setter, calls .empty() first to properly cleanup components
-     */
-    jQuery.fn.text = function (value) {
-        // Getter - just pass through
-        if (arguments.length === 0) {
-            return originalText.call(this);
-        }
-        // Setter - empty first (which stops components), then set content
-        return this.each(function () {
-            jQuery(this).empty();
-            originalText.call(jQuery(this), value);
-        });
+        return originalHtml.call(this, value);
     };
     // Store original jQuery.fn.on
     const originalOn = jQuery.fn.on;
@@ -7335,7 +7521,7 @@ function init(jQuery, config) {
     }
 }
 // Version - will be replaced during build with actual version from package.json
-const version = '2.3.71';
+const version = '2.3.72';
 // Default export with all functionality
 const jqhtml = {
     // Core
@@ -7450,7 +7636,11 @@ const jqhtml = {
     get_captured_data,
     stop_data_capture,
     set_preload_data,
-    clear_preload_data
+    clear_preload_data,
+    // Attachment tracking diagnostics - how many components are watched for
+    // attach/detach and whether the document observer is currently installed
+    tracked_attachment_count,
+    attachment_observer_active
 };
 // Auto-register on window for browser environments
 // This is REQUIRED for compiled templates which use window.jqhtml.register_template()
@@ -7480,5 +7670,5 @@ if (typeof window !== 'undefined' && !window.jqhtml) {
     }
 }
 
-export { COMPONENT_NAME_PATTERN, COMPONENT_NAME_RULE, Jqhtml_Component, LifecycleManager as Jqhtml_LifecycleManager, Jqhtml_Local_Storage, LifecycleManager, Load_Coordinator, add_object_printer, applyDebugDelay, boot, clear_preload_data, configure, create_component, debug_overlay, jqhtml as default, devWarn, dynamic_component_name, escape_html, escape_html_nl2br, extract_slots, get_captured_data, get_component_class, get_component_names, get_config, get_object_printers, get_registered_templates, get_template, get_template_by_class, handleComponentError, has_component, init, init_jquery_plugin, isSequentialProcessing, is_component_name, list_components, logDataChange, logDispatch, logInstruction, logLifecycle, print_object, process_instructions, register, register_cache_class, register_component, register_template, set_preload_data, start_data_capture, stop_data_capture, version };
+export { COMPONENT_NAME_PATTERN, COMPONENT_NAME_RULE, Jqhtml_Component, LifecycleManager as Jqhtml_LifecycleManager, Jqhtml_Local_Storage, LifecycleManager, Load_Coordinator, add_object_printer, applyDebugDelay, attachment_observer_active, boot, clear_preload_data, configure, create_component, debug_overlay, jqhtml as default, devWarn, dynamic_component_name, escape_html, escape_html_nl2br, extract_slots, get_captured_data, get_component_class, get_component_names, get_config, get_object_printers, get_registered_templates, get_template, get_template_by_class, handleComponentError, has_component, init, init_jquery_plugin, isSequentialProcessing, is_component_name, list_components, logDataChange, logDispatch, logInstruction, logLifecycle, print_object, process_instructions, register, register_cache_class, register_component, register_template, set_preload_data, start_data_capture, stop_data_capture, tracked_attachment_count, version };
 //# sourceMappingURL=jqhtml-core.esm.js.map