ngx-kit 9.2.0 → 9.2.2

package/drag-resize/README.md

@@ -110,3 +110,8 @@ Known limits: cross-origin iframes (no coordinate access), iframes clipped by an
 ## Tests
 
 `tests/browser/*.spec.ts` run in real Chromium (Playwright + vitest, set `CHROMIUM_PATH`); `tests/browser/page-builder.spec.ts` covers palette → iframe canvas, iframe scroll/auto-scroll, scaled iframes, editing inside blocks, resizing and export cleanup.
+
+## Keyboard & auto-scroll (kanban boards)
+
+- Focus a card and press an arrow key to lift it. **One press = one slot**; at the edge of a list the card hops to the neighbouring connected list (Left/Right between columns, Up/Down between the sections of a column). Enter drops, Esc cancels.
+- Auto-scroll picks the nearest scroller **per axis**, so a column that scrolls vertically inside a board that scrolls horizontally scrolls both ways; with the pointer outside every list it uses the dragged item's own scrollers.

package/fesm2022/ngx-kit-drag-resize.mjs

@@ -593,6 +593,92 @@ class DragRef {
             this.applyTransform();
         }
     }
+    /**
+     * Keyboard sorting for list items: jump by whole SLOTS instead of pixels (an 8px step can
+     * never cross the centre of a 190px card), and hop to the neighbouring connected list when the
+     * edge of the current one is reached — Left/Right between kanban columns, Up/Down between
+     * the sections of a column. Returns `false` for free drags (use `nudge`).
+     */
+    nudgeToSlot(direction) {
+        if (!this.listDrag)
+            return false;
+        if (!this.isDragging())
+            this.startDrag(this.lastPointer);
+        const list = this.activeDropList;
+        if (!list?.el)
+            return true;
+        const vertical = direction === 'up' || direction === 'down';
+        const sign = direction === 'down' || direction === 'right' ? 1 : -1;
+        const cur = { x: this.startPointer.x + this.moveDx, y: this.startPointer.y + this.moveDy };
+        const listAxis = list.getAxis();
+        // A grid has no single main axis: step through its slots along the pressed key's axis.
+        const axis = listAxis === 'grid' ? (vertical ? 'y' : 'x') : listAxis;
+        let target = null;
+        if ((axis === 'y') === vertical)
+            target = this.neighbourSlot(list, axis, sign, cur);
+        target ??= this.neighbourList(list, vertical ? 'y' : 'x', sign, cur);
+        if (target)
+            this.dragMove(target);
+        return true;
+    }
+    neighbourSlot(list, axis, sign, cur) {
+        const mid = (r) => (axis === 'y' ? r.top + r.height / 2 : r.left + r.width / 2);
+        const slots = Array.from(list.el.children)
+            .filter((n) => n instanceof HTMLElement &&
+            n !== this.el &&
+            !n.classList.contains('ngx-drag-preview') &&
+            n.getClientRects().length > 0)
+            .map((el) => ({ el, r: el.getBoundingClientRect() }))
+            .sort((a, b) => mid(a.r) - mid(b.r));
+        const p = slots.findIndex((s) => s.el.classList.contains('ngx-drag-placeholder'));
+        const next = slots[p + sign];
+        if (p < 0 || !next)
+            return null;
+        // a little PAST the neighbour's centre, beyond the sort hysteresis
+        const past = mid(next.r) + 8 * sign;
+        return axis === 'y' ? { x: cur.x, y: past } : { x: past, y: cur.y };
+    }
+    neighbourList(from, along, sign, cur) {
+        const doc = this.el.ownerDocument;
+        const origin = visibleRect(from.el);
+        if (!origin)
+            return null;
+        let best = null;
+        for (const l of this.cachedLists) {
+            if (l === from || !l.el || l.el.ownerDocument !== doc)
+                continue;
+            const r = visibleRect(l.el);
+            if (!r || r.width < 8 || r.height < 8)
+                continue;
+            const dist = along === 'x'
+                ? (r.left + r.width / 2 - (origin.left + origin.width / 2)) * sign
+                : (r.top + r.height / 2 - (origin.top + origin.height / 2)) * sign;
+            if (dist <= 4)
+                continue;
+            let score;
+            if (along === 'x') {
+                // prefer the list that is level with the pointer
+                const off = Math.max(r.top - cur.y, 0, cur.y - r.bottom);
+                score = dist + off * 0.5;
+            }
+            else {
+                // Up/Down only moves between lists that overlap horizontally (sections of one column)
+                const overlap = Math.min(r.right, origin.right) - Math.max(r.left, origin.left);
+                if (overlap < Math.min(r.width, origin.width) * 0.5)
+                    continue;
+                score = dist;
+            }
+            if (!best || score < best.score)
+                best = { rect: r, score };
+        }
+        if (!best)
+            return null;
+        const r = best.rect;
+        const clamp = (v, lo, hi) => Math.max(lo, Math.min(hi, v));
+        return along === 'y'
+            ? { x: clamp(cur.x, r.left + 8, r.right - 8), y: sign > 0 ? r.top + 8 : r.bottom - 8 }
+            : { x: r.left + r.width / 2, y: clamp(cur.y, r.top + 8, r.bottom - 8) };
+    }
     nudge(dx, dy) {
         if (!this.isDragging())
             this.startDrag(this.lastPointer);
@@ -922,6 +1008,34 @@ function isDescendantOfList(list, ancestor) {
     }
     return false;
 }
+/** The part of `el` that is actually on screen (clipped by scroll containers and the viewport). */
+function visibleRect(el) {
+    const win = el.ownerDocument.defaultView;
+    if (!win)
+        return null;
+    const r = el.getBoundingClientRect();
+    let left = r.left;
+    let top = r.top;
+    let right = r.right;
+    let bottom = r.bottom;
+    for (let n = el.parentElement; n; n = n.parentElement) {
+        const cs = win.getComputedStyle(n);
+        if (cs.overflowX === 'visible' && cs.overflowY === 'visible')
+            continue;
+        const nr = n.getBoundingClientRect();
+        left = Math.max(left, nr.left);
+        top = Math.max(top, nr.top);
+        right = Math.min(right, nr.right);
+        bottom = Math.min(bottom, nr.bottom);
+    }
+    left = Math.max(left, 0);
+    top = Math.max(top, 0);
+    right = Math.min(right, win.innerWidth);
+    bottom = Math.min(bottom, win.innerHeight);
+    if (right <= left || bottom <= top)
+        return null;
+    return { left, top, right, bottom, width: right - left, height: bottom - top };
+}
 
 class ElementHelper {
     static collectionHas(a, b) {
@@ -1713,6 +1827,10 @@ class DropListRef {
     parentList = null;
     childLists = new Set();
     session = null;
+    /** Main axis of this list: the measured one while sorting, else a CSS-based guess. */
+    getAxis() {
+        return this.session?.axis ?? fallbackAxis(this.el);
+    }
     placeholder;
     customPlaceholder;
     activeDrag = null;
@@ -2436,11 +2554,14 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.4", ngImpor
  */
 class AutoScroller {
     raf = 0;
-    container;
+    /** Nearest scroller per axis: a kanban column scrolls vertically while its BOARD scrolls horizontally. */
+    containerX;
+    containerY;
     win;
     /** Document the pointer coordinates (`update(x, y)`) are expressed in. */
     pointerDoc;
     speed = { x: 0, y: 0 };
+    carry = { x: 0, y: 0 };
     onTick;
     edge;
     maxSpeed;
@@ -2452,60 +2573,84 @@ class AutoScroller {
     start(fromEl, onTick) {
         this.win = fromEl.ownerDocument.defaultView ?? undefined;
         this.pointerDoc = fromEl.ownerDocument;
-        this.container = findScrollableAncestor(fromEl);
+        this.retarget(fromEl);
         this.onTick = onTick;
     }
     /** فقط container را عوض می‌کند بدون قطع حلقه‌ی در حال اجرا یا صفر کردن speed. */
     retarget(fromEl) {
-        this.container = findScrollableAncestor(fromEl);
+        this.containerX = findScrollableAncestorForAxis(fromEl, 'x');
+        this.containerY = findScrollableAncestorForAxis(fromEl, 'y');
     }
     update(clientX, clientY) {
+        this.speed = {
+            x: this.axisSpeed(this.containerX, 'x', clientX, clientY),
+            y: this.axisSpeed(this.containerY, 'y', clientX, clientY),
+        };
+        if ((this.speed.x || this.speed.y) && !this.raf) {
+            this.raf = this.win?.requestAnimationFrame(this.tick) ?? 0;
+        }
+    }
+    axisSpeed(container, axis, clientX, clientY) {
         // The scroll container may live in another document (a page-builder iframe). Its rect is in
         // THAT document's viewport pixels, so bring the pointer into the same space first.
         let x = clientX;
         let y = clientY;
-        const containerDoc = documentOf(this.container);
+        const containerDoc = documentOf(container);
         if (this.pointerDoc && containerDoc && containerDoc !== this.pointerDoc) {
             const p = convertPointBetweenDocuments({ x, y }, this.pointerDoc, containerDoc);
-            if (!p) {
-                this.speed = { x: 0, y: 0 };
-                return;
-            }
+            if (!p)
+                return 0;
             x = p.x;
             y = p.y;
         }
-        const rect = getScrollRect(this.container);
-        this.speed = {
-            x: edgeSpeed(x, rect.left, rect.right, this.edge, this.maxSpeed),
-            y: edgeSpeed(y, rect.top, rect.bottom, this.edge, this.maxSpeed),
-        };
-        if ((this.speed.x || this.speed.y) && !this.raf) {
-            this.raf = this.win?.requestAnimationFrame(this.tick) ?? 0;
-        }
+        const rect = getScrollRect(container);
+        return axis === 'x'
+            ? edgeSpeed(x, rect.left, rect.right, this.edge, this.maxSpeed)
+            : edgeSpeed(y, rect.top, rect.bottom, this.edge, this.maxSpeed);
     }
     stop() {
         if (this.raf)
             this.win?.cancelAnimationFrame(this.raf);
         this.raf = 0;
         this.speed = { x: 0, y: 0 };
+        this.carry = { x: 0, y: 0 };
         this.onTick = undefined;
         this.win = undefined;
         this.pointerDoc = undefined;
     }
+    /** Scrolls one container by a speed measured in viewport pixels (carrying sub-pixel remainders). */
+    scrollContainer(container, sx, sy) {
+        if (!sx && !sy)
+            return;
+        // An element's scrollLeft/Top are local to it; a window's are viewport pixels already.
+        const local = isWindow(container)
+            ? { x: sx, y: sy }
+            : viewportDeltaToLocal(container, { x: sx, y: sy });
+        // Browsers snap scroll offsets to whole pixels, so a slow speed (< 1px/frame, i.e. when the
+        // pointer has just entered the edge zone) would never move anything. Carry the remainder.
+        this.carry.x += local.x;
+        this.carry.y += local.y;
+        const dx = Math.trunc(this.carry.x);
+        const dy = Math.trunc(this.carry.y);
+        this.carry.x -= dx;
+        this.carry.y -= dy;
+        // `behavior: 'instant'` matters: with `scroll-behavior: smooth` on <html> or on the scroller
+        // (very common in apps) every per-frame scroll would start a new animation that cancels the
+        // previous one, and the list would not move at all.
+        if (dx || dy)
+            container.scrollBy({ left: dx, top: dy, behavior: 'instant' });
+    }
     tick = () => {
         if (!this.speed.x && !this.speed.y) {
             this.raf = 0;
             return;
         }
-        const container = this.container;
-        if (isWindow(container)) {
-            container.scrollBy(this.speed.x, this.speed.y);
+        if (this.containerX === this.containerY) {
+            this.scrollContainer(this.containerX, this.speed.x, this.speed.y);
         }
         else {
-            // Edge speed is measured in viewport pixels; scrollLeft/Top are local to the scroller.
-            const local = viewportDeltaToLocal(container, this.speed);
-            container.scrollLeft += local.x;
-            container.scrollTop += local.y;
+            this.scrollContainer(this.containerX, this.speed.x, 0);
+            this.scrollContainer(this.containerY, 0, this.speed.y);
         }
         // Pointer ثابت مانده ولی محتوا اسکرول شده؛
         // بنابراین موقعیت placeholder/sort را دوباره محاسبه کن.
@@ -2548,7 +2693,8 @@ function findScrollableAncestor(el) {
             break;
         const style = win.getComputedStyle(node);
         const scrollable = /(auto|scroll|overlay)/.test(style.overflowY + style.overflowX);
-        if (scrollable && (node.scrollHeight > node.clientHeight || node.scrollWidth > node.clientWidth)) {
+        if (scrollable &&
+            (node.scrollHeight > node.clientHeight || node.scrollWidth > node.clientWidth)) {
             // <html>/<body> scroll the whole document: their own rect spans the full (tall) page, so
             // edge detection must use the window's viewport instead.
             const doc = node.ownerDocument;
@@ -2560,6 +2706,26 @@ function findScrollableAncestor(el) {
     }
     return el.ownerDocument.defaultView ?? el;
 }
+/** Nearest ancestor that can scroll along ONE axis (`<html>`/`<body>` resolve to the window). */
+function findScrollableAncestorForAxis(el, axis) {
+    let node = el;
+    while (node) {
+        const win = node.ownerDocument.defaultView;
+        if (!win)
+            break;
+        const style = win.getComputedStyle(node);
+        const overflow = axis === 'x' ? style.overflowX : style.overflowY;
+        const canScroll = axis === 'x' ? node.scrollWidth > node.clientWidth : node.scrollHeight > node.clientHeight;
+        if (/(auto|scroll|overlay)/.test(overflow) && canScroll) {
+            const doc = node.ownerDocument;
+            if (node === doc.documentElement || node === doc.body)
+                return win;
+            return node;
+        }
+        node = node.parentElement;
+    }
+    return el.ownerDocument.defaultView ?? el;
+}
 function getScrollPosition(container) {
     if (isWindow(container)) {
         return { left: container.scrollX, top: container.scrollY };
@@ -2772,7 +2938,7 @@ class NgxDraggable {
             const after = this._ref.activeDropList;
             // Follow the hovered list; outside every list, scroll the page.
             if (after !== before)
-                this.scroller.retarget(after?.el ?? this._ref.el.ownerDocument.body);
+                this.scroller.retarget(after?.el ?? this._ref.dropList?.el ?? this._ref.el);
         }
         this.dragMove.emit(p);
     }
@@ -2944,7 +3110,13 @@ class NgxDraggable {
                 this.beginKeyboardSession();
                 this.dragStart.emit(origin);
             }
-            this._ref.nudge(delta.x, delta.y);
+            // Holding the key down repeats faster than the 200ms slide animation settles.
+            if (e.repeat && this._ref.isListDrag)
+                return;
+            const name = { ArrowLeft: 'left', ArrowRight: 'right', ArrowUp: 'up', ArrowDown: 'down' }[e.key];
+            // List items hop by whole slots / neighbouring lists; free drags move by `keyboardStep` px.
+            if (!this._ref.nudgeToSlot(name))
+                this._ref.nudge(delta.x, delta.y);
             this.dragMove.emit(this._ref.pointer);
             return;
         }
@@ -3732,5 +3904,5 @@ function getCleanHtml(el, options) {
  * Generated bundle index. Do not edit.
  */
 
-export { AutoScroller, DragDropService, DragRef, DropListGroupRef, DropListRef, NGX_DRAGGABLE, NGX_DRAG_PREVIEW, NGX_DROPLIST, NGX_DROPLIST_GROUP, NGX_PLACEHOLDER, NgxDragPreview, NgxDraggable, NgxDropList, NgxDropListGroup, NgxPlaceholder, NgxResizable, PlaceHolderRef, adjustForZoom, checkBoundX, checkBoundY, clampResizeWithinBoundary, copyArrayItem, findScrollableAncestor, getCleanHtml, getPageZoom, getScrollPosition, isRtl, moveItemInArray, resolveLogicalDirection, stripEditorArtifacts, transferArrayItem };
+export { AutoScroller, DragDropService, DragRef, DropListGroupRef, DropListRef, NGX_DRAGGABLE, NGX_DRAG_PREVIEW, NGX_DROPLIST, NGX_DROPLIST_GROUP, NGX_PLACEHOLDER, NgxDragPreview, NgxDraggable, NgxDropList, NgxDropListGroup, NgxPlaceholder, NgxResizable, PlaceHolderRef, adjustForZoom, checkBoundX, checkBoundY, clampResizeWithinBoundary, copyArrayItem, findScrollableAncestor, findScrollableAncestorForAxis, getCleanHtml, getPageZoom, getScrollPosition, isRtl, moveItemInArray, resolveLogicalDirection, stripEditorArtifacts, transferArrayItem };
 //# sourceMappingURL=ngx-kit-drag-resize.mjs.map