blockly 9.2.1 → 9.3.0

package/core/events/utils.d.ts

@@ -14,196 +14,124 @@ import type { CommentMove } from './events_comment_move.js';
  * Sets whether events should be added to the undo stack.
  *
  * @param newValue True if events should be added to the undo stack.
- * @alias Blockly.Events.utils.setRecordUndo
  */
 export declare function setRecordUndo(newValue: boolean): void;
 /**
  * Returns whether or not events will be added to the undo stack.
  *
  * @returns True if events will be added to the undo stack.
- * @alias Blockly.Events.utils.getRecordUndo
  */
 export declare function getRecordUndo(): boolean;
 /**
  * Name of event that creates a block. Will be deprecated for BLOCK_CREATE.
- *
- * @alias Blockly.Events.utils.CREATE
  */
 export declare const CREATE = "create";
 /**
  * Name of event that creates a block.
- *
- * @alias Blockly.Events.utils.BLOCK_CREATE
  */
 export declare const BLOCK_CREATE = "create";
 /**
  * Name of event that deletes a block. Will be deprecated for BLOCK_DELETE.
- *
- * @alias Blockly.Events.utils.DELETE
  */
 export declare const DELETE = "delete";
 /**
  * Name of event that deletes a block.
- *
- * @alias Blockly.Events.utils.BLOCK_DELETE
  */
 export declare const BLOCK_DELETE = "delete";
 /**
  * Name of event that changes a block. Will be deprecated for BLOCK_CHANGE.
- *
- * @alias Blockly.Events.utils.CHANGE
  */
 export declare const CHANGE = "change";
 /**
  * Name of event that changes a block.
- *
- * @alias Blockly.Events.utils.BLOCK_CHANGE
  */
 export declare const BLOCK_CHANGE = "change";
 /**
  * Name of event that moves a block. Will be deprecated for BLOCK_MOVE.
- *
- * @alias Blockly.Events.utils.MOVE
  */
 export declare const MOVE = "move";
 /**
  * Name of event that moves a block.
- *
- * @alias Blockly.Events.utils.BLOCK_MOVE
  */
 export declare const BLOCK_MOVE = "move";
 /**
  * Name of event that creates a variable.
- *
- * @alias Blockly.Events.utils.VAR_CREATE
  */
 export declare const VAR_CREATE = "var_create";
 /**
  * Name of event that deletes a variable.
- *
- * @alias Blockly.Events.utils.VAR_DELETE
  */
 export declare const VAR_DELETE = "var_delete";
 /**
  * Name of event that renames a variable.
- *
- * @alias Blockly.Events.utils.VAR_RENAME
  */
 export declare const VAR_RENAME = "var_rename";
 /**
  * Name of generic event that records a UI change.
- *
- * @alias Blockly.Events.utils.UI
  */
 export declare const UI = "ui";
 /**
  * Name of event that record a block drags a block.
- *
- * @alias Blockly.Events.utils.BLOCK_DRAG
  */
 export declare const BLOCK_DRAG = "drag";
 /**
  * Name of event that records a change in selected element.
- *
- * @alias Blockly.Events.utils.SELECTED
  */
 export declare const SELECTED = "selected";
 /**
  * Name of event that records a click.
- *
- * @alias Blockly.Events.utils.CLICK
  */
 export declare const CLICK = "click";
 /**
  * Name of event that records a marker move.
- *
- * @alias Blockly.Events.utils.MARKER_MOVE
  */
 export declare const MARKER_MOVE = "marker_move";
 /**
  * Name of event that records a bubble open.
- *
- * @alias Blockly.Events.utils.BUBBLE_OPEN
  */
 export declare const BUBBLE_OPEN = "bubble_open";
 /**
  * Name of event that records a trashcan open.
- *
- * @alias Blockly.Events.utils.TRASHCAN_OPEN
  */
 export declare const TRASHCAN_OPEN = "trashcan_open";
 /**
  * Name of event that records a toolbox item select.
- *
- * @alias Blockly.Events.utils.TOOLBOX_ITEM_SELECT
  */
 export declare const TOOLBOX_ITEM_SELECT = "toolbox_item_select";
 /**
  * Name of event that records a theme change.
- *
- * @alias Blockly.Events.utils.THEME_CHANGE
  */
 export declare const THEME_CHANGE = "theme_change";
 /**
  * Name of event that records a viewport change.
- *
- * @alias Blockly.Events.utils.VIEWPORT_CHANGE
  */
 export declare const VIEWPORT_CHANGE = "viewport_change";
 /**
  * Name of event that creates a comment.
- *
- * @alias Blockly.Events.utils.COMMENT_CREATE
  */
 export declare const COMMENT_CREATE = "comment_create";
 /**
  * Name of event that deletes a comment.
- *
- * @alias Blockly.Events.utils.COMMENT_DELETE
  */
 export declare const COMMENT_DELETE = "comment_delete";
 /**
  * Name of event that changes a comment.
- *
- * @alias Blockly.Events.utils.COMMENT_CHANGE
  */
 export declare const COMMENT_CHANGE = "comment_change";
 /**
  * Name of event that moves a comment.
- *
- * @alias Blockly.Events.utils.COMMENT_MOVE
  */
 export declare const COMMENT_MOVE = "comment_move";
 /**
  * Name of event that records a workspace load.
- *
- * @alias Blockly.Events.utils.FINISHED_LOADING
  */
 export declare const FINISHED_LOADING = "finished_loading";
-/** Name of event that creates a procedure model. */
-export declare const PROCEDURE_CREATE = "procedure_create";
-/** Name of event that deletes a procedure model. */
-export declare const PROCEDURE_DELETE = "procedure_delete";
-/** Name of event that renames a procedure model. */
-export declare const PROCEDURE_RENAME = "procedure_rename";
-/** Name of event that enables/disables a procedure model. */
-export declare const PROCEDURE_ENABLE = "procedure_enable";
-/** Name of event that changes the returntype of a procedure model. */
-export declare const PROCEDURE_CHANGE_RETURN = "procedure_change_return";
-/** Name of event that creates a procedure parameter. */
-export declare const PROCEDURE_PARAMETER_CREATE = "procedure_parameter_create";
-/** Name of event that deletes a procedure parameter. */
-export declare const PROCEDURE_PARAMETER_DELETE = "procedure_parameter_delete";
-/** Name of event that renames a procedure parameter. */
-export declare const PROCEDURE_PARAMETER_RENAME = "procedure_parameter_rename";
 /**
  * Type of events that cause objects to be bumped back into the visible
  * portion of the workspace.
  *
  * Not to be confused with bumping so that disconnected connections do not
  * appear connected.
- *
- * @alias Blockly.Events.utils.BumpEvent
  */
 export type BumpEvent = BlockCreate | BlockMove | CommentCreate | CommentMove;
 /**
@@ -212,15 +140,12 @@ export type BumpEvent = BlockCreate | BlockMove | CommentCreate | CommentMove;
  *
  * Not to be confused with bumping so that disconnected connections do not
  * appear connected.
- *
- * @alias Blockly.Events.utils.BUMP_EVENTS
  */
 export declare const BUMP_EVENTS: string[];
 /**
  * Create a custom event and fire it.
  *
  * @param event Custom data for event.
- * @alias Blockly.Events.utils.fire
  */
 export declare function fire(event: Abstract): void;
 /**
@@ -235,41 +160,32 @@ declare function fireNow(): void;
  * @param queueIn Array of events.
  * @param forward True if forward (redo), false if backward (undo).
  * @returns Array of filtered events.
- * @alias Blockly.Events.utils.filter
  */
 export declare function filter(queueIn: Abstract[], forward: boolean): Abstract[];
 /**
  * Modify pending undo events so that when they are fired they don't land
  * in the undo stack.  Called by Workspace.clearUndo.
- *
- * @alias Blockly.Events.utils.clearPendingUndo
  */
 export declare function clearPendingUndo(): void;
 /**
  * Stop sending events.  Every call to this function MUST also call enable.
- *
- * @alias Blockly.Events.utils.disable
  */
 export declare function disable(): void;
 /**
  * Start sending events.  Unless events were already disabled when the
  * corresponding call to disable was made.
- *
- * @alias Blockly.Events.utils.enable
  */
 export declare function enable(): void;
 /**
  * Returns whether events may be fired or not.
  *
  * @returns True if enabled.
- * @alias Blockly.Events.utils.isEnabled
  */
 export declare function isEnabled(): boolean;
 /**
  * Current group.
  *
  * @returns ID string.
- * @alias Blockly.Events.utils.getGroup
  */
 export declare function getGroup(): string;
 /**
@@ -277,7 +193,6 @@ export declare function getGroup(): string;
  *
  * @param state True to start new group, false to end group.
  *   String to set group explicitly.
- * @alias Blockly.Events.utils.setGroup
  */
 export declare function setGroup(state: boolean | string): void;
 /**
@@ -289,7 +204,6 @@ declare function setGroupInternal(state: boolean | string): void;
  *
  * @param block The root block.
  * @returns List of block IDs.
- * @alias Blockly.Events.utils.getDescendantIds
  * @internal
  */
 export declare function getDescendantIds(block: Block): string[];
@@ -300,7 +214,6 @@ export declare function getDescendantIds(block: Block): string[];
  * @param workspace Target workspace for event.
  * @returns The event represented by the JSON.
  * @throws {Error} if an event type is not found in the registry.
- * @alias Blockly.Events.utils.fromJson
  */
 export declare function fromJson(json: any, workspace: Workspace): Abstract;
 /**
@@ -308,7 +221,6 @@ export declare function fromJson(json: any, workspace: Workspace): Abstract;
  *
  * @param eventType The type of the event to get.
  * @returns The event class with the given type.
- * @alias Blockly.Events.utils.get
  */
 export declare function get(eventType: string): (new (...p1: any[]) => Abstract);
 /**
@@ -318,7 +230,6 @@ export declare function get(eventType: string): (new (...p1: any[]) => Abstract)
  * users don't try to re-enable disabled orphan blocks.
  *
  * @param event Custom data for event.
- * @alias Blockly.Events.utils.disableOrphans
  */
 export declare function disableOrphans(event: Abstract): void;
 export declare const TEST_ONLY: {

package/core/events/workspace_events.d.ts

@@ -6,12 +6,8 @@
 import type { Workspace } from '../workspace.js';
 import { Abstract as AbstractEvent, AbstractEventJson } from './events_abstract.js';
 /**
- * Class for a finished loading event.
- * Used to notify the developer when the workspace has finished loading (i.e
- * domToWorkspace).
- * Finished loading events do not record undo or redo.
- *
- * @alias Blockly.Events.FinishedLoading
+ * Notifies listeners when the workspace has finished deserializing from
+ * JSON/XML.
  */
 export declare class FinishedLoading extends AbstractEvent {
     isBlank: boolean;

package/core/extensions.d.ts

@@ -17,7 +17,6 @@ export declare const TEST_ONLY: {
  * @param initFn The function to initialize an extended block.
  * @throws {Error} if the extension name is empty, the extension is already
  *     registered, or extensionFn is not a function.
- * @alias Blockly.Extensions.register
  */
 export declare function register(name: string, initFn: Function): void;
 /**
@@ -27,7 +26,6 @@ export declare function register(name: string, initFn: Function): void;
  * @param mixinObj The values to mix in.
  * @throws {Error} if the extension name is empty or the extension is already
  *     registered.
- * @alias Blockly.Extensions.registerMixin
  */
 export declare function registerMixin(name: string, mixinObj: any): void;
 /**
@@ -42,14 +40,12 @@ export declare function registerMixin(name: string, mixinObj: any): void;
  * @param opt_blockList A list of blocks to appear in the flyout of the mutator
  *     dialog.
  * @throws {Error} if the mutation is invalid or can't be applied to the block.
- * @alias Blockly.Extensions.registerMutator
  */
 export declare function registerMutator(name: string, mixinObj: any, opt_helperFn?: () => any, opt_blockList?: string[]): void;
 /**
  * Unregisters the extension registered with the given name.
  *
  * @param name The name of the extension to unregister.
- * @alias Blockly.Extensions.unregister
  */
 export declare function unregister(name: string): void;
 /**
@@ -57,7 +53,6 @@ export declare function unregister(name: string): void;
  *
  * @param name The name of the extension to check for.
  * @returns True if the extension is registered.  False if it is not registered.
- * @alias Blockly.Extensions.isRegistered
  */
 export declare function isRegistered(name: string): boolean;
 /**
@@ -68,7 +63,6 @@ export declare function isRegistered(name: string): boolean;
  * @param block The block to apply the named extension to.
  * @param isMutator True if this extension defines a mutator.
  * @throws {Error} if the extension is not found.
- * @alias Blockly.Extensions.apply
  */
 export declare function apply(name: string, block: Block, isMutator: boolean): void;
 /**
@@ -97,7 +91,6 @@ export declare function runAfterPageLoad(fn: () => void): void;
  *     lookup table.
  * @param lookupTable The table of field values to tooltip text.
  * @returns The extension function.
- * @alias Blockly.Extensions.buildTooltipForDropdown
  */
 export declare function buildTooltipForDropdown(dropdownName: string, lookupTable: {
     [key: string]: string;
@@ -111,7 +104,6 @@ export declare function buildTooltipForDropdown(dropdownName: string, lookupTabl
  *     placeholder.
  * @param fieldName The field with the replacement text.
  * @returns The extension function.
- * @alias Blockly.Extensions.buildTooltipWithFieldText
  */
 export declare function buildTooltipWithFieldText(msgTemplate: string, fieldName: string): Function;
 //# sourceMappingURL=extensions.d.ts.map

package/core/field.d.ts

@@ -15,13 +15,27 @@ import type { KeyboardShortcut } from './shortcut_registry.js';
 import * as Tooltip from './tooltip.js';
 import type { Coordinate } from './utils/coordinate.js';
 import { Rect } from './utils/rect.js';
-import { Sentinel } from './utils/sentinel.js';
 import { Size } from './utils/size.js';
-export type FieldValidator<T = any> = (value?: T) => T | null | undefined;
+/**
+ * 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 FieldValidator<T = any> = (newValue: T) => T | null | undefined;
 /**
  * Abstract class for an editable field.
  *
- * @alias Blockly.Field
+ * @typeParam T - The value stored on the field.
  */
 export declare abstract class Field<T = any> implements IASTNodeLocationSvg, IASTNodeLocationWithBlock, IKeyboardAccessible, IRegistrable {
     /**
@@ -41,7 +55,7 @@ export declare abstract class Field<T = any> implements IASTNodeLocationSvg, IAS
      * field's value or run configure_, and should allow a subclass to do that
      * instead.
      */
-    static readonly SKIP_SETUP: Sentinel;
+    static readonly SKIP_SETUP: unique symbol;
     /**
      * Name of field.  Unique within each block.
      * Static labels are usually unnamed.
@@ -128,14 +142,14 @@ export declare abstract class Field<T = any> implements IASTNodeLocationSvg, IAS
      *     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 opt_validator  A function that is called to validate changes to the
+     * @param validator  A function that is called to validate changes to the
      *     field's value. Takes in a value & returns a validated value, or null to
      *     abort the change.
-     * @param opt_config A map of options used to configure the field.
+     * @param config A map of options used to configure the field.
      *    Refer to the individual field's documentation for a list of properties
      * this parameter supports.
      */
-    constructor(value: T | Sentinel, opt_validator?: FieldValidator<T> | null, opt_config?: FieldConfig);
+    constructor(value: T | typeof Field.SKIP_SETUP, validator?: FieldValidator<T> | null, config?: FieldConfig);
     /**
      * Process the configuration map passed to the field.
      *
@@ -336,7 +350,7 @@ export declare abstract class Field<T = any> implements IASTNodeLocationSvg, IAS
      *
      * @returns Validation function, or null.
      */
-    getValidator(): Function | null;
+    getValidator(): FieldValidator<T> | null;
     /**
      * Gets the group element for this editable field.
      * Used for measuring the size and for positioning.
@@ -383,12 +397,12 @@ export declare abstract class Field<T = any> implements IASTNodeLocationSvg, IAS
      * Calls showEditor_ when the field is clicked if the field is clickable.
      * Do not override.
      *
-     * @param opt_e Optional mouse event that triggered the field to open, or
+     * @param e Optional mouse event that triggered the field to open, or
      *     undefined if triggered programmatically.
      * @sealed
      * @internal
      */
-    showEditor(opt_e?: Event): void;
+    showEditor(e?: Event): void;
     /**
      * A developer hook to create an editor for the field. This is no-op by
      * default, and must be overriden to create an editor.
@@ -400,9 +414,9 @@ export declare abstract class Field<T = any> implements IASTNodeLocationSvg, IAS
     /**
      * Updates the size of the field based on the text.
      *
-     * @param opt_margin margin to use when positioning the text element.
+     * @param margin margin to use when positioning the text element.
      */
-    protected updateSize_(opt_margin?: number): void;
+    protected updateSize_(margin?: number): void;
     /**
      * Position a field's text element after a size change.  This handles both LTR
      * and RTL positioning.
@@ -495,22 +509,36 @@ export declare abstract class Field<T = any> implements IASTNodeLocationSvg, IAS
      *
      * @returns Current value.
      */
-    getValue(): any;
+    getValue(): T | null;
     /**
-     * Used to validate a value. Returns input by default. Can be overridden by
-     * subclasses, see FieldDropdown.
+     * Validate the changes to a field's value before they are set. See
+     * **FieldDropdown** for an example of subclass implementation.
+     *
+     * **NOTE:** Validation returns one option between `T`, `null`, and
+     * `undefined`. **Field**'s implementation will never return `undefined`, but
+     * it is valid for a subclass to return `undefined` if the new value is
+     * compatible with `T`.
+     *
+     * @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`.
      *
-     * @param opt_newValue The value to be validated.
-     * @returns The validated value, same as input by default.
+     * - `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.
      */
-    protected doClassValidation_(opt_newValue?: any): any;
+    protected doClassValidation_(newValue: T): T | null | undefined;
+    protected doClassValidation_(newValue?: any): T | null;
     /**
      * Used to update the value of a field. Can be overridden by subclasses to do
      * custom storage of values/updating of external things.
      *
      * @param newValue The value to be saved.
      */
-    protected doValueUpdate_(newValue: any): void;
+    protected doValueUpdate_(newValue: T): void;
     /**
      * Used to notify the field an invalid value was input. Can be overridden by
      * subclasses, see FieldTextInput.
@@ -612,8 +640,12 @@ export declare abstract class Field<T = any> implements IASTNodeLocationSvg, IAS
      * @internal
      */
     setMarkerSvg(markerSvg: SVGElement): void;
-    /** Redraw any attached marker or cursor svgs if needed. */
-    protected updateMarkers_(): void;
+    /**
+     * Redraw any attached marker or cursor svgs if needed.
+     *
+     * @internal
+     */
+    updateMarkers_(): void;
 }
 /**
  * Extra configuration options for the base field.
@@ -624,6 +656,8 @@ export interface FieldConfig {
 /**
  * For use by Field and descendants of Field. Constructors can change
  * in descendants, though they should contain all of Field's prototype methods.
+ *
+ * @internal
  */
 export type FieldProto = Pick<typeof Field, 'prototype'>;
 /**