blockly 8.0.4 → 8.0.5-beta.0

package/core/utils/object.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @license
+ * Copyright 2019 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Inherit the prototype methods from one constructor into another.
+ * @param childCtor Child class.
+ * @param parentCtor Parent class.
+ * @suppress {strictMissingProperties} superClass_ is not defined on Function.
+ * @alias Blockly.utils.object.inherits
+ */
+export declare function inherits(childCtor: Function, parentCtor: Function): void;
+/**
+ * Copies all the members of a source object to a target object.
+ * @param target Target.
+ * @param source Source.
+ * @alias Blockly.utils.object.mixin
+ */
+export declare function mixin(target: any, source: any): void;
+/**
+ * Complete a deep merge of all members of a source object with a target object.
+ * @param target Target.
+ * @param source Source.
+ * @return The resulting object.
+ * @alias Blockly.utils.object.deepMerge
+ */
+export declare function deepMerge(target: any, source: any): any;
+/**
+ * Returns an array of a given object's own enumerable property values.
+ * @param obj Object containing values.
+ * @return Array of values.
+ * @alias Blockly.utils.object.values
+ */
+export declare function values(obj: any): any[];

package/core/utils/{object.js → object.ts}

@@ -7,27 +7,31 @@
 /**
  * @fileoverview Utility methods for objects.
  */
-'use strict';
 
 /**
  * Utility methods for objects.
  * @namespace Blockly.utils.object
  */
-goog.module('Blockly.utils.object');
+import * as goog from '../../closure/goog/goog.js';
+goog.declareModuleId('Blockly.utils.object');
+
+import * as deprecation from './deprecation.js';
 
 
 /**
  * Inherit the prototype methods from one constructor into another.
- * @param {!Function} childCtor Child class.
- * @param {!Function} parentCtor Parent class.
+ * @param childCtor Child class.
+ * @param parentCtor Parent class.
  * @suppress {strictMissingProperties} superClass_ is not defined on Function.
  * @alias Blockly.utils.object.inherits
  */
-const inherits = function(childCtor, parentCtor) {
+export function inherits(childCtor: Function, parentCtor: Function) {
   // Set a .superClass_ property so that methods can call parent methods
   // without hard-coding the parent class name.
   // Could be replaced by ES6's super().
-  childCtor.superClass_ = parentCtor.prototype;
+  // AnyDuringMigration because:  Property 'superClass_' does not exist on type
+  // 'Function'.
+  (childCtor as AnyDuringMigration).superClass_ = parentCtor.prototype;
 
   // Link the child class to the parent class so that static methods inherit.
   Object.setPrototypeOf(childCtor, parentCtor);
@@ -36,32 +40,34 @@ const inherits = function(childCtor, parentCtor) {
   // of the parent class.
   childCtor.prototype = Object.create(parentCtor.prototype);
   childCtor.prototype.constructor = childCtor;
-  // Alternatively, one could use this instead:
-  // Object.setPrototypeOf(childCtor.prototype, parentCtor.prototype);
-};
-exports.inherits = inherits;
+}
+// Alternatively, one could use this instead:
+// Object.setPrototypeOf(childCtor.prototype, parentCtor.prototype);
 
 /**
  * Copies all the members of a source object to a target object.
- * @param {!Object} target Target.
- * @param {!Object} source Source.
+ * @param target Target.
+ * @param source Source.
  * @alias Blockly.utils.object.mixin
  */
-const mixin = function(target, source) {
+export function mixin(target: AnyDuringMigration, source: AnyDuringMigration) {
+  deprecation.warn(
+      'Blockly.utils.object.mixin', 'May 2022', 'May 2023', 'Object.assign');
   for (const x in source) {
     target[x] = source[x];
   }
-};
-exports.mixin = mixin;
+}
 
 /**
  * Complete a deep merge of all members of a source object with a target object.
- * @param {!Object} target Target.
- * @param {!Object} source Source.
- * @return {!Object} The resulting object.
+ * @param target Target.
+ * @param source Source.
+ * @return The resulting object.
  * @alias Blockly.utils.object.deepMerge
  */
-const deepMerge = function(target, source) {
+export function deepMerge(
+    target: AnyDuringMigration,
+    source: AnyDuringMigration): AnyDuringMigration {
   for (const x in source) {
     if (source[x] !== null && typeof source[x] === 'object') {
       target[x] = deepMerge(target[x] || Object.create(null), source[x]);
@@ -70,16 +76,15 @@ const deepMerge = function(target, source) {
     }
   }
   return target;
-};
-exports.deepMerge = deepMerge;
+}
 
 /**
  * Returns an array of a given object's own enumerable property values.
- * @param {!Object} obj Object containing values.
- * @return {!Array} Array of values.
+ * @param obj Object containing values.
+ * @return Array of values.
  * @alias Blockly.utils.object.values
  */
-const values = function(obj) {
+export function values(obj: AnyDuringMigration): AnyDuringMigration[] {
   if (Object.values) {
     return Object.values(obj);
   }
@@ -87,5 +92,4 @@ const values = function(obj) {
   return Object.keys(obj).map(function(e) {
     return obj[e];
   });
-};
-exports.values = values;
+}

package/core/utils/parsing.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * 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.
+ * @alias Blockly.utils.parsing.tokenizeInterpolation
+ */
+export declare function tokenizeInterpolation(message: string): (string | number)[];
+/**
+ * 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.
+ * @alias Blockly.utils.parsing.replaceMessageReferences
+ */
+export declare function replaceMessageReferences(message: string | any): string;
+/**
+ * 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.
+ * @alias Blockly.utils.parsing.checkMessageReferences
+ */
+export declare function checkMessageReferences(message: string): boolean;
+/**
+ * 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.
+ * @alias Blockly.utils.parsing.parseBlockColour
+ */
+export declare function parseBlockColour(colour: number | string): {
+    hue: number | null;
+    hex: string;
+};

package/core/utils/{parsing.js → parsing.ts}

@@ -7,50 +7,51 @@
 /**
  * @fileoverview Utility methods related to block and message parsing.
  */
-'use strict';
 
 /**
  * @namespace Blockly.utils.parsing
  */
-goog.module('Blockly.utils.parsing');
+import * as goog from '../../closure/goog/goog.js';
+goog.declareModuleId('Blockly.utils.parsing');
 
-const colourUtils = goog.require('Blockly.utils.colour');
-const stringUtils = goog.require('Blockly.utils.string');
-const {Msg} = goog.require('Blockly.Msg');
+import {Msg} from '../msg.js';
+
+import * as colourUtils from './colour.js';
 
 
 /**
  * Internal implementation of the message reference and interpolation token
  * parsing used by tokenizeInterpolation() and replaceMessageReferences().
- * @param {string} message Text which might contain string table references and
+ * @param message Text which might contain string table references and
  *     interpolation tokens.
- * @param {boolean} parseInterpolationTokens Option to parse numeric
+ * @param parseInterpolationTokens Option to parse numeric
  *     interpolation tokens (%1, %2, ...) when true.
- * @return {!Array<string|number>} Array of strings and numbers.
+ * @return Array of strings and numbers.
  */
-const tokenizeInterpolationInternal = function(
-    message, parseInterpolationTokens) {
+function tokenizeInterpolationInternal(
+    message: string, parseInterpolationTokens: boolean): (string|number)[] {
   const tokens = [];
   const chars = message.split('');
-  chars.push('');  // End marker.
+  chars.push(  // End marker.
+      '');
   // Parse the message with a finite state machine.
   // 0 - Base case.
   // 1 - % found.
   // 2 - Digit found.
   // 3 - Message ref found.
   let state = 0;
-  const buffer = [];
+  const buffer = new Array<string>();
   let number = null;
   for (let i = 0; i < chars.length; i++) {
     const c = chars[i];
-    if (state === 0) {
+    if (state === 0) {  // Start escape.
       if (c === '%') {
         const text = buffer.join('');
         if (text) {
           tokens.push(text);
         }
         buffer.length = 0;
-        state = 1;  // Start escape.
+        state = 1;
       } else {
         buffer.push(c);  // Regular char.
       }
@@ -76,7 +77,7 @@ const tokenizeInterpolationInternal = function(
       if ('0' <= c && c <= '9') {
         number += c;  // Multi-digit number.
       } else {
-        tokens.push(parseInt(number, 10));
+        tokens.push(parseInt(number ?? '', 10));
         i--;  // Parse this char again.
         state = 0;
       }
@@ -94,16 +95,16 @@ const tokenizeInterpolationInternal = function(
           // Found a valid string key. Attempt case insensitive match.
           const keyUpper = rawKey.toUpperCase();
 
-          // BKY_ is the prefix used to namespace the strings used in Blockly
-          // core files and the predefined blocks in ../blocks/.
+          // BKY_ is the prefix used to namespace the strings used in
+          // Blockly core files and the predefined blocks in ../blocks/.
           // These strings are defined in ../msgs/ files.
-          const bklyKey = stringUtils.startsWith(keyUpper, 'BKY_') ?
-              keyUpper.substring(4) :
-              null;
+          const bklyKey =
+              keyUpper.startsWith('BKY_') ? keyUpper.substring(4) : null;
           if (bklyKey && bklyKey in Msg) {
             const rawValue = Msg[bklyKey];
             if (typeof rawValue === 'string') {
-              // Attempt to dereference substrings, too, appending to the end.
+              // Attempt to dereference substrings, too, appending to the
+              // end.
               Array.prototype.push.apply(
                   tokens,
                   tokenizeInterpolationInternal(
@@ -140,7 +141,7 @@ const tokenizeInterpolationInternal = function(
   buffer.length = 0;
   for (let i = 0; i < tokens.length; i++) {
     if (typeof tokens[i] === 'string') {
-      buffer.push(tokens[i]);
+      buffer.push(tokens[i] as string);
     } else {
       text = buffer.join('');
       if (text) {
@@ -157,7 +158,7 @@ const tokenizeInterpolationInternal = function(
   buffer.length = 0;
 
   return mergedTokens;
-};
+}
 
 /**
  * Parse a string with any number of interpolation tokens (%1, %2, ...).
@@ -165,26 +166,26 @@ const tokenizeInterpolationInternal = function(
  * %{BKY_MY_MSG} will both be replaced with the value in
  * Msg['MY_MSG']). Percentage sign characters '%' may be self-escaped
  * (e.g., '%%').
- * @param {string} message Text which might contain string table references and
+ * @param message Text which might contain string table references and
  *     interpolation tokens.
- * @return {!Array<string|number>} Array of strings and numbers.
+ * @return Array of strings and numbers.
  * @alias Blockly.utils.parsing.tokenizeInterpolation
  */
-const tokenizeInterpolation = function(message) {
+export function tokenizeInterpolation(message: string): (string|number)[] {
   return tokenizeInterpolationInternal(message, true);
-};
-exports.tokenizeInterpolation = tokenizeInterpolation;
+}
 
 /**
  * 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 {string|?} message Message, which may be a string that contains
+ * @param message Message, which may be a string that contains
  *     string table references.
- * @return {string} String with message references replaced.
+ * @return String with message references replaced.
  * @alias Blockly.utils.parsing.replaceMessageReferences
  */
-const replaceMessageReferences = function(message) {
+export function replaceMessageReferences(message: string|
+                                         AnyDuringMigration): string {
   if (typeof message !== 'string') {
     return message;
   }
@@ -192,50 +193,50 @@ const replaceMessageReferences = function(message) {
   // When parseInterpolationTokens === false, interpolatedResult should be at
   // most length 1.
   return interpolatedResult.length ? String(interpolatedResult[0]) : '';
-};
-exports.replaceMessageReferences = replaceMessageReferences;
+}
 
 /**
  * Validates that any %{MSG_KEY} references in the message refer to keys of
  * the Msg string table.
- * @param {string} message Text which might contain string table references.
- * @return {boolean} True if all message references have matching values.
+ * @param message Text which might contain string table references.
+ * @return True if all message references have matching values.
  *     Otherwise, false.
  * @alias Blockly.utils.parsing.checkMessageReferences
  */
-const checkMessageReferences = function(message) {
+export function checkMessageReferences(message: string): boolean {
   let validSoFar = true;
 
   const msgTable = Msg;
-
   // TODO (#1169): Implement support for other string tables,
   // prefixes other than BKY_.
   const m = message.match(/%{BKY_[A-Z]\w*}/ig);
-  for (let i = 0; i < m.length; i++) {
-    const msgKey = m[i].toUpperCase();
-    if (msgTable[msgKey.slice(6, -1)] === undefined) {
-      console.warn('No message string for ' + m[i] + ' in ' + message);
-      validSoFar = false;  // Continue to report other errors.
+  if (m) {
+    for (let i = 0; i < m.length; i++) {
+      const msgKey = m[i].toUpperCase();
+      if (msgTable[msgKey.slice(6, -1)] === undefined) {
+        console.warn('No message string for ' + m[i] + ' in ' + message);
+        validSoFar = false;  // Continue to report other errors.
+      }
     }
   }
 
   return validSoFar;
-};
-exports.checkMessageReferences = checkMessageReferences;
+}
 
 /**
  * Parse a block colour from a number or string, as provided in a block
  * definition.
- * @param {number|string} colour HSV hue value (0 to 360), #RRGGBB string,
+ * @param colour HSV hue value (0 to 360), #RRGGBB string,
  *     or a message reference string pointing to one of those two values.
- * @return {{hue: ?number, hex: string}} An object containing the colour as
+ * @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.
  * @alias Blockly.utils.parsing.parseBlockColour
  */
-const parseBlockColour = function(colour) {
+export function parseBlockColour(colour: number|
+                                 string): {hue: number|null, hex: string} {
   const dereferenced =
-      (typeof colour === 'string') ? replaceMessageReferences(colour) : colour;
+      typeof colour === 'string' ? replaceMessageReferences(colour) : colour;
 
   const hue = Number(dereferenced);
   if (!isNaN(hue) && 0 <= hue && hue <= 360) {
@@ -257,5 +258,4 @@ const parseBlockColour = function(colour) {
       throw Error(errorMsg);
     }
   }
-};
-exports.parseBlockColour = parseBlockColour;
+}

package/core/utils/rect.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @license
+ * Copyright 2019 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Class for representing rectangular regions.
+ * @alias Blockly.utils.Rect
+ */
+export declare class Rect {
+    top: number;
+    bottom: number;
+    left: number;
+    right: number;
+    /**
+     * @param top Top.
+     * @param bottom Bottom.
+     * @param left Left.
+     * @param right Right.
+     * @struct
+     */
+    constructor(top: number, bottom: number, left: number, right: number);
+    /**
+     * Tests whether this rectangle contains a x/y coordinate.
+     *
+     * @param x The x coordinate to test for containment.
+     * @param y The y coordinate to test for containment.
+     * @return Whether this rectangle contains given coordinate.
+     */
+    contains(x: number, y: number): boolean;
+    /**
+     * Tests whether this rectangle intersects the provided rectangle.
+     * Assumes that the coordinate system increases going down and left.
+     * @param other The other rectangle to check for intersection with.
+     * @return Whether this rectangle intersects the provided rectangle.
+     */
+    intersects(other: Rect): boolean;
+}

package/core/utils/{rect.js → rect.ts}

@@ -9,7 +9,6 @@
  * These methods are not specific to Blockly, and could be factored out into
  * a JavaScript framework such as Closure.
  */
-'use strict';
 
 /**
  * Utility methods for rectangle manipulation.
@@ -17,43 +16,34 @@
  * a JavaScript framework such as Closure.
  * @class
  */
-goog.module('Blockly.utils.Rect');
+import * as goog from '../../closure/goog/goog.js';
+goog.declareModuleId('Blockly.utils.Rect');
 
 
 /**
  * Class for representing rectangular regions.
  * @alias Blockly.utils.Rect
  */
-const Rect = class {
+export class Rect {
   /**
-   * @param {number} top Top.
-   * @param {number} bottom Bottom.
-   * @param {number} left Left.
-   * @param {number} right Right.
+   * @param top Top.
+   * @param bottom Bottom.
+   * @param left Left.
+   * @param right Right.
    * @struct
    */
-  constructor(top, bottom, left, right) {
-    /** @type {number} */
-    this.top = top;
-
-    /** @type {number} */
-    this.bottom = bottom;
-
-    /** @type {number} */
-    this.left = left;
-
-    /** @type {number} */
-    this.right = right;
-  }
+  constructor(
+      public top: number, public bottom: number, public left: number,
+      public right: number) {}
 
   /**
    * Tests whether this rectangle contains a x/y coordinate.
    *
-   * @param {number} x The x coordinate to test for containment.
-   * @param {number} y The y coordinate to test for containment.
-   * @return {boolean} Whether this rectangle contains given coordinate.
+   * @param x The x coordinate to test for containment.
+   * @param y The y coordinate to test for containment.
+   * @return Whether this rectangle contains given coordinate.
    */
-  contains(x, y) {
+  contains(x: number, y: number): boolean {
     return x >= this.left && x <= this.right && y >= this.top &&
         y <= this.bottom;
   }
@@ -61,15 +51,12 @@ const Rect = class {
   /**
    * Tests whether this rectangle intersects the provided rectangle.
    * Assumes that the coordinate system increases going down and left.
-   * @param {!Rect} other The other rectangle to check for
-   *    intersection with.
-   * @return {boolean} Whether this rectangle intersects the provided rectangle.
+   * @param other The other rectangle to check for intersection with.
+   * @return Whether this rectangle intersects the provided rectangle.
    */
-  intersects(other) {
+  intersects(other: Rect): boolean {
     return !(
         this.left > other.right || this.right < other.left ||
         this.top > other.bottom || this.bottom < other.top);
   }
-};
-
-exports.Rect = Rect;
+}

package/core/utils/sentinel.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @license
+ * Copyright 2022 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * A type used to create flag values.
+ * @alias Blockly.utils.Sentinel
+ */
+export declare class Sentinel {
+}

package/core/utils/{sentinel.js → sentinel.ts}

@@ -7,19 +7,17 @@
 /**
  * @fileoverview A type used to create flag values (e.g. SKIP_SETUP).
  */
-'use strict';
 
 /**
  * A type used to create flag values.
  * @class
  */
-goog.module('Blockly.utils.Sentinel');
+import * as goog from '../../closure/goog/goog.js';
+goog.declareModuleId('Blockly.utils.Sentinel');
 
 
 /**
  * A type used to create flag values.
  * @alias Blockly.utils.Sentinel
  */
-class Sentinel {}
-
-exports.Sentinel = Sentinel;
+export class Sentinel {}

package/core/utils/size.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @license
+ * Copyright 2019 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Class for representing sizes consisting of a width and height.
+ * @alias Blockly.utils.Size
+ */
+export declare class Size {
+    width: number;
+    height: number;
+    /**
+     * @param width Width.
+     * @param height Height.
+     * @struct
+     */
+    constructor(width: number, height: number);
+    /**
+     * Compares sizes for equality.
+     * @param a A Size.
+     * @param b A Size.
+     * @return True iff the sizes have equal widths and equal heights, or if both
+     *     are null.
+     */
+    static equals(a: Size | null, b: Size | null): boolean;
+}