blockly 8.0.5 → 9.0.0-beta.0

package/core/input.ts

@@ -0,0 +1,309 @@
+/**
+ * @license
+ * Copyright 2012 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * @fileoverview Object representing an input (value, statement, or dummy).
+ */
+
+/**
+ * Object representing an input (value, statement, or dummy).
+ * @class
+ */
+import * as goog from '../closure/goog/goog.js';
+goog.declareModuleId('Blockly.Input');
+
+// 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';
+
+
+/**
+ * Class for an input with an optional field.
+ * @alias Blockly.Input
+ */
+export class Input {
+  private sourceBlock_: Block;
+  fieldRow: Field[] = [];
+  align: Align;
+
+  /** Is the input visible? */
+  private visible_ = true;
+
+  /**
+   * @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(
+      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.');
+    }
+    this.sourceBlock_ = block;
+
+    /** Alignment of input's fields (left, right or centre). */
+    this.align = Align.LEFT;
+  }
+
+  /**
+   * Get the source block for this input.
+   * @return The source block, or null if there is none.
+   */
+  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 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: string|Field, opt_name?: string): Input {
+    this.insertFieldAt(this.fieldRow.length, field, opt_name);
+    return this;
+  }
+
+  /**
+   * Inserts a field (or label from string), and all prefix and suffix fields,
+   * at the location of the input's field row.
+   * @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: number, field: string|Field, opt_name?: string): number {
+    if (index < 0 || index > this.fieldRow.length) {
+      throw Error('index ' + index + ' out of bounds.');
+    }
+    // Falsy field values don't generate a field, unless the field is an empty
+    // string and named.
+    if (!field && !(field === '' && opt_name)) {
+      return index;
+    }
+
+    // Generate a FieldLabel when given a plain text field.
+    if (typeof field === 'string') {
+      field = fieldRegistry.fromJson({
+        'type': 'field_label',
+        'text': field,
+      }) as Field;
+    }
+
+    field.setSourceBlock(this.sourceBlock_);
+    if (this.sourceBlock_.rendered) {
+      field.init();
+      field.applyColour();
+    }
+    field.name = opt_name;
+    field.setVisible(this.isVisible());
+
+    if (field.prefixField) {
+      // Add any prefix.
+      index = this.insertFieldAt(index, field.prefixField);
+    }
+    // Add the field to the field row.
+    this.fieldRow.splice(index, 0, field);
+    index++;
+    if (field.suffixField) {
+      // Add any suffix.
+      index = this.insertFieldAt(index, field.suffixField);
+    }
+
+    if (this.sourceBlock_.rendered) {
+      (this.sourceBlock_ as BlockSvg).render();
+      // Adding a field will cause the block to change shape.
+      this.sourceBlock_.bumpNeighbours();
+    }
+    return index;
+  }
+
+  /**
+   * Remove a field from this input.
+   * @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: 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_ as BlockSvg).render();
+          // Removing a field will cause the block to change shape.
+          this.sourceBlock_.bumpNeighbours();
+        }
+        return true;
+      }
+    }
+    if (opt_quiet) {
+      return false;
+    }
+    throw Error('Field "' + name + '" not found.');
+  }
+
+  /**
+   * Gets whether this input is visible or not.
+   * @return True if visible.
+   */
+  isVisible(): boolean {
+    return this.visible_;
+  }
+
+  /**
+   * Sets whether this input is visible or not.
+   * Should only be used to collapse/uncollapse a block.
+   * @param visible True if visible.
+   * @return List of blocks to render.
+   * @internal
+   */
+  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: AnyDuringMigration[] = [];
+    if (this.visible_ === visible) {
+      return renderList;
+    }
+    this.visible_ = visible;
+
+    for (let y = 0, field; field = this.fieldRow[y]; y++) {
+      field.setVisible(visible);
+    }
+    if (this.connection) {
+      const renderedConnection = this.connection as RenderedConnection;
+      // Has a connection.
+      if (visible) {
+        renderList = renderedConnection.startTrackingAll();
+      } else {
+        renderedConnection.stopTrackingAll();
+      }
+      const child = renderedConnection.targetBlock();
+      if (child) {
+        child.getSvgRoot().style.display = visible ? 'block' : 'none';
+      }
+    }
+    return renderList;
+  }
+
+  /**
+   * Mark all fields on this input as dirty.
+   * @internal
+   */
+  markDirty() {
+    for (let y = 0, field; field = this.fieldRow[y]; y++) {
+      field.markDirty();
+    }
+  }
+
+  /**
+   * Change a connection's compatibility.
+   * @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: string|string[]|null): Input {
+    if (!this.connection) {
+      throw Error('This input does not have a connection.');
+    }
+    this.connection.setCheck(check);
+    return this;
+  }
+
+  /**
+   * Change the alignment of the connection's field(s).
+   * @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: Align): Input {
+    this.align = align;
+    if (this.sourceBlock_.rendered) {
+      const sourceBlock = this.sourceBlock_ as BlockSvg;
+      sourceBlock.render();
+    }
+    return this;
+  }
+
+  /**
+   * Changes the connection's shadow block.
+   * @param shadow DOM representation of a block or null.
+   * @return The input being modified (to allow chaining).
+   */
+  setShadowDom(shadow: Element|null): Input {
+    if (!this.connection) {
+      throw Error('This input does not have a connection.');
+    }
+    this.connection.setShadowDom(shadow);
+    return this;
+  }
+
+  /**
+   * Returns the XML representation of the connection's shadow block.
+   * @return Shadow DOM representation of a block or null.
+   */
+  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. */
+  init() {
+    if (!this.sourceBlock_.workspace.rendered) {
+      return;  // Headless blocks don't need fields initialized.
+    }
+    for (let i = 0; i < this.fieldRow.length; i++) {
+      this.fieldRow[i].init();
+    }
+  }
+
+  /**
+   * Sever all links to this input.
+   * @suppress {checkTypes}
+   */
+  dispose() {
+    for (let i = 0, field; field = this.fieldRow[i]; i++) {
+      field.dispose();
+    }
+    if (this.connection) {
+      this.connection.dispose();
+    }
+  }
+}
+
+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;