blockly 8.20220331.0-beta.0 → 9.0.0-beta.1

package/core/metrics_manager.d.ts

@@ -0,0 +1,216 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { IFlyout } from './interfaces/i_flyout.js';
+import type { IMetricsManager } from './interfaces/i_metrics_manager.js';
+import type { IToolbox } from './interfaces/i_toolbox.js';
+import type { Metrics } from './utils/metrics.js';
+import { Size } from './utils/size.js';
+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 {
+    /** The workspace to calculate metrics for. */
+    protected readonly workspace_: WorkspaceSvg;
+    /** @param workspace The workspace to calculate metrics for. */
+    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().
+     * @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;
+    /**
+     * 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.
+     * @returns The width and height of the flyout.
+     */
+    getFlyoutMetrics(opt_own?: boolean): ToolboxMetrics;
+    /**
+     * 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 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.
+     *
+     * @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.
+     *
+     * @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.
+     * @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.
+     * @returns The metrics for the content container.
+     */
+    getContentMetrics(opt_getWorkspaceCoordinates?: boolean): ContainerRegion;
+    /**
+     * Returns 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.
+     * @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.
+     * @returns The padded content area.
+     */
+    protected getPaddedContent_(viewMetrics: ContainerRegion, contentMetrics: ContainerRegion): {
+        top: number;
+        bottom: number;
+        left: number;
+        right: number;
+    };
+    /**
+     * 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
+     *     computed. Passing in null may cause the view metrics to be computed
+     *     again, if it is needed.
+     * @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.
+     * @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.
+     *
+     * @returns The UI metrics.
+     */
+    getUiMetrics(): UiMetrics;
+    /**
+     * Returns an object with all the metrics required to size scrollbars for a
+     * top level workspace.  The following properties are computed:
+     * Coordinate system: pixel coordinates, -left, -up, +right, +down
+     * .viewHeight: Height of the visible portion of the workspace.
+     * .viewWidth: Width of the visible portion of the workspace.
+     * .contentHeight: Height of the content.
+     * .contentWidth: Width of the content.
+     * .scrollHeight: Height of the scroll area.
+     * .scrollWidth: Width of the scroll area.
+     * .svgHeight: Height of the Blockly div (the view + the toolbox,
+     *    simple or otherwise),
+     * .svgWidth: Width of the Blockly div (the view + the toolbox,
+     *    simple or otherwise),
+     * .viewTop: Top-edge of the visible portion of the workspace, relative to
+     *     the workspace origin.
+     * .viewLeft: Left-edge of the visible portion of the workspace, relative to
+     *     the workspace origin.
+     * .contentTop: Top-edge of the content, relative to the workspace origin.
+     * .contentLeft: Left-edge of the content relative to the workspace origin.
+     * .scrollTop: Top-edge of the scroll area, relative to the workspace origin.
+     * .scrollLeft: Left-edge of the scroll area relative to the workspace origin.
+     * .absoluteTop: Top-edge of the visible portion of the workspace, relative
+     *     to the blocklyDiv.
+     * .absoluteLeft: Left-edge of the visible portion of the workspace, relative
+     *     to the blocklyDiv.
+     * .toolboxWidth: Width of the toolbox, if it exists.  Otherwise zero.
+     * .toolboxHeight: Height of the toolbox, if it exists.  Otherwise zero.
+     * .flyoutWidth: Width of the flyout if it is always open.  Otherwise zero.
+     * .flyoutHeight: Height of the flyout if it is always open.  Otherwise zero.
+     * .toolboxPosition: Top, bottom, left or right. Use TOOLBOX_AT constants to
+     *     compare.
+     *
+     * @returns Contains size and position metrics of a top level workspace.
+     */
+    getMetrics(): Metrics;
+}
+export declare namespace MetricsManager {
+    /**
+     * Describes the width, height and location of the toolbox on the main
+     * workspace.
+     */
+    interface ToolboxMetrics {
+        width: number;
+        height: number;
+        position: toolboxUtils.Position;
+    }
+    /** Describes where the viewport starts in relation to the workspace SVG. */
+    interface AbsoluteMetrics {
+        left: number;
+        top: number;
+    }
+    /**
+     * All the measurements needed to describe the size and location of a
+     * container.
+     */
+    interface ContainerRegion {
+        height: number;
+        width: number;
+        top: number;
+        left: number;
+    }
+    /** Describes fixed edges of the workspace. */
+    interface FixedEdges {
+        top?: number;
+        bottom?: number;
+        left?: number;
+        right?: number;
+    }
+    /** Common metrics used for UI elements. */
+    interface UiMetrics {
+        viewMetrics: ContainerRegion;
+        absoluteMetrics: AbsoluteMetrics;
+        toolboxMetrics: ToolboxMetrics;
+    }
+}
+export declare type ToolboxMetrics = MetricsManager.ToolboxMetrics;
+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

@@ -0,0 +1,10 @@
+/**
+ * @license
+ * Copyright 2013 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/** A dictionary of localised messages. */
+export declare const Msg: {
+    [key: string]: string;
+};
+//# sourceMappingURL=msg.d.ts.map

package/core/mutator.d.ts

@@ -0,0 +1,140 @@
+/**
+ * @license
+ * Copyright 2012 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import './events/events_bubble_open.js';
+import type { Block } from './block.js';
+import type { BlockSvg } from './block_svg.js';
+import type { Connection } from './connection.js';
+import type { Abstract } from './events/events_abstract.js';
+import { Icon } from './icon.js';
+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 {
+    private quarkNames_;
+    /** Workspace in the mutator's bubble. */
+    private workspace_;
+    /** Width of workspace. */
+    private workspaceWidth_;
+    /** Height of workspace. */
+    private workspaceHeight_;
+    /**
+     * The SVG element that is the parent of the mutator workspace, or null if
+     * not created.
+     */
+    private svgDialog_;
+    /**
+     * The root block of the mutator workspace, created by decomposing the
+     * source block.
+     */
+    private rootBlock_;
+    /**
+     * Function registered on the main workspace to update the mutator contents
+     * when the main workspace changes.
+     */
+    private sourceListener_;
+    /**
+     * 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[]);
+    /**
+     * 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.
+     *
+     * @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.
+     *
+     * @returns The top-level node of the editor.
+     */
+    private createEditor_;
+    /**
+     * @internal
+     */
+    newWorkspaceSvg(options: Options): WorkspaceSvg;
+    /** Add or remove the UI indicating if this icon may be clicked or not. */
+    updateEditable(): void;
+    /** Resize the bubble to match the size of the workspace. */
+    private resizeBubble_;
+    /** A method handler for when the bubble is moved. */
+    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.
+     * @returns Whether to ignore the event or not.
+     */
+    shouldIgnoreMutatorEvent_(e: Abstract): boolean;
+    /**
+     * Updates the source block when the mutator's blocks are changed.
+     * Bump down any block that's too high.
+     */
+    private updateWorkspace_;
+    /** Dispose of this mutator. */
+    dispose(): void;
+    /** Update the styles on all blocks in the mutator. */
+    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.
+     * @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.
+     * @returns The mutator's parent workspace or null.
+     */
+    static findParentWs(workspace: WorkspaceSvg): WorkspaceSvg | null;
+}
+//# sourceMappingURL=mutator.d.ts.map

package/core/names.d.ts

@@ -0,0 +1,136 @@
+/**
+ * @license
+ * Copyright 2012 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+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 {
+    static DEVELOPER_VARIABLE_TYPE: NameType;
+    private readonly variablePrefix_;
+    /** A set of reserved words. */
+    private readonly reservedWords;
+    /**
+     * A map from type (e.g. name, procedure) to maps from names to generated
+     * names.
+     */
+    private readonly db;
+    /** A set of used names to avoid collisions. */
+    private readonly dbReverse;
+    /**
+     * The variable map from the workspace, containing Blockly variable models.
+     */
+    private variableMap_;
+    /**
+     * @param reservedWordsList A comma-separated string of words that are illegal
+     *     for use as names in a language (e.g. 'new,if,this,...').
+     * @param opt_variablePrefix Some languages need a '$' or a namespace before
+     *     all variable names (but not procedure names).
+     */
+    constructor(reservedWordsList: string, opt_variablePrefix?: string);
+    /**
+     * Empty the database and start from scratch.  The reserved words are kept.
+     */
+    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.
+     * @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...).
+     * @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...).
+     * @returns A list of Blockly entity names (no constraints).
+     */
+    getUserNames(type: NameType | string): string[];
+    /**
+     * Convert a Blockly entity name to a legal exportable entity name.
+     * 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...).
+     * @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.
+     * @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.
+     * @returns True if names are the same.
+     */
+    static equals(name1: string, name2: string): boolean;
+}
+export declare namespace Names {
+    /**
+     * Enum for the type of a name. Different name types may have different rules
+     * about collisions.
+     * When JavaScript (or most other languages) is generated, variable 'foo' and
+     * 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'
+     *
+     * @alias Blockly.Names.NameType
+     */
+    enum NameType {
+        DEVELOPER_VARIABLE = "DEVELOPER_VARIABLE",
+        VARIABLE = "VARIABLE",
+        PROCEDURE = "PROCEDURE"
+    }
+}
+export declare type NameType = Names.NameType;
+export declare const NameType: typeof Names.NameType;
+//# sourceMappingURL=names.d.ts.map

package/core/options.d.ts

@@ -0,0 +1,143 @@
+/**
+ * @license
+ * Copyright 2016 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { BlocklyOptions } from './blockly_options.js';
+import { Theme } from './theme.js';
+import type { Metrics } from './utils/metrics.js';
+import * as toolbox from './utils/toolbox.js';
+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 {
+    RTL: boolean;
+    oneBasedIndex: boolean;
+    collapse: boolean;
+    comments: boolean;
+    disable: boolean;
+    readOnly: boolean;
+    maxBlocks: number;
+    maxInstances: {
+        [key: string]: number;
+    } | null;
+    pathToMedia: string;
+    hasCategories: boolean;
+    moveOptions: MoveOptions;
+    hasScrollbars: boolean;
+    hasTrashcan: boolean;
+    maxTrashcanContents: number;
+    hasSounds: boolean;
+    hasCss: boolean;
+    horizontalLayout: boolean;
+    languageTree: toolbox.ToolboxInfo | null;
+    gridOptions: GridOptions;
+    zoomOptions: ZoomOptions;
+    toolboxPosition: toolbox.Position;
+    theme: Theme;
+    renderer: string;
+    rendererOverrides: {
+        [rendererConstant: string]: any;
+    } | null;
+    /**
+     * The SVG element for the grid pattern.
+     * Created during injection.
+     */
+    gridPattern: SVGElement | null;
+    parentWorkspace: WorkspaceSvg | null;
+    plugins: {
+        [key: string]: (new (...p1: any[]) => any) | string;
+    };
+    /**
+     * If set, sets the translation of the workspace to match the scrollbars.
+     * A function that
+     *     sets the translation of the workspace to match the scrollbars. The
+     *     argument Contains an x and/or y property which is a float between 0
+     *     and 1 specifying the degree of scrolling.
+     */
+    setMetrics?: ((p1: {
+        x?: number;
+        y?: number;
+    }) => void);
+    /**
+     * A function that returns a metrics
+     *     object that describes the current workspace.
+     */
+    getMetrics?: (() => Metrics);
+    /**
+     * @param options Dictionary of options.
+     *     Specification:
+     * https://developers.google.com/blockly/guides/get-started/web#configuration
+     */
+    constructor(options: BlocklyOptions);
+    /**
+     * 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.
+     * @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.
+     * @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.
+     * @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.
+     * @returns A Blockly Theme.
+     */
+    private static parseThemeOptions_;
+}
+export declare namespace Options {
+    interface GridOptions {
+        colour: string;
+        length: number;
+        snap: boolean;
+        spacing: number;
+    }
+    interface MoveOptions {
+        drag: boolean;
+        scrollbars: boolean | ScrollbarOptions;
+        wheel: boolean;
+    }
+    interface ScrollbarOptions {
+        horizontal: boolean;
+        vertical: boolean;
+    }
+    interface ZoomOptions {
+        controls: boolean;
+        maxScale: number;
+        minScale: number;
+        pinch: boolean;
+        scaleSpeed: number;
+        startScale: number;
+        wheel: boolean;
+    }
+}
+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