@jqhtml/core 2.3.71 → 2.3.74

package/dist/component.d.ts

@@ -77,6 +77,9 @@ export declare class Jqhtml_Component {
     private __load_gates;
     private __first_load_started;
     private __gate_resume;
+    private _attached;
+    private _attachment_checked;
+    private _attachment_tracking;
     constructor(element?: any, args?: Record<string, any>);
     /**
      * Protect lifecycle methods from manual invocation
@@ -405,6 +408,51 @@ export declare class Jqhtml_Component {
     on_loaded(): void | Promise<void>;
     on_ready(): Promise<void>;
     on_stop(): void;
+    on_attach(): void;
+    on_detach(): void;
+    /**
+     * Whether this component's root is in the document right now.
+     *
+     * A live answer - one isConnected read - so it is correct at every point in the
+     * lifecycle (including on_create()/on_load()/on_ready(), before the first 'attach')
+     * and for untracked components (a natively-removed component that nothing watches
+     * still answers false). A stopped component always answers false.
+     *
+     * It does NOT read the recorded state behind 'attach'/'detach' (_attached), and it
+     * never starts tracking. The two can disagree briefly: is_attached() can be true
+     * before the first 'attach' has fired, and changes a moment before the matching
+     * event, since the events come from the document observer.
+     */
+    is_attached(): boolean;
+    /**
+     * 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
+     */
+    private _transition_attachment;
+    /**
+     * 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(): void;
+    /**
+     * 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
+     */
+    private _attachment_first_check;
+    /**
+     * 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
+     */
+    private _watch_attachment;
     /**
      * Called with the viewport width in CSS pixels:
      *   - after every on_render()
@@ -461,6 +509,12 @@ export declare class Jqhtml_Component {
     /**
      * 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: string, data?: any): void;
     /**

package/dist/component.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"component.d.ts","sourceRoot":"","sources":["../src/component.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"component.d.ts","sourceRoot":"","sources":["../src/component.ts"],"names":[],"mappings":"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"}

package/dist/dom-attachment.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 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.
+ */
+/** Start watching a component's root for attach/detach transitions. Idempotent. */
+export declare function track_attachment(component: any): void;
+/** Stop watching a component (called from _stop()). Idempotent. */
+export declare function untrack_attachment(component: any): void;
+/** Number of components currently tracked (diagnostics / tests). */
+export declare function tracked_attachment_count(): number;
+/** Whether the document observer is currently installed (diagnostics / tests). */
+export declare function attachment_observer_active(): boolean;
+//# sourceMappingURL=dom-attachment.d.ts.map

package/dist/dom-attachment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dom-attachment.d.ts","sourceRoot":"","sources":["../src/dom-attachment.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AA+BH,mFAAmF;AACnF,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,GAAG,GAAG,IAAI,CAMrD;AAED,mEAAmE;AACnE,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,GAAG,GAAG,IAAI,CAMvD;AAED,oEAAoE;AACpE,wBAAgB,wBAAwB,IAAI,MAAM,CAEjD;AAED,kFAAkF;AAClF,wBAAgB,0BAA0B,IAAI,OAAO,CAEpD"}

package/dist/index.cjs

@@ -218,12 +218,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
@@ -234,7 +239,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();
@@ -395,12 +399,6 @@ class LifecycleManager {
             }
         }
     }
-    /**
-     * Unregister a component (called on destroy)
-     */
-    unregister_component(component) {
-        this.active_components.delete(component);
-    }
 }
 
 /**
@@ -1619,7 +1617,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.74';
 const CLASS_MARKER = '__jqhtml_class__';
 const PROPS_MARKER = '__jqhtml_props__';
 /**
@@ -3180,6 +3178,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
  *
@@ -4088,6 +4165,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
@@ -4161,6 +4244,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');
     }
     /**
@@ -4174,7 +4263,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;
@@ -5528,8 +5619,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.
@@ -5574,6 +5670,94 @@ 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's root is in the document right now.
+     *
+     * A live answer - one isConnected read - so it is correct at every point in the
+     * lifecycle (including on_create()/on_load()/on_ready(), before the first 'attach')
+     * and for untracked components (a natively-removed component that nothing watches
+     * still answers false). A stopped component always answers false.
+     *
+     * It does NOT read the recorded state behind 'attach'/'detach' (_attached), and it
+     * never starts tracking. The two can disagree briefly: is_attached() can be true
+     * before the first 'attach' has fired, and changes a moment before the matching
+     * event, since the events come from the document observer.
+     */
+    is_attached() {
+        return !this._stopped && !!this.$[0].isConnected;
+    }
+    /**
+     * 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()
@@ -5638,6 +5822,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);
     }
     /**
@@ -5646,14 +5832,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
@@ -7087,9 +7283,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.
     //
@@ -7146,53 +7375,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;
@@ -7334,7 +7525,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.74';
 // Default export with all functionality
 const jqhtml = {
     // Core
@@ -7449,7 +7640,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()
@@ -7488,6 +7683,7 @@ exports.LifecycleManager = LifecycleManager;
 exports.Load_Coordinator = Load_Coordinator;
 exports.add_object_printer = add_object_printer;
 exports.applyDebugDelay = applyDebugDelay;
+exports.attachment_observer_active = attachment_observer_active;
 exports.boot = boot;
 exports.clear_preload_data = clear_preload_data;
 exports.configure = configure;
@@ -7527,5 +7723,6 @@ exports.register_template = register_template;
 exports.set_preload_data = set_preload_data;
 exports.start_data_capture = start_data_capture;
 exports.stop_data_capture = stop_data_capture;
+exports.tracked_attachment_count = tracked_attachment_count;
 exports.version = version;
 //# sourceMappingURL=index.cjs.map