dnd-manager 1.1.0 → 1.3.0

package/dist/index.d.mts

@@ -18,6 +18,24 @@ type DragDropConfig = {
    * dragThreshold: 15  // Harder to start drag (better for mobile scroll)
    */
   dragThreshold?: number;
+  /**
+   * Milliseconds a press must be held, moving at most `dragDelayTolerance`, before it becomes a
+   * drag: a long press, so a touch list still scrolls under a swiping finger. A number applies to
+   * every pointer type; an object sets it per type (`{ touch: 250 }`: a mouse still drags at once).
+   * Moving further during the delay releases the press and leaves the gesture to the browser. Once
+   * the delay passes the drag starts at once, without waiting for a move.
+   * @default 0
+   */
+  dragDelay?: number | {
+    mouse?: number;
+    pen?: number;
+    touch?: number;
+  };
+  /**
+   * Pixels a press may move during `dragDelay` before it is released.
+   * @default 5
+   */
+  dragDelayTolerance?: number;
   /**
    * Maximum distance in pixels between pointerdown and pointerup to treat as a click/tap.
    * Used to distinguish intentional clicks from cancelled drag attempts.
@@ -29,8 +47,11 @@ type DragDropConfig = {
    */
   clickThreshold?: number;
   /**
-   * Distance in pixels from viewport edge that triggers auto-scrolling during drag.
-   * When dragging near screen edges, the window automatically scrolls.
+   * Distance in pixels from an edge that triggers auto-scrolling during drag.
+   * Near an edge of the closest scroll container under the pointer that can still scroll that way
+   * (an `overflow: auto | scroll` element), that container scrolls; its zone is at most a quarter
+   * of its size. Otherwise the window scrolls near the viewport's edges. Scrolling continues while
+   * the pointer rests in the zone.
    * @default 100
    * @example
    * scrollThreshold: 50   // Start scrolling closer to edges
@@ -38,8 +59,8 @@ type DragDropConfig = {
    */
   scrollThreshold?: number;
   /**
-   * Scroll speed in pixels per animation frame during auto-scroll.
-   * Higher values = faster scrolling when dragging near viewport edges.
+   * Scroll speed in pixels per animation frame during auto-scroll (`0` disables it).
+   * Higher values = faster scrolling when dragging near edges.
    * @default 10
    * @example
    * scrollSpeed: 5   // Slower, smoother scroll
@@ -59,34 +80,79 @@ type DragDropConfig = {
    */
   cancelOnPointerLeave?: boolean;
   /**
-   * The `data-kind` attribute value for draggable elements.
-   * Elements with this attribute can be picked up and dragged.
+   * The `data-kind` value(s) for draggable elements.
+   * Can be a single kind or multiple kinds.
+   * Each draggable element should still expose a single `data-kind` value.
    * @example
    * draggableKind: 'cell'       // <div data-kind="cell">
+   * draggableKind: ['quest', 'bounty'] // <div data-kind="quest">
    * draggableKind: 'card'       // <div data-kind="card">
    * draggableKind: 'list-item'  // <div data-kind="list-item">
    */
-  draggableKind: string;
+  draggableKind: string | string[];
   /**
-   * The `data-kind` attribute value for droppable target elements.
-   * Elements with this attribute can receive dropped items.
+   * The `data-kind` value(s) for droppable target elements.
+   * Can be a single kind or multiple kinds.
+   * Elements with matching kinds can receive dropped items.
+   * Each droppable element should still expose a single `data-kind` value.
    * Often the same as `draggableKind` for reorderable lists.
    * @example
    * droppableKind: 'cell'   // Can drop on cells
+   * droppableKind: ['quest', 'bounty'] // Can drop on either kind
    * droppableKind: 'zone'   // Can drop on zones
    */
-  droppableKind: string;
+  droppableKind: string | string[];
+  /**
+   * Where droppables are looked for under the pointer.
+   * - `'document'`: anywhere in the page, so items can move to another manager's container (a box
+   *   and a party panel each with its own manager).
+   * - `'container'`: only inside this manager's container, for independent widgets on one page
+   *   that share kinds.
+   * @default 'document'
+   */
+  dropScope?: 'document' | 'container';
+  /**
+   * Keyboard pick-and-place. Space or Enter on a focused draggable (make it focusable: a
+   * `<button>`, or `tabindex="0"`) picks it up; the arrow keys move the target to the nearest
+   * droppable in that direction (scrolled into view); Space or Enter drops there (ignored on a
+   * target `canDrop` rejects); Escape cancels (whatever `cancelOnEscape` says), and so do Tab and
+   * focus leaving the source. The callbacks fire as for a pointer drag, `onDragMove` with the
+   * target's center. Announce the moves from them in an `aria-live` region.
+   * @default false
+   */
+  keyboard?: boolean;
+  /**
+   * Let a press focus the draggable, as a click would. By default the manager cancels the
+   * `pointerdown`, which keeps the browser from selecting text or dragging an image natively, but
+   * also from moving focus. With `true` it cancels `selectstart` and `dragstart` during the press
+   * instead: the source is focused (no focus ring for a mouse, per `:focus-visible`), so focus
+   * styles, keyboard follow-ups and a virtual list that keeps its focused row rendered all work.
+   * @default false
+   */
+  focusOnPress?: boolean;
 };
 type PointerPosition = {
   x: number;
   y: number;
 };
+/** Result passed to onDragEnd when the item was dropped on a valid target; null when drag was cancelled or dropped on invalid target. */
+type DragEndResult<TItem, TPosition> = {
+  sourcePosition: TPosition;
+  targetPosition: TPosition;
+  sourceItem: TItem;
+};
 type DragDropCallbacks<TItem, TPosition> = {
-  /** Called when determining if an element can be dragged */canDrag?: (element: HTMLElement, position: TPosition) => boolean; /** Called when drag starts (after threshold is met) */
-  onDragStart?: (element: HTMLElement, position: TPosition, item: TItem) => void; /** Called continuously during drag */
+  /** Called when determining if an element can be dragged */canDrag?: (element: HTMLElement, position: TPosition) => boolean;
+  /**
+   * Called for the droppable under the pointer on every drag frame, and again at the drop: return
+   * `false` to reject it. A rejected droppable gets `data-drop-invalid` instead of `data-hovered`,
+   * and a drop on it ends the drag with `onDragEnd(null)`. Keep it cheap.
+   */
+  canDrop?: (sourcePosition: TPosition, targetPosition: TPosition, sourceItem: TItem) => boolean; /** Called when drag starts (after threshold is met) */
+  onDragStart?: (element: HTMLElement, position: TPosition, item: TItem) => void; /** Called continuously during drag, with the droppable that would receive a drop (or null) */
   onDragMove?: (pos: PointerPosition, hoveredElement: HTMLElement | null) => void; /** Called when item is dropped on a valid target */
-  onDrop?: (sourcePosition: TPosition, targetPosition: TPosition, sourceItem: TItem) => void; /** Called when drag ends (regardless of success) */
-  onDragEnd?: () => void; /** Called on simple click/tap (no drag) */
+  onDrop?: (sourcePosition: TPosition, targetPosition: TPosition, sourceItem: TItem) => void; /** Called when drag ends (success or cancel). Receives drop result when dropped on valid target, null otherwise. Use for reordering DOM/state and cleanup. */
+  onDragEnd?: (result: DragEndResult<TItem, TPosition> | null) => void; /** Called on simple click/tap (no drag) */
   onClick?: (element: HTMLElement, position: TPosition) => void; /** Called to extract item data from an element */
   getItemData?: (element: HTMLElement, position: TPosition) => TItem | null; /** Called to get the custom position/coordinates of an element */
   getItemPosition: (element: HTMLElement, kind: string) => TPosition | null;
@@ -96,36 +162,112 @@ type DragState<TItem, TPosition> = {
   sourceElement: HTMLElement | null;
   sourcePosition: TPosition | null;
   sourceItem: TItem | null;
-  activePointerId: number | null;
+  activePointerId: number | null; /** What drives the current press or drag. */
+  input: 'pointer' | 'keyboard' | null;
   isDragging: boolean;
-  lastHoveredElement: HTMLElement | null;
+  lastHoveredElement: HTMLElement | null; /** The droppable under the pointer that `canDrop` rejected (marked `data-drop-invalid`). */
+  lastInvalidElement: HTMLElement | null; /** Set when drop on valid target; passed to onDragEnd in cleanup */
+  lastDropResult: DragEndResult<TItem, TPosition> | null;
 };
 declare class DragDropManager<TItem = unknown, TPosition = unknown> {
   private container;
   private config;
+  private draggableKinds;
+  private droppableKinds;
   private callbacks;
   private state;
   private rafId;
   private lastPointerPos;
+  /**
+   * Set while a drag holds the pointer down: the browser follows the release with a native
+   * `click` (on the source element under pointer capture), which must not activate it.
+   */
+  private suppressClickOnRelease;
+  private releaseClickBlocker;
+  /** The pending `dragDelay` of the current press. */
+  private delayTimer;
+  private activePointerType;
+  /** The droppable a keyboard drag points at. */
+  private keyboardTarget;
+  /**
+   * The key that picked up or dropped: its `keyup` would activate a focused button (Space clicks
+   * on keyup), so it is swallowed.
+   */
+  private swallowKeyUp;
   private boundHandlers;
   constructor(containerRef: {
     current: HTMLElement | null;
   } | string | HTMLElement, config: DragDropConfig, callbacks: DragDropCallbacks<TItem, TPosition>);
   private attachListeners;
+  /**
+   * The source position and item of the draggable `match`, if it may be dragged: it has a
+   * position, is not `data-empty`, `canDrag` allows it and it has item data.
+   */
+  private resolveSource;
   private handlePointerDown;
   private handlePointerMove;
+  private startDrag;
+  /** The `dragDelay` for a pointer type (`''` from a constructed event counts as a mouse). */
+  private delayFor;
+  /**
+   * Once a touch press is a drag, the finger moves the item, not the page: a browser that starts
+   * panning would cancel the pointer. Before that, touches stay the browser's.
+   */
+  private handleTouchMove;
+  /**
+   * The press's pointer events, heard on the source itself. While it is in the DOM they also reach
+   * the window's listeners, which handle them; once it is detached only these hear them.
+   */
+  private handleDetachedSourcePointer;
+  /** A long press opens no context menu (Android, iOS) while it is a drag or about to be one. */
+  private handleContextMenu;
+  private scheduleFrame;
+  /** One drag frame: hover feedback, auto-scroll and `onDragMove` at the latest pointer position. */
+  private runFrame;
   private handlePointerUp;
   private handlePointerCancel;
   private handleKeyDown;
   private handleMouseOut;
-  private handleAutoScroll;
+  /** Space or Enter on a focused draggable picks it up (`keyboard: true`). */
+  private handlePickUpKey;
+  /** The keys of a keyboard drag, ahead of anything else on the page. */
+  private handleKeyboardDragKey;
+  private handleKeyUp;
+  /** Focus leaving the source (Tab, a click elsewhere) cancels a keyboard drag. */
+  private handleFocusOut;
+  /** Makes `match` the keyboard drag's target: marked, scrolled into view, sent to `onDragMove`. */
+  private pointKeyboardAt;
+  /**
+   * The droppable nearest the current target (or the source) in a direction: its center lies that
+   * way, and it is closest along the axis, with distance across the axis counting double, so the
+   * next cell in the same row or column wins over a diagonal one.
+   */
+  private nearestDroppable;
+  /** Drops a keyboard drag on its target, unless there is none or `canDrop` rejects it. */
+  private dropWithKeyboard;
+  /**
+   * Swallows the `click` the browser dispatches right after the release that ended a drag, in the
+   * same task; a timeout lets the blocker go when no click comes.
+   */
+  private blockNextClick;
   private cleanup;
   private getPointerId;
   private isActivePointer;
+  private normalizeKindList;
+  /** The target position of the droppable `match` if the current source may drop there. */
+  private acceptedPosition;
+  /**
+   * Marks the droppable under the pointer: `data-hovered` when it would receive a drop (also the
+   * source itself, for "drag over itself" styling), `data-drop-invalid` when `canDrop` rejects it.
+   * Without `canDrop` every droppable is marked hovered.
+   */
+  private markTarget;
+  /** The droppable around `element` (the one under the pointer), within `dropScope`. */
+  private findDroppable;
   /**
-   * Find closest ancestor element with matching data-kind attribute
+   * Find closest ancestor element with a `data-kind` matching any expected kind.
    */
-  private findElementByKind;
+  private findElementByKinds;
   /**
    * Calculate distance between two points
    */
@@ -163,5 +305,5 @@ declare class DragPreviewController {
   destroy(): void;
 }
 //#endregion
-export { type DragDropCallbacks, type DragDropConfig, DragDropManager, DragPreviewController, type DragPreviewControllerOptions, type PointerPosition };
+export { type DragDropCallbacks, type DragDropConfig, DragDropManager, type DragEndResult, DragPreviewController, type DragPreviewControllerOptions, type PointerPosition };
 //# sourceMappingURL=index.d.mts.map