assign-gingerly 0.0.59 → 0.0.60

package/resolveIdRef.ts

@@ -11,7 +11,7 @@
 /**
  * Configuration for a withIds entry.
  */
-export type WithIdConfig = string | { qry: string };
+export type WithIdConfig = string | { qry: string } | number[] | { path: number[]; expect?: string; fallback?: boolean };
 
 /**
  * Module-level cache: rootNode → Map<varName, { id, WeakRef }>
@@ -26,14 +26,15 @@ const idCounterMap = new WeakMap<object, number>();
 
 /**
  * Generate a unique ID within a rootNode.
- * Format: _ag0, _ag1, _ag2, ...
+ * Format: -ag:0, -ag:1, -ag:2, ...
+ * Starts with '-' and contains ':' to avoid collision with JS identifiers/globalThis properties.
  */
 function generateUniqueId(rootNode: any): string {
     let counter = idCounterMap.get(rootNode) ?? 0;
     let id: string;
     // Ensure uniqueness (skip if ID already exists in the document)
     do {
-        id = `_ag${counter}`;
+        id = `-ag:${counter}`;
         counter++;
     } while (rootNode.getElementById?.(id));
     idCounterMap.set(rootNode, counter);
@@ -56,6 +57,57 @@ export function resolveIdVariable(
     const config = withIds[varName];
     if (config === undefined) return undefined;
 
+    // For 'at' option path-based configs (array or { path }), resolve directly from target — no ID, no caching
+    // These are target-relative and fast (~2-4ns), for when structure is guaranteed stable
+    if (Array.isArray(config)) {
+        let current: any = target;
+        for (const idx of config) {
+            if (!current || !current.children) break;
+            current = current.children[idx];
+        }
+        return current instanceof Element ? current : undefined;
+    }
+
+    if (typeof config === 'object' && 'path' in config && !('qry' in config)) {
+        // Determine if this is from 'at' (no ID assignment) or 'withIds' with path (assigns ID + caches)
+        // When called from 'at', we skip ID/caching. When from 'withIds', we assign ID and cache.
+        // Distinguish by presence in the options — caller passes the merged map.
+        // For now: { path } without 'noId' → assign ID + cache (withIds behavior)
+        const rootNode = target.getRootNode?.() ?? target;
+        let current: any = target;
+        for (const idx of config.path) {
+            if (!current || !current.children) break;
+            current = current.children[idx];
+        }
+        let el: Element | null = current instanceof Element ? current : null;
+
+        // Validation: check if resolved element matches expected selector
+        if (config.expect) {
+            const didNotMatch = !el || !el.matches(config.expect);
+            if (didNotMatch) {
+                if (config.fallback) {
+                    el = target.querySelector?.(config.expect) ?? el;
+                }
+                // Fire-and-forget: log correction suggestion
+                const capturedConfig = config;
+                const capturedVarName = varName;
+                import('./withIdsCorrector.js').then(module => {
+                    module.logConfigCorrection(target, capturedVarName, capturedConfig);
+                }).catch(() => {});
+            }
+        }
+
+        if (!el) return undefined;
+
+        // Assign ID for stability against future DOM mutations
+        let id = el.id;
+        if (!id) {
+            id = generateUniqueId(rootNode);
+            el.id = id;
+        }
+        return el;
+    }
+
     const rootNode = target.getRootNode?.() ?? target;
 
     // Get or create cache for this rootNode
@@ -65,29 +117,27 @@ export function resolveIdVariable(
         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: Element | null = null;
 
     if (typeof config === 'string') {
         // String form: existing ID — use getElementById directly
+        // Check cache first (getElementById lookups are cacheable — global to rootNode)
+        const cached = cache.get(varName);
+        if (cached) {
+            const cachedEl = cached.ref.deref();
+            if (cachedEl) return cachedEl;
+
+            // 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;
+            }
+        }
         el = rootNode.getElementById?.(config) ?? null;
     } else {
-        // Object form: { qry } — run querySelector against target
+        // Object form: { qry } — run querySelector against target (target-relative, no cache)
         el = target.querySelector?.(config.qry) ?? null;
     }
 
@@ -100,8 +150,10 @@ export function resolveIdVariable(
         el.id = id;
     }
 
-    // Cache it
-    cache.set(varName, { id, ref: new WeakRef(el) });
+    // Cache only for string-form (getElementById) — not for qry form (target-relative)
+    if (typeof config === 'string') {
+        cache.set(varName, { id, ref: new WeakRef(el) });
+    }
     return el;
 }
 

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

@@ -616,6 +616,16 @@ export interface LazyLoadResolvedParams {
     toggleInert?: boolean;
     /** Set disabled property on hidden form elements */
     toggleDisabled?: boolean;
+    /** Name of a pre-existing marker pair whose content should be removed on first activation.
+     *  Used for SSR placeholder content (e.g., "Loading..." text) that disappears once real content loads. */
+    placeholder?: string;
+    /** Assignment config applied to cloned content before insertion.
+     *  Same shape as manageTemplateList's fromEachItem: { assignToFragment, withOptions } or { configs: [...] } */
+    assign?: {
+        assignToFragment?: Record<string, any>;
+        withOptions?: Record<string, any>;
+        configs?: Array<{ assignToFragment?: Record<string, any>; withOptions?: Record<string, any> }>;
+    };
 }
 
 /**

package/withIdsCorrector.js

@@ -0,0 +1,47 @@
+/**
+ * withIdsCorrector.ts — Dev-time diagnostic for stale withIds coordinates.
+ *
+ * Dynamically imported only on mismatch — zero cost in production or when coordinates are correct.
+ * Computes and logs the correct child index path for a given selector.
+ */
+/**
+ * Compute the child index path from a root element to a target element.
+ * Returns the array of children indices, or null if not found.
+ */
+function computeChildPath(root, target) {
+    const path = [];
+    let current = target;
+    while (current && current !== root) {
+        const parent = current.parentElement;
+        if (!parent)
+            return null;
+        const idx = Array.prototype.indexOf.call(parent.children, current);
+        if (idx === -1)
+            return null;
+        path.unshift(idx);
+        current = parent;
+    }
+    return current === root ? path : null;
+}
+/**
+ * Log a correction suggestion for a mismatched withIds config.
+ */
+export function logConfigCorrection(target, varName, config) {
+    if (!config.expect)
+        return;
+    const correctEl = target.querySelector?.(config.expect);
+    if (!correctEl) {
+        console.warn(`withIds["${varName}"]: path [${config.path}] did not match "${config.expect}" ` +
+            `and querySelector also found no match. Check that the selector is correct.`);
+        return;
+    }
+    const correctPath = computeChildPath(target, correctEl);
+    if (correctPath) {
+        console.warn(`withIds["${varName}"]: path [${config.path}] did not match "${config.expect}". ` +
+            `Suggested correction: [${correctPath.join(', ')}]`);
+    }
+    else {
+        console.warn(`withIds["${varName}"]: path [${config.path}] did not match "${config.expect}". ` +
+            `Could not compute a child index path (element may not be a descendant of target).`);
+    }
+}

package/withIdsCorrector.ts

@@ -0,0 +1,59 @@
+/**
+ * withIdsCorrector.ts — Dev-time diagnostic for stale withIds coordinates.
+ * 
+ * Dynamically imported only on mismatch — zero cost in production or when coordinates are correct.
+ * Computes and logs the correct child index path for a given selector.
+ */
+
+/**
+ * Compute the child index path from a root element to a target element.
+ * Returns the array of children indices, or null if not found.
+ */
+function computeChildPath(root: Element, target: Element): number[] | null {
+    const path: number[] = [];
+    let current: Element | null = target;
+
+    while (current && current !== root) {
+        const parent = current.parentElement;
+        if (!parent) return null;
+        const idx = Array.prototype.indexOf.call(parent.children, current);
+        if (idx === -1) return null;
+        path.unshift(idx);
+        current = parent;
+    }
+
+    return current === root ? path : null;
+}
+
+/**
+ * Log a correction suggestion for a mismatched withIds config.
+ */
+export function logConfigCorrection(
+    target: any,
+    varName: string,
+    config: { path: number[]; expect?: string; fallback?: boolean }
+): void {
+    if (!config.expect) return;
+
+    const correctEl = target.querySelector?.(config.expect);
+    if (!correctEl) {
+        console.warn(
+            `withIds["${varName}"]: path [${config.path}] did not match "${config.expect}" ` +
+            `and querySelector also found no match. Check that the selector is correct.`
+        );
+        return;
+    }
+
+    const correctPath = computeChildPath(target, correctEl);
+    if (correctPath) {
+        console.warn(
+            `withIds["${varName}"]: path [${config.path}] did not match "${config.expect}". ` +
+            `Suggested correction: [${correctPath.join(', ')}]`
+        );
+    } else {
+        console.warn(
+            `withIds["${varName}"]: path [${config.path}] did not match "${config.expect}". ` +
+            `Could not compute a child index path (element may not be a descendant of target).`
+        );
+    }
+}