blockly 12.0.0-beta.1 → 12.0.0-beta.3

package/core/interfaces/i_focusable_node.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @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 unique to the
+     * element relative to its nearest IFocusableTree parent. It must also have a
+     * negative tabindex (since the focus manager itself will manage its tab index
+     * and a tab index must be present in order for the element to be focusable in
+     * the DOM).
+     *
+     * It's expected the return element will not change for the lifetime of the
+     * 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.
+     */
+    getFocusableTree(): IFocusableTree;
+}
+//# sourceMappingURL=i_focusable_node.d.ts.map

package/core/interfaces/i_focusable_tree.d.ts

@@ -0,0 +1,58 @@
+/**
+ * @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 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;
+}
+//# sourceMappingURL=i_focusable_tree.d.ts.map

package/core/keyboard_nav/ast_node.d.ts

@@ -72,7 +72,7 @@ export declare class ASTNode {
      * @returns The workspace coordinate or null if the location is not a
      *     workspace.
      */
-    getWsCoordinate(): Coordinate;
+    getWsCoordinate(): Coordinate | null;
     /**
      * Whether the node points to a connection.
      *
@@ -213,7 +213,7 @@ export declare class ASTNode {
      * @param field The location of the AST node.
      * @returns An AST node pointing to a field.
      */
-    static createFieldNode(field: Field): ASTNode | null;
+    static createFieldNode(field: Field): ASTNode;
     /**
      * Creates an AST node pointing to a connection. If the connection has a
      * parent input then create an AST node of type input that will hold the
@@ -237,7 +237,7 @@ export declare class ASTNode {
      * @param block The block used to create an AST node.
      * @returns An AST node pointing to a block.
      */
-    static createBlockNode(block: Block): ASTNode | null;
+    static createBlockNode(block: Block): ASTNode;
     /**
      * Create an AST node of type stack. A stack, represented by its top block, is
      *     the set of all blocks connected to a top block, including the top
@@ -248,7 +248,7 @@ export declare class ASTNode {
      * @returns An AST node of type stack that points to the top block on the
      *     stack.
      */
-    static createStackNode(topBlock: Block): ASTNode | null;
+    static createStackNode(topBlock: Block): ASTNode;
     /**
      * Create an AST node of type button. A button in this case refers
      * specifically to a button in a flyout.
@@ -258,7 +258,7 @@ export declare class ASTNode {
      * @returns An AST node of type stack that points to the top block on the
      *     stack.
      */
-    static createButtonNode(button: FlyoutButton): ASTNode | null;
+    static createButtonNode(button: FlyoutButton): ASTNode;
     /**
      * Creates an AST node pointing to a workspace.
      *
@@ -267,7 +267,7 @@ export declare class ASTNode {
      * @returns An AST node pointing to a workspace and a position on the
      *     workspace.
      */
-    static createWorkspaceNode(workspace: Workspace | null, wsCoordinate: Coordinate | null): ASTNode | null;
+    static createWorkspaceNode(workspace: Workspace, wsCoordinate: Coordinate): ASTNode;
     /**
      * Creates an AST node for the top position on a block.
      * This is either an output connection, previous connection, or block.

package/core/keyboard_nav/line_cursor.d.ts

@@ -0,0 +1,313 @@
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * @fileoverview The class representing a line cursor.
+ * A line cursor tries to traverse the blocks and connections on a block as if
+ * they were lines of code in a text editor. Previous and next traverse previous
+ * connections, next connections and blocks, while in and out traverse input
+ * connections and fields.
+ * @author aschmiedt@google.com (Abby Schmiedt)
+ */
+import type { Block } from '../block.js';
+import type { MarkerSvg } from '../renderers/common/marker_svg.js';
+import type { WorkspaceSvg } from '../workspace_svg.js';
+import { ASTNode } from './ast_node.js';
+import { Marker } from './marker.js';
+/** Options object for LineCursor instances. */
+export interface CursorOptions {
+    /**
+     * Can the cursor visit all stack connections (next/previous), or
+     * (if false) only unconnected next connections?
+     */
+    stackConnections: boolean;
+}
+/**
+ * Class for a line cursor.
+ */
+export declare class LineCursor extends Marker {
+    private readonly workspace;
+    type: string;
+    /** Options for this line cursor. */
+    private readonly options;
+    /** Locations to try moving the cursor to after a deletion. */
+    private potentialNodes;
+    /** Whether the renderer is zelos-style. */
+    private isZelos;
+    /**
+     * @param workspace The workspace this cursor belongs to.
+     * @param options Cursor options.
+     */
+    constructor(workspace: WorkspaceSvg, options?: Partial<CursorOptions>);
+    /**
+     * Clean up this cursor.
+     */
+    dispose(): void;
+    /**
+     * Moves the cursor to the next previous connection, next connection or block
+     * in the pre order traversal. Finds the next node in the pre order traversal.
+     *
+     * @returns The next node, or null if the current node is
+     *     not set or there is no next value.
+     */
+    next(): ASTNode | null;
+    /**
+     * Moves the cursor to the next input connection or field
+     * in the pre order traversal.
+     *
+     * @returns The next node, or null if the current node is
+     *     not set or there is no next value.
+     */
+    in(): ASTNode | null;
+    /**
+     * Moves the cursor to the previous next connection or previous connection in
+     * the pre order traversal.
+     *
+     * @returns The previous node, or null if the current node
+     *     is not set or there is no previous value.
+     */
+    prev(): ASTNode | null;
+    /**
+     * Moves the cursor to the previous input connection or field in the pre order
+     * traversal.
+     *
+     * @returns The previous node, or null if the current node
+     *     is not set or there is no previous value.
+     */
+    out(): ASTNode | null;
+    /**
+     * Returns true iff the node to which we would navigate if in() were
+     * called, which will be a validInLineNode, is also a validLineNode
+     * - in effect, if the LineCursor is at the end of the 'current
+     * line' of the program.
+     */
+    atEndOfLine(): boolean;
+    /**
+     * Returns true iff the given node represents the "beginning of a
+     * new line of code" (and thus can be visited by pressing the
+     * up/down arrow keys).  Specifically, if the node is for:
+     *
+     * - Any block that is not a value block.
+     * - A top-level value block (one that is unconnected).
+     * - An unconnected next statement input.
+     * - An unconnected 'next' connection - the "blank line at the end".
+     *   This is to facilitate connecting additional blocks to a
+     *   stack/substack.
+     *
+     * If options.stackConnections is true (the default) then allow the
+     * cursor to visit all (useful) stack connection by additionally
+     * returning true for:
+     *
+     *   - Any next statement input
+     *   - Any 'next' connection.
+     *   - An unconnected previous statement input.
+     *
+     * @param node The AST node to check.
+     * @returns True if the node should be visited, false otherwise.
+     */
+    protected validLineNode(node: ASTNode | null): boolean;
+    /**
+     * Returns true iff the given node can be visited by the cursor when
+     * using the left/right arrow keys.  Specifically, if the node is
+     * any node for which valideLineNode would return true, plus:
+     *
+     * - Any block.
+     * - Any field that is not a full block field.
+     * - Any unconnected next or input connection.  This is to
+     *   facilitate connecting additional blocks.
+     *
+     * @param node The AST node to check whether it is valid.
+     * @returns True if the node should be visited, false otherwise.
+     */
+    protected validInLineNode(node: ASTNode | null): boolean;
+    /**
+     * Returns true iff the given node can be visited by the cursor.
+     * Specifically, if the node is any for which validInLineNode would
+     * return true, or if it is a workspace node.
+     *
+     * @param node The AST node to check whether it is valid.
+     * @returns True if the node should be visited, false otherwise.
+     */
+    protected validNode(node: ASTNode | null): boolean;
+    /**
+     * Uses pre order traversal to navigate the Blockly AST. This will allow
+     * a user to easily navigate the entire Blockly AST without having to go in
+     * and out levels on the tree.
+     *
+     * @param node The current position in the AST.
+     * @param isValid A function true/false depending on whether the given node
+     *     should be traversed.
+     * @returns The next node in the traversal.
+     */
+    getNextNode(node: ASTNode | null, isValid: (p1: ASTNode | null) => boolean): ASTNode | null;
+    /**
+     * Reverses the pre order traversal in order to find the previous node. This
+     * will allow a user to easily navigate the entire Blockly AST without having
+     * to go in and out levels on the tree.
+     *
+     * @param node The current position in the AST.
+     * @param isValid A function true/false depending on whether the given node
+     *     should be traversed.
+     * @returns The previous node in the traversal or null if no previous node
+     *     exists.
+     */
+    getPreviousNode(node: ASTNode | null, isValid: (p1: ASTNode | null) => boolean): ASTNode | null;
+    /**
+     * From the given node find either the next valid sibling or the parent's
+     * next sibling.
+     *
+     * @param node The current position in the AST.
+     * @returns The next sibling node, the parent's next sibling, or null.
+     */
+    private findSiblingOrParentSibling;
+    /**
+     * Get the right most child of a node.
+     *
+     * @param node The node to find the right most child of.
+     * @returns The right most child of the given node, or the node if no child
+     *     exists.
+     */
+    private getRightMostChild;
+    /**
+     * Prepare for the deletion of a block by making a list of nodes we
+     * could move the cursor to afterwards and save it to
+     * this.potentialNodes.
+     *
+     * After the deletion has occurred, call postDelete to move it to
+     * the first valid node on that list.
+     *
+     * The locations to try (in order of preference) are:
+     *
+     * - The current location.
+     * - The connection to which the deleted block is attached.
+     * - The block connected to the next connection of the deleted block.
+     * - The parent block of the deleted block.
+     * - A location on the workspace beneath the deleted block.
+     *
+     * N.B.: When block is deleted, all of the blocks conneccted to that
+     * block's inputs are also deleted, but not blocks connected to its
+     * next connection.
+     *
+     * @param deletedBlock The block that is being deleted.
+     */
+    preDelete(deletedBlock: Block): void;
+    /**
+     * Move the cursor to the first valid location in
+     * this.potentialNodes, following a block deletion.
+     */
+    postDelete(): void;
+    /**
+     * Get the current location of the cursor.
+     *
+     * Overrides normal Marker getCurNode to update the current node from the
+     * selected block. This typically happens via the selection listener but that
+     * is not called immediately when `Gesture` calls
+     * `Blockly.common.setSelected`. In particular the listener runs after showing
+     * the context menu.
+     *
+     * @returns The current field, connection, or block the cursor is on.
+     */
+    getCurNode(): ASTNode | null;
+    /**
+     * Sets the object in charge of drawing the marker.
+     *
+     * We want to customize drawing, so rather than directly setting the given
+     * object, we instead set a wrapper proxy object that passes through all
+     * method calls and property accesses except for draw(), which it delegates
+     * to the drawMarker() method in this class.
+     *
+     * @param drawer The object ~in charge of drawing the marker.
+     */
+    setDrawer(drawer: MarkerSvg): void;
+    /**
+     * Set the location of the cursor and draw it.
+     *
+     * Overrides normal Marker setCurNode logic to call
+     * this.drawMarker() instead of this.drawer.draw() directly.
+     *
+     * @param newNode The new location of the cursor.
+     * @param updateSelection If true (the default) we'll update the selection
+     *     too.
+     */
+    setCurNode(newNode: ASTNode | null, updateSelection?: boolean): void;
+    /**
+     * Draw this cursor's marker.
+     *
+     * This is a wrapper around this.drawer.draw (usually implemented by
+     * MarkerSvg.prototype.draw) that will, if newNode is a BLOCK node,
+     * instead call `setSelected` to select it (if it's a regular block)
+     * or `addSelect` (if it's a shadow block, since shadow blocks can't
+     * be selected) instead of using the normal drawer logic.
+     *
+     * TODO(#142): The selection and fake-selection code was originally
+     * a hack added for testing on October 28 2024, because the default
+     * drawer (MarkerSvg) behaviour in Zelos was to draw a box around
+     * the block and all attached child blocks, which was confusing when
+     * navigating stacks.
+     *
+     * Since then we have decided that we probably _do_ in most cases
+     * want navigating to a block to select the block, but more
+     * particularly that we want navigation to move _focus_.  Replace
+     * this selection hack with non-hacky changing of focus once that's
+     * possible.
+     *
+     * @param oldNode The previous node.
+     * @param curNode The current node.
+     * @param realDrawer The object ~in charge of drawing the marker.
+     */
+    private drawMarker;
+    /**
+     * Check whether the node represents a value input connection.
+     *
+     * @param node The node to check
+     * @returns True if the node represents a value input connection.
+     */
+    private isValueInputConnection;
+    /**
+     * Hide the cursor rendering at the given input node.
+     *
+     * @param node The input node to hide.
+     */
+    private hideAtInput;
+    /**
+     * Show the cursor rendering at the given input node.
+     *
+     * @param node The input node to show.
+     */
+    private showAtInput;
+    /**
+     * Event listener that syncs the cursor location to the selected block on
+     * SELECTED events.
+     *
+     * This does not run early enough in all cases so `getCurNode()` also updates
+     * the node from the selection.
+     *
+     * @param event The `Selected` event.
+     */
+    private changeListener;
+    /**
+     * Updates the current node to match the selection.
+     *
+     * Clears the current node if it's on a block but the selection is null.
+     * Sets the node to a block if selected for our workspace.
+     * For shadow blocks selections the parent is used by default (unless we're
+     * already on the shadow block via keyboard) as that's where the visual
+     * selection is.
+     */
+    private updateCurNodeFromSelection;
+    /**
+     * Updates the selection from the node.
+     *
+     * Clears the selection for non-block nodes.
+     * Clears the selection for shadow blocks as the selection is drawn on
+     * the parent but the cursor will be drawn on the shadow block itself.
+     * We need to take care not to later clear the current node due to that null
+     * selection, so we track the latest selection we're in sync with.
+     *
+     * @param newNode The new node.
+     */
+    private updateSelectionFromNode;
+}
+//# sourceMappingURL=line_cursor.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

@@ -4,8 +4,8 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 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): FlyoutItem;
+    load(state: object, flyout: IFlyout): FlyoutItem;
     /**
      * Returns the amount of space that should follow this label.
      *

package/core/marker_manager.d.ts

@@ -8,7 +8,7 @@
  *
  * @class
  */
-import type { Cursor } from './keyboard_nav/cursor.js';
+import type { LineCursor } from './keyboard_nav/line_cursor.js';
 import type { Marker } from './keyboard_nav/marker.js';
 import type { WorkspaceSvg } from './workspace_svg.js';
 /**
@@ -49,7 +49,7 @@ export declare class MarkerManager {
      *
      * @returns The cursor for this workspace.
      */
-    getCursor(): Cursor | null;
+    getCursor(): LineCursor | null;
     /**
      * Get a single marker that corresponds to the given ID.
      *
@@ -64,7 +64,7 @@ export declare class MarkerManager {
      *
      * @param cursor The cursor used to move around this workspace.
      */
-    setCursor(cursor: Cursor): void;
+    setCursor(cursor: LineCursor): void;
     /**
      * Add the cursor SVG to this workspace SVG group.
      *

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,17 +136,17 @@ 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.
      *
@@ -160,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