blockly 12.3.1 → 12.4.0

package/core/events/events_block_move.ts

@@ -0,0 +1,306 @@
+/**
+ * @license
+ * Copyright 2018 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Class for a block move event.
+ *
+ * @class
+ */
+// Former goog.module ID: Blockly.Events.BlockMove
+
+import type {Block} from '../block.js';
+import {ConnectionType} from '../connection_type.js';
+import * as registry from '../registry.js';
+import {Coordinate} from '../utils/coordinate.js';
+import type {Workspace} from '../workspace.js';
+import {BlockBase, BlockBaseJson} from './events_block_base.js';
+import {EventType} from './type.js';
+
+interface BlockLocation {
+  parentId?: string;
+  inputName?: string;
+  coordinate?: Coordinate;
+}
+
+/**
+ * Notifies listeners when a block is moved. This could be from one
+ * connection to another, or from one location on the workspace to another.
+ */
+export class BlockMove extends BlockBase {
+  override type = EventType.BLOCK_MOVE;
+
+  /** The ID of the old parent block. Undefined if it was a top-level block. */
+  oldParentId?: string;
+
+  /**
+   * The name of the old input. Undefined if it was a top-level block or the
+   * parent's next block.
+   */
+  oldInputName?: string;
+
+  /**
+   * The old X and Y workspace coordinates of the block if it was a top level
+   * block. Undefined if it was not a top level block.
+   */
+  oldCoordinate?: Coordinate;
+
+  /** The ID of the new parent block. Undefined if it is a top-level block. */
+  newParentId?: string;
+
+  /**
+   * The name of the new input. Undefined if it is a top-level block or the
+   * parent's next block.
+   */
+  newInputName?: string;
+
+  /**
+   * The new X and Y workspace coordinates of the block if it is a top-level
+   * block. Undefined if it is not a top level block.
+   */
+  newCoordinate?: Coordinate;
+
+  /**
+   * An explanation of what this move is for.  Known values include:
+   *  'drag' -- A drag operation completed.
+   *  'bump' -- Block got bumped away from an invalid connection.
+   *  'snap' -- Block got shifted to line up with the grid.
+   *  'inbounds' -- Block got pushed back into a non-scrolling workspace.
+   *  'connect' -- Block got connected to another block.
+   *  'disconnect' -- Block got disconnected from another block.
+   *  'create' -- Block created via XML.
+   *  'cleanup' -- Workspace aligned top-level blocks.
+   * Event merging may create multiple reasons: ['drag', 'bump', 'snap'].
+   */
+  reason?: string[];
+
+  /** @param opt_block The moved block.  Undefined for a blank event. */
+  constructor(opt_block?: Block) {
+    super(opt_block);
+
+    if (!opt_block) {
+      return;
+    }
+    // Blank event to be populated by fromJson.
+    if (opt_block.isShadow()) {
+      // Moving shadow blocks is handled via disconnection.
+      this.recordUndo = false;
+    }
+
+    const location = this.currentLocation();
+    this.oldParentId = location.parentId;
+    this.oldInputName = location.inputName;
+    this.oldCoordinate = location.coordinate;
+  }
+
+  /**
+   * Encode the event as JSON.
+   *
+   * @returns JSON representation.
+   */
+  override toJson(): BlockMoveJson {
+    const json = super.toJson() as BlockMoveJson;
+    json['oldParentId'] = this.oldParentId;
+    json['oldInputName'] = this.oldInputName;
+    if (this.oldCoordinate) {
+      json['oldCoordinate'] =
+        `${Math.round(this.oldCoordinate.x)}, ` +
+        `${Math.round(this.oldCoordinate.y)}`;
+    }
+    json['newParentId'] = this.newParentId;
+    json['newInputName'] = this.newInputName;
+    if (this.newCoordinate) {
+      json['newCoordinate'] =
+        `${Math.round(this.newCoordinate.x)}, ` +
+        `${Math.round(this.newCoordinate.y)}`;
+    }
+    if (this.reason) {
+      json['reason'] = this.reason;
+    }
+    if (!this.recordUndo) {
+      json['recordUndo'] = this.recordUndo;
+    }
+    return json;
+  }
+
+  /**
+   * Deserializes the JSON event.
+   *
+   * @param event The event to append new properties to. Should be a subclass
+   *     of BlockMove, but we can't specify that due to the fact that parameters
+   *     to static methods in subclasses must be supertypes of parameters to
+   *     static methods in superclasses.
+   * @internal
+   */
+  static fromJson(
+    json: BlockMoveJson,
+    workspace: Workspace,
+    event?: any,
+  ): BlockMove {
+    const newEvent = super.fromJson(
+      json,
+      workspace,
+      event ?? new BlockMove(),
+    ) as BlockMove;
+    newEvent.oldParentId = json['oldParentId'];
+    newEvent.oldInputName = json['oldInputName'];
+    if (json['oldCoordinate']) {
+      const xy = json['oldCoordinate'].split(',');
+      newEvent.oldCoordinate = new Coordinate(Number(xy[0]), Number(xy[1]));
+    }
+    newEvent.newParentId = json['newParentId'];
+    newEvent.newInputName = json['newInputName'];
+    if (json['newCoordinate']) {
+      const xy = json['newCoordinate'].split(',');
+      newEvent.newCoordinate = new Coordinate(Number(xy[0]), Number(xy[1]));
+    }
+    if (json['reason'] !== undefined) {
+      newEvent.reason = json['reason'];
+    }
+    if (json['recordUndo'] !== undefined) {
+      newEvent.recordUndo = json['recordUndo'];
+    }
+    return newEvent;
+  }
+
+  /** Record the block's new location.  Called after the move. */
+  recordNew() {
+    const location = this.currentLocation();
+    this.newParentId = location.parentId;
+    this.newInputName = location.inputName;
+    this.newCoordinate = location.coordinate;
+  }
+
+  /**
+   * Set the reason for a move event.
+   *
+   * @param reason Why is this move happening?  'drag', 'bump', 'snap', ...
+   */
+  setReason(reason: string[]) {
+    this.reason = reason;
+  }
+
+  /**
+   * Returns the parentId and input if the block is connected,
+   *   or the XY location if disconnected.
+   *
+   * @returns Collection of location info.
+   */
+  private currentLocation(): BlockLocation {
+    const workspace = this.getEventWorkspace_();
+    if (!this.blockId) {
+      throw new Error(
+        'The block ID is undefined. Either pass a block to ' +
+          'the constructor, or call fromJson',
+      );
+    }
+    const block = workspace.getBlockById(this.blockId);
+    if (!block) {
+      throw new Error(
+        'The block associated with the block move event ' +
+          'could not be found',
+      );
+    }
+    const location = {} as BlockLocation;
+    const parent = block.getParent();
+    if (parent) {
+      location.parentId = parent.id;
+      const input = parent.getInputWithBlock(block);
+      if (input) {
+        location.inputName = input.name;
+      }
+    } else {
+      location.coordinate = block.getRelativeToSurfaceXY();
+    }
+    return location;
+  }
+
+  /**
+   * Does this event record any change of state?
+   *
+   * @returns False if something changed.
+   */
+  override isNull(): boolean {
+    return (
+      this.oldParentId === this.newParentId &&
+      this.oldInputName === this.newInputName &&
+      Coordinate.equals(this.oldCoordinate, this.newCoordinate)
+    );
+  }
+
+  /**
+   * Run a move event.
+   *
+   * @param forward True if run forward, false if run backward (undo).
+   */
+  override run(forward: boolean) {
+    const workspace = this.getEventWorkspace_();
+    if (!this.blockId) {
+      throw new Error(
+        'The block ID is undefined. Either pass a block to ' +
+          'the constructor, or call fromJson',
+      );
+    }
+    const block = workspace.getBlockById(this.blockId);
+    if (!block) {
+      console.warn("Can't move non-existent block: " + this.blockId);
+      return;
+    }
+    const parentId = forward ? this.newParentId : this.oldParentId;
+    const inputName = forward ? this.newInputName : this.oldInputName;
+    const coordinate = forward ? this.newCoordinate : this.oldCoordinate;
+    let parentBlock: Block | null;
+    if (parentId) {
+      parentBlock = workspace.getBlockById(parentId);
+      if (!parentBlock) {
+        console.warn("Can't connect to non-existent block: " + parentId);
+        return;
+      }
+    }
+    if (block.getParent()) {
+      block.unplug();
+    }
+    if (coordinate) {
+      const xy = block.getRelativeToSurfaceXY();
+      block.moveBy(coordinate.x - xy.x, coordinate.y - xy.y, this.reason);
+    } else {
+      let blockConnection = block.outputConnection;
+      if (
+        !blockConnection ||
+        (block.previousConnection && block.previousConnection.isConnected())
+      ) {
+        blockConnection = block.previousConnection;
+      }
+      let parentConnection;
+      const connectionType = blockConnection?.type;
+      if (inputName) {
+        const input = parentBlock!.getInput(inputName);
+        if (input) {
+          parentConnection = input.connection;
+        }
+      } else if (connectionType === ConnectionType.PREVIOUS_STATEMENT) {
+        parentConnection = parentBlock!.nextConnection;
+      }
+      if (parentConnection && blockConnection) {
+        blockConnection.connect(parentConnection);
+      } else {
+        console.warn("Can't connect to non-existent input: " + inputName);
+      }
+    }
+  }
+}
+
+export interface BlockMoveJson extends BlockBaseJson {
+  oldParentId?: string;
+  oldInputName?: string;
+  oldCoordinate?: string;
+  newParentId?: string;
+  newInputName?: string;
+  newCoordinate?: string;
+  reason?: string[];
+  recordUndo?: boolean;
+}
+
+registry.register(registry.Type.EVENT, EventType.BLOCK_MOVE, BlockMove);

package/core/events/events_bubble_open.ts

@@ -0,0 +1,121 @@
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Events fired as a result of bubble open.
+ *
+ * @class
+ */
+
+// Former goog.module ID: Blockly.Events.BubbleOpen
+
+import type {BlockSvg} from '../block_svg.js';
+import * as registry from '../registry.js';
+import type {Workspace} from '../workspace.js';
+import type {AbstractEventJson} from './events_abstract.js';
+import {UiBase} from './events_ui_base.js';
+import {EventType} from './type.js';
+
+/**
+ * Class for a bubble open event.
+ */
+export class BubbleOpen extends UiBase {
+  /** The ID of the block the bubble is attached to. */
+  blockId?: string;
+
+  /** True if the bubble is opening, false if closing. */
+  isOpen?: boolean;
+
+  /** The type of bubble; one of 'mutator', 'comment', or 'warning'. */
+  bubbleType?: BubbleType;
+
+  override type = EventType.BUBBLE_OPEN;
+
+  /**
+   * @param opt_block The associated block. Undefined for a blank event.
+   * @param opt_isOpen Whether the bubble is opening (false if closing).
+   *     Undefined for a blank event.
+   * @param opt_bubbleType The type of bubble. One of 'mutator', 'comment' or
+   *     'warning'. Undefined for a blank event.
+   */
+  constructor(
+    opt_block?: BlockSvg,
+    opt_isOpen?: boolean,
+    opt_bubbleType?: BubbleType,
+  ) {
+    const workspaceId = opt_block ? opt_block.workspace.id : undefined;
+    super(workspaceId);
+    if (!opt_block) return;
+
+    this.blockId = opt_block.id;
+    this.isOpen = opt_isOpen;
+    this.bubbleType = opt_bubbleType;
+  }
+
+  /**
+   * Encode the event as JSON.
+   *
+   * @returns JSON representation.
+   */
+  override toJson(): BubbleOpenJson {
+    const json = super.toJson() as BubbleOpenJson;
+    if (this.isOpen === undefined) {
+      throw new Error(
+        'Whether this event is for opening the bubble is undefined. ' +
+          'Either pass the value to the constructor, or call fromJson',
+      );
+    }
+    if (!this.bubbleType) {
+      throw new Error(
+        'The type of bubble is undefined. Either pass the ' +
+          'value to the constructor, or call fromJson',
+      );
+    }
+    json['isOpen'] = this.isOpen;
+    json['bubbleType'] = this.bubbleType;
+    json['blockId'] = this.blockId || '';
+    return json;
+  }
+
+  /**
+   * Deserializes the JSON event.
+   *
+   * @param event The event to append new properties to. Should be a subclass
+   *     of BubbleOpen, but we can't specify that due to the fact that
+   *     parameters to static methods in subclasses must be supertypes of
+   *     parameters to static methods in superclasses.
+   * @internal
+   */
+  static fromJson(
+    json: BubbleOpenJson,
+    workspace: Workspace,
+    event?: any,
+  ): BubbleOpen {
+    const newEvent = super.fromJson(
+      json,
+      workspace,
+      event ?? new BubbleOpen(),
+    ) as BubbleOpen;
+    newEvent.isOpen = json['isOpen'];
+    newEvent.bubbleType = json['bubbleType'];
+    newEvent.blockId = json['blockId'];
+    return newEvent;
+  }
+}
+
+export enum BubbleType {
+  MUTATOR = 'mutator',
+  COMMENT = 'comment',
+  WARNING = 'warning',
+}
+
+export interface BubbleOpenJson extends AbstractEventJson {
+  isOpen: boolean;
+  bubbleType: BubbleType;
+  blockId: string;
+}
+
+registry.register(registry.Type.EVENT, EventType.BUBBLE_OPEN, BubbleOpen);

package/core/events/events_click.ts

@@ -0,0 +1,110 @@
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Events fired as a result of UI click in Blockly's editor.
+ *
+ * @class
+ */
+
+// Former goog.module ID: Blockly.Events.Click
+
+import type {Block} from '../block.js';
+import * as registry from '../registry.js';
+import {Workspace} from '../workspace.js';
+import {AbstractEventJson} from './events_abstract.js';
+import {UiBase} from './events_ui_base.js';
+import {EventType} from './type.js';
+
+/**
+ * Notifies listeners that some blockly element was clicked.
+ */
+export class Click extends UiBase {
+  /** The ID of the block that was clicked, if a block was clicked. */
+  blockId?: string;
+
+  /**
+   * The type of element that was clicked; one of 'block', 'workspace',
+   * or 'zoom_controls'.
+   */
+  targetType?: ClickTarget;
+  override type = EventType.CLICK;
+
+  /**
+   * @param opt_block The affected block. Null for click events that do not have
+   *     an associated block (i.e. workspace click). Undefined for a blank
+   *     event.
+   * @param opt_workspaceId The workspace identifier for this event.
+   *    Not used if block is passed. Undefined for a blank event.
+   * @param opt_targetType The type of element targeted by this click event.
+   *     Undefined for a blank event.
+   */
+  constructor(
+    opt_block?: Block | null,
+    opt_workspaceId?: string | null,
+    opt_targetType?: ClickTarget,
+  ) {
+    let workspaceId = opt_block ? opt_block.workspace.id : opt_workspaceId;
+    if (workspaceId === null) {
+      workspaceId = undefined;
+    }
+    super(workspaceId);
+
+    this.blockId = opt_block ? opt_block.id : undefined;
+    this.targetType = opt_targetType;
+  }
+
+  /**
+   * Encode the event as JSON.
+   *
+   * @returns JSON representation.
+   */
+  override toJson(): ClickJson {
+    const json = super.toJson() as ClickJson;
+    if (!this.targetType) {
+      throw new Error(
+        'The click target type is undefined. Either pass a block to ' +
+          'the constructor, or call fromJson',
+      );
+    }
+    json['targetType'] = this.targetType;
+    json['blockId'] = this.blockId;
+    return json;
+  }
+
+  /**
+   * Deserializes the JSON event.
+   *
+   * @param event The event to append new properties to. Should be a subclass
+   *     of Click, but we can't specify that due to the fact that parameters to
+   *     static methods in subclasses must be supertypes of parameters to
+   *     static methods in superclasses.
+   * @internal
+   */
+  static fromJson(json: ClickJson, workspace: Workspace, event?: any): Click {
+    const newEvent = super.fromJson(
+      json,
+      workspace,
+      event ?? new Click(),
+    ) as Click;
+    newEvent.targetType = json['targetType'];
+    newEvent.blockId = json['blockId'];
+    return newEvent;
+  }
+}
+
+export enum ClickTarget {
+  BLOCK = 'block',
+  WORKSPACE = 'workspace',
+  ZOOM_CONTROLS = 'zoom_controls',
+}
+
+export interface ClickJson extends AbstractEventJson {
+  targetType: ClickTarget;
+  blockId?: string;
+}
+
+registry.register(registry.Type.EVENT, EventType.CLICK, Click);

package/core/events/events_comment_base.ts

@@ -0,0 +1,126 @@
+/**
+ * @license
+ * Copyright 2018 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Base class for comment events.
+ *
+ * @class
+ */
+// Former goog.module ID: Blockly.Events.CommentBase
+
+import type {WorkspaceComment} from '../comments/workspace_comment.js';
+import * as comments from '../serialization/workspace_comments.js';
+import type {Workspace} from '../workspace.js';
+import {
+  Abstract as AbstractEvent,
+  AbstractEventJson,
+} from './events_abstract.js';
+import type {CommentCreate} from './events_comment_create.js';
+import type {CommentDelete} from './events_comment_delete.js';
+import {getGroup, getRecordUndo} from './utils.js';
+
+/**
+ * Abstract class for a comment event.
+ */
+export class CommentBase extends AbstractEvent {
+  override isBlank = true;
+
+  /** The ID of the comment that this event references. */
+  commentId?: string;
+
+  /**
+   * @param opt_comment The comment this event corresponds to.  Undefined for a
+   *     blank event.
+   */
+  constructor(opt_comment?: WorkspaceComment) {
+    super();
+    /** Whether or not an event is blank. */
+    this.isBlank = !opt_comment;
+
+    if (!opt_comment) return;
+
+    this.commentId = opt_comment.id;
+    this.workspaceId = opt_comment.workspace.id;
+    this.group = getGroup();
+    this.recordUndo = getRecordUndo();
+  }
+
+  /**
+   * Encode the event as JSON.
+   *
+   * @returns JSON representation.
+   */
+  override toJson(): CommentBaseJson {
+    const json = super.toJson() as CommentBaseJson;
+    if (!this.commentId) {
+      throw new Error(
+        'The comment ID is undefined. Either pass a comment to ' +
+          'the constructor, or call fromJson',
+      );
+    }
+    json['commentId'] = this.commentId;
+    return json;
+  }
+
+  /**
+   * Deserializes the JSON event.
+   *
+   * @param event The event to append new properties to. Should be a subclass
+   *     of CommentBase, but we can't specify that due to the fact that
+   *     parameters to static methods in subclasses must be supertypes of
+   *     parameters to static methods in superclasses.
+   * @internal
+   */
+  static fromJson(
+    json: CommentBaseJson,
+    workspace: Workspace,
+    event?: any,
+  ): CommentBase {
+    const newEvent = super.fromJson(
+      json,
+      workspace,
+      event ?? new CommentBase(),
+    ) as CommentBase;
+    newEvent.commentId = json['commentId'];
+    return newEvent;
+  }
+
+  /**
+   * Helper function for Comment[Create|Delete]
+   *
+   * @param event The event to run.
+   * @param create if True then Create, if False then Delete
+   */
+  static CommentCreateDeleteHelper(
+    event: CommentCreate | CommentDelete,
+    create: boolean,
+  ) {
+    const workspace = event.getEventWorkspace_();
+    if (create) {
+      if (!event.json) {
+        throw new Error('Encountered a comment event without proper json');
+      }
+      comments.append(event.json, workspace);
+    } else {
+      if (!event.commentId) {
+        throw new Error(
+          'The comment ID is undefined. Either pass a comment to ' +
+            'the constructor, or call fromJson',
+        );
+      }
+      const comment = workspace.getCommentById(event.commentId);
+      if (comment) {
+        comment.dispose();
+      } else {
+        console.warn("Can't delete non-existent comment: " + event.commentId);
+      }
+    }
+  }
+}
+
+export interface CommentBaseJson extends AbstractEventJson {
+  commentId: string;
+}