blockly 12.4.0 → 12.5.0

package/core/events/events_block_field_intermediate_change.d.ts

@@ -0,0 +1,71 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Class for an event representing an intermediate change to a block's field's
+ * value.
+ *
+ * @class
+ */
+import type { Block } from '../block.js';
+import { Workspace } from '../workspace.js';
+import { BlockBase, BlockBaseJson } from './events_block_base.js';
+import { EventType } from './type.js';
+/**
+ * Notifies listeners when the value of a block's field has changed but the
+ * change is not yet complete, and is expected to be followed by a block change
+ * event.
+ */
+export declare class BlockFieldIntermediateChange extends BlockBase {
+    type: EventType;
+    recordUndo: boolean;
+    /** The name of the field that changed. */
+    name?: string;
+    /** The original value of the element. */
+    oldValue: unknown;
+    /** The new value of the element. */
+    newValue: unknown;
+    /**
+     * @param opt_block The changed block. Undefined for a blank event.
+     * @param opt_name Name of the field affected.
+     * @param opt_oldValue Previous value of element.
+     * @param opt_newValue New value of element.
+     */
+    constructor(opt_block?: Block, opt_name?: string, opt_oldValue?: unknown, opt_newValue?: unknown);
+    /**
+     * Encode the event as JSON.
+     *
+     * @returns JSON representation.
+     */
+    toJson(): BlockFieldIntermediateChangeJson;
+    /**
+     * Deserializes the JSON event.
+     *
+     * @param event The event to append new properties to. Should be a subclass
+     *     of BlockFieldIntermediateChange, 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: BlockFieldIntermediateChangeJson, workspace: Workspace, event?: any): BlockFieldIntermediateChange;
+    /**
+     * Does this event record any change of state?
+     *
+     * @returns False if something changed.
+     */
+    isNull(): boolean;
+    /**
+     * Run a change event.
+     *
+     * @param forward True if run forward, false if run backward (undo).
+     */
+    run(forward: boolean): void;
+}
+export interface BlockFieldIntermediateChangeJson extends BlockBaseJson {
+    name: string;
+    newValue: unknown;
+    oldValue: unknown;
+}
+//# sourceMappingURL=events_block_field_intermediate_change.d.ts.map

package/core/events/events_block_move.d.ts

@@ -0,0 +1,115 @@
+/**
+ * @license
+ * Copyright 2018 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Class for a block move event.
+ *
+ * @class
+ */
+import type { Block } from '../block.js';
+import { Coordinate } from '../utils/coordinate.js';
+import type { Workspace } from '../workspace.js';
+import { BlockBase, BlockBaseJson } from './events_block_base.js';
+import { EventType } from './type.js';
+/**
+ * Notifies listeners when a block is moved. This could be from one
+ * connection to another, or from one location on the workspace to another.
+ */
+export declare class BlockMove extends BlockBase {
+    type: EventType;
+    /** The ID of the old parent block. Undefined if it was a top-level block. */
+    oldParentId?: string;
+    /**
+     * The name of the old input. Undefined if it was a top-level block or the
+     * parent's next block.
+     */
+    oldInputName?: string;
+    /**
+     * The old X and Y workspace coordinates of the block if it was a top level
+     * block. Undefined if it was not a top level block.
+     */
+    oldCoordinate?: Coordinate;
+    /** The ID of the new parent block. Undefined if it is a top-level block. */
+    newParentId?: string;
+    /**
+     * The name of the new input. Undefined if it is a top-level block or the
+     * parent's next block.
+     */
+    newInputName?: string;
+    /**
+     * The new X and Y workspace coordinates of the block if it is a top-level
+     * block. Undefined if it is not a top level block.
+     */
+    newCoordinate?: Coordinate;
+    /**
+     * An explanation of what this move is for.  Known values include:
+     *  'drag' -- A drag operation completed.
+     *  'bump' -- Block got bumped away from an invalid connection.
+     *  'snap' -- Block got shifted to line up with the grid.
+     *  'inbounds' -- Block got pushed back into a non-scrolling workspace.
+     *  'connect' -- Block got connected to another block.
+     *  'disconnect' -- Block got disconnected from another block.
+     *  'create' -- Block created via XML.
+     *  'cleanup' -- Workspace aligned top-level blocks.
+     * Event merging may create multiple reasons: ['drag', 'bump', 'snap'].
+     */
+    reason?: string[];
+    /** @param opt_block The moved block.  Undefined for a blank event. */
+    constructor(opt_block?: Block);
+    /**
+     * Encode the event as JSON.
+     *
+     * @returns JSON representation.
+     */
+    toJson(): BlockMoveJson;
+    /**
+     * Deserializes the JSON event.
+     *
+     * @param event The event to append new properties to. Should be a subclass
+     *     of BlockMove, 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: BlockMoveJson, workspace: Workspace, event?: any): BlockMove;
+    /** Record the block's new location.  Called after the move. */
+    recordNew(): void;
+    /**
+     * Set the reason for a move event.
+     *
+     * @param reason Why is this move happening?  'drag', 'bump', 'snap', ...
+     */
+    setReason(reason: string[]): void;
+    /**
+     * Returns the parentId and input if the block is connected,
+     *   or the XY location if disconnected.
+     *
+     * @returns Collection of location info.
+     */
+    private currentLocation;
+    /**
+     * Does this event record any change of state?
+     *
+     * @returns False if something changed.
+     */
+    isNull(): boolean;
+    /**
+     * Run a move event.
+     *
+     * @param forward True if run forward, false if run backward (undo).
+     */
+    run(forward: boolean): void;
+}
+export interface BlockMoveJson extends BlockBaseJson {
+    oldParentId?: string;
+    oldInputName?: string;
+    oldCoordinate?: string;
+    newParentId?: string;
+    newInputName?: string;
+    newCoordinate?: string;
+    reason?: string[];
+    recordUndo?: boolean;
+}
+//# sourceMappingURL=events_block_move.d.ts.map

package/core/events/events_bubble_open.d.ts

@@ -0,0 +1,62 @@
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Events fired as a result of bubble open.
+ *
+ * @class
+ */
+import type { BlockSvg } from '../block_svg.js';
+import type { Workspace } from '../workspace.js';
+import type { AbstractEventJson } from './events_abstract.js';
+import { UiBase } from './events_ui_base.js';
+import { EventType } from './type.js';
+/**
+ * Class for a bubble open event.
+ */
+export declare class BubbleOpen extends UiBase {
+    /** The ID of the block the bubble is attached to. */
+    blockId?: string;
+    /** True if the bubble is opening, false if closing. */
+    isOpen?: boolean;
+    /** The type of bubble; one of 'mutator', 'comment', or 'warning'. */
+    bubbleType?: BubbleType;
+    type: EventType;
+    /**
+     * @param opt_block The associated block. Undefined for a blank event.
+     * @param opt_isOpen Whether the bubble is opening (false if closing).
+     *     Undefined for a blank event.
+     * @param opt_bubbleType The type of bubble. One of 'mutator', 'comment' or
+     *     'warning'. Undefined for a blank event.
+     */
+    constructor(opt_block?: BlockSvg, opt_isOpen?: boolean, opt_bubbleType?: BubbleType);
+    /**
+     * Encode the event as JSON.
+     *
+     * @returns JSON representation.
+     */
+    toJson(): BubbleOpenJson;
+    /**
+     * Deserializes the JSON event.
+     *
+     * @param event The event to append new properties to. Should be a subclass
+     *     of BubbleOpen, 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: BubbleOpenJson, workspace: Workspace, event?: any): BubbleOpen;
+}
+export declare enum BubbleType {
+    MUTATOR = "mutator",
+    COMMENT = "comment",
+    WARNING = "warning"
+}
+export interface BubbleOpenJson extends AbstractEventJson {
+    isOpen: boolean;
+    bubbleType: BubbleType;
+    blockId: string;
+}
+//# sourceMappingURL=events_bubble_open.d.ts.map

package/core/events/events_click.d.ts

@@ -0,0 +1,64 @@
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Events fired as a result of UI click in Blockly's editor.
+ *
+ * @class
+ */
+import type { Block } from '../block.js';
+import { Workspace } from '../workspace.js';
+import { AbstractEventJson } from './events_abstract.js';
+import { UiBase } from './events_ui_base.js';
+import { EventType } from './type.js';
+/**
+ * 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. */
+    blockId?: string;
+    /**
+     * The type of element that was clicked; one of 'block', 'workspace',
+     * or 'zoom_controls'.
+     */
+    targetType?: ClickTarget;
+    type: EventType;
+    /**
+     * @param opt_block The affected block. Null for click events that do not have
+     *     an associated block (i.e. workspace click). Undefined for a blank
+     *     event.
+     * @param opt_workspaceId The workspace identifier for this event.
+     *    Not used if block is passed. Undefined for a blank event.
+     * @param opt_targetType The type of element targeted by this click event.
+     *     Undefined for a blank event.
+     */
+    constructor(opt_block?: Block | null, opt_workspaceId?: string | null, opt_targetType?: ClickTarget);
+    /**
+     * Encode the event as JSON.
+     *
+     * @returns JSON representation.
+     */
+    toJson(): ClickJson;
+    /**
+     * Deserializes the JSON event.
+     *
+     * @param event The event to append new properties to. Should be a subclass
+     *     of Click, 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: ClickJson, workspace: Workspace, event?: any): Click;
+}
+export declare enum ClickTarget {
+    BLOCK = "block",
+    WORKSPACE = "workspace",
+    ZOOM_CONTROLS = "zoom_controls"
+}
+export interface ClickJson extends AbstractEventJson {
+    targetType: ClickTarget;
+    blockId?: string;
+}
+//# sourceMappingURL=events_click.d.ts.map

package/core/events/events_comment_base.d.ts

@@ -0,0 +1,55 @@
+/**
+ * @license
+ * Copyright 2018 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Base class for comment events.
+ *
+ * @class
+ */
+import type { WorkspaceComment } from '../comments/workspace_comment.js';
+import type { Workspace } from '../workspace.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';
+/**
+ * Abstract class for a comment event.
+ */
+export declare class CommentBase extends AbstractEvent {
+    isBlank: boolean;
+    /** The ID of the comment that this event references. */
+    commentId?: string;
+    /**
+     * @param opt_comment The comment this event corresponds to.  Undefined for a
+     *     blank event.
+     */
+    constructor(opt_comment?: WorkspaceComment);
+    /**
+     * Encode the event as JSON.
+     *
+     * @returns JSON representation.
+     */
+    toJson(): CommentBaseJson;
+    /**
+     * Deserializes the JSON event.
+     *
+     * @param event The event to append new properties to. Should be a subclass
+     *     of CommentBase, 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: CommentBaseJson, workspace: Workspace, event?: any): CommentBase;
+    /**
+     * Helper function for Comment[Create|Delete]
+     *
+     * @param event The event to run.
+     * @param create if True then Create, if False then Delete
+     */
+    static CommentCreateDeleteHelper(event: CommentCreate | CommentDelete, create: boolean): void;
+}
+export interface CommentBaseJson extends AbstractEventJson {
+    commentId: string;
+}
+//# sourceMappingURL=events_comment_base.d.ts.map

package/core/events/events_comment_change.d.ts

@@ -0,0 +1,64 @@
+/**
+ * @license
+ * Copyright 2018 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Class for comment change event.
+ *
+ * @class
+ */
+import type { WorkspaceComment } from '../comments/workspace_comment.js';
+import type { Workspace } from '../workspace.js';
+import { CommentBase, CommentBaseJson } from './events_comment_base.js';
+import { EventType } from './type.js';
+/**
+ * Notifies listeners that the contents of a workspace comment has changed.
+ */
+export declare class CommentChange extends CommentBase {
+    type: EventType;
+    /** The previous contents of the comment. */
+    oldContents_?: string;
+    /** The new contents of the comment. */
+    newContents_?: string;
+    /**
+     * @param opt_comment The comment that is being changed.  Undefined for a
+     *     blank event.
+     * @param opt_oldContents Previous contents of the comment.
+     * @param opt_newContents New contents of the comment.
+     */
+    constructor(opt_comment?: WorkspaceComment, opt_oldContents?: string, opt_newContents?: string);
+    /**
+     * Encode the event as JSON.
+     *
+     * @returns JSON representation.
+     */
+    toJson(): CommentChangeJson;
+    /**
+     * Deserializes the JSON event.
+     *
+     * @param event The event to append new properties to. Should be a subclass
+     *     of CommentChange, 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: CommentChangeJson, workspace: Workspace, event?: any): CommentChange;
+    /**
+     * Does this event record any change of state?
+     *
+     * @returns False if something changed.
+     */
+    isNull(): boolean;
+    /**
+     * Run a change event.
+     *
+     * @param forward True if run forward, false if run backward (undo).
+     */
+    run(forward: boolean): void;
+}
+export interface CommentChangeJson extends CommentBaseJson {
+    oldContents: string;
+    newContents: string;
+}
+//# sourceMappingURL=events_comment_change.d.ts.map

package/core/events/events_comment_collapse.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @license
+ * Copyright 2024 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { WorkspaceComment } from '../comments/workspace_comment.js';
+import type { Workspace } from '../workspace.js';
+import { CommentBase, CommentBaseJson } from './events_comment_base.js';
+import { EventType } from './type.js';
+export declare class CommentCollapse extends CommentBase {
+    newCollapsed?: boolean | undefined;
+    type: EventType;
+    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

@@ -0,0 +1,57 @@
+/**
+ * @license
+ * Copyright 2018 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Class for comment creation event.
+ *
+ * @class
+ */
+import type { WorkspaceComment } from '../comments/workspace_comment.js';
+import * as comments from '../serialization/workspace_comments.js';
+import type { Workspace } from '../workspace.js';
+import { CommentBase, CommentBaseJson } from './events_comment_base.js';
+import { EventType } from './type.js';
+/**
+ * Notifies listeners that a workspace comment was created.
+ */
+export declare class CommentCreate extends CommentBase {
+    type: EventType;
+    /** 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.
+     */
+    constructor(opt_comment?: WorkspaceComment);
+    /**
+     * Encode the event as JSON.
+     *
+     * @returns JSON representation.
+     */
+    toJson(): CommentCreateJson;
+    /**
+     * Deserializes the JSON event.
+     *
+     * @param event The event to append new properties to. Should be a subclass
+     *     of CommentCreate, 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: CommentCreateJson, workspace: Workspace, event?: any): CommentCreate;
+    /**
+     * Run a creation event.
+     *
+     * @param forward True if run forward, false if run backward (undo).
+     */
+    run(forward: boolean): void;
+}
+export interface CommentCreateJson extends CommentBaseJson {
+    xml: string;
+    json: object;
+}
+//# sourceMappingURL=events_comment_create.d.ts.map

package/core/events/events_comment_delete.d.ts

@@ -0,0 +1,57 @@
+/**
+ * @license
+ * Copyright 2018 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Class for comment deletion event.
+ *
+ * @class
+ */
+import type { WorkspaceComment } from '../comments/workspace_comment.js';
+import * as comments from '../serialization/workspace_comments.js';
+import type { Workspace } from '../workspace.js';
+import { CommentBase, CommentBaseJson } from './events_comment_base.js';
+import { EventType } from './type.js';
+/**
+ * Notifies listeners that a workspace comment has been deleted.
+ */
+export declare class CommentDelete extends CommentBase {
+    type: EventType;
+    /** 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.
+     */
+    constructor(opt_comment?: WorkspaceComment);
+    /**
+     * Run a creation event.
+     *
+     * @param forward True if run forward, false if run backward (undo).
+     */
+    run(forward: boolean): void;
+    /**
+     * Encode the event as JSON.
+     *
+     * @returns JSON representation.
+     */
+    toJson(): CommentDeleteJson;
+    /**
+     * Deserializes the JSON event.
+     *
+     * @param event The event to append new properties to. Should be a subclass
+     *     of CommentDelete, 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: CommentDeleteJson, workspace: Workspace, event?: any): CommentDelete;
+}
+export interface CommentDeleteJson extends CommentBaseJson {
+    xml: string;
+    json: object;
+}
+//# sourceMappingURL=events_comment_delete.d.ts.map

package/core/events/events_comment_drag.d.ts

@@ -0,0 +1,51 @@
+/**
+ * @license
+ * Copyright 2024 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Events fired when a workspace comment is dragged.
+ */
+import type { WorkspaceComment } from '../comments/workspace_comment.js';
+import { Workspace } from '../workspace.js';
+import { AbstractEventJson } from './events_abstract.js';
+import { UiBase } from './events_ui_base.js';
+import { EventType } from './type.js';
+/**
+ * Notifies listeners when a comment is being manually dragged/dropped.
+ */
+export declare class CommentDrag extends UiBase {
+    /** The ID of the top-level comment being dragged. */
+    commentId?: string;
+    /** True if this is the start of a drag, false if this is the end of one. */
+    isStart?: boolean;
+    type: EventType;
+    /**
+     * @param opt_comment The comment that is being dragged.
+     *     Undefined for a blank event.
+     * @param opt_isStart Whether this is the start of a comment drag.
+     *    Undefined for a blank event.
+     */
+    constructor(opt_comment?: WorkspaceComment, opt_isStart?: boolean);
+    /**
+     * Encode the event as JSON.
+     *
+     * @returns JSON representation.
+     */
+    toJson(): CommentDragJson;
+    /**
+     * Deserializes the JSON event.
+     *
+     * @param event The event to append new properties to. Should be a subclass
+     *     of CommentDrag, 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: CommentDragJson, workspace: Workspace, event?: any): CommentDrag;
+}
+export interface CommentDragJson extends AbstractEventJson {
+    isStart: boolean;
+    commentId: string;
+}
+//# sourceMappingURL=events_comment_drag.d.ts.map