feat(dragging): Create (new) IDragger and IDraggable interfaces (#…

…7953)

* chore(dragging): Rename core/interfaces/i_draggable.ts

  Rename core/interfaces/i_draggable.ts to
  core/interfaces/i_draggable.old.ts to make room for new
  IDraggable.  Do not rename actual interface as it's not yet
  clear that it will be necessary for both to coexist as
  imports in the same file.


* feat(dragging): Introduce new IDraggable interface

* feat(dragging): Introduce new IDragger interface

---------

Co-authored-by: Beka Westberg <bwestberg@google.com>

core/block_svg.ts

@@ -36,7 +36,7 @@ import type {Input} from './inputs/input.js';
 import type {IASTNodeLocationSvg} from './interfaces/i_ast_node_location_svg.js';
 import type {IBoundedElement} from './interfaces/i_bounded_element.js';
 import type {ICopyable} from './interfaces/i_copyable.js';
-import type {IDraggable} from './interfaces/i_draggable.js';
+import type {IDraggable} from './interfaces/i_draggable.old.js';
 import {IIcon} from './interfaces/i_icon.js';
 import * as internalConstants from './internal_constants.js';
 import {ASTNode} from './keyboard_nav/ast_node.js';

core/blockly.ts

@@ -125,7 +125,7 @@ import {ICopyable, isCopyable} from './interfaces/i_copyable.js';
 import {IDeletable} from './interfaces/i_deletable.js';
 import {IDeleteArea} from './interfaces/i_delete_area.js';
 import {IDragTarget} from './interfaces/i_drag_target.js';
-import {IDraggable} from './interfaces/i_draggable.js';
+import {IDraggable} from './interfaces/i_draggable.old.js';
 import {IFlyout} from './interfaces/i_flyout.js';
 import {IHasBubble, hasBubble} from './interfaces/i_has_bubble.js';
 import {IIcon, isIcon} from './interfaces/i_icon.js';

core/delete_area.ts

@@ -15,7 +15,7 @@
 import {BlockSvg} from './block_svg.js';
 import {DragTarget} from './drag_target.js';
 import type {IDeleteArea} from './interfaces/i_delete_area.js';
-import type {IDraggable} from './interfaces/i_draggable.js';
+import type {IDraggable} from './interfaces/i_draggable.old.js';
 
 /**
  * Abstract class for a component that can delete a block or bubble that is

core/drag_target.ts

@@ -13,7 +13,7 @@
 // Former goog.module ID: Blockly.DragTarget
 
 import type {IDragTarget} from './interfaces/i_drag_target.js';
-import type {IDraggable} from './interfaces/i_draggable.js';
+import type {IDraggable} from './interfaces/i_draggable.old.js';
 import type {Rect} from './utils/rect.js';
 
 /**

core/interfaces/i_bubble.ts

@@ -8,7 +8,7 @@ import type {Coordinate} from '../utils/coordinate.js';
 // Former goog.module ID: Blockly.IBubble
 
 import type {IContextMenu} from './i_contextmenu.js';
-import type {IDraggable} from './i_draggable.js';
+import type {IDraggable} from './i_draggable.old.js';
 
 /**
  * A bubble interface.

core/interfaces/i_delete_area.ts

@@ -7,7 +7,7 @@
 // Former goog.module ID: Blockly.IDeleteArea
 
 import type {IDragTarget} from './i_drag_target.js';
-import type {IDraggable} from './i_draggable.js';
+import type {IDraggable} from './i_draggable.old.js';
 
 /**
  * Interface for a component that can delete a block or bubble that is dropped

core/interfaces/i_drag_target.ts

@@ -6,7 +6,7 @@
 
 import {Rect} from '../utils/rect.js';
 
-import {IDraggable} from './i_draggable.js';
+import {IDraggable} from './i_draggable.old.js';
 
 // Former goog.module ID: Blockly.IDragTarget
 

core/interfaces/i_draggable.old.ts

@@ -0,0 +1,14 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+// Former goog.module ID: Blockly.IDraggable
+
+import type {IDeletable} from './i_deletable.js';
+
+/**
+ * The interface for an object that can be dragged.
+ */
+export interface IDraggable extends IDeletable {}

core/interfaces/i_draggable.ts

@@ -4,11 +4,68 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-// Former goog.module ID: Blockly.IDraggable
+import {Coordinate} from '../utils/coordinate';
+import {IDragTarget} from './i_drag_target';
 
-import type {IDeletable} from './i_deletable.js';
+/**
+ * Represents an object that can be dragged.
+ */
+export interface IDraggable extends IDragStrategy {
+  /** Returns true iff the element is currently movable. */
+  isMovable(): boolean;
+
+  /**
+   * Returns the current location of the draggable in workspace
+   * coordinates.
+   *
+   * @returns Coordinate of current location on workspace.
+   */
+  getLocation(): Coordinate;
+}
 
 /**
- * The interface for an object that can be dragged.
+ * Represents an object that can be dragged.
  */
-export interface IDraggable extends IDeletable {}
+export interface IDragStrategy {
+  /**
+   * Handles any drag startup (e.g moving elements to the front of the
+   * workspace).
+   *
+   * @param e PointerEvent that started the drag; could be used to
+   *     check modifier keys, etc.  May be missing when dragging is
+   *     triggered programatically rather than by user.
+   */
+  startDrag(e?: PointerEvent): void;
+
+  /**
+   * Handles moving elements to the new location, and updating any
+   * visuals based on that (e.g connection previews for blocks).
+   *
+   * @param newLoc Workspace coordinate to which the draggable has
+   *     been dragged.
+   * @param e PointerEvent that continued the drag.  Should be used to
+   *     look up any IDragTarget the pointer is over; could also be
+   *     used to check modifier keys, etc.
+   * @param target The drag target the pointer is over, if any.  Could
+   *     be supplied as an alternative to providing a PointerEvent for
+   *     programatic drags.
+   */
+  drag(newLoc: Coordinate, e?: PointerEvent): void;
+  drag(newLoc: Coordinate, target: IDragTarget): void;
+
+  /**
+   * Handles any drag cleanup, including e.g. connecting or deleting
+   * blocks.
+   *
+   * @param newLoc Workspace coordinate at which the drag finished.
+   *     been dragged.
+   * @param e PointerEvent that finished the drag.  Should be used to
+   *     look up any IDragTarget the pointer is over; could also be
+   *     used to check modifier keys, etc.
+   * @param target The drag target the pointer is over, if any.  Could
+   *     be supplied as an alternative to providing a PointerEvent for
+   *     programatic drags.
+   */
+  endDrag(newLoc: Coordinate, e?: PointerEvent): void;
+  endDrag(newLoc: Coordinate, target: IDragTarget): void;
+}

core/interfaces/i_dragger.ts

@@ -0,0 +1,35 @@
+/**
+ * @license
+ * Copyright 2024 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {Coordinate} from '../utils/coordinate';
+
+export interface IDragger {
+  /**
+   * Handles any drag startup.
+   *
+   * @param e PointerEvent that started the drag.
+   */
+  onDragStart(e: PointerEvent): void;
+
+  /**
+   * Handles dragging, including calculating where the element should
+   * actually be moved to.
+   *
+   * @param e PointerEvent that continued the drag.
+   * @param totalDelta The total distance, in pixels, that the mouse
+   *     has moved since the start of the drag.
+   */
+  onDrag(e: PointerEvent, totalDelta: Coordinate): void;
+
+  /**
+   * Handles any drag cleanup.
+   *
+   * @param e PointerEvent that finished the drag.
+   * @param totalDelta The total distance, in pixels, that the mouse
+   *     has moved since the start of the drag.
+   */
+  onDragEnd(e: PointerEvent, totalDelta: Coordinate): void;
+}

core/toolbox/toolbox.ts

@@ -24,7 +24,7 @@ import {DeleteArea} from '../delete_area.js';
 import * as eventUtils from '../events/utils.js';
 import type {IAutoHideable} from '../interfaces/i_autohideable.js';
 import type {ICollapsibleToolboxItem} from '../interfaces/i_collapsible_toolbox_item.js';
-import type {IDraggable} from '../interfaces/i_draggable.js';
+import type {IDraggable} from '../interfaces/i_draggable.old.js';
 import type {IFlyout} from '../interfaces/i_flyout.js';
 import type {IKeyboardAccessible} from '../interfaces/i_keyboard_accessible.js';
 import type {ISelectableToolboxItem} from '../interfaces/i_selectable_toolbox_item.js';

core/trashcan.ts

@@ -22,7 +22,7 @@ import type {Abstract} from './events/events_abstract.js';
 import type {BlockDelete} from './events/events_block_delete.js';
 import * as eventUtils from './events/utils.js';
 import type {IAutoHideable} from './interfaces/i_autohideable.js';
-import type {IDraggable} from './interfaces/i_draggable.js';
+import type {IDraggable} from './interfaces/i_draggable.old.js';
 import type {IFlyout} from './interfaces/i_flyout.js';
 import type {IPositionable} from './interfaces/i_positionable.js';
 import type {UiMetrics} from './metrics_manager.js';