blockly 8.0.5 → 9.0.0-beta.0

package/core/blockly_options.d.ts

@@ -0,0 +1,69 @@
+/**
+ * @license
+ * Copyright 2016 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { Theme, ITheme } from './theme.js';
+import type { WorkspaceSvg } from './workspace_svg.js';
+import type { ToolboxDefinition } from './utils/toolbox.js';
+/**
+ * Blockly options.
+ * @alias Blockly.BlocklyOptions
+ */
+export interface BlocklyOptions {
+    collapse?: boolean;
+    comments?: boolean;
+    css?: boolean;
+    disable?: boolean;
+    grid?: GridOptions;
+    horizontalLayout?: boolean;
+    maxBlocks?: number;
+    maxInstances?: {
+        [blockType: string]: number;
+    };
+    media?: string;
+    move?: MoveOptions;
+    oneBasedIndex?: boolean;
+    readOnly?: boolean;
+    renderer?: string;
+    rendererOverrides?: {
+        [rendererConstant: string]: any;
+    };
+    rtl?: boolean;
+    scrollbars?: ScrollbarOptions | boolean;
+    sounds?: boolean;
+    theme?: Theme | string | ITheme;
+    toolbox?: string | ToolboxDefinition | Element;
+    toolboxPosition?: string;
+    trashcan?: boolean;
+    maxTrashcanContents?: number;
+    plugins?: {
+        [key: string]: (new (...p1: any[]) => any) | string;
+    };
+    zoom?: ZoomOptions;
+    parentWorkspace?: WorkspaceSvg;
+}
+export interface GridOptions {
+    colour?: string;
+    length?: number;
+    snap?: boolean;
+    spacing?: number;
+}
+export interface MoveOptions {
+    drag?: boolean;
+    scrollbars?: boolean | ScrollbarOptions;
+    wheel?: boolean;
+}
+export interface ScrollbarOptions {
+    horizontal?: boolean;
+    vertical?: boolean;
+}
+export interface ZoomOptions {
+    controls?: boolean;
+    maxScale?: number;
+    minScale?: number;
+    pinch?: boolean;
+    scaleSpeed?: number;
+    startScale?: number;
+    wheel?: boolean;
+}

package/core/blockly_options.ts

@@ -0,0 +1,81 @@
+/**
+ * @license
+ * Copyright 2016 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * @fileoverview Object that defines user-specified options for the workspace.
+ */
+
+/**
+ * Object that defines user-specified options for the workspace.
+ * @namespace Blockly.BlocklyOptions
+ */
+import * as goog from '../closure/goog/goog.js';
+goog.declareModuleId('Blockly.BlocklyOptions');
+
+import type {Theme, ITheme} from './theme.js';
+import type {WorkspaceSvg} from './workspace_svg.js';
+import type {ToolboxDefinition} from './utils/toolbox.js';
+
+
+/**
+ * Blockly options.
+ * @alias Blockly.BlocklyOptions
+ */
+export interface BlocklyOptions {
+  collapse?: boolean;
+  comments?: boolean;
+  css?: boolean;
+  disable?: boolean;
+  grid?: GridOptions;
+  horizontalLayout?: boolean;
+  maxBlocks?: number;
+  maxInstances?: {[blockType: string]: number};
+  media?: string;
+  move?: MoveOptions;
+  oneBasedIndex?: boolean;
+  readOnly?: boolean;
+  renderer?: string;
+  rendererOverrides?: {[rendererConstant: string]: any};
+  rtl?: boolean;
+  scrollbars?: ScrollbarOptions|boolean;
+  sounds?: boolean;
+  theme?: Theme|string|ITheme;
+  toolbox?: string|ToolboxDefinition|Element;
+  toolboxPosition?: string;
+  trashcan?: boolean;
+  maxTrashcanContents?: number;
+  plugins?: {[key: string]: (new(...p1: any[]) => any)|string};
+  zoom?: ZoomOptions;
+  parentWorkspace?: WorkspaceSvg;
+}
+
+export interface GridOptions {
+  colour?: string;
+  length?: number;
+  snap?: boolean;
+  spacing?: number;
+}
+
+export interface MoveOptions {
+  drag?: boolean;
+  scrollbars?: boolean|ScrollbarOptions;
+  wheel?: boolean;
+}
+
+export interface ScrollbarOptions {
+  horizontal?: boolean;
+  vertical?: boolean;
+}
+
+export interface ZoomOptions {
+  controls?: boolean;
+  maxScale?: number;
+  minScale?: number;
+  pinch?: boolean;
+  scaleSpeed?: number;
+  startScale?: number;
+  wheel?: boolean;
+}

package/core/blocks.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @license
+ * Copyright 2013 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * A block definition.  For now this very lose, but it can potentially
+ * be refined e.g. by replacing this typedef with a class definition.
+ */
+export declare type BlockDefinition = any;
+/**
+ * A mapping of block type names to block prototype objects.
+ * @alias Blockly.blocks.Blocks
+ */
+export declare const Blocks: {
+    [key: string]: BlockDefinition;
+};

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

@@ -7,27 +7,23 @@
 /**
  * @fileoverview A mapping of block type names to block prototype objects.
  */
-'use strict';
 
 /**
  * A mapping of block type names to block prototype objects.
  * @namespace Blockly.blocks
  */
-goog.module('Blockly.blocks');
+import * as goog from '../closure/goog/goog.js';
+goog.declareModuleId('Blockly.blocks');
 
 
 /**
  * A block definition.  For now this very lose, but it can potentially
  * be refined e.g. by replacing this typedef with a class definition.
- * @typedef {!Object}
  */
-let BlockDefinition;
-exports.BlockDefinition = BlockDefinition;
+export type BlockDefinition = AnyDuringMigration;
 
 /**
  * A mapping of block type names to block prototype objects.
- * @type {!Object<string,!BlockDefinition>}
  * @alias Blockly.blocks.Blocks
  */
-const Blocks = Object.create(null);
-exports.Blocks = Blocks;
+export const Blocks: {[key: string]: BlockDefinition} = Object.create(null);

package/core/browser_events.d.ts

@@ -0,0 +1,85 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Blockly opaque event data used to unbind events when using
+ * `bind` and `conditionalBind`.
+ * @alias Blockly.browserEvents.Data
+ */
+export declare type Data = [EventTarget, string, (e: Event) => void][];
+/**
+ * Bind an event handler that can be ignored if it is not part of the active
+ * touch stream.
+ * Use this for events that either start or continue a multi-part gesture (e.g.
+ * mousedown or mousemove, which may be part of a drag or click).
+ * @param node Node upon which to listen.
+ * @param name Event name to listen to (e.g. 'mousedown').
+ * @param thisObject The value of 'this' in the function.
+ * @param func Function to call when event is triggered.
+ * @param opt_noCaptureIdentifier True if triggering on this event should not
+ *     block execution of other event handlers on this touch or other
+ *     simultaneous touches.  False by default.
+ * @param opt_noPreventDefault True if triggering on this event should prevent
+ *     the default handler.  False by default.  If opt_noPreventDefault is
+ *     provided, opt_noCaptureIdentifier must also be provided.
+ * @return Opaque data that can be passed to unbindEvent_.
+ * @alias Blockly.browserEvents.conditionalBind
+ */
+export declare function conditionalBind(node: EventTarget, name: string, thisObject: Object | null, func: Function, opt_noCaptureIdentifier?: boolean, opt_noPreventDefault?: boolean): Data;
+/**
+ * Bind an event handler that should be called regardless of whether it is part
+ * of the active touch stream.
+ * Use this for events that are not part of a multi-part gesture (e.g.
+ * mouseover for tooltips).
+ * @param node Node upon which to listen.
+ * @param name Event name to listen to (e.g. 'mousedown').
+ * @param thisObject The value of 'this' in the function.
+ * @param func Function to call when event is triggered.
+ * @return Opaque data that can be passed to unbindEvent_.
+ * @alias Blockly.browserEvents.bind
+ */
+export declare function bind(node: EventTarget, name: string, thisObject: Object | null, func: Function): Data;
+/**
+ * Unbind one or more events event from a function call.
+ * @param bindData Opaque data from bindEvent_.
+ *     This list is emptied during the course of calling this function.
+ * @return The function call.
+ * @alias Blockly.browserEvents.unbind
+ */
+export declare function unbind(bindData: Data): (e: Event) => void;
+/**
+ * Returns true if this event is targeting a text input widget?
+ * @param e An event.
+ * @return True if text input.
+ * @alias Blockly.browserEvents.isTargetInput
+ */
+export declare function isTargetInput(e: Event): boolean;
+/**
+ * Returns true this event is a right-click.
+ * @param e Mouse event.
+ * @return True if right-click.
+ * @alias Blockly.browserEvents.isRightButton
+ */
+export declare function isRightButton(e: MouseEvent): boolean;
+/**
+ * Returns the converted coordinates of the given mouse event.
+ * The origin (0,0) is the top-left corner of the Blockly SVG.
+ * @param e Mouse event.
+ * @param svg SVG element.
+ * @param matrix Inverted screen CTM to use.
+ * @return Object with .x and .y properties.
+ * @alias Blockly.browserEvents.mouseToSvg
+ */
+export declare function mouseToSvg(e: MouseEvent, svg: SVGSVGElement, matrix: SVGMatrix | null): SVGPoint;
+/**
+ * Returns the scroll delta of a mouse event in pixel units.
+ * @param e Mouse event.
+ * @return Scroll delta object with .x and .y properties.
+ * @alias Blockly.browserEvents.getScrollDeltaPixels
+ */
+export declare function getScrollDeltaPixels(e: WheelEvent): {
+    x: number;
+    y: number;
+};

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

@@ -7,34 +7,29 @@
 /**
  * @fileoverview Browser event handling.
  */
-'use strict';
 
 /**
  * Browser event handling.
  * @namespace Blockly.browserEvents
  */
-goog.module('Blockly.browserEvents');
+import * as goog from '../closure/goog/goog.js';
+goog.declareModuleId('Blockly.browserEvents');
 
-const Touch = goog.require('Blockly.Touch');
-const userAgent = goog.require('Blockly.utils.userAgent');
-const {globalThis} = goog.require('Blockly.utils.global');
+import * as Touch from './touch.js';
+import * as userAgent from './utils/useragent.js';
 
 
 /**
  * Blockly opaque event data used to unbind events when using
  * `bind` and `conditionalBind`.
- * @typedef {!Array<!Array>}
  * @alias Blockly.browserEvents.Data
  */
-let Data;
-exports.Data = Data;
+export type Data = [EventTarget, string, (e: Event) => void][];
 
 /**
  * The multiplier for scroll wheel deltas using the line delta mode.
  * See https://developer.mozilla.org/en-US/docs/Web/API/WheelEvent/deltaMode
  * for more information on deltaMode.
- * @type {number}
- * @const
  */
 const LINE_MODE_MULTIPLIER = 40;
 
@@ -42,8 +37,6 @@ const LINE_MODE_MULTIPLIER = 40;
  * The multiplier for scroll wheel deltas using the page delta mode.
  * See https://developer.mozilla.org/en-US/docs/Web/API/WheelEvent/deltaMode
  * for more information on deltaMode.
- * @type {number}
- * @const
  */
 const PAGE_MODE_MULTIPLIER = 125;
 
@@ -52,26 +45,24 @@ const PAGE_MODE_MULTIPLIER = 125;
  * touch stream.
  * Use this for events that either start or continue a multi-part gesture (e.g.
  * mousedown or mousemove, which may be part of a drag or click).
- * @param {!EventTarget} node Node upon which to listen.
- * @param {string} name Event name to listen to (e.g. 'mousedown').
- * @param {?Object} thisObject The value of 'this' in the function.
- * @param {!Function} func Function to call when event is triggered.
- * @param {boolean=} opt_noCaptureIdentifier True if triggering on this event
- *     should not block execution of other event handlers on this touch or
- *     other simultaneous touches.  False by default.
- * @param {boolean=} opt_noPreventDefault True if triggering on this event
- *     should prevent the default handler.  False by default.  If
- *     opt_noPreventDefault is provided, opt_noCaptureIdentifier must also be
- *     provided.
- * @return {!Data} Opaque data that can be passed to
- *     unbindEvent_.
+ * @param node Node upon which to listen.
+ * @param name Event name to listen to (e.g. 'mousedown').
+ * @param thisObject The value of 'this' in the function.
+ * @param func Function to call when event is triggered.
+ * @param opt_noCaptureIdentifier True if triggering on this event should not
+ *     block execution of other event handlers on this touch or other
+ *     simultaneous touches.  False by default.
+ * @param opt_noPreventDefault True if triggering on this event should prevent
+ *     the default handler.  False by default.  If opt_noPreventDefault is
+ *     provided, opt_noCaptureIdentifier must also be provided.
+ * @return Opaque data that can be passed to unbindEvent_.
  * @alias Blockly.browserEvents.conditionalBind
  */
-const conditionalBind = function(
-    node, name, thisObject, func, opt_noCaptureIdentifier,
-    opt_noPreventDefault) {
+export function conditionalBind(
+    node: EventTarget, name: string, thisObject: Object|null, func: Function,
+    opt_noCaptureIdentifier?: boolean, opt_noPreventDefault?: boolean): Data {
   let handled = false;
-  const wrapFunc = function(e) {
+  function wrapFunc(e: Event) {
     const captureIdentifier = !opt_noCaptureIdentifier;
     // Handle each touch point separately.  If the event was a mouse event, this
     // will hand back an array with one element, which we're fine handling.
@@ -89,10 +80,10 @@ const conditionalBind = function(
       }
       handled = true;
     }
-  };
+  }
 
-  const bindData = [];
-  if (globalThis['PointerEvent'] && (name in Touch.TOUCH_MAP)) {
+  const bindData: Data = [];
+  if (globalThis['PointerEvent'] && name in Touch.TOUCH_MAP) {
     for (let i = 0; i < Touch.TOUCH_MAP[name].length; i++) {
       const type = Touch.TOUCH_MAP[name][i];
       node.addEventListener(type, wrapFunc, false);
@@ -104,7 +95,7 @@ const conditionalBind = function(
 
     // Add equivalent touch event.
     if (name in Touch.TOUCH_MAP) {
-      const touchWrapFunc = function(e) {
+      const touchWrapFunc = (e: Event) => {
         wrapFunc(e);
         // Calling preventDefault stops the browser from scrolling/zooming the
         // page.
@@ -121,34 +112,33 @@ const conditionalBind = function(
     }
   }
   return bindData;
-};
-exports.conditionalBind = conditionalBind;
-
+}
 
 /**
  * Bind an event handler that should be called regardless of whether it is part
  * of the active touch stream.
  * Use this for events that are not part of a multi-part gesture (e.g.
  * mouseover for tooltips).
- * @param {!EventTarget} node Node upon which to listen.
- * @param {string} name Event name to listen to (e.g. 'mousedown').
- * @param {?Object} thisObject The value of 'this' in the function.
- * @param {!Function} func Function to call when event is triggered.
- * @return {!Data} Opaque data that can be passed to
- *     unbindEvent_.
+ * @param node Node upon which to listen.
+ * @param name Event name to listen to (e.g. 'mousedown').
+ * @param thisObject The value of 'this' in the function.
+ * @param func Function to call when event is triggered.
+ * @return Opaque data that can be passed to unbindEvent_.
  * @alias Blockly.browserEvents.bind
  */
-const bind = function(node, name, thisObject, func) {
-  const wrapFunc = function(e) {
+export function bind(
+    node: EventTarget, name: string, thisObject: Object|null,
+    func: Function): Data {
+  function wrapFunc(e: Event) {
     if (thisObject) {
       func.call(thisObject, e);
     } else {
       func(e);
     }
-  };
+  }
 
-  const bindData = [];
-  if (globalThis['PointerEvent'] && (name in Touch.TOUCH_MAP)) {
+  const bindData: Data = [];
+  if (globalThis['PointerEvent'] && name in Touch.TOUCH_MAP) {
     for (let i = 0; i < Touch.TOUCH_MAP[name].length; i++) {
       const type = Touch.TOUCH_MAP[name][i];
       node.addEventListener(type, wrapFunc, false);
@@ -160,13 +150,17 @@ const bind = function(node, name, thisObject, func) {
 
     // Add equivalent touch event.
     if (name in Touch.TOUCH_MAP) {
-      const touchWrapFunc = function(e) {
+      const touchWrapFunc = (e: Event) => {
         // Punt on multitouch events.
-        if (e.changedTouches && e.changedTouches.length === 1) {
+        if (e instanceof TouchEvent && e.changedTouches &&
+            e.changedTouches.length === 1) {
           // Map the touch event's properties to the event.
           const touchPoint = e.changedTouches[0];
-          e.clientX = touchPoint.clientX;
-          e.clientY = touchPoint.clientY;
+          // TODO (6311): We are trying to make a touch event look like a mouse
+          //   event, which is not allowed, because it requires adding more
+          //   properties to the event. How do we want to deal with this?
+          (e as AnyDuringMigration).clientX = touchPoint.clientX;
+          (e as AnyDuringMigration).clientY = touchPoint.clientY;
         }
         wrapFunc(e);
 
@@ -181,90 +175,102 @@ const bind = function(node, name, thisObject, func) {
     }
   }
   return bindData;
-};
-exports.bind = bind;
+}
 
 /**
  * Unbind one or more events event from a function call.
- * @param {!Data} bindData Opaque data from bindEvent_.
+ * @param bindData Opaque data from bindEvent_.
  *     This list is emptied during the course of calling this function.
- * @return {!Function} The function call.
+ * @return The function call.
  * @alias Blockly.browserEvents.unbind
  */
-const unbind = function(bindData) {
-  let func;
+export function unbind(bindData: Data): (e: Event) => void {
+  // Accessing an element of the last property of the array is unsafe if the
+  // bindData is an empty array. But that should never happen because developers
+  // should only pass Data from bind or conditionalBind.
+  let callback = bindData[bindData.length - 1][2];
   while (bindData.length) {
     const bindDatum = bindData.pop();
-    const node = bindDatum[0];
-    const name = bindDatum[1];
-    func = bindDatum[2];
+    const node = bindDatum![0];
+    const name = bindDatum![1];
+    const func = bindDatum![2];
     node.removeEventListener(name, func, false);
   }
-  return func;
-};
-exports.unbind = unbind;
+  return callback;
+}
 
 /**
  * Returns true if this event is targeting a text input widget?
- * @param {!Event} e An event.
- * @return {boolean} True if text input.
+ * @param e An event.
+ * @return True if text input.
  * @alias Blockly.browserEvents.isTargetInput
  */
-const isTargetInput = function(e) {
-  return e.target.type === 'textarea' || e.target.type === 'text' ||
-      e.target.type === 'number' || e.target.type === 'email' ||
-      e.target.type === 'password' || e.target.type === 'search' ||
-      e.target.type === 'tel' || e.target.type === 'url' ||
-      e.target.isContentEditable ||
-      (e.target.dataset && e.target.dataset.isTextInput === 'true');
-};
-exports.isTargetInput = isTargetInput;
+export function isTargetInput(e: Event): boolean {
+  if (e.target instanceof HTMLElement) {
+    if (e.target.isContentEditable ||
+        e.target.getAttribute('data-is-text-input') === 'true') {
+      return true;
+    }
+
+    if (e.target instanceof HTMLInputElement) {
+      const target = e.target;
+      return target.type === 'text' || target.type === 'number' ||
+          target.type === 'email' || target.type === 'password' ||
+          target.type === 'search' || target.type === 'tel' ||
+          target.type === 'url';
+    }
+
+    if (e.target instanceof HTMLTextAreaElement) {
+      return true;
+    }
+  }
+
+  return false;
+}
 
 /**
  * Returns true this event is a right-click.
- * @param {!Event} e Mouse event.
- * @return {boolean} True if right-click.
+ * @param e Mouse event.
+ * @return True if right-click.
  * @alias Blockly.browserEvents.isRightButton
  */
-const isRightButton = function(e) {
+export function isRightButton(e: MouseEvent): boolean {
   if (e.ctrlKey && userAgent.MAC) {
     // Control-clicking on Mac OS X is treated as a right-click.
     // WebKit on Mac OS X fails to change button to 2 (but Gecko does).
     return true;
   }
   return e.button === 2;
-};
-exports.isRightButton = isRightButton;
+}
 
 /**
  * Returns the converted coordinates of the given mouse event.
  * The origin (0,0) is the top-left corner of the Blockly SVG.
- * @param {!Event} e Mouse event.
- * @param {!Element} svg SVG element.
- * @param {?SVGMatrix} matrix Inverted screen CTM to use.
- * @return {!SVGPoint} Object with .x and .y properties.
+ * @param e Mouse event.
+ * @param svg SVG element.
+ * @param matrix Inverted screen CTM to use.
+ * @return Object with .x and .y properties.
  * @alias Blockly.browserEvents.mouseToSvg
  */
-const mouseToSvg = function(e, svg, matrix) {
+export function mouseToSvg(
+    e: MouseEvent, svg: SVGSVGElement, matrix: SVGMatrix|null): SVGPoint {
   const svgPoint = svg.createSVGPoint();
   svgPoint.x = e.clientX;
   svgPoint.y = e.clientY;
 
   if (!matrix) {
-    matrix = svg.getScreenCTM().inverse();
+    matrix = svg.getScreenCTM()!.inverse();
   }
   return svgPoint.matrixTransform(matrix);
-};
-exports.mouseToSvg = mouseToSvg;
+}
 
 /**
  * Returns the scroll delta of a mouse event in pixel units.
- * @param {!Event} e Mouse event.
- * @return {{x: number, y: number}} Scroll delta object with .x and .y
- *    properties.
+ * @param e Mouse event.
+ * @return Scroll delta object with .x and .y properties.
  * @alias Blockly.browserEvents.getScrollDeltaPixels
  */
-const getScrollDeltaPixels = function(e) {
+export function getScrollDeltaPixels(e: WheelEvent): {x: number, y: number} {
   switch (e.deltaMode) {
     case 0x00:  // Pixel mode.
     default:
@@ -280,5 +286,4 @@ const getScrollDeltaPixels = function(e) {
         y: e.deltaY * PAGE_MODE_MULTIPLIER,
       };
   }
-};
-exports.getScrollDeltaPixels = getScrollDeltaPixels;
+}