blockly 12.4.0 → 12.5.0

package/core/connection.d.ts

@@ -0,0 +1,291 @@
+/**
+ * @license
+ * Copyright 2011 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Components for creating connections between blocks.
+ *
+ * @class
+ */
+import type { Block } from './block.js';
+import type { Input } from './inputs/input.js';
+import type { IConnectionChecker } from './interfaces/i_connection_checker.js';
+import * as blocks from './serialization/blocks.js';
+/**
+ * Class for a connection between blocks.
+ */
+export declare class Connection {
+    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;
+    /** The unique ID of this connection. */
+    id: string;
+    /**
+     * 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.
+     *
+     * @returns The source block.
+     */
+    getSourceBlock(): Block;
+    /**
+     * Does the connection belong to a superior block (higher in the source
+     * stack)?
+     *
+     * @returns True if connection faces down or right.
+     */
+    isSuperior(): boolean;
+    /**
+     * Is the connection connected?
+     *
+     * @returns True if connection is connected to another connection.
+     */
+    isConnected(): boolean;
+    /**
+     * Get the workspace's connection type checker object.
+     *
+     * @returns 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 _superiorConnection Connection that this connection failed to connect
+     *     to. The provided connection should be the superior connection.
+     * @internal
+     */
+    onFailedConnect(_superiorConnection: Connection): void;
+    /**
+     * Connect this connection to another connection.
+     *
+     * @param otherConnection Connection to connect to.
+     * @returns Whether 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 setParent Whether to set the parent of the disconnected block or
+     *     not, defaults to true.
+     *     If you do not set the parent, ensure that a subsequent action does,
+     *     otherwise the view and model will be out of sync.
+     */
+    protected disconnectInternal(setParent?: boolean): void;
+    /**
+     * Returns the parent connection (superior) and child connection (inferior)
+     * given this connection and the connection it is connected to.
+     *
+     * @returns The parent connection and child connection, given this connection
+     *     and the connection it is connected to.
+     */
+    protected getParentAndChildConnections(): {
+        parentConnection?: Connection;
+        childConnection?: Connection;
+    };
+    /**
+     * Respawn the shadow block if there was one connected to the this connection.
+     */
+    protected respawnShadow_(): void;
+    /**
+     * Reconnects this connection to the input with the given name on the given
+     * block. If there is already a connection connected to that input, that
+     * connection is disconnected.
+     *
+     * @param block The block to connect this connection to.
+     * @param inputName The name of the input to connect this connection to.
+     * @returns True if this connection was able to connect, false otherwise.
+     */
+    reconnect(block: Block, inputName: string): boolean;
+    /**
+     * Returns the block that this connection connects to.
+     *
+     * @returns 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.
+     * @returns The connection being modified (to allow chaining).
+     */
+    setCheck(check: string | string[] | null): Connection;
+    /**
+     * Get a connection's compatibility.
+     *
+     * @returns 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.
+     * @returns 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.
+     * @returns 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 (RenderedConnection:class).neighbours} overrides this behavior with a list
+     * computed from the rendered positioning.
+     *
+     * @param _maxLimit The maximum radius to another connection.
+     * @returns List of connections.
+     * @internal
+     */
+    neighbours(_maxLimit: number): Connection[];
+    /**
+     * Get the parent input of a connection.
+     *
+     * @returns 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.
+     *
+     * @returns The description.
+     */
+    toString(): string;
+    /**
+     * Returns the state of the shadowDom_ and shadowState_ properties, then
+     * temporarily sets those properties to null so no shadow respawns.
+     *
+     * @returns 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.
+     * @returns 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.
+     * @returns The suitable connection point on the chain of blocks, or null.
+     */
+    static getConnectionForOrphanedConnection(startBlock: Block, orphanConnection: Connection): Connection | null;
+}
+//# sourceMappingURL=connection.d.ts.map

package/core/connection_checker.d.ts

@@ -0,0 +1,85 @@
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Connection } from './connection.js';
+import type { IConnectionChecker } from './interfaces/i_connection_checker.js';
+import type { RenderedConnection } from './rendered_connection.js';
+/**
+ * Class for connection type checking logic.
+ */
+export declare class ConnectionChecker implements IConnectionChecker {
+    /**
+     * Check whether the current connection can connect with the target
+     * connection.
+     *
+     * @param a Connection to check compatibility with.
+     * @param b Connection to check compatibility with.
+     * @param isDragging True if the connection is being made by dragging a block.
+     * @param opt_distance The max allowable distance between the connections for
+     *     drag checks.
+     * @returns Whether the connection is legal.
+     */
+    canConnect(a: Connection | null, b: Connection | null, isDragging: boolean, opt_distance?: number): boolean;
+    /**
+     * Checks whether the current connection can connect with the target
+     * connection, and return an error code if there are problems.
+     *
+     * @param a Connection to check compatibility with.
+     * @param b Connection to check compatibility with.
+     * @param isDragging True if the connection is being made by dragging a block.
+     * @param opt_distance The max allowable distance between the connections for
+     *     drag checks.
+     * @returns Connection.CAN_CONNECT if the connection is legal, an error code
+     *     otherwise.
+     */
+    canConnectWithReason(a: Connection | null, b: Connection | null, isDragging: boolean, opt_distance?: number): number;
+    /**
+     * Helper method that translates a connection error code into a string.
+     *
+     * @param errorCode The error code.
+     * @param a One of the two connections being checked.
+     * @param b The second of the two connections being checked.
+     * @returns A developer-readable error string.
+     */
+    getErrorMessage(errorCode: number, a: Connection | null, b: Connection | null): string;
+    /**
+     * Check that connecting the given connections is safe, meaning that it would
+     * not break any of Blockly's basic assumptions (e.g. no self connections).
+     *
+     * @param a The first of the connections to check.
+     * @param b The second of the connections to check.
+     * @returns An enum with the reason this connection is safe or unsafe.
+     */
+    doSafetyChecks(a: Connection | null, b: Connection | null): number;
+    /**
+     * Check whether this connection is compatible with another connection with
+     * respect to the value type system.  E.g. square_root("Hello") is not
+     * compatible.
+     *
+     * @param a Connection to compare.
+     * @param b Connection to compare against.
+     * @returns True if the connections share a type.
+     */
+    doTypeChecks(a: Connection, b: Connection): boolean;
+    /**
+     * Check whether this connection can be made by dragging.
+     *
+     * @param a Connection to compare (on the block that's being dragged).
+     * @param b Connection to compare against.
+     * @param distance The maximum allowable distance between connections.
+     * @returns True if the connection is allowed during a drag.
+     */
+    doDragChecks(a: RenderedConnection, b: RenderedConnection, distance: number): boolean;
+    /**
+     * Helper function for drag checking.
+     *
+     * @param a The connection to check, which must be a statement input or next
+     *     connection.
+     * @param b A nearby connection to check, which must be a previous connection.
+     * @returns True if the connection is allowed, false otherwise.
+     */
+    protected canConnectToPrevious_(a: Connection, b: Connection): boolean;
+}
+//# sourceMappingURL=connection_checker.d.ts.map

package/core/connection_db.d.ts

@@ -0,0 +1,100 @@
+/**
+ * @license
+ * Copyright 2011 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { IConnectionChecker } from './interfaces/i_connection_checker.js';
+import type { RenderedConnection } from './rendered_connection.js';
+import type { Coordinate } from './utils/coordinate.js';
+/**
+ * Database of connections.
+ * Connections are stored in order of their vertical component.  This way
+ * connections in an area may be looked up quickly using a binary search.
+ */
+export declare class ConnectionDB {
+    private readonly connectionChecker;
+    /** Array of connections sorted by y position in workspace units. */
+    private readonly connections;
+    /**
+     * @param connectionChecker The workspace's connection type checker, used to
+     *     decide if connections are valid during a drag.
+     */
+    constructor(connectionChecker: IConnectionChecker);
+    /**
+     * Add a connection to the database. Should not already exist in the database.
+     *
+     * @param connection The connection to be added.
+     * @param yPos The y position used to decide where to insert the connection.
+     * @internal
+     */
+    addConnection(connection: RenderedConnection, yPos: number): void;
+    /**
+     * Finds the index of the given connection.
+     *
+     * Starts by doing a binary search to find the approximate location, then
+     * linearly searches nearby for the exact connection.
+     *
+     * @param conn The connection to find.
+     * @param yPos The y position used to find the index of the connection.
+     * @returns The index of the connection, or -1 if the connection was not
+     *     found.
+     */
+    private findIndexOfConnection;
+    /**
+     * Finds the correct index for the given y position.
+     *
+     * @param yPos The y position used to decide where to insert the connection.
+     * @returns The candidate index.
+     */
+    private calculateIndexForYPos;
+    /**
+     * Remove a connection from the database.  Must already exist in DB.
+     *
+     * @param connection The connection to be removed.
+     * @param yPos The y position used to find the index of the connection.
+     * @throws {Error} If the connection cannot be found in the database.
+     */
+    removeConnection(connection: RenderedConnection, yPos: number): void;
+    /**
+     * Find all nearby connections to the given connection.
+     * Type checking does not apply, since this function is used for bumping.
+     *
+     * @param connection The connection whose neighbours should be returned.
+     * @param maxRadius The maximum radius to another connection.
+     * @returns List of connections.
+     */
+    getNeighbours(connection: RenderedConnection, maxRadius: number): RenderedConnection[];
+    /**
+     * Is the candidate connection close to the reference connection.
+     * Extremely fast; only looks at Y distance.
+     *
+     * @param index Index in database of candidate connection.
+     * @param baseY Reference connection's Y value.
+     * @param maxRadius The maximum radius to another connection.
+     * @returns True if connection is in range.
+     */
+    private isInYRange;
+    /**
+     * Find the closest compatible connection to this connection.
+     *
+     * @param conn The connection searching for a compatible mate.
+     * @param maxRadius The maximum radius to another connection.
+     * @param dxy Offset between this connection's location in the database and
+     *     the current location (as a result of dragging).
+     * @returns Contains two properties: 'connection' which is either another
+     *     connection or null, and 'radius' which is the distance.
+     */
+    searchForClosest(conn: RenderedConnection, maxRadius: number, dxy: Coordinate): {
+        connection: RenderedConnection | null;
+        radius: number;
+    };
+    /**
+     * Initialize a set of connection DBs for a workspace.
+     *
+     * @param checker The workspace's connection checker, used to decide if
+     *     connections are valid during a drag.
+     * @returns Array of databases.
+     */
+    static init(checker: IConnectionChecker): ConnectionDB[];
+}
+//# sourceMappingURL=connection_db.d.ts.map

package/core/connection_type.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Enum for the type of a connection or input.
+ */
+export declare enum ConnectionType {
+    INPUT_VALUE = 1,
+    OUTPUT_VALUE = 2,
+    NEXT_STATEMENT = 3,
+    PREVIOUS_STATEMENT = 4
+}
+//# sourceMappingURL=connection_type.d.ts.map

package/core/constants.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @license
+ * Copyright 2016 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * The language-neutral ID given to the collapsed input.
+ */
+export declare const COLLAPSED_INPUT_NAME = "_TEMP_COLLAPSED_INPUT";
+/**
+ * The language-neutral ID given to the collapsed field.
+ */
+export declare const COLLAPSED_FIELD_NAME = "_TEMP_COLLAPSED_FIELD";
+/**
+ * The language-neutral ID for when the reason why a block is disabled is
+ * because the user manually disabled it, such as via the context menu.
+ */
+export declare const MANUALLY_DISABLED = "MANUALLY_DISABLED";
+//# sourceMappingURL=constants.d.ts.map

package/core/contextmenu.d.ts

@@ -0,0 +1,58 @@
+/**
+ * @license
+ * Copyright 2011 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { Block } from './block.js';
+import type { BlockSvg } from './block_svg.js';
+import type { ContextMenuOption, LegacyContextMenuOption } from './contextmenu_registry.js';
+import { Menu } from './menu.js';
+import * as serializationBlocks from './serialization/blocks.js';
+import { Coordinate } from './utils/coordinate.js';
+import type { WorkspaceSvg } from './workspace_svg.js';
+/**
+ * Gets the block the context menu is currently attached to.
+ * It is not recommended that you use this function; instead,
+ * use the scope object passed to the context menu callback.
+ *
+ * @returns The block the context menu is attached to.
+ */
+export declare function getCurrentBlock(): Block | null;
+/**
+ * Sets the block the context menu is currently attached to.
+ *
+ * @param block The block the context menu is attached to.
+ */
+export declare function setCurrentBlock(block: Block | null): void;
+/**
+ * Construct the menu based on the list of options and show the menu.
+ *
+ * @param menuOpenEvent Event that caused the menu to open.
+ * @param options Array of menu options.
+ * @param rtl True if RTL, false if LTR.
+ * @param workspace The workspace associated with the context menu, if any.
+ * @param location The screen coordinates at which to show the menu.
+ */
+export declare function show(menuOpenEvent: Event, options: (ContextMenuOption | LegacyContextMenuOption)[], rtl: boolean, workspace?: WorkspaceSvg, location?: Coordinate): void;
+/**
+ * Hide the context menu.
+ */
+export declare function hide(): void;
+/**
+ * Dispose of the menu.
+ */
+export declare function dispose(): void;
+/**
+ * Create a callback function that creates and configures a block,
+ *   then places the new block next to the original and returns it.
+ *
+ * @param block Original block.
+ * @param state XML or JSON object representation of the new block.
+ * @returns Function that creates a block.
+ */
+export declare function callbackFactory(block: Block, state: Element | serializationBlocks.State): () => BlockSvg;
+/**
+ * Returns the contextual menu if it is currently being shown.
+ */
+export declare function getMenu(): Menu | null;
+//# sourceMappingURL=contextmenu.d.ts.map

package/core/contextmenu_items.d.ts

@@ -0,0 +1,73 @@
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Option to undo previous action.
+ */
+export declare function registerUndo(): void;
+/**
+ * Option to redo previous action.
+ */
+export declare function registerRedo(): void;
+/**
+ * Option to clean up blocks.
+ */
+export declare function registerCleanup(): void;
+/**
+ * Option to collapse all blocks.
+ */
+export declare function registerCollapse(): void;
+/**
+ * Option to expand all blocks.
+ */
+export declare function registerExpand(): void;
+/**
+ * Option to delete all blocks.
+ */
+export declare function registerDeleteAll(): void;
+/**
+ * Option to duplicate a block.
+ */
+export declare function registerDuplicate(): void;
+/**
+ * Option to add or remove block-level comment.
+ */
+export declare function registerComment(): void;
+/**
+ * Option to inline variables.
+ */
+export declare function registerInline(): void;
+/**
+ * Option to collapse or expand a block.
+ */
+export declare function registerCollapseExpandBlock(): void;
+/**
+ * Option to disable or enable a block.
+ */
+export declare function registerDisable(): void;
+/**
+ * Option to delete a block.
+ */
+export declare function registerDelete(): void;
+/**
+ * Option to open help for a block.
+ */
+export declare function registerHelp(): void;
+/** Registers an option for deleting a workspace comment. */
+export declare function registerCommentDelete(): void;
+/** Registers an option for duplicating a workspace comment. */
+export declare function registerCommentDuplicate(): void;
+/** Registers an option for adding a workspace comment to the workspace. */
+export declare function registerCommentCreate(): void;
+/** Registers all workspace comment related menu items. */
+export declare function registerCommentOptions(): void;
+/**
+ * Registers all default context menu items. This should be called once per
+ * instance of ContextMenuRegistry.
+ *
+ * @internal
+ */
+export declare function registerDefaultOptions(): void;
+//# sourceMappingURL=contextmenu_items.d.ts.map