blockly 12.4.0 → 12.5.0

package/core/insertion_marker_previewer.d.ts

@@ -0,0 +1,67 @@
+/**
+ * @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 * as blocks from './serialization/blocks.js';
+export declare class InsertionMarkerPreviewer implements IConnectionPreviewer {
+    private readonly workspace;
+    private fadedBlock;
+    private markerConn;
+    private draggedConn;
+    private staticConn;
+    constructor(draggedBlock: BlockSvg);
+    /**
+     * 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): void;
+    /**
+     * 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): void;
+    private shouldUseMarkerPreview;
+    private previewMarker;
+    /**
+     * Transforms the given block into a JSON representation used to construct an
+     * insertion marker.
+     *
+     * @param block The block to serialize and use as an insertion marker.
+     * @returns A JSON-formatted string corresponding to a serialized
+     *     representation of the given block suitable for use as an insertion
+     *     marker.
+     */
+    protected serializeBlockToInsertionMarker(block: BlockSvg): blocks.State;
+    private createInsertionMarker;
+    /**
+     * 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;
+    /** Hide any previews that are currently displayed. */
+    hidePreview(): void;
+    private hideInsertionMarker;
+    /** Dispose of any references held by this connection previewer. */
+    dispose(): void;
+}
+//# sourceMappingURL=insertion_marker_previewer.d.ts.map

package/core/interfaces/i_autohideable.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+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 declare function isAutoHideable(obj: any): obj is IAutoHideable;
+//# sourceMappingURL=i_autohideable.d.ts.map

package/core/interfaces/i_bounded_element.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+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;
+}
+//# sourceMappingURL=i_bounded_element.d.ts.map

package/core/interfaces/i_bubble.d.ts

@@ -0,0 +1,55 @@
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+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;
+}
+//# sourceMappingURL=i_bubble.d.ts.map

package/core/interfaces/i_collapsible_toolbox_item.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+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;
+}
+//# sourceMappingURL=i_collapsible_toolbox_item.d.ts.map

package/core/interfaces/i_comment_icon.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @license
+ * Copyright 2024 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { CommentState } from '../icons/comment_icon.js';
+import { Coordinate } from '../utils/coordinate.js';
+import { Size } from '../utils/size.js';
+import { IHasBubble } from './i_has_bubble.js';
+import { IIcon } from './i_icon.js';
+import { ISerializable } 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 declare function isCommentIcon(obj: any): obj is ICommentIcon;
+//# sourceMappingURL=i_comment_icon.d.ts.map

package/core/interfaces/i_component.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * 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;
+}
+//# sourceMappingURL=i_component.d.ts.map

package/core/interfaces/i_connection_checker.d.ts

@@ -0,0 +1,75 @@
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+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;
+}
+//# sourceMappingURL=i_connection_checker.d.ts.map

package/core/interfaces/i_connection_previewer.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @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;
+}
+//# sourceMappingURL=i_connection_previewer.d.ts.map

package/core/interfaces/i_contextmenu.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+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 declare function hasContextMenu(obj: any): obj is IContextMenu;
+//# sourceMappingURL=i_contextmenu.d.ts.map

package/core/interfaces/i_copyable.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @license
+ * Copyright 2019 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+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 declare namespace ICopyable {
+    interface ICopyData {
+        paster: string;
+    }
+}
+export type ICopyData = ICopyable.ICopyData;
+/** @returns true if the given object is an ICopyable. */
+export declare function isCopyable(obj: any): obj is ICopyable<ICopyData>;
+//# sourceMappingURL=i_copyable.d.ts.map

package/core/interfaces/i_deletable.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @license
+ * Copyright 2019 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * 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 declare function isDeletable(obj: any): obj is IDeletable;
+//# sourceMappingURL=i_deletable.d.ts.map

package/core/interfaces/i_delete_area.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+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;
+}
+//# sourceMappingURL=i_delete_area.d.ts.map

package/core/interfaces/i_drag_target.d.ts

@@ -0,0 +1,59 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+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;
+}
+//# sourceMappingURL=i_drag_target.d.ts.map

package/core/interfaces/i_draggable.d.ts

@@ -0,0 +1,56 @@
+/**
+ * @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 declare function isDraggable(obj: any): obj is IDraggable;
+//# sourceMappingURL=i_draggable.d.ts.map

package/core/interfaces/i_dragger.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @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;
+}
+//# sourceMappingURL=i_dragger.d.ts.map