blockly 9.2.1 → 9.3.0

package/core/events/events_abstract.d.ts

@@ -6,8 +6,6 @@
 import type { Workspace } from '../workspace.js';
 /**
  * Abstract class for an event.
- *
- * @alias Blockly.Events.Abstract
  */
 export declare abstract class Abstract {
     /**
@@ -17,13 +15,19 @@ export declare abstract class Abstract {
     abstract isBlank: boolean;
     /** The workspace identifier for this event. */
     workspaceId?: string;
+    /**
+     * An ID for the group of events this block is associated with.
+     *
+     * Groups define events that should be treated as an single action from the
+     * user's perspective, and should be undone together.
+     */
     group: string;
+    /** Whether this event is undoable or not. */
     recordUndo: boolean;
     /** Whether or not the event is a UI event. */
     isUiEvent: boolean;
     /** Type of this event. */
     type: string;
-    /** @alias Blockly.Events.Abstract */
     constructor();
     /**
      * Encode the event as JSON.

package/core/events/events_block_base.d.ts

@@ -7,12 +7,11 @@ import type { Block } from '../block.js';
 import type { Workspace } from '../workspace.js';
 import { Abstract as AbstractEvent, AbstractEventJson } from './events_abstract.js';
 /**
- * Abstract class for a block event.
- *
- * @alias Blockly.Events.BlockBase
+ * Abstract class for any event related to blocks.
  */
 export declare class BlockBase extends AbstractEvent {
     isBlank: boolean;
+    /** The ID of the block associated with this event. */
     blockId?: string;
     /**
      * @param opt_block The block this event corresponds to.

package/core/events/events_block_change.d.ts

@@ -8,15 +8,21 @@ import type { BlockSvg } from '../block_svg.js';
 import { Workspace } from '../workspace.js';
 import { BlockBase, BlockBaseJson } from './events_block_base.js';
 /**
- * Class for a block change event.
- *
- * @alias Blockly.Events.BlockChange
+ * Notifies listeners when some element of a block has changed (e.g.
+ * field values, comments, etc).
  */
 export declare class BlockChange extends BlockBase {
     type: string;
+    /**
+     * The element that changed; one of 'field', 'comment', 'collapsed',
+     * 'disabled', 'inline', or 'mutation'
+     */
     element?: string;
+    /** The name of the field that changed, if this is a change to a field. */
     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.

package/core/events/events_block_create.d.ts

@@ -8,15 +8,17 @@ import * as blocks from '../serialization/blocks.js';
 import { BlockBase, BlockBaseJson } from './events_block_base.js';
 import { Workspace } from '../workspace.js';
 /**
- * Class for a block creation event.
- *
- * @alias Blockly.Events.BlockCreate
+ * Notifies listeners when a block (or connected stack of blocks) is
+ * created.
  */
 export declare class BlockCreate extends BlockBase {
     type: string;
+    /** The XML representation of the created block(s). */
     xml?: Element | DocumentFragment;
-    ids?: string[];
+    /** The JSON respresentation of the created block(s). */
     json?: blocks.State;
+    /** All of the IDs of created blocks. */
+    ids?: string[];
     /** @param opt_block The created block.  Undefined for a blank event. */
     constructor(opt_block?: Block);
     /**

package/core/events/events_block_delete.d.ts

@@ -8,15 +8,18 @@ import * as blocks from '../serialization/blocks.js';
 import { BlockBase, BlockBaseJson } from './events_block_base.js';
 import { Workspace } from '../workspace.js';
 /**
- * Class for a block deletion event.
- *
- * @alias Blockly.Events.BlockDelete
+ * Notifies listeners when a block (or connected stack of blocks) is
+ * deleted.
  */
 export declare class BlockDelete extends BlockBase {
+    /** The XML representation of the deleted block(s). */
     oldXml?: Element | DocumentFragment;
+    /** The JSON respresentation of the deleted block(s). */
+    oldJson?: blocks.State;
+    /** All of the IDs of deleted blocks. */
     ids?: string[];
+    /** True if the deleted block was a shadow block, false otherwise. */
     wasShadow?: boolean;
-    oldJson?: blocks.State;
     type: string;
     /** @param opt_block The deleted block.  Undefined for a blank event. */
     constructor(opt_block?: Block);

package/core/events/events_block_drag.d.ts

@@ -8,13 +8,17 @@ import { AbstractEventJson } from './events_abstract.js';
 import { UiBase } from './events_ui_base.js';
 import { Workspace } from '../workspace.js';
 /**
- * Class for a block drag event.
- *
- * @alias Blockly.Events.BlockDrag
+ * Notifies listeners when a block is being manually dragged/dropped.
  */
 export declare class BlockDrag extends UiBase {
+    /** The ID of the top-level block being dragged. */
     blockId?: string;
+    /** True if this is the start of a drag, false if this is the end of one. */
     isStart?: boolean;
+    /**
+     * A list of all of the blocks (i.e. all descendants of the block associated
+     * with the block ID) being dragged.
+     */
     blocks?: Block[];
     type: string;
     /**

package/core/events/events_block_move.d.ts

@@ -8,17 +8,34 @@ import { Coordinate } from '../utils/coordinate.js';
 import { BlockBase, BlockBaseJson } from './events_block_base.js';
 import type { Workspace } from '../workspace.js';
 /**
- * Class for a block move event.  Created before the move.
- *
- * @alias Blockly.Events.BlockMove
+ * 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: string;
+    /** 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;
     /** @param opt_block The moved block.  Undefined for a blank event. */
     constructor(opt_block?: Block);

package/core/events/events_bubble_open.d.ts

@@ -9,12 +9,13 @@ import { UiBase } from './events_ui_base.js';
 import type { Workspace } from '../workspace.js';
 /**
  * Class for a bubble open event.
- *
- * @alias Blockly.Events.BubbleOpen
  */
 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: string;
     /**

package/core/events/events_click.d.ts

@@ -8,12 +8,15 @@ import { AbstractEventJson } from './events_abstract.js';
 import { UiBase } from './events_ui_base.js';
 import { Workspace } from '../workspace.js';
 /**
- * Class for a click event.
- *
- * @alias Blockly.Events.Click
+ * Notifies listeners that ome 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: string;
     /**

package/core/events/events_comment_base.d.ts

@@ -10,11 +10,10 @@ import type { CommentDelete } from './events_comment_delete.js';
 import type { Workspace } from '../workspace.js';
 /**
  * Abstract class for a comment event.
- *
- * @alias Blockly.Events.CommentBase
  */
 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

package/core/events/events_comment_change.d.ts

@@ -7,13 +7,13 @@ import type { WorkspaceComment } from '../workspace_comment.js';
 import { CommentBase, CommentBaseJson } from './events_comment_base.js';
 import type { Workspace } from '../workspace.js';
 /**
- * Class for a comment change event.
- *
- * @alias Blockly.Events.CommentChange
+ * Notifies listeners that the contents of a workspace comment has changed.
  */
 export declare class CommentChange extends CommentBase {
     type: string;
+    /** 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

package/core/events/events_comment_create.d.ts

@@ -7,12 +7,11 @@ import type { WorkspaceComment } from '../workspace_comment.js';
 import { CommentBase, CommentBaseJson } from './events_comment_base.js';
 import type { Workspace } from '../workspace.js';
 /**
- * Class for a comment creation event.
- *
- * @alias Blockly.Events.CommentCreate
+ * Notifies listeners that a workspace comment was created.
  */
 export declare class CommentCreate extends CommentBase {
     type: string;
+    /** The XML representation of the created workspace comment. */
     xml?: Element | DocumentFragment;
     /**
      * @param opt_comment The created comment.

package/core/events/events_comment_delete.d.ts

@@ -7,12 +7,11 @@ import type { WorkspaceComment } from '../workspace_comment.js';
 import { CommentBase, CommentBaseJson } from './events_comment_base.js';
 import type { Workspace } from '../workspace.js';
 /**
- * Class for a comment deletion event.
- *
- * @alias Blockly.Events.CommentDelete
+ * Notifies listeners that a workspace comment has been deleted.
  */
 export declare class CommentDelete extends CommentBase {
     type: string;
+    /** The XML representation of the deleted workspace comment. */
     xml?: Element;
     /**
      * @param opt_comment The deleted comment.

package/core/events/events_comment_move.d.ts

@@ -8,15 +8,15 @@ import type { WorkspaceComment } from '../workspace_comment.js';
 import { CommentBase, CommentBaseJson } from './events_comment_base.js';
 import type { Workspace } from '../workspace.js';
 /**
- * Class for a comment move event.  Created before the move.
- *
- * @alias Blockly.Events.CommentMove
+ * Notifies listeners that a workspace comment has moved.
  */
 export declare class CommentMove extends CommentBase {
     type: string;
+    /** The comment that is being moved. */
     comment_?: WorkspaceComment;
+    /** The location of the comment before the move, in workspace coordinates. */
     oldCoordinate_?: Coordinate;
-    /** The location after the move, in workspace coordinates. */
+    /** The location of the comment after the move, in workspace coordinates. */
     newCoordinate_?: Coordinate;
     /**
      * @param opt_comment The comment that is being moved.  Undefined for a blank

package/core/events/events_marker_move.d.ts

@@ -9,14 +9,21 @@ import type { Workspace } from '../workspace.js';
 import { AbstractEventJson } from './events_abstract.js';
 import { UiBase } from './events_ui_base.js';
 /**
- * Class for a marker move event.
- *
- * @alias Blockly.Events.MarkerMove
+ * Notifies listeners that a marker (used for keyboard navigation) has
+ * moved.
  */
 export declare class MarkerMove extends UiBase {
+    /** The ID of the block the marker is now on, if any. */
     blockId?: string;
+    /** The old node the marker used to be on, if any. */
     oldNode?: ASTNode;
+    /** The new node the marker is now on. */
     newNode?: ASTNode;
+    /**
+     * True if this is a cursor event, false otherwise.
+     * For information about cursors vs markers see {@link
+     * https://blocklycodelabs.dev/codelabs/keyboard-navigation/index.html?index=..%2F..index#1}.
+     */
     isCursor?: boolean;
     type: string;
     /**

package/core/events/events_selected.d.ts

@@ -8,11 +8,15 @@ import { UiBase } from './events_ui_base.js';
 import type { Workspace } from '../workspace.js';
 /**
  * Class for a selected event.
- *
- * @alias Blockly.Events.Selected
+ * Notifies listeners that a new element has been selected.
  */
 export declare class Selected extends UiBase {
+    /** The id of the last selected selectable element. */
     oldElementId?: string;
+    /**
+     * The id of the newly selected selectable element,
+     * or undefined if unselected.
+     */
     newElementId?: string;
     type: string;
     /**

package/core/events/events_theme_change.d.ts

@@ -7,11 +7,10 @@ import { AbstractEventJson } from './events_abstract.js';
 import { UiBase } from './events_ui_base.js';
 import type { Workspace } from '../workspace.js';
 /**
- * Class for a theme change event.
- *
- * @alias Blockly.Events.ThemeChange
+ * Notifies listeners that the workspace theme has changed.
  */
 export declare class ThemeChange extends UiBase {
+    /** The name of the new theme that has been set. */
     themeName?: string;
     type: string;
     /**

package/core/events/events_toolbox_item_select.d.ts

@@ -7,12 +7,12 @@ import { AbstractEventJson } from './events_abstract.js';
 import { UiBase } from './events_ui_base.js';
 import type { Workspace } from '../workspace.js';
 /**
- * Class for a toolbox item select event.
- *
- * @alias Blockly.Events.ToolboxItemSelect
+ * Notifies listeners that a toolbox item has been selected.
  */
 export declare class ToolboxItemSelect extends UiBase {
+    /** The previously selected toolbox item. */
     oldItem?: string;
+    /** The newly selected toolbox item. */
     newItem?: string;
     type: string;
     /**

package/core/events/events_trashcan_open.d.ts

@@ -7,11 +7,13 @@ import { AbstractEventJson } from './events_abstract.js';
 import { UiBase } from './events_ui_base.js';
 import type { Workspace } from '../workspace.js';
 /**
- * Class for a trashcan open event.
- *
- * @alias Blockly.Events.TrashcanOpen
+ * Notifies listeners when the trashcan is opening or closing.
  */
 export declare class TrashcanOpen extends UiBase {
+    /**
+     * True if the trashcan is currently opening (previously closed).
+     * False if it is currently closing (previously open).
+     */
     isOpen?: boolean;
     type: string;
     /**

package/core/events/events_ui.d.ts

@@ -9,7 +9,6 @@ import { UiBase } from './events_ui_base.js';
  * Class for a UI event.
  *
  * @deprecated December 2020. Instead use a more specific UI event.
- * @alias Blockly.Events.Ui
  */
 export declare class Ui extends UiBase {
     blockId: any;

package/core/events/events_ui_base.d.ts

@@ -10,8 +10,6 @@ import { Abstract as AbstractEvent } from './events_abstract.js';
  * editing to work (e.g. scrolling the workspace, zooming, opening toolbox
  * categories).
  * UI events do not undo or redo.
- *
- * @alias Blockly.Events.UiBase
  */
 export declare class UiBase extends AbstractEvent {
     isBlank: boolean;

package/core/events/events_var_base.d.ts

@@ -8,11 +8,10 @@ import { Abstract as AbstractEvent, AbstractEventJson } from './events_abstract.
 import type { Workspace } from '../workspace.js';
 /**
  * Abstract class for a variable event.
- *
- * @alias Blockly.Events.VarBase
  */
 export declare class VarBase extends AbstractEvent {
     isBlank: boolean;
+    /** The ID of the variable this event references. */
     varId?: string;
     /**
      * @param opt_variable The variable this event corresponds to.  Undefined for

package/core/events/events_var_create.d.ts

@@ -7,13 +7,13 @@ import type { VariableModel } from '../variable_model.js';
 import { VarBase, VarBaseJson } from './events_var_base.js';
 import type { Workspace } from '../workspace.js';
 /**
- * Class for a variable creation event.
- *
- * @alias Blockly.Events.VarCreate
+ * Notifies listeners that a variable model has been created.
  */
 export declare class VarCreate extends VarBase {
     type: string;
+    /** The type of the variable that was created. */
     varType?: string;
+    /** The name of the variable that was created. */
     varName?: string;
     /**
      * @param opt_variable The created variable. Undefined for a blank event.

package/core/events/events_var_delete.d.ts

@@ -7,13 +7,15 @@ import type { VariableModel } from '../variable_model.js';
 import { VarBase, VarBaseJson } from './events_var_base.js';
 import type { Workspace } from '../workspace.js';
 /**
- * Class for a variable deletion event.
+ * Notifies listeners that a variable model has been deleted.
  *
- * @alias Blockly.Events.VarDelete
+ * @class
  */
 export declare class VarDelete extends VarBase {
     type: string;
+    /** The type of the variable that was deleted. */
     varType?: string;
+    /** The name of the variable that was deleted. */
     varName?: string;
     /**
      * @param opt_variable The deleted variable. Undefined for a blank event.

package/core/events/events_var_rename.d.ts

@@ -7,13 +7,15 @@ import type { VariableModel } from '../variable_model.js';
 import { VarBase, VarBaseJson } from './events_var_base.js';
 import type { Workspace } from '../workspace.js';
 /**
- * Class for a variable rename event.
+ * Notifies listeners that a variable model was renamed.
  *
- * @alias Blockly.Events.VarRename
+ * @class
  */
 export declare class VarRename extends VarBase {
     type: string;
+    /** The previous name of the variable. */
     oldName?: string;
+    /** The new name of the variable. */
     newName?: string;
     /**
      * @param opt_variable The renamed variable. Undefined for a blank event.

package/core/events/events_viewport.d.ts

@@ -7,14 +7,25 @@ import { AbstractEventJson } from './events_abstract.js';
 import { UiBase } from './events_ui_base.js';
 import type { Workspace } from '../workspace.js';
 /**
- * Class for a viewport change event.
+ * Notifies listeners that the workspace surface's position or scale has
+ * changed.
  *
- * @alias Blockly.Events.ViewportChange
+ * Does not notify when the workspace itself resizes.
  */
 export declare class ViewportChange extends UiBase {
+    /**
+     * Top edge of the visible portion of the workspace, relative to the
+     * workspace origin.
+     */
     viewTop?: number;
+    /**
+     * The left edge of the visible portion of the workspace, relative to
+     * the workspace origin.
+     */
     viewLeft?: number;
+    /** The scale of the workpace. */
     scale?: number;
+    /** The previous scale of the workspace. */
     oldScale?: number;
     type: string;
     /**