blockly 12.0.0-beta.2 → 12.0.0-beta.4

package/core/keyboard_nav/line_cursor.d.ts

@@ -0,0 +1,348 @@
+/**
+ * @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.
+     */
+    private getNextNodeImpl;
+    /**
+     * Get the next node in the AST, optionally allowing for loopback.
+     *
+     * @param node The current position in the AST.
+     * @param isValid A function true/false depending on whether the given node
+     *     should be traversed.
+     * @param loop Whether to loop around to the beginning of the workspace if
+     *     novalid node was found.
+     * @returns The next node in the traversal.
+     */
+    getNextNode(node: ASTNode | null, isValid: (p1: ASTNode | null) => boolean, loop: 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.
+     */
+    private getPreviousNodeImpl;
+    /**
+     * Get the previous node in the AST, optionally allowing for loopback.
+     *
+     * @param node The current position in the AST.
+     * @param isValid A function true/false depending on whether the given node
+     *     should be traversed.
+     * @param loop Whether to loop around to the end of the workspace if no
+     *     valid node was found.
+     * @returns The previous node in the traversal or null if no previous node
+     *     exists.
+     */
+    getPreviousNode(node: ASTNode | null, isValid: (p1: ASTNode | null) => boolean, loop: 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;
+    /**
+     * Get the first navigable node on the workspace, or null if none exist.
+     *
+     * @returns The first navigable node on the workspace, or null.
+     */
+    getFirstNode(): ASTNode | null;
+    /**
+     * Get the last navigable node on the workspace, or null if none exist.
+     *
+     * @returns The last navigable node on the workspace, or null.
+     */
+    getLastNode(): ASTNode | null;
+}
+//# sourceMappingURL=line_cursor.d.ts.map

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/menuitem.d.ts

@@ -120,9 +120,12 @@ export declare class MenuItem {
      * Performs the appropriate action when the menu item is activated
      * by the user.
      *
+     * @param menuSelectEvent the event that triggered the selection
+     * of the menu item.
+     *
      * @internal
      */
-    performAction(): void;
+    performAction(menuSelectEvent: Event): void;
     /**
      * Set the handler that's called when the menu item is activated by the user.
      * `obj` will be used as the 'this' object in the function when called.
@@ -131,6 +134,6 @@ export declare class MenuItem {
      * @param obj Used as the 'this' object in fn when called.
      * @internal
      */
-    onAction(fn: (p1: MenuItem) => void, obj: object): void;
+    onAction(fn: (p1: MenuItem, menuSelectEvent: Event) => void, obj: object): void;
 }
 //# sourceMappingURL=menuitem.d.ts.map

package/core/registry.d.ts

@@ -19,7 +19,7 @@ import type { ISerializer } from './interfaces/i_serializer.js';
 import type { IToolbox } from './interfaces/i_toolbox.js';
 import type { IVariableMap } from './interfaces/i_variable_map.js';
 import type { IVariableModel, IVariableModelStatic, IVariableState } from './interfaces/i_variable_model.js';
-import type { Cursor } from './keyboard_nav/cursor.js';
+import type { LineCursor } from './keyboard_nav/line_cursor.js';
 import type { Options } from './options.js';
 import type { Renderer } from './renderers/common/renderer.js';
 import type { Theme } from './theme.js';
@@ -50,7 +50,7 @@ export declare class Type<_T> {
     toString(): string;
     static CONNECTION_CHECKER: Type<IConnectionChecker>;
     static CONNECTION_PREVIEWER: Type<IConnectionPreviewer>;
-    static CURSOR: Type<Cursor>;
+    static CURSOR: Type<LineCursor>;
     static EVENT: Type<Abstract>;
     static FIELD: Type<Field<any>>;
     static INPUT: Type<Input>;

package/core/renderers/zelos/path_object.d.ts

@@ -61,10 +61,11 @@ export declare class PathObject extends BasePathObject {
     /**
      * Create's an outline path for the specified input.
      *
+     * @internal
      * @param name The input name.
      * @returns The SVG outline path.
      */
-    private getOutlinePath;
+    getOutlinePath(name: string): SVGElement;
     /**
      * Remove an outline path that is associated with the specified input.
      *

package/core/utils/focusable_tree_traverser.d.ts

@@ -0,0 +1,53 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { IFocusableNode } from '../interfaces/i_focusable_node.js';
+import type { IFocusableTree } from '../interfaces/i_focusable_tree.js';
+/**
+ * A helper utility for IFocusableTree implementations to aid with common
+ * tree traversals.
+ */
+export declare class FocusableTreeTraverser {
+    private static readonly ACTIVE_CLASS_NAME;
+    private static readonly PASSIVE_CSS_CLASS_NAME;
+    private static readonly ACTIVE_FOCUS_NODE_CSS_SELECTOR;
+    private static readonly PASSIVE_FOCUS_NODE_CSS_SELECTOR;
+    /**
+     * Returns the current IFocusableNode that is styled (and thus represented) as
+     * having either passive or active focus, only considering HTML and SVG
+     * elements.
+     *
+     * This can match against the tree's root.
+     *
+     * Note that this will never return a node from a nested sub-tree as that tree
+     * should specifically be used to retrieve its focused node.
+     *
+     * @param tree The IFocusableTree in which to search for a focused node.
+     * @returns The IFocusableNode currently with focus, or null if none.
+     */
+    static findFocusedNode(tree: IFocusableTree): IFocusableNode | null;
+    /**
+     * Returns the IFocusableNode corresponding to the specified HTML or SVG
+     * element iff it's the root element or a descendent of the root element of
+     * the specified IFocusableTree.
+     *
+     * If the element exists within the specified tree's DOM structure but does
+     * not directly correspond to a node, the nearest parent node (or the tree's
+     * root) will be returned to represent the provided element.
+     *
+     * If the tree contains another nested IFocusableTree, the nested tree may be
+     * traversed but its nodes will never be returned here per the contract of
+     * IFocusableTree.lookUpFocusableNode.
+     *
+     * The provided element must have a non-null ID that conforms to the contract
+     * mentioned in IFocusableNode.
+     *
+     * @param element The HTML or SVG element being sought.
+     * @param tree The tree under which the provided element may be a descendant.
+     * @returns The matching IFocusableNode, or null if there is no match.
+     */
+    static findFocusableNodeFor(element: HTMLElement | SVGElement, tree: IFocusableTree): IFocusableNode | null;
+}
+//# sourceMappingURL=focusable_tree_traverser.d.ts.map

package/core/workspace.d.ts

@@ -411,7 +411,6 @@ export declare class Workspace implements IASTNodeLocation {
      * These exist in the flyout but not in the workspace.
      *
      * @returns The potential variable map.
-     * @internal
      */
     getPotentialVariableMap(): IVariableMap<IVariableModel<IVariableState>> | null;
     /**

package/core/workspace_svg.d.ts

@@ -22,12 +22,13 @@ import { Gesture } from './gesture.js';
 import { Grid } from './grid.js';
 import type { IASTNodeLocationSvg } from './interfaces/i_ast_node_location_svg.js';
 import type { IBoundedElement } from './interfaces/i_bounded_element.js';
+import { IContextMenu } from './interfaces/i_contextmenu.js';
 import type { IDragTarget } from './interfaces/i_drag_target.js';
 import type { IFlyout } from './interfaces/i_flyout.js';
 import type { IMetricsManager } from './interfaces/i_metrics_manager.js';
 import type { IToolbox } from './interfaces/i_toolbox.js';
 import type { IVariableModel, IVariableState } from './interfaces/i_variable_model.js';
-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 { LayerManager } from './layer_manager.js';
 import { MarkerManager } from './marker_manager.js';
@@ -50,7 +51,7 @@ import { ZoomControls } from './zoom_controls.js';
  * Class for a workspace.  This is an onscreen area with optional trashcan,
  * scrollbars, bubbles, and dragging.
  */
-export declare class WorkspaceSvg extends Workspace implements IASTNodeLocationSvg {
+export declare class WorkspaceSvg extends Workspace implements IASTNodeLocationSvg, IContextMenu {
     /**
      * A wrapper function called when a resize event occurs.
      * You can pass the result to `eventHandling.unbind`.
@@ -304,7 +305,7 @@ export declare class WorkspaceSvg extends Workspace implements IASTNodeLocationS
      *
      * @returns The cursor for the workspace.
      */
-    getCursor(): Cursor | null;
+    getCursor(): LineCursor | null;
     /**
      * Get the block renderer attached to this workspace.
      *
@@ -711,7 +712,7 @@ export declare class WorkspaceSvg extends Workspace implements IASTNodeLocationS
      * @param e Mouse event.
      * @internal
      */
-    showContextMenu(e: PointerEvent): void;
+    showContextMenu(e: Event): void;
     /**
      * Modify the block tree on the existing toolbox.
      *
@@ -1004,6 +1005,19 @@ export declare class WorkspaceSvg extends Workspace implements IASTNodeLocationS
      */
     removeClass(className: string): void;
     setIsReadOnly(readOnly: boolean): void;
+    /**
+     * Scrolls the provided bounds into view.
+     *
+     * In the case of small workspaces/large bounds, this function prioritizes
+     * getting the top left corner of the bounds into view. It also adds some
+     * padding around the bounds to allow the element to be comfortably in view.
+     *
+     * @internal
+     * @param bounds A rectangle to scroll into view, as best as possible.
+     * @param padding Amount of spacing to put between the bounds and the edge of
+     *     the workspace's viewport.
+     */
+    scrollBoundsIntoView(bounds: Rect, padding?: number): void;
 }
 /**
  * Size the workspace when the contents change.  This also updates

package/index.mjs

@@ -1,7 +1,6 @@
 import Blockly from './index.js';
 export const {
   ASTNode,
-  BasicCursor,
   Block,
   BlockFlyoutInflater,
   BlockSvg,
@@ -21,7 +20,6 @@ export const {
   ContextMenuItems,
   ContextMenuRegistry,
   Css,
-  Cursor,
   DELETE_VARIABLE_ID,
   DeleteArea,
   DragTarget,
@@ -42,6 +40,7 @@ export const {
   FlyoutItem,
   FlyoutMetricsManager,
   FlyoutSeparator,
+  FocusManager,
   Generator,
   Gesture,
   Grid,
@@ -50,6 +49,7 @@ export const {
   Input,
   InsertionMarkerPreviewer,
   LabelFlyoutInflater,
+  LineCursor,
   Marker,
   MarkerManager,
   Menu,
@@ -75,7 +75,6 @@ export const {
   TOOLBOX_AT_LEFT,
   TOOLBOX_AT_RIGHT,
   TOOLBOX_AT_TOP,
-  TabNavigateCursor,
   Theme,
   ThemeManager,
   Themes,
@@ -117,6 +116,7 @@ export const {
   dragging,
   fieldRegistry,
   geras,
+  getFocusManager,
   getMainWorkspace,
   getSelected,
   hasBubble,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blockly",
-  "version": "12.0.0-beta.2",
+  "version": "12.0.0-beta.4",
   "description": "Blockly is a library for building visual programming editors.",
   "keywords": [
     "blockly"