assign-gingerly 0.0.53 → 0.0.55

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

@@ -64,6 +64,12 @@ export interface EnhancementConfig<T = any, Obj = Element> extends EnhancementCo
 
   //only applicable when spawning from a DOM Element reference
   enhKey?: EnhKey;
+
+  /**
+   * Optional features to associate with the spawn class.
+   * Calls assignFeatures(spawn, features) automatically on registration.
+   */
+  features?: FeatureConfigsMap;
     
 }
 
@@ -300,6 +306,12 @@ export interface ItemscopeManagerConfig<T = any> {
     dispose?: string | symbol;
     resolved?: string | symbol;
   };
+
+  /**
+   * Optional features to associate with the manager class.
+   * Calls assignFeatures(manager, features) automatically on registration.
+   */
+  features?: FeatureConfigsMap;
 }
 
 /**
@@ -481,3 +493,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>;
+}