blockly 11.0.0-beta.4 → 11.0.0-beta.5

package/core/field_colour.d.ts

@@ -0,0 +1,243 @@
+/**
+ * @license
+ * Copyright 2012 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Colour input field.
+ *
+ * @class
+ */
+import './events/events_block_change.js';
+import { Field, FieldConfig, FieldValidator } from './field.js';
+import { Size } from './utils/size.js';
+/**
+ * Class for a colour input field.
+ */
+export declare class FieldColour extends Field<string> {
+    /**
+     * An array of colour strings for the palette.
+     * Copied from goog.ui.ColorPicker.SIMPLE_GRID_COLORS
+     * All colour pickers use this unless overridden with setColours.
+     */
+    static COLOURS: string[];
+    /**
+     * An array of tooltip strings for the palette.  If not the same length as
+     * COLOURS, the colour's hex code will be used for any missing titles.
+     * All colour pickers use this unless overridden with setColours.
+     */
+    static TITLES: string[];
+    /**
+     * Number of columns in the palette.
+     * All colour pickers use this unless overridden with setColumns.
+     */
+    static COLUMNS: number;
+    /** The field's colour picker element. */
+    private picker;
+    /** Index of the currently highlighted element. */
+    private highlightedIndex;
+    /**
+     * Array holding info needed to unbind events.
+     * Used for disposing.
+     * Ex: [[node, name, func], [node, name, func]].
+     */
+    private boundEvents;
+    /**
+     * Serializable fields are saved by the serializer, non-serializable fields
+     * are not. Editable fields should also be serializable.
+     */
+    SERIALIZABLE: boolean;
+    /** Mouse cursor style when over the hotspot that initiates the editor. */
+    CURSOR: string;
+    /**
+     * Used to tell if the field needs to be rendered the next time the block is
+     * rendered. Colour fields are statically sized, and only need to be
+     * rendered at initialization.
+     */
+    protected isDirty_: boolean;
+    /** Array of colours used by this field.  If null, use the global list. */
+    private colours;
+    /**
+     * Array of colour tooltips used by this field.  If null, use the global
+     * list.
+     */
+    private titles;
+    /**
+     * Number of colour columns used by this field.  If 0, use the global
+     * setting. By default use the global constants for columns.
+     */
+    private columns;
+    /**
+     * @param value The initial value of the field. Should be in '#rrggbb'
+     *     format. Defaults to the first value in the default colour array. 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 colour string & returns a validated colour
+     *     string ('#rrggbb' format), 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/colour}
+     * for a list of properties this parameter supports.
+     */
+    constructor(value?: string | typeof Field.SKIP_SETUP, validator?: FieldColourValidator, config?: FieldColourConfig);
+    /**
+     * 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: FieldColourConfig): void;
+    /**
+     * Create the block UI for this colour field.
+     */
+    initView(): void;
+    protected isFullBlockField(): boolean;
+    /**
+     * 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;
+    /**
+     * Updates the colour of the block to reflect whether this is a full
+     * block field or not.
+     */
+    protected render_(): void;
+    /**
+     * Updates the size of the field based on whether it is a full block field
+     * or not.
+     *
+     * @param margin margin to use when positioning the field.
+     */
+    protected updateSize_(margin?: number): void;
+    /**
+     * Ensure that the input value is a valid colour.
+     *
+     * @param newValue The input value.
+     * @returns A valid colour, or null if invalid.
+     */
+    protected doClassValidation_(newValue?: any): string | null;
+    /**
+     * Get the text for this field.  Used when the block is collapsed.
+     *
+     * @returns Text representing the value of this field.
+     */
+    getText(): string;
+    /**
+     * Set a custom colour grid for this field.
+     *
+     * @param colours Array of colours for this block, or null to use default
+     *     (FieldColour.COLOURS).
+     * @param titles Optional array of colour tooltips, or null to use default
+     *     (FieldColour.TITLES).
+     * @returns Returns itself (for method chaining).
+     */
+    setColours(colours: string[], titles?: string[]): FieldColour;
+    /**
+     * Set a custom grid size for this field.
+     *
+     * @param columns Number of columns for this block, or 0 to use default
+     *     (FieldColour.COLUMNS).
+     * @returns Returns itself (for method chaining).
+     */
+    setColumns(columns: number): FieldColour;
+    /** Create and show the colour field's editor. */
+    protected showEditor_(): void;
+    /**
+     * Handle a click on a colour cell.
+     *
+     * @param e Mouse event.
+     */
+    private onClick;
+    /**
+     * Handle a key down event. Navigate around the grid with the
+     * arrow keys. Enter selects the highlighted colour.
+     *
+     * @param e Keyboard event.
+     */
+    private onKeyDown;
+    /**
+     * Move the currently highlighted position by dx and dy.
+     *
+     * @param dx Change of x.
+     * @param dy Change of y.
+     */
+    private moveHighlightBy;
+    /**
+     * Handle a mouse move event. Highlight the hovered colour.
+     *
+     * @param e Mouse event.
+     */
+    private onMouseMove;
+    /** Handle a mouse enter event. Focus the picker. */
+    private onMouseEnter;
+    /**
+     * Handle a mouse leave event. Blur the picker and unhighlight
+     * the currently highlighted colour.
+     */
+    private onMouseLeave;
+    /**
+     * Returns the currently highlighted item (if any).
+     *
+     * @returns Highlighted item (null if none).
+     */
+    private getHighlighted;
+    /**
+     * Update the currently highlighted cell.
+     *
+     * @param cell The new cell to highlight.
+     * @param index The index of the new cell.
+     */
+    private setHighlightedCell;
+    /** Create a colour picker dropdown editor. */
+    private dropdownCreate;
+    /** Disposes of events and DOM-references belonging to the colour editor. */
+    private dropdownDispose;
+    /**
+     * Construct a FieldColour from a JSON arg object.
+     *
+     * @param options A JSON object with options (colour).
+     * @returns The new field instance.
+     * @nocollapse
+     * @internal
+     */
+    static fromJson(options: FieldColourFromJsonConfig): FieldColour;
+}
+/**
+ * Config options for the colour field.
+ */
+export interface FieldColourConfig extends FieldConfig {
+    colourOptions?: string[];
+    colourTitles?: string[];
+    columns?: number;
+}
+/**
+ * fromJson config options for the colour field.
+ */
+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>;
+//# sourceMappingURL=field_colour.d.ts.map

package/core/field_dropdown.d.ts

@@ -148,7 +148,6 @@ export declare class FieldDropdown extends Field<string> {
      * @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.

package/core/field_image.d.ts

@@ -134,7 +134,7 @@ export interface FieldImageConfig extends FieldConfig {
     alt?: string;
 }
 /**
- * fromJson config options for the image field.
+ * fromJson config options for the colour field.
  */
 export interface FieldImageFromJsonConfig extends FieldImageConfig {
     src?: string;

package/core/field_multilineinput.d.ts

@@ -0,0 +1,182 @@
+/**
+ * @license
+ * Copyright 2019 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Field } from './field.js';
+import { FieldTextInput, FieldTextInputConfig, FieldTextInputValidator } from './field_textinput.js';
+/**
+ * Class for an editable text area field.
+ */
+export declare class FieldMultilineInput extends FieldTextInput {
+    /**
+     * The SVG group element that will contain a text element for each text row
+     *     when initialized.
+     */
+    textGroup: SVGGElement | null;
+    /**
+     * Defines the maximum number of lines of field.
+     * If exceeded, scrolling functionality is enabled.
+     */
+    protected maxLines_: number;
+    /** Whether Y overflow is currently occurring. */
+    protected isOverflowedY_: boolean;
+    /**
+     * @param value The initial content 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 An optional function that is called to validate any
+     *     constraints on what the user entered.  Takes the new text as an
+     *     argument and returns either the accepted text, a replacement text, 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/multiline-text-input#creation}
+     * for a list of properties this parameter supports.
+     */
+    constructor(value?: string | typeof Field.SKIP_SETUP, validator?: FieldMultilineInputValidator, config?: FieldMultilineInputConfig);
+    /**
+     * 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: FieldMultilineInputConfig): void;
+    /**
+     * 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.
+     * @internal
+     */
+    toXml(fieldElement: Element): Element;
+    /**
+     * 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;
+    /**
+     * Saves this field's value.
+     * This function only exists for subclasses of FieldMultilineInput which
+     * predate the load/saveState API and only define to/fromXml.
+     *
+     * @returns The state of this field.
+     * @internal
+     */
+    saveState(): any;
+    /**
+     * Sets the field's value based on the given state.
+     * This function only exists for subclasses of FieldMultilineInput which
+     * predate the load/saveState API and only define to/fromXml.
+     *
+     * @param state The state of the variable to assign to this variable field.
+     * @internal
+     */
+    loadState(state: any): void;
+    /**
+     * Create the block UI for this field.
+     */
+    initView(): void;
+    /**
+     * Get the text from this field as displayed on screen.  May differ from
+     * getText due to ellipsis, and other formatting.
+     *
+     * @returns Currently displayed text.
+     */
+    protected getDisplayText_(): string;
+    /**
+     * 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_). Is being redefined here to update
+     * overflow state of the field.
+     *
+     * @param newValue The value to be saved. The default validator guarantees
+     *     that this is a string.
+     */
+    protected doValueUpdate_(newValue: string): void;
+    /** Updates the text of the textElement. */
+    protected render_(): void;
+    /** Updates the size of the field based on the text. */
+    protected updateSize_(): void;
+    /**
+     * Show the inline free-text editor on top of the text.
+     * Overrides the default behaviour to force rerender in order to
+     * correct block size, based on editor text.
+     *
+     * @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.
+     */
+    showEditor_(e?: Event, quietInput?: boolean): void;
+    /**
+     * Create the text input editor widget.
+     *
+     * @returns The newly created text input editor.
+     */
+    protected widgetCreate_(): HTMLTextAreaElement;
+    /**
+     * Sets the maxLines config for this field.
+     *
+     * @param maxLines Defines the maximum number of lines allowed, before
+     *     scrolling functionality is enabled.
+     */
+    setMaxLines(maxLines: number): void;
+    /**
+     * Returns the maxLines config of this field.
+     *
+     * @returns The maxLines config value.
+     */
+    getMaxLines(): number;
+    /**
+     * Handle key down to the editor. Override the text input definition of this
+     * so as to not close the editor when enter is typed in.
+     *
+     * @param e Keyboard event.
+     */
+    protected onHtmlInputKeyDown_(e: KeyboardEvent): void;
+    /**
+     * Construct a FieldMultilineInput from a JSON arg object,
+     * dereferencing any string table references.
+     *
+     * @param options A JSON object with options (text, and spellcheck).
+     * @returns The new field instance.
+     * @nocollapse
+     * @internal
+     */
+    static fromJson(options: FieldMultilineInputFromJsonConfig): FieldMultilineInput;
+}
+/**
+ * Config options for the multiline input field.
+ */
+export interface FieldMultilineInputConfig extends FieldTextInputConfig {
+    maxLines?: number;
+}
+/**
+ * fromJson config options for the multiline input field.
+ */
+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;
+//# sourceMappingURL=field_multilineinput.d.ts.map

package/core/generator.d.ts

@@ -254,7 +254,7 @@ export declare class CodeGenerator {
      * @param _opt_thisOnly True to generate code for only this statement.
      * @returns Code with comments and subsequent blocks added.
      */
-    scrub_(_block: Block, code: string, _opt_thisOnly?: boolean): string;
+    protected scrub_(_block: Block, code: string, _opt_thisOnly?: boolean): string;
     /**
      * Hook for code to run at end of code generation.
      * Subclasses may override this, e.g. to prepend the generated code with

package/core/gesture.d.ts

@@ -86,8 +86,6 @@ export declare class Gesture {
      * is in progress.
      */
     private workspaceDragger;
-    /** Whether the gesture is dragging or not. */
-    private dragging;
     /** The flyout a gesture started in, if any. */
     private flyout;
     /** Boolean for sanity-checking that some code is only called once. */

package/core/grid.d.ts

@@ -31,16 +31,8 @@ export declare class Grid {
      * dropped it will snap to the grid if snapping to the grid is enabled.
      */
     setSpacing(spacing: number): void;
-    /**
-     * Get the spacing of the grid points (in px).
-     *
-     * @returns The spacing of the grid points.
-     */
-    getSpacing(): number;
     /** Sets the length of the grid lines. */
     setLength(length: number): void;
-    /** Get the length of the grid lines (in px). */
-    getLength(): number;
     /**
      * Sets whether blocks should snap to the grid or not.
      *
@@ -51,11 +43,19 @@ export declare class Grid {
      */
     setSnapToGrid(snap: boolean): void;
     /**
-     * Whether blocks should snap to the grid.
+     * Whether blocks should snap to the grid, based on the initial configuration.
      *
      * @returns True if blocks should snap, false otherwise.
+     * @internal
      */
     shouldSnap(): boolean;
+    /**
+     * Get the spacing of the grid points (in px).
+     *
+     * @returns The spacing of the grid points.
+     * @internal
+     */
+    getSpacing(): number;
     /**
      * Get the ID of the pattern element, which should be randomized to avoid
      * conflicts with other Blockly instances on the page.

package/core/icons/comment_icon.d.ts

@@ -16,7 +16,7 @@ import { Size } from '../utils/size.js';
 export declare class CommentIcon extends Icon implements IHasBubble, ISerializable {
     protected readonly sourceBlock: Block;
     /** The type string used to identify this icon. */
-    static readonly TYPE: IconType<import("../interfaces/i_comment_icon.js").ICommentIcon>;
+    static readonly TYPE: IconType<CommentIcon>;
     /**
      * The weight this icon has relative to other icons. Icons with more positive
      * weight values are rendered farther toward the end of the block.
@@ -49,7 +49,7 @@ export declare class CommentIcon extends Icon implements IHasBubble, ISerializab
      * Updates the state of the bubble (editable / noneditable) to reflect the
      * state of the bubble if the bubble is currently shown.
      */
-    updateEditable(): Promise<void>;
+    updateEditable(): void;
     onLocationChange(blockOrigin: Coordinate): void;
     /** Sets the text of this comment. Updates any bubbles if they are visible. */
     setText(text: string): void;
@@ -82,7 +82,7 @@ export declare class CommentIcon extends Icon implements IHasBubble, ISerializab
      */
     onSizeChange(): void;
     bubbleIsVisible(): boolean;
-    setBubbleVisible(visible: boolean): Promise<void>;
+    setBubbleVisible(visible: boolean): void;
     /**
      * Shows the editable text bubble for this comment, and adds change listeners
      * to update the state of this icon in response to changes in the bubble.

package/core/icons/icon.d.ts

@@ -59,5 +59,11 @@ export declare abstract class Icon implements IIcon {
      * @returns Whether the icon should be clickable while the block is in a flyout.
      */
     isClickableInFlyout(autoClosingFlyout: boolean): boolean;
+    /**
+     * Sets the visibility of the icon's bubble if one exists.
+     *
+     * @deprecated Use `setBubbleVisible` instead. To be removed in v11.
+     */
+    setVisible(visibility: boolean): void;
 }
 //# sourceMappingURL=icon.d.ts.map

package/core/icons/icon_types.d.ts

@@ -3,8 +3,8 @@
  * Copyright 2023 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import { ICommentIcon } from '../interfaces/i_comment_icon.js';
 import { IIcon } from '../interfaces/i_icon.js';
+import { CommentIcon } from './comment_icon.js';
 import { MutatorIcon } from './mutator_icon.js';
 import { WarningIcon } from './warning_icon.js';
 /**
@@ -20,6 +20,6 @@ export declare class IconType<_T extends IIcon> {
     equals(type: IconType<IIcon>): boolean;
     static MUTATOR: IconType<MutatorIcon>;
     static WARNING: IconType<WarningIcon>;
-    static COMMENT: IconType<ICommentIcon>;
+    static COMMENT: IconType<CommentIcon>;
 }
 //# sourceMappingURL=icon_types.d.ts.map

package/core/icons/mutator_icon.d.ts

@@ -4,7 +4,9 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import type { Abstract } from '../events/events_abstract.js';
+import type { Block } from '../block.js';
 import type { BlockSvg } from '../block_svg.js';
+import type { Connection } from '../connection.js';
 import { Coordinate } from '../utils/coordinate.js';
 import type { IHasBubble } from '../interfaces/i_has_bubble.js';
 import { Icon } from './icon.js';
@@ -53,7 +55,7 @@ export declare class MutatorIcon extends Icon implements IHasBubble {
     onClick(): void;
     isClickableInFlyout(): boolean;
     bubbleIsVisible(): boolean;
-    setBubbleVisible(visible: boolean): Promise<void>;
+    setBubbleVisible(visible: boolean): void;
     /** @returns the configuration the mini workspace should have. */
     private getMiniWorkspaceConfig;
     /**
@@ -89,5 +91,18 @@ export declare class MutatorIcon extends Icon implements IHasBubble {
      *     currently open.
      */
     getWorkspace(): WorkspaceSvg | undefined;
+    /**
+     * Reconnects the given connection to the mutated input on the given block.
+     *
+     * @deprecated Use connection.reconnect instead. To be removed in v11.
+     */
+    static reconnect(connectionChild: Connection | null, block: Block, inputName: string): boolean;
+    /**
+     * Returns the parent workspace of a workspace that is inside a mini workspace
+     * bubble, taking into account whether the workspace is a flyout.
+     *
+     * @deprecated Use workspace.getRootWorkspace. To be removed in v11.
+     */
+    static findParentWs(workspace: WorkspaceSvg): WorkspaceSvg | null;
 }
 //# sourceMappingURL=mutator_icon.d.ts.map

package/core/icons/warning_icon.d.ts

@@ -59,7 +59,7 @@ export declare class WarningIcon extends Icon implements IHasBubble {
     onClick(): void;
     isClickableInFlyout(): boolean;
     bubbleIsVisible(): boolean;
-    setBubbleVisible(visible: boolean): Promise<void>;
+    setBubbleVisible(visible: boolean): void;
     /**
      * @returns the location the bubble should be anchored to.
      *     I.E. the middle of this icon.

package/core/inputs/input.d.ts

@@ -15,14 +15,13 @@ import type { Connection } from '../connection.js';
 import type { ConnectionType } from '../connection_type.js';
 import type { Field } from '../field.js';
 import { inputTypes } from './input_types.js';
-import { Align } from './align.js';
 /** Class for an input with optional fields. */
 export declare class Input {
     name: string;
     private sourceBlock;
     fieldRow: Field[];
     /** Alignment of input's fields (left, right or centre). */
-    align: Align;
+    align: Input.Align;
     /** Is the input visible? */
     private visible;
     readonly type: inputTypes;
@@ -122,14 +121,6 @@ export declare class Input {
     getShadowDom(): Element | null;
     /** Initialize the fields on this input. */
     init(): void;
-    /**
-     * Initializes the fields on this input for a headless block.
-     *
-     * @internal
-     */
-    initModel(): void;
-    /** Initializes the given field. */
-    private initField;
     /**
      * Sever all links to this input.
      */
@@ -144,4 +135,22 @@ export declare class Input {
      */
     protected makeConnection(type: ConnectionType): Connection;
 }
+export declare namespace Input {
+    /**
+     * Enum for alignment of inputs.
+     *
+     * @deprecated Use Blockly.inputs.Align. To be removed in v11.
+     */
+    enum Align {
+        LEFT = -1,
+        CENTRE = 0,
+        RIGHT = 1
+    }
+}
+/** @deprecated Use Blockly.inputs.Align. To be removed in v11. */
+/** @suppress {deprecated} */
+export type Align = Input.Align;
+/** @deprecated Use Blockly.inputs.Align. To be removed in v11. */
+/** @suppress {deprecated} */
+export declare const Align: typeof Input.Align;
 //# sourceMappingURL=input.d.ts.map

package/core/interfaces/i_has_bubble.d.ts

@@ -7,7 +7,7 @@ export interface IHasBubble {
     /** @returns True if the bubble is currently open, false otherwise. */
     bubbleIsVisible(): boolean;
     /** Sets whether the bubble is open or not. */
-    setBubbleVisible(visible: boolean): Promise<void>;
+    setBubbleVisible(visible: boolean): void;
 }
 /** Type guard that checks whether the given object is a IHasBubble. */
 export declare function hasBubble(obj: any): obj is IHasBubble;