blockly 12.4.0 → 12.5.0

package/core/toolbox/separator.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { IToolbox } from '../interfaces/i_toolbox.js';
+import type * as toolbox from '../utils/toolbox.js';
+import { ToolboxItem } from './toolbox_item.js';
+/**
+ * Class for a toolbox separator. This is the thin visual line that appears on
+ * the toolbox. This item is not interactable.
+ */
+export declare class ToolboxSeparator extends ToolboxItem {
+    /** Name used for registering a toolbox separator. */
+    static registrationName: string;
+    /** All the CSS class names that are used to create a separator. */
+    protected cssConfig_: CssConfig;
+    private htmlDiv;
+    /**
+     * @param separatorDef The information needed to create a separator.
+     * @param toolbox The parent toolbox for the separator.
+     */
+    constructor(separatorDef: toolbox.SeparatorInfo, toolbox: IToolbox);
+    init(): void;
+    /**
+     * Creates the DOM for a separator.
+     *
+     * @returns The parent element for the separator.
+     */
+    protected createDom_(): HTMLDivElement;
+    getDiv(): HTMLDivElement;
+    dispose(): void;
+}
+export declare namespace ToolboxSeparator {
+    interface CssConfig {
+        container: string | undefined;
+    }
+}
+export type CssConfig = ToolboxSeparator.CssConfig;
+//# sourceMappingURL=separator.d.ts.map

package/core/toolbox/toolbox.d.ts

@@ -0,0 +1,419 @@
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import * as browserEvents from '../browser_events.js';
+import { DeleteArea } from '../delete_area.js';
+import '../events/events_toolbox_item_select.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 { IFocusableNode } from '../interfaces/i_focusable_node.js';
+import type { IFocusableTree } from '../interfaces/i_focusable_tree.js';
+import type { IKeyboardAccessible } from '../interfaces/i_keyboard_accessible.js';
+import type { ISelectableToolboxItem } from '../interfaces/i_selectable_toolbox_item.js';
+import type { IStyleable } from '../interfaces/i_styleable.js';
+import type { IToolbox } from '../interfaces/i_toolbox.js';
+import type { IToolboxItem } from '../interfaces/i_toolbox_item.js';
+import type { KeyboardShortcut } from '../shortcut_registry.js';
+import { Rect } from '../utils/rect.js';
+import * as toolbox from '../utils/toolbox.js';
+import type { WorkspaceSvg } from '../workspace_svg.js';
+/**
+ * Class for a Toolbox.
+ * Creates the toolbox's DOM.
+ */
+export declare class Toolbox extends DeleteArea implements IAutoHideable, IKeyboardAccessible, IStyleable, IToolbox, IFocusableNode {
+    /**
+     * The unique ID for this component that is used to register with the
+     * ComponentManager.
+     */
+    id: string;
+    protected toolboxDef_: toolbox.ToolboxInfo;
+    private readonly horizontalLayout;
+    /** The HTML container for the toolbox. */
+    HtmlDiv: HTMLDivElement | null;
+    /** The HTML container for the contents of a toolbox. */
+    protected contentsDiv_: HTMLDivElement | null;
+    /** Whether the Toolbox is visible. */
+    protected isVisible_: boolean;
+    /** The width of the toolbox. */
+    protected width_: number;
+    /** The height of the toolbox. */
+    protected height_: number;
+    RTL: boolean;
+    /** The flyout for the toolbox. */
+    private flyout;
+    /** Map from ID to the corresponding toolbox item. */
+    protected contents: Map<string, IToolboxItem>;
+    toolboxPosition: toolbox.Position;
+    /** The currently selected item. */
+    protected selectedItem_: ISelectableToolboxItem | null;
+    /** The previously selected item. */
+    protected previouslySelectedItem_: ISelectableToolboxItem | null;
+    /**
+     * Array holding info needed to unbind event handlers.
+     * Used for disposing.
+     * Ex: [[node, name, func], [node, name, func]].
+     */
+    protected boundEvents_: browserEvents.Data[];
+    /** The workspace this toolbox is on. */
+    protected readonly workspace_: WorkspaceSvg;
+    /** Whether the mouse is currently being clicked. */
+    private mouseDown;
+    /** @param workspace The workspace in which to create new blocks. */
+    constructor(workspace: WorkspaceSvg);
+    /**
+     * Handles the given keyboard shortcut.
+     *
+     * @param _shortcut The shortcut to be handled.
+     * @returns True if the shortcut has been handled, false otherwise.
+     */
+    onShortcut(_shortcut: KeyboardShortcut): boolean;
+    /** Initializes the toolbox */
+    init(): void;
+    /**
+     * Creates the DOM for the toolbox.
+     *
+     * @param workspace The workspace this toolbox is on.
+     * @returns The HTML container for the toolbox.
+     */
+    protected createDom_(workspace: WorkspaceSvg): HTMLDivElement;
+    /**
+     * Creates the container div for the toolbox.
+     *
+     * @returns The HTML container for the toolbox.
+     */
+    protected createContainer_(): HTMLDivElement;
+    /**
+     * Creates the container for all the contents in the toolbox.
+     *
+     * @returns The HTML container for the toolbox contents.
+     */
+    protected createContentsContainer_(): HTMLDivElement;
+    /**
+     * Adds event listeners to the toolbox container div.
+     *
+     * @param container The HTML container for the toolbox.
+     * @param contentsContainer The HTML container for the contents of the
+     *     toolbox.
+     */
+    protected attachEvents_(container: HTMLDivElement, contentsContainer: HTMLDivElement): void;
+    /**
+     * Handles on click events for when the toolbox or toolbox items are clicked.
+     *
+     * @param e Click event to handle.
+     */
+    protected onClick_(e: PointerEvent): void;
+    /**
+     * Handles key down events for the toolbox.
+     *
+     * @param e The key down event.
+     */
+    protected onKeyDown_(e: KeyboardEvent): void;
+    /**
+     * Creates the flyout based on the toolbox layout.
+     *
+     * @returns The flyout for the toolbox.
+     * @throws {Error} If missing a require for `Blockly.HorizontalFlyout`,
+     *     `Blockly.VerticalFlyout`, and no flyout plugin is specified.
+     */
+    protected createFlyout_(): IFlyout;
+    /**
+     * Fills the toolbox with new toolbox items and removes any old contents.
+     *
+     * @param toolboxDef Object holding information for creating a toolbox.
+     * @internal
+     */
+    render(toolboxDef: toolbox.ToolboxInfo): void;
+    /**
+     * Adds all the toolbox items to the toolbox.
+     *
+     * @param toolboxDef Array holding objects containing information on the
+     *     contents of the toolbox.
+     */
+    protected renderContents_(toolboxDef: toolbox.ToolboxItemInfo[]): void;
+    /**
+     * Creates and renders the toolbox item.
+     *
+     * @param toolboxItemDef Any information that can be used to create an item in
+     *     the toolbox.
+     * @param fragment The document fragment to add the child toolbox elements to.
+     */
+    private createToolboxItem;
+    /**
+     * Adds an item to the toolbox.
+     *
+     * @param toolboxItem The item in the toolbox.
+     */
+    protected addToolboxItem_(toolboxItem: IToolboxItem): void;
+    /**
+     * Gets the items in the toolbox.
+     *
+     * @returns The list of items in the toolbox.
+     */
+    getToolboxItems(): IToolboxItem[];
+    /**
+     * Adds a style on the toolbox. Usually used to change the cursor.
+     *
+     * @param style The name of the class to add.
+     * @internal
+     */
+    addStyle(style: string): void;
+    /**
+     * Removes a style from the toolbox. Usually used to change the cursor.
+     *
+     * @param style The name of the class to remove.
+     * @internal
+     */
+    removeStyle(style: string): void;
+    /**
+     * 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;
+    /**
+     * Returns whether the provided block or bubble would be deleted if dropped on
+     * this area.
+     * This method should check if the element is deletable and is always called
+     * before onDragEnter/onDragOver/onDragExit.
+     *
+     * @param element The block or bubble currently being dragged.
+     * @returns Whether the element provided would be deleted if dropped on this
+     *     area.
+     */
+    wouldDelete(element: IDraggable): boolean;
+    /**
+     * Handles when a cursor with a block or bubble enters this drag target.
+     *
+     * @param _dragElement The block or bubble currently being dragged.
+     */
+    onDragEnter(_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;
+    /**
+     * Updates the internal wouldDelete_ state.
+     *
+     * @param wouldDelete The new value for the wouldDelete state.
+     */
+    protected updateWouldDelete_(wouldDelete: boolean): void;
+    /**
+     * Adds or removes the CSS style of the cursor over the toolbox based whether
+     * the block or bubble over it is expected to be deleted if dropped (using the
+     * internal this.wouldDelete_ property).
+     *
+     * @param addStyle Whether the style should be added or removed.
+     */
+    protected updateCursorDeleteStyle_(addStyle: boolean): void;
+    /**
+     * Gets the toolbox item with the given ID.
+     *
+     * @param id The ID of the toolbox item.
+     * @returns The toolbox item with the given ID, or null if no item exists.
+     */
+    getToolboxItemById(id: string): IToolboxItem | null;
+    /**
+     * Gets the width of the toolbox.
+     *
+     * @returns The width of the toolbox.
+     */
+    getWidth(): number;
+    /**
+     * Gets the height of the toolbox.
+     *
+     * @returns The width of the toolbox.
+     */
+    getHeight(): number;
+    /**
+     * Gets the toolbox flyout.
+     *
+     * @returns The toolbox flyout.
+     */
+    getFlyout(): IFlyout | null;
+    /**
+     * Gets the workspace for the toolbox.
+     *
+     * @returns The parent workspace for the toolbox.
+     */
+    getWorkspace(): WorkspaceSvg;
+    /**
+     * Gets the selected item.
+     *
+     * @returns The selected item, or null if no item is currently selected.
+     */
+    getSelectedItem(): ISelectableToolboxItem | null;
+    /**
+     * Gets the previously selected item.
+     *
+     * @returns The previously selected item, or null if no item was previously
+     *     selected.
+     */
+    getPreviouslySelectedItem(): ISelectableToolboxItem | null;
+    /**
+     * Gets whether or not the toolbox is horizontal.
+     *
+     * @returns True if the toolbox is horizontal, false if the toolbox is
+     *     vertical.
+     */
+    isHorizontal(): boolean;
+    /**
+     * Positions the toolbox based on whether it is a horizontal toolbox and
+     * whether the workspace is in rtl.
+     */
+    position(): void;
+    /**
+     * Handles resizing the toolbox when a toolbox item resizes.
+     *
+     * @internal
+     */
+    handleToolboxItemResize(): void;
+    /** Unhighlights any previously selected item. */
+    clearSelection(): void;
+    /**
+     * Updates the category colours and background colour of selected categories.
+     *
+     * @internal
+     */
+    refreshTheme(): void;
+    /**
+     * Updates the flyout's content without closing it.  Should be used in
+     * response to a change in one of the dynamic categories, such as variables or
+     * procedures.
+     */
+    refreshSelection(): void;
+    /**
+     * Shows or hides the toolbox.
+     *
+     * @param isVisible True if toolbox should be visible.
+     */
+    setVisible(isVisible: boolean): 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;
+    /**
+     * Sets the given item as selected.
+     * No-op if the item is not selectable.
+     *
+     * @param newItem The toolbox item to select.
+     */
+    setSelectedItem(newItem: IToolboxItem | null): void;
+    /**
+     * Decides whether the old item should be deselected.
+     *
+     * @param oldItem The previously selected toolbox item.
+     * @param newItem The newly selected toolbox item.
+     * @returns True if the old item should be deselected, false otherwise.
+     */
+    protected shouldDeselectItem_(oldItem: ISelectableToolboxItem | null, newItem: ISelectableToolboxItem | null): boolean;
+    /**
+     * Decides whether the new item should be selected.
+     *
+     * @param oldItem The previously selected toolbox item.
+     * @param newItem The newly selected toolbox item.
+     * @returns True if the new item should be selected, false otherwise.
+     */
+    protected shouldSelectItem_(oldItem: ISelectableToolboxItem | null, newItem: ISelectableToolboxItem | null): boolean;
+    /**
+     * Deselects the given item, marks it as unselected, and updates aria state.
+     *
+     * @param item The previously selected toolbox item which should be
+     *     deselected.
+     */
+    protected deselectItem_(item: ISelectableToolboxItem): void;
+    /**
+     * Selects the given item, marks it selected, and updates aria state.
+     *
+     * @param oldItem The previously selected toolbox item.
+     * @param newItem The newly selected toolbox item.
+     */
+    protected selectItem_(oldItem: ISelectableToolboxItem | null, newItem: ISelectableToolboxItem): void;
+    /**
+     * Selects the toolbox item by its position in the list of toolbox items.
+     *
+     * @param position The position of the item to select.
+     */
+    selectItemByPosition(position: number): void;
+    /**
+     * Decides whether to hide or show the flyout depending on the selected item.
+     *
+     * @param oldItem The previously selected toolbox item.
+     * @param newItem The newly selected toolbox item.
+     */
+    protected updateFlyout_(oldItem: ISelectableToolboxItem | null, newItem: ISelectableToolboxItem | null): void;
+    /**
+     * Emits an event when a new toolbox item is selected.
+     *
+     * @param oldItem The previously selected toolbox item.
+     * @param newItem The newly selected toolbox item.
+     */
+    private fireSelectEvent;
+    /**
+     * Closes the current item if it is expanded, or selects the parent.
+     *
+     * @returns True if a parent category was selected, false otherwise.
+     */
+    private selectParent;
+    /**
+     * Selects the first child of the currently selected item, or nothing if the
+     * toolbox item has no children.
+     *
+     * @returns True if a child category was selected, false otherwise.
+     */
+    private selectChild;
+    /**
+     * Selects the next visible toolbox item.
+     *
+     * @returns True if a next category was selected, false otherwise.
+     */
+    private selectNext;
+    /**
+     * Selects the previous visible toolbox item.
+     *
+     * @returns True if a previous category was selected, false otherwise.
+     */
+    private selectPrevious;
+    /** Disposes of this toolbox. */
+    dispose(): void;
+    /** 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;
+    /** See IFocusableTree.getRootFocusableNode. */
+    getRootFocusableNode(): IFocusableNode;
+    /** See IFocusableTree.getRestoredFocusableNode. */
+    getRestoredFocusableNode(previousNode: IFocusableNode | null): IFocusableNode | null;
+    /** See IFocusableTree.getNestedTrees. */
+    getNestedTrees(): Array<IFocusableTree>;
+    /** See IFocusableTree.lookUpFocusableNode. */
+    lookUpFocusableNode(id: string): IFocusableNode | null;
+    /** See IFocusableTree.onTreeFocus. */
+    onTreeFocus(node: IFocusableNode, _previousTree: IFocusableTree | null): void;
+    /** See IFocusableTree.onTreeBlur. */
+    onTreeBlur(nextTree: IFocusableTree | null): void;
+}
+//# sourceMappingURL=toolbox.d.ts.map

package/core/toolbox/toolbox_item.d.ts

@@ -0,0 +1,109 @@
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * An item in the toolbox.
+ *
+ * @class
+ */
+import type { ICollapsibleToolboxItem } from '../interfaces/i_collapsible_toolbox_item.js';
+import type { IFocusableTree } from '../interfaces/i_focusable_tree.js';
+import type { IToolbox } from '../interfaces/i_toolbox.js';
+import type { IToolboxItem } from '../interfaces/i_toolbox_item.js';
+import type * as toolbox from '../utils/toolbox.js';
+import type { WorkspaceSvg } from '../workspace_svg.js';
+/**
+ * Class for an item in the toolbox.
+ */
+export declare class ToolboxItem implements IToolboxItem {
+    protected id_: string;
+    protected parent_: ICollapsibleToolboxItem | null;
+    protected level_: number;
+    protected toolboxItemDef_: toolbox.ToolboxItemInfo | null;
+    protected workspace_: WorkspaceSvg;
+    /** The toolbox this category belongs to. */
+    protected readonly parentToolbox_: IToolbox;
+    /**
+     * @param toolboxItemDef The JSON defining the toolbox item.
+     * @param parentToolbox The toolbox that holds the toolbox item.
+     * @param opt_parent The parent toolbox item or null if the category does not
+     *     have a parent.
+     */
+    constructor(toolboxItemDef: toolbox.ToolboxItemInfo, parentToolbox: IToolbox, opt_parent?: ICollapsibleToolboxItem);
+    /**
+     * Initializes the toolbox item.
+     * This includes creating the DOM and updating the state of any items based
+     * on the info object.
+     */
+    init(): void;
+    /**
+     * Gets the div for the toolbox item.
+     *
+     * @returns The div for the toolbox item.
+     */
+    getDiv(): Element | null;
+    /**
+     * Gets the HTML element that is clickable.
+     * The parent toolbox element receives clicks. The parent toolbox will add an
+     * ID to this element so it can pass the onClick event to the correct
+     * toolboxItem.
+     *
+     * @returns The HTML element that receives clicks, or null if this item should
+     *     not receive clicks.
+     */
+    getClickTarget(): Element | null;
+    /**
+     * Gets a unique identifier for this toolbox item.
+     *
+     * @returns The ID for the toolbox item.
+     */
+    getId(): string;
+    /**
+     * Gets the parent if the toolbox item is nested.
+     *
+     * @returns The parent toolbox item, or null if this toolbox item is not
+     *     nested.
+     */
+    getParent(): ICollapsibleToolboxItem | null;
+    /**
+     * Gets the nested level of the category.
+     *
+     * @returns The nested level of the category.
+     * @internal
+     */
+    getLevel(): number;
+    /**
+     * Whether the toolbox item is selectable.
+     *
+     * @returns True if the toolbox item can be selected.
+     */
+    isSelectable(): boolean;
+    /**
+     * Whether the toolbox item is collapsible.
+     *
+     * @returns True if the toolbox item is collapsible.
+     */
+    isCollapsible(): boolean;
+    /** Dispose of this toolbox item. No-op by default. */
+    dispose(): void;
+    /**
+     * Sets whether the category is visible or not.
+     * For a category to be visible its parent category must also be expanded.
+     *
+     * @param _isVisible True if category should be visible.
+     */
+    setVisible_(_isVisible: boolean): void;
+    /** 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=toolbox_item.d.ts.map

package/core/tooltip.d.ts

@@ -0,0 +1,118 @@
+/**
+ * @license
+ * Copyright 2011 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * A type which can define a tooltip.
+ * Either a string, an object containing a tooltip property, or a function which
+ * returns either a string, or another arbitrarily nested function which
+ * eventually unwinds to a string.
+ */
+export type TipInfo = string | {
+    tooltip: any;
+} | (() => TipInfo | string);
+/**
+ * A function that renders custom tooltip UI.
+ * 1st parameter: the div element to render content into.
+ * 2nd parameter: the element being moused over (i.e., the element for which the
+ * tooltip should be shown).
+ */
+export type CustomTooltip = (p1: Element, p2: Element) => any;
+/**
+ * Sets a custom function that will be called if present instead of the default
+ * tooltip UI.
+ *
+ * @param customFn A custom tooltip used to render an alternate tooltip UI.
+ */
+export declare function setCustomTooltip(customFn: CustomTooltip): void;
+/**
+ * Gets the custom tooltip function.
+ *
+ * @returns The custom tooltip function, if defined.
+ */
+export declare function getCustomTooltip(): CustomTooltip | undefined;
+/**
+ * Returns whether or not a tooltip is showing
+ *
+ * @returns True if a tooltip is showing
+ */
+export declare function isVisible(): boolean;
+/**
+ * Maximum width (in characters) of a tooltip.
+ */
+export declare const LIMIT = 50;
+/**
+ * Horizontal offset between mouse cursor and tooltip.
+ */
+export declare const OFFSET_X = 0;
+/**
+ * Vertical offset between mouse cursor and tooltip.
+ */
+export declare const OFFSET_Y = 10;
+/**
+ * Radius mouse can move before killing tooltip.
+ */
+export declare const RADIUS_OK = 10;
+/**
+ * Delay before tooltip appears.
+ */
+export declare const HOVER_MS = 750;
+/**
+ * Horizontal padding between tooltip and screen edge.
+ */
+export declare const MARGINS = 5;
+/**
+ * Returns the HTML tooltip container.
+ *
+ * @returns The HTML tooltip container.
+ */
+export declare function getDiv(): HTMLDivElement | null;
+/**
+ * Returns the tooltip text for the given element.
+ *
+ * @param object The object to get the tooltip text of.
+ * @returns The tooltip text of the element.
+ */
+export declare function getTooltipOfObject(object: any | null): string;
+/**
+ * Create the tooltip div and inject it onto the page.
+ */
+export declare function createDom(): void;
+/**
+ * Binds the required mouse events onto an SVG element.
+ *
+ * @param element SVG element onto which tooltip is to be bound.
+ */
+export declare function bindMouseEvents(element: Element): void;
+/**
+ * Unbinds tooltip mouse events from the SVG element.
+ *
+ * @param element SVG element onto which tooltip is bound.
+ */
+export declare function unbindMouseEvents(element: Element | null): void;
+/**
+ * Dispose of the tooltip.
+ *
+ * @internal
+ */
+export declare function dispose(): void;
+/**
+ * Hide the tooltip.
+ */
+export declare function hide(): void;
+/**
+ * Hide any in-progress tooltips and block showing new tooltips until the next
+ * call to unblock().
+ *
+ * @internal
+ */
+export declare function block(): void;
+/**
+ * Unblock tooltips: allow them to be scheduled and shown according to their own
+ * logic.
+ *
+ * @internal
+ */
+export declare function unblock(): void;
+//# sourceMappingURL=tooltip.d.ts.map