assign-gingerly 0.0.64 → 0.0.66

package/getValues.js

@@ -16,6 +16,38 @@
  *     count: 42
  * }, source, { withMethods: ['querySelector'], aka: { q: 'querySelector' } });
  */
+export function normalizeAliasOptions(options) {
+    const aliasMap = new Map();
+    if (options?.aka) {
+        for (const [alias, target] of Object.entries(options.aka)) {
+            if (alias.includes(' ') || alias.includes('`')) {
+                throw new Error(`Invalid alias '${alias}': aliases cannot contain space or backtick characters`);
+            }
+            aliasMap.set(alias, target);
+        }
+    }
+    if (options?.akaMethods) {
+        for (const [alias, target] of Object.entries(options.akaMethods)) {
+            if (alias.includes(' ') || alias.includes('`')) {
+                throw new Error(`Invalid alias '${alias}': aliases cannot contain space or backtick characters`);
+            }
+            aliasMap.set(alias, target);
+        }
+    }
+    const withMethods = options?.withMethods
+        ? options.withMethods instanceof Set
+            ? new Set(options.withMethods)
+            : new Set(options.withMethods)
+        : options?.akaMethods
+            ? new Set()
+            : undefined;
+    if (options?.akaMethods) {
+        for (const target of Object.values(options.akaMethods)) {
+            withMethods?.add(target);
+        }
+    }
+    return { aliasMap, withMethods };
+}
 /**
  * Apply alias substitutions to a path string.
  * Replaces complete tokens between `?.` delimiters with their aliased values.
@@ -27,6 +59,17 @@ function applyAliases(path, aliasMap) {
     const substituted = parts.map(part => aliasMap.get(part) ?? part);
     return substituted.join('?.');
 }
+/**
+ * Resolve a special root-reference token at the start of a string.
+ * '$0' refers to the first argument passed to assignFrom / resolveValues.
+ */
+function resolveRootReference(path, source, root) {
+    if (path === '$0')
+        return { source: root ?? source, path: '' };
+    if (path.startsWith('$0?.'))
+        return { source: root ?? source, path: path.substring(4) };
+    return null;
+}
 /**
  * Path cache for parsed path strings.
  * Avoids re-splitting the same path on repeated calls.
@@ -116,6 +159,18 @@ function getArray(arr, source, aliasMap, withMethods, protocols, options) {
             const parts = parseCachedPath(aliased);
             result.push(parts.length === 0 ? source : navigatePath(source, parts, withMethods));
         }
+        else if (typeof item === 'string' && item.startsWith('$0')) {
+            const rootRef = resolveRootReference(item, source, options?.root);
+            if (rootRef === null) {
+                result.push(source);
+            }
+            else {
+                const aliased = applyAliases(rootRef.path, aliasMap);
+                const normalizedPath = aliased.startsWith('?.') ? aliased : (aliased ? `?.${aliased}` : '?.');
+                const parts = parseCachedPath(normalizedPath);
+                result.push(parts.length === 0 ? rootRef.source : navigatePath(rootRef.source, parts, withMethods));
+            }
+        }
         else if (typeof item === 'string' && protocols && hasProtocol(item)) {
             result.push(getProtocolValue(item, protocols, options));
         }
@@ -150,19 +205,7 @@ function getArray(arr, source, aliasMap, withMethods, protocols, options) {
  * @returns New object with path strings replaced by resolved values
  */
 export function getValues(pattern, source, options) {
-    // Build alias map
-    const aliasMap = new Map();
-    if (options?.aka) {
-        for (const [alias, target] of Object.entries(options.aka)) {
-            aliasMap.set(alias, target);
-        }
-    }
-    // Build methods set
-    const withMethods = options?.withMethods
-        ? options.withMethods instanceof Set
-            ? options.withMethods
-            : new Set(options.withMethods)
-        : undefined;
+    const { aliasMap, withMethods } = normalizeAliasOptions(options);
     const protocols = options?.protocols;
     const result = {};
     for (const [key, value] of Object.entries(pattern)) {
@@ -171,6 +214,18 @@ export function getValues(pattern, source, options) {
             const parts = parseCachedPath(aliased);
             result[key] = parts.length === 0 ? source : navigatePath(source, parts, withMethods);
         }
+        else if (typeof value === 'string' && value.startsWith('$0')) {
+            const rootRef = resolveRootReference(value, source, options?.root);
+            if (rootRef === null) {
+                result[key] = source;
+            }
+            else {
+                const aliased = applyAliases(rootRef.path, aliasMap);
+                const normalizedPath = aliased.startsWith('?.') ? aliased : (aliased ? `?.${aliased}` : '?.');
+                const parts = parseCachedPath(normalizedPath);
+                result[key] = parts.length === 0 ? rootRef.source : navigatePath(rootRef.source, parts, withMethods);
+            }
+        }
         else if (typeof value === 'string' && protocols && hasProtocol(value)) {
             result[key] = getProtocolValue(value, protocols, options);
         }
@@ -201,23 +256,23 @@ export function getValues(pattern, source, options) {
  * @returns The resolved value, or undefined if any segment is nullish
  */
 export function getValue(path, source, options) {
-    if (!path.startsWith('?.'))
+    const rootRef = resolveRootReference(path, source, options?.root);
+    if (rootRef) {
+        path = rootRef.path;
+        source = rootRef.source;
+    }
+    else if (!path.startsWith('?.')) {
         return path;
+    }
     let aliased = path;
-    if (options?.aka) {
-        const aliasMap = new Map();
-        for (const [alias, target] of Object.entries(options.aka)) {
-            aliasMap.set(alias, target);
-        }
+    const { aliasMap } = normalizeAliasOptions(options);
+    if (aliasMap.size > 0) {
         aliased = applyAliases(path, aliasMap);
     }
-    const parts = parseCachedPath(aliased);
+    const normalizedPath = aliased.startsWith('?.') ? aliased : (aliased ? `?.${aliased}` : '?.');
+    const parts = parseCachedPath(normalizedPath);
     if (parts.length === 0)
         return source;
-    const withMethods = options?.withMethods
-        ? options.withMethods instanceof Set
-            ? options.withMethods
-            : new Set(options.withMethods)
-        : undefined;
+    const { withMethods } = normalizeAliasOptions(options);
     return navigatePath(source, parts, withMethods);
 }

package/getValues.ts

@@ -19,6 +19,48 @@
 
 import type { GetValuesOptions } from './types/assign-gingerly/types.js';
 
+export function normalizeAliasOptions(options?: {
+    aka?: Record<string, string>;
+    akaMethods?: Record<string, string>;
+    withMethods?: string[] | Set<string>;
+}): { aliasMap: Map<string, string>; withMethods: Set<string> | undefined } {
+    const aliasMap = new Map<string, string>();
+
+    if (options?.aka) {
+        for (const [alias, target] of Object.entries(options.aka)) {
+            if (alias.includes(' ') || alias.includes('`')) {
+                throw new Error(`Invalid alias '${alias}': aliases cannot contain space or backtick characters`);
+            }
+            aliasMap.set(alias, target);
+        }
+    }
+
+    if (options?.akaMethods) {
+        for (const [alias, target] of Object.entries(options.akaMethods)) {
+            if (alias.includes(' ') || alias.includes('`')) {
+                throw new Error(`Invalid alias '${alias}': aliases cannot contain space or backtick characters`);
+            }
+            aliasMap.set(alias, target);
+        }
+    }
+
+    const withMethods = options?.withMethods
+        ? options.withMethods instanceof Set
+            ? new Set(options.withMethods)
+            : new Set(options.withMethods)
+        : options?.akaMethods
+            ? new Set<string>()
+            : undefined;
+
+    if (options?.akaMethods) {
+        for (const target of Object.values(options.akaMethods)) {
+            withMethods?.add(target);
+        }
+    }
+
+    return { aliasMap, withMethods };
+}
+
 /**
  * Apply alias substitutions to a path string.
  * Replaces complete tokens between `?.` delimiters with their aliased values.
@@ -30,6 +72,16 @@ function applyAliases(path: string, aliasMap: Map<string, string>): string {
     return substituted.join('?.');
 }
 
+/**
+ * Resolve a special root-reference token at the start of a string.
+ * '$0' refers to the first argument passed to assignFrom / resolveValues.
+ */
+function resolveRootReference(path: string, source: any, root: any): { source: any; path: string } | null {
+    if (path === '$0') return { source: root ?? source, path: '' };
+    if (path.startsWith('$0?.')) return { source: root ?? source, path: path.substring(4) };
+    return null;
+}
+
 /**
  * Path cache for parsed path strings.
  * Avoids re-splitting the same path on repeated calls.
@@ -142,6 +194,16 @@ function getArray(
             const aliased = applyAliases(item, aliasMap);
             const parts = parseCachedPath(aliased);
             result.push(parts.length === 0 ? source : navigatePath(source, parts, withMethods));
+        } else if (typeof item === 'string' && item.startsWith('$0')) {
+            const rootRef = resolveRootReference(item, source, options?.root);
+            if (rootRef === null) {
+                result.push(source);
+            } else {
+                const aliased = applyAliases(rootRef.path, aliasMap);
+                const normalizedPath = aliased.startsWith('?.') ? aliased : (aliased ? `?.${aliased}` : '?.');
+                const parts = parseCachedPath(normalizedPath);
+                result.push(parts.length === 0 ? rootRef.source : navigatePath(rootRef.source, parts, withMethods));
+            }
         } else if (typeof item === 'string' && protocols && hasProtocol(item)) {
             result.push(getProtocolValue(item, protocols, options));
         } else if (Array.isArray(item)) {
@@ -177,20 +239,7 @@ export function getValues(
     source: any,
     options?: GetValuesOptions
 ): Record<string, any> {
-    // Build alias map
-    const aliasMap = new Map<string, string>();
-    if (options?.aka) {
-        for (const [alias, target] of Object.entries(options.aka)) {
-            aliasMap.set(alias, target);
-        }
-    }
-
-    // Build methods set
-    const withMethods = options?.withMethods
-        ? options.withMethods instanceof Set
-            ? options.withMethods
-            : new Set(options.withMethods)
-        : undefined;
+    const { aliasMap, withMethods } = normalizeAliasOptions(options);
 
     const protocols = options?.protocols;
 
@@ -200,6 +249,16 @@ export function getValues(
             const aliased = applyAliases(value, aliasMap);
             const parts = parseCachedPath(aliased);
             result[key] = parts.length === 0 ? source : navigatePath(source, parts, withMethods);
+        } else if (typeof value === 'string' && value.startsWith('$0')) {
+            const rootRef = resolveRootReference(value, source, options?.root);
+            if (rootRef === null) {
+                result[key] = source;
+            } else {
+                const aliased = applyAliases(rootRef.path, aliasMap);
+                const normalizedPath = aliased.startsWith('?.') ? aliased : (aliased ? `?.${aliased}` : '?.');
+                const parts = parseCachedPath(normalizedPath);
+                result[key] = parts.length === 0 ? rootRef.source : navigatePath(rootRef.source, parts, withMethods);
+            }
         } else if (typeof value === 'string' && protocols && hasProtocol(value)) {
             result[key] = getProtocolValue(value, protocols, options);
         } else if (Array.isArray(value)) {
@@ -231,25 +290,25 @@ export function getValue(
     source: any,
     options?: GetValuesOptions
 ): any {
-    if (!path.startsWith('?.')) return path;
+    const rootRef = resolveRootReference(path, source, options?.root);
+    if (rootRef) {
+        path = rootRef.path;
+        source = rootRef.source;
+    } else if (!path.startsWith('?.')) {
+        return path;
+    }
 
     let aliased = path;
-    if (options?.aka) {
-        const aliasMap = new Map<string, string>();
-        for (const [alias, target] of Object.entries(options.aka)) {
-            aliasMap.set(alias, target);
-        }
+    const { aliasMap } = normalizeAliasOptions(options);
+    if (aliasMap.size > 0) {
         aliased = applyAliases(path, aliasMap);
     }
 
-    const parts = parseCachedPath(aliased);
+    const normalizedPath = aliased.startsWith('?.') ? aliased : (aliased ? `?.${aliased}` : '?.');
+    const parts = parseCachedPath(normalizedPath);
     if (parts.length === 0) return source;
 
-    const withMethods = options?.withMethods
-        ? options.withMethods instanceof Set
-            ? options.withMethods
-            : new Set(options.withMethods)
-        : undefined;
+    const { withMethods } = normalizeAliasOptions(options);
 
     return navigatePath(source, parts, withMethods);
 }

package/handlers/addEventListener.js

@@ -0,0 +1,153 @@
+/**
+ * handlers/addEventListener.ts — Event binding handler for += operator.
+ *
+ * Dynamically imported when assignGingerly/assignFrom detects an += with
+ * an object RHS containing an `on` property on a DOM Element LHS.
+ *
+ * Attaches an event listener that executes assign vectors on event fire.
+ */
+import assignGingerly from '../assignGingerly.js';
+/**
+ * WeakMap for dedup: Element → Map<key, AbortController>
+ */
+const keyMap = new WeakMap();
+/**
+ * Reserved keys that are not shorthand assign patterns.
+ */
+const RESERVED_KEYS = new Set([
+    'on', 'get', 'fromLHS', 'fromHost', 'fromEvent', 'fromTarget',
+    'toTarget', 'toHost', 'toLHS', 'withOptions', 'toTargetOptions',
+    'toHostOptions', 'toLHSOptions', 'dispatch', 'nudge'
+]);
+/**
+ * Extract shorthand keys (implicit toHost) from a vector config.
+ * Any key not in RESERVED_KEYS that starts with '?.' or contains an operator is shorthand.
+ */
+function extractShorthand(config) {
+    const shorthand = {};
+    let hasAny = false;
+    for (const key of Object.keys(config)) {
+        if (!RESERVED_KEYS.has(key)) {
+            shorthand[key] = config[key];
+            hasAny = true;
+        }
+    }
+    return hasAny ? shorthand : null;
+}
+/**
+ * Process a single AssignDispatchVector — execute all toTarget/toHost/toLHS assignments.
+ */
+function processVector(vector, source, target, host, lhs, inheritedOptions, useAssignFrom) {
+    const destinations = [
+        { key: 'toTarget', dest: target },
+        { key: 'toHost', dest: host },
+        { key: 'toLHS', dest: lhs },
+    ];
+    for (const { key, dest } of destinations) {
+        const pattern = vector[key];
+        if (!pattern || Object.keys(pattern).length === 0)
+            continue;
+        if (useAssignFrom && source != null) {
+            // Dynamic import assignFrom on demand (fire-and-forget context, already async)
+            import('../assignFrom.js').then(({ assignFrom }) => {
+                assignFrom(dest, pattern, { from: source, ...inheritedOptions, ...vector.withOptions });
+            });
+        }
+        else {
+            assignGingerly(dest, pattern, inheritedOptions);
+        }
+    }
+    // Handle shorthand (implicit toHost)
+    const shorthand = extractShorthand(vector);
+    if (shorthand) {
+        if (useAssignFrom && source != null) {
+            import('../assignFrom.js').then(({ assignFrom }) => {
+                assignFrom(host, shorthand, { from: source, ...inheritedOptions, ...vector.withOptions });
+            });
+        }
+        else {
+            assignGingerly(host, shorthand, inheritedOptions);
+        }
+    }
+}
+/**
+ * Attach an event listener based on AddEventListenerConfig.
+ *
+ * @param lhs - The DOM element to attach the listener to
+ * @param config - The event handler configuration
+ * @param target - The assignFrom target (first arg)
+ * @param host - The options.from (source/view model)
+ * @param inheritedOptions - Parent assignFrom options (withMethods, aka, etc.)
+ */
+export function attachEventListener(lhs, config, target, host, inheritedOptions) {
+    const { on: eventName, get: getConfig, fromLHS, fromHost, fromTarget, fromEvent, dispatch } = config;
+    // Resolve get config values
+    const { abortController, key, nudge, options: listenerOptions, stopPropagation, preventDefault, dispatch: getDispatch } = getConfig ?? {};
+    // Handle dedup via key
+    let controller;
+    if (key) {
+        let elMap = keyMap.get(lhs);
+        if (!elMap) {
+            elMap = new Map();
+            keyMap.set(lhs, elMap);
+        }
+        // Abort previous listener with same key
+        const prev = elMap.get(key);
+        if (prev)
+            prev.abort();
+        // Create new controller for this key
+        controller = new AbortController();
+        elMap.set(key, controller);
+    }
+    else if (abortController instanceof AbortController) {
+        controller = abortController;
+    }
+    else {
+        controller = new AbortController();
+    }
+    // Attach the listener
+    lhs.addEventListener(eventName, (event) => {
+        if (stopPropagation)
+            event.stopPropagation();
+        if (preventDefault)
+            event.preventDefault();
+        // Static assignments (no from) — top-level toTarget/toHost/toLHS + shorthand
+        processVector(config, null, target, host, lhs, inheritedOptions, false);
+        // fromLHS assignments
+        if (fromLHS) {
+            processVector(fromLHS, lhs, target, host, lhs, inheritedOptions, true);
+        }
+        // fromHost assignments
+        if (fromHost) {
+            processVector(fromHost, host, target, host, lhs, inheritedOptions, true);
+        }
+        // fromTarget assignments
+        if (fromTarget) {
+            processVector(fromTarget, target, target, host, lhs, inheritedOptions, true);
+        }
+        // fromEvent assignments
+        if (fromEvent) {
+            processVector(fromEvent, event, target, host, lhs, inheritedOptions, true);
+        }
+        // Dispatch custom event if configured
+        const dispatchConfig = dispatch || getDispatch;
+        if (dispatchConfig && dispatchConfig.type) {
+            const EventCtr = (typeof dispatchConfig.eventCtr === 'function'
+                ? dispatchConfig.eventCtr
+                : CustomEvent);
+            const evt = new EventCtr(dispatchConfig.type, {
+                detail: dispatchConfig.detail,
+                bubbles: dispatchConfig.bubbles ?? true,
+                cancelable: dispatchConfig.cancelable ?? false,
+                composed: dispatchConfig.composed ?? true,
+            });
+            lhs.dispatchEvent(evt);
+        }
+    }, { signal: controller.signal, ...listenerOptions });
+    // Nudge: remove disabled, add interaction hints
+    if (nudge) {
+        import('./nudge.js').then(({ nudge: nudgeFn }) => {
+            nudgeFn(lhs);
+        });
+    }
+}

package/handlers/addEventListener.ts

@@ -0,0 +1,178 @@
+/**
+ * handlers/addEventListener.ts — Event binding handler for += operator.
+ * 
+ * Dynamically imported when assignGingerly/assignFrom detects an += with
+ * an object RHS containing an `on` property on a DOM Element LHS.
+ * 
+ * Attaches an event listener that executes assign vectors on event fire.
+ */
+
+import assignGingerly from '../assignGingerly.js';
+import type { AddEventListenerConfig, AssignDispatchVector } from '../types/assign-gingerly/types.js';
+
+/**
+ * WeakMap for dedup: Element → Map<key, AbortController>
+ */
+const keyMap = new WeakMap<Element, Map<string, AbortController>>();
+
+/**
+ * Reserved keys that are not shorthand assign patterns.
+ */
+const RESERVED_KEYS = new Set([
+    'on', 'get', 'fromLHS', 'fromHost', 'fromEvent', 'fromTarget',
+    'toTarget', 'toHost', 'toLHS', 'withOptions', 'toTargetOptions',
+    'toHostOptions', 'toLHSOptions', 'dispatch', 'nudge'
+]);
+
+/**
+ * Extract shorthand keys (implicit toHost) from a vector config.
+ * Any key not in RESERVED_KEYS that starts with '?.' or contains an operator is shorthand.
+ */
+function extractShorthand(config: Record<string, any>): Record<string, any> | null {
+    const shorthand: Record<string, any> = {};
+    let hasAny = false;
+    for (const key of Object.keys(config)) {
+        if (!RESERVED_KEYS.has(key)) {
+            shorthand[key] = config[key];
+            hasAny = true;
+        }
+    }
+    return hasAny ? shorthand : null;
+}
+
+/**
+ * Process a single AssignDispatchVector — execute all toTarget/toHost/toLHS assignments.
+ */
+function processVector(
+    vector: AssignDispatchVector,
+    source: any,
+    target: any,
+    host: any,
+    lhs: Element,
+    inheritedOptions: any,
+    useAssignFrom: boolean
+): void {
+    const destinations = [
+        { key: 'toTarget' as const, dest: target },
+        { key: 'toHost' as const, dest: host },
+        { key: 'toLHS' as const, dest: lhs },
+    ];
+
+    for (const { key, dest } of destinations) {
+        const pattern = vector[key];
+        if (!pattern || Object.keys(pattern).length === 0) continue;
+        if (useAssignFrom && source != null) {
+            // Dynamic import assignFrom on demand (fire-and-forget context, already async)
+            import('../assignFrom.js').then(({ assignFrom }) => {
+                assignFrom(dest, pattern, { from: source, ...inheritedOptions, ...vector.withOptions });
+            });
+        } else {
+            assignGingerly(dest, pattern, inheritedOptions);
+        }
+    }
+
+    // Handle shorthand (implicit toHost)
+    const shorthand = extractShorthand(vector as Record<string, any>);
+    if (shorthand) {
+        if (useAssignFrom && source != null) {
+            import('../assignFrom.js').then(({ assignFrom }) => {
+                assignFrom(host, shorthand, { from: source, ...inheritedOptions, ...vector.withOptions });
+            });
+        } else {
+            assignGingerly(host, shorthand, inheritedOptions);
+        }
+    }
+}
+
+/**
+ * Attach an event listener based on AddEventListenerConfig.
+ * 
+ * @param lhs - The DOM element to attach the listener to
+ * @param config - The event handler configuration
+ * @param target - The assignFrom target (first arg)
+ * @param host - The options.from (source/view model)
+ * @param inheritedOptions - Parent assignFrom options (withMethods, aka, etc.)
+ */
+export function attachEventListener(
+    lhs: Element,
+    config: AddEventListenerConfig,
+    target: any,
+    host: any,
+    inheritedOptions: any
+): void {
+    const { on: eventName, get: getConfig, fromLHS, fromHost, fromTarget, fromEvent, dispatch } = config;
+
+    // Resolve get config values
+    const { abortController, key, nudge, options: listenerOptions, stopPropagation, preventDefault, dispatch: getDispatch } = getConfig ?? {} as any;
+
+    // Handle dedup via key
+    let controller: AbortController;
+    if (key) {
+        let elMap = keyMap.get(lhs);
+        if (!elMap) {
+            elMap = new Map();
+            keyMap.set(lhs, elMap);
+        }
+        // Abort previous listener with same key
+        const prev = elMap.get(key);
+        if (prev) prev.abort();
+        // Create new controller for this key
+        controller = new AbortController();
+        elMap.set(key, controller);
+    } else if (abortController instanceof AbortController) {
+        controller = abortController;
+    } else {
+        controller = new AbortController();
+    }
+
+    // Attach the listener
+    lhs.addEventListener(eventName, (event: Event) => {
+        if (stopPropagation) event.stopPropagation();
+        if (preventDefault) event.preventDefault();
+
+        // Static assignments (no from) — top-level toTarget/toHost/toLHS + shorthand
+        processVector(config, null, target, host, lhs, inheritedOptions, false);
+
+        // fromLHS assignments
+        if (fromLHS) {
+            processVector(fromLHS, lhs, target, host, lhs, inheritedOptions, true);
+        }
+
+        // fromHost assignments
+        if (fromHost) {
+            processVector(fromHost, host, target, host, lhs, inheritedOptions, true);
+        }
+
+        // fromTarget assignments
+        if (fromTarget) {
+            processVector(fromTarget, target, target, host, lhs, inheritedOptions, true);
+        }
+
+        // fromEvent assignments
+        if (fromEvent) {
+            processVector(fromEvent, event, target, host, lhs, inheritedOptions, true);
+        }
+
+        // Dispatch custom event if configured
+        const dispatchConfig = dispatch || getDispatch;
+        if (dispatchConfig && dispatchConfig.type) {
+            const EventCtr = (typeof dispatchConfig.eventCtr === 'function' 
+                ? dispatchConfig.eventCtr 
+                : CustomEvent) as typeof CustomEvent;
+            const evt = new EventCtr(dispatchConfig.type, {
+                detail: dispatchConfig.detail,
+                bubbles: dispatchConfig.bubbles ?? true,
+                cancelable: dispatchConfig.cancelable ?? false,
+                composed: dispatchConfig.composed ?? true,
+            });
+            lhs.dispatchEvent(evt);
+        }
+    }, { signal: controller.signal, ...listenerOptions });
+
+    // Nudge: remove disabled, add interaction hints
+    if (nudge) {
+        import('./nudge.js').then(({ nudge: nudgeFn }) => {
+            nudgeFn(lhs);
+        });
+    }
+}

package/handlers/arr.js

@@ -0,0 +1,13 @@
+/**
+ * Utility function to normalize a value to an array.
+ * - If undefined, returns empty array
+ * - If already an array, returns as-is
+ * - Otherwise, wraps the value in an array
+ *
+ * @param inp - Value to normalize to array
+ * @returns Array containing the value(s)
+ */
+export function arr(inp) {
+    return inp === undefined ? []
+        : Array.isArray(inp) ? inp : [inp];
+}

package/handlers/arr.ts

@@ -0,0 +1,13 @@
+/**
+ * Utility function to normalize a value to an array.
+ * - If undefined, returns empty array
+ * - If already an array, returns as-is
+ * - Otherwise, wraps the value in an array
+ * 
+ * @param inp - Value to normalize to array
+ * @returns Array containing the value(s)
+ */
+export function arr<T = any>(inp: T | T[] | undefined): T[] {
+    return inp === undefined ? []
+        : Array.isArray(inp) ? inp : [inp];
+}

package/handlers/lazyLoad.js

@@ -217,10 +217,10 @@ export class LazyLoadHandler {
             const len = Math.min(elements.length, assign.configs.length);
             for (let j = 0; j < len; j++) {
                 const cfg = assign.configs[j];
-                assignFrom(elements[j], cfg.assignToFragment ?? {}, { from, ...cfg.withOptions });
+                assignFrom(elements[j], cfg.toClone ?? {}, { from, ...cfg.withOptions });
             }
-        } else if (assign.assignToFragment) {
-            assignFrom(elements[0], assign.assignToFragment, { from, ...assign.withOptions });
+        } else if (assign.toClone) {
+            assignFrom(elements[0], assign.toClone, { from, ...assign.withOptions });
         }
     }
     async onCloneInserted(nodes, lhsTarget, resolvedParams) {