blockly 12.4.0 → 12.4.1

package/core/contextmenu_registry.d.ts

@@ -0,0 +1,173 @@
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Registry for context menu option items.
+ *
+ * @class
+ */
+import type { BlockSvg } from './block_svg.js';
+import { RenderedWorkspaceComment } from './comments/rendered_workspace_comment.js';
+import type { IFocusableNode } from './interfaces/i_focusable_node.js';
+import { Coordinate } from './utils/coordinate.js';
+import type { WorkspaceSvg } from './workspace_svg.js';
+/**
+ * Class for the registry of context menu items. This is intended to be a
+ * singleton. You should not create a new instance, and only access this class
+ * from ContextMenuRegistry.registry.
+ */
+export declare class ContextMenuRegistry {
+    static registry: ContextMenuRegistry;
+    /** Registry of all registered RegistryItems, keyed by ID. */
+    private registeredItems;
+    /** Resets the existing singleton instance of ContextMenuRegistry. */
+    constructor();
+    /** Clear and recreate the registry. */
+    reset(): void;
+    /**
+     * Registers a RegistryItem.
+     *
+     * @param item Context menu item to register.
+     * @throws {Error} if an item with the given ID already exists.
+     */
+    register(item: RegistryItem): void;
+    /**
+     * Unregisters a RegistryItem with the given ID.
+     *
+     * @param id The ID of the RegistryItem to remove.
+     * @throws {Error} if an item with the given ID does not exist.
+     */
+    unregister(id: string): void;
+    /**
+     * @param id The ID of the RegistryItem to get.
+     * @returns RegistryItem or null if not found
+     */
+    getItem(id: string): RegistryItem | null;
+    /**
+     * Gets the valid context menu options for the given scope.
+     * Options are only included if the preconditionFn shows
+     * they should not be hidden.
+     *
+     * @param scope Current scope of context menu (i.e., the exact workspace or
+     *     block being clicked on).
+     * @param menuOpenEvent Event that caused the menu to open.
+     * @returns the list of ContextMenuOptions
+     */
+    getContextMenuOptions(scope: Scope, menuOpenEvent: Event): ContextMenuOption[];
+}
+export declare namespace ContextMenuRegistry {
+    /**
+     * Where this menu item should be rendered. If the menu item should be
+     * rendered in multiple scopes, e.g. on both a block and a workspace, it
+     * should be registered for each scope.
+     */
+    export enum ScopeType {
+        BLOCK = "block",
+        WORKSPACE = "workspace",
+        COMMENT = "comment"
+    }
+    /**
+     * The actual workspace/block/focused object where the menu is being
+     * rendered. This is passed to callback and displayText functions
+     * that depend on this information.
+     */
+    export interface Scope {
+        block?: BlockSvg;
+        workspace?: WorkspaceSvg;
+        comment?: RenderedWorkspaceComment;
+        focusedNode?: IFocusableNode;
+    }
+    /**
+     * Fields common to all context menu registry items.
+     */
+    interface CoreRegistryItem {
+        scopeType?: ScopeType;
+        weight: number;
+        id: string;
+        preconditionFn?: (p1: Scope, menuOpenEvent: Event) => string;
+    }
+    /**
+     * A representation of a normal, clickable menu item in the registry.
+     */
+    interface ActionRegistryItem extends CoreRegistryItem {
+        /**
+         * @param scope Object that provides a reference to the thing that had its
+         *     context menu opened.
+         * @param menuOpenEvent The original event that triggered the context menu to open.
+         * @param menuSelectEvent The event that triggered the option being selected.
+         * @param location The location in screen coordinates where the menu was opened.
+         */
+        callback: (scope: Scope, menuOpenEvent: Event, menuSelectEvent: Event, location: Coordinate) => void;
+        displayText: ((p1: Scope) => string | HTMLElement) | string | HTMLElement;
+        separator?: never;
+        preconditionFn: (p1: Scope, menuOpenEvent: Event) => string;
+    }
+    /**
+     * A representation of a menu separator item in the registry.
+     */
+    interface SeparatorRegistryItem extends CoreRegistryItem {
+        separator: true;
+        callback?: never;
+        displayText?: never;
+    }
+    /**
+     * A menu item as entered in the registry.
+     */
+    export type RegistryItem = ActionRegistryItem | SeparatorRegistryItem;
+    /**
+     * Fields common to all context menu items as used by contextmenu.ts.
+     */
+    export interface CoreContextMenuOption {
+        scope: Scope;
+        weight: number;
+    }
+    /**
+     * A representation of a normal, clickable menu item in contextmenu.ts.
+     */
+    export interface ActionContextMenuOption extends CoreContextMenuOption {
+        text: string | HTMLElement;
+        enabled: boolean;
+        /**
+         * @param scope Object that provides a reference to the thing that had its
+         *     context menu opened.
+         * @param menuOpenEvent The original event that triggered the context menu to open.
+         * @param menuSelectEvent The event that triggered the option being selected.
+         * @param location The location in screen coordinates where the menu was opened.
+         */
+        callback: (scope: Scope, menuOpenEvent: Event, menuSelectEvent: Event, location: Coordinate) => void;
+        separator?: never;
+    }
+    /**
+     * A representation of a menu separator item in contextmenu.ts.
+     */
+    export interface SeparatorContextMenuOption extends CoreContextMenuOption {
+        separator: true;
+        text?: never;
+        enabled?: never;
+        callback?: never;
+    }
+    /**
+     * A menu item as presented to contextmenu.ts.
+     */
+    export type ContextMenuOption = ActionContextMenuOption | SeparatorContextMenuOption;
+    /**
+     * A subset of ContextMenuOption corresponding to what was publicly
+     * documented.  ContextMenuOption should be preferred for new code.
+     */
+    export interface LegacyContextMenuOption {
+        text: string;
+        enabled: boolean;
+        callback: (p1: Scope) => void;
+        separator?: never;
+    }
+    export {};
+}
+export type ScopeType = ContextMenuRegistry.ScopeType;
+export declare const ScopeType: typeof ContextMenuRegistry.ScopeType;
+export type Scope = ContextMenuRegistry.Scope;
+export type RegistryItem = ContextMenuRegistry.RegistryItem;
+export type ContextMenuOption = ContextMenuRegistry.ContextMenuOption;
+export type LegacyContextMenuOption = ContextMenuRegistry.LegacyContextMenuOption;
+//# sourceMappingURL=contextmenu_registry.d.ts.map

package/core/css.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @license
+ * Copyright 2013 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Add some CSS to the blob that will be injected later.  Allows optional
+ * components such as fields and the toolbox to store separate CSS.
+ *
+ * @param cssContent Multiline CSS string or an array of single lines of CSS.
+ */
+export declare function register(cssContent: string): void;
+/**
+ * Inject the CSS into the DOM.  This is preferable over using a regular CSS
+ * file since:
+ * a) It loads synchronously and doesn't force a redraw later.
+ * b) It speeds up loading by not blocking on a separate HTTP transfer.
+ * c) The CSS content may be made dynamic depending on init options.
+ *
+ * @param hasCss If false, don't inject CSS (providing CSS becomes the
+ *     document's responsibility).
+ * @param pathToMedia Path from page to the Blockly media directory.
+ */
+export declare function inject(hasCss: boolean, pathToMedia: string): void;
+//# sourceMappingURL=css.d.ts.map

package/core/delete_area.d.ts

@@ -0,0 +1,48 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { DragTarget } from './drag_target.js';
+import type { IDeleteArea } from './interfaces/i_delete_area.js';
+import type { IDraggable } from './interfaces/i_draggable.js';
+/**
+ * Abstract class for a component that can delete a block or bubble that is
+ * dropped on top of it.
+ */
+export declare class DeleteArea extends DragTarget implements IDeleteArea {
+    /**
+     * Whether the last block or bubble dragged over this delete area would be
+     * deleted if dropped on this component.
+     * This property is not updated after the block or bubble is deleted.
+     */
+    protected wouldDelete_: boolean;
+    /**
+     * The unique id for this component that is used to register with the
+     * ComponentManager.
+     */
+    id: string;
+    /**
+     * Constructor for DeleteArea. Should not be called directly, only by a
+     * subclass.
+     */
+    constructor();
+    /**
+     * 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;
+    /**
+     * Updates the internal wouldDelete_ state.
+     *
+     * @param wouldDelete The new value for the wouldDelete state.
+     */
+    protected updateWouldDelete_(wouldDelete: boolean): void;
+}
+//# sourceMappingURL=delete_area.d.ts.map

package/core/dialog.d.ts

@@ -0,0 +1,82 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { ToastOptions } from './toast.js';
+import type { WorkspaceSvg } from './workspace_svg.js';
+/**
+ * Wrapper to window.alert() that app developers may override via setAlert to
+ * provide alternatives to the modal browser window.
+ *
+ * @param message The message to display to the user.
+ * @param opt_callback The callback when the alert is dismissed.
+ */
+export declare function alert(message: string, opt_callback?: () => void): void;
+/**
+ * Sets the function to be run when Blockly.dialog.alert() is called.
+ *
+ * @param alertFunction The function to be run, or undefined to restore the
+ *     default implementation.
+ * @see Blockly.dialog.alert
+ */
+export declare function setAlert(alertFunction?: (message: string, callback?: () => void) => void): void;
+/**
+ * Wrapper to window.confirm() that app developers may override via setConfirm
+ * to provide alternatives to the modal browser window.
+ *
+ * @param message The message to display to the user.
+ * @param callback The callback for handling user response.
+ */
+export declare function confirm(message: string, callback: (result: boolean) => void): void;
+/**
+ * Sets the function to be run when Blockly.dialog.confirm() is called.
+ *
+ * @param confirmFunction The function to be run, or undefined to restore the
+ *     default implementation.
+ * @see Blockly.dialog.confirm
+ */
+export declare function setConfirm(confirmFunction?: (message: string, callback: (result: boolean) => void) => void): void;
+/**
+ * Wrapper to window.prompt() that app developers may override via setPrompt to
+ * provide alternatives to the modal browser window. Built-in browser prompts
+ * are often used for better text input experience on mobile device. We strongly
+ * recommend testing mobile when overriding this.
+ *
+ * @param message The message to display to the user.
+ * @param defaultValue The value to initialize the prompt with.
+ * @param callback The callback for handling user response.
+ */
+export declare function prompt(message: string, defaultValue: string, callback: (result: string | null) => void): void;
+/**
+ * Sets the function to be run when Blockly.dialog.prompt() is called.
+ *
+ * **Important**: When overridding this, be aware that non-native prompt
+ * experiences may require managing ephemeral focus in FocusManager. This isn't
+ * needed for the native window prompt because it prevents focus from being
+ * changed while open.
+ *
+ * @param promptFunction The function to be run, or undefined to restore the
+ *     default implementation.
+ * @see Blockly.dialog.prompt
+ */
+export declare function setPrompt(promptFunction?: (message: string, defaultValue: string, callback: (result: string | null) => void) => void): void;
+/**
+ * Displays a temporary notification atop the workspace. Blockly provides a
+ * default toast implementation, but developers may provide their own via
+ * setToast. For simple appearance customization, CSS should be sufficient.
+ *
+ * @param workspace The workspace to display the toast notification atop.
+ * @param options Configuration options for the notification, including its
+ *     message and duration.
+ */
+export declare function toast(workspace: WorkspaceSvg, options: ToastOptions): void;
+/**
+ * Sets the function to be run when Blockly.dialog.toast() is called.
+ *
+ * @param toastFunction The function to be run, or undefined to restore the
+ *     default implementation.
+ * @see Blockly.dialog.toast
+ */
+export declare function setToast(toastFunction?: (workspace: WorkspaceSvg, options: ToastOptions) => void): void;
+//# sourceMappingURL=dialog.d.ts.map

package/core/drag_target.d.ts

@@ -0,0 +1,75 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * The abstract class for a component with custom behaviour when a
+ * block or bubble is dragged over or dropped on top of it.
+ *
+ * @class
+ */
+import type { IDragTarget } from './interfaces/i_drag_target.js';
+import type { IDraggable } from './interfaces/i_draggable.js';
+import type { Rect } from './utils/rect.js';
+/**
+ * Abstract class for a component with custom behaviour when a block or bubble
+ * is dragged over or dropped on top of it.
+ */
+export declare class DragTarget implements IDragTarget {
+    /**
+     * The unique id for this component that is used to register with the
+     * ComponentManager.
+     */
+    id: string;
+    /**
+     * Constructor for DragTarget. It exists to add the id property and should not
+     * be called directly, only by a subclass.
+     */
+    constructor();
+    /**
+     * 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 the bounding rectangle of the drag target area in pixel units
+     * relative to the Blockly injection div.
+     *
+     * @returns The component's bounding box. Null if drag target area should be
+     *     ignored.
+     */
+    getClientRect(): Rect | null;
+    /**
+     * 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=drag_target.d.ts.map

package/core/dragging/block_drag_strategy.d.ts

@@ -0,0 +1,130 @@
+/**
+ * @license
+ * Copyright 2024 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { BlockSvg } from '../block_svg.js';
+import { IDragStrategy } from '../interfaces/i_draggable.js';
+import { Coordinate } from '../utils.js';
+export declare class BlockDragStrategy implements IDragStrategy {
+    private block;
+    private workspace;
+    /** The parent block at the start of the drag. */
+    private startParentConn;
+    /**
+     * The child block at the start of the drag. Only gets set if
+     * `healStack` is true.
+     */
+    private startChildConn;
+    private startLoc;
+    private connectionCandidate;
+    private connectionPreviewer;
+    private dragging;
+    /**
+     * If this is a shadow block, the offset between this block and the parent
+     * block, to add to the drag location. In workspace units.
+     */
+    private dragOffset;
+    /** Used to persist an event group when snapping is done async. */
+    private originalEventGroup;
+    constructor(block: BlockSvg);
+    /** Returns true if the block is currently movable. False otherwise. */
+    isMovable(): boolean;
+    /**
+     * Handles any setup for starting the drag, including disconnecting the block
+     * from any parent blocks.
+     */
+    startDrag(e?: PointerEvent): void;
+    /**
+     * Returns an array of visible bubbles attached to the given block or its
+     * descendants.
+     *
+     * @param block The block to identify open bubbles on.
+     * @returns An array of all currently visible bubbles on the given block or
+     *    its descendants.
+     */
+    private getVisibleBubbles;
+    /**
+     * Get whether the drag should act on a single block or a block stack.
+     *
+     * @param e The instigating pointer event, if any.
+     * @returns True if just the initial block should be dragged out, false
+     *     if all following blocks should also be dragged.
+     */
+    protected shouldHealStack(e: PointerEvent | undefined): boolean;
+    /** Starts a drag on a shadow, recording the drag offset. */
+    private startDraggingShadow;
+    /**
+     * Whether or not we should disconnect the block when a drag is started.
+     *
+     * @param healStack Whether or not to heal the stack after disconnecting.
+     * @returns True to disconnect the block, false otherwise.
+     */
+    private shouldDisconnect;
+    /**
+     * Disconnects the block from any parents. If `healStack` is true and this is
+     * a stack block, we also disconnect from any next blocks and attempt to
+     * attach them to any parent.
+     *
+     * @param healStack Whether or not to heal the stack after disconnecting.
+     */
+    private disconnectBlock;
+    /** Fire a UI event at the start of a block drag. */
+    private fireDragStartEvent;
+    /** Fire a UI event at the end of a block drag. */
+    private fireDragEndEvent;
+    /** Fire a move event at the end of a block drag. */
+    private fireMoveEvent;
+    /** Moves the block and updates any connection previews. */
+    drag(newLoc: Coordinate): void;
+    /**
+     * @param draggingBlock The block being dragged.
+     * @param delta How far the pointer has moved from the position
+     *     at the start of the drag, in workspace units.
+     */
+    private updateConnectionPreview;
+    /**
+     * Returns true if the given orphan block can connect at the end of the
+     * top block's stack or row, false otherwise.
+     */
+    private orphanCanConnectAtEnd;
+    /**
+     * Returns true if the current candidate is better than the new candidate.
+     *
+     * We slightly prefer the current candidate even if it is farther away.
+     */
+    private currCandidateIsBetter;
+    /**
+     * Returns the closest valid candidate connection, if one can be found.
+     *
+     * Valid neighbour connections are within the configured start radius, with a
+     * compatible type (input, output, etc) and connection check.
+     */
+    private getConnectionCandidate;
+    /**
+     * Get the radius to use when searching for a nearby valid connection.
+     */
+    protected getSearchRadius(): number;
+    /**
+     * Returns all of the connections we might connect to blocks on the workspace.
+     *
+     * Includes any connections on the dragging block, and any last next
+     * connection on the stack (if one exists).
+     */
+    private getLocalConnections;
+    /**
+     * Cleans up any state at the end of the drag. Applies any pending
+     * connections.
+     */
+    endDrag(e?: PointerEvent): void;
+    /** Disposes of any state at the end of the drag. */
+    private disposeStep;
+    /** Connects the given candidate connections. */
+    private applyConnections;
+    /**
+     * Moves the block back to where it was at the beginning of the drag,
+     * including reconnecting connections.
+     */
+    revertDrag(): void;
+}
+//# sourceMappingURL=block_drag_strategy.d.ts.map

package/core/dragging/bubble_drag_strategy.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @license
+ * Copyright 2024 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { IBubble, WorkspaceSvg } from '../blockly.js';
+import { IDragStrategy } from '../interfaces/i_draggable.js';
+import { Coordinate } from '../utils.js';
+export declare class BubbleDragStrategy implements IDragStrategy {
+    private bubble;
+    private workspace;
+    private startLoc;
+    constructor(bubble: IBubble, workspace: WorkspaceSvg);
+    isMovable(): boolean;
+    startDrag(): void;
+    drag(newLoc: Coordinate): void;
+    endDrag(): void;
+    revertDrag(): void;
+}
+//# sourceMappingURL=bubble_drag_strategy.d.ts.map

package/core/dragging/comment_drag_strategy.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @license
+ * Copyright 2024 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { RenderedWorkspaceComment } from '../comments.js';
+import { IDragStrategy } from '../interfaces/i_draggable.js';
+import { Coordinate } from '../utils.js';
+export declare class CommentDragStrategy implements IDragStrategy {
+    private comment;
+    private startLoc;
+    private workspace;
+    constructor(comment: RenderedWorkspaceComment);
+    isMovable(): boolean;
+    startDrag(): void;
+    drag(newLoc: Coordinate): void;
+    endDrag(): void;
+    /** Fire a UI event at the start of a comment drag. */
+    private fireDragStartEvent;
+    /** Fire a UI event at the end of a comment drag. */
+    private fireDragEndEvent;
+    /** Fire a move event at the end of a comment drag. */
+    private fireMoveEvent;
+    revertDrag(): void;
+}
+//# sourceMappingURL=comment_drag_strategy.d.ts.map

package/core/dragging/dragger.d.ts

@@ -0,0 +1,49 @@
+/**
+ * @license
+ * Copyright 2024 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { IDeletable } from '../interfaces/i_deletable.js';
+import { IDragTarget } from '../interfaces/i_drag_target.js';
+import { IDraggable } from '../interfaces/i_draggable.js';
+import { IDragger } from '../interfaces/i_dragger.js';
+import { Coordinate } from '../utils/coordinate.js';
+import { WorkspaceSvg } from '../workspace_svg.js';
+export declare class Dragger implements IDragger {
+    protected draggable: IDraggable;
+    protected workspace: WorkspaceSvg;
+    protected startLoc: Coordinate;
+    protected dragTarget: IDragTarget | null;
+    constructor(draggable: IDraggable, workspace: WorkspaceSvg);
+    /** Handles any drag startup. */
+    onDragStart(e: PointerEvent): void;
+    /**
+     * Handles calculating where the element should actually be moved to.
+     *
+     * @param totalDelta The total amount in pixel coordinates the mouse has moved
+     *     since the start of the drag.
+     */
+    onDrag(e: PointerEvent, totalDelta: Coordinate): void;
+    /** Updates the drag target under the pointer (if there is one). */
+    protected updateDragTarget(e: PointerEvent): void;
+    /**
+     * Calculates the correct workspace coordinate for the movable and tells
+     * the draggable to go to that location.
+     */
+    private moveDraggable;
+    /**
+     * Returns true if we would delete the draggable if it was dropped
+     * at the current location.
+     */
+    protected wouldDeleteDraggable(e: PointerEvent, rootDraggable: IDraggable & IDeletable): boolean;
+    /** Handles any drag cleanup. */
+    onDragEnd(e: PointerEvent): void;
+    private getRoot;
+    /**
+     * Returns true if we should return the draggable to its original location
+     * at the end of the drag.
+     */
+    protected shouldReturnToStart(e: PointerEvent, rootDraggable: IDraggable): boolean;
+    protected pixelsToWorkspaceUnits(pixelCoord: Coordinate): Coordinate;
+}
+//# sourceMappingURL=dragger.d.ts.map

package/core/dragging.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @license
+ * Copyright 2024 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { BlockDragStrategy } from './dragging/block_drag_strategy.js';
+import { BubbleDragStrategy } from './dragging/bubble_drag_strategy.js';
+import { CommentDragStrategy } from './dragging/comment_drag_strategy.js';
+import { Dragger } from './dragging/dragger.js';
+export { BlockDragStrategy, BubbleDragStrategy, CommentDragStrategy, Dragger };
+//# sourceMappingURL=dragging.d.ts.map