blockly 12.5.1 → 13.0.0-beta.1

package/core/dragging/block_drag_strategy.d.ts

@@ -3,9 +3,23 @@
  * Copyright 2024 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import { BlockSvg } from '../block_svg.js';
-import { IDragStrategy } from '../interfaces/i_draggable.js';
+import type { BlockSvg } from '../block_svg.js';
+import type { IDragStrategy } from '../interfaces/i_draggable.js';
+import { DragDisposition } from '../interfaces/i_draggable.js';
+import type { RenderedConnection } from '../rendered_connection.js';
 import { Coordinate } from '../utils.js';
+/** Represents a valid pair of connections between the dragging block and a block on the workspace. */
+interface ConnectionPair {
+    /** A connection on the dragging stack that is compatible with neighbour. */
+    local: RenderedConnection;
+    /** A nearby connection that is compatible with local. */
+    neighbour: RenderedConnection;
+}
+/** Represents a nearby valid connection. */
+interface ConnectionCandidate extends ConnectionPair {
+    /** The distance between the local connection and the neighbour connection. */
+    distance: number;
+}
 export declare class BlockDragStrategy implements IDragStrategy {
     private block;
     private workspace;
@@ -20,21 +34,53 @@ export declare class BlockDragStrategy implements IDragStrategy {
     private connectionCandidate;
     private connectionPreviewer;
     private dragging;
-    /**
-     * If this is a shadow block, the offset between this block and the parent
-     * block, to add to the drag location. In workspace units.
-     */
-    private dragOffset;
+    /** List of all connections available on the workspace. */
+    private allConnectionPairs;
+    /** The current movement mode. */
+    private moveMode;
     /** Used to persist an event group when snapping is done async. */
     private originalEventGroup;
+    protected readonly BLOCK_CONNECTION_OFFSET = 10;
     constructor(block: BlockSvg);
     /** Returns true if the block is currently movable. False otherwise. */
     isMovable(): boolean;
+    /**
+     * Positions a cloned block on its new workspace.
+     *
+     * @param oldBlock The flyout block that was cloned.
+     * @param newBlock The new block to position.
+     */
+    private positionNewBlock;
+    /**
+     * Returns the block to use for the current drag operation. This may create
+     * and return a newly instantiated block when e.g. dragging from a flyout.
+     */
+    protected getTargetBlock(): BlockSvg;
+    /**
+     * Announces a move on the ARIA live region for assistive technologies.
+     *
+     * @param isMoveStart Whether this announcement is for the start of a move. If false,
+     * skip announcing the block label since it should have already been announced at the
+     * start of the move.
+     */
+    private announceMove;
+    /**
+     * Checks if there are multiple compatible connections for the specified side of the pair.
+     *
+     * @param forLocal Whether we are considering the local or neighbour side of the pair
+     * @returns True if there are multiple compatible connections, false otherwise
+     */
+    private hasMultipleCompatibleConnections;
     /**
      * Handles any setup for starting the drag, including disconnecting the block
      * from any parent blocks.
      */
-    startDrag(e?: PointerEvent): void;
+    startDrag(e?: PointerEvent | KeyboardEvent): import("../interfaces/i_draggable.js").IDraggable;
+    /**
+     * Handles any setup for starting the drag, including disconnecting the block
+     * from any parent blocks.
+     */
+    private cacheAllConnectionPairs;
     /**
      * Returns an array of visible bubbles attached to the given block or its
      * descendants.
@@ -47,13 +93,11 @@ export declare class BlockDragStrategy implements IDragStrategy {
     /**
      * Get whether the drag should act on a single block or a block stack.
      *
-     * @param e The instigating pointer event, if any.
+     * @param e The instigating pointer or keyboard event, if any.
      * @returns True if just the initial block should be dragged out, false
      *     if all following blocks should also be dragged.
      */
-    protected shouldHealStack(e: PointerEvent | undefined): boolean;
-    /** Starts a drag on a shadow, recording the drag offset. */
-    private startDraggingShadow;
+    protected shouldHealStack(e: PointerEvent | KeyboardEvent | undefined): boolean;
     /**
      * Whether or not we should disconnect the block when a drag is started.
      *
@@ -69,6 +113,12 @@ export declare class BlockDragStrategy implements IDragStrategy {
      * @param healStack Whether or not to heal the stack after disconnecting.
      */
     private disconnectBlock;
+    /**
+     * Stores the dragging block's current parent or child connection before
+     * unplugging. This allows us to revert the drag cleanly. In keyboard move mode,
+     * the initial connection pair is also used as the first connection candidate.
+     */
+    private storeInitialConnections;
     /** Fire a UI event at the start of a block drag. */
     private fireDragStartEvent;
     /** Fire a UI event at the end of a block drag. */
@@ -76,11 +126,15 @@ export declare class BlockDragStrategy implements IDragStrategy {
     /** Fire a move event at the end of a block drag. */
     private fireMoveEvent;
     /** Moves the block and updates any connection previews. */
-    drag(newLoc: Coordinate): void;
+    drag(newLoc: Coordinate, e?: PointerEvent | KeyboardEvent): void;
     /**
+     * Renders the connection preview indicator.
+     *
      * @param draggingBlock The block being dragged.
      * @param delta How far the pointer has moved from the position
      *     at the start of the drag, in workspace units.
+     * @returns The neighbouring connection to which the connection preview will
+     *     be attached.
      */
     private updateConnectionPreview;
     /**
@@ -101,6 +155,14 @@ export declare class BlockDragStrategy implements IDragStrategy {
      * compatible type (input, output, etc) and connection check.
      */
     private getConnectionCandidate;
+    /**
+     * Returns the closest connection candidate for the given block.
+     *
+     * @param block The block to find a connection for.
+     * @param delta The distance the block has traveled since dragging began.
+     * @returns The closest available connection candidate, if any.
+     */
+    private getClosestCandidate;
     /**
      * Get the radius to use when searching for a nearby valid connection.
      */
@@ -116,7 +178,7 @@ export declare class BlockDragStrategy implements IDragStrategy {
      * Cleans up any state at the end of the drag. Applies any pending
      * connections.
      */
-    endDrag(e?: PointerEvent): void;
+    endDrag(_e: PointerEvent | KeyboardEvent | undefined, disposition: DragDisposition): void;
     /** Disposes of any state at the end of the drag. */
     private disposeStep;
     /** Connects the given candidate connections. */
@@ -126,5 +188,55 @@ export declare class BlockDragStrategy implements IDragStrategy {
      * including reconnecting connections.
      */
     revertDrag(): void;
+    /**
+     * Get the nearest valid candidate connection in traversal order.
+     *
+     * @param delta The distance the block has moved since this drag began.
+     * @returns A candidate connection and radius, or null if none was found.
+     */
+    findTraversalCandidate(delta: Coordinate): ConnectionCandidate | null;
+    /**
+     * Returns whether or not the given block is at a terminal position (start or
+     * end) of the blocks on the workspace. This helps distinguish between a block
+     * that is at the end of the line because all valid connections have been
+     * visited and the proposed constrained move destination is now to drop it on
+     * the workspace as a top-level block (in which case it will be in a terminal
+     * position), and a block that just entered move mode as a top-level block,
+     * and should therefore still be able to move to another connection point
+     * even if looping is disabled.
+     *
+     * @param block The block to check.
+     * @param direction The current dragging direction.
+     * @returns True if the block is at the start or end of its possible positions
+     *     on the workspace.
+     */
+    private isInTerminalPosition;
+    /**
+     * Converts a connection pair to a connection candidate with a default
+     * distance of 0.
+     */
+    private pairToCandidate;
+    /**
+     * Returns the cardinal direction that the block being dragged would have to
+     * move in to reach the given location.
+     * The given coordinate should differ from the current location on only one
+     * axis.
+     *
+     * @param newLocation The intended destination for the block.
+     * @returns The direction the block would need to travel to reach the new
+     *     location.
+     */
+    private getDirectionToNewLocation;
+    /**
+     * Returns all navigable connections on the given block and its children.
+     * Omits connections on shadow blocks, collapsed blocks, or those that are
+     * associated with a hidden input.
+     *
+     * @param block The block to use as a starting point for retrieving
+     *     connections.
+     * @returns All connections on the block and its children.
+     */
+    private getAllConnections;
 }
+export {};
 //# sourceMappingURL=block_drag_strategy.d.ts.map

package/core/dragging/bubble_drag_strategy.d.ts

@@ -3,16 +3,17 @@
  * Copyright 2024 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import { IBubble, WorkspaceSvg } from '../blockly.js';
-import { IDragStrategy } from '../interfaces/i_draggable.js';
-import { Coordinate } from '../utils.js';
+import type { IBubble } from '../interfaces/i_bubble.js';
+import type { IDragStrategy } from '../interfaces/i_draggable.js';
+import type { Coordinate } from '../utils.js';
+import type { WorkspaceSvg } from '../workspace_svg.js';
 export declare class BubbleDragStrategy implements IDragStrategy {
     private bubble;
     private workspace;
     private startLoc;
     constructor(bubble: IBubble, workspace: WorkspaceSvg);
     isMovable(): boolean;
-    startDrag(): void;
+    startDrag(): IBubble;
     drag(newLoc: Coordinate): void;
     endDrag(): void;
     revertDrag(): void;

package/core/dragging/comment_drag_strategy.d.ts

@@ -3,16 +3,16 @@
  * Copyright 2024 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import { RenderedWorkspaceComment } from '../comments.js';
-import { IDragStrategy } from '../interfaces/i_draggable.js';
-import { Coordinate } from '../utils.js';
+import type { RenderedWorkspaceComment } from '../comments.js';
+import type { IDragStrategy } from '../interfaces/i_draggable.js';
+import type { Coordinate } from '../utils.js';
 export declare class CommentDragStrategy implements IDragStrategy {
     private comment;
     private startLoc;
     private workspace;
     constructor(comment: RenderedWorkspaceComment);
     isMovable(): boolean;
-    startDrag(): void;
+    startDrag(): RenderedWorkspaceComment;
     drag(newLoc: Coordinate): void;
     endDrag(): void;
     /** Fire a UI event at the start of a comment drag. */

package/core/dragging/dragger.d.ts

@@ -3,29 +3,27 @@
  * Copyright 2024 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import { IDeletable } from '../interfaces/i_deletable.js';
-import { IDragTarget } from '../interfaces/i_drag_target.js';
-import { IDraggable } from '../interfaces/i_draggable.js';
-import { IDragger } from '../interfaces/i_dragger.js';
+import type { IDeletable } from '../interfaces/i_deletable.js';
+import type { IDragTarget } from '../interfaces/i_drag_target.js';
+import { type IDraggable } from '../interfaces/i_draggable.js';
+import type { IDragger } from '../interfaces/i_dragger.js';
 import { Coordinate } from '../utils/coordinate.js';
-import { WorkspaceSvg } from '../workspace_svg.js';
 export declare class Dragger implements IDragger {
     protected draggable: IDraggable;
-    protected workspace: WorkspaceSvg;
     protected startLoc: Coordinate;
     protected dragTarget: IDragTarget | null;
-    constructor(draggable: IDraggable, workspace: WorkspaceSvg);
+    constructor(draggable: IDraggable);
     /** Handles any drag startup. */
-    onDragStart(e: PointerEvent): void;
+    onDragStart(e?: PointerEvent | KeyboardEvent): IDraggable;
     /**
      * Handles calculating where the element should actually be moved to.
      *
      * @param totalDelta The total amount in pixel coordinates the mouse has moved
      *     since the start of the drag.
      */
-    onDrag(e: PointerEvent, totalDelta: Coordinate): void;
+    onDrag(e: PointerEvent | KeyboardEvent | undefined, totalDelta: Coordinate): void;
     /** Updates the drag target under the pointer (if there is one). */
-    protected updateDragTarget(e: PointerEvent): void;
+    protected updateDragTarget(coordinate: Coordinate): void;
     /**
      * Calculates the correct workspace coordinate for the movable and tells
      * the draggable to go to that location.
@@ -35,15 +33,16 @@ export declare class Dragger implements IDragger {
      * Returns true if we would delete the draggable if it was dropped
      * at the current location.
      */
-    protected wouldDeleteDraggable(e: PointerEvent, rootDraggable: IDraggable & IDeletable): boolean;
+    protected wouldDeleteDraggable(coordinate: Coordinate, rootDraggable: IDraggable & IDeletable): boolean;
     /** Handles any drag cleanup. */
-    onDragEnd(e: PointerEvent): void;
-    private getRoot;
+    onDragEnd(e?: PointerEvent | KeyboardEvent): void;
+    /** Handles a drag being reverted. */
+    onDragRevert(): void;
     /**
      * Returns true if we should return the draggable to its original location
      * at the end of the drag.
      */
-    protected shouldReturnToStart(e: PointerEvent, rootDraggable: IDraggable): boolean;
+    protected shouldReturnToStart(coordinate: Coordinate, rootDraggable: IDraggable): boolean;
     protected pixelsToWorkspaceUnits(pixelCoord: Coordinate): Coordinate;
 }
 //# sourceMappingURL=dragger.d.ts.map

package/core/events/events_block_create.d.ts

@@ -19,8 +19,6 @@ import { EventType } from './type.js';
  */
 export declare class BlockCreate extends BlockBase {
     type: EventType;
-    /** The XML representation of the created block(s). */
-    xml?: Element | DocumentFragment;
     /** The JSON respresentation of the created block(s). */
     json?: blocks.State;
     /** All of the IDs of created blocks. */
@@ -51,7 +49,6 @@ export declare class BlockCreate extends BlockBase {
     run(forward: boolean): void;
 }
 export interface BlockCreateJson extends BlockBaseJson {
-    xml: string;
     ids: string[];
     json: object;
     recordUndo?: boolean;

package/core/events/events_block_delete.d.ts

@@ -18,8 +18,6 @@ import { EventType } from './type.js';
  * deleted.
  */
 export declare class BlockDelete extends BlockBase {
-    /** The XML representation of the deleted block(s). */
-    oldXml?: Element | DocumentFragment;
     /** The JSON respresentation of the deleted block(s). */
     oldJson?: blocks.State;
     /** All of the IDs of deleted blocks. */
@@ -53,7 +51,6 @@ export declare class BlockDelete extends BlockBase {
     run(forward: boolean): void;
 }
 export interface BlockDeleteJson extends BlockBaseJson {
-    oldXml: string;
     ids: string[];
     wasShadow: boolean;
     oldJson: blocks.State;

package/core/events/events_comment_create.d.ts

@@ -18,8 +18,6 @@ import { EventType } from './type.js';
  */
 export declare class CommentCreate extends CommentBase {
     type: EventType;
-    /** The XML representation of the created workspace comment. */
-    xml?: Element | DocumentFragment;
     /** The JSON representation of the created workspace comment. */
     json?: comments.State;
     /**
@@ -51,7 +49,6 @@ export declare class CommentCreate extends CommentBase {
     run(forward: boolean): void;
 }
 export interface CommentCreateJson extends CommentBaseJson {
-    xml: string;
     json: object;
 }
 //# sourceMappingURL=events_comment_create.d.ts.map

package/core/events/events_comment_delete.d.ts

@@ -18,8 +18,6 @@ import { EventType } from './type.js';
  */
 export declare class CommentDelete extends CommentBase {
     type: EventType;
-    /** The XML representation of the deleted workspace comment. */
-    xml?: Element;
     /** The JSON representation of the created workspace comment. */
     json?: comments.State;
     /**
@@ -51,7 +49,6 @@ export declare class CommentDelete extends CommentBase {
     static fromJson(json: CommentDeleteJson, workspace: Workspace, event?: any): CommentDelete;
 }
 export interface CommentDeleteJson extends CommentBaseJson {
-    xml: string;
     json: object;
 }
 //# sourceMappingURL=events_comment_delete.d.ts.map

package/core/field.d.ts

@@ -70,6 +70,8 @@ export declare abstract class Field<T = any> implements IKeyboardAccessible, IRe
     protected value_: T | null;
     /** Validation function called when user edits an editable field. */
     protected validator_: FieldValidator<T> | null;
+    /** The ARIA-friendly label representation of this field's type. */
+    protected ariaTypeName: string | null;
     /**
      * Used to cache the field's tooltip value if setTooltip is called when the
      * field is not yet initialized. Is *not* guaranteed to be accurate.
@@ -184,6 +186,63 @@ export declare abstract class Field<T = any> implements IKeyboardAccessible, IRe
      * @throws An error if the source block is not defined.
      */
     getSourceBlock(): Block | null;
+    /**
+     * 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 null if it is
+     *     unspecified.
+     */
+    getAriaTypeName(): string | null;
+    /**
+     * Gets an ARIA-friendly label representation of this field's value.
+     *
+     * Note that implementations should generally always override this value to
+     * ensure a non-null value is returned. The default implementation relies on
+     * 'getText' which may return an empty string. A null return value from this
+     * function will prompt ARIA label generation to skip the field's value
+     * entirely when there may be a better contextual placeholder to use isstead.
+     *
+     * For example, to avoid hiding an empty text input field from screen reader,
+     * implementations should ensure that if the text is an empty string, this
+     * function would return an appropriate, localized value such as "empty text".
+     *
+     * 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, or null if no text is
+     *     currently defined or known for the field.
+     */
+    getAriaValue(): string | null;
+    /**
+     * Computes a descriptive ARIA label to represent this field with configurable
+     * verbosity.
+     *
+     * A 'verbose' label includes type information, if available, whereas a
+     * non-verbose label only contains the field's value.
+     *
+     * Note that this will always return the latest representation of the field's
+     * label which may differ from any previously set ARIA label for the field
+     * itself. Implementations are largely responsible for ensuring that the
+     * field's ARIA label is set correctly at relevant moments in the field's
+     * lifecycle (such as when its value changes).
+     *
+     * Finally, it is never guaranteed that implementations use the label returned
+     * by this method for their actual ARIA label. Some implementations may rely
+     * on other contexts to convey information like the field's value. Example:
+     * checkboxes represent their checked/non-checked status (i.e. value) through
+     * a separate ARIA property.
+     *
+     * It's not expected that this method, under normal operations, returns an empty
+     * string. If the field's value is empty then it will return a localized
+     * placeholder indicating that its value is empty.
+     *
+     * @param includeTypeInfo Whether to include the field's type information in
+     *     the returned label, if available.
+     */
+    computeAriaLabel(includeTypeInfo?: boolean): string;
     /**
      * Initialize everything to render this field. Override
      * methods initModel and initView rather than this method.
@@ -219,9 +278,11 @@ export declare abstract class Field<T = any> implements IKeyboardAccessible, IRe
      */
     protected createBorderRect_(): void;
     /**
-     * Create a field text element. Not to be overridden by subclasses. Instead
+     * Create a field text element. Not to be overridden by subclasses. Instead,
      * modify the result of the function inside initView, or create a separate
-     * function to call.
+     * function to call. Aria state is hidden; use the aria label for the field
+     * and/or containing block to expose content to screen readers. Text content
+     * for custom blocks can be set after creation.
      */
     protected createTextElement_(): void;
     /**
@@ -684,6 +745,11 @@ export declare abstract class Field<T = any> implements IKeyboardAccessible, IRe
     onNodeBlur(): void;
     /** See IFocusableNode.canBeFocused. */
     canBeFocused(): boolean;
+    /**
+     * Handles the user acting on this field via keyboard navigation.
+     * Shows and focuses the field editor.
+     */
+    performAction(): void;
     /**
      * Subclasses should reimplement this method to construct their Field
      * subclass from a JSON arg object.
@@ -701,6 +767,7 @@ export declare abstract class Field<T = any> implements IKeyboardAccessible, IRe
  */
 export interface FieldConfig {
     tooltip?: string;
+    ariaTypeName?: string;
 }
 /**
  * Represents an object that has all the prototype properties of the `Field`

package/core/field_input.d.ts

@@ -263,6 +263,29 @@ export declare abstract class FieldInput<T extends InputTypes> extends Field<str
      * @returns The value to store.
      */
     protected getValueFromEditorText_(text: string): any;
+    /**
+     * 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;
+    /**
+     * 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 | null;
+    /**
+     * Recomputes the ARIA role and label for this field.
+     */
+    private recomputeAriaContext;
 }
 /**
  * Config options for the input field.