blockly 12.4.0 → 12.5.0

package/core/gesture.d.ts

@@ -0,0 +1,449 @@
+/**
+ * @license
+ * Copyright 2017 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * The class representing an in-progress gesture, e.g. a drag,
+ * tap, or pinch to zoom.
+ *
+ * @class
+ */
+import './events/events_click.js';
+import type { BlockSvg } from './block_svg.js';
+import { RenderedWorkspaceComment } from './comments.js';
+import type { Field } from './field.js';
+import type { IBubble } from './interfaces/i_bubble.js';
+import { IDragger } from './interfaces/i_dragger.js';
+import type { IFlyout } from './interfaces/i_flyout.js';
+import type { IIcon } from './interfaces/i_icon.js';
+import { Coordinate } from './utils/coordinate.js';
+import { WorkspaceDragger } from './workspace_dragger.js';
+import type { WorkspaceSvg } from './workspace_svg.js';
+/**
+ * Class for one gesture.
+ */
+export declare class Gesture {
+    private readonly creatorWorkspace;
+    /**
+     * The position of the pointer when the gesture started.  Units are CSS
+     * pixels, with (0, 0) at the top left of the browser window (pointer event
+     * clientX/Y).
+     */
+    private mouseDownXY;
+    private currentDragDeltaXY;
+    /**
+     * The bubble that the gesture started on, or null if it did not start on a
+     * bubble.
+     */
+    private startBubble;
+    /**
+     * The field that the gesture started on, or null if it did not start on a
+     * field.
+     */
+    private startField;
+    /**
+     * The icon that the gesture started on, or null if it did not start on an
+     * icon.
+     */
+    private startIcon;
+    /**
+     * The block that the gesture started on, or null if it did not start on a
+     * block.
+     */
+    private startBlock;
+    /**
+     * The comment that the gesture started on, or null if it did not start on a
+     * comment.
+     */
+    private startComment;
+    /**
+     * The block that this gesture targets.  If the gesture started on a
+     * shadow block, this is the first non-shadow parent of the block.  If the
+     * gesture started in the flyout, this is the root block of the block group
+     * that was clicked or dragged.
+     */
+    private targetBlock;
+    /**
+     * The workspace that the gesture started on.  There may be multiple
+     * workspaces on a page; this is more accurate than using
+     * Blockly.common.getMainWorkspace().
+     */
+    protected startWorkspace_: WorkspaceSvg | null;
+    /**
+     * Whether the pointer has at any point moved out of the drag radius.
+     * A gesture that exceeds the drag radius is a drag even if it ends exactly
+     * at its start point.
+     */
+    private hasExceededDragRadius;
+    /**
+     * Array holding info needed to unbind events.
+     * Used for disposing.
+     * Ex: [[node, name, func], [node, name, func]].
+     */
+    private boundEvents;
+    private dragger;
+    /**
+     * The object tracking a workspace or flyout workspace drag, or null if none
+     * is in progress.
+     */
+    private workspaceDragger;
+    /** Whether the gesture is dragging or not. */
+    private dragging;
+    /** The flyout a gesture started in, if any. */
+    private flyout;
+    /** Boolean for sanity-checking that some code is only called once. */
+    private calledUpdateIsDragging;
+    /** Boolean for sanity-checking that some code is only called once. */
+    private gestureHasStarted;
+    /** Boolean used internally to break a cycle in disposal. */
+    protected isEnding_: boolean;
+    /** The event that most recently updated this gesture. */
+    private mostRecentEvent;
+    /** Boolean for whether or not this gesture is a multi-touch gesture. */
+    private multiTouch;
+    /** A map of cached points used for tracking multi-touch gestures. */
+    private cachedPoints;
+    /**
+     * This is the ratio between the starting distance between the touch points
+     * and the most recent distance between the touch points.
+     * Scales between 0 and 1 mean the most recent zoom was a zoom out.
+     * Scales above 1.0 mean the most recent zoom was a zoom in.
+     */
+    private previousScale;
+    /** The starting distance between two touch points. */
+    private startDistance;
+    /** Boolean for whether or not the workspace supports pinch-zoom. */
+    private isPinchZoomEnabled;
+    /**
+     * The owner of the dropdownDiv when this gesture first starts.
+     * Needed because we'll close the dropdown before fields get to
+     * act on their events, and some fields care about who owns
+     * the dropdown.
+     */
+    currentDropdownOwner: Field | null;
+    /**
+     * @param e The event that kicked off this gesture.
+     * @param creatorWorkspace The workspace that created this gesture and has a
+     *     reference to it.
+     */
+    constructor(e: PointerEvent, creatorWorkspace: WorkspaceSvg);
+    /**
+     * Sever all links from this object.
+     *
+     * @internal
+     */
+    dispose(): void;
+    /**
+     * Update internal state based on an event.
+     *
+     * @param e The most recent pointer event.
+     */
+    private updateFromEvent;
+    /**
+     * DO MATH to set currentDragDeltaXY_ based on the most recent pointer
+     * position.
+     *
+     * @param currentXY The most recent pointer position, in pixel units,
+     *     with (0, 0) at the window's top left corner.
+     * @returns True if the drag just exceeded the drag radius for the first time.
+     */
+    private updateDragDelta;
+    /**
+     * Update this gesture to record whether a block is being dragged from the
+     * flyout.
+     * This function should be called on a pointermove event the first time
+     * the drag radius is exceeded.  It should be called no more than once per
+     * gesture. If a block should be dragged from the flyout this function creates
+     * the new block on the main workspace and updates targetBlock_ and
+     * startWorkspace_.
+     *
+     * @returns True if a block is being dragged from the flyout.
+     */
+    private updateIsDraggingFromFlyout;
+    /**
+     * Check whether to start a workspace drag. If a workspace is being dragged,
+     * create the necessary WorkspaceDragger and start the drag.
+     *
+     * This function should be called on a pointermove event the first time
+     * the drag radius is exceeded.  It should be called no more than once per
+     * gesture. If a workspace is being dragged this function creates the
+     * necessary WorkspaceDragger and starts the drag.
+     */
+    private updateIsDraggingWorkspace;
+    /**
+     * Update this gesture to record whether anything is being dragged.
+     * This function should be called on a pointermove event the first time
+     * the drag radius is exceeded.  It should be called no more than once per
+     * gesture.
+     */
+    private updateIsDragging;
+    private createDragger;
+    /**
+     * Start a gesture: update the workspace to indicate that a gesture is in
+     * progress and bind pointermove and pointerup handlers.
+     *
+     * @param e A pointerdown event.
+     * @internal
+     */
+    doStart(e: PointerEvent): void;
+    /**
+     * Bind gesture events.
+     *
+     * @param e A pointerdown event.
+     * @internal
+     */
+    bindMouseEvents(e: PointerEvent): void;
+    /**
+     * Handle a pointerdown event.
+     *
+     * @param e A pointerdown event.
+     * @internal
+     */
+    handleStart(e: PointerEvent): void;
+    /**
+     * Handle a pointermove event.
+     *
+     * @param e A pointermove event.
+     * @internal
+     */
+    handleMove(e: PointerEvent): void;
+    /**
+     * Handle a pointerup event.
+     *
+     * @param e A pointerup event.
+     * @internal
+     */
+    handleUp(e: PointerEvent): void;
+    /**
+     * Handle a pointerdown event and keep track of current
+     * pointers.
+     *
+     * @param e A pointerdown event.
+     * @internal
+     */
+    handleTouchStart(e: PointerEvent): void;
+    /**
+     * Handle a pointermove event and zoom in/out if two pointers
+     * are on the screen.
+     *
+     * @param e A pointermove event.
+     * @internal
+     */
+    handleTouchMove(e: PointerEvent): void;
+    /**
+     * Handle pinch zoom gesture.
+     *
+     * @param e A pointermove event.
+     */
+    private handlePinch;
+    /**
+     * Handle a pointerup event and end the gesture.
+     *
+     * @param e A pointerup event.
+     * @internal
+     */
+    handleTouchEnd(e: PointerEvent): void;
+    /**
+     * Helper function returning the current touch point coordinate.
+     *
+     * @param e A pointer event.
+     * @returns The current touch point coordinate
+     * @internal
+     */
+    getTouchPoint(e: PointerEvent): Coordinate | null;
+    /**
+     * Whether this gesture is part of a multi-touch gesture.
+     *
+     * @returns Whether this gesture is part of a multi-touch gesture.
+     * @internal
+     */
+    isMultiTouch(): boolean;
+    /**
+     * Cancel an in-progress gesture.  If a workspace or block drag is in
+     * progress, end the drag at the most recent location.
+     *
+     * @internal
+     */
+    cancel(): void;
+    /**
+     * Handle a real or faked right-click event by showing a context menu.
+     *
+     * @param e A pointerdown event.
+     * @internal
+     */
+    handleRightClick(e: PointerEvent): void;
+    /**
+     * Handle a pointerdown event on a workspace.
+     *
+     * @param e A pointerdown event.
+     * @param ws The workspace the event hit.
+     * @internal
+     */
+    handleWsStart(e: PointerEvent, ws: WorkspaceSvg): void;
+    /**
+     * Fires a workspace click event.
+     *
+     * @param ws The workspace that a user clicks on.
+     */
+    private fireWorkspaceClick;
+    /**
+     * Handle a pointerdown event on a flyout.
+     *
+     * @param e A pointerdown event.
+     * @param flyout The flyout the event hit.
+     * @internal
+     */
+    handleFlyoutStart(e: PointerEvent, flyout: IFlyout): void;
+    /**
+     * Handle a pointerdown event on a block.
+     *
+     * @param e A pointerdown event.
+     * @param block The block the event hit.
+     * @internal
+     */
+    handleBlockStart(e: PointerEvent, block: BlockSvg): void;
+    /**
+     * Handle a pointerdown event on a bubble.
+     *
+     * @param e A pointerdown event.
+     * @param bubble The bubble the event hit.
+     * @internal
+     */
+    handleBubbleStart(e: PointerEvent, bubble: IBubble): void;
+    /**
+     * Handle a pointerdown event on a workspace comment.
+     *
+     * @param e A pointerdown event.
+     * @param comment The comment the event hit.
+     * @internal
+     */
+    handleCommentStart(e: PointerEvent, comment: RenderedWorkspaceComment): void;
+    /** Execute a field click. */
+    private doFieldClick;
+    /** Execute an icon click. */
+    private doIconClick;
+    /** Execute a block click. */
+    private doBlockClick;
+    /**
+     * Execute a workspace click. When in accessibility mode shift clicking will
+     * move the cursor.
+     *
+     * @param _e A pointerup event.
+     */
+    private doWorkspaceClick;
+    /**
+     * Record the field that a gesture started on.
+     *
+     * @param field The field the gesture started on.
+     * @internal
+     */
+    setStartField<T>(field: Field<T>): void;
+    /**
+     * Record the icon that a gesture started on.
+     *
+     * @param icon The icon the gesture started on.
+     * @internal
+     */
+    setStartIcon(icon: IIcon): void;
+    /**
+     * Record the bubble that a gesture started on
+     *
+     * @param bubble The bubble the gesture started on.
+     * @internal
+     */
+    setStartBubble(bubble: IBubble): void;
+    /**
+     * Record the comment that a gesture started on
+     *
+     * @param comment The comment the gesture started on.
+     * @internal
+     */
+    setStartComment(comment: RenderedWorkspaceComment): void;
+    /**
+     * Record the block that a gesture started on, and set the target block
+     * appropriately.
+     *
+     * @param block The block the gesture started on.
+     * @internal
+     */
+    setStartBlock(block: BlockSvg): void;
+    /**
+     * Record the block that a gesture targets, meaning the block that will be
+     * dragged if this turns into a drag.  If this block is a shadow, that will be
+     * its first non-shadow parent.
+     *
+     * @param block The block the gesture targets.
+     */
+    private setTargetBlock;
+    /**
+     * Record the workspace that a gesture started on.
+     *
+     * @param ws The workspace the gesture started on.
+     */
+    private setStartWorkspace;
+    /**
+     * Record the flyout that a gesture started on.
+     *
+     * @param flyout The flyout the gesture started on.
+     */
+    private setStartFlyout;
+    /**
+     * Whether this gesture is a click on a bubble.  This should only be called
+     * when ending a gesture (pointerup).
+     *
+     * @returns Whether this gesture was a click on a bubble.
+     */
+    private isBubbleClick;
+    private isCommentClick;
+    /**
+     * Whether this gesture is a click on a block.  This should only be called
+     * when ending a gesture (pointerup).
+     *
+     * @returns Whether this gesture was a click on a block.
+     */
+    private isBlockClick;
+    /**
+     * Whether this gesture is a click on a field that should be handled.  This should only be called
+     * when ending a gesture (pointerup).
+     *
+     * @returns Whether this gesture was a click on a field.
+     */
+    private isFieldClick;
+    /** @returns Whether this gesture is a click on an icon that should be handled. */
+    private isIconClick;
+    /**
+     * Whether this gesture is a click on a workspace.  This should only be called
+     * when ending a gesture (pointerup).
+     *
+     * @returns Whether this gesture was a click on a workspace.
+     */
+    private isWorkspaceClick;
+    /** Returns the current dragger if the gesture is a drag. */
+    getCurrentDragger(): WorkspaceDragger | IDragger | null;
+    /**
+     * Whether this gesture is a drag of either a workspace or block.
+     * This function is called externally to block actions that cannot be taken
+     * mid-drag (e.g. using the keyboard to delete the selected blocks).
+     *
+     * @returns True if this gesture is a drag of a workspace or block.
+     * @internal
+     */
+    isDragging(): boolean;
+    /**
+     * Whether this gesture has already been started.  In theory every pointerdown
+     * has a corresponding pointerup, but in reality it is possible to lose a
+     * pointerup, leaving an in-process gesture hanging.
+     *
+     * @returns Whether this gesture was a click on a workspace.
+     * @internal
+     */
+    hasStarted(): boolean;
+    /**
+     * Is a drag or other gesture currently in progress on any workspace?
+     *
+     * @returns True if gesture is occurring.
+     */
+    static inProgress(): boolean;
+}
+//# sourceMappingURL=gesture.d.ts.map

package/core/grid.d.ts

@@ -0,0 +1,124 @@
+/**
+ * @license
+ * Copyright 2017 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Object for configuring and updating a workspace grid in
+ * Blockly.
+ *
+ * @class
+ */
+import { GridOptions } from './options.js';
+import { Coordinate } from './utils/coordinate.js';
+/**
+ * Class for a workspace's grid.
+ */
+export declare class Grid {
+    private pattern;
+    private spacing;
+    private length;
+    private scale;
+    private readonly line1;
+    private readonly line2;
+    private snapToGrid;
+    /**
+     * @param pattern The grid's SVG pattern, created during injection.
+     * @param options A dictionary of normalized options for the grid.
+     *     See grid documentation:
+     *     https://developers.google.com/blockly/guides/configure/web/grid
+     */
+    constructor(pattern: SVGElement, options: GridOptions);
+    /**
+     * Sets the spacing between the centers of the grid lines.
+     *
+     * This does not trigger snapping to the newly spaced grid. If you want to
+     * snap blocks to the grid programmatically that needs to be triggered
+     * on individual top-level blocks. The next time a block is dragged and
+     * dropped it will snap to the grid if snapping to the grid is enabled.
+     */
+    setSpacing(spacing: number): void;
+    /**
+     * Get the spacing of the grid points (in px).
+     *
+     * @returns The spacing of the grid points.
+     */
+    getSpacing(): number;
+    /** Sets the length of the grid lines. */
+    setLength(length: number): void;
+    /** Get the length of the grid lines (in px). */
+    getLength(): number;
+    /**
+     * Sets whether blocks should snap to the grid or not.
+     *
+     * Setting this to true does not trigger snapping. If you want to snap blocks
+     * to the grid programmatically that needs to be triggered on individual
+     * top-level blocks. The next time a block is dragged and dropped it will
+     * snap to the grid.
+     */
+    setSnapToGrid(snap: boolean): void;
+    /**
+     * Whether blocks should snap to the grid.
+     *
+     * @returns True if blocks should snap, false otherwise.
+     */
+    shouldSnap(): boolean;
+    /**
+     * Get the ID of the pattern element, which should be randomized to avoid
+     * conflicts with other Blockly instances on the page.
+     *
+     * @returns The pattern ID.
+     * @internal
+     */
+    getPatternId(): string;
+    /**
+     * Update the grid with a new scale.
+     *
+     * @param scale The new workspace scale.
+     * @internal
+     */
+    update(scale: number): void;
+    /**
+     * Set the attributes on one of the lines in the grid.  Use this to update the
+     * length and stroke width of the grid lines.
+     *
+     * @param line Which line to update.
+     * @param width The new stroke size (in px).
+     * @param x1 The new x start position of the line (in px).
+     * @param x2 The new x end position of the line (in px).
+     * @param y1 The new y start position of the line (in px).
+     * @param y2 The new y end position of the line (in px).
+     */
+    private setLineAttributes;
+    /**
+     * Move the grid to a new x and y position, and make sure that change is
+     * visible.
+     *
+     * @param x The new x position of the grid (in px).
+     * @param y The new y position of the grid (in px).
+     * @internal
+     */
+    moveTo(x: number, y: number): void;
+    /**
+     * Given a coordinate, return the nearest coordinate aligned to the grid.
+     *
+     * @param xy A workspace coordinate.
+     * @returns Workspace coordinate of nearest grid point.
+     *   If there's no change, return the same coordinate object.
+     */
+    alignXY(xy: Coordinate): Coordinate;
+    /**
+     * Create the DOM for the grid described by options.
+     *
+     * @param rnd A random ID to append to the pattern's ID.
+     * @param gridOptions The object containing grid configuration.
+     * @param defs The root SVG element for this workspace's defs.
+     * @param injectionDiv The div containing the parent workspace and all related
+     *   workspaces and block containers. CSS variables representing SVG patterns
+     *   will be scoped to this container.
+     * @returns The SVG element for the grid pattern.
+     * @internal
+     */
+    static createDom(rnd: string, gridOptions: GridOptions, defs: SVGElement, injectionDiv?: HTMLElement): SVGElement;
+}
+//# sourceMappingURL=grid.d.ts.map

package/core/icons/comment_icon.d.ts

@@ -0,0 +1,134 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { Block } from '../block.js';
+import { TextInputBubble } from '../bubbles/textinput_bubble.js';
+import type { IHasBubble } from '../interfaces/i_has_bubble.js';
+import type { ISerializable } from '../interfaces/i_serializable.js';
+import { Coordinate } from '../utils.js';
+import { Size } from '../utils/size.js';
+import { Icon } from './icon.js';
+import { IconType } from './icon_types.js';
+/**
+ * An icon which allows the user to add comment text to a block.
+ */
+export declare class CommentIcon extends Icon implements IHasBubble, ISerializable {
+    protected readonly sourceBlock: Block;
+    /** The type string used to identify this icon. */
+    static readonly TYPE: IconType<import("../interfaces/i_comment_icon.js").ICommentIcon>;
+    /**
+     * The weight this icon has relative to other icons. Icons with more positive
+     * weight values are rendered farther toward the end of the block.
+     */
+    static readonly WEIGHT = 3;
+    /** The bubble used to show comment text to the user. */
+    private textInputBubble;
+    /** The text of this comment. */
+    private text;
+    /** The size of this comment (which is applied to the editable bubble). */
+    private bubbleSize;
+    /** The location of the comment bubble in workspace coordinates. */
+    private bubbleLocation?;
+    /**
+     * The visibility of the bubble for this comment.
+     *
+     * This is used to track what the visible state /should/ be, not necessarily
+     * what it currently /is/. E.g. sometimes this will be true, but the block
+     * hasn't been rendered yet, so the bubble will not currently be visible.
+     */
+    private bubbleVisiblity;
+    constructor(sourceBlock: Block);
+    getType(): IconType<CommentIcon>;
+    initView(pointerdownListener: (e: PointerEvent) => void): void;
+    dispose(): void;
+    getWeight(): number;
+    getSize(): Size;
+    applyColour(): void;
+    /**
+     * Updates the state of the bubble (editable / noneditable) to reflect the
+     * state of the bubble if the bubble is currently shown.
+     */
+    updateEditable(): Promise<void>;
+    onLocationChange(blockOrigin: Coordinate): void;
+    /** Sets the text of this comment. Updates any bubbles if they are visible. */
+    setText(text: string): void;
+    /** Returns the text of this comment. */
+    getText(): string;
+    /**
+     * Sets the size of the editable bubble for this comment. Resizes the
+     * bubble if it is visible.
+     */
+    setBubbleSize(size: Size): void;
+    /** @returns the size of the editable bubble for this comment. */
+    getBubbleSize(): Size;
+    /**
+     * Sets the location of the comment bubble in the workspace.
+     */
+    setBubbleLocation(location: Coordinate): void;
+    /**
+     * @returns the location of the comment bubble in the workspace.
+     */
+    getBubbleLocation(): Coordinate | undefined;
+    /**
+     * @returns the state of the comment as a JSON serializable value if the
+     * comment has text. Otherwise returns null.
+     */
+    saveState(): CommentState | null;
+    /** Applies the given state to this comment. */
+    loadState(state: CommentState): void;
+    onClick(): void;
+    isClickableInFlyout(): boolean;
+    /**
+     * Updates the text of this comment in response to changes in the text of
+     * the input bubble.
+     */
+    onTextChange(): void;
+    /**
+     * Updates the size of this icon in response to changes in the size of the
+     * input bubble.
+     */
+    onSizeChange(): void;
+    onBubbleLocationChange(): void;
+    bubbleIsVisible(): boolean;
+    setBubbleVisible(visible: boolean): Promise<void>;
+    /** See IHasBubble.getBubble. */
+    getBubble(): TextInputBubble | null;
+    /**
+     * Shows the editable text bubble for this comment, and adds change listeners
+     * to update the state of this icon in response to changes in the bubble.
+     */
+    private showEditableBubble;
+    /** Shows the non editable text bubble for this comment. */
+    private showNonEditableBubble;
+    protected createBubble(): void;
+    /** Hides any open bubbles owned by this comment. */
+    private hideBubble;
+    /**
+     * @returns the location the bubble should be anchored to.
+     *     I.E. the middle of this icon.
+     */
+    private getAnchorLocation;
+    /**
+     * @returns the rect the bubble should avoid overlapping.
+     *     I.E. the block that owns this icon.
+     */
+    private getBubbleOwnerRect;
+}
+/** The save state format for a comment icon. */
+export interface CommentState {
+    /** The text of the comment. */
+    text?: string;
+    /** True if the comment is open, false otherwise. */
+    pinned?: boolean;
+    /** The height of the comment bubble. */
+    height?: number;
+    /** The width of the comment bubble. */
+    width?: number;
+    /** The X coordinate of the comment bubble. */
+    x?: number;
+    /** The Y coordinate of the comment bubble. */
+    y?: number;
+}
+//# sourceMappingURL=comment_icon.d.ts.map