blockly 8.0.4 → 8.0.5-beta.0

package/core/utils/{size.js → size.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 size calculation.
@@ -17,41 +16,30 @@
  * a JavaScript framework such as Closure.
  * @class
  */
-goog.module('Blockly.utils.Size');
+import * as goog from '../../closure/goog/goog.js';
+goog.declareModuleId('Blockly.utils.Size');
 
 
 /**
  * Class for representing sizes consisting of a width and height.
  * @alias Blockly.utils.Size
  */
-const Size = class {
+export class Size {
   /**
-   * @param {number} width Width.
-   * @param {number} height Height.
+   * @param width Width.
+   * @param height Height.
    * @struct
    */
-  constructor(width, height) {
-    /**
-     * Width
-     * @type {number}
-     */
-    this.width = width;
-
-    /**
-     * Height
-     * @type {number}
-     */
-    this.height = height;
-  }
+  constructor(public width: number, public height: number) {}
 
   /**
    * Compares sizes for equality.
-   * @param {?Size} a A Size.
-   * @param {?Size} b A Size.
-   * @return {boolean} True iff the sizes have equal widths and equal
-   *     heights, or if both are null.
+   * @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, b) {
+  static equals(a: Size|null, b: Size|null): boolean {
     if (a === b) {
       return true;
     }
@@ -60,6 +48,4 @@ const Size = class {
     }
     return a.width === b.width && a.height === b.height;
   }
-};
-
-exports.Size = Size;
+}

package/core/utils/string.d.ts

@@ -0,0 +1,55 @@
+/**
+ * @license
+ * Copyright 2019 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Fast prefix-checker.
+ * Copied from Closure's goog.string.startsWith.
+ * @param str The string to check.
+ * @param prefix A string to look for at the start of `str`.
+ * @return True if `str` begins with `prefix`.
+ * @alias Blockly.utils.string.startsWith
+ * @deprecated April 2022. Use built-in string.startsWith.
+ */
+export declare function startsWith(str: string, prefix: string): boolean;
+/**
+ * Given an array of strings, return the length of the shortest one.
+ * @param array Array of strings.
+ * @return Length of shortest string.
+ * @alias Blockly.utils.string.shortestStringLength
+ */
+export declare function shortestStringLength(array: string[]): number;
+/**
+ * Given an array of strings, return the length of the common prefix.
+ * Words may not be split.  Any space after a word is included in the length.
+ * @param array Array of strings.
+ * @param opt_shortest Length of shortest string.
+ * @return Length of common prefix.
+ * @alias Blockly.utils.string.commonWordPrefix
+ */
+export declare function commonWordPrefix(array: string[], opt_shortest?: number): number;
+/**
+ * Given an array of strings, return the length of the common suffix.
+ * Words may not be split.  Any space after a word is included in the length.
+ * @param array Array of strings.
+ * @param opt_shortest Length of shortest string.
+ * @return Length of common suffix.
+ * @alias Blockly.utils.string.commonWordSuffix
+ */
+export declare function commonWordSuffix(array: string[], opt_shortest?: number): number;
+/**
+ * Wrap text to the specified width.
+ * @param text Text to wrap.
+ * @param limit Width to wrap each line.
+ * @return Wrapped text.
+ * @alias Blockly.utils.string.wrap
+ */
+export declare function wrap(text: string, limit: number): string;
+/**
+ * Is the given string a number (includes negative and decimals).
+ * @param str Input string.
+ * @return True if number, false otherwise.
+ * @alias Blockly.utils.string.isNumber
+ */
+export declare function isNumber(str: string): boolean;

package/core/utils/{string.js → string.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 string manipulation.
@@ -17,29 +16,35 @@
  * a JavaScript framework such as Closure.
  * @namespace Blockly.utils.string
  */
-goog.module('Blockly.utils.string');
+import * as goog from '../../closure/goog/goog.js';
+goog.declareModuleId('Blockly.utils.string');
+
+import * as deprecation from './deprecation.js';
 
 
 /**
  * Fast prefix-checker.
  * Copied from Closure's goog.string.startsWith.
- * @param {string} str The string to check.
- * @param {string} prefix A string to look for at the start of `str`.
- * @return {boolean} True if `str` begins with `prefix`.
+ * @param str The string to check.
+ * @param prefix A string to look for at the start of `str`.
+ * @return True if `str` begins with `prefix`.
  * @alias Blockly.utils.string.startsWith
+ * @deprecated April 2022. Use built-in string.startsWith.
  */
-const startsWith = function(str, prefix) {
-  return str.lastIndexOf(prefix, 0) === 0;
-};
-exports.startsWith = startsWith;
+export function startsWith(str: string, prefix: string): boolean {
+  deprecation.warn(
+      'Blockly.utils.string.startsWith()', 'April 2022', 'April 2023',
+      'Use built-in string.startsWith');
+  return str.startsWith(prefix);
+}
 
 /**
  * Given an array of strings, return the length of the shortest one.
- * @param {!Array<string>} array Array of strings.
- * @return {number} Length of shortest string.
+ * @param array Array of strings.
+ * @return Length of shortest string.
  * @alias Blockly.utils.string.shortestStringLength
  */
-const shortestStringLength = function(array) {
+export function shortestStringLength(array: string[]): number {
   if (!array.length) {
     return 0;
   }
@@ -48,18 +53,18 @@ const shortestStringLength = function(array) {
         return a.length < b.length ? a : b;
       })
       .length;
-};
-exports.shortestStringLength = shortestStringLength;
+}
 
 /**
  * Given an array of strings, return the length of the common prefix.
  * Words may not be split.  Any space after a word is included in the length.
- * @param {!Array<string>} array Array of strings.
- * @param {number=} opt_shortest Length of shortest string.
- * @return {number} Length of common prefix.
+ * @param array Array of strings.
+ * @param opt_shortest Length of shortest string.
+ * @return Length of common prefix.
  * @alias Blockly.utils.string.commonWordPrefix
  */
-const commonWordPrefix = function(array, opt_shortest) {
+export function commonWordPrefix(
+    array: string[], opt_shortest?: number): number {
   if (!array.length) {
     return 0;
   } else if (array.length === 1) {
@@ -86,18 +91,18 @@ const commonWordPrefix = function(array, opt_shortest) {
     }
   }
   return max;
-};
-exports.commonWordPrefix = commonWordPrefix;
+}
 
 /**
  * Given an array of strings, return the length of the common suffix.
  * Words may not be split.  Any space after a word is included in the length.
- * @param {!Array<string>} array Array of strings.
- * @param {number=} opt_shortest Length of shortest string.
- * @return {number} Length of common suffix.
+ * @param array Array of strings.
+ * @param opt_shortest Length of shortest string.
+ * @return Length of common suffix.
  * @alias Blockly.utils.string.commonWordSuffix
  */
-const commonWordSuffix = function(array, opt_shortest) {
+export function commonWordSuffix(
+    array: string[], opt_shortest?: number): number {
   if (!array.length) {
     return 0;
   } else if (array.length === 1) {
@@ -124,32 +129,30 @@ const commonWordSuffix = function(array, opt_shortest) {
     }
   }
   return max;
-};
-exports.commonWordSuffix = commonWordSuffix;
+}
 
 /**
  * Wrap text to the specified width.
- * @param {string} text Text to wrap.
- * @param {number} limit Width to wrap each line.
- * @return {string} Wrapped text.
+ * @param text Text to wrap.
+ * @param limit Width to wrap each line.
+ * @return Wrapped text.
  * @alias Blockly.utils.string.wrap
  */
-const wrap = function(text, limit) {
+export function wrap(text: string, limit: number): string {
   const lines = text.split('\n');
   for (let i = 0; i < lines.length; i++) {
     lines[i] = wrapLine(lines[i], limit);
   }
   return lines.join('\n');
-};
-exports.wrap = wrap;
+}
 
 /**
  * Wrap single line of text to the specified width.
- * @param {string} text Text to wrap.
- * @param {number} limit Width to wrap each line.
- * @return {string} Wrapped text.
+ * @param text Text to wrap.
+ * @param limit Width to wrap each line.
+ * @return Wrapped text.
  */
-const wrapLine = function(text, limit) {
+function wrapLine(text: string, limit: number): string {
   if (text.length <= limit) {
     // Short text, no need to wrap.
     return text;
@@ -190,16 +193,17 @@ const wrapLine = function(text, limit) {
     lineCount++;
   } while (score > lastScore);
   return lastText;
-};
+}
 
 /**
  * Compute a score for how good the wrapping is.
- * @param {!Array<string>} words Array of each word.
- * @param {!Array<boolean>} wordBreaks Array of line breaks.
- * @param {number} limit Width to wrap each line.
- * @return {number} Larger the better.
+ * @param words Array of each word.
+ * @param wordBreaks Array of line breaks.
+ * @param limit Width to wrap each line.
+ * @return Larger the better.
  */
-const wrapScore = function(words, wordBreaks, limit) {
+function wrapScore(
+    words: string[], wordBreaks: boolean[], limit: number): number {
   // If this function becomes a performance liability, add caching.
   // Compute the length of each line.
   const lineLengths = [0];
@@ -241,17 +245,17 @@ const wrapScore = function(words, wordBreaks, limit) {
     score += 0.5;
   }
   return score;
-};
-
+}
 /**
  * Mutate the array of line break locations until an optimal solution is found.
  * No line breaks are added or deleted, they are simply moved around.
- * @param {!Array<string>} words Array of each word.
- * @param {!Array<boolean>} wordBreaks Array of line breaks.
- * @param {number} limit Width to wrap each line.
- * @return {!Array<boolean>} New array of optimal line breaks.
+ * @param words Array of each word.
+ * @param wordBreaks Array of line breaks.
+ * @param limit Width to wrap each line.
+ * @return New array of optimal line breaks.
  */
-const wrapMutate = function(words, wordBreaks, limit) {
+function wrapMutate(
+    words: string[], wordBreaks: boolean[], limit: number): boolean[] {
   let bestScore = wrapScore(words, wordBreaks, limit);
   let bestBreaks;
   // Try shifting every line break forward or backward.
@@ -259,7 +263,7 @@ const wrapMutate = function(words, wordBreaks, limit) {
     if (wordBreaks[i] === wordBreaks[i + 1]) {
       continue;
     }
-    const mutatedWordBreaks = [].concat(wordBreaks);
+    const mutatedWordBreaks = (new Array<boolean>()).concat(wordBreaks);
     mutatedWordBreaks[i] = !mutatedWordBreaks[i];
     mutatedWordBreaks[i + 1] = !mutatedWordBreaks[i + 1];
     const mutatedScore = wrapScore(words, mutatedWordBreaks, limit);
@@ -274,15 +278,15 @@ const wrapMutate = function(words, wordBreaks, limit) {
   }
   // No improvements found.  Done.
   return wordBreaks;
-};
+}
 
 /**
  * Reassemble the array of words into text, with the specified line breaks.
- * @param {!Array<string>} words Array of each word.
- * @param {!Array<boolean>} wordBreaks Array of line breaks.
- * @return {string} Plain text.
+ * @param words Array of each word.
+ * @param wordBreaks Array of line breaks.
+ * @return Plain text.
  */
-const wrapToText = function(words, wordBreaks) {
+function wrapToText(words: string[], wordBreaks: boolean[]): string {
   const text = [];
   for (let i = 0; i < words.length; i++) {
     text.push(words[i]);
@@ -291,15 +295,14 @@ const wrapToText = function(words, wordBreaks) {
     }
   }
   return text.join('');
-};
+}
 
 /**
  * Is the given string a number (includes negative and decimals).
- * @param {string} str Input string.
- * @return {boolean} True if number, false otherwise.
+ * @param str Input string.
+ * @return True if number, false otherwise.
  * @alias Blockly.utils.string.isNumber
  */
-const isNumber = function(str) {
+export function isNumber(str: string): boolean {
   return /^\s*-?\d+(\.\d+)?\s*$/.test(str);
-};
-exports.isNumber = isNumber;
+}

package/core/utils/style.d.ts

@@ -0,0 +1,127 @@
+/**
+ * @license
+ * Copyright 2019 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Coordinate } from './coordinate.js';
+import { Rect } from './rect.js';
+import { Size } from './size.js';
+/**
+ * Gets the height and width of an element.
+ * Similar to Closure's goog.style.getSize
+ * @param element Element to get size of.
+ * @return Object with width/height properties.
+ * @alias Blockly.utils.style.getSize
+ */
+export declare function getSize(element: Element): Size;
+/**
+ * Private version of getSize for stubbing in tests.
+ */
+declare function getSizeInternal(element: Element): Size;
+/**
+ * Retrieves a computed style value of a node. It returns empty string if the
+ * value cannot be computed (which will be the case in Internet Explorer) or
+ * "none" if the property requested is an SVG one and it has not been
+ * explicitly set (firefox and webkit).
+ *
+ * Copied from Closure's goog.style.getComputedStyle
+ *
+ * @param element Element to get style of.
+ * @param property Property to get (camel-case).
+ * @return Style value.
+ * @alias Blockly.utils.style.getComputedStyle
+ */
+export declare function getComputedStyle(element: Element, property: string): string;
+/**
+ * Gets the cascaded style value of a node, or null if the value cannot be
+ * computed (only Internet Explorer can do this).
+ *
+ * Copied from Closure's goog.style.getCascadedStyle
+ *
+ * @param element Element to get style of.
+ * @param style Property to get (camel-case).
+ * @return Style value.
+ * @alias Blockly.utils.style.getCascadedStyle
+ */
+export declare function getCascadedStyle(element: Element, style: string): string;
+/**
+ * Returns a Coordinate object relative to the top-left of the HTML document.
+ * Similar to Closure's goog.style.getPageOffset
+ * @param el Element to get the page offset for.
+ * @return The page offset.
+ * @alias Blockly.utils.style.getPageOffset
+ */
+export declare function getPageOffset(el: Element): Coordinate;
+/**
+ * Calculates the viewport coordinates relative to the document.
+ * Similar to Closure's goog.style.getViewportPageOffset
+ * @return The page offset of the viewport.
+ * @alias Blockly.utils.style.getViewportPageOffset
+ */
+export declare function getViewportPageOffset(): Coordinate;
+/**
+ * Shows or hides an element from the page. Hiding the element is done by
+ * setting the display property to "none", removing the element from the
+ * rendering hierarchy so it takes up no space. To show the element, the default
+ * inherited display property is restored (defined either in stylesheets or by
+ * the browser's default style rules).
+ * Copied from Closure's goog.style.getViewportPageOffset
+ *
+ * @param el Element to show or hide.
+ * @param isShown True to render the element in its default style, false to
+ *     disable rendering the element.
+ * @alias Blockly.utils.style.setElementShown
+ */
+export declare function setElementShown(el: Element, isShown: any): void;
+/**
+ * Returns true if the element is using right to left (RTL) direction.
+ * Copied from Closure's goog.style.isRightToLeft
+ *
+ * @param el The element to test.
+ * @return True for right to left, false for left to right.
+ * @alias Blockly.utils.style.isRightToLeft
+ */
+export declare function isRightToLeft(el: Element): boolean;
+/**
+ * Gets the computed border widths (on all sides) in pixels
+ * Copied from Closure's goog.style.getBorderBox
+ * @param element  The element to get the border widths for.
+ * @return The computed border widths.
+ * @alias Blockly.utils.style.getBorderBox
+ */
+export declare function getBorderBox(element: Element): Rect;
+/**
+ * Changes the scroll position of `container` with the minimum amount so
+ * that the content and the borders of the given `element` become visible.
+ * If the element is bigger than the container, its top left corner will be
+ * aligned as close to the container's top left corner as possible.
+ * Copied from Closure's goog.style.scrollIntoContainerView
+ *
+ * @param element The element to make visible.
+ * @param container The container to scroll. If not set, then the document
+ *     scroll element will be used.
+ * @param opt_center Whether to center the element in the container.
+ *     Defaults to false.
+ * @alias Blockly.utils.style.scrollIntoContainerView
+ */
+export declare function scrollIntoContainerView(element: Element, container: Element, opt_center?: boolean): void;
+/**
+ * Calculate the scroll position of `container` with the minimum amount so
+ * that the content and the borders of the given `element` become visible.
+ * If the element is bigger than the container, its top left corner will be
+ * aligned as close to the container's top left corner as possible.
+ * Copied from Closure's goog.style.getContainerOffsetToScrollInto
+ *
+ * @param element The element to make visible.
+ * @param container The container to scroll. If not set, then the document
+ *     scroll element will be used.
+ * @param opt_center Whether to center the element in the container.
+ *     Defaults to false.
+ * @return The new scroll position of the container.
+ * @alias Blockly.utils.style.getContainerOffsetToScrollInto
+ */
+export declare function getContainerOffsetToScrollInto(element: Element, container: Element, opt_center?: boolean): Coordinate;
+export declare const TEST_ONLY: {
+    getSizeInternal: typeof getSizeInternal;
+};
+export {};