blockly 8.0.5 → 9.0.0-beta.0

package/core/utils.ts

@@ -0,0 +1,428 @@
+/**
+ * @license
+ * Copyright 2012 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * @fileoverview Utility methods.
+ */
+
+/**
+ * Utility methods.
+ * @namespace Blockly.utils
+ */
+import * as goog from '../closure/goog/goog.js';
+goog.declareModuleId('Blockly.utils');
+
+import type {Block} from './block.js';
+import * as browserEvents from './browser_events.js';
+import * as common from './common.js';
+import * as extensions from './extensions.js';
+import * as aria from './utils/aria.js';
+import * as arrayUtils from './utils/array.js';
+import * as colour from './utils/colour.js';
+import {Coordinate} from './utils/coordinate.js';
+import * as deprecation from './utils/deprecation.js';
+import * as dom from './utils/dom.js';
+import * as idGenerator from './utils/idgenerator.js';
+import {KeyCodes} from './utils/keycodes.js';
+import * as math from './utils/math.js';
+import type {Metrics} from './utils/metrics.js';
+import * as object from './utils/object.js';
+import * as parsing from './utils/parsing.js';
+import {Rect} from './utils/rect.js';
+import {Size} from './utils/size.js';
+import * as stringUtils from './utils/string.js';
+import * as style from './utils/style.js';
+import {Svg} from './utils/svg.js';
+import * as svgMath from './utils/svg_math.js';
+import * as svgPaths from './utils/svg_paths.js';
+import * as toolbox from './utils/toolbox.js';
+import * as userAgent from './utils/useragent.js';
+import * as xml from './utils/xml.js';
+import type {WorkspaceSvg} from './workspace_svg.js';
+
+
+export {
+  aria,
+  arrayUtils as array,
+  browserEvents,
+  colour,
+  Coordinate,
+  deprecation,
+  dom,
+  extensions,
+  idGenerator,
+  KeyCodes,
+  math,
+  Metrics,
+  object,
+  parsing,
+  Rect,
+  Size,
+  stringUtils as string,
+  style,
+  Svg,
+  svgMath,
+  svgPaths,
+  toolbox,
+  userAgent,
+  xml
+};
+
+/**
+ * Halts the propagation of the event without doing anything else.
+ * @param e An event.
+ * @deprecated
+ * @alias Blockly.utils.noEvent
+ */
+export function noEvent(e: Event) {
+  // AnyDuringMigration because:  Property 'warn' does not exist on type 'void'.
+  (deprecation as AnyDuringMigration)
+      .warn('Blockly.utils.noEvent', 'September 2021', 'September 2022');
+  // This event has been handled.  No need to bubble up to the document.
+  e.preventDefault();
+  e.stopPropagation();
+}
+
+/**
+ * Returns true if this event is targeting a text input widget?
+ * @param e An event.
+ * @return True if text input.
+ * @deprecated Use Blockly.browserEvents.isTargetInput instead.
+ * @alias Blockly.utils.isTargetInput
+ */
+export function isTargetInput(e: Event): boolean {
+  // AnyDuringMigration because:  Property 'warn' does not exist on type 'void'.
+  (deprecation as AnyDuringMigration)
+      .warn(
+          'Blockly.utils.isTargetInput', 'September 2021', 'September 2022',
+          'Blockly.browserEvents.isTargetInput');
+  return browserEvents.isTargetInput(e);
+}
+
+/**
+ * Return the coordinates of the top-left corner of this element relative to
+ * its parent.  Only for SVG elements and children (e.g. rect, g, path).
+ * @param element SVG element to find the coordinates of.
+ * @return Object with .x and .y properties.
+ * @deprecated
+ * @alias Blockly.utils.getRelativeXY
+ */
+export function getRelativeXY(element: Element): Coordinate {
+  // AnyDuringMigration because:  Property 'warn' does not exist on type 'void'.
+  (deprecation as AnyDuringMigration)
+      .warn(
+          'Blockly.utils.getRelativeXY', 'December 2021', 'December 2022',
+          'Blockly.utils.svgMath.getRelativeXY');
+  // AnyDuringMigration because:  Property 'getRelativeXY' does not exist on
+  // type 'void'.
+  return (svgMath as AnyDuringMigration).getRelativeXY(element);
+}
+
+/**
+ * Return the coordinates of the top-left corner of this element relative to
+ * the div Blockly was injected into.
+ * @param element SVG element to find the coordinates of. If this is not a child
+ *     of the div Blockly was injected into, the behaviour is undefined.
+ * @return Object with .x and .y properties.
+ * @deprecated
+ * @alias Blockly.utils.getInjectionDivXY_
+ */
+function getInjectionDivXY(element: Element): Coordinate {
+  // AnyDuringMigration because:  Property 'warn' does not exist on type 'void'.
+  (deprecation as AnyDuringMigration)
+      .warn(
+          'Blockly.utils.getInjectionDivXY_', 'December 2021', 'December 2022',
+          'Blockly.utils.svgMath.getInjectionDivXY');
+  // AnyDuringMigration because:  Property 'getInjectionDivXY' does not exist on
+  // type 'void'.
+  return (svgMath as AnyDuringMigration).getInjectionDivXY(element);
+}
+export const getInjectionDivXY_ = getInjectionDivXY;
+
+/**
+ * Returns true this event is a right-click.
+ * @param e Mouse event.
+ * @return True if right-click.
+ * @deprecated Use Blockly.browserEvents.isRightButton instead.
+ * @alias Blockly.utils.isRightButton
+ */
+export function isRightButton(e: Event): boolean {
+  // AnyDuringMigration because:  Property 'warn' does not exist on type 'void'.
+  (deprecation as AnyDuringMigration)
+      .warn(
+          'Blockly.utils.isRightButton', 'September 2021', 'September 2022',
+          'Blockly.browserEvents.isRightButton');
+  return browserEvents.isRightButton(e as MouseEvent);
+}
+
+/**
+ * Returns the converted coordinates of the given mouse event.
+ * The origin (0,0) is the top-left corner of the Blockly SVG.
+ * @param e Mouse event.
+ * @param svg SVG element.
+ * @param matrix Inverted screen CTM to use.
+ * @return Object with .x and .y properties.
+ * @deprecated Use Blockly.browserEvents.mouseToSvg instead;
+ * @alias Blockly.utils.mouseToSvg
+ */
+export function mouseToSvg(
+    e: Event, svg: SVGSVGElement, matrix: SVGMatrix|null): SVGPoint {
+  // AnyDuringMigration because:  Property 'warn' does not exist on type 'void'.
+  (deprecation as AnyDuringMigration)
+      .warn(
+          'Blockly.utils.mouseToSvg', 'September 2021', 'September 2022',
+          'Blockly.browserEvents.mouseToSvg');
+  return browserEvents.mouseToSvg(e as MouseEvent, svg, matrix);
+}
+
+/**
+ * Returns the scroll delta of a mouse event in pixel units.
+ * @param e Mouse event.
+ * @return Scroll delta object with .x and .y properties.
+ * @deprecated Use Blockly.browserEvents.getScrollDeltaPixels instead.
+ * @alias Blockly.utils.getScrollDeltaPixels
+ */
+export function getScrollDeltaPixels(e: WheelEvent): {x: number, y: number} {
+  // AnyDuringMigration because:  Property 'warn' does not exist on type 'void'.
+  (deprecation as AnyDuringMigration)
+      .warn(
+          'Blockly.utils.getScrollDeltaPixels', 'September 2021',
+          'September 2022', 'Blockly.browserEvents.getScrollDeltaPixels');
+  return browserEvents.getScrollDeltaPixels(e);
+}
+
+/**
+ * Parse a string with any number of interpolation tokens (%1, %2, ...).
+ * It will also replace string table references (e.g., %{bky_my_msg} and
+ * %{BKY_MY_MSG} will both be replaced with the value in
+ * Msg['MY_MSG']). Percentage sign characters '%' may be self-escaped
+ * (e.g., '%%').
+ * @param message Text which might contain string table references and
+ *     interpolation tokens.
+ * @return Array of strings and numbers.
+ * @deprecated
+ * @alias Blockly.utils.tokenizeInterpolation
+ */
+export function tokenizeInterpolation(message: string): Array<string|number> {
+  // AnyDuringMigration because:  Property 'warn' does not exist on type 'void'.
+  (deprecation as AnyDuringMigration)
+      .warn(
+          'Blockly.utils.tokenizeInterpolation', 'December 2021',
+          'December 2022', 'Blockly.utils.parsing.tokenizeInterpolation');
+  // AnyDuringMigration because:  Property 'tokenizeInterpolation' does not
+  // exist on type 'void'.
+  return (parsing as AnyDuringMigration).tokenizeInterpolation(message);
+}
+
+/**
+ * Replaces string table references in a message, if the message is a string.
+ * For example, "%{bky_my_msg}" and "%{BKY_MY_MSG}" will both be replaced with
+ * the value in Msg['MY_MSG'].
+ * @param message Message, which may be a string that contains string table
+ *     references.
+ * @return String with message references replaced.
+ * @deprecated
+ * @alias Blockly.utils.replaceMessageReferences
+ */
+export function replaceMessageReferences(message: string|
+                                         AnyDuringMigration): string {
+  // AnyDuringMigration because:  Property 'warn' does not exist on type 'void'.
+  (deprecation as AnyDuringMigration)
+      .warn(
+          'Blockly.utils.replaceMessageReferences', 'December 2021',
+          'December 2022', 'Blockly.utils.parsing.replaceMessageReferences');
+  // AnyDuringMigration because:  Property 'replaceMessageReferences' does not
+  // exist on type 'void'.
+  return (parsing as AnyDuringMigration).replaceMessageReferences(message);
+}
+
+/**
+ * Validates that any %{MSG_KEY} references in the message refer to keys of
+ * the Msg string table.
+ * @param message Text which might contain string table references.
+ * @return True if all message references have matching values.
+ *     Otherwise, false.
+ * @deprecated
+ * @alias Blockly.utils.checkMessageReferences
+ */
+export function checkMessageReferences(message: string): boolean {
+  // AnyDuringMigration because:  Property 'warn' does not exist on type 'void'.
+  (deprecation as AnyDuringMigration)
+      .warn(
+          'Blockly.utils.checkMessageReferences', 'December 2021',
+          'December 2022', 'Blockly.utils.parsing.checkMessageReferences');
+  // AnyDuringMigration because:  Property 'checkMessageReferences' does not
+  // exist on type 'void'.
+  return (parsing as AnyDuringMigration).checkMessageReferences(message);
+}
+
+/**
+ * Generate a unique ID.
+ * @return A globally unique ID string.
+ * @deprecated Use Blockly.utils.idGenerator.genUid instead.
+ * @alias Blockly.utils.genUid
+ */
+export function genUid(): string {
+  // AnyDuringMigration because:  Property 'warn' does not exist on type 'void'.
+  (deprecation as AnyDuringMigration)
+      .warn(
+          'Blockly.utils.genUid', 'September 2021', 'September 2022',
+          'Blockly.utils.idGenerator.genUid');
+  // AnyDuringMigration because:  Property 'genUid' does not exist on type
+  // 'void'.
+  return (idGenerator as AnyDuringMigration).genUid();
+}
+
+/**
+ * Check if 3D transforms are supported by adding an element
+ * and attempting to set the property.
+ * @return True if 3D transforms are supported.
+ * @deprecated
+ * @alias Blockly.utils.is3dSupported
+ */
+export function is3dSupported(): boolean {
+  // AnyDuringMigration because:  Property 'warn' does not exist on type 'void'.
+  (deprecation as AnyDuringMigration)
+      .warn(
+          'Blockly.utils.is3dSupported', 'December 2021', 'December 2022',
+          'Blockly.utils.svgMath.is3dSupported');
+  // AnyDuringMigration because:  Property 'is3dSupported' does not exist on
+  // type 'void'.
+  return (svgMath as AnyDuringMigration).is3dSupported();
+}
+
+/**
+ * Get the position of the current viewport in window coordinates.  This takes
+ * scroll into account.
+ * @return An object containing window width, height, and scroll position in
+ *     window coordinates.
+ * @alias Blockly.utils.getViewportBBox
+ * @deprecated
+ * @internal
+ */
+export function getViewportBBox(): Rect {
+  // AnyDuringMigration because:  Property 'warn' does not exist on type 'void'.
+  (deprecation as AnyDuringMigration)
+      .warn(
+          'Blockly.utils.getViewportBBox', 'December 2021', 'December 2022',
+          'Blockly.utils.svgMath.getViewportBBox');
+  // AnyDuringMigration because:  Property 'getViewportBBox' does not exist on
+  // type 'void'.
+  return (svgMath as AnyDuringMigration).getViewportBBox();
+}
+
+/**
+ * Removes the first occurrence of a particular value from an array.
+ * @param arr Array from which to remove value.
+ * @param value Value to remove.
+ * @return True if an element was removed.
+ * @alias Blockly.utils.arrayRemove
+ * @deprecated
+ * @internal
+ */
+export function arrayRemove(
+    arr: AnyDuringMigration[], value: AnyDuringMigration): boolean {
+  // AnyDuringMigration because:  Property 'warn' does not exist on type 'void'.
+  (deprecation as AnyDuringMigration)
+      .warn('Blockly.utils.arrayRemove', 'December 2021', 'December 2022');
+  return arrayUtils.removeElem(arr, value);
+}
+
+/**
+ * Gets the document scroll distance as a coordinate object.
+ * Copied from Closure's goog.dom.getDocumentScroll.
+ * @return Object with values 'x' and 'y'.
+ * @deprecated
+ * @alias Blockly.utils.getDocumentScroll
+ */
+export function getDocumentScroll(): Coordinate {
+  // AnyDuringMigration because:  Property 'warn' does not exist on type 'void'.
+  (deprecation as AnyDuringMigration)
+      .warn(
+          'Blockly.utils.getDocumentScroll', 'December 2021', 'December 2022',
+          'Blockly.utils.svgMath.getDocumentScroll');
+  // AnyDuringMigration because:  Property 'getDocumentScroll' does not exist on
+  // type 'void'.
+  return (svgMath as AnyDuringMigration).getDocumentScroll();
+}
+
+/**
+ * Get a map of all the block's descendants mapping their type to the number of
+ *    children with that type.
+ * @param block The block to map.
+ * @param opt_stripFollowing Optionally ignore all following statements (blocks
+ *     that are not inside a value or statement input of the block).
+ * @return Map of types to type counts for descendants of the bock.
+ * @deprecated
+ * @alias Blockly.utils.getBlockTypeCounts
+ */
+export function getBlockTypeCounts(
+    block: Block, opt_stripFollowing?: boolean): AnyDuringMigration {
+  // AnyDuringMigration because:  Property 'warn' does not exist on type 'void'.
+  (deprecation as AnyDuringMigration)
+      .warn(
+          'Blockly.utils.getBlockTypeCounts', 'December 2021', 'December 2022',
+          'Blockly.common.getBlockTypeCounts');
+  return common.getBlockTypeCounts(block, opt_stripFollowing);
+}
+
+/**
+ * Converts screen coordinates to workspace coordinates.
+ * @param ws The workspace to find the coordinates on.
+ * @param screenCoordinates The screen coordinates to be converted to workspace
+ *     coordinates
+ * @deprecated
+ * @return The workspace coordinates.
+ */
+export function screenToWsCoordinates(
+    ws: WorkspaceSvg, screenCoordinates: Coordinate): Coordinate {
+  // AnyDuringMigration because:  Property 'warn' does not exist on type 'void'.
+  (deprecation as AnyDuringMigration)
+      .warn(
+          'Blockly.utils.screenToWsCoordinates', 'December 2021',
+          'December 2022', 'Blockly.utils.svgMath.screenToWsCoordinates');
+  // AnyDuringMigration because:  Property 'screenToWsCoordinates' does not
+  // exist on type 'void'.
+  return (svgMath as AnyDuringMigration)
+      .screenToWsCoordinates(ws, screenCoordinates);
+}
+
+/**
+ * Parse a block colour from a number or string, as provided in a block
+ * definition.
+ * @param colour HSV hue value (0 to 360), #RRGGBB string, or a message
+ *     reference string pointing to one of those two values.
+ * @return An object containing the colour as a #RRGGBB string, and the hue if
+ *     the input was an HSV hue value.
+ * @throws {Error} If the colour cannot be parsed.
+ * @deprecated
+ * @alias Blockly.utils.parseBlockColour
+ */
+export function parseBlockColour(colour: number|
+                                 string): {hue: number|null, hex: string} {
+  // AnyDuringMigration because:  Property 'warn' does not exist on type 'void'.
+  (deprecation as AnyDuringMigration)
+      .warn(
+          'Blockly.utils.parseBlockColour', 'December 2021', 'December 2022',
+          'Blockly.utils.parsing.parseBlockColour');
+  // AnyDuringMigration because:  Property 'parseBlockColour' does not exist on
+  // type 'void'.
+  return (parsing as AnyDuringMigration).parseBlockColour(colour);
+}
+
+/**
+ * Calls a function after the page has loaded, possibly immediately.
+ * @param fn Function to run.
+ * @throws Error Will throw if no global document can be found (e.g., Node.js).
+ * @deprecated
+ * @alias Blockly.utils.runAfterPageLoad
+ */
+export function runAfterPageLoad(fn: () => AnyDuringMigration) {
+  // AnyDuringMigration because:  Property 'warn' does not exist on type 'void'.
+  (deprecation as AnyDuringMigration)
+      .warn('Blockly.utils.runAfterPageLoad', 'December 2021', 'December 2022');
+  extensions.runAfterPageLoad(fn);
+}

package/core/variable_map.d.ts

@@ -0,0 +1,141 @@
+/**
+ * @license
+ * Copyright 2017 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import './events/events_var_delete.js';
+import './events/events_var_rename.js';
+import type { Block } from './block.js';
+import { VariableModel } from './variable_model.js';
+import type { Workspace } from './workspace.js';
+/**
+ * Class for a variable map.  This contains a dictionary data structure with
+ * variable types as keys and lists of variables as values.  The list of
+ * variables are the type indicated by the key.
+ * @alias Blockly.VariableMap
+ */
+export declare class VariableMap {
+    workspace: Workspace;
+    /**
+     * A map from variable type to list of variable names.  The lists contain
+     * all of the named variables in the workspace, including variables that are
+     * not currently in use.
+     */
+    private variableMap;
+    /** @param workspace The workspace this map belongs to. */
+    constructor(workspace: Workspace);
+    /** Clear the variable map. */
+    clear(): void;
+    /**
+     * Rename the given variable by updating its name in the variable map.
+     * @param variable Variable to rename.
+     * @param newName New variable name.
+     * @internal
+     */
+    renameVariable(variable: VariableModel, newName: string): void;
+    /**
+     * Rename a variable by updating its name in the variable map. Identify the
+     * variable to rename with the given ID.
+     * @param id ID of the variable to rename.
+     * @param newName New variable name.
+     */
+    renameVariableById(id: string, newName: string): void;
+    /**
+     * Update the name of the given variable and refresh all references to it.
+     * The new name must not conflict with any existing variable names.
+     * @param variable Variable to rename.
+     * @param newName New variable name.
+     * @param blocks The list of all blocks in the workspace.
+     */
+    private renameVariableAndUses_;
+    /**
+     * Update the name of the given variable to the same name as an existing
+     * variable.  The two variables are coalesced into a single variable with the
+     * ID of the existing variable that was already using newName. Refresh all
+     * references to the variable.
+     * @param variable Variable to rename.
+     * @param newName New variable name.
+     * @param conflictVar The variable that was already using newName.
+     * @param blocks The list of all blocks in the workspace.
+     */
+    private renameVariableWithConflict_;
+    /**
+     * Create a variable with a given name, optional type, and optional ID.
+     * @param name The name of the variable. This must be unique across variables
+     *     and procedures.
+     * @param opt_type The type of the variable like 'int' or 'string'.
+     *     Does not need to be unique. Field_variable can filter variables based
+     * on their type. This will default to '' which is a specific type.
+     * @param opt_id The unique ID of the variable. This will default to a UUID.
+     * @return The newly created variable.
+     */
+    createVariable(name: string, opt_type?: string | null, opt_id?: string | null): VariableModel;
+    /**
+     * Delete a variable.
+     * @param variable Variable to delete.
+     */
+    deleteVariable(variable: VariableModel): void;
+    /**
+     * Delete a variables by the passed in ID and all of its uses from this
+     * workspace. May prompt the user for confirmation.
+     * @param id ID of variable to delete.
+     */
+    deleteVariableById(id: string): void;
+    /**
+     * Deletes a variable and all of its uses from this workspace without asking
+     * the user for confirmation.
+     * @param variable Variable to delete.
+     * @param uses An array of uses of the variable.
+     * @internal
+     */
+    deleteVariableInternal(variable: VariableModel, uses: Block[]): void;
+    /**
+     * Find the variable by the given name and type and return it.  Return null if
+     *     it is not found.
+     * @param name The name to check for.
+     * @param opt_type The type of the variable.  If not provided it defaults to
+     *     the empty string, which is a specific type.
+     * @return The variable with the given name, or null if it was not found.
+     */
+    getVariable(name: string, opt_type?: string | null): VariableModel | null;
+    /**
+     * Find the variable by the given ID and return it.  Return null if not found.
+     * @param id The ID to check for.
+     * @return The variable with the given ID.
+     */
+    getVariableById(id: string): VariableModel | null;
+    /**
+     * Get a list containing all of the variables of a specified type. If type is
+     *     null, return list of variables with empty string type.
+     * @param type Type of the variables to find.
+     * @return The sought after variables of the passed in type. An empty array if
+     *     none are found.
+     */
+    getVariablesOfType(type: string | null): VariableModel[];
+    /**
+     * Return all variable and potential variable types.  This list always
+     * contains the empty string.
+     * @param ws The workspace used to look for potential variables. This can be
+     *     different than the workspace stored on this object if the passed in ws
+     *     is a flyout workspace.
+     * @return List of variable types.
+     * @internal
+     */
+    getVariableTypes(ws: Workspace | null): string[];
+    /**
+     * Return all variables of all types.
+     * @return List of variable models.
+     */
+    getAllVariables(): VariableModel[];
+    /**
+     * Returns all of the variable names of all types.
+     * @return All of the variable names of all types.
+     */
+    getAllVariableNames(): string[];
+    /**
+     * Find all the uses of a named variable.
+     * @param id ID of the variable to find.
+     * @return Array of block usages.
+     */
+    getVariableUsesById(id: string): Block[];
+}