blockly 8.0.5 → 9.0.0-beta.0

package/core/contextmenu_registry.ts

@@ -0,0 +1,179 @@
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * @fileoverview Registry for context menu option items.
+ */
+
+/**
+ * Registry for context menu option items.
+ * @class
+ */
+import * as goog from '../closure/goog/goog.js';
+goog.declareModuleId('Blockly.ContextMenuRegistry');
+
+import type {BlockSvg} from './block_svg.js';
+import type {WorkspaceSvg} from './workspace_svg.js';
+
+
+/**
+ * Class for the registry of context menu items. This is intended to be a
+ * singleton. You should not create a new instance, and only access this class
+ * from ContextMenuRegistry.registry.
+ * @alias Blockly.ContextMenuRegistry
+ */
+export class ContextMenuRegistry {
+  static registry: ContextMenuRegistry;
+  /** Registry of all registered RegistryItems, keyed by ID. */
+  private registry_ = new Map<string, RegistryItem>();
+
+  /** Resets the existing singleton instance of ContextMenuRegistry. */
+  constructor() {
+    this.reset();
+  }
+
+  /** Clear and recreate the registry. */
+  reset() {
+    this.registry_.clear();
+  }
+
+  /**
+   * Registers a RegistryItem.
+   * @param item Context menu item to register.
+   * @throws {Error} if an item with the given ID already exists.
+   */
+  register(item: RegistryItem) {
+    if (this.registry_.has(item.id)) {
+      throw Error('Menu item with ID "' + item.id + '" is already registered.');
+    }
+    this.registry_.set(item.id, item);
+  }
+
+  /**
+   * Unregisters a RegistryItem with the given ID.
+   * @param id The ID of the RegistryItem to remove.
+   * @throws {Error} if an item with the given ID does not exist.
+   */
+  unregister(id: string) {
+    if (!this.registry_.has(id)) {
+      throw new Error('Menu item with ID "' + id + '" not found.');
+    }
+    this.registry_.delete(id);
+  }
+
+  /**
+   * @param id The ID of the RegistryItem to get.
+   * @return RegistryItem or null if not found
+   */
+  getItem(id: string): RegistryItem|null {
+    return this.registry_.get(id) ?? null;
+  }
+
+  /**
+   * Gets the valid context menu options for the given scope type (e.g. block or
+   * workspace) and scope. Blocks are only shown if the preconditionFn shows
+   * they should not be hidden.
+   * @param scopeType Type of scope where menu should be shown (e.g. on a block
+   *     or on a workspace)
+   * @param scope Current scope of context menu (i.e., the exact workspace or
+   *     block being clicked on)
+   * @return the list of ContextMenuOptions
+   */
+  getContextMenuOptions(scopeType: ScopeType, scope: Scope):
+      ContextMenuOption[] {
+    const menuOptions: AnyDuringMigration[] = [];
+    for (const item of this.registry_.values()) {
+      if (scopeType === item.scopeType) {
+        const precondition = item.preconditionFn(scope);
+        if (precondition !== 'hidden') {
+          const displayText = typeof item.displayText === 'function' ?
+              item.displayText(scope) :
+              item.displayText;
+          const menuOption: ContextMenuOption = {
+            text: displayText,
+            enabled: precondition === 'enabled',
+            callback: item.callback,
+            scope,
+            weight: item.weight,
+          };
+          menuOptions.push(menuOption);
+        }
+      }
+    }
+    menuOptions.sort(function(a, b) {
+      return a.weight - b.weight;
+    });
+    return menuOptions;
+  }
+}
+
+export namespace ContextMenuRegistry {
+  /**
+   * Where this menu item should be rendered. If the menu item should be
+   * rendered in multiple scopes, e.g. on both a block and a workspace, it
+   * should be registered for each scope.
+   */
+  export enum ScopeType {
+    BLOCK = 'block',
+    WORKSPACE = 'workspace',
+  }
+
+  /**
+   * The actual workspace/block where the menu is being rendered. This is passed
+   * to callback and displayText functions that depend on this information.
+   */
+  export interface Scope {
+    block: BlockSvg|undefined;
+    workspace: WorkspaceSvg|undefined;
+  }
+
+  /**
+   * A menu item as entered in the registry.
+   */
+  export interface RegistryItem {
+    callback: (p1: Scope) => AnyDuringMigration;
+    scopeType: ScopeType;
+    displayText: ((p1: Scope) => string)|string;
+    preconditionFn: (p1: Scope) => string;
+    weight: number;
+    id: string;
+  }
+
+  /**
+   * A menu item as presented to contextmenu.js.
+   */
+  export interface ContextMenuOption {
+    text: string;
+    enabled: boolean;
+    callback: (p1: Scope) => AnyDuringMigration;
+    scope: Scope;
+    weight: number;
+  }
+
+  /**
+   * A subset of ContextMenuOption corresponding to what was publicly
+   * documented.  ContextMenuOption should be preferred for new code.
+   */
+  export interface LegacyContextMenuOption {
+    text: string;
+    enabled: boolean;
+    callback: (p1: Scope) => AnyDuringMigration;
+  }
+
+  /**
+   * Singleton instance of this class. All interactions with this class should
+   * be done on this object.
+   */
+  ContextMenuRegistry.registry = new ContextMenuRegistry();
+}
+
+export type ScopeType = ContextMenuRegistry.ScopeType;
+export const ScopeType = ContextMenuRegistry.ScopeType;
+export type Scope = ContextMenuRegistry.Scope;
+export type RegistryItem = ContextMenuRegistry.RegistryItem;
+export type ContextMenuOption = ContextMenuRegistry.ContextMenuOption;
+export type LegacyContextMenuOption =
+    ContextMenuRegistry.LegacyContextMenuOption;

package/core/css.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @license
+ * Copyright 2013 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Add some CSS to the blob that will be injected later.  Allows optional
+ * components such as fields and the toolbox to store separate CSS.
+ * @param cssContent Multiline CSS string or an array of single lines of CSS.
+ * @alias Blockly.Css.register
+ */
+export declare function register(cssContent: string | string[]): void;
+/**
+ * Inject the CSS into the DOM.  This is preferable over using a regular CSS
+ * file since:
+ * a) It loads synchronously and doesn't force a redraw later.
+ * b) It speeds up loading by not blocking on a separate HTTP transfer.
+ * c) The CSS content may be made dynamic depending on init options.
+ * @param hasCss If false, don't inject CSS (providing CSS becomes the
+ *     document's responsibility).
+ * @param pathToMedia Path from page to the Blockly media directory.
+ * @alias Blockly.Css.inject
+ */
+export declare function inject(hasCss: boolean, pathToMedia: string): void;

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

@@ -7,32 +7,27 @@
 /**
  * @fileoverview Inject Blockly's CSS synchronously.
  */
-'use strict';
 
 /**
  * Inject Blockly's CSS synchronously.
  * @namespace Blockly.Css
  */
-goog.module('Blockly.Css');
+import * as goog from '../closure/goog/goog.js';
+goog.declareModuleId('Blockly.Css');
 
-const deprecation = goog.require('Blockly.utils.deprecation');
+import * as deprecation from './utils/deprecation.js';
 
 
-/**
- * Has CSS already been injected?
- * @type {boolean}
- * @private
- */
+/** Has CSS already been injected? */
 let injected = false;
 
 /**
  * Add some CSS to the blob that will be injected later.  Allows optional
  * components such as fields and the toolbox to store separate CSS.
- * @param {string|!Array<string>} cssContent Multiline CSS string or an array of
- *    single lines of CSS.
+ * @param cssContent Multiline CSS string or an array of single lines of CSS.
  * @alias Blockly.Css.register
  */
-const register = function(cssContent) {
+export function register(cssContent: string|string[]) {
   if (injected) {
     throw Error('CSS already injected');
   }
@@ -41,13 +36,12 @@ const register = function(cssContent) {
     deprecation.warn(
         'Registering CSS by passing an array of strings', 'September 2021',
         'September 2022', 'css.register passing a multiline string');
-    content += ('\n' + cssContent.join('\n'));
+    content += '\n' + cssContent.join('\n');
   } else {
     // Add new cssContent in the global content.
-    content += ('\n' + cssContent);
+    content += '\n' + cssContent;
   }
-};
-exports.register = register;
+}
 
 /**
  * Inject the CSS into the DOM.  This is preferable over using a regular CSS
@@ -55,12 +49,12 @@ exports.register = register;
  * a) It loads synchronously and doesn't force a redraw later.
  * b) It speeds up loading by not blocking on a separate HTTP transfer.
  * c) The CSS content may be made dynamic depending on init options.
- * @param {boolean} hasCss If false, don't inject CSS
- *     (providing CSS becomes the document's responsibility).
- * @param {string} pathToMedia Path from page to the Blockly media directory.
+ * @param hasCss If false, don't inject CSS (providing CSS becomes the
+ *     document's responsibility).
+ * @param pathToMedia Path from page to the Blockly media directory.
  * @alias Blockly.Css.inject
  */
-const inject = function(hasCss, pathToMedia) {
+export function inject(hasCss: boolean, pathToMedia: string) {
   // Only inject the CSS once.
   if (injected) {
     return;
@@ -81,14 +75,13 @@ const inject = function(hasCss, pathToMedia) {
   const cssTextNode = document.createTextNode(cssContent);
   cssNode.appendChild(cssTextNode);
   document.head.insertBefore(cssNode, document.head.firstChild);
-};
-exports.inject = inject;
+}
 
 /**
  * The CSS content for Blockly.
  * @alias Blockly.Css.content
  */
-let content = (`
+let content = `
 .blocklySvg {
   background-color: #fff;
   outline: none;
@@ -564,5 +557,4 @@ let content = (`
   float: right;
   margin-right: -24px;
 }
-`);
-exports.content = content;
+`;

package/core/delete_area.d.ts

@@ -0,0 +1,47 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { DragTarget } from './drag_target.js';
+import type { IDeleteArea } from './interfaces/i_delete_area.js';
+import type { IDraggable } from './interfaces/i_draggable.js';
+/**
+ * Abstract class for a component that can delete a block or bubble that is
+ * dropped on top of it.
+ * @alias Blockly.DeleteArea
+ */
+export declare class DeleteArea extends DragTarget implements IDeleteArea {
+    /**
+     * Whether the last block or bubble dragged over this delete area would be
+     * deleted if dropped on this component.
+     * This property is not updated after the block or bubble is deleted.
+     */
+    protected wouldDelete_: boolean;
+    /**
+     * The unique id for this component that is used to register with the
+     * ComponentManager.
+     */
+    id: string;
+    /**
+     * Constructor for DeleteArea. Should not be called directly, only by a
+     * subclass.
+     */
+    constructor();
+    /**
+     * Returns whether the provided block or bubble would be deleted if dropped on
+     * this area.
+     * This method should check if the element is deletable and is always called
+     * before onDragEnter/onDragOver/onDragExit.
+     * @param element The block or bubble currently being dragged.
+     * @param couldConnect Whether the element could could connect to another.
+     * @return Whether the element provided would be deleted if dropped on this
+     *     area.
+     */
+    wouldDelete(element: IDraggable, couldConnect: boolean): boolean;
+    /**
+     * Updates the internal wouldDelete_ state.
+     * @param wouldDelete The new value for the wouldDelete state.
+     */
+    protected updateWouldDelete_(wouldDelete: boolean): void;
+}

package/core/delete_area.ts

@@ -0,0 +1,82 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * @fileoverview The abstract class for a component that can delete a block or
+ * bubble that is dropped on top of it.
+ */
+
+/**
+ * The abstract class for a component that can delete a block or
+ * bubble that is dropped on top of it.
+ * @class
+ */
+import * as goog from '../closure/goog/goog.js';
+goog.declareModuleId('Blockly.DeleteArea');
+
+import {BlockSvg} from './block_svg.js';
+import {DragTarget} from './drag_target.js';
+import type {IDeleteArea} from './interfaces/i_delete_area.js';
+import type {IDraggable} from './interfaces/i_draggable.js';
+
+
+/**
+ * Abstract class for a component that can delete a block or bubble that is
+ * dropped on top of it.
+ * @alias Blockly.DeleteArea
+ */
+export class DeleteArea extends DragTarget implements IDeleteArea {
+  /**
+   * Whether the last block or bubble dragged over this delete area would be
+   * deleted if dropped on this component.
+   * This property is not updated after the block or bubble is deleted.
+   */
+  protected wouldDelete_ = false;
+
+  /**
+   * The unique id for this component that is used to register with the
+   * ComponentManager.
+   */
+  // TODO(b/109816955): remove '!', see go/strict-prop-init-fix.
+  override id!: string;
+
+  /**
+   * Constructor for DeleteArea. Should not be called directly, only by a
+   * subclass.
+   */
+  constructor() {
+    super();
+  }
+
+  /**
+   * Returns whether the provided block or bubble would be deleted if dropped on
+   * this area.
+   * This method should check if the element is deletable and is always called
+   * before onDragEnter/onDragOver/onDragExit.
+   * @param element The block or bubble currently being dragged.
+   * @param couldConnect Whether the element could could connect to another.
+   * @return Whether the element provided would be deleted if dropped on this
+   *     area.
+   */
+  wouldDelete(element: IDraggable, couldConnect: boolean): boolean {
+    if (element instanceof BlockSvg) {
+      const block = (element);
+      const couldDeleteBlock = !block.getParent() && block.isDeletable();
+      this.updateWouldDelete_(couldDeleteBlock && !couldConnect);
+    } else {
+      this.updateWouldDelete_(element.isDeletable());
+    }
+    return this.wouldDelete_;
+  }
+
+  /**
+   * Updates the internal wouldDelete_ state.
+   * @param wouldDelete The new value for the wouldDelete state.
+   */
+  protected updateWouldDelete_(wouldDelete: boolean) {
+    this.wouldDelete_ = wouldDelete;
+  }
+}

package/core/dialog.d.ts

@@ -0,0 +1,61 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Wrapper to window.alert() that app developers may override via setAlert to
+ * provide alternatives to the modal browser window.
+ * @param message The message to display to the user.
+ * @param opt_callback The callback when the alert is dismissed.
+ * @alias Blockly.dialog.alert
+ */
+export declare function alert(message: string, opt_callback?: () => any): void;
+/**
+ * Sets the function to be run when Blockly.dialog.alert() is called.
+ * @param alertFunction The function to be run.
+ * @see Blockly.dialog.alert
+ * @alias Blockly.dialog.setAlert
+ */
+export declare function setAlert(alertFunction: (p1: string, p2?: () => any) => any): void;
+/**
+ * Wrapper to window.confirm() that app developers may override via setConfirm
+ * to provide alternatives to the modal browser window.
+ * @param message The message to display to the user.
+ * @param callback The callback for handling user response.
+ * @alias Blockly.dialog.confirm
+ */
+export declare function confirm(message: string, callback: (p1: boolean) => any): void;
+/**
+ * Private version of confirm for stubbing in tests.
+ */
+declare function confirmInternal(message: string, callback: (p1: boolean) => any): void;
+/**
+ * Sets the function to be run when Blockly.dialog.confirm() is called.
+ * @param confirmFunction The function to be run.
+ * @see Blockly.dialog.confirm
+ * @alias Blockly.dialog.setConfirm
+ */
+export declare function setConfirm(confirmFunction: (p1: string, p2: (p1: boolean) => any) => any): void;
+/**
+ * Wrapper to window.prompt() that app developers may override via setPrompt to
+ * provide alternatives to the modal browser window. Built-in browser prompts
+ * are often used for better text input experience on mobile device. We strongly
+ * recommend testing mobile when overriding this.
+ * @param message The message to display to the user.
+ * @param defaultValue The value to initialize the prompt with.
+ * @param callback The callback for handling user response.
+ * @alias Blockly.dialog.prompt
+ */
+export declare function prompt(message: string, defaultValue: string, callback: (p1: string | null) => any): void;
+/**
+ * Sets the function to be run when Blockly.dialog.prompt() is called.
+ * @param promptFunction The function to be run.
+ * @see Blockly.dialog.prompt
+ * @alias Blockly.dialog.setPrompt
+ */
+export declare function setPrompt(promptFunction: (p1: string, p2: string, p3: (p1: string | null) => any) => any): void;
+export declare const TEST_ONLY: {
+    confirmInternal: typeof confirmInternal;
+};
+export {};

package/core/dialog.ts

@@ -0,0 +1,127 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * @fileoverview Wrapper functions around JS functions for showing
+ * alert/confirmation dialogs.
+ */
+
+/**
+ * Wrapper functions around JS functions for showing alert/confirmation dialogs.
+ * @namespace Blockly.dialog
+ */
+import * as goog from '../closure/goog/goog.js';
+goog.declareModuleId('Blockly.dialog');
+
+
+let alertImplementation = function(
+    message: AnyDuringMigration, opt_callback: AnyDuringMigration) {
+  window.alert(message);
+  if (opt_callback) {
+    opt_callback();
+  }
+};
+
+let confirmImplementation = function(
+    message: AnyDuringMigration, callback: AnyDuringMigration) {
+  callback(window.confirm(message));
+};
+
+let promptImplementation = function(
+    message: AnyDuringMigration, defaultValue: AnyDuringMigration,
+    callback: AnyDuringMigration) {
+  callback(window.prompt(message, defaultValue));
+};
+
+/**
+ * Wrapper to window.alert() that app developers may override via setAlert to
+ * provide alternatives to the modal browser window.
+ * @param message The message to display to the user.
+ * @param opt_callback The callback when the alert is dismissed.
+ * @alias Blockly.dialog.alert
+ */
+export function alert(
+    message: string, opt_callback?: () => AnyDuringMigration) {
+  alertImplementation(message, opt_callback);
+}
+
+/**
+ * Sets the function to be run when Blockly.dialog.alert() is called.
+ * @param alertFunction The function to be run.
+ * @see Blockly.dialog.alert
+ * @alias Blockly.dialog.setAlert
+ */
+export function setAlert(
+    alertFunction: (p1: string, p2?: () => AnyDuringMigration) =>
+        AnyDuringMigration) {
+  alertImplementation = alertFunction;
+}
+
+/**
+ * Wrapper to window.confirm() that app developers may override via setConfirm
+ * to provide alternatives to the modal browser window.
+ * @param message The message to display to the user.
+ * @param callback The callback for handling user response.
+ * @alias Blockly.dialog.confirm
+ */
+export function confirm(
+    message: string, callback: (p1: boolean) => AnyDuringMigration) {
+  TEST_ONLY.confirmInternal(message, callback);
+}
+
+/**
+ * Private version of confirm for stubbing in tests.
+ */
+function confirmInternal(
+    message: string, callback: (p1: boolean) => AnyDuringMigration) {
+  confirmImplementation(message, callback);
+}
+
+
+/**
+ * Sets the function to be run when Blockly.dialog.confirm() is called.
+ * @param confirmFunction The function to be run.
+ * @see Blockly.dialog.confirm
+ * @alias Blockly.dialog.setConfirm
+ */
+export function setConfirm(
+    confirmFunction: (p1: string, p2: (p1: boolean) => AnyDuringMigration) =>
+        AnyDuringMigration) {
+  confirmImplementation = confirmFunction;
+}
+
+/**
+ * Wrapper to window.prompt() that app developers may override via setPrompt to
+ * provide alternatives to the modal browser window. Built-in browser prompts
+ * are often used for better text input experience on mobile device. We strongly
+ * recommend testing mobile when overriding this.
+ * @param message The message to display to the user.
+ * @param defaultValue The value to initialize the prompt with.
+ * @param callback The callback for handling user response.
+ * @alias Blockly.dialog.prompt
+ */
+export function prompt(
+    message: string, defaultValue: string,
+    callback: (p1: string|null) => AnyDuringMigration) {
+  promptImplementation(message, defaultValue, callback);
+}
+
+/**
+ * Sets the function to be run when Blockly.dialog.prompt() is called.
+ * @param promptFunction The function to be run.
+ * @see Blockly.dialog.prompt
+ * @alias Blockly.dialog.setPrompt
+ */
+export function setPrompt(
+    promptFunction:
+        (p1: string, p2: string, p3: (p1: string|null) => AnyDuringMigration) =>
+            AnyDuringMigration) {
+  promptImplementation = promptFunction;
+}
+
+export const TEST_ONLY = {
+  confirmInternal,
+}

package/core/drag_target.d.ts

@@ -0,0 +1,63 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { IDragTarget } from './interfaces/i_drag_target.js';
+import type { IDraggable } from './interfaces/i_draggable.js';
+import type { Rect } from './utils/rect.js';
+/**
+ * Abstract class for a component with custom behaviour when a block or bubble
+ * is dragged over or dropped on top of it.
+ * @alias Blockly.DragTarget
+ */
+export declare class DragTarget implements IDragTarget {
+    /**
+     * The unique id for this component that is used to register with the
+     * ComponentManager.
+     */
+    id: string;
+    /**
+     * Constructor for DragTarget. It exists to add the id property and should not
+     * be called directly, only by a subclass.
+     */
+    constructor();
+    /**
+     * Handles when a cursor with a block or bubble enters this drag target.
+     * @param _dragElement The block or bubble currently being dragged.
+     */
+    onDragEnter(_dragElement: IDraggable): void;
+    /**
+     * Handles when a cursor with a block or bubble is dragged over this drag
+     * target.
+     * @param _dragElement The block or bubble currently being dragged.
+     */
+    onDragOver(_dragElement: IDraggable): void;
+    /**
+     * Handles when a cursor with a block or bubble exits this drag target.
+     * @param _dragElement The block or bubble currently being dragged.
+     */
+    onDragExit(_dragElement: IDraggable): void;
+    /**
+     * Handles when a block or bubble is dropped on this component.
+     * Should not handle delete here.
+     * @param _dragElement The block or bubble currently being dragged.
+     */
+    onDrop(_dragElement: IDraggable): void;
+    /**
+     * Returns the bounding rectangle of the drag target area in pixel units
+     * relative to the Blockly injection div.
+     * @return The component's bounding box. Null if drag target area should be
+     *     ignored.
+     */
+    getClientRect(): Rect | null;
+    /**
+     * Returns whether the provided block or bubble should not be moved after
+     * being dropped on this component. If true, the element will return to where
+     * it was when the drag started.
+     * @param _dragElement The block or bubble currently being dragged.
+     * @return Whether the block or bubble provided should be returned to drag
+     *     start.
+     */
+    shouldPreventMove(_dragElement: IDraggable): boolean;
+}