blockly 8.20220331.0-beta.1 → 9.0.0-beta.0

package/core/interfaces/i_connection_checker.d.ts

@@ -0,0 +1,69 @@
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { Connection } from '../connection.js';
+import type { RenderedConnection } from '../rendered_connection.js';
+/**
+ * Class for connection type checking logic.
+ * @alias Blockly.IConnectionChecker
+ */
+export interface IConnectionChecker {
+    /**
+     * Check whether the current connection can connect with the target
+     * connection.
+     * @param a Connection to check compatibility with.
+     * @param b Connection to check compatibility with.
+     * @param isDragging True if the connection is being made by dragging a block.
+     * @param opt_distance The max allowable distance between the connections for
+     *     drag checks.
+     * @return Whether the connection is legal.
+     */
+    canConnect(a: Connection | null, b: Connection | null, isDragging: boolean, opt_distance?: number): boolean;
+    /**
+     * Checks whether the current connection can connect with the target
+     * connection, and return an error code if there are problems.
+     * @param a Connection to check compatibility with.
+     * @param b Connection to check compatibility with.
+     * @param isDragging True if the connection is being made by dragging a block.
+     * @param opt_distance The max allowable distance between the connections for
+     *     drag checks.
+     * @return Connection.CAN_CONNECT if the connection is legal, an error code
+     *     otherwise.
+     */
+    canConnectWithReason(a: Connection | null, b: Connection | null, isDragging: boolean, opt_distance?: number): number;
+    /**
+     * Helper method that translates a connection error code into a string.
+     * @param errorCode The error code.
+     * @param a One of the two connections being checked.
+     * @param b The second of the two connections being checked.
+     * @return A developer-readable error string.
+     */
+    getErrorMessage(errorCode: number, a: Connection | null, b: Connection | null): string;
+    /**
+     * Check that connecting the given connections is safe, meaning that it would
+     * not break any of Blockly's basic assumptions (e.g. no self connections).
+     * @param a The first of the connections to check.
+     * @param b The second of the connections to check.
+     * @return An enum with the reason this connection is safe or unsafe.
+     */
+    doSafetyChecks(a: Connection | null, b: Connection | null): number;
+    /**
+     * Check whether this connection is compatible with another connection with
+     * respect to the value type system.  E.g. square_root("Hello") is not
+     * compatible.
+     * @param a Connection to compare.
+     * @param b Connection to compare against.
+     * @return True if the connections share a type.
+     */
+    doTypeChecks(a: Connection, b: Connection): boolean;
+    /**
+     * Check whether this connection can be made by dragging.
+     * @param a Connection to compare.
+     * @param b Connection to compare against.
+     * @param distance The maximum allowable distance between connections.
+     * @return True if the connection is allowed during a drag.
+     */
+    doDragChecks(a: RenderedConnection, b: RenderedConnection, distance: number): boolean;
+}

package/core/interfaces/i_connection_checker.ts

@@ -0,0 +1,102 @@
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * @fileoverview The interface for an object that encapsulates logic for
+ * checking whether a potential connection is safe and valid.
+ */
+
+/**
+ * The interface for an object that encapsulates logic for
+ * checking whether a potential connection is safe and valid.
+ * @namespace Blockly.IConnectionChecker
+ */
+import * as goog from '../../closure/goog/goog.js';
+import type {Connection} from '../connection.js';
+import type {RenderedConnection} from '../rendered_connection.js';
+goog.declareModuleId('Blockly.IConnectionChecker');
+
+/* eslint-disable-next-line no-unused-vars */
+// Unused import preserved for side-effects. Remove if unneeded.
+// import '../connection.js';
+/* eslint-disable-next-line no-unused-vars */
+// Unused import preserved for side-effects. Remove if unneeded.
+// import '../rendered_connection.js';
+
+
+/**
+ * Class for connection type checking logic.
+ * @alias Blockly.IConnectionChecker
+ */
+export interface IConnectionChecker {
+  /**
+   * Check whether the current connection can connect with the target
+   * connection.
+   * @param a Connection to check compatibility with.
+   * @param b Connection to check compatibility with.
+   * @param isDragging True if the connection is being made by dragging a block.
+   * @param opt_distance The max allowable distance between the connections for
+   *     drag checks.
+   * @return Whether the connection is legal.
+   */
+  canConnect(
+      a: Connection|null, b: Connection|null, isDragging: boolean,
+      opt_distance?: number): boolean;
+
+  /**
+   * Checks whether the current connection can connect with the target
+   * connection, and return an error code if there are problems.
+   * @param a Connection to check compatibility with.
+   * @param b Connection to check compatibility with.
+   * @param isDragging True if the connection is being made by dragging a block.
+   * @param opt_distance The max allowable distance between the connections for
+   *     drag checks.
+   * @return Connection.CAN_CONNECT if the connection is legal, an error code
+   *     otherwise.
+   */
+  canConnectWithReason(
+      a: Connection|null, b: Connection|null, isDragging: boolean,
+      opt_distance?: number): number;
+
+  /**
+   * Helper method that translates a connection error code into a string.
+   * @param errorCode The error code.
+   * @param a One of the two connections being checked.
+   * @param b The second of the two connections being checked.
+   * @return A developer-readable error string.
+   */
+  getErrorMessage(errorCode: number, a: Connection|null, b: Connection|null):
+      string;
+
+  /**
+   * Check that connecting the given connections is safe, meaning that it would
+   * not break any of Blockly's basic assumptions (e.g. no self connections).
+   * @param a The first of the connections to check.
+   * @param b The second of the connections to check.
+   * @return An enum with the reason this connection is safe or unsafe.
+   */
+  doSafetyChecks(a: Connection|null, b: Connection|null): number;
+
+  /**
+   * Check whether this connection is compatible with another connection with
+   * respect to the value type system.  E.g. square_root("Hello") is not
+   * compatible.
+   * @param a Connection to compare.
+   * @param b Connection to compare against.
+   * @return True if the connections share a type.
+   */
+  doTypeChecks(a: Connection, b: Connection): boolean;
+
+  /**
+   * Check whether this connection can be made by dragging.
+   * @param a Connection to compare.
+   * @param b Connection to compare against.
+   * @param distance The maximum allowable distance between connections.
+   * @return True if the connection is allowed during a drag.
+   */
+  doDragChecks(a: RenderedConnection, b: RenderedConnection, distance: number):
+      boolean;
+}

package/core/interfaces/i_contextmenu.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/** @alias Blockly.IContextMenu */
+export interface IContextMenu {
+    /**
+     * Show the context menu for this object.
+     * @param e Mouse event.
+     */
+    showContextMenu(e: Event): void;
+}

package/core/interfaces/i_contextmenu.ts

@@ -0,0 +1,26 @@
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * @fileoverview The interface for an object that supports a right-click.
+ */
+
+/**
+ * The interface for an object that supports a right-click.
+ * @namespace Blockly.IContextMenu
+ */
+import * as goog from '../../closure/goog/goog.js';
+goog.declareModuleId('Blockly.IContextMenu');
+
+
+/** @alias Blockly.IContextMenu */
+export interface IContextMenu {
+  /**
+   * Show the context menu for this object.
+   * @param e Mouse event.
+   */
+  showContextMenu(e: Event): void;
+}

package/core/interfaces/i_copyable.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @license
+ * Copyright 2019 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { WorkspaceSvg } from '../workspace_svg.js';
+import type { ISelectable } from './i_selectable.js';
+/** @alias Blockly.ICopyable */
+export interface ICopyable extends ISelectable {
+    /**
+     * Encode for copying.
+     * @return Copy metadata.
+     * @internal
+     */
+    toCopyData(): CopyData | null;
+}
+export declare namespace ICopyable {
+    interface CopyData {
+        saveInfo: Object | Element;
+        source: WorkspaceSvg;
+        typeCounts: Object | null;
+    }
+}
+export declare type CopyData = ICopyable.CopyData;

package/core/interfaces/i_copyable.ts

@@ -0,0 +1,40 @@
+/**
+ * @license
+ * Copyright 2019 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * @fileoverview The interface for an object that is copyable.
+ */
+
+/**
+ * The interface for an object that is copyable.
+ * @namespace Blockly.ICopyable
+ */
+import * as goog from '../../closure/goog/goog.js';
+goog.declareModuleId('Blockly.ICopyable');
+
+import type {WorkspaceSvg} from '../workspace_svg.js';
+import type {ISelectable} from './i_selectable.js';
+
+
+/** @alias Blockly.ICopyable */
+export interface ICopyable extends ISelectable {
+  /**
+   * Encode for copying.
+   * @return Copy metadata.
+   * @internal
+   */
+  toCopyData(): CopyData|null;
+}
+
+export namespace ICopyable {
+  export interface CopyData {
+    saveInfo: Object|Element;
+    source: WorkspaceSvg;
+    typeCounts: Object|null;
+  }
+}
+
+export type CopyData = ICopyable.CopyData;

package/core/interfaces/i_deletable.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @license
+ * Copyright 2019 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * The interface for an object that can be deleted.
+ * @alias Blockly.IDeletable
+ */
+export interface IDeletable {
+    /**
+     * Get whether this object is deletable or not.
+     * @return True if deletable.
+     */
+    isDeletable(): boolean;
+}

package/core/interfaces/{i_deletable.js → i_deletable.ts}

@@ -8,26 +8,22 @@
  * @fileoverview The interface for an object that is deletable.
  */
 
-'use strict';
-
 /**
  * The interface for an object that is deletable.
  * @namespace Blockly.IDeletable
  */
-goog.module('Blockly.IDeletable');
+import * as goog from '../../closure/goog/goog.js';
+goog.declareModuleId('Blockly.IDeletable');
 
 
 /**
  * The interface for an object that can be deleted.
- * @interface
  * @alias Blockly.IDeletable
  */
-const IDeletable = function() {};
-
-/**
- * Get whether this object is deletable or not.
- * @return {boolean} True if deletable.
- */
-IDeletable.prototype.isDeletable;
-
-exports.IDeletable = IDeletable;
+export interface IDeletable {
+  /**
+   * Get whether this object is deletable or not.
+   * @return True if deletable.
+   */
+  isDeletable(): boolean;
+}

package/core/interfaces/i_delete_area.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { IDragTarget } from './i_drag_target.js';
+import type { IDraggable } from './i_draggable.js';
+/**
+ * Interface for a component that can delete a block or bubble that is dropped
+ * on top of it.
+ * @alias Blockly.IDeleteArea
+ */
+export interface IDeleteArea extends IDragTarget {
+    /**
+     * Returns whether the provided block or bubble would be deleted if dropped on
+     * this area.
+     * This method should check if the element is deletable and is always called
+     * before onDragEnter/onDragOver/onDragExit.
+     * @param element The block or bubble currently being dragged.
+     * @param couldConnect Whether the element could could connect to another.
+     * @return Whether the element provided would be deleted if dropped on this
+     *     area.
+     */
+    wouldDelete(element: IDraggable, couldConnect: boolean): boolean;
+}

package/core/interfaces/i_delete_area.ts

@@ -0,0 +1,46 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * @fileoverview The interface for a component that can delete a block or bubble
+ * that is dropped on top of it.
+ */
+
+/**
+ * The interface for a component that can delete a block or bubble
+ * that is dropped on top of it.
+ * @namespace Blockly.IDeleteArea
+ */
+import * as goog from '../../closure/goog/goog.js';
+goog.declareModuleId('Blockly.IDeleteArea');
+
+/* eslint-disable-next-line no-unused-vars */
+/* eslint-disable-next-line no-unused-vars */
+// Unused import preserved for side-effects. Remove if unneeded.
+// import './i_draggable.js';
+
+import type {IDragTarget} from './i_drag_target.js';
+import type {IDraggable} from './i_draggable.js';
+
+
+/**
+ * Interface for a component that can delete a block or bubble that is dropped
+ * on top of it.
+ * @alias Blockly.IDeleteArea
+ */
+export interface IDeleteArea extends IDragTarget {
+  /**
+   * Returns whether the provided block or bubble would be deleted if dropped on
+   * this area.
+   * This method should check if the element is deletable and is always called
+   * before onDragEnter/onDragOver/onDragExit.
+   * @param element The block or bubble currently being dragged.
+   * @param couldConnect Whether the element could could connect to another.
+   * @return Whether the element provided would be deleted if dropped on this
+   *     area.
+   */
+  wouldDelete(element: IDraggable, couldConnect: boolean): boolean;
+}

package/core/interfaces/i_drag_target.d.ts

@@ -0,0 +1,53 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Rect } from '../utils/rect.js';
+import { IDraggable } from './i_draggable.js';
+import type { IComponent } from './i_component.js';
+/**
+ * Interface for a component with custom behaviour when a block or bubble is
+ * dragged over or dropped on top of it.
+ * @alias Blockly.IDragTarget
+ */
+export interface IDragTarget extends IComponent {
+    /**
+     * Returns the bounding rectangle of the drag target area in pixel units
+     * relative to viewport.
+     * @return The component's bounding box. Null if drag target area should be
+     *     ignored.
+     */
+    getClientRect(): Rect | null;
+    /**
+     * Handles when a cursor with a block or bubble enters this drag target.
+     * @param dragElement The block or bubble currently being dragged.
+     */
+    onDragEnter(dragElement: IDraggable): void;
+    /**
+     * Handles when a cursor with a block or bubble is dragged over this drag
+     * target.
+     * @param dragElement The block or bubble currently being dragged.
+     */
+    onDragOver(dragElement: IDraggable): void;
+    /**
+     * Handles when a cursor with a block or bubble exits this drag target.
+     * @param dragElement The block or bubble currently being dragged.
+     */
+    onDragExit(dragElement: IDraggable): void;
+    /**
+     * Handles when a block or bubble is dropped on this component.
+     * Should not handle delete here.
+     * @param dragElement The block or bubble currently being dragged.
+     */
+    onDrop(dragElement: IDraggable): void;
+    /**
+     * Returns whether the provided block or bubble should not be moved after
+     * being dropped on this component. If true, the element will return to where
+     * it was when the drag started.
+     * @param dragElement The block or bubble currently being dragged.
+     * @return Whether the block or bubble provided should be returned to drag
+     *     start.
+     */
+    shouldPreventMove(dragElement: IDraggable): boolean;
+}

package/core/interfaces/i_drag_target.ts

@@ -0,0 +1,84 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * @fileoverview The interface for a component that has a handler for when a
+ * block is dropped on top of it.
+ */
+
+/**
+ * The interface for a component that has a handler for when a
+ * block is dropped on top of it.
+ * @namespace Blockly.IDragTarget
+ */
+import * as goog from '../../closure/goog/goog.js';
+import {Rect} from '../utils/rect.js';
+
+import {IDraggable} from './i_draggable.js';
+
+goog.declareModuleId('Blockly.IDragTarget');
+
+/* eslint-disable-next-line no-unused-vars */
+/* eslint-disable-next-line no-unused-vars */
+// Unused import preserved for side-effects. Remove if unneeded.
+// import './i_draggable.js';
+/* eslint-disable-next-line no-unused-vars */
+// Unused import preserved for side-effects. Remove if unneeded.
+// import '../utils/rect.js';
+
+import type {IComponent} from './i_component.js';
+
+
+/**
+ * Interface for a component with custom behaviour when a block or bubble is
+ * dragged over or dropped on top of it.
+ * @alias Blockly.IDragTarget
+ */
+export interface IDragTarget extends IComponent {
+  /**
+   * Returns the bounding rectangle of the drag target area in pixel units
+   * relative to viewport.
+   * @return The component's bounding box. Null if drag target area should be
+   *     ignored.
+   */
+  getClientRect(): Rect|null;
+
+  /**
+   * Handles when a cursor with a block or bubble enters this drag target.
+   * @param dragElement The block or bubble currently being dragged.
+   */
+  onDragEnter(dragElement: IDraggable): void;
+
+  /**
+   * Handles when a cursor with a block or bubble is dragged over this drag
+   * target.
+   * @param dragElement The block or bubble currently being dragged.
+   */
+  onDragOver(dragElement: IDraggable): void;
+
+  /**
+   * Handles when a cursor with a block or bubble exits this drag target.
+   * @param dragElement The block or bubble currently being dragged.
+   */
+  onDragExit(dragElement: IDraggable): void;
+
+  /**
+   * Handles when a block or bubble is dropped on this component.
+   * Should not handle delete here.
+   * @param dragElement The block or bubble currently being dragged.
+   */
+  onDrop(dragElement: IDraggable): void;
+
+  /**
+   * Returns whether the provided block or bubble should not be moved after
+   * being dropped on this component. If true, the element will return to where
+   * it was when the drag started.
+   * @param dragElement The block or bubble currently being dragged.
+   * @return Whether the block or bubble provided should be returned to drag
+   *     start.
+   */
+  shouldPreventMove(dragElement: IDraggable): boolean;
+}

package/core/interfaces/i_draggable.d.ts

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

package/core/interfaces/{i_draggable.js → i_draggable.ts}

@@ -8,24 +8,18 @@
  * @fileoverview The interface for an object that is draggable.
  */
 
-'use strict';
-
 /**
  * The interface for an object that is draggable.
  * @namespace Blockly.IDraggable
  */
-goog.module('Blockly.IDraggable');
+import * as goog from '../../closure/goog/goog.js';
+goog.declareModuleId('Blockly.IDraggable');
 
-/* eslint-disable-next-line no-unused-vars */
-const {IDeletable} = goog.require('Blockly.IDeletable');
+import type {IDeletable} from './i_deletable.js';
 
 
 /**
  * The interface for an object that can be dragged.
- * @extends {IDeletable}
- * @interface
  * @alias Blockly.IDraggable
  */
-const IDraggable = function() {};
-
-exports.IDraggable = IDraggable;
+export interface IDraggable extends IDeletable {}