blockly 9.0.0-beta.0 → 9.0.0-beta.2

package/core/menu.d.ts

@@ -9,6 +9,7 @@ import { Coordinate } from './utils/coordinate.js';
 import type { Size } from './utils/size.js';
 /**
  * A basic menu class.
+ *
  * @alias Blockly.Menu
  */
 export declare class Menu {
@@ -47,23 +48,28 @@ export declare class Menu {
     constructor();
     /**
      * Add a new menu item to the bottom of this menu.
+     *
      * @param menuItem Menu item to append.
      * @internal
      */
     addChild(menuItem: MenuItem): void;
     /**
      * Creates the menu DOM.
+     *
      * @param container Element upon which to append this menu.
+     * @returns The menu's root DOM element.
      */
-    render(container: Element): void;
+    render(container: Element): HTMLDivElement;
     /**
      * Gets the menu's element.
-     * @return The DOM element.
+     *
+     * @returns The DOM element.
      * @internal
      */
-    getElement(): Element | null;
+    getElement(): HTMLDivElement | null;
     /**
      * Focus the menu element.
+     *
      * @internal
      */
     focus(): void;
@@ -71,6 +77,7 @@ export declare class Menu {
     private blur_;
     /**
      * Set the menu accessibility role.
+     *
      * @param roleName role name.
      * @internal
      */
@@ -80,12 +87,14 @@ export declare class Menu {
     /**
      * Returns the child menu item that owns the given DOM element,
      * or null if no such menu item is found.
+     *
      * @param elem DOM element whose owner is to be returned.
-     * @return Menu item for which the DOM element belongs to.
+     * @returns Menu item for which the DOM element belongs to.
      */
     private getMenuItem_;
     /**
      * Highlights the given menu item, or clears highlighting if null.
+     *
      * @param item Item to highlight, or null.
      * @internal
      */
@@ -93,12 +102,14 @@ export declare class Menu {
     /**
      * Highlights the next highlightable item (or the first if nothing is
      * currently highlighted).
+     *
      * @internal
      */
     highlightNext(): void;
     /**
      * Highlights the previous highlightable item (or the last if nothing is
      * currently highlighted).
+     *
      * @internal
      */
     highlightPrevious(): void;
@@ -109,41 +120,49 @@ export declare class Menu {
     /**
      * Helper function that manages the details of moving the highlight among
      * child menuitems in response to keyboard events.
+     *
      * @param startIndex Start index.
      * @param delta Step direction: 1 to go down, -1 to go up.
      */
     private highlightHelper_;
     /**
      * Handles mouseover events. Highlight menuitems as the user hovers over them.
+     *
      * @param e Mouse event to handle.
      */
     private handleMouseOver_;
     /**
      * Handles click events. Pass the event onto the child menuitem to handle.
+     *
      * @param e Click event to handle.
      */
     private handleClick_;
     /**
      * Handles mouse enter events. Focus the element.
+     *
      * @param _e Mouse event to handle.
      */
     private handleMouseEnter_;
     /**
      * Handles mouse leave events. Blur and clear highlight.
+     *
      * @param _e Mouse event to handle.
      */
     private handleMouseLeave_;
     /**
      * Attempts to handle a keyboard event, if the menu item is enabled, by
      * calling
-     * {@link handleKeyEventInternal_}.
+     * {@link Menu#handleKeyEventInternal_}.
+     *
      * @param e Key event to handle.
      */
     private handleKeyEvent_;
     /**
      * Get the size of a rendered menu.
-     * @return Object with width and height properties.
+     *
+     * @returns Object with width and height properties.
      * @internal
      */
     getSize(): Size;
 }
+//# sourceMappingURL=menu.d.ts.map

package/core/menuitem.d.ts

@@ -6,6 +6,7 @@
 import * as aria from './utils/aria.js';
 /**
  * Class representing an item in a menu.
+ *
  * @alias Blockly.MenuItem
  */
 export declare class MenuItem {
@@ -35,37 +36,43 @@ export declare class MenuItem {
     constructor(content: string | HTMLElement, opt_value?: string | undefined);
     /**
      * Creates the menuitem's DOM.
-     * @return Completed DOM.
+     *
+     * @returns Completed DOM.
      */
     createDom(): Element;
     /** Dispose of this menu item. */
     dispose(): void;
     /**
      * Gets the menu item's element.
-     * @return The DOM element.
+     *
+     * @returns The DOM element.
      * @internal
      */
     getElement(): Element | null;
     /**
      * Gets the unique ID for this menu item.
-     * @return Unique component ID.
+     *
+     * @returns Unique component ID.
      * @internal
      */
     getId(): string;
     /**
      * Gets the value associated with the menu item.
-     * @return value Value associated with the menu item.
+     *
+     * @returns value Value associated with the menu item.
      * @internal
      */
-    getValue(): any;
+    getValue(): string | null;
     /**
      * Set menu item's rendering direction.
+     *
      * @param rtl True if RTL, false if LTR.
      * @internal
      */
     setRightToLeft(rtl: boolean): void;
     /**
      * Set the menu item's accessibility role.
+     *
      * @param roleName Role name.
      * @internal
      */
@@ -73,30 +80,35 @@ export declare class MenuItem {
     /**
      * Sets the menu item to be checkable or not. Set to true for menu items
      * that represent checkable options.
+     *
      * @param checkable Whether the menu item is checkable.
      * @internal
      */
     setCheckable(checkable: boolean): void;
     /**
      * Checks or unchecks the component.
+     *
      * @param checked Whether to check or uncheck the component.
      * @internal
      */
     setChecked(checked: boolean): void;
     /**
      * Highlights or unhighlights the component.
+     *
      * @param highlight Whether to highlight or unhighlight the component.
      * @internal
      */
     setHighlighted(highlight: boolean): void;
     /**
      * Returns true if the menu item is enabled, false otherwise.
-     * @return Whether the menu item is enabled.
+     *
+     * @returns Whether the menu item is enabled.
      * @internal
      */
     isEnabled(): boolean;
     /**
      * Enables or disables the menu item.
+     *
      * @param enabled Whether to enable or disable the menu item.
      * @internal
      */
@@ -104,15 +116,18 @@ export declare class MenuItem {
     /**
      * Performs the appropriate action when the menu item is activated
      * by the user.
+     *
      * @internal
      */
     performAction(): void;
     /**
      * Set the handler that's called when the menu item is activated by the user.
      * `obj` will be used as the 'this' object in the function when called.
+     *
      * @param fn The handler.
      * @param obj Used as the 'this' object in fn when called.
      * @internal
      */
-    onAction(fn: (p1: MenuItem) => any, obj: any): void;
+    onAction(fn: (p1: MenuItem) => void, obj: object): void;
 }
+//# sourceMappingURL=menuitem.d.ts.map

package/core/metrics_manager.d.ts

@@ -12,6 +12,7 @@ import * as toolboxUtils from './utils/toolbox.js';
 import type { WorkspaceSvg } from './workspace_svg.js';
 /**
  * The manager for all workspace metrics calculations.
+ *
  * @alias Blockly.MetricsManager
  */
 export declare class MetricsManager implements IMetricsManager {
@@ -21,9 +22,10 @@ export declare class MetricsManager implements IMetricsManager {
     constructor(workspace: WorkspaceSvg);
     /**
      * Gets the dimensions of the given workspace component, in pixel coordinates.
+     *
      * @param elem The element to get the dimensions of, or null.  It should be a
      *     toolbox or flyout, and should implement getWidth() and getHeight().
-     * @return An object containing width and height attributes, which will both
+     * @returns An object containing width and height attributes, which will both
      *     be zero if elem did not exist.
      */
     protected getDimensionsPx_(elem: IToolbox | null | IFlyout): Size;
@@ -31,8 +33,9 @@ export declare class MetricsManager implements IMetricsManager {
      * 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.
+     *
      * @param opt_own Whether to only return the workspace's own flyout.
-     * @return The width and height of the flyout.
+     * @returns The width and height of the flyout.
      */
     getFlyoutMetrics(opt_own?: boolean): ToolboxMetrics;
     /**
@@ -40,60 +43,68 @@ export declare class MetricsManager implements IMetricsManager {
      * 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 getFlyoutMetrics}.
-     * @return The object with the width, height and position of the toolbox.
+     * simple toolbox @see {@link MetricsManager#getFlyoutMetrics}.
+     *
+     * @returns The object with the width, height and position of the toolbox.
      */
     getToolboxMetrics(): ToolboxMetrics;
     /**
      * Gets the width and height of the workspace's parent SVG element in pixel
      * coordinates. This area includes the toolbox and the visible workspace area.
-     * @return The width and height of the workspace's parent SVG element.
+     *
+     * @returns The width and height of the workspace's parent SVG element.
      */
     getSvgMetrics(): Size;
     /**
      * Gets the absolute left and absolute top in pixel coordinates.
      * This is where the visible workspace starts in relation to the SVG
      * container.
-     * @return The absolute metrics for the workspace.
+     *
+     * @returns The absolute metrics for the workspace.
      */
     getAbsoluteMetrics(): AbsoluteMetrics;
     /**
      * Gets the metrics for the visible workspace in either pixel or workspace
      * coordinates. The visible workspace does not include the toolbox or flyout.
+     *
      * @param opt_getWorkspaceCoordinates True to get the view metrics in
      *     workspace coordinates, false to get them in pixel coordinates.
-     * @return The width, height, top and left of the viewport in either workspace
-     *     coordinates or pixel coordinates.
+     * @returns The width, height, top and left of the viewport in either
+     *     workspace coordinates or pixel coordinates.
      */
     getViewMetrics(opt_getWorkspaceCoordinates?: boolean): ContainerRegion;
     /**
      * Gets content metrics in either pixel or workspace coordinates.
      * The content area is a rectangle around all the top bounded elements on the
      * workspace (workspace comments and blocks).
+     *
      * @param opt_getWorkspaceCoordinates True to get the content metrics in
      *     workspace coordinates, false to get them in pixel coordinates.
-     * @return The metrics for the content container.
+     * @returns The metrics for the content container.
      */
     getContentMetrics(opt_getWorkspaceCoordinates?: boolean): ContainerRegion;
     /**
      * Returns whether the scroll area has fixed edges.
-     * @return Whether the scroll area has fixed edges.
+     *
+     * @returns Whether the scroll area has fixed edges.
      * @internal
      */
     hasFixedEdges(): boolean;
     /**
      * Computes the fixed edges of the scroll area.
+     *
      * @param opt_viewMetrics The view metrics if they have been previously
      *     computed. Passing in null may cause the view metrics to be computed
      *     again, if it is needed.
-     * @return The fixed edges of the scroll area.
+     * @returns The fixed edges of the scroll area.
      */
     protected getComputedFixedEdges_(opt_viewMetrics?: ContainerRegion): FixedEdges;
     /**
      * Returns the content area with added padding.
+     *
      * @param viewMetrics The view metrics.
      * @param contentMetrics The content metrics.
-     * @return The padded content area.
+     * @returns The padded content area.
      */
     protected getPaddedContent_(viewMetrics: ContainerRegion, contentMetrics: ContainerRegion): {
         top: number;
@@ -103,6 +114,7 @@ export declare class MetricsManager implements IMetricsManager {
     };
     /**
      * Returns the metrics for the scroll area of the workspace.
+     *
      * @param opt_getWorkspaceCoordinates True to get the scroll metrics in
      *     workspace coordinates, false to get them in pixel coordinates.
      * @param opt_viewMetrics The view metrics if they have been previously
@@ -111,12 +123,13 @@ export declare class MetricsManager implements IMetricsManager {
      * @param opt_contentMetrics The content metrics if they have been previously
      *     computed. Passing in null may cause the content metrics to be computed
      *     again, if it is needed.
-     * @return The metrics for the scroll container.
+     * @returns The metrics for the scroll container.
      */
     getScrollMetrics(opt_getWorkspaceCoordinates?: boolean, opt_viewMetrics?: ContainerRegion, opt_contentMetrics?: ContainerRegion): ContainerRegion;
     /**
      * Returns common metrics used by UI elements.
-     * @return The UI metrics.
+     *
+     * @returns The UI metrics.
      */
     getUiMetrics(): UiMetrics;
     /**
@@ -151,7 +164,8 @@ export declare class MetricsManager implements IMetricsManager {
      * .flyoutHeight: Height of the flyout if it is always open.  Otherwise zero.
      * .toolboxPosition: Top, bottom, left or right. Use TOOLBOX_AT constants to
      *     compare.
-     * @return Contains size and position metrics of a top level workspace.
+     *
+     * @returns Contains size and position metrics of a top level workspace.
      */
     getMetrics(): Metrics;
 }
@@ -199,3 +213,4 @@ export declare type AbsoluteMetrics = MetricsManager.AbsoluteMetrics;
 export declare type ContainerRegion = MetricsManager.ContainerRegion;
 export declare type FixedEdges = MetricsManager.FixedEdges;
 export declare type UiMetrics = MetricsManager.UiMetrics;
+//# sourceMappingURL=metrics_manager.d.ts.map

package/core/msg.d.ts

@@ -7,3 +7,18 @@
 export declare const Msg: {
     [key: string]: string;
 };
+/**
+ * Sets the locale (i.e. the localized messages/block-text/etc) to the given
+ * locale.
+ *
+ * This is not useful/necessary when loading from a script tag, because the
+ * messages are automatically cluged into the Blockly.Msg object. But we provide
+ * it in both the script-tag and non-script-tag contexts so that the tscompiler
+ * can properly create our type definition files.
+ *
+ * @param locale An object defining the messages for a given language.
+ */
+export declare const setLocale: (locale: {
+    [key: string]: string;
+}) => void;
+//# sourceMappingURL=msg.d.ts.map

package/core/mutator.d.ts

@@ -13,10 +13,11 @@ import { Options } from './options.js';
 import type { WorkspaceSvg } from './workspace_svg.js';
 /**
  * Class for a mutator dialog.
+ *
  * @alias Blockly.Mutator
  */
 export declare class Mutator extends Icon {
-    quarkNames_: any;
+    private quarkNames_;
     /** Workspace in the mutator's bubble. */
     private workspace_;
     /** Width of workspace. */
@@ -39,39 +40,44 @@ export declare class Mutator extends Icon {
      */
     private sourceListener_;
     /**
-     * The PID associated with the updateWorkpace_ timeout, or 0 if no timeout
+     * The PID associated with the updateWorkpace_ timeout, or null if no timeout
      * is currently running.
      */
     private updateWorkspacePid_;
     /** @param quarkNames List of names of sub-blocks for flyout. */
-    constructor(block: BlockSvg, quarkNames: string[]);
+    constructor(quarkNames: string[], block?: BlockSvg);
     /**
      * Set the block this mutator is associated with.
+     *
      * @param block The block associated with this mutator.
      * @internal
      */
     setBlock(block: BlockSvg): void;
     /**
      * Returns the workspace inside this mutator icon's bubble.
-     * @return The workspace inside this mutator icon's bubble or null if the
+     *
+     * @returns The workspace inside this mutator icon's bubble or null if the
      *     mutator isn't open.
      * @internal
      */
     getWorkspace(): WorkspaceSvg | null;
     /**
      * Draw the mutator icon.
+     *
      * @param group The icon group.
      */
     protected drawIcon_(group: Element): void;
     /**
      * Clicking on the icon toggles if the mutator bubble is visible.
      * Disable if block is uneditable.
+     *
      * @param e Mouse click event.
      */
     protected iconClick_(e: MouseEvent): void;
     /**
      * Create the editor for the mutator's bubble.
-     * @return The top-level node of the editor.
+     *
+     * @returns The top-level node of the editor.
      */
     private createEditor_;
     /**
@@ -86,19 +92,22 @@ export declare class Mutator extends Icon {
     private onBubbleMove_;
     /**
      * Show or hide the mutator bubble.
+     *
      * @param visible True if the bubble should be visible.
      */
     setVisible(visible: boolean): void;
     /**
      * Fired whenever a change is made to the mutator's workspace.
+     *
      * @param e Custom data for event.
      */
     private workspaceChanged_;
     /**
      * Returns whether the given event in the mutator workspace should be ignored
      * when deciding whether to update the workspace and compose the block or not.
+     *
      * @param e The event.
-     * @return Whether to ignore the event or not.
+     * @returns Whether to ignore the event or not.
      */
     shouldIgnoreMutatorEvent_(e: Abstract): boolean;
     /**
@@ -112,17 +121,20 @@ export declare class Mutator extends Icon {
     updateBlockStyle(): void;
     /**
      * Reconnect an block to a mutated input.
+     *
      * @param connectionChild Connection on child block.
      * @param block Parent block.
      * @param inputName Name of input on parent block.
-     * @return True iff a reconnection was made, false otherwise.
+     * @returns True iff a reconnection was made, false otherwise.
      */
     static reconnect(connectionChild: Connection, block: Block, inputName: string): boolean;
     /**
      * Get the parent workspace of a workspace that is inside a mutator, taking
      * into account whether it is a flyout.
+     *
      * @param workspace The workspace that is inside a mutator.
-     * @return The mutator's parent workspace or null.
+     * @returns The mutator's parent workspace or null.
      */
     static findParentWs(workspace: WorkspaceSvg): WorkspaceSvg | null;
 }
+//# sourceMappingURL=mutator.d.ts.map

package/core/names.d.ts

@@ -7,6 +7,7 @@ import type { VariableMap } from './variable_map.js';
 import type { Workspace } from './workspace.js';
 /**
  * Class for a database of entity names (variables, procedures, etc).
+ *
  * @alias Blockly.Names
  */
 export declare class Names {
@@ -38,40 +39,46 @@ export declare class Names {
     reset(): void;
     /**
      * Set the variable map that maps from variable name to variable object.
+     *
      * @param map The map to track.
      */
     setVariableMap(map: VariableMap): void;
     /**
      * Get the name for a user-defined variable, based on its ID.
      * This should only be used for variables of NameType VARIABLE.
+     *
      * @param id The ID to look up in the variable map.
-     * @return The name of the referenced variable, or null if there was no
+     * @returns The name of the referenced variable, or null if there was no
      *     variable map or the variable was not found in the map.
      */
     private getNameForUserVariable_;
     /**
      * Generate names for user variables, but only ones that are being used.
+     *
      * @param workspace Workspace to generate variables from.
      */
     populateVariables(workspace: Workspace): void;
     /**
      * Generate names for procedures.
+     *
      * @param workspace Workspace to generate procedures from.
      */
     populateProcedures(workspace: Workspace): void;
     /**
      * Convert a Blockly entity name to a legal exportable entity name.
+     *
      * @param nameOrId The Blockly entity name (no constraints) or variable ID.
      * @param type The type of the name in Blockly ('VARIABLE', 'PROCEDURE',
      *     'DEVELOPER_VARIABLE', etc...).
-     * @return An entity name that is legal in the exported language.
+     * @returns An entity name that is legal in the exported language.
      */
     getName(nameOrId: string, type: NameType | string): string;
     /**
      * Return a list of all known user-created names of a specified name type.
+     *
      * @param type The type of entity in Blockly ('VARIABLE', 'PROCEDURE',
      *     'DEVELOPER_VARIABLE', etc...).
-     * @return A list of Blockly entity names (no constraints).
+     * @returns A list of Blockly entity names (no constraints).
      */
     getUserNames(type: NameType | string): string[];
     /**
@@ -79,26 +86,29 @@ export declare class Names {
      * Ensure that this is a new name not overlapping any previously defined name.
      * Also check against list of reserved words for the current language and
      * ensure name doesn't collide.
+     *
      * @param name The Blockly entity name (no constraints).
      * @param type The type of entity in Blockly ('VARIABLE', 'PROCEDURE',
      *     'DEVELOPER_VARIABLE', etc...).
-     * @return An entity name that is legal in the exported language.
+     * @returns An entity name that is legal in the exported language.
      */
     getDistinctName(name: string, type: NameType | string): string;
     /**
      * Given a proposed entity name, generate a name that conforms to the
      * [_A-Za-z][_A-Za-z0-9]* format that most languages consider legal for
      * variable and function names.
+     *
      * @param name Potentially illegal entity name.
-     * @return Safe entity name.
+     * @returns Safe entity name.
      */
     private safeName_;
     /**
      * Do the given two entity names refer to the same entity?
      * Blockly names are case-insensitive.
+     *
      * @param name1 First name.
      * @param name2 Second name.
-     * @return True if names are the same.
+     * @returns True if names are the same.
      */
     static equals(name1: string, name2: string): boolean;
 }
@@ -110,8 +120,9 @@ export declare namespace Names {
      * procedure 'foo' would collide.  However, Blockly has no such problems since
      * variable get 'foo' and procedure call 'foo' are unambiguous.
      * Therefore, Blockly keeps a separate name type to disambiguate.
-     * getName('foo', 'VARIABLE') -> 'foo'
-     * getName('foo', 'PROCEDURE') -> 'foo2'
+     * getName('foo', 'VARIABLE') = 'foo'
+     * getName('foo', 'PROCEDURE') = 'foo2'
+     *
      * @alias Blockly.Names.NameType
      */
     enum NameType {
@@ -122,3 +133,4 @@ export declare namespace Names {
 }
 export declare type NameType = Names.NameType;
 export declare const NameType: typeof Names.NameType;
+//# sourceMappingURL=names.d.ts.map

package/core/options.d.ts

@@ -11,6 +11,7 @@ import type { WorkspaceSvg } from './workspace_svg.js';
 /**
  * Parse the user-specified options, using reasonable defaults where behaviour
  * is unspecified.
+ *
  * @alias Blockly.Options
  */
 export declare class Options {
@@ -59,8 +60,8 @@ export declare class Options {
      *     and 1 specifying the degree of scrolling.
      */
     setMetrics?: ((p1: {
-        x: number;
-        y: number;
+        x?: number;
+        y?: number;
     }) => void);
     /**
      * A function that returns a metrics
@@ -76,32 +77,36 @@ export declare class Options {
     /**
      * Parse the user-specified move options, using reasonable defaults where
      *    behaviour is unspecified.
+     *
      * @param options Dictionary of options.
      * @param hasCategories Whether the workspace has categories or not.
-     * @return Normalized move options.
+     * @returns Normalized move options.
      */
     private static parseMoveOptions_;
     /**
      * Parse the user-specified zoom options, using reasonable defaults where
      * behaviour is unspecified.  See zoom documentation:
      *   https://developers.google.com/blockly/guides/configure/web/zoom
+     *
      * @param options Dictionary of options.
-     * @return Normalized zoom options.
+     * @returns Normalized zoom options.
      */
     private static parseZoomOptions_;
     /**
      * Parse the user-specified grid options, using reasonable defaults where
      * behaviour is unspecified. See grid documentation:
      *   https://developers.google.com/blockly/guides/configure/web/grid
+     *
      * @param options Dictionary of options.
-     * @return Normalized grid options.
+     * @returns Normalized grid options.
      */
     private static parseGridOptions_;
     /**
      * Parse the user-specified theme options, using the classic theme as a
      * default. https://developers.google.com/blockly/guides/configure/web/themes
+     *
      * @param options Dictionary of options.
-     * @return A Blockly Theme.
+     * @returns A Blockly Theme.
      */
     private static parseThemeOptions_;
 }
@@ -135,3 +140,4 @@ export declare type GridOptions = Options.GridOptions;
 export declare type MoveOptions = Options.MoveOptions;
 export declare type ScrollbarOptions = Options.ScrollbarOptions;
 export declare type ZoomOptions = Options.ZoomOptions;
+//# sourceMappingURL=options.d.ts.map