blockly 13.0.0-beta.0 → 13.0.0-beta.2

package/core/field_textinput.d.ts

@@ -48,6 +48,16 @@ export declare class FieldTextInput extends FieldInput<string> {
      * @internal
      */
     static fromJson(options: FieldTextInputFromJsonConfig): FieldTextInput;
+    /**
+     * Gets an ARIA-friendly label representation of this field's type.
+     *
+     * Implementations are responsible for, and encouraged to, return a localized
+     * version of the ARIA representation of the field's type.
+     *
+     * @returns An ARIA representation of the field's type or a default if it is
+     *     unspecified.
+     */
+    getAriaTypeName(): string | null;
 }
 /**
  *  Config options for the text input field.

package/core/field_variable.d.ts

@@ -228,6 +228,15 @@ export declare class FieldVariable extends FieldDropdown {
      * @returns Array of variable names/id tuples.
      */
     static dropdownCreate(this: FieldVariable): MenuOption[];
+    /**
+     * Gets an ARIA-friendly label representation of this field's value.
+     *
+     * Implementations are responsible for, and encouraged to, return a localized
+     * version of the ARIA representation of the field's value.
+     *
+     * @returns An ARIA representation of the field's text.
+     */
+    getAriaValue(): string;
 }
 /**
  * Config options for the variable field.

package/core/flyout_base.d.ts

@@ -268,6 +268,16 @@ export declare abstract class Flyout extends DeleteArea implements IAutoHideable
      *     toolbox definition, or a string with the name of the dynamic category.
      */
     show(flyoutDef: toolbox.FlyoutDefinition | string): void;
+    /**
+     * Updates the aria attributes for the entire flyout dom.
+     * This needs to do two things:
+     * 1. Set aria-owns on the flyout's workspace canvas to include the ids of all
+     *    focusable elements in the flyout.
+     * 2. Update the aria attributes on the flyout's workspace. This can't be done at workspace
+     *    creation because the workspace may not have all required information until the flyout
+     *    is fully shown.
+     */
+    protected updateAriaContext(): void;
     /**
      * Create the contents array and gaps array necessary to create the layout for
      * the flyout.

package/core/focus_manager.d.ts

@@ -7,11 +7,15 @@ import type { IFocusableNode } from './interfaces/i_focusable_node.js';
 import type { IFocusableTree } from './interfaces/i_focusable_tree.js';
 /**
  * Type declaration for returning focus to FocusManager upon completing an
- * ephemeral UI flow (such as a dialog).
+ * ephemeral UI flow (such as a dialog). Normally, the FocusManager will refocus
+ * the previously-focused element. If callers do not wish for the FocusManager
+ * to do so, they may call this method with `restoreFocus` set to false to
+ * prevent automatic refocusing and leave focus where it is.
+ *
  *
  * See FocusManager.takeEphemeralFocus for more details.
  */
-export type ReturnEphemeralFocus = () => void;
+export type ReturnEphemeralFocus = (restoreFocus?: boolean) => void;
 /**
  * A per-page singleton that manages Blockly focus across one or more
  * IFocusableTrees, and bidirectionally synchronizes this focus with the DOM.
@@ -56,6 +60,20 @@ export declare class FocusManager {
     private lockFocusStateChanges;
     private recentlyLostAllFocus;
     private isUpdatingFocusedNode;
+    /**
+     * Root element in which popovers (WidgetDiv, DropDownDiv) currently live.
+     */
+    private popoverFocusRoot?;
+    /**
+     * Set of callbacks to invoke if the popover focus root loses focus.
+     */
+    private popoverFocusLossHandlers;
+    /**
+     * Handler for focusout in the popover focus root that selectively
+     * invokes the popover focus loss handlers if focus has truly transitioned
+     * outside of the focus root, and not e.g. to a different popover.
+     */
+    private popoverFocusOutHandler;
     constructor(addGlobalEventListener: (type: string, listener: EventListener) => void);
     /**
      * Registers a new IFocusableTree for automatic focus management.
@@ -260,6 +278,33 @@ export declare class FocusManager {
      * but may change across page loads.
      */
     static getFocusManager(): FocusManager;
+    /**
+     * Sets the current popover focus root. Generally this is active
+     * workspace's injection div or the explicitly specified parent container for
+     * the WidgetDiv, DropDownDiv, etc.
+     *
+     * @internal
+     * @param newRoot The new element that contains all popovers.
+     */
+    setPopoverFocusRoot(newRoot: HTMLElement): void;
+    /**
+     * Registers a callback to be invoked if the popover focus root loses
+     * focus. This should only be called by popovers that need to react to
+     * focus changes by e.g. hiding themselves and resigning ephemeral focus.
+     *
+     * @internal
+     * @param handler A callback function.
+     */
+    registerPopoverFocusLossHandler(handler: () => void): void;
+    /**
+     * Unregisters a previously-registered popover focus loss handler. This
+     * should only be invoked by popovers when they no longer need to be
+     * notified of focus loss, typically when they are hidden.
+     *
+     * @internal
+     * @param handler A previously-registered callback function.
+     */
+    unregisterPopoverFocusLossHandler(handler: () => void): void;
 }
 /** Convenience function for FocusManager.getFocusManager. */
 export declare function getFocusManager(): FocusManager;

package/core/inputs/input.d.ts

@@ -14,6 +14,7 @@ import type { BlockSvg } from '../block_svg.js';
 import type { Connection } from '../connection.js';
 import { ConnectionType } from '../connection_type.js';
 import type { Field } from '../field.js';
+import { Verbosity } from '../utils/aria.js';
 import { Align } from './align.js';
 import { inputTypes } from './input_types.js';
 /** Class for an input with optional fields. */
@@ -149,5 +150,19 @@ export declare class Input {
      * @internal
      */
     getRowId(): string;
+    /**
+     * Returns an accessibility label describing this input, including the labels
+     * of any fields on the input and the labels of any connected blocks, to help
+     * disambiguate this input from others on the same block.
+     *
+     * @internal
+     */
+    getLabel(verbosity?: Verbosity): string;
+    /**
+     * Returns the index of this input on its source block.
+     *
+     * @internal
+     */
+    getIndex(): number;
 }
 //# sourceMappingURL=input.d.ts.map

package/core/interfaces/i_flyout_inflater.d.ts

@@ -7,6 +7,15 @@ export interface IFlyoutInflater {
      * Note that this method's interface is identical to that in ISerializer, to
      * allow for code reuse.
      *
+     * You must ensure that any item created by this method has the appropriate
+     * ARIA markup:
+     * - The role of the element's focusable element should be set to `listitem`.
+     * - The focusable element must have an `id` attribute.
+     * - Any DOM parents of the focusable element should set their role to
+     *   `presentation` to avoid interfering with flyout list navigation.
+     * - If the element is not focusable, it must be hidden from the ARIA tree.
+     *   Only do this if the content should be inaccessible to screenreaders.
+     *
      * @param state A JSON representation of an element to inflate on the flyout.
      * @param flyout The flyout on whose workspace the inflated element
      *    should be created. If the inflated element is an `IRenderedElement` it

package/core/interfaces/i_focusable_node.d.ts

@@ -97,8 +97,10 @@ export interface IFocusableNode {
      * Optional method invoked when this node has focus and the user acts on it by
      * pressing Enter or Space. Behavior should generally be similar to the node
      * being clicked on.
+     *
+     * @param e The event that triggered this action, if any.
      */
-    performAction?(): void;
+    performAction?(e?: Event): void;
 }
 /**
  * Determines whether the provided object fulfills the contract of

package/core/interfaces/i_json_block_definition.d.ts

@@ -40,6 +40,7 @@ export interface JsonBlockDefinition {
     inputsInline?: boolean;
     tooltip?: string;
     helpUrl?: string;
+    ariaRoleDescription?: string;
     extensions?: string[];
     mutator?: string;
     enableContextMenu?: boolean;

package/core/keyboard_nav/keyboard_mover.d.ts

@@ -1,8 +1,3 @@
-/**
- * @license
- * Copyright 2026 Raspberry Pi Foundation
- * SPDX-License-Identifier: Apache-2.0
- */
 import type { IDraggable } from '../interfaces/i_draggable.js';
 /**
  * Cardinal directions in which a move can proceed.
@@ -113,6 +108,22 @@ export declare class KeyboardMover {
      * Repositions the move indicator to the corner of the item being moved.
      */
     private repositionMoveIndicator;
+    /**
+     * Returns a bounding box used for positioning the move indicator on a block.
+     * Blocks require special treatment because `BlockSvg.getBoundingRectangle()`
+     * includes the bounds of nested and subsequent blocks. Since the move
+     * indicator is positioned at the top right corner of the bounds, this can
+     * result in it appearing to float in empty space when e.g. a small block has
+     * a much wider block nested inside a statement input. BlockSvg also provides
+     * `getBoundingRectangleWithoutChildren()`, which addresses that case, but is
+     * insufficient because in the case of nested *value* blocks in a row, the
+     * child blocks' bounds should contribute to the bounding box.
+     *
+     * @param block The block to retrieve an adjusted bounding box for.
+     * @returns A bounding box for the given block whose top-right corner
+     *     corresponds to the maximum visual extent of the given block's row.
+     */
+    private positionForBlockMoveIndicator;
     /**
      * Common clean-up for finish/abort run before terminating the move.
      */

package/core/keyboard_nav/navigation_policies/bubble_navigation_policy.d.ts

@@ -0,0 +1,63 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Bubble } from '../../bubbles/bubble.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 Bubble.
+ */
+export declare class BubbleNavigationPolicy implements INavigationPolicy<Bubble> {
+    /**
+     * Returns the first child of the given bubble.
+     *
+     * @param _current The bubble to return the first child of.
+     * @returns Null.
+     */
+    getFirstChild(_current: Bubble): IFocusableNode | null;
+    /**
+     * Returns the parent of the given bubble.
+     *
+     * @param current The bubble to return the parent of.
+     * @returns The parent block of the given bubble.
+     */
+    getParent(current: Bubble): IFocusableNode | null;
+    /**
+     * Returns the next peer node of the given bubble.
+     *
+     * @param current The bubble to find the following element of.
+     * @returns The next navigable item on the bubble's icon's parent block.
+     */
+    getNextSibling(current: Bubble): IFocusableNode | null;
+    /**
+     * Returns the previous peer node of the given bubble.
+     *
+     * @param current The bubble to find the preceding element of.
+     * @returns The previous navigable item on the bubble's icon's parent block.
+     */
+    getPreviousSibling(current: Bubble): IFocusableNode | null;
+    /**
+     * Returns the row ID of the given bubble.
+     *
+     * @param current The bubble to retrieve the row ID of.
+     * @returns The row ID of the given bubble.
+     */
+    getRowId(current: Bubble): string;
+    /**
+     * Returns whether or not the given bubble can be navigated to.
+     *
+     * @param current The instance to check for navigability.
+     * @returns True if the given bubble can be focused.
+     */
+    isNavigable(current: Bubble): 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 Bubble.
+     */
+    isApplicable(current: any): current is Bubble;
+}
+//# sourceMappingURL=bubble_navigation_policy.d.ts.map

package/core/keyboard_nav/navigation_policies/icon_navigation_policy.d.ts

@@ -13,10 +13,10 @@ 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.
+     * @param _current The icon to return the first child of.
      * @returns Null.
      */
-    getFirstChild(current: Icon): IFocusableNode | null;
+    getFirstChild(_current: Icon): IFocusableNode | null;
     /**
      * Returns the parent of the given icon.
      *

package/core/keyboard_nav/navigators/flyout_navigator.d.ts

@@ -3,8 +3,8 @@
  * Copyright 2025 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import { IFocusableNode } from '../../blockly.js';
 import type { IFlyout } from '../../interfaces/i_flyout.js';
+import type { IFocusableNode } from '../../interfaces/i_focusable_node.js';
 import { Navigator } from './navigator.js';
 /**
  * Navigator that handles keyboard navigation within a flyout.

package/core/menu.d.ts

@@ -41,6 +41,8 @@ export declare class Menu {
     private element;
     /** ARIA name for this menu. */
     private roleName;
+    /** The menu's ID. */
+    private id;
     /** Constructs a new Menu instance. */
     constructor();
     /**
@@ -166,5 +168,6 @@ export declare class Menu {
      * @returns The MenuItem objects displayed in this menu.
      */
     private getMenuItems;
+    getId(): string;
 }
 //# sourceMappingURL=menu.d.ts.map

package/core/menuitem.d.ts

@@ -15,6 +15,7 @@ import * as aria from './utils/aria.js';
 export declare class MenuItem {
     private readonly content;
     private readonly opt_value?;
+    private readonly ariaLabel?;
     /** Is the menu item clickable, as opposed to greyed-out. */
     private enabled;
     /** The DOM element for the menu item. */
@@ -31,18 +32,24 @@ export declare class MenuItem {
     private highlight;
     /** Bound function to call when this menu item is clicked. */
     private actionHandler;
+    /** The unique ID for this menu item. */
+    private id;
     /**
      * @param content Text caption to display as the content of the item, or a
      *     HTML element to display.
      * @param opt_value Data/model associated with the menu item.
      */
-    constructor(content: string | HTMLElement, opt_value?: string | undefined);
+    constructor(content: string | HTMLElement, opt_value?: string | undefined, ariaLabel?: string | undefined);
     /**
      * Creates the menuitem's DOM.
      *
      * @returns Completed DOM.
      */
     createDom(): Element;
+    /**
+     * Gets the ARIA label for this menu item.
+     */
+    getAriaLabel(): string;
     /** Dispose of this menu item. */
     dispose(): void;
     /**

package/core/shortcut_items.d.ts

@@ -33,7 +33,10 @@ export declare enum names {
     NEXT_STACK = "next_stack",
     PREVIOUS_STACK = "previous_stack",
     INFORMATION = "information",
-    PERFORM_ACTION = "perform_action"
+    PERFORM_ACTION = "perform_action",
+    DUPLICATE = "duplicate",
+    CLEANUP = "cleanup",
+    SHOW_TOOLTIP = "show_tooltip"
 }
 /**
  * Keyboard shortcut to hide chaff on escape.
@@ -102,6 +105,18 @@ export declare function registerStackNavigation(): void;
  * Registers keyboard shortcut to perform an action on the focused element.
  */
 export declare function registerPerformAction(): void;
+/**
+ * Registers keyboard shortcut to duplicate a block or workspace comment.
+ */
+export declare function registerDuplicate(): void;
+/**
+ * Registers keyboard shortcut to clean up the workspace.
+ */
+export declare function registerCleanup(): void;
+/**
+ * Registers keyboard shortcut to display the tooltip for the focused element.
+ */
+export declare function registerShowTooltip(): void;
 /**
  * Registers all default keyboard shortcut item. This should be called once per
  * instance of KeyboardShortcutRegistry.

package/core/shortcut_registry.d.ts

@@ -223,6 +223,12 @@ export declare namespace ShortcutRegistry {
          * name.
          */
         allowCollision?: boolean;
+        /**
+         * Display text for the shortcut. This is not used in core but may
+         * be used by plugins or applications to provide a user-facing
+         * label for the shortcut.
+         */
+        displayText?: string | (() => string);
     }
     /** Supported modifiers. */
     enum modifierKeys {

package/core/toolbox/toolbox.d.ts

@@ -3,6 +3,11 @@
  * Copyright 2020 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
+/**
+ * Toolbox from whence to create blocks.
+ *
+ * @class
+ */
 import * as browserEvents from '../browser_events.js';
 import { DeleteArea } from '../delete_area.js';
 import '../events/events_toolbox_item_select.js';
@@ -179,17 +184,6 @@ export declare class Toolbox extends DeleteArea implements IAutoHideable, IKeybo
      *     ignored.
      */
     getClientRect(): Rect | null;
-    /**
-     * Returns whether the provided block or bubble would be deleted if dropped on
-     * this area.
-     * This method should check if the element is deletable and is always called
-     * before onDragEnter/onDragOver/onDragExit.
-     *
-     * @param element The block or bubble currently being dragged.
-     * @returns Whether the element provided would be deleted if dropped on this
-     *     area.
-     */
-    wouldDelete(element: IDraggable): boolean;
     /**
      * Handles when a cursor with a block or bubble enters this drag target.
      *

package/core/tooltip.d.ts

@@ -3,6 +3,8 @@
  * Copyright 2011 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
+import type { IFocusableNode } from './interfaces/i_focusable_node.js';
+import type { WorkspaceSvg } from './workspace_svg.js';
 /**
  * A type which can define a tooltip.
  * Either a string, an object containing a tooltip property, or a function which
@@ -101,6 +103,14 @@ export declare function dispose(): void;
  * Hide the tooltip.
  */
 export declare function hide(): void;
+/**
+ * Display the tooltip for a given target.
+ *
+ * @internal
+ * @param target The node upon which the tooltip should be displayed.
+ * @param workspace The target node's workspace.
+ */
+export declare function display(target: IFocusableNode, workspace?: WorkspaceSvg): void;
 /**
  * Hide any in-progress tooltips and block showing new tooltips until the next
  * call to unblock().

package/core/trashcan.d.ts

@@ -8,6 +8,7 @@ import './events/events_trashcan_open.js';
 import type { IAutoHideable } from './interfaces/i_autohideable.js';
 import type { IDraggable } from './interfaces/i_draggable.js';
 import type { IFlyout } from './interfaces/i_flyout.js';
+import type { IFocusableNode } from './interfaces/i_focusable_node.js';
 import type { IPositionable } from './interfaces/i_positionable.js';
 import type { UiMetrics } from './metrics_manager.js';
 import { Rect } from './utils/rect.js';
@@ -15,13 +16,20 @@ import type { WorkspaceSvg } from './workspace_svg.js';
 /**
  * Class for a trash can.
  */
-export declare class Trashcan extends DeleteArea implements IAutoHideable, IPositionable {
+export declare class Trashcan extends DeleteArea implements IAutoHideable, IPositionable, IFocusableNode {
     private workspace;
     /**
-     * The unique id for this component that is used to register with the
+     * The id for this component that is used to register with the
      * ComponentManager.
      */
     id: string;
+    /**
+     * A globally unique ID for this particular trashcan. Component Manager IDs
+     * (the ID above) are 1:1 with classes, but if there are multiple workspaces
+     * with trashcans on a page, each actual trashcan DOM element needs a unique
+     * ID to support focusable node resolution. This ID is for that purpose.
+     */
+    private uniqueId;
     /**
      * A list of JSON (stored as strings) representing blocks in the trashcan.
      */
@@ -34,19 +42,8 @@ export declare class Trashcan extends DeleteArea implements IAutoHideable, IPosi
     flyout: IFlyout | null;
     /** Current open/close state of the lid. */
     isLidOpen: boolean;
-    /**
-     * The minimum openness of the lid. Used to indicate if the trashcan
-     * contains blocks.
-     */
-    private minOpenness;
     /** The SVG group containing the trash can. */
     private svgGroup;
-    /** The SVG image element of the trash can lid. */
-    private svgLid;
-    /** Task ID of opening/closing animation. */
-    private lidTask;
-    /** Current state of lid opening (0.0 = closed, 1.0 = open). */
-    private lidOpen;
     /** Left coordinate of the trash can. */
     private left;
     /** Top coordinate of the trash can. */
@@ -148,22 +145,6 @@ export declare class Trashcan extends DeleteArea implements IAutoHideable, IPosi
      * @internal
      */
     setLidOpen(state: boolean): void;
-    /** Rotate the lid open or closed by one step.  Then wait and recurse. */
-    private animateLid;
-    /**
-     * Set the angle of the trashcan's lid.
-     *
-     * @param lidAngle The angle at which to set the lid.
-     */
-    private setLidAngle;
-    /**
-     * Sets the minimum openness of the trashcan lid. If the lid is currently
-     * closed, this will update lid's position.
-     *
-     * @param newMin The new minimum openness of the lid. Should be between 0
-     *     and 1.
-     */
-    private setMinOpenness;
     /**
      * Flip the lid shut.
      * Called externally after a drag.
@@ -183,15 +164,6 @@ export declare class Trashcan extends DeleteArea implements IAutoHideable, IPosi
      * @param e A mouse down event.
      */
     private blockMouseDownWhenOpenable;
-    /**
-     * Indicate that the trashcan can be clicked (by opening it) if it has blocks.
-     */
-    private mouseOver;
-    /**
-     * Close the lid of the trashcan if it was open (Vis. it was indicating it had
-     *    blocks).
-     */
-    private mouseOut;
     /**
      * Handle a BLOCK_DELETE event. Adds deleted blocks oldXml to the content
      * array.
@@ -208,5 +180,18 @@ export declare class Trashcan extends DeleteArea implements IAutoHideable, IPosi
      *     unnecessary attributes.
      */
     private cleanBlockJson;
+    getFocusableElement(): SVGElement;
+    getFocusableTree(): WorkspaceSvg;
+    onNodeFocus(): void;
+    onNodeBlur(): void;
+    canBeFocused(): boolean;
+    performAction(): void;
+    /**
+     * Retrieves the globally unique ID of this Trashcan instance. Used for focus
+     * management.
+     *
+     * @internal
+     */
+    getGloballyUniqueId(): string;
 }
 //# sourceMappingURL=trashcan.d.ts.map