blockly 9.2.1 → 9.3.0

package/core/field_variable.d.ts

@@ -5,18 +5,14 @@
  */
 import './events/events_block_change.js';
 import type { Block } from './block.js';
-import { FieldConfig } from './field.js';
+import { Field, FieldConfig } from './field.js';
 import { FieldDropdown, FieldDropdownValidator, MenuGenerator, MenuOption } from './field_dropdown.js';
 import type { Menu } from './menu.js';
 import type { MenuItem } from './menuitem.js';
-import type { Sentinel } from './utils/sentinel.js';
 import { Size } from './utils/size.js';
 import { VariableModel } from './variable_model.js';
-export type FieldVariableValidator = FieldDropdownValidator;
 /**
  * Class for a variable's dropdown field.
- *
- * @alias Blockly.FieldVariable
  */
 export declare class FieldVariable extends FieldDropdown {
     protected menuGenerator_: MenuGenerator | undefined;
@@ -42,20 +38,20 @@ export declare class FieldVariable extends FieldDropdown {
      *     Also accepts Field.SKIP_SETUP if you wish to skip setup (only used by
      * subclasses that want to handle configuration and setting the field value
      * after their own constructors have run).
-     * @param opt_validator A function that is called to validate changes to the
+     * @param validator A function that is called to validate changes to the
      *     field's value. Takes in a variable ID  & returns a validated variable
      *     ID, or null to abort the change.
-     * @param opt_variableTypes A list of the types of variables to include in the
-     *     dropdown. Will only be used if opt_config is not provided.
-     * @param opt_defaultType The type of variable to create if this field's value
-     *     is not explicitly set.  Defaults to ''. Will only be used if opt_config
+     * @param variableTypes A list of the types of variables to include in the
+     *     dropdown. Will only be used if config is not provided.
+     * @param defaultType The type of variable to create if this field's value
+     *     is not explicitly set.  Defaults to ''. Will only be used if config
      *     is not provided.
-     * @param opt_config A map of options used to configure the field.
+     * @param config A map of options used to configure the field.
      *    See the [field creation documentation]{@link
      * https://developers.google.com/blockly/guides/create-custom-blocks/fields/built-in-fields/variable#creation}
      * for a list of properties this parameter supports.
      */
-    constructor(varName: string | null | Sentinel, opt_validator?: FieldVariableValidator, opt_variableTypes?: string[], opt_defaultType?: string, opt_config?: FieldVariableConfig);
+    constructor(varName: string | null | typeof Field.SKIP_SETUP, validator?: FieldVariableValidator, variableTypes?: string[], defaultType?: string, config?: FieldVariableConfig);
     /**
      * Configure the field based on the given map of options.
      *
@@ -139,14 +135,14 @@ export declare class FieldVariable extends FieldDropdown {
      *
      * @returns Validation function, or null.
      */
-    getValidator(): Function | null;
+    getValidator(): FieldVariableValidator | null;
     /**
      * Ensure that the ID belongs to a valid variable of an allowed type.
      *
-     * @param opt_newValue The ID of the new variable to set.
+     * @param newValue The ID of the new variable to set.
      * @returns The validated ID, or null if invalid.
      */
-    protected doClassValidation_(opt_newValue?: any): string | null;
+    protected doClassValidation_(newValue?: any): string | null;
     /**
      * Update the value of this variable field, as well as its variable and text.
      *
@@ -155,7 +151,7 @@ export declare class FieldVariable extends FieldDropdown {
      *
      * @param newId The value to be saved.
      */
-    protected doValueUpdate_(newId: any): void;
+    protected doValueUpdate_(newId: string): void;
     /**
      * Check whether the given variable type is allowed on this field.
      *
@@ -174,10 +170,10 @@ export declare class FieldVariable extends FieldDropdown {
      * Parse the optional arguments representing the allowed variable types and
      * the default variable type.
      *
-     * @param opt_variableTypes A list of the types of variables to include in the
+     * @param variableTypes A list of the types of variables to include in the
      *     dropdown.  If null or undefined, variables of all types will be
      *     displayed in the dropdown.
-     * @param opt_defaultType The type of the variable to create if this field's
+     * @param defaultType The type of the variable to create if this field's
      *     value is not explicitly set.  Defaults to ''.
      */
     private setTypes_;
@@ -238,4 +234,20 @@ export interface FieldVariableConfig extends FieldConfig {
 export interface FieldVariableFromJsonConfig extends FieldVariableConfig {
     variable?: string;
 }
+/**
+ * A function that is called to validate changes to the field's value before
+ * they are set.
+ *
+ * @see {@link https://developers.google.com/blockly/guides/create-custom-blocks/fields/validators#return_values}
+ * @param newValue The value to be validated.
+ * @returns One of three instructions for setting the new value: `T`, `null`,
+ * or `undefined`.
+ *
+ * - `T` to set this function's returned value instead of `newValue`.
+ *
+ * - `null` to invoke `doValueInvalid_` and not set a value.
+ *
+ * - `undefined` to set `newValue` as is.
+ */
+export type FieldVariableValidator = FieldDropdownValidator;
 //# sourceMappingURL=field_variable.d.ts.map

package/core/flyout_base.d.ts

@@ -18,8 +18,6 @@ declare enum FlyoutItemType {
 }
 /**
  * Class for a flyout.
- *
- * @alias Blockly.Flyout
  */
 export declare abstract class Flyout extends DeleteArea implements IFlyout {
     /**
@@ -50,8 +48,7 @@ export declare abstract class Flyout extends DeleteArea implements IFlyout {
     /**
      * Lay out the blocks in the flyout.
      *
-     * @param contents The blocks and buttons to lay
-     *     out.
+     * @param contents The blocks and buttons to lay out.
      * @param gaps The visible gaps between blocks.
      */
     protected abstract layout_(contents: FlyoutItem[], gaps: number[]): void;
@@ -96,9 +93,11 @@ export declare abstract class Flyout extends DeleteArea implements IFlyout {
     horizontalLayout: boolean;
     protected toolboxPosition_: number;
     /**
-     * Opaque data that can be passed to Blockly.unbindEvent_.
+     * Array holding info needed to unbind events.
+     * Used for disposing.
+     * Ex: [[node, name, func], [node, name, func]].
      */
-    private eventWrappers_;
+    private boundEvents;
     /**
      * Function that will be registered as a change listener on the workspace
      * to reflow when blocks in the flyout workspace change.

package/core/flyout_button.d.ts

@@ -8,8 +8,6 @@ import type * as toolbox from './utils/toolbox.js';
 import type { WorkspaceSvg } from './workspace_svg.js';
 /**
  * Class for a button or label in the flyout.
- *
- * @alias Blockly.FlyoutButton
  */
 export declare class FlyoutButton {
     private readonly workspace;
@@ -19,6 +17,8 @@ export declare class FlyoutButton {
     static TEXT_MARGIN_X: number;
     /** The vertical margin around the text in the button. */
     static TEXT_MARGIN_Y: number;
+    /** The radius of the flyout button's borders. */
+    static BORDER_RADIUS: number;
     private readonly text_;
     private readonly position_;
     private readonly callbackKey_;

package/core/flyout_horizontal.d.ts

@@ -9,8 +9,6 @@ import type { Coordinate } from './utils/coordinate.js';
 import { Rect } from './utils/rect.js';
 /**
  * Class for a flyout.
- *
- * @alias Blockly.HorizontalFlyout
  */
 export declare class HorizontalFlyout extends Flyout {
     horizontalLayout: boolean;

package/core/flyout_metrics_manager.d.ts

@@ -9,8 +9,6 @@ import type { WorkspaceSvg } from './workspace_svg.js';
 /**
  * Calculates metrics for a flyout's workspace.
  * The metrics are mainly used to size scrollbars for the flyout.
- *
- * @alias Blockly.FlyoutMetricsManager
  */
 export declare class FlyoutMetricsManager extends MetricsManager {
     /** The flyout that owns the workspace to calculate metrics for. */

package/core/flyout_vertical.d.ts

@@ -9,8 +9,6 @@ import type { Coordinate } from './utils/coordinate.js';
 import { Rect } from './utils/rect.js';
 /**
  * Class for a flyout.
- *
- * @alias Blockly.VerticalFlyout
  */
 export declare class VerticalFlyout extends Flyout {
     /** The name of the vertical flyout in the registry. */

package/core/generator.d.ts

@@ -10,7 +10,6 @@ import type { Workspace } from './workspace.js';
  * Class for a code generator that translates the blocks into a language.
  *
  * @unrestricted
- * @alias Blockly.CodeGenerator
  */
 export declare class CodeGenerator {
     name_: string;

package/core/gesture.d.ts

@@ -5,7 +5,6 @@
  */
 import './events/events_click.js';
 import type { BlockSvg } from './block_svg.js';
-import * as browserEvents from './browser_events.js';
 import { BubbleDragger } from './bubble_dragger.js';
 import type { Field } from './field.js';
 import type { IBlockDragger } from './interfaces/i_block_dragger.js';
@@ -16,8 +15,6 @@ import { WorkspaceDragger } from './workspace_dragger.js';
 import type { WorkspaceSvg } from './workspace_svg.js';
 /**
  * Class for one gesture.
- *
- * @alias Blockly.Gesture
  */
 export declare class Gesture {
     private readonly creatorWorkspace;
@@ -63,15 +60,11 @@ export declare class Gesture {
      */
     private hasExceededDragRadius_;
     /**
-     * A handle to use to unbind a pointermove listener at the end of a drag.
-     * Opaque data returned from Blockly.bindEventWithChecks_.
+     * Array holding info needed to unbind events.
+     * Used for disposing.
+     * Ex: [[node, name, func], [node, name, func]].
      */
-    protected onMoveWrapper_: browserEvents.Data | null;
-    /**
-     * A handle to use to unbind a pointerup listener at the end of a drag.
-     * Opaque data returned from Blockly.bindEventWithChecks_.
-     */
-    protected onUpWrapper_: browserEvents.Data | null;
+    private boundEvents;
     /** The object tracking a bubble drag, or null if none is in progress. */
     private bubbleDragger_;
     /** The object tracking a block drag, or null if none is in progress. */
@@ -105,12 +98,6 @@ export declare class Gesture {
     private previousScale_;
     /** The starting distance between two touch points. */
     private startDistance_;
-    /**
-     * A handle to use to unbind the second pointerdown listener
-     * at the end of a drag.
-     * Opaque data returned from Blockly.bindEventWithChecks_.
-     */
-    private onStartWrapper_;
     /** Boolean for whether or not the workspace supports pinch-zoom. */
     private isPinchZoomEnabled_;
     /**
@@ -360,7 +347,7 @@ export declare class Gesture {
      * @param field The field the gesture started on.
      * @internal
      */
-    setStartField(field: Field): void;
+    setStartField<T>(field: Field<T>): void;
     /**
      * Record the bubble that a gesture started on
      *

package/core/grid.d.ts

@@ -6,8 +6,6 @@
 import { GridOptions } from './options.js';
 /**
  * Class for a workspace's grid.
- *
- * @alias Blockly.Grid
  */
 export declare class Grid {
     private pattern;

package/core/icon.d.ts

@@ -9,8 +9,6 @@ import { Coordinate } from './utils/coordinate.js';
 import { Size } from './utils/size.js';
 /**
  * Class for an icon.
- *
- * @alias Blockly.Icon
  */
 export declare abstract class Icon {
     protected block_: BlockSvg | null;

package/core/inject.d.ts

@@ -11,7 +11,6 @@ import { WorkspaceSvg } from './workspace_svg.js';
  * @param container Containing element, or its ID, or a CSS selector.
  * @param opt_options Optional dictionary of options.
  * @returns Newly created main workspace.
- * @alias Blockly.inject
  */
 export declare function inject(container: Element | string, opt_options?: BlocklyOptions): WorkspaceSvg;
 //# sourceMappingURL=inject.d.ts.map

package/core/input.d.ts

@@ -10,8 +10,6 @@ import type { Connection } from './connection.js';
 import type { Field } from './field.js';
 /**
  * Class for an input with an optional field.
- *
- * @alias Blockly.Input
  */
 export declare class Input {
     type: number;
@@ -131,7 +129,6 @@ export declare namespace Input {
     /**
      * Enum for alignment of inputs.
      *
-     * @alias Blockly.Input.Align
      */
     enum Align {
         LEFT = -1,

package/core/input_types.d.ts

@@ -5,8 +5,6 @@
  */
 /**
  * Enum for the type of a connection or input.
- *
- * @alias Blockly.inputTypes
  */
 export declare enum inputTypes {
     VALUE = 1,

package/core/insertion_marker_manager.d.ts

@@ -10,8 +10,6 @@ import type { Coordinate } from './utils/coordinate.js';
  * Class that controls updates to connections during drags.  It is primarily
  * responsible for finding the closest eligible connection and highlighting or
  * unhighlighting it as needed during a drag.
- *
- * @alias Blockly.InsertionMarkerManager
  */
 export declare class InsertionMarkerManager {
     /**
@@ -114,10 +112,8 @@ export declare class InsertionMarkerManager {
      */
     private createMarkerBlock;
     /**
-     * Populate the list of available connections on this block stack.  This
-     * should only be called once, at the beginning of a drag. If the stack has
-     * more than one block, this function will populate lastOnStack and create
-     * the corresponding insertion marker.
+     * Populate the list of available connections on this block stack. If the
+     * stack has more than one block, this function will also update lastOnStack.
      *
      * @returns A list of available connections.
      */
@@ -230,6 +226,10 @@ export declare class InsertionMarkerManager {
      * @internal
      */
     getInsertionMarkers(): BlockSvg[];
+    /**
+     * Safely disposes of an insertion marker.
+     */
+    private disposeInsertionMarker;
 }
 export declare namespace InsertionMarkerManager {
     /**

package/core/interfaces/i_ast_node_location.d.ts

@@ -5,8 +5,6 @@
  */
 /**
  * An AST node location interface.
- *
- * @alias Blockly.IASTNodeLocation
  */
 export interface IASTNodeLocation {
 }

package/core/interfaces/i_ast_node_location_svg.d.ts

@@ -6,8 +6,6 @@
 import type { IASTNodeLocation } from './i_ast_node_location.js';
 /**
  * An AST node location SVG interface.
- *
- * @alias Blockly.IASTNodeLocationSvg
  */
 export interface IASTNodeLocationSvg extends IASTNodeLocation {
     /**

package/core/interfaces/i_ast_node_location_with_block.d.ts

@@ -7,8 +7,6 @@ import type { IASTNodeLocation } from './i_ast_node_location.js';
 import type { Block } from '../block.js';
 /**
  * An AST node location that has an associated block.
- *
- * @alias Blockly.IASTNodeLocationWithBlock
  */
 export interface IASTNodeLocationWithBlock extends IASTNodeLocation {
     /**

package/core/interfaces/i_autohideable.d.ts

@@ -6,8 +6,6 @@
 import type { IComponent } from './i_component.js';
 /**
  * Interface for a component that can be automatically hidden.
- *
- * @alias Blockly.IAutoHideable
  */
 export interface IAutoHideable extends IComponent {
     /**

package/core/interfaces/i_block_dragger.d.ts

@@ -7,8 +7,6 @@ import type { Coordinate } from '../utils/coordinate.js';
 import type { BlockSvg } from '../block_svg.js';
 /**
  * A block dragger interface.
- *
- * @alias Blockly.IBlockDragger
  */
 export interface IBlockDragger {
     /**

package/core/interfaces/i_bounded_element.d.ts

@@ -6,8 +6,6 @@
 import type { Rect } from '../utils/rect.js';
 /**
  * A bounded element interface.
- *
- * @alias Blockly.IBoundedElement
  */
 export interface IBoundedElement {
     /**

package/core/interfaces/i_bubble.d.ts

@@ -9,8 +9,6 @@ import type { IContextMenu } from './i_contextmenu.js';
 import type { IDraggable } from './i_draggable.js';
 /**
  * A bubble interface.
- *
- * @alias Blockly.IBubble
  */
 export interface IBubble extends IDraggable, IContextMenu {
     /**

package/core/interfaces/i_collapsible_toolbox_item.d.ts

@@ -7,8 +7,6 @@ import type { ISelectableToolboxItem } from './i_selectable_toolbox_item.js';
 import type { IToolboxItem } from './i_toolbox_item.js';
 /**
  * Interface for an item in the toolbox that can be collapsed.
- *
- * @alias Blockly.ICollapsibleToolboxItem
  */
 export interface ICollapsibleToolboxItem extends ISelectableToolboxItem {
     /**

package/core/interfaces/i_component.d.ts

@@ -6,8 +6,6 @@
 /**
  * The interface for a workspace component that can be registered with the
  * ComponentManager.
- *
- * @alias Blockly.IComponent
  */
 export interface IComponent {
     /**

package/core/interfaces/i_connection_checker.d.ts

@@ -7,8 +7,6 @@ import type { Connection } from '../connection.js';
 import type { RenderedConnection } from '../rendered_connection.js';
 /**
  * Class for connection type checking logic.
- *
- * @alias Blockly.IConnectionChecker
  */
 export interface IConnectionChecker {
     /**

package/core/interfaces/i_contextmenu.d.ts

@@ -3,7 +3,6 @@
  * Copyright 2020 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-/** @alias Blockly.IContextMenu */
 export interface IContextMenu {
     /**
      * Show the context menu for this object.

package/core/interfaces/i_copyable.d.ts

@@ -5,7 +5,6 @@
  */
 import type { WorkspaceSvg } from '../workspace_svg.js';
 import type { ISelectable } from './i_selectable.js';
-/** @alias Blockly.ICopyable */
 export interface ICopyable extends ISelectable {
     /**
      * Encode for copying.
@@ -19,7 +18,9 @@ export declare namespace ICopyable {
     interface CopyData {
         saveInfo: Object | Element;
         source: WorkspaceSvg;
-        typeCounts: Object | null;
+        typeCounts: {
+            [key: string]: number;
+        } | null;
     }
 }
 export type CopyData = ICopyable.CopyData;

package/core/interfaces/i_deletable.d.ts

@@ -5,8 +5,6 @@
  */
 /**
  * The interface for an object that can be deleted.
- *
- * @alias Blockly.IDeletable
  */
 export interface IDeletable {
     /**

package/core/interfaces/i_delete_area.d.ts

@@ -8,8 +8,6 @@ import type { IDraggable } from './i_draggable.js';
 /**
  * Interface for a component that can delete a block or bubble that is dropped
  * on top of it.
- *
- * @alias Blockly.IDeleteArea
  */
 export interface IDeleteArea extends IDragTarget {
     /**

package/core/interfaces/i_drag_target.d.ts

@@ -9,8 +9,6 @@ import type { IComponent } from './i_component.js';
 /**
  * Interface for a component with custom behaviour when a block or bubble is
  * dragged over or dropped on top of it.
- *
- * @alias Blockly.IDragTarget
  */
 export interface IDragTarget extends IComponent {
     /**

package/core/interfaces/i_draggable.d.ts

@@ -6,8 +6,6 @@
 import type { IDeletable } from './i_deletable.js';
 /**
  * The interface for an object that can be dragged.
- *
- * @alias Blockly.IDraggable
  */
 export interface IDraggable extends IDeletable {
 }

package/core/interfaces/i_flyout.d.ts

@@ -11,8 +11,6 @@ import type { Svg } from '../utils/svg.js';
 import type { IRegistrable } from './i_registrable.js';
 /**
  * Interface for a flyout.
- *
- * @alias Blockly.IFlyout
  */
 export interface IFlyout extends IRegistrable {
     /** Whether the flyout is laid out horizontally or not. */

package/core/interfaces/i_keyboard_accessible.d.ts

@@ -6,8 +6,6 @@
 import { KeyboardShortcut } from '../shortcut_registry.js';
 /**
  * An interface for an object that handles keyboard shortcuts.
- *
- * @alias Blockly.IKeyboardAccessible
  */
 export interface IKeyboardAccessible {
     /**

package/core/interfaces/i_legacy_procedure_blocks.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Legacy means of representing a procedure signature. The elements are
+ * respectively: name, parameter names, and whether it has a return value.
+ */
+export type ProcedureTuple = [string, string[], boolean];
+/**
+ * Procedure block type.
+ *
+ * @internal
+ */
+export interface ProcedureBlock {
+    getProcedureCall: () => string;
+    renameProcedure: (p1: string, p2: string) => void;
+    getProcedureDef: () => ProcedureTuple;
+}
+/** @internal */
+export interface LegacyProcedureDefBlock {
+    getProcedureDef: () => ProcedureTuple;
+}
+/** @internal */
+export declare function isLegacyProcedureDefBlock(block: Object): block is LegacyProcedureDefBlock;
+/** @internal */
+export interface LegacyProcedureCallBlock {
+    getProcedureCall: () => string;
+    renameProcedure: (p1: string, p2: string) => void;
+}
+/** @internal */
+export declare function isLegacyProcedureCallBlock(block: Object): block is LegacyProcedureCallBlock;
+//# sourceMappingURL=i_legacy_procedure_blocks.d.ts.map

package/core/interfaces/i_metrics_manager.d.ts

@@ -8,8 +8,6 @@ import type { Size } from '../utils/size.js';
 import type { Metrics } from '../utils/metrics.js';
 /**
  * Interface for a metrics manager.
- *
- * @alias Blockly.IMetricsManager
  */
 export interface IMetricsManager {
     /**
@@ -34,11 +32,14 @@ export interface IMetricsManager {
      */
     getScrollMetrics(opt_getWorkspaceCoordinates?: boolean, opt_viewMetrics?: ContainerRegion, opt_contentMetrics?: ContainerRegion): ContainerRegion;
     /**
-     * Gets the width and the height of the flyout on the workspace in pixel
-     * coordinates. Returns 0 for the width and height if the workspace has a
-     * category toolbox instead of a simple toolbox.
+     * Gets the width and the height of the flyout in pixel
+     * coordinates. By default, will get metrics for either a simple flyout (owned
+     * directly by the workspace) or for the flyout owned by the toolbox. If you
+     * pass `opt_own` as `true` then only metrics for the simple flyout will be
+     * returned, and it will return 0 for the width and height if the workspace
+     * has a category toolbox instead of a simple toolbox.
      *
-     * @param opt_own Whether to only return the workspace's own flyout.
+     * @param opt_own Whether to only return the workspace's own flyout metrics.
      * @returns The width and height of the flyout.
      */
     getFlyoutMetrics(opt_own?: boolean): ToolboxMetrics;
@@ -46,8 +47,7 @@ export interface IMetricsManager {
      * Gets the width, height and position of the toolbox on the workspace in
      * pixel coordinates. Returns 0 for the width and height if the workspace has
      * a simple toolbox instead of a category toolbox. To get the width and height
-     * of a
-     * simple toolbox @see {@link IMetricsManager#getFlyoutMetrics}.
+     * of a simple toolbox, see {@link IMetricsManager#getFlyoutMetrics}.
      *
      * @returns The object with the width, height and position of the toolbox.
      */

package/core/interfaces/i_movable.d.ts

@@ -5,8 +5,6 @@
  */
 /**
  * The interface for an object that is movable.
- *
- * @alias Blockly.IMovable
  */
 export interface IMovable {
     /**

package/core/interfaces/i_positionable.d.ts

@@ -8,8 +8,6 @@ import type { UiMetrics } from '../metrics_manager.js';
 import type { IComponent } from './i_component.js';
 /**
  * Interface for a component that is positioned on top of the workspace.
- *
- * @alias Blockly.IPositionable
  */
 export interface IPositionable extends IComponent {
     /**

package/core/interfaces/i_procedure_block.d.ts

@@ -4,9 +4,12 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import type { Block } from '../block.js';
+import { IProcedureModel } from './i_procedure_model.js';
 /** The interface for a block which models a procedure. */
 export interface IProcedureBlock {
+    getProcedureModel(): IProcedureModel;
     doProcedureUpdate(): void;
+    isProcedureDef(): boolean;
 }
 /** A type guard which checks if the given block is a procedure block. */
 export declare function isProcedureBlock(block: Block | IProcedureBlock): block is IProcedureBlock;