blockly 12.4.0 → 12.5.0

package/core/field_checkbox.d.ts

@@ -0,0 +1,156 @@
+/**
+ * @license
+ * Copyright 2012 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Checkbox field.  Checked or not checked.
+ *
+ * @class
+ */
+import './events/events_block_change.js';
+import { Field, FieldConfig, FieldValidator } from './field.js';
+type BoolString = 'TRUE' | 'FALSE';
+type CheckboxBool = BoolString | boolean;
+/**
+ * Class for a checkbox field.
+ */
+export declare class FieldCheckbox extends Field<CheckboxBool> {
+    /** Default character for the checkmark. */
+    static readonly CHECK_CHAR = "\u2713";
+    private checkChar;
+    /**
+     * Serializable fields are saved by the serializer, non-serializable fields
+     * are not. Editable fields should also be serializable.
+     */
+    SERIALIZABLE: boolean;
+    /**
+     * NOTE: The default value is set in `Field`, so maintain that value instead
+     * of overwriting it here or in the constructor.
+     */
+    value_: boolean | null;
+    /**
+     * @param value The initial value of the field. Should either be 'TRUE',
+     *     'FALSE' or a boolean. Defaults to 'FALSE'. 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 ('TRUE' or 'FALSE') & returns a
+     *     validated value ('TRUE' or 'FALSE'), or null to abort the change.
+     * @param config A map of options used to configure the field.
+     *     See the [field creation documentation]{@link
+     * https://developers.google.com/blockly/guides/create-custom-blocks/fields/built-in-fields/checkbox#creation}
+     * for a list of properties this parameter supports.
+     */
+    constructor(value?: CheckboxBool | typeof Field.SKIP_SETUP, validator?: FieldCheckboxValidator, config?: FieldCheckboxConfig);
+    /**
+     * 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: FieldCheckboxConfig): void;
+    /**
+     * Saves this field's value.
+     *
+     * @returns The boolean value held by this field.
+     * @internal
+     */
+    saveState(): any;
+    /**
+     * Create the block UI for this checkbox.
+     */
+    initView(): void;
+    render_(): void;
+    getDisplayText_(): string;
+    /**
+     * Set the character used for the check mark.
+     *
+     * @param character The character to use for the check mark, or null to use
+     *     the default.
+     */
+    setCheckCharacter(character: string | null): void;
+    /** Toggle the state of the checkbox on click. */
+    protected showEditor_(): void;
+    /**
+     * Ensure that the input value is valid ('TRUE' or 'FALSE').
+     *
+     * @param newValue The input value.
+     * @returns A valid value ('TRUE' or 'FALSE), or null if invalid.
+     */
+    protected doClassValidation_(newValue?: any): BoolString | null;
+    /**
+     * Update the value of the field, and update the checkElement.
+     *
+     * @param newValue The value to be saved. The default validator guarantees
+     *     that this is a either 'TRUE' or 'FALSE'.
+     */
+    protected doValueUpdate_(newValue: BoolString): void;
+    /**
+     * Get the value of this field, either 'TRUE' or 'FALSE'.
+     *
+     * @returns The value of this field.
+     */
+    getValue(): BoolString;
+    /**
+     * Get the boolean value of this field.
+     *
+     * @returns The boolean value of this field.
+     */
+    getValueBoolean(): boolean | null;
+    /**
+     * Get the text of this field. Used when the block is collapsed.
+     *
+     * @returns Text representing the value of this field ('true' or 'false').
+     */
+    getText(): string;
+    /**
+     * Convert a value into a pure boolean.
+     *
+     * Converts 'TRUE' to true and 'FALSE' to false correctly, everything else
+     * is cast to a boolean.
+     *
+     * @param value The value to convert.
+     * @returns The converted value.
+     */
+    private convertValueToBool;
+    /**
+     * Construct a FieldCheckbox from a JSON arg object.
+     *
+     * @param options A JSON object with options (checked).
+     * @returns The new field instance.
+     * @nocollapse
+     * @internal
+     */
+    static fromJson(options: FieldCheckboxFromJsonConfig): FieldCheckbox;
+}
+/**
+ * Config options for the checkbox field.
+ */
+export interface FieldCheckboxConfig extends FieldConfig {
+    checkCharacter?: string;
+}
+/**
+ * fromJson config options for the checkbox field.
+ */
+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>;
+export {};
+//# sourceMappingURL=field_checkbox.d.ts.map

package/core/field_dropdown.d.ts

@@ -0,0 +1,295 @@
+/**
+ * @license
+ * Copyright 2012 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Field, FieldConfig, FieldValidator } from './field.js';
+import { Menu } from './menu.js';
+import { MenuItem } from './menuitem.js';
+/**
+ * Class for an editable dropdown field.
+ */
+export declare class FieldDropdown extends Field<string> {
+    /**
+     * Magic constant used to represent a separator in a list of dropdown items.
+     */
+    static readonly SEPARATOR = "separator";
+    static ARROW_CHAR: string;
+    /** A reference to the currently selected menu item. */
+    private selectedMenuItem;
+    /** The dropdown menu. */
+    protected menu_: Menu | null;
+    /**
+     * SVG image element if currently selected option is an image, or null.
+     */
+    private imageElement;
+    /** Tspan based arrow element. */
+    private arrow;
+    /** SVG based arrow element. */
+    private svgArrow;
+    /**
+     * Serializable fields are saved by the serializer, non-serializable fields
+     * are not. Editable fields should also be serializable.
+     */
+    SERIALIZABLE: boolean;
+    protected menuGenerator_?: MenuGenerator;
+    /** A cache of the most recently generated options. */
+    private generatedOptions;
+    /**
+     * The prefix field label, of common words set after options are trimmed.
+     *
+     * @internal
+     */
+    prefixField: string | null;
+    /**
+     * The suffix field label, of common words set after options are trimmed.
+     *
+     * @internal
+     */
+    suffixField: string | null;
+    private selectedOption;
+    clickTarget_: SVGElement | null;
+    /**
+     * The y offset from the top of the field to the top of the image, if an image
+     * is selected.
+     */
+    protected static IMAGE_Y_OFFSET: number;
+    /** The total vertical padding above and below an image. */
+    protected static IMAGE_Y_PADDING: number;
+    /**
+     * @param menuGenerator A non-empty array of options for a dropdown list, or a
+     *     function which generates these options. 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 language-neutral dropdown option & returns a
+     *     validated language-neutral dropdown option, 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/dropdown#creation}
+     * for a list of properties this parameter supports.
+     * @throws {TypeError} If `menuGenerator` options are incorrectly structured.
+     */
+    constructor(menuGenerator: MenuGenerator, validator?: FieldDropdownValidator, config?: FieldDropdownConfig);
+    constructor(menuGenerator: typeof Field.SKIP_SETUP);
+    /**
+     * 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.
+     * @internal
+     */
+    fromXml(fieldElement: Element): void;
+    /**
+     * Sets the field's value based on the given state.
+     *
+     * @param state The state to apply to the dropdown field.
+     * @internal
+     */
+    loadState(state: any): void;
+    /**
+     * Create the block UI for this dropdown.
+     */
+    initView(): void;
+    /**
+     * Whether or not the dropdown should add a border rect.
+     *
+     * @returns True if the dropdown field should add a border rect.
+     */
+    protected shouldAddBorderRect_(): boolean;
+    /** Create a tspan based arrow. */
+    protected createTextArrow_(): void;
+    /** Create an SVG based arrow. */
+    protected createSVGArrow_(): void;
+    /**
+     * Create a dropdown menu under the text.
+     *
+     * @param e Optional mouse event that triggered the field to open, or
+     *     undefined if triggered programmatically.
+     */
+    protected showEditor_(e?: MouseEvent): void;
+    /** Create the dropdown editor. */
+    private dropdownCreate;
+    /**
+     * Disposes of events and DOM-references belonging to the dropdown editor.
+     */
+    protected dropdownDispose_(): void;
+    /**
+     * Handle an action in the dropdown menu.
+     *
+     * @param menuItem The MenuItem selected within menu.
+     */
+    private handleMenuActionEvent;
+    /**
+     * Handle the selection of an item in the dropdown menu.
+     *
+     * @param menu The Menu component clicked.
+     * @param menuItem The MenuItem selected within menu.
+     */
+    protected onItemSelected_(menu: Menu, menuItem: MenuItem): void;
+    /**
+     * @returns True if the option list is generated by a function.
+     *     Otherwise false.
+     */
+    isOptionListDynamic(): boolean;
+    /**
+     * Return a list of the options for this dropdown.
+     *
+     * @param useCache For dynamic options, whether or not to use the cached
+     *     options or to re-generate them.
+     * @returns A non-empty array of option tuples:
+     *     (human-readable text or image, language-neutral name).
+     * @throws {TypeError} If generated options are incorrectly structured.
+     */
+    getOptions(useCache?: boolean): MenuOption[];
+    /**
+     * Update the options on this dropdown. This will reset the selected item to
+     * the first item in the list.
+     *
+     * @param menuGenerator The array of options or a generator function.
+     */
+    setOptions(menuGenerator: MenuGenerator): void;
+    /**
+     * Ensure that the input value is a valid language-neutral option.
+     *
+     * @param newValue The input value.
+     * @returns A valid language-neutral option, or null if invalid.
+     */
+    protected doClassValidation_(newValue: string): string | null | undefined;
+    protected doClassValidation_(newValue?: string): string | null;
+    /**
+     * Update the value of this dropdown field.
+     *
+     * @param newValue The value to be saved. The default validator guarantees
+     *     that this is one of the valid dropdown options.
+     */
+    protected doValueUpdate_(newValue: string): void;
+    /**
+     * Updates the dropdown arrow to match the colour/style of the block.
+     */
+    applyColour(): void;
+    /** Draws the border with the correct width. */
+    protected render_(): void;
+    /**
+     * Renders the selected option, which must be an image.
+     *
+     * @param imageJson Selected option that must be an image.
+     */
+    private renderSelectedImage;
+    /** Renders the selected option, which must be text. */
+    private renderSelectedText;
+    /**
+     * Position a drop-down arrow at the appropriate location at render-time.
+     *
+     * @param x X position the arrow is being rendered at, in px.
+     * @param y Y position the arrow is being rendered at, in px.
+     * @returns Amount of space the arrow is taking up, in px.
+     */
+    private positionSVGArrow;
+    /**
+     * Use the `getText_` developer hook to override the field's text
+     * representation.  Get the selected option text.  If the selected option is
+     * an image we return the image alt text. If the selected option is
+     * an HTMLElement, return the title, ariaLabel, or innerText of the
+     * element.
+     *
+     * If you use HTMLElement options in Node.js and call this function,
+     * ensure that you are supplying an implementation of HTMLElement,
+     * such as through jsdom-global.
+     *
+     * @returns Selected option text.
+     */
+    protected getText_(): string | null;
+    /**
+     * Construct a FieldDropdown from a JSON arg object.
+     *
+     * @param options A JSON object with options (options).
+     * @returns The new field instance.
+     * @nocollapse
+     * @internal
+     */
+    static fromJson(options: FieldDropdownFromJsonConfig): FieldDropdown;
+    /**
+     * Factor out common words in statically defined options.
+     * Create prefix and/or suffix labels.
+     */
+    protected trimOptions(options: MenuOption[]): {
+        options: MenuOption[];
+        prefix?: string;
+        suffix?: string;
+    };
+    /**
+     * Use the calculated prefix and suffix lengths to trim all of the options in
+     * the given array.
+     *
+     * @param options Array of option tuples:
+     *     (human-readable text or image, language-neutral name).
+     * @param prefixLength The length of the common prefix.
+     * @param suffixLength The length of the common suffix
+     * @returns A new array with all of the option text trimmed.
+     */
+    private applyTrim;
+    /**
+     * Validates the data structure to be processed as an options list.
+     *
+     * @param options The proposed dropdown options.
+     * @throws {TypeError} If proposed options are incorrectly structured.
+     */
+    protected validateOptions(options: MenuOption[]): void;
+}
+/**
+ * Definition of a human-readable image dropdown option.
+ */
+export interface ImageProperties {
+    src: string;
+    alt: string;
+    width: number;
+    height: number;
+}
+/**
+ * An individual option in the dropdown menu. Can be either the string literal
+ * `separator` for a menu separator item, or an array for normal action menu
+ * items. In the latter case, the first element is the human-readable value
+ * (text, ImageProperties object, or HTML element), and the second element is
+ * the language-neutral value.
+ */
+export type MenuOption = [string | ImageProperties | HTMLElement, string] | 'separator';
+/**
+ * A function that generates an array of menu options for FieldDropdown
+ * or its descendants.
+ */
+export type MenuGeneratorFunction = (this: FieldDropdown) => MenuOption[];
+/**
+ * Either an array of menu options or a function that generates an array of
+ * menu options for FieldDropdown or its descendants.
+ */
+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 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>;
+//# sourceMappingURL=field_dropdown.d.ts.map

package/core/field_image.d.ts

@@ -0,0 +1,148 @@
+/**
+ * @license
+ * Copyright 2012 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Image field.  Used for pictures, icons, etc.
+ *
+ * @class
+ */
+import { Field, FieldConfig } from './field.js';
+/**
+ * Class for an image on a block.
+ */
+export declare class FieldImage extends Field<string> {
+    /**
+     * Vertical padding below the image, which is included in the reported height
+     * of the field.
+     */
+    private static readonly Y_PADDING;
+    protected readonly imageHeight: number;
+    /** The function to be called when this field is clicked. */
+    private clickHandler;
+    /** The rendered field's image element. */
+    protected imageElement: SVGImageElement | null;
+    /**
+     * Editable fields usually show some sort of UI indicating they are
+     * editable. This field should not.
+     */
+    readonly EDITABLE = false;
+    /**
+     * Used to tell if the field needs to be rendered the next time the block is
+     * rendered. Image fields are statically sized, and only need to be
+     * rendered at initialization.
+     */
+    protected isDirty_: boolean;
+    /** Whether to flip this image in RTL. */
+    private flipRtl;
+    /** Alt text of this image. */
+    private altText;
+    /**
+     * @param src The URL of the image.
+     *     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 width Width of the image.
+     * @param height Height of the image.
+     * @param alt Optional alt text for when block is collapsed.
+     * @param onClick Optional function to be called when the image is
+     *     clicked. If onClick is defined, alt must also be defined.
+     * @param flipRtl Whether to flip the icon in RTL.
+     * @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/image#creation}
+     * for a list of properties this parameter supports.
+     */
+    constructor(src: string | typeof Field.SKIP_SETUP, width: string | number, height: string | number, alt?: string, onClick?: (p1: FieldImage) => void, flipRtl?: boolean, config?: FieldImageConfig);
+    /**
+     * 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: FieldImageConfig): void;
+    /**
+     * Create the block UI for this image.
+     */
+    initView(): void;
+    updateSize_(): void;
+    /**
+     * Ensure that the input value (the source URL) is a string.
+     *
+     * @param newValue The input value.
+     * @returns A string, or null if invalid.
+     */
+    protected doClassValidation_(newValue?: any): string | null;
+    /**
+     * Update the value of this image field, and update the displayed image.
+     *
+     * @param newValue The value to be saved. The default validator guarantees
+     *     that this is a string.
+     */
+    protected doValueUpdate_(newValue: string): void;
+    /**
+     * Get whether to flip this image in RTL
+     *
+     * @returns True if we should flip in RTL.
+     */
+    getFlipRtl(): boolean;
+    /**
+     * Set the alt text of this image.
+     *
+     * @param alt New alt text.
+     */
+    setAlt(alt: string | null): void;
+    /**
+     * Check whether this field should be clickable.
+     *
+     * @returns Whether this field is clickable.
+     */
+    isClickable(): boolean;
+    /**
+     * If field click is called, and click handler defined,
+     * call the handler.
+     */
+    protected showEditor_(): void;
+    /**
+     * Set the function that is called when this image  is clicked.
+     *
+     * @param func The function that is called when the image is clicked, or null
+     *     to remove.
+     */
+    setOnClickHandler(func: ((p1: FieldImage) => void) | null): void;
+    /**
+     * Use the `getText_` developer hook to override the field's text
+     * representation.
+     * Return the image alt text instead.
+     *
+     * @returns The image alt text.
+     */
+    protected getText_(): string | null;
+    /**
+     * Construct a FieldImage from a JSON arg object,
+     * dereferencing any string table references.
+     *
+     * @param options A JSON object with options (src, width, height, alt, and
+     *     flipRtl).
+     * @returns The new field instance.
+     * @nocollapse
+     * @internal
+     */
+    static fromJson(options: FieldImageFromJsonConfig): FieldImage;
+}
+/**
+ * Config options for the image field.
+ */
+export interface FieldImageConfig extends FieldConfig {
+    flipRtl?: boolean;
+    alt?: string;
+}
+/**
+ * fromJson config options for the image field.
+ */
+export interface FieldImageFromJsonConfig extends FieldImageConfig {
+    src?: string;
+    width?: number;
+    height?: number;
+}
+//# sourceMappingURL=field_image.d.ts.map