ngx-virtual-dnd 3.2.0 → 3.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ngx-virtual-dnd",
-  "version": "3.2.0",
+  "version": "3.3.0",
   "description": "A performant drag-and-drop library for Angular that works seamlessly with virtual scrolling",
   "keywords": [
     "angular",

package/types/ngx-virtual-dnd.d.ts

@@ -1,5 +1,5 @@
 import * as _angular_core from '@angular/core';
-import { Signal, InjectionToken, OnDestroy, OnInit, AfterViewInit, TemplateRef, ElementRef, WritableSignal } from '@angular/core';
+import { Signal, InjectionToken, OnDestroy, OnChanges, OnInit, AfterViewInit, AfterViewChecked, TemplateRef, ElementRef, WritableSignal } from '@angular/core';
 
 /**
  * Represents the item currently being dragged.
@@ -49,9 +49,13 @@ interface DragState {
     sourceIndex: number | null;
     /** ID of the droppable currently being hovered over */
     activeDroppableId: string | null;
-    /** ID of the item the placeholder should appear before, or 'END_OF_LIST' */
+    /**
+     * `END_OF_LIST` while a droppable is targeted, otherwise null.
+     * @deprecated It never identifies an item. Use `placeholderIndex`. Will be removed in the next
+     * major version.
+     */
     placeholderId: string | null;
-    /** Index where the placeholder should be inserted (more stable than placeholderId) */
+    /** Index where the placeholder should be inserted */
     placeholderIndex: number | null;
     /** Current cursor position */
     cursorPosition: CursorPosition | null;
@@ -100,7 +104,11 @@ interface DropSource {
 interface DropDestination {
     /** ID of the droppable container receiving the item */
     droppableId: string;
-    /** ID of the item to insert before, or 'END_OF_LIST' */
+    /**
+     * The library always sets `END_OF_LIST`.
+     * @deprecated It never identifies an item. Use `index` for the insertion position. Will be
+     * removed in the next major version.
+     */
     placeholderId: string;
     /** Target index in the destination list */
     index: number;
@@ -108,7 +116,8 @@ interface DropDestination {
     data?: unknown;
 }
 /**
- * Event emitted when an item is dropped.
+ * Event emitted by the destination droppable when an item is dropped on it: at release,
+ * right after the dragged item's `DragEndEvent` and before the next render.
  */
 interface DropEvent {
     /** Information about where the item came from */
@@ -150,7 +159,9 @@ interface DragEndEvent {
     /** ID of the droppable container the item originated from */
     droppableId: string;
     /**
-     * Whether the drag was actively cancelled (Escape key). Releasing over no valid
+     * Whether the drag was cancelled: Escape, Tab during a keyboard drag, or, during a pointer
+     * drag, the window losing focus, the page being hidden or the system cancelling the touch
+     * (`touchcancel`). Releasing over no valid
      * target (outside any droppable, or over a disabled droppable) is NOT a cancel —
      * it reports `cancelled: false` with `destinationIndex: null`. Branch on
      * `destinationIndex === null` to detect "no drop occurred".
@@ -163,7 +174,7 @@ interface DragEndEvent {
     /**
      * Final 0-indexed insertion position, or `null` when there is no valid drop target —
      * a cancelled drag, a release outside every droppable, or a release over a disabled
-     * droppable. A non-null value pairs with a `DropEvent` on the destination.
+     * droppable. A non-null value pairs with the `DropEvent` the destination emits right after.
      */
     destinationIndex: number | null;
 }
@@ -172,7 +183,10 @@ interface DragEndEvent {
  */
 declare const INITIAL_DRAG_STATE: DragState;
 /**
- * Placeholder ID used when dropping at the end of a list.
+ * The value of every `placeholderId` the library sets. Positions are reported as indexes
+ * (`placeholderIndex`, `DropDestination.index`).
+ * @deprecated Goes with the deprecated `placeholderId` fields. Use the indexes. Will be removed in
+ * the next major version.
  */
 declare const END_OF_LIST = "END_OF_LIST";
 
@@ -230,6 +244,12 @@ declare class FixedHeightStrategy implements VirtualScrollStrategy {
     getItemHeight(index: number): number;
     setMeasuredHeight(key: unknown, height: number): void;
     setItemKeys(keys: unknown[]): void;
+    /**
+     * Set the item count: all this strategy needs of the keys, so the library's containers skip
+     * computing them.
+     * @internal
+     */
+    setItemCount(count: number): void;
     setExcludedIndex(index: number | null): void;
     findIndexAtOffset(offset: number): number;
     getItemCount(): number;
@@ -392,7 +412,7 @@ declare const VDND_ANIMATION_CONFIG: InjectionToken<VdndAnimationConfig>;
  */
 declare class DragStateService {
     #private;
-    /** Whether the last drag was cancelled (for droppable to check before emitting drop) */
+    /** Whether the last drag was cancelled (a cancelled drag delivers no drop) */
     readonly wasCancelled: _angular_core.Signal<boolean>;
     /** Snapshot captured synchronously before the last drag reset. */
     readonly endedDragState: _angular_core.Signal<DragState | null>;
@@ -408,7 +428,11 @@ declare class DragStateService {
     readonly sourceIndex: _angular_core.Signal<number | null>;
     /** ID of the droppable currently being hovered over */
     readonly activeDroppableId: _angular_core.Signal<string | null>;
-    /** ID of the item the placeholder should appear before */
+    /**
+     * `END_OF_LIST` while a droppable is targeted, otherwise null.
+     * @deprecated It never identifies an item. Use `placeholderIndex`. Will be removed in the next
+     * major version.
+     */
     readonly placeholderId: _angular_core.Signal<string | null>;
     /** Index where the placeholder should be inserted */
     readonly placeholderIndex: _angular_core.Signal<number | null>;
@@ -427,10 +451,12 @@ declare class DragStateService {
     constructor();
     /**
      * Start a drag operation.
+     * `placeholderId` is deprecated with the `placeholderId` signal; the library passes `END_OF_LIST`.
      */
     startDrag(item: DraggedItem, cursorPosition?: CursorPosition, grabOffset?: GrabOffset, lockAxis?: 'x' | 'y' | null, activeDroppableId?: string | null, placeholderId?: string | null, placeholderIndex?: number | null, sourceIndex?: number | null, isKeyboardDrag?: boolean, axisLockPosition?: CursorPosition): void;
     /**
      * Update the drag position and targets.
+     * `placeholderId` is deprecated with the `placeholderId` signal; the library passes `END_OF_LIST`.
      */
     updateDragPosition(update: {
         cursorPosition: CursorPosition;
@@ -443,7 +469,9 @@ declare class DragStateService {
      */
     setActiveDroppable(droppableId: string | null): void;
     /**
-     * Update just the placeholder position.
+     * Update just the placeholder ID.
+     * @deprecated Sets only the deprecated `placeholderId`. Will be removed in the next major
+     * version.
      */
     setPlaceholder(placeholderId: string | null): void;
     /**
@@ -452,10 +480,12 @@ declare class DragStateService {
      * 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.
+     * `placeholderId` is deprecated with the `placeholderId` signal; the library passes `END_OF_LIST`.
      */
     updateScrollOnlyPlaceholder(placeholderId: string | null, placeholderIndex: number | null): void;
     /**
-     * End the drag operation and reset state (normal drop).
+     * End the drag operation and reset state (normal drop), then deliver the drop: the target
+     * droppable (`activeDroppableId`) emits `drop` before this returns.
      */
     endDrag(): void;
     /**
@@ -489,6 +519,7 @@ declare class DragStateService {
  */
 declare class PositionCalculatorService {
     #private;
+    constructor();
     /**
      * Begin a drag session: snapshot the candidate droppables for `groupName` and
      * their rects once, then watch for viewport changes (scroll/resize) that would
@@ -510,22 +541,22 @@ declare class PositionCalculatorService {
      */
     invalidateDroppableRects(): void;
     /**
-     * Re-query the candidate droppable *list* for the active session and re-read their
-     * rects. Unlike {@link invalidateDroppableRects} (which only refreshes rects), this
-     * picks up droppables added or removed since the snapshot was captured at drag start —
-     * the frozen candidate list is otherwise blind to mid-drag mounts/unmounts.
+     * Re-read the candidate droppable *list* for the active session from the registry and
+     * re-read their rects. Unlike {@link invalidateDroppableRects} (which only refreshes
+     * rects), this picks up droppables added or removed since the snapshot was captured at
+     * drag start. Registration changes already trigger it on the next hit-test; this is the
+     * manual escape hatch.
      *
      * Safe to call when no session is active (no-op).
      */
     refreshCandidates(): void;
     /**
      * Signal that the set of droppables for `groupName` may have changed (a droppable
-     * registered or unregistered mid-drag). Defers the actual re-query to the next
-     * hit-test — where a removed element is already gone from the DOM and a newly added
-     * one has its data attributes applied — keeping this notification path cheap.
+     * registered or unregistered mid-drag). Defers the re-read to the next hit-test, keeping
+     * this notification path cheap.
      *
-     * Called by {@link DroppableDirective} lifecycle hooks. No-op when the active session
-     * belongs to a different group or no session is active.
+     * Called for every droppable registry change. No-op when the active session belongs to
+     * a different group or no session is active.
      */
     notifyCandidatesChanged(groupName: string): void;
     /**
@@ -547,8 +578,8 @@ declare class PositionCalculatorService {
     /**
      * 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.
+     * When a drag session is active, searches the cached candidate list. Otherwise looks the
+     * ID up in the droppable registry. Neither queries the document.
      *
      * Intended for the autoscroll scroll-only fast path, where the active droppable is already
      * known and only the placeholder index needs recalculation.
@@ -870,8 +901,14 @@ interface VirtualScrollItemContext<T> {
  * </vdnd-virtual-scroll>
  * ```
  */
-declare class VirtualScrollContainerComponent<T> implements OnInit, AfterViewInit, OnDestroy {
+declare class VirtualScrollContainerComponent<T> implements OnChanges, OnInit, AfterViewInit, AfterViewChecked, OnDestroy {
     #private;
+    /** The template's spacer (cannot use ES private with viewChild) */
+    private readonly spacer;
+    /** The template's content wrapper (cannot use ES private with viewChild) */
+    private readonly contentWrapper;
+    /** Where #renderRows inserts the rows (cannot use ES private with viewChild) */
+    private readonly rowOutlet;
     /** Template for rendering each item - passed as input instead of content child for reliability */
     itemTemplate: _angular_core.InputSignal<TemplateRef<VirtualScrollItemContext<T>>>;
     /** Unique ID for this scroll container (used for auto-scroll registration) */
@@ -918,6 +955,13 @@ declare class VirtualScrollContainerComponent<T> implements OnInit, AfterViewIni
      * Required for placeholder positioning.
      */
     droppableId: _angular_core.InputSignal<string | undefined>;
+    /**
+     * Reuse the views of rows that scroll out to render the rows that scroll in, instead of
+     * destroying them and creating new ones. Scrolling creates fewer components and elements, but
+     * a row's components, element and DOM state (focus aside) then carry over to other items.
+     * @default false
+     */
+    recycleRows: _angular_core.InputSignal<boolean>;
     /**
      * Whether to automatically add the dragged item to the sticky list.
      * This ensures the dragged item remains visible during virtual scrolling.
@@ -961,8 +1005,10 @@ declare class VirtualScrollContainerComponent<T> implements OnInit, AfterViewIni
         isDragging: boolean;
     }[]>;
     constructor();
+    ngOnChanges(): void;
     ngOnInit(): void;
     ngAfterViewInit(): void;
+    ngAfterViewChecked(): void;
     ngOnDestroy(): void;
     /**
      * Scroll to a specific position.
@@ -985,7 +1031,7 @@ declare class VirtualScrollContainerComponent<T> implements OnInit, AfterViewIni
      */
     scrollBy(delta: number): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<VirtualScrollContainerComponent<any>, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<VirtualScrollContainerComponent<any>, "vdnd-virtual-scroll", never, { "itemTemplate": { "alias": "itemTemplate"; "required": true; "isSignal": true; }; "scrollContainerId": { "alias": "scrollContainerId"; "required": false; "isSignal": true; }; "autoScrollEnabled": { "alias": "autoScrollEnabled"; "required": false; "isSignal": true; }; "autoScrollConfig": { "alias": "autoScrollConfig"; "required": false; "isSignal": true; }; "items": { "alias": "items"; "required": true; "isSignal": true; }; "itemHeight": { "alias": "itemHeight"; "required": true; "isSignal": true; }; "dynamicItemHeight": { "alias": "dynamicItemHeight"; "required": false; "isSignal": true; }; "containerHeight": { "alias": "containerHeight"; "required": false; "isSignal": true; }; "overscan": { "alias": "overscan"; "required": false; "isSignal": true; }; "stickyItemIds": { "alias": "stickyItemIds"; "required": false; "isSignal": true; }; "itemIdFn": { "alias": "itemIdFn"; "required": true; "isSignal": true; }; "trackByFn": { "alias": "trackByFn"; "required": false; "isSignal": true; }; "droppableId": { "alias": "droppableId"; "required": false; "isSignal": true; }; "autoStickyDraggedItem": { "alias": "autoStickyDraggedItem"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<VirtualScrollContainerComponent<any>, "vdnd-virtual-scroll", never, { "itemTemplate": { "alias": "itemTemplate"; "required": true; "isSignal": true; }; "scrollContainerId": { "alias": "scrollContainerId"; "required": false; "isSignal": true; }; "autoScrollEnabled": { "alias": "autoScrollEnabled"; "required": false; "isSignal": true; }; "autoScrollConfig": { "alias": "autoScrollConfig"; "required": false; "isSignal": true; }; "items": { "alias": "items"; "required": true; "isSignal": true; }; "itemHeight": { "alias": "itemHeight"; "required": true; "isSignal": true; }; "dynamicItemHeight": { "alias": "dynamicItemHeight"; "required": false; "isSignal": true; }; "containerHeight": { "alias": "containerHeight"; "required": false; "isSignal": true; }; "overscan": { "alias": "overscan"; "required": false; "isSignal": true; }; "stickyItemIds": { "alias": "stickyItemIds"; "required": false; "isSignal": true; }; "itemIdFn": { "alias": "itemIdFn"; "required": true; "isSignal": true; }; "trackByFn": { "alias": "trackByFn"; "required": false; "isSignal": true; }; "droppableId": { "alias": "droppableId"; "required": false; "isSignal": true; }; "recycleRows": { "alias": "recycleRows"; "required": false; "isSignal": true; }; "autoStickyDraggedItem": { "alias": "autoStickyDraggedItem"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
 /**
@@ -1040,12 +1086,11 @@ declare class DragPreviewComponent<T = unknown> implements OnDestroy {
     protected readonly clonedElement: _angular_core.Signal<HTMLElement | null>;
     constructor();
     ngOnDestroy(): void;
-    /** Whether the preview is visible */
+    /**
+     * Whether the preview is visible. A drag shows it once it has a position: `initialPosition`
+     * is set from the drag-start cursor and, unlike `cursorPosition`, does not change per frame.
+     */
     protected readonly isVisible: _angular_core.Signal<boolean>;
-    /** Position of the preview */
-    protected readonly position: _angular_core.Signal<CursorPosition>;
-    /** Transform-based positioning for better performance (avoid layout from left/top). */
-    protected readonly transform: _angular_core.Signal<string>;
     /** Dimensions of the preview */
     protected readonly dimensions: _angular_core.Signal<{
         width: number;
@@ -1188,6 +1233,13 @@ declare class VirtualSortableListComponent<T> {
     containerHeight: _angular_core.InputSignal<number | undefined>;
     /** Number of items to render above/below the visible area */
     overscan: _angular_core.InputSignal<number>;
+    /**
+     * Reuse the views of rows that scroll out to render the rows that scroll in, instead of
+     * destroying them and creating new ones. Scrolling creates fewer components and elements, but
+     * a row's components, element and DOM state (focus aside) then carry over to other items.
+     * @default false
+     */
+    recycleRows: _angular_core.InputSignal<boolean>;
     /** Enable auto-scroll when dragging near edges */
     autoScrollEnabled: _angular_core.InputSignal<boolean>;
     /** Auto-scroll configuration */
@@ -1199,7 +1251,7 @@ declare class VirtualSortableListComponent<T> {
     /** Emits each time the placeholder moves within this list (every item displacement) */
     placeholderMove: _angular_core.OutputEmitterRef<PlaceholderMoveEvent>;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<VirtualSortableListComponent<any>, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<VirtualSortableListComponent<any>, "vdnd-sortable-list", never, { "droppableId": { "alias": "droppableId"; "required": true; "isSignal": true; }; "group": { "alias": "group"; "required": false; "isSignal": true; }; "items": { "alias": "items"; "required": true; "isSignal": true; }; "itemHeight": { "alias": "itemHeight"; "required": true; "isSignal": true; }; "dynamicItemHeight": { "alias": "dynamicItemHeight"; "required": false; "isSignal": true; }; "itemIdFn": { "alias": "itemIdFn"; "required": true; "isSignal": true; }; "itemTemplate": { "alias": "itemTemplate"; "required": true; "isSignal": true; }; "trackByFn": { "alias": "trackByFn"; "required": false; "isSignal": true; }; "droppableData": { "alias": "droppableData"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "containerHeight": { "alias": "containerHeight"; "required": false; "isSignal": true; }; "overscan": { "alias": "overscan"; "required": false; "isSignal": true; }; "autoScrollEnabled": { "alias": "autoScrollEnabled"; "required": false; "isSignal": true; }; "autoScrollConfig": { "alias": "autoScrollConfig"; "required": false; "isSignal": true; }; "constrainToContainer": { "alias": "constrainToContainer"; "required": false; "isSignal": true; }; }, { "drop": "drop"; "placeholderMove": "placeholderMove"; }, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<VirtualSortableListComponent<any>, "vdnd-sortable-list", never, { "droppableId": { "alias": "droppableId"; "required": true; "isSignal": true; }; "group": { "alias": "group"; "required": false; "isSignal": true; }; "items": { "alias": "items"; "required": true; "isSignal": true; }; "itemHeight": { "alias": "itemHeight"; "required": true; "isSignal": true; }; "dynamicItemHeight": { "alias": "dynamicItemHeight"; "required": false; "isSignal": true; }; "itemIdFn": { "alias": "itemIdFn"; "required": true; "isSignal": true; }; "itemTemplate": { "alias": "itemTemplate"; "required": true; "isSignal": true; }; "trackByFn": { "alias": "trackByFn"; "required": false; "isSignal": true; }; "droppableData": { "alias": "droppableData"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "containerHeight": { "alias": "containerHeight"; "required": false; "isSignal": true; }; "overscan": { "alias": "overscan"; "required": false; "isSignal": true; }; "recycleRows": { "alias": "recycleRows"; "required": false; "isSignal": true; }; "autoScrollEnabled": { "alias": "autoScrollEnabled"; "required": false; "isSignal": true; }; "autoScrollConfig": { "alias": "autoScrollConfig"; "required": false; "isSignal": true; }; "constrainToContainer": { "alias": "constrainToContainer"; "required": false; "isSignal": true; }; }, { "drop": "drop"; "placeholderMove": "placeholderMove"; }, never, never, true, never>;
 }
 
 /**
@@ -1385,7 +1437,7 @@ declare class VirtualContentComponent implements VdndVirtualViewport, VdndScroll
  * </div>
  * ```
  */
-declare class DraggableDirective implements OnInit, OnDestroy {
+declare class DraggableDirective implements OnChanges, OnInit, OnDestroy {
     #private;
     /** Unique identifier for this draggable */
     vdndDraggable: _angular_core.InputSignal<string>;
@@ -1419,10 +1471,16 @@ declare class DraggableDirective implements OnInit, OnDestroy {
     dragStart: _angular_core.OutputEmitterRef<DragStartEvent>;
     /** Emits when drag ends */
     dragEnd: _angular_core.OutputEmitterRef<DragEndEvent>;
+    /**
+     * Whether this element is in the "ready to drag" state (delay has passed). Tied to the pressed
+     * item: a recycled row that renders another item is not ready to drag.
+     */
     readonly isPending: _angular_core.Signal<boolean>;
     /** Whether this element is currently being dragged (based on global drag state) */
     readonly isDragging: _angular_core.Signal<boolean>;
+    constructor();
     ngOnInit(): void;
+    ngOnChanges(): void;
     ngOnDestroy(): void;
     /**
      * Handle pointer down (mouse or touch).
@@ -1494,7 +1552,7 @@ declare class DroppableDirective implements OnDestroy {
     autoScrollConfig: _angular_core.InputSignal<Partial<AutoScrollConfig>>;
     /** Constrain drag preview and placeholder to container boundaries */
     constrainToContainer: _angular_core.InputSignal<boolean>;
-    /** Emits when an item is dropped on this droppable */
+    /** Emits when an item is dropped on this droppable: at release, right after its `dragEnd` */
     drop: _angular_core.OutputEmitterRef<DropEvent>;
     /**
      * Emits each time the placeholder moves within this droppable during a drag
@@ -1503,7 +1561,11 @@ declare class DroppableDirective implements OnDestroy {
     placeholderMove: _angular_core.OutputEmitterRef<PlaceholderMoveEvent>;
     /** Whether this droppable is currently being targeted */
     readonly isActive: _angular_core.Signal<boolean>;
-    /** The current placeholder ID when this droppable is active */
+    /**
+     * `END_OF_LIST` while this droppable is active, otherwise null.
+     * @deprecated It never identifies an item. For the position, use the `placeholderMove` output
+     * (and `DropEvent.destination.index` on drop). Will be removed in the next major version.
+     */
     readonly placeholderId: _angular_core.Signal<string | null>;
     constructor();
     ngOnDestroy(): void;