assign-gingerly 0.0.53 → 0.0.55

package/assignGingerly.ts

@@ -1,6 +1,8 @@
 
 
 import { EnhancementConfig } from "./types/assign-gingerly/types";
+import type { FeatureConfigsMap } from "./types/assign-gingerly/types";
+import type { AssignPermissions } from "./isAllowedImportPath.js";
 
 /**
  * Constructor signature for ItemScope Manager classes
@@ -116,6 +118,18 @@ export interface IAssignGingerlyOptions {
    * // Calls: (await el.whenFeatureReady('photoTaker')).someProp = 'hello'
    */
   withAsyncMethods?: string[] | Set<string>;
+
+  /**
+   * Bulk enhancement application via EMC JSON configs.
+   * Finds matching elements and spawns enhancements on them.
+   * Fire-and-forget (async) — assignGingerly remains synchronous.
+   * 
+   * @example
+   * enhance: [
+   *     { emc: 'be-bound/emc.json', matching: '[name]' },
+   * ]
+   */
+  enhance?: Array<{ emc: string; matching?: string; parse?: boolean }>;
 }
 
 /**
@@ -167,6 +181,23 @@ export class EnhancementRegistry extends EventTarget {
     
     // Dispatch event after adding items
     this.dispatchEvent(new EnhancementRegisteredEvent(items));
+
+    // Process features if present (fire-and-forget, uses shared featuresRegistry)
+    const itemsArr = Array.isArray(items) ? items : [items];
+    for (const item of itemsArr) {
+      if (item.features) {
+        this.#assignFeatures(item.spawn, item.features);
+      }
+    }
+  }
+
+  async #assignFeatures(spawn: any, features: FeatureConfigsMap): Promise<void> {
+    const { assignFeatures } = await import('./assignFeatures.js');
+    const featuresRegistry = (this as any)._featuresRegistry
+      ?? (typeof customElements !== 'undefined' ? (customElements as any).featuresRegistry : undefined);
+    if (featuresRegistry) {
+      assignFeatures(spawn, features, featuresRegistry);
+    }
   }
 
   getItems(): EnhancementConfig[] {
@@ -218,6 +249,20 @@ export class ItemscopeRegistry extends EventTarget {
     }
     this.#configs.set(name, config);
     this.dispatchEvent(new Event(name));
+
+    // Process features if present (fire-and-forget, uses shared featuresRegistry)
+    if ((config as any).features) {
+      this.#assignFeatures(config.manager, (config as any).features);
+    }
+  }
+
+  async #assignFeatures(manager: any, features: FeatureConfigsMap): Promise<void> {
+    const { assignFeatures } = await import('./assignFeatures.js');
+    const featuresRegistry = (this as any)._featuresRegistry
+      ?? (typeof customElements !== 'undefined' ? (customElements as any).featuresRegistry : undefined);
+    if (featuresRegistry) {
+      assignFeatures(manager, features, featuresRegistry);
+    }
   }
 
   /**
@@ -691,7 +736,8 @@ function applyAliases(key: string, aliasMap: Map<string, string>): string {
 export function assignGingerly(
   target: any,
   source: Record<string | symbol, any>,
-  options?: IAssignGingerlyOptions
+  options?: IAssignGingerlyOptions,
+  permissions?: AssignPermissions
 ): any {
   if (!target || typeof target !== 'object') {
     return target;
@@ -1274,6 +1320,13 @@ export function assignGingerly(
     });
   }
 
+  // Fire-and-forget bulk enhancements (async, non-blocking)
+  if (options?.enhance && options.enhance.length > 0 && typeof target === 'object' && target instanceof Element) {
+    import('./enhanceAll.js').then(({ enhanceAll }) => {
+      enhanceAll(target, options!.enhance!, permissions);
+    });
+  }
+
   return target;
 }
 

package/beVigilant.js

@@ -0,0 +1,73 @@
+/**
+ * beVigilant.ts — MutationObserver-based reactive inference for newly added elements.
+ *
+ * Dynamically imported when `inferredAssignments.beVigilant: true` is set.
+ * Watches for new [itemprop] elements and attribute changes, applying inferred
+ * assignments from the live `from` object.
+ *
+ * Requires an AbortSignal for cleanup (disconnects the observer on abort).
+ */
+import { Infer } from './inferencer/inferencer.js';
+import { withScopePerimeter } from './inferencer/withScopePerimeter.js';
+import { registerInCache } from './resolveIdRef.js';
+/**
+ * Set up a MutationObserver that watches for new [itemprop] elements
+ * and applies inferred assignments from the live `from` object.
+ *
+ * @param target - The DOM element to observe
+ * @param from - The live source object (read at observation time for current values)
+ * @param config - The inferredAssignments config (byItemprop keys)
+ * @param signal - AbortSignal for cleanup (required)
+ */
+export function setupVigilantObserver(target, from, config, signal) {
+    const keys = config.byItemprop === true ? null : new Set(config.byItemprop);
+    const observer = new MutationObserver((mutations) => {
+        for (const mutation of mutations) {
+            if (mutation.type === 'childList') {
+                // Process added nodes and their descendants
+                for (const node of mutation.addedNodes) {
+                    if (!(node instanceof Element))
+                        continue;
+                    // Check the added element itself
+                    processElement(node, from, keys, target);
+                    // Check descendants (respecting scope perimeter)
+                    const nested = node.querySelectorAll('[itemprop]');
+                    for (const el of nested) {
+                        processElement(el, from, keys, target);
+                    }
+                }
+            }
+            else if (mutation.type === 'attributes' && mutation.target instanceof Element) {
+                // itemprop attribute was added or changed on an existing element
+                processElement(mutation.target, from, keys, target);
+            }
+        }
+    });
+    observer.observe(target, {
+        childList: true,
+        subtree: true,
+        attributes: true,
+        attributeFilter: ['itemprop']
+    });
+    // Cleanup on abort
+    signal.addEventListener('abort', () => observer.disconnect(), { once: true });
+}
+/**
+ * Process a single element: check if it matches, apply inferred value, cache it.
+ */
+function processElement(element, from, keys, scopeRoot) {
+    const itemprop = element.getAttribute('itemprop');
+    if (!itemprop)
+        return;
+    if (keys && !keys.has(itemprop))
+        return;
+    if (!(itemprop in from))
+        return;
+    if (!withScopePerimeter(scopeRoot, element, '[itemscope]'))
+        return;
+    // Set value via inferencer
+    const infer = new Infer(element, itemprop);
+    infer.value = from[itemprop];
+    // Cache for future fast access
+    registerInCache(scopeRoot, itemprop, element);
+}

package/beVigilant.ts

@@ -0,0 +1,85 @@
+/**
+ * beVigilant.ts — MutationObserver-based reactive inference for newly added elements.
+ * 
+ * Dynamically imported when `inferredAssignments.beVigilant: true` is set.
+ * Watches for new [itemprop] elements and attribute changes, applying inferred
+ * assignments from the live `from` object.
+ * 
+ * Requires an AbortSignal for cleanup (disconnects the observer on abort).
+ */
+
+import { Infer } from './inferencer/inferencer.js';
+import { withScopePerimeter } from './inferencer/withScopePerimeter.js';
+import { registerInCache } from './resolveIdRef.js';
+
+/**
+ * Set up a MutationObserver that watches for new [itemprop] elements
+ * and applies inferred assignments from the live `from` object.
+ * 
+ * @param target - The DOM element to observe
+ * @param from - The live source object (read at observation time for current values)
+ * @param config - The inferredAssignments config (byItemprop keys)
+ * @param signal - AbortSignal for cleanup (required)
+ */
+export function setupVigilantObserver(
+    target: Element,
+    from: any,
+    config: { byItemprop?: string[] | true },
+    signal: AbortSignal
+): void {
+    const keys = config.byItemprop === true ? null : new Set(config.byItemprop);
+
+    const observer = new MutationObserver((mutations) => {
+        for (const mutation of mutations) {
+            if (mutation.type === 'childList') {
+                // Process added nodes and their descendants
+                for (const node of mutation.addedNodes) {
+                    if (!(node instanceof Element)) continue;
+                    // Check the added element itself
+                    processElement(node, from, keys, target);
+                    // Check descendants (respecting scope perimeter)
+                    const nested = node.querySelectorAll('[itemprop]');
+                    for (const el of nested) {
+                        processElement(el as Element, from, keys, target);
+                    }
+                }
+            } else if (mutation.type === 'attributes' && mutation.target instanceof Element) {
+                // itemprop attribute was added or changed on an existing element
+                processElement(mutation.target, from, keys, target);
+            }
+        }
+    });
+
+    observer.observe(target, {
+        childList: true,
+        subtree: true,
+        attributes: true,
+        attributeFilter: ['itemprop']
+    });
+
+    // Cleanup on abort
+    signal.addEventListener('abort', () => observer.disconnect(), { once: true });
+}
+
+/**
+ * Process a single element: check if it matches, apply inferred value, cache it.
+ */
+function processElement(
+    element: Element,
+    from: any,
+    keys: Set<string> | null,
+    scopeRoot: Element
+): void {
+    const itemprop = element.getAttribute('itemprop');
+    if (!itemprop) return;
+    if (keys && !keys.has(itemprop)) return;
+    if (!(itemprop in from)) return;
+    if (!withScopePerimeter(scopeRoot, element, '[itemscope]')) return;
+
+    // Set value via inferencer
+    const infer = new Infer(element, itemprop);
+    infer.value = from[itemprop];
+
+    // Cache for future fast access
+    registerInCache(scopeRoot, itemprop, element);
+}

package/enhanceAll.js

@@ -0,0 +1,106 @@
+/**
+ * enhanceAll.ts — Bulk enhancement application via EMC (Element Mount Configuration) JSON.
+ *
+ * Finds matching elements within a target and spawns enhancements on them
+ * using the configuration from EMC JSON files that enhancement packages publish.
+ *
+ * Dynamically imported by assignFrom when `enhance` option is present,
+ * or used standalone.
+ *
+ * @example
+ * import { enhanceAll } from 'assign-gingerly/enhanceAll.js';
+ *
+ * await enhanceAll(shadowRoot, [
+ *     { emc: 'be-bound/emc.json', matching: '[name]' },
+ *     { emc: 'be-observant/emc.json', matching: '[itemprop]' },
+ * ]);
+ */
+import { isAllowedImportPath } from './isAllowedImportPath.js';
+/**
+ * Apply enhancements in bulk to matching elements within a target.
+ *
+ * For each entry:
+ * 1. Dynamically imports the EMC JSON
+ * 2. Extracts enhConfig (spawn path, enhKey, withAttrs)
+ * 3. Finds matching elements via querySelectorAll
+ * 4. Registers the enhancement if not already registered
+ * 5. Spawns the enhancement on each matched element via enh.get()
+ *
+ * Note: No scope perimeter is applied. For reactive observation of new elements,
+ * use mount-observer instead.
+ *
+ * @param target - The DOM element to search within
+ * @param configs - Array of enhancement configurations
+ */
+export async function enhanceAll(target, configs, permissions) {
+    for (const config of configs) {
+        // Validate EMC path unless cross-domain imports are explicitly permitted
+        if (!permissions?.crossDomainImports && !isAllowedImportPath(config.emc)) {
+            throw new Error(`enhanceAll: EMC path "${config.emc}" is a cross-domain URL. ` +
+                `Only relative, absolute, or bare specifier paths are allowed by default. ` +
+                `Pass { crossDomainImports: true } in permissions to override.`);
+        }
+        // 1. Import the EMC JSON
+        const emcModule = await import(config.emc, { with: { type: 'json' } });
+        const emc = emcModule.default ?? emcModule;
+        const { enhConfig } = emc;
+        if (!enhConfig) {
+            throw new Error(`enhanceAll: EMC at "${config.emc}" does not contain an enhConfig field`);
+        }
+        // 2. Determine the selector
+        const selector = config.matching ?? enhConfig.matching ?? '*';
+        // 3. Find matching elements
+        const elements = target.querySelectorAll(selector);
+        if (elements.length === 0)
+            continue;
+        // 4. Resolve and register the enhancement
+        const registryItem = await resolveAndRegister(enhConfig, target);
+        if (!registryItem)
+            continue;
+        // 5. Spawn enhancement on each matched element
+        for (const el of elements) {
+            try {
+                el.enh.get(registryItem);
+            }
+            catch {
+                // If enh gateway isn't available, skip silently
+            }
+        }
+    }
+}
+/**
+ * Resolve the enhancement's registry item from EMC enhConfig.
+ * If not already registered, dynamically imports the spawn module and registers it.
+ */
+async function resolveAndRegister(enhConfig, target) {
+    const { enhKey, spawn: spawnPath } = enhConfig;
+    // Get the enhancement registry for this element's scope
+    const registry = target.customElementRegistry?.enhancementRegistry
+        ?? (typeof customElements !== 'undefined' ? customElements.enhancementRegistry : undefined);
+    if (!registry)
+        return null;
+    // Check if already registered
+    if (enhKey) {
+        const existing = registry.findByEnhKey(enhKey);
+        if (existing)
+            return existing;
+    }
+    // Not registered — dynamically import the spawn module
+    if (!spawnPath)
+        return null;
+    const spawnModule = await import(spawnPath);
+    const SpawnClass = spawnModule.default ?? Object.values(spawnModule).find((v) => typeof v === 'function' && v.prototype);
+    if (!SpawnClass)
+        return null;
+    // Build and register the registry item
+    const registryItem = {
+        spawn: SpawnClass,
+        enhKey,
+    };
+    // Include withAttrs if present in enhConfig
+    if (enhConfig.withAttrs) {
+        registryItem.withAttrs = enhConfig.withAttrs;
+    }
+    registry.push(registryItem);
+    return registryItem;
+}

package/enhanceAll.ts

@@ -0,0 +1,138 @@
+/**
+ * enhanceAll.ts — Bulk enhancement application via EMC (Element Mount Configuration) JSON.
+ * 
+ * Finds matching elements within a target and spawns enhancements on them
+ * using the configuration from EMC JSON files that enhancement packages publish.
+ * 
+ * Dynamically imported by assignFrom when `enhance` option is present,
+ * or used standalone.
+ * 
+ * @example
+ * import { enhanceAll } from 'assign-gingerly/enhanceAll.js';
+ * 
+ * await enhanceAll(shadowRoot, [
+ *     { emc: 'be-bound/emc.json', matching: '[name]' },
+ *     { emc: 'be-observant/emc.json', matching: '[itemprop]' },
+ * ]);
+ */
+
+import { isAllowedImportPath } from './isAllowedImportPath.js';
+import type { AssignPermissions } from './isAllowedImportPath.js';
+
+/**
+ * Configuration for a single enhancement to apply in bulk.
+ */
+export interface EnhanceConfig {
+    /** Path to the EMC JSON file (dynamically imported) */
+    emc: string;
+    /** Override the CSS selector from the EMC (optional) */
+    matching?: string;
+    /** Whether to parse attributes via withAttrs (default: false). Phase II feature. */
+    parse?: boolean;
+}
+
+/**
+ * Apply enhancements in bulk to matching elements within a target.
+ * 
+ * For each entry:
+ * 1. Dynamically imports the EMC JSON
+ * 2. Extracts enhConfig (spawn path, enhKey, withAttrs)
+ * 3. Finds matching elements via querySelectorAll
+ * 4. Registers the enhancement if not already registered
+ * 5. Spawns the enhancement on each matched element via enh.get()
+ * 
+ * Note: No scope perimeter is applied. For reactive observation of new elements,
+ * use mount-observer instead.
+ * 
+ * @param target - The DOM element to search within
+ * @param configs - Array of enhancement configurations
+ */
+export async function enhanceAll(
+    target: Element,
+    configs: EnhanceConfig[],
+    permissions?: AssignPermissions
+): Promise<void> {
+    for (const config of configs) {
+        // Validate EMC path unless cross-domain imports are explicitly permitted
+        if (!permissions?.crossDomainImports && !isAllowedImportPath(config.emc)) {
+            throw new Error(
+                `enhanceAll: EMC path "${config.emc}" is a cross-domain URL. ` +
+                `Only relative, absolute, or bare specifier paths are allowed by default. ` +
+                `Pass { crossDomainImports: true } in permissions to override.`
+            );
+        }
+
+        // 1. Import the EMC JSON
+        const emcModule = await import(config.emc, { with: { type: 'json' } });
+        const emc = emcModule.default ?? emcModule;
+        const { enhConfig } = emc;
+
+        if (!enhConfig) {
+            throw new Error(`enhanceAll: EMC at "${config.emc}" does not contain an enhConfig field`);
+        }
+
+        // 2. Determine the selector
+        const selector = config.matching ?? enhConfig.matching ?? '*';
+
+        // 3. Find matching elements
+        const elements = target.querySelectorAll(selector);
+        if (elements.length === 0) continue;
+
+        // 4. Resolve and register the enhancement
+        const registryItem = await resolveAndRegister(enhConfig, target);
+        if (!registryItem) continue;
+
+        // 5. Spawn enhancement on each matched element
+        for (const el of elements) {
+            try {
+                (el as any).enh.get(registryItem);
+            } catch {
+                // If enh gateway isn't available, skip silently
+            }
+        }
+    }
+}
+
+/**
+ * Resolve the enhancement's registry item from EMC enhConfig.
+ * If not already registered, dynamically imports the spawn module and registers it.
+ */
+async function resolveAndRegister(enhConfig: any, target: Element): Promise<any> {
+    const { enhKey, spawn: spawnPath } = enhConfig;
+
+    // Get the enhancement registry for this element's scope
+    const registry = (target as any).customElementRegistry?.enhancementRegistry
+        ?? (typeof customElements !== 'undefined' ? (customElements as any).enhancementRegistry : undefined);
+
+    if (!registry) return null;
+
+    // Check if already registered
+    if (enhKey) {
+        const existing = registry.findByEnhKey(enhKey);
+        if (existing) return existing;
+    }
+
+    // Not registered — dynamically import the spawn module
+    if (!spawnPath) return null;
+
+    const spawnModule = await import(spawnPath);
+    const SpawnClass = spawnModule.default ?? Object.values(spawnModule).find(
+        (v: any) => typeof v === 'function' && v.prototype
+    );
+
+    if (!SpawnClass) return null;
+
+    // Build and register the registry item
+    const registryItem: any = {
+        spawn: SpawnClass,
+        enhKey,
+    };
+
+    // Include withAttrs if present in enhConfig
+    if (enhConfig.withAttrs) {
+        registryItem.withAttrs = enhConfig.withAttrs;
+    }
+
+    registry.push(registryItem);
+    return registryItem;
+}

package/handlers/join.js

@@ -0,0 +1,74 @@
+/**
+ * builtIns.join handler for assignFrom.
+ *
+ * Joins a resolved array into a single string. Supports nested sub-arrays
+ * with "all-or-nothing" semantics: if any element in a nested sub-array
+ * resolves to null/undefined, the entire sub-array is dropped.
+ *
+ * This handler is auto-loaded by processHandlerCommands when `do: 'builtIns.join'`
+ * is encountered — no explicit import is needed.
+ *
+ * @example
+ * assignFrom(oElement, {
+ *     '?.textContent =>': {
+ *         do: 'builtIns.join',
+ *         resolve: {
+ *             value: ['?.lastName', ', ', '?.firstName']
+ *         }
+ *     }
+ * }, { from: vm });
+ *
+ * @example
+ * // With optional segment (all-or-nothing):
+ * assignFrom(oElement, {
+ *     '?.textContent =>': {
+ *         do: 'builtIns.join',
+ *         resolve: {
+ *             value: ['?.lastName', [', ', '?.middleName'], ', ', '?.firstName']
+ *         }
+ *     }
+ * }, { from: vm });
+ * // If middleName is undefined, the sub-array [', ', undefined] is dropped entirely.
+ */
+/**
+ * Process nested arrays with all-or-nothing null semantics.
+ * - Top-level null/undefined values are filtered out.
+ * - If a nested sub-array contains any null/undefined element, the entire sub-array is dropped.
+ * - Nested sub-arrays that pass are flattened into the result.
+ */
+function processValue(value) {
+    const result = [];
+    for (const item of value) {
+        if (Array.isArray(item)) {
+            // All-or-nothing: if any element is null/undefined, drop the entire sub-array
+            if (item.some(el => el == null)) {
+                continue;
+            }
+            // Sub-array passes — flatten its elements (recursively process nested arrays)
+            result.push(...processValue(item));
+        }
+        else if (item != null) {
+            result.push(item);
+        }
+        // Top-level null/undefined are silently filtered out
+    }
+    return result;
+}
+/**
+ * JoinHandler — built-in handler for composing strings from resolved arrays.
+ *
+ * Returns the joined string via the return-value protocol, which causes
+ * processHandlerCommands to assign it back to the LHS path.
+ */
+export class JoinHandler {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    async assign(lhsTarget, resolvedParams) {
+        const { value } = resolvedParams;
+        const separator = this.config.separator ?? '';
+        const items = Array.isArray(value) ? processValue(value) : [value];
+        return items.join(separator);
+    }
+}

package/handlers/join.ts

@@ -0,0 +1,80 @@
+/**
+ * builtIns.join handler for assignFrom.
+ * 
+ * Joins a resolved array into a single string. Supports nested sub-arrays
+ * with "all-or-nothing" semantics: if any element in a nested sub-array
+ * resolves to null/undefined, the entire sub-array is dropped.
+ * 
+ * This handler is auto-loaded by processHandlerCommands when `do: 'builtIns.join'`
+ * is encountered — no explicit import is needed.
+ * 
+ * @example
+ * assignFrom(oElement, {
+ *     '?.textContent =>': {
+ *         do: 'builtIns.join',
+ *         resolve: {
+ *             value: ['?.lastName', ', ', '?.firstName']
+ *         }
+ *     }
+ * }, { from: vm });
+ * 
+ * @example
+ * // With optional segment (all-or-nothing):
+ * assignFrom(oElement, {
+ *     '?.textContent =>': {
+ *         do: 'builtIns.join',
+ *         resolve: {
+ *             value: ['?.lastName', [', ', '?.middleName'], ', ', '?.firstName']
+ *         }
+ *     }
+ * }, { from: vm });
+ * // If middleName is undefined, the sub-array [', ', undefined] is dropped entirely.
+ */
+
+import type { AssignFromHandler } from '../assignFrom.js';
+
+/**
+ * Process nested arrays with all-or-nothing null semantics.
+ * - Top-level null/undefined values are filtered out.
+ * - If a nested sub-array contains any null/undefined element, the entire sub-array is dropped.
+ * - Nested sub-arrays that pass are flattened into the result.
+ */
+function processValue(value: any[]): any[] {
+    const result: any[] = [];
+    for (const item of value) {
+        if (Array.isArray(item)) {
+            // All-or-nothing: if any element is null/undefined, drop the entire sub-array
+            if (item.some(el => el == null)) {
+                continue;
+            }
+            // Sub-array passes — flatten its elements (recursively process nested arrays)
+            result.push(...processValue(item));
+        } else if (item != null) {
+            result.push(item);
+        }
+        // Top-level null/undefined are silently filtered out
+    }
+    return result;
+}
+
+/**
+ * JoinHandler — built-in handler for composing strings from resolved arrays.
+ * 
+ * Returns the joined string via the return-value protocol, which causes
+ * processHandlerCommands to assign it back to the LHS path.
+ */
+export class JoinHandler implements AssignFromHandler {
+    config: any;
+
+    constructor(config: any) {
+        this.config = config;
+    }
+
+    async assign(lhsTarget: any, resolvedParams: Record<string, any>): Promise<string> {
+        const { value } = resolvedParams;
+        const separator = this.config.separator ?? '';
+
+        const items = Array.isArray(value) ? processValue(value) : [value];
+        return items.join(separator);
+    }
+}