assign-gingerly 0.0.17 → 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)
@@ -2209,7 +2222,11 @@ 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]'
 
@@ -2300,7 +2317,7 @@ buildCSSQuery(config, 'div');
 
 ### Edge Cases
 
-**Empty selectors return attribute-only selectors:**
+**Omitting or empty selectors return attribute-only selectors:**
 ```TypeScript
 const config = {
   spawn: MyClass,
@@ -2310,8 +2327,10 @@ const config = {
   }
 };
 
-buildCSSQuery(config, '');
-// '[my-attr], [enh-my-attr], [my-attr-theme], [enh-my-attr-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
 ```
 
@@ -2338,7 +2357,7 @@ buildCSSQuery(config, '  div  ,  span  ,  p  ');
 1. **Mount Observer Integration**: Find elements that need enhancement
    ```TypeScript
    // Match any element with the attributes
-   const query = buildCSSQuery(enhancementConfig, '');
+   const query = buildCSSQuery(enhancementConfig);
    const observer = new MutationObserver(() => {
      const elements = document.querySelectorAll(query);
      elements.forEach(el => enhance(el));
@@ -2364,19 +2383,19 @@ 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'`)
-  - If empty string or whitespace only, returns attribute selectors without element prefix
+- `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
-- If selectors is empty: returns attribute-only selectors (e.g., `'[attr], [enh-attr]'`)
+- 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:**

package/buildCSSQuery.js

@@ -64,8 +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')
- *                    If empty, returns just the attribute selectors without element prefix
+ * @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
@@ -83,6 +83,8 @@ function extractAttributeNames(withAttrs) {
  * //           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]'
  */

package/buildCSSQuery.ts

@@ -82,8 +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')
- *                    If empty, returns just the attribute selectors without element prefix
+ * @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
@@ -101,12 +101,14 @@ function extractAttributeNames(withAttrs: AttrPatterns<any>): string[] {
  * //           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) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "assign-gingerly",
-  "version": "0.0.17",
+  "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;
+}