scratch-blocks 1.1.206 → 2.0.0-beta.1

package/blockly-rc/core/events/events_block_create.ts

@@ -0,0 +1,185 @@
+/**
+ * @license
+ * Copyright 2018 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Class for a block creation event.
+ *
+ * @class
+ */
+// Former goog.module ID: Blockly.Events.BlockCreate
+
+import type {Block} from '../block.js';
+import * as registry from '../registry.js';
+import * as blocks from '../serialization/blocks.js';
+import * as utilsXml from '../utils/xml.js';
+import * as Xml from '../xml.js';
+
+import {BlockBase, BlockBaseJson} from './events_block_base.js';
+import * as eventUtils from './utils.js';
+import {Workspace} from '../workspace.js';
+
+/**
+ * Notifies listeners when a block (or connected stack of blocks) is
+ * created.
+ */
+export class BlockCreate extends BlockBase {
+  override type = eventUtils.BLOCK_CREATE;
+
+  /** The XML representation of the created block(s). */
+  xml?: Element | DocumentFragment;
+
+  /** The JSON respresentation of the created block(s). */
+  json?: blocks.State;
+
+  /** All of the IDs of created blocks. */
+  ids?: string[];
+
+  /** @param opt_block The created 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;
+    }
+
+    this.xml = Xml.blockToDomWithXY(opt_block);
+    this.ids = eventUtils.getDescendantIds(opt_block);
+
+    this.json = blocks.save(opt_block, {addCoordinates: true}) as blocks.State;
+  }
+
+  /**
+   * Encode the event as JSON.
+   *
+   * @returns JSON representation.
+   */
+  override toJson(): BlockCreateJson {
+    const json = super.toJson() as BlockCreateJson;
+    if (!this.xml) {
+      throw new Error(
+        'The block XML is undefined. Either pass a block to ' +
+          'the constructor, or call fromJson',
+      );
+    }
+    if (!this.ids) {
+      throw new Error(
+        'The block IDs are undefined. Either pass a block to ' +
+          'the constructor, or call fromJson',
+      );
+    }
+    if (!this.json) {
+      throw new Error(
+        'The block JSON is undefined. Either pass a block to ' +
+          'the constructor, or call fromJson',
+      );
+    }
+    json['xml'] = Xml.domToText(this.xml);
+    json['ids'] = this.ids;
+    json['json'] = this.json;
+    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 BlockCreate, 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: BlockCreateJson,
+    workspace: Workspace,
+    event?: any,
+  ): BlockCreate {
+    const newEvent = super.fromJson(
+      json,
+      workspace,
+      event ?? new BlockCreate(),
+    ) as BlockCreate;
+    newEvent.xml = utilsXml.textToDom(json['xml']);
+    newEvent.ids = json['ids'];
+    newEvent.json = json['json'] as blocks.State;
+    if (json['recordUndo'] !== undefined) {
+      newEvent.recordUndo = json['recordUndo'];
+    }
+    return newEvent;
+  }
+
+  /**
+   * Run a creation event.
+   *
+   * @param forward True if run forward, false if run backward (undo).
+   */
+  override run(forward: boolean) {
+    const workspace = this.getEventWorkspace_();
+    if (!this.json) {
+      throw new Error(
+        'The block JSON is undefined. Either pass a block to ' +
+          'the constructor, or call fromJson',
+      );
+    }
+    if (!this.ids) {
+      throw new Error(
+        'The block IDs are undefined. Either pass a block to ' +
+          'the constructor, or call fromJson',
+      );
+    }
+    if (allShadowBlocks(workspace, this.ids)) return;
+    if (forward) {
+      blocks.append(this.json, workspace);
+    } else {
+      for (let i = 0; i < this.ids.length; i++) {
+        const id = this.ids[i];
+        const block = workspace.getBlockById(id);
+        if (block) {
+          block.dispose(false);
+        } else if (id === this.blockId) {
+          // Only complain about root-level block.
+          console.warn("Can't uncreate non-existent block: " + id);
+        }
+      }
+    }
+  }
+}
+/**
+ * Returns true if all blocks in the list are shadow blocks. If so, that means
+ * the top-level block being created is a shadow block. This only happens when a
+ * block that was covering up a shadow block is removed. We don't need to create
+ * an additional block in that case because the original block still has its
+ * shadow block.
+ *
+ * @param workspace Workspace to check for blocks
+ * @param ids A list of block ids that were created in this event
+ * @returns True if all block ids in the list are shadow blocks
+ */
+const allShadowBlocks = function (
+  workspace: Workspace,
+  ids: string[],
+): boolean {
+  const shadows = ids
+    .map((id) => workspace.getBlockById(id))
+    .filter((block) => block && block.isShadow());
+  return shadows.length === ids.length;
+};
+
+export interface BlockCreateJson extends BlockBaseJson {
+  xml: string;
+  ids: string[];
+  json: object;
+  recordUndo?: boolean;
+}
+
+registry.register(registry.Type.EVENT, eventUtils.CREATE, BlockCreate);

package/blockly-rc/core/events/events_block_delete.ts

@@ -0,0 +1,182 @@
+/**
+ * @license
+ * Copyright 2018 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Class for a block delete event.
+ *
+ * @class
+ */
+// Former goog.module ID: Blockly.Events.BlockDelete
+
+import type {Block} from '../block.js';
+import * as registry from '../registry.js';
+import * as blocks from '../serialization/blocks.js';
+import * as utilsXml from '../utils/xml.js';
+import * as Xml from '../xml.js';
+
+import {BlockBase, BlockBaseJson} from './events_block_base.js';
+import * as eventUtils from './utils.js';
+import {Workspace} from '../workspace.js';
+
+/**
+ * Notifies listeners when a block (or connected stack of blocks) is
+ * deleted.
+ */
+export class BlockDelete extends BlockBase {
+  /** The XML representation of the deleted block(s). */
+  oldXml?: Element | DocumentFragment;
+
+  /** The JSON respresentation of the deleted block(s). */
+  oldJson?: blocks.State;
+
+  /** All of the IDs of deleted blocks. */
+  ids?: string[];
+
+  /** True if the deleted block was a shadow block, false otherwise. */
+  wasShadow?: boolean;
+
+  override type = eventUtils.BLOCK_DELETE;
+
+  /** @param opt_block The deleted 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.getParent()) {
+      throw Error('Connected blocks cannot be deleted.');
+    }
+    if (opt_block.isShadow()) {
+      // Respawning shadow blocks is handled via disconnection.
+      this.recordUndo = false;
+    }
+
+    this.oldXml = Xml.blockToDomWithXY(opt_block);
+    this.ids = eventUtils.getDescendantIds(opt_block);
+    this.wasShadow = opt_block.isShadow();
+    this.oldJson = blocks.save(opt_block, {
+      addCoordinates: true,
+    }) as blocks.State;
+  }
+
+  /**
+   * Encode the event as JSON.
+   *
+   * @returns JSON representation.
+   */
+  override toJson(): BlockDeleteJson {
+    const json = super.toJson() as BlockDeleteJson;
+    if (!this.oldXml) {
+      throw new Error(
+        'The old block XML is undefined. Either pass a block ' +
+          'to the constructor, or call fromJson',
+      );
+    }
+    if (!this.ids) {
+      throw new Error(
+        'The block IDs are undefined. Either pass a block to ' +
+          'the constructor, or call fromJson',
+      );
+    }
+    if (this.wasShadow === undefined) {
+      throw new Error(
+        'Whether the block was a shadow is undefined. Either ' +
+          'pass a block to the constructor, or call fromJson',
+      );
+    }
+    if (!this.oldJson) {
+      throw new Error(
+        'The old block JSON is undefined. Either pass a block ' +
+          'to the constructor, or call fromJson',
+      );
+    }
+    json['oldXml'] = Xml.domToText(this.oldXml);
+    json['ids'] = this.ids;
+    json['wasShadow'] = this.wasShadow;
+    json['oldJson'] = this.oldJson;
+    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 BlockDelete, 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: BlockDeleteJson,
+    workspace: Workspace,
+    event?: any,
+  ): BlockDelete {
+    const newEvent = super.fromJson(
+      json,
+      workspace,
+      event ?? new BlockDelete(),
+    ) as BlockDelete;
+    newEvent.oldXml = utilsXml.textToDom(json['oldXml']);
+    newEvent.ids = json['ids'];
+    newEvent.wasShadow =
+      json['wasShadow'] || newEvent.oldXml.tagName.toLowerCase() === 'shadow';
+    newEvent.oldJson = json['oldJson'];
+    if (json['recordUndo'] !== undefined) {
+      newEvent.recordUndo = json['recordUndo'];
+    }
+    return newEvent;
+  }
+
+  /**
+   * Run a deletion event.
+   *
+   * @param forward True if run forward, false if run backward (undo).
+   */
+  override run(forward: boolean) {
+    const workspace = this.getEventWorkspace_();
+    if (!this.ids) {
+      throw new Error(
+        'The block IDs are undefined. Either pass a block to ' +
+          'the constructor, or call fromJson',
+      );
+    }
+    if (!this.oldJson) {
+      throw new Error(
+        'The old block JSON is undefined. Either pass a block ' +
+          'to the constructor, or call fromJson',
+      );
+    }
+    if (forward) {
+      for (let i = 0; i < this.ids.length; i++) {
+        const id = this.ids[i];
+        const block = workspace.getBlockById(id);
+        if (block) {
+          block.dispose(false);
+        } else if (id === this.blockId) {
+          // Only complain about root-level block.
+          console.warn("Can't delete non-existent block: " + id);
+        }
+      }
+    } else {
+      blocks.append(this.oldJson, workspace);
+    }
+  }
+}
+
+export interface BlockDeleteJson extends BlockBaseJson {
+  oldXml: string;
+  ids: string[];
+  wasShadow: boolean;
+  oldJson: blocks.State;
+  recordUndo?: boolean;
+}
+
+registry.register(registry.Type.EVENT, eventUtils.DELETE, BlockDelete);

package/blockly-rc/core/events/events_block_drag.ts

@@ -0,0 +1,116 @@
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Events fired as a block drag.
+ *
+ * @class
+ */
+// Former goog.module ID: Blockly.Events.BlockDrag
+
+import type {Block} from '../block.js';
+import * as registry from '../registry.js';
+import {AbstractEventJson} from './events_abstract.js';
+import {UiBase} from './events_ui_base.js';
+import * as eventUtils from './utils.js';
+import {Workspace} from '../workspace.js';
+
+/**
+ * Notifies listeners when a block is being manually dragged/dropped.
+ */
+export class BlockDrag extends UiBase {
+  /** The ID of the top-level block being dragged. */
+  blockId?: string;
+
+  /** True if this is the start of a drag, false if this is the end of one. */
+  isStart?: boolean;
+
+  /**
+   * A list of all of the blocks (i.e. all descendants of the block associated
+   * with the block ID) being dragged.
+   */
+  blocks?: Block[];
+
+  override type = eventUtils.BLOCK_DRAG;
+
+  /**
+   * @param opt_block The top block in the stack that is being dragged.
+   *     Undefined for a blank event.
+   * @param opt_isStart Whether this is the start of a block drag.
+   *    Undefined for a blank event.
+   * @param opt_blocks The blocks affected by this drag. Undefined for a blank
+   *     event.
+   */
+  constructor(opt_block?: Block, opt_isStart?: boolean, opt_blocks?: Block[]) {
+    const workspaceId = opt_block ? opt_block.workspace.id : undefined;
+    super(workspaceId);
+    if (!opt_block) return;
+
+    this.blockId = opt_block.id;
+    this.isStart = opt_isStart;
+    this.blocks = opt_blocks;
+  }
+
+  /**
+   * Encode the event as JSON.
+   *
+   * @returns JSON representation.
+   */
+  override toJson(): BlockDragJson {
+    const json = super.toJson() as BlockDragJson;
+    if (this.isStart === undefined) {
+      throw new Error(
+        'Whether this event is the start of a drag is undefined. ' +
+          'Either pass the value to the constructor, or call fromJson',
+      );
+    }
+    if (this.blockId === undefined) {
+      throw new Error(
+        'The block ID is undefined. Either pass a block to ' +
+          'the constructor, or call fromJson',
+      );
+    }
+    json['isStart'] = this.isStart;
+    json['blockId'] = this.blockId;
+    // TODO: I don't think we should actually apply the blocks array to the JSON
+    //   object b/c they have functions and aren't actually serializable.
+    json['blocks'] = this.blocks;
+    return json;
+  }
+
+  /**
+   * Deserializes the JSON event.
+   *
+   * @param event The event to append new properties to. Should be a subclass
+   *     of BlockDrag, 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: BlockDragJson,
+    workspace: Workspace,
+    event?: any,
+  ): BlockDrag {
+    const newEvent = super.fromJson(
+      json,
+      workspace,
+      event ?? new BlockDrag(),
+    ) as BlockDrag;
+    newEvent.isStart = json['isStart'];
+    newEvent.blockId = json['blockId'];
+    newEvent.blocks = json['blocks'];
+    return newEvent;
+  }
+}
+
+export interface BlockDragJson extends AbstractEventJson {
+  isStart: boolean;
+  blockId: string;
+  blocks?: Block[];
+}
+
+registry.register(registry.Type.EVENT, eventUtils.BLOCK_DRAG, BlockDrag);

package/blockly-rc/core/events/events_block_field_intermediate_change.ts

@@ -0,0 +1,167 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Class for an event representing an intermediate change to a block's field's
+ * value.
+ *
+ * @class
+ */
+// Former goog.module ID: Blockly.Events.BlockFieldIntermediateChange
+
+import type {Block} from '../block.js';
+import * as registry from '../registry.js';
+import {Workspace} from '../workspace.js';
+
+import {BlockBase, BlockBaseJson} from './events_block_base.js';
+import * as eventUtils from './utils.js';
+
+/**
+ * Notifies listeners when the value of a block's field has changed but the
+ * change is not yet complete, and is expected to be followed by a block change
+ * event.
+ */
+export class BlockFieldIntermediateChange extends BlockBase {
+  override type = eventUtils.BLOCK_FIELD_INTERMEDIATE_CHANGE;
+
+  // Intermediate events do not undo or redo. They may be fired frequently while
+  // the field editor widget is open. A separate BLOCK_CHANGE event is fired
+  // when the editor is closed, which combines all of the field value changes
+  // into a single change that is recorded in the undo history instead. The
+  // intermediate changes are important for reacting to immediate changes, but
+  // some event handlers would prefer to handle the less frequent final events,
+  // like when triggering workspace serialization. Technically, this method of
+  // grouping changes can result in undo perfoming actions out of order if some
+  // other event occurs between opening and closing the field editor, but such
+  // events are unlikely to cause a broken state.
+  override recordUndo = false;
+
+  /** The name of the field that changed. */
+  name?: string;
+
+  /** The original value of the element. */
+  oldValue: unknown;
+
+  /** The new value of the element. */
+  newValue: unknown;
+
+  /**
+   * @param opt_block The changed block. Undefined for a blank event.
+   * @param opt_name Name of the field affected.
+   * @param opt_oldValue Previous value of element.
+   * @param opt_newValue New value of element.
+   */
+  constructor(
+    opt_block?: Block,
+    opt_name?: string,
+    opt_oldValue?: unknown,
+    opt_newValue?: unknown,
+  ) {
+    super(opt_block);
+    if (!opt_block) {
+      return; // Blank event to be populated by fromJson.
+    }
+
+    this.name = opt_name;
+    this.oldValue = opt_oldValue;
+    this.newValue = opt_newValue;
+  }
+
+  /**
+   * Encode the event as JSON.
+   *
+   * @returns JSON representation.
+   */
+  override toJson(): BlockFieldIntermediateChangeJson {
+    const json = super.toJson() as BlockFieldIntermediateChangeJson;
+    if (!this.name) {
+      throw new Error(
+        'The changed field name is undefined. Either pass a ' +
+          'name to the constructor, or call fromJson.',
+      );
+    }
+    json['name'] = this.name;
+    json['oldValue'] = this.oldValue;
+    json['newValue'] = this.newValue;
+    return json;
+  }
+
+  /**
+   * Deserializes the JSON event.
+   *
+   * @param event The event to append new properties to. Should be a subclass
+   *     of BlockFieldIntermediateChange, 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: BlockFieldIntermediateChangeJson,
+    workspace: Workspace,
+    event?: any,
+  ): BlockFieldIntermediateChange {
+    const newEvent = super.fromJson(
+      json,
+      workspace,
+      event ?? new BlockFieldIntermediateChange(),
+    ) as BlockFieldIntermediateChange;
+    newEvent.name = json['name'];
+    newEvent.oldValue = json['oldValue'];
+    newEvent.newValue = json['newValue'];
+    return newEvent;
+  }
+
+  /**
+   * Does this event record any change of state?
+   *
+   * @returns False if something changed.
+   */
+  override isNull(): boolean {
+    return this.oldValue === this.newValue;
+  }
+
+  /**
+   * Run a change 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) {
+      throw new Error(
+        'The associated block is undefined. Either pass a ' +
+          'block to the constructor, or call fromJson',
+      );
+    }
+
+    const value = forward ? this.newValue : this.oldValue;
+    const field = block.getField(this.name!);
+    if (field) {
+      field.setValue(value);
+    } else {
+      console.warn("Can't set non-existent field: " + this.name);
+    }
+  }
+}
+
+export interface BlockFieldIntermediateChangeJson extends BlockBaseJson {
+  name: string;
+  newValue: unknown;
+  oldValue: unknown;
+}
+
+registry.register(
+  registry.Type.EVENT,
+  eventUtils.BLOCK_FIELD_INTERMEDIATE_CHANGE,
+  BlockFieldIntermediateChange,
+);