blockly 12.3.1 → 12.4.0

package/core/utils/aria.ts

@@ -0,0 +1,158 @@
+/**
+ * @license
+ * Copyright 2019 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+// Former goog.module ID: Blockly.utils.aria
+
+/** ARIA states/properties prefix. */
+const ARIA_PREFIX = 'aria-';
+
+/** ARIA role attribute. */
+const ROLE_ATTRIBUTE = 'role';
+
+/**
+ * ARIA role values.
+ * Copied from Closure's goog.a11y.aria.Role
+ */
+export enum Role {
+  // ARIA role for an interactive control of tabular data.
+  GRID = 'grid',
+
+  // ARIA role for a cell in a grid.
+  GRIDCELL = 'gridcell',
+  // ARIA role for a group of related elements like tree item siblings.
+  GROUP = 'group',
+
+  // ARIA role for a listbox.
+  LISTBOX = 'listbox',
+
+  // ARIA role for a popup menu.
+  MENU = 'menu',
+
+  // ARIA role for menu item elements.
+  MENUITEM = 'menuitem',
+  // ARIA role for a checkbox box element inside a menu.
+  MENUITEMCHECKBOX = 'menuitemcheckbox',
+  // ARIA role for option items that are  children of combobox, listbox, menu,
+  // radiogroup, or tree elements.
+  OPTION = 'option',
+  // ARIA role for ignorable cosmetic elements with no semantic significance.
+  PRESENTATION = 'presentation',
+
+  // ARIA role for a row of cells in a grid.
+  ROW = 'row',
+  // ARIA role for a tree.
+  TREE = 'tree',
+
+  // ARIA role for a tree item that sometimes may be expanded or collapsed.
+  TREEITEM = 'treeitem',
+
+  // ARIA role for a visual separator in e.g. a menu.
+  SEPARATOR = 'separator',
+
+  // ARIA role for a live region providing information.
+  STATUS = 'status',
+}
+
+/**
+ * ARIA states and properties.
+ * Copied from Closure's goog.a11y.aria.State
+ */
+export enum State {
+  // ARIA property for setting the currently active descendant of an element,
+  // for example the selected item in a list box. Value: ID of an element.
+  ACTIVEDESCENDANT = 'activedescendant',
+  // ARIA property defines the total number of columns in a table, grid, or
+  // treegrid.
+  // Value: integer.
+  COLCOUNT = 'colcount',
+  // ARIA state for a disabled item. Value: one of {true, false}.
+  DISABLED = 'disabled',
+
+  // ARIA state for setting whether the element like a tree node is expanded.
+  // Value: one of {true, false, undefined}.
+  EXPANDED = 'expanded',
+
+  // ARIA state indicating that the entered value does not conform. Value:
+  // one of {false, true, 'grammar', 'spelling'}
+  INVALID = 'invalid',
+
+  // ARIA property that provides a label to override any other text, value, or
+  // contents used to describe this element. Value: string.
+  LABEL = 'label',
+  // ARIA property for setting the element which labels another element.
+  // Value: space-separated IDs of elements.
+  LABELLEDBY = 'labelledby',
+
+  // ARIA property for setting the level of an element in the hierarchy.
+  // Value: integer.
+  LEVEL = 'level',
+  // ARIA property indicating if the element is horizontal or vertical.
+  // Value: one of {'vertical', 'horizontal'}.
+  ORIENTATION = 'orientation',
+
+  // ARIA property that defines an element's number of position in a list.
+  // Value: integer.
+  POSINSET = 'posinset',
+
+  // ARIA property defines the total number of rows in a table, grid, or
+  // treegrid.
+  // Value: integer.
+  ROWCOUNT = 'rowcount',
+
+  // ARIA state for setting the currently selected item in the list.
+  // Value: one of {true, false, undefined}.
+  SELECTED = 'selected',
+  // ARIA property defining the number of items in a list. Value: integer.
+  SETSIZE = 'setsize',
+
+  // ARIA property for slider maximum value. Value: number.
+  VALUEMAX = 'valuemax',
+
+  // ARIA property for slider minimum value. Value: number.
+  VALUEMIN = 'valuemin',
+
+  // ARIA property for live region chattiness.
+  // Value: one of {polite, assertive, off}.
+  LIVE = 'live',
+
+  // ARIA property for removing elements from the accessibility tree.
+  // Value: one of {true, false, undefined}.
+  HIDDEN = 'hidden',
+}
+
+/**
+ * Sets the role of an element.
+ *
+ * Similar to Closure's goog.a11y.aria
+ *
+ * @param element DOM node to set role of.
+ * @param roleName Role name.
+ */
+export function setRole(element: Element, roleName: Role) {
+  element.setAttribute(ROLE_ATTRIBUTE, roleName);
+}
+
+/**
+ * Sets the state or property of an element.
+ * Copied from Closure's goog.a11y.aria
+ *
+ * @param element DOM node where we set state.
+ * @param stateName State attribute being set.
+ *     Automatically adds prefix 'aria-' to the state name if the attribute is
+ * not an extra attribute.
+ * @param value Value for the state attribute.
+ */
+export function setState(
+  element: Element,
+  stateName: State,
+  value: string | boolean | number | string[],
+) {
+  if (Array.isArray(value)) {
+    value = value.join(' ');
+  }
+  const attrStateName = ARIA_PREFIX + stateName;
+  element.setAttribute(attrStateName, `${value}`);
+}

package/core/utils/array.ts

@@ -0,0 +1,24 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+// Former goog.module ID: Blockly.utils.array
+
+/**
+ * Removes the first occurrence of a particular value from an array.
+ *
+ * @param arr Array from which to remove value.
+ * @param value Value to remove.
+ * @returns True if an element was removed.
+ * @internal
+ */
+export function removeElem<T>(arr: Array<T>, value: T): boolean {
+  const i = arr.indexOf(value);
+  if (i === -1) {
+    return false;
+  }
+  arr.splice(i, 1);
+  return true;
+}

package/core/utils/colour.ts

@@ -0,0 +1,265 @@
+/**
+ * @license
+ * Copyright 2019 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+// Former goog.module ID: Blockly.utils.colour
+
+/**
+ * The richness of block colours, regardless of the hue.
+ * Must be in the range of 0 (inclusive) to 1 (exclusive).
+ */
+let hsvSaturation = 0.45;
+
+/**
+ * Get the richness of block colours, regardless of the hue.
+ *
+ * @returns The current richness.
+ * @internal
+ */
+export function getHsvSaturation(): number {
+  return hsvSaturation;
+}
+
+/**
+ * Set the richness of block colours, regardless of the hue.
+ *
+ * @param newSaturation The new richness, in the range of  0 (inclusive) to 1
+ *     (exclusive)
+ * @internal
+ */
+export function setHsvSaturation(newSaturation: number) {
+  hsvSaturation = newSaturation;
+}
+
+/**
+ * The intensity of block colours, regardless of the hue.
+ * Must be in the range of 0 (inclusive) to 1 (exclusive).
+ */
+let hsvValue = 0.65;
+
+/**
+ * Get the intensity of block colours, regardless of the hue.
+ *
+ * @returns The current intensity.
+ * @internal
+ */
+export function getHsvValue(): number {
+  return hsvValue;
+}
+
+/**
+ * Set the intensity of block colours, regardless of the hue.
+ *
+ * @param newValue The new intensity, in the range of  0 (inclusive) to 1
+ *     (exclusive)
+ * @internal
+ */
+export function setHsvValue(newValue: number) {
+  hsvValue = newValue;
+}
+
+/**
+ * Parses a colour from a string.
+ * .parse('red') = '#ff0000'
+ * .parse('#f00') = '#ff0000'
+ * .parse('#ff0000') = '#ff0000'
+ * .parse('0xff0000') = '#ff0000'
+ * .parse('rgb(255, 0, 0)') = '#ff0000'
+ *
+ * @param str Colour in some CSS format.
+ * @returns A string containing a hex representation of the colour, or null if
+ *     can't be parsed.
+ */
+export function parse(str: string | number): string | null {
+  str = `${str}`.toLowerCase().trim();
+  let hex = names[str];
+  if (hex) {
+    // e.g. 'red'
+    return hex;
+  }
+  hex = str.substring(0, 2) === '0x' ? '#' + str.substring(2) : str;
+  hex = hex[0] === '#' ? hex : '#' + hex;
+  if (/^#[0-9a-f]{6}$/.test(hex)) {
+    // e.g. '#00ff88'
+    return hex;
+  }
+  if (/^#[0-9a-f]{3}$/.test(hex)) {
+    // e.g. '#0f8'
+    return ['#', hex[1], hex[1], hex[2], hex[2], hex[3], hex[3]].join('');
+  }
+  const rgb = str.match(/^(?:rgb)?\s*\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)\s*\)$/);
+  if (rgb) {
+    // e.g. 'rgb(0, 128, 255)'
+    const r = Number(rgb[1]);
+    const g = Number(rgb[2]);
+    const b = Number(rgb[3]);
+    if (r >= 0 && r < 256 && g >= 0 && g < 256 && b >= 0 && b < 256) {
+      return rgbToHex(r, g, b);
+    }
+  }
+  return null;
+}
+
+/**
+ * Converts a colour from RGB to hex representation.
+ *
+ * @param r Amount of red, int between 0 and 255.
+ * @param g Amount of green, int between 0 and 255.
+ * @param b Amount of blue, int between 0 and 255.
+ * @returns Hex representation of the colour.
+ */
+export function rgbToHex(r: number, g: number, b: number): string {
+  const rgb = (r << 16) | (g << 8) | b;
+  if (r < 0x10) {
+    return '#' + (0x1000000 | rgb).toString(16).substr(1);
+  }
+  return '#' + rgb.toString(16);
+}
+
+/**
+ * Converts a colour to RGB.
+ *
+ * @param colour String representing colour in any colour format ('#ff0000',
+ *     'red', '0xff000', etc).
+ * @returns RGB representation of the colour.
+ */
+export function hexToRgb(colour: string): number[] {
+  const hex = parse(colour);
+  if (!hex) {
+    return [0, 0, 0];
+  }
+
+  const rgb = parseInt(hex.substr(1), 16);
+  const r = rgb >> 16;
+  const g = (rgb >> 8) & 255;
+  const b = rgb & 255;
+
+  return [r, g, b];
+}
+
+/**
+ * Converts an HSV triplet to hex representation.
+ *
+ * @param h Hue value in [0, 360].
+ * @param s Saturation value in [0, 1].
+ * @param v Brightness in [0, 255].
+ * @returns Hex representation of the colour.
+ */
+export function hsvToHex(h: number, s: number, v: number): string {
+  let red = 0;
+  let green = 0;
+  let blue = 0;
+  if (s === 0) {
+    red = v;
+    green = v;
+    blue = v;
+  } else {
+    const sextant = Math.floor(h / 60);
+    const remainder = h / 60 - sextant;
+    const val1 = v * (1 - s);
+    const val2 = v * (1 - s * remainder);
+    const val3 = v * (1 - s * (1 - remainder));
+    switch (sextant) {
+      case 1:
+        red = val2;
+        green = v;
+        blue = val1;
+        break;
+      case 2:
+        red = val1;
+        green = v;
+        blue = val3;
+        break;
+      case 3:
+        red = val1;
+        green = val2;
+        blue = v;
+        break;
+      case 4:
+        red = val3;
+        green = val1;
+        blue = v;
+        break;
+      case 5:
+        red = v;
+        green = val1;
+        blue = val2;
+        break;
+      case 6:
+      case 0:
+        red = v;
+        green = val3;
+        blue = val1;
+        break;
+    }
+  }
+  return rgbToHex(Math.floor(red), Math.floor(green), Math.floor(blue));
+}
+
+/**
+ * Blend two colours together, using the specified factor to indicate the
+ * weight given to the first colour.
+ *
+ * @param colour1 First colour.
+ * @param colour2 Second colour.
+ * @param factor The weight to be given to colour1 over colour2.
+ *     Values should be in the range [0, 1].
+ * @returns Combined colour represented in hex.
+ */
+export function blend(
+  colour1: string,
+  colour2: string,
+  factor: number,
+): string | null {
+  const hex1 = parse(colour1);
+  if (!hex1) {
+    return null;
+  }
+  const hex2 = parse(colour2);
+  if (!hex2) {
+    return null;
+  }
+  const rgb1 = hexToRgb(hex1);
+  const rgb2 = hexToRgb(hex2);
+  const r = Math.round(rgb2[0] + factor * (rgb1[0] - rgb2[0]));
+  const g = Math.round(rgb2[1] + factor * (rgb1[1] - rgb2[1]));
+  const b = Math.round(rgb2[2] + factor * (rgb1[2] - rgb2[2]));
+  return rgbToHex(r, g, b);
+}
+
+/**
+ * A map that contains the 16 basic colour keywords as defined by W3C:
+ * https://www.w3.org/TR/2018/REC-css-color-3-20180619/#html4
+ * The keys of this map are the lowercase "readable" names of the colours,
+ * while the values are the "hex" values.
+ */
+export const names: {[key: string]: string} = {
+  'aqua': '#00ffff',
+  'black': '#000000',
+  'blue': '#0000ff',
+  'fuchsia': '#ff00ff',
+  'gray': '#808080',
+  'green': '#008000',
+  'lime': '#00ff00',
+  'maroon': '#800000',
+  'navy': '#000080',
+  'olive': '#808000',
+  'purple': '#800080',
+  'red': '#ff0000',
+  'silver': '#c0c0c0',
+  'teal': '#008080',
+  'white': '#ffffff',
+  'yellow': '#ffff00',
+};
+
+/**
+ * Convert a hue (HSV model) into an RGB hex triplet.
+ *
+ * @param hue Hue on a colour wheel (0-360).
+ * @returns RGB code, e.g. '#5ba65b'.
+ */
+export function hueToHex(hue: number): string {
+  return hsvToHex(hue, hsvSaturation, hsvValue * 255);
+}

package/core/utils/coordinate.ts

@@ -0,0 +1,129 @@
+/**
+ * @license
+ * Copyright 2019 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Utility methods for coordinate manipulation.
+ * These methods are not specific to Blockly, and could be factored out into
+ * a JavaScript framework such as Closure.
+ *
+ * @class
+ */
+// Former goog.module ID: Blockly.utils.Coordinate
+
+/**
+ * Class for representing coordinates and positions.
+ */
+export class Coordinate {
+  /**
+   * @param x Left.
+   * @param y Top.
+   */
+  constructor(
+    public x: number,
+    public y: number,
+  ) {}
+
+  /**
+   * Creates a new copy of this coordinate.
+   *
+   * @returns A copy of this coordinate.
+   */
+  clone(): Coordinate {
+    return new Coordinate(this.x, this.y);
+  }
+
+  /**
+   * Scales this coordinate by the given scale factor.
+   *
+   * @param s The scale factor to use for both x and y dimensions.
+   * @returns This coordinate after scaling.
+   */
+  scale(s: number): Coordinate {
+    this.x *= s;
+    this.y *= s;
+    return this;
+  }
+
+  /**
+   * Translates this coordinate by the given offsets.
+   * respectively.
+   *
+   * @param tx The value to translate x by.
+   * @param ty The value to translate y by.
+   * @returns This coordinate after translating.
+   */
+  translate(tx: number, ty: number): Coordinate {
+    this.x += tx;
+    this.y += ty;
+    return this;
+  }
+
+  /**
+   * Compares coordinates for equality.
+   *
+   * @param a A Coordinate.
+   * @param b A Coordinate.
+   * @returns True iff the coordinates are equal, or if both are null.
+   */
+  static equals(a?: Coordinate | null, b?: Coordinate | null): boolean {
+    if (a === b) {
+      return true;
+    }
+    if (!a || !b) {
+      return false;
+    }
+    return a.x === b.x && a.y === b.y;
+  }
+
+  /**
+   * Returns the distance between two coordinates.
+   *
+   * @param a A Coordinate.
+   * @param b A Coordinate.
+   * @returns The distance between `a` and `b`.
+   */
+  static distance(a: Coordinate, b: Coordinate): number {
+    const dx = a.x - b.x;
+    const dy = a.y - b.y;
+    return Math.sqrt(dx * dx + dy * dy);
+  }
+
+  /**
+   * Returns the magnitude of a coordinate.
+   *
+   * @param a A Coordinate.
+   * @returns The distance between the origin and `a`.
+   */
+  static magnitude(a: Coordinate): number {
+    return Math.sqrt(a.x * a.x + a.y * a.y);
+  }
+
+  /**
+   * Returns the difference between two coordinates as a new
+   * Coordinate.
+   *
+   * @param a An x/y coordinate.
+   * @param b An x/y coordinate.
+   * @returns A Coordinate representing the difference between `a` and `b`.
+   */
+  static difference(
+    a: Coordinate | SVGPoint,
+    b: Coordinate | SVGPoint,
+  ): Coordinate {
+    return new Coordinate(a.x - b.x, a.y - b.y);
+  }
+
+  /**
+   * Returns the sum of two coordinates as a new Coordinate.
+   *
+   * @param a An x/y coordinate.
+   * @param b An x/y coordinate.
+   * @returns A Coordinate representing the sum of the two coordinates.
+   */
+  static sum(a: Coordinate | SVGPoint, b: Coordinate | SVGPoint): Coordinate {
+    return new Coordinate(a.x + b.x, a.y + b.y);
+  }
+}

package/core/utils/deprecation.ts

@@ -0,0 +1,47 @@
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+// Former goog.module ID: Blockly.utils.deprecation
+
+// Set of previously-emitted warnings.
+const previousWarnings = new Set();
+
+/**
+ * Warn developers that a function or property is deprecated.
+ *
+ * @param name The name of the function or property.
+ * @param deprecationDate The date of deprecation. Prefer 'version n.0.0'
+ *     format, and fall back to 'month yyyy' or 'quarter yyyy' format.
+ * @param deletionDate The date of deletion. Prefer 'version n.0.0'
+ *     format, and fall back to 'month yyyy' or 'quarter yyyy' format.
+ * @param opt_use The name of a function or property to use instead, if any.
+ * @internal
+ */
+export function warn(
+  name: string,
+  deprecationDate: string,
+  deletionDate: string,
+  opt_use?: string,
+) {
+  let msg =
+    name +
+    ' was deprecated in ' +
+    deprecationDate +
+    ' and will be deleted in ' +
+    deletionDate +
+    '.';
+  if (opt_use) {
+    msg += '\nUse ' + opt_use + ' instead.';
+  }
+
+  // Don't log deprecation warnings multiple times.
+  if (previousWarnings.has(msg)) {
+    return;
+  }
+
+  previousWarnings.add(msg);
+  console.warn(msg);
+}