blockly 12.0.0-beta.0 → 12.0.0-beta.2

package/core/interfaces/i_focusable_tree.d.ts

@@ -0,0 +1,48 @@
+/**
+ * @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.
+ */
+export interface IFocusableTree {
+    /**
+     * Returns the current node with focus in this tree, or null if none (or if
+     * the root has focus).
+     *
+     * Note that this will never return a node from a nested sub-tree as that tree
+     * should specifically be called in order to retrieve its focused node.
+     */
+    getFocusedNode(): IFocusableNode | null;
+    /**
+     * 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 corresponding to the select element, or null if
+     * the element does not have such a node.
+     *
+     * The provided element must have a non-null ID that conforms to the contract
+     * mentioned in IFocusableNode.
+     */
+    findFocusableNodeFor(element: HTMLElement | SVGElement): IFocusableNode | null;
+}
+//# sourceMappingURL=i_focusable_tree.d.ts.map

package/core/interfaces/i_metrics_manager.d.ts

@@ -47,7 +47,7 @@ export interface IMetricsManager {
      * Gets the width, height and position of the toolbox on the workspace in
      * pixel coordinates. Returns 0 for the width and height if the workspace has
      * a simple toolbox instead of a category toolbox. To get the width and height
-     * of a simple toolbox, see {@link IMetricsManager#getFlyoutMetrics}.
+     * of a simple toolbox, see {@link IMetricsManager.getFlyoutMetrics}.
      *
      * @returns The object with the width, height and position of the toolbox.
      */

package/core/interfaces/i_rendered_element.d.ts

@@ -3,17 +3,14 @@
  * Copyright 2023 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-/** @internal */
 export interface IRenderedElement {
     /**
-     * @returns The root SVG element of htis rendered element.
+     * @returns The root SVG element of this rendered element.
      */
     getSvgRoot(): SVGElement;
 }
 /**
  * @returns True if the given object is an IRenderedElement.
- *
- * @internal
  */
 export declare function isRenderedElement(obj: any): obj is IRenderedElement;
 //# sourceMappingURL=i_rendered_element.d.ts.map

package/core/keyboard_nav/marker.d.ts

@@ -27,8 +27,6 @@ export declare class Marker {
     private drawer;
     /** The type of the marker. */
     type: string;
-    /** Constructs a new Marker instance. */
-    constructor();
     /**
      * Sets the object in charge of drawing the marker.
      *
@@ -40,21 +38,19 @@ export declare class Marker {
      *
      * @returns The object in charge of drawing the marker.
      */
-    getDrawer(): MarkerSvg;
+    getDrawer(): MarkerSvg | null;
     /**
      * Gets the current location of the marker.
      *
      * @returns The current field, connection, or block the marker is on.
      */
-    getCurNode(): ASTNode;
+    getCurNode(): ASTNode | null;
     /**
      * Set the location of the marker and call the update method.
-     * Setting isStack to true will only work if the newLocation is the top most
-     * output or previous connection on a stack.
      *
-     * @param newNode The new location of the marker.
+     * @param newNode The new location of the marker, or null to remove it.
      */
-    setCurNode(newNode: ASTNode): void;
+    setCurNode(newNode: ASTNode | null): void;
     /**
      * Redraw the current marker.
      *

package/core/label_flyout_inflater.d.ts

@@ -3,9 +3,9 @@
  * Copyright 2024 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import type { IBoundedElement } from './interfaces/i_bounded_element.js';
+import { FlyoutItem } from './flyout_item.js';
+import type { IFlyout } from './interfaces/i_flyout.js';
 import type { IFlyoutInflater } from './interfaces/i_flyout_inflater.js';
-import type { WorkspaceSvg } from './workspace_svg.js';
 /**
  * Class responsible for creating labels for flyouts.
  */
@@ -14,10 +14,10 @@ export declare class LabelFlyoutInflater implements IFlyoutInflater {
      * Inflates a flyout label from the given state and adds it to the flyout.
      *
      * @param state A JSON representation of a flyout label.
-     * @param flyoutWorkspace The workspace to create the label on.
+     * @param flyout The flyout to create the label on.
      * @returns A FlyoutButton configured as a label.
      */
-    load(state: object, flyoutWorkspace: WorkspaceSvg): IBoundedElement;
+    load(state: object, flyout: IFlyout): FlyoutItem;
     /**
      * Returns the amount of space that should follow this label.
      *
@@ -25,12 +25,18 @@ export declare class LabelFlyoutInflater implements IFlyoutInflater {
      * @param defaultGap The default spacing for flyout items.
      * @returns The amount of space that should follow this label.
      */
-    gapForElement(state: object, defaultGap: number): number;
+    gapForItem(state: object, defaultGap: number): number;
     /**
      * Disposes of the given label.
      *
-     * @param element The flyout label to dispose of.
+     * @param item The flyout label to dispose of.
      */
-    disposeElement(element: IBoundedElement): void;
+    disposeItem(item: FlyoutItem): void;
+    /**
+     * Returns the type of items this inflater is responsible for creating.
+     *
+     * @returns An identifier for the type of items this inflater creates.
+     */
+    getType(): string;
 }
 //# sourceMappingURL=label_flyout_inflater.d.ts.map

package/core/menu.d.ts

@@ -3,7 +3,8 @@
  * Copyright 2019 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import type { MenuItem } from './menuitem.js';
+import type { MenuSeparator } from './menu_separator.js';
+import { MenuItem } from './menuitem.js';
 import * as aria from './utils/aria.js';
 import { Coordinate } from './utils/coordinate.js';
 import type { Size } from './utils/size.js';
@@ -12,14 +13,12 @@ import type { Size } from './utils/size.js';
  */
 export declare class Menu {
     /**
-     * Array of menu items.
-     * (Nulls are never in the array, but typing the array as nullable prevents
-     * the compiler from objecting to .indexOf(null))
+     * Array of menu items and separators.
      */
     private readonly menuItems;
     /**
-     * Coordinates of the mousedown event that caused this menu to open. Used to
-     * prevent the consequent mouseup event due to a simple click from
+     * Coordinates of the pointerdown event that caused this menu to open. Used to
+     * prevent the consequent pointerup event due to a simple click from
      * activating a menu item immediately.
      */
     openingCoords: Coordinate | null;
@@ -28,14 +27,14 @@ export declare class Menu {
      * A value of null means no menu item is highlighted.
      */
     private highlightedItem;
-    /** Mouse over event data. */
-    private mouseOverHandler;
+    /** Pointer over event data. */
+    private pointerMoveHandler;
     /** Click event data. */
     private clickHandler;
-    /** Mouse enter event data. */
-    private mouseEnterHandler;
-    /** Mouse leave event data. */
-    private mouseLeaveHandler;
+    /** Pointer enter event data. */
+    private pointerEnterHandler;
+    /** Pointer leave event data. */
+    private pointerLeaveHandler;
     /** Key down event data. */
     private onKeyDownHandler;
     /** The menu's root DOM element. */
@@ -47,10 +46,10 @@ export declare class Menu {
     /**
      * Add a new menu item to the bottom of this menu.
      *
-     * @param menuItem Menu item to append.
+     * @param menuItem Menu item or separator to append.
      * @internal
      */
-    addChild(menuItem: MenuItem): void;
+    addChild(menuItem: MenuItem | MenuSeparator): void;
     /**
      * Creates the menu DOM.
      *
@@ -124,11 +123,12 @@ export declare class Menu {
      */
     private highlightHelper;
     /**
-     * Handles mouseover events. Highlight menuitems as the user hovers over them.
+     * Handles pointermove events. Highlight menu items as the user hovers over
+     * them.
      *
-     * @param e Mouse event to handle.
+     * @param e Pointer event to handle.
      */
-    private handleMouseOver;
+    private handlePointerMove;
     /**
      * Handles click events. Pass the event onto the child menuitem to handle.
      *
@@ -136,21 +136,19 @@ export declare class Menu {
      */
     private handleClick;
     /**
-     * Handles mouse enter events. Focus the element.
+     * Handles pointer enter events. Focus the element.
      *
-     * @param _e Mouse event to handle.
+     * @param _e Pointer event to handle.
      */
-    private handleMouseEnter;
+    private handlePointerEnter;
     /**
-     * Handles mouse leave events. Blur and clear highlight.
+     * Handles pointer leave events by clearing the active highlight.
      *
-     * @param _e Mouse event to handle.
+     * @param _e Pointer event to handle.
      */
-    private handleMouseLeave;
+    private handlePointerLeave;
     /**
-     * Attempts to handle a keyboard event, if the menu item is enabled, by
-     * calling
-     * {@link Menu#handleKeyEventInternal_}.
+     * Attempts to handle a keyboard event.
      *
      * @param e Key event to handle.
      */
@@ -162,5 +160,11 @@ export declare class Menu {
      * @internal
      */
     getSize(): Size;
+    /**
+     * Returns the action menu items (omitting separators) in this menu.
+     *
+     * @returns The MenuItem objects displayed in this menu.
+     */
+    private getMenuItems;
 }
 //# sourceMappingURL=menu.d.ts.map

package/core/menu_separator.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Representation of a section separator in a menu.
+ */
+export declare class MenuSeparator {
+    /**
+     * DOM element representing this separator in a menu.
+     */
+    private element;
+    /**
+     * Creates the DOM representation of this separator.
+     *
+     * @returns An <hr> element.
+     */
+    createDom(): HTMLHRElement;
+    /**
+     * Disposes of this separator.
+     */
+    dispose(): void;
+}
+//# sourceMappingURL=menu_separator.d.ts.map

package/core/menuitem.d.ts

@@ -95,6 +95,13 @@ export declare class MenuItem {
      * @internal
      */
     setChecked(checked: boolean): void;
+    /**
+     * Highlights or unhighlights the component.
+     *
+     * @param highlight Whether to highlight or unhighlight the component.
+     * @internal
+     */
+    setHighlighted(highlight: boolean): void;
     /**
      * Returns true if the menu item is enabled, false otherwise.
      *

package/core/metrics_manager.d.ts

@@ -48,7 +48,7 @@ export declare class MetricsManager implements IMetricsManager {
      * Gets the width, height and position of the toolbox on the workspace in
      * pixel coordinates. Returns 0 for the width and height if the workspace has
      * a simple toolbox instead of a category toolbox. To get the width and height
-     * of a simple toolbox, see {@link MetricsManager#getFlyoutMetrics}.
+     * of a simple toolbox, see {@link (MetricsManager:class).getFlyoutMetrics}.
      *
      * @returns The object with the width, height and position of the toolbox.
      */

package/core/procedures.d.ts

@@ -13,6 +13,7 @@ import { IProcedureBlock, isProcedureBlock } from './interfaces/i_procedure_bloc
 import { IProcedureMap } from './interfaces/i_procedure_map.js';
 import { IProcedureModel } from './interfaces/i_procedure_model.js';
 import { ObservableProcedureMap } from './observable_procedure_map.js';
+import type { FlyoutItemInfo } from './utils/toolbox.js';
 import type { Workspace } from './workspace.js';
 import type { WorkspaceSvg } from './workspace_svg.js';
 /**
@@ -64,12 +65,14 @@ export declare function isNameUsed(name: string, workspace: Workspace, opt_exclu
  */
 export declare function rename(this: Field, name: string): string;
 /**
- * Construct the blocks required by the flyout for the procedure category.
+ * Internal wrapper that returns the contents of the procedure category.
  *
- * @param workspace The workspace containing procedures.
- * @returns Array of XML block elements.
+ * @internal
+ * @param workspace The workspace to populate procedure blocks for.
  */
-export declare function flyoutCategory(workspace: WorkspaceSvg): Element[];
+export declare function internalFlyoutCategory(workspace: WorkspaceSvg): FlyoutItemInfo[];
+export declare function flyoutCategory(workspace: WorkspaceSvg, useXml: true): Element[];
+export declare function flyoutCategory(workspace: WorkspaceSvg, useXml: false): FlyoutItemInfo[];
 /**
  * Listens for when a procedure mutator is opened. Then it triggers a flyout
  * update and adds a mutator change listener to the mutator workspace.

package/core/renderers/common/marker_svg.d.ts

@@ -78,7 +78,7 @@ export declare class MarkerSvg {
      * @param oldNode The previous node the marker was on or null.
      * @param curNode The node that we want to draw the marker for.
      */
-    draw(oldNode: ASTNode, curNode: ASTNode): void;
+    draw(oldNode: ASTNode | null, curNode: ASTNode | null): void;
     /**
      * Update the marker's visible state based on the type of curNode..
      *
@@ -229,7 +229,7 @@ export declare class MarkerSvg {
      * @param oldNode The old node the marker used to be on.
      * @param curNode The new node the marker is currently on.
      */
-    protected fireMarkerEvent(oldNode: ASTNode, curNode: ASTNode): void;
+    protected fireMarkerEvent(oldNode: ASTNode | null, curNode: ASTNode): void;
     /**
      * Get the properties to make a marker blink.
      *

package/core/renderers/common/renderer.d.ts

@@ -47,7 +47,7 @@ export declare class Renderer implements IRegistrable {
     /**
      * Create any DOM elements that this renderer needs.
      * If you need to create additional DOM elements, override the
-     * {@link ConstantProvider#createDom} method instead.
+     * {@link blockRendering#ConstantProvider.createDom} method instead.
      *
      * @param svg The root of the workspace's SVG.
      * @param theme The workspace theme object.

package/core/renderers/measurables/in_row_spacer.d.ts

@@ -10,6 +10,7 @@ import { Measurable } from './base.js';
  * row.
  */
 export declare class InRowSpacer extends Measurable {
+    private inRowSpacer;
     /**
      * @param constants The rendering constants provider.
      * @param width The width of the spacer.

package/core/renderers/measurables/jagged_edge.d.ts

@@ -10,6 +10,7 @@ import { Measurable } from './base.js';
  * collapsed block takes up during rendering.
  */
 export declare class JaggedEdge extends Measurable {
+    private jaggedEdge;
     /**
      * @param constants The rendering constants provider.
      */

package/core/renderers/measurables/next_connection.d.ts

@@ -11,6 +11,7 @@ import { Connection } from './connection.js';
  * up during rendering.
  */
 export declare class NextConnection extends Connection {
+    private nextConnection;
     /**
      * @param constants The rendering constants provider.
      * @param connectionModel The connection object on the block that this

package/core/renderers/measurables/previous_connection.d.ts

@@ -11,6 +11,7 @@ import { Connection } from './connection.js';
  * up during rendering.
  */
 export declare class PreviousConnection extends Connection {
+    private previousConnection;
     /**
      * @param constants The rendering constants provider.
      * @param connectionModel The connection object on the block that this

package/core/renderers/measurables/round_corner.d.ts

@@ -10,6 +10,7 @@ import { Measurable } from './base.js';
  * during rendering.
  */
 export declare class RoundCorner extends Measurable {
+    private roundCorner;
     /**
      * @param constants The rendering constants provider.
      * @param opt_position The position of this corner.

package/core/renderers/measurables/square_corner.d.ts

@@ -10,6 +10,7 @@ import { Measurable } from './base.js';
  * during rendering.
  */
 export declare class SquareCorner extends Measurable {
+    private squareCorner;
     /**
      * @param constants The rendering constants provider.
      * @param opt_position The position of this corner.

package/core/renderers/measurables/statement_input.d.ts

@@ -11,6 +11,7 @@ import { InputConnection } from './input_connection.js';
  * during rendering
  */
 export declare class StatementInput extends InputConnection {
+    private statementInput;
     /**
      * @param constants The rendering constants provider.
      * @param input The statement input to measure and store information for.