blockly 12.4.0 → 12.4.1

package/core/field_input.d.ts

@@ -0,0 +1,293 @@
+/**
+ * @license
+ * Copyright 2012 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Text input field.
+ *
+ * @class
+ */
+import './events/events_block_change.js';
+import { Field, FieldConfig, FieldValidator } from './field.js';
+import { Size } from './utils/size.js';
+import type { WorkspaceSvg } from './workspace_svg.js';
+/**
+ * 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 declare abstract class FieldInput<T extends InputTypes> extends Field<string | T> {
+    /**
+     * Pixel size of input border radius.
+     * Should match blocklyText's border-radius in CSS.
+     */
+    static BORDERRADIUS: number;
+    /** Allow browser to spellcheck this field. */
+    protected spellcheck_: boolean;
+    /** The HTML input element. */
+    protected htmlInput_: HTMLInputElement | null;
+    /** True if the field's value is currently being edited via the UI. */
+    protected isBeingEdited_: boolean;
+    /**
+     * True if the value currently displayed in the field's editory UI is valid.
+     */
+    protected isTextValid_: boolean;
+    /**
+     * The intial value of the field when the user opened an editor to change its
+     * value. When the editor is disposed, an event will be fired that uses this
+     * as the event's oldValue.
+     */
+    protected valueWhenEditorWasOpened_: string | T | null;
+    /** Key down event data. */
+    private onKeyDownWrapper;
+    /** Input element input event data. */
+    private onInputWrapper;
+    /**
+     * Whether the field should consider the whole parent block to be its click
+     * target.
+     */
+    fullBlockClickTarget_: boolean;
+    /** The workspace that this field belongs to. */
+    protected workspace_: WorkspaceSvg | null;
+    /**
+     * Serializable fields are saved by the serializer, non-serializable fields
+     * are not. Editable fields should also be serializable.
+     */
+    SERIALIZABLE: boolean;
+    protected set size_(newValue: Size);
+    /**
+     * Returns the size of this field, with a minimum width of 14.
+     */
+    protected get size_(): Size;
+    /**
+     * @param value The initial value of the field. Should cast to a string.
+     *     Defaults to an empty string if null or undefined. 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 string & returns a validated string, 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/text-input#creation}
+     * for a list of properties this parameter supports.
+     */
+    constructor(value?: string | typeof Field.SKIP_SETUP, validator?: FieldInputValidator<T> | null, config?: FieldInputConfig);
+    protected configure_(config: FieldInputConfig): void;
+    initView(): void;
+    isFullBlockField(): boolean;
+    /**
+     * Called by setValue if the text input is not valid. If the field is
+     * currently being edited it reverts value of the field to the previous
+     * value while allowing the display text to be handled by the htmlInput_.
+     *
+     * @param _invalidValue The input value that was determined to be invalid.
+     *     This is not used by the text input because its display value is stored
+     *     on the htmlInput_.
+     * @param fireChangeEvent Whether to fire a change event if the value changes.
+     */
+    protected doValueInvalid_(_invalidValue: any, fireChangeEvent?: boolean): void;
+    /**
+     * Called by setValue if the text input is valid. Updates the value of the
+     * field, and updates the text of the field if it is not currently being
+     * edited (i.e. handled by the htmlInput_).
+     *
+     * @param newValue The value to be saved. The default validator guarantees
+     *     that this is a string.
+     */
+    protected doValueUpdate_(newValue: string | T): void;
+    /**
+     * Updates text field to match the colour/style of the block.
+     */
+    applyColour(): void;
+    /**
+     * 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;
+    /**
+     * Notifies the field that it has changed locations. Moves the widget div to
+     * be in the correct place if it is open.
+     */
+    onLocationChange(): void;
+    /**
+     * Updates the colour of the htmlInput given the current validity of the
+     * field's value.
+     *
+     * Also updates the colour of the block to reflect whether this is a full
+     * block field or not.
+     */
+    protected render_(): void;
+    /**
+     * Set whether this field is spellchecked by the browser.
+     *
+     * @param check True if checked.
+     */
+    setSpellcheck(check: boolean): void;
+    /**
+     * Show an editor for the field.
+     * Shows the inline free-text editor on top of the text by default.
+     * Shows a prompt editor for mobile browsers if the modalInputs option is
+     * enabled.
+     *
+     * @param _e Optional mouse event that triggered the field to open, or
+     *     undefined if triggered programmatically.
+     * @param quietInput True if editor should be created without focus.
+     *     Defaults to false.
+     * @param manageEphemeralFocus Whether ephemeral focus should be managed as
+     *     part of the editor's inline editor (when the inline editor is shown).
+     *     Callers must manage ephemeral focus themselves if this is false.
+     *     Defaults to true.
+     */
+    protected showEditor_(_e?: Event, quietInput?: boolean, manageEphemeralFocus?: boolean): void;
+    /**
+     * Create and show a text input editor that is a prompt (usually a popup).
+     * Mobile browsers may have issues with in-line textareas (focus and
+     * keyboards).
+     */
+    private showPromptEditor;
+    /**
+     * Create and show a text input editor that sits directly over the text input.
+     *
+     * @param quietInput True if editor should be created without focus.
+     * @param manageEphemeralFocus Whether ephemeral focus should be managed as
+     *     part of the field's inline editor (widget div).
+     */
+    private showInlineEditor;
+    /**
+     * Create the text input editor widget.
+     *
+     * @returns The newly created text input editor.
+     */
+    protected widgetCreate_(): HTMLInputElement | HTMLTextAreaElement;
+    /**
+     * Closes the editor, saves the results, and disposes of any events or
+     * DOM-references belonging to the editor.
+     */
+    protected widgetDispose_(): void;
+    /**
+     * A callback triggered when the user is done editing the field via the UI.
+     *
+     * @param _value The new value of the field.
+     */
+    onFinishEditing_(_value: any): void;
+    /**
+     * Bind handlers for user input on the text input field's editor.
+     *
+     * @param htmlInput The htmlInput to which event handlers will be bound.
+     */
+    protected bindInputEvents_(htmlInput: HTMLElement): void;
+    /** Unbind handlers for user input and workspace size changes. */
+    protected unbindInputEvents_(): void;
+    /**
+     * Handle key down to the editor.
+     *
+     * @param e Keyboard event.
+     */
+    protected onHtmlInputKeyDown_(e: KeyboardEvent): void;
+    /**
+     * Handle a change to the editor.
+     *
+     * @param _e InputEvent.
+     */
+    private onHtmlInputChange;
+    /**
+     * Set the HTML input value and the field's internal value. The difference
+     * between this and `setValue` is that this also updates the HTML input
+     * value whilst editing.
+     *
+     * @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.
+     */
+    protected setEditorValue_(newValue: any, fireChangeEvent?: boolean): void;
+    /** Resize the editor to fit the text. */
+    protected resizeEditor_(): void;
+    /**
+     * Handles repositioning the WidgetDiv used for input fields when the
+     * workspace is resized. Will bump the block into the viewport and update the
+     * position of the text input if necessary.
+     *
+     * @returns True for rendered workspaces, as we never want to hide the widget
+     *     div.
+     */
+    repositionForWindowResize(): boolean;
+    /**
+     * Position a field's text element after a size change.  This handles both LTR
+     * and RTL positioning.
+     *
+     * @param xMargin x offset to use when positioning the text element.
+     * @param contentWidth The content width.
+     */
+    protected positionTextElement_(xMargin: number, contentWidth: number): void;
+    /**
+     * Use the `getText_` developer hook to override the field's text
+     * representation. When we're currently editing, return the current HTML value
+     * instead. Otherwise, return null which tells the field to use the default
+     * behaviour (which is a string cast of the field's value).
+     *
+     * @returns The HTML value if we're editing, otherwise null.
+     */
+    protected getText_(): string | null;
+    /**
+     * Transform the provided value into a text to show in the HTML input.
+     * Override this method if the field's HTML input representation is different
+     * than the field's value. This should be coupled with an override of
+     * `getValueFromEditorText_`.
+     *
+     * @param value The value stored in this field.
+     * @returns The text to show on the HTML input.
+     */
+    protected getEditorText_(value: any): string;
+    /**
+     * Transform the text received from the HTML input into a value to store
+     * in this field.
+     * Override this method if the field's HTML input representation is different
+     * than the field's value. This should be coupled with an override of
+     * `getEditorText_`.
+     *
+     * @param text Text received from the HTML input.
+     * @returns The value to store.
+     */
+    protected getValueFromEditorText_(text: string): any;
+}
+/**
+ * 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>;
+export {};
+//# sourceMappingURL=field_input.d.ts.map

package/core/field_label.d.ts

@@ -0,0 +1,80 @@
+/**
+ * @license
+ * Copyright 2012 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Non-editable, non-serializable text field.  Used for titles,
+ *    labels, etc.
+ *
+ * @class
+ */
+import { Field, FieldConfig } from './field.js';
+/**
+ * Class for a non-editable, non-serializable text field.
+ */
+export declare class FieldLabel extends Field<string> {
+    /** The HTML class name to use for this field. */
+    private class;
+    /**
+     * Editable fields usually show some sort of UI indicating they are
+     * editable. This field should not.
+     */
+    EDITABLE: boolean;
+    /** Text labels should not truncate. */
+    maxDisplayLength: number;
+    /**
+     * @param value The initial value of the field. Should cast to a string.
+     *     Defaults to an empty string if null or undefined. 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 textClass Optional CSS class for the field's text.
+     * @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/label#creation}
+     * for a list of properties this parameter supports.
+     */
+    constructor(value?: string | typeof Field.SKIP_SETUP, textClass?: string, config?: FieldLabelConfig);
+    protected configure_(config: FieldLabelConfig): void;
+    /**
+     * Create block UI for this label.
+     */
+    initView(): void;
+    /**
+     * Ensure that the input value casts to a valid string.
+     *
+     * @param newValue The input value.
+     * @returns A valid string, or null if invalid.
+     */
+    protected doClassValidation_(newValue?: any): string | null;
+    /**
+     * Set the CSS class applied to the field's textElement_.
+     *
+     * @param cssClass The new CSS class name, or null to remove.
+     */
+    setClass(cssClass: string | null): void;
+    /**
+     * Construct a FieldLabel from a JSON arg object,
+     * dereferencing any string table references.
+     *
+     * @param options A JSON object with options (text, and class).
+     * @returns The new field instance.
+     * @nocollapse
+     * @internal
+     */
+    static fromJson(options: FieldLabelFromJsonConfig): FieldLabel;
+}
+/**
+ * Config options for the label field.
+ */
+export interface FieldLabelConfig extends FieldConfig {
+    class?: string;
+}
+/**
+ * fromJson config options for the label field.
+ */
+export interface FieldLabelFromJsonConfig extends FieldLabelConfig {
+    text?: string;
+}
+//# sourceMappingURL=field_label.d.ts.map

package/core/field_label_serializable.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @license
+ * Copyright 2019 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Non-editable, serializable text field. Behaves like a
+ *    normal label but is serialized to XML. It may only be
+ *    edited programmatically.
+ *
+ * @class
+ */
+import { FieldLabel, FieldLabelConfig, FieldLabelFromJsonConfig } from './field_label.js';
+/**
+ * Class for a non-editable, serializable text field.
+ */
+export declare class FieldLabelSerializable extends FieldLabel {
+    /**
+     * Editable fields usually show some sort of UI indicating they are
+     * editable. This field should not.
+     */
+    EDITABLE: boolean;
+    /**
+     * Serializable fields are saved by the XML renderer, non-serializable
+     * fields are not.  This field should be serialized, but only edited
+     * programmatically.
+     */
+    SERIALIZABLE: boolean;
+    /**
+     * @param value The initial value of the field. Should cast to a string.
+     *     Defaults to an empty string if null or undefined.
+     * @param textClass Optional CSS class for the field's text.
+     * @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/label-serializable#creation}
+     * for a list of properties this parameter supports.
+     */
+    constructor(value?: string, textClass?: string, config?: FieldLabelConfig);
+    /**
+     * Construct a FieldLabelSerializable from a JSON arg object,
+     * dereferencing any string table references.
+     *
+     * @param options A JSON object with options (text, and class).
+     * @returns The new field instance.
+     * @nocollapse
+     * @internal
+     */
+    static fromJson(options: FieldLabelFromJsonConfig): FieldLabelSerializable;
+}
+//# sourceMappingURL=field_label_serializable.d.ts.map

package/core/field_number.d.ts

@@ -0,0 +1,194 @@
+/**
+ * @license
+ * Copyright 2016 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Number input field
+ *
+ * @class
+ */
+import { Field } from './field.js';
+import { FieldInput, FieldInputConfig, FieldInputValidator } from './field_input.js';
+/**
+ * Class for an editable number field.
+ */
+export declare class FieldNumber extends FieldInput<number> {
+    /** The minimum value this number field can contain. */
+    protected min_: number;
+    /** The maximum value this number field can contain. */
+    protected max_: number;
+    /** The multiple to which this fields value is rounded. */
+    protected precision_: number;
+    /**
+     * The number of decimal places to allow, or null to allow any number of
+     * decimal digits.
+     */
+    private decimalPlaces;
+    /** Don't spellcheck numbers.  Our validator does a better job. */
+    protected spellcheck_: boolean;
+    /**
+     * @param value The initial value of the field. Should cast to a number.
+     *     Defaults to 0. 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 min Minimum value. Will only be used if config is not
+     *     provided.
+     * @param max Maximum value. Will only be used if config is not
+     *     provided.
+     * @param precision Precision for value. Will only be used if config
+     *     is not provided.
+     * @param validator A function that is called to validate changes to the
+     *     field's value. Takes in a number & returns a validated number, 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/number#creation}
+     * for a list of properties this parameter supports.
+     */
+    constructor(value?: string | number | typeof Field.SKIP_SETUP, min?: string | number | null, max?: string | number | null, precision?: string | number | null, validator?: FieldNumberValidator | null, config?: FieldNumberConfig);
+    /**
+     * Configure the field based on the given map of options.
+     *
+     * @param config A map of options to configure the field based on.
+     */
+    protected configure_(config: FieldNumberConfig): void;
+    /**
+     * Set the maximum, minimum and precision constraints on this field.
+     * Any of these properties may be undefined or NaN to be disabled.
+     * Setting precision (usually a power of 10) enforces a minimum step between
+     * values. That is, the user's value will rounded to the closest multiple of
+     * precision. The least significant digit place is inferred from the
+     * precision. Integers values can be enforces by choosing an integer
+     * precision.
+     *
+     * @param min Minimum value.
+     * @param max Maximum value.
+     * @param precision Precision for value.
+     */
+    setConstraints(min: number | string | undefined | null, max: number | string | undefined | null, precision: number | string | undefined | null): void;
+    /**
+     * Sets the minimum value this field can contain. Updates the value to
+     * reflect.
+     *
+     * @param min Minimum value.
+     */
+    setMin(min: number | string | undefined | null): void;
+    /**
+     * Sets the minimum value this field can contain. Called internally to avoid
+     * value updates.
+     *
+     * @param min Minimum value.
+     */
+    private setMinInternal;
+    /**
+     * Returns the current minimum value this field can contain. Default is
+     * -Infinity.
+     *
+     * @returns The current minimum value this field can contain.
+     */
+    getMin(): number;
+    /**
+     * Sets the maximum value this field can contain. Updates the value to
+     * reflect.
+     *
+     * @param max Maximum value.
+     */
+    setMax(max: number | string | undefined | null): void;
+    /**
+     * Sets the maximum value this field can contain. Called internally to avoid
+     * value updates.
+     *
+     * @param max Maximum value.
+     */
+    private setMaxInternal;
+    /**
+     * Returns the current maximum value this field can contain. Default is
+     * Infinity.
+     *
+     * @returns The current maximum value this field can contain.
+     */
+    getMax(): number;
+    /**
+     * Sets the precision of this field's value, i.e. the number to which the
+     * value is rounded. Updates the field to reflect.
+     *
+     * @param precision The number to which the field's value is rounded.
+     */
+    setPrecision(precision: number | string | undefined | null): void;
+    /**
+     * Sets the precision of this field's value. Called internally to avoid
+     * value updates.
+     *
+     * @param precision The number to which the field's value is rounded.
+     */
+    private setPrecisionInternal;
+    /**
+     * Returns the current precision of this field. The precision being the
+     * number to which the field's value is rounded. A precision of 0 means that
+     * the value is not rounded.
+     *
+     * @returns The number to which this field's value is rounded.
+     */
+    getPrecision(): number;
+    /**
+     * Ensure that the input value is a valid number (must fulfill the
+     * constraints placed on the field).
+     *
+     * @param newValue The input value.
+     * @returns A valid number, or null if invalid.
+     */
+    protected doClassValidation_(newValue?: any): number | null;
+    /**
+     * Create the number input editor widget.
+     *
+     * @returns The newly created number input editor.
+     */
+    protected widgetCreate_(): HTMLInputElement;
+    /**
+     * Initialize the field's DOM.
+     *
+     * @override
+     */
+    initView(): void;
+    /**
+     * Construct a FieldNumber from a JSON arg object.
+     *
+     * @param options A JSON object with options (value, min, max, and precision).
+     * @returns The new field instance.
+     * @nocollapse
+     * @internal
+     */
+    static fromJson(options: FieldNumberFromJsonConfig): FieldNumber;
+}
+/**
+ * Config options for the number field.
+ */
+export interface FieldNumberConfig extends FieldInputConfig {
+    min?: number;
+    max?: number;
+    precision?: number;
+}
+/**
+ * fromJson config options for the number field.
+ */
+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>;
+//# sourceMappingURL=field_number.d.ts.map

package/core/field_registry.d.ts

@@ -0,0 +1,83 @@
+/**
+ * @license
+ * Copyright 2019 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { Field, FieldConfig } from './field.js';
+/**
+ * When constructing a field from JSON using the registry, the
+ * `fromJson` method in this file is called with an options parameter
+ * object consisting of the "type" which is the name of the field, and
+ * other options that are part of the field's config object.
+ *
+ * These options are then passed to the field's static `fromJson`
+ * method. That method accepts an options parameter with a type that usually
+ * extends from FieldConfig, and may or may not have a "type" attribute (in
+ * fact, it shouldn't, because we'd overwrite it as described above!)
+ *
+ * Unfortunately the registry has no way of knowing the actual Field subclass
+ * that will be returned from passing in the name of the field. Therefore it
+ * also has no way of knowing that the options object not only implements
+ * `FieldConfig`, but it also should satisfy the Config that belongs to that
+ * specific class's `fromJson` method.
+ *
+ * Because of this uncertainty, we just give up on type checking the properties
+ * passed to the `fromJson` method, and allow arbitrary string keys with
+ * unknown types.
+ */
+type RegistryOptions = FieldConfig & {
+    type: string;
+    [key: string]: unknown;
+};
+/**
+ * Represents the static methods that must be defined on any
+ * field that is registered, i.e. the constructor and fromJson methods.
+ *
+ * Because we don't know which Field subclass will be registered, we
+ * are unable to typecheck the parameters of the constructor.
+ */
+export interface RegistrableField {
+    new (...args: any[]): Field;
+    fromJson(options: FieldConfig): Field;
+}
+/**
+ * Registers a field type.
+ * fieldRegistry.fromJson uses this registry to
+ * find the appropriate field type.
+ *
+ * @param type The field type name as used in the JSON definition.
+ * @param fieldClass The field class containing a fromJson function that can
+ *     construct an instance of the field.
+ * @throws {Error} if the type name is empty or the fieldClass is not an object
+ *     containing a fromJson function.
+ */
+export declare function register(type: string, fieldClass: RegistrableField): void;
+/**
+ * Unregisters the field registered with the given type.
+ *
+ * @param type The field type name as used in the JSON definition.
+ */
+export declare function unregister(type: string): void;
+/**
+ * Construct a Field from a JSON arg object.
+ * Finds the appropriate registered field by the type name as registered using
+ * fieldRegistry.register.
+ *
+ * @param options A JSON object with a type and options specific to the field
+ *     type.
+ * @returns The new field instance or null if a field wasn't found with the
+ *     given type name
+ * @internal
+ */
+export declare function fromJson<T>(options: RegistryOptions): Field<T> | null;
+/**
+ * Private version of fromJson for stubbing in tests.
+ *
+ * @param options
+ */
+declare function fromJsonInternal<T>(options: RegistryOptions): Field<T> | null;
+export declare const TEST_ONLY: {
+    fromJsonInternal: typeof fromJsonInternal;
+};
+export {};
+//# sourceMappingURL=field_registry.d.ts.map