blockly 8.0.5 → 9.0.0-beta.0

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

@@ -7,92 +7,85 @@
 /**
  * @fileoverview Utility functions for positioning UI elements.
  */
-'use strict';
 
 /**
  * Utility functions for positioning UI elements.
  * @namespace Blockly.uiPosition
  */
-goog.module('Blockly.uiPosition');
+import * as goog from '../closure/goog/goog.js';
+goog.declareModuleId('Blockly.uiPosition');
 
-const toolbox = goog.require('Blockly.utils.toolbox');
 /* eslint-disable-next-line no-unused-vars */
-const {MetricsManager} = goog.requireType('Blockly.MetricsManager');
-const {Rect} = goog.require('Blockly.utils.Rect');
-const {Scrollbar} = goog.require('Blockly.Scrollbar');
-/* eslint-disable-next-line no-unused-vars */
-const {Size} = goog.requireType('Blockly.utils.Size');
-/* eslint-disable-next-line no-unused-vars */
-const {WorkspaceSvg} = goog.requireType('Blockly.WorkspaceSvg');
+// Unused import preserved for side-effects. Remove if unneeded.
+// import './metrics_manager.js';
+
+import type {UiMetrics} from './metrics_manager.js';
+import {Scrollbar} from './scrollbar.js';
+import {Rect} from './utils/rect.js';
+import type {Size} from './utils/size.js';
+import * as toolbox from './utils/toolbox.js';
+import type {WorkspaceSvg} from './workspace_svg.js';
 
 
 /**
  * Enum for vertical positioning.
- * @enum {number}
  * @alias Blockly.uiPosition.verticalPosition
- * @package
+ * @internal
  */
-const verticalPosition = {
-  TOP: 0,
-  BOTTOM: 1,
-};
-exports.verticalPosition = verticalPosition;
+export enum verticalPosition {
+  TOP,
+  BOTTOM
+}
 
 /**
  * Enum for horizontal positioning.
- * @enum {number}
  * @alias Blockly.uiPosition.horizontalPosition
- * @package
+ * @internal
  */
-const horizontalPosition = {
-  LEFT: 0,
-  RIGHT: 1,
-};
-exports.horizontalPosition = horizontalPosition;
+export enum horizontalPosition {
+  LEFT,
+  RIGHT
+}
 
 /**
  * An object defining a horizontal and vertical positioning.
- * @typedef {{
- *   horizontal: !horizontalPosition,
- *   vertical: !verticalPosition
- * }}
  * @alias Blockly.uiPosition.Position
- * @package
+ * @internal
  */
-let Position;
-exports.Position = Position;
+export interface Position {
+  horizontal: horizontalPosition;
+  vertical: verticalPosition;
+}
 
 /**
  * Enum for bump rules to use for dealing with collisions.
- * @enum {number}
  * @alias Blockly.uiPosition.bumpDirection
- * @package
+ * @internal
  */
-const bumpDirection = {
-  UP: 0,
-  DOWN: 1,
-};
-exports.bumpDirection = bumpDirection;
+export enum bumpDirection {
+  UP,
+  DOWN
+}
 
 /**
  * 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} position The starting
- *    horizontal and vertical position.
- * @param {!Size} size the size of the UI element to get a start
- *    position for.
- * @param {number} horizontalPadding The horizontal padding to use.
- * @param {number} verticalPadding The vertical padding to use.
- * @param {!MetricsManager.UiMetrics} metrics The workspace UI metrics.
- * @param {!WorkspaceSvg} workspace The workspace.
- * @return {!Rect} The suggested start position.
+ * @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
- * @package
+ * @internal
  */
-const getStartPositionRect = function(
-    position, size, horizontalPadding, verticalPadding, metrics, workspace) {
+export function getStartPositionRect(
+    position: Position, size: Size, horizontalPadding: number,
+    verticalPadding: number, metrics: UiMetrics,
+    workspace: WorkspaceSvg): Rect {
   // Horizontal positioning.
   let left = 0;
   const hasVerticalScrollbar =
@@ -122,21 +115,21 @@ const getStartPositionRect = function(
     }
   }
   return new Rect(top, top + size.height, left, left + size.width);
-};
-exports.getStartPositionRect = getStartPositionRect;
+}
 
 /**
  * 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 {!WorkspaceSvg} workspace The workspace.
- * @param {!MetricsManager.UiMetrics} metrics The workspace metrics.
- * @return {!Position} The suggested corner position.
+ * @param workspace The workspace.
+ * @param metrics The workspace metrics.
+ * @return The suggested corner position.
  * @alias Blockly.uiPosition.getCornerOppositeToolbox
- * @package
+ * @internal
  */
-const getCornerOppositeToolbox = function(workspace, metrics) {
+export function getCornerOppositeToolbox(
+    workspace: WorkspaceSvg, metrics: UiMetrics): Position {
   const leftCorner =
       metrics.toolboxMetrics.position !== toolbox.Position.LEFT &&
       (!workspace.horizontalLayout || workspace.RTL);
@@ -145,24 +138,25 @@ const getCornerOppositeToolbox = function(workspace, metrics) {
       leftCorner ? horizontalPosition.LEFT : horizontalPosition.RIGHT;
   const vPosition = topCorner ? verticalPosition.TOP : verticalPosition.BOTTOM;
   return {horizontal: hPosition, vertical: vPosition};
-};
-exports.getCornerOppositeToolbox = getCornerOppositeToolbox;
+}
 
 /**
  * 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 {!Rect} startRect The starting position to use.
- * @param {number} margin The margin to use between elements when bumping.
- * @param {!bumpDirection} bumpDir The direction to bump if there is a collision
- *    with an existing UI element.
- * @param {!Array<!Rect>} savedPositions List of rectangles that
- *    represent the positions of UI elements already placed.
- * @return {!Rect} The suggested position rectangle.
+ * @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
- * @package
+ * @internal
  */
-const bumpPositionRect = function(startRect, margin, bumpDir, savedPositions) {
+export function bumpPositionRect(
+    startRect: Rect, margin: number, bumpDir: bumpDirection,
+    savedPositions: Rect[]): Rect {
   let top = startRect.top;
   const left = startRect.left;
   const width = startRect.right - startRect.left;
@@ -184,5 +178,4 @@ const bumpPositionRect = function(startRect, margin, bumpDir, savedPositions) {
     }
   }
   return boundingRect;
-};
-exports.bumpPositionRect = bumpPositionRect;
+}

package/core/procedures.d.ts

@@ -0,0 +1,108 @@
+/**
+ * @license
+ * Copyright 2012 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import './events/events_block_change.js';
+import type { Block } from './block.js';
+import type { Abstract } from './events/events_abstract.js';
+import type { Field } from './field.js';
+import type { Workspace } from './workspace.js';
+import type { WorkspaceSvg } from './workspace_svg.js';
+/**
+ * String for use in the "custom" attribute of a category in toolbox XML.
+ * This string indicates that the category should be dynamically populated with
+ * procedure blocks.
+ * See also Blockly.Variables.CATEGORY_NAME and
+ * Blockly.VariablesDynamic.CATEGORY_NAME.
+ * @alias Blockly.Procedures.CATEGORY_NAME
+ */
+export declare const CATEGORY_NAME = "PROCEDURE";
+/**
+ * The default argument for a procedures_mutatorarg block.
+ * @alias Blockly.Procedures.DEFAULT_ARG
+ */
+export declare const DEFAULT_ARG = "x";
+/**
+ * Procedure block type.
+ * @alias Blockly.Procedures.ProcedureBlock
+ */
+export interface ProcedureBlock {
+    getProcedureCall: () => string;
+    renameProcedure: (p1: string, p2: string) => any;
+    getProcedureDef: () => any[];
+}
+/**
+ * Find all user-created procedure definitions in a workspace.
+ * @param root Root workspace.
+ * @return Pair of arrays, the first contains procedures without return
+ *     variables, the second with. Each procedure is defined by a three-element
+ *     list of name, parameter list, and return value boolean.
+ * @alias Blockly.Procedures.allProcedures
+ */
+export declare function allProcedures(root: Workspace): any[][][];
+/**
+ * Ensure two identically-named procedures don't exist.
+ * Take the proposed procedure name, and return a legal name i.e. one that
+ * is not empty and doesn't collide with other procedures.
+ * @param name Proposed procedure name.
+ * @param block Block to disambiguate.
+ * @return Non-colliding name.
+ * @alias Blockly.Procedures.findLegalName
+ */
+export declare function findLegalName(name: string, block: Block): string;
+/**
+ * Return if the given name is already a procedure name.
+ * @param name The questionable name.
+ * @param workspace The workspace to scan for collisions.
+ * @param opt_exclude Optional block to exclude from comparisons (one doesn't
+ *     want to collide with oneself).
+ * @return True if the name is used, otherwise return false.
+ * @alias Blockly.Procedures.isNameUsed
+ */
+export declare function isNameUsed(name: string, workspace: Workspace, opt_exclude?: Block): boolean;
+/**
+ * Rename a procedure.  Called by the editable field.
+ * @param name The proposed new name.
+ * @return The accepted name.
+ * @alias Blockly.Procedures.rename
+ */
+export declare function rename(this: Field, name: string): string;
+/**
+ * Construct the blocks required by the flyout for the procedure category.
+ * @param workspace The workspace containing procedures.
+ * @return Array of XML block elements.
+ * @alias Blockly.Procedures.flyoutCategory
+ */
+export declare function flyoutCategory(workspace: WorkspaceSvg): Element[];
+/**
+ * Listens for when a procedure mutator is opened. Then it triggers a flyout
+ * update and adds a mutator change listener to the mutator workspace.
+ * @param e The event that triggered this listener.
+ * @alias Blockly.Procedures.mutatorOpenListener
+ * @internal
+ */
+export declare function mutatorOpenListener(e: Abstract): void;
+/**
+ * Find all the callers of a named procedure.
+ * @param name Name of procedure.
+ * @param workspace The workspace to find callers in.
+ * @return Array of caller blocks.
+ * @alias Blockly.Procedures.getCallers
+ */
+export declare function getCallers(name: string, workspace: Workspace): Block[];
+/**
+ * When a procedure definition changes its parameters, find and edit all its
+ * callers.
+ * @param defBlock Procedure definition block.
+ * @alias Blockly.Procedures.mutateCallers
+ */
+export declare function mutateCallers(defBlock: Block): void;
+/**
+ * Find the definition block for the named procedure.
+ * @param name Name of procedure.
+ * @param workspace The workspace to search.
+ * @return The procedure definition block, or null not found.
+ * @alias Blockly.Procedures.getDefinition
+ */
+export declare function getDefinition(name: string, workspace: Workspace): Block | null;