blockly 13.0.0-beta.1 → 13.0.0-beta.3

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/bubbles/textinput_bubble.d.ts

@@ -43,6 +43,7 @@ export declare class TextInputBubble extends Bubble {
     private editable;
     /** View responsible for supporting text editing. */
     private editor;
+    private readonly textChangeListener;
     /**
      * @param workspace The workspace this bubble belongs to.
      * @param anchor The anchor location of the thing this bubble is attached to.
@@ -103,5 +104,9 @@ export declare class TextInputBubble extends Bubble {
      * the comment editor.
      */
     performAction(): void;
+    /**
+     * Dispose of this bubble.
+     */
+    dispose(): void;
 }
 //# sourceMappingURL=textinput_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/icons/comment_icon.d.ts

@@ -115,6 +115,14 @@ export declare class CommentIcon extends Icon implements IHasBubble, ISerializab
      *     I.E. the block that owns this icon.
      */
     private getBubbleOwnerRect;
+    /**
+     * Returns the ARIA label to use for this icon (defaults to null). Note that this
+     * method will only be called during initialization by default, so dynamic changes
+     * to the icon's ARIA label need to be applied by calling recomputeAriaContext.
+     *
+     * @returns The ARIA label to use for this icon, or null to use a default.
+     */
+    protected getAriaLabel(): string | null;
 }
 /** The save state format for a comment icon. */
 export interface CommentState {

package/core/icons/icon.d.ts

@@ -86,5 +86,19 @@ export declare abstract class Icon implements IIcon, IContextMenu {
      */
     getSourceBlock(): Block;
     showContextMenu(e: PointerEvent): void;
+    /**
+     * Recomputes the ARIA label and role for this icon. This is automatically called
+     * during initialization, but implementations may find it useful to call this if
+     * the icon's label should be changed.
+     */
+    protected recomputeAriaContext(): void;
+    /**
+     * Returns the ARIA label to use for this icon (defaults to null). Note that this
+     * method will only be called during initialization by default, so dynamic changes
+     * to the icon's ARIA label need to be applied by calling recomputeAriaContext.
+     *
+     * @returns The ARIA label to use for this icon, or null to use a default.
+     */
+    protected getAriaLabel(): string | null;
 }
 //# sourceMappingURL=icon.d.ts.map

package/core/icons/mutator_icon.d.ts

@@ -92,5 +92,13 @@ export declare class MutatorIcon extends Icon implements IHasBubble {
      *     currently open.
      */
     getWorkspace(): WorkspaceSvg | undefined;
+    /**
+     * Returns the ARIA label to use for this icon (defaults to null). Note that this
+     * method will only be called during initialization by default, so dynamic changes
+     * to the icon's ARIA label need to be applied by calling recomputeAriaContext.
+     *
+     * @returns The ARIA label to use for this icon, or null to use a default.
+     */
+    protected getAriaLabel(): string | null;
 }
 //# sourceMappingURL=mutator_icon.d.ts.map

package/core/icons/warning_icon.d.ts

@@ -73,5 +73,13 @@ export declare class WarningIcon extends Icon implements IHasBubble {
      *     I.E. the block that owns this icon.
      */
     private getBubbleOwnerRect;
+    /**
+     * Returns the ARIA label to use for this icon (defaults to null). Note that this
+     * method will only be called during initialization by default, so dynamic changes
+     * to the icon's ARIA label need to be applied by calling recomputeAriaContext.
+     *
+     * @returns The ARIA label to use for this icon, or null to use a default.
+     */
+    protected getAriaLabel(): string | null;
 }
 //# sourceMappingURL=warning_icon.d.ts.map

package/core/inputs/input.d.ts

@@ -17,6 +17,12 @@ import type { Field } from '../field.js';
 import { Verbosity } from '../utils/aria.js';
 import { Align } from './align.js';
 import { inputTypes } from './input_types.js';
+/**
+ * Represents a string or a function that returns a string which can be used as a
+ * custom ARIA string to represent an Input, or null if the default fallback should
+ * be used. See setAriaLabelProvider for more context.
+ */
+export type AriaLabelProvider = ((input: Input) => string | null) | string;
 /** Class for an input with optional fields. */
 export declare class Input {
     name: string;
@@ -26,6 +32,8 @@ export declare class Input {
     align: Align;
     /** Is the input visible? */
     private visible;
+    /** The AriaLabelProvider */
+    private ariaLabelProvider;
     readonly type: inputTypes;
     connection: Connection | null;
     /**
@@ -123,6 +131,26 @@ export declare class Input {
     getShadowDom(): Element | null;
     /** Initialize the fields on this input. */
     init(): void;
+    /**
+     * Sets a custom ARIA label provider for this input, or null if it should be reset
+     * to use the default method.
+     *
+     * Inputs do not compute ARIA contexts directly, so the set provider will be used
+     * in select cases when the Input needs to be represented (such as for parts of a
+     * block label or for connections). Note that overriding this provider will not
+     * recompute any already constructed ARIA labels, and it cannot be assumed that the
+     * provider will be called any particular number of times during label
+     * recomputation. As such, implementations should make sure to provide a
+     * deterministic and idempotent ARIA representation each time the provider is
+     * called for a given input. It's also fine to reuse providers across multiple
+     * Input implementations.
+     */
+    setAriaLabelProvider(provider: AriaLabelProvider | null): void;
+    /**
+     * Returns the string from the custom ARIA label provider set, or null if the default label (from the field row) should
+     * be used. See setAriaLabelProvider for more context.
+     */
+    getAriaLabelText(): string | null;
     /**
      * Initializes the fields on this input for a headless block.
      *

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().