blockly 8.0.5 → 9.0.0-beta.0

package/core/serialization/exceptions.d.ts

@@ -0,0 +1,73 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { Block } from '../block.js';
+import type { State } from './blocks.js';
+/** @alias Blockly.serialization.exceptions.DeserializationError */
+export declare class DeserializationError extends Error {
+}
+/**
+ * Represents an error where the serialized state is expected to provide a
+ * block type, but it is not provided.
+ * @alias Blockly.serialization.exceptions.MissingBlockType
+ */
+export declare class MissingBlockType extends DeserializationError {
+    state: State;
+    /**
+     * @param state The state object which is missing the block type.
+     * @internal
+     */
+    constructor(state: State);
+}
+/**
+ * Represents an error where deserialization encountered a block that did
+ * not have a connection that was defined in the serialized state.
+ * @alias Blockly.serialization.exceptions.MissingConnection
+ */
+export declare class MissingConnection extends DeserializationError {
+    block: Block;
+    state: State;
+    /**
+     * @param connection The name of the connection that is missing. E.g.
+     *     'IF0', or 'next'.
+     * @param block The block missing the connection.
+     * @param state The state object containing the bad connection.
+     * @internal
+     */
+    constructor(connection: string, block: Block, state: State);
+}
+/**
+ * Represents an error where deserialization tried to connect two connections
+ * that were not compatible.
+ * @alias Blockly.serialization.exceptions.BadConnectionCheck
+ */
+export declare class BadConnectionCheck extends DeserializationError {
+    childBlock: Block;
+    childState: State;
+    /**
+     * @param reason The reason the connections were not compatible.
+     * @param childConnection The name of the incompatible child connection. E.g.
+     *     'output' or 'previous'.
+     * @param childBlock The child block that could not connect to its parent.
+     * @param childState The state object representing the child block.
+     * @internal
+     */
+    constructor(reason: string, childConnection: string, childBlock: Block, childState: State);
+}
+/**
+ * Represents an error where deserialization encountered a real block as it
+ * was deserializing children of a shadow.
+ * This is an error because it is an invariant of Blockly that shadow blocks
+ * do not have real children.
+ * @alias Blockly.serialization.exceptions.RealChildOfShadow
+ */
+export declare class RealChildOfShadow extends DeserializationError {
+    state: State;
+    /**
+     * @param state The state object representing the real block.
+     * @internal
+     */
+    constructor(state: State);
+}

package/core/serialization/exceptions.ts

@@ -0,0 +1,98 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * @fileoverview Contains custom errors thrown by the serialization system.
+ */
+
+/**
+ * Contains custom errors thrown by the serialization system.
+ * @namespace Blockly.serialization.exceptions
+ */
+import * as goog from '../../closure/goog/goog.js';
+goog.declareModuleId('Blockly.serialization.exceptions');
+
+import type {Block} from '../block.js';
+import type {State} from './blocks.js';
+
+
+/** @alias Blockly.serialization.exceptions.DeserializationError */
+export class DeserializationError extends Error {}
+
+/**
+ * Represents an error where the serialized state is expected to provide a
+ * block type, but it is not provided.
+ * @alias Blockly.serialization.exceptions.MissingBlockType
+ */
+export class MissingBlockType extends DeserializationError {
+  /**
+   * @param state The state object which is missing the block type.
+   * @internal
+   */
+  constructor(public state: State) {
+    super(`Expected to find a 'type' property, defining the block type`);
+  }
+}
+
+/**
+ * Represents an error where deserialization encountered a block that did
+ * not have a connection that was defined in the serialized state.
+ * @alias Blockly.serialization.exceptions.MissingConnection
+ */
+export class MissingConnection extends DeserializationError {
+  /**
+   * @param connection The name of the connection that is missing. E.g.
+   *     'IF0', or 'next'.
+   * @param block The block missing the connection.
+   * @param state The state object containing the bad connection.
+   * @internal
+   */
+  constructor(connection: string, public block: Block, public state: State) {
+    super(`The block ${block.toDevString()} is missing a(n) ${connection}
+connection`);
+  }
+}
+
+/**
+ * Represents an error where deserialization tried to connect two connections
+ * that were not compatible.
+ * @alias Blockly.serialization.exceptions.BadConnectionCheck
+ */
+export class BadConnectionCheck extends DeserializationError {
+  /**
+   * @param reason The reason the connections were not compatible.
+   * @param childConnection The name of the incompatible child connection. E.g.
+   *     'output' or 'previous'.
+   * @param childBlock The child block that could not connect to its parent.
+   * @param childState The state object representing the child block.
+   * @internal
+   */
+  constructor(
+      reason: string, childConnection: string, public childBlock: Block,
+      public childState: State) {
+    super(`The block ${childBlock.toDevString()} could not connect its
+${childConnection} to its parent, because: ${reason}`);
+  }
+}
+
+/**
+ * Represents an error where deserialization encountered a real block as it
+ * was deserializing children of a shadow.
+ * This is an error because it is an invariant of Blockly that shadow blocks
+ * do not have real children.
+ * @alias Blockly.serialization.exceptions.RealChildOfShadow
+ */
+export class RealChildOfShadow extends DeserializationError {
+  /**
+   * @param state The state object representing the real block.
+   * @internal
+   */
+  constructor(public state: State) {
+    super(`Encountered a real block which is defined as a child of a shadow
+block. It is an invariant of Blockly that shadow blocks only have shadow
+children`);
+  }
+}

package/core/serialization/priorities.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * The priority for deserializing variables.
+ * @alias Blockly.serialization.priorities.VARIABLES
+ */
+export declare const VARIABLES = 100;
+/**
+ * The priority for deserializing blocks.
+ * @alias Blockly.serialization.priorities.BLOCKS
+ */
+export declare const BLOCKS = 50;

package/core/serialization/{priorities.js → priorities.ts}

@@ -10,29 +10,23 @@
  * serializers. Higher priorities are deserialized first.
  */
 
-'use strict';
-
 /**
  * The top level namespace for priorities of plugin serializers.
  * Includes constants for the priorities of different plugin serializers. Higher
  * priorities are deserialized first.
  * @namespace Blockly.serialization.priorities
  */
-goog.module('Blockly.serialization.priorities');
+import * as goog from '../../closure/goog/goog.js';
+goog.declareModuleId('Blockly.serialization.priorities');
 
 
 /**
  * The priority for deserializing variables.
- * @type {number}
- * @const
  * @alias Blockly.serialization.priorities.VARIABLES
  */
-exports.VARIABLES = 100;
-
+export const VARIABLES = 100;
 /**
  * The priority for deserializing blocks.
- * @type {number}
- * @const
  * @alias Blockly.serialization.priorities.BLOCKS
  */
-exports.BLOCKS = 50;
+export const BLOCKS = 50;

package/core/serialization/registry.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { ISerializer } from '../interfaces/i_serializer.js';
+/**
+ * Registers the given serializer so that it can be used for serialization and
+ * deserialization.
+ * @param name The name of the serializer to register.
+ * @param serializer The serializer to register.
+ * @alias Blockly.serialization.registry.register
+ */
+export declare function register(name: string, serializer: ISerializer): void;
+/**
+ * Unregisters the serializer associated with the given name.
+ * @param name The name of the serializer to unregister.
+ * @alias Blockly.serialization.registry.unregister
+ */
+export declare function unregister(name: string): void;

package/core/serialization/{registry.js → registry.ts}

@@ -8,38 +8,36 @@
  * @fileoverview Contains functions registering serializers (eg blocks,
  * variables, plugins, etc).
  */
-'use strict';
 
 /**
  * Contains functions registering serializers (eg blocks, variables, plugins,
  * etc).
  * @namespace Blockly.serialization.registry
  */
-goog.module('Blockly.serialization.registry');
+import * as goog from '../../closure/goog/goog.js';
+goog.declareModuleId('Blockly.serialization.registry');
 
-const registry = goog.require('Blockly.registry');
 // eslint-disable-next-line no-unused-vars
-const {ISerializer} = goog.requireType('Blockly.serialization.ISerializer');
+import type {ISerializer} from '../interfaces/i_serializer.js';
+import * as registry from '../registry.js';
 
 
 /**
  * Registers the given serializer so that it can be used for serialization and
  * deserialization.
- * @param {string} name The name of the serializer to register.
- * @param {ISerializer} serializer The serializer to register.
+ * @param name The name of the serializer to register.
+ * @param serializer The serializer to register.
  * @alias Blockly.serialization.registry.register
  */
-const register = function(name, serializer) {
+export function register(name: string, serializer: ISerializer) {
   registry.register(registry.Type.SERIALIZER, name, serializer);
-};
-exports.register = register;
+}
 
 /**
  * Unregisters the serializer associated with the given name.
- * @param {string} name The name of the serializer to unregister.
+ * @param name The name of the serializer to unregister.
  * @alias Blockly.serialization.registry.unregister
  */
-const unregister = function(name) {
+export function unregister(name: string) {
   registry.unregister(registry.Type.SERIALIZER, name);
-};
-exports.unregister = unregister;
+}

package/core/serialization/variables.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Represents the state of a given variable.
+ * @alias Blockly.serialization.variables.State
+ */
+export interface State {
+    name: string;
+    id: string;
+    type: string | undefined;
+}

package/core/serialization/{variables.js → variables.ts}

@@ -8,57 +8,52 @@
  * @fileoverview Handles serializing variables to plain JavaScript objects, only
  * containing state.
  */
-'use strict';
 
 /**
  * Handles serializing variables to plain JavaScript objects, only containing
  * state.
  * @namespace Blockly.serialization.variables
  */
-goog.module('Blockly.serialization.variables');
+import * as goog from '../../closure/goog/goog.js';
+goog.declareModuleId('Blockly.serialization.variables');
 
-const priorities = goog.require('Blockly.serialization.priorities');
-const serializationRegistry = goog.require('Blockly.serialization.registry');
-// eslint-disable-next-line no-unused-vars
-const {ISerializer} = goog.require('Blockly.serialization.ISerializer');
-// eslint-disable-next-line no-unused-vars
-const {Workspace} = goog.requireType('Blockly.Workspace');
+import type {ISerializer} from '../interfaces/i_serializer.js';
+import type {Workspace} from '../workspace.js';
+
+import * as priorities from './priorities.js';
+import * as serializationRegistry from './registry.js';
 
 
 /**
  * Represents the state of a given variable.
- * @typedef {{
- *   name: string,
- *   id: string,
- *   type: (string|undefined)
- * }}
  * @alias Blockly.serialization.variables.State
  */
-let State;
-exports.State = State;
+export interface State {
+  name: string;
+  id: string;
+  type: string|undefined;
+}
 
 /**
  * Serializer for saving and loading variable state.
- * @implements {ISerializer}
  * @alias Blockly.serialization.variables.VariableSerializer
  */
-class VariableSerializer {
+class VariableSerializer implements ISerializer {
+  priority: number;
+
   /* eslint-disable-next-line require-jsdoc */
   constructor() {
-    /**
-     * The priority for deserializing variables.
-     * @type {number}
-     */
+    /** The priority for deserializing variables. */
     this.priority = priorities.VARIABLES;
   }
 
   /**
    * Serializes the variables of the given workspace.
-   * @param {!Workspace} workspace The workspace to save the variables of.
-   * @return {?Array<!State>} The state of the workspace's variables, or null
-   *     if there are no variables.
+   * @param workspace The workspace to save the variables of.
+   * @return The state of the workspace's variables, or null if there are no
+   *     variables.
    */
-  save(workspace) {
+  save(workspace: Workspace): State[]|null {
     const variableStates = [];
     for (const variable of workspace.getAllVariables()) {
       const state = {
@@ -66,20 +61,23 @@ class VariableSerializer {
         'id': variable.getId(),
       };
       if (variable.type) {
-        state['type'] = variable.type;
+        (state as AnyDuringMigration)['type'] = variable.type;
       }
       variableStates.push(state);
     }
-    return variableStates.length ? variableStates : null;
+    // AnyDuringMigration because:  Type '{ name: string; id: string; }[] |
+    // null' is not assignable to type 'State[] | null'.
+    return (variableStates.length ? variableStates : null) as
+        AnyDuringMigration;
   }
 
   /**
    * Deserializes the variable defined by the given state into the given
    * workspace.
-   * @param {!Array<!State>} state The state of the variables to deserialize.
-   * @param {!Workspace} workspace The workspace to deserialize into.
+   * @param state The state of the variables to deserialize.
+   * @param workspace The workspace to deserialize into.
    */
-  load(state, workspace) {
+  load(state: State[], workspace: Workspace) {
     for (const varState of state) {
       workspace.createVariable(
           varState['name'], varState['type'], varState['id']);
@@ -88,9 +86,9 @@ class VariableSerializer {
 
   /**
    * Disposes of any variables that exist on the workspace.
-   * @param {!Workspace} workspace The workspace to clear the variables of.
+   * @param workspace The workspace to clear the variables of.
    */
-  clear(workspace) {
+  clear(workspace: Workspace) {
     workspace.getVariableMap().clear();
   }
 }

package/core/serialization/workspaces.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { Workspace } from '../workspace.js';
+/**
+ * Returns the state of the workspace as a plain JavaScript object.
+ * @param workspace The workspace to serialize.
+ * @return The serialized state of the workspace.
+ * @alias Blockly.serialization.workspaces.save
+ */
+export declare function save(workspace: Workspace): {
+    [key: string]: any;
+};
+/**
+ * Loads the variable represented by the given state into the given workspace.
+ * @param state The state of the workspace to deserialize into the workspace.
+ * @param workspace The workspace to add the new state to.
+ * @param param1 recordUndo: If true, events triggered by this function will be
+ *     undo-able by the user. False by default.
+ * @alias Blockly.serialization.workspaces.load
+ */
+export declare function load(state: {
+    [key: string]: any;
+}, workspace: Workspace, { recordUndo }?: {
+    recordUndo?: boolean;
+}): void;

package/core/serialization/{workspaces.js → workspaces.ts}

@@ -8,60 +8,63 @@
  * @fileoverview Contains top-level functions for serializing workspaces to
  * plain JavaScript objects.
  */
-'use strict';
 
 /**
  * Contains top-level functions for serializing workspaces to plain JavaScript
  * objects.
  * @namespace Blockly.serialization.workspaces
  */
-goog.module('Blockly.serialization.workspaces');
+import * as goog from '../../closure/goog/goog.js';
+goog.declareModuleId('Blockly.serialization.workspaces');
 
-const dom = goog.require('Blockly.utils.dom');
-const eventUtils = goog.require('Blockly.Events.utils');
-const registry = goog.require('Blockly.registry');
+import * as eventUtils from '../events/utils.js';
+import type {ISerializer} from '../interfaces/i_serializer.js';
+import * as registry from '../registry.js';
+import * as dom from '../utils/dom.js';
 // eslint-disable-next-line no-unused-vars
-const {Workspace} = goog.require('Blockly.Workspace');
-const {WorkspaceSvg} = goog.require('Blockly.WorkspaceSvg');
+import type {Workspace} from '../workspace.js';
+import {WorkspaceSvg} from '../workspace_svg.js';
 
 
 /**
  * Returns the state of the workspace as a plain JavaScript object.
- * @param {!Workspace} workspace The workspace to serialize.
- * @return {!Object<string, *>} The serialized state of the workspace.
+ * @param workspace The workspace to serialize.
+ * @return The serialized state of the workspace.
  * @alias Blockly.serialization.workspaces.save
  */
-const save = function(workspace) {
+export function save(workspace: Workspace):
+    {[key: string]: AnyDuringMigration} {
   const state = Object.create(null);
   const serializerMap = registry.getAllItems(registry.Type.SERIALIZER, true);
   for (const key in serializerMap) {
-    const save = serializerMap[key].save(workspace);
+    const save = (serializerMap[key] as ISerializer)?.save(workspace);
     if (save) {
       state[key] = save;
     }
   }
   return state;
-};
-exports.save = save;
+}
 
 /**
  * Loads the variable represented by the given state into the given workspace.
- * @param {!Object<string, *>} state The state of the workspace to deserialize
- *     into the workspace.
- * @param {!Workspace} workspace The workspace to add the new state to.
- * @param {{recordUndo: (boolean|undefined)}=} param1
- *     recordUndo: If true, events triggered by this function will be undo-able
- *       by the user. False by default.
+ * @param state The state of the workspace to deserialize into the workspace.
+ * @param workspace The workspace to add the new state to.
+ * @param param1 recordUndo: If true, events triggered by this function will be
+ *     undo-able by the user. False by default.
  * @alias Blockly.serialization.workspaces.load
  */
-const load = function(state, workspace, {recordUndo = false} = {}) {
+export function load(
+    state: {[key: string]: AnyDuringMigration}, workspace: Workspace,
+    {recordUndo = false}: {recordUndo?: boolean} = {}) {
   const serializerMap = registry.getAllItems(registry.Type.SERIALIZER, true);
   if (!serializerMap) {
     return;
   }
 
   const deserializers = Object.entries(serializerMap)
-                            .sort((a, b) => b[1].priority - a[1].priority);
+                            .sort(
+                                (a, b) => (b[1] as ISerializer)!.priority -
+                                    (a[1] as ISerializer)!.priority);
 
   const prevRecordUndo = eventUtils.getRecordUndo();
   eventUtils.setRecordUndo(recordUndo);
@@ -78,15 +81,15 @@ const load = function(state, workspace, {recordUndo = false} = {}) {
   // We want to trigger clearing in reverse priority order so plugins don't end
   // up missing dependencies.
   for (const [, deserializer] of deserializers.reverse()) {
-    deserializer.clear(workspace);
+    (deserializer as ISerializer)?.clear(workspace);
   }
 
   // reverse() is destructive, so we have to re-reverse to correct the order.
   for (let [name, deserializer] of deserializers.reverse()) {
-    name = /** @type {string} */ (name);
+    name = name;
     const pluginState = state[name];
     if (pluginState) {
-      deserializer.load(state[name], workspace);
+      (deserializer as ISerializer)?.load(state[name], workspace);
     }
   }
 
@@ -95,9 +98,9 @@ const load = function(state, workspace, {recordUndo = false} = {}) {
   }
   dom.stopTextWidthCache();
 
-  eventUtils.fire(new (eventUtils.get(eventUtils.FINISHED_LOADING))(workspace));
+  eventUtils.fire(new (eventUtils.get(eventUtils.FINISHED_LOADING))!
+                  (workspace));
 
   eventUtils.setGroup(existingGroup);
   eventUtils.setRecordUndo(prevRecordUndo);
-};
-exports.load = load;
+}

package/core/shortcut_items.d.ts

@@ -0,0 +1,61 @@
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Object holding the names of the default shortcut items.
+ * @alias Blockly.ShortcutItems.names
+ */
+export declare enum names {
+    ESCAPE = "escape",
+    DELETE = "delete",
+    COPY = "copy",
+    CUT = "cut",
+    PASTE = "paste",
+    UNDO = "undo",
+    REDO = "redo"
+}
+/**
+ * Keyboard shortcut to hide chaff on escape.
+ * @alias Blockly.ShortcutItems.registerEscape
+ */
+export declare function registerEscape(): void;
+/**
+ * Keyboard shortcut to delete a block on delete or backspace
+ * @alias Blockly.ShortcutItems.registerDelete
+ */
+export declare function registerDelete(): void;
+/**
+ * Keyboard shortcut to copy a block on ctrl+c, cmd+c, or alt+c.
+ * @alias Blockly.ShortcutItems.registerCopy
+ */
+export declare function registerCopy(): void;
+/**
+ * Keyboard shortcut to copy and delete a block on ctrl+x, cmd+x, or alt+x.
+ * @alias Blockly.ShortcutItems.registerCut
+ */
+export declare function registerCut(): void;
+/**
+ * Keyboard shortcut to paste a block on ctrl+v, cmd+v, or alt+v.
+ * @alias Blockly.ShortcutItems.registerPaste
+ */
+export declare function registerPaste(): void;
+/**
+ * Keyboard shortcut to undo the previous action on ctrl+z, cmd+z, or alt+z.
+ * @alias Blockly.ShortcutItems.registerUndo
+ */
+export declare function registerUndo(): void;
+/**
+ * Keyboard shortcut to redo the previous action on ctrl+shift+z, cmd+shift+z,
+ * or alt+shift+z.
+ * @alias Blockly.ShortcutItems.registerRedo
+ */
+export declare function registerRedo(): void;
+/**
+ * Registers all default keyboard shortcut item. This should be called once per
+ * instance of KeyboardShortcutRegistry.
+ * @alias Blockly.ShortcutItems.registerDefaultShortcuts
+ * @internal
+ */
+export declare function registerDefaultShortcuts(): void;