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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ngx-virtual-dnd",
-  "version": "3.1.2",
+  "version": "3.2.0-alpha.0",
   "description": "A performant drag-and-drop library for Angular that works seamlessly with virtual scrolling",
   "keywords": [
     "angular",
@@ -19,11 +19,11 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/gultyayev/angular-vdnd.git"
+    "url": "git+https://github.com/gultyayev/ngx-virtual-dnd.git"
   },
-  "homepage": "https://github.com/gultyayev/angular-vdnd#readme",
+  "homepage": "https://github.com/gultyayev/ngx-virtual-dnd#readme",
   "bugs": {
-    "url": "https://github.com/gultyayev/angular-vdnd/issues"
+    "url": "https://github.com/gultyayev/ngx-virtual-dnd/issues"
   },
   "peerDependencies": {
     "@angular/common": "^21.0.0 || ^22.0.0",

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

@@ -59,7 +59,7 @@ interface DragState {
     grabOffset: GrabOffset | null;
     /** Position when drag started (for axis locking) */
     initialPosition: CursorPosition | null;
-    /** Axis to lock movement to ('x' = horizontal only, 'y' = vertical only) */
+    /** Axis to freeze ('x' = X frozen → vertical-only, 'y' = Y frozen → horizontal-only) */
     lockAxis: 'x' | 'y' | null;
     /** Whether this is a keyboard-initiated drag */
     isKeyboardDrag: boolean;
@@ -116,6 +116,31 @@ interface DropEvent {
     /** Information about where the item is going */
     destination: DropDestination;
 }
+/**
+ * Event emitted by a droppable each time the placeholder moves within it during a drag,
+ * i.e. whenever items are displaced. Useful for haptic feedback on every step.
+ *
+ * Indexes use the same convention as `DropEvent.destination.index` (the insertion index
+ * the item would get if dropped now). Not emitted for the placeholder's initial position
+ * at drag start, nor when the placeholder leaves this droppable.
+ */
+interface PlaceholderMoveEvent {
+    /** Unique identifier for the dragged item */
+    draggableId: string;
+    /** ID of the droppable container the item originated from */
+    sourceDroppableId: string;
+    /** ID of the droppable the placeholder moved within */
+    droppableId: string;
+    /**
+     * Previous insertion index in this droppable, or `null` when the placeholder just entered
+     * it from elsewhere. For the first move in the source list this is the item's own index.
+     */
+    previousIndex: number | null;
+    /** New insertion index in this droppable */
+    currentIndex: number;
+    /** Optional user-provided data associated with the dragged item */
+    data?: unknown;
+}
 /**
  * Event emitted when a drag operation ends (including cancel).
  */
@@ -124,13 +149,22 @@ interface DragEndEvent {
     draggableId: string;
     /** ID of the droppable container the item originated from */
     droppableId: string;
-    /** Whether the drag was cancelled (escaped, dropped outside) */
+    /**
+     * Whether the drag was actively cancelled (Escape key). 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".
+     */
     cancelled: boolean;
     /** Optional user-provided data associated with the item */
     data?: unknown;
     /** Original 0-indexed position in source list (for cancel announcements) */
     sourceIndex: number;
-    /** Final 0-indexed position (null if cancelled) */
+    /**
+     * 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.
+     */
     destinationIndex: number | null;
 }
 /**
@@ -302,6 +336,37 @@ interface VdndVirtualViewport {
  */
 declare const VDND_VIRTUAL_VIEWPORT: InjectionToken<VdndVirtualViewport>;
 
+/**
+ * Animation settings for drag-and-drop lists.
+ */
+interface VdndAnimationConfig {
+    /**
+     * Duration (ms) of the slide animation played when items are displaced by the
+     * placeholder during a drag. `0` disables the animation.
+     * @default 200
+     */
+    shiftDuration?: number;
+    /**
+     * CSS easing function for the shift animation.
+     * @default 'cubic-bezier(0.2, 0, 0, 1)'
+     */
+    shiftEasing?: string;
+}
+/**
+ * Opt-in animation configuration. When provided, items displaced by the placeholder
+ * slide into their new position instead of jumping. 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
+ * time an animation starts, so getters can toggle the animation at runtime.
+ *
+ * @example
+ * ```typescript
+ * providers: [{ provide: VDND_ANIMATION_CONFIG, useValue: { shiftDuration: 200 } }]
+ * ```
+ */
+declare const VDND_ANIMATION_CONFIG: InjectionToken<VdndAnimationConfig>;
+
 /**
  * Central service for managing drag-and-drop state.
  * Uses signals for reactive state management.
@@ -317,6 +382,8 @@ declare class DragStateService {
     #private;
     /** Whether the last drag was cancelled (for droppable to check before emitting drop) */
     readonly wasCancelled: _angular_core.Signal<boolean>;
+    /** Snapshot captured synchronously before the last drag reset. */
+    readonly endedDragState: _angular_core.Signal<DragState | null>;
     /** Whether a drag operation is in progress */
     readonly isDragging: _angular_core.Signal<boolean>;
     /** The currently dragged item, or null */
@@ -430,6 +497,25 @@ declare class PositionCalculatorService {
      * scroll event has not yet fired but the container has already moved.
      */
     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.
+     *
+     * 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.
+     *
+     * Called by {@link DroppableDirective} lifecycle hooks. No-op when the active session
+     * belongs to a different group or no session is active.
+     */
+    notifyCandidatesChanged(groupName: string): void;
     /**
      * Find the droppable element at a given point.
      *
@@ -538,8 +624,14 @@ declare class PositionCalculatorService {
     findAdjacentDroppable(currentDroppableId: string, direction: 'left' | 'right', groupName: string): {
         element: HTMLElement;
         id: string;
-        itemCount: number;
     } | null;
+    /**
+     * Whether the droppable with the given ID is currently disabled. A droppable that cannot
+     * be found is reported as disabled (treat missing as not a valid target). Used to
+     * revalidate a keyboard drag's active target at drop time, since it may have been disabled
+     * after the drag navigated into it.
+     */
+    isDroppableDisabledById(id: string): boolean;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<PositionCalculatorService, never>;
     static ɵprov: _angular_core.ɵɵInjectableDeclaration<PositionCalculatorService>;
 }
@@ -550,7 +642,7 @@ declare class PositionCalculatorService {
 interface AutoScrollConfig {
     /** Distance from edge to start scrolling (in pixels) */
     threshold: number;
-    /** Maximum scroll speed (in pixels per frame) */
+    /** Maximum scroll speed in pixels per 60fps frame (about 16.67ms) */
     maxSpeed: number;
     /** Whether to accelerate scroll based on distance from edge */
     accelerate: boolean;
@@ -1075,8 +1167,10 @@ declare class VirtualSortableListComponent<T> {
     constrainToContainer: _angular_core.InputSignal<boolean>;
     /** Emits when an item is dropped on this list */
     drop: _angular_core.OutputEmitterRef<DropEvent>;
+    /** 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"; }, 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; }; "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>;
 }
 
 /**
@@ -1285,7 +1379,12 @@ declare class DraggableDirective implements OnInit, OnDestroy {
      * Set to 0 for immediate drag (default behavior).
      */
     dragDelay: _angular_core.InputSignal<number>;
-    /** Lock dragging to a single axis ('x' = horizontal only, 'y' = vertical only) */
+    /**
+     * Lock dragging by freezing one axis. The value names the axis that stays
+     * fixed: `'x'` freezes the X coordinate (vertical-only movement), `'y'`
+     * freezes the Y coordinate (horizontal-only movement). `null` allows free
+     * movement. Note: this is the opposite of Angular CDK's `cdkDragLockAxis`.
+     */
     lockAxis: _angular_core.InputSignal<"x" | "y" | null>;
     /** Emits when drag starts */
     dragStart: _angular_core.OutputEmitterRef<DragStartEvent>;
@@ -1368,6 +1467,11 @@ declare class DroppableDirective implements OnDestroy {
     constrainToContainer: _angular_core.InputSignal<boolean>;
     /** Emits when an item is dropped on this droppable */
     drop: _angular_core.OutputEmitterRef<DropEvent>;
+    /**
+     * Emits each time the placeholder moves within this droppable during a drag
+     * (every item displacement) — e.g. to trigger haptic feedback.
+     */
+    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 */
@@ -1391,7 +1495,7 @@ declare class DroppableDirective implements OnDestroy {
      */
     getScrollHeight(): number;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<DroppableDirective, never>;
-    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<DroppableDirective, "[vdndDroppable]", never, { "vdndDroppable": { "alias": "vdndDroppable"; "required": true; "isSignal": true; }; "vdndDroppableGroup": { "alias": "vdndDroppableGroup"; "required": false; "isSignal": true; }; "vdndDroppableData": { "alias": "vdndDroppableData"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "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"; }, never, never, true, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<DroppableDirective, "[vdndDroppable]", never, { "vdndDroppable": { "alias": "vdndDroppable"; "required": true; "isSignal": true; }; "vdndDroppableGroup": { "alias": "vdndDroppableGroup"; "required": false; "isSignal": true; }; "vdndDroppableData": { "alias": "vdndDroppableData"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "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>;
 }
 
 /**
@@ -1700,5 +1804,5 @@ declare function insertAt<T>(list: T[], item: T, index: number): T[];
  */
 declare function removeAt<T>(list: T[], index: number): T[];
 
-export { AutoScrollService, ContentHeaderDirective, DragPlaceholderComponent, DragPreviewComponent, DragStateService, DraggableDirective, DroppableDirective, DroppableGroupDirective, DynamicHeightStrategy, END_OF_LIST, ElementCloneService, FixedHeightStrategy, INITIAL_DRAG_STATE, KeyboardDragService, OverlayContainerService, PlaceholderComponent, PositionCalculatorService, ScrollableDirective, VDND_GROUP_TOKEN, VDND_SCROLL_CONTAINER, VDND_VIRTUAL_VIEWPORT, VirtualContentComponent, VirtualForDirective, VirtualScrollContainerComponent, VirtualSortableListComponent, VirtualViewportComponent, applyMove, insertAt, isNoOpDrop, moveItem, removeAt, reorderItems };
-export type { AutoScrollConfig, CursorPosition, DragEndEvent, DragPreviewContext, DragStartEvent, DragState, DraggedItem, DropDestination, DropEvent, DropSource, GrabOffset, PlaceholderContext, VdndGroupContext, VdndScrollContainer, VdndVirtualViewport, VirtualForContext, VirtualScrollItemContext, VirtualScrollStrategy };
+export { AutoScrollService, ContentHeaderDirective, DragPlaceholderComponent, DragPreviewComponent, DragStateService, DraggableDirective, DroppableDirective, DroppableGroupDirective, DynamicHeightStrategy, END_OF_LIST, ElementCloneService, FixedHeightStrategy, INITIAL_DRAG_STATE, KeyboardDragService, OverlayContainerService, PlaceholderComponent, PositionCalculatorService, ScrollableDirective, VDND_ANIMATION_CONFIG, VDND_GROUP_TOKEN, VDND_SCROLL_CONTAINER, VDND_VIRTUAL_VIEWPORT, VirtualContentComponent, VirtualForDirective, VirtualScrollContainerComponent, VirtualSortableListComponent, VirtualViewportComponent, applyMove, insertAt, isNoOpDrop, moveItem, removeAt, reorderItems };
+export type { AutoScrollConfig, CursorPosition, DragEndEvent, DragPreviewContext, DragStartEvent, DragState, DraggedItem, DropDestination, DropEvent, DropSource, GrabOffset, PlaceholderContext, PlaceholderMoveEvent, VdndAnimationConfig, VdndGroupContext, VdndScrollContainer, VdndVirtualViewport, VirtualForContext, VirtualScrollItemContext, VirtualScrollStrategy };