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

package/core/{input.js → input.ts}

@@ -7,104 +7,75 @@
 /**
  * @fileoverview Object representing an input (value, statement, or dummy).
  */
-'use strict';
 
 /**
  * Object representing an input (value, statement, or dummy).
  * @class
  */
-goog.module('Blockly.Input');
+import * as goog from '../closure/goog/goog.js';
+goog.declareModuleId('Blockly.Input');
 
-const fieldRegistry = goog.require('Blockly.fieldRegistry');
-/* eslint-disable-next-line no-unused-vars */
-const {BlockSvg} = goog.requireType('Blockly.BlockSvg');
-/* eslint-disable-next-line no-unused-vars */
-const {Block} = goog.requireType('Blockly.Block');
-/* eslint-disable-next-line no-unused-vars */
-const {Connection} = goog.requireType('Blockly.Connection');
-/* eslint-disable-next-line no-unused-vars */
-const {Field} = goog.requireType('Blockly.Field');
-/* eslint-disable-next-line no-unused-vars */
-const {RenderedConnection} = goog.requireType('Blockly.RenderedConnection');
-const {inputTypes} = goog.require('Blockly.inputTypes');
-/** @suppress {extraRequire} */
-goog.require('Blockly.FieldLabel');
+// Unused import preserved for side-effects. Remove if unneeded.
+import './field_label.js';
 
+import type {Block} from './block.js';
+import type {BlockSvg} from './block_svg.js';
+import type {Connection} from './connection.js';
+import type {Field} from './field.js';
+import * as fieldRegistry from './field_registry.js';
+import {inputTypes} from './input_types.js';
+import type {RenderedConnection} from './rendered_connection.js';
 
-/**
- * Enum for alignment of inputs.
- * @enum {number}
- * @alias Blockly.Input.Align
- */
-const Align = {
-  LEFT: -1,
-  CENTRE: 0,
-  RIGHT: 1,
-};
-exports.Align = Align;
 
 /**
  * Class for an input with an optional field.
  * @alias Blockly.Input
  */
-class Input {
+export class Input {
+  private sourceBlock_: Block;
+  fieldRow: Field[] = [];
+  align: Align;
+
+  /** Is the input visible? */
+  private visible_ = true;
+
   /**
-   * @param {number} type The type of the input.
-   * @param {string} name Language-neutral identifier which may used to find
-   *     this input again.
-   * @param {!Block} block The block containing this input.
-   * @param {Connection} connection Optional connection for this input.
+   * @param type The type of the input.
+   * @param name Language-neutral identifier which may used to find this input
+   *     again.
+   * @param block The block containing this input.
+   * @param connection Optional connection for this input.
    */
-  constructor(type, name, block, connection) {
+  constructor(
+      public type: number, public name: string, block: Block,
+      public connection: Connection|null) {
     if (type !== inputTypes.DUMMY && !name) {
       throw Error(
           'Value inputs and statement inputs must have non-empty name.');
     }
-    /** @type {number} */
-    this.type = type;
-    /** @type {string} */
-    this.name = name;
-    /**
-     * @type {!Block}
-     * @private
-     */
     this.sourceBlock_ = block;
-    /** @type {Connection} */
-    this.connection = connection;
-    /** @type {!Array<!Field>} */
-    this.fieldRow = [];
 
-    /**
-     * Alignment of input's fields (left, right or centre).
-     * @type {number}
-     */
+    /** Alignment of input's fields (left, right or centre). */
     this.align = Align.LEFT;
-
-    /**
-     * Is the input visible?
-     * @type {boolean}
-     * @private
-     */
-    this.visible_ = true;
   }
 
   /**
    * Get the source block for this input.
-   * @return {?Block} The source block, or null if there is none.
+   * @return The source block, or null if there is none.
    */
-  getSourceBlock() {
+  getSourceBlock(): Block {
     return this.sourceBlock_;
   }
 
   /**
    * Add a field (or label from string), and all prefix and suffix fields, to
    * the end of the input's field row.
-   * @param {string|!Field} field Something to add as a field.
-   * @param {string=} opt_name Language-neutral identifier which may used to
-   *     find this field again.  Should be unique to the host block.
-   * @return {!Input} The input being append to (to allow chaining).
+   * @param field Something to add as a field.
+   * @param opt_name Language-neutral identifier which may used to find this
+   *     field again.  Should be unique to the host block.
+   * @return The input being append to (to allow chaining).
    */
-  appendField(field, opt_name) {
+  appendField(field: string|Field, opt_name?: string): Input {
     this.insertFieldAt(this.fieldRow.length, field, opt_name);
     return this;
   }
@@ -112,13 +83,13 @@ class Input {
   /**
    * Inserts a field (or label from string), and all prefix and suffix fields,
    * at the location of the input's field row.
-   * @param {number} index The index at which to insert field.
-   * @param {string|!Field} field Something to add as a field.
-   * @param {string=} opt_name Language-neutral identifier which may used to
-   *     find this field again.  Should be unique to the host block.
-   * @return {number} The index following the last inserted field.
+   * @param index The index at which to insert field.
+   * @param field Something to add as a field.
+   * @param opt_name Language-neutral identifier which may used to find this
+   *     field again.  Should be unique to the host block.
+   * @return The index following the last inserted field.
    */
-  insertFieldAt(index, field, opt_name) {
+  insertFieldAt(index: number, field: string|Field, opt_name?: string): number {
     if (index < 0 || index > this.fieldRow.length) {
       throw Error('index ' + index + ' out of bounds.');
     }
@@ -130,10 +101,10 @@ class Input {
 
     // Generate a FieldLabel when given a plain text field.
     if (typeof field === 'string') {
-      field = /** @type {!Field} **/ (fieldRegistry.fromJson({
+      field = fieldRegistry.fromJson({
         'type': 'field_label',
         'text': field,
-      }));
+      }) as Field;
     }
 
     field.setSourceBlock(this.sourceBlock_);
@@ -157,8 +128,7 @@ class Input {
     }
 
     if (this.sourceBlock_.rendered) {
-      this.sourceBlock_ = /** @type {!BlockSvg} */ (this.sourceBlock_);
-      this.sourceBlock_.render();
+      (this.sourceBlock_ as BlockSvg).render();
       // Adding a field will cause the block to change shape.
       this.sourceBlock_.bumpNeighbours();
     }
@@ -167,21 +137,19 @@ class Input {
 
   /**
    * Remove a field from this input.
-   * @param {string} name The name of the field.
-   * @param {boolean=} opt_quiet True to prevent an error if field is not
-   *     present.
-   * @return {boolean} True if operation succeeds, false if field is not present
-   *     and opt_quiet is true.
+   * @param name The name of the field.
+   * @param opt_quiet True to prevent an error if field is not present.
+   * @return True if operation succeeds, false if field is not present and
+   *     opt_quiet is true.
    * @throws {Error} if the field is not present and opt_quiet is false.
    */
-  removeField(name, opt_quiet) {
-    for (let i = 0, field; (field = this.fieldRow[i]); i++) {
+  removeField(name: string, opt_quiet?: boolean): boolean {
+    for (let i = 0, field; field = this.fieldRow[i]; i++) {
       if (field.name === name) {
         field.dispose();
         this.fieldRow.splice(i, 1);
         if (this.sourceBlock_.rendered) {
-          this.sourceBlock_ = /** @type {!BlockSvg} */ (this.sourceBlock_);
-          this.sourceBlock_.render();
+          (this.sourceBlock_ as BlockSvg).render();
           // Removing a field will cause the block to change shape.
           this.sourceBlock_.bumpNeighbours();
         }
@@ -196,42 +164,41 @@ class Input {
 
   /**
    * Gets whether this input is visible or not.
-   * @return {boolean} True if visible.
+   * @return True if visible.
    */
-  isVisible() {
+  isVisible(): boolean {
     return this.visible_;
   }
 
   /**
    * Sets whether this input is visible or not.
    * Should only be used to collapse/uncollapse a block.
-   * @param {boolean} visible True if visible.
-   * @return {!Array<!BlockSvg>} List of blocks to render.
-   * @package
+   * @param visible True if visible.
+   * @return List of blocks to render.
+   * @internal
    */
-  setVisible(visible) {
+  setVisible(visible: boolean): BlockSvg[] {
     // Note: Currently there are only unit tests for block.setCollapsed()
     // because this function is package. If this function goes back to being a
     // public API tests (lots of tests) should be added.
-    let renderList = [];
+    let renderList: AnyDuringMigration[] = [];
     if (this.visible_ === visible) {
       return renderList;
     }
     this.visible_ = visible;
 
-    for (let y = 0, field; (field = this.fieldRow[y]); y++) {
+    for (let y = 0, field; field = this.fieldRow[y]; y++) {
       field.setVisible(visible);
     }
     if (this.connection) {
-      this.connection =
-          /** @type {!RenderedConnection} */ (this.connection);
+      const renderedConnection = this.connection as RenderedConnection;
       // Has a connection.
       if (visible) {
-        renderList = this.connection.startTrackingAll();
+        renderList = renderedConnection.startTrackingAll();
       } else {
-        this.connection.stopTrackingAll();
+        renderedConnection.stopTrackingAll();
       }
-      const child = this.connection.targetBlock();
+      const child = renderedConnection.targetBlock();
       if (child) {
         child.getSvgRoot().style.display = visible ? 'block' : 'none';
       }
@@ -241,21 +208,21 @@ class Input {
 
   /**
    * Mark all fields on this input as dirty.
-   * @package
+   * @internal
    */
   markDirty() {
-    for (let y = 0, field; (field = this.fieldRow[y]); y++) {
+    for (let y = 0, field; field = this.fieldRow[y]; y++) {
       field.markDirty();
     }
   }
 
   /**
    * Change a connection's compatibility.
-   * @param {string|Array<string>|null} check Compatible value type or
-   *     list of value types.  Null if all types are compatible.
-   * @return {!Input} The input being modified (to allow chaining).
+   * @param check Compatible value type or list of value types.  Null if all
+   *     types are compatible.
+   * @return The input being modified (to allow chaining).
    */
-  setCheck(check) {
+  setCheck(check: string|string[]|null): Input {
     if (!this.connection) {
       throw Error('This input does not have a connection.');
     }
@@ -265,25 +232,25 @@ class Input {
 
   /**
    * Change the alignment of the connection's field(s).
-   * @param {number} align One of the values of Align
-   *   In RTL mode directions are reversed, and Align.RIGHT aligns to the left.
-   * @return {!Input} The input being modified (to allow chaining).
+   * @param align One of the values of Align.  In RTL mode directions
+   *     are reversed, and Align.RIGHT aligns to the left.
+   * @return The input being modified (to allow chaining).
    */
-  setAlign(align) {
+  setAlign(align: Align): Input {
     this.align = align;
     if (this.sourceBlock_.rendered) {
-      this.sourceBlock_ = /** @type {!BlockSvg} */ (this.sourceBlock_);
-      this.sourceBlock_.render();
+      const sourceBlock = this.sourceBlock_ as BlockSvg;
+      sourceBlock.render();
     }
     return this;
   }
 
   /**
    * Changes the connection's shadow block.
-   * @param {?Element} shadow DOM representation of a block or null.
-   * @return {!Input} The input being modified (to allow chaining).
+   * @param shadow DOM representation of a block or null.
+   * @return The input being modified (to allow chaining).
    */
-  setShadowDom(shadow) {
+  setShadowDom(shadow: Element|null): Input {
     if (!this.connection) {
       throw Error('This input does not have a connection.');
     }
@@ -293,18 +260,16 @@ class Input {
 
   /**
    * Returns the XML representation of the connection's shadow block.
-   * @return {?Element} Shadow DOM representation of a block or null.
+   * @return Shadow DOM representation of a block or null.
    */
-  getShadowDom() {
+  getShadowDom(): Element|null {
     if (!this.connection) {
       throw Error('This input does not have a connection.');
     }
     return this.connection.getShadowDom();
   }
 
-  /**
-   * Initialize the fields on this input.
-   */
+  /** Initialize the fields on this input. */
   init() {
     if (!this.sourceBlock_.workspace.rendered) {
       return;  // Headless blocks don't need fields initialized.
@@ -319,14 +284,26 @@ class Input {
    * @suppress {checkTypes}
    */
   dispose() {
-    for (let i = 0, field; (field = this.fieldRow[i]); i++) {
+    for (let i = 0, field; field = this.fieldRow[i]; i++) {
       field.dispose();
     }
     if (this.connection) {
       this.connection.dispose();
     }
-    this.sourceBlock_ = null;
   }
 }
 
-exports.Input = Input;
+export namespace Input {
+  /**
+   * Enum for alignment of inputs.
+   * @alias Blockly.Input.Align
+   */
+  export enum Align {
+    LEFT = -1,
+    CENTRE = 0,
+    RIGHT = 1,
+  }
+}
+
+export type Align = Input.Align;
+export const Align = Input.Align;

package/core/input_types.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Enum for the type of a connection or input.
+ * @alias Blockly.inputTypes
+ */
+export declare enum inputTypes {
+    VALUE = 1,
+    STATEMENT = 3,
+    DUMMY = 5
+}

package/core/{input_types.js → input_types.ts}

@@ -8,29 +8,25 @@
  * @fileoverview An enum for the possible types of inputs.
  */
 
-'use strict';
-
 /**
  * An enum for the possible types of inputs.
  * @namespace Blockly.inputTypes
  */
-goog.module('Blockly.inputTypes');
+import * as goog from '../closure/goog/goog.js';
+goog.declareModuleId('Blockly.inputTypes');
 
-const {ConnectionType} = goog.require('Blockly.ConnectionType');
+import {ConnectionType} from './connection_type.js';
 
 
 /**
  * Enum for the type of a connection or input.
- * @enum {number}
  * @alias Blockly.inputTypes
  */
-const inputTypes = {
+export enum inputTypes {
   // A right-facing value input.  E.g. 'set item to' or 'return'.
-  VALUE: ConnectionType.INPUT_VALUE,
+  VALUE = ConnectionType.INPUT_VALUE,
   // A down-facing block stack.  E.g. 'if-do' or 'else'.
-  STATEMENT: ConnectionType.NEXT_STATEMENT,
+  STATEMENT = ConnectionType.NEXT_STATEMENT,
   // A dummy input.  Used to add field(s) with no input.
-  DUMMY: 5,
-};
-
-exports.inputTypes = inputTypes;
+  DUMMY = 5
+}

package/core/insertion_marker_manager.d.ts

@@ -0,0 +1,212 @@
+/**
+ * @license
+ * Copyright 2017 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { BlockSvg } from './block_svg.js';
+import type { IDragTarget } from './interfaces/i_drag_target.js';
+import type { Coordinate } from './utils/coordinate.js';
+/**
+ * Class that controls updates to connections during drags.  It is primarily
+ * responsible for finding the closest eligible connection and highlighting or
+ * unhighlighting it as needed during a drag.
+ * @alias Blockly.InsertionMarkerManager
+ */
+export declare class InsertionMarkerManager {
+    private readonly topBlock_;
+    private readonly workspace_;
+    /**
+     * The last connection on the stack, if it's not the last connection on the
+     * first block.
+     * Set in initAvailableConnections, if at all.
+     */
+    private lastOnStack_;
+    /**
+     * The insertion marker corresponding to the last block in the stack, if
+     * that's not the same as the first block in the stack.
+     * Set in initAvailableConnections, if at all
+     */
+    private lastMarker_;
+    private firstMarker_;
+    /**
+     * The connection that this block would connect to if released immediately.
+     * Updated on every mouse move.
+     * This is not on any of the blocks that are being dragged.
+     */
+    private closestConnection_;
+    /**
+     * The connection that would connect to this.closestConnection_ if this
+     * block were released immediately. Updated on every mouse move. This is on
+     * the top block that is being dragged or the last block in the dragging
+     * stack.
+     */
+    private localConnection_;
+    /**
+     * Whether the block would be deleted if it were dropped immediately.
+     * Updated on every mouse move.
+     */
+    private wouldDeleteBlock_;
+    /**
+     * Connection on the insertion marker block that corresponds to
+     * this.localConnection_ on the currently dragged block.
+     */
+    private markerConnection_;
+    /** The block that currently has an input being highlighted, or null. */
+    private highlightedBlock_;
+    /** The block being faded to indicate replacement, or null. */
+    private fadedBlock_;
+    private availableConnections_;
+    /** @param block The top block in the stack being dragged. */
+    constructor(block: BlockSvg);
+    /**
+     * Sever all links from this object.
+     * @internal
+     */
+    dispose(): void;
+    /**
+     * Update the available connections for the top block. These connections can
+     * change if a block is unplugged and the stack is healed.
+     * @internal
+     */
+    updateAvailableConnections(): void;
+    /**
+     * Return whether the block would be deleted if dropped immediately, based on
+     * information from the most recent move event.
+     * @return True if the block would be deleted if dropped immediately.
+     * @internal
+     */
+    wouldDeleteBlock(): boolean;
+    /**
+     * Return whether the block would be connected if dropped immediately, based
+     * on information from the most recent move event.
+     * @return True if the block would be connected if dropped immediately.
+     * @internal
+     */
+    wouldConnectBlock(): boolean;
+    /**
+     * Connect to the closest connection and render the results.
+     * This should be called at the end of a drag.
+     * @internal
+     */
+    applyConnections(): void;
+    /**
+     * Update connections based on the most recent move location.
+     * @param dxy Position relative to drag start, in workspace units.
+     * @param dragTarget The drag target that the block is currently over.
+     * @internal
+     */
+    update(dxy: Coordinate, dragTarget: IDragTarget | null): void;
+    /**
+     * Create an insertion marker that represents the given block.
+     * @param sourceBlock The block that the insertion marker will represent.
+     * @return The insertion marker that represents the given block.
+     */
+    private createMarkerBlock_;
+    /**
+     * Populate the list of available connections on this block stack.  This
+     * should only be called once, at the beginning of a drag. If the stack has
+     * more than one block, this function will populate lastOnStack_ and create
+     * the corresponding insertion marker.
+     * @return A list of available connections.
+     */
+    private initAvailableConnections_;
+    /**
+     * Whether the previews (insertion marker and replacement marker) should be
+     * updated based on the closest candidate and the current drag distance.
+     * @param candidate An object containing a local connection, a closest
+     *     connection, and a radius.  Returned by getCandidate_.
+     * @param dxy Position relative to drag start, in workspace units.
+     * @return Whether the preview should be updated.
+     */
+    private shouldUpdatePreviews_;
+    /**
+     * Find the nearest valid connection, which may be the same as the current
+     * closest connection.
+     * @param dxy Position relative to drag start, in workspace units.
+     * @return An object containing a local connection, a closest connection, and
+     *     a radius.
+     */
+    private getCandidate_;
+    /**
+     * Decide the radius at which to start searching for the closest connection.
+     * @return The radius at which to start the search for the closest connection.
+     */
+    private getStartRadius_;
+    /**
+     * Whether ending the drag would delete the block.
+     * @param candidate An object containing a local connection, a closest
+     *     connection, and a radius.
+     * @param dragTarget The drag target that the block is currently over.
+     * @return Whether dropping the block immediately would delete the block.
+     */
+    private shouldDelete_;
+    /**
+     * Show an insertion marker or replacement highlighting during a drag, if
+     * needed.
+     * At the beginning of this function, this.localConnection_ and
+     * this.closestConnection_ should both be null.
+     * @param candidate An object containing a local connection, a closest
+     *     connection, and a radius.
+     */
+    private maybeShowPreview_;
+    /**
+     * A preview should be shown.  This function figures out if it should be a
+     * block highlight or an insertion marker, and shows the appropriate one.
+     */
+    private showPreview_;
+    /**
+     * Show an insertion marker or replacement highlighting during a drag, if
+     * needed.
+     * At the end of this function, this.localConnection_ and
+     * this.closestConnection_ should both be null.
+     * @param candidate An object containing a local connection, a closest
+     *     connection, and a radius.
+     */
+    private maybeHidePreview_;
+    /**
+     * A preview should be hidden.  This function figures out if it is a block
+     *  highlight or an insertion marker, and hides the appropriate one.
+     */
+    private hidePreview_;
+    /**
+     * Shows an insertion marker connected to the appropriate blocks (based on
+     * manager state).
+     */
+    private showInsertionMarker_;
+    /**
+     * Disconnects and hides the current insertion marker. Should return the
+     * blocks to their original state.
+     */
+    private hideInsertionMarker_;
+    /** Shows an outline around the input the closest connection belongs to. */
+    private showInsertionInputOutline_;
+    /** Hides any visible input outlines. */
+    private hideInsertionInputOutline_;
+    /**
+     * Shows a replacement fade affect on the closest connection's target block
+     * (the block that is currently connected to it).
+     */
+    private showReplacementFade_;
+    /** Hides/Removes any visible fade affects. */
+    private hideReplacementFade_;
+    /**
+     * Get a list of the insertion markers that currently exist.  Drags have 0, 1,
+     * or 2 insertion markers.
+     * @return A possibly empty list of insertion marker blocks.
+     * @internal
+     */
+    getInsertionMarkers(): BlockSvg[];
+}
+export declare namespace InsertionMarkerManager {
+    /**
+     * An enum describing different kinds of previews the InsertionMarkerManager
+     * could display.
+     */
+    enum PREVIEW_TYPE {
+        INSERTION_MARKER = 0,
+        INPUT_OUTLINE = 1,
+        REPLACEMENT_FADE = 2
+    }
+}
+export declare type PreviewType = InsertionMarkerManager.PREVIEW_TYPE;
+export declare const PreviewType: typeof InsertionMarkerManager.PREVIEW_TYPE;