blockly 12.4.0 → 12.4.1

package/core/icons/exceptions.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { IIcon } from '../interfaces/i_icon.js';
+/**
+ * Thrown when you add more than one icon of the same type to a block.
+ */
+export declare class DuplicateIconType extends Error {
+    icon: IIcon;
+    /**
+     * @internal
+     */
+    constructor(icon: IIcon);
+}
+//# sourceMappingURL=exceptions.d.ts.map

package/core/icons/icon.d.ts

@@ -0,0 +1,84 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { Block } from '../block.js';
+import type { IContextMenu } from '../interfaces/i_contextmenu.js';
+import type { IFocusableTree } from '../interfaces/i_focusable_tree.js';
+import type { IIcon } from '../interfaces/i_icon.js';
+import * as tooltip from '../tooltip.js';
+import { Coordinate } from '../utils/coordinate.js';
+import { Size } from '../utils/size.js';
+import type { IconType } from './icon_types.js';
+/**
+ * The abstract icon class. Icons are visual elements that live in the top-start
+ * corner of the block. Usually they provide more "meta" information about a
+ * block (such as warnings or comments) as opposed to fields, which provide
+ * "actual" information, related to how a block functions.
+ */
+export declare abstract class Icon implements IIcon, IContextMenu {
+    protected sourceBlock: Block;
+    /**
+     * The position of this icon relative to its blocks top-start,
+     * in workspace units.
+     */
+    protected offsetInBlock: Coordinate;
+    /** The position of this icon in workspace coordinates. */
+    protected workspaceLocation: Coordinate;
+    /** The root svg element visually representing this icon. */
+    protected svgRoot: SVGGElement | null;
+    /** The tooltip for this icon. */
+    protected tooltip: tooltip.TipInfo;
+    /** The unique ID of this icon. */
+    private id;
+    constructor(sourceBlock: Block);
+    getType(): IconType<IIcon>;
+    initView(pointerdownListener: (e: PointerEvent) => void): void;
+    dispose(): void;
+    getWeight(): number;
+    getSize(): Size;
+    /**
+     * Sets the tooltip for this icon to the given value. Null to show the
+     * tooltip of the block.
+     */
+    setTooltip(tip: tooltip.TipInfo | null): void;
+    /** Returns the tooltip for this icon. */
+    getTooltip(): tooltip.TipInfo;
+    applyColour(): void;
+    updateEditable(): void;
+    updateCollapsed(): void;
+    hideForInsertionMarker(): void;
+    isShownWhenCollapsed(): boolean;
+    setOffsetInBlock(offset: Coordinate): void;
+    private updateSvgRootOffset;
+    onLocationChange(blockOrigin: Coordinate): void;
+    onClick(): void;
+    /**
+     * Check whether the icon should be clickable while the block is in a flyout.
+     * The default is that icons are clickable in all flyouts (auto-closing or not).
+     * Subclasses may override this function to change this behavior.
+     *
+     * @param autoClosingFlyout true if the containing flyout is an auto-closing one.
+     * @returns Whether the icon should be clickable while the block is in a flyout.
+     */
+    isClickableInFlyout(autoClosingFlyout: boolean): boolean;
+    /** See IFocusableNode.getFocusableElement. */
+    getFocusableElement(): HTMLElement | SVGElement;
+    /** See IFocusableNode.getFocusableTree. */
+    getFocusableTree(): IFocusableTree;
+    /** See IFocusableNode.onNodeFocus. */
+    onNodeFocus(): void;
+    /** See IFocusableNode.onNodeBlur. */
+    onNodeBlur(): void;
+    /** See IFocusableNode.canBeFocused. */
+    canBeFocused(): boolean;
+    /**
+     * Returns the block that this icon is attached to.
+     *
+     * @returns The block this icon is attached to.
+     */
+    getSourceBlock(): Block;
+    showContextMenu(e: PointerEvent): void;
+}
+//# sourceMappingURL=icon.d.ts.map

package/core/icons/icon_types.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { ICommentIcon } from '../interfaces/i_comment_icon.js';
+import { IIcon } from '../interfaces/i_icon.js';
+import { MutatorIcon } from './mutator_icon.js';
+import { WarningIcon } from './warning_icon.js';
+/**
+ * Defines the type of an icon, so that it can be retrieved from block.getIcon
+ */
+export declare class IconType<_T extends IIcon> {
+    private readonly name;
+    /** @param name The name of the registry type. */
+    constructor(name: string);
+    /** @returns the name of the type. */
+    toString(): string;
+    /** @returns true if this icon type is equivalent to the given icon type. */
+    equals(type: IconType<IIcon>): boolean;
+    static MUTATOR: IconType<MutatorIcon>;
+    static WARNING: IconType<WarningIcon>;
+    static COMMENT: IconType<ICommentIcon>;
+}
+//# sourceMappingURL=icon_types.d.ts.map

package/core/icons/mutator_icon.d.ts

@@ -0,0 +1,96 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { BlockSvg } from '../block_svg.js';
+import { MiniWorkspaceBubble } from '../bubbles/mini_workspace_bubble.js';
+import type { Abstract } from '../events/events_abstract.js';
+import type { IHasBubble } from '../interfaces/i_has_bubble.js';
+import { Coordinate } from '../utils/coordinate.js';
+import { Size } from '../utils/size.js';
+import type { WorkspaceSvg } from '../workspace_svg.js';
+import { Icon } from './icon.js';
+import { IconType } from './icon_types.js';
+/**
+ * An icon that allows the user to change the shape of the block.
+ *
+ * For example, it could be used to add additional fields or inputs to
+ * the block.
+ */
+export declare class MutatorIcon extends Icon implements IHasBubble {
+    private readonly flyoutBlockTypes;
+    protected readonly sourceBlock: BlockSvg;
+    /** The type string used to identify this icon. */
+    static readonly TYPE: IconType<MutatorIcon>;
+    /**
+     * The weight this icon has relative to other icons. Icons with more positive
+     * weight values are rendered farther toward the end of the block.
+     */
+    static readonly WEIGHT = 1;
+    /** The bubble used to show the mini workspace to the user. */
+    private miniWorkspaceBubble;
+    /** The root block in the mini workspace. */
+    private rootBlock;
+    /** The PID tracking updating the workkspace in response to user events. */
+    private updateWorkspacePid;
+    /**
+     * The change listener in the main workspace that triggers the saveConnections
+     * method when anything in the main workspace changes.
+     *
+     * Only actually registered to listen for events while the mutator bubble is
+     * open.
+     */
+    private saveConnectionsListener;
+    constructor(flyoutBlockTypes: string[], sourceBlock: BlockSvg);
+    getType(): IconType<MutatorIcon>;
+    initView(pointerdownListener: (e: PointerEvent) => void): void;
+    dispose(): void;
+    getWeight(): number;
+    getSize(): Size;
+    applyColour(): void;
+    updateCollapsed(): void;
+    onLocationChange(blockOrigin: Coordinate): void;
+    onClick(): void;
+    isClickableInFlyout(): boolean;
+    bubbleIsVisible(): boolean;
+    setBubbleVisible(visible: boolean): Promise<void>;
+    /** See IHasBubble.getBubble. */
+    getBubble(): MiniWorkspaceBubble | null;
+    /** @returns the configuration the mini workspace should have. */
+    private getMiniWorkspaceConfig;
+    /**
+     * @returns the location the bubble should be anchored to.
+     *     I.E. the middle of this icon.
+     */
+    private getAnchorLocation;
+    /**
+     * @returns the rect the bubble should avoid overlapping.
+     *     I.E. the block that owns this icon.
+     */
+    private getBubbleOwnerRect;
+    /** Decomposes the source block to create blocks in the mini workspace. */
+    private createRootBlock;
+    /** Adds a listen to the source block that triggers saving connections. */
+    private addSaveConnectionsListener;
+    /**
+     * Creates a change listener to add to the mini workspace which recomposes
+     * the block.
+     */
+    private createMiniWorkspaceChangeListener;
+    /**
+     * Returns true if the given event is not one the mutator needs to
+     * care about.
+     *
+     * @internal
+     */
+    static isIgnorableMutatorEvent(e: Abstract): boolean;
+    /** Recomposes the source block based on changes to the mini workspace. */
+    private recomposeSourceBlock;
+    /**
+     * @returns The workspace of the mini workspace bubble, if the bubble is
+     *     currently open.
+     */
+    getWorkspace(): WorkspaceSvg | undefined;
+}
+//# sourceMappingURL=mutator_icon.d.ts.map

package/core/icons/registry.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { Block } from '../block.js';
+import type { IIcon } from '../interfaces/i_icon.js';
+import { IconType } from './icon_types.js';
+/**
+ * Registers the given icon so that it can be deserialized.
+ *
+ * @param type The type of the icon to register. This should be the same string
+ *     that is returned from its `getType` method.
+ * @param iconConstructor The icon class/constructor to register.
+ */
+export declare function register(type: IconType<IIcon>, iconConstructor: new (block: Block) => IIcon): void;
+/**
+ * Unregisters the icon associated with the given type.
+ *
+ * @param type The type of the icon to unregister.
+ */
+export declare function unregister(type: string): void;
+//# sourceMappingURL=registry.d.ts.map

package/core/icons/warning_icon.d.ts

@@ -0,0 +1,77 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { BlockSvg } from '../block_svg.js';
+import type { IBubble } from '../interfaces/i_bubble.js';
+import type { IHasBubble } from '../interfaces/i_has_bubble.js';
+import { Size } from '../utils.js';
+import { Coordinate } from '../utils/coordinate.js';
+import { Icon } from './icon.js';
+import { IconType } from './icon_types.js';
+/**
+ * An icon that warns the user that something is wrong with their block.
+ *
+ * For example, this could be used to warn them about incorrect field values,
+ * or incorrect placement of the block (putting it somewhere it doesn't belong).
+ */
+export declare class WarningIcon extends Icon implements IHasBubble {
+    protected readonly sourceBlock: BlockSvg;
+    /** The type string used to identify this icon. */
+    static readonly TYPE: IconType<WarningIcon>;
+    /**
+     * The weight this icon has relative to other icons. Icons with more positive
+     * weight values are rendered farther toward the end of the block.
+     */
+    static readonly WEIGHT = 2;
+    /** A map of warning IDs to warning text. */
+    private textMap;
+    /** The bubble used to display the warnings to the user. */
+    private textBubble;
+    /** @internal */
+    constructor(sourceBlock: BlockSvg);
+    getType(): IconType<WarningIcon>;
+    initView(pointerdownListener: (e: PointerEvent) => void): void;
+    dispose(): void;
+    getWeight(): number;
+    getSize(): Size;
+    applyColour(): void;
+    updateCollapsed(): void;
+    /** Tells blockly that this icon is shown when the block is collapsed. */
+    isShownWhenCollapsed(): boolean;
+    /** Updates the location of the icon's bubble if it is open. */
+    onLocationChange(blockOrigin: Coordinate): void;
+    /**
+     * Adds a warning message to this warning icon.
+     *
+     * @param text The text of the message to add.
+     * @param id The id of the message to add.
+     * @internal
+     */
+    addMessage(text: string, id: string): this;
+    /**
+     * @returns the display text for this icon. Includes all warning messages
+     *     concatenated together with newlines.
+     * @internal
+     */
+    getText(): string;
+    /** Toggles the visibility of the bubble. */
+    onClick(): void;
+    isClickableInFlyout(): boolean;
+    bubbleIsVisible(): boolean;
+    setBubbleVisible(visible: boolean): Promise<void>;
+    /** See IHasBubble.getBubble. */
+    getBubble(): IBubble | null;
+    /**
+     * @returns the location the bubble should be anchored to.
+     *     I.E. the middle of this icon.
+     */
+    private getAnchorLocation;
+    /**
+     * @returns the rect the bubble should avoid overlapping.
+     *     I.E. the block that owns this icon.
+     */
+    private getBubbleOwnerRect;
+}
+//# sourceMappingURL=warning_icon.d.ts.map

package/core/icons.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { CommentIcon, CommentState } from './icons/comment_icon.js';
+import * as exceptions from './icons/exceptions.js';
+import { Icon } from './icons/icon.js';
+import { IconType } from './icons/icon_types.js';
+import { MutatorIcon } from './icons/mutator_icon.js';
+import * as registry from './icons/registry.js';
+import { WarningIcon } from './icons/warning_icon.js';
+export { CommentIcon, CommentState, exceptions, Icon, IconType, MutatorIcon, registry, WarningIcon, };
+//# sourceMappingURL=icons.d.ts.map

package/core/inject.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @license
+ * Copyright 2011 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { BlocklyOptions } from './blockly_options.js';
+import { WorkspaceSvg } from './workspace_svg.js';
+/**
+ * Inject a Blockly editor into the specified container element (usually a div).
+ *
+ * @param container Containing element, or its ID, or a CSS selector.
+ * @param opt_options Optional dictionary of options.
+ * @returns Newly created main workspace.
+ */
+export declare function inject(container: Element | string, opt_options?: BlocklyOptions): WorkspaceSvg;
+//# sourceMappingURL=inject.d.ts.map

package/core/inputs/align.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @license
+ * Copyright 2012 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Enum for alignment of inputs.
+ */
+export declare enum Align {
+    LEFT = -1,
+    CENTRE = 0,
+    RIGHT = 1
+}
+//# sourceMappingURL=align.d.ts.map

package/core/inputs/dummy_input.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { Block } from '../block.js';
+import { Input } from './input.js';
+import { inputTypes } from './input_types.js';
+/** Represents an input on a block with no connection. */
+export declare class DummyInput extends Input {
+    name: string;
+    readonly type = inputTypes.DUMMY;
+    /**
+     * @param name Language-neutral identifier which may used to find this input
+     *     again.
+     * @param block The block containing this input.
+     */
+    constructor(name: string, block: Block);
+}
+//# sourceMappingURL=dummy_input.d.ts.map

package/core/inputs/end_row_input.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { Block } from '../block.js';
+import { Input } from './input.js';
+import { inputTypes } from './input_types.js';
+/**
+ * Represents an input on a block that is always the last input in the row. Any
+ * following input will be rendered on the next row even if the block has inline
+ * inputs. Any newline character in a JSON block definition's message will
+ * automatically be parsed as an end-row input.
+ */
+export declare class EndRowInput extends Input {
+    name: string;
+    readonly type = inputTypes.END_ROW;
+    /**
+     * @param name Language-neutral identifier which may used to find this input
+     *     again.
+     * @param block The block containing this input.
+     */
+    constructor(name: string, block: Block);
+}
+//# sourceMappingURL=end_row_input.d.ts.map

package/core/inputs/input.d.ts

@@ -0,0 +1,147 @@
+/**
+ * @license
+ * Copyright 2012 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Object representing an input (value, statement, or dummy).
+ *
+ * @class
+ */
+import '../field_label.js';
+import type { Block } from '../block.js';
+import type { BlockSvg } from '../block_svg.js';
+import type { Connection } from '../connection.js';
+import type { ConnectionType } from '../connection_type.js';
+import type { Field } from '../field.js';
+import { Align } from './align.js';
+import { inputTypes } from './input_types.js';
+/** Class for an input with optional fields. */
+export declare class Input {
+    name: string;
+    private sourceBlock;
+    fieldRow: Field[];
+    /** Alignment of input's fields (left, right or centre). */
+    align: Align;
+    /** Is the input visible? */
+    private visible;
+    readonly type: inputTypes;
+    connection: Connection | null;
+    /**
+     * @param name Language-neutral identifier which may used to find this input
+     *     again.
+     * @param sourceBlock The block containing this input.
+     */
+    constructor(name: string, sourceBlock: Block);
+    /**
+     * Get the source block for this input.
+     *
+     * @returns The block this input is part of.
+     */
+    getSourceBlock(): Block;
+    /**
+     * Add a field (or label from string), and all prefix and suffix fields, to
+     * the end of the input's field row.
+     *
+     * @param field Something to add as a field.
+     * @param opt_name Language-neutral identifier which may used to find this
+     *     field again.  Should be unique to the host block.
+     * @returns The input being append to (to allow chaining).
+     */
+    appendField<T>(field: string | Field<T>, opt_name?: string): Input;
+    /**
+     * Inserts a field (or label from string), and all prefix and suffix fields,
+     * at the location of the input's field row.
+     *
+     * @param index The index at which to insert field.
+     * @param field Something to add as a field.
+     * @param opt_name Language-neutral identifier which may used to find this
+     *     field again.  Should be unique to the host block.
+     * @returns The index following the last inserted field.
+     */
+    insertFieldAt<T>(index: number, field: string | Field<T>, opt_name?: string): number;
+    /**
+     * Remove a field from this input.
+     *
+     * @param name The name of the field.
+     * @param opt_quiet True to prevent an error if field is not present.
+     * @returns True if operation succeeds, false if field is not present and
+     *     opt_quiet is true.
+     * @throws {Error} if the field is not present and opt_quiet is false.
+     */
+    removeField(name: string, opt_quiet?: boolean): boolean;
+    /**
+     * Gets whether this input is visible or not.
+     *
+     * @returns True if visible.
+     */
+    isVisible(): boolean;
+    /**
+     * Sets whether this input is visible or not.
+     * Should only be used to collapse/uncollapse a block.
+     *
+     * @param visible True if visible.
+     * @returns List of blocks to render.
+     * @internal
+     */
+    setVisible(visible: boolean): BlockSvg[];
+    /**
+     * Mark all fields on this input as dirty.
+     *
+     * @internal
+     */
+    markDirty(): void;
+    /**
+     * Change a connection's compatibility.
+     *
+     * @param check Compatible value type or list of value types.  Null if all
+     *     types are compatible.
+     * @returns The input being modified (to allow chaining).
+     */
+    setCheck(check: string | string[] | null): Input;
+    /**
+     * Change the alignment of the connection's field(s).
+     *
+     * @param align One of the values of Align.  In RTL mode directions
+     *     are reversed, and Align.RIGHT aligns to the left.
+     * @returns The input being modified (to allow chaining).
+     */
+    setAlign(align: Align): Input;
+    /**
+     * Changes the connection's shadow block.
+     *
+     * @param shadow DOM representation of a block or null.
+     * @returns The input being modified (to allow chaining).
+     */
+    setShadowDom(shadow: Element | null): Input;
+    /**
+     * Returns the XML representation of the connection's shadow block.
+     *
+     * @returns Shadow DOM representation of a block or null.
+     */
+    getShadowDom(): Element | null;
+    /** Initialize the fields on this input. */
+    init(): void;
+    /**
+     * Initializes the fields on this input for a headless block.
+     *
+     * @internal
+     */
+    initModel(): void;
+    /** Initializes the given field. */
+    private initField;
+    /**
+     * Sever all links to this input.
+     */
+    dispose(): void;
+    /**
+     * Constructs a connection based on the type of this input's source block.
+     * Properly handles constructing headless connections for headless blocks
+     * and rendered connections for rendered blocks.
+     *
+     * @returns a connection of the given type, which is either a headless
+     *     or rendered connection, based on the type of this input's source block.
+     */
+    protected makeConnection(type: ConnectionType): Connection;
+}
+//# sourceMappingURL=input.d.ts.map

package/core/inputs/input_types.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Enum for the type of a connection or input.
+ */
+export declare enum inputTypes {
+    VALUE = 1,
+    STATEMENT = 3,
+    DUMMY = 5,
+    CUSTOM = 6,
+    END_ROW = 7
+}
+//# sourceMappingURL=input_types.d.ts.map

package/core/inputs/statement_input.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { Block } from '../block.js';
+import type { Connection } from '../connection.js';
+import { Input } from './input.js';
+import { inputTypes } from './input_types.js';
+/** Represents an input on a block with a statement connection. */
+export declare class StatementInput extends Input {
+    name: string;
+    readonly type = inputTypes.STATEMENT;
+    connection: Connection;
+    /**
+     * @param name Language-neutral identifier which may used to find this input
+     *     again.
+     * @param block The block containing this input.
+     */
+    constructor(name: string, block: Block);
+}
+//# sourceMappingURL=statement_input.d.ts.map

package/core/inputs/value_input.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { Block } from '../block.js';
+import { Input } from './input.js';
+import { inputTypes } from './input_types.js';
+/** Represents an input on a block with a value connection. */
+export declare class ValueInput extends Input {
+    name: string;
+    readonly type = inputTypes.VALUE;
+    /**
+     * @param name Language-neutral identifier which may used to find this input
+     *     again.
+     * @param block The block containing this input.
+     */
+    constructor(name: string, block: Block);
+}
+//# sourceMappingURL=value_input.d.ts.map

package/core/inputs.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Align } from './inputs/align.js';
+import { DummyInput } from './inputs/dummy_input.js';
+import { EndRowInput } from './inputs/end_row_input.js';
+import { Input } from './inputs/input.js';
+import { inputTypes } from './inputs/input_types.js';
+import { StatementInput } from './inputs/statement_input.js';
+import { ValueInput } from './inputs/value_input.js';
+export { Align, DummyInput, EndRowInput, Input, inputTypes, StatementInput, ValueInput, };
+//# sourceMappingURL=inputs.d.ts.map