blockly 8.0.5 → 9.0.0-beta.0

package/core/{tooltip.js → tooltip.ts}

@@ -4,8 +4,6 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-'use strict';
-
 /**
  * Library to create tooltips for Blockly.
  * First, call createDom() after onload.
@@ -15,12 +13,12 @@
  * tooltip will be used. Third, call bindMouseEvents(e) passing the SVG element.
  * @namespace Blockly.Tooltip
  */
-goog.module('Blockly.Tooltip');
+import * as goog from '../closure/goog/goog.js';
+goog.declareModuleId('Blockly.Tooltip');
 
-const blocklyString = goog.require('Blockly.utils.string');
-const browserEvents = goog.require('Blockly.browserEvents');
-const common = goog.require('Blockly.common');
-const deprecation = goog.require('Blockly.utils.deprecation');
+import * as browserEvents from './browser_events.js';
+import * as common from './common.js';
+import * as blocklyString from './utils/string.js';
 
 
 /**
@@ -28,109 +26,71 @@ const deprecation = goog.require('Blockly.utils.deprecation');
  * Either a string, an object containing a tooltip property, or a function which
  * returns either a string, or another arbitrarily nested function which
  * eventually unwinds to a string.
- * @typedef {string|{tooltip}|function(): (string|!Function)}
  * @alias Blockly.Tooltip.TipInfo
  */
-let TipInfo;
-exports.TipInfo = TipInfo;
+export type TipInfo =
+    string|{tooltip: AnyDuringMigration}|(() => TipInfo|string|Function);
 
 /**
  * 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;
+export type CustomTooltip = (p1: Element, p2: Element) => AnyDuringMigration;
 
 /**
  * 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;
+let customTooltip: CustomTooltip|undefined = 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.
+ * @param customFn A custom tooltip used to render an alternate tooltip UI.
  * @alias Blockly.Tooltip.setCustomTooltip
  */
-const setCustomTooltip = function(customFn) {
+export function setCustomTooltip(customFn: CustomTooltip) {
   customTooltip = customFn;
-};
-exports.setCustomTooltip = setCustomTooltip;
+}
 
 /**
  * Gets the custom tooltip function.
- * @returns {!CustomTooltip|undefined} The custom tooltip function, if defined.
+ * @returns The custom tooltip function, if defined.
  */
-const getCustomTooltip = function() {
+export function getCustomTooltip(): CustomTooltip|undefined {
   return customTooltip;
-};
-exports.getCustomTooltip = getCustomTooltip;
+}
 
-/**
- * Is a tooltip currently showing?
- * @type {boolean}
- */
+/** Is a tooltip currently showing? */
 let visible = false;
 
 /**
  * Returns whether or not a tooltip is showing
- * @returns {boolean} True if a tooltip is showing
+ * @returns True if a tooltip is showing
  * @alias Blockly.Tooltip.isVisible
  */
-const isVisible = function() {
+export function isVisible(): boolean {
   return visible;
-};
-exports.isVisible = isVisible;
-
-Object.defineProperties(exports, {
-  /**
-   * Is a tooltip currently showing?
-   * @name Blockly.Tooltip.visible
-   * @type {boolean}
-   * @deprecated Use Blockly.Tooltip.isVisible() instead.  (September
-   *     2021)
-   * @suppress {checkTypes}
-   */
-  visible: {
-    get: function() {
-      deprecation.warn(
-          'Blockly.Tooltip.visible', 'September 2021', 'September 2022',
-          'Blockly.Tooltip.isVisible()');
-      return isVisible();
-    },
-  },
-});
+}
 
-/**
- * Is someone else blocking the tooltip from being shown?
- * @type {boolean}
- */
+/** Is someone else blocking the tooltip from being shown? */
 let blocked = false;
 
 /**
  * Maximum width (in characters) of a tooltip.
  * @alias Blockly.Tooltip.LIMIT
  */
-const LIMIT = 50;
-exports.LIMIT = LIMIT;
+export const LIMIT = 50;
 
-/**
- * PID of suspended thread to clear tooltip on mouse out.
- */
-let mouseOutPid = 0;
+/** PID of suspended thread to clear tooltip on mouse out. */
+let mouseOutPid: AnyDuringMigration = 0;
 
-/**
- * PID of suspended thread to show the tooltip.
- */
-let showPid = 0;
+/** PID of suspended thread to show the tooltip. */
+let showPid: AnyDuringMigration = 0;
 
 /**
  * Last observed X location of the mouse pointer (freezes when tooltip appears).
@@ -142,96 +102,64 @@ let lastX = 0;
  */
 let lastY = 0;
 
-/**
- * Current element being pointed at.
- * @type {Element}
- */
-let element = null;
+/** Current element being pointed at. */
+let element: AnyDuringMigration = null;
 
 /**
  * Once a tooltip has opened for an element, that element is 'poisoned' and
  * cannot respawn a tooltip until the pointer moves over a different element.
- * @type {Element}
  */
-let poisonedElement = null;
+let poisonedElement: AnyDuringMigration = null;
 
 /**
  * Horizontal offset between mouse cursor and tooltip.
  * @alias Blockly.Tooltip.OFFSET_X
  */
-const OFFSET_X = 0;
-exports.OFFSET_X = OFFSET_X;
+export const OFFSET_X = 0;
 
 /**
  * Vertical offset between mouse cursor and tooltip.
  * @alias Blockly.Tooltip.OFFSET_Y
  */
-const OFFSET_Y = 10;
-exports.OFFSET_Y = OFFSET_Y;
+export const OFFSET_Y = 10;
 
 /**
  * Radius mouse can move before killing tooltip.
  * @alias Blockly.Tooltip.RADIUS_OK
  */
-const RADIUS_OK = 10;
-exports.RADIUS_OK = RADIUS_OK;
+export const RADIUS_OK = 10;
 
 /**
  * Delay before tooltip appears.
  * @alias Blockly.Tooltip.HOVER_MS
  */
-const HOVER_MS = 750;
-exports.HOVER_MS = HOVER_MS;
+export const HOVER_MS = 750;
 
 /**
  * Horizontal padding between tooltip and screen edge.
  * @alias Blockly.Tooltip.MARGINS
  */
-const MARGINS = 5;
-exports.MARGINS = MARGINS;
+export const MARGINS = 5;
 
-/**
- * The HTML container.  Set once by createDom.
- * @type {?HTMLDivElement}
- */
-let DIV = null;
+/** The HTML container.  Set once by createDom. */
+let containerDiv: HTMLDivElement|null = null;
 
 /**
  * Returns the HTML tooltip container.
- * @returns {?HTMLDivElement} The HTML tooltip container.
+ * @returns The HTML tooltip container.
  * @alias Blockly.Tooltip.getDiv
  */
-const getDiv = function() {
-  return DIV;
-};
-exports.getDiv = getDiv;
-
-Object.defineProperties(exports, {
-  /**
-   * The HTML container.  Set once by createDom.
-   * @name Blockly.Tooltip.DIV
-   * @type {HTMLDivElement}
-   * @deprecated Use Blockly.Tooltip.getDiv() and .setDiv().
-   *     (September 2021)
-   * @suppress {checkTypes}
-   */
-  DIV: {
-    get: function() {
-      deprecation.warn(
-          'Blockly.Tooltip.DIV', 'September 2021', 'September 2022',
-          'Blockly.Tooltip.getDiv()');
-      return getDiv();
-    },
-  },
-});
+export function getDiv(): HTMLDivElement|null {
+  return containerDiv;
+}
 
 /**
  * Returns the tooltip text for the given element.
- * @param {?Object} object The object to get the tooltip text of.
- * @return {string} The tooltip text of the element.
+ * @param object The object to get the tooltip text of.
+ * @return The tooltip text of the element.
  * @alias Blockly.Tooltip.getTooltipOfObject
  */
-const getTooltipOfObject = function(object) {
+export function getTooltipOfObject(object: AnyDuringMigration|null): string {
   const obj = getTargetObject(object);
   if (obj) {
     let tooltip = obj.tooltip;
@@ -244,89 +172,86 @@ const getTooltipOfObject = function(object) {
     return tooltip;
   }
   return '';
-};
-exports.getTooltipOfObject = getTooltipOfObject;
+}
 
 /**
  * Returns the target object that the given object is targeting for its
  * tooltip. Could be the object itself.
- * @param {?Object} obj The object are trying to find the target tooltip
- *     object of.
- * @return {?{tooltip}} The target tooltip object.
- */
-const getTargetObject = function(obj) {
-  while (obj && obj.tooltip) {
-    if ((typeof obj.tooltip === 'string') ||
-        (typeof obj.tooltip === 'function')) {
-      return obj;
+ * @param obj The object are trying to find the target tooltip object of.
+ * @return The target tooltip object.
+ */
+function getTargetObject(obj: object|null): {tooltip: AnyDuringMigration}|null {
+  while (obj && (obj as any).tooltip) {
+    if (typeof (obj as any).tooltip === 'string' ||
+        typeof (obj as any).tooltip === 'function') {
+      return obj as {tooltip: string | (() => string)};
     }
-    obj = obj.tooltip;
+    obj = (obj as any).tooltip;
   }
   return null;
-};
+}
 
 /**
  * Create the tooltip div and inject it onto the page.
  * @alias Blockly.Tooltip.createDom
  */
-const createDom = function() {
-  if (DIV) {
+export function createDom() {
+  if (containerDiv) {
     return;  // Already created.
   }
   // Create an HTML container for popup overlays (e.g. editor widgets).
-  DIV = /** @type {!HTMLDivElement} */ (document.createElement('div'));
-  DIV.className = 'blocklyTooltipDiv';
+  containerDiv = document.createElement('div');
+  containerDiv.className = 'blocklyTooltipDiv';
   const container = common.getParentContainer() || document.body;
-  container.appendChild(DIV);
-};
-exports.createDom = createDom;
+  container.appendChild(containerDiv);
+}
 
 /**
  * Binds the required mouse events onto an SVG element.
- * @param {!Element} element SVG element onto which tooltip is to be bound.
+ * @param element SVG element onto which tooltip is to be bound.
  * @alias Blockly.Tooltip.bindMouseEvents
  */
-const bindMouseEvents = function(element) {
-  element.mouseOverWrapper_ =
+export function bindMouseEvents(element: Element) {
+  // TODO (#6097): Don't stash wrapper info on the DOM.
+  (element as AnyDuringMigration).mouseOverWrapper_ =
       browserEvents.bind(element, 'mouseover', null, onMouseOver);
-  element.mouseOutWrapper_ =
+  (element as AnyDuringMigration).mouseOutWrapper_ =
       browserEvents.bind(element, 'mouseout', null, onMouseOut);
 
   // Don't use bindEvent_ for mousemove since that would create a
   // corresponding touch handler, even though this only makes sense in the
   // context of a mouseover/mouseout.
   element.addEventListener('mousemove', onMouseMove, false);
-};
-exports.bindMouseEvents = bindMouseEvents;
+}
 
 /**
  * Unbinds tooltip mouse events from the SVG element.
- * @param {!Element} element SVG element onto which tooltip is bound.
+ * @param element SVG element onto which tooltip is bound.
  * @alias Blockly.Tooltip.unbindMouseEvents
  */
-const unbindMouseEvents = function(element) {
+export function unbindMouseEvents(element: Element) {
   if (!element) {
     return;
   }
-  browserEvents.unbind(element.mouseOverWrapper_);
-  browserEvents.unbind(element.mouseOutWrapper_);
+  // TODO (#6097): Don't stash wrapper info on the DOM.
+  browserEvents.unbind((element as AnyDuringMigration).mouseOverWrapper_);
+  browserEvents.unbind((element as AnyDuringMigration).mouseOutWrapper_);
   element.removeEventListener('mousemove', onMouseMove);
-};
-exports.unbindMouseEvents = unbindMouseEvents;
+}
 
 /**
  * Hide the tooltip if the mouse is over a different object.
  * Initialize the tooltip to potentially appear for this object.
- * @param {!Event} e Mouse event.
+ * @param e Mouse event.
  */
-const onMouseOver = function(e) {
+function onMouseOver(e: Event) {
   if (blocked) {
     // Someone doesn't want us to show tooltips.
     return;
   }
   // If the tooltip is an object, treat it as a pointer to the next object in
   // the chain to look at.  Terminate when a string or function is found.
-  const newElement = /** @type {Element} */ (getTargetObject(e.currentTarget));
+  const newElement = getTargetObject(e.currentTarget);
   if (element !== newElement) {
     hide();
     poisonedElement = null;
@@ -334,13 +259,13 @@ const onMouseOver = function(e) {
   }
   // Forget about any immediately preceding mouseOut event.
   clearTimeout(mouseOutPid);
-};
+}
 
 /**
  * Hide the tooltip if the mouse leaves the object and enters the workspace.
- * @param {!Event} _e Mouse event.
+ * @param _e Mouse event.
  */
-const onMouseOut = function(_e) {
+function onMouseOut(_e: Event) {
   if (blocked) {
     // Someone doesn't want us to show tooltips.
     return;
@@ -355,15 +280,15 @@ const onMouseOut = function(_e) {
     hide();
   }, 1);
   clearTimeout(showPid);
-};
+}
 
 /**
  * When hovering over an element, schedule a tooltip to be shown.  If a tooltip
  * is already visible, hide it if the mouse strays out of a certain radius.
- * @param {!Event} e Mouse event.
+ * @param e Mouse event.
  */
-const onMouseMove = function(e) {
-  if (!element || !element.tooltip) {
+function onMouseMove(e: Event) {
+  if (!element || !(element as AnyDuringMigration).tooltip) {
     // No tooltip here to show.
     return;
   } else if (blocked) {
@@ -374,8 +299,12 @@ const onMouseMove = function(e) {
   if (visible) {
     // Compute the distance between the mouse position when the tooltip was
     // shown and the current mouse position.  Pythagorean theorem.
-    const dx = lastX - e.pageX;
-    const dy = lastY - e.pageY;
+    // AnyDuringMigration because:  Property 'pageX' does not exist on type
+    // 'Event'.
+    const dx = lastX - (e as AnyDuringMigration).pageX;
+    // AnyDuringMigration because:  Property 'pageY' does not exist on type
+    // 'Event'.
+    const dy = lastY - (e as AnyDuringMigration).pageY;
     if (Math.sqrt(dx * dx + dy * dy) > RADIUS_OK) {
       hide();
     }
@@ -383,159 +312,152 @@ const onMouseMove = function(e) {
     // The mouse moved, clear any previously scheduled tooltip.
     clearTimeout(showPid);
     // Maybe this time the mouse will stay put.  Schedule showing of tooltip.
-    lastX = e.pageX;
-    lastY = e.pageY;
+    // AnyDuringMigration because:  Property 'pageX' does not exist on type
+    // 'Event'.
+    lastX = (e as AnyDuringMigration).pageX;
+    // AnyDuringMigration because:  Property 'pageY' does not exist on type
+    // 'Event'.
+    lastY = (e as AnyDuringMigration).pageY;
     showPid = setTimeout(show, HOVER_MS);
   }
-};
+}
 
 /**
  * Dispose of the tooltip.
  * @alias Blockly.Tooltip.dispose
- * @package
+ * @internal
  */
-const dispose = function() {
+export function dispose() {
   element = null;
   poisonedElement = null;
   hide();
-};
-exports.dispose = dispose;
+}
 
 /**
  * Hide the tooltip.
  * @alias Blockly.Tooltip.hide
  */
-const hide = function() {
+export function hide() {
   if (visible) {
     visible = false;
-    if (DIV) {
-      DIV.style.display = 'none';
+    if (containerDiv) {
+      containerDiv.style.display = 'none';
     }
   }
   if (showPid) {
     clearTimeout(showPid);
   }
-};
-exports.hide = hide;
+}
 
 /**
  * Hide any in-progress tooltips and block showing new tooltips until the next
  * call to unblock().
  * @alias Blockly.Tooltip.block
- * @package
+ * @internal
  */
-const block = function() {
+export function block() {
   hide();
   blocked = true;
-};
-exports.block = block;
+}
 
 /**
  * Unblock tooltips: allow them to be scheduled and shown according to their own
  * logic.
  * @alias Blockly.Tooltip.unblock
- * @package
+ * @internal
  */
-const unblock = function() {
+export function unblock() {
   blocked = false;
-};
-exports.unblock = unblock;
+}
 
-/**
- * Renders the tooltip content into the tooltip div.
- */
-const renderContent = function() {
-  if (!DIV || !element) {
+/** Renders the tooltip content into the tooltip div. */
+function renderContent() {
+  if (!containerDiv || !element) {
     // This shouldn't happen, but if it does, we can't render.
     return;
   }
   if (typeof customTooltip === 'function') {
-    customTooltip(DIV, element);
+    customTooltip(containerDiv, element);
   } else {
     renderDefaultContent();
   }
-};
+}
 
-/**
- * Renders the default tooltip UI.
- */
-const renderDefaultContent = function() {
+/** Renders the default tooltip UI. */
+function renderDefaultContent() {
   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 = /** @type {!HTMLDivElement} */ (document.createElement('div'));
+    const div = (document.createElement('div'));
     div.appendChild(document.createTextNode(lines[i]));
-    DIV.appendChild(div);
+    containerDiv!.appendChild(div);
   }
-};
+}
 
 /**
  * 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.
+ * @param rtl True if the tooltip should be in right-to-left layout.
+ * @returns Coordinates at which the tooltip div should be placed.
  */
-const getPosition = function(rtl) {
+function getPosition(rtl: boolean): {x: number, y: number} {
   // Position the tooltip just below the cursor.
   const windowWidth = document.documentElement.clientWidth;
   const windowHeight = document.documentElement.clientHeight;
 
   let anchorX = lastX;
   if (rtl) {
-    anchorX -= OFFSET_X + DIV.offsetWidth;
+    anchorX -= OFFSET_X + containerDiv!.offsetWidth;
   } else {
     anchorX += OFFSET_X;
   }
 
   let anchorY = lastY + OFFSET_Y;
-  if (anchorY + DIV.offsetHeight > windowHeight + window.scrollY) {
+  if (anchorY + containerDiv!.offsetHeight > windowHeight + window.scrollY) {
     // Falling off the bottom of the screen; shift the tooltip up.
-    anchorY -= DIV.offsetHeight + 2 * OFFSET_Y;
+    anchorY -= containerDiv!.offsetHeight + 2 * OFFSET_Y;
   }
 
   if (rtl) {
     // Prevent falling off left edge in RTL mode.
     anchorX = Math.max(MARGINS - window.scrollX, anchorX);
   } else {
-    if (anchorX + DIV.offsetWidth >
+    if (anchorX + containerDiv!.offsetWidth >
         windowWidth + window.scrollX - 2 * MARGINS) {
       // Falling off the right edge of the screen;
       // clamp the tooltip on the edge.
-      anchorX = windowWidth - DIV.offsetWidth - 2 * MARGINS;
+      anchorX = windowWidth - containerDiv!.offsetWidth - 2 * MARGINS;
     }
   }
 
   return {x: anchorX, y: anchorY};
-};
+}
 
-/**
- * Create the tooltip and show it.
- */
-const show = function() {
+/** Create the tooltip and show it. */
+function show() {
   if (blocked) {
     // Someone doesn't want us to show tooltips.
     return;
   }
   poisonedElement = element;
-  if (!DIV) {
+  if (!containerDiv) {
     return;
   }
   // Erase all existing text.
-  DIV.textContent = '';
+  containerDiv.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';
+  const rtl = (element as any).RTL;
+  containerDiv.style.direction = rtl ? 'rtl' : 'ltr';
+  containerDiv.style.display = 'block';
   visible = true;
 
   const {x, y} = getPosition(rtl);
-  DIV.style.left = x + 'px';
-  DIV.style.top = y + 'px';
-};
+  containerDiv.style.left = x + 'px';
+  containerDiv.style.top = y + 'px';
+}