blockly 8.0.5 → 9.0.0-beta.0

package/core/interfaces/{i_movable.js → i_movable.ts}

@@ -8,26 +8,22 @@
  * @fileoverview The interface for an object that is movable.
  */
 
-'use strict';
-
 /**
  * The interface for an object that is movable.
  * @namespace Blockly.IMovable
  */
-goog.module('Blockly.IMovable');
+import * as goog from '../../closure/goog/goog.js';
+goog.declareModuleId('Blockly.IMovable');
 
 
 /**
  * The interface for an object that is movable.
- * @interface
  * @alias Blockly.IMovable
  */
-const IMovable = function() {};
-
-/**
- * Get whether this is movable or not.
- * @return {boolean} True if movable.
- */
-IMovable.prototype.isMovable;
-
-exports.IMovable = IMovable;
+export interface IMovable {
+  /**
+   * Get whether this is movable or not.
+   * @return True if movable.
+   */
+  isMovable(): boolean;
+}

package/core/interfaces/i_positionable.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { Rect } from '../utils/rect.js';
+import type { UiMetrics } from '../metrics_manager.js';
+import type { IComponent } from './i_component.js';
+/**
+ * Interface for a component that is positioned on top of the workspace.
+ * @alias Blockly.IPositionable
+ */
+export interface IPositionable extends IComponent {
+    /**
+     * Positions the element. Called when the window is resized.
+     * @param metrics The workspace metrics.
+     * @param savedPositions List of rectangles that are already on the workspace.
+     */
+    position(metrics: UiMetrics, savedPositions: Rect[]): void;
+    /**
+     * Returns the bounding rectangle of the UI element in pixel units relative to
+     * the Blockly injection div.
+     * @return The UI elements's bounding box. Null if bounding box should be
+     *     ignored by other UI elements.
+     */
+    getBoundingRectangle(): Rect | null;
+}

package/core/interfaces/i_positionable.ts

@@ -0,0 +1,50 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * @fileoverview The interface for a positionable UI element.
+ */
+
+/**
+ * The interface for a positionable UI element.
+ * @namespace Blockly.IPositionable
+ */
+import * as goog from '../../closure/goog/goog.js';
+import type {Rect} from '../utils/rect.js';
+import type {UiMetrics} from '../metrics_manager.js';
+goog.declareModuleId('Blockly.IPositionable');
+
+/* eslint-disable-next-line no-unused-vars */
+/* eslint-disable-next-line no-unused-vars */
+// Unused import preserved for side-effects. Remove if unneeded.
+// import '../metrics_manager.js';
+/* eslint-disable-next-line no-unused-vars */
+// Unused import preserved for side-effects. Remove if unneeded.
+// import '../utils/rect.js';
+
+import type {IComponent} from './i_component.js';
+
+
+/**
+ * Interface for a component that is positioned on top of the workspace.
+ * @alias Blockly.IPositionable
+ */
+export interface IPositionable extends IComponent {
+  /**
+   * Positions the element. Called when the window is resized.
+   * @param metrics The workspace metrics.
+   * @param savedPositions List of rectangles that are already on the workspace.
+   */
+  position(metrics: UiMetrics, savedPositions: Rect[]): void;
+
+  /**
+   * Returns the bounding rectangle of the UI element in pixel units relative to
+   * the Blockly injection div.
+   * @return The UI elements's bounding box. Null if bounding box should be
+   *     ignored by other UI elements.
+   */
+  getBoundingRectangle(): Rect|null;
+}

package/core/interfaces/i_registrable.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * The interface for a Blockly component that can be registered.
+ * @alias Blockly.IRegistrable
+ */
+export interface IRegistrable {
+}

package/core/interfaces/{i_registrable.js → i_registrable.ts}

@@ -9,21 +9,17 @@
  *    (Ex. Toolbox, Fields, Renderers)
  */
 
-'use strict';
-
 /**
  * The interface for a Blockly component that can be registered.
  *    (Ex. Toolbox, Fields, Renderers)
  * @namespace Blockly.IRegistrable
  */
-goog.module('Blockly.IRegistrable');
+import * as goog from '../../closure/goog/goog.js';
+goog.declareModuleId('Blockly.IRegistrable');
 
 
 /**
  * The interface for a Blockly component that can be registered.
- * @interface
  * @alias Blockly.IRegistrable
  */
-const IRegistrable = function() {};
-
-exports.IRegistrable = IRegistrable;
+export interface IRegistrable {}

package/core/interfaces/i_registrable_field.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { Field } from '../field.js';
+declare type fromJson = (p1: object) => Field;
+/**
+ * A registrable field.
+ * Note: We are not using an interface here as we are interested in defining the
+ * static methods of a field rather than the instance methods.
+ * @alias Blockly.IRegistrableField
+ */
+export interface IRegistrableField {
+    fromJson: fromJson;
+}
+export {};

package/core/interfaces/{i_registrable_field.js → i_registrable_field.ts}

@@ -8,32 +8,24 @@
  * @fileoverview The interface for a Blockly field that can be registered.
  */
 
-'use strict';
-
 /**
  * The interface for a Blockly field that can be registered.
  * @namespace Blockly.IRegistrableField
  */
-goog.module('Blockly.IRegistrableField');
+import * as goog from '../../closure/goog/goog.js';
+goog.declareModuleId('Blockly.IRegistrableField');
+
+import type {Field} from '../field.js';
 
-/* eslint-disable-next-line no-unused-vars */
-const {Field} = goog.requireType('Blockly.Field');
 
+type fromJson = (p1: object) => Field;
 
 /**
  * A registrable field.
  * Note: We are not using an interface here as we are interested in defining the
  * static methods of a field rather than the instance methods.
- * @typedef {{
- *     fromJson:IRegistrableField.fromJson
- * }}
  * @alias Blockly.IRegistrableField
  */
-const IRegistrableField = {};
-
-/**
- * @typedef {function(!Object): Field}
- */
-IRegistrableField.fromJson;
-
-exports.IRegistrableField = IRegistrableField;
+export interface IRegistrableField {
+  fromJson: fromJson;
+}

package/core/interfaces/i_selectable.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @license
+ * Copyright 2019 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { IDeletable } from './i_deletable.js';
+import type { IMovable } from './i_movable.js';
+/**
+ * The interface for an object that is selectable.
+ * @alias Blockly.ISelectable
+ */
+export interface ISelectable extends IDeletable, IMovable {
+    id: string;
+    /** Select this.  Highlight it visually. */
+    select(): void;
+    /** Unselect this.  Unhighlight it visually. */
+    unselect(): void;
+}

package/core/interfaces/i_selectable.ts

@@ -0,0 +1,34 @@
+/**
+ * @license
+ * Copyright 2019 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * @fileoverview The interface for an object that is selectable.
+ */
+
+/**
+ * The interface for an object that is selectable.
+ * @namespace Blockly.ISelectable
+ */
+import * as goog from '../../closure/goog/goog.js';
+goog.declareModuleId('Blockly.ISelectable');
+
+import type {IDeletable} from './i_deletable.js';
+import type {IMovable} from './i_movable.js';
+
+
+/**
+ * The interface for an object that is selectable.
+ * @alias Blockly.ISelectable
+ */
+export interface ISelectable extends IDeletable, IMovable {
+  id: string;
+
+  /** Select this.  Highlight it visually. */
+  select(): void;
+
+  /** Unselect this.  Unhighlight it visually. */
+  unselect(): void;
+}

package/core/interfaces/i_selectable_toolbox_item.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { FlyoutItemInfoArray } from '../utils/toolbox';
+import type { IToolboxItem } from './i_toolbox_item.js';
+/**
+ * Interface for an item in the toolbox that can be selected.
+ * @alias Blockly.ISelectableToolboxItem
+ */
+export interface ISelectableToolboxItem extends IToolboxItem {
+    /**
+     * Gets the name of the toolbox item. Used for emitting events.
+     * @return The name of the toolbox item.
+     */
+    getName(): string;
+    /**
+     * Gets the contents of the toolbox item. These are items that are meant to be
+     * displayed in the flyout.
+     * @return The definition of items to be displayed in the flyout.
+     */
+    getContents(): FlyoutItemInfoArray | string;
+    /**
+     * Sets the current toolbox item as selected.
+     * @param _isSelected True if this category is selected, false otherwise.
+     */
+    setSelected(_isSelected: boolean): void;
+    /**
+     * Gets the HTML element that is clickable.
+     * The parent toolbox element receives clicks. The parent toolbox will add an
+     * ID to this element so it can pass the onClick event to the correct
+     * toolboxItem.
+     * @return The HTML element that receives clicks.
+     */
+    getClickTarget(): Element;
+    /**
+     * Handles when the toolbox item is clicked.
+     * @param _e Click event to handle.
+     */
+    onClick(_e: Event): void;
+}

package/core/interfaces/i_selectable_toolbox_item.ts

@@ -0,0 +1,64 @@
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * @fileoverview The interface for a selectable toolbox item.
+ */
+
+/**
+ * The interface for a selectable toolbox item.
+ * @namespace Blockly.ISelectableToolboxItem
+ */
+import * as goog from '../../closure/goog/goog.js';
+import type {FlyoutItemInfoArray} from '../utils/toolbox';
+goog.declareModuleId('Blockly.ISelectableToolboxItem');
+
+/* eslint-disable-next-line no-unused-vars */
+// Unused import preserved for side-effects. Remove if unneeded.
+// import '../utils/toolbox.js';
+
+import type {IToolboxItem} from './i_toolbox_item.js';
+
+
+/**
+ * Interface for an item in the toolbox that can be selected.
+ * @alias Blockly.ISelectableToolboxItem
+ */
+export interface ISelectableToolboxItem extends IToolboxItem {
+  /**
+   * Gets the name of the toolbox item. Used for emitting events.
+   * @return The name of the toolbox item.
+   */
+  getName(): string;
+
+  /**
+   * Gets the contents of the toolbox item. These are items that are meant to be
+   * displayed in the flyout.
+   * @return The definition of items to be displayed in the flyout.
+   */
+  getContents(): FlyoutItemInfoArray|string;
+
+  /**
+   * Sets the current toolbox item as selected.
+   * @param _isSelected True if this category is selected, false otherwise.
+   */
+  setSelected(_isSelected: boolean): void;
+
+  /**
+   * Gets the HTML element that is clickable.
+   * The parent toolbox element receives clicks. The parent toolbox will add an
+   * ID to this element so it can pass the onClick event to the correct
+   * toolboxItem.
+   * @return The HTML element that receives clicks.
+   */
+  getClickTarget(): Element;
+
+  /**
+   * Handles when the toolbox item is clicked.
+   * @param _e Click event to handle.
+   */
+  onClick(_e: Event): void;
+}

package/core/interfaces/i_serializer.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { Workspace } from '../workspace.js';
+/**
+ * Serializes and deserializes a plugin or system.
+ * @alias Blockly.serialization.ISerializer.ISerializer
+ */
+export interface ISerializer {
+    /**
+     * A priority value used to determine the order of deserializing state.
+     * More positive priorities are deserialized before less positive
+     * priorities. Eg if you have priorities (0, -10, 10, 100) the order of
+     * deserialiation will be (100, 10, 0, -10).
+     * If two serializers have the same priority, they are deserialized in an
+     * arbitrary order relative to each other.
+     */
+    priority: number;
+    /**
+     * Saves the state of the plugin or system.
+     * @param workspace The workspace the system to serialize is associated with.
+     * @return A JS object containing the system's state, or null if there is no
+     *     state to record.
+     */
+    save(workspace: Workspace): Object | null;
+    /**
+     * Loads the state of the plugin or system.
+     * @param state The state of the system to deserialize. This will always be
+     *     non-null.
+     * @param workspace The workspace the system to deserialize is associated
+     *     with.
+     */
+    load(state: Object, workspace: Workspace): void;
+    /**
+     * Clears the state of the plugin or system.
+     * @param workspace The workspace the system to clear the state of is
+     *     associated with.
+     */
+    clear(workspace: Workspace): void;
+}

package/core/interfaces/i_serializer.ts

@@ -0,0 +1,65 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * @fileoverview The record type for an object containing functions for
+ * serializing part of the workspace.
+ */
+
+/**
+ * The record type for an object containing functions for
+ *     serializing part of the workspace.
+ * @namespace Blockly.serialization.ISerializer
+ */
+import * as goog from '../../closure/goog/goog.js';
+goog.declareModuleId('Blockly.serialization.ISerializer');
+
+import type {Workspace} from '../workspace.js';
+
+
+/**
+ * Serializes and deserializes a plugin or system.
+ * @alias Blockly.serialization.ISerializer.ISerializer
+ */
+export interface ISerializer {
+  /**
+   * A priority value used to determine the order of deserializing state.
+   * More positive priorities are deserialized before less positive
+   * priorities. Eg if you have priorities (0, -10, 10, 100) the order of
+   * deserialiation will be (100, 10, 0, -10).
+   * If two serializers have the same priority, they are deserialized in an
+   * arbitrary order relative to each other.
+   */
+  priority: number;
+
+  /* eslint-disable no-unused-vars, valid-jsdoc */
+
+  /**
+   * Saves the state of the plugin or system.
+   * @param workspace The workspace the system to serialize is associated with.
+   * @return A JS object containing the system's state, or null if there is no
+   *     state to record.
+   */
+  save(workspace: Workspace): Object|null;
+  /* eslint-enable valid-jsdoc */
+
+  /**
+   * Loads the state of the plugin or system.
+   * @param state The state of the system to deserialize. This will always be
+   *     non-null.
+   * @param workspace The workspace the system to deserialize is associated
+   *     with.
+   */
+  load(state: Object, workspace: Workspace): void;
+
+  /**
+   * Clears the state of the plugin or system.
+   * @param workspace The workspace the system to clear the state of is
+   *     associated with.
+   */
+  clear(workspace: Workspace): void;
+}
+/* eslint-enable no-unused-vars */

package/core/interfaces/i_styleable.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Interface for an object that a style can be added to.
+ * @alias Blockly.IStyleable
+ */
+export interface IStyleable {
+    /**
+     * Adds a style on the toolbox. Usually used to change the cursor.
+     * @param style The name of the class to add.
+     */
+    addStyle(style: string): void;
+    /**
+     * Removes a style from the toolbox. Usually used to change the cursor.
+     * @param style The name of the class to remove.
+     */
+    removeStyle(style: string): void;
+}

package/core/interfaces/i_styleable.ts

@@ -0,0 +1,35 @@
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * @fileoverview The interface for an object that a style can be added to.
+ */
+
+/**
+ * The interface for an object that a style can be added to.
+ * @namespace Blockly.IStyleable
+ */
+import * as goog from '../../closure/goog/goog.js';
+goog.declareModuleId('Blockly.IStyleable');
+
+
+/**
+ * Interface for an object that a style can be added to.
+ * @alias Blockly.IStyleable
+ */
+export interface IStyleable {
+  /**
+   * Adds a style on the toolbox. Usually used to change the cursor.
+   * @param style The name of the class to add.
+   */
+  addStyle(style: string): void;
+
+  /**
+   * Removes a style from the toolbox. Usually used to change the cursor.
+   * @param style The name of the class to remove.
+   */
+  removeStyle(style: string): void;
+}

package/core/interfaces/i_toolbox.d.ts

@@ -0,0 +1,85 @@
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+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;
+}