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

package/README.md

@@ -15,6 +15,7 @@ Inspired by [react-virtualized-dnd](https://github.com/forecast-it/react-virtual
 - **Container Constraints** - Constrain drag preview to container boundaries
 - **Axis Locking** - Lock dragging to horizontal or vertical axis
 - **Custom Previews** - Template-based drag preview and placeholder customization
+- **Shift Animations** - Opt-in sliding of displaced items, plus a per-step event for haptics
 - **Keyboard Accessible** - Space to grab, arrows to move, Escape to cancel
 - **Touch Support** - Works with mouse and touch, with configurable delay/threshold
 - **Angular 21+** - Signals, standalone components, modern patterns
@@ -45,15 +46,15 @@ import {
     DragPreviewComponent,
   ],
   template: `
-    <!-- Item template -->
-    <ng-template #itemTpl let-item>
-      <div class="item" [vdndDraggable]="item.id" [vdndDraggableData]="item">
-        {{ item.name }}
-      </div>
-    </ng-template>
-
     <!-- Lists wrapped in a group -->
     <div vdndGroup="my-group">
+      <!-- Item template: declare it inside vdndGroup so the draggables inherit the group -->
+      <ng-template #itemTpl let-item>
+        <div class="item" [vdndDraggable]="item.id" [vdndDraggableData]="item">
+          {{ item.name }}
+        </div>
+      </ng-template>
+
       <vdnd-sortable-list
         droppableId="list-1"
         group="my-group"
@@ -98,6 +99,8 @@ export class MyComponent {
 
 **That's it!** `VirtualSortableListComponent` handles placeholder positioning, sticky items during drag, and virtual scroll integration automatically.
 
+> Every draggable and droppable needs a group (from a `vdndGroup` ancestor or `vdndDraggableGroup` / `vdndDroppableGroup`), even for a single list — without one, drag is disabled. Templates resolve the group from where they are **declared**, so keep the `<ng-template>` inside the `vdndGroup` element.
+
 ## API Overview
 
 The library exports these main pieces (use IDE completion for full details):
@@ -241,10 +244,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,14 +295,48 @@ 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`.
 
+### Shift Animations & Haptics
+
+Items displaced by the placeholder jump into place by default. Provide `VDND_ANIMATION_CONFIG` to make them slide instead (a compositor-only `transform` animation, works with virtual scrolling and dynamic heights):
+
+```typescript
+import { VDND_ANIMATION_CONFIG } from 'ngx-virtual-dnd';
+
+// app.config.ts (app-wide) or any component's `providers` (that subtree only)
+providers: [{ provide: VDND_ANIMATION_CONFIG, useValue: { shiftDuration: 200 } }];
+```
+
+| Option          | Default                      | Description                         |
+| --------------- | ---------------------------- | ----------------------------------- |
+| `shiftDuration` | `200`                        | Slide duration in ms (`0` disables) |
+| `shiftEasing`   | `cubic-bezier(0.2, 0, 0, 1)` | CSS easing function                 |
+
+The animation is skipped when the user prefers reduced motion. If the placeholder moves again mid-slide, items continue from where they currently are. Values are read each time an animation starts, so a getter can toggle it at runtime.
+
+For haptic feedback on every step, listen to `(placeholderMove)` on `vdndDroppable` or `vdnd-sortable-list`. It fires each time the placeholder moves within that list (every item displacement), including when it enters the list — not for the initial pick-up or when it leaves:
+
+```html
+<vdnd-sortable-list ... (placeholderMove)="onPlaceholderMove($event)" />
+```
+
+```typescript
+import { Haptics } from '@capacitor/haptics';
+
+onPlaceholderMove(event: PlaceholderMoveEvent): void {
+  Haptics.selectionChanged(); // or navigator.vibrate?.(10) on the web
+}
+```
+
+`PlaceholderMoveEvent` carries `draggableId`, `sourceDroppableId`, `droppableId`, `previousIndex` (`null` when the placeholder just entered the list) and `currentIndex`, using the same index convention as `DropEvent.destination.index`.
+
 ### Disabling Drag & Drop
 
 Use the `disabled` input to conditionally disable draggables, droppables, or entire lists:
@@ -320,6 +360,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`:
@@ -334,13 +376,13 @@ For maximum control, use individual components instead of `VirtualSortableListCo
     DragPreviewComponent,
   ],
   template: `
-    <ng-template #itemTpl let-item>
-      <div class="item" [vdndDraggable]="item.id" [vdndDraggableData]="item">
-        {{ item.name }}
-      </div>
-    </ng-template>
-
     <div vdndGroup="demo">
+      <ng-template #itemTpl let-item>
+        <div class="item" [vdndDraggable]="item.id" [vdndDraggableData]="item">
+          {{ item.name }}
+        </div>
+      </ng-template>
+
       <div vdndDroppable="list-1" (drop)="onDrop($event)">
         <vdnd-virtual-scroll
           droppableId="list-1"
@@ -428,6 +470,7 @@ The library emits events with position data. Implement announcements in your app
 ```typescript
 @Component({
   template: `
+    <!-- Inside a vdndGroup, like any draggable -->
     <div
       vdndDraggable="item-1"
       (dragStart)="announce('Grabbed ' + item.name)"
@@ -446,11 +489,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}`);
   }
 }
 ```
@@ -483,19 +528,29 @@ ARIA attributes (`aria-grabbed`, `aria-dropeffect`, `tabindex`) are managed auto
 
 All event types are importable from `ngx-virtual-dnd`.
 
-| Output        | Event Type       | Emitted By                                           |
-| ------------- | ---------------- | ---------------------------------------------------- |
-| `(dragStart)` | `DragStartEvent` | `DraggableDirective`                                 |
-| `(dragEnd)`   | `DragEndEvent`   | `DraggableDirective`                                 |
-| `(drop)`      | `DropEvent`      | `DroppableDirective`, `VirtualSortableListComponent` |
+| Output              | Event Type             | Emitted By                                           |
+| ------------------- | ---------------------- | ---------------------------------------------------- |
+| `(dragStart)`       | `DragStartEvent`       | `DraggableDirective`                                 |
+| `(dragEnd)`         | `DragEndEvent`         | `DraggableDirective`                                 |
+| `(drop)`            | `DropEvent`            | `DroppableDirective`, `VirtualSortableListComponent` |
+| `(placeholderMove)` | `PlaceholderMoveEvent` | `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 +572,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).