assign-gingerly 0.0.39 → 0.0.41

package/README.md

@@ -4615,6 +4615,114 @@ class MyBehaviors extends PropertyBag {
 customElements.assignFeatures(MyBehaviors, { anything: { spawn: AnythingImpl } }); // ✓
 ```
 
+### Lifecycle callback forwarding with `callbackForwarding`
+
+Features can receive custom element lifecycle callbacks by declaring `callbackForwarding` in their config. This can be specified by the feature author (in `static supportedFeatures`) and/or by the consumer (in `assignFeatures`). Both are merged — the author declares what the feature intrinsically needs, the consumer can add more:
+
+```JavaScript
+// Author declares what the feature needs
+class MyElement extends HTMLElement {
+    static supportedFeatures = {
+        reflector: {
+            fallbackSpawn: Reflector,
+            callbackForwarding: ['connectedCallback', 'disconnectedCallback']
+        }
+    }
+}
+
+// Consumer can add more (but not remove author's)
+customElements.assignFeatures(MyElement, {
+    reflector: {
+        spawn: Reflector,
+        callbackForwarding: ['adoptedCallback'] // merged with author's
+    }
+});
+```
+
+When the custom element's `connectedCallback` fires, the feature's `connectedCallback` is called automatically. This eliminates boilerplate forwarding code and handles feature activation timing naturally.
+
+**How it works:**
+
+1. `assignFeatures` patches the custom element's lifecycle callback on the prototype (once per callback type).
+2. The original callback runs first, then all registered features are forwarded.
+3. On first `connectedCallback`, the getter is triggered — spawning the feature lazily at the correct lifecycle moment (when the element is in the DOM and computed styles are available).
+4. For async features, forwarding is skipped until the real instance is available.
+
+**Supported callbacks:**
+
+| Callback | Use case |
+|----------|----------|
+| `connectedCallback` | Feature needs DOM context (computed styles, layout, etc.) |
+| `disconnectedCallback` | Feature needs cleanup (remove listeners, abort fetches) |
+| `attributeChangedCallback` | Feature reacts to attribute changes (limited to element's `observedAttributes`) |
+| `adoptedCallback` | Feature reacts to document adoption |
+
+**Example: Feature that reads computed styles on connect**
+
+```JavaScript
+class Reflector {
+    constructor(host, ctx) {
+        this.host = host;
+        this.internals = ctx.shared.internals;
+    }
+    
+    connectedCallback() {
+        // Safe to call getComputedStyle here — element is in the DOM
+        const styles = getComputedStyle(this.host);
+        const exports = styles.getPropertyValue('--custom-state-exports');
+        // ... process exports
+    }
+    
+    disconnectedCallback() {
+        // Cleanup
+    }
+}
+
+class MyElement extends HTMLElement {
+    #internals;
+    static supportedFeatures = {
+        reflector: {
+            fallbackSpawn: Reflector,
+            getSharedContext(instance) {
+                return { internals: instance.#internals };
+            }
+        }
+    }
+    constructor() {
+        super();
+        this.#internals = this.attachInternals();
+    }
+}
+
+customElements.assignFeatures(MyElement, {
+    reflector: {
+        spawn: Reflector,
+        callbackForwarding: ['connectedCallback', 'disconnectedCallback']
+    }
+});
+customElements.define('my-element', MyElement);
+```
+
+No manual getter access or `connectedCallback` boilerplate needed — the feature activates at the right time automatically.
+
+**Multiple features with callbacks:**
+
+```JavaScript
+customElements.assignFeatures(MyElement, {
+    reflector: {
+        spawn: Reflector,
+        callbackForwarding: ['connectedCallback']
+    },
+    logger: {
+        spawn: Logger,
+        callbackForwarding: ['connectedCallback', 'disconnectedCallback']
+    }
+});
+// Both features receive connectedCallback; only logger receives disconnectedCallback
+```
+
+**Note on `attributeChangedCallback`:** The feature only receives callbacks for attributes listed in the element's `static observedAttributes`. Features cannot add to this list after `define()` is called.
+
 ### Roadmap (future phases)
 
 - **Nested features**: Support `?.path?.notation` keys directly in `assignFeatures` (without requiring `PropertyBag`).

package/assignFeatures.js

@@ -298,6 +298,73 @@ function installFeatureGetter(ctr, key, featuresRegistry) {
         configurable: false
     });
 }
+/**
+ * Valid lifecycle callback names that can be forwarded to features.
+ */
+const VALID_CALLBACKS = new Set([
+    'connectedCallback',
+    'disconnectedCallback',
+    'attributeChangedCallback',
+    'adoptedCallback'
+]);
+/**
+ * WeakMap tracking which callbacks have been patched on which constructors,
+ * and which feature keys are registered for each callback.
+ * Structure: Map<Function, Map<callbackName, Set<featureKey>>>
+ */
+const callbackRegistry = new Map();
+/**
+ * Installs or updates lifecycle callback forwarding on a constructor's prototype.
+ * Patches the callback once per type, accumulating feature keys for each.
+ */
+function installCallbackForwarding(ctr, key, callbacks) {
+    let ctrCallbacks = callbackRegistry.get(ctr);
+    if (!ctrCallbacks) {
+        ctrCallbacks = new Map();
+        callbackRegistry.set(ctr, ctrCallbacks);
+    }
+    for (const callbackName of callbacks) {
+        if (!VALID_CALLBACKS.has(callbackName)) {
+            throw new Error(`assignFeatures: invalid callbackForwarding "${callbackName}" for feature "${key}". ` +
+                `Valid values: ${[...VALID_CALLBACKS].join(', ')}`);
+        }
+        // Validate that the spawn class has the method (sync spawners only)
+        // For async spawners, validation is deferred to runtime
+        let featureKeys = ctrCallbacks.get(callbackName);
+        if (!featureKeys) {
+            featureKeys = new Set();
+            ctrCallbacks.set(callbackName, featureKeys);
+            // Patch the prototype callback (only once per callback type per class)
+            const original = ctr.prototype[callbackName];
+            Object.defineProperty(ctr.prototype, callbackName, {
+                value: function (...args) {
+                    // Call original first
+                    if (original)
+                        original.apply(this, args);
+                    // Forward to all registered features
+                    const keys = callbackRegistry.get(ctr)?.get(callbackName);
+                    if (keys) {
+                        for (const featureKey of keys) {
+                            // Access the getter (triggers lazy spawn on first connectedCallback)
+                            const feature = this[featureKey];
+                            // Only forward if it's a real instance (not a placeholder or error)
+                            if (feature && typeof feature === 'object' &&
+                                typeof feature[callbackName] === 'function' &&
+                                !(FEATURE_ERROR in feature)) {
+                                feature[callbackName](...args);
+                            }
+                        }
+                    }
+                },
+                writable: true,
+                enumerable: false,
+                configurable: true
+            });
+        }
+        // Add this feature key to the set for this callback
+        featureKeys.add(key);
+    }
+}
 /**
  * Core assignFeatures implementation.
  * Validates inputs, registers injections, and installs lazy getters.
@@ -334,6 +401,16 @@ export function assignFeatures(ctr, features, featuresRegistry) {
         featuresRegistry.set(ctr, key, features[key]);
         // 5. Install the lazy getter on the prototype
         installFeatureGetter(ctr, key, featuresRegistry);
+        // 6. Install callback forwarding if configured (merge author + consumer)
+        const featureConfig = features[key];
+        const optIn = supportedFeatures[key];
+        const authorCallbacks = optIn.callbackForwarding || [];
+        const consumerCallbacks = featureConfig.callbackForwarding || [];
+        // Union of both (author defaults + consumer additions)
+        const allCallbacks = [...new Set([...authorCallbacks, ...consumerCallbacks])];
+        if (allCallbacks.length > 0) {
+            installCallbackForwarding(ctr, key, allCallbacks);
+        }
     }
     // 6. Install whenFeatureReady method if featuresConfig.lifecycleKeys is configured
     const featuresConfig = ctr.featuresConfig;

package/assignFeatures.ts

@@ -65,6 +65,16 @@ export interface SupportedFeatureConfig {
      * }
      */
     getSharedContext?: (instance: any) => any;
+
+    /**
+     * Lifecycle callbacks that this feature requires.
+     * Serves as the default — the consumer can add more via FeatureConfig.callbackForwarding
+     * but cannot remove these.
+     * 
+     * Supported: 'connectedCallback', 'disconnectedCallback',
+     *            'attributeChangedCallback', 'adoptedCallback'
+     */
+    callbackForwarding?: string[];
 }
 
 /**
@@ -133,6 +143,22 @@ export interface FeatureConfig {
      * via ctx.injection.customData in the constructor.
      */
     customData?: any;
+
+    /**
+     * Custom element lifecycle callbacks to forward to this feature.
+     * The feature class must implement the listed methods.
+     * 
+     * On first `connectedCallback` forwarding, the getter is triggered (spawning
+     * the feature if needed). For async features, forwarding is skipped until
+     * the real instance is available.
+     * 
+     * Supported values: 'connectedCallback', 'disconnectedCallback',
+     *                   'attributeChangedCallback', 'adoptedCallback'
+     * 
+     * Note: `attributeChangedCallback` only receives events for attributes
+     * listed in the element's `static observedAttributes`.
+     */
+    callbackForwarding?: string[];
 }
 
 export type SupportedFeaturesMap = Record<string, SupportedFeatureConfig>;
@@ -482,6 +508,89 @@ function installFeatureGetter(
     });
 }
 
+/**
+ * Valid lifecycle callback names that can be forwarded to features.
+ */
+const VALID_CALLBACKS = new Set([
+    'connectedCallback',
+    'disconnectedCallback',
+    'attributeChangedCallback',
+    'adoptedCallback'
+]);
+
+/**
+ * WeakMap tracking which callbacks have been patched on which constructors,
+ * and which feature keys are registered for each callback.
+ * Structure: Map<Function, Map<callbackName, Set<featureKey>>>
+ */
+const callbackRegistry = new Map<Function, Map<string, Set<string>>>();
+
+/**
+ * Installs or updates lifecycle callback forwarding on a constructor's prototype.
+ * Patches the callback once per type, accumulating feature keys for each.
+ */
+function installCallbackForwarding(
+    ctr: Function,
+    key: string,
+    callbacks: string[]
+): void {
+    let ctrCallbacks = callbackRegistry.get(ctr);
+    if (!ctrCallbacks) {
+        ctrCallbacks = new Map();
+        callbackRegistry.set(ctr, ctrCallbacks);
+    }
+
+    for (const callbackName of callbacks) {
+        if (!VALID_CALLBACKS.has(callbackName)) {
+            throw new Error(
+                `assignFeatures: invalid callbackForwarding "${callbackName}" for feature "${key}". ` +
+                `Valid values: ${[...VALID_CALLBACKS].join(', ')}`
+            );
+        }
+
+        // Validate that the spawn class has the method (sync spawners only)
+        // For async spawners, validation is deferred to runtime
+
+        let featureKeys = ctrCallbacks.get(callbackName);
+        if (!featureKeys) {
+            featureKeys = new Set();
+            ctrCallbacks.set(callbackName, featureKeys);
+
+            // Patch the prototype callback (only once per callback type per class)
+            const original = ctr.prototype[callbackName];
+            
+            Object.defineProperty(ctr.prototype, callbackName, {
+                value: function (this: any, ...args: any[]) {
+                    // Call original first
+                    if (original) original.apply(this, args);
+
+                    // Forward to all registered features
+                    const keys = callbackRegistry.get(ctr)?.get(callbackName);
+                    if (keys) {
+                        for (const featureKey of keys) {
+                            // Access the getter (triggers lazy spawn on first connectedCallback)
+                            const feature = this[featureKey];
+
+                            // Only forward if it's a real instance (not a placeholder or error)
+                            if (feature && typeof feature === 'object' &&
+                                typeof feature[callbackName] === 'function' &&
+                                !(FEATURE_ERROR in feature)) {
+                                feature[callbackName](...args);
+                            }
+                        }
+                    }
+                },
+                writable: true,
+                enumerable: false,
+                configurable: true
+            });
+        }
+
+        // Add this feature key to the set for this callback
+        featureKeys.add(key);
+    }
+}
+
 /**
  * Core assignFeatures implementation.
  * Validates inputs, registers injections, and installs lazy getters.
@@ -536,6 +645,17 @@ export function assignFeatures(
 
         // 5. Install the lazy getter on the prototype
         installFeatureGetter(ctr, key, featuresRegistry);
+
+        // 6. Install callback forwarding if configured (merge author + consumer)
+        const featureConfig = features[key];
+        const optIn = supportedFeatures[key];
+        const authorCallbacks = optIn.callbackForwarding || [];
+        const consumerCallbacks = featureConfig.callbackForwarding || [];
+        // Union of both (author defaults + consumer additions)
+        const allCallbacks = [...new Set([...authorCallbacks, ...consumerCallbacks])];
+        if (allCallbacks.length > 0) {
+            installCallbackForwarding(ctr, key, allCallbacks);
+        }
     }
 
     // 6. Install whenFeatureReady method if featuresConfig.lifecycleKeys is configured

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "assign-gingerly",
-  "version": "0.0.39",
+  "version": "0.0.41",
   "description": "This package provides a utility function for carefully merging one object into another.",
   "homepage": "https://github.com/bahrus/assign-gingerly#readme",
   "bugs": {
@@ -87,9 +87,9 @@
     "chrome": "npx playwright cr http://localhost:8000"
   },
   "devDependencies": {
-    "@playwright/test": "1.59.1",
+    "@playwright/test": "1.60.0",
     "spa-ssi": "0.0.27",
-    "@types/node": "25.6.2",
+    "@types/node": "25.7.0",
     "typescript": "6.0.3"
   }
 }