assign-gingerly 0.0.16 → 0.0.18

package/README.md

@@ -23,8 +23,14 @@ One can achieve the same functionality with a little more work, and "playing nic
 
 Not only does this polyfill package allow merging data properties onto objects that are expecting them, this polyfill also provides the ability to merge *augmented behavior* onto run-time objects without sub classing all such objects of the same type. This includes the ability to spawn an instance of a class and "merge" it into the API of the original object in an elegant way that is easy to wrap one's brain around, without ever blocking access to the original object or breaking it.
 
+
+
 So we are providing a form of the ["Decorator Pattern"](https://en.wikipedia.org/wiki/Decorator_pattern) or perhaps more accurately the [Extension Object Pattern](https://swiftorial.com/swiftlessons/design-patterns/structural-patterns/extension-object-pattern) as tailored for the quirks of the web.  
 
+## Custom Enhancement Registry
+
+On top of that, this polyfill package builds on the newly minted Custom Element Registry, adding an additional EnhancementRegistry object on top of the customElementRegistry object associated with all elements, to be able to manage namespace conflicts, and, importantly, as a basis for defining custom attributes associated with the enhancements.
+
 So in our view this package helps fill the void left by not supporting the "is" attribute for built-in elements (but is not a complete solution, just a critical building block).  Mount-observer, mount-observer-script-element, and custom enhancements builds on top of the critical role that assign-gingerly plays.
 
 Anyway, let's start out detailing the more innocent features of this package / polyfill.
@@ -33,7 +39,7 @@ The two utility functions are:
 
 ## assignGingerly
 
-assignGingerly builds on Object.assign.  Like Object.assign, the object getting assigned can be a JSON stringified object.  Some of the unusual syntax we see with assignGingerly is there to continue to support JSON deserialized objects as a viable argument to be passed.  
+assignGingerly builds on Object.assign.  Like Object.assign, the object getting assigned can often be a JSON stringified object.  Some of the unusual syntax we see with assignGingerly is there to continue to support JSON deserialized objects as a viable argument to be passed.  
 
 assign-gingerly adds support for:
 
@@ -96,7 +102,9 @@ console.log(obj);
 
 When the right hand side of an expression is an object, assignGingerly is recursively applied (passing the third argument in if applicable, which will be discussed below).
 
-While we are in the business of passing values of object A into object B, we might as well add some extremely common behavior that allows updating properties of object B based on the current values of object B -- things like incrementing, toggling, and deleting.  Deleting is critical for assignTentatively, but is included with both functions
+Of course, just as Object.assign led to object spread notation, assignGingerly could lead to some sort of deep structural JavaScript syntax, but that is outside the scope of this polyfill package. 
+
+While we are in the business of passing values of object A into object B, we might as well add some extremely common behavior that allows updating properties of object B based on the current values of object B -- things like incrementing, toggling, and deleting.  Deleting is critical for assignTentatively, but is included with both functions.
 
 ## Example 4 - Incrementing values with += command
 
@@ -213,8 +221,7 @@ console.log(obj);
 - Non-existent properties are silently skipped
 - If the parent path doesn't exist, the command is silently skipped
 - For root-level deletion, use ` -=` (space before -=)
-//   }
-// }
+
 
 
 
@@ -285,9 +292,9 @@ This guarantees that applying the reversal object restores the object to its exa
 ## Dependency injection based on a registry object and a Symbolic reference mapping
 
 ```Typescript
-interface IBaseRegistryItem<T = any> {
-    spawn: {new(): T} | Promise<{new(): T}>
-    symlinks: {[key: symbol]: keyof T}
+interface IBaseRegistryItem<T = any, TObjToExtend = any> {
+    spawn: {new(objToExtend: TObjToExtend, ctx: SpawnContext, initVals: Partial<T>): T}
+    symlinks?: {[key: symbol]: keyof T}
     // Optional: for element enhancement access
     enhKey?: string
     // Optional: automatic attribute parsing 
@@ -508,6 +515,9 @@ The prototype extensions are non-enumerable and won't appear in `Object.keys()`
 
 This package includes support for Chrome's scoped custom element registries, which automatically integrates dependency injection in harmony with scoped custom elements DOM sections or ShadowRoots.
 
+> [!NOTE]
+> Safari/WebKit played a critical role in pushing scoped custom element registries forward, and announced with little fanfare or documentation that [Safari 26 supports it](https://developer.apple.com/documentation/safari-release-notes/safari-26-release-notes).  However, the Playwright test machinery's cross platform Safari test browser doesn't yet support it.
+
 <details>
   <summary>Automatic Registry Population</summary>
 
@@ -515,7 +525,6 @@ When `assignGingerly` or `assignTentatively` is called on an Element instance wi
 
 ```TypeScript
 import 'assign-gingerly/object-extension.js';
-import { BaseRegistry } from 'assign-gingerly';
 
 // Set up a registry on the custom element registry
 const myElement = document.createElement('div');
@@ -649,7 +658,7 @@ This approach is part of a proposal to WHATWG for standardizing element enhancem
 
 ### Constructor Signature
 
-Enhancement classes should follow this constructor signature:
+Element enhancement classes should follow this constructor signature:
 
 ```TypeScript
 interface SpawnContext<T, TMountContext = any> {
@@ -657,7 +666,7 @@ interface SpawnContext<T, TMountContext = any> {
   mountCtx?: TMountContext;  // Optional custom context passed by caller
 }
 
-class Enhancement {
+class Enhancement<T> {
   constructor(
     oElement?: Element,      // The element being enhanced
     ctx?: SpawnContext,      // Context with registry item info and optional mountCtx
@@ -671,6 +680,8 @@ class Enhancement {
 
 All parameters are optional for backward compatibility with existing code.
 
+Note that the class need not extend any base class or leverage any mixins.  In fact, ES5 prototype functions can be used, and in both cases are instanted using new ....  Arrow functions cannot be used.
+
 <details>
 <summary>Passing Custom Context</summary>
 
@@ -705,10 +716,10 @@ This is useful for:
 In addition to spawn and symlinks, registry items support optional properties `enhKey`, `withAttrs`, `canSpawn`, and `lifecycleKeys`:
 
 ```TypeScript
-interface IBaseRegistryItem<T> {
+interface IBaseRegistryItem<T, TObj = Element> {
   spawn: { 
-    new (oElement?: Element, ctx?: SpawnContext<T>, initVals?: Partial<T>): T;
-    canSpawn?: (obj: any, ctx?: SpawnContext<T>) => boolean;  // Optional spawn guard
+    new (obj?: TObj, ctx?: SpawnContext<T>, initVals?: Partial<T>): T;
+    canSpawn?: (obj: TObj, ctx?: SpawnContext<T>) => boolean;  // Optional spawn guard
   };
   symlinks?: { [key: string | symbol]: keyof T };
   enhKey?: string;  // String identifier for set proxy access
@@ -818,7 +829,7 @@ console.log(item.enhKey); // 'myEnh'
 
 ### Programmatic Instance Spawning with `enh.get()`
 
-The `enh.get(registryItem)` method provides a programmatic way to spawn or retrieve enhancement instances:
+The `enh.get(registryItem)` method provides a programmatic way to spawn or retrieve previously instantiated enhancement instances:
 
 ```TypeScript
 const registryItem = {
@@ -948,9 +959,9 @@ Note: Symbol event names are not yet supported by the platform but have been req
 
 </details>
 
-### Disposing Enhancement Instances with `enh.dispose()`
+### Disposing Enhancement Instances with `enh.dispose(regItem)`
 
-The `enh.dispose()` method provides a way to clean up and remove enhancement instances:
+The `enh.dispose(regItem)` method provides a way to clean up and remove enhancement instances:
 
 ```TypeScript
 class MyEnhancement {
@@ -991,7 +1002,7 @@ const instance = element.enh.get(registryItem);
 element.enh.dispose(registryItem);
 ```
 
-**How `enh.dispose()` works:**
+**How `enh.dispose(regItem)` works:**
 
 1. **Retrieves instance**: Gets the spawned instance from the global instance map
 2. **Calls lifecycle method**: If `lifecycleKeys.dispose` is specified, calls that method on the instance (passing the registry item)
@@ -1043,9 +1054,9 @@ 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
 
-### Waiting for Async Initialization with `enh.whenResolved()`
+### Waiting for Async Initialization with `enh.whenResolved(regItem)`
 
-The `enh.whenResolved()` method provides a way to wait for asynchronous enhancement initialization:
+The `enh.whenResolved(regItem)` method provides a way to wait for asynchronous enhancement initialization:
 
 ```TypeScript
 class AsyncEnhancement extends EventTarget {
@@ -1351,11 +1362,11 @@ assignGingerly(element, { [enhSymbol]: 'test' }, { registry });
 
 ## Parsing Attributes with `parseWithAttrs`
 
-The `parseWithAttrs` function provides a declarative way to read and parse HTML attributes into structured data objects. It's particularly useful for custom elements and web components that need to extract configuration from attributes.
+The `parseWithAttrs` function provides a declarative way to read and parse HTML attributes and pass the parsed values into the spawned enhancement constructor. 
 
 ### Automatic Integration with Enhancement Spawning
 
-**Important**: When using the `enh.get()`, `enh.set`, or `assignGingerly()` methods with registry items, you typically **do not need to call `parseWithAttrs()` manually**. The attribute parsing happens automatically during enhancement spawning when you include a `withAttrs` property in your registry item.
+**Important**: When using the `enh.get()`, `enh.set`, or `assignGingerly()` methods with registry items, you typically **do not need to call `parseWithAttrs()` manually**. The attribute parsing happens automatically during enhancement spawning when you include a `withAttrs` property in your registry item configuration.
 
 ```html
 <my-element my-enhancement-count="42" my-enhancement-theme="dark"></my-element>
@@ -1747,6 +1758,8 @@ const result = parseWithAttrs(element, config);
 
 **Built-in Named Parsers:**
 
+[TODO]: Check if this is all needed
+
 The following parsers are pre-registered in `globalParserRegistry`:
 
 - `'timestamp'` - Parses ISO date string to Unix timestamp (milliseconds)
@@ -2206,6 +2219,21 @@ console.log(query);
 const elements = document.querySelectorAll(query);
 ```
 
+**Without selectors (matches any element):**
+
+```TypeScript
+// Omit the selectors parameter
+const query = buildCSSQuery(config);
+// or explicitly pass empty string
+const query = buildCSSQuery(config, '');
+
+console.log(query);
+// '[my-component], [enh-my-component], [my-component-theme], [enh-my-component-theme]'
+
+// Matches any element with these attributes
+const elements = document.querySelectorAll(query);
+```
+
 ### How It Works
 
 `buildCSSQuery` creates a cross-product of:
@@ -2289,11 +2317,27 @@ buildCSSQuery(config, 'div');
 
 ### Edge Cases
 
-**Empty inputs return empty string:**
+**Omitting or empty selectors return attribute-only selectors:**
+```TypeScript
+const config = {
+  spawn: MyClass,
+  withAttrs: {
+    base: 'my-attr',
+    theme: '${base}-theme'
+  }
+};
+
+buildCSSQuery(config);  // Omit selectors parameter
+// or
+buildCSSQuery(config, '');  // Empty string
+// Both return: '[my-attr], [enh-my-attr], [my-attr-theme], [enh-my-attr-theme]'
+// Matches any element with these attributes
+```
+
+**Empty withAttrs returns empty string:**
 ```TypeScript
 buildCSSQuery({ spawn: MyClass }, 'div');  // '' (no withAttrs)
 buildCSSQuery({ spawn: MyClass, withAttrs: {} }, 'div');  // '' (empty withAttrs)
-buildCSSQuery({ spawn: MyClass, withAttrs: { base: 'x' } }, '');  // '' (empty selectors)
 ```
 
 **Deduplication:**
@@ -2312,14 +2356,15 @@ buildCSSQuery(config, '  div  ,  span  ,  p  ');
 
 1. **Mount Observer Integration**: Find elements that need enhancement
    ```TypeScript
-   const query = buildCSSQuery(enhancementConfig, '*');
+   // Match any element with the attributes
+   const query = buildCSSQuery(enhancementConfig);
    const observer = new MutationObserver(() => {
      const elements = document.querySelectorAll(query);
      elements.forEach(el => enhance(el));
    });
    ```
 
-2. **Batch Enhancement**: Enhance all matching elements at once
+2. **Specific Element Types**: Enhance only certain element types
    ```TypeScript
    const query = buildCSSQuery(config, 'template, script');
    document.querySelectorAll(query).forEach(el => {
@@ -2338,17 +2383,20 @@ buildCSSQuery(config, '  div  ,  span  ,  p  ');
 ```TypeScript
 function buildCSSQuery(
   config: EnhancementConfig,
-  selectors: string
+  selectors?: string
 ): string
 ```
 
 **Parameters:**
 - `config`: Enhancement configuration with `withAttrs` property
-- `selectors`: Comma-separated CSS selectors (e.g., `'div, span'`)
+- `selectors` (optional): Comma-separated CSS selectors (e.g., `'div, span'`)
+  - If omitted or empty string, returns attribute selectors without element prefix
+  - This matches any element with the specified attributes
 
 **Returns:**
 - CSS query string with cross-product of selectors and attributes
-- Empty string if `withAttrs` is missing or empty
+- If selectors is omitted or empty: returns attribute-only selectors (e.g., `'[attr], [enh-attr]'`)
+- If withAttrs is missing or empty: returns empty string
 
 **Throws:**
 - Error if template variables have circular references

package/buildCSSQuery.js

@@ -64,7 +64,8 @@ function extractAttributeNames(withAttrs) {
  * Creates a cross-product of selectors and attribute names (both prefixed and unprefixed)
  *
  * @param config - Enhancement configuration with withAttrs
- * @param selectors - Comma-separated CSS selectors to match (e.g., 'template, script')
+ * @param selectors - Optional comma-separated CSS selectors to match (e.g., 'template, script')
+ *                    If omitted or empty, returns just the attribute selectors without element prefix
  * @returns CSS query string with cross-product of selectors and attributes
  *
  * @example
@@ -76,36 +77,49 @@ function extractAttributeNames(withAttrs) {
  *   }
  * };
  *
+ * // With selectors
  * buildCSSQuery(config, 'div, span');
  * // Returns: 'div[my-attr], span[my-attr], div[enh-my-attr], span[enh-my-attr],
  * //           div[my-attr-theme], span[my-attr-theme], div[enh-my-attr-theme], span[enh-my-attr-theme]'
+ *
+ * // Without selectors (matches any element)
+ * buildCSSQuery(config);
+ * // or
+ * buildCSSQuery(config, '');
+ * // Returns: '[my-attr], [enh-my-attr], [my-attr-theme], [enh-my-attr-theme]'
  */
 export function buildCSSQuery(config, selectors) {
     // Validate inputs
-    if (!config.withAttrs || !selectors) {
-        return '';
-    }
-    // Parse and normalize selectors
-    const selectorList = selectors
-        .split(',')
-        .map(s => s.trim())
-        .filter(s => s.length > 0);
-    if (selectorList.length === 0) {
+    if (!config.withAttrs) {
         return '';
     }
-    // Extract and resolve attribute names
+    // Extract and resolve attribute names first
     const attrNames = extractAttributeNames(config.withAttrs);
     if (attrNames.length === 0) {
         return '';
     }
-    // Build cross-product of selectors × attributes × prefixes
+    // Parse and normalize selectors
+    const selectorList = selectors
+        ? selectors.split(',').map(s => s.trim()).filter(s => s.length > 0)
+        : [];
+    // Build queries
     const queries = [];
-    for (const selector of selectorList) {
+    if (selectorList.length === 0) {
+        // No selectors provided - return just attribute selectors
         for (const attrName of attrNames) {
-            // Unprefixed version
-            queries.push(`${selector}[${attrName}]`);
-            // enh- prefixed version
-            queries.push(`${selector}[enh-${attrName}]`);
+            queries.push(`[${attrName}]`);
+            queries.push(`[enh-${attrName}]`);
+        }
+    }
+    else {
+        // Build cross-product of selectors × attributes × prefixes
+        for (const selector of selectorList) {
+            for (const attrName of attrNames) {
+                // Unprefixed version
+                queries.push(`${selector}[${attrName}]`);
+                // enh- prefixed version
+                queries.push(`${selector}[enh-${attrName}]`);
+            }
         }
     }
     // Deduplicate and join

package/buildCSSQuery.ts

@@ -82,7 +82,8 @@ function extractAttributeNames(withAttrs: AttrPatterns<any>): string[] {
  * Creates a cross-product of selectors and attribute names (both prefixed and unprefixed)
  * 
  * @param config - Enhancement configuration with withAttrs
- * @param selectors - Comma-separated CSS selectors to match (e.g., 'template, script')
+ * @param selectors - Optional comma-separated CSS selectors to match (e.g., 'template, script')
+ *                    If omitted or empty, returns just the attribute selectors without element prefix
  * @returns CSS query string with cross-product of selectors and attributes
  * 
  * @example
@@ -94,45 +95,56 @@ function extractAttributeNames(withAttrs: AttrPatterns<any>): string[] {
  *   }
  * };
  * 
+ * // With selectors
  * buildCSSQuery(config, 'div, span');
  * // Returns: 'div[my-attr], span[my-attr], div[enh-my-attr], span[enh-my-attr], 
  * //           div[my-attr-theme], span[my-attr-theme], div[enh-my-attr-theme], span[enh-my-attr-theme]'
+ * 
+ * // Without selectors (matches any element)
+ * buildCSSQuery(config);
+ * // or
+ * buildCSSQuery(config, '');
+ * // Returns: '[my-attr], [enh-my-attr], [my-attr-theme], [enh-my-attr-theme]'
  */
 export function buildCSSQuery(
     config: EnhancementConfig,
-    selectors: string
+    selectors?: string
 ): string {
     // Validate inputs
-    if (!config.withAttrs || !selectors) {
+    if (!config.withAttrs) {
         return '';
     }
     
-    // Parse and normalize selectors
-    const selectorList = selectors
-        .split(',')
-        .map(s => s.trim())
-        .filter(s => s.length > 0);
-    
-    if (selectorList.length === 0) {
-        return '';
-    }
-    
-    // Extract and resolve attribute names
+    // Extract and resolve attribute names first
     const attrNames = extractAttributeNames(config.withAttrs);
     
     if (attrNames.length === 0) {
         return '';
     }
     
-    // Build cross-product of selectors × attributes × prefixes
+    // Parse and normalize selectors
+    const selectorList = selectors
+        ? selectors.split(',').map(s => s.trim()).filter(s => s.length > 0)
+        : [];
+    
+    // Build queries
     const queries: string[] = [];
     
-    for (const selector of selectorList) {
+    if (selectorList.length === 0) {
+        // No selectors provided - return just attribute selectors
         for (const attrName of attrNames) {
-            // Unprefixed version
-            queries.push(`${selector}[${attrName}]`);
-            // enh- prefixed version
-            queries.push(`${selector}[enh-${attrName}]`);
+            queries.push(`[${attrName}]`);
+            queries.push(`[enh-${attrName}]`);
+        }
+    } else {
+        // Build cross-product of selectors × attributes × prefixes
+        for (const selector of selectorList) {
+            for (const attrName of attrNames) {
+                // Unprefixed version
+                queries.push(`${selector}[${attrName}]`);
+                // enh- prefixed version
+                queries.push(`${selector}[enh-${attrName}]`);
+            }
         }
     }
     

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "assign-gingerly",
-  "version": "0.0.16",
+  "version": "0.0.18",
   "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/assign-gingerly/types.d.ts

@@ -25,16 +25,18 @@ type DisposeEvent =
     //reference count outside any enhancements goes to zero
     | 'dispose'
 
+export type Spawner<T = any, Obj = Element> = {
+  new (obj?: Obj, ctx?: SpawnContext<T>, initVals?: Partial<T>): T;
+  canSpawn?: (obj: any, ctx?: SpawnContext<T>) => boolean;
+}
+
 /**
  * Configuration for enhancing elements with class instances
  * Defines how to spawn and initialize enhancement classes
  */
-export interface EnhancementConfig<T = any> {
+export interface EnhancementConfig<T = any, Obj = Element> {
   
-  spawn: { 
-    new (obj?: any, ctx?: SpawnContext<T>, initVals?: Partial<T>): T;
-    canSpawn?: (obj: any, ctx?: SpawnContext<T>) => boolean;
-  };
+  spawn: Spawner<T, Obj>;
   
   //Applicable to passing in the initVals during the spawn lifecycle event
   withAttrs?: AttrPatterns<T>;
@@ -180,3 +182,11 @@ export declare function assignGingerly(
 ): any;
 
 export default assignGingerly;
+
+export declare class ElementEnhancementGateway{
+  enh: ElementEnhancement;
+}
+
+export interface ElementEnhancement{
+  dispose(regItem: EnhancementConfig): void;
+}