blockly 9.3.0-beta.0 → 9.3.0

package/core/any_aliases.d.ts

@@ -1,2 +1,7 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
 type any = any;
 //# sourceMappingURL=any_aliases.d.ts.map

package/core/block.d.ts

@@ -22,8 +22,6 @@ import type { Workspace } from './workspace.js';
 /**
  * Class for one block.
  * Not normally called directly, workspace.newBlock() is preferred.
- *
- * @alias Blockly.Block
  */
 export declare class Block implements IASTNodeLocation, IDeletable {
     /**
@@ -31,7 +29,7 @@ export declare class Block implements IASTNodeLocation, IDeletable {
      * changes. This is usually only called from the constructor, the block type
      * initializer function, or an extension initializer function.
      */
-    onchange?: ((p1: Abstract) => any) | null;
+    onchange?: ((p1: Abstract) => void) | null;
     /** The language-neutral ID given to the collapsed input. */
     static readonly COLLAPSED_INPUT_NAME: string;
     /** The language-neutral ID given to the collapsed field. */
@@ -57,7 +55,7 @@ export declare class Block implements IASTNodeLocation, IDeletable {
     /** Name of the block style. */
     protected styleName_: string;
     /** An optional method called during initialization. */
-    init?: (() => any) | null;
+    init?: (() => void);
     /** An optional method called during disposal. */
     destroy?: (() => void);
     /**
@@ -65,25 +63,25 @@ export declare class Block implements IASTNodeLocation, IDeletable {
      * mutation state to XML. This must be coupled with defining
      * `domToMutation`.
      */
-    mutationToDom?: ((...p1: any[]) => Element) | null;
+    mutationToDom?: (...p1: any[]) => Element;
     /**
      * An optional deserialization method for defining how to deserialize the
      * mutation state from XML. This must be coupled with defining
      * `mutationToDom`.
      */
-    domToMutation?: ((p1: Element) => any) | null;
+    domToMutation?: (p1: Element) => void;
     /**
      * An optional serialization method for defining how to serialize the
      * block's extra state (eg mutation state) to something JSON compatible.
      * This must be coupled with defining `loadExtraState`.
      */
-    saveExtraState?: (() => any) | null;
+    saveExtraState?: () => any;
     /**
      * An optional serialization method for defining how to deserialize the
      * block's extra state (eg mutation state) from something JSON compatible.
      * This must be coupled with defining `saveExtraState`.
      */
-    loadExtraState?: ((p1: any) => any) | null;
+    loadExtraState?: (p1: any) => void;
     /**
      * An optional property for suppressing adding STATEMENT_PREFIX and
      * STATEMENT_SUFFIX to generated code.
@@ -95,21 +93,21 @@ export declare class Block implements IASTNodeLocation, IDeletable {
      * shown to the user, but are declared as global variables in the generated
      * code.
      */
-    getDeveloperVariables?: (() => string[]);
+    getDeveloperVariables?: () => string[];
     /**
      * An optional function that reconfigures the block based on the contents of
      * the mutator dialog.
      */
-    compose?: ((p1: Block) => void);
+    compose?: (p1: Block) => void;
     /**
      * An optional function that populates the mutator's dialog with
      * this block's components.
      */
-    decompose?: ((p1: Workspace) => Block);
+    decompose?: (p1: Workspace) => Block;
     id: string;
-    outputConnection: Connection;
-    nextConnection: Connection;
-    previousConnection: Connection;
+    outputConnection: Connection | null;
+    nextConnection: Connection | null;
+    previousConnection: Connection | null;
     inputList: Input[];
     inputsInline?: boolean;
     private disabled;
@@ -147,7 +145,7 @@ export declare class Block implements IASTNodeLocation, IDeletable {
     /**
      * String for block help, or function that returns a URL. Null for no help.
      */
-    helpUrl: string | Function;
+    helpUrl: string | Function | null;
     /** A bound callback function to use when the parent workspace changes. */
     private onchangeWrapper_;
     /**
@@ -179,6 +177,11 @@ export declare class Block implements IASTNodeLocation, IDeletable {
      * @suppress {checkTypes}
      */
     dispose(healStack: boolean): void;
+    /**
+     * Disposes of this block without doing things required by the top block.
+     * E.g. does not fire events, unplug the block, etc.
+     */
+    protected disposeInternal(): void;
     /**
      * Returns true if the block is either in the process of being disposed, or
      * is disposed.
@@ -348,6 +351,12 @@ export declare class Block implements IASTNodeLocation, IDeletable {
      * @returns True if deletable.
      */
     isDeletable(): boolean;
+    /**
+     * Return whether this block's own deletable property is true or false.
+     *
+     * @returns True if the block's deletable property is true, false otherwise.
+     */
+    isOwnDeletable(): boolean;
     /**
      * Set whether this block is deletable or not.
      *
@@ -358,8 +367,16 @@ export declare class Block implements IASTNodeLocation, IDeletable {
      * Get whether this block is movable or not.
      *
      * @returns True if movable.
+     * @internal
      */
     isMovable(): boolean;
+    /**
+     * Return whether this block's own movable property is true or false.
+     *
+     * @returns True if the block's movable property is true, false otherwise.
+     * @internal
+     */
+    isOwnMovable(): boolean;
     /**
      * Set whether this block is movable or not.
      *
@@ -406,8 +423,15 @@ export declare class Block implements IASTNodeLocation, IDeletable {
      * Get whether this block is editable or not.
      *
      * @returns True if editable.
+     * @internal
      */
     isEditable(): boolean;
+    /**
+     * Return whether this block's own editable property is true or false.
+     *
+     * @returns True if the block's editable property is true, false otherwise.
+     */
+    isOwnEditable(): boolean;
     /**
      * Set whether this block is editable or not.
      *
@@ -492,7 +516,7 @@ export declare class Block implements IASTNodeLocation, IDeletable {
      * @param onchangeFn The callback to call when the block's workspace changes.
      * @throws {Error} if onchangeFn is not falsey and not a function.
      */
-    setOnChange(onchangeFn: (p1: Abstract) => any): void;
+    setOnChange(onchangeFn: (p1: Abstract) => void): void;
     /**
      * Returns the named field from a block.
      *
@@ -627,11 +651,19 @@ export declare class Block implements IASTNodeLocation, IDeletable {
      * Create a human-readable text representation of this block and any children.
      *
      * @param opt_maxLength Truncate the string to this length.
-     * @param opt_emptyToken The placeholder string used to denote an empty field.
+     * @param opt_emptyToken The placeholder string used to denote an empty input.
      *     If not specified, '?' is used.
      * @returns Text of block.
      */
     toString(opt_maxLength?: number, opt_emptyToken?: string): string;
+    /**
+     * Converts this block into string tokens.
+     *
+     * @param emptyToken The token to use in place of an empty input.
+     *     Defaults to '?'.
+     * @returns The array of string tokens representing this block.
+     */
+    private toTokens;
     /**
      * Shortcut for appending a value input row.
      *

package/core/block_animations.d.ts

@@ -8,7 +8,6 @@ import type { BlockSvg } from './block_svg.js';
  * Play some UI effects (sound, animation) when disposing of a block.
  *
  * @param block The block being disposed of.
- * @alias Blockly.blockAnimations.disposeUiEffect
  * @internal
  */
 export declare function disposeUiEffect(block: BlockSvg): void;
@@ -16,7 +15,6 @@ export declare function disposeUiEffect(block: BlockSvg): void;
  * Play some UI effects (sound, ripple) after a connection has been established.
  *
  * @param block The block being connected.
- * @alias Blockly.blockAnimations.connectionUiEffect
  * @internal
  */
 export declare function connectionUiEffect(block: BlockSvg): void;
@@ -24,14 +22,12 @@ export declare function connectionUiEffect(block: BlockSvg): void;
  * Play some UI effects (sound, animation) when disconnecting a block.
  *
  * @param block The block being disconnected.
- * @alias Blockly.blockAnimations.disconnectUiEffect
  * @internal
  */
 export declare function disconnectUiEffect(block: BlockSvg): void;
 /**
  * Stop the disconnect UI animation immediately.
  *
- * @alias Blockly.blockAnimations.disconnectUiStop
  * @internal
  */
 export declare function disconnectUiStop(): void;

package/core/block_drag_surface.d.ts

@@ -0,0 +1,135 @@
+/**
+ * @license
+ * Copyright 2016 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Coordinate } from './utils/coordinate.js';
+/**
+ * Class for a drag surface for the currently dragged block. This is a separate
+ * SVG that contains only the currently moving block, or nothing.
+ *
+ * @alias Blockly.BlockDragSurfaceSvg
+ */
+export declare class BlockDragSurfaceSvg {
+    private readonly container;
+    /**
+     * The root element of the drag surface.
+     */
+    private svg;
+    /**
+     * This is where blocks live while they are being dragged if the drag
+     * surface is enabled.
+     */
+    private dragGroup;
+    /**
+     * Cached value for the scale of the drag surface.
+     * Used to set/get the correct translation during and after a drag.
+     */
+    private scale;
+    /**
+     * Cached value for the translation of the drag surface.
+     * This translation is in pixel units, because the scale is applied to the
+     * drag group rather than the top-level SVG.
+     */
+    private surfaceXY;
+    /**
+     * Cached value for the translation of the child drag surface in pixel
+     * units. Since the child drag surface tracks the translation of the
+     * workspace this is ultimately the translation of the workspace.
+     */
+    private readonly childSurfaceXY;
+    /** @param container Containing element. */
+    constructor(container: Element);
+    /**
+     * Create the drag surface and inject it into the container.
+     *
+     * @deprecated The DOM is automatically created by the constructor.
+     */
+    createDom(): void;
+    /**
+     * Set the SVG blocks on the drag surface's group and show the surface.
+     * Only one block group should be on the drag surface at a time.
+     *
+     * @param blocks Block or group of blocks to place on the drag surface.
+     */
+    setBlocksAndShow(blocks: SVGElement): void;
+    /**
+     * Translate and scale the entire drag surface group to the given position, to
+     * keep in sync with the workspace.
+     *
+     * @param x X translation in pixel coordinates.
+     * @param y Y translation in pixel coordinates.
+     * @param scale Scale of the group.
+     */
+    translateAndScaleGroup(x: number, y: number, scale: number): void;
+    /**
+     * Translate the drag surface's SVG based on its internal state.
+     *
+     * @internal
+     */
+    translateSurfaceInternal_(): void;
+    /**
+     * Translates the entire surface by a relative offset.
+     *
+     * @param deltaX Horizontal offset in pixel units.
+     * @param deltaY Vertical offset in pixel units.
+     */
+    translateBy(deltaX: number, deltaY: number): void;
+    /**
+     * Translate the entire drag surface during a drag.
+     * We translate the drag surface instead of the blocks inside the surface
+     * so that the browser avoids repainting the SVG.
+     * Because of this, the drag coordinates must be adjusted by scale.
+     *
+     * @param x X translation for the entire surface.
+     * @param y Y translation for the entire surface.
+     */
+    translateSurface(x: number, y: number): void;
+    /**
+     * Reports the surface translation in scaled workspace coordinates.
+     * Use this when finishing a drag to return blocks to the correct position.
+     *
+     * @returns Current translation of the surface.
+     */
+    getSurfaceTranslation(): Coordinate;
+    /**
+     * Provide a reference to the drag group (primarily for
+     * BlockSvg.getRelativeToSurfaceXY).
+     *
+     * @returns Drag surface group element.
+     */
+    getGroup(): SVGElement;
+    /**
+     * Returns the SVG drag surface.
+     *
+     * @returns The SVG drag surface.
+     */
+    getSvgRoot(): SVGElement;
+    /**
+     * Get the current blocks on the drag surface, if any (primarily
+     * for BlockSvg.getRelativeToSurfaceXY).
+     *
+     * @returns Drag surface block DOM element, or null if no blocks exist.
+     */
+    getCurrentBlock(): Element | null;
+    /**
+     * Gets the translation of the child block surface
+     * This surface is in charge of keeping track of how much the workspace has
+     * moved.
+     *
+     * @returns The amount the workspace has been moved.
+     */
+    getWsTranslation(): Coordinate;
+    /**
+     * Clear the group and hide the surface; move the blocks off onto the provided
+     * element.
+     * If the block is being deleted it doesn't need to go back to the original
+     * surface, since it would be removed immediately during dispose.
+     *
+     * @param opt_newSurface Surface the dragging blocks should be moved to, or
+     *     null if the blocks should be removed from this surface without being
+     *     moved to a different surface.
+     */
+    clearAndHide(opt_newSurface?: Element): void;
+}
+//# sourceMappingURL=block_drag_surface.d.ts.map

package/core/block_dragger.d.ts

@@ -13,8 +13,6 @@ import type { WorkspaceSvg } from './workspace_svg.js';
 /**
  * Class for a block dragger.  It moves blocks around the workspace when they
  * are being dragged by a mouse or touch.
- *
- * @alias Blockly.BlockDragger
  */
 export declare class BlockDragger implements IBlockDragger {
     /** The top block in the stack that is being dragged. */
@@ -40,7 +38,7 @@ export declare class BlockDragger implements IBlockDragger {
      */
     dispose(): void;
     /**
-     * Start dragging a block.
+     * Start dragging a block.  This includes moving it to the drag surface.
      *
      * @param currentDragDeltaXY How far the pointer has moved from the position
      *     at mouse down, in pixel units.
@@ -103,11 +101,8 @@ export declare class BlockDragger implements IBlockDragger {
     protected maybeDeleteBlock_(): boolean;
     /**
      * Updates the necessary information to place a block at a certain location.
-     *
-     * @param delta The change in location from where the block started the drag
-     *     to where it ended the drag.
      */
-    protected updateBlockAfterMove_(delta: Coordinate): void;
+    protected updateBlockAfterMove_(): void;
     /** Fire a UI event at the end of a block drag. */
     protected fireDragEndEvent_(): void;
     /**

package/core/block_svg.d.ts

@@ -28,8 +28,6 @@ import type { WorkspaceSvg } from './workspace_svg.js';
 /**
  * Class for a block's SVG representation.
  * Not normally called directly, workspace.newBlock() is preferred.
- *
- * @alias Blockly.BlockSvg
  */
 export declare class BlockSvg extends Block implements IASTNodeLocationSvg, IBoundedElement, ICopyable, IDraggable {
     /**
@@ -43,9 +41,9 @@ export declare class BlockSvg extends Block implements IASTNodeLocationSvg, IBou
      * the block.
      */
     static readonly COLLAPSED_WARNING_ID = "TEMP_COLLAPSED_WARNING_";
-    decompose?: ((p1: Workspace) => BlockSvg);
-    saveConnections?: ((p1: BlockSvg) => any);
-    customContextMenu?: ((p1: Array<ContextMenuOption | LegacyContextMenuOption>) => any) | null;
+    decompose?: (p1: Workspace) => BlockSvg;
+    saveConnections?: (p1: BlockSvg) => void;
+    customContextMenu?: (p1: Array<ContextMenuOption | LegacyContextMenuOption>) => void;
     /**
      * An property used internally to reference the block's rendering debugger.
      *
@@ -78,6 +76,7 @@ export declare class BlockSvg extends Block implements IASTNodeLocationSvg, IBou
     /** @internal */
     pathObject: IPathObject;
     rendered: boolean;
+    private visuallyDisabled;
     /**
      * Is this block currently rendering? Used to stop recursive render calls
      * from actually triggering a re-render.
@@ -89,7 +88,21 @@ export declare class BlockSvg extends Block implements IASTNodeLocationSvg, IBou
     outputConnection: RenderedConnection;
     nextConnection: RenderedConnection;
     previousConnection: RenderedConnection;
+    private readonly useDragSurface_;
     private translation;
+    /**
+     * The ID of the setTimeout callback for bumping neighbours, or 0 if no bump
+     * is currently scheduled.
+     */
+    private bumpNeighboursPid;
+    /**
+     * The location of the top left of this block (in workspace coordinates)
+     * relative to either its parent block, or the workspace origin if it has no
+     * parent.
+     *
+     * @internal
+     */
+    relativeCoords: Coordinate;
     /**
      * @param workspace The block's workspace.
      * @param prototypeName Name of the language object containing type-specific
@@ -169,6 +182,14 @@ export declare class BlockSvg extends Block implements IASTNodeLocationSvg, IBou
      * @internal
      */
     getTranslation(): string;
+    /**
+     * Move this block to its workspace's drag surface, accounting for
+     * positioning. Generally should be called at the same time as
+     * setDragging_(true). Does nothing if useDragSurface_ is false.
+     *
+     * @internal
+     */
+    moveToDragSurface(): void;
     /**
      * Move a block to a position.
      *
@@ -176,7 +197,18 @@ export declare class BlockSvg extends Block implements IASTNodeLocationSvg, IBou
      */
     moveTo(xy: Coordinate): void;
     /**
-     * Move this block during a drag.
+     * Move this block back to the workspace block canvas.
+     * Generally should be called at the same time as setDragging_(false).
+     * Does nothing if useDragSurface_ is false.
+     *
+     * @param newXY The position the block should take on on the workspace canvas,
+     *     in workspace coordinates.
+     * @internal
+     */
+    moveOffDragSurface(newXY: Coordinate): void;
+    /**
+     * Move this block during a drag, taking into account whether we are using a
+     * drag surface to translate blocks.
      * This block must be a top-level block.
      *
      * @param newLoc The location to translate to, in workspace coordinates.
@@ -306,6 +338,11 @@ export declare class BlockSvg extends Block implements IASTNodeLocationSvg, IBou
      * @suppress {checkTypes}
      */
     dispose(healStack?: boolean, animate?: boolean): void;
+    /**
+     * Disposes of this block without doing things required by the top block.
+     * E.g. does trigger UI effects, remove nodes, etc.
+     */
+    disposeInternal(): void;
     /**
      * Delete a block and hide chaff when doing so. The block will not be deleted
      * if it's in a flyout. This is called from the context menu and keyboard
@@ -495,7 +532,7 @@ export declare class BlockSvg extends Block implements IASTNodeLocationSvg, IBou
      *
      * @param all If true, return all connections even hidden ones.
      *     Otherwise, for a non-rendered block return an empty list, and for a
-     * collapsed block don't return inputs connections.
+     *     collapsed block don't return inputs connections.
      * @returns Array of connections.
      * @internal
      */
@@ -586,20 +623,46 @@ export declare class BlockSvg extends Block implements IASTNodeLocationSvg, IBou
      */
     getChildren(ordered: boolean): BlockSvg[];
     /**
-     * Lays out and reflows a block based on its contents and settings.
+     * Triggers a rerender after a delay to allow for batching.
+     *
+     * @internal
+     */
+    queueRender(): void;
+    /**
+     * Immediately lays out and reflows a block based on its contents and
+     * settings.
      *
      * @param opt_bubble If false, just render this block.
      *   If true, also render block's parent, grandparent, etc.  Defaults to true.
      */
     render(opt_bubble?: boolean): void;
+    /**
+     * Renders this block in a way that's compatible with the more efficient
+     * render management system.
+     *
+     * @internal
+     */
+    renderEfficiently(): void;
+    /**
+     * Tightens all children of this block so they are snuggly rendered against
+     * their parent connections.
+     *
+     * Does not update connection locations, so that they can be updated more
+     * efficiently by the render management system.
+     *
+     * @internal
+     */
+    tightenChildrenEfficiently(): void;
     /** Redraw any attached marker or cursor svgs if needed. */
     protected updateMarkers_(): void;
     /**
      * Update all of the connections on this block with the new locations
      * calculated during rendering.  Also move all of the connected blocks based
      * on the new connection locations.
+     *
+     * @internal
      */
-    private updateConnectionLocations_;
+    updateConnectionLocations(): void;
     /**
      * Add the cursor SVG to this block's SVG group.
      *