assign-gingerly 0.0.59 → 0.0.60

package/assignFromAsync.ts

@@ -51,6 +51,17 @@ export interface AssignFromOptions extends IAssignGingerlyOptions {
    */
   withIds?: Record<string, string | { qry: string }>;
 
+  /**
+   * Positional element references for use with `#[varName]` syntax.
+   * Resolves elements by child index path — no IDs assigned, no caching.
+   * 
+   * - Array value: child index path (e.g., [0, 1] = target.children[0].children[1])
+   * - Object value: { path: [...], expect?: 'selector', fallback?: true }
+   *   expect: validates via element.matches(), logs correction if wrong
+   *   fallback: on mismatch, recovers via querySelector(expect)
+   */
+  at?: Record<string, number[] | { path: number[]; expect?: string; fallback?: boolean }>;
+
   /**
    * Handler implementations scoped to this call.
    * Key: the `do` name referenced in handler configs.
@@ -79,13 +90,16 @@ export interface AssignFromOptions extends IAssignGingerlyOptions {
    * matched element (textContent, value, checked, dateTime, ish, etc.).
    * 
    * @example
-   * inferredAssignments: {
+   * infer: {
    *     byItemprop: ['user', 'name', 'email'],  // or true for all source keys
    *     beVigilant: true,  // watch for new matching elements (requires signal)
    * }
    */
-  inferredAssignments?: {
+  infer?: {
     byItemprop?: string[] | true;
+    '|'?: string[] | true;
+    byName?: string[] | true | { props: string[] | true; outside: string };
+    '@'?: string[] | true | { props: string[] | true; outside: string };
     /** Watch for new matching elements via MutationObserver. Requires options.signal for cleanup. */
     beVigilant?: boolean;
   };
@@ -150,13 +164,14 @@ export async function assignFromAsync(
   }
 
   // Process #[x] normal keys — resolve element, then apply remaining path + value
-  if (idRefNormalKeys.length > 0 && options.withIds) {
+  if (idRefNormalKeys.length > 0 && (options.withIds || options.at)) {
+    const ids = { ...options.withIds, ...options.at };
     const { resolveIdVariable, parseIdRef } = await import('./resolveIdRef.js');
     for (const key of idRefNormalKeys) {
       const parsed = parseIdRef(key);
       if (!parsed) continue;
 
-      const el = resolveIdVariable(parsed.varName, target, options.withIds);
+      const el = resolveIdVariable(parsed.varName, target, ids);
       if (!el) continue;
 
       const value = expandedPattern[key];
@@ -190,7 +205,8 @@ export async function assignFromAsync(
     await _processHandlerCommands(target, handlerKeys, expandedPattern, options, permissions);
   }
   // Process #[x] handler keys — resolve element, then pass to handler processing
-  if (idRefHandlerKeys.length > 0 && options.withIds) {
+  if (idRefHandlerKeys.length > 0 && (options.withIds || options.at)) {
+    const ids = { ...options.withIds, ...options.at };
     const { resolveIdVariable, parseIdRef } = await import('./resolveIdRef.js');
     _processHandlerCommands ??= (await import('./processHandlerCommands.js')).processHandlerCommands;
 
@@ -198,7 +214,7 @@ export async function assignFromAsync(
       const parsed = parseIdRef(key);
       if (!parsed) continue;
 
-      const el = resolveIdVariable(parsed.varName, target, options.withIds);
+      const el = resolveIdVariable(parsed.varName, target, ids);
       if (!el) continue;
 
       // Build a synthetic key for processHandlerCommands:
@@ -216,17 +232,17 @@ export async function assignFromAsync(
   }
 
   // Process inferred assignments — dynamically imported only when option is present
-  if (options.inferredAssignments) {
+  if (options.infer) {
     const { processInferredAssignments } = await import('./inferredAssignments.js');
-    await processInferredAssignments(target, options.from, options.inferredAssignments);
+    await processInferredAssignments(target, options.from, options.infer);
 
     // Set up MutationObserver for new matching elements if beVigilant
-    if (options.inferredAssignments.beVigilant) {
+    if (options.infer.beVigilant) {
       if (!options.signal) {
-        throw new Error('assignFrom: inferredAssignments.beVigilant requires options.signal (AbortSignal) for cleanup');
+        throw new Error('assignFrom: infer.beVigilant requires options.signal (AbortSignal) for cleanup');
       }
       const { setupVigilantObserver } = await import('./beVigilant.js');
-      setupVigilantObserver(target, options.from, options.inferredAssignments, options.signal);
+      setupVigilantObserver(target, options.from, options.infer, options.signal);
     }
   }
 

package/assignGingerly.js

@@ -226,6 +226,21 @@ function parseDeleteCommand(key) {
     }
     return key.substring(0, key.length - 3); // Remove ' -=' suffix
 }
+/**
+ * Helper function to check if a key represents a Y= merge command
+ */
+function isMergeCommand(key) {
+    return key.endsWith(' Y=');
+}
+/**
+ * Helper function to parse a Y= merge command and extract the path
+ */
+function parseMergeCommand(key) {
+    if (!isMergeCommand(key)) {
+        return null;
+    }
+    return key.substring(0, key.length - 3); // Remove ' Y=' suffix
+}
 /**
  * Helper function to parse a path string with ?. notation
  * Always splits on '?.' delimiter, preserving dots that are part of values
@@ -769,6 +784,41 @@ export function assignGingerly(target, source, options, permissions) {
             }
             continue;
         }
+        // Handle Y= merge commands (recursive assignGingerly into sub-object)
+        if (isMergeCommand(key)) {
+            const path = parseMergeCommand(key);
+            if (path) {
+                // Navigate to the target sub-object
+                let mergeTarget;
+                if (isNestedPath(path)) {
+                    if (withMethodsSet) {
+                        const result = evaluatePathWithMethods(target, parsePath(path), value, withMethodsSet);
+                        mergeTarget = result.target[result.lastKey];
+                    }
+                    else {
+                        const pathParts = parsePath(path);
+                        mergeTarget = target;
+                        for (const part of pathParts) {
+                            if (mergeTarget && typeof mergeTarget === 'object' && part in mergeTarget) {
+                                mergeTarget = mergeTarget[part];
+                            }
+                            else {
+                                mergeTarget = undefined;
+                                break;
+                            }
+                        }
+                    }
+                }
+                else {
+                    mergeTarget = target[path];
+                }
+                // Recursively merge if target is a valid object
+                if (mergeTarget && typeof mergeTarget === 'object') {
+                    assignGingerly(mergeTarget, value, options, permissions);
+                }
+            }
+            continue;
+        }
         if (isNestedPath(key)) {
             const pathParts = parsePath(key);
             // Check if path contains @each or @eachTime (forEach)

package/assignGingerly.ts

@@ -388,6 +388,23 @@ function parseDeleteCommand(key: string): string | null {
   return key.substring(0, key.length - 3); // Remove ' -=' suffix
 }
 
+/**
+ * Helper function to check if a key represents a Y= merge command
+ */
+function isMergeCommand(key: string): boolean {
+  return key.endsWith(' Y=');
+}
+
+/**
+ * Helper function to parse a Y= merge command and extract the path
+ */
+function parseMergeCommand(key: string): string | null {
+  if (!isMergeCommand(key)) {
+    return null;
+  }
+  return key.substring(0, key.length - 3); // Remove ' Y=' suffix
+}
+
 /**
  * Helper function to parse a path string with ?. notation
  * Always splits on '?.' delimiter, preserving dots that are part of values
@@ -968,6 +985,40 @@ export function assignGingerly(
       continue;
     }
 
+    // Handle Y= merge commands (recursive assignGingerly into sub-object)
+    if (isMergeCommand(key)) {
+      const path = parseMergeCommand(key);
+      if (path) {
+        // Navigate to the target sub-object
+        let mergeTarget: any;
+        if (isNestedPath(path)) {
+          if (withMethodsSet) {
+            const result = evaluatePathWithMethods(target, parsePath(path), value, withMethodsSet);
+            mergeTarget = result.target[result.lastKey];
+          } else {
+            const pathParts = parsePath(path);
+            mergeTarget = target;
+            for (const part of pathParts) {
+              if (mergeTarget && typeof mergeTarget === 'object' && part in mergeTarget) {
+                mergeTarget = mergeTarget[part];
+              } else {
+                mergeTarget = undefined;
+                break;
+              }
+            }
+          }
+        } else {
+          mergeTarget = target[path];
+        }
+        
+        // Recursively merge if target is a valid object
+        if (mergeTarget && typeof mergeTarget === 'object') {
+          assignGingerly(mergeTarget, value, options, permissions);
+        }
+      }
+      continue;
+    }
+
     if (isNestedPath(key)) {
       const pathParts = parsePath(key);
       

package/builtInEmoji.js

@@ -0,0 +1,25 @@
+/**
+ * builtInEmoji.js — Predefined emoji aliases for built-in handlers.
+ * 
+ * Import and spread into the `handlers` option for concise handler configs:
+ * 
+ * @example
+ * import { builtInEmoji } from 'assign-gingerly/builtInEmoji.js';
+ * 
+ * assignFrom(target, {
+ *     '?.el =>': { do: '🔗', get: { value: ['?.first', ' ', '?.last'] } }
+ * }, { from: vm, handlers: builtInEmoji });
+ */
+
+/**
+ * Emoji → built-in handler name mapping.
+ */
+export const builtInEmoji = {
+    '📦': 'builtIns.lazyLoad',
+    '🎚️': 'builtIns.lazyLoadSwitch',
+    '🔗': 'builtIns.join',
+    '🏷️': 'builtIns.microDataJoin',
+    '📋': 'builtIns.manageTemplateList',
+};
+
+export default builtInEmoji;

package/builtInEmoji.ts

@@ -0,0 +1,33 @@
+/**
+ * builtInEmoji.ts — Predefined emoji aliases for built-in handlers.
+ * 
+ * Import and spread into the `handlers` option for concise handler configs:
+ * 
+ * @example
+ * import { builtInEmoji } from 'assign-gingerly/builtInEmoji.js';
+ * 
+ * assignFrom(target, {
+ *     '?.el =>': { do: '🔗', get: { value: ['?.first', ' ', '?.last'] } }
+ * }, { from: vm, handlers: builtInEmoji });
+ */
+
+/**
+ * Emoji → built-in handler name mapping.
+ * 
+ * | Emoji | Handler |
+ * |-------|---------|
+ * | 📦 | builtIns.lazyLoad |
+ * | 🎚️ | builtIns.lazyLoadSwitch |
+ * | 🔗 | builtIns.join |
+ * | 🏷️ | builtIns.microDataJoin |
+ * | 📋 | builtIns.manageTemplateList |
+ */
+export const builtInEmoji: Record<string, string> = {
+    '📦': 'builtIns.lazyLoad',
+    '🎚️': 'builtIns.lazyLoadSwitch',
+    '🔗': 'builtIns.join',
+    '🏷️': 'builtIns.microDataJoin',
+    '📋': 'builtIns.manageTemplateList',
+};
+
+export default builtInEmoji;

package/handlers/lazyLoad.js

@@ -37,14 +37,17 @@ function getMarkerName(templateEl) {
  *
  * Exported so it can be subclassed for custom behavior.
  */
+import { assignFrom } from '../assignFrom.js';
 export class LazyLoadHandler {
     config;
+    _options;
     static #markerCounter = 0;
     constructor(config) {
         this.config = config;
     }
-    async assign(lhsTarget, resolvedParams) {
-        const { if: condition, instantiate, method = 'appendChild', forget = false, transitional = false, hideClass = DEFAULT_HIDE_CLASS, hideCss, markerName, toggleInert = false, toggleDisabled = false } = resolvedParams;
+    async assign(lhsTarget, resolvedParams, options) {
+        this._options = options;
+        const { if: condition, instantiate, method = 'appendChild', forget = false, transitional = false, hideClass = DEFAULT_HIDE_CLASS, hideCss, markerName, toggleInert = false, toggleDisabled = false, placeholder } = resolvedParams;
         if (!(lhsTarget instanceof Element)) {
             throw new Error('builtIns.lazyLoad: lhsTarget must be a DOM Element');
         }
@@ -83,6 +86,16 @@ export class LazyLoadHandler {
                 }
             }
             else {
+                // Remove placeholder content if specified
+                if (placeholder) {
+                    const [phStart, phEnd] = findMarkers(lhsTarget, placeholder);
+                    if (phStart && phEnd) {
+                        const phNodes = getNodesBetweenMarkers(phStart, phEnd);
+                        for (const node of phNodes) {
+                            node.parentNode?.removeChild(node);
+                        }
+                    }
+                }
                 if (method === 'after') {
                     [startMarker, endMarker] = createMarkersSibling(lhsTarget, name);
                 } else {
@@ -164,6 +177,7 @@ export class LazyLoadHandler {
             throw new Error(`builtIns.lazyLoad: instantiate must resolve to an HTMLTemplateElement or DocumentFragment`);
         }
         const nodes = Array.from(content.childNodes);
+        this.applyAssign(nodes, resolvedParams);
         endMarker.parentNode.insertBefore(content, endMarker);
         return nodes;
     }
@@ -179,6 +193,7 @@ export class LazyLoadHandler {
             throw new Error(`builtIns.lazyLoad: instantiate must resolve to an HTMLTemplateElement or DocumentFragment`);
         }
         const nodes = Array.from(content.childNodes);
+        this.applyAssign(nodes, resolvedParams);
         endMarker.parentNode.insertBefore(content, endMarker);
         await this.onCloneInserted(nodes, lhsTarget, resolvedParams);
         if (resolvedParams.onInstantiated && typeof resolvedParams.onInstantiated === 'function') {
@@ -192,6 +207,22 @@ export class LazyLoadHandler {
         }
         return nodes;
     }
+    applyAssign(nodes, resolvedParams) {
+        const assign = resolvedParams.assign;
+        if (!assign) return;
+        const elements = nodes.filter(n => n instanceof Element);
+        if (elements.length === 0) return;
+        const from = this._options?.from ?? {};
+        if (assign.configs && Array.isArray(assign.configs)) {
+            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 });
+            }
+        } else if (assign.assignToFragment) {
+            assignFrom(elements[0], assign.assignToFragment, { from, ...assign.withOptions });
+        }
+    }
     async onCloneInserted(nodes, lhsTarget, resolvedParams) {
         // No-op by default. Subclasses override.
     }

package/handlers/lazyLoad.ts

@@ -23,6 +23,7 @@ import type { AssignFromHandler } from '../assignFromAsync.js';
 import type { LazyLoadResolvedParams, LazyLoadInstantiatedContext } from '../types/assign-gingerly/types.js';
 import { withTransition, ensureHideStyle, DEFAULT_HIDE_CLASS } from '../transitionHelper.js';
 import { findMarkers, createMarkers, getNodesBetweenMarkers, findMarkersSibling, createMarkersSibling, MARKER_START_PREFIX, MARKER_END } from '../markerUtils.js';
+import { assignFrom } from '../assignFrom.js';
 
 export type { LazyLoadResolvedParams, LazyLoadInstantiatedContext };
 
@@ -46,13 +47,15 @@ function getMarkerName(templateEl: any): string {
  */
 export class LazyLoadHandler implements AssignFromHandler {
     config: any;
+    _options: any;
     static #markerCounter = 0;
 
     constructor(config: any) {
         this.config = config;
     }
 
-    async assign(lhsTarget: any, resolvedParams: LazyLoadResolvedParams): Promise<void> {
+    async assign(lhsTarget: any, resolvedParams: LazyLoadResolvedParams, options?: any): Promise<void> {
+        this._options = options; // Store for applyAssign access
         const {
             if: condition,
             instantiate,
@@ -64,6 +67,7 @@ export class LazyLoadHandler implements AssignFromHandler {
             markerName,
             toggleInert = false,
             toggleDisabled = false,
+            placeholder,
         } = resolvedParams;
 
         if (!(lhsTarget instanceof Element)) {
@@ -112,6 +116,16 @@ export class LazyLoadHandler implements AssignFromHandler {
                 }
             } else {
                 // No markers — first time. Create markers and clone template.
+                // Remove placeholder content if specified
+                if (placeholder) {
+                    const [phStart, phEnd] = findMarkers(lhsTarget, placeholder);
+                    if (phStart && phEnd) {
+                        const phNodes = getNodesBetweenMarkers(phStart, phEnd);
+                        for (const node of phNodes) {
+                            node.parentNode?.removeChild(node);
+                        }
+                    }
+                }
                 if (method === 'after') {
                     [startMarker, endMarker] = createMarkersSibling(lhsTarget, name);
                 } else {
@@ -229,6 +243,10 @@ export class LazyLoadHandler implements AssignFromHandler {
         }
 
         const nodes = Array.from(content.childNodes);
+
+        // Apply assignments to cloned content before insertion
+        this.applyAssign(nodes, resolvedParams);
+
         endMarker.parentNode!.insertBefore(content, endMarker);
         return nodes;
     }
@@ -259,6 +277,9 @@ export class LazyLoadHandler implements AssignFromHandler {
         // Capture nodes before insertion (childNodes empties after insertBefore)
         const nodes = Array.from(content.childNodes);
 
+        // Apply assignments to cloned content before insertion
+        this.applyAssign(nodes, resolvedParams);
+
         // Insert before endMarker
         endMarker.parentNode!.insertBefore(content, endMarker);
 
@@ -279,6 +300,30 @@ export class LazyLoadHandler implements AssignFromHandler {
         return nodes;
     }
 
+    /**
+     * Apply assignFrom to cloned nodes based on the `assign` config.
+     * Supports single-element and multi-element (configs array) templates.
+     */
+    protected applyAssign(nodes: Node[], resolvedParams: LazyLoadResolvedParams): void {
+        const assign = (resolvedParams as any).assign;
+        if (!assign) return;
+
+        const elements = nodes.filter(n => n instanceof Element) as Element[];
+        if (elements.length === 0) return;
+
+        const from = this._options?.from ?? {};
+
+        if (assign.configs && Array.isArray(assign.configs)) {
+            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 });
+            }
+        } else if (assign.assignToFragment) {
+            assignFrom(elements[0], assign.assignToFragment, { from, ...assign.withOptions });
+        }
+    }
+
     /**
      * Hook called after template content is cloned and inserted.
      * Override in subclasses for custom post-clone logic.

package/handlers/manageTemplateList.js

@@ -18,7 +18,7 @@
  *         },
  *         fromEachItem: {
  *             assignToFragment: { '?.querySelector?.tr?.ish': '?.' },
- *             withOptions: { withMethods: ['querySelector'], inferredAssignments: true },
+ *             withOptions: { withMethods: ['querySelector'], infer: true },
  *             resolve: { key: '?.rank' }
  *         }
  *     }
@@ -47,6 +47,7 @@ export class ManageTemplateListHandler {
             return; // Nothing to iterate
         }
         const fromEachItem = this.config.fromEachItem;
+        const configs = fromEachItem?.configs; // Array form for multi-element templates
         const assignToFragment = fromEachItem?.assignToFragment ?? {};
         const withOptions = fromEachItem?.withOptions ?? {};
         const perItemResolve = fromEachItem?.resolve ?? {};
@@ -55,10 +56,10 @@ export class ManageTemplateListHandler {
         const fromSource = this.config.fromSource;
         const sourceAssignToFragment = fromSource?.assignToFragment;
         const sourceWithOptions = fromSource?.withOptions ?? {};
-        // Detect fast path: no assignToFragment patterns, just inferredAssignments
-        const hasAssignPatterns = Object.keys(assignToFragment).length > 0;
-        const inferredConfig = withOptions.inferredAssignments;
-        const useFastPath = !hasAssignPatterns && inferredConfig && !sourceAssignToFragment;
+        // Detect fast path: no assignToFragment patterns, just infer (only for non-configs mode)
+        const hasAssignPatterns = !configs && Object.keys(assignToFragment).length > 0;
+        const inferredConfig = !configs && withOptions.infer;
+        const useFastPath = !configs && !hasAssignPatterns && inferredConfig && !sourceAssignToFragment;
         const name = markerName ?? getMarkerName(instantiate) ?? 'templateList';
         // Find or create markers
         let [startMarker, endMarker] = findMarkers(lhsTarget, name);
@@ -112,19 +113,30 @@ export class ManageTemplateListHandler {
             if (state.keyToNodes.has(key) && oldKeys.has(key)) {
                 // Existing item — update in place
                 const existingNodes = state.keyToNodes.get(key);
-                const rootEl = existingNodes.find(n => n instanceof Element);
-                if (rootEl) {
-                    const shouldYield = yieldEvery && i > 0 && i % yieldEvery === 0;
-                    if (shouldYield)
-                        await new Promise(r => setTimeout(r, 0));
-                    if (processInferred) {
-                        processInferred(rootEl, item, inferredConfig === true ? { byItemprop: true } : inferredConfig);
+                const shouldYield = yieldEvery && i > 0 && i % yieldEvery === 0;
+                if (shouldYield)
+                    await new Promise(r => setTimeout(r, 0));
+                if (configs) {
+                    // Multi-element: zip configs with element nodes
+                    const elements = existingNodes.filter(n => n instanceof Element);
+                    const len = Math.min(elements.length, configs.length);
+                    for (let j = 0; j < len; j++) {
+                        const cfg = configs[j];
+                        assignFrom(elements[j], cfg.assignToFragment ?? {}, { from: item, ...cfg.withOptions });
                     }
-                    else {
-                        assignFrom(rootEl, assignToFragment, { from: item, ...withOptions });
-                    }
-                    if (sourceAssignToFragment && options?.from) {
-                        assignFrom(rootEl, sourceAssignToFragment, { from: options.from, ...sourceWithOptions });
+                }
+                else {
+                    const rootEl = existingNodes.find(n => n instanceof Element);
+                    if (rootEl) {
+                        if (processInferred) {
+                            processInferred(rootEl, item, inferredConfig === true ? { byItemprop: true } : inferredConfig);
+                        }
+                        else {
+                            assignFrom(rootEl, assignToFragment, { from: item, ...withOptions });
+                        }
+                        if (sourceAssignToFragment && options?.from) {
+                            assignFrom(rootEl, sourceAssignToFragment, { from: options.from, ...sourceWithOptions });
+                        }
                     }
                 }
                 newKeyToNodes.set(key, existingNodes);
@@ -147,21 +159,32 @@ export class ManageTemplateListHandler {
                 }
                 const clonedNodes = Array.from(content.childNodes);
                 // Apply per-item assignments to the cloned fragment
-                const rootEl = clonedNodes.find(n => n instanceof Element);
-                if (rootEl) {
-                    const tempContainer = document.createDocumentFragment();
-                    tempContainer.appendChild(content);
-                    const shouldYield = yieldEvery && i > 0 && i % yieldEvery === 0;
-                    if (shouldYield)
-                        await new Promise(r => setTimeout(r, 0));
-                    if (processInferred) {
-                        processInferred(rootEl, item, inferredConfig === true ? { byItemprop: true } : inferredConfig);
+                const shouldYield = yieldEvery && i > 0 && i % yieldEvery === 0;
+                if (shouldYield)
+                    await new Promise(r => setTimeout(r, 0));
+                if (configs) {
+                    // Multi-element: zip configs with element nodes
+                    const elements = clonedNodes.filter(n => n instanceof Element);
+                    const len = Math.min(elements.length, configs.length);
+                    for (let j = 0; j < len; j++) {
+                        const cfg = configs[j];
+                        assignFrom(elements[j], cfg.assignToFragment ?? {}, { from: item, ...cfg.withOptions });
                     }
-                    else {
-                        assignFrom(rootEl, assignToFragment, { from: item, ...withOptions });
-                    }
-                    if (sourceAssignToFragment && options?.from) {
-                        assignFrom(rootEl, sourceAssignToFragment, { from: options.from, ...sourceWithOptions });
+                }
+                else {
+                    const rootEl = clonedNodes.find(n => n instanceof Element);
+                    if (rootEl) {
+                        const tempContainer = document.createDocumentFragment();
+                        tempContainer.appendChild(content);
+                        if (processInferred) {
+                            processInferred(rootEl, item, inferredConfig === true ? { byItemprop: true } : inferredConfig);
+                        }
+                        else {
+                            assignFrom(rootEl, assignToFragment, { from: item, ...withOptions });
+                        }
+                        if (sourceAssignToFragment && options?.from) {
+                            assignFrom(rootEl, sourceAssignToFragment, { from: options.from, ...sourceWithOptions });
+                        }
                     }
                 }
                 for (const node of clonedNodes) {