blockly 12.4.0 → 12.5.0

package/core/interfaces/i_metrics_manager.d.ts

@@ -0,0 +1,129 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { AbsoluteMetrics, ContainerRegion, ToolboxMetrics, UiMetrics } from '../metrics_manager.js';
+import type { Metrics } from '../utils/metrics.js';
+import type { Size } from '../utils/size.js';
+/**
+ * Interface for a metrics manager.
+ */
+export interface IMetricsManager {
+    /**
+     * Returns whether the scroll area has fixed edges.
+     *
+     * @returns Whether the scroll area has fixed edges.
+     * @internal
+     */
+    hasFixedEdges(): boolean;
+    /**
+     * 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;
+    /**
+     * 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 IMetricsManager.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 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.
+     * .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.
+     * .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;
+    /**
+     * Returns common metrics used by UI elements.
+     *
+     * @returns The UI metrics.
+     */
+    getUiMetrics(): UiMetrics;
+}
+//# sourceMappingURL=i_metrics_manager.d.ts.map

package/core/interfaces/i_movable.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @license
+ * Copyright 2019 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * The interface for an object that is movable.
+ */
+export interface IMovable {
+    /**
+     * Get whether this is movable or not.
+     *
+     * @returns True if movable.
+     */
+    isMovable(): boolean;
+}
+//# sourceMappingURL=i_movable.d.ts.map

package/core/interfaces/i_navigation_policy.d.ts

@@ -0,0 +1,63 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { IFocusableNode } from './i_focusable_node.js';
+/**
+ * A set of rules that specify where keyboard navigation should proceed.
+ */
+export interface INavigationPolicy<T> {
+    /**
+     * Returns the first child element of the given element, if any.
+     *
+     * @param current The element which the user is navigating into.
+     * @returns The current element's first child, or null if it has none.
+     */
+    getFirstChild(current: T): IFocusableNode | null;
+    /**
+     * Returns the parent element of the given element, if any.
+     *
+     * @param current The element which the user is navigating out of.
+     * @returns The parent element of the current element, or null if it has none.
+     */
+    getParent(current: T): IFocusableNode | null;
+    /**
+     * Returns the peer element following the given element, if any.
+     *
+     * @param current The element which the user is navigating past.
+     * @returns The next peer element of the current element, or null if there is
+     *     none.
+     */
+    getNextSibling(current: T): IFocusableNode | null;
+    /**
+     * Returns the peer element preceding the given element, if any.
+     *
+     * @param current The element which the user is navigating past.
+     * @returns The previous peer element of the current element, or null if
+     *     there is none.
+     */
+    getPreviousSibling(current: T): IFocusableNode | null;
+    /**
+     * Returns whether or not the given instance should be reachable via keyboard
+     * navigation.
+     *
+     * Implementors should generally return true, unless there are circumstances
+     * under which this item should be skipped while using keyboard navigation.
+     * Common examples might include being disabled, invalid, readonly, or purely
+     * a visual decoration. For example, while Fields are navigable, non-editable
+     * fields return false, since they cannot be interacted with when focused.
+     *
+     * @returns True if this element should be included in keyboard navigation.
+     */
+    isNavigable(current: T): boolean;
+    /**
+     * Returns whether or not this navigation policy corresponds to the type of
+     * the given object.
+     *
+     * @param current An instance to check whether this policy applies to.
+     * @returns True if the given object is of a type handled by this policy.
+     */
+    isApplicable(current: any): current is T;
+}
+//# sourceMappingURL=i_navigation_policy.d.ts.map

package/core/interfaces/i_observable.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @license
+ * Copyright 2022 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * An object that fires events optionally.
+ *
+ * @internal
+ */
+export interface IObservable {
+    startPublishing(): void;
+    stopPublishing(): void;
+}
+/**
+ * Type guard for checking if an object fulfills IObservable.
+ *
+ * @internal
+ */
+export declare function isObservable(obj: any): obj is IObservable;
+//# sourceMappingURL=i_observable.d.ts.map

package/core/interfaces/i_parameter_model.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @license
+ * Copyright 2022 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { ParameterState } from '../serialization/procedures';
+import { IProcedureModel } from './i_procedure_model';
+/**
+ * A data model for a procedure.
+ */
+export interface IParameterModel {
+    /**
+     * Sets the name of this parameter to the given name.
+     */
+    setName(name: string): this;
+    /**
+     * Sets the types of this parameter to the given type.
+     */
+    setTypes(types: string[]): this;
+    /**
+     * Returns the name of this parameter.
+     */
+    getName(): string;
+    /**
+     * Return the types of this parameter.
+     */
+    getTypes(): string[];
+    /**
+     * Returns the unique language-neutral ID for the parameter.
+     *
+     * This represents the identify of the variable model which does not change
+     * over time.
+     */
+    getId(): string;
+    /** Sets the procedure model this parameter is associated with. */
+    setProcedureModel(model: IProcedureModel): this;
+    /**
+     * Serializes the state of the parameter to JSON.
+     *
+     * @returns JSON serializable state of the parameter.
+     */
+    saveState(): ParameterState;
+}
+//# sourceMappingURL=i_parameter_model.d.ts.map

package/core/interfaces/i_paster.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Coordinate } from '../utils/coordinate.js';
+import { WorkspaceSvg } from '../workspace_svg.js';
+import { ICopyable, ICopyData } from './i_copyable.js';
+/** An object that can paste data into a workspace. */
+export interface IPaster<U extends ICopyData, T extends ICopyable<U>> {
+    paste(copyData: U, workspace: WorkspaceSvg, coordinate?: Coordinate): T | null;
+}
+/** @returns True if the given object is a paster. */
+export declare function isPaster(obj: any): obj is IPaster<ICopyData, ICopyable<ICopyData>>;
+//# sourceMappingURL=i_paster.d.ts.map

package/core/interfaces/i_positionable.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { UiMetrics } from '../metrics_manager.js';
+import type { Rect } from '../utils/rect.js';
+import type { IComponent } from './i_component.js';
+/**
+ * Interface for a component that is positioned on top of the workspace.
+ */
+export interface IPositionable extends IComponent {
+    /**
+     * Positions the element. Called when the window is resized.
+     *
+     * @param metrics The workspace metrics.
+     * @param savedPositions List of rectangles that are already on the workspace.
+     */
+    position(metrics: UiMetrics, savedPositions: Rect[]): void;
+    /**
+     * Returns the bounding rectangle of the UI element in pixel units relative to
+     * the Blockly injection div.
+     *
+     * @returns The UI elements's bounding box. Null if bounding box should be
+     *     ignored by other UI elements.
+     */
+    getBoundingRectangle(): Rect | null;
+}
+//# sourceMappingURL=i_positionable.d.ts.map

package/core/interfaces/i_procedure_block.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @license
+ * Copyright 2022 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { Block } from '../block.js';
+import { IProcedureModel } from './i_procedure_model.js';
+/** The interface for a block which models a procedure. */
+export interface IProcedureBlock {
+    getProcedureModel(): IProcedureModel;
+    doProcedureUpdate(): void;
+    isProcedureDef(): boolean;
+}
+/** A type guard which checks if the given block is a procedure block. */
+export declare function isProcedureBlock(block: Block | IProcedureBlock): block is IProcedureBlock;
+//# sourceMappingURL=i_procedure_block.d.ts.map

package/core/interfaces/i_procedure_map.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @license
+ * Copyright 2022 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { IProcedureModel } from './i_procedure_model.js';
+export interface IProcedureMap extends Map<string, IProcedureModel> {
+    /**
+     * 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=i_procedure_map.d.ts.map

package/core/interfaces/i_procedure_model.d.ts

@@ -0,0 +1,59 @@
+/**
+ * @license
+ * Copyright 2022 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { State } from '../serialization/procedures.js';
+import { IParameterModel } from './i_parameter_model.js';
+/**
+ * A data model for a procedure.
+ */
+export interface IProcedureModel {
+    /** Sets the human-readable name of the procedure. */
+    setName(name: string): this;
+    /**
+     * Inserts a parameter into the list of parameters.
+     *
+     * To move a parameter, first delete it, and then re-insert.
+     */
+    insertParameter(parameterModel: IParameterModel, index: number): this;
+    /** Removes the parameter at the given index from the parameter list. */
+    deleteParameter(index: number): this;
+    /**
+     * Sets the return type(s) of the procedure.
+     *
+     * Pass null to represent a procedure that does not return.
+     */
+    setReturnTypes(types: string[] | null): this;
+    /**
+     * Sets whether this procedure is enabled/disabled. If a procedure is disabled
+     * all procedure caller blocks should be disabled as well.
+     */
+    setEnabled(enabled: boolean): this;
+    /** Returns the unique language-neutral ID for the procedure. */
+    getId(): string;
+    /** Returns the human-readable name of the procedure. */
+    getName(): string;
+    /** Returns the parameter at the given index in the parameter list. */
+    getParameter(index: number): IParameterModel;
+    /** Returns an array of all of the parameters in the parameter list. */
+    getParameters(): IParameterModel[];
+    /**
+     * Returns the return type(s) of the procedure.
+     *
+     * Null represents a procedure that does not return a value.
+     */
+    getReturnTypes(): string[] | null;
+    /**
+     * Returns whether the procedure is enabled/disabled. If a procedure is
+     * disabled, all procedure caller blocks should be disabled as well.
+     */
+    getEnabled(): boolean;
+    /**
+     * Serializes the state of the procedure to JSON.
+     *
+     * @returns JSON serializable state of the procedure.
+     */
+    saveState(): State;
+}
+//# sourceMappingURL=i_procedure_model.d.ts.map

package/core/interfaces/i_registrable.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * The interface for a Blockly component that can be registered.
+ */
+export interface IRegistrable {
+}
+//# sourceMappingURL=i_registrable.d.ts.map

package/core/interfaces/i_rendered_element.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export interface IRenderedElement {
+    /**
+     * @returns The root SVG element of this rendered element.
+     */
+    getSvgRoot(): SVGElement;
+}
+/**
+ * @returns True if the given object is an IRenderedElement.
+ */
+export declare function isRenderedElement(obj: any): obj is IRenderedElement;
+//# sourceMappingURL=i_rendered_element.d.ts.map

package/core/interfaces/i_selectable.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @license
+ * Copyright 2019 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { Workspace } from '../workspace.js';
+import { IFocusableNode } from './i_focusable_node.js';
+/**
+ * The interface for an object that is selectable.
+ *
+ * Implementations are generally expected to use their implementations of
+ * onNodeFocus() and onNodeBlur() to call setSelected() with themselves and
+ * null, respectively, in order to ensure that selections are correctly updated
+ * and the selection change event is fired.
+ */
+export interface ISelectable extends IFocusableNode {
+    id: string;
+    workspace: Workspace;
+    /** Select this.  Highlight it visually. */
+    select(): void;
+    /** Unselect this.  Unhighlight it visually. */
+    unselect(): void;
+}
+/** Checks whether the given object is an ISelectable. */
+export declare function isSelectable(obj: any): obj is ISelectable;
+//# sourceMappingURL=i_selectable.d.ts.map

package/core/interfaces/i_selectable_toolbox_item.d.ts

@@ -0,0 +1,51 @@
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { FlyoutItemInfoArray } from '../utils/toolbox';
+import type { IToolboxItem } from './i_toolbox_item.js';
+/**
+ * Interface for an item in the toolbox that can be selected.
+ */
+export interface ISelectableToolboxItem extends IToolboxItem {
+    /**
+     * Gets the name of the toolbox item. Used for emitting events.
+     *
+     * @returns The name of the toolbox item.
+     */
+    getName(): string;
+    /**
+     * Gets the contents of the toolbox item. These are items that are meant to be
+     * displayed in the flyout.
+     *
+     * @returns The definition of items to be displayed in the flyout.
+     */
+    getContents(): FlyoutItemInfoArray | string;
+    /**
+     * Sets the current toolbox item as selected.
+     *
+     * @param _isSelected True if this category is selected, false otherwise.
+     */
+    setSelected(_isSelected: boolean): void;
+    /**
+     * Gets the HTML element that is clickable.
+     * The parent toolbox element receives clicks. The parent toolbox will add an
+     * ID to this element so it can pass the onClick event to the correct
+     * toolboxItem.
+     *
+     * @returns The HTML element that receives clicks.
+     */
+    getClickTarget(): Element;
+    /**
+     * Handles when the toolbox item is clicked.
+     *
+     * @param _e Click event to handle.
+     */
+    onClick(_e: Event): void;
+}
+/**
+ * Type guard that checks whether an IToolboxItem is an ISelectableToolboxItem.
+ */
+export declare function isSelectableToolboxItem(toolboxItem: IToolboxItem): toolboxItem is ISelectableToolboxItem;
+//# sourceMappingURL=i_selectable_toolbox_item.d.ts.map

package/core/interfaces/i_serializable.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export interface ISerializable {
+    /**
+     * @param doFullSerialization If true, this signals that any backing data
+     *     structures used by this ISerializable should also be serialized. This
+     *     is used for copy-paste.
+     * @returns a JSON serializable value that records the ISerializable's state.
+     */
+    saveState(doFullSerialization: boolean): any;
+    /**
+     * Takes in a JSON serializable value and sets the ISerializable's state
+     * based on that.
+     *
+     * @param state The state to apply to the ISerializable.
+     */
+    loadState(state: any): void;
+}
+/** Type guard that checks whether the given object is a ISerializable. */
+export declare function isSerializable(obj: any): obj is ISerializable;
+//# sourceMappingURL=i_serializable.d.ts.map

package/core/interfaces/i_serializer.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { Workspace } from '../workspace.js';
+/**
+ * Serializes and deserializes a plugin or system.
+ */
+export interface ISerializer {
+    /**
+     * A priority value used to determine the order of deserializing state.
+     * More positive priorities are deserialized before less positive
+     * priorities. Eg if you have priorities (0, -10, 10, 100) the order of
+     * deserialiation will be (100, 10, 0, -10).
+     * If two serializers have the same priority, they are deserialized in an
+     * arbitrary order relative to each other.
+     */
+    priority: number;
+    /**
+     * Saves the state of the plugin or system.
+     *
+     * @param workspace The workspace the system to serialize is associated with.
+     * @returns A JS object containing the system's state, or null if there is no
+     *     state to record.
+     */
+    save(workspace: Workspace): object | null;
+    /**
+     * Loads the state of the plugin or system.
+     *
+     * @param state The state of the system to deserialize. This will always be
+     *     non-null.
+     * @param workspace The workspace the system to deserialize is associated
+     *     with.
+     */
+    load(state: object, workspace: Workspace): void;
+    /**
+     * Clears the state of the plugin or system.
+     *
+     * @param workspace The workspace the system to clear the state of is
+     *     associated with.
+     */
+    clear(workspace: Workspace): void;
+}
+//# sourceMappingURL=i_serializer.d.ts.map

package/core/interfaces/i_styleable.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Interface for an object that a style can be added to.
+ */
+export interface IStyleable {
+    /**
+     * Adds a style on the toolbox. Usually used to change the cursor.
+     *
+     * @param style The name of the class to add.
+     */
+    addStyle(style: string): void;
+    /**
+     * Removes a style from the toolbox. Usually used to change the cursor.
+     *
+     * @param style The name of the class to remove.
+     */
+    removeStyle(style: string): void;
+}
+//# sourceMappingURL=i_styleable.d.ts.map