blockly 11.2.0-beta.1 → 12.0.0-beta.0

package/core/renderers/common/renderer.d.ts

@@ -5,10 +5,8 @@
  */
 import type { BlockSvg } from '../../block_svg.js';
 import { Connection } from '../../connection.js';
-import { PreviewType } from '../../insertion_marker_manager.js';
 import type { IRegistrable } from '../../interfaces/i_registrable.js';
 import type { Marker } from '../../keyboard_nav/marker.js';
-import type { RenderedConnection } from '../../rendered_connection.js';
 import type { BlockStyle, Theme } from '../../theme.js';
 import type { WorkspaceSvg } from '../../workspace_svg.js';
 import { ConstantProvider } from './constants.js';
@@ -53,16 +51,26 @@ export declare class Renderer implements IRegistrable {
      *
      * @param svg The root of the workspace's SVG.
      * @param theme The workspace theme object.
+     * @param injectionDivIfIsParent The div containing the parent workspace and
+     *   all related workspaces and block containers, if this renderer is for the
+     *   parent workspace. CSS variables representing SVG patterns will be scoped
+     *   to this container. Child workspaces should not override the CSS variables
+     *   created by the parent and thus do not need access to the injection div.
      * @internal
      */
-    createDom(svg: SVGElement, theme: Theme): void;
+    createDom(svg: SVGElement, theme: Theme, injectionDivIfIsParent?: HTMLElement): void;
     /**
      * Refresh the renderer after a theme change.
      *
      * @param svg The root of the workspace's SVG.
      * @param theme The workspace theme object.
+     * @param injectionDivIfIsParent The div containing the parent workspace and
+     *   all related workspaces and block containers, if this renderer is for the
+     *   parent workspace. CSS variables representing SVG patterns will be scoped
+     *   to this container. Child workspaces should not override the CSS variables
+     *   created by the parent and thus do not need access to the injection div.
      */
-    refreshDom(svg: SVGElement, theme: Theme): void;
+    refreshDom(svg: SVGElement, theme: Theme, injectionDivIfIsParent?: HTMLElement): void;
     /**
      * Dispose of this renderer.
      * Delete all DOM elements that this renderer and its constants created.
@@ -133,19 +141,6 @@ export declare class Renderer implements IRegistrable {
      * @returns Whether there is a home for the orphan or not.
      */
     protected orphanCanConnectAtEnd(topBlock: BlockSvg, orphanBlock: BlockSvg, localType: number): boolean;
-    /**
-     * Chooses a connection preview method based on the available connection, the
-     * current dragged connection, and the block being dragged.
-     *
-     * @param closest The available connection.
-     * @param local The connection currently being dragged.
-     * @param topBlock The block currently being dragged.
-     * @returns The preview type to display.
-     *
-     * @deprecated v10 - This function is no longer respected. A custom
-     *    IConnectionPreviewer may be able to fulfill the functionality.
-     */
-    getConnectionPreviewMethod(closest: RenderedConnection, local: RenderedConnection, topBlock: BlockSvg): PreviewType;
     /**
      * Render the block.
      *

package/core/renderers/geras/renderer.d.ts

@@ -34,7 +34,7 @@ export declare class Renderer extends BaseRenderer {
     init(theme: Theme, opt_rendererOverrides?: {
         [rendererConstant: string]: any;
     }): void;
-    refreshDom(svg: SVGElement, theme: Theme): void;
+    refreshDom(svg: SVGElement, theme: Theme, injectionDiv: HTMLElement): void;
     makeConstants_(): ConstantProvider;
     /**
      * Create a new instance of the renderer's render info object.

package/core/renderers/zelos/constants.d.ts

@@ -102,7 +102,13 @@ export declare class ConstantProvider extends BaseConstantProvider {
      * rectangular reporter block. Null before init is called.
      */
     SQUARED: Shape | null;
-    constructor();
+    /**
+     * Creates a new ConstantProvider.
+     *
+     * @param gridUnit If set, defines the base unit used to calculate other
+     *     constants.
+     */
+    constructor(gridUnit?: number);
     setFontConstants_(theme: Theme): void;
     init(): void;
     setDynamicProperties_(theme: Theme): void;
@@ -153,7 +159,7 @@ export declare class ConstantProvider extends BaseConstantProvider {
     };
     generateSecondaryColour_(colour: string): string;
     generateTertiaryColour_(colour: string): string;
-    createDom(svg: SVGElement, tagName: string, selector: string): void;
+    createDom(svg: SVGElement, tagName: string, selector: string, injectionDivIfIsParent?: HTMLElement): void;
     getCSS_(selector: string): string[];
 }
 //# sourceMappingURL=constants.d.ts.map

package/core/renderers/zelos/renderer.d.ts

@@ -4,9 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import type { BlockSvg } from '../../block_svg.js';
-import { InsertionMarkerManager } from '../../insertion_marker_manager.js';
 import type { Marker } from '../../keyboard_nav/marker.js';
-import type { RenderedConnection } from '../../rendered_connection.js';
 import type { BlockStyle } from '../../theme.js';
 import type { WorkspaceSvg } from '../../workspace_svg.js';
 import type { RenderInfo as BaseRenderInfo } from '../common/info.js';
@@ -73,10 +71,5 @@ export declare class Renderer extends BaseRenderer {
      * @returns The constant provider.
      */
     getConstants(): ConstantProvider;
-    /**
-     * @deprecated v10 - This function is no longer respected. A custom
-     *    IConnectionPreviewer may be able to fulfill the functionality.
-     */
-    getConnectionPreviewMethod(closest: RenderedConnection, local: RenderedConnection, topBlock: BlockSvg): InsertionMarkerManager.PREVIEW_TYPE;
 }
 //# sourceMappingURL=renderer.d.ts.map

package/core/scrollbar_pair.d.ts

@@ -15,7 +15,7 @@ export declare class ScrollbarPair {
     vScroll: Scrollbar | null;
     corner_: SVGRectElement | null;
     /** Previously recorded metrics from the workspace. */
-    private oldHostMetrics_;
+    private oldHostMetrics;
     /**
      * @param workspace Workspace to bind the scrollbars to.
      * @param addHorizontal Whether to add a horizontal scrollbar.

package/core/separator_flyout_inflater.d.ts

@@ -0,0 +1,47 @@
+/**
+ * @license
+ * Copyright 2024 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { IBoundedElement } from './interfaces/i_bounded_element.js';
+import type { IFlyoutInflater } from './interfaces/i_flyout_inflater.js';
+import type { WorkspaceSvg } from './workspace_svg.js';
+/**
+ * Class responsible for creating separators for flyouts.
+ */
+export declare class SeparatorFlyoutInflater implements IFlyoutInflater {
+    /**
+     * Inflates a dummy flyout separator.
+     *
+     * The flyout automatically creates separators between every element with a
+     * size determined by calling gapForElement on the relevant inflater.
+     * Additionally, users can explicitly add separators in the flyout definition.
+     * When separators (implicitly or explicitly created) follow one another, the
+     * gap of the last one propagates backwards and flattens to one separator.
+     * This flattening is not additive; if there are initially separators of 2, 3,
+     * and 4 pixels, after normalization there will be one separator of 4 pixels.
+     * Therefore, this method returns a zero-width separator, which will be
+     * replaced by the one implicitly created by the flyout based on the value
+     * returned by gapForElement, which knows the default gap, unlike this method.
+     *
+     * @param _state A JSON representation of a flyout separator.
+     * @param flyoutWorkspace The workspace the separator belongs to.
+     * @returns A newly created FlyoutSeparator.
+     */
+    load(_state: object, flyoutWorkspace: WorkspaceSvg): IBoundedElement;
+    /**
+     * Returns the size of the separator. See `load` for more details.
+     *
+     * @param state A JSON representation of a flyout separator.
+     * @param defaultGap The default spacing for flyout items.
+     * @returns The desired size of the separator.
+     */
+    gapForElement(state: object, defaultGap: number): number;
+    /**
+     * Disposes of the given separator. Intentional no-op.
+     *
+     * @param _element The flyout separator to dispose of.
+     */
+    disposeElement(_element: IBoundedElement): void;
+}
+//# sourceMappingURL=separator_flyout_inflater.d.ts.map

package/core/serialization/variables.d.ts

@@ -4,15 +4,8 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import type { ISerializer } from '../interfaces/i_serializer.js';
+import type { IVariableState } from '../interfaces/i_variable_model.js';
 import type { Workspace } from '../workspace.js';
-/**
- * Represents the state of a given variable.
- */
-export interface State {
-    name: string;
-    id: string;
-    type: string | undefined;
-}
 /**
  * Serializer for saving and loading variable state.
  */
@@ -26,7 +19,7 @@ export declare class VariableSerializer implements ISerializer {
      * @returns The state of the workspace's variables, or null if there are no
      *     variables.
      */
-    save(workspace: Workspace): State[] | null;
+    save(workspace: Workspace): IVariableState[] | null;
     /**
      * Deserializes the variable defined by the given state into the given
      * workspace.
@@ -34,7 +27,7 @@ export declare class VariableSerializer implements ISerializer {
      * @param state The state of the variables to deserialize.
      * @param workspace The workspace to deserialize into.
      */
-    load(state: State[], workspace: Workspace): void;
+    load(state: IVariableState[], workspace: Workspace): void;
     /**
      * Disposes of any variables that exist on the workspace.
      *

package/core/shortcut_registry.d.ts

@@ -154,14 +154,14 @@ export declare class ShortcutRegistry {
      * @param e A key down event.
      * @returns The serialized key code for the given event.
      */
-    private serializeKeyEvent_;
+    private serializeKeyEvent;
     /**
      * Checks whether any of the given modifiers are not valid.
      *
      * @param modifiers List of modifiers to be used with the key.
      * @throws {Error} if the modifier is not in the valid modifiers list.
      */
-    private checkModifiers_;
+    private checkModifiers;
     /**
      * Creates the serialized key code that will be used in the key map.
      *

package/core/theme_manager.d.ts

@@ -19,7 +19,7 @@ export declare class ThemeManager {
     private readonly workspace;
     private theme;
     /** A list of workspaces that are subscribed to this theme. */
-    private subscribedWorkspaces_;
+    private subscribedWorkspaces;
     private componentDB;
     /**
      * @param workspace The main workspace.

package/core/toolbox/category.d.ts

@@ -143,7 +143,7 @@ export declare class ToolboxCategory extends ToolboxItem implements ISelectableT
      * @param styleName Name of the style.
      * @returns The hex colour for the category.
      */
-    private getColourfromStyle_;
+    private getColourfromStyle;
     /**
      * Gets the HTML element that is clickable.
      * The parent toolbox element receives clicks. The parent toolbox will add an
@@ -160,7 +160,7 @@ export declare class ToolboxCategory extends ToolboxItem implements ISelectableT
      *     reference string pointing to one of those two values.
      * @returns The hex colour for the category.
      */
-    private parseColour_;
+    private parseColour;
     /**
      * Adds appropriate classes to display an open icon.
      *

package/core/toolbox/collapsible_category.d.ts

@@ -40,7 +40,7 @@ export declare class CollapsibleToolboxCategory extends ToolboxCategory implemen
      *
      * @param itemDef The information needed to create a toolbox item.
      */
-    private createToolboxItem_;
+    private createToolboxItem;
     init(): void;
     createDom_(): HTMLDivElement;
     createIconDom_(): HTMLSpanElement;

package/core/toolbox/separator.d.ts

@@ -15,7 +15,7 @@ export declare class ToolboxSeparator extends ToolboxItem {
     static registrationName: string;
     /** All the CSS class names that are used to create a separator. */
     protected cssConfig_: CssConfig;
-    private htmlDiv_;
+    private htmlDiv;
     /**
      * @param separatorDef The information needed to create a separator.
      * @param toolbox The parent toolbox for the separator.

package/core/toolbox/toolbox.d.ts

@@ -29,25 +29,22 @@ export declare class Toolbox extends DeleteArea implements IAutoHideable, IKeybo
      */
     id: string;
     protected toolboxDef_: toolbox.ToolboxInfo;
-    private readonly horizontalLayout_;
+    private readonly horizontalLayout;
     /** The HTML container for the toolbox. */
     HtmlDiv: HTMLDivElement | null;
     /** The HTML container for the contents of a toolbox. */
     protected contentsDiv_: HTMLDivElement | null;
     /** Whether the Toolbox is visible. */
     protected isVisible_: boolean;
-    /** The list of items in the toolbox. */
-    protected contents_: IToolboxItem[];
     /** The width of the toolbox. */
     protected width_: number;
     /** The height of the toolbox. */
     protected height_: number;
     RTL: boolean;
     /** The flyout for the toolbox. */
-    private flyout_;
-    protected contentMap_: {
-        [key: string]: IToolboxItem;
-    };
+    private flyout;
+    /** Map from ID to the corresponding toolbox item. */
+    protected contents: Map<string, IToolboxItem>;
     toolboxPosition: toolbox.Position;
     /** The currently selected item. */
     protected selectedItem_: ISelectableToolboxItem | null;
@@ -140,7 +137,7 @@ export declare class Toolbox extends DeleteArea implements IAutoHideable, IKeybo
      *     the toolbox.
      * @param fragment The document fragment to add the child toolbox elements to.
      */
-    private createToolboxItem_;
+    private createToolboxItem;
     /**
      * Adds an item to the toolbox.
      *
@@ -364,32 +361,32 @@ export declare class Toolbox extends DeleteArea implements IAutoHideable, IKeybo
      * @param oldItem The previously selected toolbox item.
      * @param newItem The newly selected toolbox item.
      */
-    private fireSelectEvent_;
+    private fireSelectEvent;
     /**
      * Closes the current item if it is expanded, or selects the parent.
      *
      * @returns True if a parent category was selected, false otherwise.
      */
-    private selectParent_;
+    private selectParent;
     /**
      * Selects the first child of the currently selected item, or nothing if the
      * toolbox item has no children.
      *
      * @returns True if a child category was selected, false otherwise.
      */
-    private selectChild_;
+    private selectChild;
     /**
      * Selects the next visible toolbox item.
      *
      * @returns True if a next category was selected, false otherwise.
      */
-    private selectNext_;
+    private selectNext;
     /**
      * Selects the previous visible toolbox item.
      *
      * @returns True if a previous category was selected, false otherwise.
      */
-    private selectPrevious_;
+    private selectPrevious;
     /** Disposes of this toolbox. */
     dispose(): void;
 }

package/core/variable_map.d.ts

@@ -11,17 +11,18 @@
 import './events/events_var_delete.js';
 import './events/events_var_rename.js';
 import type { Block } from './block.js';
-import { VariableModel } from './variable_model.js';
+import type { IVariableMap } from './interfaces/i_variable_map.js';
+import { IVariableModel, IVariableState } from './interfaces/i_variable_model.js';
 import type { Workspace } from './workspace.js';
 /**
  * Class for a variable map.  This contains a dictionary data structure with
  * variable types as keys and lists of variables as values.  The list of
  * variables are the type indicated by the key.
  */
-export declare class VariableMap {
+export declare class VariableMap implements IVariableMap<IVariableModel<IVariableState>> {
     workspace: Workspace;
     /**
-     * A map from variable type to list of variable names.  The lists contain
+     * A map from variable type to map of IDs to variables. The maps contain
      * all of the named variables in the workspace, including variables that are
      * not currently in use.
      */
@@ -35,13 +36,15 @@ export declare class VariableMap {
      *
      * @param variable Variable to rename.
      * @param newName New variable name.
-     * @internal
+     * @returns The newly renamed variable.
      */
-    renameVariable(variable: VariableModel, newName: string): void;
+    renameVariable(variable: IVariableModel<IVariableState>, newName: string): IVariableModel<IVariableState>;
+    changeVariableType(variable: IVariableModel<IVariableState>, newType: string): IVariableModel<IVariableState>;
     /**
      * Rename a variable by updating its name in the variable map. Identify the
      * variable to rename with the given ID.
      *
+     * @deprecated v12, use VariableMap.renameVariable.
      * @param id ID of the variable to rename.
      * @param newName New variable name.
      */
@@ -54,7 +57,7 @@ export declare class VariableMap {
      * @param newName New variable name.
      * @param blocks The list of all blocks in the workspace.
      */
-    private renameVariableAndUses_;
+    private renameVariableAndUses;
     /**
      * Update the name of the given variable to the same name as an existing
      * variable.  The two variables are coalesced into a single variable with the
@@ -66,7 +69,7 @@ export declare class VariableMap {
      * @param conflictVar The variable that was already using newName.
      * @param blocks The list of all blocks in the workspace.
      */
-    private renameVariableWithConflict_;
+    private renameVariableWithConflict;
     /**
      * Create a variable with a given name, optional type, and optional ID.
      *
@@ -78,29 +81,27 @@ export declare class VariableMap {
      * @param opt_id The unique ID of the variable. This will default to a UUID.
      * @returns The newly created variable.
      */
-    createVariable(name: string, opt_type?: string | null, opt_id?: string | null): VariableModel;
+    createVariable(name: string, opt_type?: string, opt_id?: string): IVariableModel<IVariableState>;
     /**
-     * Delete a variable.
+     * Adds the given variable to this variable map.
+     *
+     * @param variable The variable to add.
+     */
+    addVariable(variable: IVariableModel<IVariableState>): void;
+    /**
+     * Delete a variable and all of its uses without confirmation.
      *
      * @param variable Variable to delete.
      */
-    deleteVariable(variable: VariableModel): void;
+    deleteVariable(variable: IVariableModel<IVariableState>): void;
     /**
      * Delete a variables by the passed in ID and all of its uses from this
      * workspace. May prompt the user for confirmation.
      *
+     * @deprecated v12, use Blockly.Variables.deleteVariable.
      * @param id ID of variable to delete.
      */
     deleteVariableById(id: string): void;
-    /**
-     * Deletes a variable and all of its uses from this workspace without asking
-     * the user for confirmation.
-     *
-     * @param variable Variable to delete.
-     * @param uses An array of uses of the variable.
-     * @internal
-     */
-    deleteVariableInternal(variable: VariableModel, uses: Block[]): void;
     /**
      * Find the variable by the given name and type and return it.  Return null if
      *     it is not found.
@@ -110,14 +111,14 @@ export declare class VariableMap {
      *     the empty string, which is a specific type.
      * @returns The variable with the given name, or null if it was not found.
      */
-    getVariable(name: string, opt_type?: string | null): VariableModel | null;
+    getVariable(name: string, opt_type?: string): IVariableModel<IVariableState> | null;
     /**
      * Find the variable by the given ID and return it.  Return null if not found.
      *
      * @param id The ID to check for.
      * @returns The variable with the given ID.
      */
-    getVariableById(id: string): VariableModel | null;
+    getVariableById(id: string): IVariableModel<IVariableState> | null;
     /**
      * Get a list containing all of the variables of a specified type. If type is
      *     null, return list of variables with empty string type.
@@ -126,33 +127,30 @@ export declare class VariableMap {
      * @returns The sought after variables of the passed in type. An empty array
      *     if none are found.
      */
-    getVariablesOfType(type: string | null): VariableModel[];
+    getVariablesOfType(type: string | null): IVariableModel<IVariableState>[];
     /**
-     * Return all variable and potential variable types.  This list always
-     * contains the empty string.
+     * Returns a list of unique types of variables in this variable map.
      *
-     * @param ws The workspace used to look for potential variables. This can be
-     *     different than the workspace stored on this object if the passed in ws
-     *     is a flyout workspace.
-     * @returns List of variable types.
-     * @internal
+     * @returns A list of unique types of variables in this variable map.
      */
-    getVariableTypes(ws: Workspace | null): string[];
+    getTypes(): string[];
     /**
      * Return all variables of all types.
      *
      * @returns List of variable models.
      */
-    getAllVariables(): VariableModel[];
+    getAllVariables(): IVariableModel<IVariableState>[];
     /**
      * Returns all of the variable names of all types.
      *
+     * @deprecated v12, use Blockly.Variables.getAllVariables.
      * @returns All of the variable names of all types.
      */
     getAllVariableNames(): string[];
     /**
      * Find all the uses of a named variable.
      *
+     * @deprecated v12, use Blockly.Variables.getVariableUsesById.
      * @param id ID of the variable to find.
      * @returns Array of block usages.
      */

package/core/variable_model.d.ts

@@ -9,6 +9,7 @@
  * @class
  */
 import './events/events_var_create.js';
+import { IVariableModel, IVariableState } from './interfaces/i_variable_model.js';
 import type { Workspace } from './workspace.js';
 /**
  * Class for a variable model.
@@ -16,11 +17,11 @@ import type { Workspace } from './workspace.js';
  *
  * @see {Blockly.FieldVariable}
  */
-export declare class VariableModel {
-    workspace: Workspace;
-    name: string;
-    type: string;
-    private readonly id_;
+export declare class VariableModel implements IVariableModel<IVariableState> {
+    private readonly workspace;
+    private name;
+    private type;
+    private readonly id;
     /**
      * @param workspace The variable's workspace.
      * @param name The name of the variable.  This is the user-visible name (e.g.
@@ -33,15 +34,40 @@ export declare class VariableModel {
     constructor(workspace: Workspace, name: string, opt_type?: string, opt_id?: string);
     /** @returns The ID for the variable. */
     getId(): string;
+    /** @returns The name of this variable. */
+    getName(): string;
     /**
-     * A custom compare function for the VariableModel objects.
+     * Updates the user-visible name of this variable.
      *
-     * @param var1 First variable to compare.
-     * @param var2 Second variable to compare.
-     * @returns -1 if name of var1 is less than name of var2, 0 if equal, and 1 if
-     *     greater.
-     * @internal
+     * @returns The newly-updated variable.
      */
-    static compareByName(var1: VariableModel, var2: VariableModel): number;
+    setName(newName: string): this;
+    /** @returns The type of this variable. */
+    getType(): string;
+    /**
+     * Updates the type of this variable.
+     *
+     * @returns The newly-updated variable.
+     */
+    setType(newType: string): this;
+    /**
+     * Returns the workspace this VariableModel belongs to.
+     *
+     * @returns The workspace this VariableModel belongs to.
+     */
+    getWorkspace(): Workspace;
+    /**
+     * Serializes this VariableModel.
+     *
+     * @returns a JSON representation of this VariableModel.
+     */
+    save(): IVariableState;
+    /**
+     * Loads the persisted state into a new variable in the given workspace.
+     *
+     * @param state The serialized state of a variable model from save().
+     * @param workspace The workspace to create the new variable in.
+     */
+    static load(state: IVariableState, workspace: Workspace): void;
 }
 //# sourceMappingURL=variable_model.d.ts.map