blockly 12.4.0 → 12.4.1

package/core/interfaces/i_toolbox.d.ts

@@ -0,0 +1,102 @@
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { ToolboxInfo } from '../utils/toolbox.js';
+import type { WorkspaceSvg } from '../workspace_svg.js';
+import type { IFlyout } from './i_flyout.js';
+import type { IFocusableTree } from './i_focusable_tree.js';
+import type { IRegistrable } from './i_registrable.js';
+import type { IToolboxItem } from './i_toolbox_item.js';
+/**
+ * Interface for a toolbox.
+ */
+export interface IToolbox extends IRegistrable, IFocusableTree {
+    /** 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.
+     *
+     * @returns The width of the toolbox.
+     */
+    getWidth(): number;
+    /**
+     * Gets the height of the toolbox.
+     *
+     * @returns The height of the toolbox.
+     */
+    getHeight(): number;
+    /**
+     * Gets the toolbox flyout.
+     *
+     * @returns The toolbox flyout.
+     */
+    getFlyout(): IFlyout | null;
+    /**
+     * Gets the workspace for the toolbox.
+     *
+     * @returns The parent workspace for the toolbox.
+     */
+    getWorkspace(): WorkspaceSvg;
+    /**
+     * Gets whether or not the toolbox is horizontal.
+     *
+     * @returns 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 its position in the list of toolbox items.
+     *
+     * @param position The position of the item to select.
+     */
+    selectItemByPosition(position: number): void;
+    /**
+     * Gets the selected item.
+     *
+     * @returns The selected item, or null if no item is currently selected.
+     */
+    getSelectedItem(): IToolboxItem | null;
+    /**
+     * Sets the selected item.
+     *
+     * @param item The toolbox item to select, or null to remove the current
+     *     selection.
+     */
+    setSelectedItem(item: IToolboxItem | null): void;
+    /** Disposes of this toolbox. */
+    dispose(): void;
+}
+//# sourceMappingURL=i_toolbox.d.ts.map

package/core/interfaces/i_toolbox_item.d.ts

@@ -0,0 +1,71 @@
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { IFocusableNode } from './i_focusable_node.js';
+/**
+ * Interface for an item in the toolbox.
+ */
+export interface IToolboxItem extends IFocusableNode {
+    /**
+     * 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.
+     *
+     * @returns The div for the toolbox item.
+     */
+    getDiv(): Element | null;
+    /**
+     * Gets a unique identifier for this toolbox item.
+     *
+     * @returns The ID for the toolbox item.
+     */
+    getId(): string;
+    /**
+     * Gets the parent if the toolbox item is nested.
+     *
+     * @returns The parent toolbox item, or null if this toolbox item is not
+     *     nested.
+     */
+    getParent(): IToolboxItem | null;
+    /**
+     * Gets the nested level of the category.
+     *
+     * @returns The nested level of the category.
+     * @internal
+     */
+    getLevel(): number;
+    /**
+     * Whether the toolbox item is selectable.
+     *
+     * @returns True if the toolbox item can be selected.
+     */
+    isSelectable(): boolean;
+    /**
+     * Whether the toolbox item is collapsible.
+     *
+     * @returns 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.
+     *
+     * @returns 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;
+}
+//# sourceMappingURL=i_toolbox_item.d.ts.map

package/core/interfaces/i_variable_backed_parameter_model.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { IParameterModel } from './i_parameter_model.js';
+import type { IVariableModel, IVariableState } from './i_variable_model.js';
+/** Interface for a parameter model that holds a variable model. */
+export interface IVariableBackedParameterModel extends IParameterModel {
+    /** Returns the variable model held by this type. */
+    getVariableModel(): IVariableModel<IVariableState>;
+}
+/**
+ * Returns whether the given object is a variable holder or not.
+ */
+export declare function isVariableBackedParameterModel(param: IParameterModel): param is IVariableBackedParameterModel;
+//# sourceMappingURL=i_variable_backed_parameter_model.d.ts.map

package/core/interfaces/i_variable_map.d.ts

@@ -0,0 +1,48 @@
+/**
+ * @license
+ * Copyright 2024 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { IVariableModel, IVariableState } from './i_variable_model.js';
+/**
+ * Variable maps are container objects responsible for storing and managing the
+ * set of variables referenced on a workspace.
+ *
+ * Any of these methods may define invariants about which names and types are
+ * legal, and throw if they are not met.
+ */
+export interface IVariableMap<T extends IVariableModel<IVariableState>> {
+    getVariableById(id: string): T | null;
+    /**
+     * Returns the variable with the given name, or null if not found. If `type`
+     * is provided, the variable's type must also match, or null should be
+     * returned.
+     */
+    getVariable(name: string, type?: string): T | null;
+    getAllVariables(): T[];
+    /**
+     * Returns a list of all of the variables of the given type managed by this
+     * variable map.
+     */
+    getVariablesOfType(type: string): T[];
+    /**
+     * Returns a list of the set of types of the variables managed by this
+     * variable map.
+     */
+    getTypes(): string[];
+    /**
+     * Creates a new variable with the given name. If ID is not specified, the
+     * variable map should create one. Returns the new variable.
+     */
+    createVariable(name: string, type?: string, id?: string | null): T;
+    addVariable(variable: T): void;
+    /**
+     * Changes the name of the given variable to the name provided and returns the
+     * renamed variable.
+     */
+    renameVariable(variable: T, newName: string): T;
+    changeVariableType(variable: T, newType: string): T;
+    deleteVariable(variable: T): void;
+    clear(): void;
+}
+//# sourceMappingURL=i_variable_map.d.ts.map

package/core/interfaces/i_variable_model.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @license
+ * Copyright 2024 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { Workspace } from '../workspace.js';
+export interface IVariableModel<T extends IVariableState> {
+    getId(): string;
+    getName(): string;
+    /**
+     * Returns the type of the variable like 'int' or 'string'.  Does not need to be
+     * unique. This will default to '' which is a specific type.
+     */
+    getType(): string;
+    setName(name: string): this;
+    setType(type: string): this;
+    getWorkspace(): Workspace;
+    save(): T;
+}
+export interface IVariableModelStatic<T extends IVariableState> {
+    new (workspace: Workspace, name: string, type?: string, id?: string): IVariableModel<T>;
+    /**
+     * Creates a new IVariableModel corresponding to the given state on the
+     * specified workspace. This method must be static in your implementation.
+     */
+    load(state: T, workspace: Workspace): IVariableModel<T>;
+}
+/**
+ * Represents the state of a given variable.
+ */
+export interface IVariableState {
+    name: string;
+    id: string;
+    type?: string;
+}
+//# sourceMappingURL=i_variable_model.d.ts.map

package/core/internal_constants.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Number of characters to truncate a collapsed block to.
+ *
+ * @internal
+ */
+export declare const COLLAPSE_CHARS = 30;
+/**
+ * Lookup table for determining the opposite type of a connection.
+ *
+ * @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.
+ *
+ * @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.
+ *
+ * @internal
+ */
+export declare const DELETE_VARIABLE_ID = "DELETE_VARIABLE_ID";
+//# sourceMappingURL=internal_constants.d.ts.map

package/core/keyboard_nav/block_comment_navigation_policy.d.ts

@@ -0,0 +1,56 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { TextInputBubble } from '../bubbles/textinput_bubble.js';
+import type { IFocusableNode } from '../interfaces/i_focusable_node.js';
+import type { INavigationPolicy } from '../interfaces/i_navigation_policy.js';
+/**
+ * Set of rules controlling keyboard navigation from an TextInputBubble.
+ */
+export declare class BlockCommentNavigationPolicy implements INavigationPolicy<TextInputBubble> {
+    /**
+     * Returns the first child of the given block comment.
+     *
+     * @param current The block comment to return the first child of.
+     * @returns The text editor of the given block comment bubble.
+     */
+    getFirstChild(current: TextInputBubble): IFocusableNode | null;
+    /**
+     * Returns the parent of the given block comment.
+     *
+     * @param current The block comment to return the parent of.
+     * @returns The parent block of the given block comment.
+     */
+    getParent(current: TextInputBubble): IFocusableNode | null;
+    /**
+     * Returns the next peer node of the given block comment.
+     *
+     * @param _current The block comment to find the following element of.
+     * @returns Null.
+     */
+    getNextSibling(_current: TextInputBubble): IFocusableNode | null;
+    /**
+     * Returns the previous peer node of the given block comment.
+     *
+     * @param _current The block comment to find the preceding element of.
+     * @returns Null.
+     */
+    getPreviousSibling(_current: TextInputBubble): IFocusableNode | null;
+    /**
+     * Returns whether or not the given block comment can be navigated to.
+     *
+     * @param current The instance to check for navigability.
+     * @returns True if the given block comment can be focused.
+     */
+    isNavigable(current: TextInputBubble): boolean;
+    /**
+     * Returns whether the given object can be navigated from by this policy.
+     *
+     * @param current The object to check if this policy applies to.
+     * @returns True if the object is an TextInputBubble.
+     */
+    isApplicable(current: any): current is TextInputBubble;
+}
+//# sourceMappingURL=block_comment_navigation_policy.d.ts.map

package/core/keyboard_nav/block_navigation_policy.d.ts

@@ -0,0 +1,84 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { BlockSvg } from '../block_svg.js';
+import type { Field } from '../field.js';
+import type { Icon } from '../icons/icon.js';
+import type { IFocusableNode } from '../interfaces/i_focusable_node.js';
+import type { INavigationPolicy } from '../interfaces/i_navigation_policy.js';
+import type { ISelectable } from '../interfaces/i_selectable.js';
+import { RenderedConnection } from '../rendered_connection.js';
+/**
+ * Set of rules controlling keyboard navigation from a block.
+ */
+export declare class BlockNavigationPolicy implements INavigationPolicy<BlockSvg> {
+    /**
+     * Returns the first child of the given block.
+     *
+     * @param current The block to return the first child of.
+     * @returns The first field or input of the given block, if any.
+     */
+    getFirstChild(current: BlockSvg): IFocusableNode | null;
+    /**
+     * Returns the parent of the given block.
+     *
+     * @param current The block to return the parent of.
+     * @returns The top block of the given block's stack, or the connection to
+     *     which it is attached.
+     */
+    getParent(current: BlockSvg): IFocusableNode | null;
+    /**
+     * Returns the next peer node of the given block.
+     *
+     * @param current The block to find the following element of.
+     * @returns The first node of the next input/stack if the given block is a terminal
+     *     block, or its next connection.
+     */
+    getNextSibling(current: BlockSvg): IFocusableNode | null;
+    /**
+     * Returns the previous peer node of the given block.
+     *
+     * @param current The block to find the preceding element of.
+     * @returns The block's previous/output connection, or the last
+     *     connection/block of the previous block stack if it is a root block.
+     */
+    getPreviousSibling(current: BlockSvg): IFocusableNode | null;
+    /**
+     * Returns whether or not the given block can be navigated to.
+     *
+     * @param current The instance to check for navigability.
+     * @returns True if the given block can be focused.
+     */
+    isNavigable(current: BlockSvg): boolean;
+    /**
+     * Returns whether the given object can be navigated from by this policy.
+     *
+     * @param current The object to check if this policy applies to.
+     * @returns True if the object is a BlockSvg.
+     */
+    isApplicable(current: any): current is BlockSvg;
+}
+/**
+ * Returns the next/previous stack relative to the given element's stack.
+ *
+ * @param current The element whose stack will be navigated relative to.
+ * @param delta The difference in index to navigate; positive values navigate
+ *     to the nth next stack, while negative values navigate to the nth previous
+ *     stack.
+ * @returns The first element in the stack offset by `delta` relative to the
+ *     current element's stack, or the last element in the stack offset by
+ * `delta` relative to the current element's stack when navigating backwards.
+ */
+export declare function navigateStacks(current: ISelectable, delta: number): IFocusableNode | null;
+/**
+ * Returns the next navigable item relative to the provided block child.
+ *
+ * @param current The navigable block child item to navigate relative to.
+ * @param delta The difference in index to navigate; positive values navigate
+ *     forward by n, while negative values navigate backwards by n.
+ * @returns The navigable block child offset by `delta` relative to `current`.
+ */
+export declare function navigateBlock(current: Icon | Field | RenderedConnection | BlockSvg, delta: number): IFocusableNode | null;
+//# sourceMappingURL=block_navigation_policy.d.ts.map

package/core/keyboard_nav/comment_bar_button_navigation_policy.d.ts

@@ -0,0 +1,56 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { CommentBarButton } from '../comments/comment_bar_button.js';
+import type { IFocusableNode } from '../interfaces/i_focusable_node.js';
+import type { INavigationPolicy } from '../interfaces/i_navigation_policy.js';
+/**
+ * Set of rules controlling keyboard navigation from a CommentBarButton.
+ */
+export declare class CommentBarButtonNavigationPolicy implements INavigationPolicy<CommentBarButton> {
+    /**
+     * Returns the first child of the given CommentBarButton.
+     *
+     * @param _current The CommentBarButton to return the first child of.
+     * @returns Null.
+     */
+    getFirstChild(_current: CommentBarButton): IFocusableNode | null;
+    /**
+     * Returns the parent of the given CommentBarButton.
+     *
+     * @param current The CommentBarButton to return the parent of.
+     * @returns The parent comment of the given CommentBarButton.
+     */
+    getParent(current: CommentBarButton): IFocusableNode | null;
+    /**
+     * Returns the next peer node of the given CommentBarButton.
+     *
+     * @param current The CommentBarButton to find the following element of.
+     * @returns The next CommentBarButton, if any.
+     */
+    getNextSibling(current: CommentBarButton): IFocusableNode | null;
+    /**
+     * Returns the previous peer node of the given CommentBarButton.
+     *
+     * @param current The CommentBarButton to find the preceding element of.
+     * @returns The CommentBarButton's previous CommentBarButton, if any.
+     */
+    getPreviousSibling(current: CommentBarButton): IFocusableNode | null;
+    /**
+     * Returns whether or not the given CommentBarButton can be navigated to.
+     *
+     * @param current The instance to check for navigability.
+     * @returns True if the given CommentBarButton can be focused.
+     */
+    isNavigable(current: CommentBarButton): boolean;
+    /**
+     * Returns whether the given object can be navigated from by this policy.
+     *
+     * @param current The object to check if this policy applies to.
+     * @returns True if the object is an CommentBarButton.
+     */
+    isApplicable(current: any): current is CommentBarButton;
+}
+//# sourceMappingURL=comment_bar_button_navigation_policy.d.ts.map

package/core/keyboard_nav/comment_editor_navigation_policy.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { CommentEditor } from '../comments/comment_editor.js';
+import type { IFocusableNode } from '../interfaces/i_focusable_node.js';
+import type { INavigationPolicy } from '../interfaces/i_navigation_policy.js';
+/**
+ * Set of rules controlling keyboard navigation from a comment editor.
+ * This is a no-op placeholder (other than isNavigable/isApplicable) since
+ * comment editors handle their own navigation when editing ends.
+ */
+export declare class CommentEditorNavigationPolicy implements INavigationPolicy<CommentEditor> {
+    getFirstChild(_current: CommentEditor): IFocusableNode | null;
+    getParent(_current: CommentEditor): IFocusableNode | null;
+    getNextSibling(_current: CommentEditor): IFocusableNode | null;
+    getPreviousSibling(_current: CommentEditor): IFocusableNode | null;
+    /**
+     * Returns whether or not the given comment editor can be navigated to.
+     *
+     * @param current The instance to check for navigability.
+     * @returns False.
+     */
+    isNavigable(current: CommentEditor): boolean;
+    /**
+     * Returns whether the given object can be navigated from by this policy.
+     *
+     * @param current The object to check if this policy applies to.
+     * @returns True if the object is a CommentEditor.
+     */
+    isApplicable(current: any): current is CommentEditor;
+}
+//# sourceMappingURL=comment_editor_navigation_policy.d.ts.map

package/core/keyboard_nav/connection_navigation_policy.d.ts

@@ -0,0 +1,67 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { BlockSvg } from '../block_svg.js';
+import type { IFocusableNode } from '../interfaces/i_focusable_node.js';
+import type { INavigationPolicy } from '../interfaces/i_navigation_policy.js';
+import { RenderedConnection } from '../rendered_connection.js';
+/**
+ * Set of rules controlling keyboard navigation from a connection.
+ */
+export declare class ConnectionNavigationPolicy implements INavigationPolicy<RenderedConnection> {
+    /**
+     * Returns the first child of the given connection.
+     *
+     * @param current The connection to return the first child of.
+     * @returns The connection's first child element, or null if not none.
+     */
+    getFirstChild(current: RenderedConnection): IFocusableNode | null;
+    /**
+     * Returns the parent of the given connection.
+     *
+     * @param current The connection to return the parent of.
+     * @returns The given connection's parent connection or block.
+     */
+    getParent(current: RenderedConnection): IFocusableNode | null;
+    /**
+     * Returns the next element following the given connection.
+     *
+     * @param current The connection to navigate from.
+     * @returns The field, input connection or block following this connection.
+     */
+    getNextSibling(current: RenderedConnection): IFocusableNode | null;
+    /**
+     * Returns the element preceding the given connection.
+     *
+     * @param current The connection to navigate from.
+     * @returns The field, input connection or block preceding this connection.
+     */
+    getPreviousSibling(current: RenderedConnection): IFocusableNode | null;
+    /**
+     * Gets the parent connection on a block.
+     * This is either an output connection, previous connection or undefined.
+     * If both connections exist return the one that is actually connected
+     * to another block.
+     *
+     * @param block The block to find the parent connection on.
+     * @returns The connection connecting to the parent of the block.
+     */
+    protected getParentConnection(block: BlockSvg): RenderedConnection;
+    /**
+     * Returns whether or not the given connection can be navigated to.
+     *
+     * @param current The instance to check for navigability.
+     * @returns True if the given connection can be focused.
+     */
+    isNavigable(current: RenderedConnection): boolean;
+    /**
+     * Returns whether the given object can be navigated from by this policy.
+     *
+     * @param current The object to check if this policy applies to.
+     * @returns True if the object is a RenderedConnection.
+     */
+    isApplicable(current: any): current is RenderedConnection;
+}
+//# sourceMappingURL=connection_navigation_policy.d.ts.map

package/core/keyboard_nav/field_navigation_policy.d.ts

@@ -0,0 +1,56 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Field } from '../field.js';
+import type { IFocusableNode } from '../interfaces/i_focusable_node.js';
+import type { INavigationPolicy } from '../interfaces/i_navigation_policy.js';
+/**
+ * Set of rules controlling keyboard navigation from a field.
+ */
+export declare class FieldNavigationPolicy implements INavigationPolicy<Field<any>> {
+    /**
+     * Returns null since fields do not have children.
+     *
+     * @param _current The field to navigate from.
+     * @returns Null.
+     */
+    getFirstChild(_current: Field<any>): IFocusableNode | null;
+    /**
+     * Returns the parent block of the given field.
+     *
+     * @param current The field to navigate from.
+     * @returns The given field's parent block.
+     */
+    getParent(current: Field<any>): IFocusableNode | null;
+    /**
+     * Returns the next field or input following the given field.
+     *
+     * @param current The field to navigate from.
+     * @returns The next field or input in the given field's block.
+     */
+    getNextSibling(current: Field<any>): IFocusableNode | null;
+    /**
+     * Returns the field or input preceding the given field.
+     *
+     * @param current The field to navigate from.
+     * @returns The preceding field or input in the given field's block.
+     */
+    getPreviousSibling(current: Field<any>): IFocusableNode | null;
+    /**
+     * Returns whether or not the given field can be navigated to.
+     *
+     * @param current The instance to check for navigability.
+     * @returns True if the given field can be focused and navigated to.
+     */
+    isNavigable(current: Field<any>): boolean;
+    /**
+     * Returns whether the given object can be navigated from by this policy.
+     *
+     * @param current The object to check if this policy applies to.
+     * @returns True if the object is a Field.
+     */
+    isApplicable(current: any): current is Field;
+}
+//# sourceMappingURL=field_navigation_policy.d.ts.map