From 9e5bfc243ea285d530d2ad2f2e579a76dcc73815 Mon Sep 17 00:00:00 2001 From: Blake Thomas Williams <49404493+btw17@users.noreply.github.com> Date: Fri, 3 Mar 2023 16:20:20 -0600 Subject: [PATCH] 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 | 79 ++++++++++++++++++++++++++---------- core/field.ts | 4 +- core/field_angle.ts | 19 ++++++++- core/field_checkbox.ts | 18 +++++++- core/field_colour.ts | 19 ++++++++- core/field_dropdown.ts | 30 +++++++++++--- core/field_input.ts | 31 ++++++++++++-- core/field_multilineinput.ts | 19 ++++++++- core/field_number.ts | 19 ++++++++- core/field_textinput.ts | 28 ++++++++++--- core/field_variable.ts | 19 ++++++++- 11 files changed, 238 insertions(+), 47 deletions(-) diff --git a/core/blockly.ts b/core/blockly.ts index ab81e516e..98399c766 100644 --- a/core/blockly.ts +++ b/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}; diff --git a/core/field.ts b/core/field.ts index 3675bd174..8db438354 100644 --- a/core/field.ts +++ b/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; diff --git a/core/field_angle.ts b/core/field_angle.ts index 31c910920..971126cf9 100644 --- a/core/field_angle.ts +++ b/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; - /** * 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; diff --git a/core/field_checkbox.ts b/core/field_checkbox.ts index 9f3f107c7..f884bc47c 100644 --- a/core/field_checkbox.ts +++ b/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; /** * 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; diff --git a/core/field_colour.ts b/core/field_colour.ts index 8df51ed77..cc703a8ed 100644 --- a/core/field_colour.ts +++ b/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; - /** * 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; diff --git a/core/field_dropdown.ts b/core/field_dropdown.ts index 50734bd55..04d9d7580 100644 --- a/core/field_dropdown.ts +++ b/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; - /** * Class for an editable dropdown field. */ @@ -112,13 +110,13 @@ export class FieldDropdown extends Field { 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; + /** * The y offset from the top of the field to the top of the image, if an image * is selected. diff --git a/core/field_input.ts b/core/field_input.ts index 9eb0b7614..3d3f4302a 100644 --- a/core/field_input.ts +++ b/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 = - FieldValidator; +/** + * 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 extends Field { /** @@ -559,7 +563,28 @@ export abstract class FieldInput extends Field { /** * 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 = + FieldValidator; diff --git a/core/field_multilineinput.ts b/core/field_multilineinput.ts index 1d4aac52f..467ace17c 100644 --- a/core/field_multilineinput.ts +++ b/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; diff --git a/core/field_number.ts b/core/field_number.ts index 9f45d8ef6..5be44816d 100644 --- a/core/field_number.ts +++ b/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; - /** * 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; diff --git a/core/field_textinput.ts b/core/field_textinput.ts index 401984b76..5b6a3878e 100644 --- a/core/field_textinput.ts +++ b/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; - /** * Class for an editable text field. */ @@ -42,7 +40,7 @@ export class FieldTextInput extends FieldInput { */ 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; diff --git a/core/field_variable.ts b/core/field_variable.ts index 4a2c1b8f1..091a01a4a 100644 --- a/core/field_variable.ts +++ b/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;