From dc9aa1befb90b1a96b405f5fd33bcc0b420a7ac8 Mon Sep 17 00:00:00 2001
From: Beka Westberg <bwestberg@google.com>
Date: Mon, 13 Nov 2023 17:20:28 +0000
Subject: [PATCH] feat: add connection previewer interface (#7637)

* feat: add connection previewer interface

* chore: PR comments
---
 core/blockly.ts                           |  2 +
 core/interfaces/i_connection_previewer.ts | 50 +++++++++++++++++++++++
 core/registry.ts                          |  9 +++-
 3 files changed, 59 insertions(+), 2 deletions(-)
 create mode 100644 core/interfaces/i_connection_previewer.ts

diff --git a/core/blockly.ts b/core/blockly.ts
index 00c10f69e..9abea068e 100644
--- a/core/blockly.ts
+++ b/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};
diff --git a/core/interfaces/i_connection_previewer.ts b/core/interfaces/i_connection_previewer.ts
new file mode 100644
index 000000000..df7906a29
--- /dev/null
+++ b/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;
+}
diff --git a/core/registry.ts b/core/registry.ts
index 33bded304..3645a6fdf 100644
--- a/core/registry.ts
+++ b/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');