blockly 12.4.0 → 12.5.0

package/core/serialization/exceptions.d.ts

@@ -0,0 +1,81 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { Block } from '../block.js';
+import type { State } from './blocks.js';
+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.
+ *
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+export declare class RealChildOfShadow extends DeserializationError {
+    state: State;
+    /**
+     * @param state The state object representing the real block.
+     * @internal
+     */
+    constructor(state: State);
+}
+export declare class UnregisteredIcon extends DeserializationError {
+    block: Block;
+    state: State;
+    /**
+     * @param iconType The type of the unregistered icon we are attempting to
+     *     deserialize.
+     * @param block The block we are attempting to add the unregistered icon to.
+     * @param state The state object representing the block.
+     */
+    constructor(iconType: string, block: Block, state: State);
+}
+//# sourceMappingURL=exceptions.d.ts.map

package/core/serialization/priorities.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * The priority for deserializing variables.
+ */
+export declare const VARIABLES = 100;
+/**
+ * The priority for deserializing variable data.
+ */
+export declare const PROCEDURES = 75;
+/**
+ * The priority for deserializing blocks.
+ */
+export declare const BLOCKS = 50;
+/** The priority for deserializing workspace comments. */
+export declare const WORKSPACE_COMMENTS = 25;
+//# sourceMappingURL=priorities.d.ts.map

package/core/serialization/procedures.d.ts

@@ -0,0 +1,97 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { IParameterModel } from '../interfaces/i_parameter_model.js';
+import { IProcedureModel } from '../interfaces/i_procedure_model.js';
+import type { ISerializer } from '../interfaces/i_serializer.js';
+import type { Workspace } from '../workspace.js';
+/** Represents the state of a procedure model. */
+export interface State {
+    id: string;
+    name: string;
+    returnTypes: string[] | null;
+    parameters?: ParameterState[];
+    [key: string]: unknown;
+}
+/** Represents the state of a parameter model. */
+export interface ParameterState {
+    id: string;
+    name: string;
+    types?: string[];
+    [key: string]: unknown;
+}
+/**
+ * A newable signature for an IProcedureModel.
+ *
+ * Refer to
+ * https://www.typescriptlang.org/docs/handbook/interfaces.html#difference-between-the-static-and-instance-sides-of-classes
+ * for what is going on with this.
+ */
+interface ProcedureModelConstructor<ProcedureModel extends IProcedureModel> {
+    new (workspace: Workspace, name: string, id: string): ProcedureModel;
+    /**
+     * Deserializes the JSON state and returns a procedure model.
+     *
+     * @param state The state to deserialize.
+     * @param workspace The workspace to load the procedure model into.
+     * @returns The constructed procedure model.
+     */
+    loadState(state: object, workspace: Workspace): ProcedureModel;
+}
+/**
+ * A newable signature for an IParameterModel.
+ *
+ * Refer to
+ * https://www.typescriptlang.org/docs/handbook/interfaces.html#difference-between-the-static-and-instance-sides-of-classes
+ * for what is going on with this.
+ */
+interface ParameterModelConstructor<ParameterModel extends IParameterModel> {
+    new (workspace: Workspace, name: string, id: string): ParameterModel;
+    /**
+     * Deserializes the JSON state and returns a parameter model.
+     *
+     * @param state The state to deserialize.
+     * @param workspace The workspace to load the parameter model into.
+     * @returns The constructed parameter model.
+     */
+    loadState(state: object, workspace: Workspace): ParameterModel;
+}
+/**
+ * Serializes the given IProcedureModel to JSON.
+ */
+export declare function saveProcedure(proc: IProcedureModel): State;
+/**
+ * Deserializes the given procedure model State from JSON.
+ */
+export declare function loadProcedure<ProcedureModel extends IProcedureModel, ParameterModel extends IParameterModel>(procedureModelClass: ProcedureModelConstructor<ProcedureModel>, parameterModelClass: ParameterModelConstructor<ParameterModel>, state: State, workspace: Workspace): ProcedureModel;
+/** Serializer for saving and loading procedure state. */
+export declare class ProcedureSerializer<ProcedureModel extends IProcedureModel, ParameterModel extends IParameterModel> implements ISerializer {
+    private readonly procedureModelClass;
+    private readonly parameterModelClass;
+    priority: number;
+    /**
+     * Constructs the procedure serializer.
+     *
+     * Example usage:
+     *   new ProcedureSerializer(MyProcedureModelClass, MyParameterModelClass)
+     *
+     * @param procedureModelClass The class (implementing IProcedureModel) that
+     *     you want this serializer to deserialize.
+     * @param parameterModelClass The class (implementing IParameterModel) that
+     *     you want this serializer to deserialize.
+     */
+    constructor(procedureModelClass: ProcedureModelConstructor<ProcedureModel>, parameterModelClass: ParameterModelConstructor<ParameterModel>);
+    /** Serializes the procedure models of the given workspace. */
+    save(workspace: Workspace): State[] | null;
+    /**
+     * Deserializes the procedures models defined by the given state into the
+     * workspace.
+     */
+    load(state: State[], workspace: Workspace): void;
+    /** Disposes of any procedure models that exist on the workspace. */
+    clear(workspace: Workspace): void;
+}
+export {};
+//# sourceMappingURL=procedures.d.ts.map

package/core/serialization/registry.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @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.
+ */
+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.
+ */
+export declare function unregister(name: string): void;
+//# sourceMappingURL=registry.d.ts.map

package/core/serialization/variables.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { ISerializer } from '../interfaces/i_serializer.js';
+import type { IVariableState } from '../interfaces/i_variable_model.js';
+import type { Workspace } from '../workspace.js';
+/**
+ * Serializer for saving and loading variable state.
+ */
+export declare class VariableSerializer implements ISerializer {
+    priority: number;
+    constructor();
+    /**
+     * Serializes the variables of the given workspace.
+     *
+     * @param workspace The workspace to save the variables of.
+     * @returns The state of the workspace's variables, or null if there are no
+     *     variables.
+     */
+    save(workspace: Workspace): IVariableState[] | null;
+    /**
+     * Deserializes the variable defined by the given state into the given
+     * workspace.
+     *
+     * @param state The state of the variables to deserialize.
+     * @param workspace The workspace to deserialize into.
+     */
+    load(state: IVariableState[], workspace: Workspace): void;
+    /**
+     * Disposes of any variables that exist on the workspace.
+     *
+     * @param workspace The workspace to clear the variables of.
+     */
+    clear(workspace: Workspace): void;
+}
+//# sourceMappingURL=variables.d.ts.map

package/core/serialization/workspace_comments.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @license
+ * Copyright 2024 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { WorkspaceComment } from '../comments/workspace_comment.js';
+import { ISerializer } from '../interfaces/i_serializer.js';
+import { Workspace } from '../workspace.js';
+export interface State {
+    id?: string;
+    text?: string;
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number;
+    collapsed?: boolean;
+    editable?: boolean;
+    movable?: boolean;
+    deletable?: boolean;
+}
+/** Serializes the state of the given comment to JSON. */
+export declare function save(comment: WorkspaceComment, { addCoordinates, saveIds, }?: {
+    addCoordinates?: boolean;
+    saveIds?: boolean;
+}): State;
+/** Appends the comment defined by the given state to the given workspace. */
+export declare function append(state: State, workspace: Workspace, { recordUndo }?: {
+    recordUndo?: boolean;
+}): WorkspaceComment;
+/** Serializer for saving and loading workspace comment state. */
+export declare class WorkspaceCommentSerializer implements ISerializer {
+    priority: number;
+    /**
+     * Returns the state of all workspace comments in the given workspace.
+     */
+    save(workspace: Workspace): State[] | null;
+    /**
+     * Deserializes the comments defined by the given state into the given
+     * workspace.
+     */
+    load(state: State[], workspace: Workspace): void;
+    /** Disposes of any comments that exist on the given workspace. */
+    clear(workspace: Workspace): void;
+}
+//# sourceMappingURL=workspace_comments.d.ts.map

package/core/serialization/workspaces.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @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.
+ * @returns The serialized state of the workspace.
+ */
+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.
+ */
+export declare function load(state: {
+    [key: string]: any;
+}, workspace: Workspace, { recordUndo }?: {
+    recordUndo?: boolean;
+}): void;
+//# sourceMappingURL=workspaces.d.ts.map

package/core/serialization.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @license
+ * Copyright 2022 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Serialization methods.
+ */
+import { ISerializer } from './interfaces/i_serializer.js';
+import * as blocks from './serialization/blocks.js';
+import * as exceptions from './serialization/exceptions.js';
+import * as priorities from './serialization/priorities.js';
+import * as procedures from './serialization/procedures.js';
+import * as registry from './serialization/registry.js';
+import * as variables from './serialization/variables.js';
+import * as workspaceComments from './serialization/workspace_comments.js';
+import * as workspaces from './serialization/workspaces.js';
+export { blocks, exceptions, ISerializer, priorities, procedures, registry, variables, workspaceComments, workspaces, };
+//# sourceMappingURL=serialization.d.ts.map

package/core/shortcut_items.d.ts

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

package/core/shortcut_registry.d.ts

@@ -0,0 +1,236 @@
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * The namespace used to keep track of keyboard shortcuts and the
+ * key codes used to execute those shortcuts.
+ *
+ * @class
+ */
+import { Scope } from './contextmenu_registry.js';
+import { KeyCodes } from './utils/keycodes.js';
+import { WorkspaceSvg } from './workspace_svg.js';
+/**
+ * Class for the registry of keyboard shortcuts. This is intended to be a
+ * singleton. You should not create a new instance, and only access this class
+ * from ShortcutRegistry.registry.
+ */
+export declare class ShortcutRegistry {
+    static readonly registry: ShortcutRegistry;
+    /** Registry of all keyboard shortcuts, keyed by name of shortcut. */
+    private shortcuts;
+    /** Map of key codes to an array of shortcut names. */
+    private keyMap;
+    /** Resets the existing ShortcutRegistry singleton. */
+    private constructor();
+    /** Clear and recreate the registry and keyMap. */
+    reset(): void;
+    /**
+     * Registers a keyboard shortcut.
+     *
+     * @param shortcut The shortcut for this key code.
+     * @param allowOverrides True to prevent a warning when overriding an
+     *     already registered item.
+     * @throws {Error} if a shortcut with the same name already exists.
+     */
+    register(shortcut: KeyboardShortcut, allowOverrides?: boolean): void;
+    /**
+     * Unregisters a keyboard shortcut registered with the given name. This
+     * will also remove any key mappings that reference this shortcut.
+     *
+     * @param shortcutName The name of the shortcut to unregister.
+     * @returns True if an item was unregistered, false otherwise.
+     */
+    unregister(shortcutName: string): boolean;
+    /**
+     * Adds a mapping between a keycode and a keyboard shortcut.
+     *
+     * Normally only one shortcut can be mapped to any given keycode,
+     * but setting allowCollisions to true allows a keyboard to be
+     * mapped to multiple shortcuts.  In that case, when onKeyDown is
+     * called with the given keystroke, it will process the mapped
+     * shortcuts in reverse order, from the most- to least-recently
+     * mapped).
+     *
+     * @param keyCode The key code for the keyboard shortcut. If registering a key
+     *     code with a modifier (ex: ctrl+c) use
+     *     ShortcutRegistry.registry.createSerializedKey;
+     * @param shortcutName The name of the shortcut to execute when the given
+     *     keycode is pressed.
+     * @param allowCollision True to prevent an error when adding a shortcut
+     *     to a key that is already mapped to a shortcut.
+     * @throws {Error} if the given key code is already mapped to a shortcut.
+     */
+    addKeyMapping(keyCode: string | number | KeyCodes, shortcutName: string, allowCollision?: boolean): void;
+    /**
+     * Removes a mapping between a keycode and a keyboard shortcut.
+     *
+     * @param keyCode The key code for the keyboard shortcut. If registering a key
+     *     code with a modifier (ex: ctrl+c) use
+     *     ShortcutRegistry.registry.createSerializedKey;
+     * @param shortcutName The name of the shortcut to execute when the given
+     *     keycode is pressed.
+     * @param quiet True to not console warn when there is no shortcut to
+     *     remove.
+     * @returns True if a key mapping was removed, false otherwise.
+     */
+    removeKeyMapping(keyCode: string, shortcutName: string, quiet?: boolean): boolean;
+    /**
+     * Removes all the key mappings for a shortcut with the given name.
+     * Useful when changing the default key mappings and the key codes registered
+     * to the shortcut are unknown.
+     *
+     * @param shortcutName The name of the shortcut to remove from the key map.
+     */
+    removeAllKeyMappings(shortcutName: string): void;
+    /**
+     * Sets the key map. Setting the key map will override any default key
+     * mappings.
+     *
+     * @param newKeyMap The object with key code to shortcut names.
+     */
+    setKeyMap(newKeyMap: {
+        [key: string]: string[];
+    }): void;
+    /**
+     * Gets the current key map.
+     *
+     * @returns The object holding key codes to ShortcutRegistry.KeyboardShortcut.
+     */
+    getKeyMap(): {
+        [key: string]: string[];
+    };
+    /**
+     * Gets the registry of keyboard shortcuts.
+     *
+     * @returns The registry of keyboard shortcuts.
+     */
+    getRegistry(): {
+        [key: string]: KeyboardShortcut;
+    };
+    /**
+     * Handles key down events.
+     *
+     * - Any `KeyboardShortcut`(s) mapped to the keycodes that cause
+     *   event `e` to be fired will be processed, in order from least-
+     *   to most-recently registered.
+     * - If the shortcut's `preconditionFn` exists it will be called.
+     *   If `preconditionFn` returns false the shortcut's `callback`
+     *   function will be skipped.  Processing will continue with the
+     *   next shortcut, if any.
+     * - The shortcut's `callback` function will then be called.  If it
+     *   returns true, processing will terminate and `onKeyDown` will
+     *   return true.  If it returns false, processing will continue
+     *   with with the next shortcut, if any.
+     * - If all registered shortcuts for the given keycode have been
+     *   processed without any having returned true, `onKeyDown` will
+     *   return false.
+     *
+     * @param workspace The main workspace where the event was captured.
+     * @param e The key down event.
+     * @returns True if the event was handled, false otherwise.
+     */
+    onKeyDown(workspace: WorkspaceSvg, e: KeyboardEvent): boolean;
+    /**
+     * Gets the shortcuts registered to the given key code.
+     *
+     * @param keyCode The serialized key code.
+     * @returns The list of shortcuts to call when the given keyCode is used.
+     *     Undefined if no shortcuts exist.
+     */
+    getShortcutNamesByKeyCode(keyCode: string): string[] | undefined;
+    /**
+     * Gets the serialized key codes that the shortcut with the given name is
+     * registered under.
+     *
+     * @param shortcutName The name of the shortcut.
+     * @returns An array with all the key codes the shortcut is registered under.
+     */
+    getKeyCodesByShortcutName(shortcutName: string): string[];
+    /**
+     * Serializes a key event.
+     *
+     * @param e A key down event.
+     * @returns The serialized key code for the given event.
+     */
+    private serializeKeyEvent;
+    /**
+     * Checks whether any of the given modifiers are not valid.
+     *
+     * @param modifiers List of modifiers to be used with the key.
+     * @throws {Error} if the modifier is not in the valid modifiers list.
+     */
+    private checkModifiers;
+    /**
+     * Creates the serialized key code that will be used in the key map.
+     *
+     * @param keyCode Number code representing the key.
+     * @param modifiers List of modifier key codes to be used with the key. All
+     *     valid modifiers can be found in the `ShortcutRegistry.modifierKeys`.
+     * @returns The serialized key code for the given modifiers and key.
+     */
+    createSerializedKey(keyCode: number, modifiers: KeyCodes[] | null): string;
+}
+export declare namespace ShortcutRegistry {
+    /** Interface defining a keyboard shortcut. */
+    interface KeyboardShortcut {
+        /**
+         * The function to be called when the shorctut is invoked.
+         *
+         * @param workspace The `WorkspaceSvg` when the shortcut was
+         *     invoked.
+         * @param e The event that caused the shortcut to be activated.
+         * @param shortcut The `KeyboardShortcut` that was activated
+         *     (i.e., the one this callback is attached to).
+         * @param scope Information about the focused item when the
+         * shortcut was invoked.
+         * @returns Returning true ends processing of the invoked keycode.
+         *     Returning false causes processing to continue with the
+         *     next-most-recently registered shortcut for the invoked
+         *     keycode.
+         */
+        callback?: (workspace: WorkspaceSvg, e: Event, shortcut: KeyboardShortcut, scope: Scope) => boolean;
+        /** The name of the shortcut.  Should be unique. */
+        name: string;
+        /**
+         * A function to be called when the shortcut is invoked, before
+         * calling `callback`, to decide if this shortcut is applicable in
+         * the current situation.
+         *
+         * @param workspace The `WorkspaceSvg` where the shortcut was
+         *     invoked.
+         * @param scope Information about the focused item when the
+         * shortcut would be invoked.
+         * @returns True iff `callback` function should be called.
+         */
+        preconditionFn?: (workspace: WorkspaceSvg, scope: Scope) => boolean;
+        /** Optional arbitray extra data attached to the shortcut. */
+        metadata?: object;
+        /**
+         * Optional list of key codes to be bound (via
+         * ShortcutRegistry.prototype.addKeyMapping) to this shortcut.
+         */
+        keyCodes?: (number | string)[];
+        /**
+         * Value of `allowCollision` to pass to `addKeyMapping` when
+         * binding this shortcut's `.keyCodes` (if any).
+         *
+         * N.B.: this is only used for binding keycodes at the time this
+         * shortcut is initially registered, not for any subsequent
+         * `addKeyMapping` calls that happen to reference this shortcut's
+         * name.
+         */
+        allowCollision?: boolean;
+    }
+    /** Supported modifiers. */
+    enum modifierKeys {
+        Shift = 16,
+        Control = 17,
+        Alt = 18,
+        Meta = 91
+    }
+}
+export type KeyboardShortcut = ShortcutRegistry.KeyboardShortcut;
+//# sourceMappingURL=shortcut_registry.d.ts.map

package/core/sprites.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @license
+ * Copyright 2022 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Contains the path to a single png tat holds the images for the trashcan
+ * as well as the zoom controls.
+ */
+export declare const SPRITE: {
+    width: number;
+    height: number;
+    url: string;
+};
+//# sourceMappingURL=sprites.d.ts.map

package/core/theme/classic.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @license
+ * Copyright 2018 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Theme } from '../theme.js';
+/**
+ * Classic theme.
+ * Contains multi-coloured border to create shadow effect.
+ */
+export declare const Classic: Theme;
+//# sourceMappingURL=classic.d.ts.map