assign-gingerly 0.0.57 → 0.0.59

package/resolveValues.ts

@@ -1,55 +1,42 @@
 /**
- * Options for resolveValues
+ * resolveValues.ts — Async value resolution for path strings.
+ * 
+ * Thin async wrapper around getValues that adds support for async protocol handlers.
+ * For synchronous-only use cases, import getValues/getValue directly for better performance.
+ * 
+ * Re-exports ResolveValuesOptions for backward compatibility.
  */
-export interface ResolveValuesOptions {
-  /**
-   * Method names that should be called instead of accessed as properties.
-   * When a path segment matches, it's called as a method with the next segment as argument.
-   */
-  withMethods?: string[] | Set<string>;
-  
-  /**
-   * Alias mappings for path segments.
-   * Substituted before path resolution, matching complete tokens between `?.` delimiters.
-   */
-  aka?: Record<string, string>;
 
-  /**
-   * Protocol handlers for resolving protocol-prefixed values (e.g., 'globalThis://key').
-   * Each handler receives the key portion and returns the resolved value (sync or async).
-   * 
-   * If a value contains '://' but the protocol isn't in this map, the value passes through unchanged.
-   * If a '?.' appears after the protocol key, the remaining path is resolved against the handler's result.
-   * 
-   * @example
-   * protocols: {
-   *     globalThis: (key) => globalThis[key],
-   *     localStorage: (key) => JSON.parse(localStorage.getItem(key) || 'null')
-   * }
-   */
-  protocols?: Record<string, (key: string) => any | Promise<any>>;
+import { getValue } from './getValues.js';
+import type { ResolveValuesOptions } from './types/assign-gingerly/types.js';
+
+export type { ResolveValuesOptions };
+
+// Re-export getValue as resolveValue for backward compatibility
+export { getValue as resolveValue };
+
+/**
+ * Checks if a string value looks like a protocol reference.
+ */
+function hasProtocol(value: string): boolean {
+    return value.includes('://');
 }
 
 /**
  * Apply alias substitutions to a path string.
- * Replaces complete tokens between `?.` delimiters with their aliased values.
  */
 function applyAliases(path: string, aliasMap: Map<string, string>): string {
-  if (aliasMap.size === 0) return path;
-  const parts = path.split('?.');
-  const substituted = parts.map(part => aliasMap.get(part) ?? part);
-  return substituted.join('?.');
+    if (aliasMap.size === 0) return path;
+    const parts = path.split('?.');
+    const substituted = parts.map(part => aliasMap.get(part) ?? part);
+    return substituted.join('?.');
 }
 
 /**
  * Path cache for parsed path strings.
- * Avoids re-splitting the same path on repeated calls.
  */
 const pathCache = new Map<string, string[]>();
 
-/**
- * Parse a `?.`-delimited path string into segments, with caching.
- */
 function parseCachedPath(path: string): string[] {
     let parts = pathCache.get(path);
     if (!parts) {
@@ -60,265 +47,154 @@ function parseCachedPath(path: string): string[] {
 }
 
 /**
- * Resolves a protocol-prefixed value (e.g., 'globalThis://key?.path').
- * 
- * 1. Extracts the protocol name (before '://')
- * 2. If the protocol isn't in the protocols map, returns the value unchanged (false positive)
- * 3. Extracts the key (between '://' and first '?.' or end of string)
- * 4. Calls the protocol handler with the key
- * 5. If there's a remaining '?.' path, resolves it against the handler's result
+ * Navigate a path against a source object, optionally calling methods.
+ */
+function navigatePath(
+    source: any,
+    parts: string[],
+    withMethods: Set<string> | undefined
+): any {
+    let current = source;
+    let i = 0;
+    while (i < parts.length) {
+        if (current == null) return current;
+        const part = parts[i];
+        if (withMethods && withMethods.has(part)) {
+            const method = current[part];
+            if (typeof method === 'function') {
+                const nextPart = parts[i + 1];
+                if (nextPart !== undefined && !(withMethods.has(nextPart))) {
+                    current = method.call(current, nextPart);
+                    i += 2;
+                } else {
+                    current = method.call(current);
+                    i++;
+                }
+            } else {
+                current = current[part];
+                i++;
+            }
+        } else {
+            current = current[part];
+            i++;
+        }
+    }
+    return current;
+}
+
+/**
+ * Resolves a protocol-prefixed value asynchronously.
  */
 async function resolveProtocolValue(
     value: string,
     protocols: Record<string, (key: string) => any | Promise<any>>,
     options?: ResolveValuesOptions
 ): Promise<any> {
-    // Extract protocol name (before ://)
     const protoEnd = value.indexOf('://');
     const protocol = value.substring(0, protoEnd);
 
-    // Resolve via protocol handler
     const handler = protocols[protocol];
-    if (!handler) return value; // false flag — coincidentally looks like a protocol
+    if (!handler) return value;
 
     const rest = value.substring(protoEnd + 3);
-
-    // Split at first ?. to separate key from path
     const pathStart = rest.indexOf('?.');
     const key = pathStart === -1 ? rest : rest.substring(0, pathStart);
     const path = pathStart === -1 ? null : rest.substring(pathStart);
 
     const resolved = await handler(key);
 
-    // If there's a remaining path, resolve it against the result
     if (path) {
-        return resolveValue(path, resolved, options);
+        return getValue(path, resolved, options);
     }
     return resolved;
 }
 
 /**
- * Checks if a string value looks like a protocol reference.
- */
-function hasProtocol(value: string): boolean {
-    return value.includes('://');
-}
-
-/**
- * Navigate a path against a source object, optionally calling methods.
- * Returns the resolved value at the end of the path.
- */
-function navigatePath(
-  source: any,
-  parts: string[],
-  withMethods: Set<string> | undefined
-): any {
-  let current = source;
-  let i = 0;
-  
-  while (i < parts.length) {
-    if (current == null) return current;
-    
-    const part = parts[i];
-    
-    if (withMethods && withMethods.has(part)) {
-      const method = current[part];
-      if (typeof method === 'function') {
-        const nextPart = parts[i + 1];
-        if (nextPart !== undefined && !(withMethods.has(nextPart))) {
-          // Call method with next segment as argument, consume it
-          current = method.call(current, nextPart);
-          i += 2;
-        } else {
-          // Consecutive methods or last segment — call with no args
-          current = method.call(current);
-          i++;
-        }
-      } else {
-        current = current[part];
-        i++;
-      }
-    } else {
-      current = current[part];
-      i++;
-    }
-  }
-  
-  return current;
-}
-
-/**
- * Resolve path strings and protocol references within an array.
- * Recurses into nested arrays and plain objects. Non-string elements,
- * class instances, and other non-plain objects pass through unchanged.
+ * Resolve path strings and protocol references within an array (async).
  */
 async function resolveArray(
-  arr: any[],
-  source: any,
-  aliasMap: Map<string, string>,
-  withMethods: Set<string> | undefined,
-  protocols: Record<string, (key: string) => any | Promise<any>> | undefined,
-  options?: ResolveValuesOptions
+    arr: any[],
+    source: any,
+    aliasMap: Map<string, string>,
+    withMethods: Set<string> | undefined,
+    protocols: Record<string, (key: string) => any | Promise<any>> | undefined,
+    options?: ResolveValuesOptions
 ): Promise<any[]> {
-  const result: any[] = [];
-  for (const item of arr) {
-    if (typeof item === 'string' && item.startsWith('?.')) {
-      const aliased = applyAliases(item, aliasMap);
-      const parts = parseCachedPath(aliased);
-      result.push(parts.length === 0 ? source : navigatePath(source, parts, withMethods));
-    } else if (typeof item === 'string' && protocols && hasProtocol(item)) {
-      result.push(await resolveProtocolValue(item, protocols, options));
-    } else if (Array.isArray(item)) {
-      result.push(await resolveArray(item, source, aliasMap, withMethods, protocols, options));
-    } else if (item && typeof item === 'object') {
-      const proto = Object.getPrototypeOf(item);
-      if (proto === Object.prototype || proto === null) {
-        result.push(await resolveValues(item, source, options));
-      } else {
-        result.push(item);
-      }
-    } else {
-      result.push(item);
+    const result: any[] = [];
+    for (const item of arr) {
+        if (typeof item === 'string' && item.startsWith('?.')) {
+            const aliased = applyAliases(item, aliasMap);
+            const parts = parseCachedPath(aliased);
+            result.push(parts.length === 0 ? source : navigatePath(source, parts, withMethods));
+        } else if (typeof item === 'string' && protocols && hasProtocol(item)) {
+            result.push(await resolveProtocolValue(item, protocols, options));
+        } else if (Array.isArray(item)) {
+            result.push(await resolveArray(item, source, aliasMap, withMethods, protocols, options));
+        } else if (item && typeof item === 'object') {
+            const proto = Object.getPrototypeOf(item);
+            if (proto === Object.prototype || proto === null) {
+                result.push(await resolveValues(item, source, options));
+            } else {
+                result.push(item);
+            }
+        } else {
+            result.push(item);
+        }
     }
-  }
-  return result;
+    return result;
 }
 
 /**
- * Resolve RHS path strings in a pattern object against a source object.
- * 
- * Any value that is a string starting with `?.` is treated as a path
- * and resolved against the source object using optional chaining semantics.
- * Non-string values and strings not starting with `?.` pass through unchanged.
+ * Async resolve RHS path strings in a pattern object against a source object.
  * 
- * Supports `withMethods` for calling methods during resolution and `aka` for
- * alias substitution, consistent with assignGingerly's LHS path handling.
- * 
- * Special case: `'?.'` (empty path) resolves to the source object itself.
+ * Supports async protocol handlers (e.g., fetch, IndexedDB).
+ * For synchronous-only patterns, use `getValues` from 'assign-gingerly/getValues.js' instead.
  * 
  * @param pattern - Object whose RHS values may contain `?.` path strings
  * @param source - Object to resolve paths against
- * @param options - Optional withMethods and aka for method calls and aliases
+ * @param options - Optional withMethods, aka, and protocol handlers
  * @returns New object with path strings replaced by resolved values
- * 
- * @example
- * const result = resolveValues({
- *   hello: '?.myPropContainer?.stringProp',
- *   foo: '?.myFooString',
- *   literal: 42
- * }, source);
- * 
- * @example
- * // With methods and aliases
- * const result = resolveValues({
- *   text: '?.q?..username?.textContent'
- * }, source, { 
- *   withMethods: ['querySelector'],
- *   aka: { 'q': 'querySelector' }
- * });
  */
 export async function resolveValues(
-  pattern: Record<string, any>,
-  source: any,
-  options?: ResolveValuesOptions
+    pattern: Record<string, any>,
+    source: any,
+    options?: ResolveValuesOptions
 ): Promise<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 protocols = options?.protocols;
-  
-  const result: Record<string, any> = {};
-  for (const [key, value] of Object.entries(pattern)) {
-    if (typeof value === 'string' && value.startsWith('?.')) {
-      // Apply aliases to the RHS path
-      const aliased = applyAliases(value, aliasMap);
-      
-      // Parse path with caching
-      const parts = parseCachedPath(aliased);
-      
-      // Navigate with method support
-      result[key] = parts.length === 0 ? source : navigatePath(source, parts, withMethods);
-    } else if (typeof value === 'string' && protocols && hasProtocol(value)) {
-      // Protocol-prefixed value — resolve asynchronously
-      result[key] = await resolveProtocolValue(value, protocols, options);
-    } else if (Array.isArray(value)) {
-      // Resolve path strings and protocols within arrays (recursing into nested arrays)
-      result[key] = await resolveArray(value, source, aliasMap, withMethods, protocols, options);
-    } else if (typeof value === 'object' && value !== null) {
-      // Recursively resolve nested plain objects (e.g., headers: { "...": "globalThis://key" })
-      // Only recurse into plain objects — skip DOM elements, class instances, etc.
-      const proto = Object.getPrototypeOf(value);
-      if (proto === Object.prototype || proto === null) {
-        result[key] = await resolveValues(value, source, options);
-      } else {
-        result[key] = value;
-      }
-    } else {
-      result[key] = value;
-    }
-  }
-  return result;
-}
-
-/**
- * Resolve a single `?.`-delimited path string against a source object.
- * 
- * This is a lighter-weight alternative to `resolveValues` when you only need
- * to resolve one path and don't want the overhead of creating wrapper objects.
- * 
- * @param path - A `?.`-delimited path string (e.g., '?.behaviors?.command')
- * @param source - Object to resolve the path against
- * @param options - Optional withMethods and aka for method calls and aliases
- * @returns The resolved value, or undefined if any segment is nullish
- * 
- * @example
- * const value = resolveValue('?.behaviors?.commandBehavior?.command', el);
- * 
- * @example
- * const value = resolveValue('?.q?.myEl?.textContent', el, {
- *   withMethods: ['querySelector'],
- *   aka: { 'q': 'querySelector' }
- * });
- */
-export function resolveValue(
-  path: string,
-  source: any,
-  options?: ResolveValuesOptions
-): any {
-  if (!path.startsWith('?.')) return path;
-
-  // Build alias map
-  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);
+    if (options?.aka) {
+        for (const [alias, target] of Object.entries(options.aka)) {
+            aliasMap.set(alias, target);
+        }
     }
-    aliased = applyAliases(path, aliasMap);
-  }
-
-  // Parse path with caching
-  const parts = parseCachedPath(aliased);
-  if (parts.length === 0) return source;
 
-  // Build methods set
-  const withMethods = options?.withMethods
-    ? options.withMethods instanceof Set
-      ? options.withMethods
-      : new Set(options.withMethods)
-    : undefined;
-
-  return navigatePath(source, parts, withMethods);
+    const withMethods = options?.withMethods
+        ? options.withMethods instanceof Set
+            ? options.withMethods
+            : new Set(options.withMethods)
+        : undefined;
+
+    const protocols = options?.protocols;
+
+    const result: Record<string, any> = {};
+    for (const [key, value] of Object.entries(pattern)) {
+        if (typeof value === 'string' && value.startsWith('?.')) {
+            const aliased = applyAliases(value, aliasMap);
+            const parts = parseCachedPath(aliased);
+            result[key] = parts.length === 0 ? source : navigatePath(source, parts, withMethods);
+        } else if (typeof value === 'string' && protocols && hasProtocol(value)) {
+            result[key] = await resolveProtocolValue(value, protocols, options);
+        } else if (Array.isArray(value)) {
+            result[key] = await resolveArray(value, source, aliasMap, withMethods, protocols, options);
+        } else if (typeof value === 'object' && value !== null) {
+            const proto = Object.getPrototypeOf(value);
+            if (proto === Object.prototype || proto === null) {
+                result[key] = await resolveValues(value, source, options);
+            } else {
+                result[key] = value;
+            }
+        } else {
+            result[key] = value;
+        }
+    }
+    return result;
 }

package/transitionHelper.js

@@ -77,9 +77,9 @@ export function withTransition(markerNode, direction, transitional, domMutation)
 }
 
 /**
- * Track which rootNodes already have the hide style injected.
+ * Track which (rootNode, className) combos already have styles injected.
  */
-const styleInjected = new WeakSet();
+const styleInjected = new WeakMap();
 
 /**
  * Default CSS class name for hidden elements during transitions.
@@ -87,7 +87,7 @@ const styleInjected = new WeakSet();
 export const DEFAULT_HIDE_CLASS = 'ag-hide';
 
 /**
- * Ensure the hide class style is injected into the rootNode (once per rootNode).
+ * Ensure the hide class style is injected into the rootNode (once per rootNode + className combo).
  *
  * @param {any} rootNode - The Document, ShadowRoot, or element root to inject into
  * @param {string} [hideClass='ag-hide'] - CSS class name
@@ -100,8 +100,14 @@ export function ensureHideStyle(rootNode, hideClass = DEFAULT_HIDE_CLASS, hideCs
         target = document.head;
     }
 
-    if (styleInjected.has(target)) return;
-    styleInjected.add(target);
+    let injectedClasses = styleInjected.get(target);
+    if (!injectedClasses) {
+        injectedClasses = new Set();
+        styleInjected.set(target, injectedClasses);
+    }
+
+    if (injectedClasses.has(hideClass)) return;
+    injectedClasses.add(hideClass);
 
     const style = document.createElement('style');
     style.textContent = `.${hideClass} { ${hideCss} }`;

package/transitionHelper.ts

@@ -91,9 +91,9 @@ export function withTransition(
 }
 
 /**
- * Track which rootNodes already have the hide style injected.
+ * Track which (rootNode, className) combos already have styles injected.
  */
-const styleInjected = new WeakSet<object>();
+const styleInjected = new WeakMap<object, Set<string>>();
 
 /**
  * Default CSS class name for hidden elements during transitions.
@@ -106,7 +106,7 @@ export const DEFAULT_HIDE_CLASS = 'ag-hide';
 const DEFAULT_HIDE_CSS = `display: none`;
 
 /**
- * Ensure the hide class style is injected into the rootNode (once per rootNode).
+ * Ensure the hide class style is injected into the rootNode (once per rootNode + className combo).
  * 
  * @param rootNode - The Document, ShadowRoot, or element root to inject into
  * @param hideClass - CSS class name (default: 'ag-hide')
@@ -123,8 +123,14 @@ export function ensureHideStyle(
         target = document.head;
     }
 
-    if (styleInjected.has(target)) return;
-    styleInjected.add(target);
+    let injectedClasses = styleInjected.get(target);
+    if (!injectedClasses) {
+        injectedClasses = new Set();
+        styleInjected.set(target, injectedClasses);
+    }
+
+    if (injectedClasses.has(hideClass)) return;
+    injectedClasses.add(hideClass);
 
     const style = document.createElement('style');
     style.textContent = `.${hideClass} { ${hideCss} }`;

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

@@ -261,6 +261,37 @@ export interface IAssignGingerlyOptions {
   signal?: AbortSignal;
 }
 
+/**
+ * Options for synchronous value resolution (getValues / getValue).
+ * Extends IAssignGingerlyOptions with synchronous protocol handlers.
+ */
+export interface GetValuesOptions extends IAssignGingerlyOptions {
+  /**
+   * Synchronous protocol handlers for resolving protocol-prefixed values.
+   * Each handler receives the key portion and MUST return synchronously.
+   * For async protocols, use ResolveValuesOptions / resolveValues instead.
+   * 
+   * @example
+   * protocols: {
+   *     globalThis: (key) => globalThis[key],
+   *     localStorage: (key) => JSON.parse(localStorage.getItem(key) || 'null')
+   * }
+   */
+  protocols?: Record<string, (key: string) => any>;
+}
+
+/**
+ * Options for async value resolution (resolveValues).
+ * Same as GetValuesOptions but protocol handlers may return Promises.
+ */
+export interface ResolveValuesOptions extends IAssignGingerlyOptions {
+  /**
+   * Protocol handlers for resolving protocol-prefixed values (e.g., 'globalThis://key').
+   * Each handler receives the key portion and returns the resolved value (sync or async).
+   */
+  protocols?: Record<string, (key: string) => any | Promise<any>>;
+}
+
 /**
  * Event dispatched when enhancement configs are registered
  */
@@ -628,6 +659,26 @@ export interface LazyLoadSwitchResolvedParams extends Omit<LazyLoadResolvedParam
     rhs: any;
 }
 
+/**
+ * Resolved parameters received by ManageTemplateListHandler.assign().
+ */
+export interface ManageTemplateListResolvedParams {
+    /** The iterable to loop over (resolved from VM) */
+    forEach: Iterable<any>;
+    /** Template element to clone per item */
+    instantiate: HTMLTemplateElement | DocumentFragment;
+    /** Insertion method (default: 'appendChild') */
+    method?: 'appendChild' | 'prepend' | 'after';
+    /** Remove nodes on hide instead of using hidden attribute */
+    forget?: boolean;
+    /** Override auto-derived marker name */
+    markerName?: string;
+    /** Wait for async rendering before DOM commit */
+    waitForSettled?: boolean | { idleMs?: number; timeout?: number };
+    /** Yield to browser every N items to prevent jank (default: undefined = no yielding) */
+    yieldEvery?: number;
+}
+
 /**
  * Context passed to onInstantiated callbacks after template cloning.
  */

package/waitForSettled.js

@@ -0,0 +1,57 @@
+/**
+ * waitForSettled.ts — Waits for a DOM subtree to "settle" (mutations stop cascading).
+ *
+ * Observes a node for DOM mutations and debounces: each mutation resets an idle timer.
+ * When no mutations have occurred for `idleMs` milliseconds, the promise resolves.
+ *
+ * Useful for waiting for async rendering (itemscope managers, enhancements, features)
+ * to complete inside a DocumentFragment before committing to the live DOM.
+ *
+ * @example
+ * import { waitForSettled } from 'assign-gingerly/waitForSettled.js';
+ *
+ * const fragment = document.createDocumentFragment();
+ * // ... clone and assign into fragment ...
+ * await waitForSettled(fragment, 100, 2000);
+ * target.appendChild(fragment);
+ *
+ * @param root - The node to observe (typically a DocumentFragment or Element)
+ * @param idleMs - Debounce window in milliseconds. Default: 100
+ * @param timeout - Maximum wait time in milliseconds. If exceeded, rejects. Default: none (infinite)
+ */
+export function waitForSettled(root, idleMs = 100, timeout) {
+    return new Promise((resolve, reject) => {
+        let timer;
+        let maxTimer;
+        const mo = new MutationObserver(() => {
+            clearTimeout(timer);
+            timer = setTimeout(() => {
+                mo.disconnect();
+                if (maxTimer)
+                    clearTimeout(maxTimer);
+                resolve();
+            }, idleMs);
+        });
+        mo.observe(root, {
+            childList: true,
+            subtree: true,
+            attributes: true,
+            characterData: true
+        });
+        // Initial timer — resolves if no mutations happen at all
+        timer = setTimeout(() => {
+            mo.disconnect();
+            if (maxTimer)
+                clearTimeout(maxTimer);
+            resolve();
+        }, idleMs);
+        // Maximum timeout — rejects if mutations never quiesce
+        if (timeout !== undefined) {
+            maxTimer = setTimeout(() => {
+                mo.disconnect();
+                clearTimeout(timer);
+                reject(new Error(`waitForSettled: mutations did not quiesce within ${timeout}ms`));
+            }, timeout);
+        }
+    });
+}