ngx-virtual-dnd 3.1.0 → 3.1.1

package/package.json

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

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

@@ -306,10 +306,12 @@ declare const VDND_VIRTUAL_VIEWPORT: InjectionToken<VdndVirtualViewport>;
  * Central service for managing drag-and-drop state.
  * Uses signals for reactive state management.
  *
- * Architecture: High-frequency fields (`cursorPosition`, `keyboardTargetIndex`)
- * are stored in dedicated signals, separate from the core state. This prevents
- * 60fps cursor updates from triggering re-evaluation of the 10+ computeds
- * that only depend on rarely-changing properties (isDragging, draggedItem, etc.).
+ * Architecture: High-frequency fields (`cursorPosition`, `keyboardTargetIndex`,
+ * `activeDroppableId`, `placeholderId`, `placeholderIndex`) are stored in dedicated
+ * signals, separate from the core state. This prevents 60fps cursor and
+ * placeholder updates from rebuilding the core state object or re-evaluating the
+ * 8+ computeds that only depend on rarely-changing properties (isDragging,
+ * draggedItem, etc.).
  */
 declare class DragStateService {
     #private;
@@ -365,6 +367,14 @@ declare class DragStateService {
      * Update just the placeholder position.
      */
     setPlaceholder(placeholderId: string | null): void;
+    /**
+     * Update only the placeholder signals without touching cursor position or active droppable.
+     *
+     * 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.
+     */
+    updateScrollOnlyPlaceholder(placeholderId: string | null, placeholderIndex: number | null): void;
     /**
      * End the drag operation and reset state (normal drop).
      */
@@ -400,19 +410,52 @@ declare class DragStateService {
  */
 declare class PositionCalculatorService {
     #private;
+    /**
+     * Begin a drag session: snapshot the candidate droppables for `groupName` and
+     * their rects once, then watch for viewport changes (scroll/resize) that would
+     * invalidate those rects. While a session is active, `findDroppableAtPoint`
+     * runs as pure geometry against the cached rects instead of `elementFromPoint`.
+     *
+     * Safe to call repeatedly — a new call replaces any previous session.
+     */
+    beginDragSession(groupName: string): void;
+    /**
+     * End the current drag session and detach viewport listeners.
+     * Safe to call when no session is active.
+     */
+    endDragSession(): void;
+    /**
+     * Mark the cached droppable rects as stale so they are re-read on the next
+     * hit-test. Called explicitly from the autoscroll recalculation path, where the
+     * scroll event has not yet fired but the container has already moved.
+     */
+    invalidateDroppableRects(): void;
     /**
      * Find the droppable element at a given point.
      *
-     * This works by temporarily hiding the dragged element, then using
-     * document.elementFromPoint to find what's underneath the cursor.
+     * Uses pure geometric hit-testing against snapshotted droppable rects. When a
+     * drag session is active (see {@link beginDragSession}) the rects are cached and
+     * reused across frames; otherwise a one-shot DOM query is performed. The
+     * `draggedElement` parameter is retained for API compatibility but no longer
+     * needs to be hidden — geometry does not depend on cursor occlusion.
      *
      * @param x - Cursor X coordinate
      * @param y - Cursor Y coordinate
-     * @param draggedElement - The element being dragged (will be temporarily hidden)
+     * @param _draggedElement - The element being dragged (unused; kept for compatibility)
      * @param groupName - The drag-and-drop group name to filter by
      * @returns The droppable element, or null if none found
      */
-    findDroppableAtPoint(x: number, y: number, draggedElement: HTMLElement, groupName: string): HTMLElement | null;
+    findDroppableAtPoint(x: number, y: number, _draggedElement: HTMLElement, groupName: string): HTMLElement | null;
+    /**
+     * 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.
+     *
+     * Intended for the autoscroll scroll-only fast path, where the active droppable is already
+     * known and only the placeholder index needs recalculation.
+     */
+    getDroppableById(id: string): HTMLElement | null;
     /**
      * Find the draggable element at a given point.
      *
@@ -527,12 +570,14 @@ declare class AutoScrollService {
     unregisterContainer(id: string): void;
     /**
      * Start monitoring for auto-scroll.
-     * Call this when a drag starts.
+     * Registers this service as a tick participant in DragSchedulerService.
+     * The scheduler drives the RAF loop; this service handles scroll logic each frame.
      * @param onScroll Optional callback to invoke when scrolling occurs (for placeholder recalculation)
      */
     startMonitoring(onScroll?: () => void): void;
     /**
      * Stop monitoring for auto-scroll.
+     * Removes this service from the scheduler's participant list.
      * Call this when a drag ends.
      */
     stopMonitoring(): void;
@@ -639,6 +684,19 @@ declare class KeyboardDragService {
  */
 declare class OverlayContainerService implements OnDestroy {
     #private;
+    /**
+     * Whether at least one mounted drag preview renders via a custom template.
+     *
+     * When true, DraggableDirective/KeyboardDragHandler skip the expensive
+     * drag-start element clone: the clone would never be shown because the
+     * template takes precedence (see DragPreviewComponent).
+     */
+    readonly hasTemplatePreview: _angular_core.Signal<boolean>;
+    /**
+     * Register (`active = true`) or unregister (`active = false`) a preview that
+     * renders via a custom template. Calls must be balanced per preview instance.
+     */
+    setTemplatePreviewActive(active: boolean): void;
     /**
      * Returns the shared overlay container element, lazily creating it on first access.
      * Returns `null` in non-browser environments (SSR).