assign-gingerly 0.0.54 → 0.0.55

package/beVigilant.ts

@@ -0,0 +1,85 @@
+/**
+ * beVigilant.ts — MutationObserver-based reactive inference for newly added elements.
+ * 
+ * Dynamically imported when `inferredAssignments.beVigilant: true` is set.
+ * Watches for new [itemprop] elements and attribute changes, applying inferred
+ * assignments from the live `from` object.
+ * 
+ * Requires an AbortSignal for cleanup (disconnects the observer on abort).
+ */
+
+import { Infer } from './inferencer/inferencer.js';
+import { withScopePerimeter } from './inferencer/withScopePerimeter.js';
+import { registerInCache } from './resolveIdRef.js';
+
+/**
+ * Set up a MutationObserver that watches for new [itemprop] elements
+ * and applies inferred assignments from the live `from` object.
+ * 
+ * @param target - The DOM element to observe
+ * @param from - The live source object (read at observation time for current values)
+ * @param config - The inferredAssignments config (byItemprop keys)
+ * @param signal - AbortSignal for cleanup (required)
+ */
+export function setupVigilantObserver(
+    target: Element,
+    from: any,
+    config: { byItemprop?: string[] | true },
+    signal: AbortSignal
+): void {
+    const keys = config.byItemprop === true ? null : new Set(config.byItemprop);
+
+    const observer = new MutationObserver((mutations) => {
+        for (const mutation of mutations) {
+            if (mutation.type === 'childList') {
+                // Process added nodes and their descendants
+                for (const node of mutation.addedNodes) {
+                    if (!(node instanceof Element)) continue;
+                    // Check the added element itself
+                    processElement(node, from, keys, target);
+                    // Check descendants (respecting scope perimeter)
+                    const nested = node.querySelectorAll('[itemprop]');
+                    for (const el of nested) {
+                        processElement(el as Element, from, keys, target);
+                    }
+                }
+            } else if (mutation.type === 'attributes' && mutation.target instanceof Element) {
+                // itemprop attribute was added or changed on an existing element
+                processElement(mutation.target, from, keys, target);
+            }
+        }
+    });
+
+    observer.observe(target, {
+        childList: true,
+        subtree: true,
+        attributes: true,
+        attributeFilter: ['itemprop']
+    });
+
+    // Cleanup on abort
+    signal.addEventListener('abort', () => observer.disconnect(), { once: true });
+}
+
+/**
+ * Process a single element: check if it matches, apply inferred value, cache it.
+ */
+function processElement(
+    element: Element,
+    from: any,
+    keys: Set<string> | null,
+    scopeRoot: Element
+): void {
+    const itemprop = element.getAttribute('itemprop');
+    if (!itemprop) return;
+    if (keys && !keys.has(itemprop)) return;
+    if (!(itemprop in from)) return;
+    if (!withScopePerimeter(scopeRoot, element, '[itemscope]')) return;
+
+    // Set value via inferencer
+    const infer = new Infer(element, itemprop);
+    infer.value = from[itemprop];
+
+    // Cache for future fast access
+    registerInCache(scopeRoot, itemprop, element);
+}

package/enhanceAll.js

@@ -0,0 +1,106 @@
+/**
+ * enhanceAll.ts — Bulk enhancement application via EMC (Element Mount Configuration) JSON.
+ *
+ * Finds matching elements within a target and spawns enhancements on them
+ * using the configuration from EMC JSON files that enhancement packages publish.
+ *
+ * Dynamically imported by assignFrom when `enhance` option is present,
+ * or used standalone.
+ *
+ * @example
+ * import { enhanceAll } from 'assign-gingerly/enhanceAll.js';
+ *
+ * await enhanceAll(shadowRoot, [
+ *     { emc: 'be-bound/emc.json', matching: '[name]' },
+ *     { emc: 'be-observant/emc.json', matching: '[itemprop]' },
+ * ]);
+ */
+import { isAllowedImportPath } from './isAllowedImportPath.js';
+/**
+ * Apply enhancements in bulk to matching elements within a target.
+ *
+ * For each entry:
+ * 1. Dynamically imports the EMC JSON
+ * 2. Extracts enhConfig (spawn path, enhKey, withAttrs)
+ * 3. Finds matching elements via querySelectorAll
+ * 4. Registers the enhancement if not already registered
+ * 5. Spawns the enhancement on each matched element via enh.get()
+ *
+ * Note: No scope perimeter is applied. For reactive observation of new elements,
+ * use mount-observer instead.
+ *
+ * @param target - The DOM element to search within
+ * @param configs - Array of enhancement configurations
+ */
+export async function enhanceAll(target, configs, permissions) {
+    for (const config of configs) {
+        // Validate EMC path unless cross-domain imports are explicitly permitted
+        if (!permissions?.crossDomainImports && !isAllowedImportPath(config.emc)) {
+            throw new Error(`enhanceAll: EMC path "${config.emc}" is a cross-domain URL. ` +
+                `Only relative, absolute, or bare specifier paths are allowed by default. ` +
+                `Pass { crossDomainImports: true } in permissions to override.`);
+        }
+        // 1. Import the EMC JSON
+        const emcModule = await import(config.emc, { with: { type: 'json' } });
+        const emc = emcModule.default ?? emcModule;
+        const { enhConfig } = emc;
+        if (!enhConfig) {
+            throw new Error(`enhanceAll: EMC at "${config.emc}" does not contain an enhConfig field`);
+        }
+        // 2. Determine the selector
+        const selector = config.matching ?? enhConfig.matching ?? '*';
+        // 3. Find matching elements
+        const elements = target.querySelectorAll(selector);
+        if (elements.length === 0)
+            continue;
+        // 4. Resolve and register the enhancement
+        const registryItem = await resolveAndRegister(enhConfig, target);
+        if (!registryItem)
+            continue;
+        // 5. Spawn enhancement on each matched element
+        for (const el of elements) {
+            try {
+                el.enh.get(registryItem);
+            }
+            catch {
+                // If enh gateway isn't available, skip silently
+            }
+        }
+    }
+}
+/**
+ * Resolve the enhancement's registry item from EMC enhConfig.
+ * If not already registered, dynamically imports the spawn module and registers it.
+ */
+async function resolveAndRegister(enhConfig, target) {
+    const { enhKey, spawn: spawnPath } = enhConfig;
+    // Get the enhancement registry for this element's scope
+    const registry = target.customElementRegistry?.enhancementRegistry
+        ?? (typeof customElements !== 'undefined' ? customElements.enhancementRegistry : undefined);
+    if (!registry)
+        return null;
+    // Check if already registered
+    if (enhKey) {
+        const existing = registry.findByEnhKey(enhKey);
+        if (existing)
+            return existing;
+    }
+    // Not registered — dynamically import the spawn module
+    if (!spawnPath)
+        return null;
+    const spawnModule = await import(spawnPath);
+    const SpawnClass = spawnModule.default ?? Object.values(spawnModule).find((v) => typeof v === 'function' && v.prototype);
+    if (!SpawnClass)
+        return null;
+    // Build and register the registry item
+    const registryItem = {
+        spawn: SpawnClass,
+        enhKey,
+    };
+    // Include withAttrs if present in enhConfig
+    if (enhConfig.withAttrs) {
+        registryItem.withAttrs = enhConfig.withAttrs;
+    }
+    registry.push(registryItem);
+    return registryItem;
+}

package/enhanceAll.ts

@@ -0,0 +1,138 @@
+/**
+ * enhanceAll.ts — Bulk enhancement application via EMC (Element Mount Configuration) JSON.
+ * 
+ * Finds matching elements within a target and spawns enhancements on them
+ * using the configuration from EMC JSON files that enhancement packages publish.
+ * 
+ * Dynamically imported by assignFrom when `enhance` option is present,
+ * or used standalone.
+ * 
+ * @example
+ * import { enhanceAll } from 'assign-gingerly/enhanceAll.js';
+ * 
+ * await enhanceAll(shadowRoot, [
+ *     { emc: 'be-bound/emc.json', matching: '[name]' },
+ *     { emc: 'be-observant/emc.json', matching: '[itemprop]' },
+ * ]);
+ */
+
+import { isAllowedImportPath } from './isAllowedImportPath.js';
+import type { AssignPermissions } from './isAllowedImportPath.js';
+
+/**
+ * Configuration for a single enhancement to apply in bulk.
+ */
+export interface EnhanceConfig {
+    /** Path to the EMC JSON file (dynamically imported) */
+    emc: string;
+    /** Override the CSS selector from the EMC (optional) */
+    matching?: string;
+    /** Whether to parse attributes via withAttrs (default: false). Phase II feature. */
+    parse?: boolean;
+}
+
+/**
+ * Apply enhancements in bulk to matching elements within a target.
+ * 
+ * For each entry:
+ * 1. Dynamically imports the EMC JSON
+ * 2. Extracts enhConfig (spawn path, enhKey, withAttrs)
+ * 3. Finds matching elements via querySelectorAll
+ * 4. Registers the enhancement if not already registered
+ * 5. Spawns the enhancement on each matched element via enh.get()
+ * 
+ * Note: No scope perimeter is applied. For reactive observation of new elements,
+ * use mount-observer instead.
+ * 
+ * @param target - The DOM element to search within
+ * @param configs - Array of enhancement configurations
+ */
+export async function enhanceAll(
+    target: Element,
+    configs: EnhanceConfig[],
+    permissions?: AssignPermissions
+): Promise<void> {
+    for (const config of configs) {
+        // Validate EMC path unless cross-domain imports are explicitly permitted
+        if (!permissions?.crossDomainImports && !isAllowedImportPath(config.emc)) {
+            throw new Error(
+                `enhanceAll: EMC path "${config.emc}" is a cross-domain URL. ` +
+                `Only relative, absolute, or bare specifier paths are allowed by default. ` +
+                `Pass { crossDomainImports: true } in permissions to override.`
+            );
+        }
+
+        // 1. Import the EMC JSON
+        const emcModule = await import(config.emc, { with: { type: 'json' } });
+        const emc = emcModule.default ?? emcModule;
+        const { enhConfig } = emc;
+
+        if (!enhConfig) {
+            throw new Error(`enhanceAll: EMC at "${config.emc}" does not contain an enhConfig field`);
+        }
+
+        // 2. Determine the selector
+        const selector = config.matching ?? enhConfig.matching ?? '*';
+
+        // 3. Find matching elements
+        const elements = target.querySelectorAll(selector);
+        if (elements.length === 0) continue;
+
+        // 4. Resolve and register the enhancement
+        const registryItem = await resolveAndRegister(enhConfig, target);
+        if (!registryItem) continue;
+
+        // 5. Spawn enhancement on each matched element
+        for (const el of elements) {
+            try {
+                (el as any).enh.get(registryItem);
+            } catch {
+                // If enh gateway isn't available, skip silently
+            }
+        }
+    }
+}
+
+/**
+ * Resolve the enhancement's registry item from EMC enhConfig.
+ * If not already registered, dynamically imports the spawn module and registers it.
+ */
+async function resolveAndRegister(enhConfig: any, target: Element): Promise<any> {
+    const { enhKey, spawn: spawnPath } = enhConfig;
+
+    // Get the enhancement registry for this element's scope
+    const registry = (target as any).customElementRegistry?.enhancementRegistry
+        ?? (typeof customElements !== 'undefined' ? (customElements as any).enhancementRegistry : undefined);
+
+    if (!registry) return null;
+
+    // Check if already registered
+    if (enhKey) {
+        const existing = registry.findByEnhKey(enhKey);
+        if (existing) return existing;
+    }
+
+    // Not registered — dynamically import the spawn module
+    if (!spawnPath) return null;
+
+    const spawnModule = await import(spawnPath);
+    const SpawnClass = spawnModule.default ?? Object.values(spawnModule).find(
+        (v: any) => typeof v === 'function' && v.prototype
+    );
+
+    if (!SpawnClass) return null;
+
+    // Build and register the registry item
+    const registryItem: any = {
+        spawn: SpawnClass,
+        enhKey,
+    };
+
+    // Include withAttrs if present in enhConfig
+    if (enhConfig.withAttrs) {
+        registryItem.withAttrs = enhConfig.withAttrs;
+    }
+
+    registry.push(registryItem);
+    return registryItem;
+}

package/handlers/join.js

@@ -0,0 +1,74 @@
+/**
+ * builtIns.join handler for assignFrom.
+ *
+ * Joins a resolved array into a single string. Supports nested sub-arrays
+ * with "all-or-nothing" semantics: if any element in a nested sub-array
+ * resolves to null/undefined, the entire sub-array is dropped.
+ *
+ * This handler is auto-loaded by processHandlerCommands when `do: 'builtIns.join'`
+ * is encountered — no explicit import is needed.
+ *
+ * @example
+ * assignFrom(oElement, {
+ *     '?.textContent =>': {
+ *         do: 'builtIns.join',
+ *         resolve: {
+ *             value: ['?.lastName', ', ', '?.firstName']
+ *         }
+ *     }
+ * }, { from: vm });
+ *
+ * @example
+ * // With optional segment (all-or-nothing):
+ * assignFrom(oElement, {
+ *     '?.textContent =>': {
+ *         do: 'builtIns.join',
+ *         resolve: {
+ *             value: ['?.lastName', [', ', '?.middleName'], ', ', '?.firstName']
+ *         }
+ *     }
+ * }, { from: vm });
+ * // If middleName is undefined, the sub-array [', ', undefined] is dropped entirely.
+ */
+/**
+ * Process nested arrays with all-or-nothing null semantics.
+ * - Top-level null/undefined values are filtered out.
+ * - If a nested sub-array contains any null/undefined element, the entire sub-array is dropped.
+ * - Nested sub-arrays that pass are flattened into the result.
+ */
+function processValue(value) {
+    const result = [];
+    for (const item of value) {
+        if (Array.isArray(item)) {
+            // All-or-nothing: if any element is null/undefined, drop the entire sub-array
+            if (item.some(el => el == null)) {
+                continue;
+            }
+            // Sub-array passes — flatten its elements (recursively process nested arrays)
+            result.push(...processValue(item));
+        }
+        else if (item != null) {
+            result.push(item);
+        }
+        // Top-level null/undefined are silently filtered out
+    }
+    return result;
+}
+/**
+ * JoinHandler — built-in handler for composing strings from resolved arrays.
+ *
+ * Returns the joined string via the return-value protocol, which causes
+ * processHandlerCommands to assign it back to the LHS path.
+ */
+export class JoinHandler {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    async assign(lhsTarget, resolvedParams) {
+        const { value } = resolvedParams;
+        const separator = this.config.separator ?? '';
+        const items = Array.isArray(value) ? processValue(value) : [value];
+        return items.join(separator);
+    }
+}

package/handlers/join.ts

@@ -0,0 +1,80 @@
+/**
+ * builtIns.join handler for assignFrom.
+ * 
+ * Joins a resolved array into a single string. Supports nested sub-arrays
+ * with "all-or-nothing" semantics: if any element in a nested sub-array
+ * resolves to null/undefined, the entire sub-array is dropped.
+ * 
+ * This handler is auto-loaded by processHandlerCommands when `do: 'builtIns.join'`
+ * is encountered — no explicit import is needed.
+ * 
+ * @example
+ * assignFrom(oElement, {
+ *     '?.textContent =>': {
+ *         do: 'builtIns.join',
+ *         resolve: {
+ *             value: ['?.lastName', ', ', '?.firstName']
+ *         }
+ *     }
+ * }, { from: vm });
+ * 
+ * @example
+ * // With optional segment (all-or-nothing):
+ * assignFrom(oElement, {
+ *     '?.textContent =>': {
+ *         do: 'builtIns.join',
+ *         resolve: {
+ *             value: ['?.lastName', [', ', '?.middleName'], ', ', '?.firstName']
+ *         }
+ *     }
+ * }, { from: vm });
+ * // If middleName is undefined, the sub-array [', ', undefined] is dropped entirely.
+ */
+
+import type { AssignFromHandler } from '../assignFrom.js';
+
+/**
+ * Process nested arrays with all-or-nothing null semantics.
+ * - Top-level null/undefined values are filtered out.
+ * - If a nested sub-array contains any null/undefined element, the entire sub-array is dropped.
+ * - Nested sub-arrays that pass are flattened into the result.
+ */
+function processValue(value: any[]): any[] {
+    const result: any[] = [];
+    for (const item of value) {
+        if (Array.isArray(item)) {
+            // All-or-nothing: if any element is null/undefined, drop the entire sub-array
+            if (item.some(el => el == null)) {
+                continue;
+            }
+            // Sub-array passes — flatten its elements (recursively process nested arrays)
+            result.push(...processValue(item));
+        } else if (item != null) {
+            result.push(item);
+        }
+        // Top-level null/undefined are silently filtered out
+    }
+    return result;
+}
+
+/**
+ * JoinHandler — built-in handler for composing strings from resolved arrays.
+ * 
+ * Returns the joined string via the return-value protocol, which causes
+ * processHandlerCommands to assign it back to the LHS path.
+ */
+export class JoinHandler implements AssignFromHandler {
+    config: any;
+
+    constructor(config: any) {
+        this.config = config;
+    }
+
+    async assign(lhsTarget: any, resolvedParams: Record<string, any>): Promise<string> {
+        const { value } = resolvedParams;
+        const separator = this.config.separator ?? '';
+
+        const items = Array.isArray(value) ? processValue(value) : [value];
+        return items.join(separator);
+    }
+}

package/handlers/lazyLoad.js

@@ -0,0 +1,212 @@
+/**
+ * builtIns.lazyLoad handler for assignFrom.
+ *
+ * Conditionally clones a template into a target element, using comment markers
+ * to track the inserted content. Supports show/hide and show/remove modes.
+ *
+ * This handler is auto-loaded by processHandlerCommands when `do: 'builtIns.lazyLoad'`
+ * is encountered — no explicit import is needed.
+ *
+ * @example
+ * assignFrom(document.body, {
+ *     '?.querySelector?..mainView =>': {
+ *         do: 'builtIns.lazyLoad',
+ *         resolve: {
+ *             if: '?.isHappy',
+ *             instantiate: 'globalThis://happyMood',
+ *         }
+ *     }
+ * }, { withMethods: ['querySelector'], from: myVM });
+ */
+import { withTransition, ensureHideStyle, DEFAULT_HIDE_CLASS } from '../transitionHelper.js';
+const MARKER_START_PREFIX = '?start name="';
+const MARKER_END = '?end';
+/**
+ * Get the marker name from a template element (uses its id).
+ */
+function getMarkerName(templateEl) {
+    if (templateEl instanceof HTMLTemplateElement) {
+        return templateEl.id || 'anonymous';
+    }
+    if (typeof templateEl === 'string') {
+        return templateEl;
+    }
+    return 'anonymous';
+}
+/**
+ * Find existing start/end comment markers in a target element.
+ * Returns [startMarker, endMarker] or [null, null] if not found.
+ */
+function findMarkers(target, name) {
+    const startText = `${MARKER_START_PREFIX}${name}"`;
+    let startMarker = null;
+    let endMarker = null;
+    const walker = document.createTreeWalker(target, NodeFilter.SHOW_COMMENT);
+    let node;
+    while ((node = walker.nextNode())) {
+        if (!startMarker && node.data === startText) {
+            startMarker = node;
+        }
+        else if (startMarker && !endMarker && node.data === MARKER_END) {
+            endMarker = node;
+            break;
+        }
+    }
+    return [startMarker, endMarker];
+}
+/**
+ * Create start/end markers and insert them into the target.
+ */
+function createMarkers(target, name, method) {
+    const startMarker = document.createComment(`${MARKER_START_PREFIX}${name}"`);
+    const endMarker = document.createComment(MARKER_END);
+    if (method === 'prepend') {
+        target.prepend(endMarker);
+        target.prepend(startMarker);
+    }
+    else {
+        target.appendChild(startMarker);
+        target.appendChild(endMarker);
+    }
+    return [startMarker, endMarker];
+}
+/**
+ * Get all nodes between start and end markers.
+ */
+function getNodesBetweenMarkers(start, end) {
+    const nodes = [];
+    let current = start.nextSibling;
+    while (current && current !== end) {
+        nodes.push(current);
+        current = current.nextSibling;
+    }
+    return nodes;
+}
+/**
+ * LazyLoadHandler — built-in handler for conditional template instantiation.
+ *
+ * Exported so it can be subclassed for custom behavior.
+ */
+export class LazyLoadHandler {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    async assign(lhsTarget, resolvedParams) {
+        const { if: condition, instantiate, method = 'appendChild', forget = false, transitional = false, hideClass = DEFAULT_HIDE_CLASS } = resolvedParams;
+        if (!(lhsTarget instanceof Element)) {
+            throw new Error('builtIns.lazyLoad: lhsTarget must be a DOM Element');
+        }
+        const name = getMarkerName(instantiate);
+        let [startMarker, endMarker] = findMarkers(lhsTarget, name);
+        if (condition) {
+            if (startMarker && endMarker) {
+                const nodes = getNodesBetweenMarkers(startMarker, endMarker);
+                if (nodes.length > 0) {
+                    withTransition(startMarker, 'show', transitional, () => {
+                        for (const node of nodes) {
+                            if (node instanceof Element) {
+                                if (transitional) {
+                                    node.classList.remove(hideClass);
+                                } else {
+                                    node.removeAttribute('hidden');
+                                }
+                            }
+                        }
+                    });
+                }
+                else {
+                    if (transitional) {
+                        ensureHideStyle(lhsTarget.getRootNode());
+                        withTransition(startMarker, 'show', true, () => {
+                            this.cloneAndInsertSync(instantiate, startMarker, endMarker, lhsTarget, resolvedParams);
+                        });
+                    } else {
+                        await this.cloneAndInsert(instantiate, startMarker, endMarker, lhsTarget, resolvedParams);
+                    }
+                }
+            }
+            else {
+                [startMarker, endMarker] = createMarkers(lhsTarget, name, method);
+                if (transitional) {
+                    ensureHideStyle(lhsTarget.getRootNode());
+                    withTransition(startMarker, 'show', true, () => {
+                        this.cloneAndInsertSync(instantiate, startMarker, endMarker, lhsTarget, resolvedParams);
+                    });
+                } else {
+                    await this.cloneAndInsert(instantiate, startMarker, endMarker, lhsTarget, resolvedParams);
+                }
+            }
+        }
+        else {
+            if (startMarker && endMarker) {
+                const nodes = getNodesBetweenMarkers(startMarker, endMarker);
+                if (nodes.length === 0) return;
+                if (forget) {
+                    withTransition(startMarker, 'hide', transitional, () => {
+                        for (const node of nodes) {
+                            node.parentNode?.removeChild(node);
+                        }
+                    });
+                }
+                else {
+                    withTransition(startMarker, 'hide', transitional, () => {
+                        for (const node of nodes) {
+                            if (node instanceof Element) {
+                                if (transitional) {
+                                    ensureHideStyle(lhsTarget.getRootNode(), hideClass);
+                                    node.classList.add(hideClass);
+                                } else {
+                                    node.setAttribute('hidden', '');
+                                }
+                            }
+                        }
+                    });
+                }
+            }
+        }
+    }
+    cloneAndInsertSync(templateEl, startMarker, endMarker, lhsTarget, resolvedParams) {
+        let content;
+        if (templateEl instanceof HTMLTemplateElement) {
+            content = templateEl.content.cloneNode(true);
+        }
+        else if (templateEl instanceof DocumentFragment) {
+            content = templateEl.cloneNode(true);
+        }
+        else {
+            throw new Error(`builtIns.lazyLoad: instantiate must resolve to an HTMLTemplateElement or DocumentFragment`);
+        }
+        const nodes = Array.from(content.childNodes);
+        endMarker.parentNode.insertBefore(content, endMarker);
+        return nodes;
+    }
+    async cloneAndInsert(templateEl, startMarker, endMarker, lhsTarget, resolvedParams) {
+        let content;
+        if (templateEl instanceof HTMLTemplateElement) {
+            content = templateEl.content.cloneNode(true);
+        }
+        else if (templateEl instanceof DocumentFragment) {
+            content = templateEl.cloneNode(true);
+        }
+        else {
+            throw new Error(`builtIns.lazyLoad: instantiate must resolve to an HTMLTemplateElement or DocumentFragment`);
+        }
+        const nodes = Array.from(content.childNodes);
+        endMarker.parentNode.insertBefore(content, endMarker);
+        await this.onCloneInserted(nodes, lhsTarget, resolvedParams);
+        if (resolvedParams.onInstantiated && typeof resolvedParams.onInstantiated === 'function') {
+            const ctx = {
+                nodes,
+                target: lhsTarget,
+                config: this.config,
+                resolvedParams
+            };
+            await resolvedParams.onInstantiated(ctx);
+        }
+        return nodes;
+    }
+    async onCloneInserted(nodes, lhsTarget, resolvedParams) {
+        // No-op by default. Subclasses override.
+    }
+}