blockly 9.3.0-beta.0 → 9.3.1

package/core/events/utils.d.ts

@@ -14,170 +14,116 @@ 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";
 /**
@@ -186,8 +132,6 @@ export declare const FINISHED_LOADING = "finished_loading";
  *
  * 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;
 /**
@@ -196,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;
 /**
@@ -219,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;
 /**
@@ -261,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;
 /**
@@ -273,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[];
@@ -284,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;
 /**
@@ -292,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);
 /**
@@ -302,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

@@ -8,8 +8,6 @@ import { Abstract as AbstractEvent, AbstractEventJson } from './events_abstract.
 /**
  * Notifies listeners when the workspace has finished deserializing from
  * JSON/XML.
- *
- * @alias Blockly.Events.FinishedLoading
  */
 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,14 +15,11 @@ 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';
 /**
  * A function that is called to validate changes to the field's value before
  * they are set.
  *
- * **NOTE:** Validation returns one option between `T`, `null`, and `undefined`.
- *
  * @see {@link https://developers.google.com/blockly/guides/create-custom-blocks/fields/validators#return_values}
  * @param newValue The value to be validated.
  * @returns One of three instructions for setting the new value: `T`, `null`,
@@ -38,7 +35,6 @@ 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 {
@@ -59,8 +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 isSentinel<T>(value: T | Sentinel): value is Sentinel;
+    static readonly SKIP_SETUP: unique symbol;
     /**
      * Name of field.  Unique within each block.
      * Static labels are usually unnamed.
@@ -147,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.
      *
@@ -402,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.
@@ -419,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.
@@ -645,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.
@@ -657,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'>;
 /**

package/core/field_angle.d.ts

@@ -3,22 +3,19 @@
  * Copyright 2013 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
+import { Field } from './field.js';
 import { FieldInput, FieldInputConfig, FieldInputValidator } from './field_input.js';
-import type { Sentinel } from './utils/sentinel.js';
-export type FieldAngleValidator = FieldInputValidator<number>;
 /**
  * Class for an editable angle field.
- *
- * @alias Blockly.FieldAngle
  */
 export declare class FieldAngle extends FieldInput<number> {
-    /**
-     * The default amount to round angles to when using a mouse or keyboard nav
-     * input. Must be a positive integer to support keyboard navigation.
-     */
-    static readonly ROUND = 15;
     /** Half the width of protractor image. */
     static readonly HALF: number;
+    /**
+     * Radius of protractor circle.  Slightly smaller than protractor size since
+     * otherwise SVG crops off half the border at the edges.
+     */
+    static readonly RADIUS: number;
     /**
      * Default property describing which direction makes an angle field's value
      * increase. Angle increases clockwise (true) or counterclockwise (false).
@@ -36,60 +33,53 @@ export declare class FieldAngle extends FieldInput<number> {
      */
     static readonly WRAP = 360;
     /**
-     * Radius of protractor circle.  Slightly smaller than protractor size since
-     * otherwise SVG crops off half the border at the edges.
+     * The default amount to round angles to when using a mouse or keyboard nav
+     * input. Must be a positive integer to support keyboard navigation.
      */
-    static readonly RADIUS: number;
+    static readonly ROUND = 15;
     /**
      * Whether the angle should increase as the angle picker is moved clockwise
      * (true) or counterclockwise (false).
      */
-    private clockwise_;
+    private clockwise;
     /**
      * The offset of zero degrees (and all other angles).
      */
-    private offset_;
+    private offset;
     /**
      * The maximum angle to allow before wrapping.
      */
-    private wrap_;
+    private wrap;
     /**
      * The amount to round angles to when using a mouse or keyboard nav input.
      */
-    private round_;
-    /** The angle picker's SVG element. */
-    private editor_;
-    /** The angle picker's gauge path depending on the value. */
-    gauge_: SVGPathElement | null;
-    /** The angle picker's line drawn representing the value's angle. */
-    line_: SVGLineElement | null;
-    /** The degree symbol for this field. */
-    protected symbol_: SVGTSpanElement;
-    /** Wrapper click event data. */
-    private clickWrapper_;
-    /** Surface click event data. */
-    private clickSurfaceWrapper_;
-    /** Surface mouse move event data. */
-    private moveSurfaceWrapper_;
+    private round;
     /**
-     * Serializable fields are saved by the serializer, non-serializable fields
-     * are not. Editable fields should also be serializable.
+     * Array holding info needed to unbind events.
+     * Used for disposing.
+     * Ex: [[node, name, func], [node, name, func]].
      */
-    SERIALIZABLE: boolean;
+    private boundEvents;
+    /** Dynamic red line pointing at the value's angle. */
+    private line;
+    /** Dynamic pink area extending from 0 to the value's angle. */
+    private gauge;
+    /** The degree symbol for this field. */
+    protected symbol_: SVGTSpanElement | null;
     /**
-     * @param opt_value The initial value of the field. Should cast to a number.
+     * @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 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 number & returns a validated number, 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.
      *     See the [field creation documentation]{@link
      * https://developers.google.com/blockly/guides/create-custom-blocks/fields/built-in-fields/angle#creation}
      * for a list of properties this parameter supports.
      */
-    constructor(opt_value?: string | number | Sentinel, opt_validator?: FieldAngleValidator, opt_config?: FieldAngleConfig);
+    constructor(value?: string | number | typeof Field.SKIP_SETUP, validator?: FieldAngleValidator, config?: FieldAngleConfig);
     /**
      * Configure the field based on the given map of options.
      *
@@ -102,21 +92,25 @@ export declare class FieldAngle extends FieldInput<number> {
      * @internal
      */
     initView(): void;
-    /** Updates the graph when the field rerenders. */
+    /** Updates the angle when the field rerenders. */
     protected render_(): void;
     /**
      * Create and show the angle field's editor.
      *
-     * @param opt_e Optional mouse event that triggered the field to open, or
-     *     undefined if triggered programmatically.
+     * @param e Optional mouse event that triggered the field to open,
+     *     or undefined if triggered programmatically.
+     */
+    protected showEditor_(e?: Event): void;
+    /**
+     * Creates the angle dropdown editor.
+     *
+     * @returns The newly created slider.
      */
-    protected showEditor_(opt_e?: Event): void;
-    /** Create the angle dropdown editor. */
-    private dropdownCreate_;
+    private dropdownCreate;
     /** Disposes of events and DOM-references belonging to the angle editor. */
-    private dropdownDispose_;
+    private dropdownDispose;
     /** Hide the editor. */
-    private hide_;
+    private hide;
     /**
      * Set the angle to match the mouse's position.
      *
@@ -130,9 +124,9 @@ export declare class FieldAngle extends FieldInput<number> {
      *
      * @param angle New angle.
      */
-    private displayMouseOrKeyboardValue_;
+    private displayMouseOrKeyboardValue;
     /** Redraw the graph with the current angle. */
-    private updateGraph_;
+    private updateGraph;
     /**
      * Handle key down to the editor.
      *
@@ -142,17 +136,17 @@ export declare class FieldAngle extends FieldInput<number> {
     /**
      * Ensure that the input value is a valid angle.
      *
-     * @param opt_newValue The input value.
+     * @param newValue The input value.
      * @returns A valid angle, or null if invalid.
      */
-    protected doClassValidation_(opt_newValue?: any): number | null;
+    protected doClassValidation_(newValue?: any): number | null;
     /**
      * Wraps the value so that it is in the range (-360 + wrap, wrap).
      *
      * @param value The value to wrap.
      * @returns The wrapped value.
      */
-    private wrapValue_;
+    private wrapValue;
     /**
      * Construct a FieldAngle from a JSON arg object.
      *
@@ -197,4 +191,20 @@ export interface FieldAngleConfig extends FieldInputConfig {
 export interface FieldAngleFromJsonConfig extends FieldAngleConfig {
     angle?: number;
 }
+/**
+ * A function that is called to validate changes to the field's value before
+ * they are set.
+ *
+ * @see {@link https://developers.google.com/blockly/guides/create-custom-blocks/fields/validators#return_values}
+ * @param newValue The value to be validated.
+ * @returns One of three instructions for setting the new value: `T`, `null`,
+ * or `undefined`.
+ *
+ * - `T` to set this function's returned value instead of `newValue`.
+ *
+ * - `null` to invoke `doValueInvalid_` and not set a value.
+ *
+ * - `undefined` to set `newValue` as is.
+ */
+export type FieldAngleValidator = FieldInputValidator<number>;
 //# sourceMappingURL=field_angle.d.ts.map