feat: add connection previewer interface (#7637)

* feat: add connection previewer interface

* chore: PR comments

core/blockly.ts

@@ -138,6 +138,7 @@ import {IBubble} from './interfaces/i_bubble.js';
 import {ICollapsibleToolboxItem} from './interfaces/i_collapsible_toolbox_item.js';
 import {IComponent} from './interfaces/i_component.js';
 import {IConnectionChecker} from './interfaces/i_connection_checker.js';
+import {IConnectionPreviewer} from './interfaces/i_connection_previewer.js';
 import {IContextMenu} from './interfaces/i_contextmenu.js';
 import {ICopyable, isCopyable} from './interfaces/i_copyable.js';
 import {IDeletable} from './interfaces/i_deletable.js';
@@ -589,6 +590,7 @@ export {IBubble};
 export {ICollapsibleToolboxItem};
 export {IComponent};
 export {IConnectionChecker};
+export {IConnectionPreviewer};
 export {IContextMenu};
 export {icons};
 export {ICopyable, isCopyable};

core/interfaces/i_connection_previewer.ts

@@ -0,0 +1,50 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type {BlockSvg} from '../block_svg';
+import type {RenderedConnection} from '../rendered_connection';
+
+/**
+ * Displays visual "previews" of where a block will be connected if it is
+ * dropped.
+ */
+export interface IConnectionPreviewer {
+  /**
+   * Display a connection preview where the draggedCon connects to the
+   * staticCon, replacing the replacedBlock (currently connected to the
+   * staticCon).
+   *
+   * @param draggedCon The connection on the block stack being dragged.
+   * @param staticCon The connection not being dragged that we are
+   *     connecting to.
+   * @param replacedBlock The block currently connected to the staticCon that
+   *     is being replaced.
+   */
+  previewReplacement(
+    draggedConn: RenderedConnection,
+    staticConn: RenderedConnection,
+    replacedBlock: BlockSvg,
+  ): void;
+
+  /**
+   * Display a connection preview where the draggedCon connects to the
+   * staticCon, and no block is being relaced.
+   *
+   * @param draggedCon The connection on the block stack being dragged.
+   * @param staticCon The connection not being dragged that we are
+   *     connecting to.
+   */
+  previewConnection(
+    draggedConn: RenderedConnection,
+    staticConn: RenderedConnection,
+  ): void;
+
+  /** Hide any previews that are currently displayed. */
+  hidePreview(): void;
+
+  /** Dispose of any references held by this connection previewer. */
+  dispose(): void;
+}

core/registry.ts

@@ -21,8 +21,9 @@ import type {Options} from './options.js';
 import type {Renderer} from './renderers/common/renderer.js';
 import type {Theme} from './theme.js';
 import type {ToolboxItem} from './toolbox/toolbox_item.js';
-import {IPaster} from './interfaces/i_paster.js';
-import {ICopyData, ICopyable} from './interfaces/i_copyable.js';
+import type {IPaster} from './interfaces/i_paster.js';
+import type {ICopyData, ICopyable} from './interfaces/i_copyable.js';
+import type {IConnectionPreviewer} from './interfaces/i_connection_previewer.js';
 
 /**
  * A map of maps. With the keys being the type and name of the class we are
@@ -66,6 +67,10 @@ export class Type<_T> {
 
   static CONNECTION_CHECKER = new Type<IConnectionChecker>('connectionChecker');
 
+  static CONNECTION_PREVIEWER = new Type<IConnectionPreviewer>(
+    'connectionPreviewer',
+  );
+
   static CURSOR = new Type<Cursor>('cursor');
 
   static EVENT = new Type<Abstract>('event');