blockly 9.0.0-beta.3 → 9.0.0

package/core/block_drag_surface.d.ts

@@ -33,7 +33,11 @@ export declare class BlockDragSurfaceSvg {
     private readonly childSurfaceXY_;
     /** @param container Containing element. */
     constructor(container: Element);
-    /** Create the drag surface and inject it into the container. */
+    /**
+     * Create the drag surface and inject it into the container.
+     *
+     * @deprecated The DOM is automatically created by the constructor.
+     */
     createDom(): void;
     /**
      * Set the SVG blocks on the drag surface's group and show the surface.

package/core/blockly.d.ts

@@ -282,22 +282,12 @@ export declare const defineBlocksWithJsonArray: typeof common.defineBlocksWithJs
  * @alias Blockly.setParentContainer
  */
 export declare const setParentContainer: typeof common.setParentContainer;
-/**
- * Returns the dimensions of the specified SVG image.
- *
- * @param svg SVG image.
- * @returns Contains width and height properties.
- * @deprecated Use workspace.setCachedParentSvgSize. (2021 March 5)
- * @see Blockly.WorkspaceSvg.setCachedParentSvgSize
- * @alias Blockly.svgSize
- */
-export declare const svgSize: typeof utils.svgMath.svgSize;
 /**
  * Size the workspace when the contents change.  This also updates
  * scrollbars accordingly.
  *
  * @param workspace The workspace to resize.
- * @deprecated Use workspace.resizeContents. (2021 December)
+ * @deprecated Use **workspace.resizeContents** instead.
  * @see Blockly.WorkspaceSvg.resizeContents
  * @alias Blockly.resizeSvgContents
  */
@@ -307,7 +297,7 @@ export declare const resizeSvgContents: typeof resizeSvgContentsLocal;
  * Copy a block or workspace comment onto the local clipboard.
  *
  * @param toCopy Block or Workspace Comment to be copied.
- * @deprecated Use Blockly.clipboard.copy(). (2021 December)
+ * @deprecated Use **Blockly.clipboard.copy** instead.
  * @see Blockly.clipboard.copy
  * @alias Blockly.copy
  */
@@ -316,7 +306,7 @@ export declare function copy(toCopy: ICopyable): void;
  * Paste a block or workspace comment on to the main workspace.
  *
  * @returns True if the paste was successful, false otherwise.
- * @deprecated Use Blockly.clipboard.paste(). (2021 December)
+ * @deprecated Use **Blockly.clipboard.paste** instead.
  * @see Blockly.clipboard.paste
  * @alias Blockly.paste
  */
@@ -325,7 +315,7 @@ export declare function paste(): boolean;
  * Duplicate this block and its children, or a workspace comment.
  *
  * @param toDuplicate Block or Workspace Comment to be copied.
- * @deprecated Use Blockly.clipboard.duplicate(). (2021 December)
+ * @deprecated Use **Blockly.clipboard.duplicate** instead.
  * @see Blockly.clipboard.duplicate
  * @alias Blockly.duplicate
  */
@@ -335,7 +325,7 @@ export declare function duplicate(toDuplicate: ICopyable): void;
  *
  * @param str Input string.
  * @returns True if number, false otherwise.
- * @deprecated Use Blockly.utils.string.isNumber(str). (2021 December)
+ * @deprecated Use **Blockly.utils.string.isNumber** instead.
  * @see Blockly.utils.string.isNumber
  * @alias Blockly.isNumber
  */
@@ -345,7 +335,7 @@ export declare function isNumber(str: string): boolean;
  *
  * @param hue Hue on a colour wheel (0-360).
  * @returns RGB code, e.g. '#5ba65b'.
- * @deprecated Use Blockly.utils.colour.hueToHex(). (2021 December)
+ * @deprecated Use **Blockly.utils.colour.hueToHex** instead.
  * @see Blockly.utils.colour.hueToHex
  * @alias Blockly.hueToHex
  */
@@ -361,7 +351,7 @@ export declare function hueToHex(hue: number): string;
  * @param thisObject The value of 'this' in the function.
  * @param func Function to call when event is triggered.
  * @returns Opaque data that can be passed to unbindEvent_.
- * @deprecated Use Blockly.browserEvents.bind(). (December 2021)
+ * @deprecated Use **Blockly.browserEvents.bind** instead.
  * @see Blockly.browserEvents.bind
  * @alias Blockly.bindEvent_
  */
@@ -372,7 +362,7 @@ export declare function bindEvent_(node: EventTarget, name: string, thisObject:
  * @param bindData Opaque data from bindEvent_.
  *     This list is emptied during the course of calling this function.
  * @returns The function call.
- * @deprecated Use Blockly.browserEvents.unbind(). (December 2021)
+ * @deprecated Use **Blockly.browserEvents.unbind** instead.
  * @see browserEvents.unbind
  * @alias Blockly.unbindEvent_
  */
@@ -394,7 +384,7 @@ export declare function unbindEvent_(bindData: browserEvents.Data): Function;
  *     the default handler.  False by default.  If opt_noPreventDefault is
  *     provided, opt_noCaptureIdentifier must also be provided.
  * @returns Opaque data that can be passed to unbindEvent_.
- * @deprecated Use Blockly.browserEvents.conditionalBind(). (December 2021)
+ * @deprecated Use **Blockly.browserEvents.conditionalBind** instead.
  * @see browserEvents.conditionalBind
  * @alias Blockly.bindEventWithChecks_
  */

package/core/css.d.ts

@@ -10,7 +10,7 @@
  * @param cssContent Multiline CSS string or an array of single lines of CSS.
  * @alias Blockly.Css.register
  */
-export declare function register(cssContent: string | string[]): void;
+export declare function register(cssContent: string): void;
 /**
  * Inject the CSS into the DOM.  This is preferable over using a regular CSS
  * file since:

package/core/field.d.ts

@@ -38,7 +38,7 @@ export declare abstract class Field implements IASTNodeLocationSvg, IASTNodeLoca
     name?: string;
     protected value_: any;
     /** Validation function called when user edits an editable field. */
-    protected validator_: Function;
+    protected validator_: Function | null;
     /**
      * Used to cache the field's tooltip value if setTooltip is called when the
      * field is not yet initialized. Is *not* guaranteed to be accurate.
@@ -56,17 +56,17 @@ export declare abstract class Field implements IASTNodeLocationSvg, IASTNodeLoca
      */
     private markerSvg_;
     /** The rendered field's SVG group element. */
-    protected fieldGroup_: SVGGElement;
+    protected fieldGroup_: SVGGElement | null;
     /** The rendered field's SVG border element. */
-    protected borderRect_: SVGRectElement;
+    protected borderRect_: SVGRectElement | null;
     /** The rendered field's SVG text element. */
-    protected textElement_: SVGTextElement;
+    protected textElement_: SVGTextElement | null;
     /** The rendered field's text content element. */
-    protected textContent_: Text;
+    protected textContent_: Text | null;
     /** Mouse down event listener data. */
     private mouseDownWrapper_;
     /** Constants associated with the source block's renderer. */
-    protected constants_: ConstantProvider;
+    protected constants_: ConstantProvider | null;
     /**
      * Has this field been disposed of?
      *
@@ -76,7 +76,7 @@ export declare abstract class Field implements IASTNodeLocationSvg, IASTNodeLoca
     /** Maximum characters of text to display before adding an ellipsis. */
     maxDisplayLength: number;
     /** Block this field is attached to.  Starts as null, then set in init. */
-    protected sourceBlock_: Block;
+    protected sourceBlock_: Block | null;
     /** Does this block need to be re-rendered? */
     protected isDirty_: boolean;
     /** Is the field visible, or hidden due to the block being collapsed? */
@@ -86,7 +86,7 @@ export declare abstract class Field implements IASTNodeLocationSvg, IASTNodeLoca
      */
     protected enabled_: boolean;
     /** The element the click handler is bound to. */
-    protected clickTarget_: Element;
+    protected clickTarget_: Element | null;
     /**
      * The prefix field.
      *
@@ -149,6 +149,7 @@ export declare abstract class Field implements IASTNodeLocationSvg, IASTNodeLoca
      * Get the block this field is attached to.
      *
      * @returns The block containing this field.
+     * @throws An error if the source block is not defined.
      */
     getSourceBlock(): Block;
     /**
@@ -234,7 +235,7 @@ export declare abstract class Field implements IASTNodeLocationSvg, IASTNodeLoca
      *     Used to see if `this` has overridden any relevant hooks.
      * @returns The stringified version of the XML state, or null.
      */
-    protected saveLegacyState(callingClass: any): string | null;
+    protected saveLegacyState(callingClass: FieldProto): string | null;
     /**
      * Loads the given state using either the old XML hooks, if they should be
      * used. Returns true to indicate loading has been handled, false otherwise.
@@ -244,7 +245,7 @@ export declare abstract class Field implements IASTNodeLocationSvg, IASTNodeLoca
      * @param state The state to apply to the field.
      * @returns Whether the state was applied or not.
      */
-    loadLegacyState(callingClass: any, state: any): boolean;
+    loadLegacyState(callingClass: FieldProto, state: any): boolean;
     /**
      * Dispose of all DOM objects and events belonging to this editable field.
      *
@@ -331,7 +332,28 @@ export declare abstract class Field implements IASTNodeLocationSvg, IASTNodeLoca
      *
      * @returns The group element.
      */
-    getSvgRoot(): SVGGElement;
+    getSvgRoot(): SVGGElement | null;
+    /**
+     * Gets the border rectangle element.
+     *
+     * @returns The border rectangle element.
+     * @throws An error if the border rectangle element is not defined.
+     */
+    protected getBorderRect(): SVGRectElement;
+    /**
+     * Gets the text element.
+     *
+     * @returns The text element.
+     * @throws An error if the text element is not defined.
+     */
+    protected getTextElement(): SVGTextElement;
+    /**
+     * Gets the text content.
+     *
+     * @returns The text content.
+     * @throws An error if the text content is not defined.
+     */
+    protected getTextContent(): Text;
     /**
      * Updates the field to match the colour/style of the block. Should only be
      * called by BlockSvg.applyColour().
@@ -514,7 +536,7 @@ export declare abstract class Field implements IASTNodeLocationSvg, IASTNodeLoca
      *
      * @returns Element to bind click handler to.
      */
-    protected getClickTarget_(): Element;
+    protected getClickTarget_(): Element | null;
     /**
      * Return the absolute coordinates of the top-left corner of this field.
      * The origin (0,0) is the top-left corner of the page body.
@@ -588,4 +610,9 @@ export declare abstract class Field implements IASTNodeLocationSvg, IASTNodeLoca
 export interface FieldConfig {
     tooltip?: string;
 }
+/**
+ * For use by Field and descendants of Field. Constructors can change
+ * in descendants, though they should contain all of Field's prototype methods.
+ */
+export declare type FieldProto = Pick<typeof Field, 'prototype'>;
 //# sourceMappingURL=field.d.ts.map

package/core/renderers/common/block_rendering.d.ts

@@ -34,15 +34,6 @@ import { RenderInfo } from './info.js';
 import { MarkerSvg } from './marker_svg.js';
 import { PathObject } from './path_object.js';
 import { Renderer } from './renderer.js';
-/**
- * Returns whether the debugger is turned on.
- *
- * @returns Whether the debugger is turned on.
- * @alias Blockly.blockRendering.isDebuggerEnabled
- * @deprecated
- * @internal
- */
-export declare function isDebuggerEnabled(): boolean;
 /**
  * Registers a new renderer.
  *
@@ -58,19 +49,12 @@ export declare function register(name: string, rendererClass: Function): void;
  * @alias Blockly.blockRendering.unregister
  */
 export declare function unregister(name: string): void;
-/**
- * Turn on the blocks debugger.
- *
- * @alias Blockly.blockRendering.startDebugger
- * @deprecated
- * @internal
- */
-export declare function startDebugger(): void;
 /**
  * Turn off the blocks debugger.
  *
  * @alias Blockly.blockRendering.stopDebugger
- * @deprecated
+ * @deprecated Use the debug renderer in **\@blockly/dev-tools** (See {@link
+ *     https://www.npmjs.com/package/@blockly/dev-tools}.)
  * @internal
  */
 export declare function stopDebugger(): void;

package/core/tooltip.d.ts

@@ -114,7 +114,7 @@ export declare function bindMouseEvents(element: Element): void;
  * @param element SVG element onto which tooltip is bound.
  * @alias Blockly.Tooltip.unbindMouseEvents
  */
-export declare function unbindMouseEvents(element: Element): void;
+export declare function unbindMouseEvents(element: Element | null): void;
 /**
  * Dispose of the tooltip.
  *

package/core/utils/object.d.ts

@@ -9,6 +9,7 @@
  * @param childCtor Child class.
  * @param parentCtor Parent class.
  * @suppress {strictMissingProperties} superClass_ is not defined on Function.
+ * @deprecated No longer provided by Blockly.
  * @alias Blockly.utils.object.inherits
  */
 export declare function inherits(childCtor: Function, parentCtor: Function): void;
@@ -17,6 +18,7 @@ export declare function inherits(childCtor: Function, parentCtor: Function): voi
  *
  * @param target Target.
  * @param source Source.
+ * @deprecated Use the built-in **Object.assign** instead.
  * @alias Blockly.utils.object.mixin
  */
 export declare function mixin(target: any, source: any): void;
@@ -34,6 +36,7 @@ export declare function deepMerge(target: any, source: any): any;
  *
  * @param obj Object containing values.
  * @returns Array of values.
+ * @deprecated Use the built-in **Object.values** instead.
  * @alias Blockly.utils.object.values
  */
 export declare function values(obj: any): any[];

package/core/utils/string.d.ts

@@ -11,7 +11,7 @@
  * @param prefix A string to look for at the start of `str`.
  * @returns True if `str` begins with `prefix`.
  * @alias Blockly.utils.string.startsWith
- * @deprecated April 2022. Use built-in string.startsWith.
+ * @deprecated Use built-in **string.startsWith** instead.
  */
 export declare function startsWith(str: string, prefix: string): boolean;
 /**

package/core/utils/style.d.ts

@@ -41,6 +41,7 @@ export declare function getComputedStyle(element: Element, property: string): st
  * @param element Element to get style of.
  * @param style Property to get (camel-case).
  * @returns Style value.
+ * @deprecated No longer provided by Blockly.
  * @alias Blockly.utils.style.getCascadedStyle
  */
 export declare function getCascadedStyle(element: Element, style: string): string;

package/core/utils/svg_math.d.ts

@@ -6,7 +6,6 @@
 import type { WorkspaceSvg } from '../workspace_svg.js';
 import { Coordinate } from './coordinate.js';
 import { Rect } from './rect.js';
-import { Size } from './size.js';
 /**
  * Return the coordinates of the top-left corner of this element relative to
  * its parent.  Only for SVG elements and children (e.g. rect, g, path).
@@ -31,6 +30,7 @@ export declare function getInjectionDivXY(element: Element): Coordinate;
  * and attempting to set the property.
  *
  * @returns True if 3D transforms are supported.
+ * @deprecated No longer provided by Blockly.
  * @alias Blockly.utils.svgMath.is3dSupported
  */
 export declare function is3dSupported(): boolean;
@@ -62,15 +62,6 @@ export declare function getDocumentScroll(): Coordinate;
  * @alias Blockly.utils.svgMath.screenToWsCoordinates
  */
 export declare function screenToWsCoordinates(ws: WorkspaceSvg, screenCoordinates: Coordinate): Coordinate;
-/**
- * Returns the dimensions of the specified SVG image.
- *
- * @param svg SVG image.
- * @returns Contains width and height properties.
- * @deprecated Use workspace.getCachedParentSvgSize. (2021 March 5)
- * @alias Blockly.utils.svgMath.svgSize
- */
-export declare function svgSize(svg: SVGElement): Size;
 export declare const TEST_ONLY: {
     XY_REGEX: RegExp;
     XY_STYLE_REGEX: RegExp;

package/core/utils.d.ts

@@ -30,30 +30,13 @@ import * as userAgent from './utils/useragent.js';
 import * as xml from './utils/xml.js';
 import type { WorkspaceSvg } from './workspace_svg.js';
 export { aria, arrayUtils as array, browserEvents, colour, Coordinate, deprecation, dom, extensions, idGenerator, KeyCodes, math, Metrics, object, parsing, Rect, Size, stringUtils as string, style, Svg, svgMath, svgPaths, toolbox, userAgent, xml, };
-/**
- * Halts the propagation of the event without doing anything else.
- *
- * @param e An event.
- * @deprecated
- * @alias Blockly.utils.noEvent
- */
-export declare function noEvent(e: Event): void;
-/**
- * Returns true if this event is targeting a text input widget?
- *
- * @param e An event.
- * @returns True if text input.
- * @deprecated Use Blockly.browserEvents.isTargetInput instead.
- * @alias Blockly.utils.isTargetInput
- */
-export declare function isTargetInput(e: Event): boolean;
 /**
  * Return the coordinates of the top-left corner of this element relative to
  * its parent.  Only for SVG elements and children (e.g. rect, g, path).
  *
  * @param element SVG element to find the coordinates of.
  * @returns Object with .x and .y properties.
- * @deprecated
+ * @deprecated Use **Blockly.utils.svgMath.getRelativeXY** instead.
  * @alias Blockly.utils.getRelativeXY
  */
 export declare function getRelativeXY(element: Element): Coordinate;
@@ -64,44 +47,11 @@ export declare function getRelativeXY(element: Element): Coordinate;
  * @param element SVG element to find the coordinates of. If this is not a child
  *     of the div Blockly was injected into, the behaviour is undefined.
  * @returns Object with .x and .y properties.
- * @deprecated
+ * @deprecated Use **Blockly.utils.svgMath.getInjectionDivXY** instead.
  * @alias Blockly.utils.getInjectionDivXY_
  */
 declare function getInjectionDivXY(element: Element): Coordinate;
 export declare const getInjectionDivXY_: typeof getInjectionDivXY;
-/**
- * Returns true this event is a right-click.
- *
- * @param e Mouse event.
- * @returns True if right-click.
- * @deprecated Use Blockly.browserEvents.isRightButton instead.
- * @alias Blockly.utils.isRightButton
- */
-export declare function isRightButton(e: Event): boolean;
-/**
- * Returns the converted coordinates of the given mouse event.
- * The origin (0,0) is the top-left corner of the Blockly SVG.
- *
- * @param e Mouse event.
- * @param svg SVG element.
- * @param matrix Inverted screen CTM to use.
- * @returns Object with .x and .y properties.
- * @deprecated Use Blockly.browserEvents.mouseToSvg instead;
- * @alias Blockly.utils.mouseToSvg
- */
-export declare function mouseToSvg(e: Event, svg: SVGSVGElement, matrix: SVGMatrix | null): SVGPoint;
-/**
- * Returns the scroll delta of a mouse event in pixel units.
- *
- * @param e Mouse event.
- * @returns Scroll delta object with .x and .y properties.
- * @deprecated Use Blockly.browserEvents.getScrollDeltaPixels instead.
- * @alias Blockly.utils.getScrollDeltaPixels
- */
-export declare function getScrollDeltaPixels(e: WheelEvent): {
-    x: number;
-    y: number;
-};
 /**
  * Parse a string with any number of interpolation tokens (%1, %2, ...).
  * It will also replace string table references (e.g., %{bky_my_msg} and
@@ -112,7 +62,7 @@ export declare function getScrollDeltaPixels(e: WheelEvent): {
  * @param message Text which might contain string table references and
  *     interpolation tokens.
  * @returns Array of strings and numbers.
- * @deprecated
+ * @deprecated Use **Blockly.utils.parsing.tokenizeInterpolation** instead.
  * @alias Blockly.utils.tokenizeInterpolation
  */
 export declare function tokenizeInterpolation(message: string): Array<string | number>;
@@ -124,7 +74,7 @@ export declare function tokenizeInterpolation(message: string): Array<string | n
  * @param message Message, which may be a string that contains string table
  *     references.
  * @returns String with message references replaced.
- * @deprecated
+ * @deprecated Use **Blockly.utils.parsing.replaceMessageReferences** instead.
  * @alias Blockly.utils.replaceMessageReferences
  */
 export declare function replaceMessageReferences(message: string | any): string;
@@ -135,24 +85,16 @@ export declare function replaceMessageReferences(message: string | any): string;
  * @param message Text which might contain string table references.
  * @returns True if all message references have matching values.
  *     Otherwise, false.
- * @deprecated
+ * @deprecated Use **Blockly.utils.parsing.checkMessageReferences** instead.
  * @alias Blockly.utils.checkMessageReferences
  */
 export declare function checkMessageReferences(message: string): boolean;
-/**
- * Generate a unique ID.
- *
- * @returns A globally unique ID string.
- * @deprecated Use Blockly.utils.idGenerator.genUid instead.
- * @alias Blockly.utils.genUid
- */
-export declare function genUid(): string;
 /**
  * Check if 3D transforms are supported by adding an element
  * and attempting to set the property.
  *
  * @returns True if 3D transforms are supported.
- * @deprecated
+ * @deprecated Use **Blockly.utils.svgMath.is3dSupported** instead.
  * @alias Blockly.utils.is3dSupported
  */
 export declare function is3dSupported(): boolean;
@@ -163,7 +105,7 @@ export declare function is3dSupported(): boolean;
  * @returns An object containing window width, height, and scroll position in
  *     window coordinates.
  * @alias Blockly.utils.getViewportBBox
- * @deprecated
+ * @deprecated Use **Blockly.utils.svgMath.getViewportBBox** instead.
  * @internal
  */
 export declare function getViewportBBox(): Rect;
@@ -174,7 +116,7 @@ export declare function getViewportBBox(): Rect;
  * @param value Value to remove.
  * @returns True if an element was removed.
  * @alias Blockly.utils.arrayRemove
- * @deprecated
+ * @deprecated Use **Blockly.array.removeElem** instead.
  * @internal
  */
 export declare function arrayRemove<T>(arr: Array<T>, value: T): boolean;
@@ -183,7 +125,7 @@ export declare function arrayRemove<T>(arr: Array<T>, value: T): boolean;
  * Copied from Closure's goog.dom.getDocumentScroll.
  *
  * @returns Object with values 'x' and 'y'.
- * @deprecated
+ * @deprecated Use **Blockly.utils.svgMath.getDocumentScroll** instead.
  * @alias Blockly.utils.getDocumentScroll
  */
 export declare function getDocumentScroll(): Coordinate;
@@ -195,7 +137,7 @@ export declare function getDocumentScroll(): Coordinate;
  * @param opt_stripFollowing Optionally ignore all following statements (blocks
  *     that are not inside a value or statement input of the block).
  * @returns Map of types to type counts for descendants of the bock.
- * @deprecated
+ * @deprecated Use **Blockly.common.getBlockTypeCounts** instead.
  * @alias Blockly.utils.getBlockTypeCounts
  */
 export declare function getBlockTypeCounts(block: Block, opt_stripFollowing?: boolean): {
@@ -207,7 +149,7 @@ export declare function getBlockTypeCounts(block: Block, opt_stripFollowing?: bo
  * @param ws The workspace to find the coordinates on.
  * @param screenCoordinates The screen coordinates to be converted to workspace
  *     coordinates
- * @deprecated
+ * @deprecated Use **Blockly.utils.svgMath.screenToWsCoordinates** instead.
  * @returns The workspace coordinates.
  */
 export declare function screenToWsCoordinates(ws: WorkspaceSvg, screenCoordinates: Coordinate): Coordinate;
@@ -220,7 +162,7 @@ export declare function screenToWsCoordinates(ws: WorkspaceSvg, screenCoordinate
  * @returns An object containing the colour as a #RRGGBB string, and the hue if
  *     the input was an HSV hue value.
  * @throws {Error} If the colour cannot be parsed.
- * @deprecated
+ * @deprecated Use **Blockly.utils.parsing.parseBlockColour** instead.
  * @alias Blockly.utils.parseBlockColour
  */
 export declare function parseBlockColour(colour: number | string): {
@@ -232,7 +174,7 @@ export declare function parseBlockColour(colour: number | string): {
  *
  * @param fn Function to run.
  * @throws Error Will throw if no global document can be found (e.g., Node.js).
- * @deprecated
+ * @deprecated No longer provided by Blockly.
  * @alias Blockly.utils.runAfterPageLoad
  */
 export declare function runAfterPageLoad(fn: () => void): void;

package/core/workspace_svg.d.ts

@@ -658,12 +658,6 @@ export declare class WorkspaceSvg extends Workspace implements IASTNodeLocationS
      * @returns The newly created variable.
      */
     createVariable(name: string, opt_type?: string | null, opt_id?: string | null): VariableModel;
-    /**
-     * Make a list of all the delete areas for this workspace.
-     *
-     * @deprecated Use workspace.recordDragTargets. (2021 June)
-     */
-    recordDeleteAreas(): void;
     /** Make a list of all the delete areas for this workspace. */
     recordDragTargets(): void;
     /**