blockly 11.0.0-beta.1 → 11.0.0-beta.10

package/core/dragging/block_drag_strategy.d.ts

@@ -0,0 +1,105 @@
+/**
+ * @license
+ * Copyright 2024 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { IDragStrategy } from '../interfaces/i_draggable.js';
+import { Coordinate } from '../utils.js';
+import { BlockSvg } from '../block_svg.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;
+    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;
+    /** 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;
+    /**
+     * 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;
+    /** 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 { IDragStrategy } from '../interfaces/i_draggable.js';
+import { Coordinate } from '../utils.js';
+import { IBubble, WorkspaceSvg } from '../blockly.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,21 @@
+/**
+ * @license
+ * Copyright 2024 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { IDragStrategy } from '../interfaces/i_draggable.js';
+import { Coordinate } from '../utils.js';
+import { RenderedWorkspaceComment } from '../comments.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;
+    private fireMoveEvent;
+    revertDrag(): void;
+}
+//# sourceMappingURL=comment_drag_strategy.d.ts.map

package/core/dragging/dragger.d.ts

@@ -0,0 +1,48 @@
+/**
+ * @license
+ * Copyright 2024 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { IDragTarget } from '../interfaces/i_drag_target.js';
+import { IDeletable } from '../interfaces/i_deletable.js';
+import { IDragger } from '../interfaces/i_dragger.js';
+import { IDraggable } from '../interfaces/i_draggable.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, draggable: IDraggable & IDeletable): boolean;
+    /** Handles any drag cleanup. */
+    onDragEnd(e: PointerEvent): void;
+    /**
+     * Returns true if we should return the draggable to its original location
+     * at the end of the drag.
+     */
+    protected shouldReturnToStart(e: PointerEvent, draggable: 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 { Dragger } from './dragging/dragger.js';
+import { BlockDragStrategy } from './dragging/block_drag_strategy.js';
+import { BubbleDragStrategy } from './dragging/bubble_drag_strategy.js';
+import { CommentDragStrategy } from './dragging/comment_drag_strategy.js';
+export { Dragger, BlockDragStrategy, BubbleDragStrategy, CommentDragStrategy };
+//# sourceMappingURL=dragging.d.ts.map

package/core/events/events.d.ts

@@ -18,6 +18,7 @@ import { CommentChange, CommentChangeJson } from './events_comment_change.js';
 import { CommentCreate, CommentCreateJson } from './events_comment_create.js';
 import { CommentDelete } from './events_comment_delete.js';
 import { CommentMove, CommentMoveJson } from './events_comment_move.js';
+import { CommentCollapse, CommentCollapseJson } from './events_comment_collapse.js';
 import { MarkerMove, MarkerMoveJson } from './events_marker_move.js';
 import { Selected, SelectedJson } from './events_selected.js';
 import { ThemeChange, ThemeChangeJson } from './events_theme_change.js';
@@ -62,6 +63,8 @@ export { CommentCreateJson };
 export { CommentDelete };
 export { CommentMove };
 export { CommentMoveJson };
+export { CommentCollapse };
+export { CommentCollapseJson };
 export { FinishedLoading };
 export { MarkerMove };
 export { MarkerMoveJson };

package/core/events/events_block_change.d.ts

@@ -29,6 +29,11 @@ export declare class BlockChange extends BlockBase {
     oldValue: unknown;
     /** The new value of the element. */
     newValue: unknown;
+    /**
+     * If element is 'disabled', this is the language-neutral identifier of the
+     * reason why the block was or was not disabled.
+     */
+    private disabledReason?;
     /**
      * @param opt_block The changed block.  Undefined for a blank event.
      * @param opt_element One of 'field', 'comment', 'disabled', etc.
@@ -53,6 +58,15 @@ export declare class BlockChange extends BlockBase {
      * @internal
      */
     static fromJson(json: BlockChangeJson, workspace: Workspace, event?: any): BlockChange;
+    /**
+     * Set the language-neutral identifier for the reason why the block was or was
+     * not disabled. This is only valid for events where element is 'disabled'.
+     * Defaults to 'MANUALLY_DISABLED'.
+     *
+     * @param disabledReason The identifier of the reason why the block was or was
+     *     not disabled.
+     */
+    setDisabledReason(disabledReason: string): void;
     /**
      * Does this event record any change of state?
      *
@@ -80,5 +94,6 @@ export interface BlockChangeJson extends BlockBaseJson {
     name?: string;
     newValue: unknown;
     oldValue: unknown;
+    disabledReason?: string;
 }
 //# sourceMappingURL=events_block_change.d.ts.map

package/core/events/events_click.d.ts

@@ -13,7 +13,7 @@ import { AbstractEventJson } from './events_abstract.js';
 import { UiBase } from './events_ui_base.js';
 import { Workspace } from '../workspace.js';
 /**
- * Notifies listeners that ome blockly element was clicked.
+ * Notifies listeners that some blockly element was clicked.
  */
 export declare class Click extends UiBase {
     /** The ID of the block that was clicked, if a block was clicked. */

package/core/events/events_comment_base.d.ts

@@ -3,7 +3,12 @@
  * Copyright 2018 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import type { WorkspaceComment } from '../workspace_comment.js';
+/**
+ * Base class for comment events.
+ *
+ * @class
+ */
+import type { WorkspaceComment } from '../comments/workspace_comment.js';
 import { Abstract as AbstractEvent, AbstractEventJson } from './events_abstract.js';
 import type { CommentCreate } from './events_comment_create.js';
 import type { CommentDelete } from './events_comment_delete.js';

package/core/events/events_comment_change.d.ts

@@ -3,7 +3,7 @@
  * Copyright 2018 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import type { WorkspaceComment } from '../workspace_comment.js';
+import type { WorkspaceComment } from '../comments/workspace_comment.js';
 import { CommentBase, CommentBaseJson } from './events_comment_base.js';
 import type { Workspace } from '../workspace.js';
 /**

package/core/events/events_comment_collapse.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @license
+ * Copyright 2024 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { WorkspaceComment } from '../comments/workspace_comment.js';
+import { CommentBase, CommentBaseJson } from './events_comment_base.js';
+import type { Workspace } from '../workspace.js';
+export declare class CommentCollapse extends CommentBase {
+    newCollapsed?: boolean | undefined;
+    type: string;
+    constructor(comment?: WorkspaceComment, newCollapsed?: boolean | undefined);
+    /**
+     * Encode the event as JSON.
+     *
+     * @returns JSON representation.
+     */
+    toJson(): CommentCollapseJson;
+    /**
+     * Deserializes the JSON event.
+     *
+     * @param event The event to append new properties to. Should be a subclass
+     *     of CommentCollapse, but we can't specify that due to the fact that
+     *     parameters to static methods in subclasses must be supertypes of
+     *     parameters to static methods in superclasses.
+     * @internal
+     */
+    static fromJson(json: CommentCollapseJson, workspace: Workspace, event?: any): CommentCollapse;
+    /**
+     * Run a collapse event.
+     *
+     * @param forward True if run forward, false if run backward (undo).
+     */
+    run(forward: boolean): void;
+}
+export interface CommentCollapseJson extends CommentBaseJson {
+    newCollapsed: boolean;
+}
+//# sourceMappingURL=events_comment_collapse.d.ts.map

package/core/events/events_comment_create.d.ts

@@ -3,7 +3,8 @@
  * Copyright 2018 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import type { WorkspaceComment } from '../workspace_comment.js';
+import type { WorkspaceComment } from '../comments/workspace_comment.js';
+import * as comments from '../serialization/workspace_comments.js';
 import { CommentBase, CommentBaseJson } from './events_comment_base.js';
 import type { Workspace } from '../workspace.js';
 /**
@@ -13,6 +14,8 @@ export declare class CommentCreate extends CommentBase {
     type: string;
     /** The XML representation of the created workspace comment. */
     xml?: Element | DocumentFragment;
+    /** The JSON representation of the created workspace comment. */
+    json?: comments.State;
     /**
      * @param opt_comment The created comment.
      *     Undefined for a blank event.
@@ -43,5 +46,6 @@ export declare class CommentCreate extends CommentBase {
 }
 export interface CommentCreateJson extends CommentBaseJson {
     xml: string;
+    json: object;
 }
 //# sourceMappingURL=events_comment_create.d.ts.map

package/core/events/events_comment_delete.d.ts

@@ -3,7 +3,8 @@
  * Copyright 2018 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import type { WorkspaceComment } from '../workspace_comment.js';
+import type { WorkspaceComment } from '../comments/workspace_comment.js';
+import * as comments from '../serialization/workspace_comments.js';
 import { CommentBase, CommentBaseJson } from './events_comment_base.js';
 import type { Workspace } from '../workspace.js';
 /**
@@ -13,6 +14,8 @@ export declare class CommentDelete extends CommentBase {
     type: string;
     /** The XML representation of the deleted workspace comment. */
     xml?: Element;
+    /** The JSON representation of the created workspace comment. */
+    json?: comments.State;
     /**
      * @param opt_comment The deleted comment.
      *     Undefined for a blank event.
@@ -43,5 +46,6 @@ export declare class CommentDelete extends CommentBase {
 }
 export interface CommentDeleteJson extends CommentBaseJson {
     xml: string;
+    json: object;
 }
 //# sourceMappingURL=events_comment_delete.d.ts.map

package/core/events/events_comment_move.d.ts

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import { Coordinate } from '../utils/coordinate.js';
-import type { WorkspaceComment } from '../workspace_comment.js';
+import type { WorkspaceComment } from '../comments/workspace_comment.js';
 import { CommentBase, CommentBaseJson } from './events_comment_base.js';
 import type { Workspace } from '../workspace.js';
 /**
@@ -18,6 +18,16 @@ export declare class CommentMove extends CommentBase {
     oldCoordinate_?: Coordinate;
     /** The location of the comment after the move, in workspace coordinates. */
     newCoordinate_?: Coordinate;
+    /**
+     * An explanation of what this move is for.  Known values include:
+     *  'drag' -- A drag operation completed.
+     *  'snap' -- Comment got shifted to line up with the grid.
+     *  'inbounds' -- Block got pushed back into a non-scrolling workspace.
+     *  'create' -- Block created via deserialization.
+     *  'cleanup' -- Workspace aligned top-level blocks.
+     * Event merging may create multiple reasons: ['drag', 'inbounds', 'snap'].
+     */
+    reason?: string[];
     /**
      * @param opt_comment The comment that is being moved.  Undefined for a blank
      *     event.
@@ -28,6 +38,12 @@ export declare class CommentMove extends CommentBase {
      * called once.
      */
     recordNew(): void;
+    /**
+     * Sets the reason for a move event.
+     *
+     * @param reason Why is this move happening?  'drag', 'bump', 'snap', ...
+     */
+    setReason(reason: string[]): void;
     /**
      * Override the location before the move.  Use this if you don't create the
      * event until the end of the move, but you know the original location.

package/core/events/utils.d.ts

@@ -127,6 +127,8 @@ export declare const COMMENT_CHANGE = "comment_change";
  * Name of event that moves a comment.
  */
 export declare const COMMENT_MOVE = "comment_move";
+/** Type of event that moves a comment. */
+export declare const COMMENT_COLLAPSE = "comment_collapse";
 /**
  * Name of event that records a workspace load.
  */
@@ -229,10 +231,8 @@ export declare function fromJson(json: any, workspace: Workspace): Abstract;
  */
 export declare function get(eventType: string): new (...p1: any[]) => Abstract;
 /**
- * Enable/disable a block depending on whether it is properly connected.
+ * Set if a block is disabled depending on whether it is properly connected.
  * Use this on applications where all blocks should be connected to a top block.
- * Recommend setting the 'disable' option to 'false' in the config so that
- * users don't try to re-enable disabled orphan blocks.
  *
  * @param event Custom data for event.
  */

package/core/field_dropdown.d.ts

@@ -148,6 +148,7 @@ export declare class FieldDropdown extends Field<string> {
      * @param newValue The input value.
      * @returns A valid language-neutral option, or null if invalid.
      */
+    protected doClassValidation_(newValue: string): string | null | undefined;
     protected doClassValidation_(newValue?: string): string | null;
     /**
      * Update the value of this dropdown field.

package/core/field_image.d.ts

@@ -134,7 +134,7 @@ export interface FieldImageConfig extends FieldConfig {
     alt?: string;
 }
 /**
- * fromJson config options for the colour field.
+ * fromJson config options for the image field.
  */
 export interface FieldImageFromJsonConfig extends FieldImageConfig {
     src?: string;

package/core/flyout_base.d.ts

@@ -3,7 +3,7 @@
  * Copyright 2011 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import type { BlockSvg } from './block_svg.js';
+import { BlockSvg } from './block_svg.js';
 import { DeleteArea } from './delete_area.js';
 import { FlyoutButton } from './flyout_button.js';
 import type { IFlyout } from './interfaces/i_flyout.js';
@@ -119,6 +119,10 @@ export declare abstract class Flyout extends DeleteArea implements IAutoHideable
      * List of visible buttons.
      */
     protected buttons_: FlyoutButton[];
+    /**
+     * List of visible buttons and blocks.
+     */
+    protected contents: FlyoutItem[];
     /**
      * List of event listeners.
      */
@@ -279,6 +283,18 @@ export declare abstract class Flyout extends DeleteArea implements IAutoHideable
      * @param visible Whether the container is visible.
      */
     setContainerVisible(visible: boolean): void;
+    /**
+     * Get the list of buttons and blocks of the current flyout.
+     *
+     * @returns The array of flyout buttons and blocks.
+     */
+    getContents(): FlyoutItem[];
+    /**
+     * Store the list of buttons and blocks on the flyout.
+     *
+     * @param contents - The array of items for the flyout.
+     */
+    setContents(contents: FlyoutItem[]): void;
     /**
      * Update the display property of the flyout based whether it thinks it should
      * be visible and whether its containing workspace is visible.

package/core/flyout_button.d.ts

@@ -6,10 +6,11 @@
 import { Coordinate } from './utils/coordinate.js';
 import type * as toolbox from './utils/toolbox.js';
 import type { WorkspaceSvg } from './workspace_svg.js';
+import type { IASTNodeLocationSvg } from './blockly.js';
 /**
  * Class for a button or label in the flyout.
  */
-export declare class FlyoutButton {
+export declare class FlyoutButton implements IASTNodeLocationSvg {
     private readonly workspace;
     private readonly targetWorkspace;
     private readonly isLabel_;
@@ -34,6 +35,11 @@ export declare class FlyoutButton {
     private svgGroup;
     /** The SVG element with the text of the label or button. */
     private svgText;
+    /**
+     * Holds the cursors svg element when the cursor is attached to the button.
+     * This is null if there is no cursor on the button.
+     */
+    cursorSvg: SVGElement | null;
     /**
      * @param workspace The workspace in which to place this button.
      * @param targetWorkspace The flyout's target workspace.
@@ -76,8 +82,27 @@ export declare class FlyoutButton {
      * @returns The target workspace of the flyout where this button resides.
      */
     getTargetWorkspace(): WorkspaceSvg;
+    /**
+     * Get the button's workspace.
+     *
+     * @returns The workspace in which to place this button.
+     */
+    getWorkspace(): WorkspaceSvg;
     /** Dispose of this button. */
     dispose(): void;
+    /**
+     * Add the cursor SVG to this buttons's SVG group.
+     *
+     * @param cursorSvg The SVG root of the cursor to be added to the button SVG
+     *     group.
+     */
+    setCursorSvg(cursorSvg: SVGElement): void;
+    /**
+     * Required by IASTNodeLocationSvg, but not used. A marker cannot be set on a
+     * button. If the 'mark' shortcut is used on a button, its associated callback
+     * function is triggered.
+     */
+    setMarkerSvg(): void;
     /**
      * Do something when the button is clicked.
      *

package/core/generator.d.ts

@@ -254,7 +254,7 @@ export declare class CodeGenerator {
      * @param _opt_thisOnly True to generate code for only this statement.
      * @returns Code with comments and subsequent blocks added.
      */
-    protected scrub_(_block: Block, code: string, _opt_thisOnly?: boolean): string;
+    scrub_(_block: Block, code: string, _opt_thisOnly?: boolean): string;
     /**
      * Hook for code to run at end of code generation.
      * Subclasses may override this, e.g. to prepend the generated code with