blockly 13.0.0-beta.1 → 13.0.0-beta.2

package/core/block.d.ts

@@ -174,6 +174,8 @@ export declare class Block {
     type: string;
     inputsInlineDefault?: boolean;
     workspace: Workspace;
+    /** A custom provider for generating the aria role description for this block. */
+    private ariaRoleDescriptionProvider;
     /**
      * @param workspace The block's workspace.
      * @param prototypeName Name of the language object containing type-specific
@@ -695,6 +697,22 @@ export declare class Block {
      * @param collapsed True if collapsed.
      */
     setCollapsed(collapsed: boolean): void;
+    /**
+     * Set a custom aria role description provider for this block. If not set,
+     * uses a default provider based on the block's properties (e.g. whether it has
+     * inputs, outputs, etc.).
+     *
+     * @param description The description or function to provide the description.
+     *   If a string, we'll replace message references in the string, e.g.
+     *   `%{BKY_CUSTOM_MESSAGE}` will be replaced with the value of
+     *   `Blockly.Msg['CUSTOM_MESSAGE']`.}'
+     */
+    setAriaRoleDescriptionProvider(description: string | (() => string)): void;
+    /**
+     * @returns The custom string to use as the role description for this block,
+     *   or undefined if no custom description is set.
+     */
+    getAriaRoleDescription(): string | undefined;
     /**
      * Create a human-readable text representation of this block and any children.
      *

package/core/block_aria_composer.d.ts

@@ -4,8 +4,8 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import type { BlockSvg } from './block_svg.js';
-import { RenderedConnection } from './blockly.js';
 import type { Input } from './inputs/input.js';
+import { RenderedConnection } from './rendered_connection.js';
 import { Verbosity } from './utils/aria.js';
 /**
  * Prepositions to use when describing the relationship between two blocks based

package/core/bubbles/bubble.d.ts

@@ -13,6 +13,12 @@ import { Coordinate } from '../utils/coordinate.js';
 import { Rect } from '../utils/rect.js';
 import { Size } from '../utils/size.js';
 import { WorkspaceSvg } from '../workspace_svg.js';
+/**
+ * Represents a either a string or a function that, when called, can provide a
+ * custom ARIA string to represent a bubble, or null if the default fallback
+ * should be used. See setAriaLabelProvider for more context.
+ */
+export type AriaLabelProvider = string | ((bubble: Bubble) => string | null);
 /**
  * The abstract pop-up bubble class. This creates a UI that looks like a speech
  * bubble, where it has a "tail" that points to the block, and a "head" that
@@ -66,6 +72,7 @@ export declare abstract class Bubble implements IBubble, ISelectable, IFocusable
     private relativeLeft;
     private dragStrategy;
     private focusableElement;
+    private ariaLabelProvider;
     /**
      * @param workspace The workspace this bubble belongs to.
      * @param anchor The anchor location of the thing this bubble is attached to.
@@ -239,5 +246,37 @@ export declare abstract class Bubble implements IBubble, ISelectable, IFocusable
      * Returns the object that owns/hosts this bubble, if any.
      */
     getOwner(): (IHasBubble & IFocusableNode) | undefined;
+    /**
+     * Recomputes the ARIA label and role for this bubble. This is automatically called
+     * during initialization, but implementations may find it useful to call this if
+     * the bubble's label should be changed.
+     *
+     * Bubbles use a default non-specific label unless they're customized otherwise
+     * which is the responsibility of the bubble's owner rather than bubble
+     * implementations. Customization can be done via setAriaLabelProvider.
+     */
+    protected recomputeAriaContext(): void;
+    /**
+     * Sets a custom ARIA label provider for this bubble, or null if it should be reset
+     * to use the default method.
+     *
+     * Bubbles do not compute ARIA labels specifically to their implementation since
+     * they can be rather general-purpose. Instead, owners of the specific bubble
+     * instance (such as an icon) are responsible for defining custom label providers
+     * for their bubbles.
+     *
+     * Note that calling this isn't sufficient for it to actually be used.
+     * recomputeAriaContext will likely also need to be called to actually apply the
+     * custom label to the bubble's focusable element.
+     */
+    setAriaLabelProvider(provider: AriaLabelProvider | null): void;
+    /**
+     * Returns the ARIA label to use for this bubble based on the provider set via
+     * setAriaLabelProvider. This will return null if the provider is absent or
+     * returns null.
+     *
+     * @returns The ARIA label to use for this bubble, or null if one is not provided.
+     */
+    getAriaLabel(): string | null;
 }
 //# sourceMappingURL=bubble.d.ts.map

package/core/field_checkbox.d.ts

@@ -114,6 +114,29 @@ export declare class FieldCheckbox extends Field<CheckboxBool> {
      * @returns The converted value.
      */
     private convertValueToBool;
+    /**
+     * 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;
+    /**
+     * 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.
+     *
+     * The FieldCheckbox implementation is not used for the actual ARIA label of
+     * the field, since the checked state is already included in the ARIA checked
+     * state, but it is used for the ARIA label of its source block.
+     *
+     * @returns An ARIA representation of the field's text.
+     */
+    getAriaValue(): string | null;
     /**
      * Construct a FieldCheckbox from a JSON arg object.
      *
@@ -123,6 +146,10 @@ export declare class FieldCheckbox extends Field<CheckboxBool> {
      * @internal
      */
     static fromJson(options: FieldCheckboxFromJsonConfig): FieldCheckbox;
+    /**
+     * Recomputes the ARIA role and label for this field.
+     */
+    protected recomputeAriaContext(): void;
 }
 /**
  * Config options for the checkbox field.

package/core/field_dropdown.d.ts

@@ -56,6 +56,11 @@ export declare class FieldDropdown extends Field<string> {
     protected static IMAGE_Y_OFFSET: number;
     /** The total vertical padding above and below an image. */
     protected static IMAGE_Y_PADDING: number;
+    /**
+     * True once the field’s DOM has been created and it is safe to run ARIA
+     * updates in response to value changes.
+     */
+    isInitialized: boolean;
     /**
      * @param menuGenerator A non-empty array of options for a dropdown list, or a
      *     function which generates these options. Also accepts Field.SKIP_SETUP
@@ -238,6 +243,50 @@ export declare class FieldDropdown extends Field<string> {
      * @throws {TypeError} If proposed options are incorrectly structured.
      */
     protected validateOptions(options: MenuOption[]): void;
+    /**
+     * 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;
+    /**
+     * Returns the ARIA label for the currently selected dropdown option.
+     *
+     * @returns The computed ARIA label for the selected option, or `null` if no
+     * option is selected.
+     */
+    private getSelectedAriaLabel;
+    /**
+     * Recomputes the ARIA role and label for this field.
+     */
+    protected recomputeAriaContext(): void;
+    /**
+     * Computes an ARIA-friendly label for a dropdown option.
+     *
+     * The label is derived using a prioritized set of sources.
+     *
+     * Returned values are guaranteed to be non-empty strings for all non-separator
+     * options. Whitespace-only values are ignored when determining a usable label.
+     *
+     * @param option The dropdown option for which to compute the ARIA label.
+     * @param index The index of the option within the dropdown (0-based).
+     * @returns A string suitable for use as an ARIA label. Returns an empty string
+     *     only if the option is a separator.
+     */
+    private computeOptionAriaLabel;
 }
 /**
  * Definition of a human-readable image dropdown option.
@@ -247,6 +296,7 @@ export interface ImageProperties {
     alt: string;
     width: number;
     height: number;
+    ariaLabel?: string;
 }
 /**
  * An individual option in the dropdown menu. Can be either the string literal
@@ -255,7 +305,7 @@ export interface ImageProperties {
  * (text, ImageProperties object, or HTML element), and the second element is
  * the language-neutral value.
  */
-export type MenuOption = [string | ImageProperties | HTMLElement, string] | 'separator';
+export type MenuOption = [string | ImageProperties | HTMLElement, string, string?] | 'separator';
 /**
  * A function that generates an array of menu options for FieldDropdown
  * or its descendants.

package/core/field_image.d.ts

@@ -129,6 +129,30 @@ export declare class FieldImage extends Field<string> {
      * @internal
      */
     static fromJson(options: FieldImageFromJsonConfig): FieldImage;
+    /**
+     * 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, or null if no text is
+     *     currently defined or known for the field.
+     */
+    getAriaValue(): string | null;
+    /**
+     * Recomputes the ARIA role and label for this field.
+     */
+    protected recomputeAriaContext(): void;
 }
 /**
  * Config options for the image field.

package/core/field_input.d.ts

@@ -285,7 +285,7 @@ export declare abstract class FieldInput<T extends InputTypes> extends Field<str
     /**
      * Recomputes the ARIA role and label for this field.
      */
-    private recomputeAriaContext;
+    protected recomputeAriaContext(): void;
 }
 /**
  * Config options for the input field.

package/core/field_number.d.ts

@@ -160,6 +160,16 @@ export declare class FieldNumber extends FieldInput<number> {
      * @internal
      */
     static fromJson(options: FieldNumberFromJsonConfig): FieldNumber;
+    /**
+     * 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 number field.

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/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_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/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

@@ -35,7 +35,8 @@ export declare enum names {
     INFORMATION = "information",
     PERFORM_ACTION = "perform_action",
     DUPLICATE = "duplicate",
-    CLEANUP = "cleanup"
+    CLEANUP = "cleanup",
+    SHOW_TOOLTIP = "show_tooltip"
 }
 /**
  * Keyboard shortcut to hide chaff on escape.
@@ -112,6 +113,10 @@ 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/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

package/core/utils/aria.d.ts

@@ -187,7 +187,13 @@ export declare enum State {
      *
      * Value: a number representing the minimum allowed value for a range widget.
      */
-    VALUEMIN = "valuemin"
+    VALUEMIN = "valuemin",
+    /**
+     * See https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-owns
+     *
+     * Value: a space-separated list of element IDs that are owned by the current element.
+     */
+    OWNS = "owns"
 }
 /**
  * Used to control how verbose generated a11y labels are.

package/core/workspace.d.ts

@@ -353,7 +353,11 @@ export declare class Workspace {
      *
      * @param redo False if undo, true if redo.
      */
-    undo(redo: boolean): void;
+    undo(redo?: boolean): void;
+    /**
+     * Redoes the previous action.
+     */
+    redo(): void;
     /** Clear the undo/redo stacks. */
     clearUndo(): void;
     /**

package/core/workspace_svg.d.ts

@@ -377,6 +377,14 @@ export declare class WorkspaceSvg extends Workspace implements IContextMenu, IFo
      * @param handler Data that can be passed to eventHandling.unbind.
      */
     setResizeHandlerWrapper(handler: browserEvents.Data): void;
+    /**
+     * Sets Aria labels, roles, etc. for the workspace depending on the type of workspace it is.
+     */
+    setInitialAriaContext(): void;
+    /**
+     * Updates the label on the workspace to reflect the number of top-level stacks in the workspace.
+     */
+    private updateAriaLabel;
     /**
      * Create the workspace DOM elements.
      *