blockly 8.0.5 → 9.0.0-beta.0

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

@@ -13,8 +13,6 @@
  * while dragging blocks.
  */
 
-'use strict';
-
 /**
  * A class that manages a surface for dragging blocks.  When a
  * block drag is started, we move the block (and children) to a separate DOM
@@ -24,12 +22,14 @@
  * while dragging blocks.
  * @class
  */
-goog.module('Blockly.BlockDragSurfaceSvg');
+import * as goog from '../closure/goog/goog.js';
+goog.declareModuleId('Blockly.BlockDragSurfaceSvg');
 
-const dom = goog.require('Blockly.utils.dom');
-const svgMath = goog.require('Blockly.utils.svgMath');
-const {Coordinate} = goog.require('Blockly.utils.Coordinate');
-const {Svg} = goog.require('Blockly.utils.Svg');
+import {Coordinate} from './utils/coordinate.js';
+import * as deprecation from './utils/deprecation.js';
+import * as dom from './utils/dom.js';
+import {Svg} from './utils/svg.js';
+import * as svgMath from './utils/svg_math.js';
 
 
 /**
@@ -37,70 +37,40 @@ const {Svg} = goog.require('Blockly.utils.Svg');
  * SVG that contains only the currently moving block, or nothing.
  * @alias Blockly.BlockDragSurfaceSvg
  */
-const BlockDragSurfaceSvg = class {
+export class BlockDragSurfaceSvg {
+  /** The SVG drag surface. Set once by BlockDragSurfaceSvg.createDom. */
+  private svg_: SVGElement;
+
   /**
-   * @param {!Element} container Containing element.
+   * This is where blocks live while they are being dragged if the drag
+   * surface is enabled.
    */
-  constructor(container) {
-    /**
-     * The SVG drag surface. Set once by BlockDragSurfaceSvg.createDom.
-     * @type {?SVGElement}
-     * @private
-     */
-    this.SVG_ = null;
-
-    /**
-     * This is where blocks live while they are being dragged if the drag
-     * surface is enabled.
-     * @type {?SVGElement}
-     * @private
-     */
-    this.dragGroup_ = null;
-
-    /**
-     * Containing HTML element; parent of the workspace and the drag surface.
-     * @type {!Element}
-     * @private
-     */
-    this.container_ = container;
+  private dragGroup_: SVGElement;
 
-    /**
-     * Cached value for the scale of the drag surface.
-     * Used to set/get the correct translation during and after a drag.
-     * @type {number}
-     * @private
-     */
-    this.scale_ = 1;
+  /**
+   * Cached value for the scale of the drag surface.
+   * Used to set/get the correct translation during and after a drag.
+   */
+  private scale_ = 1;
 
-    /**
-     * Cached value for the translation of the drag surface.
-     * This translation is in pixel units, because the scale is applied to the
-     * drag group rather than the top-level SVG.
-     * @type {?Coordinate}
-     * @private
-     */
-    this.surfaceXY_ = null;
+  /**
+   * Cached value for the translation of the drag surface.
+   * This translation is in pixel units, because the scale is applied to the
+   * drag group rather than the top-level SVG.
+   */
+  private surfaceXY_: Coordinate = new Coordinate(0, 0);
+  private readonly childSurfaceXY_: Coordinate;
 
+  /** @param container Containing element. */
+  constructor(private readonly container: Element) {
     /**
      * Cached value for the translation of the child drag surface in pixel
      * units. Since the child drag surface tracks the translation of the
      * workspace this is ultimately the translation of the workspace.
-     * @type {!Coordinate}
-     * @private
      */
     this.childSurfaceXY_ = new Coordinate(0, 0);
 
-    this.createDom();
-  }
-
-  /**
-   * Create the drag surface and inject it into the container.
-   */
-  createDom() {
-    if (this.SVG_) {
-      return;  // Already created.
-    }
-    this.SVG_ = dom.createSvgElement(
+    this.svg_ = dom.createSvgElement(
         Svg.SVG, {
           'xmlns': dom.SVG_NS,
           'xmlns:html': dom.HTML_NS,
@@ -108,46 +78,49 @@ const BlockDragSurfaceSvg = class {
           'version': '1.1',
           'class': 'blocklyBlockDragSurface',
         },
-        this.container_);
-    this.dragGroup_ = dom.createSvgElement(Svg.G, {}, this.SVG_);
+        this.container);
+    this.dragGroup_ = dom.createSvgElement(Svg.G, {}, this.svg_ as SVGElement);
+  }
+
+  /** Create the drag surface and inject it into the container. */
+  createDom() {
+    // No alternative provided, because now the dom is just automatically
+    // created in the constructor now.
+    deprecation.warn('BlockDragSurfaceSvg createDom', 'June 2022', 'June 2023');
   }
 
   /**
    * Set the SVG blocks on the drag surface's group and show the surface.
    * Only one block group should be on the drag surface at a time.
-   * @param {!SVGElement} blocks Block or group of blocks to place on the drag
-   * surface.
+   * @param blocks Block or group of blocks to place on the drag surface.
    */
-  setBlocksAndShow(blocks) {
+  setBlocksAndShow(blocks: SVGElement) {
     if (this.dragGroup_.childNodes.length) {
       throw Error('Already dragging a block.');
     }
     // appendChild removes the blocks from the previous parent
     this.dragGroup_.appendChild(blocks);
-    this.SVG_.style.display = 'block';
+    this.svg_.style.display = 'block';
     this.surfaceXY_ = new Coordinate(0, 0);
   }
 
   /**
    * Translate and scale the entire drag surface group to the given position, to
    * keep in sync with the workspace.
-   * @param {number} x X translation in pixel coordinates.
-   * @param {number} y Y translation in pixel coordinates.
-   * @param {number} scale Scale of the group.
+   * @param x X translation in pixel coordinates.
+   * @param y Y translation in pixel coordinates.
+   * @param scale Scale of the group.
    */
-  translateAndScaleGroup(x, y, scale) {
+  translateAndScaleGroup(x: number, y: number, scale: number) {
     this.scale_ = scale;
-    // This is a work-around to prevent a the blocks from rendering
-    // fuzzy while they are being dragged on the drag surface.
-    const fixedX = x.toFixed(0);
-    const fixedY = y.toFixed(0);
-
-    this.childSurfaceXY_.x = parseInt(fixedX, 10);
-    this.childSurfaceXY_.y = parseInt(fixedY, 10);
-
-    this.dragGroup_.setAttribute(
+    // Make sure the svg exists on a pixel boundary so that it is not fuzzy.
+    const roundX = Math.round(x);
+    const roundY = Math.round(y);
+    this.childSurfaceXY_.x = roundX;
+    this.childSurfaceXY_.y = roundY;
+    this.dragGroup_!.setAttribute(
         'transform',
-        'translate(' + fixedX + ',' + fixedY + ') scale(' + scale + ')');
+        'translate(' + roundX + ',' + roundY + ') scale(' + scale + ')');
   }
 
   /**
@@ -155,23 +128,21 @@ const BlockDragSurfaceSvg = class {
    * @private
    */
   translateSurfaceInternal_() {
-    let x = this.surfaceXY_.x;
-    let y = this.surfaceXY_.y;
-    // This is a work-around to prevent a the blocks from rendering
-    // fuzzy while they are being dragged on the drag surface.
-    x = x.toFixed(0);
-    y = y.toFixed(0);
-    this.SVG_.style.display = 'block';
-
-    dom.setCssTransform(this.SVG_, 'translate3d(' + x + 'px, ' + y + 'px, 0)');
+    let x = this.surfaceXY_!.x;
+    let y = this.surfaceXY_!.y;
+    // Make sure the svg exists on a pixel boundary so that it is not fuzzy.
+    x = Math.round(x);
+    y = Math.round(y);
+    this.svg_.style.display = 'block';
+    dom.setCssTransform(this.svg_, 'translate3d(' + x + 'px, ' + y + 'px, 0)');
   }
 
   /**
    * Translates the entire surface by a relative offset.
-   * @param {number} deltaX Horizontal offset in pixel units.
-   * @param {number} deltaY Vertical offset in pixel units.
+   * @param deltaX Horizontal offset in pixel units.
+   * @param deltaY Vertical offset in pixel units.
    */
-  translateBy(deltaX, deltaY) {
+  translateBy(deltaX: number, deltaY: number) {
     const x = this.surfaceXY_.x + deltaX;
     const y = this.surfaceXY_.y + deltaY;
     this.surfaceXY_ = new Coordinate(x, y);
@@ -183,10 +154,10 @@ const BlockDragSurfaceSvg = class {
    * We translate the drag surface instead of the blocks inside the surface
    * so that the browser avoids repainting the SVG.
    * Because of this, the drag coordinates must be adjusted by scale.
-   * @param {number} x X translation for the entire surface.
-   * @param {number} y Y translation for the entire surface.
+   * @param x X translation for the entire surface.
+   * @param y Y translation for the entire surface.
    */
-  translateSurface(x, y) {
+  translateSurface(x: number, y: number) {
     this.surfaceXY_ = new Coordinate(x * this.scale_, y * this.scale_);
     this.translateSurfaceInternal_();
   }
@@ -194,47 +165,46 @@ const BlockDragSurfaceSvg = class {
   /**
    * Reports the surface translation in scaled workspace coordinates.
    * Use this when finishing a drag to return blocks to the correct position.
-   * @return {!Coordinate} Current translation of the surface.
+   * @return Current translation of the surface.
    */
-  getSurfaceTranslation() {
-    const xy = svgMath.getRelativeXY(/** @type {!SVGElement} */ (this.SVG_));
+  getSurfaceTranslation(): Coordinate {
+    const xy = svgMath.getRelativeXY(this.svg_ as SVGElement);
     return new Coordinate(xy.x / this.scale_, xy.y / this.scale_);
   }
 
   /**
    * Provide a reference to the drag group (primarily for
    * BlockSvg.getRelativeToSurfaceXY).
-   * @return {?SVGElement} Drag surface group element.
+   * @return Drag surface group element.
    */
-  getGroup() {
+  getGroup(): SVGElement|null {
     return this.dragGroup_;
   }
 
   /**
    * Returns the SVG drag surface.
-   * @returns {?SVGElement} The SVG drag surface.
+   * @returns The SVG drag surface.
    */
-  getSvgRoot() {
-    return this.SVG_;
+  getSvgRoot(): SVGElement|null {
+    return this.svg_;
   }
 
   /**
    * Get the current blocks on the drag surface, if any (primarily
    * for BlockSvg.getRelativeToSurfaceXY).
-   * @return {?Element} Drag surface block DOM element, or null if no blocks
-   *     exist.
+   * @return Drag surface block DOM element, or null if no blocks exist.
    */
-  getCurrentBlock() {
-    return /** @type {Element} */ (this.dragGroup_.firstChild);
+  getCurrentBlock(): Element|null {
+    return this.dragGroup_.firstChild as Element;
   }
 
   /**
    * Gets the translation of the child block surface
    * This surface is in charge of keeping track of how much the workspace has
    * moved.
-   * @return {!Coordinate} The amount the workspace has been moved.
+   * @return The amount the workspace has been moved.
    */
-  getWsTranslation() {
+  getWsTranslation(): Coordinate {
     // Returning a copy so the coordinate can not be changed outside this class.
     return this.childSurfaceXY_.clone();
   }
@@ -244,11 +214,11 @@ const BlockDragSurfaceSvg = class {
    * element.
    * If the block is being deleted it doesn't need to go back to the original
    * surface, since it would be removed immediately during dispose.
-   * @param {Element=} opt_newSurface Surface the dragging blocks should be
-   *     moved to, or null if the blocks should be removed from this surface
-   *     without being moved to a different surface.
+   * @param opt_newSurface Surface the dragging blocks should be moved to, or
+   *     null if the blocks should be removed from this surface without being
+   *     moved to a different surface.
    */
-  clearAndHide(opt_newSurface) {
+  clearAndHide(opt_newSurface?: Element) {
     const currentBlockElement = this.getCurrentBlock();
     if (currentBlockElement) {
       if (opt_newSurface) {
@@ -258,12 +228,10 @@ const BlockDragSurfaceSvg = class {
         this.dragGroup_.removeChild(currentBlockElement);
       }
     }
-    this.SVG_.style.display = 'none';
+    this.svg_.style.display = 'none';
     if (this.dragGroup_.childNodes.length) {
       throw Error('Drag group was not cleared.');
     }
-    this.surfaceXY_ = null;
+    this.surfaceXY_ = new Coordinate(0, 0);
   }
-};
-
-exports.BlockDragSurfaceSvg = BlockDragSurfaceSvg;
+}

package/core/block_dragger.d.ts

@@ -0,0 +1,143 @@
+/**
+ * @license
+ * Copyright 2017 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import './events/events_block_drag.js';
+import type { BlockSvg } from './block_svg.js';
+import type { Icon } from './icon.js';
+import { InsertionMarkerManager } from './insertion_marker_manager.js';
+import type { IBlockDragger } from './interfaces/i_block_dragger.js';
+import { Coordinate } from './utils/coordinate.js';
+import type { WorkspaceSvg } from './workspace_svg.js';
+/**
+ * Class for a block dragger.  It moves blocks around the workspace when they
+ * are being dragged by a mouse or touch.
+ * @alias Blockly.BlockDragger
+ */
+export declare class BlockDragger implements IBlockDragger {
+    /** The top block in the stack that is being dragged. */
+    protected draggingBlock_: BlockSvg;
+    protected draggedConnectionManager_: InsertionMarkerManager;
+    /** The workspace on which the block is being dragged. */
+    protected workspace_: WorkspaceSvg;
+    /** Which drag area the mouse pointer is over, if any. */
+    private dragTarget_;
+    /** Whether the block would be deleted if dropped immediately. */
+    protected wouldDeleteBlock_: boolean;
+    protected startXY_: Coordinate;
+    protected dragIconData_: IconPositionData[];
+    /**
+     * @param block The block to drag.
+     * @param workspace The workspace to drag on.
+     */
+    constructor(block: BlockSvg, workspace: WorkspaceSvg);
+    /**
+     * Sever all links from this object.
+     * @internal
+     */
+    dispose(): void;
+    /**
+     * Start dragging a block.  This includes moving it to the drag surface.
+     * @param currentDragDeltaXY How far the pointer has moved from the position
+     *     at mouse down, in pixel units.
+     * @param healStack Whether or not to heal the stack after disconnecting.
+     */
+    startDrag(currentDragDeltaXY: Coordinate, healStack: boolean): void;
+    /**
+     * Whether or not we should disconnect the block when a drag is started.
+     * @param healStack Whether or not to heal the stack after disconnecting.
+     * @return True to disconnect the block, false otherwise.
+     */
+    protected shouldDisconnect_(healStack: boolean): boolean;
+    /**
+     * Disconnects the block and moves it to a new location.
+     * @param healStack Whether or not to heal the stack after disconnecting.
+     * @param currentDragDeltaXY How far the pointer has moved from the position
+     *     at mouse down, in pixel units.
+     */
+    protected disconnectBlock_(healStack: boolean, currentDragDeltaXY: Coordinate): void;
+    /** Fire a UI event at the start of a block drag. */
+    protected fireDragStartEvent_(): void;
+    /**
+     * Execute a step of block dragging, based on the given event.  Update the
+     * display accordingly.
+     * @param e The most recent move event.
+     * @param currentDragDeltaXY How far the pointer has moved from the position
+     *     at the start of the drag, in pixel units.
+     */
+    drag(e: Event, currentDragDeltaXY: Coordinate): void;
+    /**
+     * Finish a block drag and put the block back on the workspace.
+     * @param e The mouseup/touchend event.
+     * @param currentDragDeltaXY How far the pointer has moved from the position
+     *     at the start of the drag, in pixel units.
+     */
+    endDrag(e: Event, currentDragDeltaXY: Coordinate): void;
+    /**
+     * Calculates the drag delta and new location values after a block is dragged.
+     * @param currentDragDeltaXY How far the pointer has moved from the start of
+     *     the drag, in pixel units.
+     * @return New location after drag. delta is in workspace units. newLocation
+     *     is the new coordinate where the block should end up.
+     */
+    protected getNewLocationAfterDrag_(currentDragDeltaXY: Coordinate): {
+        delta: Coordinate;
+        newLocation: Coordinate;
+    };
+    /**
+     * May delete the dragging block, if allowed. If `this.wouldDeleteBlock_` is
+     * not true, the block will not be deleted. This should be called at the end
+     * of a block drag.
+     * @return True if the block was deleted.
+     */
+    protected maybeDeleteBlock_(): boolean;
+    /**
+     * Updates the necessary information to place a block at a certain location.
+     * @param delta The change in location from where the block started the drag
+     *     to where it ended the drag.
+     */
+    protected updateBlockAfterMove_(delta: Coordinate): void;
+    /** Fire a UI event at the end of a block drag. */
+    protected fireDragEndEvent_(): void;
+    /**
+     * Adds or removes the style of the cursor for the toolbox.
+     * This is what changes the cursor to display an x when a deletable block is
+     * held over the toolbox.
+     * @param isEnd True if we are at the end of a drag, false otherwise.
+     */
+    protected updateToolboxStyle_(isEnd: boolean): void;
+    /** Fire a move event at the end of a block drag. */
+    protected fireMoveEvent_(): void;
+    /**
+     * Update the cursor (and possibly the trash can lid) to reflect whether the
+     * dragging block would be deleted if released immediately.
+     */
+    protected updateCursorDuringBlockDrag_(): void;
+    /**
+     * Convert a coordinate object from pixels to workspace units, including a
+     * correction for mutator workspaces.
+     * This function does not consider differing origins.  It simply scales the
+     * input's x and y values.
+     * @param pixelCoord A coordinate with x and y values in CSS pixel units.
+     * @return The input coordinate divided by the workspace scale.
+     */
+    protected pixelsToWorkspaceUnits_(pixelCoord: Coordinate): Coordinate;
+    /**
+     * Move all of the icons connected to this drag.
+     * @param dxy How far to move the icons from their original positions, in
+     *     workspace units.
+     */
+    protected dragIcons_(dxy: Coordinate): void;
+    /**
+     * 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.
+     */
+    getInsertionMarkers(): BlockSvg[];
+}
+/** Data about the position of a given icon. */
+export interface IconPositionData {
+    location: Coordinate;
+    icon: Icon;
+}