dockview-core 6.3.0 → 6.5.0

package/dist/esm/dnd/backend.d.ts

@@ -0,0 +1,70 @@
+import { IDisposable } from '../lifecycle';
+import { DroptargetOptions, IDropTarget } from './droptarget';
+/**
+ * Backend factory surface. Each implementation hides one concrete DnD
+ * mechanism (HTML5 native events, pointer events) behind a uniform set of
+ * `createX` methods.
+ *
+ * The backends are stateless — `html5Backend` and `pointerBackend` below
+ * are exported as module-level singletons so they need no construction
+ * or wiring through the component tree.
+ */
+export interface IDragBackend {
+    /** Stable identifier, mostly for debugging / tests. */
+    readonly kind: 'html5' | 'pointer';
+    createDropTarget(element: HTMLElement, options: DroptargetOptions): IDropTarget;
+    createDragSource(element: HTMLElement, options: DragSourceOptions): IDragSource;
+}
+/**
+ * Visual specification handed to the backend. HTML5 calls `setDragImage`
+ * with `(element, offsetX, offsetY)` and discards the element after a
+ * microtask. Pointer wraps the element in a `PointerGhost` that follows
+ * the cursor for the duration of the drag.
+ */
+export interface IDragGhostSpec {
+    element: HTMLElement;
+    /** Pixels from cursor to ghost's top-left. Default 0. */
+    offsetX?: number;
+    offsetY?: number;
+    /**
+     * Called when the backend is done with the ghost. HTML5 fires it after
+     * the drag-image snapshot is captured (next tick); pointer fires it
+     * when the follow-cursor ghost is removed at drag end. Use for custom
+     * framework renderers that need teardown.
+     */
+    dispose?: () => void;
+}
+export interface DragSourceOptions {
+    /** Populate transfer; returned disposer clears it on drag end. */
+    getData: (event: DragEvent | PointerEvent) => IDisposable;
+    /** Veto a drag at start time. */
+    isCancelled?: (event: DragEvent | PointerEvent) => boolean;
+    createGhost?: (event: DragEvent | PointerEvent) => IDragGhostSpec | undefined;
+    onDragStart?: (event: DragEvent | PointerEvent) => void;
+    onDragEnd?: (event: DragEvent | PointerEvent) => void;
+    /** Initial disabled state; toggle later via `setDisabled`. */
+    disabled?: boolean;
+    /**
+     * Pointer-only. When true (default), the pointer backend ignores mouse
+     * pointers and lets the HTML5 path handle them. HTML5 backend ignores.
+     */
+    touchOnly?: boolean;
+    /**
+     * Pointer-only long-press delay in ms. May be a function so the value
+     * can vary per gesture (e.g. floating-group redock vs docked rearrange).
+     */
+    touchInitiationDelay?: number | (() => number);
+    /** Pointer-only pre-arm movement tolerance in px. May also be a function. */
+    pressTolerance?: number | (() => number);
+    /** Pointer-only movement threshold to promote pointerdown → drag. */
+    threshold?: number;
+}
+export interface IDragSource extends IDisposable {
+    setDisabled(value: boolean): void;
+    /** Pointer-only knob; no-op on HTML5 backend. */
+    setTouchOnly(value: boolean): void;
+    /** Pointer-only; no-op on HTML5 backend. */
+    cancelPending(): void;
+}
+export declare const html5Backend: IDragBackend;
+export declare const pointerBackend: IDragBackend;

package/dist/esm/dnd/backend.js

@@ -0,0 +1,148 @@
+import { addDisposableListener } from '../events';
+import { CompositeDisposable, MutableDisposable, } from '../lifecycle';
+import { Droptarget } from './droptarget';
+import { addGhostImage } from './ghost';
+import { PointerDropTarget } from './pointer/pointerDropTarget';
+import { PointerDragSource } from './pointer/pointerDragSource';
+import { PointerGhost } from './pointer/pointerGhost';
+import { disableIframePointEvents } from '../dom';
+/**
+ * HTML5 drag source. Listens for the native `dragstart` event, calls
+ * `getData` to populate transfer, optionally renders the ghost via
+ * `setDragImage`, fires `onDragStart` / `onDragEnd`, and tears down the
+ * transfer disposer after `dragend`.
+ */
+class Html5DragSource extends CompositeDisposable {
+    constructor(el, opts) {
+        super();
+        this.el = el;
+        this.opts = opts;
+        this._dataDisposable = new MutableDisposable();
+        this._pointerEventsDisposable = new MutableDisposable();
+        this._disabled = !!opts.disabled;
+        this.addDisposables(this._dataDisposable, this._pointerEventsDisposable, addDisposableListener(this.el, 'dragstart', (event) => {
+            var _a, _b, _c, _d, _e, _f, _g, _h, _j;
+            if (event.defaultPrevented ||
+                this._disabled ||
+                ((_b = (_a = this.opts).isCancelled) === null || _b === void 0 ? void 0 : _b.call(_a, event))) {
+                event.preventDefault();
+                return;
+            }
+            // Iframes capture pointermove once the cursor enters them,
+            // which freezes drag tracking from the parent window's
+            // POV. Shield the source's owning document so popout-window
+            // drags shield the popout, not the main window.
+            const iframes = disableIframePointEvents((_c = this.el.ownerDocument) !== null && _c !== void 0 ? _c : document);
+            this._pointerEventsDisposable.value = {
+                dispose: () => iframes.release(),
+            };
+            this.el.classList.add('dv-dragged');
+            setTimeout(() => this.el.classList.remove('dv-dragged'), 0);
+            this._dataDisposable.value = this.opts.getData(event);
+            const ghost = (_e = (_d = this.opts).createGhost) === null || _e === void 0 ? void 0 : _e.call(_d, event);
+            if (ghost && event.dataTransfer) {
+                addGhostImage(event.dataTransfer, ghost.element, {
+                    x: (_f = ghost.offsetX) !== null && _f !== void 0 ? _f : 0,
+                    y: (_g = ghost.offsetY) !== null && _g !== void 0 ? _g : 0,
+                });
+                if (ghost.dispose) {
+                    // addGhostImage removes the element from the DOM on
+                    // the next tick; dispose the framework renderer on
+                    // the same schedule.
+                    const disposeGhost = ghost.dispose;
+                    setTimeout(() => disposeGhost(), 0);
+                }
+            }
+            if (event.dataTransfer) {
+                event.dataTransfer.effectAllowed = 'move';
+                // Some third-party DnD libs (e.g. react-dnd) cancel the
+                // dragstart when `dataTransfer.types` is empty.
+                if (event.dataTransfer.items.length === 0) {
+                    event.dataTransfer.setData('text/plain', '');
+                }
+            }
+            (_j = (_h = this.opts).onDragStart) === null || _j === void 0 ? void 0 : _j.call(_h, event);
+        }), addDisposableListener(this.el, 'dragend', (event) => {
+            var _a, _b;
+            this._pointerEventsDisposable.dispose();
+            // Defer disposal so drop handlers can still read the
+            // transfer payload before it clears.
+            setTimeout(() => this._dataDisposable.dispose(), 0);
+            (_b = (_a = this.opts).onDragEnd) === null || _b === void 0 ? void 0 : _b.call(_a, event);
+        }));
+    }
+    setDisabled(value) {
+        this._disabled = value;
+    }
+    setTouchOnly(_) {
+        // No-op — HTML5 path can't filter by pointer type.
+    }
+    cancelPending() {
+        // No-op — HTML5 has no pre-arm phase to cancel.
+    }
+}
+class Html5DragBackend {
+    constructor() {
+        this.kind = 'html5';
+    }
+    createDropTarget(element, options) {
+        return new Droptarget(element, options);
+    }
+    createDragSource(element, options) {
+        return new Html5DragSource(element, options);
+    }
+}
+class PointerDragBackend {
+    constructor() {
+        this.kind = 'pointer';
+    }
+    createDropTarget(element, options) {
+        return new PointerDropTarget(element, options);
+    }
+    createDragSource(element, options) {
+        const pointerCreateGhost = options.createGhost
+            ? (event) => {
+                const spec = options.createGhost(event);
+                if (!spec) {
+                    return undefined;
+                }
+                const ghost = new PointerGhost({
+                    element: spec.element,
+                    initialX: event.clientX,
+                    initialY: event.clientY,
+                    offsetX: spec.offsetX,
+                    offsetY: spec.offsetY,
+                    owner: element,
+                });
+                if (spec.dispose) {
+                    const baseDispose = ghost.dispose.bind(ghost);
+                    const disposeSpec = spec.dispose;
+                    ghost.dispose = () => {
+                        baseDispose();
+                        disposeSpec();
+                    };
+                }
+                return ghost;
+            }
+            : undefined;
+        const source = new PointerDragSource(element, {
+            getData: options.getData,
+            isCancelled: options.isCancelled,
+            onDragStart: options.onDragStart,
+            onDragEnd: options.onDragEnd
+                ? (event) => options.onDragEnd(event.pointerEvent)
+                : undefined,
+            createGhost: pointerCreateGhost,
+            touchOnly: options.touchOnly,
+            touchInitiationDelay: options.touchInitiationDelay,
+            pressTolerance: options.pressTolerance,
+            threshold: options.threshold,
+        });
+        if (options.disabled) {
+            source.setDisabled(true);
+        }
+        return source;
+    }
+}
+export const html5Backend = new Html5DragBackend();
+export const pointerBackend = new PointerDragBackend();

package/dist/esm/dnd/dropOverlay.d.ts

@@ -0,0 +1,20 @@
+import { DropTargetTargetModel, DroptargetOverlayModel, Position } from './droptarget';
+export interface OverlayElements {
+    dropzone: HTMLElement;
+    selection: HTMLElement;
+}
+export declare function createOverlayElements(): OverlayElements;
+export declare function renderInPlaceOverlay(overlay: HTMLElement, quadrant: Position, width: number, height: number, overlayModel?: DroptargetOverlayModel): void;
+/** `boundsChanged: false` lets callers skip redundant work on tight drag loops. */
+export declare function renderAnchoredOverlay(args: {
+    outlineElement: HTMLElement;
+    targetModel: DropTargetTargetModel;
+    quadrant: Position;
+    width: number;
+    height: number;
+    overlayModel?: DroptargetOverlayModel;
+    className?: string;
+}): {
+    boundsChanged: boolean;
+    targetChanged: boolean;
+};

package/dist/esm/dnd/dropOverlay.js

@@ -0,0 +1,192 @@
+// Two render paths: in-place (dropzone appended to drop element) and
+// anchored (overlay rendered into an external anchor container).
+import { toggleClass } from '../dom';
+import { clamp } from '../math';
+const DEFAULT_SIZE = { value: 50, type: 'percentage' };
+const SMALL_WIDTH_BOUNDARY = 100;
+const SMALL_HEIGHT_BOUNDARY = 100;
+export function createOverlayElements() {
+    const dropzone = document.createElement('div');
+    dropzone.className = 'dv-drop-target-dropzone';
+    const selection = document.createElement('div');
+    selection.className = 'dv-drop-target-selection';
+    dropzone.appendChild(selection);
+    return { dropzone, selection };
+}
+function computeOverlayShape(quadrant, width, height, overlayModel) {
+    var _a, _b, _c;
+    const smallWidthBoundary = (_a = overlayModel === null || overlayModel === void 0 ? void 0 : overlayModel.smallWidthBoundary) !== null && _a !== void 0 ? _a : SMALL_WIDTH_BOUNDARY;
+    const smallHeightBoundary = (_b = overlayModel === null || overlayModel === void 0 ? void 0 : overlayModel.smallHeightBoundary) !== null && _b !== void 0 ? _b : SMALL_HEIGHT_BOUNDARY;
+    const isSmallX = width < smallWidthBoundary;
+    const isSmallY = height < smallHeightBoundary;
+    const isLeft = quadrant === 'left';
+    const isRight = quadrant === 'right';
+    const isTop = quadrant === 'top';
+    const isBottom = quadrant === 'bottom';
+    const rightClass = !isSmallX && isRight;
+    const leftClass = !isSmallX && isLeft;
+    const topClass = !isSmallY && isTop;
+    const bottomClass = !isSmallY && isBottom;
+    let size = 1;
+    const sizeOptions = (_c = overlayModel === null || overlayModel === void 0 ? void 0 : overlayModel.size) !== null && _c !== void 0 ? _c : DEFAULT_SIZE;
+    if (sizeOptions.type === 'percentage') {
+        size = clamp(sizeOptions.value, 0, 100) / 100;
+    }
+    else {
+        if (rightClass || leftClass) {
+            size = clamp(0, sizeOptions.value, width) / width;
+        }
+        if (topClass || bottomClass) {
+            size = clamp(0, sizeOptions.value, height) / height;
+        }
+    }
+    return {
+        isSmallX,
+        isSmallY,
+        isLeft,
+        isRight,
+        isTop,
+        isBottom,
+        rightClass,
+        leftClass,
+        topClass,
+        bottomClass,
+        size,
+    };
+}
+export function renderInPlaceOverlay(overlay, quadrant, width, height, overlayModel) {
+    const shape = computeOverlayShape(quadrant, width, height, overlayModel);
+    const { rightClass, leftClass, topClass, bottomClass, size } = shape;
+    const box = { top: '0px', left: '0px', width: '100%', height: '100%' };
+    if (rightClass) {
+        box.left = `${100 * (1 - size)}%`;
+        box.width = `${100 * size}%`;
+    }
+    else if (leftClass) {
+        box.width = `${100 * size}%`;
+    }
+    else if (topClass) {
+        box.height = `${100 * size}%`;
+    }
+    else if (bottomClass) {
+        box.top = `${100 * (1 - size)}%`;
+        box.height = `${100 * size}%`;
+    }
+    if (shape.isSmallX && shape.isLeft) {
+        box.width = '4px';
+    }
+    if (shape.isSmallX && shape.isRight) {
+        box.left = `${width - 4}px`;
+        box.width = '4px';
+    }
+    if (shape.isSmallY && shape.isTop) {
+        box.height = '4px';
+    }
+    if (shape.isSmallY && shape.isBottom) {
+        box.top = `${height - 4}px`;
+        box.height = '4px';
+    }
+    overlay.style.top = box.top;
+    overlay.style.left = box.left;
+    overlay.style.width = box.width;
+    overlay.style.height = box.height;
+    overlay.style.visibility = 'visible';
+    if (!overlay.style.transform || overlay.style.transform === '') {
+        overlay.style.transform = 'translate3d(0, 0, 0)';
+    }
+    const isLine = (shape.isSmallX && (shape.isLeft || shape.isRight)) ||
+        (shape.isSmallY && (shape.isTop || shape.isBottom));
+    toggleClass(overlay, 'dv-drop-target-small-vertical', shape.isSmallY);
+    toggleClass(overlay, 'dv-drop-target-small-horizontal', shape.isSmallX);
+    toggleClass(overlay, 'dv-drop-target-selection-line', isLine);
+    toggleClass(overlay, 'dv-drop-target-left', shape.isLeft);
+    toggleClass(overlay, 'dv-drop-target-right', shape.isRight);
+    toggleClass(overlay, 'dv-drop-target-top', shape.isTop);
+    toggleClass(overlay, 'dv-drop-target-bottom', shape.isBottom);
+    toggleClass(overlay, 'dv-drop-target-center', quadrant === 'center');
+}
+function checkAnchoredBoundsChanged(overlay, bounds) {
+    const topPx = `${Math.round(bounds.top)}px`;
+    const leftPx = `${Math.round(bounds.left)}px`;
+    const widthPx = `${Math.round(bounds.width)}px`;
+    const heightPx = `${Math.round(bounds.height)}px`;
+    return (overlay.style.top !== topPx ||
+        overlay.style.left !== leftPx ||
+        overlay.style.width !== widthPx ||
+        overlay.style.height !== heightPx);
+}
+function applyAnchoredBounds(overlay, bounds) {
+    overlay.style.top = `${Math.round(bounds.top)}px`;
+    overlay.style.left = `${Math.round(bounds.left)}px`;
+    overlay.style.width = `${Math.round(bounds.width)}px`;
+    overlay.style.height = `${Math.round(bounds.height)}px`;
+    overlay.style.visibility = 'visible';
+    if (!overlay.style.transform || overlay.style.transform === '') {
+        overlay.style.transform = 'translate3d(0, 0, 0)';
+    }
+}
+/** `boundsChanged: false` lets callers skip redundant work on tight drag loops. */
+export function renderAnchoredOverlay(args) {
+    const shape = computeOverlayShape(args.quadrant, args.width, args.height, args.overlayModel);
+    const { rightClass, leftClass, topClass, bottomClass, size } = shape;
+    const elBox = args.outlineElement.getBoundingClientRect();
+    const ta = args.targetModel.getElements(undefined, args.outlineElement);
+    const el = ta.root;
+    const overlay = ta.overlay;
+    const bigbox = el.getBoundingClientRect();
+    const rootTop = elBox.top - bigbox.top;
+    const rootLeft = elBox.left - bigbox.left;
+    const box = {
+        top: rootTop,
+        left: rootLeft,
+        width: args.width,
+        height: args.height,
+    };
+    if (rightClass) {
+        box.left = rootLeft + args.width * (1 - size);
+        box.width = args.width * size;
+    }
+    else if (leftClass) {
+        box.width = args.width * size;
+    }
+    else if (topClass) {
+        box.height = args.height * size;
+    }
+    else if (bottomClass) {
+        box.top = rootTop + args.height * (1 - size);
+        box.height = args.height * size;
+    }
+    if (shape.isSmallX && shape.isLeft) {
+        box.width = 4;
+    }
+    if (shape.isSmallX && shape.isRight) {
+        box.left = rootLeft + args.width - 4;
+        box.width = 4;
+    }
+    if (shape.isSmallY && shape.isTop) {
+        box.height = 4;
+    }
+    if (shape.isSmallY && shape.isBottom) {
+        box.top = rootTop + args.height - 4;
+        box.height = 4;
+    }
+    if (!checkAnchoredBoundsChanged(overlay, box)) {
+        return { boundsChanged: false, targetChanged: ta.changed };
+    }
+    applyAnchoredBounds(overlay, box);
+    overlay.className = `dv-drop-target-anchor${args.className ? ` ${args.className}` : ''}`;
+    toggleClass(overlay, 'dv-drop-target-left', shape.isLeft);
+    toggleClass(overlay, 'dv-drop-target-right', shape.isRight);
+    toggleClass(overlay, 'dv-drop-target-top', shape.isTop);
+    toggleClass(overlay, 'dv-drop-target-bottom', shape.isBottom);
+    toggleClass(overlay, 'dv-drop-target-anchor-line', (shape.isSmallX && (shape.isLeft || shape.isRight)) ||
+        (shape.isSmallY && (shape.isTop || shape.isBottom)));
+    toggleClass(overlay, 'dv-drop-target-center', args.quadrant === 'center');
+    if (ta.changed) {
+        toggleClass(overlay, 'dv-drop-target-anchor-container-changed', true);
+        setTimeout(() => {
+            toggleClass(overlay, 'dv-drop-target-anchor-container-changed', false);
+        }, 10);
+    }
+    return { boundsChanged: true, targetChanged: ta.changed };
+}

package/dist/esm/dnd/droptarget.d.ts

@@ -1,24 +1,25 @@
 import { DockviewEvent, Event } from '../events';
-import { CompositeDisposable } from '../lifecycle';
+import { CompositeDisposable, IDisposable } from '../lifecycle';
 import { DragAndDropObserver } from './dnd';
 import { Direction } from '../gridview/baseComponentGridview';
 export interface DroptargetEvent {
     readonly position: Position;
-    readonly nativeEvent: DragEvent;
+    /** Narrow with `instanceof DragEvent` before reading `dataTransfer`. */
+    readonly nativeEvent: DragEvent | PointerEvent;
 }
 export declare class WillShowOverlayEvent extends DockviewEvent implements DroptargetEvent {
     private readonly options;
-    get nativeEvent(): DragEvent;
+    get nativeEvent(): DragEvent | PointerEvent;
     get position(): Position;
     constructor(options: {
-        nativeEvent: DragEvent;
+        nativeEvent: DragEvent | PointerEvent;
         position: Position;
     });
 }
 export declare function directionToPosition(direction: Direction): Position;
 export declare function positionToDirection(position: Position): Direction;
 export type Position = 'top' | 'bottom' | 'left' | 'right' | 'center';
-export type CanDisplayOverlay = (dragEvent: DragEvent, state: Position) => boolean;
+export type CanDisplayOverlay = (dragEvent: DragEvent | PointerEvent, state: Position) => boolean;
 export type MeasuredValue = {
     value: number;
     type: 'pixels' | 'percentage';
@@ -56,7 +57,20 @@ export interface DroptargetOptions {
     className?: string;
     getOverlayOutline?: () => HTMLElement | null;
 }
-export declare class Droptarget extends CompositeDisposable {
+/**
+ * Backend-agnostic drop target. Both the HTML5 `Droptarget` and the pointer
+ * `PointerDropTarget` implement this shape so consumers can hold one field
+ * regardless of which DnD backend produced it.
+ */
+export interface IDropTarget extends IDisposable {
+    readonly onDrop: Event<DroptargetEvent>;
+    readonly onWillShowOverlay: Event<WillShowOverlayEvent>;
+    readonly state: Position | undefined;
+    disabled: boolean;
+    setTargetZones(zones: Position[]): void;
+    setOverlayModel(model: DroptargetOverlayModel): void;
+}
+export declare class Droptarget extends CompositeDisposable implements IDropTarget {
     private readonly element;
     private readonly options;
     private targetElement;