blockly 8.0.4 → 8.0.5-beta.0

package/core/common.d.ts

@@ -0,0 +1,129 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { Block } from './block.js';
+import { BlockDefinition } from './blocks.js';
+import type { Connection } from './connection.js';
+import type { ICopyable } from './interfaces/i_copyable.js';
+import type { Workspace } from './workspace.js';
+import type { WorkspaceSvg } from './workspace_svg.js';
+/**
+ * Find the workspace with the specified ID.
+ * @param id ID of workspace to find.
+ * @return The sought after workspace or null if not found.
+ */
+export declare function getWorkspaceById(id: string): Workspace | null;
+/**
+ * Find all workspaces.
+ * @return Array of workspaces.
+ */
+export declare function getAllWorkspaces(): Workspace[];
+export declare function registerWorkspace(workspace: Workspace): void;
+export declare function unregisterWorkpace(workspace: Workspace): void;
+/**
+ * Returns the last used top level workspace (based on focus).  Try not to use
+ * this function, particularly if there are multiple Blockly instances on a
+ * page.
+ * @return The main workspace.
+ * @alias Blockly.common.getMainWorkspace
+ */
+export declare function getMainWorkspace(): Workspace;
+/**
+ * Sets last used main workspace.
+ * @param workspace The most recently used top level workspace.
+ * @alias Blockly.common.setMainWorkspace
+ */
+export declare function setMainWorkspace(workspace: Workspace): void;
+/**
+ * Returns the currently selected copyable object.
+ * @alias Blockly.common.getSelected
+ */
+export declare function getSelected(): ICopyable | null;
+/**
+ * Sets the currently selected block. This function does not visually mark the
+ * block as selected or fire the required events. If you wish to
+ * programmatically select a block, use `BlockSvg#select`.
+ * @param newSelection The newly selected block.
+ * @alias Blockly.common.setSelected
+ * @internal
+ */
+export declare function setSelected(newSelection: ICopyable | null): void;
+/**
+ * Get the container element in which to render the WidgetDiv, DropDownDiv and\
+ * Tooltip.
+ * @return The parent container.
+ * @alias Blockly.common.getParentContainer
+ */
+export declare function getParentContainer(): Element | null;
+/**
+ * Set the parent container.  This is the container element that the WidgetDiv,
+ * DropDownDiv, and Tooltip are rendered into the first time `Blockly.inject`
+ * is called.
+ * This method is a NOP if called after the first ``Blockly.inject``.
+ * @param newParent The container element.
+ * @alias Blockly.common.setParentContainer
+ */
+export declare function setParentContainer(newParent: Element): void;
+/**
+ * Size the SVG image to completely fill its container. Call this when the view
+ * actually changes sizes (e.g. on a window resize/device orientation change).
+ * See workspace.resizeContents to resize the workspace when the contents
+ * change (e.g. when a block is added or removed).
+ * Record the height/width of the SVG image.
+ * @param workspace Any workspace in the SVG.
+ * @alias Blockly.common.svgResize
+ */
+export declare function svgResize(workspace: WorkspaceSvg): void;
+/**
+ * All of the connections on blocks that are currently being dragged.
+ */
+export declare const draggingConnections: Connection[];
+/**
+ * Get a map of all the block's descendants mapping their type to the number of
+ *    children with that type.
+ * @param block The block to map.
+ * @param opt_stripFollowing Optionally ignore all following
+ *    statements (blocks that are not inside a value or statement input
+ *    of the block).
+ * @return Map of types to type counts for descendants of the bock.
+ * @alias Blockly.common.getBlockTypeCounts
+ */
+export declare function getBlockTypeCounts(block: Block, opt_stripFollowing?: boolean): any;
+/**
+ * Define blocks from an array of JSON block definitions, as might be generated
+ * by the Blockly Developer Tools.
+ * @param jsonArray An array of JSON block definitions.
+ * @alias Blockly.common.defineBlocksWithJsonArray
+ */
+export declare function defineBlocksWithJsonArray(jsonArray: any[]): void;
+/**
+ * Private version of defineBlocksWithJsonArray for stubbing in tests.
+ */
+declare function defineBlocksWithJsonArrayInternal(jsonArray: any[]): void;
+/**
+ * Define blocks from an array of JSON block definitions, as might be generated
+ * by the Blockly Developer Tools.
+ * @param jsonArray An array of JSON block definitions.
+ * @return A map of the block
+ *     definitions created.
+ * @alias Blockly.common.defineBlocksWithJsonArray
+ */
+export declare function createBlockDefinitionsFromJsonArray(jsonArray: any[]): {
+    [key: string]: BlockDefinition;
+};
+/**
+ * Add the specified block definitions to the block definitions
+ * dictionary (Blockly.Blocks).
+ * @param blocks A map of block
+ *     type names to block definitions.
+ * @alias Blockly.common.defineBlocks
+ */
+export declare function defineBlocks(blocks: {
+    [key: string]: BlockDefinition;
+}): void;
+export declare const TEST_ONLY: {
+    defineBlocksWithJsonArrayInternal: typeof defineBlocksWithJsonArrayInternal;
+};
+export {};

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

@@ -8,116 +8,134 @@
  * @fileoverview Common functions used both internally and externally, but which
  * must not be at the top level to avoid circular dependencies.
  */
-'use strict';
 
 /**
  * Common functions used both internally and externally, but which
  * must not be at the top level to avoid circular dependencies.
  * @namespace Blockly.common
  */
-goog.module('Blockly.common');
+import * as goog from '../closure/goog/goog.js';
+goog.declareModuleId('Blockly.common');
 
 /* eslint-disable-next-line no-unused-vars */
-const {BlockDefinition, Blocks} = goog.require('Blockly.blocks');
-/* eslint-disable-next-line no-unused-vars */
-const {Connection} = goog.requireType('Blockly.Connection');
-/* eslint-disable-next-line no-unused-vars */
-const {ICopyable} = goog.requireType('Blockly.ICopyable');
-/* eslint-disable-next-line no-unused-vars */
-const {Block} = goog.requireType('Blockly.Block');
-/* eslint-disable-next-line no-unused-vars */
-const {WorkspaceSvg} = goog.requireType('Blockly.WorkspaceSvg');
-/* eslint-disable-next-line no-unused-vars */
-const {Workspace} = goog.requireType('Blockly.Workspace');
+import type {Block} from './block.js';
+import {BlockDefinition, Blocks} from './blocks.js';
+import type {Connection} from './connection.js';
+import type {ICopyable} from './interfaces/i_copyable.js';
+import type {Workspace} from './workspace.js';
+import type {WorkspaceSvg} from './workspace_svg.js';
+
+
+/** Database of all workspaces. */
+const WorkspaceDB_ = Object.create(null);
 
 
+/**
+ * Find the workspace with the specified ID.
+ * @param id ID of workspace to find.
+ * @return The sought after workspace or null if not found.
+ */
+export function getWorkspaceById(id: string): Workspace|null {
+  return WorkspaceDB_[id] || null;
+}
+
+/**
+ * Find all workspaces.
+ * @return Array of workspaces.
+ */
+export function getAllWorkspaces(): Workspace[] {
+  const workspaces = [];
+  for (const workspaceId in WorkspaceDB_) {
+    workspaces.push(WorkspaceDB_[workspaceId]);
+  }
+  return workspaces;
+}
+
+export function registerWorkspace(workspace: Workspace) {
+  WorkspaceDB_[workspace.id] = workspace;
+}
+
+export function unregisterWorkpace(workspace: Workspace) {
+  delete WorkspaceDB_[workspace.id];
+}
+
 /**
  * The main workspace most recently used.
  * Set by Blockly.WorkspaceSvg.prototype.markFocused
- * @type {!Workspace}
  */
-let mainWorkspace;
+let mainWorkspace: Workspace;
 
 /**
  * Returns the last used top level workspace (based on focus).  Try not to use
  * this function, particularly if there are multiple Blockly instances on a
  * page.
- * @return {!Workspace} The main workspace.
+ * @return The main workspace.
  * @alias Blockly.common.getMainWorkspace
  */
-const getMainWorkspace = function() {
+export function getMainWorkspace(): Workspace {
   return mainWorkspace;
-};
-exports.getMainWorkspace = getMainWorkspace;
+}
 
 /**
  * Sets last used main workspace.
- * @param {!Workspace} workspace The most recently used top level workspace.
+ * @param workspace The most recently used top level workspace.
  * @alias Blockly.common.setMainWorkspace
  */
-const setMainWorkspace = function(workspace) {
+export function setMainWorkspace(workspace: Workspace) {
   mainWorkspace = workspace;
-};
-exports.setMainWorkspace = setMainWorkspace;
+}
 
 /**
- * Currently selected block.
- * @type {?ICopyable}
+ * Currently selected copyable object.
  */
-let selected = null;
+let selected: ICopyable|null = null;
 
 /**
- * Returns the currently selected block.
- * @return {?ICopyable} The currently selected block.
+ * Returns the currently selected copyable object.
  * @alias Blockly.common.getSelected
  */
-const getSelected = function() {
+export function getSelected(): ICopyable|null {
   return selected;
-};
-exports.getSelected = getSelected;
+}
 
 /**
  * Sets the currently selected block. This function does not visually mark the
  * block as selected or fire the required events. If you wish to
  * programmatically select a block, use `BlockSvg#select`.
- * @param {?ICopyable} newSelection The newly selected block.
+ * @param newSelection The newly selected block.
  * @alias Blockly.common.setSelected
- * @package
+ * @internal
  */
-const setSelected = function(newSelection) {
+export function setSelected(newSelection: ICopyable|null) {
   selected = newSelection;
-};
-exports.setSelected = setSelected;
+}
 
 /**
  * Container element in which to render the WidgetDiv, DropDownDiv and Tooltip.
- * @type {?Element}
  */
-let parentContainer;
+let parentContainer: Element|null;
 
 /**
  * Get the container element in which to render the WidgetDiv, DropDownDiv and\
  * Tooltip.
- * @return {?Element} The parent container.
+ * @return The parent container.
  * @alias Blockly.common.getParentContainer
  */
-const getParentContainer = function() {
+export function getParentContainer(): Element|null {
   return parentContainer;
-};
-exports.getParentContainer = getParentContainer;
+}
 
 /**
  * Set the parent container.  This is the container element that the WidgetDiv,
  * DropDownDiv, and Tooltip are rendered into the first time `Blockly.inject`
  * is called.
  * This method is a NOP if called after the first ``Blockly.inject``.
- * @param {!Element} newParent The container element.
+ * @param newParent The container element.
  * @alias Blockly.common.setParentContainer
  */
-const setParentContainer = function(newParent) {
+export function setParentContainer(newParent: Element) {
   parentContainer = newParent;
-};
-exports.setParentContainer = setParentContainer;
+}
 
 /**
  * Size the SVG image to completely fill its container. Call this when the view
@@ -125,21 +143,22 @@ exports.setParentContainer = setParentContainer;
  * See workspace.resizeContents to resize the workspace when the contents
  * change (e.g. when a block is added or removed).
  * Record the height/width of the SVG image.
- * @param {!WorkspaceSvg} workspace Any workspace in the SVG.
+ * @param workspace Any workspace in the SVG.
  * @alias Blockly.common.svgResize
  */
-const svgResize = function(workspace) {
+export function svgResize(workspace: WorkspaceSvg) {
   let mainWorkspace = workspace;
   while (mainWorkspace.options.parentWorkspace) {
     mainWorkspace = mainWorkspace.options.parentWorkspace;
   }
   const svg = mainWorkspace.getParentSvg();
   const cachedSize = mainWorkspace.getCachedParentSvgSize();
-  const div = svg.parentNode;
-  if (!div) {
+  const div = svg.parentElement;
+  if (!(div instanceof HTMLElement)) {
     // Workspace deleted, or something.
     return;
   }
+
   const width = div.offsetWidth;
   const height = div.offsetHeight;
   if (cachedSize.width !== width) {
@@ -151,26 +170,25 @@ const svgResize = function(workspace) {
     mainWorkspace.setCachedParentSvgSize(null, height);
   }
   mainWorkspace.resize();
-};
-exports.svgResize = svgResize;
+}
 
 /**
  * All of the connections on blocks that are currently being dragged.
- * @type {!Array<!Connection>}
  */
-exports.draggingConnections = [];
+export const draggingConnections: Connection[] = [];
 
 /**
  * Get a map of all the block's descendants mapping their type to the number of
  *    children with that type.
- * @param {!Block} block The block to map.
- * @param {boolean=} opt_stripFollowing Optionally ignore all following
+ * @param block The block to map.
+ * @param opt_stripFollowing Optionally ignore all following
  *    statements (blocks that are not inside a value or statement input
  *    of the block).
- * @return {!Object} Map of types to type counts for descendants of the bock.
+ * @return Map of types to type counts for descendants of the bock.
  * @alias Blockly.common.getBlockTypeCounts
  */
-const getBlockTypeCounts = function(block, opt_stripFollowing) {
+export function getBlockTypeCounts(
+    block: Block, opt_stripFollowing?: boolean): AnyDuringMigration {
   const typeCountsMap = Object.create(null);
   const descendants = block.getDescendants(true);
   if (opt_stripFollowing) {
@@ -180,7 +198,7 @@ const getBlockTypeCounts = function(block, opt_stripFollowing) {
       descendants.splice(index, descendants.length - index);
     }
   }
-  for (let i = 0, checkBlock; (checkBlock = descendants[i]); i++) {
+  for (let i = 0, checkBlock; checkBlock = descendants[i]; i++) {
     if (typeCountsMap[checkBlock.type]) {
       typeCountsMap[checkBlock.type]++;
     } else {
@@ -188,50 +206,56 @@ const getBlockTypeCounts = function(block, opt_stripFollowing) {
     }
   }
   return typeCountsMap;
-};
-exports.getBlockTypeCounts = getBlockTypeCounts;
+}
 
 /**
  * Helper function for defining a block from JSON.  The resulting function has
  * the correct value of jsonDef at the point in code where jsonInit is called.
- * @param {!Object} jsonDef The JSON definition of a block.
- * @return {function()} A function that calls jsonInit with the correct value
+ * @param jsonDef The JSON definition of a block.
+ * @return A function that calls jsonInit with the correct value
  *     of jsonDef.
  */
-const jsonInitFactory = function(jsonDef) {
-  return /** @this {Block} */ function() {
+function jsonInitFactory(jsonDef: AnyDuringMigration): () => void {
+  return function(this: Block) {
     this.jsonInit(jsonDef);
   };
-};
+}
 
 /**
  * Define blocks from an array of JSON block definitions, as might be generated
  * by the Blockly Developer Tools.
- * @param {!Array<!Object>} jsonArray An array of JSON block definitions.
+ * @param jsonArray An array of JSON block definitions.
  * @alias Blockly.common.defineBlocksWithJsonArray
  */
-const defineBlocksWithJsonArray = function(jsonArray) {
+export function defineBlocksWithJsonArray(jsonArray: AnyDuringMigration[]) {
+  TEST_ONLY.defineBlocksWithJsonArrayInternal(jsonArray);
+}
+
+/**
+ * Private version of defineBlocksWithJsonArray for stubbing in tests.
+ */
+function defineBlocksWithJsonArrayInternal(jsonArray: AnyDuringMigration[]) {
   defineBlocks(createBlockDefinitionsFromJsonArray(jsonArray));
-};
-exports.defineBlocksWithJsonArray = defineBlocksWithJsonArray;
+}
 
 /**
  * Define blocks from an array of JSON block definitions, as might be generated
  * by the Blockly Developer Tools.
- * @param {!Array<!Object>} jsonArray An array of JSON block definitions.
- * @return {!Object<string, !BlockDefinition>} A map of the block
+ * @param jsonArray An array of JSON block definitions.
+ * @return A map of the block
  *     definitions created.
  * @alias Blockly.common.defineBlocksWithJsonArray
  */
-const createBlockDefinitionsFromJsonArray = function(jsonArray) {
-  const /** @type {!Object<string,!BlockDefinition>} */ blocks = {};
+export function createBlockDefinitionsFromJsonArray(
+    jsonArray: AnyDuringMigration[]): {[key: string]: BlockDefinition} {
+  const blocks: {[key: string]: BlockDefinition} = {};
   for (let i = 0; i < jsonArray.length; i++) {
     const elem = jsonArray[i];
     if (!elem) {
       console.warn(`Block definition #${i} in JSON array is ${elem}. Skipping`);
       continue;
     }
-    const type = elem.type;
+    const type = elem['type'];
     if (!type) {
       console.warn(
           `Block definition #${i} in JSON array is missing a type attribute. ` +
@@ -241,18 +265,16 @@ const createBlockDefinitionsFromJsonArray = function(jsonArray) {
     blocks[type] = {init: jsonInitFactory(elem)};
   }
   return blocks;
-};
-exports.createBlockDefinitionsFromJsonArray =
-    createBlockDefinitionsFromJsonArray;
+}
 
 /**
  * Add the specified block definitions to the block definitions
  * dictionary (Blockly.Blocks).
- * @param {!Object<string,!BlockDefinition>} blocks A map of block
+ * @param blocks A map of block
  *     type names to block definitions.
  * @alias Blockly.common.defineBlocks
  */
-const defineBlocks = function(blocks) {
+export function defineBlocks(blocks: {[key: string]: BlockDefinition}) {
   // Iterate over own enumerable properties.
   for (const type of Object.keys(blocks)) {
     const definition = blocks[type];
@@ -261,5 +283,6 @@ const defineBlocks = function(blocks) {
     }
     Blocks[type] = definition;
   }
-};
-exports.defineBlocks = defineBlocks;
+}
+
+export const TEST_ONLY = {defineBlocksWithJsonArrayInternal};

package/core/component_manager.d.ts

@@ -0,0 +1,91 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { IAutoHideable } from './interfaces/i_autohideable.js';
+import type { IComponent } from './interfaces/i_component.js';
+import type { IDeleteArea } from './interfaces/i_delete_area.js';
+import type { IDragTarget } from './interfaces/i_drag_target.js';
+import type { IPositionable } from './interfaces/i_positionable.js';
+declare class Capability<T> {
+    static POSITIONABLE: Capability<IPositionable>;
+    static DRAG_TARGET: Capability<IDragTarget>;
+    static DELETE_AREA: Capability<IDeleteArea>;
+    static AUTOHIDEABLE: Capability<IAutoHideable>;
+    private readonly name_;
+    /** @param name The name of the component capability. */
+    constructor(name: string);
+    /**
+     * Returns the name of the capability.
+     * @return The name.
+     */
+    toString(): string;
+}
+/**
+ * Manager for all items registered with the workspace.
+ * @alias Blockly.ComponentManager
+ */
+export declare class ComponentManager {
+    static Capability: typeof Capability;
+    /**
+     * A map of the components registered with the workspace, mapped to id.
+     */
+    private readonly componentData;
+    /** A map of capabilities to component IDs. */
+    private readonly capabilityToComponentIds;
+    /**
+     * Adds a component.
+     * @param componentInfo The data for the component to register.
+     * @param opt_allowOverrides True to prevent an error when overriding an
+     *     already registered item.
+     */
+    addComponent(componentInfo: ComponentDatum, opt_allowOverrides?: boolean): void;
+    /**
+     * Removes a component.
+     * @param id The ID of the component to remove.
+     */
+    removeComponent(id: string): void;
+    /**
+     * Adds a capability to a existing registered component.
+     * @param id The ID of the component to add the capability to.
+     * @param capability The capability to add.
+     */
+    addCapability<T>(id: string, capability: string | Capability<T>): void;
+    /**
+     * Removes a capability from an existing registered component.
+     * @param id The ID of the component to remove the capability from.
+     * @param capability The capability to remove.
+     */
+    removeCapability<T>(id: string, capability: string | Capability<T>): void;
+    /**
+     * Returns whether the component with this id has the specified capability.
+     * @param id The ID of the component to check.
+     * @param capability The capability to check for.
+     * @return Whether the component has the capability.
+     */
+    hasCapability<T>(id: string, capability: string | Capability<T>): boolean;
+    /**
+     * Gets the component with the given ID.
+     * @param id The ID of the component to get.
+     * @return The component with the given name or undefined if not found.
+     */
+    getComponent(id: string): IComponent | undefined;
+    /**
+     * Gets all the components with the specified capability.
+     * @param capability The capability of the component.
+     * @param sorted Whether to return list ordered by weights.
+     * @return The components that match the specified capability.
+     */
+    getComponents<T>(capability: string | Capability<T>, sorted: boolean): T[];
+}
+export declare namespace ComponentManager {
+    /** An object storing component information. */
+    interface ComponentDatum {
+        component: IComponent;
+        capabilities: Array<string | Capability<IComponent>>;
+        weight: number;
+    }
+}
+export declare type ComponentDatum = ComponentManager.ComponentDatum;
+export {};