scratch-blocks 1.1.206 → 2.0.0-beta.1

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

@@ -0,0 +1,595 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+// Former goog.module ID: Blockly.Events.utils
+
+import type {Block} from '../block.js';
+import * as common from '../common.js';
+import * as registry from '../registry.js';
+import * as idGenerator from '../utils/idgenerator.js';
+import type {Workspace} from '../workspace.js';
+import type {WorkspaceSvg} from '../workspace_svg.js';
+
+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 {BlockMove} from './events_block_move.js';
+import type {CommentCreate} from './events_comment_create.js';
+import type {CommentMove} from './events_comment_move.js';
+import type {CommentResize} from './events_comment_resize.js';
+import type {ViewportChange} from './events_viewport.js';
+
+/** Group ID for new events.  Grouped events are indivisible. */
+let group = '';
+
+/** Sets whether the next event should be added to the undo stack. */
+let recordUndo = true;
+
+/**
+ * Sets whether events should be added to the undo stack.
+ *
+ * @param newValue True if events should be added to the undo stack.
+ */
+export function setRecordUndo(newValue: boolean) {
+  recordUndo = newValue;
+}
+
+/**
+ * Returns whether or not events will be added to the undo stack.
+ *
+ * @returns True if events will be added to the undo stack.
+ */
+export function getRecordUndo(): boolean {
+  return recordUndo;
+}
+
+/** Allow change events to be created and fired. */
+let disabled = 0;
+
+/**
+ * Name of event that creates a block. Will be deprecated for BLOCK_CREATE.
+ */
+export const CREATE = 'create';
+
+/**
+ * Name of event that creates a block.
+ */
+export const BLOCK_CREATE = CREATE;
+
+/**
+ * Name of event that deletes a block. Will be deprecated for BLOCK_DELETE.
+ */
+export const DELETE = 'delete';
+
+/**
+ * Name of event that deletes a block.
+ */
+export const BLOCK_DELETE = DELETE;
+
+/**
+ * Name of event that changes a block. Will be deprecated for BLOCK_CHANGE.
+ */
+export const CHANGE = 'change';
+
+/**
+ * Name of event that changes a block.
+ */
+export const BLOCK_CHANGE = CHANGE;
+
+/**
+ * Name of event representing an in-progress change to a field of a block, which
+ * is expected to be followed by a block change event.
+ */
+export const BLOCK_FIELD_INTERMEDIATE_CHANGE =
+  'block_field_intermediate_change';
+
+/**
+ * Name of event that moves a block. Will be deprecated for BLOCK_MOVE.
+ */
+export const MOVE = 'move';
+
+/**
+ * Name of event that moves a block.
+ */
+export const BLOCK_MOVE = MOVE;
+
+/**
+ * Name of event that creates a variable.
+ */
+export const VAR_CREATE = 'var_create';
+
+/**
+ * Name of event that deletes a variable.
+ */
+export const VAR_DELETE = 'var_delete';
+
+/**
+ * Name of event that renames a variable.
+ */
+export const VAR_RENAME = 'var_rename';
+
+/**
+ * Name of event that changes a variable's type.
+ */
+export const VAR_TYPE_CHANGE = 'var_type_change';
+
+/**
+ * Name of generic event that records a UI change.
+ */
+export const UI = 'ui';
+
+/**
+ * Name of event that drags a block.
+ */
+export const BLOCK_DRAG = 'drag';
+
+/**
+ * Name of event that records a change in selected element.
+ */
+export const SELECTED = 'selected';
+
+/**
+ * Name of event that records a click.
+ */
+export const CLICK = 'click';
+
+/**
+ * Name of event that records a marker move.
+ */
+export const MARKER_MOVE = 'marker_move';
+
+/**
+ * Name of event that records a bubble open.
+ */
+export const BUBBLE_OPEN = 'bubble_open';
+
+/**
+ * Name of event that records a trashcan open.
+ */
+export const TRASHCAN_OPEN = 'trashcan_open';
+
+/**
+ * Name of event that records a toolbox item select.
+ */
+export const TOOLBOX_ITEM_SELECT = 'toolbox_item_select';
+
+/**
+ * Name of event that records a theme change.
+ */
+export const THEME_CHANGE = 'theme_change';
+
+/**
+ * Name of event that records a viewport change.
+ */
+export const VIEWPORT_CHANGE = 'viewport_change';
+
+/**
+ * Name of event that creates a comment.
+ */
+export const COMMENT_CREATE = 'comment_create';
+
+/**
+ * Name of event that deletes a comment.
+ */
+export const COMMENT_DELETE = 'comment_delete';
+
+/**
+ * Name of event that changes a comment.
+ */
+export const COMMENT_CHANGE = 'comment_change';
+
+/**
+ * Name of event that moves a comment.
+ */
+export const COMMENT_MOVE = 'comment_move';
+
+/** Name of event that resizes a comment. */
+export const COMMENT_RESIZE = 'comment_resize';
+
+/**  Name of event that drags a comment. */
+export const COMMENT_DRAG = 'comment_drag';
+
+/** Type of event that collapses a comment. */
+export const COMMENT_COLLAPSE = 'comment_collapse';
+
+/**
+ * Name of event that records a workspace load.
+ */
+export const FINISHED_LOADING = 'finished_loading';
+
+/**
+ * The language-neutral ID for when the reason why a block is disabled is
+ * because the block is not descended from a root block.
+ */
+const ORPHANED_BLOCK_DISABLED_REASON = 'ORPHANED_BLOCK';
+
+/**
+ * Type 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 type BumpEvent =
+  | BlockCreate
+  | BlockMove
+  | CommentCreate
+  | CommentMove
+  | CommentResize;
+
+/**
+ * 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[] = [
+  BLOCK_CREATE,
+  BLOCK_MOVE,
+  COMMENT_CREATE,
+  COMMENT_MOVE,
+];
+
+/** List of events queued for firing. */
+const FIRE_QUEUE: Abstract[] = [];
+
+/**
+ * Create a custom event and fire it.
+ *
+ * @param event Custom data for event.
+ */
+export function fire(event: Abstract) {
+  TEST_ONLY.fireInternal(event);
+}
+
+/**
+ * Private version of fireInternal for stubbing in tests.
+ */
+function fireInternal(event: Abstract) {
+  if (!isEnabled()) {
+    return;
+  }
+  if (!FIRE_QUEUE.length) {
+    // First event added; schedule a firing of the event queue.
+    try {
+      // If we are in a browser context, we want to make sure that the event
+      // fires after blocks have been rerendered this frame.
+      requestAnimationFrame(() => {
+        setTimeout(fireNow, 0);
+      });
+    } catch (e) {
+      // Otherwise we just want to delay so events can be coallesced.
+      // requestAnimationFrame will error triggering this.
+      setTimeout(fireNow, 0);
+    }
+  }
+  FIRE_QUEUE.push(event);
+}
+
+/** Fire all queued events. */
+function fireNow() {
+  const queue = filter(FIRE_QUEUE, true);
+  FIRE_QUEUE.length = 0;
+  for (let i = 0, event; (event = queue[i]); i++) {
+    if (!event.workspaceId) {
+      continue;
+    }
+    const eventWorkspace = common.getWorkspaceById(event.workspaceId);
+    if (eventWorkspace) {
+      eventWorkspace.fireChangeListener(event);
+    }
+  }
+
+  // Post-filter the undo stack to squash and remove any events that result in
+  // a null event
+
+  // 1. Determine which workspaces will need to have their undo stacks validated
+  const workspaceIds = new Set(queue.map((e) => e.workspaceId));
+  for (const workspaceId of workspaceIds) {
+    // Only process valid workspaces
+    if (!workspaceId) {
+      continue;
+    }
+    const eventWorkspace = common.getWorkspaceById(workspaceId);
+    if (!eventWorkspace) {
+      continue;
+    }
+
+    // Find the last contiguous group of events on the stack
+    const undoStack = eventWorkspace.getUndoStack();
+    let i;
+    let group: string | undefined = undefined;
+    for (i = undoStack.length; i > 0; i--) {
+      const event = undoStack[i - 1];
+      if (event.group === '') {
+        break;
+      } else if (group === undefined) {
+        group = event.group;
+      } else if (event.group !== group) {
+        break;
+      }
+    }
+    if (!group || i == undoStack.length - 1) {
+      // Need a group of two or more events on the stack. Nothing to do here.
+      continue;
+    }
+
+    // Extract the event group, filter, and add back to the undo stack
+    let events = undoStack.splice(i, undoStack.length - i);
+    events = filter(events, true);
+    undoStack.push(...events);
+  }
+}
+
+/**
+ * Filter the queued events and merge duplicates.
+ *
+ * @param queueIn Array of events.
+ * @param forward True if forward (redo), false if backward (undo).
+ * @returns Array of filtered events.
+ */
+export function filter(queueIn: Abstract[], forward: boolean): Abstract[] {
+  let queue = queueIn.slice();
+  // Shallow copy of queue.
+  if (!forward) {
+    // Undo is merged in reverse order.
+    queue.reverse();
+  }
+  const mergedQueue = [];
+  const hash = Object.create(null);
+  // Merge duplicates.
+  for (let i = 0, event; (event = queue[i]); i++) {
+    if (!event.isNull()) {
+      // Treat all UI events as the same type in hash table.
+      const eventType = event.isUiEvent ? UI : event.type;
+      // TODO(#5927): Check whether `blockId` exists before accessing it.
+      const blockId = (event as AnyDuringMigration).blockId;
+      const key = [eventType, blockId, event.workspaceId].join(' ');
+
+      const lastEntry = hash[key];
+      const lastEvent = lastEntry ? lastEntry.event : null;
+      if (!lastEntry) {
+        // Each item in the hash table has the event and the index of that event
+        // in the input array.  This lets us make sure we only merge adjacent
+        // move events.
+        hash[key] = {event, index: i};
+        mergedQueue.push(event);
+      } else if (event.type === MOVE && lastEntry.index === i - 1) {
+        const moveEvent = event as BlockMove;
+        // Merge move events.
+        lastEvent.newParentId = moveEvent.newParentId;
+        lastEvent.newInputName = moveEvent.newInputName;
+        lastEvent.newCoordinate = moveEvent.newCoordinate;
+        if (moveEvent.reason) {
+          if (lastEvent.reason) {
+            // Concatenate reasons without duplicates.
+            const reasonSet = new Set(
+              moveEvent.reason.concat(lastEvent.reason),
+            );
+            lastEvent.reason = Array.from(reasonSet);
+          } else {
+            lastEvent.reason = moveEvent.reason;
+          }
+        }
+        lastEntry.index = i;
+      } else if (
+        event.type === CHANGE &&
+        (event as BlockChange).element === lastEvent.element &&
+        (event as BlockChange).name === lastEvent.name
+      ) {
+        const changeEvent = event as BlockChange;
+        // Merge change events.
+        lastEvent.newValue = changeEvent.newValue;
+      } else if (event.type === VIEWPORT_CHANGE) {
+        const viewportEvent = event as ViewportChange;
+        // Merge viewport change events.
+        lastEvent.viewTop = viewportEvent.viewTop;
+        lastEvent.viewLeft = viewportEvent.viewLeft;
+        lastEvent.scale = viewportEvent.scale;
+        lastEvent.oldScale = viewportEvent.oldScale;
+      } else if (event.type === CLICK && lastEvent.type === BUBBLE_OPEN) {
+        // Drop click events caused by opening/closing bubbles.
+      } else {
+        // Collision: newer events should merge into this event to maintain
+        // order.
+        hash[key] = {event, index: i};
+        mergedQueue.push(event);
+      }
+    }
+  }
+  // Filter out any events that have become null due to merging.
+  queue = mergedQueue.filter(function (e) {
+    return !e.isNull();
+  });
+  if (!forward) {
+    // Restore undo order.
+    queue.reverse();
+  }
+  // Move mutation events to the top of the queue.
+  // Intentionally skip first event.
+  for (let i = 1, event; (event = queue[i]); i++) {
+    // AnyDuringMigration because:  Property 'element' does not exist on type
+    // 'Abstract'.
+    if (
+      event.type === CHANGE &&
+      (event as AnyDuringMigration).element === 'mutation'
+    ) {
+      queue.unshift(queue.splice(i, 1)[0]);
+    }
+  }
+  return queue;
+}
+
+/**
+ * Modify pending undo events so that when they are fired they don't land
+ * in the undo stack.  Called by Workspace.clearUndo.
+ */
+export function clearPendingUndo() {
+  for (let i = 0, event; (event = FIRE_QUEUE[i]); i++) {
+    event.recordUndo = false;
+  }
+}
+
+/**
+ * Stop sending events.  Every call to this function MUST also call enable.
+ */
+export function disable() {
+  disabled++;
+}
+
+/**
+ * Start sending events.  Unless events were already disabled when the
+ * corresponding call to disable was made.
+ */
+export function enable() {
+  disabled--;
+}
+
+/**
+ * Returns whether events may be fired or not.
+ *
+ * @returns True if enabled.
+ */
+export function isEnabled(): boolean {
+  return disabled === 0;
+}
+
+/**
+ * Current group.
+ *
+ * @returns ID string.
+ */
+export function getGroup(): string {
+  return group;
+}
+
+/**
+ * Start or stop a group.
+ *
+ * @param state True to start new group, false to end group.
+ *   String to set group explicitly.
+ */
+export function setGroup(state: boolean | string) {
+  TEST_ONLY.setGroupInternal(state);
+}
+
+/**
+ * Private version of setGroup for stubbing in tests.
+ */
+function setGroupInternal(state: boolean | string) {
+  if (typeof state === 'boolean') {
+    group = state ? idGenerator.genUid() : '';
+  } else {
+    group = state;
+  }
+}
+
+/**
+ * Compute a list of the IDs of the specified block and all its descendants.
+ *
+ * @param block The root block.
+ * @returns List of block IDs.
+ * @internal
+ */
+export function getDescendantIds(block: Block): string[] {
+  const ids = [];
+  const descendants = block.getDescendants(false);
+  for (let i = 0, descendant; (descendant = descendants[i]); i++) {
+    ids[i] = descendant.id;
+  }
+  return ids;
+}
+
+/**
+ * Decode the JSON into an event.
+ *
+ * @param json JSON representation.
+ * @param workspace Target workspace for event.
+ * @returns The event represented by the JSON.
+ * @throws {Error} if an event type is not found in the registry.
+ */
+export function fromJson(
+  json: AnyDuringMigration,
+  workspace: Workspace,
+): Abstract {
+  const eventClass = get(json['type']);
+  if (!eventClass) throw Error('Unknown event type.');
+
+  return (eventClass as any).fromJson(json, workspace);
+}
+
+/**
+ * Gets the class for a specific event type from the registry.
+ *
+ * @param eventType The type of the event to get.
+ * @returns The event class with the given type.
+ */
+export function get(
+  eventType: string,
+): new (...p1: AnyDuringMigration[]) => Abstract {
+  const event = registry.getClass(registry.Type.EVENT, eventType);
+  if (!event) {
+    throw new Error(`Event type ${eventType} not found in registry.`);
+  }
+  return event;
+}
+
+/**
+ * Set if a block is disabled depending on whether it is properly connected.
+ * Use this on applications where all blocks should be connected to a top block.
+ *
+ * @param event Custom data for event.
+ */
+export function disableOrphans(event: Abstract) {
+  if (event.type === MOVE || event.type === CREATE) {
+    const blockEvent = event as BlockMove | BlockCreate;
+    if (!blockEvent.workspaceId) {
+      return;
+    }
+    const eventWorkspace = common.getWorkspaceById(
+      blockEvent.workspaceId,
+    ) as WorkspaceSvg;
+    if (!blockEvent.blockId) {
+      throw new Error('Encountered a blockEvent without a proper blockId');
+    }
+    let block = eventWorkspace.getBlockById(blockEvent.blockId);
+    if (block) {
+      // Changing blocks as part of this event shouldn't be undoable.
+      const initialUndoFlag = recordUndo;
+      try {
+        recordUndo = false;
+        const parent = block.getParent();
+        if (
+          parent &&
+          !parent.hasDisabledReason(ORPHANED_BLOCK_DISABLED_REASON)
+        ) {
+          const children = block.getDescendants(false);
+          for (let i = 0, child; (child = children[i]); i++) {
+            child.setDisabledReason(false, ORPHANED_BLOCK_DISABLED_REASON);
+          }
+        } else if (
+          (block.outputConnection || block.previousConnection) &&
+          !eventWorkspace.isDragging()
+        ) {
+          do {
+            block.setDisabledReason(true, ORPHANED_BLOCK_DISABLED_REASON);
+            block = block.getNextBlock();
+          } while (block);
+        }
+      } finally {
+        recordUndo = initialUndoFlag;
+      }
+    }
+  }
+}
+
+export const TEST_ONLY = {
+  FIRE_QUEUE,
+  fireNow,
+  fireInternal,
+  setGroupInternal,
+};

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

@@ -0,0 +1,46 @@
+/**
+ * @license
+ * Copyright 2019 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Class for a finished loading workspace event.
+ *
+ * @class
+ */
+// Former goog.module ID: Blockly.Events.FinishedLoading
+
+import * as registry from '../registry.js';
+import type {Workspace} from '../workspace.js';
+import {Abstract as AbstractEvent} from './events_abstract.js';
+import * as eventUtils from './utils.js';
+
+/**
+ * Notifies listeners when the workspace has finished deserializing from
+ * JSON/XML.
+ */
+export class FinishedLoading extends AbstractEvent {
+  override isBlank = true;
+  override recordUndo = false;
+  override type = eventUtils.FINISHED_LOADING;
+
+  /**
+   * @param opt_workspace The workspace that has finished loading.  Undefined
+   *     for a blank event.
+   */
+  constructor(opt_workspace?: Workspace) {
+    super();
+    this.isBlank = !!opt_workspace;
+
+    if (!opt_workspace) return;
+
+    this.workspaceId = opt_workspace.id;
+  }
+}
+
+registry.register(
+  registry.Type.EVENT,
+  eventUtils.FINISHED_LOADING,
+  FinishedLoading,
+);