@cp949/phyx-blockly 12.5.1-p1 → 13.4.0-patch.1

package/core/events/events_comment_change.d.ts

@@ -10,7 +10,8 @@
  */
 import type { WorkspaceComment } from '../comments/workspace_comment.js';
 import type { Workspace } from '../workspace.js';
-import { CommentBase, CommentBaseJson } from './events_comment_base.js';
+import type { CommentBaseJson } from './events_comment_base.js';
+import { CommentBase } from './events_comment_base.js';
 import { EventType } from './type.js';
 /**
  * Notifies listeners that the contents of a workspace comment has changed.

package/core/events/events_comment_collapse.d.ts

@@ -3,9 +3,10 @@
  * Copyright 2024 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import { WorkspaceComment } from '../comments/workspace_comment.js';
+import type { WorkspaceComment } from '../comments/workspace_comment.js';
 import type { Workspace } from '../workspace.js';
-import { CommentBase, CommentBaseJson } from './events_comment_base.js';
+import type { CommentBaseJson } from './events_comment_base.js';
+import { CommentBase } from './events_comment_base.js';
 import { EventType } from './type.js';
 export declare class CommentCollapse extends CommentBase {
     newCollapsed?: boolean | undefined;

package/core/events/events_comment_create.d.ts

@@ -11,15 +11,14 @@
 import type { WorkspaceComment } from '../comments/workspace_comment.js';
 import * as comments from '../serialization/workspace_comments.js';
 import type { Workspace } from '../workspace.js';
-import { CommentBase, CommentBaseJson } from './events_comment_base.js';
+import type { CommentBaseJson } from './events_comment_base.js';
+import { CommentBase } from './events_comment_base.js';
 import { EventType } from './type.js';
 /**
  * Notifies listeners that a workspace comment was created.
  */
 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 +50,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

@@ -11,15 +11,14 @@
 import type { WorkspaceComment } from '../comments/workspace_comment.js';
 import * as comments from '../serialization/workspace_comments.js';
 import type { Workspace } from '../workspace.js';
-import { CommentBase, CommentBaseJson } from './events_comment_base.js';
+import type { CommentBaseJson } from './events_comment_base.js';
+import { CommentBase } from './events_comment_base.js';
 import { EventType } from './type.js';
 /**
  * Notifies listeners that a workspace comment has been deleted.
  */
 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 +50,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/events/events_comment_drag.d.ts

@@ -7,8 +7,8 @@
  * Events fired when a workspace comment is dragged.
  */
 import type { WorkspaceComment } from '../comments/workspace_comment.js';
-import { Workspace } from '../workspace.js';
-import { AbstractEventJson } from './events_abstract.js';
+import type { Workspace } from '../workspace.js';
+import type { AbstractEventJson } from './events_abstract.js';
 import { UiBase } from './events_ui_base.js';
 import { EventType } from './type.js';
 /**

package/core/events/events_comment_move.d.ts

@@ -11,7 +11,8 @@
 import type { WorkspaceComment } from '../comments/workspace_comment.js';
 import { Coordinate } from '../utils/coordinate.js';
 import type { Workspace } from '../workspace.js';
-import { CommentBase, CommentBaseJson } from './events_comment_base.js';
+import type { CommentBaseJson } from './events_comment_base.js';
+import { CommentBase } from './events_comment_base.js';
 import { EventType } from './type.js';
 /**
  * Notifies listeners that a workspace comment has moved.

package/core/events/events_comment_resize.d.ts

@@ -9,7 +9,8 @@
 import type { WorkspaceComment } from '../comments/workspace_comment.js';
 import { Size } from '../utils/size.js';
 import type { Workspace } from '../workspace.js';
-import { CommentBase, CommentBaseJson } from './events_comment_base.js';
+import type { CommentBaseJson } from './events_comment_base.js';
+import { CommentBase } from './events_comment_base.js';
 import { EventType } from './type.js';
 /**
  * Notifies listeners that a workspace comment has resized.

package/core/events/events_selected.d.ts

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import type { Workspace } from '../workspace.js';
-import { AbstractEventJson } from './events_abstract.js';
+import type { AbstractEventJson } from './events_abstract.js';
 import { UiBase } from './events_ui_base.js';
 import { EventType } from './type.js';
 /**

package/core/events/events_theme_change.d.ts

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import type { Workspace } from '../workspace.js';
-import { AbstractEventJson } from './events_abstract.js';
+import type { AbstractEventJson } from './events_abstract.js';
 import { UiBase } from './events_ui_base.js';
 import { EventType } from './type.js';
 /**

package/core/events/events_toolbox_item_select.d.ts

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import type { Workspace } from '../workspace.js';
-import { AbstractEventJson } from './events_abstract.js';
+import type { AbstractEventJson } from './events_abstract.js';
 import { UiBase } from './events_ui_base.js';
 import { EventType } from './type.js';
 /**

package/core/events/events_trashcan_open.d.ts

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import type { Workspace } from '../workspace.js';
-import { AbstractEventJson } from './events_abstract.js';
+import type { AbstractEventJson } from './events_abstract.js';
 import { UiBase } from './events_ui_base.js';
 import { EventType } from './type.js';
 /**

package/core/events/events_var_base.d.ts

@@ -10,7 +10,8 @@
  */
 import type { IVariableModel, IVariableState } from '../interfaces/i_variable_model.js';
 import type { Workspace } from '../workspace.js';
-import { Abstract as AbstractEvent, AbstractEventJson } from './events_abstract.js';
+import type { AbstractEventJson } from './events_abstract.js';
+import { Abstract as AbstractEvent } from './events_abstract.js';
 /**
  * Abstract class for a variable event.
  */

package/core/events/events_var_create.d.ts

@@ -10,7 +10,8 @@
  */
 import type { IVariableModel, IVariableState } from '../interfaces/i_variable_model.js';
 import type { Workspace } from '../workspace.js';
-import { VarBase, VarBaseJson } from './events_var_base.js';
+import type { VarBaseJson } from './events_var_base.js';
+import { VarBase } from './events_var_base.js';
 import { EventType } from './type.js';
 /**
  * Notifies listeners that a variable model has been created.

package/core/events/events_var_delete.d.ts

@@ -5,7 +5,8 @@
  */
 import type { IVariableModel, IVariableState } from '../interfaces/i_variable_model.js';
 import type { Workspace } from '../workspace.js';
-import { VarBase, VarBaseJson } from './events_var_base.js';
+import type { VarBaseJson } from './events_var_base.js';
+import { VarBase } from './events_var_base.js';
 import { EventType } from './type.js';
 /**
  * Notifies listeners that a variable model has been deleted.

package/core/events/events_var_rename.d.ts

@@ -5,7 +5,8 @@
  */
 import type { IVariableModel, IVariableState } from '../interfaces/i_variable_model.js';
 import type { Workspace } from '../workspace.js';
-import { VarBase, VarBaseJson } from './events_var_base.js';
+import type { VarBaseJson } from './events_var_base.js';
+import { VarBase } from './events_var_base.js';
 import { EventType } from './type.js';
 /**
  * Notifies listeners that a variable model was renamed.

package/core/events/events_var_type_change.d.ts

@@ -10,7 +10,8 @@
  */
 import type { IVariableModel, IVariableState } from '../interfaces/i_variable_model.js';
 import type { Workspace } from '../workspace.js';
-import { VarBase, VarBaseJson } from './events_var_base.js';
+import type { VarBaseJson } from './events_var_base.js';
+import { VarBase } from './events_var_base.js';
 import { EventType } from './type.js';
 /**
  * Notifies listeners that a variable's type has changed.

package/core/events/events_viewport.d.ts

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import type { Workspace } from '../workspace.js';
-import { AbstractEventJson } from './events_abstract.js';
+import type { AbstractEventJson } from './events_abstract.js';
 import { UiBase } from './events_ui_base.js';
 import { EventType } from './type.js';
 /**

package/core/field.d.ts

@@ -10,14 +10,13 @@
  *
  * @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';
 import type { IFocusableTree } from './interfaces/i_focusable_tree.js';
 import type { IKeyboardAccessible } from './interfaces/i_keyboard_accessible.js';
 import type { IRegistrable } from './interfaces/i_registrable.js';
-import { ISerializable } from './interfaces/i_serializable.js';
+import type { ISerializable } from './interfaces/i_serializable.js';
 import type { ConstantProvider } from './renderers/common/constants.js';
 import type { KeyboardShortcut } from './shortcut_registry.js';
 import * as Tooltip from './tooltip.js';
@@ -28,7 +27,7 @@ import { Size } from './utils/size.js';
  * A function that is called to validate changes to the field's value before
  * they are set.
  *
- * @see {@link https://developers.google.com/blockly/guides/create-custom-blocks/fields/validators#return_values}
+ * @see {@link https://docs.blockly.com/guides/create-custom-blocks/fields/validators/#return-values}
  * @param newValue The value to be validated.
  * @returns One of three instructions for setting the new value: `T`, `null`,
  * or `undefined`.
@@ -43,7 +42,7 @@ export type FieldValidator<T = any> = (newValue: T) => T | null | undefined;
 /**
  * Abstract class for an editable field.
  *
- * @typeParam T - The value stored on the field.
+ * @template T - The value stored on the field.
  */
 export declare abstract class Field<T = any> implements IKeyboardAccessible, IRegistrable, ISerializable, IFocusableNode {
     /**
@@ -70,6 +69,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 +185,77 @@ 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;
+    /**
+     * Sets the ARIA-friendly label representation of this field's type.
+     *
+     * Implementations are responsible for, and encouraged to, set a localized
+     * version of the ARIA representation of the field's type. To that end, the
+     * provided value may contain message references of the form `%{BKY_...}`
+     * (e.g. `%{BKY_MY_FIELD_ARIA_TYPE}`), which are replaced with the
+     * corresponding `Blockly.Msg` value.
+     *
+     * @param ariaTypeName An ARIA representation of the field's type.
+     */
+    setAriaTypeName(ariaTypeName: string): void;
+    /**
+     * 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.
+     *
+     * If the field's value is empty then it will return a localized placeholder
+     * indicating that its value is empty. If this method returns an empty string,
+     * the output will be ignored when composing the block-level ARIA label. Make
+     * sure you want your label hidden from screenreaders before returning an
+     * empty string.
+     *
+     * @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.
@@ -204,14 +276,25 @@ export declare abstract class Field<T = any> implements IKeyboardAccessible, IRe
     /**
      * Defines whether this field should take up the full block or not.
      *
-     * Be cautious when overriding this function. It may not work as you expect /
-     * intend because the behavior was kind of hacked in. If you are thinking
-     * about overriding this function, post on the forum with your intended
-     * behavior to see if there's another approach.
+     * This is typically only done for certain kinds of fields and in certain
+     * renderers. You should only override this if you're sure your field will
+     * render correctly in zelos and other renderers that support full-block
+     * fields.
      *
-     * @internal
+     * Blocks that contain only a single field that is a full-block-field
+     * have a special appearance in some renderers and their behavior is
+     * unique, because we pretend that the field is a whole block in some cases.
+     * This is hacky and you should use caution when attempting to do anything
+     * 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
@@ -219,9 +302,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;
     /**
@@ -409,7 +494,7 @@ export declare abstract class Field<T = any> implements IKeyboardAccessible, IRe
      * at relevant times, such as when the parent block or renderer changes.
      *
      * See {@link
-     * https://developers.google.com/blockly/guides/create-custom-blocks/fields/customizing-fields/creating#matching_block_colours
+     * https://docs.blockly.com/guides/create-custom-blocks/fields/customizing-fields/creating/#matching-block-colours
      * | the field documentation} for more information, or FieldDropdown for an
      * example.
      */
@@ -575,7 +660,7 @@ export declare abstract class Field<T = any> implements IKeyboardAccessible, IRe
      * it is valid for a subclass to return `undefined` if the new value is
      * compatible with `T`.
      *
-     * @see {@link https://developers.google.com/blockly/guides/create-custom-blocks/fields/validators#return_values}
+     * @see {@link https://docs.blockly.com/guides/create-custom-blocks/fields/validators/#return-values}
      * @param newValue - The value to be validated.
      * @returns One of three instructions for setting the new value: `T`, `null`,
      * or `undefined`.
@@ -684,6 +769,27 @@ 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;
+    /**
+     * Recomputes the aria state and label for this field. Fields are generally hidden
+     * when in blocks in the flyout (except for top-level full-block fields), and
+     * otherwise set to a role of button (indicating they can be clicked to edit)
+     * and given the label returned from their `computeAriaLabel` method.
+     *
+     * Subclasses can override this in order to change the role or label, but they must
+     * ensure they keep the correct behavior for fields in flyout blocks.
+     *
+     * This method will return a boolean indicating if the element is displayed in the
+     * aria tree or not. This can be used by subclasses to determine whether or not
+     * to continue customizing the role and label (hidden elements should not have labels).
+     *
+     * @returns true if the element is in the accessibility tree, false if the aria state is hidden
+     */
+    recomputeAriaContext(): boolean;
     /**
      * Subclasses should reimplement this method to construct their Field
      * subclass from a JSON arg object.
@@ -701,6 +807,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_checkbox.d.ts

@@ -8,8 +8,8 @@
  *
  * @class
  */
-import './events/events_block_change.js';
-import { Field, FieldConfig, FieldValidator } from './field.js';
+import type { FieldConfig, FieldValidator } from './field.js';
+import { Field } from './field.js';
 type BoolString = 'TRUE' | 'FALSE';
 type CheckboxBool = BoolString | boolean;
 /**
@@ -40,7 +40,7 @@ export declare class FieldCheckbox extends Field<CheckboxBool> {
      *     validated value ('TRUE' or 'FALSE'), or null to abort the change.
      * @param config A map of options used to configure the field.
      *     See the [field creation documentation]{@link
-     * https://developers.google.com/blockly/guides/create-custom-blocks/fields/built-in-fields/checkbox#creation}
+     * https://docs.blockly.com/guides/create-custom-blocks/fields/built-in-fields/checkbox/#creation}
      * for a list of properties this parameter supports.
      */
     constructor(value?: CheckboxBool | typeof Field.SKIP_SETUP, validator?: FieldCheckboxValidator, config?: FieldCheckboxConfig);
@@ -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;
+    /**
+     * Customizes the label and sets additional aria state.
+     */
+    recomputeAriaContext(): boolean;
 }
 /**
  * Config options for the checkbox field.
@@ -140,7 +167,7 @@ export interface FieldCheckboxFromJsonConfig extends FieldCheckboxConfig {
  * A function that is called to validate changes to the field's value before
  * they are set.
  *
- * @see {@link https://developers.google.com/blockly/guides/create-custom-blocks/fields/validators#return_values}
+ * @see {@link https://docs.blockly.com/guides/create-custom-blocks/fields/validators/#return-values}
  * @param newValue The value to be validated.
  * @returns One of three instructions for setting the new value: `T`, `null`,
  * or `undefined`.

package/core/field_dropdown.d.ts

@@ -3,7 +3,8 @@
  * Copyright 2012 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import { Field, FieldConfig, FieldValidator } from './field.js';
+import type { FieldConfig, FieldValidator } from './field.js';
+import { Field } from './field.js';
 import { Menu } from './menu.js';
 import { MenuItem } from './menuitem.js';
 /**
@@ -56,6 +57,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
@@ -68,7 +74,7 @@ export declare class FieldDropdown extends Field<string> {
      *     change.
      * @param config A map of options used to configure the field.
      *     See the [field creation documentation]{@link
-     * https://developers.google.com/blockly/guides/create-custom-blocks/fields/built-in-fields/dropdown#creation}
+     * https://docs.blockly.com/guides/create-custom-blocks/fields/built-in-fields/dropdown/#creation}
      * for a list of properties this parameter supports.
      * @throws {TypeError} If `menuGenerator` options are incorrectly structured.
      */
@@ -93,6 +99,15 @@ export declare class FieldDropdown extends Field<string> {
      * Create the block UI for this dropdown.
      */
     initView(): void;
+    /**
+     * This is hacky way of determining if a dropdown field is a full-block field or not.
+     * The constants that control the border rect are the same ones that determine how we
+     * render full-block dropdown fields. It's a full-block field if it doesn't have the
+     * border rect (and it's a simple reporter block).
+     *
+     * @returns true if this field should be treated as a full-block field
+     */
+    isFullBlockField(): boolean;
     /**
      * Whether or not the dropdown should add a border rect.
      *
@@ -238,6 +253,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;
+    /**
+     * Sets additional aria state.
+     */
+    recomputeAriaContext(): boolean;
+    /**
+     * 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 +306,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 +315,11 @@ 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.
@@ -280,7 +344,7 @@ export interface FieldDropdownFromJsonConfig extends FieldDropdownConfig {
  * A function that is called to validate changes to the field's value before
  * they are set.
  *
- * @see {@link https://developers.google.com/blockly/guides/create-custom-blocks/fields/validators#return_values}
+ * @see {@link https://docs.blockly.com/guides/create-custom-blocks/fields/validators/#return-values}
  * @param newValue The value to be validated.
  * @returns One of three instructions for setting the new value: `T`, `null`,
  * or `undefined`.