blockly 12.4.0 → 12.4.1

package/core/utils/dom.d.ts

@@ -0,0 +1,154 @@
+/**
+ * @license
+ * Copyright 2019 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { Svg } from './svg.js';
+/**
+ * Required name space for SVG elements.
+ */
+export declare const SVG_NS = "http://www.w3.org/2000/svg";
+/**
+ * Required name space for HTML elements.
+ */
+export declare const HTML_NS = "http://www.w3.org/1999/xhtml";
+/**
+ * Required name space for XLINK elements.
+ */
+export declare const XLINK_NS = "http://www.w3.org/1999/xlink";
+/**
+ * Node type constants.
+ * https://developer.mozilla.org/en-US/docs/Web/API/Node/nodeType
+ */
+export declare enum NodeType {
+    ELEMENT_NODE = 1,
+    TEXT_NODE = 3,
+    COMMENT_NODE = 8
+}
+/**
+ * Helper method for creating SVG elements.
+ *
+ * @param name Element's tag name.
+ * @param attrs Dictionary of attribute names and values.
+ * @param opt_parent Optional parent on which to append the element.
+ * @returns if name is a string or a more specific type if it a member of Svg.
+ */
+export declare function createSvgElement<T extends SVGElement>(name: string | Svg<T>, attrs: {
+    [key: string]: string | number;
+}, opt_parent?: Element | null): T;
+/**
+ * Add a CSS class to a element.
+ *
+ * Handles multiple space-separated classes for legacy reasons.
+ *
+ * @param element DOM element to add class to.
+ * @param className Name of class to add.
+ * @returns True if class was added, false if already present.
+ */
+export declare function addClass(element: Element, className: string): boolean;
+/**
+ * Removes multiple classes from an element.
+ *
+ * @param element DOM element to remove classes from.
+ * @param classNames A string of one or multiple class names for an element.
+ */
+export declare function removeClasses(element: Element, classNames: string): void;
+/**
+ * Remove a CSS class from a element.
+ *
+ * Handles multiple space-separated classes for legacy reasons.
+ *
+ * @param element DOM element to remove class from.
+ * @param className Name of class to remove.
+ * @returns True if class was removed, false if never present.
+ */
+export declare function removeClass(element: Element, className: string): boolean;
+/**
+ * Checks if an element has the specified CSS class.
+ *
+ * @param element DOM element to check.
+ * @param className Name of class to check.
+ * @returns True if class exists, false otherwise.
+ */
+export declare function hasClass(element: Element, className: string): boolean;
+/**
+ * Removes a node from its parent. No-op if not attached to a parent.
+ *
+ * @param node The node to remove.
+ * @returns The node removed if removed; else, null.
+ */
+export declare function removeNode(node: Node | null): Node | null;
+/**
+ * Insert a node after a reference node.
+ * Contrast with node.insertBefore function.
+ *
+ * @param newNode New element to insert.
+ * @param refNode Existing element to precede new node.
+ */
+export declare function insertAfter(newNode: Element, refNode: Element): void;
+/**
+ * Sets the CSS transform property on an element. This function sets the
+ * non-vendor-prefixed and vendor-prefixed versions for backwards compatibility
+ * with older browsers. See https://caniuse.com/#feat=transforms2d
+ *
+ * @param element Element to which the CSS transform will be applied.
+ * @param transform The value of the CSS `transform` property.
+ */
+export declare function setCssTransform(element: HTMLElement | SVGElement, transform: string): void;
+/**
+ * Start caching text widths. Every call to this function MUST also call
+ * stopTextWidthCache. Caches must not survive between execution threads.
+ */
+export declare function startTextWidthCache(): void;
+/**
+ * Stop caching field widths. Unless caching was already on when the
+ * corresponding call to startTextWidthCache was made.
+ */
+export declare function stopTextWidthCache(): void;
+/**
+ * Gets the width of a text element, caching it in the process.
+ *
+ * @param textElement An SVG 'text' element.
+ * @returns Width of element.
+ */
+export declare function getTextWidth(textElement: SVGTextElement): number;
+/**
+ * Gets the width of a text element using a faster method than `getTextWidth`.
+ * This method requires that we know the text element's font family and size in
+ * advance. Similar to `getTextWidth`, we cache the width we compute.
+ *
+ * @param textElement An SVG 'text' element.
+ * @param fontSize The font size to use.
+ * @param fontWeight The font weight to use.
+ * @param fontFamily The font family to use.
+ * @returns Width of element.
+ */
+export declare function getFastTextWidth(textElement: SVGTextElement, fontSize: number, fontWeight: string, fontFamily: string): number;
+/**
+ * Gets the width of a text element using a faster method than `getTextWidth`.
+ * This method requires that we know the text element's font family and size in
+ * advance. Similar to `getTextWidth`, we cache the width we compute.
+ * This method is similar to `getFastTextWidth` but expects the font size
+ * parameter to be a string.
+ *
+ * @param textElement An SVG 'text' element.
+ * @param fontSize The font size to use.
+ * @param fontWeight The font weight to use.
+ * @param fontFamily The font family to use.
+ * @returns Width of element.
+ */
+export declare function getFastTextWidthWithSizeString(textElement: SVGTextElement, fontSize: string, fontWeight: string, fontFamily: string): number;
+/**
+ * Measure a font's metrics. The height and baseline values.
+ *
+ * @param text Text to measure the font dimensions of.
+ * @param fontSize The font size to use.
+ * @param fontWeight The font weight to use.
+ * @param fontFamily The font family to use.
+ * @returns Font measurements.
+ */
+export declare function measureFontMetrics(text: string, fontSize: string, fontWeight: string, fontFamily: string): {
+    height: number;
+    baseline: number;
+};
+//# sourceMappingURL=dom.d.ts.map

package/core/utils/drag.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @license
+ * Copyright 2024 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { WorkspaceSvg } from '../workspace_svg.js';
+import { Coordinate } from './coordinate.js';
+/**
+ * Start tracking a drag of an object on this workspace by recording the offset
+ * between the pointer's current location and the object's starting location.
+ *
+ * Used for resizing block comments and workspace comments.
+ *
+ * @param workspace The workspace where the drag is occurring.
+ * @param e Pointer down event.
+ * @param xy Starting location of object.
+ */
+export declare function start(workspace: WorkspaceSvg, e: PointerEvent, xy: Coordinate): void;
+/**
+ * Compute the new position of a dragged object in this workspace based on the
+ * current pointer position and the offset between the pointer's starting
+ * location and the object's starting location.
+ *
+ * The start function should have be called previously, when the drag started.
+ *
+ * Used for resizing block comments and workspace comments.
+ *
+ * @param workspace The workspace where the drag is occurring.
+ * @param e Pointer move event.
+ * @returns New location of object.
+ */
+export declare function move(workspace: WorkspaceSvg, e: PointerEvent): Coordinate;
+//# sourceMappingURL=drag.d.ts.map

package/core/utils/focusable_tree_traverser.d.ts

@@ -0,0 +1,53 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { IFocusableNode } from '../interfaces/i_focusable_node.js';
+import type { IFocusableTree } from '../interfaces/i_focusable_tree.js';
+/**
+ * A helper utility for IFocusableTree implementations to aid with common
+ * tree traversals.
+ */
+export declare class FocusableTreeTraverser {
+    private static readonly ACTIVE_CLASS_NAME;
+    private static readonly PASSIVE_CSS_CLASS_NAME;
+    private static readonly ACTIVE_FOCUS_NODE_CSS_SELECTOR;
+    private static readonly PASSIVE_FOCUS_NODE_CSS_SELECTOR;
+    /**
+     * Returns the current IFocusableNode that is styled (and thus represented) as
+     * having either passive or active focus, only considering HTML and SVG
+     * elements.
+     *
+     * This can match against the tree's root.
+     *
+     * Note that this will never return a node from a nested sub-tree as that tree
+     * should specifically be used to retrieve its focused node.
+     *
+     * @param tree The IFocusableTree in which to search for a focused node.
+     * @returns The IFocusableNode currently with focus, or null if none.
+     */
+    static findFocusedNode(tree: IFocusableTree): IFocusableNode | null;
+    /**
+     * Returns the IFocusableNode corresponding to the specified HTML or SVG
+     * element iff it's the root element or a descendent of the root element of
+     * the specified IFocusableTree.
+     *
+     * If the element exists within the specified tree's DOM structure but does
+     * not directly correspond to a node, the nearest parent node (or the tree's
+     * root) will be returned to represent the provided element.
+     *
+     * If the tree contains another nested IFocusableTree, the nested tree may be
+     * traversed but its nodes will never be returned here per the contract of
+     * IFocusableTree.lookUpFocusableNode.
+     *
+     * The provided element must have a non-null, non-empty ID that conforms to
+     * the contract mentioned in IFocusableNode.
+     *
+     * @param element The HTML or SVG element being sought.
+     * @param tree The tree under which the provided element may be a descendant.
+     * @returns The matching IFocusableNode, or null if there is no match.
+     */
+    static findFocusableNodeFor(element: HTMLElement | SVGElement, tree: IFocusableTree): IFocusableNode | null;
+}
+//# sourceMappingURL=focusable_tree_traverser.d.ts.map

package/core/utils/idgenerator.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @license
+ * Copyright 2019 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export declare const TEST_ONLY: {
+    /**
+     * Generate a random unique ID.  This should be globally unique.
+     * 87 characters ^ 20 length is greater than 128 bits (better than a UUID).
+     *
+     * @returns A globally unique ID string.
+     */
+    genUid: () => string;
+};
+/**
+ * Generate the next unique element IDs.
+ * IDs are compatible with the HTML4 'id' attribute restrictions:
+ * Use only ASCII letters, digits, '_', '-' and '.'
+ *
+ * For UUIDs use genUid (below) instead; this ID generator should
+ * primarily be used for IDs that end up in the DOM.
+ *
+ * @returns The next unique identifier.
+ */
+export declare function getNextUniqueId(): string;
+/**
+ * Generate a random unique ID.
+ *
+ * @see internal.genUid
+ * @returns A globally unique ID string.
+ */
+export declare function genUid(): string;
+//# sourceMappingURL=idgenerator.d.ts.map

package/core/utils/keycodes.d.ts

@@ -0,0 +1,136 @@
+/**
+ * @license
+ * Copyright 2019 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Key codes for common characters.
+ *
+ * Copied from Closure's goog.events.KeyCodes
+ *
+ * This list is not localized and therefore some of the key codes are not
+ * correct for non US keyboard layouts. See comments below.
+ */
+export declare enum KeyCodes {
+    WIN_KEY_FF_LINUX = 0,
+    MAC_ENTER = 3,
+    BACKSPACE = 8,
+    TAB = 9,
+    NUM_CENTER = 12,// NUMLOCK on FF/Safari Mac
+    ENTER = 13,
+    SHIFT = 16,
+    CTRL = 17,
+    ALT = 18,
+    PAUSE = 19,
+    CAPS_LOCK = 20,
+    ESC = 27,
+    SPACE = 32,
+    PAGE_UP = 33,// also NUM_NORTH_EAST
+    PAGE_DOWN = 34,// also NUM_SOUTH_EAST
+    END = 35,// also NUM_SOUTH_WEST
+    HOME = 36,// also NUM_NORTH_WEST
+    LEFT = 37,// also NUM_WEST
+    UP = 38,// also NUM_NORTH
+    RIGHT = 39,// also NUM_EAST
+    DOWN = 40,// also NUM_SOUTH
+    PLUS_SIGN = 43,// NOT numpad plus
+    PRINT_SCREEN = 44,
+    INSERT = 45,// also NUM_INSERT
+    DELETE = 46,// also NUM_DELETE
+    ZERO = 48,
+    ONE = 49,
+    TWO = 50,
+    THREE = 51,
+    FOUR = 52,
+    FIVE = 53,
+    SIX = 54,
+    SEVEN = 55,
+    EIGHT = 56,
+    NINE = 57,
+    FF_SEMICOLON = 59,// Firefox (Gecko) fires this for semicolon instead of 186
+    FF_EQUALS = 61,// Firefox (Gecko) fires this for equals instead of 187
+    FF_DASH = 173,// Firefox (Gecko) fires this for dash instead of 189
+    FF_HASH = 163,
+    QUESTION_MARK = 63,// needs localization
+    AT_SIGN = 64,
+    A = 65,
+    B = 66,
+    C = 67,
+    D = 68,
+    E = 69,
+    F = 70,
+    G = 71,
+    H = 72,
+    I = 73,
+    J = 74,
+    K = 75,
+    L = 76,
+    M = 77,
+    N = 78,
+    O = 79,
+    P = 80,
+    Q = 81,
+    R = 82,
+    S = 83,
+    T = 84,
+    U = 85,
+    V = 86,
+    W = 87,
+    X = 88,
+    Y = 89,
+    Z = 90,
+    META = 91,// WIN_KEY_LEFT
+    WIN_KEY_RIGHT = 92,
+    CONTEXT_MENU = 93,
+    NUM_ZERO = 96,
+    NUM_ONE = 97,
+    NUM_TWO = 98,
+    NUM_THREE = 99,
+    NUM_FOUR = 100,
+    NUM_FIVE = 101,
+    NUM_SIX = 102,
+    NUM_SEVEN = 103,
+    NUM_EIGHT = 104,
+    NUM_NINE = 105,
+    NUM_MULTIPLY = 106,
+    NUM_PLUS = 107,
+    NUM_MINUS = 109,
+    NUM_PERIOD = 110,
+    NUM_DIVISION = 111,
+    F1 = 112,
+    F2 = 113,
+    F3 = 114,
+    F4 = 115,
+    F5 = 116,
+    F6 = 117,
+    F7 = 118,
+    F8 = 119,
+    F9 = 120,
+    F10 = 121,
+    F11 = 122,
+    F12 = 123,
+    NUMLOCK = 144,
+    SCROLL_LOCK = 145,
+    FIRST_MEDIA_KEY = 166,
+    LAST_MEDIA_KEY = 183,
+    SEMICOLON = 186,// needs localization
+    DASH = 189,// needs localization
+    EQUALS = 187,// needs localization
+    COMMA = 188,// needs localization
+    PERIOD = 190,// needs localization
+    SLASH = 191,// needs localization
+    APOSTROPHE = 192,// needs localization
+    TILDE = 192,// needs localization
+    SINGLE_QUOTE = 222,// needs localization
+    OPEN_SQUARE_BRACKET = 219,// needs localization
+    BACKSLASH = 220,// needs localization
+    CLOSE_SQUARE_BRACKET = 221,// needs localization
+    WIN_KEY = 224,
+    MAC_FF_META = 224,// Firefox (Gecko) fires this for the meta key instead of 91
+    MAC_WK_CMD_LEFT = 91,// WebKit Left Command key fired, same as META
+    MAC_WK_CMD_RIGHT = 93,// WebKit Right Command key fired, different from META
+    WIN_IME = 229,
+    VK_NONAME = 252,
+    PHANTOM = 255
+}
+//# sourceMappingURL=keycodes.d.ts.map

package/core/utils/math.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @license
+ * Copyright 2019 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Converts degrees to radians.
+ * Copied from Closure's goog.math.toRadians.
+ *
+ * @param angleDegrees Angle in degrees.
+ * @returns Angle in radians.
+ */
+export declare function toRadians(angleDegrees: number): number;
+/**
+ * Converts radians to degrees.
+ * Copied from Closure's goog.math.toDegrees.
+ *
+ * @param angleRadians Angle in radians.
+ * @returns Angle in degrees.
+ */
+export declare function toDegrees(angleRadians: number): number;
+/**
+ * Clamp the provided number between the lower bound and the upper bound.
+ *
+ * @param lowerBound The desired lower bound.
+ * @param number The number to clamp.
+ * @param upperBound The desired upper bound.
+ * @returns The clamped number.
+ */
+export declare function clamp(lowerBound: number, number: number, upperBound: number): number;
+//# sourceMappingURL=math.d.ts.map

package/core/utils/metrics.d.ts

@@ -0,0 +1,64 @@
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export interface Metrics {
+    /** Height of the visible portion of the workspace. */
+    viewHeight: number;
+    /** Width of the visible portion of the workspace. */
+    viewWidth: number;
+    /** Height of the content. */
+    contentHeight: number;
+    /** Width of the content. */
+    contentWidth: number;
+    /** Height of the scroll area. */
+    scrollHeight: number;
+    /** Width of the scroll area. */
+    scrollWidth: number;
+    /**
+     * Top-edge of the visible portion of the workspace, relative to the workspace
+     * origin.
+     */
+    viewTop: number;
+    /**
+     * Left-edge of the visible portion of the workspace, relative to the
+     * workspace origin.
+     */
+    viewLeft: number;
+    /** Top-edge of the content, relative to the workspace origin. */
+    contentTop: number;
+    /** Left-edge of the content relative to the workspace origin. */
+    contentLeft: number;
+    /** Top-edge of the scroll area, relative to the workspace origin. */
+    scrollTop: number;
+    /** Left-edge of the scroll area relative to the workspace origin. */
+    scrollLeft: number;
+    /**
+     * Top-edge of the visible portion of the workspace, relative to the
+     * blocklyDiv.
+     */
+    absoluteTop: number;
+    /**
+     * Left-edge of the visible portion of the workspace, relative to the
+     * blocklyDiv.
+     */
+    absoluteLeft: number;
+    /**
+     * Height of the Blockly div (the view + the toolbox, simple of otherwise).
+     */
+    svgHeight: number;
+    /** Width of the Blockly div (the view + the toolbox, simple or otherwise). */
+    svgWidth: number;
+    /** Width of the toolbox, if it exists.  Otherwise zero. */
+    toolboxWidth: number;
+    /** Height of the toolbox, if it exists.  Otherwise zero. */
+    toolboxHeight: number;
+    /** Top, bottom, left or right. Use TOOLBOX_AT constants to compare. */
+    toolboxPosition: number;
+    /** Width of the flyout if it is always open.  Otherwise zero. */
+    flyoutWidth: number;
+    /** Height of the flyout if it is always open.  Otherwise zero. */
+    flyoutHeight: number;
+}
+//# sourceMappingURL=metrics.d.ts.map

package/core/utils/object.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @license
+ * Copyright 2019 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Complete a deep merge of all members of a source object with a target object.
+ *
+ * N.B. This is not a very sophisticated merge algorithm and does not
+ * handle complex cases. Use with caution.
+ *
+ * @param target Target.
+ * @param source Source.
+ * @returns The resulting object.
+ */
+export declare function deepMerge(target: any, source: any): any;
+//# sourceMappingURL=object.d.ts.map

package/core/utils/parsing.d.ts

@@ -0,0 +1,52 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Parse a string with any number of interpolation tokens (%1, %2, ...).
+ * It will also replace string table references (e.g., %{bky_my_msg} and
+ * %{BKY_MY_MSG} will both be replaced with the value in
+ * Msg['MY_MSG']). Percentage sign characters '%' may be self-escaped
+ * (e.g., '%%'). Newline characters will also be output as string tokens
+ * containing a single newline character.
+ *
+ * @param message Text which might contain string table references and
+ *     interpolation tokens.
+ * @returns Array of strings and numbers.
+ */
+export declare function tokenizeInterpolation(message: string): (string | number)[];
+/**
+ * Replaces string table references in a message, if the message is a string.
+ * For example, "%{bky_my_msg}" and "%{BKY_MY_MSG}" will both be replaced with
+ * the value in Msg['MY_MSG'].
+ *
+ * @param message Message, which may be a string that contains
+ *     string table references.
+ * @returns String with message references replaced.
+ */
+export declare function replaceMessageReferences(message: string | any): string;
+/**
+ * Validates that any %{MSG_KEY} references in the message refer to keys of
+ * the Msg string table.
+ *
+ * @param message Text which might contain string table references.
+ * @returns True if all message references have matching values.
+ *     Otherwise, false.
+ */
+export declare function checkMessageReferences(message: string): boolean;
+/**
+ * Parse a block colour from a number or string, as provided in a block
+ * definition.
+ *
+ * @param colour HSV hue value (0 to 360), #RRGGBB string,
+ *     or a message reference string pointing to one of those two values.
+ * @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.
+ */
+export declare function parseBlockColour(colour: number | string): {
+    hue: number | null;
+    hex: string;
+};
+//# sourceMappingURL=parsing.d.ts.map

package/core/utils/rect.d.ts

@@ -0,0 +1,82 @@
+/**
+ * @license
+ * Copyright 2019 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Utility methods for rectangle manipulation.
+ * These methods are not specific to Blockly, and could be factored out into
+ * a JavaScript framework such as Closure.
+ *
+ * @class
+ */
+import { Coordinate } from './coordinate.js';
+/**
+ * Class for representing rectangular regions.
+ */
+export declare class Rect {
+    top: number;
+    bottom: number;
+    left: number;
+    right: number;
+    /**
+     * @param top Top.
+     * @param bottom Bottom.
+     * @param left Left.
+     * @param right Right.
+     */
+    constructor(top: number, bottom: number, left: number, right: number);
+    /**
+     * Converts a DOM or SVG Rect to a Blockly Rect.
+     *
+     * @param rect The rectangle to convert.
+     * @returns A representation of the same rectangle as a Blockly Rect.
+     */
+    static from(rect: DOMRect | SVGRect): Rect;
+    /**
+     * Creates a new copy of this rectangle.
+     *
+     * @returns A copy of this Rect.
+     */
+    clone(): Rect;
+    /** Returns the height of this rectangle. */
+    getHeight(): number;
+    /** Returns the width of this rectangle. */
+    getWidth(): number;
+    /** Returns the top left coordinate of this rectangle. */
+    getOrigin(): Coordinate;
+    /**
+     * Tests whether this rectangle contains a x/y coordinate.
+     *
+     * @param x The x coordinate to test for containment.
+     * @param y The y coordinate to test for containment.
+     * @returns Whether this rectangle contains given coordinate.
+     */
+    contains(x: number, y: number): boolean;
+    /**
+     * Tests whether this rectangle intersects the provided rectangle.
+     * Assumes that the coordinate system increases going down and left.
+     *
+     * @param other The other rectangle to check for intersection with.
+     * @returns Whether this rectangle intersects the provided rectangle.
+     */
+    intersects(other: Rect): boolean;
+    /**
+     * Compares bounding rectangles for equality.
+     *
+     * @param a A Rect.
+     * @param b A Rect.
+     * @returns True iff the bounding rectangles are equal, or if both are null.
+     */
+    static equals(a?: Rect | null, b?: Rect | null): boolean;
+    /**
+     * Creates a new Rect using a position and supplied dimensions.
+     *
+     * @param position The upper left coordinate of the new rectangle.
+     * @param width The width of the rectangle, in pixels.
+     * @param height The height of the rectangle, in pixels.
+     * @returns A newly created Rect using the provided Coordinate and dimensions.
+     */
+    static createFromPoint(position: Coordinate, width: number, height: number): Rect;
+}
+//# sourceMappingURL=rect.d.ts.map