blockly 12.4.0 → 12.4.1

package/core/touch.d.ts

@@ -0,0 +1,72 @@
+/**
+ * @license
+ * Copyright 2016 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { Gesture } from './gesture.js';
+/**
+ * Whether touch is enabled in the browser.
+ * Copied from Closure's goog.events.BrowserFeature.TOUCH_ENABLED
+ */
+export declare const TOUCH_ENABLED: boolean;
+/**
+ * The TOUCH_MAP lookup dictionary specifies additional touch events to fire,
+ * in conjunction with mouse events.
+ */
+export declare const TOUCH_MAP: {
+    [key: string]: string[];
+};
+/**
+ * Context menus on touch devices are activated using a long-press.
+ * Unfortunately the contextmenu touch event is currently (2015) only supported
+ * by Chrome.  This function is fired on any touchstart event, queues a task,
+ * which after about a second opens the context menu.  The tasks is killed
+ * if the touch event terminates early.
+ *
+ * @param e Touch start event.
+ * @param gesture The gesture that triggered this longStart.
+ * @internal
+ */
+export declare function longStart(e: PointerEvent, gesture: Gesture): void;
+/**
+ * Nope, that's not a long-press.  Either touchend or touchcancel was fired,
+ * or a drag hath begun.  Kill the queued long-press task.
+ *
+ * @internal
+ */
+export declare function longStop(): void;
+/**
+ * Clear the touch identifier that tracks which touch stream to pay attention
+ * to.  This ends the current drag/gesture and allows other pointers to be
+ * captured.
+ */
+export declare function clearTouchIdentifier(): void;
+/**
+ * Decide whether Blockly should handle or ignore this event.
+ * Mouse and touch events require special checks because we only want to deal
+ * with one touch stream at a time.  All other events should always be handled.
+ *
+ * @param e The event to check.
+ * @returns True if this event should be passed through to the registered
+ *     handler; false if it should be blocked.
+ */
+export declare function shouldHandleEvent(e: Event): boolean;
+/**
+ * Get the pointer identifier from the given event.
+ *
+ * @param e Pointer event.
+ * @returns The pointerId of the event.
+ */
+export declare function getTouchIdentifierFromEvent(e: PointerEvent): string;
+/**
+ * Check whether the pointer identifier on the event matches the current saved
+ * identifier. If the current identifier was unset, save the identifier from
+ * the event. This starts a drag/gesture, during which pointer events with
+ * other identifiers will be silently ignored.
+ *
+ * @param e Pointer event.
+ * @returns Whether the identifier on the event matches the current saved
+ *     identifier.
+ */
+export declare function checkTouchIdentifier(e: PointerEvent): boolean;
+//# sourceMappingURL=touch.d.ts.map

package/core/trashcan.d.ts

@@ -0,0 +1,212 @@
+/**
+ * @license
+ * Copyright 2011 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { DeleteArea } from './delete_area.js';
+import './events/events_trashcan_open.js';
+import type { IAutoHideable } from './interfaces/i_autohideable.js';
+import type { IDraggable } from './interfaces/i_draggable.js';
+import type { IFlyout } from './interfaces/i_flyout.js';
+import type { IPositionable } from './interfaces/i_positionable.js';
+import type { UiMetrics } from './metrics_manager.js';
+import { Rect } from './utils/rect.js';
+import type { WorkspaceSvg } from './workspace_svg.js';
+/**
+ * Class for a trash can.
+ */
+export declare class Trashcan extends DeleteArea implements IAutoHideable, IPositionable {
+    private workspace;
+    /**
+     * The unique id for this component that is used to register with the
+     * ComponentManager.
+     */
+    id: string;
+    /**
+     * A list of JSON (stored as strings) representing blocks in the trashcan.
+     */
+    private readonly contents;
+    /**
+     * The trashcan flyout.
+     *
+     * @internal
+     */
+    flyout: IFlyout | null;
+    /** Current open/close state of the lid. */
+    isLidOpen: boolean;
+    /**
+     * The minimum openness of the lid. Used to indicate if the trashcan
+     * contains blocks.
+     */
+    private minOpenness;
+    /** The SVG group containing the trash can. */
+    private svgGroup;
+    /** The SVG image element of the trash can lid. */
+    private svgLid;
+    /** Task ID of opening/closing animation. */
+    private lidTask;
+    /** Current state of lid opening (0.0 = closed, 1.0 = open). */
+    private lidOpen;
+    /** Left coordinate of the trash can. */
+    private left;
+    /** Top coordinate of the trash can. */
+    private top;
+    /** Whether this trash can has been initialized. */
+    private initialized;
+    /** @param workspace The workspace to sit in. */
+    constructor(workspace: WorkspaceSvg);
+    /**
+     * Create the trash can elements.
+     *
+     * @returns The trash can's SVG group.
+     */
+    createDom(): SVGElement;
+    /** Initializes the trash can. */
+    init(): void;
+    /**
+     * Dispose of this trash can.
+     * Unlink from all DOM elements to prevent memory leaks.
+     */
+    dispose(): void;
+    /**
+     * Whether the trashcan has contents.
+     *
+     * @returns True if the trashcan has contents.
+     */
+    private hasContents;
+    /**
+     * Returns true if the trashcan contents-flyout is currently open.
+     *
+     * @returns True if the trashcan contents-flyout is currently open.
+     */
+    contentsIsOpen(): boolean;
+    /** Opens the trashcan flyout. */
+    openFlyout(): void;
+    /** Closes the trashcan flyout. */
+    closeFlyout(): void;
+    /**
+     * Hides the component. Called in WorkspaceSvg.hideChaff.
+     *
+     * @param onlyClosePopups Whether only popups should be closed.
+     *     Flyouts should not be closed if this is true.
+     */
+    autoHide(onlyClosePopups: boolean): void;
+    /**
+     * Empties the trashcan's contents. If the contents-flyout is currently open
+     * it will be closed.
+     */
+    emptyContents(): void;
+    /**
+     * Positions the trashcan.
+     * It is positioned in the opposite corner to the corner the
+     * categories/toolbox starts at.
+     *
+     * @param metrics The workspace metrics.
+     * @param savedPositions List of rectangles that are already on the workspace.
+     */
+    position(metrics: UiMetrics, savedPositions: Rect[]): void;
+    /**
+     * Returns the bounding rectangle of the UI element in pixel units relative to
+     * the Blockly injection div.
+     *
+     * @returns The UI elements's bounding box. Null if bounding box should be
+     *     ignored by other UI elements.
+     */
+    getBoundingRectangle(): Rect | null;
+    /**
+     * Returns the bounding rectangle of the drag target area in pixel units
+     * relative to viewport.
+     *
+     * @returns The component's bounding box. Null if drag target area should be
+     *     ignored.
+     */
+    getClientRect(): Rect | null;
+    /**
+     * Handles when a cursor with a block or bubble is dragged over this drag
+     * target.
+     *
+     * @param _dragElement The block or bubble currently being dragged.
+     */
+    onDragOver(_dragElement: IDraggable): void;
+    /**
+     * Handles when a cursor with a block or bubble exits this drag target.
+     *
+     * @param _dragElement The block or bubble currently being dragged.
+     */
+    onDragExit(_dragElement: IDraggable): void;
+    /**
+     * Handles when a block or bubble is dropped on this component.
+     * Should not handle delete here.
+     *
+     * @param _dragElement The block or bubble currently being dragged.
+     */
+    onDrop(_dragElement: IDraggable): void;
+    /**
+     * Flip the lid open or shut.
+     *
+     * @param state True if open.
+     * @internal
+     */
+    setLidOpen(state: boolean): void;
+    /** Rotate the lid open or closed by one step.  Then wait and recurse. */
+    private animateLid;
+    /**
+     * Set the angle of the trashcan's lid.
+     *
+     * @param lidAngle The angle at which to set the lid.
+     */
+    private setLidAngle;
+    /**
+     * Sets the minimum openness of the trashcan lid. If the lid is currently
+     * closed, this will update lid's position.
+     *
+     * @param newMin The new minimum openness of the lid. Should be between 0
+     *     and 1.
+     */
+    private setMinOpenness;
+    /**
+     * Flip the lid shut.
+     * Called externally after a drag.
+     */
+    closeLid(): void;
+    /** Inspect the contents of the trash. */
+    click(): void;
+    /**
+     * Fires a UI event for trashcan flyout open or close.
+     *
+     * @param trashcanOpen Whether the flyout is opening.
+     */
+    private fireUiEvent;
+    /**
+     * Prevents a workspace scroll and click event if the trashcan has blocks.
+     *
+     * @param e A mouse down event.
+     */
+    private blockMouseDownWhenOpenable;
+    /**
+     * Indicate that the trashcan can be clicked (by opening it) if it has blocks.
+     */
+    private mouseOver;
+    /**
+     * Close the lid of the trashcan if it was open (Vis. it was indicating it had
+     *    blocks).
+     */
+    private mouseOut;
+    /**
+     * Handle a BLOCK_DELETE event. Adds deleted blocks oldXml to the content
+     * array.
+     *
+     * @param event Workspace event.
+     */
+    private onDelete;
+    /**
+     * Converts JSON representing a block into text that can be stored in the
+     * content array.
+     *
+     * @param json A JSON representation of a block's state.
+     * @returns A BlockInfo object corresponding to the JSON, cleaned of all
+     *     unnecessary attributes.
+     */
+    private cleanBlockJson;
+}
+//# sourceMappingURL=trashcan.d.ts.map

package/core/utils/aria.d.ts

@@ -0,0 +1,69 @@
+/**
+ * @license
+ * Copyright 2019 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * ARIA role values.
+ * Copied from Closure's goog.a11y.aria.Role
+ */
+export declare enum Role {
+    GRID = "grid",
+    GRIDCELL = "gridcell",
+    GROUP = "group",
+    LISTBOX = "listbox",
+    MENU = "menu",
+    MENUITEM = "menuitem",
+    MENUITEMCHECKBOX = "menuitemcheckbox",
+    OPTION = "option",
+    PRESENTATION = "presentation",
+    ROW = "row",
+    TREE = "tree",
+    TREEITEM = "treeitem",
+    SEPARATOR = "separator",
+    STATUS = "status"
+}
+/**
+ * ARIA states and properties.
+ * Copied from Closure's goog.a11y.aria.State
+ */
+export declare enum State {
+    ACTIVEDESCENDANT = "activedescendant",
+    COLCOUNT = "colcount",
+    DISABLED = "disabled",
+    EXPANDED = "expanded",
+    INVALID = "invalid",
+    LABEL = "label",
+    LABELLEDBY = "labelledby",
+    LEVEL = "level",
+    ORIENTATION = "orientation",
+    POSINSET = "posinset",
+    ROWCOUNT = "rowcount",
+    SELECTED = "selected",
+    SETSIZE = "setsize",
+    VALUEMAX = "valuemax",
+    VALUEMIN = "valuemin",
+    LIVE = "live",
+    HIDDEN = "hidden"
+}
+/**
+ * Sets the role of an element.
+ *
+ * Similar to Closure's goog.a11y.aria
+ *
+ * @param element DOM node to set role of.
+ * @param roleName Role name.
+ */
+export declare function setRole(element: Element, roleName: Role): void;
+/**
+ * Sets the state or property of an element.
+ * Copied from Closure's goog.a11y.aria
+ *
+ * @param element DOM node where we set state.
+ * @param stateName State attribute being set.
+ *     Automatically adds prefix 'aria-' to the state name if the attribute is
+ * not an extra attribute.
+ * @param value Value for the state attribute.
+ */
+export declare function setState(element: Element, stateName: State, value: string | boolean | number | string[]): void;
+//# sourceMappingURL=aria.d.ts.map

package/core/utils/array.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Removes the first occurrence of a particular value from an array.
+ *
+ * @param arr Array from which to remove value.
+ * @param value Value to remove.
+ * @returns True if an element was removed.
+ * @internal
+ */
+export declare function removeElem<T>(arr: Array<T>, value: T): boolean;
+//# sourceMappingURL=array.d.ts.map

package/core/utils/colour.d.ts

@@ -0,0 +1,102 @@
+/**
+ * @license
+ * Copyright 2019 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Get the richness of block colours, regardless of the hue.
+ *
+ * @returns The current richness.
+ * @internal
+ */
+export declare function getHsvSaturation(): number;
+/**
+ * Set the richness of block colours, regardless of the hue.
+ *
+ * @param newSaturation The new richness, in the range of  0 (inclusive) to 1
+ *     (exclusive)
+ * @internal
+ */
+export declare function setHsvSaturation(newSaturation: number): void;
+/**
+ * Get the intensity of block colours, regardless of the hue.
+ *
+ * @returns The current intensity.
+ * @internal
+ */
+export declare function getHsvValue(): number;
+/**
+ * Set the intensity of block colours, regardless of the hue.
+ *
+ * @param newValue The new intensity, in the range of  0 (inclusive) to 1
+ *     (exclusive)
+ * @internal
+ */
+export declare function setHsvValue(newValue: number): void;
+/**
+ * Parses a colour from a string.
+ * .parse('red') = '#ff0000'
+ * .parse('#f00') = '#ff0000'
+ * .parse('#ff0000') = '#ff0000'
+ * .parse('0xff0000') = '#ff0000'
+ * .parse('rgb(255, 0, 0)') = '#ff0000'
+ *
+ * @param str Colour in some CSS format.
+ * @returns A string containing a hex representation of the colour, or null if
+ *     can't be parsed.
+ */
+export declare function parse(str: string | number): string | null;
+/**
+ * Converts a colour from RGB to hex representation.
+ *
+ * @param r Amount of red, int between 0 and 255.
+ * @param g Amount of green, int between 0 and 255.
+ * @param b Amount of blue, int between 0 and 255.
+ * @returns Hex representation of the colour.
+ */
+export declare function rgbToHex(r: number, g: number, b: number): string;
+/**
+ * Converts a colour to RGB.
+ *
+ * @param colour String representing colour in any colour format ('#ff0000',
+ *     'red', '0xff000', etc).
+ * @returns RGB representation of the colour.
+ */
+export declare function hexToRgb(colour: string): number[];
+/**
+ * Converts an HSV triplet to hex representation.
+ *
+ * @param h Hue value in [0, 360].
+ * @param s Saturation value in [0, 1].
+ * @param v Brightness in [0, 255].
+ * @returns Hex representation of the colour.
+ */
+export declare function hsvToHex(h: number, s: number, v: number): string;
+/**
+ * Blend two colours together, using the specified factor to indicate the
+ * weight given to the first colour.
+ *
+ * @param colour1 First colour.
+ * @param colour2 Second colour.
+ * @param factor The weight to be given to colour1 over colour2.
+ *     Values should be in the range [0, 1].
+ * @returns Combined colour represented in hex.
+ */
+export declare function blend(colour1: string, colour2: string, factor: number): string | null;
+/**
+ * A map that contains the 16 basic colour keywords as defined by W3C:
+ * https://www.w3.org/TR/2018/REC-css-color-3-20180619/#html4
+ * The keys of this map are the lowercase "readable" names of the colours,
+ * while the values are the "hex" values.
+ */
+export declare const names: {
+    [key: string]: string;
+};
+/**
+ * Convert a hue (HSV model) into an RGB hex triplet.
+ *
+ * @param hue Hue on a colour wheel (0-360).
+ * @returns RGB code, e.g. '#5ba65b'.
+ */
+export declare function hueToHex(hue: number): string;
+//# sourceMappingURL=colour.d.ts.map

package/core/utils/coordinate.d.ts

@@ -0,0 +1,87 @@
+/**
+ * @license
+ * Copyright 2019 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Utility methods for coordinate manipulation.
+ * These methods are not specific to Blockly, and could be factored out into
+ * a JavaScript framework such as Closure.
+ *
+ * @class
+ */
+/**
+ * Class for representing coordinates and positions.
+ */
+export declare class Coordinate {
+    x: number;
+    y: number;
+    /**
+     * @param x Left.
+     * @param y Top.
+     */
+    constructor(x: number, y: number);
+    /**
+     * Creates a new copy of this coordinate.
+     *
+     * @returns A copy of this coordinate.
+     */
+    clone(): Coordinate;
+    /**
+     * Scales this coordinate by the given scale factor.
+     *
+     * @param s The scale factor to use for both x and y dimensions.
+     * @returns This coordinate after scaling.
+     */
+    scale(s: number): Coordinate;
+    /**
+     * Translates this coordinate by the given offsets.
+     * respectively.
+     *
+     * @param tx The value to translate x by.
+     * @param ty The value to translate y by.
+     * @returns This coordinate after translating.
+     */
+    translate(tx: number, ty: number): Coordinate;
+    /**
+     * Compares coordinates for equality.
+     *
+     * @param a A Coordinate.
+     * @param b A Coordinate.
+     * @returns True iff the coordinates are equal, or if both are null.
+     */
+    static equals(a?: Coordinate | null, b?: Coordinate | null): boolean;
+    /**
+     * Returns the distance between two coordinates.
+     *
+     * @param a A Coordinate.
+     * @param b A Coordinate.
+     * @returns The distance between `a` and `b`.
+     */
+    static distance(a: Coordinate, b: Coordinate): number;
+    /**
+     * Returns the magnitude of a coordinate.
+     *
+     * @param a A Coordinate.
+     * @returns The distance between the origin and `a`.
+     */
+    static magnitude(a: Coordinate): number;
+    /**
+     * Returns the difference between two coordinates as a new
+     * Coordinate.
+     *
+     * @param a An x/y coordinate.
+     * @param b An x/y coordinate.
+     * @returns A Coordinate representing the difference between `a` and `b`.
+     */
+    static difference(a: Coordinate | SVGPoint, b: Coordinate | SVGPoint): Coordinate;
+    /**
+     * Returns the sum of two coordinates as a new Coordinate.
+     *
+     * @param a An x/y coordinate.
+     * @param b An x/y coordinate.
+     * @returns A Coordinate representing the sum of the two coordinates.
+     */
+    static sum(a: Coordinate | SVGPoint, b: Coordinate | SVGPoint): Coordinate;
+}
+//# sourceMappingURL=coordinate.d.ts.map

package/core/utils/deprecation.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Warn developers that a function or property is deprecated.
+ *
+ * @param name The name of the function or property.
+ * @param deprecationDate The date of deprecation. Prefer 'version n.0.0'
+ *     format, and fall back to 'month yyyy' or 'quarter yyyy' format.
+ * @param deletionDate The date of deletion. Prefer 'version n.0.0'
+ *     format, and fall back to 'month yyyy' or 'quarter yyyy' format.
+ * @param opt_use The name of a function or property to use instead, if any.
+ * @internal
+ */
+export declare function warn(name: string, deprecationDate: string, deletionDate: string, opt_use?: string): void;
+//# sourceMappingURL=deprecation.d.ts.map