blockly 12.3.1 → 12.4.0

package/core/interfaces/i_autohideable.ts

@@ -0,0 +1,27 @@
+/**
+ * @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;
+}
+
+/** Returns true if the given object is autohideable. */
+export function isAutoHideable(obj: any): obj is IAutoHideable {
+  return obj && typeof obj.autoHide === 'function';
+}

package/core/interfaces/i_bounded_element.ts

@@ -0,0 +1,31 @@
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+// Former goog.module ID: Blockly.IBoundedElement
+
+import type {Rect} from '../utils/rect.js';
+
+/**
+ * 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/core/interfaces/i_bubble.ts

@@ -0,0 +1,64 @@
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+// Former goog.module ID: Blockly.IBubble
+
+import type {Coordinate} from '../utils/coordinate.js';
+import type {IContextMenu} from './i_contextmenu.js';
+import type {IDraggable} from './i_draggable.js';
+import {IFocusableNode} from './i_focusable_node.js';
+
+/**
+ * A bubble interface.
+ */
+export interface IBubble extends IDraggable, IContextMenu, IFocusableNode {
+  /**
+   * 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/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/core/interfaces/i_comment_icon.ts

@@ -0,0 +1,47 @@
+/**
+ * @license
+ * Copyright 2024 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {CommentState} from '../icons/comment_icon.js';
+import {IconType} from '../icons/icon_types.js';
+import {Coordinate} from '../utils/coordinate.js';
+import {Size} from '../utils/size.js';
+import {IHasBubble, hasBubble} from './i_has_bubble.js';
+import {IIcon, isIcon} from './i_icon.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: any): obj is ICommentIcon {
+  return (
+    isIcon(obj) &&
+    hasBubble(obj) &&
+    isSerializable(obj) &&
+    typeof (obj as any).setText === 'function' &&
+    typeof (obj as any).getText === 'function' &&
+    typeof (obj as any).setBubbleSize === 'function' &&
+    typeof (obj as any).getBubbleSize === 'function' &&
+    typeof (obj as any).setBubbleLocation === 'function' &&
+    typeof (obj as any).getBubbleLocation === 'function' &&
+    obj.getType() === IconType.COMMENT
+  );
+}

package/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/core/interfaces/i_connection_checker.ts

@@ -0,0 +1,101 @@
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+// Former goog.module ID: Blockly.IConnectionChecker
+
+import type {Connection} from '../connection.js';
+import type {RenderedConnection} from '../rendered_connection.js';
+
+/**
+ * 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/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;
+}

package/core/interfaces/i_contextmenu.ts

@@ -0,0 +1,21 @@
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+// Former goog.module ID: Blockly.IContextMenu
+
+export interface IContextMenu {
+  /**
+   * Show the context menu for this object.
+   *
+   * @param e Mouse event.
+   */
+  showContextMenu(e: Event): void;
+}
+
+/** @returns true if the given object implements IContextMenu. */
+export function hasContextMenu(obj: any): obj is IContextMenu {
+  return obj && typeof obj.showContextMenu === 'function';
+}

package/core/interfaces/i_copyable.ts

@@ -0,0 +1,39 @@
+/**
+ * @license
+ * Copyright 2019 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+// Former goog.module ID: Blockly.ICopyable
+
+import type {ISelectable} from './i_selectable.js';
+
+export interface ICopyable<T extends ICopyData> extends ISelectable {
+  /**
+   * Encode for copying.
+   *
+   * @returns Copy metadata.
+   */
+  toCopyData(): T | null;
+
+  /**
+   * Whether this instance is currently copyable. The standard implementation
+   * is to return true if isOwnDeletable and isOwnMovable return true.
+   *
+   * @returns True if it can currently be copied.
+   */
+  isCopyable?(): boolean;
+}
+
+export namespace ICopyable {
+  export interface ICopyData {
+    paster: string;
+  }
+}
+
+export type ICopyData = ICopyable.ICopyData;
+
+/** @returns true if the given object is an ICopyable. */
+export function isCopyable(obj: any): obj is ICopyable<ICopyData> {
+  return obj && typeof obj.toCopyData === 'function';
+}

package/core/interfaces/i_deletable.ts

@@ -0,0 +1,35 @@
+/**
+ * @license
+ * Copyright 2019 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+// Former goog.module ID: Blockly.IDeletable
+
+/**
+ * The interface for an object that can be deleted.
+ */
+export interface IDeletable {
+  /**
+   * Get whether this object is deletable or not.
+   *
+   * @returns True if deletable.
+   */
+  isDeletable(): boolean;
+
+  /** Disposes of this object, cleaning up any references or DOM elements. */
+  dispose(): void;
+
+  /** Visually indicates that the object is pending deletion. */
+  setDeleteStyle(wouldDelete: boolean): void;
+}
+
+/** Returns whether the given object is an IDeletable. */
+export function isDeletable(obj: any): obj is IDeletable {
+  return (
+    obj &&
+    typeof obj.isDeletable === 'function' &&
+    typeof obj.dispose === 'function' &&
+    typeof obj.setDeleteStyle === 'function'
+  );
+}

package/core/interfaces/i_delete_area.ts

@@ -0,0 +1,28 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+// Former goog.module ID: Blockly.IDeleteArea
+
+import type {IDragTarget} from './i_drag_target.js';
+import type {IDraggable} from './i_draggable.js';
+
+/**
+ * Interface for a component that can delete a block or bubble that is dropped
+ * on top of it.
+ */
+export interface IDeleteArea extends IDragTarget {
+  /**
+   * Returns whether the provided block or bubble would be deleted if dropped on
+   * this area.
+   * This method should check if the element is deletable and is always called
+   * before onDragEnter/onDragOver/onDragExit.
+   *
+   * @param element The block or bubble currently being dragged.
+   * @returns Whether the element provided would be deleted if dropped on this
+   *     area.
+   */
+  wouldDelete(element: IDraggable): boolean;
+}

package/core/interfaces/i_drag_target.ts

@@ -0,0 +1,67 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+// Former goog.module ID: Blockly.IDragTarget
+
+import {Rect} from '../utils/rect.js';
+import type {IComponent} from './i_component.js';
+import {IDraggable} from './i_draggable.js';
+
+/**
+ * Interface for a component with custom behaviour when a block or bubble is
+ * dragged over or dropped on top of it.
+ */
+export interface IDragTarget extends IComponent {
+  /**
+   * Returns the bounding rectangle of the drag target area in pixel units
+   * relative to viewport.
+   *
+   * @returns The component's bounding box. Null if drag target area should be
+   *     ignored.
+   */
+  getClientRect(): Rect | null;
+
+  /**
+   * Handles when a cursor with a block or bubble enters this drag target.
+   *
+   * @param dragElement The block or bubble currently being dragged.
+   */
+  onDragEnter(dragElement: IDraggable): void;
+
+  /**
+   * Handles when a cursor with a block or bubble is dragged over this drag
+   * target.
+   *
+   * @param dragElement The block or bubble currently being dragged.
+   */
+  onDragOver(dragElement: IDraggable): void;
+
+  /**
+   * Handles when a cursor with a block or bubble exits this drag target.
+   *
+   * @param dragElement The block or bubble currently being dragged.
+   */
+  onDragExit(dragElement: IDraggable): void;
+
+  /**
+   * Handles when a block or bubble is dropped on this component.
+   * Should not handle delete here.
+   *
+   * @param dragElement The block or bubble currently being dragged.
+   */
+  onDrop(dragElement: IDraggable): void;
+
+  /**
+   * Returns whether the provided block or bubble should not be moved after
+   * being dropped on this component. If true, the element will return to where
+   * it was when the drag started.
+   *
+   * @param dragElement The block or bubble currently being dragged.
+   * @returns Whether the block or bubble provided should be returned to drag
+   *     start.
+   */
+  shouldPreventMove(dragElement: IDraggable): boolean;
+}

package/core/interfaces/i_draggable.ts

@@ -0,0 +1,73 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {Coordinate} from '../utils/coordinate';
+
+/**
+ * Represents an object that can be dragged.
+ */
+export interface IDraggable extends IDragStrategy {
+  /**
+   * Returns the current location of the draggable in workspace
+   * coordinates.
+   *
+   * @returns Coordinate of current location on workspace.
+   */
+  getRelativeToSurfaceXY(): Coordinate;
+}
+
+export interface IDragStrategy {
+  /** Returns true iff the element is currently movable. */
+  isMovable(): boolean;
+
+  /**
+   * Handles any drag startup (e.g moving elements to the front of the
+   * workspace).
+   *
+   * @param e PointerEvent that started the drag; can be used to
+   *     check modifier keys, etc.  May be missing when dragging is
+   *     triggered programatically rather than by user.
+   */
+  startDrag(e?: PointerEvent): void;
+
+  /**
+   * Handles moving elements to the new location, and updating any
+   * visuals based on that (e.g connection previews for blocks).
+   *
+   * @param newLoc Workspace coordinate to which the draggable has
+   *     been dragged.
+   * @param e PointerEvent that continued the drag.  Can be
+   *     used to check modifier keys, etc.
+   */
+  drag(newLoc: Coordinate, e?: PointerEvent): void;
+
+  /**
+   * Handles any drag cleanup, including e.g. connecting or deleting
+   * blocks.
+   *
+   * @param newLoc Workspace coordinate at which the drag finished.
+   *     been dragged.
+   * @param e PointerEvent that finished the drag.  Can be
+   *     used to check modifier keys, etc.
+   */
+  endDrag(e?: PointerEvent): void;
+
+  /** Moves the draggable back to where it was at the start of the drag. */
+  revertDrag(): void;
+}
+
+/** Returns whether the given object is an IDraggable or not. */
+export function isDraggable(obj: any): obj is IDraggable {
+  return (
+    obj &&
+    typeof obj.getRelativeToSurfaceXY === 'function' &&
+    typeof obj.isMovable === 'function' &&
+    typeof obj.startDrag === 'function' &&
+    typeof obj.drag === 'function' &&
+    typeof obj.endDrag === 'function' &&
+    typeof obj.revertDrag === 'function'
+  );
+}

package/core/interfaces/i_dragger.ts

@@ -0,0 +1,35 @@
+/**
+ * @license
+ * Copyright 2024 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {Coordinate} from '../utils/coordinate';
+
+export interface IDragger {
+  /**
+   * Handles any drag startup.
+   *
+   * @param e PointerEvent that started the drag.
+   */
+  onDragStart(e: PointerEvent): void;
+
+  /**
+   * Handles dragging, including calculating where the element should
+   * actually be moved to.
+   *
+   * @param e PointerEvent that continued the drag.
+   * @param totalDelta The total distance, in pixels, that the mouse
+   *     has moved since the start of the drag.
+   */
+  onDrag(e: PointerEvent, totalDelta: Coordinate): void;
+
+  /**
+   * Handles any drag cleanup.
+   *
+   * @param e PointerEvent that finished the drag.
+   * @param totalDelta The total distance, in pixels, that the mouse
+   *     has moved since the start of the drag.
+   */
+  onDragEnd(e: PointerEvent, totalDelta: Coordinate): void;
+}