scratch-blocks 1.1.205 → 1.2.0-beta.1

package/blockly-rc/core/insertion_marker_previewer.ts

@@ -0,0 +1,254 @@
+/**
+ * @license
+ * Copyright 2024 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {BlockSvg} from './block_svg.js';
+import {IConnectionPreviewer} from './interfaces/i_connection_previewer.js';
+import {RenderedConnection} from './rendered_connection.js';
+import {WorkspaceSvg} from './workspace_svg.js';
+import * as blocks from './serialization/blocks.js';
+import * as eventUtils from './events/utils.js';
+import * as renderManagement from './render_management.js';
+import * as registry from './registry.js';
+import {Renderer as ZelosRenderer} from './renderers/zelos/renderer.js';
+import {ConnectionType} from './connection_type.js';
+
+export class InsertionMarkerPreviewer implements IConnectionPreviewer {
+  private readonly workspace: WorkspaceSvg;
+
+  private fadedBlock: BlockSvg | null = null;
+
+  private markerConn: RenderedConnection | null = null;
+
+  private draggedConn: RenderedConnection | null = null;
+
+  private staticConn: RenderedConnection | null = null;
+
+  constructor(draggedBlock: BlockSvg) {
+    this.workspace = draggedBlock.workspace;
+  }
+
+  /**
+   * Display a connection preview where the draggedCon connects to the
+   * staticCon, replacing the replacedBlock (currently connected to the
+   * staticCon).
+   *
+   * @param draggedConn The connection on the block stack being dragged.
+   * @param staticConn The connection not being dragged that we are
+   *     connecting to.
+   * @param replacedBlock The block currently connected to the staticCon that
+   *     is being replaced.
+   */
+  previewReplacement(
+    draggedConn: RenderedConnection,
+    staticConn: RenderedConnection,
+    replacedBlock: BlockSvg,
+  ) {
+    eventUtils.disable();
+    try {
+      this.hidePreview();
+      this.fadedBlock = replacedBlock;
+      replacedBlock.fadeForReplacement(true);
+      if (this.workspace.getRenderer().shouldHighlightConnection(staticConn)) {
+        staticConn.highlight();
+        this.staticConn = staticConn;
+      }
+    } finally {
+      eventUtils.enable();
+    }
+  }
+
+  /**
+   * Display a connection preview where the draggedCon connects to the
+   * staticCon, and no block is being relaced.
+   *
+   * @param draggedConn The connection on the block stack being dragged.
+   * @param staticConn The connection not being dragged that we are
+   *     connecting to.
+   */
+  previewConnection(
+    draggedConn: RenderedConnection,
+    staticConn: RenderedConnection,
+  ) {
+    if (draggedConn === this.draggedConn && staticConn === this.staticConn) {
+      return;
+    }
+
+    eventUtils.disable();
+    try {
+      this.hidePreview();
+
+      // TODO(7898): Instead of special casing, we should change the dragger to
+      //   track the change in distance between the dragged connection and the
+      //   static connection, so that it doesn't disconnect  unless that
+      //   (+ a bit) has been exceeded.
+      if (this.shouldUseMarkerPreview(draggedConn, staticConn)) {
+        this.markerConn = this.previewMarker(draggedConn, staticConn);
+      }
+
+      if (this.workspace.getRenderer().shouldHighlightConnection(staticConn)) {
+        staticConn.highlight();
+      }
+
+      this.draggedConn = draggedConn;
+      this.staticConn = staticConn;
+    } finally {
+      eventUtils.enable();
+    }
+  }
+
+  private shouldUseMarkerPreview(
+    _draggedConn: RenderedConnection,
+    staticConn: RenderedConnection,
+  ): boolean {
+    return (
+      staticConn.type === ConnectionType.PREVIOUS_STATEMENT ||
+      staticConn.type === ConnectionType.NEXT_STATEMENT ||
+      !(this.workspace.getRenderer() instanceof ZelosRenderer)
+    );
+  }
+
+  private previewMarker(
+    draggedConn: RenderedConnection,
+    staticConn: RenderedConnection,
+  ): RenderedConnection | null {
+    const dragged = draggedConn.getSourceBlock();
+    const marker = this.createInsertionMarker(dragged);
+    const markerConn = this.getMatchingConnection(dragged, marker, draggedConn);
+    if (!markerConn) return null;
+
+    // Render disconnected from everything else so that we have a valid
+    // connection location.
+    marker.queueRender();
+    renderManagement.triggerQueuedRenders();
+
+    // Connect() also renders the insertion marker.
+    markerConn.connect(staticConn);
+
+    const originalOffsetToTarget = {
+      x: staticConn.x - markerConn.x,
+      y: staticConn.y - markerConn.y,
+    };
+    const originalOffsetInBlock = markerConn.getOffsetInBlock().clone();
+    renderManagement.finishQueuedRenders().then(() => {
+      if (marker.isDeadOrDying()) return;
+      eventUtils.disable();
+      try {
+        // Position so that the existing block doesn't move.
+        marker?.positionNearConnection(
+          markerConn,
+          originalOffsetToTarget,
+          originalOffsetInBlock,
+        );
+        marker?.getSvgRoot().setAttribute('visibility', 'visible');
+      } finally {
+        eventUtils.enable();
+      }
+    });
+    return markerConn;
+  }
+
+  private createInsertionMarker(origBlock: BlockSvg) {
+    const blockJson = blocks.save(origBlock, {
+      addCoordinates: false,
+      addInputBlocks: false,
+      addNextBlocks: false,
+      doFullSerialization: false,
+    });
+
+    if (!blockJson) {
+      throw new Error(
+        `Failed to serialize source block. ${origBlock.toDevString()}`,
+      );
+    }
+
+    const result = blocks.append(blockJson, this.workspace) as BlockSvg;
+
+    // Turn shadow blocks that are created programmatically during
+    // initalization to insertion markers too.
+    for (const block of result.getDescendants(false)) {
+      block.setInsertionMarker(true);
+    }
+
+    result.initSvg();
+    result.getSvgRoot().setAttribute('visibility', 'hidden');
+    return result;
+  }
+
+  /**
+   * Gets the connection on the marker block that matches the original
+   * connection on the original block.
+   *
+   * @param orig The original block.
+   * @param marker The marker block (where we want to find the matching
+   *     connection).
+   * @param origConn The original connection.
+   */
+  private getMatchingConnection(
+    orig: BlockSvg,
+    marker: BlockSvg,
+    origConn: RenderedConnection,
+  ): RenderedConnection | null {
+    const origConns = orig.getConnections_(true);
+    const markerConns = marker.getConnections_(true);
+    if (origConns.length !== markerConns.length) return null;
+    for (let i = 0; i < origConns.length; i++) {
+      if (origConns[i] === origConn) {
+        return markerConns[i];
+      }
+    }
+    return null;
+  }
+
+  /** Hide any previews that are currently displayed. */
+  hidePreview() {
+    eventUtils.disable();
+    try {
+      if (this.staticConn) {
+        this.staticConn.unhighlight();
+        this.staticConn = null;
+      }
+      if (this.fadedBlock) {
+        this.fadedBlock.fadeForReplacement(false);
+        this.fadedBlock = null;
+      }
+      if (this.markerConn) {
+        this.hideInsertionMarker(this.markerConn);
+        this.markerConn = null;
+        this.draggedConn = null;
+      }
+    } finally {
+      eventUtils.enable();
+    }
+  }
+
+  private hideInsertionMarker(markerConn: RenderedConnection) {
+    const marker = markerConn.getSourceBlock();
+    const markerPrev = marker.previousConnection;
+    const markerOutput = marker.outputConnection;
+
+    if (!markerPrev?.targetConnection && !markerOutput?.targetConnection) {
+      // If we are the top block, unplugging doesn't do anything.
+      // The marker connection may not have a target block if we are hiding
+      // as part of applying connections.
+      markerConn.targetBlock()?.unplug(false);
+    } else {
+      marker.unplug(true);
+    }
+
+    marker.dispose();
+  }
+
+  /** Dispose of any references held by this connection previewer. */
+  dispose() {
+    this.hidePreview();
+  }
+}
+
+registry.register(
+  registry.Type.CONNECTION_PREVIEWER,
+  registry.DEFAULT,
+  InsertionMarkerPreviewer,
+);

package/blockly-rc/core/interfaces/i_ast_node_location.ts

@@ -0,0 +1,12 @@
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+// Former goog.module ID: Blockly.IASTNodeLocation
+
+/**
+ * An AST node location interface.
+ */
+export interface IASTNodeLocation {}

package/blockly-rc/core/interfaces/i_ast_node_location_svg.ts

@@ -0,0 +1,28 @@
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+// Former goog.module ID: Blockly.IASTNodeLocationSvg
+
+import type {IASTNodeLocation} from './i_ast_node_location.js';
+
+/**
+ * An AST node location SVG interface.
+ */
+export interface IASTNodeLocationSvg extends IASTNodeLocation {
+  /**
+   * Add the marker SVG to this node's SVG group.
+   *
+   * @param markerSvg The SVG root of the marker to be added to the SVG group.
+   */
+  setMarkerSvg(markerSvg: SVGElement | null): void;
+
+  /**
+   * Add the cursor SVG to this node's SVG group.
+   *
+   * @param cursorSvg The SVG root of the cursor to be added to the SVG group.
+   */
+  setCursorSvg(cursorSvg: SVGElement | null): void;
+}

package/blockly-rc/core/interfaces/i_ast_node_location_with_block.ts

@@ -0,0 +1,22 @@
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+// Former goog.module ID: Blockly.IASTNodeLocationWithBlock
+
+import type {IASTNodeLocation} from './i_ast_node_location.js';
+import type {Block} from '../block.js';
+
+/**
+ * An AST node location that has an associated block.
+ */
+export interface IASTNodeLocationWithBlock extends IASTNodeLocation {
+  /**
+   * Get the source block associated with this node.
+   *
+   * @returns The source block.
+   */
+  getSourceBlock(): Block | null;
+}

package/blockly-rc/core/interfaces/i_autohideable.ts

@@ -0,0 +1,22 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+// Former goog.module ID: Blockly.IAutoHideable
+
+import type {IComponent} from './i_component.js';
+
+/**
+ * Interface for a component that can be automatically hidden.
+ */
+export interface IAutoHideable extends IComponent {
+  /**
+   * Hides the component. Called in WorkspaceSvg.hideChaff.
+   *
+   * @param onlyClosePopups Whether only popups should be closed.
+   *   Flyouts should not be closed if this is true.
+   */
+  autoHide(onlyClosePopups: boolean): void;
+}

package/blockly-rc/core/interfaces/i_bounded_element.ts

@@ -0,0 +1,30 @@
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type {Rect} from '../utils/rect.js';
+// Former goog.module ID: Blockly.IBoundedElement
+
+/**
+ * A bounded element interface.
+ */
+export interface IBoundedElement {
+  /**
+   * Returns the coordinates of a bounded element describing the dimensions of
+   * the element. Coordinate system: workspace coordinates.
+   *
+   * @returns Object with coordinates of the bounded element.
+   */
+  getBoundingRectangle(): Rect;
+
+  /**
+   * Move the element by a relative offset.
+   *
+   * @param dx Horizontal offset in workspace units.
+   * @param dy Vertical offset in workspace units.
+   * @param reason Why is this move happening?  'user', 'bump', 'snap'...
+   */
+  moveBy(dx: number, dy: number, reason?: string[]): void;
+}

package/blockly-rc/core/interfaces/i_bubble.ts

@@ -0,0 +1,63 @@
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type {Coordinate} from '../utils/coordinate.js';
+// Former goog.module ID: Blockly.IBubble
+
+import type {IContextMenu} from './i_contextmenu.js';
+import type {IDraggable} from './i_draggable.js';
+
+/**
+ * A bubble interface.
+ */
+export interface IBubble extends IDraggable, IContextMenu {
+  /**
+   * Return the coordinates of the top-left corner of this bubble's body
+   * relative to the drawing surface's origin (0,0), in workspace units.
+   *
+   * @returns Object with .x and .y properties.
+   */
+  getRelativeToSurfaceXY(): Coordinate;
+
+  /**
+   * Return the root node of the bubble's SVG group.
+   *
+   * @returns The root SVG node of the bubble's group.
+   */
+  getSvgRoot(): SVGElement;
+
+  /**
+   * Sets whether or not this bubble is being dragged.
+   *
+   * @param adding True if dragging, false otherwise.
+   */
+  setDragging(dragging: boolean): void;
+
+  /**
+   * Move this bubble during a drag.
+   *
+   * @param newLoc The location to translate to, in workspace coordinates.
+   */
+  moveDuringDrag(newLoc: Coordinate): void;
+
+  /**
+   * Move the bubble to the specified location in workspace coordinates.
+   *
+   * @param x The x position to move to.
+   * @param y The y position to move to.
+   */
+  moveTo(x: number, y: number): void;
+
+  /**
+   * Update the style of this bubble when it is dragged over a delete area.
+   *
+   * @param enable True if the bubble is about to be deleted, false otherwise.
+   */
+  setDeleteStyle(enable: boolean): void;
+
+  /** Dispose of this bubble. */
+  dispose(): void;
+}

package/blockly-rc/core/interfaces/i_collapsible_toolbox_item.ts

@@ -0,0 +1,33 @@
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+// Former goog.module ID: Blockly.ICollapsibleToolboxItem
+
+import type {ISelectableToolboxItem} from './i_selectable_toolbox_item.js';
+import type {IToolboxItem} from './i_toolbox_item.js';
+
+/**
+ * Interface for an item in the toolbox that can be collapsed.
+ */
+export interface ICollapsibleToolboxItem extends ISelectableToolboxItem {
+  /**
+   * Gets any children toolbox items. (ex. Gets the subcategories)
+   *
+   * @returns The child toolbox items.
+   */
+  getChildToolboxItems(): IToolboxItem[];
+
+  /**
+   * Whether the toolbox item is expanded to show its child subcategories.
+   *
+   * @returns True if the toolbox item shows its children, false if it is
+   *     collapsed.
+   */
+  isExpanded(): boolean;
+
+  /** Toggles whether or not the toolbox item is expanded. */
+  toggleExpanded(): void;
+}

package/blockly-rc/core/interfaces/i_comment_icon.ts

@@ -0,0 +1,47 @@
+/**
+ * @license
+ * Copyright 2024 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {IconType} from '../icons/icon_types.js';
+import {CommentState} from '../icons/comment_icon.js';
+import {IIcon, isIcon} from './i_icon.js';
+import {Size} from '../utils/size.js';
+import {Coordinate} from '../utils/coordinate.js';
+import {IHasBubble, hasBubble} from './i_has_bubble.js';
+import {ISerializable, isSerializable} from './i_serializable.js';
+
+export interface ICommentIcon extends IIcon, IHasBubble, ISerializable {
+  setText(text: string): void;
+
+  getText(): string;
+
+  setBubbleSize(size: Size): void;
+
+  getBubbleSize(): Size;
+
+  setBubbleLocation(location: Coordinate): void;
+
+  getBubbleLocation(): Coordinate | undefined;
+
+  saveState(): CommentState;
+
+  loadState(state: CommentState): void;
+}
+
+/** Checks whether the given object is an ICommentIcon. */
+export function isCommentIcon(obj: Object): obj is ICommentIcon {
+  return (
+    isIcon(obj) &&
+    hasBubble(obj) &&
+    isSerializable(obj) &&
+    (obj as any)['setText'] !== undefined &&
+    (obj as any)['getText'] !== undefined &&
+    (obj as any)['setBubbleSize'] !== undefined &&
+    (obj as any)['getBubbleSize'] !== undefined &&
+    (obj as any)['setBubbleLocation'] !== undefined &&
+    (obj as any)['getBubbleLocation'] !== undefined &&
+    obj.getType() === IconType.COMMENT
+  );
+}

package/blockly-rc/core/interfaces/i_component.ts

@@ -0,0 +1,19 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+// Former goog.module ID: Blockly.IComponent
+
+/**
+ * The interface for a workspace component that can be registered with the
+ * ComponentManager.
+ */
+export interface IComponent {
+  /**
+   * The unique ID for this component that is used to register with the
+   * ComponentManager.
+   */
+  id: string;
+}

package/blockly-rc/core/interfaces/i_connection_checker.ts

@@ -0,0 +1,100 @@
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type {Connection} from '../connection.js';
+import type {RenderedConnection} from '../rendered_connection.js';
+// Former goog.module ID: Blockly.IConnectionChecker
+
+/**
+ * Class for connection type checking logic.
+ */
+export interface IConnectionChecker {
+  /**
+   * Check whether the current connection can connect with the target
+   * connection.
+   *
+   * @param a Connection to check compatibility with.
+   * @param b Connection to check compatibility with.
+   * @param isDragging True if the connection is being made by dragging a block.
+   * @param opt_distance The max allowable distance between the connections for
+   *     drag checks.
+   * @returns Whether the connection is legal.
+   */
+  canConnect(
+    a: Connection | null,
+    b: Connection | null,
+    isDragging: boolean,
+    opt_distance?: number,
+  ): boolean;
+
+  /**
+   * Checks whether the current connection can connect with the target
+   * connection, and return an error code if there are problems.
+   *
+   * @param a Connection to check compatibility with.
+   * @param b Connection to check compatibility with.
+   * @param isDragging True if the connection is being made by dragging a block.
+   * @param opt_distance The max allowable distance between the connections for
+   *     drag checks.
+   * @returns Connection.CAN_CONNECT if the connection is legal, an error code
+   *     otherwise.
+   */
+  canConnectWithReason(
+    a: Connection | null,
+    b: Connection | null,
+    isDragging: boolean,
+    opt_distance?: number,
+  ): number;
+
+  /**
+   * Helper method that translates a connection error code into a string.
+   *
+   * @param errorCode The error code.
+   * @param a One of the two connections being checked.
+   * @param b The second of the two connections being checked.
+   * @returns A developer-readable error string.
+   */
+  getErrorMessage(
+    errorCode: number,
+    a: Connection | null,
+    b: Connection | null,
+  ): string;
+
+  /**
+   * Check that connecting the given connections is safe, meaning that it would
+   * not break any of Blockly's basic assumptions (e.g. no self connections).
+   *
+   * @param a The first of the connections to check.
+   * @param b The second of the connections to check.
+   * @returns An enum with the reason this connection is safe or unsafe.
+   */
+  doSafetyChecks(a: Connection | null, b: Connection | null): number;
+
+  /**
+   * Check whether this connection is compatible with another connection with
+   * respect to the value type system.  E.g. square_root("Hello") is not
+   * compatible.
+   *
+   * @param a Connection to compare.
+   * @param b Connection to compare against.
+   * @returns True if the connections share a type.
+   */
+  doTypeChecks(a: Connection, b: Connection): boolean;
+
+  /**
+   * Check whether this connection can be made by dragging.
+   *
+   * @param a Connection to compare.
+   * @param b Connection to compare against.
+   * @param distance The maximum allowable distance between connections.
+   * @returns True if the connection is allowed during a drag.
+   */
+  doDragChecks(
+    a: RenderedConnection,
+    b: RenderedConnection,
+    distance: number,
+  ): boolean;
+}

package/blockly-rc/core/interfaces/i_connection_previewer.ts

@@ -0,0 +1,50 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type {BlockSvg} from '../block_svg';
+import type {RenderedConnection} from '../rendered_connection';
+
+/**
+ * Displays visual "previews" of where a block will be connected if it is
+ * dropped.
+ */
+export interface IConnectionPreviewer {
+  /**
+   * Display a connection preview where the draggedCon connects to the
+   * staticCon, replacing the replacedBlock (currently connected to the
+   * staticCon).
+   *
+   * @param draggedCon The connection on the block stack being dragged.
+   * @param staticCon The connection not being dragged that we are
+   *     connecting to.
+   * @param replacedBlock The block currently connected to the staticCon that
+   *     is being replaced.
+   */
+  previewReplacement(
+    draggedConn: RenderedConnection,
+    staticConn: RenderedConnection,
+    replacedBlock: BlockSvg,
+  ): void;
+
+  /**
+   * Display a connection preview where the draggedCon connects to the
+   * staticCon, and no block is being relaced.
+   *
+   * @param draggedCon The connection on the block stack being dragged.
+   * @param staticCon The connection not being dragged that we are
+   *     connecting to.
+   */
+  previewConnection(
+    draggedConn: RenderedConnection,
+    staticConn: RenderedConnection,
+  ): void;
+
+  /** Hide any previews that are currently displayed. */
+  hidePreview(): void;
+
+  /** Dispose of any references held by this connection previewer. */
+  dispose(): void;
+}