blockly 13.0.0 → 13.1.0

package/core/block.d.ts

@@ -3,14 +3,6 @@
  * Copyright 2011 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-/**
- * The class representing one block.
- *
- * @class
- */
-import './events/events_block_change.js';
-import './events/events_block_create.js';
-import './events/events_block_delete.js';
 import { Connection } from './connection.js';
 import { ConnectionType } from './connection_type.js';
 import type { Abstract } from './events/events_abstract.js';

package/core/block_aria_composer.d.ts

@@ -46,9 +46,10 @@ export declare enum ConnectionPreposition {
  * @internal
  * @param block The block for which an ARIA representation should be created.
  * @param verbosity How much detail to include in the description.
+ * @param fullBlockFieldLabel An optional override for input labels for full-block fields
  * @returns The ARIA representation for the specified block.
  */
-export declare function computeAriaLabel(block: BlockSvg, verbosity?: Verbosity): string;
+export declare function computeAriaLabel(block: BlockSvg, verbosity?: Verbosity, fullBlockFieldLabel?: string | undefined): string;
 /**
  * Sets the ARIA role and role description for the specified block, accounting
  * for whether the block is part of a flyout.
@@ -83,6 +84,15 @@ export declare function configureAriaRole(block: BlockSvg): void;
  *     lookback is specified) as the given input.
  */
 export declare function computeFieldRowLabel(input: Input, lookback: boolean, verbosity?: Verbosity): string[];
+/**
+ * Returns text indicating that a block is the root block of a stack.
+ *
+ * @internal
+ * @param block The block to retrieve a label for.
+ * @returns Text indicating that the block begins a stack, or undefined if it
+ *     does not.
+ */
+export declare function getBeginStackLabel(block: BlockSvg): string | undefined;
 /**
  * Returns a list of accessibility labels for fields and inputs on a block.
  * Each entry in the returned array corresponds to one of: (a) a label for a
@@ -98,9 +108,10 @@ export declare function computeFieldRowLabel(input: Input, lookback: boolean, ve
  * @internal
  * @param block The block to retrieve a list of field/input labels for.
  * @param verbosity How much detail to include in each input label.
+ * @param fullBlockFieldLabel An optional override for full-block fields.
  * @returns A list of field/input labels for the given block.
  */
-export declare function getInputLabels(block: BlockSvg, verbosity?: Verbosity): string[];
+export declare function getInputLabels(block: BlockSvg, verbosity?: Verbosity, fullBlockFieldLabel?: string | undefined): string[];
 /**
  * Returns a subset of derived labels for inputs on the given block, ending at
  * the specified input. Used to disambiguate move targets and connection

package/core/block_svg.d.ts

@@ -8,7 +8,6 @@
  *
  * @class
  */
-import './events/events_selected.js';
 import { Block } from './block.js';
 import { BlockCopyData } from './clipboard/block_paster.js';
 import type { Connection } from './connection.js';
@@ -495,6 +494,19 @@ export declare class BlockSvg extends Block implements IBoundedElement, IContext
      *     adjusting its parents.
      */
     bringToFront(blockOnly?: boolean): void;
+    /**
+     * Reorders this block's SVG root and those of its parents (unless
+     * `blockOnly`` is set to `true`) to the end of their respective parents so
+     * they render on top of their siblings.
+     *
+     * Unlike `bringToFront`, this does not preserve focus across the reorder, so
+     * it is safe to call from within a focus callback
+     *
+     * @param blockOnly True to only move this block to the front without
+     * adjusting its parents.
+     * @internal
+     */
+    moveSvgRootToFront(blockOnly?: boolean): void;
     /**
      * Set whether this block can chain onto the bottom of another block.
      *

package/core/blockly.d.ts

@@ -3,10 +3,6 @@
  * Copyright 2011 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import './events/events_block_create.js';
-import './events/workspace_events.js';
-import './events/events_ui_base.js';
-import './events/events_var_create.js';
 import { Block } from './block.js';
 import * as blockAnimations from './block_animations.js';
 import { BlockFlyoutInflater } from './block_flyout_inflater.js';

package/core/component_manager.d.ts

@@ -12,12 +12,14 @@ import type { IAutoHideable } from './interfaces/i_autohideable.js';
 import type { IComponent } from './interfaces/i_component.js';
 import type { IDeleteArea } from './interfaces/i_delete_area.js';
 import type { IDragTarget } from './interfaces/i_drag_target.js';
+import type { IFocusableNode } from './interfaces/i_focusable_node.js';
 import type { IPositionable } from './interfaces/i_positionable.js';
 declare class Capability<_T> {
     static POSITIONABLE: Capability<IPositionable>;
     static DRAG_TARGET: Capability<IDragTarget>;
     static DELETE_AREA: Capability<IDeleteArea>;
     static AUTOHIDEABLE: Capability<IAutoHideable>;
+    static FOCUSABLE: Capability<IFocusableNode>;
     private readonly name;
     /** @param name The name of the component capability. */
     constructor(name: string);

package/core/dragging/dragger.d.ts

@@ -43,6 +43,11 @@ export declare class Dragger implements IDragger {
      * at the end of the drag.
      */
     protected shouldReturnToStart(coordinate: Coordinate, rootDraggable: IDraggable): boolean;
+    /**
+     * Returns the workspace coordinate for a pointer position, for delete-area
+     * hit testing.
+     */
+    private pointerToWorkspaceCoordinate;
     protected pixelsToWorkspaceUnits(pixelCoord: Coordinate): Coordinate;
 }
 //# sourceMappingURL=dragger.d.ts.map

package/core/field.d.ts

@@ -10,7 +10,6 @@
  *
  * @class
  */
-import './events/events_block_change.js';
 import type { Block } from './block.js';
 import type { Input } from './inputs/input.js';
 import type { IFocusableNode } from './interfaces/i_focusable_node.js';
@@ -277,6 +276,13 @@ export declare abstract class Field<T = any> implements IKeyboardAccessible, IRe
      * with this method.
      */
     isFullBlockField(): boolean;
+    /**
+     * Returns whether this field is a static text label (ex. FieldLabel).
+     * Used internally instead of `instanceof FieldLabel` to avoid circular imports.
+     *
+     * @internal
+     */
+    isLabelField(): boolean;
     /**
      * Create a field border rect element. Not to be overridden by subclasses.
      * Instead modify the result of the function inside initView, or create a
@@ -771,7 +777,7 @@ export declare abstract class Field<T = any> implements IKeyboardAccessible, IRe
      *
      * @returns true if the element is in the accessibility tree, false if the aria state is hidden
      */
-    protected recomputeAriaContext(): boolean;
+    recomputeAriaContext(): boolean;
     /**
      * Subclasses should reimplement this method to construct their Field
      * subclass from a JSON arg object.

package/core/field_checkbox.d.ts

@@ -8,7 +8,6 @@
  *
  * @class
  */
-import './events/events_block_change.js';
 import { Field, FieldConfig, FieldValidator } from './field.js';
 type BoolString = 'TRUE' | 'FALSE';
 type CheckboxBool = BoolString | boolean;

package/core/field_dropdown.d.ts

@@ -279,7 +279,7 @@ export declare class FieldDropdown extends Field<string> {
      */
     private getSelectedAriaLabel;
     /**
-     * Overrides the default label and sets additional aria state.
+     * Sets additional aria state.
      */
     recomputeAriaContext(): boolean;
     /**

package/core/field_input.d.ts

@@ -3,12 +3,6 @@
  * Copyright 2012 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-/**
- * Text input field.
- *
- * @class
- */
-import './events/events_block_change.js';
 import { Field, FieldConfig, FieldValidator } from './field.js';
 import { Size } from './utils/size.js';
 import type { WorkspaceSvg } from './workspace_svg.js';

package/core/field_label.d.ts

@@ -23,6 +23,7 @@ export declare class FieldLabel extends Field<string> {
     EDITABLE: boolean;
     /** Text labels should not truncate. */
     maxDisplayLength: number;
+    isLabelField(): boolean;
     /**
      * @param value The initial value of the field. Should cast to a string.
      *     Defaults to an empty string if null or undefined. Also accepts

package/core/field_textinput.d.ts

@@ -8,7 +8,6 @@
  *
  * @class
  */
-import './events/events_block_change.js';
 import { Field } from './field.js';
 import { FieldInput, FieldInputConfig, FieldInputValidator } from './field_input.js';
 /**

package/core/field_variable.d.ts

@@ -8,7 +8,6 @@
  *
  * @class
  */
-import './events/events_block_change.js';
 import type { Block } from './block.js';
 import { Field, FieldConfig } from './field.js';
 import { FieldDropdown, FieldDropdownValidator, MenuGenerator, MenuOption } from './field_dropdown.js';

package/core/gesture.d.ts

@@ -3,13 +3,6 @@
  * Copyright 2017 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-/**
- * The class representing an in-progress gesture, e.g. a drag,
- * tap, or pinch to zoom.
- *
- * @class
- */
-import './events/events_click.js';
 import type { BlockSvg } from './block_svg.js';
 import { RenderedWorkspaceComment } from './comments.js';
 import type { Field } from './field.js';

package/core/inputs/input.d.ts

@@ -8,7 +8,6 @@
  *
  * @class
  */
-import '../field_label.js';
 import type { Block } from '../block.js';
 import type { BlockSvg } from '../block_svg.js';
 import type { Connection } from '../connection.js';

package/core/procedures.d.ts

@@ -3,7 +3,6 @@
  * Copyright 2012 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import './events/events_block_change.js';
 import type { Block } from './block.js';
 import type { Abstract } from './events/events_abstract.js';
 import { Field } from './field.js';

package/core/rendered_connection.d.ts

@@ -128,6 +128,12 @@ export declare class RenderedConnection extends Connection implements IContextMe
         connection: RenderedConnection | null;
         radius: number;
     };
+    /**
+     * Sets the aria role and role description for this connection.
+     *
+     * @param highlightSvg The focusable element for this connection.
+     */
+    setAriaRole(highlightSvg: SVGElement): void;
     /**
      * Sets the aria role, label, and other state for this connection.
      *

package/core/shortcut_items.d.ts

@@ -40,7 +40,13 @@ export declare enum names {
     SHOW_TOOLTIP = "show_tooltip",
     NEXT_HEADING = "next_heading",
     PREVIOUS_HEADING = "previous_heading",
-    TOGGLE_SCREENREADER = "toggle_screenreader"
+    TOGGLE_SCREENREADER = "toggle_screenreader",
+    JUMP_TOP_STACK = "jump_to_top_of_stack",
+    JUMP_BOTTOM_STACK = "jump_to_bottom_of_stack",
+    JUMP_BLOCK_START = "jump_to_block_start",
+    JUMP_BLOCK_END = "jump_to_block_end",
+    JUMP_FIRST_BLOCK = "jump_to_first_block",
+    JUMP_LAST_BLOCK = "jump_to_last_block"
 }
 /**
  * Keyboard shortcut to hide chaff on escape.
@@ -141,6 +147,36 @@ export declare function registerShowTooltip(): void;
  * improve the experience for individuals using screenreaders.
  */
 export declare function registerToggleScreenreaderMode(): void;
+/**
+ * Registers a keyboard shortcut that sets the focus to the block
+ * that owns the current focused node.
+ */
+export declare function registerJumpBlockStart(): void;
+/**
+ * Registers a keyboard shortcut that sets the focus to the
+ * last input of the block that owns the current focused node.
+ */
+export declare function registerJumpBlockEnd(): void;
+/**
+ * Registers a keyboard shortcut that sets the focus to the top block
+ * in the current stack.
+ */
+export declare function registerJumpTopStack(): void;
+/**
+ * Registers a keyboard shortcut that sets the focus to the bottom block
+ * in the current stack.
+ */
+export declare function registerJumpBottomStack(): void;
+/**
+ * Registers a keyboard shortcut that sets the focus to the first
+ * block in the workspace.
+ */
+export declare function registerJumpFirstBlock(): void;
+/**
+ * Registers a keyboard shortcut that sets the focus to the last
+ * block in the workspace.
+ */
+export declare function registerJumpLastBlock(): void;
 /**
  * Registers all default keyboard shortcut item. This should be called once per
  * instance of KeyboardShortcutRegistry.
@@ -157,4 +193,9 @@ export declare function registerKeyboardNavigationShortcuts(): void;
  * Registers keyboard shortcuts used to announce screen reader information.
  */
 export declare function registerScreenReaderShortcuts(): void;
+/**
+ * Registers keyboard shortcuts used to jump between blocks and stacks in the workspace.
+ * Note these are not registered by default, so call this function to enable them if desired.
+ */
+export declare function registerNavigationShortcuts(): void;
 //# sourceMappingURL=shortcut_items.d.ts.map

package/core/toolbox/collapsible_category.d.ts

@@ -67,6 +67,8 @@ export declare class CollapsibleToolboxCategory extends ToolboxCategory implemen
     isExpanded(): boolean;
     isCollapsible(): boolean;
     onClick(_e: Event): void;
+    /** Sets the visibility of the parent toolbox's flyout. */
+    private setFlyoutVisible;
     /** Toggles whether or not the category is expanded. */
     toggleExpanded(): void;
     getDiv(): HTMLDivElement | null;

package/core/trashcan.d.ts

@@ -6,6 +6,7 @@
 import { DeleteArea } from './delete_area.js';
 import './events/events_trashcan_open.js';
 import type { IAutoHideable } from './interfaces/i_autohideable.js';
+import type { IComponent } from './interfaces/i_component';
 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';
@@ -16,7 +17,7 @@ import type { WorkspaceSvg } from './workspace_svg.js';
 /**
  * Class for a trash can.
  */
-export declare class Trashcan extends DeleteArea implements IAutoHideable, IPositionable, IFocusableNode {
+export declare class Trashcan extends DeleteArea implements IAutoHideable, IPositionable, IFocusableNode, IComponent {
     private workspace;
     /**
      * The id for this component that is used to register with the
@@ -186,12 +187,5 @@ export declare class Trashcan extends DeleteArea implements IAutoHideable, IPosi
     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

package/core/utils/aria.d.ts

@@ -61,10 +61,10 @@ export declare enum Role {
     MENU = "menu",
     /** See https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menuitem_role. */
     MENUITEM = "menuitem",
+    /** See https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/none_role. */
+    NONE = "none",
     /** See https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/option_role. */
     OPTION = "option",
-    /** See https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/presentation_role. */
-    PRESENTATION = "presentation",
     /** See https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/region_role. */
     REGION = "region",
     /** See https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/row_role. */

package/core/variable_map.d.ts

@@ -3,13 +3,6 @@
  * Copyright 2017 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-/**
- * Object representing a map of variables and their types.
- *
- * @class
- */
-import './events/events_var_delete.js';
-import './events/events_var_rename.js';
 import type { IVariableMap } from './interfaces/i_variable_map.js';
 import { IVariableModel, IVariableState } from './interfaces/i_variable_model.js';
 import type { Workspace } from './workspace.js';

package/core/variable_model.d.ts

@@ -3,12 +3,6 @@
  * Copyright 2017 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-/**
- * Components for the variable model.
- *
- * @class
- */
-import './events/events_var_create.js';
 import { IVariableModel, IVariableState } from './interfaces/i_variable_model.js';
 import type { Workspace } from './workspace.js';
 /**

package/core/workspace.d.ts

@@ -8,7 +8,6 @@
  *
  * @class
  */
-import './connection_checker.js';
 import type { Block } from './block.js';
 import { WorkspaceComment } from './comments/workspace_comment.js';
 import type { ConnectionDB } from './connection_db.js';

package/core/workspace_focus_target.d.ts

@@ -0,0 +1,46 @@
+/**
+ * @license
+ * Copyright 2026 Raspberry Pi Foundation
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { IFocusableNode } from './interfaces/i_focusable_node.js';
+import type { IFocusableTree } from './interfaces/i_focusable_tree.js';
+import type { WorkspaceSvg } from './workspace_svg.js';
+/**
+ * A focusable element representing the workspace as a whole.
+ *
+ * Focus on the workspace itself (i.e. not on any block, comment, or other
+ * content) lands here rather than on the workspace's region element. VoiceOver
+ * does not announce a region when focus moves into it from a node already
+ * inside that region, so focusing the region directly (e.g. after pressing "W"
+ * from a block) would be silent. This is an ordinary focusable node, so moving
+ * to it is announced. It carries the stack count and a "workspace" role
+ * description; the enclosing region keeps a short, stable label
+ * ("Blocks workspace.").
+ */
+export declare class WorkspaceFocusTarget implements IFocusableNode {
+    private readonly workspace;
+    private readonly element;
+    /**
+     * @param workspace The workspace this focus target represents.
+     * @param element The SVG element that receives focus for the workspace.
+     */
+    constructor(workspace: WorkspaceSvg, element: SVGElement);
+    /** See IFocusableNode.getFocusableElement. */
+    getFocusableElement(): SVGElement;
+    /** See IFocusableNode.getFocusableTree. */
+    getFocusableTree(): IFocusableTree;
+    /** See IFocusableNode.onNodeFocus. */
+    onNodeFocus(): void;
+    /** See IFocusableNode.onNodeBlur. */
+    onNodeBlur(): void;
+    /** See IFocusableNode.canBeFocused. */
+    canBeFocused(): boolean;
+    /**
+     * Returns the workspace this focus target represents.
+     *
+     * @returns The workspace this focus target represents.
+     */
+    getWorkspace(): WorkspaceSvg;
+}
+//# sourceMappingURL=workspace_focus_target.d.ts.map

package/core/workspace_svg.d.ts

@@ -8,9 +8,6 @@
  *
  * @class
  */
-import './events/events_block_create.js';
-import './events/events_theme_change.js';
-import './events/events_viewport.js';
 import type { Block } from './block.js';
 import type { BlockSvg } from './block_svg.js';
 import * as browserEvents from './browser_events.js';
@@ -45,6 +42,7 @@ import { Svg } from './utils/svg.js';
 import * as toolbox from './utils/toolbox.js';
 import { Workspace } from './workspace.js';
 import { WorkspaceAudio } from './workspace_audio.js';
+import { WorkspaceFocusTarget } from './workspace_focus_target.js';
 import { ZoomControls } from './zoom_controls.js';
 /**
  * Class for a workspace.  This is an onscreen area with optional trashcan,
@@ -250,6 +248,18 @@ export declare class WorkspaceSvg extends Workspace implements IContextMenu, IFo
      * Selection ring inside the workspace.
      */
     private workspaceSelectionRing;
+    /**
+     * Element that receives focus when the workspace itself (rather than any of
+     * its contents) is focused. See {@link WorkspaceFocusTarget}. This is the
+     * selection ring (which already represents the workspace being the active
+     * node); it's set only for main (non-flyout, non-mutator) workspaces.
+     */
+    private workspaceFocusTargetElement;
+    /**
+     * Focusable node wrapping {@link workspaceFocusTargetElement}, or null if this
+     * workspace has no focus target.
+     */
+    private workspaceFocusTarget;
     /**
      * Navigator that handles moving focus between items in this workspace in
      * response to keyboard navigation commands.
@@ -395,7 +405,8 @@ export declare class WorkspaceSvg extends Workspace implements IContextMenu, IFo
      */
     setInitialAriaContext(): void;
     /**
-     * Updates the label on the workspace to reflect the number of top-level stacks in the workspace.
+     * Updates the focus target's label to reflect the number of top-level stacks in the
+     * workspace. No-op for workspaces without a focus target (flyouts and mutators).
      */
     private updateAriaLabel;
     /**
@@ -1036,6 +1047,17 @@ export declare class WorkspaceSvg extends Workspace implements IContextMenu, IFo
     getFocusableTree(): IFocusableTree;
     /** See IFocusableNode.onNodeFocus. */
     onNodeFocus(): void;
+    /**
+     * Handles the workspace's focus target receiving focus, which represents focus
+     * landing on the workspace as a whole.
+     *
+     * @internal
+     */
+    handleWorkspaceFocusTargetFocus(): void;
+    /**
+     * Announces the screen reader hint the first time any workspace is focused.
+     */
+    private maybeAnnounceScreenreaderHint;
     /** See IFocusableNode.onNodeBlur. */
     onNodeBlur(): void;
     /** See IFocusableNode.canBeFocused. */
@@ -1044,6 +1066,16 @@ export declare class WorkspaceSvg extends Workspace implements IContextMenu, IFo
     getRootFocusableNode(): IFocusableNode;
     /** See IFocusableTree.getRestoredFocusableNode. */
     getRestoredFocusableNode(previousNode: IFocusableNode | null): IFocusableNode | null;
+    /**
+     * Returns the focusable node representing this workspace as a whole, or null
+     * for workspaces without one (flyouts and mutators).
+     *
+     * Focus lands here when the workspace itself is focused (e.g. via the focus
+     * workspace shortcut) rather than on any of its contents.
+     *
+     * @returns This workspace's focus target node, if any.
+     */
+    getWorkspaceFocusTarget(): WorkspaceFocusTarget | null;
     /** See IFocusableTree.getNestedTrees. */
     getNestedTrees(): Array<IFocusableTree>;
     /**

package/core/zoom_controls.d.ts

@@ -3,48 +3,10 @@
  * Copyright 2015 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-/**
- * Object representing a zoom icons.
- *
- * @class
- */
-import './events/events_click.js';
-import { 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';
 import type { WorkspaceSvg } from './workspace_svg.js';
-/**
- * Base class for an individual zoom control (in, out, reset).
- *
- * @internal
- */
-declare abstract class ZoomControl implements IFocusableNode {
-    protected workspace: WorkspaceSvg;
-    protected group: SVGGElement;
-    private pointerDownHandler;
-    private id;
-    constructor(workspace: WorkspaceSvg, group: SVGGElement);
-    getId(): string;
-    /**
-     * Handles a mouse down event on the zoom in or zoom out buttons on the
-     *    workspace.
-     *
-     * @param amount Amount of zooming. Negative amount values zoom out, and
-     *     positive amount values zoom in.
-     * @param e A mouse down or keydown event.
-     */
-    protected zoom(amount: number, e: Event): void;
-    /** Fires a zoom control UI event. */
-    protected fireZoomEvent(): void;
-    getFocusableElement(): SVGGElement;
-    getFocusableTree(): WorkspaceSvg;
-    onNodeFocus(): void;
-    onNodeBlur(): void;
-    canBeFocused(): boolean;
-    abstract performAction(_e: Event): void;
-    dispose(): void;
-}
 /**
  * Class for a zoom controls.
  */
@@ -115,13 +77,5 @@ export declare class ZoomControls implements IPositionable {
      * @param savedPositions List of rectangles that are already on the workspace.
      */
     position(metrics: UiMetrics, savedPositions: Rect[]): void;
-    /**
-     * Returns the individual zoom control, if any, with the given ID. Used for
-     * focus management.
-     *
-     * @internal
-     */
-    getControlWithId(id: string): ZoomControl | undefined;
 }
-export {};
 //# sourceMappingURL=zoom_controls.d.ts.map