assign-gingerly 0.0.28 → 0.0.30

package/Infer.js

@@ -0,0 +1,154 @@
+/**
+ * Symbol for smart value assignment
+ * When used with element.set[value], it infers and sets the appropriate value property
+ */
+export const value = Symbol.for('assign-gingerly:value');
+/**
+ * Symbol for smart display assignment
+ * When used with element.set[display], it infers and sets the appropriate display property
+ */
+export const display = Symbol.for('assign-gingerly:display');
+/**
+ * Enhancement class that provides smart value and display property inference
+ * Automatically determines the correct property to set based on element type
+ */
+export class Infer {
+    #weakRef;
+    get enhancedElement() {
+        return this.#weakRef.deref();
+    }
+    constructor(enhancedElement) {
+        this.#weakRef = new WeakRef(enhancedElement);
+    }
+    #value;
+    get value() {
+        return this.#value;
+    }
+    set value(nv) {
+        this.#value = nv;
+        const { enhancedElement } = this;
+        enhancedElement[inferValueProperty(enhancedElement)] = nv;
+    }
+    #display;
+    get display() {
+        return this.#display;
+    }
+    set display(nv) {
+        this.#display = nv;
+        const { enhancedElement } = this;
+        enhancedElement[inferDisplayProperty(enhancedElement)] = nv;
+    }
+    /**
+     * Get the inferred event type for the element
+     * @returns The most appropriate event type for this element
+     */
+    get eventType() {
+        return inferEventType(this.enhancedElement);
+    }
+}
+/**
+ * Registry item for the Infer enhancement
+ * Register this with customElements.enhancementRegistry to enable smart value/display assignment
+ */
+export const registryItem = {
+    spawn: Infer,
+    enhKey: 'infer',
+    symlinks: {
+        [value]: 'value',
+        [display]: 'display'
+    }
+};
+/**
+ * Infer the most appropriate value property for an element
+ * @param element - The element to infer the property for
+ * @returns The property name to use for value assignment
+ */
+export function inferValueProperty(element) {
+    const tagName = element.localName;
+    // Input elements - check type attribute
+    if (tagName === 'input') {
+        const type = element.getAttribute('type')?.toLowerCase();
+        if (type === 'checkbox' || type === 'radio') {
+            return 'checked';
+        }
+        return 'value';
+    }
+    // Form controls with value property
+    if (tagName === 'textarea' || tagName === 'select') {
+        return 'value';
+    }
+    // Semantic HTML elements with specific properties
+    if (tagName === 'time') {
+        return 'dateTime';
+    }
+    if (tagName === 'data') {
+        return 'value';
+    }
+    if (tagName === 'meter' || tagName === 'progress') {
+        return 'value';
+    }
+    if (tagName === 'output') {
+        return 'value';
+    }
+    // Check for itemprop attribute as a hint
+    const itemprop = element.getAttribute('itemprop');
+    if (itemprop) {
+        return itemprop;
+    }
+    // Default fallback
+    return 'textContent';
+}
+/**
+ * Infer the most appropriate display property for an element
+ * @param element - The element to infer the property for
+ * @returns The property name to use for display assignment
+ */
+export function inferDisplayProperty(element) {
+    const tagName = element.localName;
+    // Form controls display their value
+    if (tagName === 'input' || tagName === 'textarea' || tagName === 'select') {
+        return 'value';
+    }
+    // Time elements display formatted time
+    if (tagName === 'time') {
+        return 'textContent';
+    }
+    // Data elements display human-readable content
+    if (tagName === 'data') {
+        return 'textContent';
+    }
+    // Progress/meter elements use ARIA for display
+    if (tagName === 'meter' || tagName === 'progress') {
+        return 'ariaValueText';
+    }
+    // Default fallback
+    return 'textContent';
+}
+/**
+ * Infer the most appropriate event type for an element
+ * Used when no explicit event type is provided
+ * @param element - The element to infer the event type for
+ * @returns The event type name like 'input', 'change', 'click', 'submit'
+ */
+export function inferEventType(element) {
+    const tagName = element.localName;
+    // Form controls that support input event
+    if (tagName === 'input' || tagName === 'textarea' || tagName === 'select') {
+        return 'input';
+    }
+    // Form submission
+    if (tagName === 'form') {
+        return 'submit';
+    }
+    // Details element
+    if (tagName === 'details') {
+        return 'toggle';
+    }
+    // Dialog element
+    if (tagName === 'dialog') {
+        return 'close';
+    }
+    // Default fallback for interactive elements
+    return 'click';
+}
+export default registryItem;

package/Infer.ts

@@ -0,0 +1,190 @@
+import type { EnhancementConfig } from "./types/assign-gingerly/types";
+
+/**
+ * Symbol for smart value assignment
+ * When used with element.set[value], it infers and sets the appropriate value property
+ */
+export const value = Symbol.for('assign-gingerly:value');
+
+/**
+ * Symbol for smart display assignment
+ * When used with element.set[display], it infers and sets the appropriate display property
+ */
+export const display = Symbol.for('assign-gingerly:display');
+
+/**
+ * Enhancement class that provides smart value and display property inference
+ * Automatically determines the correct property to set based on element type
+ */
+export class Infer<TValue = any, TDisplay = any> {
+    #weakRef: WeakRef<Element>;
+
+    get enhancedElement(){
+        return this.#weakRef.deref()!;
+    }
+    
+    constructor(enhancedElement?: Element){
+        this.#weakRef = new WeakRef(enhancedElement!);
+    }
+
+    #value: TValue | undefined;
+    
+    get value(): TValue | undefined {
+        return this.#value;
+    }
+    
+    set value(nv: TValue){
+        this.#value = nv;
+        const {enhancedElement} = this;
+        (enhancedElement as any)[inferValueProperty(enhancedElement)] = nv;
+    }
+
+    #display: TDisplay | undefined;
+    
+    get display(): TDisplay | undefined {
+        return this.#display;
+    }
+    
+    set display(nv: TDisplay){
+        this.#display = nv;
+        const {enhancedElement} = this;
+        (enhancedElement as any)[inferDisplayProperty(enhancedElement)] = nv;
+    }
+
+    /**
+     * Get the inferred event type for the element
+     * @returns The most appropriate event type for this element
+     */
+    get eventType(): string {
+        return inferEventType(this.enhancedElement);
+    }
+}
+
+/**
+ * Registry item for the Infer enhancement
+ * Register this with customElements.enhancementRegistry to enable smart value/display assignment
+ */
+export const registryItem: EnhancementConfig = {
+    spawn: Infer,
+    enhKey: 'infer',
+    symlinks: {
+        [value]: 'value',
+        [display]: 'display'
+    }
+}
+
+/**
+ * Infer the most appropriate value property for an element
+ * @param element - The element to infer the property for
+ * @returns The property name to use for value assignment
+ */
+export function inferValueProperty(element: Element): string {
+    const tagName = element.localName;
+    
+    // Input elements - check type attribute
+    if (tagName === 'input') {
+        const type = element.getAttribute('type')?.toLowerCase();
+        if (type === 'checkbox' || type === 'radio') {
+            return 'checked';
+        }
+        return 'value';
+    }
+    
+    // Form controls with value property
+    if (tagName === 'textarea' || tagName === 'select') {
+        return 'value';
+    }
+    
+    // Semantic HTML elements with specific properties
+    if (tagName === 'time') {
+        return 'dateTime';
+    }
+    
+    if (tagName === 'data') {
+        return 'value';
+    }
+    
+    if (tagName === 'meter' || tagName === 'progress') {
+        return 'value';
+    }
+    
+    if (tagName === 'output') {
+        return 'value';
+    }
+    
+    // Check for itemprop attribute as a hint
+    const itemprop = element.getAttribute('itemprop');
+    if (itemprop) {
+        return itemprop;
+    }
+    
+    // Default fallback
+    return 'textContent';
+}
+
+/**
+ * Infer the most appropriate display property for an element
+ * @param element - The element to infer the property for
+ * @returns The property name to use for display assignment
+ */
+export function inferDisplayProperty(element: Element): string {
+    const tagName = element.localName;
+    
+    // Form controls display their value
+    if (tagName === 'input' || tagName === 'textarea' || tagName === 'select') {
+        return 'value';
+    }
+    
+    // Time elements display formatted time
+    if (tagName === 'time') {
+        return 'textContent';
+    }
+    
+    // Data elements display human-readable content
+    if (tagName === 'data') {
+        return 'textContent';
+    }
+    
+    // Progress/meter elements use ARIA for display
+    if (tagName === 'meter' || tagName === 'progress') {
+        return 'ariaValueText';
+    }
+    
+    // Default fallback
+    return 'textContent';
+}
+
+/**
+ * Infer the most appropriate event type for an element
+ * Used when no explicit event type is provided
+ * @param element - The element to infer the event type for
+ * @returns The event type name like 'input', 'change', 'click', 'submit'
+ */
+export function inferEventType(element: Element): string {
+    const tagName = element.localName;
+    
+    // Form controls that support input event
+    if (tagName === 'input' || tagName === 'textarea' || tagName === 'select') {
+        return 'input';
+    }
+    
+    // Form submission
+    if (tagName === 'form') {
+        return 'submit';
+    }
+    
+    // Details element
+    if (tagName === 'details') {
+        return 'toggle';
+    }
+    
+    // Dialog element
+    if (tagName === 'dialog') {
+        return 'close';
+    }
+    
+    // Default fallback for interactive elements
+    return 'click';
+}
+
+export default registryItem;

package/README.md

@@ -1427,6 +1427,150 @@ 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
 
+#### Memory Management and When to Call Dispose
+
+**Important: Understanding automatic vs manual cleanup**
+
+The enhancement storage system uses a **WeakMap** to prevent memory leaks:
+
+```TypeScript
+// Global storage: WeakMap<Element, Map<EnhancementConfig, Instance>>
+```
+
+**What this means for memory:**
+
+✅ **Automatic cleanup when elements are garbage collected:**
+- When an element is GC'd, the WeakMap entry is automatically removed
+- Both `enhKey` references (`element.enh[enhKey]`) and WeakMap entries are cleaned up
+- **No memory leak from the storage mechanism itself**
+
+⚠️ **Manual cleanup needed for enhancement internals:**
+- Event listeners on global objects (window, document)
+- Timers (setInterval, setTimeout)
+- External registries or caches
+- Network connections or subscriptions
+
+**The challenge: Knowing WHEN to dispose**
+
+JavaScript provides no way to detect when an element is about to be garbage collected. Additionally, DOM disconnection doesn't reliably indicate disposal:
+
+```TypeScript
+// Element disconnected - but should we dispose?
+element.remove();
+
+// Case 1: Temporarily removed, will be re-added
+setTimeout(() => document.body.append(element), 1000);
+// ❌ Don't dispose - enhancement should persist
+
+// Case 2: Moved to another location
+otherContainer.append(element);
+// ❌ Don't dispose - enhancement should persist
+
+// Case 3: Cached for reuse
+elementCache.set('myElement', element);
+// ❌ Don't dispose - enhancement should persist
+
+// Case 4: Truly done, ready for GC
+element = null;
+// ✅ Should dispose, but no way to detect this automatically
+```
+
+**Practical disposal strategies:**
+
+1. **Short-lived elements:** Don't worry about disposal - WeakMap handles cleanup automatically when elements are GC'd
+
+2. **Long-lived applications:** Implement manual disposal at logical boundaries:
+   ```TypeScript
+   // On route change
+   router.beforeLeave(() => {
+     oldRouteElements.forEach(el => el.enh.dispose(registryItem));
+   });
+   
+   // On explicit user action
+   closeButton.onclick = () => {
+     dialog.enh.dispose(registryItem);
+     dialog.remove();
+   };
+   ```
+
+3. **Framework integration:** Use framework lifecycle hooks:
+   ```TypeScript
+   // React
+   useEffect(() => {
+     return () => elementRef.current?.enh.dispose(registryItem);
+   }, []);
+   
+   // Vue
+   onUnmounted(() => {
+     element.value?.enh.dispose(registryItem);
+   });
+   ```
+
+4. **MutationObserver heuristic:** Watch for disconnection + timeout (imperfect but practical):
+   ```TypeScript
+   const observer = new MutationObserver(() => {
+     if (!element.isConnected) {
+       setTimeout(() => {
+         if (!element.isConnected) {
+           element.enh.dispose(registryItem);
+         }
+       }, 5000); // If still disconnected after 5s, probably done
+     }
+   });
+   ```
+
+**Best practices for enhancement authors:**
+
+Always implement proper cleanup in your dispose method:
+
+```TypeScript
+class MyEnhancement {
+  element;
+  timerId = null;
+  boundHandler = null;
+  
+  constructor(element, ctx) {
+    this.element = element;
+    this.boundHandler = this.handleClick.bind(this);
+    
+    // Local listener - OK, will be GC'd with element
+    element.addEventListener('click', this.boundHandler);
+    
+    // Global listener - MUST clean up manually
+    window.addEventListener('resize', this.boundHandler);
+    
+    // Timer - MUST clean up manually
+    this.timerId = setInterval(() => this.update(), 1000);
+  }
+  
+  dispose() {
+    // Clean up global listener
+    if (this.boundHandler) {
+      window.removeEventListener('resize', this.boundHandler);
+    }
+    
+    // Clean up timer
+    if (this.timerId) {
+      clearInterval(this.timerId);
+      this.timerId = null;
+    }
+    
+    // Clear references
+    this.element = null;
+    this.boundHandler = null;
+  }
+  
+  handleClick() { /* ... */ }
+  update() { /* ... */ }
+}
+```
+
+**Summary:**
+- ✅ Storage mechanism prevents memory leaks via WeakMap
+- ⚠️ Enhancement internals need manual cleanup via dispose()
+- ❌ No automatic way to detect when disposal should happen
+- 👍 Choose disposal strategy based on your application's lifecycle
+
 ### Waiting for Async Initialization with `enh.whenResolved(regItem)`
 
 The `enh.whenResolved(regItem)` method provides a way to wait for asynchronous enhancement initialization:
@@ -3267,3 +3411,312 @@ This design ensures backward compatibility while providing powerful new capabili
 
 
 
+## Smart Value Assignment with Infer Enhancement
+
+The Infer enhancement provides a symbol-based API for smart value and display property assignment. Instead of manually determining which property to set on different element types (e.g., `value` for inputs, `checked` for checkboxes, `textContent` for divs), the Infer enhancement automatically infers the correct property based on the element type.
+
+### Why Infer?
+
+Different HTML elements use different properties to represent their value:
+- Input text fields use `value`
+- Checkboxes and radio buttons use `checked`
+- Time elements use `dateTime`
+- Divs and spans use `textContent`
+- Progress and meter elements use `value` but display with `ariaValueText`
+
+The Infer enhancement eliminates the need to remember these differences by providing two symbols that automatically map to the correct property:
+
+- `value` symbol - Sets the element's data value
+- `display` symbol - Sets the element's display/presentation value
+
+### Basic Usage
+
+```TypeScript
+import { value, display, registryItem } from 'assign-gingerly/Infer.js';
+import 'assign-gingerly/object-extension.js';
+
+// Register the Infer enhancement
+customElements.enhancementRegistry.push(registryItem);
+
+// Use the value symbol - automatically sets the right property
+const input = document.createElement('input');
+input.type = 'text';
+input.set[value] = 'hello';
+console.log(input.value); // 'hello'
+
+const checkbox = document.createElement('input');
+checkbox.type = 'checkbox';
+checkbox.set[value] = true;
+console.log(checkbox.checked); // true
+
+const div = document.createElement('div');
+div.set[value] = 'content';
+console.log(div.textContent); // 'content'
+
+const time = document.createElement('time');
+time.set[value] = '2024-01-01T00:00:00Z';
+console.log(time.dateTime); // '2024-01-01T00:00:00Z'
+```
+
+### Value Property Inference
+
+The `value` symbol automatically maps to the most appropriate property for each element type:
+
+| Element Type | Property Set | Example |
+|-------------|-------------|---------|
+| `<input type="text">` | `value` | Text input value |
+| `<input type="checkbox">` | `checked` | Checkbox state |
+| `<input type="radio">` | `checked` | Radio button state |
+| `<textarea>` | `value` | Textarea content |
+| `<select>` | `value` | Selected option |
+| `<time>` | `dateTime` | ISO datetime string |
+| `<data>` | `value` | Machine-readable value |
+| `<meter>` | `value` | Numeric value |
+| `<progress>` | `value` | Progress value |
+| `<output>` | `value` | Output value |
+| Elements with `itemprop` | `itemprop` value | Custom property name |
+| Other elements | `textContent` | Text content |
+
+### Display Property Inference
+
+The `display` symbol sets the human-readable display value:
+
+```TypeScript
+// Time element - display formatted time
+const time = document.createElement('time');
+time.set[value] = '2024-01-01T00:00:00Z';  // Machine-readable
+time.set[display] = 'January 1, 2024';      // Human-readable
+console.log(time.dateTime);    // '2024-01-01T00:00:00Z'
+console.log(time.textContent); // 'January 1, 2024'
+
+// Meter element - display with ARIA
+const meter = document.createElement('meter');
+meter.min = 0;
+meter.max = 100;
+meter.set[value] = 75;                    // Numeric value
+meter.set[display] = '75 percent';        // Screen reader text
+console.log(meter.value);          // 75
+console.log(meter.ariaValueText);  // '75 percent'
+```
+
+| Element Type | Property Set | Example |
+|-------------|-------------|---------|
+| `<input>`, `<textarea>`, `<select>` | `value` | Form control value |
+| `<time>` | `textContent` | Formatted time string |
+| `<data>` | `textContent` | Human-readable content |
+| `<meter>`, `<progress>` | `ariaValueText` | Screen reader text |
+| Other elements | `textContent` | Text content |
+
+### Accessing the Enhancement Instance
+
+The Infer enhancement is accessible via `element.enh.infer`:
+
+```TypeScript
+const input = document.createElement('input');
+input.set[value] = 'test';
+
+// Access the enhancement instance
+console.log(input.enh.infer.value); // 'test' (cached value)
+
+// The instance maintains references to both value and display
+input.set[display] = 'Test Display';
+console.log(input.enh.infer.value);   // 'test'
+console.log(input.enh.infer.display); // 'Test Display'
+```
+
+### Using with assignGingerly
+
+The Infer enhancement integrates seamlessly with `assignGingerly`:
+
+```TypeScript
+import { value, display } from 'assign-gingerly/Infer.js';
+
+const element = document.createElement('input');
+element.type = 'text';
+
+// Use symbols in assignGingerly
+element.assignGingerly({
+  [value]: 'hello world',
+  style: {
+    color: 'blue'
+  }
+});
+
+console.log(element.value);       // 'hello world'
+console.log(element.style.color); // 'blue'
+```
+
+### Itemprop Support
+
+Elements with an `itemprop` attribute use that attribute's value as the property name:
+
+```html
+<span itemprop="title"></span>
+```
+
+```TypeScript
+const span = document.querySelector('[itemprop="title"]');
+span.set[value] = 'My Title';
+console.log(span.title); // 'My Title'
+```
+
+### Implementation Details
+
+The Infer enhancement is implemented as a standard enhancement class:
+
+```TypeScript
+class Infer<TValue = any, TDisplay = any> {
+  #weakRef: WeakRef<Element>;
+  
+  constructor(enhancedElement?: Element) {
+    this.#weakRef = new WeakRef(enhancedElement!);
+  }
+  
+  get value(): TValue | undefined { /* ... */ }
+  set value(nv: TValue) {
+    const element = this.#weakRef.deref()!;
+    element[inferValueProperty(element)] = nv;
+  }
+  
+  get display(): TDisplay | undefined { /* ... */ }
+  set display(nv: TDisplay) {
+    const element = this.#weakRef.deref()!;
+    element[inferDisplayProperty(element)] = nv;
+  }
+}
+```
+
+**Registry Configuration:**
+
+```TypeScript
+export const registryItem: EnhancementConfig = {
+  spawn: Infer,
+  enhKey: 'infer',
+  symlinks: {
+    [value]: 'value',
+    [display]: 'display'
+  }
+};
+```
+
+The `symlinks` mapping connects the symbols to the enhancement's properties, enabling the `element.set[symbol]` syntax.
+
+### Helper Functions
+
+The Infer module exports helper functions for manual property and event type inference:
+
+```TypeScript
+import { inferValueProperty, inferDisplayProperty, inferEventType } from 'assign-gingerly/Infer.js';
+
+const input = document.createElement('input');
+input.type = 'checkbox';
+
+const valueProp = inferValueProperty(input);
+console.log(valueProp); // 'checked'
+
+const displayProp = inferDisplayProperty(input);
+console.log(displayProp); // 'value'
+
+const eventType = inferEventType(input);
+console.log(eventType); // 'input'
+```
+
+These functions can be useful when you need to determine the property or event type name without actually setting a value or attaching a listener.
+
+**Event Type Inference:**
+
+The `inferEventType` function returns the most appropriate event type for different element types:
+
+| Element Type | Event Type | Use Case |
+|-------------|-----------|----------|
+| `<input>`, `<textarea>`, `<select>` | `input` | Form control value changes |
+| `<form>` | `submit` | Form submission |
+| `<details>` | `toggle` | Details element open/close |
+| `<dialog>` | `close` | Dialog dismissal |
+| Other elements | `click` | Default interactive event |
+
+**Accessing via Enhancement Instance:**
+
+The inferred event type is also available as a getter on the enhancement instance:
+
+```TypeScript
+const input = document.createElement('input');
+input.set[value] = 'test';
+
+console.log(input.enh.infer.eventType); // 'input'
+
+const form = document.createElement('form');
+form.set[value] = 'test';
+
+console.log(form.enh.infer.eventType); // 'submit'
+```
+
+This is particularly useful when building enhancements that need to attach event listeners but don't know the element type in advance.
+
+### Benefits
+
+1. **Type-agnostic code**: Write code that works with any element type without conditionals
+2. **Cleaner syntax**: No need to remember which property each element type uses
+3. **Accessibility**: Separate value and display properties support screen readers
+4. **Framework-friendly**: Symbols work well with reactive frameworks and data binding
+5. **Extensible**: Based on the enhancement registry system, can be customized or extended
+
+### Complete Example
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <script type="module">
+    import { value, display, registryItem } from './Infer.js';
+    import './object-extension.js';
+    
+    // Register the enhancement
+    customElements.enhancementRegistry.push(registryItem);
+    
+    // Create various elements
+    const input = document.createElement('input');
+    input.type = 'text';
+    
+    const checkbox = document.createElement('input');
+    checkbox.type = 'checkbox';
+    
+    const time = document.createElement('time');
+    
+    const meter = document.createElement('meter');
+    meter.min = 0;
+    meter.max = 100;
+    
+    // Set values using the same symbol - each element handles it correctly
+    input.set[value] = 'Hello World';
+    checkbox.set[value] = true;
+    time.set[value] = '2024-01-01T00:00:00Z';
+    time.set[display] = 'January 1, 2024';
+    meter.set[value] = 75;
+    meter.set[display] = '75 percent';
+    
+    // Add to document
+    document.body.append(input, checkbox, time, meter);
+    
+    console.log('Input value:', input.value);           // 'Hello World'
+    console.log('Checkbox checked:', checkbox.checked); // true
+    console.log('Time dateTime:', time.dateTime);       // '2024-01-01T00:00:00Z'
+    console.log('Time display:', time.textContent);     // 'January 1, 2024'
+    console.log('Meter value:', meter.value);           // 75
+    console.log('Meter display:', meter.ariaValueText); // '75 percent'
+  </script>
+</head>
+<body>
+  <h1>Infer Enhancement Demo</h1>
+</body>
+</html>
+```
+
+### Browser Support
+
+The Infer enhancement requires:
+- Chrome 146+ (for scoped custom element registries)
+- Modern browsers with Symbol support
+- WeakRef support (all modern browsers)
+
+For browsers without scoped registry support, the enhancement falls back to the global `customElements.enhancementRegistry`.

package/getHost.js

@@ -0,0 +1,51 @@
+/**
+ * Get the itemscope host element for a given element.
+ * This function finds the closest element with an itemscope attribute and waits for it to be ready.
+ *
+ * @param el - The element to start searching from
+ * @returns The itemscope host element, or null if none found
+ */
+export async function getHost(el) {
+    const itemScopeHost = el.closest('[itemscope]');
+    if (itemScopeHost) {
+        const { localName } = itemScopeHost;
+        // If it's a custom element, wait for it to be defined
+        if (localName.includes('-')) {
+            const registry = itemScopeHost.customElementRegistry ?? customElements;
+            await registry.whenDefined(localName);
+            return itemScopeHost;
+        }
+        else {
+            // Check if itemscope specifies a value (manager name)
+            const itemscopeValue = itemScopeHost.getAttribute('itemscope');
+            if (itemscopeValue && itemscopeValue.length > 0) {
+                // Wait for the manager to be defined in the itemscope registry
+                const registry = itemScopeHost.customElementRegistry?.itemscopeRegistry
+                    ?? (typeof customElements !== 'undefined' ? customElements.itemscopeRegistry : undefined);
+                if (registry) {
+                    await registry.whenDefined(itemscopeValue);
+                }
+            }
+            return itemScopeHost;
+        }
+    }
+    else {
+        // No itemscope host found in the light DOM
+        // Check if we're inside a shadow root and get the shadow host
+        const rootNode = el.getRootNode();
+        // Check if it's a shadow root (has a host property)
+        if (rootNode && 'host' in rootNode && rootNode.host) {
+            const host = rootNode.host;
+            const { localName } = host;
+            // If the host is a custom element, wait for it to be defined
+            if (localName.includes('-')) {
+                const registry = host.customElementRegistry ?? customElements;
+                await registry.whenDefined(localName);
+            }
+            return host;
+        }
+        // Not in a shadow root either
+        return null;
+    }
+}
+export default getHost;

package/getHost.ts

@@ -0,0 +1,58 @@
+/**
+ * Get the itemscope host element for a given element.
+ * This function finds the closest element with an itemscope attribute and waits for it to be ready.
+ * 
+ * @param el - The element to start searching from
+ * @returns The itemscope host element, or null if none found
+ */
+export async function getHost(el: Element): Promise<Element | null> {
+    const itemScopeHost = el.closest('[itemscope]');
+    if (itemScopeHost) {
+        const { localName } = itemScopeHost;
+        
+        // If it's a custom element, wait for it to be defined
+        if (localName.includes('-')) {
+            const registry = (itemScopeHost as any).customElementRegistry ?? customElements;
+            await registry.whenDefined(localName);
+            return itemScopeHost;
+        } else {
+            // Check if itemscope specifies a value (manager name)
+            const itemscopeValue = itemScopeHost.getAttribute('itemscope');
+            
+            if (itemscopeValue && itemscopeValue.length > 0) {
+                // Wait for the manager to be defined in the itemscope registry
+                const registry = (itemScopeHost as any).customElementRegistry?.itemscopeRegistry
+                    ?? (typeof customElements !== 'undefined' ? customElements.itemscopeRegistry : undefined);
+                
+                if (registry) {
+                    await registry.whenDefined(itemscopeValue);
+                }
+            }
+            
+            return itemScopeHost;
+        }
+    } else {
+        // No itemscope host found in the light DOM
+        // Check if we're inside a shadow root and get the shadow host
+        const rootNode = el.getRootNode();
+        
+        // Check if it's a shadow root (has a host property)
+        if (rootNode && 'host' in rootNode && (rootNode as ShadowRoot).host) {
+            const host = (rootNode as ShadowRoot).host;
+            const { localName } = host;
+            
+            // If the host is a custom element, wait for it to be defined
+            if (localName.includes('-')) {
+                const registry = (host as any).customElementRegistry ?? customElements;
+                await registry.whenDefined(localName);
+            }
+            
+            return host;
+        }
+        
+        // Not in a shadow root either
+        return null;
+    }
+}
+
+export default getHost;

package/index.js

@@ -6,4 +6,5 @@ export { ParserRegistry, globalParserRegistry } from './parserRegistry.js';
 export { parseWithAttrs } from './parseWithAttrs.js';
 export { buildCSSQuery } from './buildCSSQuery.js';
 export { resolveTemplate } from './resolveTemplate.js';
+export { getHost } from './getHost.js';
 import './object-extension.js';

package/index.ts

@@ -6,4 +6,5 @@ export {ParserRegistry, globalParserRegistry} from './parserRegistry.js';
 export {parseWithAttrs} from './parseWithAttrs.js';
 export {buildCSSQuery} from './buildCSSQuery.js';
 export {resolveTemplate} from './resolveTemplate.js';
+export {getHost} from './getHost.js';
 import './object-extension.js';

package/object-extension.js

@@ -284,6 +284,74 @@ if (typeof Element !== 'undefined') {
         enumerable: true,
         configurable: true,
     });
+    /**
+     * Adds 'set' property to Element prototype for symbol-based dependency injection
+     * Returns a proxy that intercepts symbol property assignments
+     */
+    Object.defineProperty(Element.prototype, 'set', {
+        get: function () {
+            const element = this;
+            return new Proxy({}, {
+                set: (_, prop, value) => {
+                    if (typeof prop === 'symbol') {
+                        // Get the registry from customElementRegistry (scoped or global)
+                        const registry = element.customElementRegistry?.enhancementRegistry
+                            ?? (typeof customElements !== 'undefined' ? customElements.enhancementRegistry : undefined);
+                        if (registry) {
+                            const registryItem = registry.findBySymbol(prop);
+                            if (registryItem) {
+                                const instanceMap = getInstanceMap();
+                                const instances = instanceMap.getOrInsertComputed(element, () => new Map());
+                                let instance = instances.get(registryItem);
+                                if (!instance) {
+                                    const SpawnClass = registryItem.spawn;
+                                    // Check canSpawn if it exists
+                                    if (typeof SpawnClass.canSpawn === 'function') {
+                                        const ctx = { config: registryItem };
+                                        if (!SpawnClass.canSpawn(element, ctx)) {
+                                            // canSpawn returned false, skip spawning
+                                            return true;
+                                        }
+                                    }
+                                    // If target is an Element and registryItem has enhKey, pass element to constructor
+                                    if (registryItem.enhKey) {
+                                        const ctx = { config: registryItem };
+                                        const initVals = element.enh?.[registryItem.enhKey] &&
+                                            !(element.enh[registryItem.enhKey] instanceof SpawnClass)
+                                            ? element.enh[registryItem.enhKey]
+                                            : undefined;
+                                        instance = new SpawnClass(element, ctx, initVals);
+                                    }
+                                    else {
+                                        const ctx = { config: registryItem };
+                                        instance = new SpawnClass(element, ctx);
+                                    }
+                                    instances.set(registryItem, instance);
+                                    // If registryItem has enhKey, store on enh
+                                    if (registryItem.enhKey) {
+                                        if (!element.enh) {
+                                            // This shouldn't happen since enh is a getter, but be safe
+                                            element.enh = {};
+                                        }
+                                        element.enh[registryItem.enhKey] = instance;
+                                    }
+                                }
+                                if (registryItem.symlinks) {
+                                    const mappedKey = registryItem.symlinks[prop];
+                                    if (mappedKey && instance && typeof instance === 'object') {
+                                        instance[mappedKey] = value;
+                                    }
+                                }
+                            }
+                        }
+                    }
+                    return true;
+                },
+            });
+        },
+        enumerable: false,
+        configurable: true,
+    });
 }
 /**
  * Adds assignGingerly method to all objects via the Object prototype

package/object-extension.ts

@@ -404,6 +404,84 @@ if (typeof Element !== 'undefined') {
     enumerable: true,
     configurable: true,
   });
+  
+  /**
+   * Adds 'set' property to Element prototype for symbol-based dependency injection
+   * Returns a proxy that intercepts symbol property assignments
+   */
+  Object.defineProperty(Element.prototype, 'set', {
+    get: function (this: Element) {
+      const element = this;
+      return new Proxy(
+        {},
+        {
+          set: (_: any, prop: string | symbol, value: any) => {
+            if (typeof prop === 'symbol') {
+              // Get the registry from customElementRegistry (scoped or global)
+              const registry = (element as any).customElementRegistry?.enhancementRegistry
+                ?? (typeof customElements !== 'undefined' ? customElements.enhancementRegistry : undefined);
+              
+              if (registry) {
+                const registryItem = registry.findBySymbol(prop);
+                if (registryItem) {
+                  const instanceMap = getInstanceMap();
+                  const instances = instanceMap.getOrInsertComputed(element, () => new Map());
+                  let instance = instances.get(registryItem);
+
+                  if (!instance) {
+                    const SpawnClass = registryItem.spawn;
+                    
+                    // Check canSpawn if it exists
+                    if (typeof SpawnClass.canSpawn === 'function') {
+                      const ctx = { config: registryItem };
+                      if (!SpawnClass.canSpawn(element, ctx)) {
+                        // canSpawn returned false, skip spawning
+                        return true;
+                      }
+                    }
+                    
+                    // If target is an Element and registryItem has enhKey, pass element to constructor
+                    if (registryItem.enhKey) {
+                      const ctx = { config: registryItem };
+                      const initVals = (element as any).enh?.[registryItem.enhKey] && 
+                                      !((element as any).enh[registryItem.enhKey] instanceof SpawnClass)
+                                      ? (element as any).enh[registryItem.enhKey]
+                                      : undefined;
+                      instance = new SpawnClass(element, ctx, initVals);
+                    } else {
+                      const ctx = { config: registryItem };
+                      instance = new SpawnClass(element, ctx);
+                    }
+                    
+                    instances.set(registryItem, instance);
+                    
+                    // If registryItem has enhKey, store on enh
+                    if (registryItem.enhKey) {
+                      if (!(element as any).enh) {
+                        // This shouldn't happen since enh is a getter, but be safe
+                        (element as any).enh = {};
+                      }
+                      (element as any).enh[registryItem.enhKey] = instance;
+                    }
+                  }
+                  
+                  if(registryItem.symlinks){
+                    const mappedKey = registryItem.symlinks[prop];
+                    if (mappedKey && instance && typeof instance === 'object') {
+                      (instance as any)[mappedKey] = value;
+                    }
+                  }
+                }
+              }
+            }
+            return true;
+          },
+        }
+      );
+    },
+    enumerable: false,
+    configurable: true,
+  });
 }
 
 /**

package/package.json

@@ -1,71 +1,79 @@
-{
-  "name": "assign-gingerly",
-  "version": "0.0.28",
-  "description": "This package provides a utility function for carefully merging one object into another.",
-  "homepage": "https://github.com/bahrus/assign-gingerly#readme",
-  "bugs": {
-    "url": "https://github.com/bahrus/assign-gingerly/issues"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/bahrus/assign-gingerly.git"
-  },
-  "license": "MIT",
-  "author": "Bruce B. Anderson <andeson.bruce.b@gmail.com>",
-  "type": "module",
-  "types": "types/assign-gingerly/types.d.ts",
-  "files": [
-    "*.js",
-    "*.ts",
-    "README.md",
-    "LICENSE",
-    "types/assign-gingerly/types.d.ts"
-  ],
-  "exports": {
-    ".": {
-      "default": "./index.js",
-      "types": "./index.ts"
-    },
-    "./assignGingerly.js": {
-      "default": "./assignGingerly.js",
-      "types": "./assignGingerly.ts"
-    },
-    "./assignTentatively.js": {
-      "default": "./assignTentatively.js",
-      "types": "./assignTentatively.ts"
-    },
-    "./waitForEvent.js": {
-      "default": "./waitForEvent.js"
-    },
-    "./parserRegistry.js": {
-      "default": "./parserRegistry.js"
-    },
-    "./parseWithAttrs.js": {
-      "default": "./parseWithAttrs.js",
-      "types": "./parseWithAttrs.ts"
-    },
-    "./buildCSSQuery.js": {
-      "default": "./buildCSSQuery.js",
-      "types": "./buildCSSQuery.ts"
-    },
-    "./resolveTemplate.js": {
-      "default": "./resolveTemplate.js",
-      "types": "./resolveTemplate.ts"
-    }
-  },
-  "main": "index.js",
-  "module": "index.js",
-  "scripts": {
-    "serve": "node ./node_modules/spa-ssi/serve.js",
-    "test": "playwright test",
-    "update": "ncu -u && npm install",
-    "safari": "npx playwright wk http://localhost:8000",
-    "chrome": "npx playwright cr http://localhost:8000"
-  },
-  "devDependencies": {
-    "@playwright/test": "1.59.1",
-    "spa-ssi": "0.0.27",
-    "@types/node": "25.5.2",
-    "typescript": "6.0.2"
-  }
-}
+{
+  "name": "assign-gingerly",
+  "version": "0.0.30",
+  "description": "This package provides a utility function for carefully merging one object into another.",
+  "homepage": "https://github.com/bahrus/assign-gingerly#readme",
+  "bugs": {
+    "url": "https://github.com/bahrus/assign-gingerly/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bahrus/assign-gingerly.git"
+  },
+  "license": "MIT",
+  "author": "Bruce B. Anderson <andeson.bruce.b@gmail.com>",
+  "type": "module",
+  "types": "types/assign-gingerly/types.d.ts",
+  "files": [
+    "*.js",
+    "*.ts",
+    "README.md",
+    "LICENSE",
+    "types/assign-gingerly/types.d.ts"
+  ],
+  "exports": {
+    ".": {
+      "default": "./index.js",
+      "types": "./index.ts"
+    },
+    "./assignGingerly.js": {
+      "default": "./assignGingerly.js",
+      "types": "./assignGingerly.ts"
+    },
+    "./assignTentatively.js": {
+      "default": "./assignTentatively.js",
+      "types": "./assignTentatively.ts"
+    },
+    "./waitForEvent.js": {
+      "default": "./waitForEvent.js"
+    },
+    "./parserRegistry.js": {
+      "default": "./parserRegistry.js"
+    },
+    "./parseWithAttrs.js": {
+      "default": "./parseWithAttrs.js",
+      "types": "./parseWithAttrs.ts"
+    },
+    "./buildCSSQuery.js": {
+      "default": "./buildCSSQuery.js",
+      "types": "./buildCSSQuery.ts"
+    },
+    "./resolveTemplate.js": {
+      "default": "./resolveTemplate.js",
+      "types": "./resolveTemplate.ts"
+    },
+    "./getHost.js": {
+      "default": "./getHost.js",
+      "types": "./getHost.ts"
+    },
+    "./Infer.js": {
+      "default": "./Infer.js",
+      "types": "./Infer.ts"
+    }
+  },
+  "main": "index.js",
+  "module": "index.js",
+  "scripts": {
+    "serve": "node ./node_modules/spa-ssi/serve.js",
+    "test": "playwright test",
+    "update": "ncu -u && npm install",
+    "safari": "npx playwright wk http://localhost:8000",
+    "chrome": "npx playwright cr http://localhost:8000"
+  },
+  "devDependencies": {
+    "@playwright/test": "1.59.1",
+    "spa-ssi": "0.0.27",
+    "@types/node": "25.5.2",
+    "typescript": "6.0.2"
+  }
+}

package/parseWithAttrs.js

@@ -147,7 +147,8 @@ function hasDashOrNonASCII(str) {
  * @returns The attribute value or null
  */
 function getAttributeValue(element, attrName, allowUnprefixed) {
-    const isCustomElement = element.tagName.includes('-');
+    const { localName } = element;
+    const isCustomElement = localName.includes('-');
     const isSVGElement = typeof SVGElement !== 'undefined' && element instanceof SVGElement;
     // For custom elements and SVG - strict enh- requirement
     if (isCustomElement || isSVGElement) {
@@ -157,8 +158,7 @@ function getAttributeValue(element, attrName, allowUnprefixed) {
         // Only fallback if tag name matches the allowUnprefixed pattern
         if (allowUnprefixed) {
             const pattern = typeof allowUnprefixed === 'string' ? new RegExp(allowUnprefixed) : allowUnprefixed;
-            const tagName = element.tagName.toLowerCase();
-            if (pattern.test(tagName)) {
+            if (pattern.test(localName)) {
                 return element.getAttribute(attrName);
             }
         }

package/parseWithAttrs.ts

@@ -186,7 +186,8 @@ function getAttributeValue(
   attrName: string,
   allowUnprefixed?: string | RegExp
 ): string | null {
-  const isCustomElement = element.tagName.includes('-');
+  const { localName } = element;
+  const isCustomElement = localName.includes('-');
   const isSVGElement = typeof SVGElement !== 'undefined' && element instanceof SVGElement;
   
   // For custom elements and SVG - strict enh- requirement
@@ -197,8 +198,7 @@ function getAttributeValue(
     // Only fallback if tag name matches the allowUnprefixed pattern
     if (allowUnprefixed) {
       const pattern = typeof allowUnprefixed === 'string' ? new RegExp(allowUnprefixed) : allowUnprefixed;
-      const tagName = element.tagName.toLowerCase();
-      if (pattern.test(tagName)) {
+      if (pattern.test(localName)) {
         return element.getAttribute(attrName);
       }
     }

package/types/assign-gingerly/types.d.ts

@@ -112,7 +112,7 @@ export type ParserFunction<T = any> =
   | ((attrValue: string | null) => any)
   | ((attrValue: string | null, context?: ParserContext<T>) => any);
 
-export interface AttrConfig<T = any> {
+export interface AttrConfig<T = unknown, TParserConfig = unknown> {
   /**
    * Type of the property value (JSON-serializable string format)
    */
@@ -152,6 +152,12 @@ export interface AttrConfig<T = any> {
     | ParserFunction<T>
     | string
   ;
+
+  /**
+   * configuration information needed by a custom parser to properly
+   * parse the attribute.
+   */
+  parserConfig?: TParserConfig;
   
   /**
    * Default value to use when attribute is missing