ngx-virtual-dnd 3.3.0 → 3.4.0

package/README.md

@@ -85,8 +85,10 @@ Every draggable and droppable needs a group (here from `vdndGroup`), even for a
 ## Documentation
 
 - [Getting started](https://gultyayev.github.io/ngx-virtual-dnd/guide/start/introduction.html): introduction, installation, quick start
-- [Guides](https://gultyayev.github.io/ngx-virtual-dnd/guide/essentials/core-concepts.html): multiple lists, dynamic heights, page scroll, drag behavior, styling, accessibility
-- [API reference](https://gultyayev.github.io/ngx-virtual-dnd/api/components.html): components, directives, events, utilities, services, types
+- [Guides](https://gultyayev.github.io/ngx-virtual-dnd/guide/essentials/core-concepts.html): multiple lists, dynamic heights, page scroll, drag behavior, styling, accessibility, performance
+- [Coming from Angular CDK](https://gultyayev.github.io/ngx-virtual-dnd/guide/start/coming-from-cdk.html): how the CDK drag-and-drop API maps to this one
+- [FAQ](https://gultyayev.github.io/ngx-virtual-dnd/guide/more/faq.html): SSR, zoneless apps, testing and more
+- [API reference](https://gultyayev.github.io/ngx-virtual-dnd/api/overview.html): components, directives, events, utilities, services, types
 
 ## AI agent skills
 
@@ -98,18 +100,9 @@ npx skills add gultyayev/ngx-virtual-dnd
 
 It works with Claude Code, Cursor, Windsurf, GitHub Copilot and [40+ other agents](https://skills.sh). The docs are also published as [llms.txt](https://gultyayev.github.io/ngx-virtual-dnd/llms.txt).
 
-## Development
+## Contributing
 
-Requires npm 12 (the version pinned in `packageManager`): `npm install -g npm@12`.
-
-```bash
-npm start              # Demo app (localhost:4200)
-npm run build:lib      # Build the library (required after library edits)
-npm run docs:dev       # Docs site (localhost:3000); live examples load from the demo on :4200
-npm test               # Unit tests
-npm run e2e            # E2E tests
-npm run site:build     # Full GitHub Pages build: docs at /, demo at /demo/
-```
+See [CONTRIBUTING.md](https://github.com/gultyayev/ngx-virtual-dnd/blob/master/CONTRIBUTING.md) to run the demo, the docs and the tests locally.
 
 ## License
 

package/fesm2022/ngx-virtual-dnd.mjs

@@ -788,6 +788,8 @@ class DragStateService {
     #placeholderId = signal(null, ...(ngDevMode ? [{ debugName: "#placeholderId" }] : []));
     /** Index where the placeholder should be inserted — updated on each placeholder move */
     #placeholderIndex = signal(null, ...(ngDevMode ? [{ debugName: "#placeholderIndex" }] : []));
+    /** Whether the drag in progress is a touch drag (no cursor shows, so no grabbing cursor) */
+    #isTouchDrag = signal(false, ...(ngDevMode ? [{ debugName: "#isTouchDrag" }] : []));
     /** Snapshot captured synchronously immediately before the last drag state reset. */
     #endedDragState = signal(null, ...(ngDevMode ? [{ debugName: "#endedDragState" }] : []));
     /** Flag indicating if the last drag was cancelled (not dropped) */
@@ -829,37 +831,44 @@ class DragStateService {
     /** Target index during keyboard navigation */
     keyboardTargetIndex = this.#keyboardTargetIndex.asReadonly();
     constructor() {
-        // Inject cursor styles once (for consistent grabbing cursor during drag)
+        // Inject the grabbing cursor styles once. They target lists and items only: a rule matching
+        // every element (`body.vdnd-dragging *`, or a `*` anywhere right of the body class) restyles
+        // the whole document each time the body class changes, at drag start and at drop. Touch drags
+        // show no cursor, so they skip it.
         if (typeof document !== 'undefined') {
             const styleId = 'vdnd-cursor-styles';
             if (!document.getElementById(styleId)) {
                 const style = document.createElement('style');
                 style.id = styleId;
                 style.textContent = `
-          body.vdnd-dragging,
-          body.vdnd-dragging * {
+          body.vdnd-dragging:not(.vdnd-dragging-touch) .vdnd-droppable,
+          body.vdnd-dragging:not(.vdnd-dragging-touch) .vdnd-draggable {
             cursor: grabbing !important;
           }
         `;
                 document.head.appendChild(style);
             }
         }
-        // Effect to toggle body class during drag
+        // Effect to toggle the body classes during drag
         effect(() => {
             if (typeof document === 'undefined')
                 return;
             const isDragging = this.isDragging();
-            document.body.classList.toggle('vdnd-dragging', isDragging);
+            const classList = document.body.classList;
+            classList.toggle('vdnd-dragging', isDragging);
+            classList.toggle('vdnd-dragging-touch', isDragging && this.#isTouchDrag());
         });
     }
     /**
      * 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, cursorPosition, grabOffset, lockAxis, activeDroppableId, placeholderId, placeholderIndex, sourceIndex, isKeyboardDrag, axisLockPosition) {
+    startDrag(item, cursorPosition, grabOffset, lockAxis, activeDroppableId, placeholderId, placeholderIndex, sourceIndex, isKeyboardDrag, axisLockPosition, isTouchDrag) {
         // Reset terminal drag metadata at start of new drag
         this.#endedDragState.set(null);
         this.#wasCancelled.set(false);
+        this.#isTouchDrag.set(isTouchDrag ?? false);
         this.#cursorPosition.set(cursorPosition ?? null);
         this.#keyboardTargetIndex.set(isKeyboardDrag ? (sourceIndex ?? 0) : null);
         this.#activeDroppableId.set(activeDroppableId ?? null);
@@ -941,7 +950,7 @@ class DragStateService {
         const endedState = this.getStateSnapshot();
         this.#endedDragState.set(endedState);
         this.#wasCancelled.set(false);
-        this.#resetHighFrequencySignals();
+        this.#resetSignalsOutsideCoreState();
         this.#state.set(INITIAL_CORE_STATE);
         // After the reset, so the drop handler sees the drag as over. Delivered here rather than
         // from a droppable effect on the next change detection: by then the target may already
@@ -959,18 +968,19 @@ class DragStateService {
         }
         this.#endedDragState.set(this.getStateSnapshot());
         this.#wasCancelled.set(true);
-        this.#resetHighFrequencySignals();
+        this.#resetSignalsOutsideCoreState();
         this.#state.set(INITIAL_CORE_STATE);
     }
     /**
-     * Reset the dedicated high-frequency signals to their initial null state.
+     * Reset the signals kept outside the core state (high-frequency fields, touch flag) to idle.
      */
-    #resetHighFrequencySignals() {
+    #resetSignalsOutsideCoreState() {
         this.#cursorPosition.set(null);
         this.#keyboardTargetIndex.set(null);
         this.#activeDroppableId.set(null);
         this.#placeholderId.set(null);
         this.#placeholderIndex.set(null);
+        this.#isTouchDrag.set(false);
     }
     /**
      * Check if a specific droppable is currently active.
@@ -3018,8 +3028,15 @@ const MIN_SHIFT_PX = 0.5;
  *
  * Call `beforeUpdate()` before the DOM reflects a new drag/placeholder state. When the
  * placeholder moved (or the drag ended), it snapshots every rendered element's visual position, then after
- * the render measures again and plays a compositor-only `transform` animation from the
- * old position to the new one.
+ * the render measures again and plays a `translate` animation from the old position to the
+ * new one.
+ *
+ * The slide animates the individual `translate` property with a replace effect, so it runs
+ * on the compositor (Chromium never composites a `composite: 'add'` keyframe effect) and
+ * composes with any `transform` the consumer sets on the row. `translate` applies before
+ * `transform`, in the parent's coordinate space, where the deltas are measured. A row
+ * that sets its own `translate` gets an additive effect instead, which keeps that value
+ * but is ticked on the main thread.
  *
  * Positions are measured relative to the scroll content, so scrolling (including
  * programmatic scroll in the same tick) never animates. Measurements include any
@@ -3156,36 +3173,51 @@ class ShiftAnimator {
             }
             // Both measurements include the in-flight offset, so the new animation must
             // start from that offset plus the layout delta to continue from the current spot.
-            const current = this.#currentOffset(element);
-            shifts.push({ element, x: dx + current.x, y: dy + current.y });
+            const active = this.#activeShift(element);
+            const remaining = active ? 1 - active.progress : 0;
+            shifts.push({
+                element,
+                x: dx + (active?.shift.x ?? 0) * remaining,
+                y: dy + (active?.shift.y ?? 0) * remaining,
+                // While a slide applies, computed style includes it: keep the decision it was made with.
+                additive: active?.shift.additive ?? this.#hasOwnTranslate(element),
+            });
         }
         // Write phase
         for (const element of stale) {
             this.cancel(element);
         }
         for (const shift of shifts) {
-            this.#start(shift.element, shift.x, shift.y);
+            this.#start(shift);
         }
     }
-    #currentOffset(element) {
-        const running = this.#running.get(element);
+    /**
+     * Whether the row sets its own `translate` (which a replace effect would hide while it
+     * runs). Only read while no slide runs on the element: the computed value would include it.
+     */
+    #hasOwnTranslate(element) {
+        const translate = getComputedStyle(element).translate;
+        return !!translate && translate !== 'none';
+    }
+    /** The element's running slide and its progress, or null when none is in effect. */
+    #activeShift(element) {
+        const shift = this.#running.get(element);
         // Effect-level easing makes `progress` the eased progress, i.e. the fraction travelled.
-        const progress = running?.animation.effect?.getComputedTiming().progress;
-        if (!running || progress === null || progress === undefined) {
-            return { x: 0, y: 0 };
+        // It is null once the animation was cancelled or finished (even before `onfinish` ran).
+        const progress = shift?.animation.effect?.getComputedTiming().progress;
+        if (!shift || progress === null || progress === undefined) {
+            return null;
         }
-        const remaining = 1 - progress;
-        return { x: running.x * remaining, y: running.y * remaining };
+        return { shift, progress };
     }
-    #start(element, x, y) {
+    #start({ element, x, y, additive }) {
         this.#running.get(element)?.animation.cancel();
-        const animation = element.animate([{ transform: `translate(${x}px, ${y}px)` }, { transform: 'translate(0px, 0px)' }], {
+        const animation = element.animate([{ translate: `${x}px ${y}px` }, { translate: '0px 0px' }], {
             duration: this.#duration(),
             easing: this.#config.shiftEasing ?? DEFAULT_SHIFT_EASING,
-            // Layer on top of any transform the consumer already applies to the item.
-            composite: 'add',
+            composite: additive ? 'add' : 'replace',
         });
-        this.#running.set(element, { animation, x, y });
+        this.#running.set(element, { animation, x, y, additive });
         animation.onfinish = () => {
             if (this.#running.get(element)?.animation === animation) {
                 this.#running.delete(element);
@@ -6259,6 +6291,8 @@ class PointerDragHandler {
     #listening = false;
     /** Identifier of the finger that pressed, for touch gestures (other fingers are ignored) */
     #touchId = null;
+    /** Whether the tracked press is a touch (which shows no cursor) */
+    #isTouch = false;
     /** Bound event handlers for cleanup */
     #boundPointerMove = null;
     #boundPointerUp = null;
@@ -6284,6 +6318,13 @@ class PointerDragHandler {
     getStartPosition() {
         return this.#startPosition;
     }
+    /**
+     * Whether the tracked press is a touch. Read by the directive when the drag starts: a touch
+     * drag shows no cursor, so it gets no grabbing cursor.
+     */
+    isTouchPress() {
+        return this.#isTouch;
+    }
     /**
      * Handle pointer down (mouse or touch).
      * Called from the directive's host binding.
@@ -6340,6 +6381,7 @@ class PointerDragHandler {
         }
         this.#isTracking = true;
         this.#pressedId = ctx.draggableId;
+        this.#isTouch = isTouch;
         if (touch) {
             this.#touchId = touch.identifier;
             this.#startPosition = { x: touch.clientX, y: touch.clientY };
@@ -6397,6 +6439,7 @@ class PointerDragHandler {
         this.#pressedId = null;
         this.#startPosition = null;
         this.#touchId = null;
+        this.#isTouch = false;
         this.#deps.callbacks.onPendingChange(false); // Clear pending state on cleanup
         this.#cancelDelayTimer();
         // Nothing to remove unless a press added listeners (most draggables are never pressed; a
@@ -7070,7 +7113,7 @@ class DraggableDirective {
             height: rect.height,
             width: rect.width,
             data: this.vdndDraggableData(),
-        }, position, grabOffset, lockAxis, activeDroppableId, initialPlaceholderId, initialPlaceholderIndex, sourceIndex, undefined, lockAxis ? startPos : undefined);
+        }, position, grabOffset, lockAxis, activeDroppableId, initialPlaceholderId, initialPlaceholderIndex, sourceIndex, undefined, lockAxis ? startPos : undefined, this.#pointerHandler.isTouchPress());
         // Start the scheduler RAF loop (drives pointer-move updates + autoscroll participant).
         // onTick is called each frame: when cursor is dirty, run full #updateDrag.
         this.#scheduler.start((cursor, cursorDirty) => {