assign-gingerly 0.0.52 → 0.0.54

package/resolveValues.js

@@ -98,6 +98,40 @@ function navigatePath(source, parts, withMethods) {
     }
     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.
+ */
+async function resolveArray(arr, source, aliasMap, withMethods, protocols, options) {
+    const result = [];
+    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;
+}
 /**
  * Resolve RHS path strings in a pattern object against a source object.
  *
@@ -160,6 +194,21 @@ export async function resolveValues(pattern, source, options) {
             // 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;
         }

package/resolveValues.ts

@@ -147,6 +147,43 @@ function navigatePath(
   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.
+ */
+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
+): 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);
+    }
+  }
+  return result;
+}
+
 /**
  * Resolve RHS path strings in a pattern object against a source object.
  * 
@@ -216,6 +253,18 @@ export async function resolveValues(
     } 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;
     }

package/transitionHelper.js

@@ -0,0 +1,109 @@
+/**
+ * transitionHelper.js — Shared view transition coordination utility.
+ *
+ * Provides transition state management, the startViewTransition wrapper with
+ * cancel/re-entry protection, and one-time CSS style injection.
+ *
+ * Used by lazyLoad, lazyLoadSwitch, and available for external consumers
+ * like be-switched.
+ *
+ * @example
+ * import { withTransition, ensureHideStyle } from 'assign-gingerly/transitionHelper.js';
+ *
+ * ensureHideStyle(rootNode);  // inject default .ag-hide style once
+ *
+ * withTransition(markerNode, 'show', true, () => {
+ *     element.classList.remove('ag-hide');
+ * });
+ */
+
+/**
+ * Module-level state map: marker node → transition state.
+ * WeakMap ensures cleanup when markers are GC'd.
+ */
+const stateMap = new WeakMap();
+
+/**
+ * Get or create transition state for a marker node.
+ */
+export function getTransitionState(markerNode) {
+    let state = stateMap.get(markerNode);
+    if (!state) {
+        state = { showPending: false, hidePending: false };
+        stateMap.set(markerNode, state);
+    }
+    return state;
+}
+
+/**
+ * Execute a DOM mutation with optional view transition coordination.
+ *
+ * When `transitional` is true and `document.startViewTransition` is available:
+ * - Cancels any in-flight transition for this marker
+ * - Prevents re-entry (duplicate show/hide while one is pending)
+ * - Wraps the mutation in `document.startViewTransition`
+ *
+ * When `transitional` is false or the API is unavailable:
+ * - Executes the mutation directly (no animation)
+ *
+ * @param {Node} markerNode - The DOM node used as state key
+ * @param {'show' | 'hide'} direction - Determines which pending flag to check
+ * @param {boolean} transitional - Whether to use view transitions
+ * @param {() => void} domMutation - The function that performs the actual DOM changes
+ */
+export function withTransition(markerNode, direction, transitional, domMutation) {
+    if (!transitional || typeof document === 'undefined' || !document.startViewTransition) {
+        domMutation();
+        return;
+    }
+
+    const state = getTransitionState(markerNode);
+
+    if (direction === 'show') {
+        state.hidePending = false;
+        if (state.showPending) return;
+        state.showPending = true;
+        state.active?.skipTransition();
+        state.active = document.startViewTransition(domMutation);
+        state.active.finished.finally(() => { state.showPending = false; });
+    } else {
+        state.showPending = false;
+        if (state.hidePending) return;
+        state.hidePending = true;
+        state.active?.skipTransition();
+        state.active = document.startViewTransition(domMutation);
+        state.active.finished.finally(() => { state.hidePending = false; });
+    }
+}
+
+/**
+ * Track which rootNodes already have the hide style injected.
+ */
+const styleInjected = new WeakSet();
+
+/**
+ * Default CSS class name for hidden elements during transitions.
+ */
+export const DEFAULT_HIDE_CLASS = 'ag-hide';
+
+/**
+ * Ensure the hide class style is injected into the rootNode (once per rootNode).
+ *
+ * @param {any} rootNode - The Document, ShadowRoot, or element root to inject into
+ * @param {string} [hideClass='ag-hide'] - CSS class name
+ * @param {string} [hideCss='display: none'] - CSS properties for the hide class
+ */
+export function ensureHideStyle(rootNode, hideClass = DEFAULT_HIDE_CLASS, hideCss = 'display: none') {
+    // Determine the injection target (shadowRoot or document.head)
+    let target = rootNode;
+    if (target.host === undefined && typeof document !== 'undefined') {
+        target = document.head;
+    }
+
+    if (styleInjected.has(target)) return;
+    styleInjected.add(target);
+
+    const style = document.createElement('style');
+    style.textContent = `.${hideClass} { ${hideCss} }`;
+    target.appendChild(style);
+}

package/transitionHelper.ts

@@ -0,0 +1,132 @@
+/**
+ * transitionHelper.ts — Shared view transition coordination utility.
+ * 
+ * Provides transition state management, the startViewTransition wrapper with
+ * cancel/re-entry protection, and one-time CSS style injection.
+ * 
+ * Used by lazyLoad, lazyLoadSwitch, and available for external consumers
+ * like be-switched.
+ * 
+ * @example
+ * import { withTransition, ensureHideStyle } from 'assign-gingerly/transitionHelper.js';
+ * 
+ * ensureHideStyle(rootNode);  // inject default .ag-hide style once
+ * 
+ * withTransition(markerNode, 'show', true, () => {
+ *     element.classList.remove('ag-hide');
+ * });
+ */
+
+/**
+ * Transition state for a given DOM marker node.
+ */
+export interface TransitionState {
+    active?: ViewTransition;
+    showPending: boolean;
+    hidePending: boolean;
+}
+
+/**
+ * Module-level state map: marker node → transition state.
+ * WeakMap ensures cleanup when markers are GC'd.
+ */
+const stateMap = new WeakMap<Node, TransitionState>();
+
+/**
+ * Get or create transition state for a marker node.
+ */
+export function getTransitionState(markerNode: Node): TransitionState {
+    let state = stateMap.get(markerNode);
+    if (!state) {
+        state = { showPending: false, hidePending: false };
+        stateMap.set(markerNode, state);
+    }
+    return state;
+}
+
+/**
+ * Execute a DOM mutation with optional view transition coordination.
+ * 
+ * When `transitional` is true and `document.startViewTransition` is available:
+ * - Cancels any in-flight transition for this marker
+ * - Prevents re-entry (duplicate show/hide while one is pending)
+ * - Wraps the mutation in `document.startViewTransition`
+ * 
+ * When `transitional` is false or the API is unavailable:
+ * - Executes the mutation directly (no animation)
+ * 
+ * @param markerNode - The DOM node used as state key (typically the start comment marker)
+ * @param direction - 'show' or 'hide' — determines which pending flag to check
+ * @param transitional - Whether to use view transitions
+ * @param domMutation - The function that performs the actual DOM changes
+ */
+export function withTransition(
+    markerNode: Node,
+    direction: 'show' | 'hide',
+    transitional: boolean,
+    domMutation: () => void
+): void {
+    if (!transitional || typeof document === 'undefined' || !document.startViewTransition) {
+        domMutation();
+        return;
+    }
+
+    const state = getTransitionState(markerNode);
+
+    if (direction === 'show') {
+        state.hidePending = false;
+        if (state.showPending) return;
+        state.showPending = true;
+        state.active?.skipTransition();
+        state.active = document.startViewTransition(domMutation);
+        state.active.finished.finally(() => { state.showPending = false; });
+    } else {
+        state.showPending = false;
+        if (state.hidePending) return;
+        state.hidePending = true;
+        state.active?.skipTransition();
+        state.active = document.startViewTransition(domMutation);
+        state.active.finished.finally(() => { state.hidePending = false; });
+    }
+}
+
+/**
+ * Track which rootNodes already have the hide style injected.
+ */
+const styleInjected = new WeakSet<object>();
+
+/**
+ * Default CSS class name for hidden elements during transitions.
+ */
+export const DEFAULT_HIDE_CLASS = 'ag-hide';
+
+/**
+ * Default CSS rule for the hide class.
+ */
+const DEFAULT_HIDE_CSS = `display: none`;
+
+/**
+ * Ensure the hide class style is injected into the rootNode (once per rootNode).
+ * 
+ * @param rootNode - The Document, ShadowRoot, or element root to inject into
+ * @param hideClass - CSS class name (default: 'ag-hide')
+ * @param hideCss - CSS properties for the hide class (default: 'display: none')
+ */
+export function ensureHideStyle(
+    rootNode: any,
+    hideClass: string = DEFAULT_HIDE_CLASS,
+    hideCss: string = DEFAULT_HIDE_CSS
+): void {
+    // Determine the injection target (shadowRoot or document.head)
+    let target = rootNode;
+    if (target.host === undefined && typeof document !== 'undefined') {
+        target = document.head;
+    }
+
+    if (styleInjected.has(target)) return;
+    styleInjected.add(target);
+
+    const style = document.createElement('style');
+    style.textContent = `.${hideClass} { ${hideCss} }`;
+    target.appendChild(style);
+}

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

@@ -481,3 +481,80 @@ export declare class PropertyBag {
     customElementRegistry: any;
     constructor(hostElement: any, ctx?: FeatureSpawnContext, initVals?: any);
 }
+
+// =============================================================================
+// assignFrom handler types
+// =============================================================================
+
+/**
+ * Base configuration for an assignFrom handler invocation.
+ * The `do` field identifies the handler; `resolve` maps named parameters to path strings.
+ */
+export interface HandlerConfig {
+    /** The registered handler name */
+    do: string;
+    /** Named parameters to resolve against the `from` source before passing to the handler */
+    resolve?: Record<string, string>;
+}
+
+/**
+ * Interface for assignFrom handler classes.
+ * Handlers are invoked when a LHS key ends with ' =>'.
+ */
+export interface AssignFromHandler {
+    assign(lhsTarget: any, resolvedParams: Record<string, any>, options: any): Promise<void> | void;
+}
+
+/**
+ * Constructor signature for assignFrom handler classes.
+ */
+export interface AssignFromHandlerConstructor {
+    new (config: HandlerConfig): AssignFromHandler;
+}
+
+// =============================================================================
+// Built-in handler config types
+// =============================================================================
+
+/**
+ * Configuration for the builtIns.lazyLoad handler.
+ */
+export interface LazyLoadConfig extends HandlerConfig {
+    do: 'builtIns.lazyLoad';
+    resolve: {
+        /** Condition to show/hide (resolved from VM) */
+        if: 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;
+        /** Optional async callback invoked after cloning, resolved from the VM */
+        onInstantiated?: string;
+    };
+}
+
+/**
+ * Context passed to onInstantiated callbacks after template cloning.
+ */
+export interface LazyLoadInstantiatedContext {
+    /** The inserted child nodes */
+    nodes: Node[];
+    /** The target element containing the markers */
+    target: Element;
+    /** The full handler config */
+    config: any;
+    /** The resolved parameters */
+    resolvedParams: Record<string, any>;
+}
+
+/**
+ * The LazyLoadHandler class (exported for subclassing).
+ */
+export declare class LazyLoadHandler implements AssignFromHandler {
+    config: any;
+    constructor(config: any);
+    assign(lhsTarget: any, resolvedParams: Record<string, any>, options?: any): Promise<void>;
+    protected onCloneInserted(nodes: Node[], lhsTarget: Element, resolvedParams: Record<string, any>): Promise<void>;
+}