scratch-blocks 2.0.0-beta.1 → 2.0.0-spork.1

package/blockly-rc/core/field.ts

@@ -1,1471 +0,0 @@
-/**
- * @license
- * Copyright 2012 Google LLC
- * SPDX-License-Identifier: Apache-2.0
- */
-
-/**
- * Field.  Used for editable titles, variables, etc.
- * This is an abstract class that defines the UI on the block.  Actual
- * instances would be FieldTextInput, FieldDropdown, etc.
- *
- * @class
- */
-// Former goog.module ID: Blockly.Field
-
-// Unused import preserved for side-effects. Remove if unneeded.
-import './events/events_block_change.js';
-
-import type {Block} from './block.js';
-import type {BlockSvg} from './block_svg.js';
-import * as browserEvents from './browser_events.js';
-import * as dropDownDiv from './dropdowndiv.js';
-import * as eventUtils from './events/utils.js';
-import type {Input} from './inputs/input.js';
-import type {IASTNodeLocationSvg} from './interfaces/i_ast_node_location_svg.js';
-import type {IASTNodeLocationWithBlock} from './interfaces/i_ast_node_location_with_block.js';
-import type {IKeyboardAccessible} from './interfaces/i_keyboard_accessible.js';
-import type {IRegistrable} from './interfaces/i_registrable.js';
-import {MarkerManager} from './marker_manager.js';
-import type {ConstantProvider} from './renderers/common/constants.js';
-import type {KeyboardShortcut} from './shortcut_registry.js';
-import * as Tooltip from './tooltip.js';
-import type {Coordinate} from './utils/coordinate.js';
-import * as dom from './utils/dom.js';
-import * as parsing from './utils/parsing.js';
-import {Rect} from './utils/rect.js';
-import {Size} from './utils/size.js';
-import * as style from './utils/style.js';
-import {Svg} from './utils/svg.js';
-import * as userAgent from './utils/useragent.js';
-import * as utilsXml from './utils/xml.js';
-import * as WidgetDiv from './widgetdiv.js';
-import type {WorkspaceSvg} from './workspace_svg.js';
-import {ISerializable} from './interfaces/i_serializable.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}
- * @param newValue The value to be validated.
- * @returns One of three instructions for setting the new value: `T`, `null`,
- * or `undefined`.
- *
- * - `T` to set this function's returned value instead of `newValue`.
- *
- * - `null` to invoke `doValueInvalid_` and not set a value.
- *
- * - `undefined` to set `newValue` as is.
- */
-export type FieldValidator<T = any> = (newValue: T) => T | null | undefined;
-
-/**
- * Abstract class for an editable field.
- *
- * @typeParam T - The value stored on the field.
- */
-export abstract class Field<T = any>
-  implements
-    IASTNodeLocationSvg,
-    IASTNodeLocationWithBlock,
-    IKeyboardAccessible,
-    IRegistrable,
-    ISerializable
-{
-  /**
-   * To overwrite the default value which is set in **Field**, directly update
-   * the prototype.
-   *
-   * Example:
-   * `FieldImage.prototype.DEFAULT_VALUE = null;`
-   */
-  DEFAULT_VALUE: T | null = null;
-
-  /** Non-breaking space. */
-  static readonly NBSP = '\u00A0';
-
-  /**
-   * A value used to signal when a field's constructor should *not* set the
-   * field's value or run configure_, and should allow a subclass to do that
-   * instead.
-   */
-  static readonly SKIP_SETUP = Symbol('SKIP_SETUP');
-
-  /**
-   * Name of field.  Unique within each block.
-   * Static labels are usually unnamed.
-   */
-  name?: string = undefined;
-  protected value_: T | null;
-
-  /** Validation function called when user edits an editable field. */
-  protected validator_: FieldValidator<T> | null = 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.
-   */
-  private tooltip_: Tooltip.TipInfo | null = null;
-  protected size_: Size;
-
-  /**
-   * Holds the cursors svg element when the cursor is attached to the field.
-   * This is null if there is no cursor on the field.
-   */
-  private cursorSvg_: SVGElement | null = null;
-
-  /**
-   * Holds the markers svg element when the marker is attached to the field.
-   * This is null if there is no marker on the field.
-   */
-  private markerSvg_: SVGElement | null = null;
-
-  /** The rendered field's SVG group element. */
-  protected fieldGroup_: SVGGElement | null = null;
-
-  /** The rendered field's SVG border element. */
-  protected borderRect_: SVGRectElement | null = null;
-
-  /** The rendered field's SVG text element. */
-  protected textElement_: SVGTextElement | null = null;
-
-  /** The rendered field's text content element. */
-  protected textContent_: Text | null = null;
-
-  /** Mouse down event listener data. */
-  private mouseDownWrapper_: browserEvents.Data | null = null;
-
-  /** Constants associated with the source block's renderer. */
-  protected constants_: ConstantProvider | null = null;
-
-  /**
-   * Has this field been disposed of?
-   *
-   * @internal
-   */
-  disposed = false;
-
-  /** Maximum characters of text to display before adding an ellipsis. */
-  maxDisplayLength = 50;
-
-  /** Block this field is attached to.  Starts as null, then set in init. */
-  protected sourceBlock_: Block | null = null;
-
-  /** Does this block need to be re-rendered? */
-  protected isDirty_ = true;
-
-  /** Is the field visible, or hidden due to the block being collapsed? */
-  protected visible_ = true;
-
-  /**
-   * Can the field value be changed using the editor on an editable block?
-   */
-  protected enabled_ = true;
-
-  /** The element the click handler is bound to. */
-  protected clickTarget_: Element | null = null;
-
-  /**
-   * The prefix field.
-   *
-   * @internal
-   */
-  prefixField: string | null = null;
-
-  /**
-   * The suffix field.
-   *
-   * @internal
-   */
-  suffixField: string | null = null;
-
-  /**
-   * Editable fields usually show some sort of UI indicating they are
-   * editable. They will also be saved by the serializer.
-   */
-  EDITABLE = true;
-
-  /**
-   * Serializable fields are saved by the serializer, non-serializable fields
-   * are not. Editable fields should also be serializable. This is not the
-   * case by default so that SERIALIZABLE is backwards compatible.
-   */
-  SERIALIZABLE = false;
-
-  /** Mouse cursor style when over the hotspot that initiates the editor. */
-  CURSOR = '';
-
-  /**
-   * @param value The initial value of the field.
-   *     Also accepts Field.SKIP_SETUP if you wish to skip setup (only used by
-   * subclasses that want to handle configuration and setting the field value
-   * after their own constructors have run).
-   * @param validator  A function that is called to validate changes to the
-   *     field's value. Takes in a value & returns a validated value, or null to
-   *     abort the change.
-   * @param config A map of options used to configure the field.
-   *    Refer to the individual field's documentation for a list of properties
-   * this parameter supports.
-   */
-  constructor(
-    value: T | typeof Field.SKIP_SETUP,
-    validator?: FieldValidator<T> | null,
-    config?: FieldConfig,
-  ) {
-    /**
-     * A generic value possessed by the field.
-     * Should generally be non-null, only null when the field is created.
-     */
-    this.value_ =
-      'DEFAULT_VALUE' in new.target.prototype
-        ? new.target.prototype.DEFAULT_VALUE
-        : this.DEFAULT_VALUE;
-
-    /** The size of the area rendered by the field. */
-    this.size_ = new Size(0, 0);
-
-    if (value === Field.SKIP_SETUP) return;
-    if (config) {
-      this.configure_(config);
-    }
-    this.setValue(value);
-    if (validator) {
-      this.setValidator(validator);
-    }
-  }
-
-  /**
-   * Process the configuration map passed to the field.
-   *
-   * @param config A map of options used to configure the field. See the
-   *     individual field's documentation for a list of properties this
-   *     parameter supports.
-   */
-  protected configure_(config: FieldConfig) {
-    // TODO (#2884): Possibly add CSS class config option.
-    // TODO (#2885): Possibly add cursor config option.
-    if (config.tooltip) {
-      this.setTooltip(parsing.replaceMessageReferences(config.tooltip));
-    }
-  }
-
-  /**
-   * Attach this field to a block.
-   *
-   * @param block The block containing this field.
-   */
-  setSourceBlock(block: Block) {
-    if (this.sourceBlock_) {
-      throw Error('Field already bound to a block');
-    }
-    this.sourceBlock_ = block;
-  }
-
-  /**
-   * Get the renderer constant provider.
-   *
-   * @returns The renderer constant provider.
-   */
-  getConstants(): ConstantProvider | null {
-    if (
-      !this.constants_ &&
-      this.sourceBlock_ &&
-      !this.sourceBlock_.isDeadOrDying() &&
-      this.sourceBlock_.workspace.rendered
-    ) {
-      this.constants_ = (this.sourceBlock_.workspace as WorkspaceSvg)
-        .getRenderer()
-        .getConstants();
-    }
-    return this.constants_;
-  }
-
-  /**
-   * Get the block this field is attached to.
-   *
-   * @returns The block containing this field.
-   * @throws An error if the source block is not defined.
-   */
-  getSourceBlock(): Block | null {
-    return this.sourceBlock_;
-  }
-
-  /**
-   * Initialize everything to render this field. Override
-   * methods initModel and initView rather than this method.
-   *
-   * @sealed
-   * @internal
-   */
-  init() {
-    if (this.fieldGroup_) {
-      // Field has already been initialized once.
-      return;
-    }
-    this.fieldGroup_ = dom.createSvgElement(Svg.G, {});
-    if (!this.isVisible()) {
-      this.fieldGroup_.style.display = 'none';
-    }
-    const sourceBlockSvg = this.sourceBlock_ as BlockSvg;
-    sourceBlockSvg.getSvgRoot().appendChild(this.fieldGroup_);
-    this.initView();
-    this.updateEditable();
-    this.setTooltip(this.tooltip_);
-    this.bindEvents_();
-    this.initModel();
-    this.applyColour();
-  }
-
-  /**
-   * Create the block UI for this field.
-   */
-  protected initView() {
-    this.createBorderRect_();
-    this.createTextElement_();
-    if (this.fieldGroup_) {
-      dom.addClass(this.fieldGroup_, 'blocklyField');
-    }
-  }
-
-  /**
-   * Initializes the model of the field after it has been installed on a block.
-   * No-op by default.
-   */
-  initModel() {}
-
-  /**
-   * 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.
-   */
-  protected isFullBlockField(): boolean {
-    return !this.borderRect_;
-  }
-
-  /**
-   * Create a field border rect element. Not to be overridden by subclasses.
-   * Instead modify the result of the function inside initView, or create a
-   * separate function to call.
-   */
-  protected createBorderRect_() {
-    this.borderRect_ = dom.createSvgElement(
-      Svg.RECT,
-      {
-        'rx': this.getConstants()!.FIELD_BORDER_RECT_RADIUS,
-        'ry': this.getConstants()!.FIELD_BORDER_RECT_RADIUS,
-        'x': 0,
-        'y': 0,
-        'height': this.size_.height,
-        'width': this.size_.width,
-        'class': 'blocklyFieldRect',
-      },
-      this.fieldGroup_,
-    );
-  }
-
-  /**
-   * 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.
-   */
-  protected createTextElement_() {
-    this.textElement_ = dom.createSvgElement(
-      Svg.TEXT,
-      {
-        'class': 'blocklyText blocklyFieldText',
-      },
-      this.fieldGroup_,
-    );
-    if (this.getConstants()!.FIELD_TEXT_BASELINE_CENTER) {
-      this.textElement_.setAttribute('dominant-baseline', 'central');
-    }
-    this.textContent_ = document.createTextNode('');
-    this.textElement_.appendChild(this.textContent_);
-  }
-
-  /**
-   * Bind events to the field. Can be overridden by subclasses if they need to
-   * do custom input handling.
-   */
-  protected bindEvents_() {
-    const clickTarget = this.getClickTarget_();
-    if (!clickTarget) throw new Error('A click target has not been set.');
-    Tooltip.bindMouseEvents(clickTarget);
-    this.mouseDownWrapper_ = browserEvents.conditionalBind(
-      clickTarget,
-      'pointerdown',
-      this,
-      this.onMouseDown_,
-    );
-  }
-
-  /**
-   * Sets the field's value based on the given XML element. Should only be
-   * called by Blockly.Xml.
-   *
-   * @param fieldElement The element containing info about the field's state.
-   */
-  fromXml(fieldElement: Element) {
-    // Any because gremlins live here. No touchie!
-    this.setValue(fieldElement.textContent as any);
-  }
-
-  /**
-   * Serializes this field's value to XML. Should only be called by Blockly.Xml.
-   *
-   * @param fieldElement The element to populate with info about the field's
-   *     state.
-   * @returns The element containing info about the field's state.
-   */
-  toXml(fieldElement: Element): Element {
-    // Any because gremlins live here. No touchie!
-    fieldElement.textContent = this.getValue() as any;
-    return fieldElement;
-  }
-
-  /**
-   * Saves this fields value as something which can be serialized to JSON.
-   * Should only be called by the serialization system.
-   *
-   * @param _doFullSerialization If true, this signals to the field that if it
-   *     normally just saves a reference to some state (eg variable fields) it
-   *     should instead serialize the full state of the thing being referenced.
-   *     See the
-   *     {@link https://developers.devsite.google.com/blockly/guides/create-custom-blocks/fields/customizing-fields/creating#full_serialization_and_backing_data | field serialization docs}
-   *     for more information.
-   * @returns JSON serializable state.
-   */
-  saveState(_doFullSerialization?: boolean): AnyDuringMigration {
-    const legacyState = this.saveLegacyState(Field);
-    if (legacyState !== null) {
-      return legacyState;
-    }
-    return this.getValue();
-  }
-
-  /**
-   * Sets the field's state based on the given state value. Should only be
-   * called by the serialization system.
-   *
-   * @param state The state we want to apply to the field.
-   */
-  loadState(state: AnyDuringMigration) {
-    if (this.loadLegacyState(Field, state)) {
-      return;
-    }
-    this.setValue(state);
-  }
-
-  /**
-   * Returns a stringified version of the XML state, if it should be used.
-   * Otherwise this returns null, to signal the field should use its own
-   * serialization.
-   *
-   * @param callingClass The class calling this method.
-   *     Used to see if `this` has overridden any relevant hooks.
-   * @returns The stringified version of the XML state, or null.
-   */
-  protected saveLegacyState(callingClass: FieldProto): string | null {
-    if (
-      callingClass.prototype.saveState === this.saveState &&
-      callingClass.prototype.toXml !== this.toXml
-    ) {
-      const elem = utilsXml.createElement('field');
-      elem.setAttribute('name', this.name || '');
-      const text = utilsXml.domToText(this.toXml(elem));
-      return text.replace(
-        ' xmlns="https://developers.google.com/blockly/xml"',
-        '',
-      );
-    }
-    // Either they called this on purpose from their saveState, or they have
-    // no implementations of either hook. Just do our thing.
-    return null;
-  }
-
-  /**
-   * Loads the given state using either the old XML hooks, if they should be
-   * used. Returns true to indicate loading has been handled, false otherwise.
-   *
-   * @param callingClass The class calling this method.
-   *     Used to see if `this` has overridden any relevant hooks.
-   * @param state The state to apply to the field.
-   * @returns Whether the state was applied or not.
-   */
-  loadLegacyState(
-    callingClass: FieldProto,
-    state: AnyDuringMigration,
-  ): boolean {
-    if (
-      callingClass.prototype.loadState === this.loadState &&
-      callingClass.prototype.fromXml !== this.fromXml
-    ) {
-      this.fromXml(utilsXml.textToDom(state as string));
-      return true;
-    }
-    // Either they called this on purpose from their loadState, or they have
-    // no implementations of either hook. Just do our thing.
-    return false;
-  }
-
-  /**
-   * Dispose of all DOM objects and events belonging to this editable field.
-   */
-  dispose() {
-    dropDownDiv.hideIfOwner(this);
-    WidgetDiv.hideIfOwner(this);
-
-    if (!this.getSourceBlock()?.isDeadOrDying()) {
-      dom.removeNode(this.fieldGroup_);
-    }
-
-    this.disposed = true;
-  }
-
-  /** Add or remove the UI indicating if this field is editable or not. */
-  updateEditable() {
-    const group = this.fieldGroup_;
-    const block = this.getSourceBlock();
-    if (!this.EDITABLE || !group || !block) {
-      return;
-    }
-    if (this.enabled_ && block.isEditable()) {
-      dom.addClass(group, 'blocklyEditableField');
-      dom.removeClass(group, 'blocklyNonEditableField');
-      group.style.cursor = this.CURSOR;
-    } else {
-      dom.addClass(group, 'blocklyNonEditableField');
-      dom.removeClass(group, 'blocklyEditableField');
-      group.style.cursor = '';
-    }
-  }
-
-  /**
-   * Set whether this field's value can be changed using the editor when the
-   *     source block is editable.
-   *
-   * @param enabled True if enabled.
-   */
-  setEnabled(enabled: boolean) {
-    this.enabled_ = enabled;
-    this.updateEditable();
-  }
-
-  /**
-   * Check whether this field's value can be changed using the editor when the
-   *     source block is editable.
-   *
-   * @returns Whether this field is enabled.
-   */
-  isEnabled(): boolean {
-    return this.enabled_;
-  }
-
-  /**
-   * Check whether this field defines the showEditor_ function.
-   *
-   * @returns Whether this field is clickable.
-   */
-  isClickable(): boolean {
-    return (
-      this.enabled_ &&
-      !!this.sourceBlock_ &&
-      this.sourceBlock_.isEditable() &&
-      this.showEditor_ !== Field.prototype.showEditor_
-    );
-  }
-
-  /**
-   * Check whether the field should be clickable while the block is in a flyout.
-   * The default is that fields are clickable in always-open flyouts such as the
-   * simple toolbox, but not in autoclosing flyouts such as the category toolbox.
-   * Subclasses may override this function to change this behavior. Note that
-   * `isClickable` must also return true for this to have any effect.
-   *
-   * @param autoClosingFlyout true if the containing flyout is an auto-closing one.
-   * @returns Whether the field should be clickable while the block is in a flyout.
-   */
-  isClickableInFlyout(autoClosingFlyout: boolean): boolean {
-    return !autoClosingFlyout;
-  }
-
-  /**
-   * Check whether this field is currently editable.  Some fields are never
-   * EDITABLE (e.g. text labels). Other fields may be EDITABLE but may exist on
-   * non-editable blocks or be currently disabled.
-   *
-   * @returns Whether this field is currently enabled, editable and on an
-   *     editable block.
-   */
-  isCurrentlyEditable(): boolean {
-    return (
-      this.enabled_ &&
-      this.EDITABLE &&
-      !!this.sourceBlock_ &&
-      this.sourceBlock_.isEditable()
-    );
-  }
-
-  /**
-   * Check whether this field should be serialized by the XML renderer.
-   * Handles the logic for backwards compatibility and incongruous states.
-   *
-   * @returns Whether this field should be serialized or not.
-   */
-  isSerializable(): boolean {
-    let isSerializable = false;
-    if (this.name) {
-      if (this.SERIALIZABLE) {
-        isSerializable = true;
-      } else if (this.EDITABLE) {
-        console.warn(
-          'Detected an editable field that was not serializable.' +
-            ' Please define SERIALIZABLE property as true on all editable custom' +
-            ' fields. Proceeding with serialization.',
-        );
-        isSerializable = true;
-      }
-    }
-    return isSerializable;
-  }
-
-  /**
-   * Gets whether this editable field is visible or not.
-   *
-   * @returns True if visible.
-   */
-  isVisible(): boolean {
-    return this.visible_;
-  }
-
-  /**
-   * Sets whether this editable field is visible or not. Should only be called
-   * by input.setVisible.
-   *
-   * @param visible True if visible.
-   * @internal
-   */
-  setVisible(visible: boolean) {
-    if (this.visible_ === visible) {
-      return;
-    }
-    this.visible_ = visible;
-    const root = this.fieldGroup_;
-    if (root) {
-      root.style.display = visible ? 'block' : 'none';
-    }
-  }
-
-  /**
-   * Sets a new validation function for editable fields, or clears a previously
-   * set validator.
-   *
-   * The validator function takes in the new field value, and returns
-   * validated value. The validated value could be the input value, a modified
-   * version of the input value, or null to abort the change.
-   *
-   * If the function does not return anything (or returns undefined) the new
-   * value is accepted as valid. This is to allow for fields using the
-   * validated function as a field-level change event notification.
-   *
-   * @param handler The validator function or null to clear a previous
-   *     validator.
-   */
-  setValidator(handler: FieldValidator<T>) {
-    this.validator_ = handler;
-  }
-
-  /**
-   * Gets the validation function for editable fields, or null if not set.
-   *
-   * @returns Validation function, or null.
-   */
-  getValidator(): FieldValidator<T> | null {
-    return this.validator_;
-  }
-
-  /**
-   * Gets the group element for this editable field.
-   * Used for measuring the size and for positioning.
-   *
-   * @returns The group element.
-   */
-  getSvgRoot(): SVGGElement | null {
-    return this.fieldGroup_;
-  }
-
-  /**
-   * Gets the border rectangle element.
-   *
-   * @returns The border rectangle element.
-   * @throws An error if the border rectangle element is not defined.
-   */
-  protected getBorderRect(): SVGRectElement {
-    if (!this.borderRect_) {
-      throw new Error(`The border rectangle is ${this.borderRect_}.`);
-    }
-    return this.borderRect_;
-  }
-
-  /**
-   * Gets the text element.
-   *
-   * @returns The text element.
-   * @throws An error if the text element is not defined.
-   */
-  protected getTextElement(): SVGTextElement {
-    if (!this.textElement_) {
-      throw new Error(`The text element is ${this.textElement_}.`);
-    }
-    return this.textElement_;
-  }
-
-  /**
-   * Gets the text content.
-   *
-   * @returns The text content.
-   * @throws An error if the text content is not defined.
-   */
-  protected getTextContent(): Text {
-    if (!this.textContent_) {
-      throw new Error(`The text content is ${this.textContent_}.`);
-    }
-    return this.textContent_;
-  }
-
-  /**
-   * Updates the field to match the colour/style of the block.
-   *
-   * Non-abstract sub-classes may wish to implement this if the colour of the
-   * field depends on the colour of the block. It will automatically be called
-   * 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
-   * | the field documentation} for more information, or FieldDropdown for an
-   * example.
-   */
-  applyColour() {}
-
-  /**
-   * Used by getSize() to move/resize any DOM elements, and get the new size.
-   *
-   * All rendering that has an effect on the size/shape of the block should be
-   * done here, and should be triggered by getSize().
-   */
-  protected render_() {
-    if (this.textContent_) {
-      this.textContent_.nodeValue = this.getDisplayText_();
-    }
-    this.updateSize_();
-  }
-
-  /**
-   * Calls showEditor_ when the field is clicked if the field is clickable.
-   * Do not override.
-   *
-   * @param e Optional mouse event that triggered the field to open, or
-   *     undefined if triggered programmatically.
-   * @sealed
-   * @internal
-   */
-  showEditor(e?: Event) {
-    if (this.isClickable()) {
-      this.showEditor_(e);
-    }
-  }
-
-  /**
-   * A developer hook to create an editor for the field. This is no-op by
-   * default, and must be overriden to create an editor.
-   *
-   * @param _e Optional mouse event that triggered the field to open, or
-   *     undefined if triggered programmatically.
-   */
-  protected showEditor_(_e?: Event): void {}
-  // NOP
-
-  /**
-   * A developer hook to reposition the WidgetDiv during a window resize. You
-   * need to define this hook if your field has a WidgetDiv that needs to
-   * reposition itself when the window is resized. For example, text input
-   * fields define this hook so that the input WidgetDiv can reposition itself
-   * on a window resize event. This is especially important when modal inputs
-   * have been disabled, as Android devices will fire a window resize event when
-   * the soft keyboard opens.
-   *
-   * If you want the WidgetDiv to hide itself instead of repositioning, return
-   * false. This is the default behavior.
-   *
-   * DropdownDivs already handle their own positioning logic, so you do not need
-   * to override this function if your field only has a DropdownDiv.
-   *
-   * @returns True if the field should be repositioned,
-   *    false if the WidgetDiv should hide itself instead.
-   */
-  repositionForWindowResize(): boolean {
-    return false;
-  }
-
-  /**
-   * Updates the size of the field based on the text.
-   *
-   * @param margin margin to use when positioning the text element.
-   */
-  protected updateSize_(margin?: number) {
-    const constants = this.getConstants();
-    const xOffset =
-      margin !== undefined
-        ? margin
-        : !this.isFullBlockField()
-          ? this.getConstants()!.FIELD_BORDER_RECT_X_PADDING
-          : 0;
-    let totalWidth = xOffset * 2;
-    let totalHeight = constants!.FIELD_TEXT_HEIGHT;
-
-    let contentWidth = 0;
-    if (this.textElement_) {
-      contentWidth = dom.getTextWidth(this.textElement_);
-      totalWidth += contentWidth;
-    }
-    if (!this.isFullBlockField()) {
-      totalHeight = Math.max(totalHeight, constants!.FIELD_BORDER_RECT_HEIGHT);
-    }
-
-    this.size_.height = totalHeight;
-    this.size_.width = totalWidth;
-
-    this.positionTextElement_(xOffset, contentWidth);
-    this.positionBorderRect_();
-  }
-
-  /**
-   * Position a field's text element after a size change.  This handles both LTR
-   * and RTL positioning.
-   *
-   * @param xOffset x offset to use when positioning the text element.
-   * @param contentWidth The content width.
-   */
-  protected positionTextElement_(xOffset: number, contentWidth: number) {
-    if (!this.textElement_) {
-      return;
-    }
-    const constants = this.getConstants();
-    const halfHeight = this.size_.height / 2;
-
-    this.textElement_.setAttribute(
-      'x',
-      String(
-        this.getSourceBlock()?.RTL
-          ? this.size_.width - contentWidth - xOffset
-          : xOffset,
-      ),
-    );
-    this.textElement_.setAttribute(
-      'y',
-      String(
-        constants!.FIELD_TEXT_BASELINE_CENTER
-          ? halfHeight
-          : halfHeight -
-              constants!.FIELD_TEXT_HEIGHT / 2 +
-              constants!.FIELD_TEXT_BASELINE,
-      ),
-    );
-  }
-
-  /** Position a field's border rect after a size change. */
-  protected positionBorderRect_() {
-    if (!this.borderRect_) {
-      return;
-    }
-    this.borderRect_.setAttribute('width', String(this.size_.width));
-    this.borderRect_.setAttribute('height', String(this.size_.height));
-    this.borderRect_.setAttribute(
-      'rx',
-      String(this.getConstants()!.FIELD_BORDER_RECT_RADIUS),
-    );
-    this.borderRect_.setAttribute(
-      'ry',
-      String(this.getConstants()!.FIELD_BORDER_RECT_RADIUS),
-    );
-  }
-
-  /**
-   * Returns the height and width of the field.
-   *
-   * This should *in general* be the only place render_ gets called from.
-   *
-   * @returns Height and width.
-   */
-  getSize(): Size {
-    if (!this.isVisible()) {
-      return new Size(0, 0);
-    }
-
-    if (this.isDirty_) {
-      this.render_();
-      this.isDirty_ = false;
-    } else if (this.visible_ && this.size_.width === 0) {
-      // If the field is not visible the width will be 0 as well, one of the
-      // problems with the old system.
-      this.render_();
-      // Don't issue a warning if the field is actually zero width.
-      if (this.size_.width !== 0) {
-        console.warn(
-          'Deprecated use of setting size_.width to 0 to rerender a' +
-            ' field. Set field.isDirty_ to true instead.',
-        );
-      }
-    }
-    return this.size_;
-  }
-
-  /**
-   * Returns the bounding box of the rendered field, accounting for workspace
-   * scaling.
-   *
-   * @returns An object with top, bottom, left, and right in pixels relative to
-   *     the top left corner of the page (window coordinates).
-   * @internal
-   */
-  getScaledBBox(): Rect {
-    let scaledWidth;
-    let scaledHeight;
-    let xy;
-    const block = this.getSourceBlock();
-    if (!block) {
-      throw new UnattachedFieldError();
-    }
-
-    if (this.isFullBlockField()) {
-      // Browsers are inconsistent in what they return for a bounding box.
-      // - Webkit / Blink: fill-box / object bounding box
-      // - Gecko: stroke-box
-      const bBox = (this.sourceBlock_ as BlockSvg).getHeightWidth();
-      const scale = (block.workspace as WorkspaceSvg).scale;
-      xy = this.getAbsoluteXY_();
-      scaledWidth = (bBox.width + 1) * scale;
-      scaledHeight = (bBox.height + 1) * scale;
-
-      if (userAgent.GECKO) {
-        xy.x += 1.5 * scale;
-        xy.y += 1.5 * scale;
-      } else {
-        xy.x -= 0.5 * scale;
-        xy.y -= 0.5 * scale;
-      }
-    } else {
-      const bBox = this.borderRect_!.getBoundingClientRect();
-      xy = style.getPageOffset(this.borderRect_!);
-      scaledWidth = bBox.width;
-      scaledHeight = bBox.height;
-    }
-    return new Rect(xy.y, xy.y + scaledHeight, xy.x, xy.x + scaledWidth);
-  }
-
-  /**
-   * Notifies the field that it has changed locations.
-   *
-   * @param _ The location of this field's block's top-start corner
-   *     in workspace coordinates.
-   */
-  onLocationChange(_: Coordinate) {}
-
-  /**
-   * Get the text from this field to display on the block. May differ from
-   * `getText` due to ellipsis, and other formatting.
-   *
-   * @returns Text to display.
-   */
-  protected getDisplayText_(): string {
-    let text = this.getText();
-    if (!text) {
-      // Prevent the field from disappearing if empty.
-      return Field.NBSP;
-    }
-    if (text.length > this.maxDisplayLength) {
-      // Truncate displayed string and add an ellipsis ('...').
-      text = text.substring(0, this.maxDisplayLength - 2) + '…';
-    }
-    // Replace whitespace with non-breaking spaces so the text doesn't collapse.
-    text = text.replace(/\s/g, Field.NBSP);
-    if (this.sourceBlock_ && this.sourceBlock_.RTL) {
-      // The SVG is LTR, force text to be RTL by adding an RLM.
-      text += '\u200F';
-    }
-    return text;
-  }
-
-  /**
-   * Get the text from this field.
-   * Override getText_ to provide a different behavior than simply casting the
-   * value to a string.
-   *
-   * @returns Current text.
-   * @sealed
-   */
-  getText(): string {
-    // this.getText_ was intended so that devs don't have to remember to call
-    // super when overriding how the text of the field is generated. (#2910)
-    const text = this.getText_();
-    if (text !== null) {
-      return String(text);
-    }
-    return String(this.getValue());
-  }
-
-  /**
-   * A developer hook to override the returned text of this field.
-   * Override if the text representation of the value of this field
-   * is not just a string cast of its value.
-   * Return null to resort to a string cast.
-   *
-   * @returns Current text or null.
-   */
-  protected getText_(): string | null {
-    return null;
-  }
-
-  /**
-   * Force a rerender of the block that this field is installed on, which will
-   * rerender this field and adjust for any sizing changes.
-   * Other fields on the same block will not rerender, because their sizes have
-   * already been recorded.
-   *
-   * @internal
-   */
-  markDirty() {
-    this.isDirty_ = true;
-    this.constants_ = null;
-  }
-
-  /**
-   * Force a rerender of the block that this field is installed on, which will
-   * rerender this field and adjust for any sizing changes.
-   * Other fields on the same block will not rerender, because their sizes have
-   * already been recorded.
-   */
-  forceRerender() {
-    this.isDirty_ = true;
-    if (this.sourceBlock_ && this.sourceBlock_.rendered) {
-      (this.sourceBlock_ as BlockSvg).queueRender();
-    }
-  }
-
-  /**
-   * Used to change the value of the field. Handles validation and events.
-   * Subclasses should override doClassValidation_ and doValueUpdate_ rather
-   * than this method.
-   *
-   * @param newValue New value.
-   * @param fireChangeEvent Whether to fire a change event. Defaults to true.
-   *     Should usually be true unless the change will be reported some other
-   *     way, e.g. an intermediate field change event.
-   * @sealed
-   */
-  setValue(newValue: AnyDuringMigration, fireChangeEvent = true) {
-    const doLogging = false;
-    if (newValue === null) {
-      doLogging && console.log('null, return');
-      // Not a valid value to check.
-      return;
-    }
-
-    const classValidation = this.doClassValidation_(newValue);
-    const classValue = this.processValidation_(
-      newValue,
-      classValidation,
-      fireChangeEvent,
-    );
-    if (classValue instanceof Error) {
-      doLogging && console.log('invalid class validation, return');
-      return;
-    }
-
-    const localValidation = this.getValidator()?.call(this, classValue);
-    const localValue = this.processValidation_(
-      classValue,
-      localValidation,
-      fireChangeEvent,
-    );
-    if (localValue instanceof Error) {
-      doLogging && console.log('invalid local validation, return');
-      return;
-    }
-
-    const source = this.sourceBlock_;
-    if (source && source.disposed) {
-      doLogging && console.log('source disposed, return');
-      return;
-    }
-
-    const oldValue = this.getValue();
-    if (oldValue === localValue) {
-      doLogging && console.log('same, doValueUpdate_, return');
-      this.doValueUpdate_(localValue);
-      return;
-    }
-
-    this.doValueUpdate_(localValue);
-    if (fireChangeEvent && source && eventUtils.isEnabled()) {
-      eventUtils.fire(
-        new (eventUtils.get(eventUtils.BLOCK_CHANGE))(
-          source,
-          'field',
-          this.name || null,
-          oldValue,
-          localValue,
-        ),
-      );
-    }
-    if (this.isDirty_) {
-      this.forceRerender();
-    }
-    doLogging && console.log(this.value_);
-  }
-
-  /**
-   * Process the result of validation.
-   *
-   * @param newValue New value.
-   * @param validatedValue Validated value.
-   * @param fireChangeEvent Whether to fire a change event if the value changes.
-   * @returns New value, or an Error object.
-   */
-  private processValidation_(
-    newValue: AnyDuringMigration,
-    validatedValue: T | null | undefined,
-    fireChangeEvent: boolean,
-  ): T | Error {
-    if (validatedValue === null) {
-      this.doValueInvalid_(newValue, fireChangeEvent);
-      if (this.isDirty_) {
-        this.forceRerender();
-      }
-      return Error();
-    }
-    return validatedValue === undefined ? (newValue as T) : validatedValue;
-  }
-
-  /**
-   * Get the current value of the field.
-   *
-   * @returns Current value.
-   */
-  getValue(): T | null {
-    return this.value_;
-  }
-
-  /**
-   * Validate the changes to a field's value before they are set. See
-   * **FieldDropdown** for an example of subclass implementation.
-   *
-   * **NOTE:** Validation returns one option between `T`, `null`, and
-   * `undefined`. **Field**'s implementation will never return `undefined`, but
-   * 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}
-   * @param newValue - The value to be validated.
-   * @returns One of three instructions for setting the new value: `T`, `null`,
-   * or `undefined`.
-   *
-   * - `T` to set this function's returned value instead of `newValue`.
-   *
-   * - `null` to invoke `doValueInvalid_` and not set a value.
-   *
-   * - `undefined` to set `newValue` as is.
-   */
-  protected doClassValidation_(newValue: T): T | null | undefined;
-  protected doClassValidation_(newValue?: AnyDuringMigration): T | null;
-  protected doClassValidation_(
-    newValue?: T | AnyDuringMigration,
-  ): T | null | undefined {
-    if (newValue === null || newValue === undefined) {
-      return null;
-    }
-
-    return newValue as T;
-  }
-
-  /**
-   * Used to update the value of a field. Can be overridden by subclasses to do
-   * custom storage of values/updating of external things.
-   *
-   * @param newValue The value to be saved.
-   */
-  protected doValueUpdate_(newValue: T) {
-    this.value_ = newValue;
-    this.isDirty_ = true;
-  }
-
-  /**
-   * Used to notify the field an invalid value was input. Can be overridden by
-   * subclasses, see FieldTextInput.
-   * No-op by default.
-   *
-   * @param _invalidValue The input value that was determined to be invalid.
-   * @param _fireChangeEvent Whether to fire a change event if the value changes.
-   */
-  protected doValueInvalid_(
-    _invalidValue: AnyDuringMigration,
-    _fireChangeEvent: boolean = true,
-  ) {}
-  // NOP
-
-  /**
-   * Handle a pointerdown event on a field.
-   *
-   * @param e Pointer down event.
-   */
-  protected onMouseDown_(e: PointerEvent) {
-    if (!this.sourceBlock_ || this.sourceBlock_.isDeadOrDying()) {
-      return;
-    }
-    const gesture = (this.sourceBlock_.workspace as WorkspaceSvg).getGesture(e);
-    if (gesture) {
-      gesture.setStartField(this);
-    }
-  }
-
-  /**
-   * Sets the tooltip for this field.
-   *
-   * @param newTip The text for the tooltip, a function that returns the text
-   *     for the tooltip, a parent object whose tooltip will be used, or null to
-   *     display the tooltip of the parent block. To not display a tooltip pass
-   *     the empty string.
-   */
-  setTooltip(newTip: Tooltip.TipInfo | null) {
-    if (!newTip && newTip !== '') {
-      // If null or undefined.
-      newTip = this.sourceBlock_;
-    }
-    const clickTarget = this.getClickTarget_();
-    if (clickTarget) {
-      (clickTarget as AnyDuringMigration).tooltip = newTip;
-    } else {
-      // Field has not been initialized yet.
-      this.tooltip_ = newTip;
-    }
-  }
-
-  /**
-   * Returns the tooltip text for this field.
-   *
-   * @returns The tooltip text for this field.
-   */
-  getTooltip(): string {
-    const clickTarget = this.getClickTarget_();
-    if (clickTarget) {
-      return Tooltip.getTooltipOfObject(clickTarget);
-    }
-    // Field has not been initialized yet. Return stashed this.tooltip_ value.
-    return Tooltip.getTooltipOfObject({tooltip: this.tooltip_});
-  }
-
-  /**
-   * The element to bind the click handler to. If not set explicitly, defaults
-   * to the SVG root of the field. When this element is
-   * clicked on an editable field, the editor will open.
-   *
-   * @returns Element to bind click handler to.
-   */
-  protected getClickTarget_(): Element | null {
-    return this.clickTarget_ || this.getSvgRoot();
-  }
-
-  /**
-   * Return the absolute coordinates of the top-left corner of this field.
-   * The origin (0,0) is the top-left corner of the page body.
-   *
-   * @returns Object with .x and .y properties.
-   */
-  protected getAbsoluteXY_(): Coordinate {
-    return style.getPageOffset(this.getClickTarget_() as SVGRectElement);
-  }
-
-  /**
-   * Whether this field references any Blockly variables.  If true it may need
-   * to be handled differently during serialization and deserialization.
-   * Subclasses may override this.
-   *
-   * @returns True if this field has any variable references.
-   */
-  referencesVariables(): boolean {
-    return false;
-  }
-
-  /**
-   * Refresh the variable name referenced by this field if this field references
-   * variables.
-   */
-  refreshVariableName() {}
-  // NOP
-
-  /**
-   * Search through the list of inputs and their fields in order to find the
-   * parent input of a field.
-   *
-   * @returns The input that the field belongs to.
-   * @internal
-   */
-  getParentInput(): Input {
-    let parentInput = null;
-    const block = this.getSourceBlock();
-    if (!block) {
-      throw new UnattachedFieldError();
-    }
-    const inputs = block.inputList;
-
-    for (let idx = 0; idx < block.inputList.length; idx++) {
-      const input = inputs[idx];
-      const fieldRows = input.fieldRow;
-      for (let j = 0; j < fieldRows.length; j++) {
-        if (fieldRows[j] === this) {
-          parentInput = input;
-          break;
-        }
-      }
-    }
-    return parentInput!;
-  }
-
-  /**
-   * Returns whether or not we should flip the field in RTL.
-   *
-   * @returns True if we should flip in RTL.
-   */
-  getFlipRtl(): boolean {
-    return false;
-  }
-
-  /**
-   * Returns whether or not the field is tab navigable.
-   *
-   * @returns True if the field is tab navigable.
-   */
-  isTabNavigable(): boolean {
-    return false;
-  }
-
-  /**
-   * Handles the given keyboard shortcut.
-   *
-   * @param _shortcut The shortcut to be handled.
-   * @returns True if the shortcut has been handled, false otherwise.
-   */
-  onShortcut(_shortcut: KeyboardShortcut): boolean {
-    return false;
-  }
-
-  /**
-   * Add the cursor SVG to this fields SVG group.
-   *
-   * @param cursorSvg The SVG root of the cursor to be added to the field group.
-   * @internal
-   */
-  setCursorSvg(cursorSvg: SVGElement) {
-    if (!cursorSvg) {
-      this.cursorSvg_ = null;
-      return;
-    }
-
-    if (!this.fieldGroup_) {
-      throw new Error(`The field group is ${this.fieldGroup_}.`);
-    }
-    this.fieldGroup_.appendChild(cursorSvg);
-    this.cursorSvg_ = cursorSvg;
-  }
-
-  /**
-   * Add the marker SVG to this fields SVG group.
-   *
-   * @param markerSvg The SVG root of the marker to be added to the field group.
-   * @internal
-   */
-  setMarkerSvg(markerSvg: SVGElement) {
-    if (!markerSvg) {
-      this.markerSvg_ = null;
-      return;
-    }
-
-    if (!this.fieldGroup_) {
-      throw new Error(`The field group is ${this.fieldGroup_}.`);
-    }
-    this.fieldGroup_.appendChild(markerSvg);
-    this.markerSvg_ = markerSvg;
-  }
-
-  /**
-   * Redraw any attached marker or cursor svgs if needed.
-   *
-   * @internal
-   */
-  updateMarkers_() {
-    const block = this.getSourceBlock();
-    if (!block) {
-      throw new UnattachedFieldError();
-    }
-    const workspace = block.workspace as WorkspaceSvg;
-    if (workspace.keyboardAccessibilityMode && this.cursorSvg_) {
-      workspace.getCursor()!.draw();
-    }
-    if (workspace.keyboardAccessibilityMode && this.markerSvg_) {
-      // TODO(#4592): Update all markers on the field.
-      workspace.getMarker(MarkerManager.LOCAL_MARKER)!.draw();
-    }
-  }
-
-  /**
-   * Subclasses should reimplement this method to construct their Field
-   * subclass from a JSON arg object.
-   *
-   * It is an error to attempt to register a field subclass in the
-   * FieldRegistry if that subclass has not overridden this method.
-   *
-   * @param _options JSON configuration object with properties needed
-   *    to configure a specific field.
-   */
-  static fromJson(_options: FieldConfig): Field {
-    throw new Error(
-      `Attempted to instantiate a field from the registry that hasn't defined a 'fromJson' method.`,
-    );
-  }
-}
-
-/**
- * Extra configuration options for the base field.
- */
-export interface FieldConfig {
-  tooltip?: string;
-}
-
-/**
- * Represents an object that has all the prototype properties of the `Field`
- * class. This is necessary because constructors can change
- * in descendants, though they should contain all of Field's prototype methods.
- *
- * This type should only be used in places where we directly access the prototype
- * of a Field class or subclass.
- */
-type FieldProto = Pick<typeof Field, 'prototype'>;
-
-/**
- * Represents an error where the field is trying to access its block or
- * information about its block before it has actually been attached to said
- * block.
- */
-export class UnattachedFieldError extends Error {
-  /** @internal */
-  constructor() {
-    super(
-      'The field has not yet been attached to its input. ' +
-        'Call appendField to attach it.',
-    );
-  }
-}