ngx-virtual-dnd 3.2.0-alpha.1 → 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
@@ -2488,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.
  *
@@ -2525,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.
@@ -2599,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 = [];
@@ -3352,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.
  *
@@ -3359,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>
@@ -3372,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) */
@@ -3385,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.
@@ -3423,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;
@@ -3433,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
@@ -3461,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();
@@ -3469,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 };
         }
@@ -3480,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"
@@ -3504,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>
@@ -3516,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"
@@ -3529,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.
@@ -4931,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
  */