ngx-virtual-dnd 3.0.1 → 3.1.1

package/fesm2022/ngx-virtual-dnd.mjs

@@ -1,5 +1,5 @@
 import * as i0 from '@angular/core';
-import { signal, InjectionToken, computed, effect, Injectable, isDevMode, inject, NgZone, input, ChangeDetectionStrategy, Component, ElementRef, Injector, afterNextRender, viewChild, Directive, output, contentChild, EnvironmentInjector, TemplateRef, ViewContainerRef } from '@angular/core';
+import { signal, InjectionToken, computed, effect, Injectable, inject, NgZone, isDevMode, input, ChangeDetectionStrategy, Component, ElementRef, Injector, afterNextRender, viewChild, Directive, output, contentChild, EnvironmentInjector, TemplateRef, ViewContainerRef } from '@angular/core';
 import { NgTemplateOutlet } from '@angular/common';
 
 /**
@@ -457,9 +457,6 @@ const INITIAL_CORE_STATE = {
     draggedItem: null,
     sourceDroppableId: null,
     sourceIndex: null,
-    activeDroppableId: null,
-    placeholderId: null,
-    placeholderIndex: null,
     grabOffset: null,
     initialPosition: null,
     lockAxis: null,
@@ -469,10 +466,12 @@ const INITIAL_CORE_STATE = {
  * Central service for managing drag-and-drop state.
  * Uses signals for reactive state management.
  *
- * Architecture: High-frequency fields (`cursorPosition`, `keyboardTargetIndex`)
- * are stored in dedicated signals, separate from the core state. This prevents
- * 60fps cursor updates from triggering re-evaluation of the 10+ computeds
- * that only depend on rarely-changing properties (isDragging, draggedItem, etc.).
+ * Architecture: High-frequency fields (`cursorPosition`, `keyboardTargetIndex`,
+ * `activeDroppableId`, `placeholderId`, `placeholderIndex`) are stored in dedicated
+ * signals, separate from the core state. This prevents 60fps cursor and
+ * placeholder updates from rebuilding the core state object or re-evaluating the
+ * 8+ computeds that only depend on rarely-changing properties (isDragging,
+ * draggedItem, etc.).
  */
 class DragStateService {
     /** Core state signal — contains all rarely-changing properties */
@@ -481,6 +480,12 @@ class DragStateService {
     #cursorPosition = signal(null, ...(ngDevMode ? [{ debugName: "#cursorPosition" }] : []));
     /** High-frequency keyboard target index — updated on each arrow key press */
     #keyboardTargetIndex = signal(null, ...(ngDevMode ? [{ debugName: "#keyboardTargetIndex" }] : []));
+    /** ID of the droppable currently being hovered over — changes on droppable crossings */
+    #activeDroppableId = signal(null, ...(ngDevMode ? [{ debugName: "#activeDroppableId" }] : []));
+    /** ID of the item the placeholder should appear before */
+    #placeholderId = signal(null, ...(ngDevMode ? [{ debugName: "#placeholderId" }] : []));
+    /** Index where the placeholder should be inserted — updated on each placeholder move */
+    #placeholderIndex = signal(null, ...(ngDevMode ? [{ debugName: "#placeholderIndex" }] : []));
     /** Flag indicating if the last drag was cancelled (not dropped) */
     #wasCancelled = signal(false, ...(ngDevMode ? [{ debugName: "#wasCancelled" }] : []));
     /** Whether the last drag was cancelled (for droppable to check before emitting drop) */
@@ -496,11 +501,11 @@ class DragStateService {
     /** Original index of the dragged item in the source list */
     sourceIndex = computed(() => this.#state().sourceIndex, ...(ngDevMode ? [{ debugName: "sourceIndex" }] : []));
     /** ID of the droppable currently being hovered over */
-    activeDroppableId = computed(() => this.#state().activeDroppableId, ...(ngDevMode ? [{ debugName: "activeDroppableId" }] : []));
+    activeDroppableId = this.#activeDroppableId.asReadonly();
     /** ID of the item the placeholder should appear before */
-    placeholderId = computed(() => this.#state().placeholderId, ...(ngDevMode ? [{ debugName: "placeholderId" }] : []));
+    placeholderId = this.#placeholderId.asReadonly();
     /** Index where the placeholder should be inserted */
-    placeholderIndex = computed(() => this.#state().placeholderIndex, ...(ngDevMode ? [{ debugName: "placeholderIndex" }] : []));
+    placeholderIndex = this.#placeholderIndex.asReadonly();
     /** Current cursor position */
     cursorPosition = this.#cursorPosition.asReadonly();
     /** Offset from cursor to element top-left (for maintaining grab position) */
@@ -545,14 +550,14 @@ class DragStateService {
         this.#wasCancelled.set(false);
         this.#cursorPosition.set(cursorPosition ?? null);
         this.#keyboardTargetIndex.set(isKeyboardDrag ? (sourceIndex ?? 0) : null);
+        this.#activeDroppableId.set(activeDroppableId ?? null);
+        this.#placeholderId.set(placeholderId ?? null);
+        this.#placeholderIndex.set(placeholderIndex ?? null);
         this.#state.set({
             isDragging: true,
             draggedItem: item,
             sourceDroppableId: item.droppableId,
             sourceIndex: sourceIndex ?? null,
-            activeDroppableId: activeDroppableId ?? null,
-            placeholderId: placeholderId ?? null,
-            placeholderIndex: placeholderIndex ?? null,
             grabOffset: grabOffset ?? null,
             initialPosition: axisLockPosition ?? cursorPosition ?? null,
             lockAxis: lockAxis ?? null,
@@ -568,18 +573,12 @@ class DragStateService {
         }
         // Write cursor to dedicated high-frequency signal
         this.#cursorPosition.set(update.cursorPosition);
-        // Only update core state if droppable/placeholder actually changed
-        const current = this.#state();
-        if (current.activeDroppableId !== update.activeDroppableId ||
-            current.placeholderId !== update.placeholderId ||
-            current.placeholderIndex !== update.placeholderIndex) {
-            this.#state.update((state) => ({
-                ...state,
-                activeDroppableId: update.activeDroppableId,
-                placeholderId: update.placeholderId,
-                placeholderIndex: update.placeholderIndex,
-            }));
-        }
+        // Each target lives in its own signal, so a placeholder-only frame never
+        // rebuilds the core state object or re-fires the rarely-changing computeds.
+        // Signals already no-op on identical values, so unconditional sets are safe.
+        this.#activeDroppableId.set(update.activeDroppableId);
+        this.#placeholderId.set(update.placeholderId);
+        this.#placeholderIndex.set(update.placeholderIndex);
     }
     /**
      * Update just the active droppable.
@@ -588,10 +587,7 @@ class DragStateService {
         if (!this.#state().isDragging) {
             return;
         }
-        this.#state.update((state) => ({
-            ...state,
-            activeDroppableId: droppableId,
-        }));
+        this.#activeDroppableId.set(droppableId);
     }
     /**
      * Update just the placeholder position.
@@ -600,18 +596,28 @@ class DragStateService {
         if (!this.#state().isDragging) {
             return;
         }
-        this.#state.update((state) => ({
-            ...state,
-            placeholderId,
-        }));
+        this.#placeholderId.set(placeholderId);
+    }
+    /**
+     * Update only the placeholder signals without touching cursor position or active droppable.
+     *
+     * Used by the autoscroll scroll-only fast path: when a scroll fires, the cursor has not
+     * moved, so only the placeholder index needs recalculation. Skipping the cursor and
+     * active-droppable writes avoids spurious re-evaluation of computeds that read those signals.
+     */
+    updateScrollOnlyPlaceholder(placeholderId, placeholderIndex) {
+        if (!this.#state().isDragging) {
+            return;
+        }
+        this.#placeholderId.set(placeholderId);
+        this.#placeholderIndex.set(placeholderIndex);
     }
     /**
      * End the drag operation and reset state (normal drop).
      */
     endDrag() {
         this.#wasCancelled.set(false);
-        this.#cursorPosition.set(null);
-        this.#keyboardTargetIndex.set(null);
+        this.#resetHighFrequencySignals();
         this.#state.set(INITIAL_CORE_STATE);
     }
     /**
@@ -619,15 +625,24 @@ class DragStateService {
      */
     cancelDrag() {
         this.#wasCancelled.set(true);
+        this.#resetHighFrequencySignals();
+        this.#state.set(INITIAL_CORE_STATE);
+    }
+    /**
+     * Reset the dedicated high-frequency signals to their initial null state.
+     */
+    #resetHighFrequencySignals() {
         this.#cursorPosition.set(null);
         this.#keyboardTargetIndex.set(null);
-        this.#state.set(INITIAL_CORE_STATE);
+        this.#activeDroppableId.set(null);
+        this.#placeholderId.set(null);
+        this.#placeholderIndex.set(null);
     }
     /**
      * Check if a specific droppable is currently active.
      */
     isDroppableActive(droppableId) {
-        return this.#state().activeDroppableId === droppableId;
+        return this.#activeDroppableId() === droppableId;
     }
     /**
      * Get the current state snapshot (for event creation).
@@ -635,6 +650,9 @@ class DragStateService {
     getStateSnapshot() {
         return {
             ...this.#state(),
+            activeDroppableId: this.#activeDroppableId(),
+            placeholderId: this.#placeholderId(),
+            placeholderIndex: this.#placeholderIndex(),
             cursorPosition: this.#cursorPosition(),
             keyboardTargetIndex: this.#keyboardTargetIndex(),
         };
@@ -651,7 +669,7 @@ class DragStateService {
         // Same-list adjustment: if target is at or after source, add 1
         // This accounts for the hidden item shifting everything up visually
         const sourceDroppableId = state.draggedItem?.droppableId;
-        const activeDroppableId = state.activeDroppableId;
+        const activeDroppableId = this.#activeDroppableId();
         const isSameList = sourceDroppableId === activeDroppableId;
         const sourceIndex = state.sourceIndex ?? -1;
         let placeholderIndex = targetIndex;
@@ -659,10 +677,7 @@ class DragStateService {
             placeholderIndex = targetIndex + 1;
         }
         this.#keyboardTargetIndex.set(targetIndex);
-        this.#state.update((s) => ({
-            ...s,
-            placeholderIndex,
-        }));
+        this.#placeholderIndex.set(placeholderIndex);
     }
     /**
      * Update the active droppable during keyboard navigation (for cross-list moves).
@@ -681,11 +696,8 @@ class DragStateService {
             placeholderIndex = targetIndex + 1;
         }
         this.#keyboardTargetIndex.set(targetIndex);
-        this.#state.update((s) => ({
-            ...s,
-            activeDroppableId: droppableId,
-            placeholderIndex,
-        }));
+        this.#activeDroppableId.set(droppableId);
+        this.#placeholderIndex.set(placeholderIndex);
     }
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.0.6", ngImport: i0, type: DragStateService, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
     static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.0.6", ngImport: i0, type: DragStateService, providedIn: 'root' });
@@ -702,6 +714,7 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.0.6", ngImpor
  * This is the core algorithm that makes virtual scroll + drag-and-drop work together.
  */
 class PositionCalculatorService {
+    #ngZone = inject(NgZone);
     /** Data attribute used to identify droppable elements */
     #DROPPABLE_ID_ATTR = 'data-droppable-id';
     /** Data attribute used to identify droppable groups */
@@ -712,39 +725,146 @@ class PositionCalculatorService {
     #MAX_PARENT_TRAVERSAL = 15;
     /** Reusable result object for getNearEdge (avoids per-frame allocation) */
     #nearEdgeResult = { top: false, bottom: false, left: false, right: false };
+    /** Active drag session rect snapshot, or null when no drag is in progress. */
+    #session = null;
+    /**
+     * Begin a drag session: snapshot the candidate droppables for `groupName` and
+     * their rects once, then watch for viewport changes (scroll/resize) that would
+     * invalidate those rects. While a session is active, `findDroppableAtPoint`
+     * runs as pure geometry against the cached rects instead of `elementFromPoint`.
+     *
+     * Safe to call repeatedly — a new call replaces any previous session.
+     */
+    beginDragSession(groupName) {
+        this.endDragSession();
+        const candidates = this.#queryDroppables(groupName);
+        const onViewportChange = () => {
+            if (this.#session) {
+                this.#session.dirty = true;
+            }
+        };
+        this.#session = {
+            groupName,
+            candidates,
+            rects: candidates.map((el) => el.getBoundingClientRect()),
+            dirty: false,
+            onViewportChange,
+        };
+        // Capture-phase scroll catches scrolling on any ancestor scroller (scroll does
+        // not bubble); resize covers viewport changes. Both only mark rects dirty —
+        // the actual re-read is deferred to the next hit-test.
+        if (typeof window !== 'undefined') {
+            this.#ngZone.runOutsideAngular(() => {
+                window.addEventListener('scroll', onViewportChange, { capture: true, passive: true });
+                window.addEventListener('resize', onViewportChange, { passive: true });
+            });
+        }
+    }
+    /**
+     * End the current drag session and detach viewport listeners.
+     * Safe to call when no session is active.
+     */
+    endDragSession() {
+        const session = this.#session;
+        if (!session) {
+            return;
+        }
+        this.#session = null;
+        if (typeof window !== 'undefined') {
+            window.removeEventListener('scroll', session.onViewportChange, { capture: true });
+            window.removeEventListener('resize', session.onViewportChange);
+        }
+    }
+    /**
+     * Mark the cached droppable rects as stale so they are re-read on the next
+     * hit-test. Called explicitly from the autoscroll recalculation path, where the
+     * scroll event has not yet fired but the container has already moved.
+     */
+    invalidateDroppableRects() {
+        if (this.#session) {
+            this.#session.dirty = true;
+        }
+    }
     /**
      * Find the droppable element at a given point.
      *
-     * This works by temporarily hiding the dragged element, then using
-     * document.elementFromPoint to find what's underneath the cursor.
+     * Uses pure geometric hit-testing against snapshotted droppable rects. When a
+     * drag session is active (see {@link beginDragSession}) the rects are cached and
+     * reused across frames; otherwise a one-shot DOM query is performed. The
+     * `draggedElement` parameter is retained for API compatibility but no longer
+     * needs to be hidden — geometry does not depend on cursor occlusion.
      *
      * @param x - Cursor X coordinate
      * @param y - Cursor Y coordinate
-     * @param draggedElement - The element being dragged (will be temporarily hidden)
+     * @param _draggedElement - The element being dragged (unused; kept for compatibility)
      * @param groupName - The drag-and-drop group name to filter by
      * @returns The droppable element, or null if none found
      */
-    findDroppableAtPoint(x, y, draggedElement, groupName) {
-        // Skip pointerEvents toggle when element is already hidden (display: none during active drag).
-        // offsetParent is null for hidden elements — toggling style would force a style recalculation.
-        const isHidden = draggedElement.offsetParent === null;
-        let originalPointerEvents;
-        if (!isHidden) {
-            originalPointerEvents = draggedElement.style.pointerEvents;
-            draggedElement.style.pointerEvents = 'none';
+    findDroppableAtPoint(x, y, _draggedElement, groupName) {
+        const session = this.#session;
+        if (session && session.groupName === groupName) {
+            if (session.dirty) {
+                for (let i = 0; i < session.candidates.length; i++) {
+                    session.rects[i] = session.candidates[i].getBoundingClientRect();
+                }
+                session.dirty = false;
+            }
+            return this.#hitTest(x, y, session.candidates, session.rects);
         }
-        try {
-            const elementAtPoint = document.elementFromPoint(x, y);
-            if (!elementAtPoint) {
-                return null;
+        // No active session: one-shot geometric query (still avoids elementFromPoint).
+        const candidates = this.#queryDroppables(groupName);
+        const rects = candidates.map((el) => el.getBoundingClientRect());
+        return this.#hitTest(x, y, candidates, rects);
+    }
+    /**
+     * Look up a droppable element by its ID.
+     *
+     * When a drag session is active, searches the cached candidate list (O(n), avoids a DOM
+     * query). Falls back to `document.querySelector` when no session is active.
+     *
+     * Intended for the autoscroll scroll-only fast path, where the active droppable is already
+     * known and only the placeholder index needs recalculation.
+     */
+    getDroppableById(id) {
+        if (this.#session) {
+            for (const candidate of this.#session.candidates) {
+                if (candidate.getAttribute(this.#DROPPABLE_ID_ATTR) === id) {
+                    return candidate;
+                }
             }
-            return this.getDroppableParent(elementAtPoint, groupName);
+            return null;
         }
-        finally {
-            if (!isHidden) {
-                draggedElement.style.pointerEvents = originalPointerEvents;
+        if (typeof document === 'undefined') {
+            return null;
+        }
+        const escaped = typeof CSS !== 'undefined' && CSS.escape ? CSS.escape(id) : id;
+        return document.querySelector(`[${this.#DROPPABLE_ID_ATTR}="${escaped}"]`);
+    }
+    /**
+     * Query all droppable elements belonging to a group, in document order.
+     */
+    #queryDroppables(groupName) {
+        if (typeof document === 'undefined') {
+            return [];
+        }
+        const escaped = typeof CSS !== 'undefined' && CSS.escape ? CSS.escape(groupName) : groupName;
+        return Array.from(document.querySelectorAll(`[${this.#DROPPABLE_GROUP_ATTR}="${escaped}"]`));
+    }
+    /**
+     * Geometric hit-test: return the last candidate (in document order) whose rect
+     * contains the point. "Last in document order" reproduces the painter's-order
+     * tie-break that `elementFromPoint` provided for free — a nested or later
+     * overlapping droppable is painted on top of an earlier/ancestor one.
+     */
+    #hitTest(x, y, candidates, rects) {
+        let match = null;
+        for (let i = 0; i < candidates.length; i++) {
+            const r = rects[i];
+            if (x >= r.left && x <= r.right && y >= r.top && y <= r.bottom) {
+                match = candidates[i];
             }
         }
+        return match;
     }
     /**
      * Find the draggable element at a given point.
@@ -956,6 +1076,123 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.0.6", ngImpor
                 }]
         }] });
 
+/**
+ * Single RAF loop that coordinates all drag-frame work in ordered phases:
+ *
+ *   1. Participant phase (READ+WRITE): registered participants run first.
+ *      AutoScrollService registers here to perform edge-scroll + immediate
+ *      placeholder recalculation in the same synchronous frame — preserving
+ *      the Safari synchronous-callback constraint.
+ *   2. Main compute phase (COMPUTE+WRITE): onTick is called with the latest
+ *      cursor. Only runs when the cursor has changed (cursorDirty=true), so
+ *      autoscroll-only frames (cursor stationary) incur zero hit-test work.
+ *
+ * PointerDragHandler calls `queueCursorUpdate()` instead of managing its own
+ * RAF per pointermove. This coalesces all moves within a frame into one update
+ * and ensures pointer-move work always runs after participant work.
+ */
+class DragSchedulerService {
+    #ngZone = inject(NgZone);
+    #rafId = null;
+    #onTick = null;
+    /** Latest cursor queued from pointer move events. */
+    #pendingCursor = null;
+    /** True when a new cursor was queued since the last frame. */
+    #cursorDirty = false;
+    /** Tick participants called before the main compute phase each frame. */
+    #participants = [];
+    /**
+     * Start the scheduler RAF loop.
+     * No-op if already running.
+     */
+    start(onTick) {
+        if (this.#rafId !== null) {
+            return;
+        }
+        this.#onTick = onTick;
+        this.#ngZone.runOutsideAngular(() => {
+            this.#scheduleNextTick();
+        });
+    }
+    /**
+     * Stop the scheduler and cancel the pending RAF.
+     * Safe to call when not running.
+     */
+    stop() {
+        if (this.#rafId !== null) {
+            cancelAnimationFrame(this.#rafId);
+            this.#rafId = null;
+        }
+        // Null out onTick so that any in-flight RAF callback (race between cancel
+        // and the browser delivering the frame) is a no-op.
+        this.#onTick = null;
+        this.#pendingCursor = null;
+        this.#cursorDirty = false;
+    }
+    /**
+     * Queue a cursor update from a pointer move event.
+     * Multiple calls between frames are coalesced — only the latest matters.
+     */
+    queueCursorUpdate(position) {
+        this.#pendingCursor = position;
+        this.#cursorDirty = true;
+    }
+    /**
+     * Register a function to be called at the start of each frame, before the main tick.
+     * AutoScrollService registers here to perform edge-scroll within the same frame.
+     * No-op if the same function reference is already registered.
+     */
+    addParticipant(fn) {
+        if (!this.#participants.includes(fn)) {
+            this.#participants.push(fn);
+        }
+    }
+    /**
+     * Unregister a previously added participant.
+     * No-op if the function was not registered.
+     */
+    removeParticipant(fn) {
+        const idx = this.#participants.indexOf(fn);
+        if (idx !== -1) {
+            this.#participants.splice(idx, 1);
+        }
+    }
+    #scheduleNextTick() {
+        this.#rafId = requestAnimationFrame(() => this.#tick());
+    }
+    #tick() {
+        this.#rafId = null;
+        // Guard against the race where stop() was called but the browser already
+        // queued the callback before cancelAnimationFrame() could prevent delivery.
+        if (!this.#onTick) {
+            return;
+        }
+        // Snapshot and reset dirty flag before participants run so that any cursor
+        // update they trigger (theoretically possible in future extensions) is
+        // picked up in the NEXT frame, not folded into this one's compute phase.
+        const cursorDirty = this.#cursorDirty;
+        this.#cursorDirty = false;
+        // Phase 1 — participants (autoscroll scroll + synchronous placeholder update)
+        for (const participant of this.#participants) {
+            participant();
+        }
+        // Phase 2 — main compute (cursor-based hit-test + signal write)
+        this.#onTick(this.#pendingCursor, cursorDirty);
+        // Reschedule only if still active (stop() may have been called by onTick).
+        if (this.#onTick !== null) {
+            this.#scheduleNextTick();
+        }
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.0.6", ngImport: i0, type: DragSchedulerService, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.0.6", ngImport: i0, type: DragSchedulerService, providedIn: 'root' });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.0.6", ngImport: i0, type: DragSchedulerService, decorators: [{
+            type: Injectable,
+            args: [{
+                    providedIn: 'root',
+                }]
+        }] });
+
 /**
  * Default auto-scroll configuration.
  */
@@ -970,11 +1207,11 @@ const DEFAULT_CONFIG = {
 class AutoScrollService {
     #dragState = inject(DragStateService);
     #positionCalculator = inject(PositionCalculatorService);
-    #ngZone = inject(NgZone);
+    #scheduler = inject(DragSchedulerService);
     /** Currently registered scrollable containers */
     #scrollableContainers = new Map();
-    /** Active animation frame ID */
-    #animationFrameId = null;
+    /** Bound reference to #participantTick for stable add/remove with the scheduler. */
+    #boundParticipantTick = () => this.#participantTick();
     /** Callback to invoke when scrolling occurs (for placeholder recalculation) */
     #onScrollCallback = null;
     /** Optional cursor position override for edge detection (bypasses DragState read) */
@@ -1007,27 +1244,21 @@ class AutoScrollService {
     }
     /**
      * Start monitoring for auto-scroll.
-     * Call this when a drag starts.
+     * Registers this service as a tick participant in DragSchedulerService.
+     * The scheduler drives the RAF loop; this service handles scroll logic each frame.
      * @param onScroll Optional callback to invoke when scrolling occurs (for placeholder recalculation)
      */
     startMonitoring(onScroll) {
-        if (this.#animationFrameId !== null) {
-            return;
-        }
         this.#onScrollCallback = onScroll ?? null;
-        this.#ngZone.runOutsideAngular(() => {
-            this.#tick();
-        });
+        this.#scheduler.addParticipant(this.#boundParticipantTick);
     }
     /**
      * Stop monitoring for auto-scroll.
+     * Removes this service from the scheduler's participant list.
      * Call this when a drag ends.
      */
     stopMonitoring() {
-        if (this.#animationFrameId !== null) {
-            cancelAnimationFrame(this.#animationFrameId);
-            this.#animationFrameId = null;
-        }
+        this.#scheduler.removeParticipant(this.#boundParticipantTick);
         this.#onScrollCallback = null;
         this.#cursorOverride = null;
         this.#lastTickCursorX = NaN;
@@ -1047,42 +1278,35 @@ class AutoScrollService {
         this.#cursorOverride = position;
     }
     /**
-     * Animation tick - check cursor position and scroll if needed.
+     * Participant tick — called by DragSchedulerService each RAF frame.
+     *
+     * Runs the edge-scroll check and, if a scroll is performed, synchronously
+     * invokes #onScrollCallback (the placeholder recalculator) in the same frame.
+     * No RAF scheduling here — the scheduler owns the loop.
      */
-    #tick() {
+    #participantTick() {
         const cursor = this.#cursorOverride ?? this.#dragState.cursorPosition();
-        const isDragging = this.#dragState.isDragging();
-        // Stop monitoring if drag ended
-        if (!isDragging) {
-            this.stopMonitoring();
-            return;
-        }
-        // Skip this frame if no cursor position yet, but continue monitoring
+        // No cursor yet — nothing to scroll toward.
         if (!cursor) {
-            this.#animationFrameId = requestAnimationFrame(() => this.#tick());
             return;
         }
-        // Skip container iteration when cursor hasn't moved and no scrolling is active
+        // Skip the container iteration when cursor hasn't moved and scroll is idle.
         if (cursor.x === this.#lastTickCursorX &&
             cursor.y === this.#lastTickCursorY &&
             !this.isScrolling()) {
-            this.#animationFrameId = requestAnimationFrame(() => this.#tick());
             return;
         }
         this.#lastTickCursorX = cursor.x;
         this.#lastTickCursorY = cursor.y;
         let scrollPerformed = false;
-        // Check each container
         for (const [id, { element, config }] of this.#scrollableContainers) {
             const rect = element.getBoundingClientRect();
-            // Check if cursor is inside this container
             const isInside = this.#positionCalculator.isInsideContainer(cursor, rect);
             if (!isInside) {
                 continue;
             }
-            // Check edges
             const nearEdge = this.#positionCalculator.getNearEdge(cursor, rect, config.threshold);
-            // Calculate scroll direction and speed (reuse object to avoid per-frame allocation)
+            // Reuse the per-frame direction object to avoid allocation.
             const direction = this.#tickDirection;
             direction.x = 0;
             direction.y = 0;
@@ -1103,9 +1327,7 @@ class AutoScrollService {
                 direction.x = 1;
                 maxDistance = Math.max(maxDistance, config.threshold - (rect.right - cursor.x));
             }
-            // If near an edge, start scrolling
             if (direction.x !== 0 || direction.y !== 0) {
-                // Calculate speed (accelerate based on distance from edge)
                 let speed = config.maxSpeed;
                 if (config.accelerate) {
                     const distanceRatio = maxDistance / config.threshold;
@@ -1120,14 +1342,12 @@ class AutoScrollService {
                 break;
             }
         }
-        // Reset scroll state if no scrolling was performed
         if (!scrollPerformed) {
             this.#scrollState.containerId = null;
             this.#scrollState.direction.x = 0;
             this.#scrollState.direction.y = 0;
             this.#scrollState.speed = 0;
         }
-        this.#animationFrameId = requestAnimationFrame(() => this.#tick());
     }
     /**
      * Perform the actual scroll operation.
@@ -1194,41 +1414,43 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.0.6", ngImpor
  */
 class ElementCloneService {
     /**
-     * CSS properties to copy from source to clone.
-     * These are the visual properties that affect appearance.
+     * CSS properties to copy from source to clone, pre-stored in kebab-case.
+     * These are the visual properties that affect appearance. Keeping them
+     * kebab-case avoids a camelCase→kebab conversion on every property of every
+     * node during the recursive clone walk (a drag-start hot path).
      */
-    #stylesToCopy = [
+    #stylePropsToCopy = [
         'background',
-        'backgroundColor',
-        'backgroundImage',
+        'background-color',
+        'background-image',
         'border',
-        'borderRadius',
-        'boxShadow',
+        'border-radius',
+        'box-shadow',
         'color',
         'font',
-        'fontFamily',
-        'fontSize',
-        'fontWeight',
-        'lineHeight',
+        'font-family',
+        'font-size',
+        'font-weight',
+        'line-height',
         'padding',
         'margin',
         'display',
-        'flexDirection',
-        'alignItems',
-        'justifyContent',
+        'flex-direction',
+        'align-items',
+        'justify-content',
         'gap',
-        'textAlign',
-        'textDecoration',
+        'text-align',
+        'text-decoration',
         'width',
         'height',
-        'minWidth',
-        'minHeight',
-        'maxWidth',
-        'maxHeight',
+        'min-width',
+        'min-height',
+        'max-width',
+        'max-height',
         'overflow',
         'opacity',
         'transform',
-        'boxSizing',
+        'box-sizing',
     ];
     /**
      * Clone an element with its computed styles.
@@ -1250,11 +1472,11 @@ class ElementCloneService {
      */
     #applyComputedStyles(source, target) {
         const computed = window.getComputedStyle(source);
-        // Copy essential visual properties
-        for (const prop of this.#stylesToCopy) {
-            const value = computed.getPropertyValue(this.#camelToKebab(prop));
+        // Copy essential visual properties (keys are already kebab-case)
+        for (const prop of this.#stylePropsToCopy) {
+            const value = computed.getPropertyValue(prop);
             if (value) {
-                target.style.setProperty(this.#camelToKebab(prop), value);
+                target.style.setProperty(prop, value);
             }
         }
         // Disable animations and transitions on clone
@@ -1372,12 +1594,6 @@ class ElementCloneService {
         clone.classList.remove('vdnd-draggable-dragging');
         clone.classList.remove('vdnd-draggable-disabled');
     }
-    /**
-     * Convert camelCase to kebab-case for CSS properties.
-     */
-    #camelToKebab(str) {
-        return str.replace(/([A-Z])/g, '-$1').toLowerCase();
-    }
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.0.6", ngImport: i0, type: ElementCloneService, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
     static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.0.6", ngImport: i0, type: ElementCloneService, providedIn: 'root' });
 }
@@ -1508,6 +1724,23 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.0.6", ngImpor
  */
 class OverlayContainerService {
     #containerElement = null;
+    /** Number of mounted drag previews currently rendering via a custom template. */
+    #templatePreviewCount = signal(0, ...(ngDevMode ? [{ debugName: "#templatePreviewCount" }] : []));
+    /**
+     * Whether at least one mounted drag preview renders via a custom template.
+     *
+     * When true, DraggableDirective/KeyboardDragHandler skip the expensive
+     * drag-start element clone: the clone would never be shown because the
+     * template takes precedence (see DragPreviewComponent).
+     */
+    hasTemplatePreview = computed(() => this.#templatePreviewCount() > 0, ...(ngDevMode ? [{ debugName: "hasTemplatePreview" }] : []));
+    /**
+     * Register (`active = true`) or unregister (`active = false`) a preview that
+     * renders via a custom template. Calls must be balanced per preview instance.
+     */
+    setTemplatePreviewActive(active) {
+        this.#templatePreviewCount.update((count) => Math.max(0, count + (active ? 1 : -1)));
+    }
     /**
      * Returns the shared overlay container element, lazily creating it on first access.
      * Returns `null` in non-browser environments (SSR).
@@ -2575,6 +2808,8 @@ class DragPreviewComponent {
     cursorOffset = input({ x: 8, y: 8 }, ...(ngDevMode ? [{ debugName: "cursorOffset" }] : []));
     /** Reference to the clone container element (cannot use ES private with viewChild) */
     cloneContainer = viewChild('cloneContainer', ...(ngDevMode ? [{ debugName: "cloneContainer" }] : []));
+    /** Whether this preview's template registration is currently counted (kept balanced). */
+    #templateRegistered = false;
     /** The cloned element from drag state (used when no custom template is provided) */
     clonedElement = computed(() => {
         if (this.previewTemplate()) {
@@ -2591,6 +2826,19 @@ class DragPreviewComponent {
                 container.appendChild(this.#elementRef.nativeElement);
             }
         });
+        // Publish whether this preview renders via a custom template so the drag
+        // directives can skip the drag-start element clone when it won't be shown.
+        effect(() => {
+            const hasTemplate = !!this.previewTemplate();
+            if (hasTemplate && !this.#templateRegistered) {
+                this.#overlayContainer.setTemplatePreviewActive(true);
+                this.#templateRegistered = true;
+            }
+            else if (!hasTemplate && this.#templateRegistered) {
+                this.#overlayContainer.setTemplatePreviewActive(false);
+                this.#templateRegistered = false;
+            }
+        });
         // Effect to insert the cloned element into the container
         effect(() => {
             const container = this.cloneContainer()?.nativeElement;
@@ -2607,6 +2855,10 @@ class DragPreviewComponent {
         });
     }
     ngOnDestroy() {
+        if (this.#templateRegistered) {
+            this.#overlayContainer.setTemplatePreviewActive(false);
+            this.#templateRegistered = false;
+        }
         this.#elementRef.nativeElement.remove();
     }
     /** Whether the preview is visible */
@@ -3789,8 +4041,11 @@ class KeyboardDragHandler {
             isSameList: false,
             draggedItemHeight: rect.height,
         });
-        // Clone element BEFORE updating drag state
-        const clonedElement = this.#deps.elementClone.cloneElement(element);
+        // Clone element BEFORE updating drag state.
+        // Template-first: skip the clone when a template-based preview is mounted.
+        const clonedElement = this.#deps.overlayContainer.hasTemplatePreview()
+            ? undefined
+            : this.#deps.elementClone.cloneElement(element);
         // Start keyboard drag
         this.#deps.keyboardDrag.startKeyboardDrag({
             draggableId: ctx.draggableId,
@@ -3989,8 +4244,6 @@ class PointerDragHandler {
     #boundPointerMove = null;
     #boundPointerUp = null;
     #boundKeyDown = null;
-    /** Request animation frame ID for drag updates */
-    #rafId = null;
     /** Timer ID for drag delay */
     #delayTimerId = null;
     /** Whether the delay has been satisfied (user held long enough) */
@@ -4077,7 +4330,7 @@ class PointerDragHandler {
         });
     }
     /**
-     * Remove listeners + cancel timers + cancel RAF.
+     * Remove listeners + cancel timers.
      * Called after pointer up or when cancelling.
      */
     cleanup() {
@@ -4085,10 +4338,6 @@ class PointerDragHandler {
         this.#startPosition = null;
         this.#deps.callbacks.onPendingChange(false); // Clear pending state on cleanup
         this.#cancelDelayTimer();
-        if (this.#rafId !== null) {
-            cancelAnimationFrame(this.#rafId);
-            this.#rafId = null;
-        }
         // Remove event listeners
         if (this.#boundPointerMove) {
             document.removeEventListener('mousemove', this.#boundPointerMove);
@@ -4145,14 +4394,9 @@ class PointerDragHandler {
         if (!this.#deps.callbacks.isDragging()) {
             return;
         }
-        // Throttle drag updates with requestAnimationFrame
-        if (this.#rafId !== null) {
-            cancelAnimationFrame(this.#rafId);
-        }
-        this.#rafId = requestAnimationFrame(() => {
-            this.#deps.callbacks.onDragMove(position);
-            this.#rafId = null;
-        });
+        // Notify the directive of the new position — it queues this into the scheduler
+        // (DragSchedulerService) which coalesces multiple moves per frame into one RAF tick.
+        this.#deps.callbacks.onDragMove(position);
     }
     /**
      * Handle pointer up (mouse or touch).
@@ -4231,6 +4475,8 @@ class DraggableDirective {
     #elementClone = inject(ElementCloneService);
     #keyboardDrag = inject(KeyboardDragService);
     #dragIndexCalculator = inject(DragIndexCalculatorService);
+    #overlayContainer = inject(OverlayContainerService);
+    #scheduler = inject(DragSchedulerService);
     #ngZone = inject(NgZone);
     #envInjector = inject(EnvironmentInjector);
     #parentGroup = inject(VDND_GROUP_TOKEN, { optional: true });
@@ -4314,6 +4560,7 @@ class DraggableDirective {
             positionCalculator: this.#positionCalculator,
             dragIndexCalculator: this.#dragIndexCalculator,
             elementClone: this.#elementClone,
+            overlayContainer: this.#overlayContainer,
             ngZone: this.#ngZone,
             envInjector: this.#envInjector,
             callbacks: {
@@ -4334,8 +4581,10 @@ class DraggableDirective {
             callbacks: {
                 onDragStart: (position) => this.#startDrag(position),
                 onDragMove: (position) => {
+                    // Record raw position synchronously (needed for autoscroll cursor override)
+                    // then queue into the scheduler's RAF loop for coalesced frame-rate processing.
                     this.#lastRawPosition = position;
-                    this.#updateDrag(position);
+                    this.#scheduler.queueCursorUpdate(position);
                 },
                 onDragEnd: (cancelled) => this.#endDrag(cancelled),
                 onPendingChange: (pending) => this.#setPending(pending),
@@ -4435,8 +4684,12 @@ class DraggableDirective {
             x: startPos.x - rect.left,
             y: startPos.y - rect.top,
         };
-        // Clone element BEFORE updating drag state (which triggers display:none via host binding)
-        const clonedElement = this.#elementClone.cloneElement(element);
+        // Clone element BEFORE updating drag state (which triggers display:none via host binding).
+        // Template-first: skip the costly getComputedStyle deep-walk when a template-based
+        // preview is mounted, since that clone would never be rendered.
+        const clonedElement = this.#overlayContainer.hasTemplatePreview()
+            ? undefined
+            : this.#elementClone.cloneElement(element);
         const parentDroppableId = this.#getParentDroppableId();
         // Find droppable and calculate initial placeholder position
         // This fixes the UI glitch by ensuring placeholder is set before the element is hidden
@@ -4446,6 +4699,9 @@ class DraggableDirective {
             this.#pointerHandler.cleanup();
             return;
         }
+        // Snapshot droppable rects for this drag session so subsequent hit-testing is
+        // pure geometry (no elementFromPoint layout flush per pointermove).
+        this.#positionCalculator.beginDragSession(groupName);
         const droppableElement = this.#positionCalculator.findDroppableAtPoint(position.x, position.y, element, groupName);
         // Cache constraint flag and element for clamping during drag
         this.#constrainToContainer =
@@ -4487,7 +4743,14 @@ class DraggableDirective {
             width: rect.width,
             data: this.vdndDraggableData(),
         }, position, grabOffset, lockAxis, activeDroppableId, initialPlaceholderId, initialPlaceholderIndex, sourceIndex, undefined, lockAxis ? startPos : undefined);
-        // Start auto-scroll monitoring with a callback to recalculate placeholder
+        // Start the scheduler RAF loop (drives pointer-move updates + autoscroll participant).
+        // onTick is called each frame: when cursor is dirty, run full #updateDrag.
+        this.#scheduler.start((cursor, cursorDirty) => {
+            if (cursorDirty && cursor && this.isDragging()) {
+                this.#updateDrag(cursor);
+            }
+        });
+        // Start auto-scroll monitoring — registers as a scheduler participant.
         this.#autoScroll.startMonitoring(() => this.#recalculatePlaceholder());
         // Emit drag start event
         this.dragStart.emit({
@@ -4554,13 +4817,42 @@ class DraggableDirective {
     }
     /**
      * Recalculate placeholder position (called during auto-scroll).
+     *
+     * Scroll-only fast path: the cursor has not moved — only `scrollTop` changed.
+     * When the active droppable is already known, skip hit-testing entirely and
+     * recalculate only the placeholder index within that droppable. This avoids the
+     * `findDroppableAtPoint` geometry scan + the `invalidateDroppableRects` DOM round-trip
+     * on every autoscroll frame while still recomputing the correct insertion index.
+     *
+     * Falls back to the full `#updateDrag` pipeline when no droppable is active (e.g.
+     * cursor drifted outside all droppables before the scroll tick fired).
      */
     #recalculatePlaceholder() {
         const cursorPosition = this.#dragState.cursorPosition();
         if (!cursorPosition || !this.isDragging()) {
             return;
         }
-        // Recalculate placeholder based on current scroll position
+        const activeDroppableId = this.#dragState.activeDroppableId();
+        if (activeDroppableId) {
+            const droppableElement = this.#positionCalculator.getDroppableById(activeDroppableId);
+            if (droppableElement) {
+                const draggedItemHeight = this.#dragState.draggedItem()?.height ?? 50;
+                const indexResult = this.#dragIndexCalculator.calculatePlaceholderIndex({
+                    droppableElement,
+                    position: cursorPosition,
+                    previousPosition: cursorPosition,
+                    grabOffset: this.#dragState.grabOffset(),
+                    draggedItemHeight,
+                    sourceDroppableId: this.#dragState.sourceDroppableId(),
+                    sourceIndex: this.#dragState.sourceIndex(),
+                });
+                this.#dragState.updateScrollOnlyPlaceholder(indexResult.placeholderId, indexResult.index);
+                return;
+            }
+        }
+        // Fallback: full recalculation when no active droppable is known.
+        // Mark rects dirty first since autoscroll moved the container before the scroll event fires.
+        this.#positionCalculator.invalidateDroppableRects();
         this.#updateDrag(cursorPosition);
     }
     /**
@@ -4667,9 +4959,11 @@ class DraggableDirective {
      * End the drag operation.
      */
     #endDrag(cancelled) {
-        // No ngZone.run() needed - signals work outside zone and effects react automatically
-        // Stop auto-scroll monitoring
+        // Stop the scheduler RAF loop first, then remove the autoscroll participant.
+        this.#scheduler.stop();
         this.#autoScroll.stopMonitoring();
+        // Tear down the geometric hit-testing snapshot + its viewport listeners
+        this.#positionCalculator.endDragSession();
         // Clear droppable metadata cache from this drag session
         this.#dragIndexCalculator.clearCache();
         // Reset cached constraint state
@@ -5272,18 +5566,20 @@ class VirtualForDirective {
         const { items, start, end, showPlaceholder, placeholderIndex, shouldKeepDragged, draggedIndex, } = params;
         const trackByFn = this.vdndVirtualForTrackBy();
         const itemsToRender = [];
+        // Track placeholder insertion with a flag instead of re-scanning itemsToRender
+        // with `.some()` on every iteration (which made the build loop O(n²)).
+        let placeholderInserted = false;
         // Build render list for visible range
         for (let i = start; i <= end && i < items.length; i++) {
             // Insert placeholder before item at placeholderIndex
-            if (showPlaceholder &&
-                placeholderIndex === i &&
-                !itemsToRender.some((r) => r.type === 'placeholder')) {
+            if (showPlaceholder && placeholderIndex === i && !placeholderInserted) {
                 itemsToRender.push({
                     type: 'placeholder',
                     key: '__placeholder__',
                     context: null,
                     visualIndex: placeholderIndex,
                 });
+                placeholderInserted = true;
             }
             const item = items[i];
             itemsToRender.push({
@@ -5300,9 +5596,7 @@ class VirtualForDirective {
             });
         }
         // Add placeholder at end if needed
-        if (showPlaceholder &&
-            placeholderIndex >= items.length &&
-            !itemsToRender.some((r) => r.type === 'placeholder')) {
+        if (showPlaceholder && placeholderIndex >= items.length && !placeholderInserted) {
             itemsToRender.push({
                 type: 'placeholder',
                 key: '__placeholder__',
@@ -5472,14 +5766,11 @@ class VirtualForDirective {
         const container = this.#viewContainer.element.nativeElement.parentElement;
         if (!container)
             return;
-        // Find children excluding spacers and placeholder itself
-        const children = Array.from(container.children).filter((el) => {
-            const element = el;
-            return (!element.classList.contains('vdnd-drag-placeholder') &&
-                !element.classList.contains('vdnd-virtual-for-spacer') &&
-                !element.classList.contains('vdnd-content-spacer'));
-        });
-        const insertBeforeEl = children[placeholderDomPosition] ?? null;
+        // The placeholder goes immediately before the item view at placeholderDomPosition
+        // (the reconcile pass counts item views only, so this index maps directly to a
+        // ViewContainerRef view). Reading the reference node from that view avoids
+        // re-querying and filtering container.children on every placeholder move.
+        const insertBeforeEl = this.#getViewReferenceNode(placeholderDomPosition);
         if (!this.#placeholderInDom) {
             // First insertion
             if (insertBeforeEl) {
@@ -5503,6 +5794,26 @@ class VirtualForDirective {
             }
         }
     }
+    /**
+     * Resolve the DOM node the placeholder should be inserted before, given the
+     * item-view index produced by the reconcile pass. Returns null when the index
+     * is past the last view (placeholder belongs at the end → append).
+     */
+    #getViewReferenceNode(viewIndex) {
+        if (viewIndex < 0 || viewIndex >= this.#viewContainer.length) {
+            return null;
+        }
+        const view = this.#viewContainer.get(viewIndex);
+        if (!view) {
+            return null;
+        }
+        for (const node of view.rootNodes) {
+            if (node instanceof HTMLElement) {
+                return node;
+            }
+        }
+        return null;
+    }
     /**
      * Trim the view pool to prevent memory bloat, keeping a reasonable buffer.
      */