blockly 12.4.0 → 12.5.0

package/core/metrics_manager.d.ts

@@ -0,0 +1,221 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Calculates and reports workspace metrics.
+ *
+ * @class
+ */
+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.
+ */
+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 in pixel
+     * coordinates. By default, will get metrics for either a simple flyout (owned
+     * directly by the workspace) or for the flyout owned by the toolbox. If you
+     * pass `opt_own` as `true` then only metrics for the simple flyout will be
+     * returned, and it will return 0 for the width and height if the workspace
+     * has a category toolbox instead of a simple toolbox.
+     *
+     * @param opt_own Whether to only return the workspace's own flyout metrics.
+     * @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:class).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 type ToolboxMetrics = MetricsManager.ToolboxMetrics;
+export type AbsoluteMetrics = MetricsManager.AbsoluteMetrics;
+export type ContainerRegion = MetricsManager.ContainerRegion;
+export type FixedEdges = MetricsManager.FixedEdges;
+export type UiMetrics = MetricsManager.UiMetrics;
+//# sourceMappingURL=metrics_manager.d.ts.map

package/core/msg.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @license
+ * Copyright 2013 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/** A dictionary of localised messages. */
+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/names.d.ts

@@ -0,0 +1,139 @@
+/**
+ * @license
+ * Copyright 2012 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Utility functions for handling variable and procedure names.
+ *
+ * @class
+ */
+import type { IVariableMap } from './interfaces/i_variable_map.js';
+import type { IVariableModel, IVariableState } from './interfaces/i_variable_model.js';
+import type { Workspace } from './workspace.js';
+/**
+ * Class for a database of entity names (variables, procedures, etc).
+ */
+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: IVariableMap<IVariableModel<IVariableState>>): 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'
+     *
+     */
+    enum NameType {
+        DEVELOPER_VARIABLE = "DEVELOPER_VARIABLE",
+        VARIABLE = "VARIABLE",
+        PROCEDURE = "PROCEDURE"
+    }
+}
+export type NameType = Names.NameType;
+export declare const NameType: typeof Names.NameType;
+//# sourceMappingURL=names.d.ts.map

package/core/navigator.d.ts

@@ -0,0 +1,65 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { IFocusableNode } from './interfaces/i_focusable_node.js';
+import type { INavigationPolicy } from './interfaces/i_navigation_policy.js';
+type RuleList<T> = INavigationPolicy<T>[];
+/**
+ * Class responsible for determining where focus should move in response to
+ * keyboard navigation commands.
+ */
+export declare class Navigator {
+    /**
+     * Map from classes to a corresponding ruleset to handle navigation from
+     * instances of that class.
+     */
+    protected rules: RuleList<any>;
+    /**
+     * Adds a navigation ruleset to this Navigator.
+     *
+     * @param policy A ruleset that determines where focus should move starting
+     *     from an instance of its managed class.
+     */
+    addNavigationPolicy(policy: INavigationPolicy<any>): void;
+    /**
+     * Returns the navigation ruleset associated with the given object instance's
+     * class.
+     *
+     * @param current An object to retrieve a navigation ruleset for.
+     * @returns The navigation ruleset of objects of the given object's class, or
+     *     undefined if no ruleset has been registered for the object's class.
+     */
+    private get;
+    /**
+     * Returns the first child of the given object instance, if any.
+     *
+     * @param current The object to retrieve the first child of.
+     * @returns The first child node of the given object, if any.
+     */
+    getFirstChild(current: IFocusableNode): IFocusableNode | null;
+    /**
+     * Returns the parent of the given object instance, if any.
+     *
+     * @param current The object to retrieve the parent of.
+     * @returns The parent node of the given object, if any.
+     */
+    getParent(current: IFocusableNode): IFocusableNode | null;
+    /**
+     * Returns the next sibling of the given object instance, if any.
+     *
+     * @param current The object to retrieve the next sibling node of.
+     * @returns The next sibling node of the given object, if any.
+     */
+    getNextSibling(current: IFocusableNode): IFocusableNode | null;
+    /**
+     * Returns the previous sibling of the given object instance, if any.
+     *
+     * @param current The object to retrieve the previous sibling node of.
+     * @returns The previous sibling node of the given object, if any.
+     */
+    getPreviousSibling(current: IFocusableNode): IFocusableNode | null;
+}
+export {};
+//# sourceMappingURL=navigator.d.ts.map

package/core/observable_procedure_map.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @license
+ * Copyright 2022 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { IProcedureMap } from './interfaces/i_procedure_map.js';
+import type { IProcedureModel } from './interfaces/i_procedure_model.js';
+export declare class ObservableProcedureMap extends Map<string, IProcedureModel> implements IProcedureMap {
+    /** @internal */
+    constructor();
+    /**
+     * Adds the given procedure model to the procedure map.
+     */
+    set(id: string, proc: IProcedureModel): this;
+    /**
+     * Deletes the ProcedureModel with the given ID from the procedure map (if it
+     * exists).
+     */
+    delete(id: string): boolean;
+    /**
+     * Removes all ProcedureModels from the procedure map.
+     */
+    clear(): void;
+    /**
+     * Adds the given ProcedureModel to the map of procedure models, so that
+     * blocks can find it.
+     */
+    add(proc: IProcedureModel): this;
+    /**
+     * Returns all of the procedures stored in this map.
+     */
+    getProcedures(): IProcedureModel[];
+}
+//# sourceMappingURL=observable_procedure_map.d.ts.map

package/core/options.d.ts

@@ -0,0 +1,148 @@
+/**
+ * @license
+ * Copyright 2016 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Object that controls settings for the workspace.
+ *
+ * @class
+ */
+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.
+ */
+export declare class Options {
+    RTL: boolean;
+    oneBasedIndex: boolean;
+    collapse: boolean;
+    comments: boolean;
+    disable: boolean;
+    readOnly: boolean;
+    maxBlocks: number;
+    maxInstances: {
+        [key: string]: number;
+    } | null;
+    modalInputs: boolean;
+    pathToMedia: string;
+    hasCategories: boolean;
+    moveOptions: MoveOptions;
+    /** @deprecated  January 2019 */
+    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 type GridOptions = Options.GridOptions;
+export type MoveOptions = Options.MoveOptions;
+export type ScrollbarOptions = Options.ScrollbarOptions;
+export type ZoomOptions = Options.ZoomOptions;
+//# sourceMappingURL=options.d.ts.map