ngx-virtual-dnd 3.2.1 → 3.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ngx-virtual-dnd",
-  "version": "3.2.1",
+  "version": "3.4.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.
@@ -116,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 */
@@ -173,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;
 }
@@ -243,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;
@@ -405,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>;
@@ -445,8 +452,9 @@ declare class DragStateService {
     /**
      * Start a drag operation.
      * `placeholderId` is deprecated with the `placeholderId` signal; the library passes `END_OF_LIST`.
+     * `isTouchDrag` marks a drag started by touch, which gets no grabbing cursor.
      */
-    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;
+    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, isTouchDrag?: boolean): void;
     /**
      * Update the drag position and targets.
      * `placeholderId` is deprecated with the `placeholderId` signal; the library passes `END_OF_LIST`.
@@ -477,7 +485,8 @@ declare class DragStateService {
      */
     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;
     /**
@@ -511,6 +520,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
@@ -532,22 +542,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;
     /**
@@ -569,8 +579,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.
@@ -892,8 +902,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) */
@@ -940,6 +956,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.
@@ -983,8 +1006,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.
@@ -1007,7 +1032,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>;
 }
 
 /**
@@ -1062,12 +1087,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;
@@ -1210,6 +1234,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 */
@@ -1221,7 +1252,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>;
 }
 
 /**
@@ -1407,7 +1438,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>;
@@ -1441,10 +1472,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).
@@ -1516,7 +1553,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