blockly 8.0.4 → 8.0.5-beta.0

package/core/component_manager.ts

@@ -0,0 +1,211 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * @fileoverview Manager for all items registered with the workspace.
+ */
+
+/**
+ * Manager for all items registered with the workspace.
+ * @class
+ */
+import * as goog from '../closure/goog/goog.js';
+goog.declareModuleId('Blockly.ComponentManager');
+
+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';
+import * as arrayUtils from './utils/array.js';
+
+
+class Capability<T> {
+  static POSITIONABLE = new Capability<IPositionable>('positionable');
+  static DRAG_TARGET = new Capability<IDragTarget>('drag_target');
+  static DELETE_AREA = new Capability<IDeleteArea>('delete_area');
+  static AUTOHIDEABLE = new Capability<IAutoHideable>('autohideable');
+  private readonly name_: string;
+  /** @param name The name of the component capability. */
+  constructor(name: string) {
+    this.name_ = name;
+  }
+
+  /**
+   * Returns the name of the capability.
+   * @return The name.
+   */
+  toString(): string {
+    return this.name_;
+  }
+}
+
+/**
+ * Manager for all items registered with the workspace.
+ * @alias Blockly.ComponentManager
+ */
+export class ComponentManager {
+  static Capability = Capability;
+
+  /**
+   * A map of the components registered with the workspace, mapped to id.
+   */
+  private readonly componentData = new Map<string, ComponentDatum>();
+
+  /** A map of capabilities to component IDs. */
+  private readonly capabilityToComponentIds = new Map<string, string[]>();
+
+  /**
+   * 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) {
+    // Don't throw an error if opt_allowOverrides is true.
+    const id = componentInfo.component.id;
+    if (!opt_allowOverrides && this.componentData.has(id)) {
+      throw Error(
+          'Plugin "' + id + '" with capabilities "' +
+          this.componentData.get(id)?.capabilities + '" already added.');
+    }
+    this.componentData.set(id, componentInfo);
+    const stringCapabilities = [];
+    for (let i = 0; i < componentInfo.capabilities.length; i++) {
+      const capability = String(componentInfo.capabilities[i]).toLowerCase();
+      stringCapabilities.push(capability);
+      if (!this.capabilityToComponentIds.has(capability)) {
+        this.capabilityToComponentIds.set(capability, [id]);
+      } else {
+        this.capabilityToComponentIds.get(capability)?.push(id);
+      }
+    }
+    this.componentData.get(id)!.capabilities = stringCapabilities;
+  }
+
+  /**
+   * Removes a component.
+   * @param id The ID of the component to remove.
+   */
+  removeComponent(id: string) {
+    const componentInfo = this.componentData.get(id);
+    if (!componentInfo) {
+      return;
+    }
+    for (let i = 0; i < componentInfo.capabilities.length; i++) {
+      const capability = String(componentInfo.capabilities[i]).toLowerCase();
+      arrayUtils.removeElem(this.capabilityToComponentIds.get(capability)!, id);
+    }
+    this.componentData.delete(id);
+  }
+
+  /**
+   * 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>) {
+    if (!this.getComponent(id)) {
+      throw Error(
+          'Cannot add capability, "' + capability + '". Plugin "' + id +
+          '" has not been added to the ComponentManager');
+    }
+    if (this.hasCapability(id, capability)) {
+      console.warn(
+          'Plugin "' + id + 'already has capability "' + capability + '"');
+      return;
+    }
+    capability = String(capability).toLowerCase();
+    this.componentData.get(id)?.capabilities.push(capability);
+    this.capabilityToComponentIds.get(capability)?.push(id);
+  }
+
+  /**
+   * 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>) {
+    if (!this.getComponent(id)) {
+      throw Error(
+          'Cannot remove capability, "' + capability + '". Plugin "' + id +
+          '" has not been added to the ComponentManager');
+    }
+    if (!this.hasCapability(id, capability)) {
+      console.warn(
+          'Plugin "' + id + 'doesn\'t have capability "' + capability +
+          '" to remove');
+      return;
+    }
+    capability = String(capability).toLowerCase();
+    arrayUtils.removeElem(this.componentData.get(id)!.capabilities, capability);
+    arrayUtils.removeElem(this.capabilityToComponentIds.get(capability)!, id);
+  }
+
+  /**
+   * 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 {
+    capability = String(capability).toLowerCase();
+    return this.componentData.has(id) &&
+        this.componentData.get(id)!.capabilities.indexOf(capability) !== -1;
+  }
+
+  /**
+   * 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 {
+    return this.componentData.get(id)?.component;
+  }
+
+  /**
+   * 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[] {
+    capability = String(capability).toLowerCase();
+    const componentIds = this.capabilityToComponentIds.get(capability);
+    if (!componentIds) {
+      return [];
+    }
+    const components: AnyDuringMigration[] = [];
+    if (sorted) {
+      const componentDataList: AnyDuringMigration[] = [];
+      componentIds.forEach((id) => {
+        componentDataList.push(this.componentData.get(id));
+      });
+      componentDataList.sort(function(a, b) {
+        return a.weight - b.weight;
+      });
+      componentDataList.forEach(function(ComponentDatum) {
+        components.push(ComponentDatum.component);
+      });
+    } else {
+      componentIds.forEach((id) => {
+        components.push(this.componentData.get(id)!.component);
+      });
+    }
+    return components;
+  }
+}
+
+export namespace ComponentManager {
+  /** An object storing component information. */
+  export interface ComponentDatum {
+    component: IComponent;
+    capabilities: Array<string|Capability<IComponent>>;
+    weight: number;
+  }
+}
+
+export type ComponentDatum = ComponentManager.ComponentDatum;

package/core/config.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @license
+ * Copyright 2022 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * All the values that we expect developers to be able to change
+ * before injecting Blockly.
+ */
+interface Config {
+    dragRadius: number;
+    flyoutDragRadius: number;
+    snapRadius: number;
+    currentConnectionPreference: number;
+    bumpDelay: number;
+    connectingSnapRadius: number;
+}
+/**
+ * Object holding all the values on Blockly that we expect developers to be
+ * able to change.
+ */
+export declare const config: Config;
+export {};

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

@@ -9,7 +9,6 @@
  * before injecting Blockly. Changing these values during run time is not
  * generally recommended.
  */
-'use strict';
 
 /**
  * All the values that we expect developers to be able to change
@@ -17,35 +16,31 @@
  * generally recommended.
  * @namespace Blockly.config
  */
-goog.module('Blockly.config');
+import * as goog from '../closure/goog/goog.js';
+goog.declareModuleId('Blockly.config');
 
 
 /**
  * All the values that we expect developers to be able to change
  * before injecting Blockly.
- * @typedef {{
- *      dragRadius: number,
- *      flyoutDragRadius: number,
- *      snapRadius: number,
- *      currentConnectionPreference: number,
- *      bumpDelay: number,
- *      connectingSnapRadius: number
- *    }}
  */
-let Config;  // eslint-disable-line no-unused-vars
+interface Config {
+  dragRadius: number;
+  flyoutDragRadius: number;
+  snapRadius: number;
+  currentConnectionPreference: number;
+  bumpDelay: number;
+  connectingSnapRadius: number;
+}
 
-/**
- * Default snap radius.
- * @type {number}
- */
+/** Default snap radius. */
 const DEFAULT_SNAP_RADIUS = 28;
 
 /**
  * Object holding all the values on Blockly that we expect developers to be
  * able to change.
- * @type {Config}
  */
-const config = {
+export const config: Config = {
   /**
    * Number of pixels the mouse must move before a drag starts.
    * @alias Blockly.config.dragRadius
@@ -83,5 +78,3 @@ const config = {
    */
   bumpDelay: 250,
 };
-
-exports.config = config;

package/core/connection.d.ts

@@ -0,0 +1,232 @@
+/**
+ * @license
+ * Copyright 2011 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { Block } from './block.js';
+import type { Input } from './input.js';
+import type { IASTNodeLocationWithBlock } from './interfaces/i_ast_node_location_with_block.js';
+import type { IConnectionChecker } from './interfaces/i_connection_checker.js';
+import * as blocks from './serialization/blocks.js';
+/**
+ * Class for a connection between blocks.
+ * @alias Blockly.Connection
+ */
+export declare class Connection implements IASTNodeLocationWithBlock {
+    type: number;
+    /** Constants for checking whether two connections are compatible. */
+    static CAN_CONNECT: number;
+    static REASON_SELF_CONNECTION: number;
+    static REASON_WRONG_TYPE: number;
+    static REASON_TARGET_NULL: number;
+    static REASON_CHECKS_FAILED: number;
+    static REASON_DIFFERENT_WORKSPACES: number;
+    static REASON_SHADOW_PARENT: number;
+    static REASON_DRAG_CHECKS_FAILED: number;
+    static REASON_PREVIOUS_AND_OUTPUT: number;
+    protected sourceBlock_: Block;
+    /** Connection this connection connects to.  Null if not connected. */
+    targetConnection: Connection | null;
+    /**
+     * Has this connection been disposed of?
+     * @internal
+     */
+    disposed: boolean;
+    /** List of compatible value types.  Null if all types are compatible. */
+    private check_;
+    /** DOM representation of a shadow block, or null if none. */
+    private shadowDom_;
+    /**
+     * Horizontal location of this connection.
+     * @internal
+     */
+    x: number;
+    /**
+     * Vertical location of this connection.
+     * @internal
+     */
+    y: number;
+    private shadowState_;
+    /**
+     * @param source The block establishing this connection.
+     * @param type The type of the connection.
+     */
+    constructor(source: Block, type: number);
+    /**
+     * Connect two connections together.  This is the connection on the superior
+     * block.
+     * @param childConnection Connection on inferior block.
+     */
+    protected connect_(childConnection: Connection): void;
+    /**
+     * Dispose of this connection and deal with connected blocks.
+     * @internal
+     */
+    dispose(): void;
+    /**
+     * Get the source block for this connection.
+     * @return The source block.
+     */
+    getSourceBlock(): Block;
+    /**
+     * Does the connection belong to a superior block (higher in the source
+     * stack)?
+     * @return True if connection faces down or right.
+     */
+    isSuperior(): boolean;
+    /**
+     * Is the connection connected?
+     * @return True if connection is connected to another connection.
+     */
+    isConnected(): boolean;
+    /**
+     * Get the workspace's connection type checker object.
+     * @return The connection type checker for the source block's workspace.
+     * @internal
+     */
+    getConnectionChecker(): IConnectionChecker;
+    /**
+     * Called when an attempted connection fails. NOP by default (i.e. for
+     * headless workspaces).
+     * @param _otherConnection Connection that this connection failed to connect
+     *     to.
+     * @internal
+     */
+    onFailedConnect(_otherConnection: Connection): void;
+    /**
+     * Connect this connection to another connection.
+     * @param otherConnection Connection to connect to.
+     * @return Whether the the blocks are now connected or not.
+     */
+    connect(otherConnection: Connection): boolean;
+    /** Disconnect this connection. */
+    disconnect(): void;
+    /**
+     * Disconnect two blocks that are connected by this connection.
+     * @param parentBlock The superior block.
+     * @param childBlock The inferior block.
+     */
+    protected disconnectInternal_(parentBlock: Block, childBlock: Block): void;
+    /**
+     * Respawn the shadow block if there was one connected to the this connection.
+     */
+    protected respawnShadow_(): void;
+    /**
+     * Returns the block that this connection connects to.
+     * @return The connected block or null if none is connected.
+     */
+    targetBlock(): Block | null;
+    /**
+     * Function to be called when this connection's compatible types have changed.
+     */
+    protected onCheckChanged_(): void;
+    /**
+     * Change a connection's compatibility.
+     * @param check Compatible value type or list of value types. Null if all
+     *     types are compatible.
+     * @return The connection being modified (to allow chaining).
+     */
+    setCheck(check: string | string[] | null): Connection;
+    /**
+     * Get a connection's compatibility.
+     * @return List of compatible value types.
+     *     Null if all types are compatible.
+     */
+    getCheck(): string[] | null;
+    /**
+     * Changes the connection's shadow block.
+     * @param shadowDom DOM representation of a block or null.
+     */
+    setShadowDom(shadowDom: Element | null): void;
+    /**
+     * Returns the xml representation of the connection's shadow block.
+     * @param returnCurrent If true, and the shadow block is currently attached to
+     *     this connection, this serializes the state of that block and returns it
+     *     (so that field values are correct). Otherwise the saved shadowDom is
+     *     just returned.
+     * @return Shadow DOM representation of a block or null.
+     */
+    getShadowDom(returnCurrent?: boolean): Element | null;
+    /**
+     * Changes the connection's shadow block.
+     * @param shadowState An state represetation of the block or null.
+     */
+    setShadowState(shadowState: blocks.State | null): void;
+    /**
+     * Returns the serialized object representation of the connection's shadow
+     * block.
+     * @param returnCurrent If true, and the shadow block is currently attached to
+     *     this connection, this serializes the state of that block and returns it
+     *     (so that field values are correct). Otherwise the saved state is just
+     *     returned.
+     * @return Serialized object representation of the block, or null.
+     */
+    getShadowState(returnCurrent?: boolean): blocks.State | null;
+    /**
+     * Find all nearby compatible connections to this connection.
+     * Type checking does not apply, since this function is used for bumping.
+     *
+     * Headless configurations (the default) do not have neighboring connection,
+     * and always return an empty list (the default).
+     * {@link Blockly.RenderedConnection} overrides this behavior with a list
+     * computed from the rendered positioning.
+     * @param _maxLimit The maximum radius to another connection.
+     * @return List of connections.
+     * @internal
+     */
+    neighbours(_maxLimit: number): Connection[];
+    /**
+     * Get the parent input of a connection.
+     * @return The input that the connection belongs to or null if no parent
+     *     exists.
+     * @internal
+     */
+    getParentInput(): Input | null;
+    /**
+     * This method returns a string describing this Connection in developer terms
+     * (English only). Intended to on be used in console logs and errors.
+     * @return The description.
+     */
+    toString(): string;
+    /**
+     * Returns the state of the shadowDom_ and shadowState_ properties, then
+     * temporarily sets those properties to null so no shadow respawns.
+     * @return The state of both the shadowDom_ and shadowState_ properties.
+     */
+    private stashShadowState_;
+    /**
+     * Reapplies the stashed state of the shadowDom_ and shadowState_ properties.
+     * @param param0 The state to reapply to the shadowDom_ and shadowState_
+     *     properties.
+     */
+    private applyShadowState_;
+    /**
+     * Sets the state of the shadow of this connection.
+     * @param param0 The state to set the shadow of this connection to.
+     */
+    private setShadowStateInternal_;
+    /**
+     * Creates a shadow block based on the current shadowState_ or shadowDom_.
+     * shadowState_ gets priority.
+     * @param attemptToConnect Whether to try to connect the shadow block to this
+     *     connection or not.
+     * @return The shadow block that was created, or null if both the shadowState_
+     *     and shadowDom_ are null.
+     */
+    private createShadowBlock_;
+    /**
+     * Saves the given shadow block to both the shadowDom_ and shadowState_
+     * properties, in their respective serialized forms.
+     * @param shadow The shadow to serialize, or null.
+     */
+    private serializeShadow_;
+    /**
+     * Returns the connection (starting at the startBlock) which will accept
+     * the given connection. This includes compatible connection types and
+     * connection checks.
+     * @param startBlock The block on which to start the search.
+     * @param orphanConnection The connection that is looking for a home.
+     * @return The suitable connection point on the chain of blocks, or null.
+     */
+    static getConnectionForOrphanedConnection(startBlock: Block, orphanConnection: Connection): Connection | null;
+}