blockly 12.4.0 → 12.5.0

package/core/flyout_base.d.ts

@@ -0,0 +1,453 @@
+/**
+ * @license
+ * Copyright 2011 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Flyout tray containing blocks which may be created.
+ *
+ * @class
+ */
+import { BlockSvg } from './block_svg.js';
+import { DeleteArea } from './delete_area.js';
+import { FlyoutItem } from './flyout_item.js';
+import { IAutoHideable } from './interfaces/i_autohideable.js';
+import type { IFlyout } from './interfaces/i_flyout.js';
+import type { IFlyoutInflater } from './interfaces/i_flyout_inflater.js';
+import { IFocusableNode } from './interfaces/i_focusable_node.js';
+import type { IFocusableTree } from './interfaces/i_focusable_tree.js';
+import type { Options } from './options.js';
+import * as blocks from './serialization/blocks.js';
+import { Coordinate } from './utils/coordinate.js';
+import { Svg } from './utils/svg.js';
+import * as toolbox from './utils/toolbox.js';
+import { WorkspaceSvg } from './workspace_svg.js';
+/**
+ * Class for a flyout.
+ */
+export declare abstract class Flyout extends DeleteArea implements IAutoHideable, IFlyout, IFocusableNode {
+    /**
+     * Position the flyout.
+     */
+    abstract position(): void;
+    /**
+     * Determine if a drag delta is toward the workspace, based on the position
+     * and orientation of the flyout. This is used in determineDragIntention_ to
+     * determine if a new block should be created or if the flyout should scroll.
+     *
+     * @param currentDragDeltaXY How far the pointer has
+     *     moved from the position at mouse down, in pixel units.
+     * @returns True if the drag is toward the workspace.
+     */
+    abstract isDragTowardWorkspace(currentDragDeltaXY: Coordinate): boolean;
+    /**
+     * Sets the translation of the flyout to match the scrollbars.
+     *
+     * @param xyRatio Contains a y property which is a float
+     *     between 0 and 1 specifying the degree of scrolling and a
+     *     similar x property.
+     */
+    protected abstract setMetrics_(xyRatio: {
+        x?: number;
+        y?: number;
+    }): void;
+    /**
+     * Lay out the elements in the flyout.
+     *
+     * @param contents The flyout elements to lay out.
+     */
+    protected abstract layout_(contents: FlyoutItem[]): void;
+    /**
+     * Scroll the flyout.
+     *
+     * @param e Mouse wheel scroll event.
+     */
+    protected abstract wheel_(e: WheelEvent): void;
+    /**
+     * Compute bounds of flyout.
+     * For RTL: Lay out the elements right-aligned.
+     */
+    protected abstract reflowInternal_(): void;
+    /**
+     * Calculates the x coordinate for the flyout position.
+     *
+     * @returns X coordinate.
+     */
+    abstract getX(): number;
+    /**
+     * Calculates the y coordinate for the flyout position.
+     *
+     * @returns Y coordinate.
+     */
+    abstract getY(): number;
+    /**
+     * Scroll the flyout to the beginning of its contents.
+     */
+    abstract scrollToStart(): void;
+    protected workspace_: WorkspaceSvg;
+    RTL: boolean;
+    /**
+     * Whether the flyout should be laid out horizontally or not.
+     *
+     * @internal
+     */
+    horizontalLayout: boolean;
+    protected toolboxPosition_: number;
+    /**
+     * Array holding info needed to unbind events.
+     * Used for disposing.
+     * Ex: [[node, name, func], [node, name, func]].
+     */
+    private boundEvents;
+    /**
+     * Function that will be registered as a change listener on the workspace
+     * to reflow when elements in the flyout workspace change.
+     */
+    private reflowWrapper;
+    /**
+     * If true, prevents the reflow wrapper from running. Used to prevent infinite
+     * recursion.
+     */
+    private inhibitReflowWrapper;
+    /**
+     * List of flyout elements.
+     */
+    protected contents: FlyoutItem[];
+    protected readonly tabWidth_: number;
+    /**
+     * The target workspace.
+     *
+     * @internal
+     */
+    targetWorkspace: WorkspaceSvg;
+    /**
+     * Does the flyout automatically close when a block is created?
+     */
+    autoClose: boolean;
+    /**
+     * Whether the flyout is visible.
+     */
+    private visible;
+    /**
+     * Whether the workspace containing this flyout is visible.
+     */
+    private containerVisible;
+    /**
+     * Corner radius of the flyout background.
+     */
+    readonly CORNER_RADIUS: number;
+    readonly MARGIN: number;
+    readonly GAP_X: number;
+    readonly GAP_Y: number;
+    /**
+     * Top/bottom padding between scrollbar and edge of flyout background.
+     */
+    readonly SCROLLBAR_MARGIN: number;
+    /**
+     * Width of flyout.
+     */
+    protected width_: number;
+    /**
+     * Height of flyout.
+     */
+    protected height_: number;
+    /**
+     * Range of a drag angle from a flyout considered "dragging toward
+     * workspace". Drags that are within the bounds of this many degrees from
+     * the orthogonal line to the flyout edge are considered to be "drags toward
+     * the workspace".
+     *
+     * @example
+     *
+     * ```
+     * Flyout                                                 Edge   Workspace
+     * [block] /  <-within this angle, drags "toward workspace" |
+     * [block] ---- orthogonal to flyout boundary ----          |
+     * [block] \                                                |
+     * ```
+     *
+     * The angle is given in degrees from the orthogonal.
+     *
+     * This is used to know when to create a new block and when to scroll the
+     * flyout. Setting it to 360 means that all drags create a new block.
+     */
+    protected dragAngleRange_: number;
+    /**
+     * The path around the background of the flyout, which will be filled with a
+     * background colour.
+     */
+    protected svgBackground_: SVGPathElement | null;
+    /**
+     * The root SVG group for the button or label.
+     */
+    protected svgGroup_: SVGGElement | null;
+    /**
+     * Map from flyout content type to the corresponding inflater class
+     * responsible for creating concrete instances of the content type.
+     */
+    protected inflaters: Map<string, IFlyoutInflater>;
+    /**
+     * @param workspaceOptions Dictionary of options for the
+     *     workspace.
+     */
+    constructor(workspaceOptions: Options);
+    /**
+     * Creates the flyout's DOM.  Only needs to be called once.  The flyout can
+     * either exist as its own SVG element or be a g element nested inside a
+     * separate SVG element.
+     *
+     * @param tagName The type of tag to
+     *     put the flyout in. This should be <svg> or <g>.
+     * @returns The flyout's SVG group.
+     */
+    createDom(tagName: string | Svg<SVGSVGElement> | Svg<SVGGElement>): SVGElement;
+    /**
+     * Initializes the flyout.
+     *
+     * @param targetWorkspace The workspace in which to
+     *     create new blocks.
+     */
+    init(targetWorkspace: WorkspaceSvg): void;
+    /**
+     * Dispose of this flyout.
+     * Unlink from all DOM elements to prevent memory leaks.
+     */
+    dispose(): void;
+    /**
+     * Get the width of the flyout.
+     *
+     * @returns The width of the flyout.
+     */
+    getWidth(): number;
+    /**
+     * Get the height of the flyout.
+     *
+     * @returns The width of the flyout.
+     */
+    getHeight(): number;
+    /**
+     * Get the scale (zoom level) of the flyout. By default,
+     * this matches the target workspace scale, but this can be overridden.
+     *
+     * @returns Flyout workspace scale.
+     */
+    getFlyoutScale(): number;
+    /**
+     * Get the workspace inside the flyout.
+     *
+     * @returns The workspace inside the flyout.
+     */
+    getWorkspace(): WorkspaceSvg;
+    /**
+     * Sets whether this flyout automatically closes when blocks are dragged out,
+     * the workspace is clicked, etc, or not.
+     */
+    setAutoClose(autoClose: boolean): void;
+    /** Automatically hides the flyout if it is an autoclosing flyout. */
+    autoHide(onlyClosePopups: boolean): void;
+    /**
+     * Get the target workspace inside the flyout.
+     *
+     * @returns The target workspace inside the flyout.
+     */
+    getTargetWorkspace(): WorkspaceSvg;
+    /**
+     * Is the flyout visible?
+     *
+     * @returns True if visible.
+     */
+    isVisible(): boolean;
+    /**
+     * Set whether the flyout is visible. A value of true does not necessarily
+     * mean that the flyout is shown. It could be hidden because its container is
+     * hidden.
+     *
+     * @param visible True if visible.
+     */
+    setVisible(visible: boolean): void;
+    /**
+     * Set whether this flyout's container is visible.
+     *
+     * @param visible Whether the container is visible.
+     */
+    setContainerVisible(visible: boolean): void;
+    /**
+     * Get the list of elements of the current flyout.
+     *
+     * @returns The array of flyout elements.
+     */
+    getContents(): FlyoutItem[];
+    /**
+     * Store the list of elements on the flyout.
+     *
+     * @param contents - The array of items for the flyout.
+     */
+    setContents(contents: FlyoutItem[]): void;
+    /**
+     * Update the display property of the flyout based whether it thinks it should
+     * be visible and whether its containing workspace is visible.
+     */
+    private updateDisplay;
+    /**
+     * Update the view based on coordinates calculated in position().
+     *
+     * @param width The computed width of the flyout's SVG group
+     * @param height The computed height of the flyout's SVG group.
+     * @param x The computed x origin of the flyout's SVG group.
+     * @param y The computed y origin of the flyout's SVG group.
+     */
+    protected positionAt_(width: number, height: number, x: number, y: number): void;
+    /**
+     * Hide and empty the flyout.
+     */
+    hide(): void;
+    /**
+     * Show and populate the flyout.
+     *
+     * @param flyoutDef Contents to display
+     *     in the flyout. This is either an array of Nodes, a NodeList, a
+     *     toolbox definition, or a string with the name of the dynamic category.
+     */
+    show(flyoutDef: toolbox.FlyoutDefinition | string): void;
+    /**
+     * Create the contents array and gaps array necessary to create the layout for
+     * the flyout.
+     *
+     * @param parsedContent The array
+     *     of objects to show in the flyout.
+     * @returns The list of contents needed to lay out the flyout.
+     */
+    private createFlyoutInfo;
+    /**
+     * Updates and returns the provided list of flyout contents to flatten
+     * separators as needed.
+     *
+     * When multiple separators occur one after another, the value of the last one
+     * takes precedence and the earlier separators in the group are removed.
+     *
+     * @param contents The list of flyout contents to flatten separators in.
+     * @returns An updated list of flyout contents with only one separator between
+     *     each non-separator item.
+     */
+    protected normalizeSeparators(contents: FlyoutItem[]): FlyoutItem[];
+    /**
+     * Gets the flyout definition for the dynamic category.
+     *
+     * @param categoryName The name of the dynamic category.
+     * @returns The definition of the
+     *     flyout in one of its many forms.
+     */
+    private getDynamicCategoryContents;
+    /**
+     * Delete elements from a previous showing of the flyout.
+     */
+    private clearOldBlocks;
+    /**
+     * Pointer down on the flyout background.  Start a vertical scroll drag.
+     *
+     * @param e Pointer down event.
+     */
+    private onMouseDown;
+    /**
+     * Does this flyout allow you to create a new instance of the given block?
+     * Used for deciding if a block can be "dragged out of" the flyout.
+     *
+     * @param block The block to copy from the flyout.
+     * @returns True if you can create a new instance of the block, false
+     *    otherwise.
+     * @internal
+     */
+    isBlockCreatable(block: BlockSvg): boolean;
+    /**
+     * Create a copy of this block on the workspace.
+     *
+     * @param originalBlock The block to copy from the flyout.
+     * @returns The newly created block.
+     * @throws {Error} if something went wrong with deserialization.
+     * @internal
+     */
+    createBlock(originalBlock: BlockSvg): BlockSvg;
+    /**
+     * Reflow flyout contents.
+     */
+    reflow(): void;
+    /**
+     * @returns True if this flyout may be scrolled with a scrollbar or
+     *     by dragging.
+     * @internal
+     */
+    isScrollable(): boolean;
+    /**
+     * Serialize a block to JSON.
+     *
+     * @param block The block to serialize.
+     * @returns A serialized representation of the block.
+     */
+    protected serializeBlock(block: BlockSvg): blocks.State;
+    /**
+     * Positions a block on the target workspace.
+     *
+     * @param oldBlock The flyout block being copied.
+     * @param block The block to posiiton.
+     */
+    private positionNewBlock;
+    /**
+     * Returns the inflater responsible for constructing items of the given type.
+     *
+     * @param type The type of flyout content item to provide an inflater for.
+     * @returns An inflater object for the given type, or null if no inflater
+     *     is registered for that type.
+     */
+    protected getInflaterForType(type: string): IFlyoutInflater | null;
+    /**
+     * See IFocusableNode.getFocusableElement.
+     *
+     * @deprecated v12: Use the Flyout's workspace for focus operations, instead.
+     */
+    getFocusableElement(): HTMLElement | SVGElement;
+    /**
+     * See IFocusableNode.getFocusableTree.
+     *
+     * @deprecated v12: Use the Flyout's workspace for focus operations, instead.
+     */
+    getFocusableTree(): IFocusableTree;
+    /** See IFocusableNode.onNodeFocus. */
+    onNodeFocus(): void;
+    /** See IFocusableNode.onNodeBlur. */
+    onNodeBlur(): void;
+    /** See IFocusableNode.canBeFocused. */
+    canBeFocused(): boolean;
+    /**
+     * See IFocusableNode.getRootFocusableNode.
+     *
+     * @deprecated v12: Use the Flyout's workspace for focus operations, instead.
+     */
+    getRootFocusableNode(): IFocusableNode;
+    /**
+     * See IFocusableNode.getRestoredFocusableNode.
+     *
+     * @deprecated v12: Use the Flyout's workspace for focus operations, instead.
+     */
+    getRestoredFocusableNode(_previousNode: IFocusableNode | null): IFocusableNode | null;
+    /**
+     * See IFocusableNode.getNestedTrees.
+     *
+     * @deprecated v12: Use the Flyout's workspace for focus operations, instead.
+     */
+    getNestedTrees(): Array<IFocusableTree>;
+    /**
+     * See IFocusableNode.lookUpFocusableNode.
+     *
+     * @deprecated v12: Use the Flyout's workspace for focus operations, instead.
+     */
+    lookUpFocusableNode(_id: string): IFocusableNode | null;
+    /** See IFocusableTree.onTreeFocus. */
+    onTreeFocus(_node: IFocusableNode, _previousTree: IFocusableTree | null): void;
+    /**
+     * See IFocusableNode.onTreeBlur.
+     *
+     * @deprecated v12: Use the Flyout's workspace for focus operations, instead.
+     */
+    onTreeBlur(_nextTree: IFocusableTree | null): void;
+}
+//# sourceMappingURL=flyout_base.d.ts.map

package/core/flyout_button.d.ts

@@ -0,0 +1,140 @@
+/**
+ * @license
+ * Copyright 2016 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { IBoundedElement } from './interfaces/i_bounded_element.js';
+import type { IFocusableNode } from './interfaces/i_focusable_node.js';
+import type { IFocusableTree } from './interfaces/i_focusable_tree.js';
+import type { IRenderedElement } from './interfaces/i_rendered_element.js';
+import { Coordinate } from './utils/coordinate.js';
+import { Rect } from './utils/rect.js';
+import type * as toolbox from './utils/toolbox.js';
+import type { WorkspaceSvg } from './workspace_svg.js';
+/**
+ * Class for a button or label in the flyout.
+ */
+export declare class FlyoutButton implements IBoundedElement, IRenderedElement, IFocusableNode {
+    private readonly workspace;
+    private readonly targetWorkspace;
+    private readonly isFlyoutLabel;
+    /** The horizontal margin around the text in the button. */
+    static TEXT_MARGIN_X: number;
+    /** The vertical margin around the text in the button. */
+    static TEXT_MARGIN_Y: number;
+    /** The radius of the flyout button's borders. */
+    static BORDER_RADIUS: number;
+    /** The key to the function called when this button is activated. */
+    readonly callbackKey: string;
+    private readonly text;
+    private readonly position;
+    private readonly cssClass;
+    /** Mouse up event data. */
+    private onMouseDownWrapper;
+    private onMouseUpWrapper;
+    info: toolbox.ButtonOrLabelInfo;
+    /** The width of the button's rect. */
+    width: number;
+    /** The height of the button's rect. */
+    height: number;
+    /** The root SVG group for the button or label. */
+    private svgGroup;
+    /** The SVG element with the text of the label or button. */
+    private svgText;
+    /**
+     * Holds the cursors svg element when the cursor is attached to the button.
+     * This is null if there is no cursor on the button.
+     */
+    cursorSvg: SVGElement | null;
+    /** The unique ID for this FlyoutButton. */
+    private id;
+    /**
+     * @param workspace The workspace in which to place this button.
+     * @param targetWorkspace The flyout's target workspace.
+     * @param json The JSON specifying the label/button.
+     * @param isFlyoutLabel Whether this button should be styled as a label.
+     * @internal
+     */
+    constructor(workspace: WorkspaceSvg, targetWorkspace: WorkspaceSvg, json: toolbox.ButtonOrLabelInfo, isFlyoutLabel: boolean);
+    createDom(): SVGElement;
+    /** Correctly position the flyout button and make it visible. */
+    show(): void;
+    /** Update SVG attributes to match internal state. */
+    private updateTransform;
+    /**
+     * Move the button to the given x, y coordinates.
+     *
+     * @param x The new x coordinate.
+     * @param y The new y coordinate.
+     */
+    moveTo(x: number, y: number): void;
+    /**
+     * Move the element by a relative offset.
+     *
+     * @param dx Horizontal offset in workspace units.
+     * @param dy Vertical offset in workspace units.
+     * @param _reason Why is this move happening?  'user', 'bump', 'snap'...
+     */
+    moveBy(dx: number, dy: number, _reason?: string[]): void;
+    /** @returns Whether or not the button is a label. */
+    isLabel(): boolean;
+    /**
+     * Location of the button.
+     *
+     * @returns x, y coordinates.
+     * @internal
+     */
+    getPosition(): Coordinate;
+    /**
+     * Returns the coordinates of a bounded element describing the dimensions of
+     * the element. Coordinate system: workspace coordinates.
+     *
+     * @returns Object with coordinates of the bounded element.
+     */
+    getBoundingRectangle(): Rect;
+    /** @returns Text of the button. */
+    getButtonText(): string;
+    /**
+     * Get the button's target workspace.
+     *
+     * @returns The target workspace of the flyout where this button resides.
+     */
+    getTargetWorkspace(): WorkspaceSvg;
+    /**
+     * Get the button's workspace.
+     *
+     * @returns The workspace in which to place this button.
+     */
+    getWorkspace(): WorkspaceSvg;
+    /** Dispose of this button. */
+    dispose(): void;
+    /**
+     * Add the cursor SVG to this buttons's SVG group.
+     *
+     * @param cursorSvg The SVG root of the cursor to be added to the button SVG
+     *     group.
+     */
+    setCursorSvg(cursorSvg: SVGElement): void;
+    /**
+     * Do something when the button is clicked.
+     *
+     * @param e Pointer up event.
+     */
+    private onMouseUp;
+    private onMouseDown;
+    /**
+     * @returns The root SVG element of this rendered element.
+     */
+    getSvgRoot(): SVGGElement;
+    /** See IFocusableNode.getFocusableElement. */
+    getFocusableElement(): HTMLElement | SVGElement;
+    /** See IFocusableNode.getFocusableTree. */
+    getFocusableTree(): IFocusableTree;
+    /** See IFocusableNode.onNodeFocus. */
+    onNodeFocus(): void;
+    /** See IFocusableNode.onNodeBlur. */
+    onNodeBlur(): void;
+    /** See IFocusableNode.canBeFocused. */
+    canBeFocused(): boolean;
+}
+//# sourceMappingURL=flyout_button.d.ts.map

package/core/flyout_horizontal.d.ts

@@ -0,0 +1,87 @@
+/**
+ * @license
+ * Copyright 2017 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Flyout } from './flyout_base.js';
+import type { FlyoutItem } from './flyout_item.js';
+import type { Options } from './options.js';
+import type { Coordinate } from './utils/coordinate.js';
+import { Rect } from './utils/rect.js';
+/**
+ * Class for a flyout.
+ */
+export declare class HorizontalFlyout extends Flyout {
+    horizontalLayout: boolean;
+    /** @param workspaceOptions Dictionary of options for the workspace. */
+    constructor(workspaceOptions: Options);
+    /**
+     * Sets the translation of the flyout to match the scrollbars.
+     *
+     * @param xyRatio Contains a y property which is a float between 0 and 1
+     *     specifying the degree of scrolling and a similar x property.
+     */
+    protected setMetrics_(xyRatio: {
+        x: number;
+        y: number;
+    }): void;
+    /**
+     * Calculates the x coordinate for the flyout position.
+     *
+     * @returns X coordinate.
+     */
+    getX(): number;
+    /**
+     * Calculates the y coordinate for the flyout position.
+     *
+     * @returns Y coordinate.
+     */
+    getY(): number;
+    /** Move the flyout to the edge of the workspace. */
+    position(): void;
+    /**
+     * Create and set the path for the visible boundaries of the flyout.
+     *
+     * @param width The width of the flyout, not including the rounded corners.
+     * @param height The height of the flyout, not including rounded corners.
+     */
+    private setBackgroundPath;
+    /** Scroll the flyout to the top. */
+    scrollToStart(): void;
+    /**
+     * Scroll the flyout.
+     *
+     * @param e Mouse wheel scroll event.
+     */
+    protected wheel_(e: WheelEvent): void;
+    /**
+     * Lay out the blocks in the flyout.
+     *
+     * @param contents The flyout items to lay out.
+     */
+    protected layout_(contents: FlyoutItem[]): void;
+    /**
+     * Determine if a drag delta is toward the workspace, based on the position
+     * and orientation of the flyout. This is used in determineDragIntention_ to
+     * determine if a new block should be created or if the flyout should scroll.
+     *
+     * @param currentDragDeltaXY How far the pointer has moved from the position
+     *     at mouse down, in pixel units.
+     * @returns True if the drag is toward the workspace.
+     */
+    isDragTowardWorkspace(currentDragDeltaXY: Coordinate): boolean;
+    /**
+     * 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;
+    /**
+     * Compute height of flyout.  toolbox.Position mat under each block.
+     * For RTL: Lay out the blocks right-aligned.
+     */
+    protected reflowInternal_(): void;
+}
+//# sourceMappingURL=flyout_horizontal.d.ts.map

package/core/flyout_item.d.ts

@@ -0,0 +1,26 @@
+import type { IBoundedElement } from './interfaces/i_bounded_element.js';
+import type { IFocusableNode } from './interfaces/i_focusable_node.js';
+/**
+ * Representation of an item displayed in a flyout.
+ */
+export declare class FlyoutItem {
+    private element;
+    private type;
+    /**
+     * Creates a new FlyoutItem.
+     *
+     * @param element The element that will be displayed in the flyout.
+     * @param type The type of element. Should correspond to the type of the
+     *     flyout inflater that created this object.
+     */
+    constructor(element: IBoundedElement & IFocusableNode, type: string);
+    /**
+     * Returns the element displayed in the flyout.
+     */
+    getElement(): IBoundedElement & IFocusableNode;
+    /**
+     * Returns the type of flyout element this item represents.
+     */
+    getType(): string;
+}
+//# sourceMappingURL=flyout_item.d.ts.map