assign-gingerly 0.0.22 → 0.0.23

package/README.md

@@ -23,13 +23,17 @@ 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 Registries
 
-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.  
+On top of that, this polyfill package builds on the newly minted Custom Element Registry, adding additional sub-registries:
+
+1.  [enhancementRegistry](#enhancement-registry-addendum-to-the-custom-element-registry) object on top of the customElementRegistry object associated with all elements, to be able to lazy load object extensions on demand while avoiding namespace conflicts, and, importantly, as a basis for defining custom attributes associated with the enhancements.
 
-## Custom Enhancement Registry
+2.  [itemscopeRegistry for Itemscope Managers](#itemscoperegistry) to automatically associate a function prototype or class instance with the itemscope attribute of an HTMLElement.
 
-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.
+3.  Custom Element Features [TODO]
 
 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.
 
@@ -296,7 +300,7 @@ interface IEnhancementRegistryItem<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
+    enhKey?: string | symbol
     // Optional: automatic attribute parsing 
     withAttrs?: AttrPatterns<T>  
 }
@@ -332,7 +336,7 @@ EnhancementRegistry.push([
         },
         spawn: MyEnhancement,
     },{
-       
+       enhKey: 'mellowYellow',
        symlinks: {
            [isMellow]: 'isMellow'
        },
@@ -511,12 +515,16 @@ The prototype extensions are non-enumerable and won't appear in `Object.keys()`
 
 -->
 
-## Custom Element Registry Integration (Chrome 146+)
+## Enhancement Registry Addendum to the Custom Element Registry
 
-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.
+This package polyfill adds an "enhancementRegistry" registry on the CustomElementRegistry prototype.
+
+In this way, we achieve dependency injection in harmony with scoped custom elements DOM registry scope islands.
 
 > [!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.
+> 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.  For now, only Chrome 146+ has been tested / vetted for this functionality.
+>
+> For more information about scoped custom element registries, see [Chrome's announcement and guide](https://developer.chrome.com/blog/scoped-registries).
 
 <details>
   <summary>Automatic Registry Population</summary>
@@ -680,7 +688,7 @@ class Enhancement<T> {
 
 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.
+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 instantiated using new ....  Arrow functions cannot be used.
 
 <details>
 <summary>Passing Custom Context</summary>
@@ -1652,7 +1660,10 @@ interface AttrPatterns<T> {
 interface AttrConfig<T> {
   mapsTo?: keyof T | '.';           // Target property name (or '.' to spread)
   instanceOf?: string | Function;   // Type for default parser
-  parser?: (v: string | null) => any;  // Custom parser function
+  parser?: 
+    | ((v: string | null) => any)   // Inline parser function
+    | string                         // Named parser from globalParserRegistry
+    | [string, string];              // [CustomElementName, StaticMethodName]
 }
 ```
 
@@ -1772,7 +1783,7 @@ The following parsers are pre-registered in `globalParserRegistry`:
 
 **Custom Element Static Method Parsers:**
 
-You can also reference static methods on custom elements using dot notation:
+You can reference static methods on custom elements using tuple syntax `[elementName, methodName]`:
 
 ```TypeScript
 class MyWidget extends HTMLElement {
@@ -1786,29 +1797,47 @@ class MyWidget extends HTMLElement {
 }
 customElements.define('my-widget', MyWidget);
 
-// Reference custom element parsers
+// Reference custom element parsers using tuple syntax
 const config = {
   base: 'data-',
   value: '${base}value',
   _value: {
-    parser: 'my-widget.parseSpecialFormat'  // element-name.methodName
+    parser: ['my-widget', 'parseSpecialFormat']  // [element-name, methodName]
+  },
+  title: '${base}title',
+  _title: {
+    parser: ['my-widget', 'parseWithPrefix']
   }
 };
+
+const result = parseWithAttrs(element, config);
 ```
 
-**Parser Resolution Order:**
+**Parser Resolution:**
+
+When a parser is specified, it can be:
+
+1. **Inline function** - `parser: (v) => v.toUpperCase()` - Used directly
+2. **String reference** - `parser: 'timestamp'` - Looks up in `globalParserRegistry`
+3. **Tuple reference** - `parser: ['my-widget', 'parseMethod']` - Looks up static method on custom element constructor
+
+**Error Handling:**
 
-When a string parser is specified:
+The tuple syntax provides clear error messages:
 
-1. **Check for dot notation** - If parser contains `.`, try to resolve as `element-name.methodName`
-2. **Try custom element** - Look up element in `customElements` registry and check for static method
-3. **Fall back to global registry** - If custom element not found, check `globalParserRegistry`
-4. **Throw error** - If not found anywhere, throw descriptive error
+```TypeScript
+// Element not found
+parser: ['non-existent', 'method']
+// Error: Cannot resolve parser [non-existent, method]: custom element "non-existent" not found
+
+// Method not found
+parser: ['my-widget', 'nonExistent']
+// Error: Cannot resolve parser [my-widget, nonExistent]: static method "nonExistent" not found on custom element "my-widget"
 
-This allows:
-- Element-specific parsers to be scoped to their custom elements
-- Fallback to global registry for shared parsers
-- Dot notation in global registry names (e.g., `'utils.parseDate'`)
+// String not found in registry
+parser: 'unknown'
+// Error: Parser "unknown" not found in globalParserRegistry. If you want to reference a custom element static method, use tuple syntax: ["element-name", "methodName"]
+```
 
 **Example: Organizing Parsers**
 
@@ -2452,6 +2481,414 @@ console.log(result);
 
 -->
 
+## Itemscope Managers (Chrome 146+)
+
+Itemscope Managers provide a way to manage DOM fragments and their associated data/view models for elements with the `itemscope` attribute. This feature enables frameworks and libraries to manage light children of web components, DOM fragments from looping constructs, and scenarios where custom element wrapping is not feasible.
+
+> [!NOTE]
+> This feature requires Chrome 146+ with scoped custom element registry support. It follows the same browser support requirements as the Enhancement Registry integration.
+>
+> For more information about scoped custom element registries, see [Chrome's announcement and guide](https://developer.chrome.com/blog/scoped-registries).
+
+### Why Itemscope Managers?
+
+The `itemscope` attribute (from the Microdata specification) provides a semantic way to mark elements that represent distinct data items. ItemScope Managers build on this by allowing us to:
+
+- **Manage light children**: Attach behavior to light DOM children of web components without wrapping them in custom elements
+- **Handle template loops**: Manage repeated DOM fragments generated by template systems
+- **Avoid custom element overhead**: Enhance elements where custom element registration isn't appropriate or possible
+- **Separate concerns**: Keep data/view model logic separate from the DOM structure
+
+### Basic Usage
+
+```html
+<div itemscope="user-card">
+  <h2>User Profile</h2>
+  <p itemprop="name"></p>
+  <p itemprop="email"></p>
+</div>
+```
+
+```TypeScript
+import 'assign-gingerly/object-extension.js';
+
+// Define a manager class
+class UserCardManager {
+  element;
+  name = '';
+  email = '';
+  
+  constructor(element, initVals) {
+    this.element = element;
+    if (initVals) {
+      Object.assign(this, initVals);
+      this.render();
+    }
+  }
+  
+  render() {
+    this.element.querySelector('[itemprop="name"]').textContent = this.name;
+    this.element.querySelector('[itemprop="email"]').textContent = this.email;
+  }
+}
+
+// Register the manager
+customElements.itemscopeRegistry.define('user-card', {
+  manager: UserCardManager
+});
+
+// Use assignGingerly with the 'ish' property
+const element = document.querySelector('[itemscope="user-card"]');
+element.assignGingerly({
+  ish: {
+    name: 'Alice',
+    email: 'alice@example.com'
+  }
+});
+
+// Wait for async setup to complete
+await customElements.itemscopeRegistry.whenDefined('user-card');
+
+// Access the manager instance
+console.log(element.ish instanceof UserCardManager); // true
+console.log(element.ish.name); // 'Alice'
+```
+
+### The 'ish' Property
+
+The `ish` property (short for "itemscope host") is the key to ItemScope Managers:
+
+- **Special behavior for HTMLElements**: When you assign an `ish` property to an HTMLElement with an `itemscope` attribute, it triggers manager instantiation
+- **Normal property for other objects**: For non-HTMLElement objects, `ish` is just a regular property with no special behavior
+- **Asynchronous setup**: The manager is instantiated asynchronously, so use `whenDefined()` to wait for completion
+
+```TypeScript
+// HTMLElement with itemscope - special behavior
+const div = document.createElement('div');
+div.setAttribute('itemscope', 'my-manager');
+div.assignGingerly({ ish: { prop: 'value' } });
+// Manager will be instantiated asynchronously
+
+// Plain object - normal property
+const obj = {};
+obj.assignGingerly({ ish: { prop: 'value' } });
+console.log(obj.ish.prop); // 'value' - just a regular property
+```
+
+### ItemscopeRegistry
+
+The `ItemscopeRegistry` class manages manager configurations and extends `EventTarget` to support lazy registration:
+
+```TypeScript
+// Access the global registry
+const registry = customElements.itemscopeRegistry;
+
+// Define a manager
+registry.define('manager-name', {
+  manager: ManagerClass,
+  lifecycleKeys: {
+    dispose: 'cleanup',
+    resolved: 'isReady'
+  }
+});
+
+// Get a manager configuration
+const config = registry.get('manager-name');
+
+// Wait for a manager to be defined and all setups to complete
+await registry.whenDefined('manager-name');
+```
+
+**Methods:**
+
+- `define(name, config)` - Register a manager configuration
+  - Throws `Error: Already registered` if name already exists
+  - Dispatches an event with the manager name when successful
+  
+- `get(name)` - Retrieve a manager configuration
+  - Returns the configuration or `undefined` if not found
+  
+- `whenDefined(name)` - Wait for manager definition and setup completion
+  - Returns a Promise that resolves when:
+    1. The manager is defined (waits for definition if not yet registered)
+    2. All pending `ish` property setups for this manager are complete
+  - This is the recommended way to wait for async manager instantiation
+
+### Manager Configuration
+
+Manager configurations follow this interface:
+
+```TypeScript
+interface ItemscopeManagerConfig<T = any> {
+  manager: {
+    new (element: HTMLElement, initVals?: Partial<T>): T;
+  };
+  lifecycleKeys?: {
+    dispose?: string | symbol;
+    resolved?: string | symbol;
+  };
+}
+```
+
+**Properties:**
+
+- `manager` (required): Constructor function that receives:
+  - `element`: The HTMLElement with the itemscope attribute
+  - `initVals`: Merged values from all queued `ish` assignments
+  
+- `lifecycleKeys` (optional): Lifecycle method names
+  - `dispose`: Method to call when cleaning up
+  - `resolved`: Property/event name for async initialization
+
+### Lazy Registration
+
+Managers can be registered after elements are already using them. The system queues values and instantiates the manager when it's registered:
+
+```TypeScript
+const element = document.createElement('div');
+element.setAttribute('itemscope', 'lazy-manager');
+
+// Assign before manager is registered - values are queued
+element.assignGingerly({ ish: { prop1: 'value1' } });
+element.assignGingerly({ ish: { prop2: 'value2' } });
+
+// Register the manager later
+setTimeout(() => {
+  customElements.itemscopeRegistry.define('lazy-manager', {
+    manager: class LazyManager {
+      constructor(element, initVals) {
+        this.element = element;
+        Object.assign(this, initVals);
+        // initVals contains both prop1 and prop2
+      }
+    }
+  });
+}, 100);
+
+// Wait for registration and setup
+await customElements.itemscopeRegistry.whenDefined('lazy-manager');
+
+console.log(element.ish.prop1); // 'value1'
+console.log(element.ish.prop2); // 'value2'
+```
+
+### Instance Caching
+
+Manager instances are cached per element. Subsequent `ish` assignments merge values into the existing instance:
+
+```TypeScript
+const element = document.createElement('div');
+element.setAttribute('itemscope', 'my-manager');
+
+// First assignment - creates instance
+element.assignGingerly({ ish: { prop1: 'value1' } });
+await customElements.itemscopeRegistry.whenDefined('my-manager');
+
+const firstInstance = element.ish;
+
+// Second assignment - reuses instance
+element.assignGingerly({ ish: { prop2: 'value2' } });
+await customElements.itemscopeRegistry.whenDefined('my-manager');
+
+console.log(element.ish === firstInstance); // true - same instance
+console.log(element.ish.prop1); // 'value1'
+console.log(element.ish.prop2); // 'value2'
+```
+
+### Validation and Error Handling
+
+The system validates `ish` property assignments and throws descriptive errors:
+
+```TypeScript
+// Error: Element must have itemscope attribute
+const div1 = document.createElement('div');
+div1.assignGingerly({ ish: { prop: 'value' } });
+// Throws asynchronously
+
+// Error: itemscope must be non-empty string
+const div2 = document.createElement('div');
+div2.setAttribute('itemscope', '');
+div2.assignGingerly({ ish: { prop: 'value' } });
+// Throws asynchronously
+
+// Error: ish value must be an object
+const div3 = document.createElement('div');
+div3.setAttribute('itemscope', 'my-manager');
+div3.assignGingerly({ ish: 'string' });
+// Throws asynchronously
+```
+
+**Note**: Errors are thrown asynchronously since the `ish` property setup happens in the background. They will appear in the console but won't be catchable with try/catch around the `assignGingerly` call.
+
+### Scoped Registries
+
+ItemScope Managers integrate with scoped custom element registries. Each element can have its own registry:
+
+```TypeScript
+// Create a scoped registry
+const scopedRegistry = new CustomElementRegistry();
+
+// Define a manager in the scoped registry
+scopedRegistry.itemscopeRegistry.define('scoped-manager', {
+  manager: ScopedManager
+});
+
+// Attach the registry to an element
+const element = document.createElement('div');
+element.customElementRegistry = scopedRegistry;
+element.setAttribute('itemscope', 'scoped-manager');
+
+// The element uses its scoped registry
+element.assignGingerly({ ish: { prop: 'value' } });
+await scopedRegistry.itemscopeRegistry.whenDefined('scoped-manager');
+```
+
+If an element doesn't have a `customElementRegistry` property, it falls back to the global `customElements.itemscopeRegistry`.
+
+### Complete Example
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <script type="module">
+    import 'assign-gingerly/object-extension.js';
+    
+    // Define a todo item manager
+    class TodoItemManager {
+      element;
+      text = '';
+      completed = false;
+      
+      constructor(element, initVals) {
+        this.element = element;
+        if (initVals) {
+          Object.assign(this, initVals);
+        }
+        this.render();
+        this.attachListeners();
+      }
+      
+      render() {
+        const checkbox = this.element.querySelector('input[type="checkbox"]');
+        const label = this.element.querySelector('label');
+        
+        if (checkbox) checkbox.checked = this.completed;
+        if (label) label.textContent = this.text;
+      }
+      
+      attachListeners() {
+        const checkbox = this.element.querySelector('input[type="checkbox"]');
+        if (checkbox) {
+          checkbox.addEventListener('change', (e) => {
+            this.completed = e.target.checked;
+            this.render();
+          });
+        }
+      }
+      
+      cleanup() {
+        // Remove event listeners, etc.
+        console.log('Cleaning up todo item');
+      }
+    }
+    
+    // Register the manager
+    customElements.itemscopeRegistry.define('todo-item', {
+      manager: TodoItemManager,
+      lifecycleKeys: {
+        dispose: 'cleanup'
+      }
+    });
+    
+    // Initialize todo items
+    async function initTodos() {
+      const items = document.querySelectorAll('[itemscope="todo-item"]');
+      
+      items.forEach((item, index) => {
+        item.assignGingerly({
+          ish: {
+            text: `Todo item ${index + 1}`,
+            completed: false
+          }
+        });
+      });
+      
+      // Wait for all setups to complete
+      await customElements.itemscopeRegistry.whenDefined('todo-item');
+      
+      console.log('All todo items initialized');
+    }
+    
+    // Run on page load
+    document.addEventListener('DOMContentLoaded', initTodos);
+  </script>
+</head>
+<body>
+  <h1>Todo List</h1>
+  <ul>
+    <li itemscope="todo-item">
+      <input type="checkbox">
+      <label></label>
+    </li>
+    <li itemscope="todo-item">
+      <input type="checkbox">
+      <label></label>
+    </li>
+    <li itemscope="todo-item">
+      <input type="checkbox">
+      <label></label>
+    </li>
+  </ul>
+</body>
+</html>
+```
+
+### Testing with whenDefined
+
+When writing tests for code that uses ItemScope Managers, use `whenDefined()` to wait for async setup:
+
+```TypeScript
+// Test example
+test('should initialize manager with values', async () => {
+  const element = document.createElement('div');
+  element.setAttribute('itemscope', 'test-manager');
+  
+  // Register manager
+  customElements.itemscopeRegistry.define('test-manager', {
+    manager: class TestManager {
+      constructor(element, initVals) {
+        this.element = element;
+        Object.assign(this, initVals);
+      }
+    }
+  });
+  
+  // Assign values
+  element.assignGingerly({ ish: { prop: 'value' } });
+  
+  // Wait for setup to complete
+  await customElements.itemscopeRegistry.whenDefined('test-manager');
+  
+  // Now we can assert
+  expect(element.ish.prop).toBe('value');
+  expect(element.ish.element).toBe(element);
+});
+```
+
+### Design Rationale
+
+ItemScope Managers follow these design principles:
+
+1. **Synchronous API**: `assignGingerly` remains synchronous and returns immediately
+2. **Async setup**: Manager instantiation happens asynchronously in the background
+3. **Explicit waiting**: Use `whenDefined()` when you need to wait for setup completion
+4. **Dual behavior**: The `ish` property has special meaning only for HTMLElements with `itemscope` attributes
+5. **Registry-based**: Follows the same pattern as `EnhancementRegistry` for consistency
+6. **Event-driven**: Uses EventTarget for lazy registration support
+
+This design ensures backward compatibility while providing powerful new capabilities for managing DOM fragments.
+