blockly 12.4.0 → 12.5.0

package/core/interfaces/i_flyout.d.ts

@@ -0,0 +1,159 @@
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { BlockSvg } from '../block_svg.js';
+import type { FlyoutItem } from '../flyout_item.js';
+import type { Coordinate } from '../utils/coordinate.js';
+import type { Svg } from '../utils/svg.js';
+import type { FlyoutDefinition } from '../utils/toolbox.js';
+import type { WorkspaceSvg } from '../workspace_svg.js';
+import { IFocusableTree } from './i_focusable_tree.js';
+import type { IRegistrable } from './i_registrable.js';
+/**
+ * Interface for a flyout.
+ */
+export interface IFlyout extends IRegistrable, IFocusableTree {
+    /** Whether the flyout is laid out horizontally or not. */
+    horizontalLayout: boolean;
+    /** Is RTL vs LTR. */
+    RTL: boolean;
+    /** The target workspace */
+    targetWorkspace: WorkspaceSvg | null;
+    /** Margin around the edges of the blocks in the flyout. */
+    readonly MARGIN: number;
+    /** Does the flyout automatically close when a block is created? */
+    autoClose: boolean;
+    /** Corner radius of the flyout background. */
+    readonly CORNER_RADIUS: number;
+    /**
+     * Creates the flyout's DOM.  Only needs to be called once.  The flyout can
+     * either exist as its own svg element or be a g element nested inside a
+     * separate svg element.
+     *
+     * @param tagName The type of tag to put the flyout in. This should be <svg>
+     *     or <g>.
+     * @returns The flyout's SVG group.
+     */
+    createDom(tagName: string | Svg<SVGSVGElement> | Svg<SVGGElement>): SVGElement;
+    /**
+     * Initializes the flyout.
+     *
+     * @param targetWorkspace The workspace in which to create new blocks.
+     */
+    init(targetWorkspace: WorkspaceSvg): void;
+    /**
+     * Dispose of this flyout.
+     * Unlink from all DOM elements to prevent memory leaks.
+     */
+    dispose(): void;
+    /**
+     * Get the width of the flyout.
+     *
+     * @returns The width of the flyout.
+     */
+    getWidth(): number;
+    /**
+     * Get the height of the flyout.
+     *
+     * @returns The height of the flyout.
+     */
+    getHeight(): number;
+    /**
+     * Get the workspace inside the flyout.
+     *
+     * @returns The workspace inside the flyout.
+     */
+    getWorkspace(): WorkspaceSvg;
+    /**
+     * Is the flyout visible?
+     *
+     * @returns True if visible.
+     */
+    isVisible(): boolean;
+    /**
+     * Set whether the flyout is visible. A value of true does not necessarily
+     * mean that the flyout is shown. It could be hidden because its container is
+     * hidden.
+     *
+     * @param visible True if visible.
+     */
+    setVisible(visible: boolean): void;
+    /**
+     * Set whether this flyout's container is visible.
+     *
+     * @param visible Whether the container is visible.
+     */
+    setContainerVisible(visible: boolean): void;
+    /** Hide and empty the flyout. */
+    hide(): void;
+    /**
+     * Show and populate the flyout.
+     *
+     * @param flyoutDef Contents to display in the flyout. This is either an array
+     *     of Nodes, a NodeList, a toolbox definition, or a string with the name
+     *     of the dynamic category.
+     */
+    show(flyoutDef: FlyoutDefinition | string): void;
+    /**
+     * Returns the list of flyout items currently present in the flyout.
+     * The `show` method parses the flyout definition into a list of actual
+     * flyout items. This method should return those concrete items, which
+     * may be used for e.g. keyboard navigation.
+     *
+     * @returns List of flyout items.
+     */
+    getContents(): FlyoutItem[];
+    /**
+     * Create a copy of this block on the workspace.
+     *
+     * @param originalBlock The block to copy from the flyout.
+     * @returns The newly created block.
+     * @throws {Error} if something went wrong with deserialization.
+     */
+    createBlock(originalBlock: BlockSvg): BlockSvg;
+    /** Reflow blocks and their mats. */
+    reflow(): void;
+    /**
+     * @returns True if this flyout may be scrolled with a scrollbar or by
+     *     dragging.
+     */
+    isScrollable(): boolean;
+    /**
+     * Calculates the x coordinate for the flyout position.
+     *
+     * @returns X coordinate.
+     */
+    getX(): number;
+    /**
+     * Calculates the y coordinate for the flyout position.
+     *
+     * @returns Y coordinate.
+     */
+    getY(): number;
+    /** Position the flyout. */
+    position(): void;
+    /**
+     * Determine if a drag delta is toward the workspace, based on the position
+     * and orientation of the flyout. This is used in determineDragIntention_ to
+     * determine if a new block should be created or if the flyout should scroll.
+     *
+     * @param currentDragDeltaXY How far the pointer has moved from the position
+     *     at mouse down, in pixel units.
+     * @returns True if the drag is toward the workspace.
+     */
+    isDragTowardWorkspace(currentDragDeltaXY: Coordinate): boolean;
+    /**
+     * Does this flyout allow you to create a new instance of the given block?
+     * Used for deciding if a block can be "dragged out of" the flyout.
+     *
+     * @param block The block to copy from the flyout.
+     * @returns True if you can create a new instance of the block, false
+     *     otherwise.
+     */
+    isBlockCreatable(block: BlockSvg): boolean;
+    /** Scroll the flyout to the beginning of its contents. */
+    scrollToStart(): void;
+}
+//# sourceMappingURL=i_flyout.d.ts.map

package/core/interfaces/i_flyout_inflater.d.ts

@@ -0,0 +1,48 @@
+import type { FlyoutItem } from '../flyout_item.js';
+import type { IFlyout } from './i_flyout.js';
+export interface IFlyoutInflater {
+    /**
+     * Loads the object represented by the given state onto the workspace.
+     *
+     * Note that this method's interface is identical to that in ISerializer, to
+     * allow for code reuse.
+     *
+     * @param state A JSON representation of an element to inflate on the flyout.
+     * @param flyout The flyout on whose workspace the inflated element
+     *    should be created. If the inflated element is an `IRenderedElement` it
+     *    itself or the inflater should append it to the workspace; the flyout
+     *    will not do so itself. The flyout is responsible for positioning the
+     *    element, however.
+     * @returns The newly inflated flyout element.
+     */
+    load(state: object, flyout: IFlyout): FlyoutItem;
+    /**
+     * Returns the amount of spacing that should follow the element corresponding
+     * to the given JSON representation.
+     *
+     * @param state A JSON representation of the element preceding the gap.
+     * @param defaultGap The default gap for elements in this flyout.
+     * @returns The gap that should follow the given element.
+     */
+    gapForItem(state: object, defaultGap: number): number;
+    /**
+     * Disposes of the given element.
+     *
+     * If the element in question resides on the flyout workspace, it should remove
+     * itself. Implementers are not otherwise required to fully dispose of the
+     * element; it may be e.g. cached for performance purposes.
+     *
+     * @param element The flyout element to dispose of.
+     */
+    disposeItem(item: FlyoutItem): void;
+    /**
+     * Returns the type of items that this inflater is responsible for inflating.
+     * This should be the same as the name under which this inflater registers
+     * itself, as well as the value returned by `getType()` on the `FlyoutItem`
+     * objects returned by `load()`.
+     *
+     * @returns The type of items this inflater creates.
+     */
+    getType(): string;
+}
+//# sourceMappingURL=i_flyout_inflater.d.ts.map

package/core/interfaces/i_focusable_node.d.ts

@@ -0,0 +1,105 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { IFocusableTree } from './i_focusable_tree.js';
+/** Represents anything that can have input focus. */
+export interface IFocusableNode {
+    /**
+     * Returns the DOM element that can be explicitly requested to receive focus.
+     *
+     * IMPORTANT: Please note that this element is expected to have a visual
+     * presence on the page as it will both be explicitly focused and have its
+     * style changed depending on its current focus state (i.e. blurred, actively
+     * focused, and passively focused). The element will have one of two styles
+     * attached (where no style indicates blurred/not focused):
+     * - blocklyActiveFocus
+     * - blocklyPassiveFocus
+     *
+     * The returned element must also have a valid ID specified, and this ID
+     * should be unique across the entire page. Failing to have a properly unique
+     * ID could result in trying to focus one node (such as via a mouse click)
+     * leading to another node with the same ID actually becoming focused by
+     * FocusManager.
+     *
+     * The returned element must be visible if the node is ever focused via
+     * FocusManager.focusNode() or FocusManager.focusTree(). It's allowed for an
+     * element to be hidden until onNodeFocus() is called, or become hidden with a
+     * call to onNodeBlur().
+     *
+     * It's expected the actual returned element will not change for the lifetime
+     * of the node (that is, its properties can change but a new element should
+     * never be returned). Also, the returned element will have its tabindex
+     * overwritten throughout the lifecycle of this node and FocusManager.
+     *
+     * If a node requires the ability to be focused directly without first being
+     * focused via FocusManager then it must set its own tab index.
+     *
+     * @returns The HTMLElement or SVGElement which can both receive focus and be
+     *     visually represented as actively or passively focused for this node.
+     */
+    getFocusableElement(): HTMLElement | SVGElement;
+    /**
+     * Returns the closest parent tree of this node (in cases where a tree has
+     * distinct trees underneath it), which represents the tree to which this node
+     * belongs.
+     *
+     * @returns The node's IFocusableTree.
+     */
+    getFocusableTree(): IFocusableTree;
+    /**
+     * Called when this node receives active focus.
+     *
+     * Note that it's fine for implementations to change visibility modifiers, but
+     * they should avoid the following:
+     * - Creating or removing DOM elements (including via the renderer or drawer).
+     * - Affecting focus via DOM focus() calls or the FocusManager.
+     *
+     * Implementations may consider scrolling themselves into view here; that is
+     * not handled by the focus manager.
+     */
+    onNodeFocus(): void;
+    /**
+     * Called when this node loses active focus. It may still have passive focus.
+     *
+     * This has the same implementation restrictions as onNodeFocus().
+     */
+    onNodeBlur(): void;
+    /**
+     * Indicates whether this node allows focus. If this returns false then none
+     * of the other IFocusableNode methods will be called.
+     *
+     * Note that special care must be taken if implementations of this function
+     * dynamically change their return value value over the lifetime of the node
+     * as certain environment conditions could affect the focusability of this
+     * node's DOM element (such as whether the element has a positive or zero
+     * tabindex). Also, changing from a true to a false value while the node holds
+     * focus will not immediately change the current focus of the node nor
+     * FocusManager's internal state, and thus may result in some of the node's
+     * functions being called later on when defocused (since it was previously
+     * considered focusable at the time of being focused).
+     *
+     * Implementations should generally always return true here unless there are
+     * circumstances under which this node should be skipped for focus
+     * considerations. Examples may include being disabled, read-only, a purely
+     * visual decoration, or a node with no visual representation that must
+     * implement this interface (e.g. due to a parent interface extending it).
+     * Keep in mind accessibility best practices when determining whether a node
+     * should be focusable since even disabled and read-only elements are still
+     * often relevant to providing organizational context to users (particularly
+     * when using a screen reader).
+     *
+     * @returns Whether this node can be focused by FocusManager.
+     */
+    canBeFocused(): boolean;
+}
+/**
+ * Determines whether the provided object fulfills the contract of
+ * IFocusableNode.
+ *
+ * @param obj The object to test.
+ * @returns Whether the provided object can be used as an IFocusableNode.
+ */
+export declare function isFocusableNode(obj: any): obj is IFocusableNode;
+//# sourceMappingURL=i_focusable_node.d.ts.map

package/core/interfaces/i_focusable_tree.d.ts

@@ -0,0 +1,125 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { IFocusableNode } from './i_focusable_node.js';
+/**
+ * Represents a tree of focusable elements with its own active/passive focus
+ * context.
+ *
+ * Note that focus is handled by FocusManager, and tree implementations can have
+ * at most one IFocusableNode focused at one time. If the tree itself has focus,
+ * then the tree's focused node is considered 'active' ('passive' if another
+ * tree has focus).
+ *
+ * Focus is shared between one or more trees, where each tree can have exactly
+ * one active or passive node (and only one active node can exist on the whole
+ * page at any given time). The idea of passive focus is to provide context to
+ * users on where their focus will be restored upon navigating back to a
+ * previously focused tree.
+ *
+ * Note that if the tree's current focused node (passive or active) is needed,
+ * FocusableTreeTraverser.findFocusedNode can be used.
+ *
+ * Note that if specific nodes are needed to be retrieved for this tree, either
+ * use lookUpFocusableNode or FocusableTreeTraverser.findFocusableNodeFor.
+ */
+export interface IFocusableTree {
+    /**
+     * Returns the top-level focusable node of the tree.
+     *
+     * It's expected that the returned node will be focused in cases where
+     * FocusManager wants to focus a tree in a situation where it does not
+     * currently have a focused node.
+     */
+    getRootFocusableNode(): IFocusableNode;
+    /**
+     * Returns the IFocusableNode of this tree that should receive active focus
+     * when the tree itself has focus returned to it.
+     *
+     * There are some very important notes to consider about a tree's focus
+     * lifecycle when implementing a version of this method that doesn't return
+     * null:
+     * 1. A null previousNode does not guarantee first-time focus state as nodes
+     *    can be deleted.
+     * 2. This method is only used when the tree itself is focused, either through
+     *    tab navigation or via FocusManager.focusTree(). In many cases, the
+     *    previously focused node will be directly focused instead which will
+     *    bypass this method.
+     * 3. The default behavior (i.e. returning null here) involves either
+     *    restoring the previous node (previousNode) or focusing the tree's root.
+     * 4. The provided node may sometimes no longer be valid, such as in the case
+     *    an attempt is made to focus a node that has been recently removed from
+     *    its parent tree. Implementations can check for the validity of the node
+     *    in order to specialize the node to which focus should fall back.
+     *
+     * This method is largely intended to provide tree implementations with the
+     * means of specifying a better default node than their root.
+     *
+     * @param previousNode The node that previously held passive focus for this
+     *     tree, or null if the tree hasn't yet been focused.
+     * @returns The IFocusableNode that should now receive focus, or null if
+     *     default behavior should be used, instead.
+     */
+    getRestoredFocusableNode(previousNode: IFocusableNode | null): IFocusableNode | null;
+    /**
+     * Returns all directly nested trees under this tree.
+     *
+     * Note that the returned list of trees doesn't need to be stable, however all
+     * returned trees *do* need to be registered with FocusManager. Additionally,
+     * this must return actual nested trees as omitting a nested tree will affect
+     * how focus changes map to a specific node and its tree, potentially leading
+     * to user confusion.
+     */
+    getNestedTrees(): Array<IFocusableTree>;
+    /**
+     * Returns the IFocusableNode corresponding to the specified element ID, or
+     * null if there's no exact node within this tree with that ID or if the ID
+     * corresponds to the root of the tree.
+     *
+     * This will never match against nested trees.
+     *
+     * @param id The ID of the node's focusable HTMLElement or SVGElement.
+     */
+    lookUpFocusableNode(id: string): IFocusableNode | null;
+    /**
+     * Called when a node of this tree has received active focus.
+     *
+     * Note that a null previousTree does not necessarily indicate that this is
+     * the first time Blockly is receiving focus. In fact, few assumptions can be
+     * made about previous focus state as a previous null tree simply indicates
+     * that Blockly did not hold active focus prior to this tree becoming focused
+     * (which can happen due to focus exiting the Blockly injection div, or for
+     * other cases like ephemeral focus).
+     *
+     * See IFocusableNode.onNodeFocus() as implementations have the same
+     * restrictions as with that method.
+     *
+     * @param node The node receiving active focus.
+     * @param previousTree The previous tree that held active focus, or null if
+     *     none.
+     */
+    onTreeFocus(node: IFocusableNode, previousTree: IFocusableTree | null): void;
+    /**
+     * Called when the previously actively focused node of this tree is now
+     * passively focused and there is no other active node of this tree taking its
+     * place.
+     *
+     * This has the same implementation restrictions and considerations as
+     * onTreeFocus().
+     *
+     * @param nextTree The next tree receiving active focus, or null if none (such
+     *     as in the case that Blockly is entirely losing DOM focus).
+     */
+    onTreeBlur(nextTree: IFocusableTree | null): void;
+}
+/**
+ * Determines whether the provided object fulfills the contract of
+ * IFocusableTree.
+ *
+ * @param obj The object to test.
+ * @returns Whether the provided object can be used as an IFocusableTree.
+ */
+export declare function isFocusableTree(obj: any): obj is IFocusableTree;
+//# sourceMappingURL=i_focusable_tree.d.ts.map

package/core/interfaces/i_has_bubble.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { IBubble } from './i_bubble';
+export interface IHasBubble {
+    /** @returns True if the bubble is currently open, false otherwise. */
+    bubbleIsVisible(): boolean;
+    /** Sets whether the bubble is open or not. */
+    setBubbleVisible(visible: boolean): Promise<void>;
+    /**
+     * Returns the current IBubble that implementations are managing, or null if
+     * there isn't one.
+     *
+     * Note that this cannot be expected to return null if bubbleIsVisible()
+     * returns false, i.e., the nullability of the returned bubble does not
+     * necessarily imply visibility.
+     *
+     * @returns The current IBubble maintained by implementations, or null if
+     *     there is not one.
+     */
+    getBubble(): IBubble | null;
+}
+/** Type guard that checks whether the given object is a IHasBubble. */
+export declare function hasBubble(obj: any): obj is IHasBubble;
+//# sourceMappingURL=i_has_bubble.d.ts.map

package/core/interfaces/i_icon.d.ts

@@ -0,0 +1,84 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { IconType } from '../icons/icon_types.js';
+import type { Coordinate } from '../utils/coordinate.js';
+import type { Size } from '../utils/size.js';
+import { IFocusableNode } from './i_focusable_node.js';
+export interface IIcon extends IFocusableNode {
+    /**
+     * @returns the IconType representing the type of the icon. This value should
+     *     also be used to register the icon via `Blockly.icons.registry.register`.
+     */
+    getType(): IconType<IIcon>;
+    /**
+     * Creates the SVG elements for the icon that will live on the block.
+     *
+     * @param pointerdownListener An event listener that must be attached to the
+     *     root SVG element by the implementation of `initView`. Used by Blockly's
+     *     gesture system to properly handle clicks and drags.
+     */
+    initView(pointerdownListener: (e: PointerEvent) => void): void;
+    /**
+     * Disposes of any elements of the icon.
+     *
+     * @remarks
+     *
+     * In particular, if this icon is currently showing a bubble, this should be
+     * used to hide it.
+     */
+    dispose(): void;
+    /**
+     * @returns the "weight" of the icon, which determines the static order which
+     *     icons should be rendered in. More positive numbers are rendered farther
+     *     toward the end of the block.
+     */
+    getWeight(): number;
+    /** @returns The dimensions of the icon for use in rendering. */
+    getSize(): Size;
+    /** Updates the icon's color when the block's color changes.. */
+    applyColour(): void;
+    /** Hides the icon when it is part of an insertion marker. */
+    hideForInsertionMarker(): void;
+    /** Updates the icon's editability when the block's editability changes. */
+    updateEditable(): void;
+    /**
+     * Updates the icon's collapsed-ness/view when the block's collapsed-ness
+     * changes.
+     */
+    updateCollapsed(): void;
+    /**
+     * @returns Whether this icon is shown when the block is collapsed. Used
+     *     to allow renderers to account for padding.
+     */
+    isShownWhenCollapsed(): boolean;
+    /**
+     * Notifies the icon where it is relative to its block's top-start, in
+     * workspace units.
+     */
+    setOffsetInBlock(offset: Coordinate): void;
+    /**
+     * Notifies the icon that it has changed locations.
+     *
+     * @param blockOrigin The location of this icon's block's top-start corner
+     *     in workspace coordinates.
+     */
+    onLocationChange(blockOrigin: Coordinate): void;
+    /**
+     * Notifies the icon that it has been clicked.
+     */
+    onClick(): void;
+    /**
+     * Check whether the icon should be clickable while the block is in a flyout.
+     * If this function is not defined, the icon will be clickable in all flyouts.
+     *
+     * @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;
+}
+/** Type guard that checks whether the given object is an IIcon. */
+export declare function isIcon(obj: any): obj is IIcon;
+//# sourceMappingURL=i_icon.d.ts.map

package/core/interfaces/i_keyboard_accessible.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { KeyboardShortcut } from '../shortcut_registry.js';
+/**
+ * An interface for an object that handles keyboard shortcuts.
+ */
+export interface IKeyboardAccessible {
+    /**
+     * Handles the given keyboard shortcut.
+     *
+     * @param shortcut The shortcut to be handled.
+     * @returns True if the shortcut has been handled, false otherwise.
+     */
+    onShortcut(shortcut: KeyboardShortcut): boolean;
+}
+//# sourceMappingURL=i_keyboard_accessible.d.ts.map

package/core/interfaces/i_legacy_procedure_blocks.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Legacy means of representing a procedure signature. The elements are
+ * respectively: name, parameter names, and whether it has a return value.
+ */
+export type ProcedureTuple = [string, string[], boolean];
+/**
+ * Procedure block type.
+ *
+ * @internal
+ */
+export interface ProcedureBlock {
+    getProcedureCall: () => string;
+    renameProcedure: (p1: string, p2: string) => void;
+    getProcedureDef: () => ProcedureTuple;
+}
+/** @internal */
+export interface LegacyProcedureDefBlock {
+    getProcedureDef: () => ProcedureTuple;
+}
+/** @internal */
+export declare function isLegacyProcedureDefBlock(obj: any): obj is LegacyProcedureDefBlock;
+/** @internal */
+export interface LegacyProcedureCallBlock {
+    getProcedureCall: () => string;
+    renameProcedure: (p1: string, p2: string) => void;
+}
+/** @internal */
+export declare function isLegacyProcedureCallBlock(obj: any): obj is LegacyProcedureCallBlock;
+//# sourceMappingURL=i_legacy_procedure_blocks.d.ts.map