blockly 9.0.0 → 9.1.0-beta.0

package/core/scrollbar.d.ts

@@ -33,17 +33,28 @@ export declare class Scrollbar {
      * @internal
      */
     static readonly DEFAULT_SCROLLBAR_MARGIN = 0.5;
-    private readonly pair_;
-    private readonly margin_;
+    /** Whether this scrollbar is part of a pair. */
+    private readonly pair;
+    /**
+     * Margin around the scrollbar (between the scrollbar and the edge of the
+     * viewport in pixels).
+     */
+    private readonly margin;
     /** Previously recorded metrics from the workspace. */
-    private oldHostMetrics_;
+    private oldHostMetrics;
     /**
      * The ratio of handle position offset to workspace content displacement.
      *
      * @internal
      */
     ratio: number;
-    private origin_;
+    /**
+     * The location of the origin of the workspace that the scrollbar is in,
+     * measured in CSS pixels relative to the injection div origin.  This is
+     * usually (0, 0).  When the scrollbar is in a flyout it may have a
+     * different origin.
+     */
+    private origin;
     /**
      * The position of the mouse along this scrollbar's major axis at the start
      * of the most recent drag. Units are CSS pixels, with (0, 0) at the top
@@ -51,35 +62,56 @@ export declare class Scrollbar {
      * coordinate of the mouse down event; for a vertical scrollbar it's the y
      * coordinate of the mouse down event.
      */
-    private startDragMouse_;
+    private startDragMouse;
     /**
      * The length of the scrollbars (including the handle and the background),
      * in CSS pixels. This is equivalent to scrollbar background length and the
      * area within which the scrollbar handle can move.
      */
-    private scrollbarLength_;
+    private scrollbarLength;
     /** The length of the scrollbar handle in CSS pixels. */
-    private handleLength_;
+    private handleLength;
     /**
      * The offset of the start of the handle from the scrollbar position, in CSS
      * pixels.
      */
-    private handlePosition_;
+    private handlePosition;
     private startDragHandle;
     /** Whether the scrollbar handle is visible. */
-    private isVisible_;
+    private isHandleVisible;
     /** Whether the workspace containing this scrollbar is visible. */
-    private containerVisible_;
-    private svgBackground_;
-    private svgHandle_;
-    private outerSvg_;
-    private svgGroup_;
+    private containerVisible;
+    /** The transparent background behind the handle. */
+    private svgBackground;
+    /** The visible handle that can be dragged around. */
+    private svgHandle;
+    /** The outermost SVG element, which contains all parts of the scrollbar. */
+    private outerSvg;
+    /**
+     * The upper left corner of the scrollbar's SVG group in CSS pixels relative
+     * to the scrollbar's origin.  This is usually relative to the injection div
+     * origin.
+     *
+     * @internal
+     */
     position: Coordinate;
+    /**
+     * The DOM attribute that controls the length of the scrollbar. Different
+     * for horizontal and vertical scrollbars.
+     */
     lengthAttribute_: string;
+    /**
+     * The DOM attribute that controls the position of the scrollbar.
+     * Different for horizontal and vertical scrollbars.
+     */
     positionAttribute_: string;
-    onMouseDownBarWrapper_: browserEvents.Data | null;
-    onMouseDownHandleWrapper_: browserEvents.Data | null;
+    /** Handler for mouse down events on the background of the scrollbar. */
+    onMouseDownBarWrapper_: browserEvents.Data;
+    /** Handler for mouse down events on the handle of the scrollbar. */
+    onMouseDownHandleWrapper_: browserEvents.Data;
+    /** Handler for mouse move events during scrollbar drags. */
     onMouseUpWrapper_: browserEvents.Data | null;
+    /** Handler for mouse up events to end scrollbar drags. */
     onMouseMoveWrapper_: browserEvents.Data | null;
     /**
      * @param workspace Workspace to bind the scrollbar to.
@@ -90,8 +122,12 @@ export declare class Scrollbar {
      */
     constructor(workspace: WorkspaceSvg, horizontal: boolean, opt_pair?: boolean, opt_class?: string, opt_margin?: number);
     /**
-     * Dispose of this scrollbar.
-     * Unlink from all DOM elements to prevent memory leaks.
+     * Set the size of the scrollbar DOM elements along the minor axis.
+     */
+    private setInitialThickness;
+    /**
+     * Dispose of this scrollbar. Remove DOM elements, event listeners,
+     * and theme subscriptions.
      *
      * @suppress {checkTypes}
      */
@@ -103,14 +139,14 @@ export declare class Scrollbar {
      * @param value Value that is potentially out of bounds, in CSS pixels.
      * @returns Constrained value, in CSS pixels.
      */
-    private constrainHandleLength_;
+    private constrainHandleLength;
     /**
      * Set the length of the scrollbar's handle and change the SVG attribute
      * accordingly.
      *
      * @param newLength The new scrollbar handle length in CSS pixels.
      */
-    private setHandleLength_;
+    private setHandleLength;
     /**
      * Constrain the handle's position within the minimum (0) and maximum values
      * allowed for the scrollbar.
@@ -118,7 +154,7 @@ export declare class Scrollbar {
      * @param value Value that is potentially out of bounds, in CSS pixels.
      * @returns Constrained value, in CSS pixels.
      */
-    private constrainHandlePosition_;
+    private constrainHandlePosition;
     /**
      * Set the offset of the scrollbar's handle from the scrollbar's position, and
      * change the SVG attribute accordingly.
@@ -132,7 +168,7 @@ export declare class Scrollbar {
      *
      * @param newSize The new scrollbar background length in CSS pixels.
      */
-    private setScrollbarLength_;
+    private setScrollbarLength;
     /**
      * Set the position of the scrollbar's SVG group in CSS pixels relative to the
      * scrollbar's origin.  This sets the scrollbar's location within the
@@ -158,14 +194,14 @@ export declare class Scrollbar {
      *     possibly fetched from the host object.
      * @returns Whether a resizeView is necessary.
      */
-    private requiresViewResize_;
+    private requiresViewResize;
     /**
      * Recalculate a horizontal scrollbar's location and length.
      *
      * @param hostMetrics A data structure describing all the required dimensions,
      *     possibly fetched from the host object.
      */
-    private resizeHorizontal_;
+    private resizeHorizontal;
     /**
      * Recalculate a horizontal scrollbar's location on the screen and path
      * length. This should be called when the layout or size of the window has
@@ -189,7 +225,7 @@ export declare class Scrollbar {
      * @param hostMetrics A data structure describing all the required dimensions,
      *     possibly fetched from the host object.
      */
-    private resizeVertical_;
+    private resizeVertical;
     /**
      * Recalculate a vertical scrollbar's location on the screen and path length.
      * This should be called when the layout or size of the window has changed.
@@ -206,13 +242,6 @@ export declare class Scrollbar {
      *     possibly fetched from the host object.
      */
     resizeContentVertical(hostMetrics: Metrics): void;
-    /**
-     * Create all the DOM elements required for a scrollbar.
-     * The resulting widget is not sized.
-     *
-     * @param opt_class A class to be applied to this scrollbar.
-     */
-    private createDom_;
     /**
      * Is the scrollbar visible.  Non-paired scrollbars disappear when they aren't
      * needed.
@@ -247,27 +276,27 @@ export declare class Scrollbar {
      *
      * @param e Mouse down event.
      */
-    private onMouseDownBar_;
+    private onMouseDownBar;
     /**
      * Start a dragging operation.
      * Called when scrollbar handle is clicked.
      *
      * @param e Mouse down event.
      */
-    private onMouseDownHandle_;
+    private onMouseDownHandle;
     /**
      * Drag the scrollbar's handle.
      *
      * @param e Mouse move event.
      */
-    private onMouseMoveHandle_;
+    private onMouseMoveHandle;
     /** Release the scrollbar handle and reset state accordingly. */
-    private onMouseUpHandle_;
+    private onMouseUpHandle;
     /**
      * Hide chaff and stop binding to mouseup and mousemove events.  Call this to
      * wrap up loose ends associated with the scrollbar.
      */
-    private cleanUp_;
+    private cleanUp;
     /**
      * Helper to calculate the ratio of handle position to scrollbar view size.
      *
@@ -279,7 +308,7 @@ export declare class Scrollbar {
      * Updates workspace metrics based on new scroll ratio. Called when scrollbar
      * is moved.
      */
-    private updateMetrics_;
+    private updateMetrics;
     /**
      * Set the scrollbar handle's position.
      *
@@ -304,6 +333,6 @@ export declare class Scrollbar {
      *     workspace.
      * @returns Whether the two sets of metrics are equivalent.
      */
-    private static metricsAreEquivalent_;
+    private static metricsAreEquivalent;
 }
 //# sourceMappingURL=scrollbar.d.ts.map

package/core/serialization/blocks.d.ts

@@ -5,6 +5,7 @@
  */
 import type { Block } from '../block.js';
 import type { Connection } from '../connection.js';
+import type { ISerializer } from '../interfaces/i_serializer.js';
 import type { Workspace } from '../workspace.js';
 /**
  * Represents the state of a connection.
@@ -101,4 +102,41 @@ export declare function appendInternal(state: State, workspace: Workspace, { par
     isShadow?: boolean;
     recordUndo?: boolean;
 }): Block;
+/**
+ * Serializer for saving and loading block state.
+ *
+ * @alias Blockly.serialization.blocks.BlockSerializer
+ */
+export declare class BlockSerializer implements ISerializer {
+    priority: number;
+    constructor();
+    /**
+     * Serializes the blocks of the given workspace.
+     *
+     * @param workspace The workspace to save the blocks of.
+     * @returns The state of the workspace's blocks, or null if there are no
+     *     blocks.
+     */
+    save(workspace: Workspace): {
+        languageVersion: number;
+        blocks: State[];
+    } | null;
+    /**
+     * Deserializes the blocks defined by the given state into the given
+     * workspace.
+     *
+     * @param state The state of the blocks to deserialize.
+     * @param workspace The workspace to deserialize into.
+     */
+    load(state: {
+        languageVersion: number;
+        blocks: State[];
+    }, workspace: Workspace): void;
+    /**
+     * Disposes of any blocks that exist on the workspace.
+     *
+     * @param workspace The workspace to clear the blocks of.
+     */
+    clear(workspace: Workspace): void;
+}
 //# sourceMappingURL=blocks.d.ts.map

package/core/serialization/priorities.d.ts

@@ -9,6 +9,10 @@
  * @alias Blockly.serialization.priorities.VARIABLES
  */
 export declare const VARIABLES = 100;
+/**
+ * The priority for deserializing variable data.
+ */
+export declare const PROCEDURES = 75;
 /**
  * The priority for deserializing blocks.
  *

package/core/serialization/procedures.d.ts

@@ -0,0 +1,78 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { IParameterModel } from '../interfaces/i_parameter_model.js';
+import { IProcedureModel } from '../interfaces/i_procedure_model.js';
+import type { ISerializer } from '../interfaces/i_serializer.js';
+import { ObservableProcedureModel } from '../procedures/observable_procedure_model.js';
+import { ObservableParameterModel } from '../procedures/observable_parameter_model.js';
+import type { Workspace } from '../workspace.js';
+/**
+ * Representation of a procedure data model.
+ */
+export interface State {
+    id: string;
+    name: string;
+    returnTypes: string[] | null;
+    parameters?: ParameterState[];
+}
+/**
+ * Representation of a parameter data model.
+ */
+export interface ParameterState {
+    id: string;
+    name: string;
+    types?: string[];
+}
+/**
+ * A newable signature for an IProcedureModel.
+ *
+ * Refer to
+ * https://www.typescriptlang.org/docs/handbook/2/generics.html#using-class-types-in-generics
+ * for what is going on with this.
+ */
+declare type ProcedureModelConstructor<ProcedureModel extends IProcedureModel> = new (workspace: Workspace, name: string, id: string) => ProcedureModel;
+/**
+ * A newable signature for an IParameterModel.
+ *
+ * Refer to
+ * https://www.typescriptlang.org/docs/handbook/2/generics.html#using-class-types-in-generics
+ * for what is going on with this.
+ */
+declare type ParameterModelConstructor<ParameterModel extends IParameterModel> = new (workspace: Workspace, name: string, id: string) => ParameterModel;
+/** Serializer for saving and loading procedure state. */
+export declare class ProcedureSerializer<ProcedureModel extends IProcedureModel, ParameterModel extends IParameterModel> implements ISerializer {
+    private readonly procedureModelClass;
+    private readonly parameterModelClass;
+    priority: number;
+    /**
+     * Constructs the procedure serializer.
+     *
+     * Example usage:
+     *   new ProcedureSerializer(MyProcedureModelClass, MyParameterModelClass)
+     *
+     * @param procedureModelClass The class (implementing IProcedureModel) that
+     *     you want this serializer to deserialize.
+     * @param parameterModelClass The class (implementing IParameterModel) that
+     *     you want this serializer to deserialize.
+     */
+    constructor(procedureModelClass: ProcedureModelConstructor<ProcedureModel>, parameterModelClass: ParameterModelConstructor<ParameterModel>);
+    /** Serializes the procedure models of the given workspace. */
+    save(workspace: Workspace): State[] | null;
+    /**
+     * Deserializes the procedures models defined by the given state into the
+     * workspace.
+     */
+    load(state: State[], workspace: Workspace): void;
+    /** Disposes of any procedure models that exist on the workspace. */
+    clear(workspace: Workspace): void;
+}
+/**
+ * A ProcedureSerializer that deserializes to create the built-in
+ * ObservableProcedureModels and ObservableParameterModels.
+ */
+export declare const observableProcedureSerializer: ProcedureSerializer<ObservableProcedureModel, ObservableParameterModel>;
+export {};
+//# sourceMappingURL=procedures.d.ts.map

package/core/serialization/variables.d.ts

@@ -3,6 +3,8 @@
  * Copyright 2021 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
+import type { ISerializer } from '../interfaces/i_serializer.js';
+import type { Workspace } from '../workspace.js';
 /**
  * Represents the state of a given variable.
  *
@@ -13,4 +15,35 @@ export interface State {
     id: string;
     type: string | undefined;
 }
+/**
+ * Serializer for saving and loading variable state.
+ *
+ * @alias Blockly.serialization.variables.VariableSerializer
+ */
+export declare class VariableSerializer implements ISerializer {
+    priority: number;
+    constructor();
+    /**
+     * Serializes the variables of the given workspace.
+     *
+     * @param workspace The workspace to save the variables of.
+     * @returns The state of the workspace's variables, or null if there are no
+     *     variables.
+     */
+    save(workspace: Workspace): State[] | null;
+    /**
+     * Deserializes the variable defined by the given state into the given
+     * workspace.
+     *
+     * @param state The state of the variables to deserialize.
+     * @param workspace The workspace to deserialize into.
+     */
+    load(state: State[], workspace: Workspace): void;
+    /**
+     * Disposes of any variables that exist on the workspace.
+     *
+     * @param workspace The workspace to clear the variables of.
+     */
+    clear(workspace: Workspace): void;
+}
 //# sourceMappingURL=variables.d.ts.map

package/core/serialization.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @license
+ * Copyright 2022 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import * as blocks from './serialization/blocks.js';
+import * as exceptions from './serialization/exceptions.js';
+import * as priorities from './serialization/priorities.js';
+import * as procedures from './serialization/procedures.js';
+import * as registry from './serialization/registry.js';
+import * as variables from './serialization/variables.js';
+import * as workspaces from './serialization/workspaces.js';
+import { ISerializer } from './interfaces/i_serializer.js';
+export { blocks, exceptions, priorities, procedures, registry, variables, workspaces, ISerializer, };
+//# sourceMappingURL=serialization.d.ts.map

package/core/theme.d.ts

@@ -5,7 +5,7 @@
  */
 export interface ITheme {
     blockStyles?: {
-        [key: string]: BlockStyle;
+        [key: string]: Partial<BlockStyle>;
     };
     categoryStyles?: {
         [key: string]: CategoryStyle;
@@ -51,7 +51,7 @@ export declare class Theme implements ITheme {
      * @param opt_componentStyles A map of Blockly component names to style value.
      */
     constructor(name: string, opt_blockStyles?: {
-        [key: string]: BlockStyle;
+        [key: string]: Partial<BlockStyle>;
     }, opt_categoryStyles?: {
         [key: string]: CategoryStyle;
     }, opt_componentStyles?: ComponentStyle);
@@ -115,9 +115,9 @@ export declare class Theme implements ITheme {
 export declare namespace Theme {
     interface BlockStyle {
         colourPrimary: string;
-        colourSecondary?: string;
-        colourTertiary?: string;
-        hat?: string;
+        colourSecondary: string;
+        colourTertiary: string;
+        hat: string;
     }
     interface CategoryStyle {
         colour: string;

package/core/touch.d.ts

@@ -73,9 +73,9 @@ export declare function shouldHandleEvent(e: Event | PseudoEvent): boolean;
  * Get the touch identifier from the given event.  If it was a mouse event, the
  * identifier is the string 'mouse'.
  *
- * @param e Mouse event or touch event.
- * @returns The touch identifier from the first changed touch, if defined.
- *     Otherwise 'mouse'.
+ * @param e Pointer event, mouse event, or touch event.
+ * @returns The pointerId, or touch identifier from the first changed touch, if
+ *     defined. Otherwise 'mouse'.
  * @alias Blockly.Touch.getTouchIdentifierFromEvent
  */
 export declare function getTouchIdentifierFromEvent(e: Event | PseudoEvent): string;

package/core/warning.d.ts

@@ -12,9 +12,9 @@ import { Icon } from './icon.js';
  * @alias Blockly.Warning
  */
 export declare class Warning extends Icon {
-    private text_;
+    private text;
     /** The top-level node of the warning text, or null if not created. */
-    private paragraphElement_;
+    private paragraphElement;
     /** Does this icon get hidden when the block is collapsed? */
     collapseHidden: boolean;
     /** @param block The block associated with this warning. */
@@ -32,9 +32,9 @@ export declare class Warning extends Icon {
      */
     setVisible(visible: boolean): void;
     /** Show the bubble. */
-    private createBubble_;
+    private createBubble;
     /** Dispose of the bubble and references to it. */
-    private disposeBubble_;
+    private disposeBubble;
     /**
      * Set this warning's text.
      *

package/core/workspace.d.ts

@@ -14,6 +14,7 @@ import type * as toolbox from './utils/toolbox.js';
 import { VariableMap } from './variable_map.js';
 import type { VariableModel } from './variable_model.js';
 import type { WorkspaceComment } from './workspace_comment.js';
+import { IProcedureMap } from './interfaces/i_procedure_map.js';
 /**
  * Class for a workspace.  This is a data structure that contains blocks.
  * There is no UI, and can be created headlessly.
@@ -68,15 +69,16 @@ export declare class Workspace implements IASTNodeLocation {
     /** Set of databases for rapid lookup of connection locations. */
     connectionDBList: ConnectionDB[];
     connectionChecker: IConnectionChecker;
-    private readonly topBlocks_;
-    private readonly topComments_;
+    private readonly topBlocks;
+    private readonly topComments;
     private readonly commentDB;
-    private readonly listeners_;
+    private readonly listeners;
     protected undoStack_: Abstract[];
     protected redoStack_: Abstract[];
     private readonly blockDB;
     private readonly typedBlocksDB;
-    private variableMap_;
+    private variableMap;
+    private procedureMap;
     /**
      * Blocks in the flyout can refer to variables that don't exist in the main
      * workspace.  For instance, the "get item in list" block refers to an
@@ -85,7 +87,7 @@ export declare class Workspace implements IASTNodeLocation {
      * these by tracking "potential" variables in the flyout.  These variables
      * become real when references to them are dragged into the main workspace.
      */
-    private potentialVariableMap_;
+    private potentialVariableMap;
     /** @param opt_options Dictionary of options. */
     constructor(opt_options?: Options);
     /**
@@ -419,6 +421,8 @@ export declare class Workspace implements IASTNodeLocation {
      * @internal
      */
     setVariableMap(variableMap: VariableMap): void;
+    /** Returns the map of all procedures on the workpace. */
+    getProcedureMap(): IProcedureMap;
     /**
      * Find the workspace with the specified ID.
      *