blockly 12.3.1 → 12.4.0

package/core/connection_checker.ts

@@ -0,0 +1,348 @@
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * An object that encapsulates logic for checking whether a
+ * potential connection is safe and valid.
+ *
+ * @class
+ */
+// Former goog.module ID: Blockly.ConnectionChecker
+
+import * as common from './common.js';
+import {Connection} from './connection.js';
+import {ConnectionType} from './connection_type.js';
+import type {IConnectionChecker} from './interfaces/i_connection_checker.js';
+import * as internalConstants from './internal_constants.js';
+import * as registry from './registry.js';
+import type {RenderedConnection} from './rendered_connection.js';
+
+/**
+ * Class for connection type checking logic.
+ */
+export class ConnectionChecker implements 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.
+   * @returns Whether the connection is legal.
+   */
+  canConnect(
+    a: Connection | null,
+    b: Connection | null,
+    isDragging: boolean,
+    opt_distance?: number,
+  ): boolean {
+    return (
+      this.canConnectWithReason(a, b, isDragging, opt_distance) ===
+      Connection.CAN_CONNECT
+    );
+  }
+
+  /**
+   * 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.
+   * @returns 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 {
+    const safety = this.doSafetyChecks(a, b);
+    if (safety !== Connection.CAN_CONNECT) {
+      return safety;
+    }
+
+    // If the safety checks passed, both connections are non-null.
+    const connOne = a!;
+    const connTwo = b!;
+    if (!this.doTypeChecks(connOne, connTwo)) {
+      return Connection.REASON_CHECKS_FAILED;
+    }
+
+    if (
+      isDragging &&
+      !this.doDragChecks(
+        a as RenderedConnection,
+        b as RenderedConnection,
+        opt_distance || 0,
+      )
+    ) {
+      return Connection.REASON_DRAG_CHECKS_FAILED;
+    }
+
+    return Connection.CAN_CONNECT;
+  }
+
+  /**
+   * 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.
+   * @returns A developer-readable error string.
+   */
+  getErrorMessage(
+    errorCode: number,
+    a: Connection | null,
+    b: Connection | null,
+  ): string {
+    switch (errorCode) {
+      case Connection.REASON_SELF_CONNECTION:
+        return 'Attempted to connect a block to itself.';
+      case Connection.REASON_DIFFERENT_WORKSPACES:
+        // Usually this means one block has been deleted.
+        return 'Blocks not on same workspace.';
+      case Connection.REASON_WRONG_TYPE:
+        return 'Attempt to connect incompatible types.';
+      case Connection.REASON_TARGET_NULL:
+        return 'Target connection is null.';
+      case Connection.REASON_CHECKS_FAILED: {
+        const connOne = a!;
+        const connTwo = b!;
+        let msg = 'Connection checks failed. ';
+        msg +=
+          connOne +
+          ' expected ' +
+          connOne.getCheck() +
+          ', found ' +
+          connTwo.getCheck();
+        return msg;
+      }
+      case Connection.REASON_SHADOW_PARENT:
+        return 'Connecting non-shadow to shadow block.';
+      case Connection.REASON_DRAG_CHECKS_FAILED:
+        return 'Drag checks failed.';
+      case Connection.REASON_PREVIOUS_AND_OUTPUT:
+        return 'Block would have an output and a previous connection.';
+      default:
+        return 'Unknown connection failure: this should never happen!';
+    }
+  }
+
+  /**
+   * 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.
+   * @returns An enum with the reason this connection is safe or unsafe.
+   */
+  doSafetyChecks(a: Connection | null, b: Connection | null): number {
+    if (!a || !b) {
+      return Connection.REASON_TARGET_NULL;
+    }
+    let superiorBlock;
+    let inferiorBlock;
+    let superiorConnection;
+    let inferiorConnection;
+    if (a.isSuperior()) {
+      superiorBlock = a.getSourceBlock();
+      inferiorBlock = b.getSourceBlock();
+      superiorConnection = a;
+      inferiorConnection = b;
+    } else {
+      inferiorBlock = a.getSourceBlock();
+      superiorBlock = b.getSourceBlock();
+      inferiorConnection = a;
+      superiorConnection = b;
+    }
+    if (superiorBlock === inferiorBlock) {
+      return Connection.REASON_SELF_CONNECTION;
+    } else if (
+      inferiorConnection.type !==
+      internalConstants.OPPOSITE_TYPE[superiorConnection.type]
+    ) {
+      return Connection.REASON_WRONG_TYPE;
+    } else if (superiorBlock.workspace !== inferiorBlock.workspace) {
+      return Connection.REASON_DIFFERENT_WORKSPACES;
+    } else if (superiorBlock.isShadow() && !inferiorBlock.isShadow()) {
+      return Connection.REASON_SHADOW_PARENT;
+    } else if (
+      inferiorConnection.type === ConnectionType.OUTPUT_VALUE &&
+      inferiorBlock.previousConnection &&
+      inferiorBlock.previousConnection.isConnected()
+    ) {
+      return Connection.REASON_PREVIOUS_AND_OUTPUT;
+    } else if (
+      inferiorConnection.type === ConnectionType.PREVIOUS_STATEMENT &&
+      inferiorBlock.outputConnection &&
+      inferiorBlock.outputConnection.isConnected()
+    ) {
+      return Connection.REASON_PREVIOUS_AND_OUTPUT;
+    }
+    return Connection.CAN_CONNECT;
+  }
+
+  /**
+   * 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.
+   * @returns True if the connections share a type.
+   */
+  doTypeChecks(a: Connection, b: Connection): boolean {
+    const checkArrayOne = a.getCheck();
+    const checkArrayTwo = b.getCheck();
+
+    if (!checkArrayOne || !checkArrayTwo) {
+      // One or both sides are promiscuous enough that anything will fit.
+      return true;
+    }
+    // Find any intersection in the check lists.
+    for (let i = 0; i < checkArrayOne.length; i++) {
+      if (checkArrayTwo.includes(checkArrayOne[i])) {
+        return true;
+      }
+    }
+    // No intersection.
+    return false;
+  }
+
+  /**
+   * Check whether this connection can be made by dragging.
+   *
+   * @param a Connection to compare (on the block that's being dragged).
+   * @param b Connection to compare against.
+   * @param distance The maximum allowable distance between connections.
+   * @returns True if the connection is allowed during a drag.
+   */
+  doDragChecks(
+    a: RenderedConnection,
+    b: RenderedConnection,
+    distance: number,
+  ): boolean {
+    if (a.distanceFrom(b) > distance) {
+      return false;
+    }
+
+    // Don't consider insertion markers.
+    if (b.getSourceBlock().isInsertionMarker()) {
+      return false;
+    }
+
+    switch (b.type) {
+      case ConnectionType.PREVIOUS_STATEMENT:
+        return this.canConnectToPrevious_(a, b);
+      case ConnectionType.OUTPUT_VALUE: {
+        // Don't offer to connect an already connected left (male) value plug to
+        // an available right (female) value plug.
+        if (
+          (b.isConnected() && !b.targetBlock()!.isInsertionMarker()) ||
+          a.isConnected()
+        ) {
+          return false;
+        }
+        break;
+      }
+      case ConnectionType.INPUT_VALUE: {
+        // Offering to connect the left (male) of a value block to an already
+        // connected value pair is ok, we'll splice it in.
+        // However, don't offer to splice into an immovable block.
+        if (
+          b.isConnected() &&
+          !b.targetBlock()!.isMovable() &&
+          !b.targetBlock()!.isShadow()
+        ) {
+          return false;
+        }
+        break;
+      }
+      case ConnectionType.NEXT_STATEMENT: {
+        // Don't let a block with no next connection bump other blocks out of
+        // the stack.  But covering up a shadow block or stack of shadow blocks
+        // is fine.  Similarly, replacing a terminal statement with another
+        // terminal statement is allowed.
+        if (
+          b.isConnected() &&
+          !a.getSourceBlock().nextConnection &&
+          !b.targetBlock()!.isShadow() &&
+          b.targetBlock()!.nextConnection
+        ) {
+          return false;
+        }
+
+        // Don't offer to splice into a stack where the connected block is
+        // immovable, unless the block is a shadow block.
+        if (
+          b.targetBlock() &&
+          !b.targetBlock()!.isMovable() &&
+          !b.targetBlock()!.isShadow()
+        ) {
+          return false;
+        }
+        break;
+      }
+      default:
+        // Unexpected connection type.
+        return false;
+    }
+
+    // Don't let blocks try to connect to themselves or ones they nest.
+    if (common.draggingConnections.includes(b)) {
+      return false;
+    }
+
+    return true;
+  }
+
+  /**
+   * Helper function for drag checking.
+   *
+   * @param a The connection to check, which must be a statement input or next
+   *     connection.
+   * @param b A nearby connection to check, which must be a previous connection.
+   * @returns True if the connection is allowed, false otherwise.
+   */
+  protected canConnectToPrevious_(a: Connection, b: Connection): boolean {
+    if (a.targetConnection) {
+      // This connection is already occupied.
+      // A next connection will never disconnect itself mid-drag.
+      return false;
+    }
+
+    // Don't let blocks try to connect to themselves or ones they nest.
+    if (common.draggingConnections.includes(b)) {
+      return false;
+    }
+
+    if (!b.targetConnection) {
+      return true;
+    }
+
+    const targetBlock = b.targetBlock();
+    // If it is connected to a real block, game over.
+    if (!targetBlock!.isInsertionMarker()) {
+      return false;
+    }
+    // If it's connected to an insertion marker but that insertion marker
+    // is the first block in a stack, it's still fine.  If that insertion
+    // marker is in the middle of a stack, it won't work.
+    return !targetBlock!.getPreviousBlock();
+  }
+}
+
+registry.register(
+  registry.Type.CONNECTION_CHECKER,
+  registry.DEFAULT,
+  ConnectionChecker,
+);

package/core/connection_db.ts

@@ -0,0 +1,297 @@
+/**
+ * @license
+ * Copyright 2011 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * A database of all the rendered connections that could
+ *    possibly be connected to (i.e. not collapsed, etc).
+ *    Sorted by y coordinate.
+ *
+ * @class
+ */
+// Former goog.module ID: Blockly.ConnectionDB
+
+import {ConnectionType} from './connection_type.js';
+import type {IConnectionChecker} from './interfaces/i_connection_checker.js';
+import type {RenderedConnection} from './rendered_connection.js';
+import type {Coordinate} from './utils/coordinate.js';
+
+/**
+ * Database of connections.
+ * Connections are stored in order of their vertical component.  This way
+ * connections in an area may be looked up quickly using a binary search.
+ */
+export class ConnectionDB {
+  /** Array of connections sorted by y position in workspace units. */
+  private readonly connections: RenderedConnection[] = [];
+
+  /**
+   * @param connectionChecker The workspace's connection type checker, used to
+   *     decide if connections are valid during a drag.
+   */
+  constructor(private readonly connectionChecker: IConnectionChecker) {}
+
+  /**
+   * Add a connection to the database. Should not already exist in the database.
+   *
+   * @param connection The connection to be added.
+   * @param yPos The y position used to decide where to insert the connection.
+   * @internal
+   */
+  addConnection(connection: RenderedConnection, yPos: number) {
+    const index = this.calculateIndexForYPos(yPos);
+    this.connections.splice(index, 0, connection);
+  }
+
+  /**
+   * Finds the index of the given connection.
+   *
+   * Starts by doing a binary search to find the approximate location, then
+   * linearly searches nearby for the exact connection.
+   *
+   * @param conn The connection to find.
+   * @param yPos The y position used to find the index of the connection.
+   * @returns The index of the connection, or -1 if the connection was not
+   *     found.
+   */
+  private findIndexOfConnection(
+    conn: RenderedConnection,
+    yPos: number,
+  ): number {
+    if (!this.connections.length) {
+      return -1;
+    }
+
+    const bestGuess = this.calculateIndexForYPos(yPos);
+    if (bestGuess >= this.connections.length) {
+      // Not in list
+      return -1;
+    }
+
+    yPos = conn.y;
+    // Walk forward and back on the y axis looking for the connection.
+    let pointer = bestGuess;
+    while (pointer >= 0 && this.connections[pointer].y === yPos) {
+      if (this.connections[pointer] === conn) {
+        return pointer;
+      }
+      pointer--;
+    }
+
+    pointer = bestGuess;
+    while (
+      pointer < this.connections.length &&
+      this.connections[pointer].y === yPos
+    ) {
+      if (this.connections[pointer] === conn) {
+        return pointer;
+      }
+      pointer++;
+    }
+    return -1;
+  }
+
+  /**
+   * Finds the correct index for the given y position.
+   *
+   * @param yPos The y position used to decide where to insert the connection.
+   * @returns The candidate index.
+   */
+  private calculateIndexForYPos(yPos: number): number {
+    if (!this.connections.length) {
+      return 0;
+    }
+    let pointerMin = 0;
+    let pointerMax = this.connections.length;
+    while (pointerMin < pointerMax) {
+      const pointerMid = Math.floor((pointerMin + pointerMax) / 2);
+      if (this.connections[pointerMid].y < yPos) {
+        pointerMin = pointerMid + 1;
+      } else if (this.connections[pointerMid].y > yPos) {
+        pointerMax = pointerMid;
+      } else {
+        pointerMin = pointerMid;
+        break;
+      }
+    }
+    return pointerMin;
+  }
+
+  /**
+   * Remove a connection from the database.  Must already exist in DB.
+   *
+   * @param connection The connection to be removed.
+   * @param yPos The y position used to find the index of the connection.
+   * @throws {Error} If the connection cannot be found in the database.
+   */
+  removeConnection(connection: RenderedConnection, yPos: number) {
+    const index = this.findIndexOfConnection(connection, yPos);
+    if (index === -1) {
+      throw Error('Unable to find connection in connectionDB.');
+    }
+    this.connections.splice(index, 1);
+  }
+
+  /**
+   * Find all nearby connections to the given connection.
+   * Type checking does not apply, since this function is used for bumping.
+   *
+   * @param connection The connection whose neighbours should be returned.
+   * @param maxRadius The maximum radius to another connection.
+   * @returns List of connections.
+   */
+  getNeighbours(
+    connection: RenderedConnection,
+    maxRadius: number,
+  ): RenderedConnection[] {
+    const db = this.connections;
+    const currentX = connection.x;
+    const currentY = connection.y;
+
+    // Binary search to find the closest y location.
+    let pointerMin = 0;
+    let pointerMax = db.length - 2;
+    let pointerMid = pointerMax;
+    while (pointerMin < pointerMid) {
+      if (db[pointerMid].y < currentY) {
+        pointerMin = pointerMid;
+      } else {
+        pointerMax = pointerMid;
+      }
+      pointerMid = Math.floor((pointerMin + pointerMax) / 2);
+    }
+
+    const neighbours: RenderedConnection[] = [];
+    /**
+     * Computes if the current connection is within the allowed radius of
+     * another connection. This function is a closure and has access to outside
+     * variables.
+     *
+     * @param yIndex The other connection's index in the database.
+     * @returns True if the current connection's vertical distance from the
+     *     other connection is less than the allowed radius.
+     */
+    function checkConnection(yIndex: number): boolean {
+      const dx = currentX - db[yIndex].x;
+      const dy = currentY - db[yIndex].y;
+      const r = Math.sqrt(dx * dx + dy * dy);
+      if (r <= maxRadius) {
+        neighbours.push(db[yIndex]);
+      }
+      return dy < maxRadius;
+    }
+
+    // Walk forward and back on the y axis looking for the closest x,y point.
+    pointerMin = pointerMid;
+    pointerMax = pointerMid;
+    if (db.length) {
+      while (pointerMin >= 0 && checkConnection(pointerMin)) {
+        pointerMin--;
+      }
+      do {
+        pointerMax++;
+      } while (pointerMax < db.length && checkConnection(pointerMax));
+    }
+
+    return neighbours;
+  }
+
+  /**
+   * Is the candidate connection close to the reference connection.
+   * Extremely fast; only looks at Y distance.
+   *
+   * @param index Index in database of candidate connection.
+   * @param baseY Reference connection's Y value.
+   * @param maxRadius The maximum radius to another connection.
+   * @returns True if connection is in range.
+   */
+  private isInYRange(index: number, baseY: number, maxRadius: number): boolean {
+    return Math.abs(this.connections[index].y - baseY) <= maxRadius;
+  }
+
+  /**
+   * Find the closest compatible connection to this connection.
+   *
+   * @param conn The connection searching for a compatible mate.
+   * @param maxRadius The maximum radius to another connection.
+   * @param dxy Offset between this connection's location in the database and
+   *     the current location (as a result of dragging).
+   * @returns Contains two properties: 'connection' which is either another
+   *     connection or null, and 'radius' which is the distance.
+   */
+  searchForClosest(
+    conn: RenderedConnection,
+    maxRadius: number,
+    dxy: Coordinate,
+  ): {connection: RenderedConnection | null; radius: number} {
+    if (!this.connections.length) {
+      // Don't bother.
+      return {connection: null, radius: maxRadius};
+    }
+
+    // Stash the values of x and y from before the drag.
+    const baseY = conn.y;
+    const baseX = conn.x;
+
+    conn.x = baseX + dxy.x;
+    conn.y = baseY + dxy.y;
+
+    // calculateIndexForYPos_ finds an index for insertion, which is always
+    // after any block with the same y index.  We want to search both forward
+    // and back, so search on both sides of the index.
+    const closestIndex = this.calculateIndexForYPos(conn.y);
+
+    let bestConnection = null;
+    let bestRadius = maxRadius;
+    let temp;
+
+    // Walk forward and back on the y axis looking for the closest x,y point.
+    let pointerMin = closestIndex - 1;
+    while (pointerMin >= 0 && this.isInYRange(pointerMin, conn.y, maxRadius)) {
+      temp = this.connections[pointerMin];
+      if (this.connectionChecker.canConnect(conn, temp, true, bestRadius)) {
+        bestConnection = temp;
+        bestRadius = temp.distanceFrom(conn);
+      }
+      pointerMin--;
+    }
+
+    let pointerMax = closestIndex;
+    while (
+      pointerMax < this.connections.length &&
+      this.isInYRange(pointerMax, conn.y, maxRadius)
+    ) {
+      temp = this.connections[pointerMax];
+      if (this.connectionChecker.canConnect(conn, temp, true, bestRadius)) {
+        bestConnection = temp;
+        bestRadius = temp.distanceFrom(conn);
+      }
+      pointerMax++;
+    }
+
+    // Reset the values of x and y.
+    conn.x = baseX;
+    conn.y = baseY;
+    // If there were no valid connections, bestConnection will be null.
+    return {connection: bestConnection, radius: bestRadius};
+  }
+
+  /**
+   * Initialize a set of connection DBs for a workspace.
+   *
+   * @param checker The workspace's connection checker, used to decide if
+   *     connections are valid during a drag.
+   * @returns Array of databases.
+   */
+  static init(checker: IConnectionChecker): ConnectionDB[] {
+    // Create four databases, one for each connection type.
+    const dbList = [];
+    dbList[ConnectionType.INPUT_VALUE] = new ConnectionDB(checker);
+    dbList[ConnectionType.OUTPUT_VALUE] = new ConnectionDB(checker);
+    dbList[ConnectionType.NEXT_STATEMENT] = new ConnectionDB(checker);
+    dbList[ConnectionType.PREVIOUS_STATEMENT] = new ConnectionDB(checker);
+    return dbList;
+  }
+}

package/core/connection_type.ts

@@ -0,0 +1,21 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+// Former goog.module ID: Blockly.ConnectionType
+
+/**
+ * Enum for the type of a connection or input.
+ */
+export enum ConnectionType {
+  // A right-facing value input.  E.g. 'set item to' or 'return'.
+  INPUT_VALUE = 1,
+  // A left-facing value output.  E.g. 'random fraction'.
+  OUTPUT_VALUE,
+  // A down-facing block stack.  E.g. 'if-do' or 'else'.
+  NEXT_STATEMENT,
+  // An up-facing block stack.  E.g. 'break out of loop'.
+  PREVIOUS_STATEMENT,
+}

package/core/constants.ts

@@ -0,0 +1,23 @@
+/**
+ * @license
+ * Copyright 2016 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+// Former goog.module ID: Blockly.constants
+
+/**
+ * The language-neutral ID given to the collapsed input.
+ */
+export const COLLAPSED_INPUT_NAME = '_TEMP_COLLAPSED_INPUT';
+
+/**
+ * The language-neutral ID given to the collapsed field.
+ */
+export const COLLAPSED_FIELD_NAME = '_TEMP_COLLAPSED_FIELD';
+
+/**
+ * The language-neutral ID for when the reason why a block is disabled is
+ * because the user manually disabled it, such as via the context menu.
+ */
+export const MANUALLY_DISABLED = 'MANUALLY_DISABLED';