assign-gingerly 0.0.6 → 0.0.7

package/README.md

@@ -282,8 +282,8 @@ baseRegistry.push([
 const result = assignGingerly({}, {
     [isHappy]: true,
     [isMellow]: true,
-    '?.style.height': '40px',
-    '?.enhancements?.mellowYellow?.madAboutFourteen': true
+    '?.style?.height': '40px',
+    '?.enh?.mellowYellow?.madAboutFourteen': true
 }, {
     registry: BaseRegistry
 });
@@ -292,7 +292,7 @@ result.set[isMellow] = false;
 
 The assignGingerly searches the registry for any items that has a mapping with a matching symbol of isHappy and isMellow, and if found, sees if it already has an instance of the spawn class associated with the first passed in parameter.  If no such instance is found, it instantiates one, associates the instance with the first parameter, then sets the property value.
 
-It also adds a lazy property to the first passed in parameter, "set", which returns a proxy, and that proxy watches for symbol references passed in a value, and sets the value from that spawned instance.  Again, if the spawned instance is not found, it respawns it.
+It also adds a lazy property to the first passed in parameter, "set", which returns a proxy, and that proxy watches for symbol references passed in a value, and sets the value from that spawned instance.  Again, if the spawned instance is not found, it re-spawns it.
 
 The suggestion to use Symbol.for with a guid, as opposed to just Symbol(), is based on some negative experiences I've had with multiple versions of the same library being referenced, but is not required. Regular symbols could also be used when that risk can be avoided.
 
@@ -303,7 +303,7 @@ const result = assignGingerly({}, {
     "[Symbol.for('TFWsx0YH5E6eSfhE7zfLxA')]": true,
     "[Symbol.for('BqnnTPWRHkWdVGWcGQoAiw')]": true,
     '?.style.height': '40px',
-    '?.enhancements?.mellowYellow?.madAboutFourteen': true
+    '?.enh?.mellowYellow?.madAboutFourteen': true
 }, {
     registry: BaseRegistry
 });
@@ -406,3 +406,182 @@ myElement.assignGingerly({
 ```
 
 **Browser Support**: This feature requires Chrome 146+ with scoped custom element registry support. The implementation is designed as a polyfill for the web standards proposal and does not include fallback behavior for older browsers.
+
+## Enhanced Element Property Assignment with `set` Proxy (Chrome 146+)
+
+Building on the Custom Element Registry integration, this package provides a powerful `set` proxy on all Element instances that enables automatic enhancement spawning and simplified property assignment syntax.
+
+### Basic Usage
+
+The `set` proxy allows you to assign properties to enhancements using a clean, chainable syntax:
+
+```TypeScript
+import 'assign-gingerly/object-extension.js';
+import { BaseRegistry } from 'assign-gingerly';
+
+// Define an enhancement class
+class MyEnhancement {
+  element;
+  ctx;
+  myProp = null;
+  anotherProp = null;
+
+  constructor(oElement, ctx, initVals) {
+    this.element = oElement;
+    this.ctx = ctx;
+    if (initVals) {
+      Object.assign(this, initVals);
+    }
+  }
+}
+
+// Register the enhancement with an enhKey
+const myElement = document.createElement('div');
+const registry = myElement.customElementRegistry.assignGingerlyRegistry;
+
+registry.push({
+  spawn: MyEnhancement,
+  map: {},
+  enhKey: 'myEnh'  // Key identifier for this enhancement
+});
+
+// Use the set proxy to automatically spawn and assign properties
+myElement.set.myEnh.myProp = 'hello';
+myElement.set.myEnh.anotherProp = 'world';
+
+console.log(myElement.myEnh instanceof MyEnhancement); // true
+console.log(myElement.myEnh.myProp); // 'hello'
+console.log(myElement.myEnh.element === myElement); // true
+```
+
+### How It Works
+
+When you access `element.set.enhKey.property`, the proxy:
+
+1. **Checks the registry**: Looks for a registry item with `enhKey` matching the property name
+2. **Spawns if needed**: If found and the enhancement doesn't exist or is the wrong type:
+   - Creates a `SpawnContext` with `{ mountInfo: registryItem }`
+   - Calls the constructor with `(element, ctx, initVals)`
+   - If a non-matching object already exists at `element[enhKey]`, it's passed as `initVals`
+   - Stores the spawned instance at `element[enhKey]`
+3. **Reuses existing instances**: If the enhancement already exists and is the correct type, it reuses it
+4. **Falls back to plain objects**: If no registry item is found, creates a plain object at `element[enhKey]`
+
+### Constructor Signature
+
+Enhancement classes should follow this constructor signature:
+
+```TypeScript
+interface SpawnContext<T> {
+  mountInfo: IBaseRegistryItem<T>;
+}
+
+class Enhancement {
+  constructor(
+    oElement?: Element,      // The element being enhanced
+    ctx?: SpawnContext,      // Context with registry item info
+    initVals?: Partial<T>    // Initial values if property existed
+  ) {
+    // Your initialization logic
+  }
+}
+```
+
+All parameters are optional for backward compatibility with existing code.
+
+### Registry Item with enhKey
+
+Registry items now support an optional `enhKey` property:
+
+```TypeScript
+interface IBaseRegistryItem<T> {
+  spawn: { new (oElement?: Element, ctx?: SpawnContext<T>, initVals?: Partial<T>): T };
+  map: { [key: string | symbol]: keyof T };
+  enhKey?: string;  // String identifier for set proxy access
+}
+```
+
+### Advanced Examples
+
+**Multiple Enhancements:**
+```TypeScript
+class StyleEnhancement {
+  constructor(oElement, ctx, initVals) {
+    this.element = oElement;
+  }
+  height = null;
+  width = null;
+}
+
+class DataEnhancement {
+  constructor(oElement, ctx, initVals) {
+    this.element = oElement;
+  }
+  value = null;
+}
+
+const element = document.createElement('div');
+const registry = element.customElementRegistry.assignGingerlyRegistry;
+
+registry.push([
+  { spawn: StyleEnhancement, map: {}, enhKey: 'styles' },
+  { spawn: DataEnhancement, map: {}, enhKey: 'data' }
+]);
+
+element.set.styles.height = '100px';
+element.set.data.value = 'test';
+
+console.log(element.styles instanceof StyleEnhancement); // true
+console.log(element.data instanceof DataEnhancement); // true
+```
+
+**Preserving Existing Data with initVals:**
+```TypeScript
+const element = document.createElement('div');
+const registry = element.customElementRegistry.assignGingerlyRegistry;
+
+registry.push({
+  spawn: MyEnhancement,
+  map: {},
+  enhKey: 'config'
+});
+
+// Set a plain object first
+element.config = { existingProp: 'preserved', anotherProp: 'also preserved' };
+
+// Access via set proxy - spawns enhancement with initVals
+element.set.config.newProp = 'added';
+
+console.log(element.config instanceof MyEnhancement); // true
+console.log(element.config.existingProp); // 'preserved'
+console.log(element.config.newProp); // 'added'
+```
+
+**Plain Objects Without Registry:**
+```TypeScript
+const element = document.createElement('div');
+
+// No registry item for 'plainData' - creates plain object
+element.set.plainData.prop1 = 'value1';
+element.set.plainData.prop2 = 'value2';
+
+console.log(element.plainData); // { prop1: 'value1', prop2: 'value2' }
+```
+
+### Finding Registry Items by enhKey
+
+The `BaseRegistry` class includes a `findByEnhKey` method:
+
+```TypeScript
+const registry = new BaseRegistry();
+registry.push({
+  spawn: MyEnhancement,
+  map: {},
+  enhKey: 'myEnh'
+});
+
+const item = registry.findByEnhKey('myEnh');
+console.log(item.enhKey); // 'myEnh'
+```
+
+**Browser Support**: This feature requires Chrome 146+ with scoped custom element registry support.

package/assignGingerly.js

@@ -29,6 +29,9 @@ export class BaseRegistry {
             }) || Object.getOwnPropertySymbols(map).some(sym => sym === symbol);
         });
     }
+    findByEnhKey(enhKey) {
+        return this.items.find(item => item.enhKey === enhKey);
+    }
 }
 /**
  * Helper function to check if a string key represents a Symbol.for expression

package/assignGingerly.ts

@@ -2,11 +2,15 @@
  * Interface for registry items that define dependency injection mappings
  */
 export interface IBaseRegistryItem<T = any> {
-  spawn: { new (): T };
+  spawn: { new (oElement?: Element, ctx?: SpawnContext<T>, initVals?: Partial<T>): T };
   map: { [key: string | symbol]: keyof T };
   enhKey?: string;
 }
 
+export interface SpawnContext<T = any> {
+  mountInfo: IBaseRegistryItem<T>;
+}
+
 /**
  * Interface for the options passed to assignGingerly
  */
@@ -48,6 +52,10 @@ export class BaseRegistry {
       }) || Object.getOwnPropertySymbols(map).some(sym => sym === symbol);
     });
   }
+
+  findByEnhKey(enhKey: string | symbol): IBaseRegistryItem | undefined {
+    return this.items.find(item => item.enhKey === enhKey);
+  }
 }
 
 /**

package/object-extension.js

@@ -20,6 +20,62 @@ if (typeof CustomElementRegistry !== 'undefined') {
         configurable: true,
     });
 }
+/**
+ * Adds 'set' proxy to Element prototype for enhanced property assignment
+ * Supports automatic spawning of enhancement classes based on registry
+ */
+if (typeof Element !== 'undefined') {
+    const setProxyWeakMap = new WeakMap();
+    Object.defineProperty(Element.prototype, 'set', {
+        get: function () {
+            if (!setProxyWeakMap.has(this)) {
+                const self = this;
+                const proxy = new Proxy(self, {
+                    get(obj, prop) {
+                        // Get the registry from customElementRegistry
+                        const registry = self.customElementRegistry?.assignGingerlyRegistry;
+                        if (registry) {
+                            // Check if there's a registry item with matching enhKey
+                            const registryItem = registry.findByEnhKey(prop);
+                            if (registryItem) {
+                                const SpawnClass = registryItem.spawn;
+                                // Check if enhancement already exists and is correct instance
+                                if (self[prop] && self[prop] instanceof SpawnClass) {
+                                    // Already exists, just return it
+                                    return self[prop];
+                                }
+                                else {
+                                    // Need to spawn
+                                    let initVals = undefined;
+                                    // If property exists but isn't the right instance, pass it as initVals
+                                    if (self[prop] && !(self[prop] instanceof SpawnClass)) {
+                                        initVals = self[prop];
+                                    }
+                                    // Create spawn context
+                                    const ctx = { mountInfo: registryItem };
+                                    // Spawn the instance
+                                    const instance = new SpawnClass(self, ctx, initVals);
+                                    // Set it on the element
+                                    self[prop] = instance;
+                                    return instance;
+                                }
+                            }
+                        }
+                        // No registry item found - create plain object if needed
+                        if (self[prop] === undefined) {
+                            self[prop] = {};
+                        }
+                        return self[prop];
+                    }
+                });
+                setProxyWeakMap.set(this, proxy);
+            }
+            return setProxyWeakMap.get(this);
+        },
+        enumerable: true,
+        configurable: true,
+    });
+}
 /**
  * Adds assignGingerly method to all objects via the Object prototype
  */

package/object-extension.ts

@@ -79,6 +79,75 @@ if (typeof CustomElementRegistry !== 'undefined') {
   });
 }
 
+/**
+ * Adds 'set' proxy to Element prototype for enhanced property assignment
+ * Supports automatic spawning of enhancement classes based on registry
+ */
+if (typeof Element !== 'undefined') {
+  const setProxyWeakMap = new WeakMap<Element, ProxyHandler<Element>>();
+  
+  Object.defineProperty(Element.prototype, 'set', {
+    get: function (this: Element) {
+      if (!setProxyWeakMap.has(this)) {
+        const self = this;
+        const proxy = new Proxy(self, {
+          get(obj: any, prop: string | symbol) {
+            // Get the registry from customElementRegistry
+            const registry = (self as any).customElementRegistry?.assignGingerlyRegistry;
+            
+            if (registry) {
+              // Check if there's a registry item with matching enhKey
+              const registryItem = registry.findByEnhKey(prop);
+              
+              if (registryItem) {
+                const SpawnClass = registryItem.spawn;
+                
+                // Check if enhancement already exists and is correct instance
+                if (self[prop as any] && self[prop as any] instanceof SpawnClass) {
+                  // Already exists, just return it
+                  return self[prop as any];
+                } else {
+                  // Need to spawn
+                  let initVals: any = undefined;
+                  
+                  // If property exists but isn't the right instance, pass it as initVals
+                  if (self[prop as any] && !(self[prop as any] instanceof SpawnClass)) {
+                    initVals = self[prop as any];
+                  }
+                  
+                  // Create spawn context
+                  const ctx = { mountInfo: registryItem };
+                  
+                  // Spawn the instance
+                  const instance = new SpawnClass(self, ctx, initVals);
+                  
+                  // Set it on the element
+                  (self as any)[prop] = instance;
+                  
+                  return instance;
+                }
+              }
+            }
+            
+            // No registry item found - create plain object if needed
+            if (self[prop as any] === undefined) {
+              (self as any)[prop] = {};
+            }
+            
+            return self[prop as any];
+          }
+        });
+        
+        setProxyWeakMap.set(this, proxy);
+      }
+      
+      return setProxyWeakMap.get(this);
+    },
+    enumerable: true,
+    configurable: true,
+  });
+}
+
 /**
  * Adds assignGingerly method to all objects via the Object prototype
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "assign-gingerly",
-  "version": "0.0.6",
+  "version": "0.0.7",
   "description": "This package provides a utility function for carefully merging one object into another.",
   "homepage": "https://github.com/bahrus/assign-gingerly#readme",
   "bugs": {

package/types.d.ts

@@ -1,9 +1,16 @@
+export type EnhKey = string | symbol;
+
 /**
  * Interface for registry items that define dependency injection mappings
  */
 export interface IBaseRegistryItem<T = any> {
-  spawn: { new (): T } | Promise<{ new (): T }>;
+  spawn: { new (oElement?: Element, ctx?: SpawnContext<T>, initVals?: Partial<T>): T  };
   map: { [key: string | symbol]: keyof T };
+  enhKey?: EnhKey;
+}
+
+export interface SpawnContext<T = any> {
+  mountInfo: IBaseRegistryItem<T>;
 }
 
 /**
@@ -21,6 +28,7 @@ export declare class BaseRegistry {
   push(items: IBaseRegistryItem | IBaseRegistryItem[]): void;
   getItems(): IBaseRegistryItem[];
   findBySymbol(symbol: symbol | string): IBaseRegistryItem | undefined;
+  findByEnhKey(enhKey: string | symbol): IBaseRegistryItem | undefined;
 }
 
 /**