assign-gingerly 0.0.28 → 0.0.29

package/README.md

@@ -1427,6 +1427,150 @@ element.enh.dispose(registryItem); // Stops timer and cleans up
 - Calling `enh.get()` again will create a new instance
 - The enhancement property is removed from the enh container
 
+#### Memory Management and When to Call Dispose
+
+**Important: Understanding automatic vs manual cleanup**
+
+The enhancement storage system uses a **WeakMap** to prevent memory leaks:
+
+```TypeScript
+// Global storage: WeakMap<Element, Map<EnhancementConfig, Instance>>
+```
+
+**What this means for memory:**
+
+✅ **Automatic cleanup when elements are garbage collected:**
+- When an element is GC'd, the WeakMap entry is automatically removed
+- Both `enhKey` references (`element.enh[enhKey]`) and WeakMap entries are cleaned up
+- **No memory leak from the storage mechanism itself**
+
+⚠️ **Manual cleanup needed for enhancement internals:**
+- Event listeners on global objects (window, document)
+- Timers (setInterval, setTimeout)
+- External registries or caches
+- Network connections or subscriptions
+
+**The challenge: Knowing WHEN to dispose**
+
+JavaScript provides no way to detect when an element is about to be garbage collected. Additionally, DOM disconnection doesn't reliably indicate disposal:
+
+```TypeScript
+// Element disconnected - but should we dispose?
+element.remove();
+
+// Case 1: Temporarily removed, will be re-added
+setTimeout(() => document.body.append(element), 1000);
+// ❌ Don't dispose - enhancement should persist
+
+// Case 2: Moved to another location
+otherContainer.append(element);
+// ❌ Don't dispose - enhancement should persist
+
+// Case 3: Cached for reuse
+elementCache.set('myElement', element);
+// ❌ Don't dispose - enhancement should persist
+
+// Case 4: Truly done, ready for GC
+element = null;
+// ✅ Should dispose, but no way to detect this automatically
+```
+
+**Practical disposal strategies:**
+
+1. **Short-lived elements:** Don't worry about disposal - WeakMap handles cleanup automatically when elements are GC'd
+
+2. **Long-lived applications:** Implement manual disposal at logical boundaries:
+   ```TypeScript
+   // On route change
+   router.beforeLeave(() => {
+     oldRouteElements.forEach(el => el.enh.dispose(registryItem));
+   });
+   
+   // On explicit user action
+   closeButton.onclick = () => {
+     dialog.enh.dispose(registryItem);
+     dialog.remove();
+   };
+   ```
+
+3. **Framework integration:** Use framework lifecycle hooks:
+   ```TypeScript
+   // React
+   useEffect(() => {
+     return () => elementRef.current?.enh.dispose(registryItem);
+   }, []);
+   
+   // Vue
+   onUnmounted(() => {
+     element.value?.enh.dispose(registryItem);
+   });
+   ```
+
+4. **MutationObserver heuristic:** Watch for disconnection + timeout (imperfect but practical):
+   ```TypeScript
+   const observer = new MutationObserver(() => {
+     if (!element.isConnected) {
+       setTimeout(() => {
+         if (!element.isConnected) {
+           element.enh.dispose(registryItem);
+         }
+       }, 5000); // If still disconnected after 5s, probably done
+     }
+   });
+   ```
+
+**Best practices for enhancement authors:**
+
+Always implement proper cleanup in your dispose method:
+
+```TypeScript
+class MyEnhancement {
+  element;
+  timerId = null;
+  boundHandler = null;
+  
+  constructor(element, ctx) {
+    this.element = element;
+    this.boundHandler = this.handleClick.bind(this);
+    
+    // Local listener - OK, will be GC'd with element
+    element.addEventListener('click', this.boundHandler);
+    
+    // Global listener - MUST clean up manually
+    window.addEventListener('resize', this.boundHandler);
+    
+    // Timer - MUST clean up manually
+    this.timerId = setInterval(() => this.update(), 1000);
+  }
+  
+  dispose() {
+    // Clean up global listener
+    if (this.boundHandler) {
+      window.removeEventListener('resize', this.boundHandler);
+    }
+    
+    // Clean up timer
+    if (this.timerId) {
+      clearInterval(this.timerId);
+      this.timerId = null;
+    }
+    
+    // Clear references
+    this.element = null;
+    this.boundHandler = null;
+  }
+  
+  handleClick() { /* ... */ }
+  update() { /* ... */ }
+}
+```
+
+**Summary:**
+- ✅ Storage mechanism prevents memory leaks via WeakMap
+- ⚠️ Enhancement internals need manual cleanup via dispose()
+- ❌ No automatic way to detect when disposal should happen
+- 👍 Choose disposal strategy based on your application's lifecycle
+
 ### Waiting for Async Initialization with `enh.whenResolved(regItem)`
 
 The `enh.whenResolved(regItem)` method provides a way to wait for asynchronous enhancement initialization:

package/getHost.js

@@ -0,0 +1,51 @@
+/**
+ * Get the itemscope host element for a given element.
+ * This function finds the closest element with an itemscope attribute and waits for it to be ready.
+ *
+ * @param el - The element to start searching from
+ * @returns The itemscope host element, or null if none found
+ */
+export async function getHost(el) {
+    const itemScopeHost = el.closest('[itemscope]');
+    if (itemScopeHost) {
+        const { localName } = itemScopeHost;
+        // If it's a custom element, wait for it to be defined
+        if (localName.includes('-')) {
+            const registry = itemScopeHost.customElementRegistry ?? customElements;
+            await registry.whenDefined(localName);
+            return itemScopeHost;
+        }
+        else {
+            // Check if itemscope specifies a value (manager name)
+            const itemscopeValue = itemScopeHost.getAttribute('itemscope');
+            if (itemscopeValue && itemscopeValue.length > 0) {
+                // Wait for the manager to be defined in the itemscope registry
+                const registry = itemScopeHost.customElementRegistry?.itemscopeRegistry
+                    ?? (typeof customElements !== 'undefined' ? customElements.itemscopeRegistry : undefined);
+                if (registry) {
+                    await registry.whenDefined(itemscopeValue);
+                }
+            }
+            return itemScopeHost;
+        }
+    }
+    else {
+        // No itemscope host found in the light DOM
+        // Check if we're inside a shadow root and get the shadow host
+        const rootNode = el.getRootNode();
+        // Check if it's a shadow root (has a host property)
+        if (rootNode && 'host' in rootNode && rootNode.host) {
+            const host = rootNode.host;
+            const { localName } = host;
+            // If the host is a custom element, wait for it to be defined
+            if (localName.includes('-')) {
+                const registry = host.customElementRegistry ?? customElements;
+                await registry.whenDefined(localName);
+            }
+            return host;
+        }
+        // Not in a shadow root either
+        return null;
+    }
+}
+export default getHost;

package/getHost.ts

@@ -0,0 +1,58 @@
+/**
+ * Get the itemscope host element for a given element.
+ * This function finds the closest element with an itemscope attribute and waits for it to be ready.
+ * 
+ * @param el - The element to start searching from
+ * @returns The itemscope host element, or null if none found
+ */
+export async function getHost(el: Element): Promise<Element | null> {
+    const itemScopeHost = el.closest('[itemscope]');
+    if (itemScopeHost) {
+        const { localName } = itemScopeHost;
+        
+        // If it's a custom element, wait for it to be defined
+        if (localName.includes('-')) {
+            const registry = (itemScopeHost as any).customElementRegistry ?? customElements;
+            await registry.whenDefined(localName);
+            return itemScopeHost;
+        } else {
+            // Check if itemscope specifies a value (manager name)
+            const itemscopeValue = itemScopeHost.getAttribute('itemscope');
+            
+            if (itemscopeValue && itemscopeValue.length > 0) {
+                // Wait for the manager to be defined in the itemscope registry
+                const registry = (itemScopeHost as any).customElementRegistry?.itemscopeRegistry
+                    ?? (typeof customElements !== 'undefined' ? customElements.itemscopeRegistry : undefined);
+                
+                if (registry) {
+                    await registry.whenDefined(itemscopeValue);
+                }
+            }
+            
+            return itemScopeHost;
+        }
+    } else {
+        // No itemscope host found in the light DOM
+        // Check if we're inside a shadow root and get the shadow host
+        const rootNode = el.getRootNode();
+        
+        // Check if it's a shadow root (has a host property)
+        if (rootNode && 'host' in rootNode && (rootNode as ShadowRoot).host) {
+            const host = (rootNode as ShadowRoot).host;
+            const { localName } = host;
+            
+            // If the host is a custom element, wait for it to be defined
+            if (localName.includes('-')) {
+                const registry = (host as any).customElementRegistry ?? customElements;
+                await registry.whenDefined(localName);
+            }
+            
+            return host;
+        }
+        
+        // Not in a shadow root either
+        return null;
+    }
+}
+
+export default getHost;

package/index.js

@@ -6,4 +6,5 @@ export { ParserRegistry, globalParserRegistry } from './parserRegistry.js';
 export { parseWithAttrs } from './parseWithAttrs.js';
 export { buildCSSQuery } from './buildCSSQuery.js';
 export { resolveTemplate } from './resolveTemplate.js';
+export { getHost } from './getHost.js';
 import './object-extension.js';

package/index.ts

@@ -6,4 +6,5 @@ export {ParserRegistry, globalParserRegistry} from './parserRegistry.js';
 export {parseWithAttrs} from './parseWithAttrs.js';
 export {buildCSSQuery} from './buildCSSQuery.js';
 export {resolveTemplate} from './resolveTemplate.js';
+export {getHost} from './getHost.js';
 import './object-extension.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "assign-gingerly",
-  "version": "0.0.28",
+  "version": "0.0.29",
   "description": "This package provides a utility function for carefully merging one object into another.",
   "homepage": "https://github.com/bahrus/assign-gingerly#readme",
   "bugs": {
@@ -51,6 +51,10 @@
     "./resolveTemplate.js": {
       "default": "./resolveTemplate.js",
       "types": "./resolveTemplate.ts"
+    },
+    "./getHost.js": {
+      "default": "./getHost.js",
+      "types": "./getHost.ts"
     }
   },
   "main": "index.js",

package/types/assign-gingerly/types.d.ts

@@ -112,7 +112,7 @@ export type ParserFunction<T = any> =
   | ((attrValue: string | null) => any)
   | ((attrValue: string | null, context?: ParserContext<T>) => any);
 
-export interface AttrConfig<T = any> {
+export interface AttrConfig<T = unknown, TParserConfig = unknown> {
   /**
    * Type of the property value (JSON-serializable string format)
    */
@@ -152,6 +152,12 @@ export interface AttrConfig<T = any> {
     | ParserFunction<T>
     | string
   ;
+
+  /**
+   * configuration information needed by a custom parser to properly
+   * parse the attribute.
+   */
+  parserConfig?: TParserConfig;
   
   /**
    * Default value to use when attribute is missing