blockly 8.0.5 → 9.0.0-beta.0

package/core/interfaces/i_toolbox.ts

@@ -0,0 +1,127 @@
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * @fileoverview The interface for a toolbox.
+ */
+
+/**
+ * The interface for a toolbox.
+ * @namespace Blockly.IToolbox
+ */
+import * as goog from '../../closure/goog/goog.js';
+goog.declareModuleId('Blockly.IToolbox');
+
+/* eslint-disable-next-line no-unused-vars */
+// Unused import preserved for side-effects. Remove if unneeded.
+// import '../utils/toolbox.js';
+/* eslint-disable-next-line no-unused-vars */
+// Unused import preserved for side-effects. Remove if unneeded.
+// import './i_flyout.js';
+/* eslint-disable-next-line no-unused-vars */
+// Unused import preserved for side-effects. Remove if unneeded.
+// import './i_toolbox_item.js';
+/* eslint-disable-next-line no-unused-vars */
+// Unused import preserved for side-effects. Remove if unneeded.
+// import '../workspace_svg.js';
+
+import type {IRegistrable} from './i_registrable.js';
+import type {IToolboxItem} from './i_toolbox_item.js';
+import type {ToolboxInfo} from '../utils/toolbox.js';
+import type {IFlyout} from './i_flyout.js';
+import type {WorkspaceSvg} from '../workspace_svg.js';
+
+
+/**
+ * Interface for a toolbox.
+ * @alias Blockly.IToolbox
+ */
+export interface IToolbox extends IRegistrable {
+  /** Initializes the toolbox. */
+  init(): void;
+
+  /**
+   * Fills the toolbox with new toolbox items and removes any old contents.
+   * @param toolboxDef Object holding information for creating a toolbox.
+   */
+  render(toolboxDef: ToolboxInfo): void;
+
+  /**
+   * Gets the width of the toolbox.
+   * @return The width of the toolbox.
+   */
+  getWidth(): number;
+
+  /**
+   * Gets the height of the toolbox.
+   * @return The height of the toolbox.
+   */
+  getHeight(): number;
+
+  /**
+   * Gets the toolbox flyout.
+   * @return The toolbox flyout.
+   */
+  getFlyout(): IFlyout|null;
+
+  /**
+   * Gets the workspace for the toolbox.
+   * @return The parent workspace for the toolbox.
+   */
+  getWorkspace(): WorkspaceSvg;
+
+  /**
+   * Gets whether or not the toolbox is horizontal.
+   * @return True if the toolbox is horizontal, false if the toolbox is
+   *     vertical.
+   */
+  isHorizontal(): boolean;
+
+  /**
+   * Positions the toolbox based on whether it is a horizontal toolbox and
+   * whether the workspace is in rtl.
+   */
+  position(): void;
+
+  /** Handles resizing the toolbox when a toolbox item resizes. */
+  handleToolboxItemResize(): void;
+
+  /** Unhighlights any previously selected item. */
+  clearSelection(): void;
+
+  /**
+   * Updates the category colours and background colour of selected categories.
+   */
+  refreshTheme(): void;
+
+  /**
+   * Updates the flyout's content without closing it.  Should be used in
+   * response to a change in one of the dynamic categories, such as variables or
+   * procedures.
+   */
+  refreshSelection(): void;
+
+  /**
+   * Sets the visibility of the toolbox.
+   * @param isVisible True if toolbox should be visible.
+   */
+  setVisible(isVisible: boolean): void;
+
+  /**
+   * Selects the toolbox item by it's position in the list of toolbox items.
+   * @param position The position of the item to select.
+   */
+  selectItemByPosition(position: number): void;
+
+  /**
+   * Gets the selected item.
+   * @return The selected item, or null if no item is currently selected.
+   */
+  getSelectedItem(): IToolboxItem|null;
+
+  /** Disposes of this toolbox. */
+  dispose(): void;
+}

package/core/interfaces/i_toolbox_item.d.ts

@@ -0,0 +1,62 @@
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Interface for an item in the toolbox.
+ * @alias Blockly.IToolboxItem
+ */
+export interface IToolboxItem {
+    /**
+     * Initializes the toolbox item.
+     * This includes creating the DOM and updating the state of any items based
+     * on the info object.
+     */
+    init(): void;
+    /**
+     * Gets the div for the toolbox item.
+     * @return The div for the toolbox item.
+     */
+    getDiv(): Element | null;
+    /**
+     * Gets a unique identifier for this toolbox item.
+     * @return The ID for the toolbox item.
+     */
+    getId(): string;
+    /**
+     * Gets the parent if the toolbox item is nested.
+     * @return The parent toolbox item, or null if this toolbox item is not
+     *     nested.
+     */
+    getParent(): IToolboxItem | null;
+    /**
+     * Gets the nested level of the category.
+     * @return The nested level of the category.
+     * @internal
+     */
+    getLevel(): number;
+    /**
+     * Whether the toolbox item is selectable.
+     * @return True if the toolbox item can be selected.
+     */
+    isSelectable(): boolean;
+    /**
+     * Whether the toolbox item is collapsible.
+     * @return True if the toolbox item is collapsible.
+     */
+    isCollapsible(): boolean;
+    /** Dispose of this toolbox item. No-op by default. */
+    dispose(): void;
+    /**
+     * Gets the HTML element that is clickable.
+     * @return The HTML element that receives clicks.
+     */
+    getClickTarget(): Element | null;
+    /**
+     * Sets whether the category is visible or not.
+     * For a category to be visible its parent category must also be expanded.
+     * @param isVisible True if category should be visible.
+     */
+    setVisible_(isVisible: boolean): void;
+}

package/core/interfaces/i_toolbox_item.ts

@@ -0,0 +1,84 @@
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * @fileoverview The interface for a toolbox item.
+ */
+
+/**
+ * The interface for a toolbox item.
+ * @namespace Blockly.IToolboxItem
+ */
+import * as goog from '../../closure/goog/goog.js';
+goog.declareModuleId('Blockly.IToolboxItem');
+
+
+/**
+ * Interface for an item in the toolbox.
+ * @alias Blockly.IToolboxItem
+ */
+export interface IToolboxItem {
+  /**
+   * Initializes the toolbox item.
+   * This includes creating the DOM and updating the state of any items based
+   * on the info object.
+   */
+  init(): void;
+
+  /**
+   * Gets the div for the toolbox item.
+   * @return The div for the toolbox item.
+   */
+  getDiv(): Element|null;
+
+  /**
+   * Gets a unique identifier for this toolbox item.
+   * @return The ID for the toolbox item.
+   */
+  getId(): string;
+
+  /**
+   * Gets the parent if the toolbox item is nested.
+   * @return The parent toolbox item, or null if this toolbox item is not
+   *     nested.
+   */
+  getParent(): IToolboxItem|null;
+
+  /**
+   * Gets the nested level of the category.
+   * @return The nested level of the category.
+   * @internal
+   */
+  getLevel(): number;
+
+  /**
+   * Whether the toolbox item is selectable.
+   * @return True if the toolbox item can be selected.
+   */
+  isSelectable(): boolean;
+
+  /**
+   * Whether the toolbox item is collapsible.
+   * @return True if the toolbox item is collapsible.
+   */
+  isCollapsible(): boolean;
+
+  /** Dispose of this toolbox item. No-op by default. */
+  dispose(): void;
+
+  /**
+   * Gets the HTML element that is clickable.
+   * @return The HTML element that receives clicks.
+   */
+  getClickTarget(): Element|null;
+
+  /**
+   * Sets whether the category is visible or not.
+   * For a category to be visible its parent category must also be expanded.
+   * @param isVisible True if category should be visible.
+   */
+  setVisible_(isVisible: boolean): void;
+}

package/core/internal_constants.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Number of characters to truncate a collapsed block to.
+ * @alias Blockly.internalConstants.COLLAPSE_CHARS
+ * @internal
+ */
+export declare const COLLAPSE_CHARS = 30;
+/**
+ * When dragging a block out of a stack, split the stack in two (true), or drag
+ * out the block healing the stack (false).
+ * @alias Blockly.internalConstants.DRAG_STACK
+ * @internal
+ */
+export declare const DRAG_STACK = true;
+/**
+ * Lookup table for determining the opposite type of a connection.
+ * @alias Blockly.internalConstants.OPPOSITE_TYPE
+ * @internal
+ */
+export declare const OPPOSITE_TYPE: number[];
+/**
+ * String for use in the dropdown created in field_variable.
+ * This string indicates that this option in the dropdown is 'Rename
+ * variable...' and if selected, should trigger the prompt to rename a variable.
+ * @alias Blockly.internalConstants.RENAME_VARIABLE_ID
+ * @internal
+ */
+export declare const RENAME_VARIABLE_ID = "RENAME_VARIABLE_ID";
+/**
+ * String for use in the dropdown created in field_variable.
+ * This string indicates that this option in the dropdown is 'Delete the "%1"
+ * variable' and if selected, should trigger the prompt to delete a variable.
+ * @alias Blockly.internalConstants.DELETE_VARIABLE_ID
+ * @internal
+ */
+export declare const DELETE_VARIABLE_ID = "DELETE_VARIABLE_ID";

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

@@ -7,41 +7,40 @@
 /**
  * @fileoverview Module that provides constants for use inside Blockly. Do not
  * use these constants outside of the core library.
- * @package
  */
-'use strict';
 
 /**
  * Module that provides constants for use inside Blockly. Do not
  * use these constants outside of the core library.
  * @namespace Blockly.internalConstants
  */
-goog.module('Blockly.internalConstants');
+import * as goog from '../closure/goog/goog.js';
+goog.declareModuleId('Blockly.internalConstants');
 
-const {ConnectionType} = goog.require('Blockly.ConnectionType');
+import {ConnectionType} from './connection_type.js';
 
 
 /**
  * Number of characters to truncate a collapsed block to.
  * @alias Blockly.internalConstants.COLLAPSE_CHARS
+ * @internal
  */
-const COLLAPSE_CHARS = 30;
-exports.COLLAPSE_CHARS = COLLAPSE_CHARS;
+export const COLLAPSE_CHARS = 30;
 
 /**
  * When dragging a block out of a stack, split the stack in two (true), or drag
  * out the block healing the stack (false).
  * @alias Blockly.internalConstants.DRAG_STACK
+ * @internal
  */
-const DRAG_STACK = true;
-exports.DRAG_STACK = DRAG_STACK;
+export const DRAG_STACK = true;
 
 /**
  * Lookup table for determining the opposite type of a connection.
- * @const
  * @alias Blockly.internalConstants.OPPOSITE_TYPE
+ * @internal
  */
-const OPPOSITE_TYPE = [];
+export const OPPOSITE_TYPE: number[] = [];
 OPPOSITE_TYPE[ConnectionType.INPUT_VALUE] = ConnectionType.OUTPUT_VALUE;
 OPPOSITE_TYPE[ConnectionType.OUTPUT_VALUE] = ConnectionType.INPUT_VALUE;
 OPPOSITE_TYPE[ConnectionType.NEXT_STATEMENT] =
@@ -49,24 +48,20 @@ OPPOSITE_TYPE[ConnectionType.NEXT_STATEMENT] =
 OPPOSITE_TYPE[ConnectionType.PREVIOUS_STATEMENT] =
     ConnectionType.NEXT_STATEMENT;
 
-exports.OPPOSITE_TYPE = OPPOSITE_TYPE;
-
 /**
  * String for use in the dropdown created in field_variable.
  * This string indicates that this option in the dropdown is 'Rename
  * variable...' and if selected, should trigger the prompt to rename a variable.
- * @const {string}
  * @alias Blockly.internalConstants.RENAME_VARIABLE_ID
+ * @internal
  */
-const RENAME_VARIABLE_ID = 'RENAME_VARIABLE_ID';
-exports.RENAME_VARIABLE_ID = RENAME_VARIABLE_ID;
+export const RENAME_VARIABLE_ID = 'RENAME_VARIABLE_ID';
 
 /**
  * String for use in the dropdown created in field_variable.
  * This string indicates that this option in the dropdown is 'Delete the "%1"
  * variable' and if selected, should trigger the prompt to delete a variable.
- * @const {string}
  * @alias Blockly.internalConstants.DELETE_VARIABLE_ID
+ * @internal
  */
-const DELETE_VARIABLE_ID = 'DELETE_VARIABLE_ID';
-exports.DELETE_VARIABLE_ID = DELETE_VARIABLE_ID;
+export const DELETE_VARIABLE_ID = 'DELETE_VARIABLE_ID';

package/core/keyboard_nav/ast_node.d.ts

@@ -0,0 +1,239 @@
+/**
+ * @license
+ * Copyright 2019 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { Block } from '../block.js';
+import type { Connection } from '../connection.js';
+import type { Field } from '../field.js';
+import type { Input } from '../input.js';
+import type { IASTNodeLocation } from '../interfaces/i_ast_node_location.js';
+import { Coordinate } from '../utils/coordinate.js';
+import type { Workspace } from '../workspace.js';
+/**
+ * Class for an AST node.
+ * It is recommended that you use one of the createNode methods instead of
+ * creating a node directly.
+ * @alias Blockly.ASTNode
+ */
+export declare class ASTNode {
+    /**
+     * True to navigate to all fields. False to only navigate to clickable fields.
+     */
+    static NAVIGATE_ALL_FIELDS: boolean;
+    /**
+     * The default y offset to use when moving the cursor from a stack to the
+     * workspace.
+     */
+    private static readonly DEFAULT_OFFSET_Y;
+    private readonly type_;
+    private readonly isConnection_;
+    private readonly location_;
+    /** The coordinate on the workspace. */
+    private wsCoordinate_;
+    /**
+     * @param type The type of the location.
+     *     Must be in ASTNode.types.
+     * @param location The position in the AST.
+     * @param opt_params Optional dictionary of options.
+     * @alias Blockly.ASTNode
+     */
+    constructor(type: string, location: IASTNodeLocation, opt_params?: Params);
+    /**
+     * Parse the optional parameters.
+     * @param params The user specified parameters.
+     */
+    private processParams_;
+    /**
+     * Gets the value pointed to by this node.
+     * It is the callers responsibility to check the node type to figure out what
+     * type of object they get back from this.
+     * @return The current field, connection, workspace, or block the cursor is
+     *     on.
+     */
+    getLocation(): IASTNodeLocation;
+    /**
+     * The type of the current location.
+     * One of ASTNode.types
+     * @return The type of the location.
+     */
+    getType(): string;
+    /**
+     * The coordinate on the workspace.
+     * @return The workspace coordinate or null if the location is not a
+     *     workspace.
+     */
+    getWsCoordinate(): Coordinate;
+    /**
+     * Whether the node points to a connection.
+     * @return [description]
+     * @internal
+     */
+    isConnection(): boolean;
+    /**
+     * Given an input find the next editable field or an input with a non null
+     * connection in the same block. The current location must be an input
+     * connection.
+     * @return The AST node holding the next field or connection or null if there
+     *     is no editable field or input connection after the given input.
+     */
+    private findNextForInput_;
+    /**
+     * Given a field find the next editable field or an input with a non null
+     * connection in the same block. The current location must be a field.
+     * @return The AST node pointing to the next field or connection or null if
+     *     there is no editable field or input connection after the given input.
+     */
+    private findNextForField_;
+    /**
+     * Given an input find the previous editable field or an input with a non null
+     * connection in the same block. The current location must be an input
+     * connection.
+     * @return The AST node holding the previous field or connection.
+     */
+    private findPrevForInput_;
+    /**
+     * Given a field find the previous editable field or an input with a non null
+     * connection in the same block. The current location must be a field.
+     * @return The AST node holding the previous input or field.
+     */
+    private findPrevForField_;
+    /**
+     * Navigate between stacks of blocks on the workspace.
+     * @param forward True to go forward. False to go backwards.
+     * @return The first block of the next stack or null if there are no blocks on
+     *     the workspace.
+     */
+    private navigateBetweenStacks_;
+    /**
+     * Finds the top most AST node for a given block.
+     * This is either the previous connection, output connection or block
+     * depending on what kind of connections the block has.
+     * @param block The block that we want to find the top connection on.
+     * @return The AST node containing the top connection.
+     */
+    private findTopASTNodeForBlock_;
+    /**
+     * Get the AST node pointing to the input that the block is nested under or if
+     * the block is not nested then get the stack AST node.
+     * @param block The source block of the current location.
+     * @return The AST node pointing to the input connection or the top block of
+     *     the stack this block is in.
+     */
+    private getOutAstNodeForBlock_;
+    /**
+     * Find the first editable field or input with a connection on a given block.
+     * @param block The source block of the current location.
+     * @return An AST node pointing to the first field or input.
+     * Null if there are no editable fields or inputs with connections on the
+     * block.
+     */
+    private findFirstFieldOrInput_;
+    /**
+     * Finds the source block of the location of this node.
+     * @return The source block of the location, or null if the node is of type
+     *     workspace.
+     */
+    getSourceBlock(): Block | null;
+    /**
+     * Find the element to the right of the current element in the AST.
+     * @return An AST node that wraps the next field, connection, block, or
+     *     workspace. Or null if there is no node to the right.
+     */
+    next(): ASTNode | null;
+    /**
+     * Find the element one level below and all the way to the left of the current
+     * location.
+     * @return An AST node that wraps the next field, connection, workspace, or
+     *     block. Or null if there is nothing below this node.
+     */
+    in(): ASTNode | null;
+    /**
+     * Find the element to the left of the current element in the AST.
+     * @return An AST node that wraps the previous field, connection, workspace or
+     *     block. Or null if no node exists to the left.
+     * null.
+     */
+    prev(): ASTNode | null;
+    /**
+     * Find the next element that is one position above and all the way to the
+     * left of the current location.
+     * @return An AST node that wraps the next field, connection, workspace or
+     *     block. Or null if we are at the workspace level.
+     */
+    out(): ASTNode | null;
+    /**
+     * Whether an AST node of the given type points to a connection.
+     * @param type The type to check.  One of ASTNode.types.
+     * @return True if a node of the given type points to a connection.
+     */
+    private static isConnectionType_;
+    /**
+     * Create an AST node pointing to a field.
+     * @param field The location of the AST node.
+     * @return An AST node pointing to a field.
+     */
+    static createFieldNode(field: Field): ASTNode | null;
+    /**
+     * Creates an AST node pointing to a connection. If the connection has a
+     * parent input then create an AST node of type input that will hold the
+     * connection.
+     * @param connection This is the connection the node will point to.
+     * @return An AST node pointing to a connection.
+     */
+    static createConnectionNode(connection: Connection): ASTNode | null;
+    /**
+     * Creates an AST node pointing to an input. Stores the input connection as
+     * the location.
+     * @param input The input used to create an AST node.
+     * @return An AST node pointing to a input.
+     */
+    static createInputNode(input: Input): ASTNode | null;
+    /**
+     * Creates an AST node pointing to a block.
+     * @param block The block used to create an AST node.
+     * @return An AST node pointing to a block.
+     */
+    static createBlockNode(block: Block): ASTNode | null;
+    /**
+     * Create an AST node of type stack. A stack, represented by its top block, is
+     *     the set of all blocks connected to a top block, including the top
+     * block.
+     * @param topBlock A top block has no parent and can be found in the list
+     *     returned by workspace.getTopBlocks().
+     * @return An AST node of type stack that points to the top block on the
+     *     stack.
+     */
+    static createStackNode(topBlock: Block): ASTNode | null;
+    /**
+     * Creates an AST node pointing to a workspace.
+     * @param workspace The workspace that we are on.
+     * @param wsCoordinate The position on the workspace for this node.
+     * @return An AST node pointing to a workspace and a position on the
+     *     workspace.
+     */
+    static createWorkspaceNode(workspace: Workspace | null, wsCoordinate: Coordinate | null): ASTNode | null;
+    /**
+     * Creates an AST node for the top position on a block.
+     * This is either an output connection, previous connection, or block.
+     * @param block The block to find the top most AST node on.
+     * @return The AST node holding the top most position on the block.
+     */
+    static createTopNode(block: Block): ASTNode | null;
+}
+export declare namespace ASTNode {
+    interface Params {
+        wsCoordinate: Coordinate;
+    }
+    enum types {
+        FIELD = "field",
+        BLOCK = "block",
+        INPUT = "input",
+        OUTPUT = "output",
+        NEXT = "next",
+        PREVIOUS = "previous",
+        STACK = "stack",
+        WORKSPACE = "workspace"
+    }
+}
+export declare type Params = ASTNode.Params;