blockly 8.0.5 → 9.0.0-beta.0

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

@@ -7,25 +7,23 @@
 /**
  * @fileoverview Object that controls settings for the workspace.
  */
-'use strict';
 
 /**
  * Object that controls settings for the workspace.
  * @class
  */
-goog.module('Blockly.Options');
+import * as goog from '../closure/goog/goog.js';
+goog.declareModuleId('Blockly.Options');
 
-const idGenerator = goog.require('Blockly.utils.idGenerator');
-const registry = goog.require('Blockly.registry');
-const toolbox = goog.require('Blockly.utils.toolbox');
-/* eslint-disable-next-line no-unused-vars */
-const {BlocklyOptions} = goog.requireType('Blockly.BlocklyOptions');
-const {Classic} = goog.require('Blockly.Themes.Classic');
-/* eslint-disable-next-line no-unused-vars */
-const {Metrics} = goog.requireType('Blockly.utils.Metrics');
-const {Theme} = goog.require('Blockly.Theme');
-/* eslint-disable-next-line no-unused-vars */
-const {WorkspaceSvg} = goog.requireType('Blockly.WorkspaceSvg');
+import type {BlocklyOptions} from './blockly_options.js';
+import * as deprecation from './utils/deprecation.js';
+import * as registry from './registry.js';
+import {Theme} from './theme.js';
+import {Classic} from './theme/classic.js';
+import * as idGenerator from './utils/idgenerator.js';
+import type {Metrics} from './utils/metrics.js';
+import * as toolbox from './utils/toolbox.js';
+import type {WorkspaceSvg} from './workspace_svg.js';
 
 
 /**
@@ -33,13 +31,61 @@ const {WorkspaceSvg} = goog.requireType('Blockly.WorkspaceSvg');
  * is unspecified.
  * @alias Blockly.Options
  */
-class Options {
+export class Options {
+  RTL: boolean;
+  oneBasedIndex: boolean;
+  collapse: boolean;
+  comments: boolean;
+  disable: boolean;
+  readOnly: boolean;
+  maxBlocks: number;
+  maxInstances: {[key: string]: number}|null;
+  pathToMedia: string;
+  hasCategories: boolean;
+  moveOptions: MoveOptions;
+  hasScrollbars: boolean;
+  hasTrashcan: boolean;
+  maxTrashcanContents: number;
+  hasSounds: boolean;
+  hasCss: boolean;
+  horizontalLayout: boolean;
+  languageTree: toolbox.ToolboxInfo|null;
+  gridOptions: GridOptions;
+  zoomOptions: ZoomOptions;
+  toolboxPosition: toolbox.Position;
+  theme: Theme;
+  renderer: string;
+  rendererOverrides: {[rendererConstant: string]: any}|null;
+
+  /**
+   * The SVG element for the grid pattern.
+   * Created during injection.
+   */
+  gridPattern: SVGElement|null = null;
+  parentWorkspace: WorkspaceSvg|null;
+  plugins: {[key: string]: (new(...p1: any[]) => any)|string};
+
   /**
-   * @param {!BlocklyOptions} options Dictionary of options.
+   * If set, sets the translation of the workspace to match the scrollbars.
+   * A function that
+   *     sets the translation of the workspace to match the scrollbars. The
+   *     argument Contains an x and/or y property which is a float between 0
+   *     and 1 specifying the degree of scrolling.
+   */
+  setMetrics?: ((p1: {x: number, y: number}) => void) = undefined;
+
+  /**
+   * A function that returns a metrics
+   *     object that describes the current workspace.
+   */
+  getMetrics?: (() => Metrics) = undefined;
+
+  /**
+   * @param options Dictionary of options.
    *     Specification:
    * https://developers.google.com/blockly/guides/get-started/web#configuration
    */
-  constructor(options) {
+  constructor(options: BlocklyOptions) {
     let toolboxJsonDef = null;
     let hasCategories = false;
     let hasTrashcan = false;
@@ -49,28 +95,22 @@ class Options {
     let hasSounds = false;
     const readOnly = !!options['readOnly'];
     if (!readOnly) {
-      toolboxJsonDef = toolbox.convertToolboxDefToJson(options['toolbox']);
+      toolboxJsonDef =
+          toolbox.convertToolboxDefToJson(options['toolbox'] ?? null);
       hasCategories = toolbox.hasCategories(toolboxJsonDef);
-      hasTrashcan = options['trashcan'];
-      if (hasTrashcan === undefined) {
-        hasTrashcan = hasCategories;
-      }
-      hasCollapse = options['collapse'];
-      if (hasCollapse === undefined) {
-        hasCollapse = hasCategories;
-      }
-      hasComments = options['comments'];
-      if (hasComments === undefined) {
-        hasComments = hasCategories;
-      }
-      hasDisable = options['disable'];
-      if (hasDisable === undefined) {
-        hasDisable = hasCategories;
-      }
-      hasSounds = options['sounds'];
-      if (hasSounds === undefined) {
-        hasSounds = true;
-      }
+      const rawHasTrashcan = options['trashcan'];
+      hasTrashcan =
+          rawHasTrashcan === undefined ? hasCategories : rawHasTrashcan;
+      const rawHasCollapse = options['collapse'];
+      hasCollapse =
+          rawHasCollapse === undefined ? hasCategories : rawHasCollapse;
+      const rawHasComments = options['comments'];
+      hasComments =
+          rawHasComments === undefined ? hasCategories : rawHasComments;
+      const rawHasDisable = options['disable'];
+      hasDisable = rawHasDisable === undefined ? hasCategories : rawHasDisable;
+      const rawHasSounds = options['sounds'];
+      hasSounds = rawHasSounds === undefined ? true : rawHasSounds;
     }
 
     let maxTrashcanContents = options['maxTrashcanContents'];
@@ -86,17 +126,15 @@ class Options {
     if (horizontalLayout === undefined) {
       horizontalLayout = false;
     }
-    let toolboxAtStart = options['toolboxPosition'];
-    toolboxAtStart = toolboxAtStart !== 'end';
+    const toolboxAtStart = options['toolboxPosition'] !== 'end';
 
-    /** @type {!toolbox.Position} */
-    let toolboxPosition;
+    let toolboxPosition: toolbox.Position;
     if (horizontalLayout) {
       toolboxPosition =
           toolboxAtStart ? toolbox.Position.TOP : toolbox.Position.BOTTOM;
     } else {
-      toolboxPosition = (toolboxAtStart === rtl) ? toolbox.Position.RIGHT :
-                                                   toolbox.Position.LEFT;
+      toolboxPosition = toolboxAtStart === rtl ? toolbox.Position.RIGHT :
+                                                 toolbox.Position.LEFT;
     }
 
     let hasCss = options['css'];
@@ -105,125 +143,76 @@ class Options {
     }
     let pathToMedia = 'https://blockly-demo.appspot.com/static/media/';
     if (options['media']) {
-      pathToMedia = options['media'];
-    } else if (options['path']) {
+      pathToMedia = options['media'].endsWith('/') ? options['media'] :
+                                                     options['media'] + '/';
+    } else if ('path' in options) {
       // 'path' is a deprecated option which has been replaced by 'media'.
-      pathToMedia = options['path'] + 'media/';
+      deprecation.warn('path', 'Nov 2014', 'Jul 2023', 'media');
+      pathToMedia = (options as any)['path'] + 'media/';
     }
     let oneBasedIndex;
-    if (options['oneBasedIndex'] === undefined) {
-      oneBasedIndex = true;
-    } else {
-      oneBasedIndex = !!options['oneBasedIndex'];
-    }
+    const rawOneBasedIndex = options['oneBasedIndex'];
+    oneBasedIndex = rawOneBasedIndex === undefined ? true : rawOneBasedIndex;
     const renderer = options['renderer'] || 'geras';
 
     const plugins = options['plugins'] || {};
 
-    /** @type {boolean} */
     this.RTL = rtl;
-    /** @type {boolean} */
     this.oneBasedIndex = oneBasedIndex;
-    /** @type {boolean} */
     this.collapse = hasCollapse;
-    /** @type {boolean} */
     this.comments = hasComments;
-    /** @type {boolean} */
     this.disable = hasDisable;
-    /** @type {boolean} */
     this.readOnly = readOnly;
-    /** @type {number} */
     this.maxBlocks = options['maxBlocks'] || Infinity;
-    /** @type {?Object<string, number>} */
-    this.maxInstances = options['maxInstances'];
-    /** @type {string} */
+    this.maxInstances = options['maxInstances'] ?? null;
     this.pathToMedia = pathToMedia;
-    /** @type {boolean} */
     this.hasCategories = hasCategories;
-    /** @type {!Options.MoveOptions} */
     this.moveOptions = Options.parseMoveOptions_(options, hasCategories);
     /** @deprecated  January 2019 */
     this.hasScrollbars = !!this.moveOptions.scrollbars;
-    /** @type {boolean} */
     this.hasTrashcan = hasTrashcan;
-    /** @type {number} */
     this.maxTrashcanContents = maxTrashcanContents;
-    /** @type {boolean} */
     this.hasSounds = hasSounds;
-    /** @type {boolean} */
     this.hasCss = hasCss;
-    /** @type {boolean} */
     this.horizontalLayout = horizontalLayout;
-    /** @type {?toolbox.ToolboxInfo} */
     this.languageTree = toolboxJsonDef;
-    /** @type {!Options.GridOptions} */
     this.gridOptions = Options.parseGridOptions_(options);
-    /** @type {!Options.ZoomOptions} */
     this.zoomOptions = Options.parseZoomOptions_(options);
-    /** @type {!toolbox.Position} */
     this.toolboxPosition = toolboxPosition;
-    /** @type {!Theme} */
     this.theme = Options.parseThemeOptions_(options);
-    /** @type {string} */
     this.renderer = renderer;
-    /** @type {?Object} */
-    this.rendererOverrides = options['rendererOverrides'];
-
-    /**
-     * The SVG element for the grid pattern.
-     * Created during injection.
-     * @type {?SVGElement}
-     */
-    this.gridPattern = null;
+    this.rendererOverrides = options['rendererOverrides'] ?? null;
 
     /**
      * The parent of the current workspace, or null if there is no parent
      * workspace.  We can assert that this is of type WorkspaceSvg as opposed to
      * Workspace as this is only used in a rendered workspace.
-     * @type {?WorkspaceSvg}
      */
-    this.parentWorkspace = options['parentWorkspace'];
+    this.parentWorkspace = options['parentWorkspace'] ?? null;
 
-    /**
-     * Map of plugin type to name of registered plugin or plugin class.
-     * @type {!Object<string, (function(new:?, ...?)|string)>}
-     */
+    /** Map of plugin type to name of registered plugin or plugin class. */
     this.plugins = plugins;
-
-    /**
-     * If set, sets the translation of the workspace to match the scrollbars.
-     * @type {undefined|function(!{x:number,y:number}):void} A function that
-     *     sets the translation of the workspace to match the scrollbars. The
-     *     argument Contains an x and/or y property which is a float between 0
-     *     and 1 specifying the degree of scrolling.
-     */
-    this.setMetrics = undefined;
-
-    /**
-     * @type {undefined|function():!Metrics} A function that returns a metrics
-     *     object that describes the current workspace.
-     */
-    this.getMetrics = undefined;
   }
 
   /**
    * Parse the user-specified move options, using reasonable defaults where
    *    behaviour is unspecified.
-   * @param {!Object} options Dictionary of options.
-   * @param {boolean} hasCategories Whether the workspace has categories or not.
-   * @return {!Options.MoveOptions} Normalized move options.
-   * @private
+   * @param options Dictionary of options.
+   * @param hasCategories Whether the workspace has categories or not.
+   * @return Normalized move options.
    */
-  static parseMoveOptions_(options, hasCategories) {
+  private static parseMoveOptions_(
+      options: BlocklyOptions, hasCategories: boolean): MoveOptions {
     const move = options['move'] || {};
-    const moveOptions = {};
+    const moveOptions = {} as MoveOptions;
     if (move['scrollbars'] === undefined &&
         options['scrollbars'] === undefined) {
       moveOptions.scrollbars = hasCategories;
     } else if (typeof move['scrollbars'] === 'object') {
-      moveOptions.scrollbars = {};
-      moveOptions.scrollbars.horizontal = !!move['scrollbars']['horizontal'];
-      moveOptions.scrollbars.vertical = !!move['scrollbars']['vertical'];
+      moveOptions.scrollbars = {
+        'horizontal': !!move['scrollbars']['horizontal'],
+        'vertical': !!move['scrollbars']['vertical'],
+      };
       // Convert scrollbars object to boolean if they have the same value.
       // This allows us to easily check for whether any scrollbars exist using
       // !!moveOptions.scrollbars.
@@ -260,13 +249,12 @@ class Options {
    * Parse the user-specified zoom options, using reasonable defaults where
    * behaviour is unspecified.  See zoom documentation:
    *   https://developers.google.com/blockly/guides/configure/web/zoom
-   * @param {!Object} options Dictionary of options.
-   * @return {!Options.ZoomOptions} Normalized zoom options.
-   * @private
+   * @param options Dictionary of options.
+   * @return Normalized zoom options.
    */
-  static parseZoomOptions_(options) {
+  private static parseZoomOptions_(options: BlocklyOptions): ZoomOptions {
     const zoom = options['zoom'] || {};
-    const zoomOptions = {};
+    const zoomOptions = {} as ZoomOptions;
     if (zoom['controls'] === undefined) {
       zoomOptions.controls = false;
     } else {
@@ -309,17 +297,16 @@ class Options {
    * Parse the user-specified grid options, using reasonable defaults where
    * behaviour is unspecified. See grid documentation:
    *   https://developers.google.com/blockly/guides/configure/web/grid
-   * @param {!Object} options Dictionary of options.
-   * @return {!Options.GridOptions} Normalized grid options.
-   * @private
+   * @param options Dictionary of options.
+   * @return Normalized grid options.
    */
-  static parseGridOptions_(options) {
+  private static parseGridOptions_(options: BlocklyOptions): GridOptions {
     const grid = options['grid'] || {};
-    const gridOptions = {};
+    const gridOptions = {} as GridOptions;
     gridOptions.spacing = Number(grid['spacing']) || 0;
     gridOptions.colour = grid['colour'] || '#888';
     gridOptions.length =
-        (grid['length'] === undefined) ? 1 : Number(grid['length']);
+        grid['length'] === undefined ? 1 : Number(grid['length']);
     gridOptions.snap = gridOptions.spacing > 0 && !!grid['snap'];
     return gridOptions;
   }
@@ -327,65 +314,52 @@ class Options {
   /**
    * Parse the user-specified theme options, using the classic theme as a
    * default. https://developers.google.com/blockly/guides/configure/web/themes
-   * @param {!Object} options Dictionary of options.
-   * @return {!Theme} A Blockly Theme.
-   * @private
+   * @param options Dictionary of options.
+   * @return A Blockly Theme.
    */
-  static parseThemeOptions_(options) {
+  private static parseThemeOptions_(options: BlocklyOptions): Theme {
     const theme = options['theme'] || Classic;
     if (typeof theme === 'string') {
-      return /** @type {!Theme} */ (
-          registry.getObject(registry.Type.THEME, theme));
+      return registry.getObject(registry.Type.THEME, theme) as Theme;
     } else if (theme instanceof Theme) {
-      return /** @type {!Theme} */ (theme);
+      return theme;
     }
     return Theme.defineTheme(
-        theme.name || ('builtin' + idGenerator.getNextUniqueId()), theme);
+        theme.name || 'builtin' + idGenerator.getNextUniqueId(), theme);
   }
 }
 
-/**
- * Grid Options.
- * @typedef {{
- *     colour: string,
- *     length: number,
- *     snap: boolean,
- *     spacing: number
- * }}
- */
-Options.GridOptions;
+export namespace Options {
+  export interface GridOptions {
+    colour: string;
+    length: number;
+    snap: boolean;
+    spacing: number;
+  }
 
-/**
- * Move Options.
- * @typedef {{
- *     drag: boolean,
- *     scrollbars: (boolean | !Options.ScrollbarOptions),
- *     wheel: boolean
- * }}
- */
-Options.MoveOptions;
+  export interface MoveOptions {
+    drag: boolean;
+    scrollbars: boolean|ScrollbarOptions;
+    wheel: boolean;
+  }
 
-/**
- * Scrollbar Options.
- * @typedef {{
- *     horizontal: boolean,
- *     vertical: boolean
- * }}
- */
-Options.ScrollbarOptions;
+  export interface ScrollbarOptions {
+    horizontal: boolean;
+    vertical: boolean;
+  }
 
-/**
- * Zoom Options.
- * @typedef {{
- *     controls: boolean,
- *     maxScale: number,
- *     minScale: number,
- *     pinch: boolean,
- *     scaleSpeed: number,
- *     startScale: number,
- *     wheel: boolean
- * }}
- */
-Options.ZoomOptions;
+  export interface ZoomOptions {
+    controls: boolean;
+    maxScale: number;
+    minScale: number;
+    pinch: boolean;
+    scaleSpeed: number;
+    startScale: number;
+    wheel: boolean;
+  }
+}
 
-exports.Options = Options;
+export type GridOptions = Options.GridOptions;
+export type MoveOptions = Options.MoveOptions;
+export type ScrollbarOptions = Options.ScrollbarOptions;
+export type ZoomOptions = Options.ZoomOptions;

package/core/positionable_helpers.d.ts

@@ -0,0 +1,88 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { UiMetrics } from './metrics_manager.js';
+import { Rect } from './utils/rect.js';
+import type { Size } from './utils/size.js';
+import type { WorkspaceSvg } from './workspace_svg.js';
+/**
+ * Enum for vertical positioning.
+ * @alias Blockly.uiPosition.verticalPosition
+ * @internal
+ */
+export declare enum verticalPosition {
+    TOP = 0,
+    BOTTOM = 1
+}
+/**
+ * Enum for horizontal positioning.
+ * @alias Blockly.uiPosition.horizontalPosition
+ * @internal
+ */
+export declare enum horizontalPosition {
+    LEFT = 0,
+    RIGHT = 1
+}
+/**
+ * An object defining a horizontal and vertical positioning.
+ * @alias Blockly.uiPosition.Position
+ * @internal
+ */
+export interface Position {
+    horizontal: horizontalPosition;
+    vertical: verticalPosition;
+}
+/**
+ * Enum for bump rules to use for dealing with collisions.
+ * @alias Blockly.uiPosition.bumpDirection
+ * @internal
+ */
+export declare enum bumpDirection {
+    UP = 0,
+    DOWN = 1
+}
+/**
+ * Returns a rectangle representing reasonable position for where to place a UI
+ * element of the specified size given the restraints and locations of the
+ * scrollbars. This method does not take into account any already placed UI
+ * elements.
+ * @param position The starting horizontal and vertical position.
+ * @param size the size of the UI element to get a start position for.
+ * @param horizontalPadding The horizontal padding to use.
+ * @param verticalPadding The vertical padding to use.
+ * @param metrics The workspace UI metrics.
+ * @param workspace The workspace.
+ * @return The suggested start position.
+ * @alias Blockly.uiPosition.getStartPositionRect
+ * @internal
+ */
+export declare function getStartPositionRect(position: Position, size: Size, horizontalPadding: number, verticalPadding: number, metrics: UiMetrics, workspace: WorkspaceSvg): Rect;
+/**
+ * Returns a corner position that is on the opposite side of the workspace from
+ * the toolbox.
+ * If in horizontal orientation, defaults to the bottom corner. If in vertical
+ * orientation, defaults to the right corner.
+ * @param workspace The workspace.
+ * @param metrics The workspace metrics.
+ * @return The suggested corner position.
+ * @alias Blockly.uiPosition.getCornerOppositeToolbox
+ * @internal
+ */
+export declare function getCornerOppositeToolbox(workspace: WorkspaceSvg, metrics: UiMetrics): Position;
+/**
+ * Returns a position Rect based on a starting position that is bumped
+ * so that it doesn't intersect with any of the provided savedPositions. This
+ * method does not check that the bumped position is still within bounds.
+ * @param startRect The starting position to use.
+ * @param margin The margin to use between elements when bumping.
+ * @param bumpDir The direction to bump if there is a collision with an existing
+ *     UI element.
+ * @param savedPositions List of rectangles that represent the positions of UI
+ *     elements already placed.
+ * @return The suggested position rectangle.
+ * @alias Blockly.uiPosition.bumpPositionRect
+ * @internal
+ */
+export declare function bumpPositionRect(startRect: Rect, margin: number, bumpDir: bumpDirection, savedPositions: Rect[]): Rect;