blockly 7.20211209.2 → 8.0.0

package/core/toolbox/toolbox_item.js

@@ -30,128 +30,144 @@ const {WorkspaceSvg} = goog.requireType('Blockly.WorkspaceSvg');
 
 /**
  * Class for an item in the toolbox.
- * @param {!toolbox.ToolboxItemInfo} toolboxItemDef The JSON defining the
- *     toolbox item.
- * @param {!IToolbox} toolbox The toolbox that holds the toolbox item.
- * @param {ICollapsibleToolboxItem=} opt_parent The parent toolbox item
- *     or null if the category does not have a parent.
- * @constructor
  * @implements {IToolboxItem}
  * @alias Blockly.ToolboxItem
  */
-const ToolboxItem = function(toolboxItemDef, toolbox, opt_parent) {
+class ToolboxItem {
   /**
-   * The id for the category.
-   * @type {string}
-   * @protected
+   * @param {!toolbox.ToolboxItemInfo} toolboxItemDef The JSON defining
+   *     the toolbox item.
+   * @param {!IToolbox} toolbox The toolbox that holds the toolbox item.
+   * @param {ICollapsibleToolboxItem=} opt_parent The parent toolbox item
+   *     or null if the category does not have a parent.
    */
-  this.id_ = toolboxItemDef['toolboxitemid'] || idGenerator.getNextUniqueId();
+  constructor(toolboxItemDef, toolbox, opt_parent) {
+    /**
+     * The id for the category.
+     * @type {string}
+     * @protected
+     */
+    this.id_ = toolboxItemDef['toolboxitemid'] || idGenerator.getNextUniqueId();
+
+    /**
+     * The parent of the category.
+     * @type {?ICollapsibleToolboxItem}
+     * @protected
+     */
+    this.parent_ = opt_parent || null;
+
+    /**
+     * The level that the category is nested at.
+     * @type {number}
+     * @protected
+     */
+    this.level_ = this.parent_ ? this.parent_.getLevel() + 1 : 0;
+
+    /**
+     * The JSON definition of the toolbox item.
+     * @type {?toolbox.ToolboxItemInfo}
+     * @protected
+     */
+    this.toolboxItemDef_ = toolboxItemDef;
+
+    /**
+     * The toolbox this category belongs to.
+     * @type {!IToolbox}
+     * @protected
+     */
+    this.parentToolbox_ = toolbox;
+
+    /**
+     * The workspace of the parent toolbox.
+     * @type {!WorkspaceSvg}
+     * @protected
+     */
+    this.workspace_ = this.parentToolbox_.getWorkspace();
+  }
 
   /**
-   * The parent of the category.
-   * @type {?ICollapsibleToolboxItem}
-   * @protected
+   * Initializes the toolbox item.
+   * This includes creating the DOM and updating the state of any items based
+   * on the info object.
+   * @public
    */
-  this.parent_ = opt_parent || null;
+  init() {
+    // No-op by default.
+  }
 
   /**
-   * The level that the category is nested at.
-   * @type {number}
-   * @protected
+   * Gets the div for the toolbox item.
+   * @return {?Element} The div for the toolbox item.
+   * @public
    */
-  this.level_ = this.parent_ ? this.parent_.getLevel() + 1 : 0;
+  getDiv() {
+    return null;
+  }
 
   /**
-   * The JSON definition of the toolbox item.
-   * @type {!toolbox.ToolboxItemInfo}
-   * @protected
+   * 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.
+   * @return {?Element} The HTML element that receives clicks, or null if this
+   *     item should not receive clicks.
+   * @public
    */
-  this.toolboxItemDef_ = toolboxItemDef;
+  getClickTarget() {
+    return null;
+  }
 
   /**
-   * The toolbox this category belongs to.
-   * @type {!IToolbox}
-   * @protected
+   * Gets a unique identifier for this toolbox item.
+   * @return {string} The ID for the toolbox item.
+   * @public
    */
-  this.parentToolbox_ = toolbox;
+  getId() {
+    return this.id_;
+  }
 
   /**
-   * The workspace of the parent toolbox.
-   * @type {!WorkspaceSvg}
-   * @protected
+   * Gets the parent if the toolbox item is nested.
+   * @return {?IToolboxItem} The parent toolbox item, or null if
+   *     this toolbox item is not nested.
+   * @public
    */
-  this.workspace_ = this.parentToolbox_.getWorkspace();
-};
+  getParent() {
+    return null;
+  }
 
-/**
- * Initializes the toolbox item.
- * This includes creating the DOM and updating the state of any items based
- * on the info object.
- * @public
- */
-ToolboxItem.prototype.init = function() {
-  // No-op by default.
-};
-
-/**
- * Gets the div for the toolbox item.
- * @return {?Element} The div for the toolbox item.
- * @public
- */
-ToolboxItem.prototype.getDiv = function() {
-  return null;
-};
-
-/**
- * Gets a unique identifier for this toolbox item.
- * @return {string} The ID for the toolbox item.
- * @public
- */
-ToolboxItem.prototype.getId = function() {
-  return this.id_;
-};
-
-/**
- * Gets the parent if the toolbox item is nested.
- * @return {?IToolboxItem} The parent toolbox item, or null if
- *     this toolbox item is not nested.
- * @public
- */
-ToolboxItem.prototype.getParent = function() {
-  return null;
-};
-
-/**
- * Gets the nested level of the category.
- * @return {number} The nested level of the category.
- * @package
- */
-ToolboxItem.prototype.getLevel = function() {
-  return this.level_;
-};
+  /**
+   * Gets the nested level of the category.
+   * @return {number} The nested level of the category.
+   * @package
+   */
+  getLevel() {
+    return this.level_;
+  }
 
-/**
- * Whether the toolbox item is selectable.
- * @return {boolean} True if the toolbox item can be selected.
- * @public
- */
-ToolboxItem.prototype.isSelectable = function() {
-  return false;
-};
+  /**
+   * Whether the toolbox item is selectable.
+   * @return {boolean} True if the toolbox item can be selected.
+   * @public
+   */
+  isSelectable() {
+    return false;
+  }
 
-/**
- * Whether the toolbox item is collapsible.
- * @return {boolean} True if the toolbox item is collapsible.
- * @public
- */
-ToolboxItem.prototype.isCollapsible = function() {
-  return false;
-};
+  /**
+   * Whether the toolbox item is collapsible.
+   * @return {boolean} True if the toolbox item is collapsible.
+   * @public
+   */
+  isCollapsible() {
+    return false;
+  }
 
-/**
- * Dispose of this toolbox item. No-op by default.
- * @public
- */
-ToolboxItem.prototype.dispose = function() {};
+  /**
+   * Dispose of this toolbox item. No-op by default.
+   * @public
+   */
+  dispose() {}
+}
 
 exports.ToolboxItem = ToolboxItem;

package/core/tooltip.js

@@ -4,23 +4,15 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-/**
- * @fileoverview Library to create tooltips for Blockly.
- * First, call init() after onload.
- * Second, set the 'tooltip' property on any SVG element that needs a tooltip.
- * If the tooltip is a string, then that message will be displayed.
- * If the tooltip is an SVG element, then that object's tooltip will be used.
- * Third, call bindMouseEvents(e) passing the SVG element.
- */
 'use strict';
 
 /**
  * Library to create tooltips for Blockly.
- * First, call init() after onload.
+ * First, call createDom() after onload.
  * Second, set the 'tooltip' property on any SVG element that needs a tooltip.
- * If the tooltip is a string, then that message will be displayed.
- * If the tooltip is an SVG element, then that object's tooltip will be used.
- * Third, call bindMouseEvents(e) passing the SVG element.
+ * If the tooltip is a string, or a function that returns a string, that message
+ * will be displayed. If the tooltip is an SVG element, then that object's
+ * tooltip will be used. Third, call bindMouseEvents(e) passing the SVG element.
  * @namespace Blockly.Tooltip
  */
 goog.module('Blockly.Tooltip');
@@ -42,6 +34,46 @@ const deprecation = goog.require('Blockly.utils.deprecation');
 let TipInfo;
 exports.TipInfo = TipInfo;
 
+/**
+ * A function that renders custom tooltip UI.
+ * 1st parameter: the div element to render content into.
+ * 2nd parameter: the element being moused over (i.e., the element for which the
+ * tooltip should be shown).
+ * @typedef {function(!Element, !Element)}
+ * @alias Blockly.Tooltip.CustomTooltip
+ */
+let CustomTooltip;
+exports.CustomTooltip = CustomTooltip;
+
+/**
+ * An optional function that renders custom tooltips into the provided DIV. If
+ * this is defined, the function will be called instead of rendering the default
+ * tooltip UI.
+ * @type {!CustomTooltip|undefined}
+ */
+let customTooltip = undefined;
+
+/**
+ * Sets a custom function that will be called if present instead of the default
+ * tooltip UI.
+ * @param {!CustomTooltip} customFn A custom tooltip used to render an alternate
+ *     tooltip UI.
+ * @alias Blockly.Tooltip.setCustomTooltip
+ */
+const setCustomTooltip = function(customFn) {
+  customTooltip = customFn;
+};
+exports.setCustomTooltip = setCustomTooltip;
+
+/**
+ * Gets the custom tooltip function.
+ * @returns {!CustomTooltip|undefined} The custom tooltip function, if defined.
+ */
+const getCustomTooltip = function() {
+  return customTooltip;
+};
+exports.getCustomTooltip = getCustomTooltip;
+
 /**
  * Is a tooltip currently showing?
  * @type {boolean}
@@ -160,13 +192,13 @@ exports.MARGINS = MARGINS;
 
 /**
  * The HTML container.  Set once by createDom.
- * @type {Element}
+ * @type {?HTMLDivElement}
  */
 let DIV = null;
 
 /**
  * Returns the HTML tooltip container.
- * @returns {Element} The HTML tooltip container.
+ * @returns {?HTMLDivElement} The HTML tooltip container.
  * @alias Blockly.Tooltip.getDiv
  */
 const getDiv = function() {
@@ -178,7 +210,7 @@ Object.defineProperties(exports, {
   /**
    * The HTML container.  Set once by createDom.
    * @name Blockly.Tooltip.DIV
-   * @type {Element}
+   * @type {HTMLDivElement}
    * @deprecated Use Blockly.Tooltip.getDiv() and .setDiv().
    *     (September 2021)
    * @suppress {checkTypes}
@@ -242,7 +274,7 @@ const createDom = function() {
     return;  // Already created.
   }
   // Create an HTML container for popup overlays (e.g. editor widgets).
-  DIV = document.createElement('div');
+  DIV = /** @type {!HTMLDivElement} */ (document.createElement('div'));
   DIV.className = 'blocklyTooltipDiv';
   const container = common.getParentContainer() || document.body;
   container.appendChild(DIV);
@@ -410,48 +442,60 @@ const unblock = function() {
 exports.unblock = unblock;
 
 /**
- * Create the tooltip and show it.
+ * Renders the tooltip content into the tooltip div.
  */
-const show = function() {
-  if (blocked) {
-    // Someone doesn't want us to show tooltips.
+const renderContent = function() {
+  if (!DIV || !element) {
+    // This shouldn't happen, but if it does, we can't render.
     return;
   }
-  poisonedElement = element;
-  if (!DIV) {
-    return;
+  if (typeof customTooltip === 'function') {
+    customTooltip(DIV, element);
+  } else {
+    renderDefaultContent();
   }
-  // Erase all existing text.
-  DIV.textContent = '';
+};
+
+/**
+ * Renders the default tooltip UI.
+ */
+const renderDefaultContent = function() {
   let tip = getTooltipOfObject(element);
   tip = blocklyString.wrap(tip, LIMIT);
   // Create new text, line by line.
   const lines = tip.split('\n');
   for (let i = 0; i < lines.length; i++) {
-    const div = document.createElement('div');
+    const div = /** @type {!HTMLDivElement} */ (document.createElement('div'));
     div.appendChild(document.createTextNode(lines[i]));
     DIV.appendChild(div);
   }
-  const rtl = /** @type {{RTL: boolean}} */ (element).RTL;
+};
+
+/**
+ * Gets the coordinates for the tooltip div, taking into account the edges of
+ * the screen to prevent showing the tooltip offscreen.
+ * @param {boolean} rtl True if the tooltip should be in right-to-left layout.
+ * @returns {{x: number, y: number}} Coordinates at which the tooltip div should
+ *     be placed.
+ */
+const getPosition = function(rtl) {
+  // Position the tooltip just below the cursor.
   const windowWidth = document.documentElement.clientWidth;
   const windowHeight = document.documentElement.clientHeight;
-  // Display the tooltip.
-  DIV.style.direction = rtl ? 'rtl' : 'ltr';
-  DIV.style.display = 'block';
-  visible = true;
-  // Move the tooltip to just below the cursor.
+
   let anchorX = lastX;
   if (rtl) {
     anchorX -= OFFSET_X + DIV.offsetWidth;
   } else {
     anchorX += OFFSET_X;
   }
-  let anchorY = lastY + OFFSET_Y;
 
+  let anchorY = lastY + OFFSET_Y;
   if (anchorY + DIV.offsetHeight > windowHeight + window.scrollY) {
     // Falling off the bottom of the screen; shift the tooltip up.
     anchorY -= DIV.offsetHeight + 2 * OFFSET_Y;
   }
+
   if (rtl) {
     // Prevent falling off left edge in RTL mode.
     anchorX = Math.max(MARGINS - window.scrollX, anchorX);
@@ -463,6 +507,35 @@ const show = function() {
       anchorX = windowWidth - DIV.offsetWidth - 2 * MARGINS;
     }
   }
-  DIV.style.top = anchorY + 'px';
-  DIV.style.left = anchorX + 'px';
+
+  return {x: anchorX, y: anchorY};
+};
+
+/**
+ * Create the tooltip and show it.
+ */
+const show = function() {
+  if (blocked) {
+    // Someone doesn't want us to show tooltips.
+    return;
+  }
+  poisonedElement = element;
+  if (!DIV) {
+    return;
+  }
+  // Erase all existing text.
+  DIV.textContent = '';
+
+  // Add new content.
+  renderContent();
+
+  // Display the tooltip.
+  const rtl = /** @type {{RTL: boolean}} */ (element).RTL;
+  DIV.style.direction = rtl ? 'rtl' : 'ltr';
+  DIV.style.display = 'block';
+  visible = true;
+
+  const {x, y} = getPosition(rtl);
+  DIV.style.left = x + 'px';
+  DIV.style.top = y + 'px';
 };

package/core/touch.js

@@ -15,13 +15,18 @@
  */
 goog.module('Blockly.Touch');
 
-const internalConstants = goog.require('Blockly.internalConstants');
 const utilsString = goog.require('Blockly.utils.string');
 /* eslint-disable-next-line no-unused-vars */
 const {Gesture} = goog.requireType('Blockly.Gesture');
 const {globalThis} = goog.require('Blockly.utils.global');
 
 
+/**
+ * Length in ms for a touch to become a long press.
+ * @const
+ */
+const LONGPRESS = 750;
+
 /**
  * Whether touch is enabled in the browser.
  * Copied from Closure's goog.events.BrowserFeature.TOUCH_ENABLED
@@ -107,7 +112,7 @@ const longStart = function(e, gesture) {
     if (gesture) {
       gesture.handleRightClick(e);
     }
-  }, internalConstants.LONGPRESS);
+  }, LONGPRESS);
 };
 exports.longStart = longStart;
 
@@ -212,7 +217,7 @@ exports.checkTouchIdentifier = checkTouchIdentifier;
  * @alias Blockly.Touch.setClientFromTouch
  */
 const setClientFromTouch = function(e) {
-  if (utilsString.startsWith(e.type, 'touch')) {
+  if (utilsString.startsWith(e.type, 'touch') && e.changedTouches) {
     // Map the touch event's properties to the event.
     const touchPoint = e.changedTouches[0];
     e.clientX = touchPoint.clientX;