blockly 8.0.4 → 8.0.5-beta.0

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

@@ -7,126 +7,88 @@
 /**
  * @fileoverview Blockly menu similar to Closure's goog.ui.Menu
  */
-'use strict';
 
 /**
  * Blockly menu similar to Closure's goog.ui.Menu
  * @class
  */
-goog.module('Blockly.Menu');
+import * as goog from '../closure/goog/goog.js';
+goog.declareModuleId('Blockly.Menu');
 
-const aria = goog.require('Blockly.utils.aria');
-const browserEvents = goog.require('Blockly.browserEvents');
-const dom = goog.require('Blockly.utils.dom');
-const style = goog.require('Blockly.utils.style');
-const {Coordinate} = goog.require('Blockly.utils.Coordinate');
-const {KeyCodes} = goog.require('Blockly.utils.KeyCodes');
-/* eslint-disable-next-line no-unused-vars */
-const {MenuItem} = goog.requireType('Blockly.MenuItem');
-/* eslint-disable-next-line no-unused-vars */
-const {Size} = goog.requireType('Blockly.utils.Size');
+import * as browserEvents from './browser_events.js';
+import type {MenuItem} from './menuitem.js';
+import * as aria from './utils/aria.js';
+import {Coordinate} from './utils/coordinate.js';
+import * as dom from './utils/dom.js';
+import {KeyCodes} from './utils/keycodes.js';
+import type {Size} from './utils/size.js';
+import * as style from './utils/style.js';
 
 
 /**
  * A basic menu class.
  * @alias Blockly.Menu
  */
-const Menu = class {
+export class Menu {
   /**
-   * Constructs a new Menu instance.
+   * Array of menu items.
+   * (Nulls are never in the array, but typing the array as nullable prevents
+   * the compiler from objecting to .indexOf(null))
    */
-  constructor() {
-    /**
-     * Array of menu items.
-     * (Nulls are never in the array, but typing the array as nullable prevents
-     * the compiler from objecting to .indexOf(null))
-     * @type {!Array<MenuItem>}
-     * @private
-     */
-    this.menuItems_ = [];
-
-    /**
-     * Coordinates of the mousedown event that caused this menu to open. Used to
-     * prevent the consequent mouseup event due to a simple click from
-     * activating a menu item immediately.
-     * @type {?Coordinate}
-     * @package
-     */
-    this.openingCoords = null;
+  private readonly menuItems_: MenuItem[] = [];
 
-    /**
-     * This is the element that we will listen to the real focus events on.
-     * A value of null means no menu item is highlighted.
-     * @type {?MenuItem}
-     * @private
-     */
-    this.highlightedItem_ = null;
-
-    /**
-     * Mouse over event data.
-     * @type {?browserEvents.Data}
-     * @private
-     */
-    this.mouseOverHandler_ = null;
-
-    /**
-     * Click event data.
-     * @type {?browserEvents.Data}
-     * @private
-     */
-    this.clickHandler_ = null;
-
-    /**
-     * Mouse enter event data.
-     * @type {?browserEvents.Data}
-     * @private
-     */
-    this.mouseEnterHandler_ = null;
-
-    /**
-     * Mouse leave event data.
-     * @type {?browserEvents.Data}
-     * @private
-     */
-    this.mouseLeaveHandler_ = null;
-
-    /**
-     * Key down event data.
-     * @type {?browserEvents.Data}
-     * @private
-     */
-    this.onKeyDownHandler_ = null;
-
-    /**
-     * The menu's root DOM element.
-     * @type {?HTMLDivElement}
-     * @private
-     */
-    this.element_ = null;
+  /**
+   * Coordinates of the mousedown event that caused this menu to open. Used to
+   * prevent the consequent mouseup event due to a simple click from
+   * activating a menu item immediately.
+   */
+  openingCoords: Coordinate|null = null;
 
-    /**
-     * ARIA name for this menu.
-     * @type {?aria.Role}
-     * @private
-     */
-    this.roleName_ = null;
-  }
+  /**
+   * This is the element that we will listen to the real focus events on.
+   * A value of null means no menu item is highlighted.
+   */
+  private highlightedItem_: MenuItem|null = null;
+
+  /** Mouse over event data. */
+  private mouseOverHandler_: browserEvents.Data|null = null;
+
+  /** Click event data. */
+  private clickHandler_: browserEvents.Data|null = null;
+
+  /** Mouse enter event data. */
+  private mouseEnterHandler_: browserEvents.Data|null = null;
+
+  /** Mouse leave event data. */
+  private mouseLeaveHandler_: browserEvents.Data|null = null;
+
+  /** Key down event data. */
+  private onKeyDownHandler_: browserEvents.Data|null = null;
+
+  /** The menu's root DOM element. */
+  private element_: HTMLDivElement|null = null;
+
+  /** ARIA name for this menu. */
+  private roleName_: aria.Role|null = null;
+
+  /** Constructs a new Menu instance. */
+  constructor() {}
 
   /**
    * Add a new menu item to the bottom of this menu.
-   * @param {!MenuItem} menuItem Menu item to append.
+   * @param menuItem Menu item to append.
+   * @internal
    */
-  addChild(menuItem) {
+  addChild(menuItem: MenuItem) {
     this.menuItems_.push(menuItem);
   }
 
   /**
    * Creates the menu DOM.
-   * @param {!Element} container Element upon which to append this menu.
+   * @param container Element upon which to append this menu.
    */
-  render(container) {
-    const element =
-        /** @type {!HTMLDivElement} */ (document.createElement('div'));
+  render(container: Element) {
+    const element = (document.createElement('div'));
     // goog-menu is deprecated, use blocklyMenu.  May 2020.
     element.className = 'blocklyMenu goog-menu blocklyNonSelectable';
     element.tabIndex = 0;
@@ -136,7 +98,7 @@ const Menu = class {
     this.element_ = element;
 
     // Add menu items.
-    for (let i = 0, menuItem; (menuItem = this.menuItems_[i]); i++) {
+    for (let i = 0, menuItem; menuItem = this.menuItems_[i]; i++) {
       element.appendChild(menuItem.createDom());
     }
 
@@ -157,49 +119,48 @@ const Menu = class {
 
   /**
    * Gets the menu's element.
-   * @return {?Element} The DOM element.
-   * @package
+   * @return The DOM element.
+   * @internal
    */
-  getElement() {
+  getElement(): Element|null {
     return this.element_;
   }
 
   /**
    * Focus the menu element.
-   * @package
+   * @internal
    */
   focus() {
     const el = this.getElement();
     if (el) {
-      el.focus({preventScroll: true});
+      // AnyDuringMigration because:  Property 'focus' does not exist on type
+      // 'Element'.
+      (el as AnyDuringMigration).focus({preventScroll: true});
       dom.addClass(el, 'blocklyFocused');
     }
   }
 
-  /**
-   * Blur the menu element.
-   * @private
-   */
-  blur_() {
+  /** Blur the menu element. */
+  private blur_() {
     const el = this.getElement();
     if (el) {
-      el.blur();
+      // AnyDuringMigration because:  Property 'blur' does not exist on type
+      // 'Element'.
+      (el as AnyDuringMigration).blur();
       dom.removeClass(el, 'blocklyFocused');
     }
   }
 
   /**
    * Set the menu accessibility role.
-   * @param {!aria.Role} roleName role name.
-   * @package
+   * @param roleName role name.
+   * @internal
    */
-  setRole(roleName) {
+  setRole(roleName: aria.Role) {
     this.roleName_ = roleName;
   }
 
-  /**
-   * Dispose of this menu.
-   */
+  /** Dispose of this menu. */
   dispose() {
     // Remove event handlers.
     if (this.mouseOverHandler_) {
@@ -224,7 +185,7 @@ const Menu = class {
     }
 
     // Remove menu items.
-    for (let i = 0, menuItem; (menuItem = this.menuItems_[i]); i++) {
+    for (let i = 0, menuItem; menuItem = this.menuItems_[i]; i++) {
       menuItem.dispose();
     }
     this.element_ = null;
@@ -235,11 +196,10 @@ const Menu = class {
   /**
    * Returns the child menu item that owns the given DOM element,
    * or null if no such menu item is found.
-   * @param {Element} elem DOM element whose owner is to be returned.
-   * @return {?MenuItem} Menu item for which the DOM element belongs to.
-   * @private
+   * @param elem DOM element whose owner is to be returned.
+   * @return Menu item for which the DOM element belongs to.
    */
-  getMenuItem_(elem) {
+  private getMenuItem_(elem: Element): MenuItem|null {
     const menuElem = this.getElement();
     // Node might be the menu border (resulting in no associated menu item), or
     // a menu item's div, or some element within the menu item.
@@ -248,13 +208,15 @@ const Menu = class {
     while (elem && elem !== menuElem) {
       if (dom.hasClass(elem, 'blocklyMenuItem')) {
         // Having found a menu item's div, locate that menu item in this menu.
-        for (let i = 0, menuItem; (menuItem = this.menuItems_[i]); i++) {
+        for (let i = 0, menuItem; menuItem = this.menuItems_[i]; i++) {
           if (menuItem.getElement() === elem) {
             return menuItem;
           }
         }
       }
-      elem = elem.parentElement;
+      // AnyDuringMigration because:  Type 'HTMLElement | null' is not
+      // assignable to type 'Element'.
+      elem = elem.parentElement as AnyDuringMigration;
     }
     return null;
   }
@@ -263,10 +225,10 @@ const Menu = class {
 
   /**
    * Highlights the given menu item, or clears highlighting if null.
-   * @param {?MenuItem} item Item to highlight, or null.
-   * @package
+   * @param item Item to highlight, or null.
+   * @internal
    */
-  setHighlighted(item) {
+  setHighlighted(item: MenuItem|null) {
     const currentHighlighted = this.highlightedItem_;
     if (currentHighlighted) {
       currentHighlighted.setHighlighted(false);
@@ -277,9 +239,8 @@ const Menu = class {
       this.highlightedItem_ = item;
       // Bring the highlighted item into view. This has no effect if the menu is
       // not scrollable.
-      const el = /** @type {!Element} */ (this.getElement());
-      style.scrollIntoContainerView(
-          /** @type {!Element} */ (item.getElement()), el);
+      const el = this.getElement() as Element;
+      style.scrollIntoContainerView(item.getElement() as Element, el);
 
       aria.setState(el, aria.State.ACTIVEDESCENDANT, item.getId());
     }
@@ -288,50 +249,49 @@ const Menu = class {
   /**
    * Highlights the next highlightable item (or the first if nothing is
    * currently highlighted).
-   * @package
+   * @internal
    */
   highlightNext() {
-    const index = this.menuItems_.indexOf(this.highlightedItem_);
+    // AnyDuringMigration because:  Argument of type 'MenuItem | null' is not
+    // assignable to parameter of type 'MenuItem'.
+    const index =
+        this.menuItems_.indexOf(this.highlightedItem_ as AnyDuringMigration);
     this.highlightHelper_(index, 1);
   }
 
   /**
    * Highlights the previous highlightable item (or the last if nothing is
    * currently highlighted).
-   * @package
+   * @internal
    */
   highlightPrevious() {
-    const index = this.menuItems_.indexOf(this.highlightedItem_);
+    // AnyDuringMigration because:  Argument of type 'MenuItem | null' is not
+    // assignable to parameter of type 'MenuItem'.
+    const index =
+        this.menuItems_.indexOf(this.highlightedItem_ as AnyDuringMigration);
     this.highlightHelper_(index < 0 ? this.menuItems_.length : index, -1);
   }
 
-  /**
-   * Highlights the first highlightable item.
-   * @private
-   */
-  highlightFirst_() {
+  /** Highlights the first highlightable item. */
+  private highlightFirst_() {
     this.highlightHelper_(-1, 1);
   }
 
-  /**
-   * Highlights the last highlightable item.
-   * @private
-   */
-  highlightLast_() {
+  /** Highlights the last highlightable item. */
+  private highlightLast_() {
     this.highlightHelper_(this.menuItems_.length, -1);
   }
 
   /**
    * Helper function that manages the details of moving the highlight among
    * child menuitems in response to keyboard events.
-   * @param {number} startIndex Start index.
-   * @param {number} delta Step direction: 1 to go down, -1 to go up.
-   * @private
+   * @param startIndex Start index.
+   * @param delta Step direction: 1 to go down, -1 to go up.
    */
-  highlightHelper_(startIndex, delta) {
+  private highlightHelper_(startIndex: number, delta: number) {
     let index = startIndex + delta;
     let menuItem;
-    while ((menuItem = this.menuItems_[index])) {
+    while (menuItem = this.menuItems_[index]) {
       if (menuItem.isEnabled()) {
         this.setHighlighted(menuItem);
         break;
@@ -344,11 +304,10 @@ const Menu = class {
 
   /**
    * Handles mouseover events. Highlight menuitems as the user hovers over them.
-   * @param {!Event} e Mouse event to handle.
-   * @private
+   * @param e Mouse event to handle.
    */
-  handleMouseOver_(e) {
-    const menuItem = this.getMenuItem_(/** @type {Element} */ (e.target));
+  private handleMouseOver_(e: Event) {
+    const menuItem = this.getMenuItem_(e.target as Element);
 
     if (menuItem) {
       if (menuItem.isEnabled()) {
@@ -363,15 +322,20 @@ const Menu = class {
 
   /**
    * Handles click events. Pass the event onto the child menuitem to handle.
-   * @param {!Event} e Click event to handle.
-   * @private
+   * @param e Click event to handle.
    */
-  handleClick_(e) {
+  private handleClick_(e: Event) {
     const oldCoords = this.openingCoords;
     // Clear out the saved opening coords immediately so they're not used twice.
     this.openingCoords = null;
-    if (oldCoords && typeof e.clientX === 'number') {
-      const newCoords = new Coordinate(e.clientX, e.clientY);
+    // AnyDuringMigration because:  Property 'clientX' does not exist on type
+    // 'Event'.
+    if (oldCoords && typeof (e as AnyDuringMigration).clientX === 'number') {
+      // AnyDuringMigration because:  Property 'clientY' does not exist on type
+      // 'Event'. AnyDuringMigration because:  Property 'clientX' does not exist
+      // on type 'Event'.
+      const newCoords = new Coordinate(
+          (e as AnyDuringMigration).clientX, (e as AnyDuringMigration).clientY);
       if (Coordinate.distance(oldCoords, newCoords) < 1) {
         // This menu was opened by a mousedown and we're handling the consequent
         // click event. The coords haven't changed, meaning this was the same
@@ -382,7 +346,7 @@ const Menu = class {
       }
     }
 
-    const menuItem = this.getMenuItem_(/** @type {Element} */ (e.target));
+    const menuItem = this.getMenuItem_(e.target as Element);
     if (menuItem) {
       menuItem.performAction();
     }
@@ -390,19 +354,17 @@ const Menu = class {
 
   /**
    * Handles mouse enter events. Focus the element.
-   * @param {!Event} _e Mouse event to handle.
-   * @private
+   * @param _e Mouse event to handle.
    */
-  handleMouseEnter_(_e) {
+  private handleMouseEnter_(_e: Event) {
     this.focus();
   }
 
   /**
    * Handles mouse leave events. Blur and clear highlight.
-   * @param {!Event} _e Mouse event to handle.
-   * @private
+   * @param _e Mouse event to handle.
    */
-  handleMouseLeave_(_e) {
+  private handleMouseLeave_(_e: Event) {
     if (this.getElement()) {
       this.blur_();
       this.setHighlighted(null);
@@ -415,21 +377,29 @@ const Menu = class {
    * Attempts to handle a keyboard event, if the menu item is enabled, by
    * calling
    * {@link handleKeyEventInternal_}.
-   * @param {!Event} e Key event to handle.
-   * @private
+   * @param e Key event to handle.
    */
-  handleKeyEvent_(e) {
+  private handleKeyEvent_(e: Event) {
     if (!this.menuItems_.length) {
       // Empty menu.
       return;
     }
-    if (e.shiftKey || e.ctrlKey || e.metaKey || e.altKey) {
+    // AnyDuringMigration because:  Property 'altKey' does not exist on type
+    // 'Event'. AnyDuringMigration because:  Property 'metaKey' does not exist
+    // on type 'Event'. AnyDuringMigration because:  Property 'ctrlKey' does not
+    // exist on type 'Event'. AnyDuringMigration because:  Property 'shiftKey'
+    // does not exist on type 'Event'.
+    if ((e as AnyDuringMigration).shiftKey ||
+        (e as AnyDuringMigration).ctrlKey ||
+        (e as AnyDuringMigration).metaKey || (e as AnyDuringMigration).altKey) {
       // Do not handle the key event if any modifier key is pressed.
       return;
     }
 
     const highlighted = this.highlightedItem_;
-    switch (e.keyCode) {
+    // AnyDuringMigration because:  Property 'keyCode' does not exist on type
+    // 'Event'.
+    switch ((e as AnyDuringMigration).keyCode) {
       case KeyCodes.ENTER:
       case KeyCodes.SPACE:
         if (highlighted) {
@@ -466,17 +436,14 @@ const Menu = class {
 
   /**
    * Get the size of a rendered menu.
-   * @return {!Size} Object with width and height properties.
-   * @package
+   * @return Object with width and height properties.
+   * @internal
    */
-  getSize() {
+  getSize(): Size {
     const menuDom = this.getElement();
-    const menuSize = style.getSize(/** @type {!Element} */
-                                   (menuDom));
+    const menuSize = style.getSize(menuDom as Element);
     // Recalculate height for the total content, not only box height.
-    menuSize.height = menuDom.scrollHeight;
+    menuSize.height = menuDom!.scrollHeight;
     return menuSize;
   }
-};
-
-exports.Menu = Menu;
+}

package/core/menuitem.d.ts

@@ -0,0 +1,118 @@
+/**
+ * @license
+ * Copyright 2019 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import * as aria from './utils/aria.js';
+/**
+ * Class representing an item in a menu.
+ * @alias Blockly.MenuItem
+ */
+export declare class MenuItem {
+    private readonly content;
+    private readonly opt_value?;
+    /** Is the menu item clickable, as opposed to greyed-out. */
+    private enabled_;
+    /** The DOM element for the menu item. */
+    private element_;
+    /** Whether the menu item is rendered right-to-left. */
+    private rightToLeft_;
+    /** ARIA name for this menu. */
+    private roleName_;
+    /** Is this menu item checkable. */
+    private checkable_;
+    /** Is this menu item currently checked. */
+    private checked_;
+    /** Is this menu item currently highlighted. */
+    private highlight_;
+    /** Bound function to call when this menu item is clicked. */
+    private actionHandler_;
+    /**
+     * @param content Text caption to display as the content of the item, or a
+     *     HTML element to display.
+     * @param opt_value Data/model associated with the menu item.
+     */
+    constructor(content: string | HTMLElement, opt_value?: string | undefined);
+    /**
+     * Creates the menuitem's DOM.
+     * @return Completed DOM.
+     */
+    createDom(): Element;
+    /** Dispose of this menu item. */
+    dispose(): void;
+    /**
+     * Gets the menu item's element.
+     * @return The DOM element.
+     * @internal
+     */
+    getElement(): Element | null;
+    /**
+     * Gets the unique ID for this menu item.
+     * @return Unique component ID.
+     * @internal
+     */
+    getId(): string;
+    /**
+     * Gets the value associated with the menu item.
+     * @return value Value associated with the menu item.
+     * @internal
+     */
+    getValue(): any;
+    /**
+     * Set menu item's rendering direction.
+     * @param rtl True if RTL, false if LTR.
+     * @internal
+     */
+    setRightToLeft(rtl: boolean): void;
+    /**
+     * Set the menu item's accessibility role.
+     * @param roleName Role name.
+     * @internal
+     */
+    setRole(roleName: aria.Role): void;
+    /**
+     * Sets the menu item to be checkable or not. Set to true for menu items
+     * that represent checkable options.
+     * @param checkable Whether the menu item is checkable.
+     * @internal
+     */
+    setCheckable(checkable: boolean): void;
+    /**
+     * Checks or unchecks the component.
+     * @param checked Whether to check or uncheck the component.
+     * @internal
+     */
+    setChecked(checked: boolean): void;
+    /**
+     * Highlights or unhighlights the component.
+     * @param highlight Whether to highlight or unhighlight the component.
+     * @internal
+     */
+    setHighlighted(highlight: boolean): void;
+    /**
+     * Returns true if the menu item is enabled, false otherwise.
+     * @return Whether the menu item is enabled.
+     * @internal
+     */
+    isEnabled(): boolean;
+    /**
+     * Enables or disables the menu item.
+     * @param enabled Whether to enable or disable the menu item.
+     * @internal
+     */
+    setEnabled(enabled: boolean): void;
+    /**
+     * Performs the appropriate action when the menu item is activated
+     * by the user.
+     * @internal
+     */
+    performAction(): void;
+    /**
+     * Set the handler that's called when the menu item is activated by the user.
+     * `obj` will be used as the 'this' object in the function when called.
+     * @param fn The handler.
+     * @param obj Used as the 'this' object in fn when called.
+     * @internal
+     */
+    onAction(fn: (p1: MenuItem) => any, obj: any): void;
+}