ngx-virtual-dnd 3.1.1 → 3.1.3

package/README.md

@@ -241,10 +241,13 @@ The preview cannot leave the droppable area, and the placeholder snaps to the ed
 Lock dragging to a single axis:
 
 ```html
+<!-- Lock the Y axis → item moves horizontally only -->
 <div [vdndDraggable]="item.id" lockAxis="y">{{ item.name }}</div>
 ```
 
-Values: `'x'` (horizontal only), `'y'` (vertical only), or omit for free movement.
+Values: `'x'` (X axis locked → **vertical-only** movement), `'y'` (Y axis locked → **horizontal-only** movement), or omit for free movement. The value names the axis that is _frozen_.
+
+> **Note:** This is the opposite of Angular CDK's `cdkDragLockAxis`, where `'x'` means _movement is constrained to_ the X axis (horizontal only). Here `'x'` freezes the X axis. Keep this in mind when migrating from CDK.
 
 ### Drag Threshold & Delay
 
@@ -289,11 +292,11 @@ Configure auto-scroll behavior when dragging near container edges:
 />
 ```
 
-| Option       | Default | Description                          |
-| ------------ | ------- | ------------------------------------ |
-| `threshold`  | `50`    | Distance from edge (px) to trigger   |
-| `maxSpeed`   | `15`    | Maximum scroll speed (px/frame)      |
-| `accelerate` | `true`  | Speed up based on distance from edge |
+| Option       | Default | Description                                    |
+| ------------ | ------- | ---------------------------------------------- |
+| `threshold`  | `50`    | Distance from edge (px) to trigger             |
+| `maxSpeed`   | `15`    | Maximum scroll speed in pixels per 60fps frame |
+| `accelerate` | `true`  | Speed up based on distance from edge           |
 
 Set `[autoScrollEnabled]="false"` to disable auto-scroll entirely. These options are available on `VirtualSortableListComponent`, `DroppableDirective`, and `ScrollableDirective`.
 
@@ -320,6 +323,8 @@ Use the `disabled` input to conditionally disable draggables, droppables, or ent
 
 Disabled draggables get the `vdnd-draggable-disabled` CSS class. Disabled droppables get `vdnd-droppable-disabled`.
 
+A disabled droppable is removed from all drag-time candidate sets: pointer hit-testing skips it (the cursor falls through to whatever enabled droppable sits underneath, or none) and keyboard `ArrowLeft`/`ArrowRight` navigation steps over it. Releasing a drag over a disabled droppable fires **no `drop` event**; the `(dragEnd)` event still fires with `cancelled: false` and `destinationIndex: null`, so consumers that pair `drop`/`dragEnd` should treat a `null` `destinationIndex` as "no valid drop target".
+
 ### Low-Level API
 
 For maximum control, use individual components instead of `VirtualSortableListComponent`:
@@ -446,11 +451,13 @@ export class MyComponent {
   }
 
   announceEnd(e: DragEndEvent) {
-    this.announce(
-      e.cancelled
-        ? `Cancelled. Returned to position ${e.sourceIndex + 1}`
-        : `Dropped at position ${e.destinationIndex! + 1}`,
-    );
+    // destinationIndex is null when there is no valid drop target: an Escape cancel,
+    // a release outside every droppable, or a release over a disabled droppable.
+    if (e.destinationIndex === null) {
+      this.announce(`Returned to position ${e.sourceIndex + 1}`);
+      return;
+    }
+    this.announce(`Dropped at position ${e.destinationIndex + 1}`);
   }
 }
 ```
@@ -489,13 +496,22 @@ All event types are importable from `ngx-virtual-dnd`.
 | `(dragEnd)`   | `DragEndEvent`   | `DraggableDirective`                                 |
 | `(drop)`      | `DropEvent`      | `DroppableDirective`, `VirtualSortableListComponent` |
 
-`DragEndEvent` includes a `cancelled` boolean to distinguish drops from cancellations.
+`DragEndEvent.destinationIndex` is `null` when no drop occurred — an Escape cancel, a release outside every droppable, or a release over a disabled droppable — so branch on `destinationIndex === null` to detect that. The `cancelled` boolean is `true` only for an active Escape cancel.
 
 ## How It Works
 
 Traditional drag-and-drop libraries query sibling DOM elements via `getBoundingClientRect()`. This fails with virtual scrolling because items outside the viewport aren't rendered.
 
-This library uses **element-under-point detection**: temporarily hide the dragged element, use `document.elementFromPoint()` to find what's at the cursor, walk up to find the droppable, and calculate placeholder position mathematically.
+This library uses **geometric hit-testing against a cached rect snapshot**: at drag start it snapshots the candidate droppables of the active group and their bounding rects, then per-pointermove it hit-tests the cursor against those rects (last match in document order wins) and calculates the placeholder position mathematically. Caching the rects avoids the forced layout flush that `document.elementFromPoint()` imposes on the hot drag loop. The snapshot self-heals during the drag: rects are re-read on scroll/resize and when a candidate resizes (via `ResizeObserver`), the candidate **list** is refreshed when a droppable mounts or unmounts mid-drag, and each rect is clipped to its nearest `vdndScrollable` ancestor so a droppable scrolled out of a clipping container is not falsely hit.
+
+### Known Limitations
+
+Because hit-testing is geometry against cached rects (not live `elementFromPoint`), a few browser-native behaviors are **not** reproduced:
+
+- **Occluding overlays** — a modal, toolbar, or other element painted over a droppable does not block a geometric hit; the droppable underneath still resolves as the target.
+- **Stacking contexts / explicit `z-index`** — the "last in document order" tie-break approximates paint order but is not true painter order once `z-index` and stacking contexts are involved. An earlier-in-DOM droppable raised visually on top via `z-index` loses the tie-break to a later sibling.
+
+If your layout depends on these, keep overlapping droppables out of the same drag group, or avoid painting interactive overlays across active drop targets during a drag.
 
 ## Browser Support
 
@@ -517,7 +533,7 @@ npm run e2e                  # E2E tests
 Install a skill to teach AI coding assistants how to integrate this library:
 
 ```bash
-npx skills add gultyayev/angular-vdnd
+npx skills add gultyayev/ngx-virtual-dnd
 ```
 
 Works with Claude Code, Cursor, Windsurf, GitHub Copilot, and [40+ other agents](https://skills.sh).