ngx-virtual-dnd 3.2.0-alpha.0 → 3.2.0-alpha.2

package/fesm2022/ngx-virtual-dnd.mjs

@@ -456,12 +456,17 @@ const VDND_VIRTUAL_VIEWPORT = new InjectionToken('VDND_VIRTUAL_VIEWPORT');
 const DEFAULT_SHIFT_DURATION = 200;
 /** Default shift animation easing used when the config omits `shiftEasing`. */
 const DEFAULT_SHIFT_EASING = 'cubic-bezier(0.2, 0, 0, 1)';
+/** Default drop animation duration (ms) used when the config omits `dropDuration`. */
+const DEFAULT_DROP_DURATION = 200;
+/** Default drop animation easing used when the config omits `dropEasing`. */
+const DEFAULT_DROP_EASING = 'cubic-bezier(0.2, 0, 0, 1)';
 /**
  * Opt-in animation configuration. When provided, items displaced by the placeholder
- * slide into their new position instead of jumping. Resolved through the element
+ * slide into their new position instead of jumping, and on drop the drag preview glides
+ * into the item's final position. Resolved through the element
  * injector, so it can be provided app-wide or per component subtree.
  *
- * The animation is skipped when the user prefers reduced motion. Values are read each
+ * Animations are skipped when the user prefers reduced motion. Values are read each
  * time an animation starts, so getters can toggle the animation at runtime.
  *
  * @example
@@ -1235,9 +1240,10 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.0.6", ngImpor
  *      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.
+ *   2. Main compute phase (COMPUTE+WRITE): onTick is called every frame with the
+ *      latest cursor and a `cursorDirty` flag. Callers skip their hit-test when
+ *      the flag is false, 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
@@ -1882,6 +1888,8 @@ class KeyboardDragService {
     #dragState = inject(DragStateService);
     /** Total item count for the current droppable (set by droppable on keyboard drag start) */
     #totalItemCount = signal(0, ...(ngDevMode ? [{ debugName: "#totalItemCount" }] : []));
+    /** Per-droppable callbacks that scroll the placeholder into view (see `registerRevealer`) */
+    #revealers = new Map();
     /** Whether a keyboard drag is currently active */
     isActive = computed(() => this.#dragState.isKeyboardDrag() && this.#dragState.isDragging(), ...(ngDevMode ? [{ debugName: "isActive" }] : []));
     /** Current target index during keyboard navigation */
@@ -1917,9 +1925,10 @@ class KeyboardDragService {
         if (!this.isActive()) {
             return targetIndex;
         }
-        const totalItems = this.#totalItemCount();
-        const clampedIndex = Math.max(0, Math.min(targetIndex, totalItems));
+        const maxIndex = this.#maxTargetIndex(this.activeDroppableId());
+        const clampedIndex = Math.max(0, Math.min(targetIndex, maxIndex));
         this.#dragState.setKeyboardTargetIndex(clampedIndex);
+        this.#revealActivePlaceholder();
         return clampedIndex;
     }
     /**
@@ -1947,8 +1956,26 @@ class KeyboardDragService {
             return;
         }
         this.#totalItemCount.set(totalItemCount);
-        const clampedIndex = Math.max(0, Math.min(targetIndex, totalItemCount));
+        const clampedIndex = Math.max(0, Math.min(targetIndex, this.#maxTargetIndex(droppableId)));
         this.#dragState.setKeyboardActiveDroppable(droppableId, clampedIndex);
+        this.#revealActivePlaceholder();
+    }
+    /**
+     * Register the callback that scrolls a droppable's placeholder into view. It runs
+     * synchronously on every keyboard move into or within that droppable, so a drop that
+     * follows before the next render still lands inside the rendered range.
+     */
+    registerRevealer(droppableId, reveal) {
+        this.#revealers.set(droppableId, reveal);
+    }
+    /**
+     * Unregister a droppable's reveal callback. Ignored if another callback has since been
+     * registered under the same ID.
+     */
+    unregisterRevealer(droppableId, reveal) {
+        if (this.#revealers.get(droppableId) === reveal) {
+            this.#revealers.delete(droppableId);
+        }
     }
     /**
      * Complete the keyboard drag (Space or Enter to drop).
@@ -1974,6 +2001,22 @@ class KeyboardDragService {
     setTotalItemCount(count) {
         this.#totalItemCount.set(count);
     }
+    #revealActivePlaceholder() {
+        const droppableId = this.activeDroppableId();
+        if (droppableId !== null) {
+            this.#revealers.get(droppableId)?.();
+        }
+    }
+    /**
+     * Last valid target index in the given droppable. Targets use the drop convention (the item's
+     * final index after it leaves its source), so the source list ends at `totalItemCount - 1`,
+     * while any other list can be appended to at `totalItemCount`.
+     */
+    #maxTargetIndex(droppableId) {
+        const totalItems = this.#totalItemCount();
+        const isSourceList = droppableId !== null && droppableId === this.#dragState.sourceDroppableId();
+        return isSourceList ? Math.max(0, totalItems - 1) : totalItems;
+    }
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.0.6", ngImport: i0, type: KeyboardDragService, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
     static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.0.6", ngImport: i0, type: KeyboardDragService, providedIn: 'root' });
 }
@@ -2451,7 +2494,7 @@ const MIN_SHIFT_PX = 0.5;
  * FLIP animator for items displaced by the drag placeholder.
  *
  * Call `beforeUpdate()` before the DOM reflects a new drag/placeholder state. When the
- * placeholder moved, it snapshots every rendered element's visual position, then after
+ * placeholder moved (or the drag ended), it snapshots every rendered element's visual position, then after
  * the render measures again and plays a compositor-only `transform` animation from the
  * old position to the new one.
  *
@@ -2488,11 +2531,19 @@ class ShiftAnimator {
         this.#wasDragging = isDragging;
         this.#lastPlaceholderIndex = placeholderIndex;
         if (!isDragging) {
-            // Drop/cancel: the list re-renders with the committed order, so snap everything.
-            this.#snapshot = null;
-            if (wasDragging) {
+            // Drop/cancel: one last pass slides rows from their drag layout into the committed
+            // order. After a drop the rows usually already sit in their final slots, so in-flight
+            // slides simply finish; after a cancel the displaced rows slide back.
+            // A pending snapshot already holds this tick's "before".
+            if (!wasDragging || this.#snapshot) {
+                return;
+            }
+            if (!this.#isEnabled()) {
                 this.cancelAll();
+                return;
             }
+            this.#snapshot = this.#measure();
+            afterNextRender(() => this.#play(), { injector: this.#injector });
             return;
         }
         // Drag start renders the placeholder in the hidden item's slot — nothing moves.
@@ -2562,7 +2613,7 @@ class ShiftAnimator {
     #play() {
         const first = this.#snapshot;
         this.#snapshot = null;
-        if (!first || !this.#wasDragging)
+        if (!first)
             return;
         const last = this.#measure();
         const stale = [];
@@ -2662,6 +2713,7 @@ class VirtualScrollContainerComponent {
     #elementRef = inject((ElementRef));
     #autoScrollService = inject(AutoScrollService);
     #dragIndexCalculator = inject(DragIndexCalculatorService);
+    #keyboardDrag = inject(KeyboardDragService);
     #ngZone = inject(NgZone);
     #injector = inject(Injector);
     /** Cleanup function for scroll listener */
@@ -2979,43 +3031,19 @@ class VirtualScrollContainerComponent {
                 untracked(() => animator.beforeUpdate(isDragging, placeholderIndex));
             });
         }
-        // Keyboard drag autoscroll: scroll to keep target index visible
-        effect(() => {
-            // Only apply when this droppable is active during keyboard drag
-            if (!this.#dragState.isKeyboardDrag())
-                return;
-            const activeDroppable = this.#dragState.activeDroppableId();
-            if (activeDroppable !== this.droppableId())
-                return;
-            const targetIndex = this.#dragState.keyboardTargetIndex();
-            if (targetIndex === null)
-                return;
-            const strategy = this.#strategy();
-            strategy.version();
-            const height = this.effectiveHeight();
-            if (height <= 0)
+        // Keyboard drag autoscroll: keep the placeholder visible. Arrow keys call
+        // #revealPlaceholder synchronously (through KeyboardDragService) so a drop right after a
+        // move never lands outside the rendered range; this effect re-runs it when item
+        // measurements or the viewport height change during the drag.
+        effect((onCleanup) => {
+            const droppableId = this.droppableId();
+            if (!droppableId)
                 return;
-            const element = this.#elementRef.nativeElement;
-            const currentScrollTop = element.scrollTop;
-            // Calculate target item position using strategy
-            const targetTop = strategy.getOffsetForIndex(targetIndex);
-            const targetBottom = targetTop + strategy.getItemHeight(targetIndex);
-            // Calculate visible range
-            const viewportTop = currentScrollTop;
-            const viewportBottom = currentScrollTop + height;
-            // Check if target is fully visible
-            if (targetTop < viewportTop) {
-                // Target is above viewport - scroll up
-                element.scrollTop = targetTop;
-                this.#scrollTop.set(targetTop);
-            }
-            else if (targetBottom > viewportBottom) {
-                // Target is below viewport - scroll down
-                const newScrollTop = targetBottom - height;
-                element.scrollTop = newScrollTop;
-                this.#scrollTop.set(newScrollTop);
-            }
+            const reveal = () => untracked(() => this.#revealPlaceholder());
+            this.#keyboardDrag.registerRevealer(droppableId, reveal);
+            onCleanup(() => this.#keyboardDrag.unregisterRevealer(droppableId, reveal));
         });
+        effect(() => this.#revealPlaceholder());
         // Preserve scroll position when drag ends at bottom of list.
         // Safety net: totalHeight no longer shrinks during drag (getTotalHeight
         // ignores exclusion), but this logic remains as harmless protection
@@ -3096,6 +3124,50 @@ class VirtualScrollContainerComponent {
             this.#observeRenderedItems();
         }
     }
+    /**
+     * Scroll so the placeholder is fully visible during a keyboard drag into this list.
+     * Reads only signals and strategy offsets, so it works before the placeholder renders.
+     */
+    #revealPlaceholder() {
+        // Only apply when this droppable is active during keyboard drag
+        if (!this.#dragState.isKeyboardDrag())
+            return;
+        const activeDroppable = this.#dragState.activeDroppableId();
+        if (activeDroppable !== this.droppableId())
+            return;
+        // The placeholder renders before the item at placeholderIndex. Below the source in the
+        // same list that is keyboardTargetIndex + 1: the dragged item's slot is excluded.
+        if (this.#dragState.keyboardTargetIndex() === null)
+            return;
+        const placeholderIndex = this.placeholderIndex();
+        if (placeholderIndex < 0)
+            return;
+        const strategy = this.#strategy();
+        strategy.version();
+        const height = this.effectiveHeight();
+        if (height <= 0)
+            return;
+        const element = this.#elementRef.nativeElement;
+        const currentScrollTop = element.scrollTop;
+        // Calculate placeholder position using strategy
+        const targetTop = strategy.getOffsetForIndex(placeholderIndex);
+        const targetBottom = targetTop + this.placeholderHeight();
+        // Calculate visible range
+        const viewportTop = currentScrollTop;
+        const viewportBottom = currentScrollTop + height;
+        // Check if target is fully visible
+        if (targetTop < viewportTop) {
+            // Target is above viewport - scroll up
+            element.scrollTop = targetTop;
+            this.#scrollTop.set(targetTop);
+        }
+        else if (targetBottom > viewportBottom) {
+            // Target is below viewport - scroll down
+            const newScrollTop = targetBottom - height;
+            element.scrollTop = newScrollTop;
+            this.#scrollTop.set(newScrollTop);
+        }
+    }
     ngOnDestroy() {
         this.#scrollCleanup?.();
         this.#resizeCleanup?.();
@@ -3294,6 +3366,124 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.0.6", ngImpor
   `, styles: [":host{display:block;overflow:auto;position:relative;overflow-anchor:none}.vdnd-virtual-scroll-spacer{position:absolute;top:0;left:0;width:1px;visibility:hidden;pointer-events:none}.vdnd-virtual-scroll-content-wrapper{position:absolute;top:0;left:0;right:0;will-change:transform}\n"] }]
         }], ctorParameters: () => [], propDecorators: { itemTemplate: [{ type: i0.Input, args: [{ isSignal: true, alias: "itemTemplate", required: true }] }], scrollContainerId: [{ type: i0.Input, args: [{ isSignal: true, alias: "scrollContainerId", required: false }] }], autoScrollEnabled: [{ type: i0.Input, args: [{ isSignal: true, alias: "autoScrollEnabled", required: false }] }], autoScrollConfig: [{ type: i0.Input, args: [{ isSignal: true, alias: "autoScrollConfig", required: false }] }], items: [{ type: i0.Input, args: [{ isSignal: true, alias: "items", required: true }] }], itemHeight: [{ type: i0.Input, args: [{ isSignal: true, alias: "itemHeight", required: true }] }], dynamicItemHeight: [{ type: i0.Input, args: [{ isSignal: true, alias: "dynamicItemHeight", required: false }] }], containerHeight: [{ type: i0.Input, args: [{ isSignal: true, alias: "containerHeight", required: false }] }], overscan: [{ type: i0.Input, args: [{ isSignal: true, alias: "overscan", required: false }] }], stickyItemIds: [{ type: i0.Input, args: [{ isSignal: true, alias: "stickyItemIds", required: false }] }], itemIdFn: [{ type: i0.Input, args: [{ isSignal: true, alias: "itemIdFn", required: true }] }], trackByFn: [{ type: i0.Input, args: [{ isSignal: true, alias: "trackByFn", required: false }] }], droppableId: [{ type: i0.Input, args: [{ isSignal: true, alias: "droppableId", required: false }] }], autoStickyDraggedItem: [{ type: i0.Input, args: [{ isSignal: true, alias: "autoStickyDraggedItem", required: false }] }] } });
 
+/**
+ * Plays the drop ("settle") animation: the drag preview glides from where it was released
+ * into the dropped item's final position, while that item stays invisible underneath.
+ *
+ * Purely visual. The drag state and the drop events are already final when it starts, so it
+ * never delays or changes a drop. Without a target (the item is not rendered, or scrolled out
+ * of view) the ghost fades out where it was released.
+ * @internal
+ */
+class DropAnimator {
+    #config;
+    #ghostAnimation = null;
+    #hideAnimation = null;
+    constructor(config) {
+        this.#config = config;
+    }
+    /** Whether a drop animation would play right now (duration, WAAPI, reduced motion). */
+    isEnabled() {
+        if (this.#duration() <= 0)
+            return false;
+        if (typeof Element === 'undefined' || typeof Element.prototype.animate !== 'function') {
+            return false;
+        }
+        if (typeof matchMedia !== 'function')
+            return true;
+        return !matchMedia('(prefers-reduced-motion: reduce)').matches;
+    }
+    /**
+     * Animate `ghost` onto `target` (or fade it out without one), then call `onDone`.
+     * `onDone` is not called when the animation is cancelled.
+     */
+    play(ghost, target, onDone) {
+        this.cancel();
+        const timing = {
+            duration: this.#duration(),
+            easing: this.#config.dropEasing ?? DEFAULT_DROP_EASING,
+            fill: 'forwards',
+        };
+        let ghostAnimation;
+        if (target) {
+            const from = ghost.getBoundingClientRect();
+            const dx = target.rect.left - from.left;
+            const dy = target.rect.top - from.top;
+            // Travel on top of the preview's own position transform (width/height must not be
+            // composited, so the base transform is repeated instead of using composite: 'add').
+            const base = ghost.style.transform;
+            ghostAnimation = ghost.animate([
+                {
+                    transform: `${base} translate(0px, 0px)`,
+                    width: `${from.width}px`,
+                    height: `${from.height}px`,
+                },
+                {
+                    transform: `${base} translate(${dx}px, ${dy}px)`,
+                    width: `${target.rect.width}px`,
+                    height: `${target.rect.height}px`,
+                },
+            ], timing);
+            // Keep the real item invisible until the ghost lands on it, so it is never seen twice.
+            this.#hideAnimation = target.element.animate([{ opacity: 0 }, { opacity: 0 }], {
+                duration: timing.duration,
+            });
+        }
+        else {
+            ghostAnimation = ghost.animate([{ opacity: 1 }, { opacity: 0 }], timing);
+        }
+        this.#ghostAnimation = ghostAnimation;
+        ghostAnimation.onfinish = () => {
+            if (this.#ghostAnimation !== ghostAnimation)
+                return;
+            this.cancel();
+            onDone();
+        };
+    }
+    /** Stop the running animation immediately and reveal the real item. */
+    cancel() {
+        const ghostAnimation = this.#ghostAnimation;
+        const hideAnimation = this.#hideAnimation;
+        this.#ghostAnimation = null;
+        this.#hideAnimation = null;
+        ghostAnimation?.cancel();
+        hideAnimation?.cancel();
+    }
+    #duration() {
+        return this.#config.dropDuration ?? DEFAULT_DROP_DURATION;
+    }
+}
+/**
+ * Find the rendered element of a dropped item: first in the droppable it was dropped on, then
+ * in the one it came from (a drop the consumer rejected or has not committed yet leaves it
+ * there). Returns null when it is not rendered, or rendered but scrolled out of its list's view.
+ */
+function findDropTarget(draggableId, droppableIds) {
+    if (typeof document === 'undefined')
+        return null;
+    for (const droppableId of droppableIds) {
+        if (!droppableId)
+            continue;
+        const droppable = queryByAttribute(document, 'data-droppable-id', droppableId);
+        const element = droppable
+            ? queryByAttribute(droppable, 'data-draggable-id', draggableId)
+            : null;
+        if (!droppable || !element)
+            continue;
+        const rect = element.getBoundingClientRect();
+        // Hidden, or virtualized/scrolled out of the list's visible box: nowhere to land.
+        if (rect.width === 0 && rect.height === 0)
+            return null;
+        const bounds = droppable.getBoundingClientRect();
+        const visible = rect.bottom > bounds.top &&
+            rect.top < bounds.bottom &&
+            rect.right > bounds.left &&
+            rect.left < bounds.right;
+        return visible ? { element, rect } : null;
+    }
+    return null;
+}
+
 /**
  * Renders a preview of the dragged item that follows the cursor.
  *
@@ -3301,6 +3491,9 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.0.6", ngImpor
  * so it works correctly even inside ancestors with CSS `transform` (e.g. Ionic pages).
  * It can be placed anywhere in the component tree.
  *
+ * When `VDND_ANIMATION_CONFIG` is provided, the preview stays up briefly after a drop or
+ * cancel and glides into the item's final position.
+ *
  * @example
  * ```html
  * <vdnd-drag-preview>
@@ -3314,12 +3507,24 @@ class DragPreviewComponent {
     dragState = inject(DragStateService);
     #overlayContainer = inject(OverlayContainerService);
     #elementRef = inject((ElementRef));
+    #injector = inject(Injector);
+    #dropAnimator = this.#createDropAnimator();
     /** Optional custom template for the preview */
     previewTemplate = input(...(ngDevMode ? [undefined, { debugName: "previewTemplate" }] : []));
     /** Offset from cursor to preview (to avoid cursor being on top of preview) */
     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" }] : []));
+    /** The rendered preview box (cannot use ES private with viewChild) */
+    previewElement = viewChild('preview', ...(ngDevMode ? [{ debugName: "previewElement" }] : []));
+    /** Set while the preview animates into the drop position after the drag ended */
+    #settling = signal(null, ...(ngDevMode ? [{ debugName: "#settling" }] : []));
+    /** Whether the drag was still active on the last state change (detects drag end) */
+    #wasDragging = false;
+    /** Whether the preview is playing the drop animation */
+    isSettling = computed(() => this.#settling() !== null, ...(ngDevMode ? [{ debugName: "isSettling" }] : []));
+    /** The item shown: the live dragged item, or the dropped one while it settles */
+    displayedItem = computed(() => this.dragState.draggedItem() ?? this.#settling()?.item ?? null, ...(ngDevMode ? [{ debugName: "displayedItem" }] : []));
     /** 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) */
@@ -3327,7 +3532,7 @@ class DragPreviewComponent {
         if (this.previewTemplate()) {
             return null; // Custom template takes precedence
         }
-        return this.dragState.draggedItem()?.clonedElement ?? null;
+        return this.displayedItem()?.clonedElement ?? null;
     }, ...(ngDevMode ? [{ debugName: "clonedElement" }] : []));
     constructor() {
         // Teleport host element into the body-level overlay container after first render.
@@ -3365,8 +3570,24 @@ class DragPreviewComponent {
                 container.appendChild(clone);
             }
         });
+        // Drop animation: when a drag ends, keep the preview up and glide it into place.
+        // A new drag cuts any settle short.
+        effect(() => {
+            const isDragging = this.dragState.isDragging();
+            untracked(() => {
+                const wasDragging = this.#wasDragging;
+                this.#wasDragging = isDragging;
+                if (isDragging) {
+                    this.#stopSettling();
+                }
+                else if (wasDragging) {
+                    this.#startSettling();
+                }
+            });
+        });
     }
     ngOnDestroy() {
+        this.#dropAnimator?.cancel();
         if (this.#templateRegistered) {
             this.#overlayContainer.setTemplatePreviewActive(false);
             this.#templateRegistered = false;
@@ -3375,20 +3596,30 @@ class DragPreviewComponent {
     }
     /** Whether the preview is visible */
     isVisible = computed(() => {
-        return this.dragState.isDragging() && this.dragState.cursorPosition() !== null;
+        return ((this.dragState.isDragging() && this.dragState.cursorPosition() !== null) || this.isSettling());
     }, ...(ngDevMode ? [{ debugName: "isVisible" }] : []));
     /** Position of the preview */
     position = computed(() => {
-        const cursor = this.dragState.cursorPosition();
-        const grabOffset = this.dragState.grabOffset();
-        const fallbackOffset = this.cursorOffset();
-        const initialPosition = this.dragState.initialPosition();
-        const lockAxis = this.dragState.lockAxis();
+        const settling = this.#settling();
+        if (settling && !this.dragState.isDragging()) {
+            return settling.position;
+        }
+        return this.#positionFor({
+            cursorPosition: this.dragState.cursorPosition(),
+            grabOffset: this.dragState.grabOffset(),
+            initialPosition: this.dragState.initialPosition(),
+            lockAxis: this.dragState.lockAxis(),
+        });
+    }, ...(ngDevMode ? [{ debugName: "position" }] : []));
+    #positionFor(state) {
+        const cursor = state.cursorPosition;
+        const initialPosition = state.initialPosition;
+        const lockAxis = state.lockAxis;
         if (!cursor) {
             return { x: 0, y: 0 };
         }
         // Use grab offset if available (preserves grab position), otherwise fall back to cursorOffset input
-        const offset = grabOffset ?? fallbackOffset;
+        const offset = state.grabOffset ?? this.cursorOffset();
         let x = cursor.x - offset.x;
         let y = cursor.y - offset.y;
         // Apply axis locking if configured
@@ -3403,7 +3634,7 @@ class DragPreviewComponent {
             }
         }
         return { x, y };
-    }, ...(ngDevMode ? [{ debugName: "position" }] : []));
+    }
     /** Transform-based positioning for better performance (avoid layout from left/top). */
     transform = computed(() => {
         const { x, y } = this.position();
@@ -3411,7 +3642,7 @@ class DragPreviewComponent {
     }, ...(ngDevMode ? [{ debugName: "transform" }] : []));
     /** Dimensions of the preview */
     dimensions = computed(() => {
-        const item = this.dragState.draggedItem();
+        const item = this.displayedItem();
         if (!item) {
             return { width: 100, height: 50 };
         }
@@ -3422,19 +3653,65 @@ class DragPreviewComponent {
     }, ...(ngDevMode ? [{ debugName: "dimensions" }] : []));
     /** Template context */
     templateContext = computed(() => {
-        const item = this.dragState.draggedItem();
+        const item = this.displayedItem();
         return {
             $implicit: (item?.data ?? null),
             draggableId: item?.draggableId ?? '',
             droppableId: item?.droppableId ?? '',
         };
     }, ...(ngDevMode ? [{ debugName: "templateContext" }] : []));
+    #createDropAnimator() {
+        const config = inject(VDND_ANIMATION_CONFIG, { optional: true });
+        return config ? new DropAnimator(config) : null;
+    }
+    /**
+     * Keep the ended drag's preview on screen, then (once the consumer's drop handler has
+     * re-rendered the lists) animate it onto the item's final position.
+     */
+    #startSettling() {
+        const ended = this.dragState.endedDragState();
+        if (!this.#dropAnimator?.isEnabled() || !ended?.draggedItem || !ended.cursorPosition) {
+            return;
+        }
+        const settling = {
+            item: ended.draggedItem,
+            position: this.#positionFor(ended),
+        };
+        this.#settling.set(settling);
+        // A normal drop lands in the target list; a cancel, a rejected drop or one the consumer
+        // has not committed yet leaves the item in its source list.
+        const droppableIds = this.dragState.wasCancelled()
+            ? [ended.sourceDroppableId]
+            : [ended.activeDroppableId, ended.sourceDroppableId];
+        afterNextRender(() => {
+            if (this.#settling() !== settling) {
+                return;
+            }
+            const ghost = this.previewElement()?.nativeElement;
+            if (!ghost || !this.#dropAnimator) {
+                this.#settling.set(null);
+                return;
+            }
+            const target = findDropTarget(settling.item.draggableId, droppableIds);
+            this.#dropAnimator.play(ghost, target, () => {
+                if (this.#settling() === settling) {
+                    this.#settling.set(null);
+                }
+            });
+        }, { injector: this.#injector });
+    }
+    #stopSettling() {
+        this.#dropAnimator?.cancel();
+        this.#settling.set(null);
+    }
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.0.6", ngImport: i0, type: DragPreviewComponent, deps: [], target: i0.ɵɵFactoryTarget.Component });
-    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "21.0.6", type: DragPreviewComponent, isStandalone: true, selector: "vdnd-drag-preview", inputs: { previewTemplate: { classPropertyName: "previewTemplate", publicName: "previewTemplate", isSignal: true, isRequired: false, transformFunction: null }, cursorOffset: { classPropertyName: "cursorOffset", publicName: "cursorOffset", isSignal: true, isRequired: false, transformFunction: null } }, viewQueries: [{ propertyName: "cloneContainer", first: true, predicate: ["cloneContainer"], descendants: true, isSignal: true }], ngImport: i0, template: `
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "21.0.6", type: DragPreviewComponent, isStandalone: true, selector: "vdnd-drag-preview", inputs: { previewTemplate: { classPropertyName: "previewTemplate", publicName: "previewTemplate", isSignal: true, isRequired: false, transformFunction: null }, cursorOffset: { classPropertyName: "cursorOffset", publicName: "cursorOffset", isSignal: true, isRequired: false, transformFunction: null } }, viewQueries: [{ propertyName: "cloneContainer", first: true, predicate: ["cloneContainer"], descendants: true, isSignal: true }, { propertyName: "previewElement", first: true, predicate: ["preview"], descendants: true, isSignal: true }], ngImport: i0, template: `
     @if (isVisible()) {
       <div
+        #preview
         class="vdnd-drag-preview"
-        data-testid="vdnd-drag-preview"
+        [class.vdnd-drag-preview-dropping]="isSettling()"
+        [attr.data-testid]="isSettling() ? 'vdnd-drag-preview-dropping' : 'vdnd-drag-preview'"
         [style.transform]="transform()"
         [style.width.px]="dimensions().width"
         [style.height.px]="dimensions().height"
@@ -3446,7 +3723,7 @@ class DragPreviewComponent {
           <div class="vdnd-drag-preview-clone" #cloneContainer></div>
         } @else {
           <div class="vdnd-drag-preview-default">
-            {{ dragState.draggedItem()?.draggableId }}
+            {{ displayedItem()?.draggableId }}
           </div>
         }
       </div>
@@ -3458,8 +3735,10 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.0.6", ngImpor
             args: [{ selector: 'vdnd-drag-preview', changeDetection: ChangeDetectionStrategy.OnPush, imports: [NgTemplateOutlet], template: `
     @if (isVisible()) {
       <div
+        #preview
         class="vdnd-drag-preview"
-        data-testid="vdnd-drag-preview"
+        [class.vdnd-drag-preview-dropping]="isSettling()"
+        [attr.data-testid]="isSettling() ? 'vdnd-drag-preview-dropping' : 'vdnd-drag-preview'"
         [style.transform]="transform()"
         [style.width.px]="dimensions().width"
         [style.height.px]="dimensions().height"
@@ -3471,13 +3750,13 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.0.6", ngImpor
           <div class="vdnd-drag-preview-clone" #cloneContainer></div>
         } @else {
           <div class="vdnd-drag-preview-default">
-            {{ dragState.draggedItem()?.draggableId }}
+            {{ displayedItem()?.draggableId }}
           </div>
         }
       </div>
     }
   `, styles: [".vdnd-drag-preview{box-sizing:border-box;position:fixed;left:0;top:0;will-change:transform;pointer-events:none;z-index:1000}.vdnd-drag-preview-clone{width:100%;height:100%;overflow:hidden}\n"] }]
-        }], ctorParameters: () => [], propDecorators: { previewTemplate: [{ type: i0.Input, args: [{ isSignal: true, alias: "previewTemplate", required: false }] }], cursorOffset: [{ type: i0.Input, args: [{ isSignal: true, alias: "cursorOffset", required: false }] }], cloneContainer: [{ type: i0.ViewChild, args: ['cloneContainer', { isSignal: true }] }] } });
+        }], ctorParameters: () => [], propDecorators: { previewTemplate: [{ type: i0.Input, args: [{ isSignal: true, alias: "previewTemplate", required: false }] }], cursorOffset: [{ type: i0.Input, args: [{ isSignal: true, alias: "cursorOffset", required: false }] }], cloneContainer: [{ type: i0.ViewChild, args: ['cloneContainer', { isSignal: true }] }], previewElement: [{ type: i0.ViewChild, args: ['preview', { isSignal: true }] }] } });
 
 /**
  * A placeholder component that indicates where a dropped item will be inserted.
@@ -4754,9 +5033,13 @@ class KeyboardDragHandler {
             sourceIndex,
             destinationIndex,
         });
+        // The item stays in its source list when there is no valid target
+        const fallbackDroppableId = hasValidTarget
+            ? activeDroppableId
+            : this.#deps.dragState.sourceDroppableId();
         this.#deps.keyboardDrag.completeKeyboardDrag();
         // Restore focus to the moved element after state updates
-        this.#restoreFocus(ctx.draggableId);
+        this.#restoreFocus(ctx.draggableId, fallbackDroppableId);
     }
     /**
      * Cancel a keyboard drag operation.
@@ -4764,6 +5047,8 @@ class KeyboardDragHandler {
     cancel() {
         const ctx = this.#deps.getContext();
         const sourceIndex = this.#deps.dragState.sourceIndex() ?? 0;
+        // A cancelled item goes back to its source list
+        const sourceDroppableId = this.#deps.dragState.sourceDroppableId();
         // Remove document listener
         this.#cleanupDocumentListener();
         // Clear droppable metadata cache from this drag session
@@ -4779,7 +5064,7 @@ class KeyboardDragHandler {
         });
         this.#deps.keyboardDrag.cancelKeyboardDrag();
         // Restore focus to the original element after state updates
-        this.#restoreFocus(ctx.draggableId);
+        this.#restoreFocus(ctx.draggableId, sourceDroppableId);
     }
     /**
      * Teardown — remove any active document listener.
@@ -4794,20 +5079,21 @@ class KeyboardDragHandler {
      *
      * Uses EnvironmentInjector to ensure callback runs even if the directive
      * is destroyed during cross-list moves.
+     *
+     * `fallbackDroppableId` is the list whose first draggable gets focus when the element is not
+     * rendered (for example scrolled out of a virtual list). Callers read it before ending the
+     * drag, which clears the drag state.
      */
-    #restoreFocus(draggableId) {
-        // Capture the destination droppable BEFORE scheduling afterNextRender
-        // (the directive may be destroyed during cross-list moves)
-        const destinationDroppableId = this.#deps.dragState.activeDroppableId();
+    #restoreFocus(draggableId, fallbackDroppableId) {
         afterNextRender(() => {
             const element = queryByAttribute(document, 'data-draggable-id', draggableId);
             if (element) {
                 element.focus();
             }
-            else if (destinationDroppableId) {
-                // Fallback: focus the first draggable in the destination container
-                const destination = queryByAttribute(document, 'data-droppable-id', destinationDroppableId);
-                const firstDraggable = destination?.querySelector('[data-draggable-id]');
+            else if (fallbackDroppableId) {
+                // Fallback: focus the first draggable in the list the item ended up in
+                const container = queryByAttribute(document, 'data-droppable-id', fallbackDroppableId);
+                const firstDraggable = container?.querySelector('[data-draggable-id]');
                 firstDraggable?.focus();
             }
         }, { injector: this.#deps.envInjector });
@@ -4866,7 +5152,7 @@ var _a;
  * - Pointer down / move / up lifecycle
  * - Drag threshold detection
  * - Drag delay timer
- * - RAF throttling for move updates
+ * - Forwarding moves to the directive (DragSchedulerService coalesces them per frame)
  * - Document-level listener management
  * - Escape key cancellation during pointer drag
  */