blockly 12.3.1 → 12.4.0

package/core/bump_objects.ts

@@ -0,0 +1,188 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+// Former goog.module ID: Blockly.bumpObjects
+
+import {RenderedWorkspaceComment} from './comments/rendered_workspace_comment.js';
+import type {Abstract} from './events/events_abstract.js';
+import type {BlockCreate} from './events/events_block_create.js';
+import type {BlockMove} from './events/events_block_move.js';
+import type {CommentCreate} from './events/events_comment_create.js';
+import type {CommentMove} from './events/events_comment_move.js';
+import type {CommentResize} from './events/events_comment_resize.js';
+import {isViewportChange} from './events/predicates.js';
+import {BUMP_EVENTS, EventType} from './events/type.js';
+import * as eventUtils from './events/utils.js';
+import type {IBoundedElement} from './interfaces/i_bounded_element.js';
+import type {ContainerRegion} from './metrics_manager.js';
+import * as mathUtils from './utils/math.js';
+import type {WorkspaceSvg} from './workspace_svg.js';
+
+/**
+ * Bumps the given object that has passed out of bounds.
+ *
+ * @param workspace The workspace containing the object.
+ * @param bounds The region to bump an object into. For example, pass
+ *     ScrollMetrics to bump a block into the scrollable region of the
+ *     workspace, or pass ViewMetrics to bump a block into the visible region of
+ *     the workspace. This should be specified in workspace coordinates.
+ * @param object The object to bump.
+ * @returns True if object was bumped.
+ */
+function bumpObjectIntoBounds(
+  workspace: WorkspaceSvg,
+  bounds: ContainerRegion,
+  object: IBoundedElement,
+): boolean {
+  // Compute new top/left position for object.
+  const objectMetrics = object.getBoundingRectangle();
+  const height = objectMetrics.bottom - objectMetrics.top;
+  const width = objectMetrics.right - objectMetrics.left;
+
+  const topClamp = bounds.top;
+  const boundsBottom = bounds.top + bounds.height;
+  const bottomClamp = boundsBottom - height;
+  // If the object is taller than the workspace we want to
+  // top-align the block
+  const newYPosition = mathUtils.clamp(
+    topClamp,
+    objectMetrics.top,
+    bottomClamp,
+  );
+  const deltaY = newYPosition - objectMetrics.top;
+
+  // Note: Even in RTL mode the "anchor" of the object is the
+  // top-left corner of the object.
+  let leftClamp = bounds.left;
+  const boundsRight = bounds.left + bounds.width;
+  let rightClamp = boundsRight - width;
+  if (workspace.RTL) {
+    // If the object is wider than the workspace and we're in RTL
+    // mode we want to right-align the block, which means setting
+    // the left clamp to match.
+    leftClamp = Math.min(rightClamp, leftClamp);
+  } else {
+    // If the object is wider than the workspace and we're in LTR
+    // mode we want to left-align the block, which means setting
+    // the right clamp to match.
+    rightClamp = Math.max(leftClamp, rightClamp);
+  }
+  const newXPosition = mathUtils.clamp(
+    leftClamp,
+    objectMetrics.left,
+    rightClamp,
+  );
+  const deltaX = newXPosition - objectMetrics.left;
+
+  if (deltaX || deltaY) {
+    object.moveBy(deltaX, deltaY, ['inbounds']);
+    return true;
+  }
+  return false;
+}
+export const bumpIntoBounds = bumpObjectIntoBounds;
+
+/**
+ * Creates a handler for bumping objects when they cross fixed bounds.
+ *
+ * @param workspace The workspace to handle.
+ * @returns The event handler.
+ */
+export function bumpIntoBoundsHandler(
+  workspace: WorkspaceSvg,
+): (p1: Abstract) => void {
+  return (e) => {
+    const metricsManager = workspace.getMetricsManager();
+    if (!metricsManager.hasFixedEdges() || workspace.isDragging()) {
+      return;
+    }
+
+    if (BUMP_EVENTS.includes(e.type ?? '')) {
+      const scrollMetricsInWsCoords = metricsManager.getScrollMetrics(true);
+
+      // Triggered by move/create event
+      const object = extractObjectFromEvent(
+        workspace,
+        e as eventUtils.BumpEvent,
+      );
+      if (!object) {
+        return;
+      }
+      // Handle undo.
+      const existingGroup = eventUtils.getGroup() || false;
+      eventUtils.setGroup(e.group);
+
+      const wasBumped = bumpObjectIntoBounds(
+        workspace,
+        scrollMetricsInWsCoords,
+        object as IBoundedElement,
+      );
+
+      if (wasBumped && !e.group) {
+        console.warn(
+          'Moved object in bounds but there was no' +
+            ' event group. This may break undo.',
+        );
+      }
+      eventUtils.setGroup(existingGroup);
+    } else if (isViewportChange(e)) {
+      if (e.scale && e.oldScale && e.scale > e.oldScale) {
+        bumpTopObjectsIntoBounds(workspace);
+      }
+    }
+  };
+}
+
+/**
+ * Extracts the object from the given event.
+ *
+ * @param workspace The workspace the event originated
+ *    from.
+ * @param e An event containing an object.
+ * @returns The extracted
+ *    object.
+ */
+function extractObjectFromEvent(
+  workspace: WorkspaceSvg,
+  e: eventUtils.BumpEvent,
+): IBoundedElement | null {
+  let object = null;
+  switch (e.type) {
+    case EventType.BLOCK_CREATE:
+    case EventType.BLOCK_MOVE:
+      object = workspace.getBlockById((e as BlockCreate | BlockMove).blockId!);
+      if (object) {
+        object = object.getRootBlock();
+      }
+      break;
+    case EventType.COMMENT_CREATE:
+    case EventType.COMMENT_MOVE:
+    case EventType.COMMENT_RESIZE:
+      object = workspace.getCommentById(
+        (e as CommentCreate | CommentMove | CommentResize).commentId!,
+      ) as RenderedWorkspaceComment;
+      break;
+  }
+  return object;
+}
+
+/**
+ * Bumps the top objects in the given workspace into bounds.
+ *
+ * @param workspace The workspace.
+ */
+export function bumpTopObjectsIntoBounds(workspace: WorkspaceSvg) {
+  const metricsManager = workspace.getMetricsManager();
+  if (!metricsManager.hasFixedEdges() || workspace.isDragging()) {
+    return;
+  }
+
+  const scrollMetricsInWsCoords = metricsManager.getScrollMetrics(true);
+  const topBlocks = workspace.getTopBoundedElements();
+  for (let i = 0, block; (block = topBlocks[i]); i++) {
+    bumpObjectIntoBounds(workspace, scrollMetricsInWsCoords, block);
+  }
+}

package/core/button_flyout_inflater.ts

@@ -0,0 +1,76 @@
+/**
+ * @license
+ * Copyright 2024 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {FlyoutButton} from './flyout_button.js';
+import {FlyoutItem} from './flyout_item.js';
+import type {IFlyout} from './interfaces/i_flyout.js';
+import type {IFlyoutInflater} from './interfaces/i_flyout_inflater.js';
+import * as registry from './registry.js';
+import {ButtonOrLabelInfo} from './utils/toolbox.js';
+
+const BUTTON_TYPE = 'button';
+
+/**
+ * Class responsible for creating buttons for flyouts.
+ */
+export class ButtonFlyoutInflater implements IFlyoutInflater {
+  /**
+   * Inflates a flyout button from the given state and adds it to the flyout.
+   *
+   * @param state A JSON representation of a flyout button.
+   * @param flyout The flyout to create the button on.
+   * @returns A newly created FlyoutButton.
+   */
+  load(state: object, flyout: IFlyout): FlyoutItem {
+    const button = new FlyoutButton(
+      flyout.getWorkspace(),
+      flyout.targetWorkspace!,
+      state as ButtonOrLabelInfo,
+      false,
+    );
+    button.show();
+
+    return new FlyoutItem(button, BUTTON_TYPE);
+  }
+
+  /**
+   * Returns the amount of space that should follow this button.
+   *
+   * @param state A JSON representation of a flyout button.
+   * @param defaultGap The default spacing for flyout items.
+   * @returns The amount of space that should follow this button.
+   */
+  gapForItem(state: object, defaultGap: number): number {
+    return defaultGap;
+  }
+
+  /**
+   * Disposes of the given button.
+   *
+   * @param item The flyout button to dispose of.
+   */
+  disposeItem(item: FlyoutItem): void {
+    const element = item.getElement();
+    if (element instanceof FlyoutButton) {
+      element.dispose();
+    }
+  }
+
+  /**
+   * Returns the type of items this inflater is responsible for creating.
+   *
+   * @returns An identifier for the type of items this inflater creates.
+   */
+  getType() {
+    return BUTTON_TYPE;
+  }
+}
+
+registry.register(
+  registry.Type.FLYOUT_INFLATER,
+  BUTTON_TYPE,
+  ButtonFlyoutInflater,
+);

package/core/clipboard/block_paster.ts

@@ -0,0 +1,154 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {BlockSvg} from '../block_svg.js';
+import {IFocusableNode} from '../blockly.js';
+import {config} from '../config.js';
+import {EventType} from '../events/type.js';
+import * as eventUtils from '../events/utils.js';
+import {getFocusManager} from '../focus_manager.js';
+import {ICopyData} from '../interfaces/i_copyable.js';
+import {IPaster} from '../interfaces/i_paster.js';
+import * as renderManagement from '../render_management.js';
+import {State, append} from '../serialization/blocks.js';
+import {Coordinate} from '../utils/coordinate.js';
+import {WorkspaceSvg} from '../workspace_svg.js';
+import * as registry from './registry.js';
+
+export class BlockPaster implements IPaster<BlockCopyData, BlockSvg> {
+  static TYPE = 'block';
+
+  paste(
+    copyData: BlockCopyData,
+    workspace: WorkspaceSvg,
+    coordinate?: Coordinate,
+  ): BlockSvg | null {
+    if (!workspace.isCapacityAvailable(copyData.typeCounts!)) return null;
+
+    if (coordinate) {
+      copyData.blockState['x'] = coordinate.x;
+      copyData.blockState['y'] = coordinate.y;
+    }
+
+    // After appending the block to the workspace, it will be bumped from its neighbors
+    // However, the algorithm for deciding where to paste a block depends on
+    // the starting position of the copied block, so we'll pass those coordinates along
+    const initialCoordinates =
+      coordinate ||
+      new Coordinate(
+        copyData.blockState['x'] || 0,
+        copyData.blockState['y'] || 0,
+      );
+
+    eventUtils.disable();
+    let block;
+    try {
+      block = append(copyData.blockState, workspace) as BlockSvg;
+      moveBlockToNotConflict(block, initialCoordinates);
+    } finally {
+      eventUtils.enable();
+    }
+
+    if (!block) return block;
+
+    if (eventUtils.isEnabled() && !block.isShadow()) {
+      eventUtils.fire(new (eventUtils.get(EventType.BLOCK_CREATE))(block));
+    }
+
+    // Sometimes there's a delay before the block is fully created and ready for
+    // focusing, so wait slightly before focusing the newly pasted block.
+    const nodeToFocus: IFocusableNode = block;
+    renderManagement
+      .finishQueuedRenders()
+      .then(() => getFocusManager().focusNode(nodeToFocus));
+    return block;
+  }
+}
+
+/**
+ * Moves the given block to a location where it does not: (1) overlap exactly
+ * with any other blocks, or (2) look like it is connected to any other blocks.
+ *
+ * Exported for testing.
+ *
+ * @param block The block to move to an unambiguous location.
+ * @param originalPosition The initial coordinate to start searching from,
+ *    likely the position of the copied block.
+ * @internal
+ */
+export function moveBlockToNotConflict(
+  block: BlockSvg,
+  originalPosition: Coordinate,
+) {
+  if (block.workspace.RTL) {
+    originalPosition.x = block.workspace.getWidth() - originalPosition.x;
+  }
+  const workspace = block.workspace;
+  const snapRadius = config.snapRadius;
+  const bumpOffset = Coordinate.difference(
+    originalPosition,
+    block.getRelativeToSurfaceXY(),
+  );
+  const offset = new Coordinate(0, 0);
+  // getRelativeToSurfaceXY is really expensive, so we want to cache this.
+  const otherCoords = workspace
+    .getAllBlocks(false)
+    .filter((otherBlock) => otherBlock.id != block.id)
+    .map((b) => b.getRelativeToSurfaceXY());
+
+  while (
+    blockOverlapsOtherExactly(
+      Coordinate.sum(originalPosition, offset),
+      otherCoords,
+    ) ||
+    blockIsInSnapRadius(block, Coordinate.sum(bumpOffset, offset), snapRadius)
+  ) {
+    if (workspace.RTL) {
+      offset.translate(-snapRadius, snapRadius * 2);
+    } else {
+      offset.translate(snapRadius, snapRadius * 2);
+    }
+  }
+
+  block!.moveTo(Coordinate.sum(originalPosition, offset));
+}
+
+/**
+ * @returns true if the given block coordinates are less than a delta of 1 from
+ *     any of the other coordinates.
+ */
+function blockOverlapsOtherExactly(
+  coord: Coordinate,
+  otherCoords: Coordinate[],
+): boolean {
+  return otherCoords.some(
+    (otherCoord) =>
+      Math.abs(otherCoord.x - coord.x) <= 1 &&
+      Math.abs(otherCoord.y - coord.y) <= 1,
+  );
+}
+
+/**
+ * @returns true if the given block (when offset by the given amount) is close
+ *     enough to any other connections (within the snap radius) that it looks
+ *     like they could connect.
+ */
+function blockIsInSnapRadius(
+  block: BlockSvg,
+  offset: Coordinate,
+  snapRadius: number,
+): boolean {
+  return block
+    .getConnections_(false)
+    .some((connection) => !!connection.closest(snapRadius, offset).connection);
+}
+
+export interface BlockCopyData extends ICopyData {
+  blockState: State;
+  typeCounts: {[key: string]: number};
+}
+
+registry.register(BlockPaster.TYPE, new BlockPaster());

package/core/clipboard/registry.ts

@@ -0,0 +1,31 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {ICopyable, ICopyData} from '../interfaces/i_copyable.js';
+import type {IPaster} from '../interfaces/i_paster.js';
+import * as registry from '../registry.js';
+
+/**
+ * Registers the given paster so that it cna be used for pasting.
+ *
+ * @param type The type of the paster to register, e.g. 'block', 'comment', etc.
+ * @param paster The paster to register.
+ */
+export function register<U extends ICopyData, T extends ICopyable<U>>(
+  type: string,
+  paster: IPaster<U, T>,
+) {
+  registry.register(registry.Type.PASTER, type, paster);
+}
+
+/**
+ * Unregisters the paster associated with the given type.
+ *
+ * @param type The type of the paster to unregister.
+ */
+export function unregister(type: string) {
+  registry.unregister(registry.Type.PASTER, type);
+}

package/core/clipboard/workspace_comment_paster.ts

@@ -0,0 +1,95 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {RenderedWorkspaceComment} from '../comments/rendered_workspace_comment.js';
+import {EventType} from '../events/type.js';
+import * as eventUtils from '../events/utils.js';
+import {getFocusManager} from '../focus_manager.js';
+import {ICopyData} from '../interfaces/i_copyable.js';
+import {IPaster} from '../interfaces/i_paster.js';
+import * as commentSerialiation from '../serialization/workspace_comments.js';
+import {Coordinate} from '../utils/coordinate.js';
+import {WorkspaceSvg} from '../workspace_svg.js';
+import * as registry from './registry.js';
+
+export class WorkspaceCommentPaster
+  implements IPaster<WorkspaceCommentCopyData, RenderedWorkspaceComment>
+{
+  static TYPE = 'workspace-comment';
+
+  paste(
+    copyData: WorkspaceCommentCopyData,
+    workspace: WorkspaceSvg,
+    coordinate?: Coordinate,
+  ): RenderedWorkspaceComment | null {
+    const state = copyData.commentState;
+
+    if (coordinate) {
+      state['x'] = coordinate.x;
+      state['y'] = coordinate.y;
+    }
+
+    eventUtils.disable();
+    let comment;
+    try {
+      comment = commentSerialiation.append(
+        state,
+        workspace,
+      ) as RenderedWorkspaceComment;
+      moveCommentToNotConflict(comment);
+    } finally {
+      eventUtils.enable();
+    }
+
+    if (!comment) return null;
+
+    if (eventUtils.isEnabled()) {
+      eventUtils.fire(new (eventUtils.get(EventType.COMMENT_CREATE))(comment));
+    }
+    getFocusManager().focusNode(comment);
+    return comment;
+  }
+}
+
+function moveCommentToNotConflict(comment: RenderedWorkspaceComment) {
+  const workspace = comment.workspace;
+  const translateDistance = 30;
+  const coord = comment.getRelativeToSurfaceXY();
+  const offset = new Coordinate(0, 0);
+  // getRelativeToSurfaceXY is really expensive, so we want to cache this.
+  const otherCoords = workspace
+    .getTopComments(false)
+    .filter((otherComment) => otherComment.id !== comment.id)
+    .map((c) => c.getRelativeToSurfaceXY());
+
+  while (
+    commentOverlapsOtherExactly(Coordinate.sum(coord, offset), otherCoords)
+  ) {
+    offset.translate(
+      workspace.RTL ? -translateDistance : translateDistance,
+      translateDistance,
+    );
+  }
+
+  comment.moveTo(Coordinate.sum(coord, offset));
+}
+
+function commentOverlapsOtherExactly(
+  coord: Coordinate,
+  otherCoords: Coordinate[],
+): boolean {
+  return otherCoords.some(
+    (otherCoord) =>
+      Math.abs(otherCoord.x - coord.x) <= 1 &&
+      Math.abs(otherCoord.y - coord.y) <= 1,
+  );
+}
+
+export interface WorkspaceCommentCopyData extends ICopyData {
+  commentState: commentSerialiation.State;
+}
+
+registry.register(WorkspaceCommentPaster.TYPE, new WorkspaceCommentPaster());