assign-gingerly 0.0.54 → 0.0.56

package/processHandlerCommands.js

@@ -5,6 +5,7 @@
  */
 import { resolveValues } from './resolveValues.js';
 import { evaluatePathWithMethods } from './assignGingerly.js';
+import { isAllowedImportPath } from './isAllowedImportPath.js';
 /**
  * Map of built-in handler names to their module paths.
  * These are auto-loaded on demand — no explicit import required.
@@ -15,22 +16,17 @@ const BUILT_IN_MAP = {
     'builtIns.join': './handlers/join.js',
     'builtIns.microDataJoin': './handlers/microDataJoin.js',
 };
-/**
- * Check if an import path is allowed (non-cross-domain).
- */
-function isAllowedImportPath(path) {
-    return path.startsWith('./') || path.startsWith('../') || path.startsWith('/')
-        || (!path.includes('://') && !path.startsWith('//'));
-}
 /**
  * Find a handler class in a dynamically imported module.
  * Checks default export first, then searches for the first class with `assign` on prototype.
  */
 function findHandlerInModule(module) {
+    // Check default export first
     if (module.default && typeof module.default === 'function'
         && module.default.prototype && 'assign' in module.default.prototype) {
         return module.default;
     }
+    // Search other exports
     for (const key of Object.keys(module)) {
         const exported = module[key];
         if (typeof exported === 'function' && exported.prototype && 'assign' in exported.prototype) {
@@ -41,6 +37,7 @@ function findHandlerInModule(module) {
 }
 /**
  * Dynamically load a built-in handler by name.
+ * Returns the handler constructor, or undefined if the name isn't a recognized built-in.
  */
 async function loadBuiltIn(name) {
     const path = BUILT_IN_MAP[name];
@@ -52,26 +49,25 @@ async function loadBuiltIn(name) {
 /**
  * Resolve a handler from options.handlers (class constructor or import path).
  */
-async function resolveFromHandlers(name, handlers) {
+async function resolveFromHandlers(name, handlers, permissions) {
     if (!handlers || !(name in handlers))
         return undefined;
     const entry = handlers[name];
+    // Class constructor — use directly
     if (typeof entry === 'function') {
         return entry;
     }
+    // Import path string — validate and dynamically import
     if (typeof entry === 'string') {
-        if (!isAllowedImportPath(entry)) {
-            throw new Error(
-                `assignFrom: handler "${name}" has an invalid import path "${entry}". ` +
-                `Only relative, absolute, or bare specifier paths are allowed (no cross-domain URLs).`
-            );
+        if (!permissions?.crossDomainImports && !isAllowedImportPath(entry)) {
+            throw new Error(`assignFrom: handler "${name}" has an invalid import path "${entry}". ` +
+                `Only relative, absolute, or bare specifier paths are allowed (no cross-domain URLs). ` +
+                `Pass { crossDomainImports: true } in permissions to override.`);
         }
         const module = await import(entry);
         const HandlerClass = findHandlerInModule(module);
         if (!HandlerClass) {
-            throw new Error(
-                `assignFrom: handler "${name}" — module "${entry}" does not export a valid handler class.`
-            );
+            throw new Error(`assignFrom: handler "${name}" — module "${entry}" does not export a valid handler class.`);
         }
         return HandlerClass;
     }
@@ -84,8 +80,9 @@ async function resolveFromHandlers(name, handlers) {
  * @param handlerKeys - Array of keys ending with ' =>'
  * @param pattern - The original pattern object
  * @param options - The assignFrom options
+ * @param handlerRegistry - The registry of handler classes
  */
-export async function processHandlerCommands(target, handlerKeys, pattern, options) {
+export async function processHandlerCommands(target, handlerKeys, pattern, options, permissions) {
     for (const key of handlerKeys) {
         const lhsPath = key.substring(0, key.length - 3); // Remove ' =>'
         const rhs = pattern[key];
@@ -104,6 +101,7 @@ export async function processHandlerCommands(target, handlerKeys, pattern, optio
         if (configs.length === 0)
             continue;
         // Resolve the LHS path, preserving parent + key for return-value assignment.
+        // lhsParent[lhsKey] === lhsTarget (the current value at the path)
         let lhsTarget;
         let lhsParent = undefined;
         let lhsKey = undefined;
@@ -119,13 +117,15 @@ export async function processHandlerCommands(target, handlerKeys, pattern, optio
                 lhsParent = result.target;
                 lhsKey = result.lastKey;
                 lhsTarget = result.target[result.lastKey];
+                // If last key is a method, call it to get the target
                 if (result.isMethod && typeof result.target[result.lastKey] === 'function') {
                     lhsTarget = result.target[result.lastKey].call(result.target);
-                    lhsParent = undefined;
+                    lhsParent = undefined; // Can't assign back to a method call result
                     lhsKey = undefined;
                 }
             }
             else {
+                // Simple path navigation — walk to parent, keep last key
                 if (pathParts.length === 0) {
                     lhsTarget = target;
                 }
@@ -158,7 +158,7 @@ export async function processHandlerCommands(target, handlerKeys, pattern, optio
         // Execute handlers sequentially, sharing the same lhsTarget
         for (const config of configs) {
             // 1. Check options.handlers (local, per-call)
-            let HandlerClass = await resolveFromHandlers(config.do, options.handlers);
+            let HandlerClass = await resolveFromHandlers(config.do, options.handlers, permissions);
             // 2. Fallback to built-in auto-load
             if (!HandlerClass && config.do.startsWith('builtIns.')) {
                 HandlerClass = await loadBuiltIn(config.do);

package/processHandlerCommands.ts

@@ -6,6 +6,8 @@
 
 import { resolveValues } from './resolveValues.js';
 import { evaluatePathWithMethods } from './assignGingerly.js';
+import { isAllowedImportPath } from './isAllowedImportPath.js';
+import type { AssignPermissions } from './isAllowedImportPath.js';
 import type { AssignFromOptions, AssignFromHandlerConstructor } from './assignFrom.js';
 
 /**
@@ -19,14 +21,6 @@ const BUILT_IN_MAP: Record<string, string> = {
     'builtIns.microDataJoin': './handlers/microDataJoin.js',
 };
 
-/**
- * Check if an import path is allowed (non-cross-domain).
- */
-function isAllowedImportPath(path: string): boolean {
-    return path.startsWith('./') || path.startsWith('../') || path.startsWith('/')
-        || (!path.includes('://') && !path.startsWith('//'));
-}
-
 /**
  * Find a handler class in a dynamically imported module.
  * Checks default export first, then searches for the first class with `assign` on prototype.
@@ -63,7 +57,8 @@ async function loadBuiltIn(name: string): Promise<AssignFromHandlerConstructor |
  */
 async function resolveFromHandlers(
     name: string,
-    handlers: Record<string, AssignFromHandlerConstructor | string> | undefined
+    handlers: Record<string, AssignFromHandlerConstructor | string> | undefined,
+    permissions?: AssignPermissions
 ): Promise<AssignFromHandlerConstructor | undefined> {
     if (!handlers || !(name in handlers)) return undefined;
 
@@ -76,10 +71,11 @@ async function resolveFromHandlers(
 
     // Import path string — validate and dynamically import
     if (typeof entry === 'string') {
-        if (!isAllowedImportPath(entry)) {
+        if (!permissions?.crossDomainImports && !isAllowedImportPath(entry)) {
             throw new Error(
                 `assignFrom: handler "${name}" has an invalid import path "${entry}". ` +
-                `Only relative, absolute, or bare specifier paths are allowed (no cross-domain URLs).`
+                `Only relative, absolute, or bare specifier paths are allowed (no cross-domain URLs). ` +
+                `Pass { crossDomainImports: true } in permissions to override.`
             );
         }
         const module = await import(entry);
@@ -108,7 +104,8 @@ export async function processHandlerCommands(
     target: any,
     handlerKeys: string[],
     pattern: Record<string, any>,
-    options: AssignFromOptions
+    options: AssignFromOptions,
+    permissions?: AssignPermissions
 ): Promise<void> {
     for (const key of handlerKeys) {
         const lhsPath = key.substring(0, key.length - 3); // Remove ' =>'
@@ -185,7 +182,7 @@ export async function processHandlerCommands(
         // Execute handlers sequentially, sharing the same lhsTarget
         for (const config of configs) {
             // 1. Check options.handlers (local, per-call)
-            let HandlerClass = await resolveFromHandlers(config.do, options.handlers);
+            let HandlerClass = await resolveFromHandlers(config.do, options.handlers, permissions);
 
             // 2. Fallback to built-in auto-load
             if (!HandlerClass && config.do.startsWith('builtIns.')) {

package/resolveIdRef.js

@@ -1,125 +1,144 @@
-/**
- * resolveIdRef.js — Cached element resolution via #[x] syntax.
- *
- * Dynamically imported by assignFrom when `withIds` is provided or `#[x]` patterns are detected.
- * Provides lazy, WeakRef-cached element lookups keyed by variable name.
- *
- * First access: runs the query against the target, auto-assigns an ID if needed, caches via WeakRef.
- * Subsequent access: WeakRef.deref() (~10ns) or getElementById fallback (~20-100ns).
- */
-
-/**
- * Module-level cache: rootNode → Map<varName, { id, WeakRef }>
- * WeakMap ensures cleanup when rootNode is GC'd.
- */
-const idCacheMap = new WeakMap();
-
-/**
- * Counter per rootNode for generating unique IDs.
- */
-const idCounterMap = new WeakMap();
-
-/**
- * Generate a unique ID within a rootNode.
- * Format: _ag0, _ag1, _ag2, ...
- */
-function generateUniqueId(rootNode) {
-    let counter = idCounterMap.get(rootNode) ?? 0;
-    let id;
-    // Ensure uniqueness (skip if ID already exists in the document)
-    do {
-        id = `_ag${counter}`;
-        counter++;
-    } while (rootNode.getElementById?.(id));
-    idCounterMap.set(rootNode, counter);
-    return id;
-}
-
-/**
- * Resolve a single #[varName] reference lazily.
- *
- * @param varName - The variable name (e.g., 'x' from '#[x]')
- * @param target - The target element to query against
- * @param withIds - The withIds configuration map
- * @returns The resolved element, or undefined if not found
- */
-export function resolveIdVariable(varName, target, withIds) {
-    const config = withIds[varName];
-    if (config === undefined) return undefined;
-
-    const rootNode = target.getRootNode?.() ?? target;
-
-    // Get or create cache for this rootNode
-    let cache = idCacheMap.get(rootNode);
-    if (!cache) {
-        cache = new Map();
-        idCacheMap.set(rootNode, cache);
-    }
-
-    // Check cache first
-    const cached = cache.get(varName);
-    if (cached) {
-        const el = cached.ref.deref();
-        if (el) return el;
-
-        // WeakRef was collected — try getElementById fallback
-        const el2 = rootNode.getElementById?.(cached.id);
-        if (el2) {
-            cache.set(varName, { id: cached.id, ref: new WeakRef(el2) });
-            return el2;
-        }
-        // Element no longer exists — fall through to re-query
-    }
-
-    // First time or cache miss — resolve the element
-    let el = null;
-
-    if (typeof config === 'string') {
-        // String form: existing ID — use getElementById directly
-        el = rootNode.getElementById?.(config) ?? null;
-    } else {
-        // Object form: { qry } — run querySelector against target
-        el = target.querySelector?.(config.qry) ?? null;
-    }
-
-    if (!el) return undefined;
-
-    // Ensure the element has an ID
-    let id = el.id;
-    if (!id) {
-        id = generateUniqueId(rootNode);
-        el.id = id;
-    }
-
-    // Cache it
-    cache.set(varName, { id, ref: new WeakRef(el) });
-    return el;
-}
-
-/**
- * Check if a key starts with #[...] syntax.
- */
-export function hasIdRef(key) {
-    return key.startsWith('#[');
-}
-
-/**
- * Extract the variable name and remaining path from a #[x]... key.
- * Returns { varName, remainingPath } or null if not valid.
- */
-export function parseIdRef(key) {
-    const closeIdx = key.indexOf(']');
-    if (closeIdx === -1) return null;
-
-    const varName = key.substring(2, closeIdx); // skip '#['
-    if (!varName) return null;
-
-    let remainingPath = key.substring(closeIdx + 1);
-
-    // Remove handler suffix if present (caller handles it separately)
-    if (remainingPath.endsWith(' =>')) {
-        remainingPath = remainingPath.substring(0, remainingPath.length - 3);
-    }
-
-    return { varName, remainingPath };
-}
+/**
+ * resolveIdRef.ts — Cached element resolution via #[x] syntax.
+ *
+ * Dynamically imported by assignFrom when `withIds` is provided or `#[x]` patterns are detected.
+ * Provides lazy, WeakRef-cached element lookups keyed by variable name.
+ *
+ * First access: runs the query against the target, auto-assigns an ID if needed, caches via WeakRef.
+ * Subsequent access: WeakRef.deref() (~10ns) or getElementById fallback (~20-100ns).
+ */
+/**
+ * Module-level cache: rootNode → Map<varName, { id, WeakRef }>
+ * WeakMap ensures cleanup when rootNode is GC'd.
+ */
+const idCacheMap = new WeakMap();
+/**
+ * Counter per rootNode for generating unique IDs.
+ */
+const idCounterMap = new WeakMap();
+/**
+ * Generate a unique ID within a rootNode.
+ * Format: _ag0, _ag1, _ag2, ...
+ */
+function generateUniqueId(rootNode) {
+    let counter = idCounterMap.get(rootNode) ?? 0;
+    let id;
+    // Ensure uniqueness (skip if ID already exists in the document)
+    do {
+        id = `_ag${counter}`;
+        counter++;
+    } while (rootNode.getElementById?.(id));
+    idCounterMap.set(rootNode, counter);
+    return id;
+}
+/**
+ * Resolve a single #[varName] reference lazily.
+ *
+ * @param varName - The variable name (e.g., 'x' from '#[x]')
+ * @param target - The target element to query against
+ * @param withIds - The withIds configuration map
+ * @returns The resolved element, or undefined if not found
+ */
+export function resolveIdVariable(varName, target, withIds) {
+    const config = withIds[varName];
+    if (config === undefined)
+        return undefined;
+    const rootNode = target.getRootNode?.() ?? target;
+    // Get or create cache for this rootNode
+    let cache = idCacheMap.get(rootNode);
+    if (!cache) {
+        cache = new Map();
+        idCacheMap.set(rootNode, cache);
+    }
+    // Check cache first
+    const cached = cache.get(varName);
+    if (cached) {
+        const el = cached.ref.deref();
+        if (el)
+            return el;
+        // WeakRef was collected — try getElementById fallback
+        const el2 = rootNode.getElementById?.(cached.id);
+        if (el2) {
+            cache.set(varName, { id: cached.id, ref: new WeakRef(el2) });
+            return el2;
+        }
+        // Element no longer exists — fall through to re-query
+    }
+    // First time or cache miss — resolve the element
+    let el = null;
+    if (typeof config === 'string') {
+        // String form: existing ID — use getElementById directly
+        el = rootNode.getElementById?.(config) ?? null;
+    }
+    else {
+        // Object form: { qry } — run querySelector against target
+        el = target.querySelector?.(config.qry) ?? null;
+    }
+    if (!el)
+        return undefined;
+    // Ensure the element has an ID
+    let id = el.id;
+    if (!id) {
+        id = generateUniqueId(rootNode);
+        el.id = id;
+    }
+    // Cache it
+    cache.set(varName, { id, ref: new WeakRef(el) });
+    return el;
+}
+/**
+ * Check if a key starts with #[...] syntax.
+ */
+export function hasIdRef(key) {
+    return key.startsWith('#[');
+}
+/**
+ * Extract the variable name and remaining path from a #[x]... key.
+ * Returns [varName, remainingPath] or null if not a valid #[x] reference.
+ *
+ * Examples:
+ *   '#[x]' → ['x', '']
+ *   '#[x] =>' → ['x', '']  (handler suffix handled separately)
+ *   '#[x]?.querySelector?..child' → ['x', '?.querySelector?..child']
+ *   '#[x]?.textContent =>' → ['x', '?.textContent']  (handler suffix handled separately)
+ */
+export function parseIdRef(key) {
+    const closeIdx = key.indexOf(']');
+    if (closeIdx === -1)
+        return null;
+    const varName = key.substring(2, closeIdx); // skip '#['
+    if (!varName)
+        return null;
+    let remainingPath = key.substring(closeIdx + 1);
+    // Remove handler suffix if present (caller handles it separately)
+    if (remainingPath.endsWith(' =>')) {
+        remainingPath = remainingPath.substring(0, remainingPath.length - 3);
+    }
+    return { varName, remainingPath };
+}
+/**
+ * Register an element in the WeakRef cache for fast subsequent access.
+ * Auto-assigns an ID if the element doesn't have one.
+ *
+ * Used by beVigilant to cache newly discovered elements so that future
+ * assignFrom calls can resolve them via getElementById/WeakRef.
+ *
+ * @param target - The target element (used to determine rootNode)
+ * @param varName - The cache key (typically the itemprop name)
+ * @param element - The element to cache
+ */
+export function registerInCache(target, varName, element) {
+    const rootNode = target.getRootNode?.() ?? target;
+    let cache = idCacheMap.get(rootNode);
+    if (!cache) {
+        cache = new Map();
+        idCacheMap.set(rootNode, cache);
+    }
+    // Ensure the element has an ID
+    let id = element.id;
+    if (!id) {
+        id = generateUniqueId(rootNode);
+        element.id = id;
+    }
+    cache.set(varName, { id, ref: new WeakRef(element) });
+}

package/resolveIdRef.ts

@@ -138,3 +138,33 @@ export function parseIdRef(key: string): { varName: string; remainingPath: strin
 
     return { varName, remainingPath };
 }
+
+/**
+ * Register an element in the WeakRef cache for fast subsequent access.
+ * Auto-assigns an ID if the element doesn't have one.
+ * 
+ * Used by beVigilant to cache newly discovered elements so that future
+ * assignFrom calls can resolve them via getElementById/WeakRef.
+ * 
+ * @param target - The target element (used to determine rootNode)
+ * @param varName - The cache key (typically the itemprop name)
+ * @param element - The element to cache
+ */
+export function registerInCache(target: any, varName: string, element: Element): void {
+    const rootNode = target.getRootNode?.() ?? target;
+
+    let cache = idCacheMap.get(rootNode);
+    if (!cache) {
+        cache = new Map();
+        idCacheMap.set(rootNode, cache);
+    }
+
+    // Ensure the element has an ID
+    let id = element.id;
+    if (!id) {
+        id = generateUniqueId(rootNode);
+        element.id = id;
+    }
+
+    cache.set(varName, { id, ref: new WeakRef(element) });
+}

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

@@ -64,6 +64,12 @@ export interface EnhancementConfig<T = any, Obj = Element> extends EnhancementCo
 
   //only applicable when spawning from a DOM Element reference
   enhKey?: EnhKey;
+
+  /**
+   * Optional features to associate with the spawn class.
+   * Calls assignFeatures(spawn, features) automatically on registration.
+   */
+  features?: FeatureConfigsMap;
     
 }
 
@@ -300,6 +306,12 @@ export interface ItemscopeManagerConfig<T = any> {
     dispose?: string | symbol;
     resolved?: string | symbol;
   };
+
+  /**
+   * Optional features to associate with the manager class.
+   * Calls assignFeatures(manager, features) automatically on registration.
+   */
+  features?: FeatureConfigsMap;
 }
 
 /**
@@ -526,15 +538,90 @@ export interface LazyLoadConfig extends HandlerConfig {
         if: string;
         /** Template element to clone (resolved via protocol or path) */
         instantiate: string;
+        /** Insert method: 'appendChild' (default), 'prepend', or 'after' (sibling after target) */
+        method?: string;
+        /** If true, removes nodes when hiding instead of adding hidden attribute */
+        forget?: boolean | string;
+        /** Enable view transitions */
+        transitional?: boolean | string;
+        /** CSS class for hiding (default: 'ag-hide', only used when transitional: true) */
+        hideClass?: string;
+        /** Optional async callback invoked after cloning, resolved from the VM */
+        onInstantiated?: string;
+        /** Override auto-derived marker name */
+        markerName?: string;
+        /** Set inert attribute on hidden elements */
+        toggleInert?: boolean | string;
+        /** Set disabled property on hidden form elements */
+        toggleDisabled?: boolean | string;
+    };
+}
+
+/**
+ * Resolved parameters received by LazyLoadHandler.assign() after resolveValues processing.
+ */
+export interface LazyLoadResolvedParams {
+    /** Condition — resolved to actual truthy/falsy value */
+    if: any;
+    /** Template element — resolved to HTMLTemplateElement or DocumentFragment */
+    instantiate: HTMLTemplateElement | DocumentFragment;
+    /** Insertion method (default: 'appendChild') */
+    method?: 'appendChild' | 'prepend' | 'after';
+    /** Remove nodes on hide instead of using hidden attribute */
+    forget?: boolean;
+    /** Enable view transitions */
+    transitional?: boolean;
+    /** CSS class for hiding (default: 'ag-hide', only used when transitional: true) */
+    hideClass?: string;
+    /** Callback after clone+insert */
+    onInstantiated?: (ctx: LazyLoadInstantiatedContext) => void | Promise<void>;
+    /** Override auto-derived marker name */
+    markerName?: string;
+    /** Set inert attribute on hidden elements (removes from a11y tree + interaction) */
+    toggleInert?: boolean;
+    /** Set disabled property on hidden form elements */
+    toggleDisabled?: boolean;
+}
+
+/**
+ * Configuration for the builtIns.lazyLoadSwitch handler.
+ */
+export interface LazyLoadSwitchConfig extends HandlerConfig {
+    do: 'builtIns.lazyLoadSwitch';
+    resolve: {
+        /** Left-hand side of comparison (resolved from VM) */
+        lhs: string;
+        /** Comparison operator (default: '===') */
+        op?: '===' | '!==' | '==' | '!=' | '<' | '>' | '<=' | '>=';
+        /** Right-hand side of comparison (resolved from VM or literal) */
+        rhs: string;
+        /** Template element to clone (resolved via protocol or path) */
+        instantiate: string;
         /** Insert method: 'appendChild' (default) or 'prepend' */
         method?: string;
         /** If true, removes nodes when hiding instead of adding hidden attribute */
         forget?: boolean | string;
+        /** Enable view transitions */
+        transitional?: boolean | string;
+        /** CSS class for hiding (default: 'ag-hide', only used when transitional: true) */
+        hideClass?: string;
         /** Optional async callback invoked after cloning, resolved from the VM */
         onInstantiated?: string;
     };
 }
 
+/**
+ * Resolved parameters received by LazyLoadSwitchHandler.assign() after resolveValues processing.
+ */
+export interface LazyLoadSwitchResolvedParams extends Omit<LazyLoadResolvedParams, 'if'> {
+    /** Left-hand side — resolved to actual value */
+    lhs: any;
+    /** Comparison operator (default: '===') */
+    op?: '===' | '!==' | '==' | '!=' | '<' | '>' | '<=' | '>=';
+    /** Right-hand side — resolved to actual value */
+    rhs: any;
+}
+
 /**
  * Context passed to onInstantiated callbacks after template cloning.
  */