blockly 12.4.0 → 12.4.1

package/core/keyboard_nav/flyout_button_navigation_policy.d.ts

@@ -0,0 +1,56 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { FlyoutButton } from '../flyout_button.js';
+import type { IFocusableNode } from '../interfaces/i_focusable_node.js';
+import type { INavigationPolicy } from '../interfaces/i_navigation_policy.js';
+/**
+ * Set of rules controlling keyboard navigation from a flyout button.
+ */
+export declare class FlyoutButtonNavigationPolicy implements INavigationPolicy<FlyoutButton> {
+    /**
+     * Returns null since flyout buttons have no children.
+     *
+     * @param _current The FlyoutButton instance to navigate from.
+     * @returns Null.
+     */
+    getFirstChild(_current: FlyoutButton): IFocusableNode | null;
+    /**
+     * Returns the parent workspace of the given flyout button.
+     *
+     * @param current The FlyoutButton instance to navigate from.
+     * @returns The given flyout button's parent workspace.
+     */
+    getParent(current: FlyoutButton): IFocusableNode | null;
+    /**
+     * Returns null since inter-item navigation is done by FlyoutNavigationPolicy.
+     *
+     * @param _current The FlyoutButton instance to navigate from.
+     * @returns Null.
+     */
+    getNextSibling(_current: FlyoutButton): IFocusableNode | null;
+    /**
+     * Returns null since inter-item navigation is done by FlyoutNavigationPolicy.
+     *
+     * @param _current The FlyoutButton instance to navigate from.
+     * @returns Null.
+     */
+    getPreviousSibling(_current: FlyoutButton): IFocusableNode | null;
+    /**
+     * Returns whether or not the given flyout button can be navigated to.
+     *
+     * @param current The instance to check for navigability.
+     * @returns True if the given flyout button can be focused.
+     */
+    isNavigable(current: FlyoutButton): boolean;
+    /**
+     * Returns whether the given object can be navigated from by this policy.
+     *
+     * @param current The object to check if this policy applies to.
+     * @returns True if the object is a FlyoutButton.
+     */
+    isApplicable(current: any): current is FlyoutButton;
+}
+//# sourceMappingURL=flyout_button_navigation_policy.d.ts.map

package/core/keyboard_nav/flyout_navigation_policy.d.ts

@@ -0,0 +1,65 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { IFlyout } from '../interfaces/i_flyout.js';
+import type { IFocusableNode } from '../interfaces/i_focusable_node.js';
+import type { INavigationPolicy } from '../interfaces/i_navigation_policy.js';
+/**
+ * Generic navigation policy that navigates between items in the flyout.
+ */
+export declare class FlyoutNavigationPolicy<T> implements INavigationPolicy<T> {
+    private policy;
+    private flyout;
+    /**
+     * Creates a new FlyoutNavigationPolicy instance.
+     *
+     * @param policy The policy to defer to for parents/children.
+     * @param flyout The flyout this policy will control navigation in.
+     */
+    constructor(policy: INavigationPolicy<T>, flyout: IFlyout);
+    /**
+     * Returns null to prevent navigating into flyout items.
+     *
+     * @param _current The flyout item to navigate from.
+     * @returns Null to prevent navigating into flyout items.
+     */
+    getFirstChild(_current: T): IFocusableNode | null;
+    /**
+     * Returns the parent of the given flyout item.
+     *
+     * @param current The flyout item to navigate from.
+     * @returns The parent of the given flyout item.
+     */
+    getParent(current: T): IFocusableNode | null;
+    /**
+     * Returns the next item in the flyout relative to the given item.
+     *
+     * @param current The flyout item to navigate from.
+     * @returns The flyout item following the given one.
+     */
+    getNextSibling(current: T): IFocusableNode | null;
+    /**
+     * Returns the previous item in the flyout relative to the given item.
+     *
+     * @param current The flyout item to navigate from.
+     * @returns The flyout item preceding the given one.
+     */
+    getPreviousSibling(current: T): IFocusableNode | null;
+    /**
+     * Returns whether or not the given flyout item can be navigated to.
+     *
+     * @param current The instance to check for navigability.
+     * @returns True if the given flyout item can be focused.
+     */
+    isNavigable(current: T): boolean;
+    /**
+     * Returns whether the given object can be navigated from by this policy.
+     *
+     * @param current The object to check if this policy applies to.
+     * @returns True if the object is a BlockSvg.
+     */
+    isApplicable(current: any): current is T;
+}
+//# sourceMappingURL=flyout_navigation_policy.d.ts.map

package/core/keyboard_nav/flyout_separator_navigation_policy.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { FlyoutSeparator } from '../flyout_separator.js';
+import type { IFocusableNode } from '../interfaces/i_focusable_node.js';
+import type { INavigationPolicy } from '../interfaces/i_navigation_policy.js';
+/**
+ * Set of rules controlling keyboard navigation from a flyout separator.
+ * This is a no-op placeholder, since flyout separators can't be navigated to.
+ */
+export declare class FlyoutSeparatorNavigationPolicy implements INavigationPolicy<FlyoutSeparator> {
+    getFirstChild(_current: FlyoutSeparator): IFocusableNode | null;
+    getParent(_current: FlyoutSeparator): IFocusableNode | null;
+    getNextSibling(_current: FlyoutSeparator): IFocusableNode | null;
+    getPreviousSibling(_current: FlyoutSeparator): IFocusableNode | null;
+    /**
+     * Returns whether or not the given flyout separator can be navigated to.
+     *
+     * @param _current The instance to check for navigability.
+     * @returns False.
+     */
+    isNavigable(_current: FlyoutSeparator): boolean;
+    /**
+     * Returns whether the given object can be navigated from by this policy.
+     *
+     * @param current The object to check if this policy applies to.
+     * @returns True if the object is a FlyoutSeparator.
+     */
+    isApplicable(current: any): current is FlyoutSeparator;
+}
+//# sourceMappingURL=flyout_separator_navigation_policy.d.ts.map

package/core/keyboard_nav/icon_navigation_policy.d.ts

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

package/core/keyboard_nav/line_cursor.d.ts

@@ -0,0 +1,187 @@
+/**
+ * @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 { BlockSvg } from '../block_svg.js';
+import type { IFocusableNode } from '../interfaces/i_focusable_node.js';
+import type { WorkspaceSvg } from '../workspace_svg.js';
+import { Marker } from './marker.js';
+/**
+ * Class for a line cursor.
+ */
+export declare class LineCursor extends Marker {
+    protected readonly workspace: WorkspaceSvg;
+    type: string;
+    /** Locations to try moving the cursor to after a deletion. */
+    private potentialNodes;
+    /**
+     * @param workspace The workspace this cursor belongs to.
+     */
+    constructor(workspace: WorkspaceSvg);
+    /**
+     * Moves the cursor to the next block or workspace comment 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(): IFocusableNode | 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(): IFocusableNode | null;
+    /**
+     * Moves the cursor to the previous block or workspace comment 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(): IFocusableNode | 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(): IFocusableNode | null;
+    /**
+     * Returns true iff the node to which we would navigate if in() were
+     * called is the same as the node to which we would navigate if next() were
+     * called - in effect, if the LineCursor is at the end of the 'current
+     * line' of the program.
+     */
+    atEndOfLine(): 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.
+     * @param visitedNodes A set of previously visited nodes used to avoid cycles.
+     * @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 no
+     *     valid node was found.
+     * @returns The next node in the traversal.
+     */
+    getNextNode(node: IFocusableNode | null, isValid: (p1: IFocusableNode | null) => boolean, loop: boolean): IFocusableNode | 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.
+     * @param visitedNodes A set of previously visited nodes used to avoid cycles.
+     * @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: IFocusableNode | null, isValid: (p1: IFocusableNode | null) => boolean, loop: boolean): IFocusableNode | null;
+    /**
+     * 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: BlockSvg): 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(): IFocusableNode | null;
+    /**
+     * 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.
+     */
+    setCurNode(newNode: IFocusableNode): void;
+    /**
+     * Get the first navigable node on the workspace, or null if none exist.
+     *
+     * @returns The first navigable node on the workspace, or null.
+     */
+    getFirstNode(): IFocusableNode | 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(): IFocusableNode | null;
+}
+//# sourceMappingURL=line_cursor.d.ts.map

package/core/keyboard_nav/marker.d.ts

@@ -0,0 +1,53 @@
+/**
+ * @license
+ * Copyright 2019 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * The class representing a marker.
+ * Used primarily for keyboard navigation to show a marked location.
+ *
+ * @class
+ */
+import { BlockSvg } from '../block_svg.js';
+import type { IFocusableNode } from '../interfaces/i_focusable_node.js';
+/**
+ * Class for a marker.
+ * This is used in keyboard navigation to save a location in the Blockly AST.
+ */
+export declare class Marker {
+    /** The colour of the marker. */
+    colour: string | null;
+    /** The current location of the marker. */
+    protected curNode: IFocusableNode | null;
+    /** The type of the marker. */
+    type: string;
+    /**
+     * Gets the current location of the marker.
+     *
+     * @returns The current field, connection, or block the marker is on.
+     */
+    getCurNode(): IFocusableNode | null;
+    /**
+     * Set the location of the marker and call the update method.
+     *
+     * @param newNode The new location of the marker, or null to remove it.
+     */
+    setCurNode(newNode: IFocusableNode | null): void;
+    /** Dispose of this marker. */
+    dispose(): void;
+    /**
+     * Returns the block that the given node is a child of.
+     *
+     * @returns The parent block of the node if any, otherwise null.
+     */
+    getSourceBlockFromNode(node: IFocusableNode | null): BlockSvg | null;
+    /**
+     * Returns the block that this marker's current node is a child of.
+     *
+     * @returns The parent block of the marker's current node if any, otherwise
+     *     null.
+     */
+    getSourceBlock(): BlockSvg | null;
+}
+//# sourceMappingURL=marker.d.ts.map

package/core/keyboard_nav/workspace_comment_navigation_policy.d.ts

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

package/core/keyboard_nav/workspace_navigation_policy.d.ts

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

package/core/keyboard_navigation_controller.d.ts

@@ -0,0 +1,48 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * The KeyboardNavigationController handles coordinating Blockly-wide
+ * keyboard navigation behavior, such as enabling/disabling full
+ * cursor visualization.
+ */
+export declare class KeyboardNavigationController {
+    /** Whether the user is actively using keyboard navigation. */
+    private isActive;
+    /** Css class name added to body if keyboard nav is active. */
+    private activeClassName;
+    /**
+     * Sets whether a user is actively using keyboard navigation.
+     *
+     * If they are, apply a css class to the entire page so that
+     * focused items can apply additional styling for keyboard users.
+     *
+     * Note that since enabling keyboard navigation presents significant UX changes
+     * (such as cursor visualization and move mode), callers should take care to
+     * only set active keyboard navigation when they have a high confidence in that
+     * being the correct state. In general, in any given mouse or key input situation
+     * callers can choose one of three paths:
+     * 1. Do nothing. This should be the choice for neutral actions that don't
+     *    predominantly imply keyboard or mouse usage (such as clicking to select a block).
+     * 2. Disable keyboard navigation. This is the best choice when a user is definitely
+     *    predominantly using the mouse (such as using a right click to open the context menu).
+     * 3. Enable keyboard navigation. This is the best choice when there's high confidence
+     *    a user actually intends to use it (such as attempting to use the arrow keys to move
+     *    around).
+     *
+     * @param isUsing
+     */
+    setIsActive(isUsing?: boolean): void;
+    /**
+     * @returns true if the user is actively using keyboard navigation
+     * (e.g., has recently taken some action that is only relevant to keyboard users)
+     */
+    getIsActive(): boolean;
+    /** Adds or removes the css class that indicates keyboard navigation is active. */
+    private updateActiveVisualization;
+}
+/** Singleton instance of the keyboard navigation controller. */
+export declare const keyboardNavigationController: KeyboardNavigationController;
+//# sourceMappingURL=keyboard_navigation_controller.d.ts.map

package/core/label_flyout_inflater.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @license
+ * Copyright 2024 Google LLC
+ * 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';
+/**
+ * Class responsible for creating labels for flyouts.
+ */
+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 flyout The flyout to create the label on.
+     * @returns A FlyoutButton configured as a label.
+     */
+    load(state: object, flyout: IFlyout): FlyoutItem;
+    /**
+     * Returns the amount of space that should follow this label.
+     *
+     * @param state A JSON representation of a flyout label.
+     * @param defaultGap The default spacing for flyout items.
+     * @returns The amount of space that should follow this label.
+     */
+    gapForItem(state: object, defaultGap: number): number;
+    /**
+     * Disposes of the given label.
+     *
+     * @param item The flyout label to dispose of.
+     */
+    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