fix: export Field-related types from Blockly (#6877)

* chore: re-exported Field config types from Blockly

* mark `@internal` types, export field error, and add validator comments

core/blockly.ts

@@ -52,19 +52,19 @@ import {DragTarget} from './drag_target.js';
 import * as dropDownDiv from './dropdowndiv.js';
 import * as Events from './events/events.js';
 import * as Extensions from './extensions.js';
-import {Field, FieldValidator} from './field.js';
-import {FieldAngle, FieldAngleValidator} from './field_angle.js';
-import {FieldCheckbox, FieldCheckboxValidator} from './field_checkbox.js';
-import {FieldColour, FieldColourValidator} from './field_colour.js';
-import {FieldDropdown, FieldDropdownValidator, MenuGenerator, MenuGeneratorFunction, MenuOption} from './field_dropdown.js';
-import {FieldImage} from './field_image.js';
-import {FieldLabel} from './field_label.js';
+import {Field, FieldConfig, FieldValidator, UnattachedFieldError} from './field.js';
+import {FieldAngle, FieldAngleConfig, FieldAngleFromJsonConfig, FieldAngleValidator} from './field_angle.js';
+import {FieldCheckbox, FieldCheckboxConfig, FieldCheckboxFromJsonConfig, FieldCheckboxValidator} from './field_checkbox.js';
+import {FieldColour, FieldColourConfig, FieldColourFromJsonConfig, FieldColourValidator} from './field_colour.js';
+import {FieldDropdown, FieldDropdownConfig, FieldDropdownFromJsonConfig, FieldDropdownValidator, MenuGenerator, MenuGeneratorFunction, MenuOption} from './field_dropdown.js';
+import {FieldImage, FieldImageConfig, FieldImageFromJsonConfig} from './field_image.js';
+import {FieldLabel, FieldLabelConfig, FieldLabelFromJsonConfig} from './field_label.js';
 import {FieldLabelSerializable} from './field_label_serializable.js';
-import {FieldMultilineInput, FieldMultilineInputValidator} from './field_multilineinput.js';
-import {FieldNumber, FieldNumberValidator} from './field_number.js';
+import {FieldMultilineInput, FieldMultilineInputConfig, FieldMultilineInputFromJsonConfig, FieldMultilineInputValidator} from './field_multilineinput.js';
+import {FieldNumber, FieldNumberConfig, FieldNumberFromJsonConfig, FieldNumberValidator} from './field_number.js';
 import * as fieldRegistry from './field_registry.js';
-import {FieldTextInput, FieldTextInputValidator} from './field_textinput.js';
-import {FieldVariable, FieldVariableValidator} from './field_variable.js';
+import {FieldTextInput, FieldTextInputConfig, FieldTextInputFromJsonConfig, FieldTextInputValidator} from './field_textinput.js';
+import {FieldVariable, FieldVariableConfig, FieldVariableFromJsonConfig, FieldVariableValidator} from './field_variable.js';
 import {Flyout} from './flyout_base.js';
 import {FlyoutButton} from './flyout_button.js';
 import {HorizontalFlyout} from './flyout_horizontal.js';
@@ -606,24 +606,61 @@ export {Cursor};
 export {DeleteArea};
 export {DragTarget};
 export const DropDownDiv = dropDownDiv;
-export {Field, FieldValidator};
-export {FieldAngle, FieldAngleValidator};
-export {FieldCheckbox, FieldCheckboxValidator};
-export {FieldColour, FieldColourValidator};
+export {Field, FieldConfig, FieldValidator, UnattachedFieldError};
+export {
+  FieldAngle,
+  FieldAngleConfig,
+  FieldAngleFromJsonConfig,
+  FieldAngleValidator,
+};
+export {
+  FieldCheckbox,
+  FieldCheckboxConfig,
+  FieldCheckboxFromJsonConfig,
+  FieldCheckboxValidator,
+};
+export {
+  FieldColour,
+  FieldColourConfig,
+  FieldColourFromJsonConfig,
+  FieldColourValidator,
+};
 export {
   FieldDropdown,
+  FieldDropdownConfig,
+  FieldDropdownFromJsonConfig,
   FieldDropdownValidator,
   MenuGenerator,
   MenuGeneratorFunction,
   MenuOption,
 };
-export {FieldImage};
-export {FieldLabel};
+export {FieldImage, FieldImageConfig, FieldImageFromJsonConfig};
+export {FieldLabel, FieldLabelConfig, FieldLabelFromJsonConfig};
 export {FieldLabelSerializable};
-export {FieldMultilineInput, FieldMultilineInputValidator};
-export {FieldNumber, FieldNumberValidator};
-export {FieldTextInput, FieldTextInputValidator};
-export {FieldVariable, FieldVariableValidator};
+export {
+  FieldMultilineInput,
+  FieldMultilineInputConfig,
+  FieldMultilineInputFromJsonConfig,
+  FieldMultilineInputValidator,
+};
+export {
+  FieldNumber,
+  FieldNumberConfig,
+  FieldNumberFromJsonConfig,
+  FieldNumberValidator,
+};
+export {
+  FieldTextInput,
+  FieldTextInputConfig,
+  FieldTextInputFromJsonConfig,
+  FieldTextInputValidator,
+};
+export {
+  FieldVariable,
+  FieldVariableConfig,
+  FieldVariableFromJsonConfig,
+  FieldVariableValidator,
+};
 export {Flyout};
 export {FlyoutButton};
 export {FlyoutMetricsManager};

core/field.ts

@@ -48,8 +48,6 @@ import type {WorkspaceSvg} from './workspace_svg.js';
  * A function that is called to validate changes to the field's value before
  * they are set.
  *
- * **NOTE:** Validation returns one option between `T`, `null`, and `undefined`.
- *
  * @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`,
@@ -1315,6 +1313,8 @@ export interface FieldConfig {
 /**
  * For use by Field and descendants of Field. Constructors can change
  * in descendants, though they should contain all of Field's prototype methods.
+ *
+ * @internal
  */
 export type FieldProto = Pick<typeof Field, 'prototype'>;
 

core/field_angle.ts

@@ -27,8 +27,6 @@ import {Svg} from './utils/svg.js';
 import * as userAgent from './utils/useragent.js';
 import * as WidgetDiv from './widgetdiv.js';
 
-export type FieldAngleValidator = FieldInputValidator<number>;
-
 /**
  * Class for an editable angle field.
  */
@@ -534,3 +532,20 @@ export interface FieldAngleConfig extends FieldInputConfig {
 export interface FieldAngleFromJsonConfig extends FieldAngleConfig {
   angle?: number;
 }
+
+/**
+ * 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 FieldAngleValidator = FieldInputValidator<number>;

core/field_checkbox.ts

@@ -22,7 +22,6 @@ import type {Sentinel} from './utils/sentinel.js';
 
 type BoolString = 'TRUE'|'FALSE';
 type CheckboxBool = BoolString|boolean;
-export type FieldCheckboxValidator = FieldValidator<CheckboxBool>;
 
 /**
  * Class for a checkbox field.
@@ -252,3 +251,20 @@ export interface FieldCheckboxConfig extends FieldConfig {
 export interface FieldCheckboxFromJsonConfig extends FieldCheckboxConfig {
   checked?: boolean;
 }
+
+/**
+ * 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 FieldCheckboxValidator = FieldValidator<CheckboxBool>;

core/field_colour.ts

@@ -29,8 +29,6 @@ import {KeyCodes} from './utils/keycodes.js';
 import type {Sentinel} from './utils/sentinel.js';
 import {Size} from './utils/size.js';
 
-export type FieldColourValidator = FieldValidator<string>;
-
 /**
  * Class for a colour input field.
  */
@@ -616,3 +614,20 @@ export interface FieldColourConfig extends FieldConfig {
 export interface FieldColourFromJsonConfig extends FieldColourConfig {
   colour?: string;
 }
+
+/**
+ * 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 FieldColourValidator = FieldValidator<string>;

core/field_dropdown.ts

@@ -28,8 +28,6 @@ import type {Sentinel} from './utils/sentinel.js';
 import * as utilsString from './utils/string.js';
 import {Svg} from './utils/svg.js';
 
-export type FieldDropdownValidator = FieldValidator<string>;
-
 /**
  * Class for an editable dropdown field.
  */
@@ -112,13 +110,13 @@ export class FieldDropdown extends Field<string> {
   constructor(
       menuGenerator: MenuGenerator,
       opt_validator?: FieldDropdownValidator,
-      opt_config?: FieldConfig,
+      opt_config?: FieldDropdownConfig,
   );
   constructor(menuGenerator: Sentinel);
   constructor(
       menuGenerator: MenuGenerator|Sentinel,
       opt_validator?: FieldDropdownValidator,
-      opt_config?: FieldConfig,
+      opt_config?: FieldDropdownConfig,
   ) {
     super(Field.SKIP_SETUP);
 
@@ -651,13 +649,35 @@ export type MenuGeneratorFunction = (this: FieldDropdown) => MenuOption[];
  */
 export type MenuGenerator = MenuOption[]|MenuGeneratorFunction;
 
+/**
+ * Config options for the dropdown field.
+ */
+export type FieldDropdownConfig = FieldConfig;
+
 /**
  * fromJson config for the dropdown field.
  */
-export interface FieldDropdownFromJsonConfig extends FieldConfig {
+export interface FieldDropdownFromJsonConfig extends FieldDropdownConfig {
   options?: MenuOption[];
 }
 
+/**
+ * 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 FieldDropdownValidator = FieldValidator<string>;
+
 /**
  * The y offset from the top of the field to the top of the image, if an image
  * is selected.

core/field_input.ts

@@ -31,14 +31,18 @@ import * as userAgent from './utils/useragent.js';
 import * as WidgetDiv from './widgetdiv.js';
 import type {WorkspaceSvg} from './workspace_svg.js';
 
-export type InputTypes = string|number;
-export type FieldInputValidator<T extends InputTypes> =
-    FieldValidator<string|T>;
+/**
+ * Supported types for FieldInput subclasses.
+ *
+ * @internal
+ */
+type InputTypes = string|number;
 
 /**
  * Abstract class for an editable input field.
  *
  * @typeParam T - The value stored on the field.
+ * @internal
  */
 export abstract class FieldInput<T extends InputTypes> extends Field<string|T> {
   /**
@@ -559,7 +563,28 @@ export abstract class FieldInput<T extends InputTypes> extends Field<string|T> {
 
 /**
  * Config options for the input field.
+ *
+ * @internal
  */
 export interface FieldInputConfig extends FieldConfig {
   spellcheck?: boolean;
 }
+
+/**
+ * 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.
+ * @internal
+ */
+export type FieldInputValidator<T extends InputTypes> =
+    FieldValidator<string|T>;

core/field_multilineinput.ts

@@ -25,8 +25,6 @@ import {Svg} from './utils/svg.js';
 import * as userAgent from './utils/useragent.js';
 import * as WidgetDiv from './widgetdiv.js';
 
-export type FieldMultilineInputValidator = FieldTextInputValidator;
-
 /**
  * Class for an editable text area field.
  */
@@ -481,3 +479,20 @@ export interface FieldMultilineInputFromJsonConfig extends
     FieldMultilineInputConfig {
   text?: string;
 }
+
+/**
+ * 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 FieldMultilineInputValidator = FieldTextInputValidator;

core/field_number.ts

@@ -18,8 +18,6 @@ import {FieldInput, FieldInputConfig, FieldInputValidator} from './field_input.j
 import * as aria from './utils/aria.js';
 import type {Sentinel} from './utils/sentinel.js';
 
-export type FieldNumberValidator = FieldInputValidator<number>;
-
 /**
  * Class for an editable number field.
  */
@@ -342,3 +340,20 @@ export interface FieldNumberConfig extends FieldInputConfig {
 export interface FieldNumberFromJsonConfig extends FieldNumberConfig {
   value?: number;
 }
+
+/**
+ * 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 FieldNumberValidator = FieldInputValidator<number>;

core/field_textinput.ts

@@ -20,8 +20,6 @@ import * as fieldRegistry from './field_registry.js';
 import * as parsing from './utils/parsing.js';
 import type {Sentinel} from './utils/sentinel.js';
 
-export type FieldTextInputValidator = FieldInputValidator<string>;
-
 /**
  * Class for an editable text field.
  */
@@ -42,7 +40,7 @@ export class FieldTextInput extends FieldInput<string> {
    */
   constructor(
       opt_value?: string|Sentinel, opt_validator?: FieldTextInputValidator|null,
-      opt_config?: FieldInputConfig) {
+      opt_config?: FieldTextInputConfig) {
     super(opt_value, opt_validator, opt_config);
   }
 
@@ -81,11 +79,31 @@ fieldRegistry.register('field_input', FieldTextInput);
 
 FieldTextInput.prototype.DEFAULT_VALUE = '';
 
+/**
+ *  Config options for the text input field.
+ */
+export type FieldTextInputConfig = FieldInputConfig;
+
 /**
  * fromJson config options for the text input field.
  */
-export interface FieldTextInputFromJsonConfig extends FieldInputConfig {
+export interface FieldTextInputFromJsonConfig extends FieldTextInputConfig {
   text?: string;
 }
 
-export {FieldInputConfig as FieldTextInputConfig};
+/**
+ * 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 FieldTextInputValidator = FieldInputValidator<string>;

core/field_variable.ts

@@ -30,8 +30,6 @@ import {VariableModel} from './variable_model.js';
 import * as Variables from './variables.js';
 import * as Xml from './xml.js';
 
-export type FieldVariableValidator = FieldDropdownValidator;
-
 /**
  * Class for a variable's dropdown field.
  */
@@ -579,3 +577,20 @@ export interface FieldVariableConfig extends FieldConfig {
 export interface FieldVariableFromJsonConfig extends FieldVariableConfig {
   variable?: string;
 }
+
+/**
+ * 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 FieldVariableValidator = FieldDropdownValidator;