blockly 12.3.1 → 12.4.0

package/core/events/events_var_type_change.ts

@@ -0,0 +1,122 @@
+/**
+ * @license
+ * Copyright 2024 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Class for a variable type change event.
+ *
+ * @class
+ */
+
+import type {
+  IVariableModel,
+  IVariableState,
+} from '../interfaces/i_variable_model.js';
+import * as registry from '../registry.js';
+
+import type {Workspace} from '../workspace.js';
+import {VarBase, VarBaseJson} from './events_var_base.js';
+import {EventType} from './type.js';
+
+/**
+ * Notifies listeners that a variable's type has changed.
+ */
+export class VarTypeChange extends VarBase {
+  override type = EventType.VAR_TYPE_CHANGE;
+
+  /**
+   * @param variable The variable whose type changed. Undefined for a blank event.
+   * @param oldType The old type of the variable. Undefined for a blank event.
+   * @param newType The new type of the variable. Undefined for a blank event.
+   */
+  constructor(
+    variable?: IVariableModel<IVariableState>,
+    public oldType?: string,
+    public newType?: string,
+  ) {
+    super(variable);
+  }
+
+  /**
+   * Encode the event as JSON.
+   *
+   * @returns JSON representation.
+   */
+  override toJson(): VarTypeChangeJson {
+    const json = super.toJson() as VarTypeChangeJson;
+    if (!this.oldType || !this.newType) {
+      throw new Error(
+        "The variable's types are undefined. Either pass them to " +
+          'the constructor, or call fromJson',
+      );
+    }
+    json['oldType'] = this.oldType;
+    json['newType'] = this.newType;
+    return json;
+  }
+
+  /**
+   * Deserializes the JSON event.
+   *
+   * @param event The event to append new properties to. Should be a subclass
+   *     of VarTypeChange, 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: VarTypeChangeJson,
+    workspace: Workspace,
+    event?: any,
+  ): VarTypeChange {
+    const newEvent = super.fromJson(
+      json,
+      workspace,
+      event ?? new VarTypeChange(),
+    ) as VarTypeChange;
+    newEvent.oldType = json['oldType'];
+    newEvent.newType = json['newType'];
+    return newEvent;
+  }
+
+  /**
+   * Run a variable type change event.
+   *
+   * @param forward True if run forward, false if run backward (undo).
+   */
+  override run(forward: boolean) {
+    const workspace = this.getEventWorkspace_();
+    if (!this.varId) {
+      throw new Error(
+        'The var ID is undefined. Either pass a variable to ' +
+          'the constructor, or call fromJson',
+      );
+    }
+    if (!this.oldType || !this.newType) {
+      throw new Error(
+        "The variable's types are undefined. Either pass them to " +
+          'the constructor, or call fromJson',
+      );
+    }
+    const variable = workspace.getVariableMap().getVariableById(this.varId);
+    if (!variable) return;
+    if (forward) {
+      workspace.getVariableMap().changeVariableType(variable, this.newType);
+    } else {
+      workspace.getVariableMap().changeVariableType(variable, this.oldType);
+    }
+  }
+}
+
+export interface VarTypeChangeJson extends VarBaseJson {
+  oldType: string;
+  newType: string;
+}
+
+registry.register(
+  registry.Type.EVENT,
+  EventType.VAR_TYPE_CHANGE,
+  VarTypeChange,
+);

package/core/events/events_viewport.ts

@@ -0,0 +1,149 @@
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Events fired as a result of a viewport change.
+ *
+ * @class
+ */
+// Former goog.module ID: Blockly.Events.ViewportChange
+
+import * as registry from '../registry.js';
+import type {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 the workspace surface's position or scale has
+ * changed.
+ *
+ * Does not notify when the workspace itself resizes.
+ */
+export class ViewportChange extends UiBase {
+  /**
+   * Top edge of the visible portion of the workspace, relative to the
+   * workspace origin.
+   */
+  viewTop?: number;
+
+  /**
+   * The left edge of the visible portion of the workspace, relative to
+   * the workspace origin.
+   */
+  viewLeft?: number;
+
+  /** The scale of the workpace. */
+  scale?: number;
+
+  /** The previous scale of the workspace. */
+  oldScale?: number;
+
+  override type = EventType.VIEWPORT_CHANGE;
+
+  /**
+   * @param opt_top Top-edge of the visible portion of the workspace, relative
+   *     to the workspace origin. Undefined for a blank event.
+   * @param opt_left Left-edge of the visible portion of the workspace relative
+   *     to the workspace origin. Undefined for a blank event.
+   * @param opt_scale The scale of the workspace. Undefined for a blank event.
+   * @param opt_workspaceId The workspace identifier for this event.
+   *    Undefined for a blank event.
+   * @param opt_oldScale The old scale of the workspace. Undefined for a blank
+   *     event.
+   */
+  constructor(
+    opt_top?: number,
+    opt_left?: number,
+    opt_scale?: number,
+    opt_workspaceId?: string,
+    opt_oldScale?: number,
+  ) {
+    super(opt_workspaceId);
+
+    this.viewTop = opt_top;
+    this.viewLeft = opt_left;
+    this.scale = opt_scale;
+    this.oldScale = opt_oldScale;
+  }
+
+  /**
+   * Encode the event as JSON.
+   *
+   * @returns JSON representation.
+   */
+  override toJson(): ViewportChangeJson {
+    const json = super.toJson() as ViewportChangeJson;
+    if (this.viewTop === undefined) {
+      throw new Error(
+        'The view top is undefined. Either pass a value to ' +
+          'the constructor, or call fromJson',
+      );
+    }
+    if (this.viewLeft === undefined) {
+      throw new Error(
+        'The view left is undefined. Either pass a value to ' +
+          'the constructor, or call fromJson',
+      );
+    }
+    if (this.scale === undefined) {
+      throw new Error(
+        'The scale is undefined. Either pass a value to ' +
+          'the constructor, or call fromJson',
+      );
+    }
+    if (this.oldScale === undefined) {
+      throw new Error(
+        'The old scale is undefined. Either pass a value to ' +
+          'the constructor, or call fromJson',
+      );
+    }
+    json['viewTop'] = this.viewTop;
+    json['viewLeft'] = this.viewLeft;
+    json['scale'] = this.scale;
+    json['oldScale'] = this.oldScale;
+    return json;
+  }
+
+  /**
+   * Deserializes the JSON event.
+   *
+   * @param event The event to append new properties to. Should be a subclass
+   *     of Viewport, 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: ViewportChangeJson,
+    workspace: Workspace,
+    event?: any,
+  ): ViewportChange {
+    const newEvent = super.fromJson(
+      json,
+      workspace,
+      event ?? new ViewportChange(),
+    ) as ViewportChange;
+    newEvent.viewTop = json['viewTop'];
+    newEvent.viewLeft = json['viewLeft'];
+    newEvent.scale = json['scale'];
+    newEvent.oldScale = json['oldScale'];
+    return newEvent;
+  }
+}
+
+export interface ViewportChangeJson extends AbstractEventJson {
+  viewTop: number;
+  viewLeft: number;
+  scale: number;
+  oldScale: number;
+}
+
+registry.register(
+  registry.Type.EVENT,
+  EventType.VIEWPORT_CHANGE,
+  ViewportChange,
+);

package/core/events/predicates.ts

@@ -0,0 +1,166 @@
+/**
+ * @license
+ * Copyright 2024 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * @file Predicates for testing Abstract event subclasses based on
+ * their .type properties.  These are useful because there are places
+ * where it is not possible to use instanceof <ClassConstructor> tests
+ * for type narrowing due to load ordering issues that would be caused
+ * by the need to import (rather than just import type) the class
+ * constructors in question.
+ */
+
+import type {Abstract} from './events_abstract.js';
+import type {BlockChange} from './events_block_change.js';
+import type {BlockCreate} from './events_block_create.js';
+import type {BlockDelete} from './events_block_delete.js';
+import type {BlockDrag} from './events_block_drag.js';
+import type {BlockFieldIntermediateChange} from './events_block_field_intermediate_change.js';
+import type {BlockMove} from './events_block_move.js';
+import type {BubbleOpen} from './events_bubble_open.js';
+import type {Click} from './events_click.js';
+import type {CommentChange} from './events_comment_change.js';
+import type {CommentCollapse} from './events_comment_collapse.js';
+import type {CommentCreate} from './events_comment_create.js';
+import type {CommentDelete} from './events_comment_delete.js';
+import type {CommentDrag} from './events_comment_drag.js';
+import type {CommentMove} from './events_comment_move.js';
+import type {CommentResize} from './events_comment_resize.js';
+import type {Selected} from './events_selected.js';
+import type {ThemeChange} from './events_theme_change.js';
+import type {ToolboxItemSelect} from './events_toolbox_item_select.js';
+import type {TrashcanOpen} from './events_trashcan_open.js';
+import type {VarCreate} from './events_var_create.js';
+import type {VarDelete} from './events_var_delete.js';
+import type {VarRename} from './events_var_rename.js';
+import type {ViewportChange} from './events_viewport.js';
+import type {FinishedLoading} from './workspace_events.js';
+
+import {EventType} from './type.js';
+
+/** @returns true iff event.type is EventType.BLOCK_CREATE */
+export function isBlockCreate(event: Abstract): event is BlockCreate {
+  return event.type === EventType.BLOCK_CREATE;
+}
+
+/** @returns true iff event.type is EventType.BLOCK_DELETE */
+export function isBlockDelete(event: Abstract): event is BlockDelete {
+  return event.type === EventType.BLOCK_DELETE;
+}
+
+/** @returns true iff event.type is EventType.BLOCK_CHANGE */
+export function isBlockChange(event: Abstract): event is BlockChange {
+  return event.type === EventType.BLOCK_CHANGE;
+}
+
+/** @returns true iff event.type is EventType.BLOCK_FIELD_INTERMEDIATE_CHANGE */
+export function isBlockFieldIntermediateChange(
+  event: Abstract,
+): event is BlockFieldIntermediateChange {
+  return event.type === EventType.BLOCK_FIELD_INTERMEDIATE_CHANGE;
+}
+
+/** @returns true iff event.type is EventType.BLOCK_MOVE */
+export function isBlockMove(event: Abstract): event is BlockMove {
+  return event.type === EventType.BLOCK_MOVE;
+}
+
+/** @returns true iff event.type is EventType.VAR_CREATE */
+export function isVarCreate(event: Abstract): event is VarCreate {
+  return event.type === EventType.VAR_CREATE;
+}
+
+/** @returns true iff event.type is EventType.VAR_DELETE */
+export function isVarDelete(event: Abstract): event is VarDelete {
+  return event.type === EventType.VAR_DELETE;
+}
+
+/** @returns true iff event.type is EventType.VAR_RENAME */
+export function isVarRename(event: Abstract): event is VarRename {
+  return event.type === EventType.VAR_RENAME;
+}
+
+/** @returns true iff event.type is EventType.BLOCK_DRAG */
+export function isBlockDrag(event: Abstract): event is BlockDrag {
+  return event.type === EventType.BLOCK_DRAG;
+}
+
+/** @returns true iff event.type is EventType.SELECTED */
+export function isSelected(event: Abstract): event is Selected {
+  return event.type === EventType.SELECTED;
+}
+
+/** @returns true iff event.type is EventType.CLICK */
+export function isClick(event: Abstract): event is Click {
+  return event.type === EventType.CLICK;
+}
+
+/** @returns true iff event.type is EventType.BUBBLE_OPEN */
+export function isBubbleOpen(event: Abstract): event is BubbleOpen {
+  return event.type === EventType.BUBBLE_OPEN;
+}
+
+/** @returns true iff event.type is EventType.TRASHCAN_OPEN */
+export function isTrashcanOpen(event: Abstract): event is TrashcanOpen {
+  return event.type === EventType.TRASHCAN_OPEN;
+}
+
+/** @returns true iff event.type is EventType.TOOLBOX_ITEM_SELECT */
+export function isToolboxItemSelect(
+  event: Abstract,
+): event is ToolboxItemSelect {
+  return event.type === EventType.TOOLBOX_ITEM_SELECT;
+}
+
+/** @returns true iff event.type is EventType.THEME_CHANGE */
+export function isThemeChange(event: Abstract): event is ThemeChange {
+  return event.type === EventType.THEME_CHANGE;
+}
+
+/** @returns true iff event.type is EventType.VIEWPORT_CHANGE */
+export function isViewportChange(event: Abstract): event is ViewportChange {
+  return event.type === EventType.VIEWPORT_CHANGE;
+}
+
+/** @returns true iff event.type is EventType.COMMENT_CREATE */
+export function isCommentCreate(event: Abstract): event is CommentCreate {
+  return event.type === EventType.COMMENT_CREATE;
+}
+
+/** @returns true iff event.type is EventType.COMMENT_DELETE */
+export function isCommentDelete(event: Abstract): event is CommentDelete {
+  return event.type === EventType.COMMENT_DELETE;
+}
+
+/** @returns true iff event.type is EventType.COMMENT_CHANGE */
+export function isCommentChange(event: Abstract): event is CommentChange {
+  return event.type === EventType.COMMENT_CHANGE;
+}
+
+/** @returns true iff event.type is EventType.COMMENT_MOVE */
+export function isCommentMove(event: Abstract): event is CommentMove {
+  return event.type === EventType.COMMENT_MOVE;
+}
+
+/** @returns true iff event.type is EventType.COMMENT_RESIZE */
+export function isCommentResize(event: Abstract): event is CommentResize {
+  return event.type === EventType.COMMENT_RESIZE;
+}
+
+/** @returns true iff event.type is EventType.COMMENT_DRAG */
+export function isCommentDrag(event: Abstract): event is CommentDrag {
+  return event.type === EventType.COMMENT_DRAG;
+}
+
+/** @returns true iff event.type is EventType.COMMENT_COLLAPSE */
+export function isCommentCollapse(event: Abstract): event is CommentCollapse {
+  return event.type === EventType.COMMENT_COLLAPSE;
+}
+
+/** @returns true iff event.type is EventType.FINISHED_LOADING */
+export function isFinishedLoading(event: Abstract): event is FinishedLoading {
+  return event.type === EventType.FINISHED_LOADING;
+}

package/core/events/type.ts

@@ -0,0 +1,87 @@
+/**
+ * @license
+ * Copyright 2024 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Enum of values for the .type property for event classes (concrete subclasses
+ * of Abstract).
+ */
+export enum EventType {
+  /** Type of event that creates a block. */
+  BLOCK_CREATE = 'create',
+  /** Type of event that deletes a block. */
+  BLOCK_DELETE = 'delete',
+  /** Type of event that changes a block. */
+  BLOCK_CHANGE = 'change',
+  /**
+   * Type of event representing an in-progress change to a field of a
+   * block, which is expected to be followed by a block change event.
+   */
+  BLOCK_FIELD_INTERMEDIATE_CHANGE = 'block_field_intermediate_change',
+  /** Type of event that moves a block. */
+  BLOCK_MOVE = 'move',
+  /** Type of event that creates a variable. */
+  VAR_CREATE = 'var_create',
+  /** Type of event that deletes a variable. */
+  VAR_DELETE = 'var_delete',
+  /** Type of event that renames a variable. */
+  VAR_RENAME = 'var_rename',
+  /** Type of event that changes the type of a variable. */
+  VAR_TYPE_CHANGE = 'var_type_change',
+  /**
+   * Type of generic event that records a UI change.
+   *
+   * @deprecated Was only ever intended for internal use.
+   */
+  UI = 'ui',
+  /** Type of event that drags a block. */
+  BLOCK_DRAG = 'drag',
+  /** Type of event that records a change in selected element. */
+  SELECTED = 'selected',
+  /** Type of event that records a click. */
+  CLICK = 'click',
+  /** Type of event that records a marker move. */
+  MARKER_MOVE = 'marker_move',
+  /** Type of event that records a bubble open. */
+  BUBBLE_OPEN = 'bubble_open',
+  /** Type of event that records a trashcan open. */
+  TRASHCAN_OPEN = 'trashcan_open',
+  /** Type of event that records a toolbox item select. */
+  TOOLBOX_ITEM_SELECT = 'toolbox_item_select',
+  /** Type of event that records a theme change. */
+  THEME_CHANGE = 'theme_change',
+  /** Type of event that records a viewport change. */
+  VIEWPORT_CHANGE = 'viewport_change',
+  /** Type of event that creates a comment. */
+  COMMENT_CREATE = 'comment_create',
+  /** Type of event that deletes a comment. */
+  COMMENT_DELETE = 'comment_delete',
+  /** Type of event that changes a comment. */
+  COMMENT_CHANGE = 'comment_change',
+  /** Type of event that moves a comment. */
+  COMMENT_MOVE = 'comment_move',
+  /** Type of event that resizes a comment. */
+  COMMENT_RESIZE = 'comment_resize',
+  /**  Type of event that drags a comment. */
+  COMMENT_DRAG = 'comment_drag',
+  /** Type of event that collapses a comment. */
+  COMMENT_COLLAPSE = 'comment_collapse',
+  /** Type of event that records a workspace load. */
+  FINISHED_LOADING = 'finished_loading',
+}
+
+/**
+ * List of events that cause objects to be bumped back into the visible
+ * portion of the workspace.
+ *
+ * Not to be confused with bumping so that disconnected connections do not
+ * appear connected.
+ */
+export const BUMP_EVENTS: string[] = [
+  EventType.BLOCK_CREATE,
+  EventType.BLOCK_MOVE,
+  EventType.COMMENT_CREATE,
+  EventType.COMMENT_MOVE,
+];