Refactor tile manager's drag and drop to use pointer events (#1557)

* Emulate native drag and drop using PointerEvent API
providing touch-based drag and drop behavior.
* Improved the deferred drag operations for tiles by moving
the drag ghost into a separate layer, simplifying some internal implementation logic.
* Use view transitions for drag operations for better UX.
* Added a dragMode property to control if and how drag operations are done in the tile manager.
* Added a resizeMode property to control if and how resize operations are done in the tile manager.

---------

Co-authored-by: Radoslav Karaivanov <[email protected]>

Author: mtsvyatkova

src/components/common/context.ts

@@ -6,13 +6,12 @@ import type IgcTileManagerComponent from '../tile-manager/tile-manager.js';
 import type IgcTileComponent from '../tile-manager/tile.js';
 
 export type TileManagerContext = {
-  /** The igc-tile-manager element providing the context. */
+  /** The igc-tile-manager instance. */
   instance: IgcTileManagerComponent;
   /** The internal CSS grid container of the igc-tile-manager. */
   grid: Ref<HTMLElement>;
-  /** The igc-tile element being dragged. */
-  draggedItem: IgcTileComponent | null;
-  lastSwapTile: IgcTileComponent | null;
+  /** The internal igc-tile-manager overlay container. */
+  overlay: Ref<HTMLElement>;
 };
 
 export type TileContext = {

src/components/common/controllers/async-consumer.ts

@@ -7,6 +7,7 @@ import type {
 
 type AsyncContextOptions<T extends Context<unknown, unknown>> = {
   context: T;
+  callback?: (value: ContextType<T>, dispose?: () => void) => void;
   subscribe?: boolean;
 };
 
@@ -39,6 +40,7 @@ export class AsyncContextConsumer<
     if (!this._consumer) {
       this._consumer = new ContextConsumer(this._host, {
         context: this._options.context,
+        callback: this._options.callback,
         subscribe: this._options.subscribe,
       });
     }
@@ -48,9 +50,14 @@ export class AsyncContextConsumer<
 export function createAsyncContext<
   T extends Context<unknown, unknown>,
   Host extends ReactiveControllerHost & LitElement,
->(host: Host, context: T): AsyncContextConsumer<T, Host> {
+>(
+  host: Host,
+  context: T,
+  callback?: (value: ContextType<T>, dispose?: () => void) => void
+): AsyncContextConsumer<T, Host> {
   return new AsyncContextConsumer(host, {
     context,
+    callback,
     subscribe: true,
   }) as AsyncContextConsumer<T, Host>;
 }

src/components/common/controllers/drag-and-drop.ts

@@ -0,0 +1,345 @@
+import type {
+  LitElement,
+  ReactiveController,
+  ReactiveControllerHost,
+} from 'lit';
+import type { Ref } from 'lit/directives/ref.js';
+import { findElementFromEventPath } from '../util.js';
+
+type DragDropCallback = () => unknown;
+
+type DragEnterCallback = (target: Element) => unknown;
+
+type DragDropConfig = {
+  /** Whether the drag and drop feature is enabled for the current host. */
+  enabled?: boolean;
+  /**
+   * The mode of the drag and drop operation.
+   *
+   * Deferred will create a ghost element and keep the original element
+   * at its place until the operation completes successfully.
+   */
+  mode?: 'immediate' | 'deferred';
+  /**
+   * Whether drag operation should snap the dragged item top left corner
+   * to the cursor position.
+   */
+  snapToCursor?: boolean;
+  /**
+   * Guard function invoked during the `dragStart` callback.
+   * Returning a truthy value will stop the current drag and drop operation.
+   */
+  skip?: (event: PointerEvent) => boolean;
+  // REVIEW: API signature
+  matchTarget?: (target: Element) => boolean;
+  /**
+   *
+   */
+  trigger?: () => HTMLElement;
+  /**
+   * Contain drag and drop operations to the scope of the passed DOM element.
+   */
+  container?: Ref<HTMLElement>;
+  /**
+   * The DOM element that will "host" the ghost drag element when the controller
+   * is set to **deferred**.
+   *
+   * @remarks
+   * In **immediate** mode, this property is ignored.
+   */
+  layer?: () => HTMLElement;
+
+  ghost?: () => HTMLElement;
+
+  /** Callback invoked at the beginning of a drag operation. */
+  dragStart?: DragDropCallback;
+  /** Callback invoked while dragging the target element.  */
+  dragMove?: DragDropCallback;
+
+  dragEnter?: DragEnterCallback;
+
+  dragLeave?: DragEnterCallback;
+
+  dragOver?: DragEnterCallback;
+
+  /** Callback invoked during a drop operation. */
+  dragEnd?: DragDropCallback;
+  /** Callback invoked when a drag and drop is cancelled */
+  dragCancel?: unknown;
+};
+
+const additionalEvents = ['pointermove', 'lostpointercapture'] as const;
+
+class DragDropController implements ReactiveController {
+  private _host: ReactiveControllerHost & LitElement;
+  private _config: DragDropConfig = {
+    enabled: true,
+    mode: 'deferred',
+    snapToCursor: false,
+  };
+
+  private _dragOffset = { dx: 0, dy: 0 };
+  private _previousMatch!: Element | null;
+
+  private _id = -1;
+  private _hasPointerCapture = false;
+
+  private _ghost: HTMLElement | null = null;
+
+  /** Whether `snapToCursor` is enabled for the controller. */
+  private get _hasSnapping(): boolean {
+    return Boolean(this._config.snapToCursor);
+  }
+
+  /** Whether the current drag mode is deferred. */
+  private get _isDeferred(): boolean {
+    return this._config.mode === 'deferred';
+  }
+
+  /**
+   * The source element which will capture pointer events and initiate drag mode.
+   *
+   * @remarks
+   * By default that will be the host element itself, unless `trigger` is passed in.
+   */
+  private get _element(): HTMLElement {
+    return this._config.trigger?.() ?? this._host;
+  }
+
+  /**
+   * The element being dragged.
+   *
+   * @remarks
+   * When in **deferred** mode this returns a reference to the drag ghost element,
+   * otherwise it is the host element.
+   */
+  private get _dragItem(): HTMLElement {
+    return this._isDeferred ? this._ghost! : this._host;
+  }
+
+  /**
+   * The DOM element that will "host" the ghost drag element when the controller
+   * is set to **deferred**.
+   *
+   * @remarks
+   * In **immediate** mode, this property is ignored.
+   */
+  private get _layer(): HTMLElement {
+    if (!this._isDeferred) {
+      return this._host;
+    }
+
+    return this._config.layer?.() ?? this._host;
+  }
+
+  /** Whether the drag controller is enabled. */
+  public get enabled(): boolean {
+    return Boolean(this._config.enabled);
+  }
+
+  constructor(
+    host: ReactiveControllerHost & LitElement,
+    config?: DragDropConfig
+  ) {
+    this._host = host;
+    this._host.addController(this);
+    this.setConfig(config);
+  }
+
+  private _setInitialState({
+    pointerId,
+    clientX,
+    clientY,
+  }: PointerEvent): void {
+    const rect = this._host.getBoundingClientRect();
+
+    this._id = pointerId;
+
+    this._dragOffset = {
+      dx: rect.x - clientX,
+      dy: rect.y - clientY,
+    };
+  }
+
+  private _setPointerCaptureState(state: boolean): void {
+    this._hasPointerCapture = state;
+    const cssValue = state ? 'none' : '';
+
+    Object.assign(this._element.style, {
+      touchAction: cssValue,
+      userSelect: cssValue,
+    });
+
+    state
+      ? this._element.setPointerCapture(this._id)
+      : this._element.releasePointerCapture(this._id);
+
+    // Toggle additional events
+    for (const type of additionalEvents) {
+      state
+        ? this._host.addEventListener(type, this)
+        : this._host.removeEventListener(type, this);
+    }
+  }
+
+  // REVIEW
+  private _updateMatcher(event: PointerEvent) {
+    if (!this._config.matchTarget) {
+      return;
+    }
+
+    const match = document
+      .elementsFromPoint(event.clientX, event.clientY)
+      .find((value) => this._config.matchTarget!.call(this._host, value));
+
+    if (match && !this._previousMatch) {
+      this._previousMatch = match;
+      this._config.dragEnter?.call(this._host, this._previousMatch);
+      return;
+    }
+
+    if (!match && this._previousMatch) {
+      this._config.dragLeave?.call(this._host, this._previousMatch);
+      this._previousMatch = null;
+      return;
+    }
+
+    if (match && match === this._previousMatch) {
+      this._config.dragOver?.call(this._host, this._previousMatch);
+    }
+  }
+
+  private _setPosition(x: number, y: number) {
+    const { top, left } = this._layer.getBoundingClientRect();
+    const posX = this._hasSnapping ? x - left : x - left + this._dragOffset.dx;
+    const posY = this._hasSnapping ? y - top : y - top + this._dragOffset.dy;
+
+    this._dragItem.style.transform = `translate(${posX}px,${posY}px)`;
+  }
+
+  private _createDragGhost({ clientX, clientY }: PointerEvent): void {
+    this._ghost = this._config.ghost
+      ? this._config.ghost.call(this._host)
+      : createDefaultDragGhost(this._host.getBoundingClientRect());
+
+    this._setPosition(clientX, clientY);
+    this._layer.append(this._ghost);
+  }
+
+  private _removeGhost(): void {
+    if (this._ghost) {
+      this._ghost.remove();
+      this._ghost = null;
+    }
+  }
+
+  private _shouldSkip(event: PointerEvent): boolean {
+    return (
+      this._config.skip?.call(this._host, event) ||
+      !findElementFromEventPath((e) => e === this._element, event)
+    );
+  }
+
+  private _handlePointerDown(event: PointerEvent): void {
+    if (this._shouldSkip(event)) {
+      return;
+    }
+
+    // REVIEW
+    event.preventDefault();
+
+    this._setInitialState(event);
+    this._createDragGhost(event);
+
+    this._config.dragStart?.call(this._host);
+    this._setPointerCaptureState(true);
+  }
+
+  private _handlePointerMove(event: PointerEvent): void {
+    if (!this._hasPointerCapture) {
+      return;
+    }
+
+    this._updateMatcher(event);
+    this._config.dragMove?.call(this._host);
+
+    this._setPosition(event.clientX, event.clientY);
+  }
+
+  private _handlePointerEnd(_: PointerEvent): void {
+    this._config.dragEnd?.call(this._host);
+    this.dispose();
+  }
+
+  /** Updates the drag and drop controller configuration. */
+  public setConfig(value?: DragDropConfig): void {
+    Object.assign(this._config, value);
+  }
+
+  /** @internal */
+  public handleEvent(event: PointerEvent): void {
+    if (!this.enabled) {
+      return;
+    }
+
+    switch (event.type) {
+      case 'touchstart':
+      case 'dragstart':
+        event.preventDefault();
+        break;
+      case 'pointerdown':
+        this._handlePointerDown(event);
+        break;
+      case 'pointermove':
+        this._handlePointerMove(event);
+        break;
+      case 'lostpointercapture':
+        this._handlePointerEnd(event);
+        break;
+    }
+  }
+
+  /** Stops any drag operation and cleans up state and additional elements. */
+  public dispose(): void {
+    this._previousMatch = null;
+    this._removeGhost();
+    this._setPointerCaptureState(false);
+  }
+
+  public hostConnected(): void {
+    this._host.addEventListener('dragstart', this);
+    this._host.addEventListener('touchstart', this, { passive: false });
+    this._host.addEventListener('pointerdown', this);
+  }
+
+  public hostDisconnected(): void {
+    this._host.removeEventListener('dragstart', this);
+    this._host.removeEventListener('touchstart', this);
+    this._host.removeEventListener('pointerdown', this);
+  }
+}
+
+function createDefaultDragGhost(rect: DOMRect): HTMLElement {
+  const element = document.createElement('div');
+  Object.assign(element.style, {
+    position: 'absolute',
+    left: rect.x,
+    top: rect.y,
+    width: rect.width,
+    height: rect.height,
+    zIndex: 1000,
+    background: 'gold',
+  });
+
+  return element;
+}
+
+/**
+ * Adds a drag and drop controller to the given host
+ */
+export function addDragDropController(
+  host: ReactiveControllerHost & LitElement,
+  config?: DragDropConfig
+): DragDropController {
+  return new DragDropController(host, config);
+}