blockly 12.4.0 → 12.4.1

package/core/events/events_viewport.d.ts

@@ -0,0 +1,67 @@
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { Workspace } from '../workspace.js';
+import { AbstractEventJson } from './events_abstract.js';
+import { UiBase } from './events_ui_base.js';
+import { EventType } from './type.js';
+/**
+ * Notifies listeners that the workspace surface's position or scale has
+ * changed.
+ *
+ * Does not notify when the workspace itself resizes.
+ */
+export declare class ViewportChange extends UiBase {
+    /**
+     * Top edge of the visible portion of the workspace, relative to the
+     * workspace origin.
+     */
+    viewTop?: number;
+    /**
+     * The left edge of the visible portion of the workspace, relative to
+     * the workspace origin.
+     */
+    viewLeft?: number;
+    /** The scale of the workpace. */
+    scale?: number;
+    /** The previous scale of the workspace. */
+    oldScale?: number;
+    type: EventType;
+    /**
+     * @param opt_top Top-edge of the visible portion of the workspace, relative
+     *     to the workspace origin. Undefined for a blank event.
+     * @param opt_left Left-edge of the visible portion of the workspace relative
+     *     to the workspace origin. Undefined for a blank event.
+     * @param opt_scale The scale of the workspace. Undefined for a blank event.
+     * @param opt_workspaceId The workspace identifier for this event.
+     *    Undefined for a blank event.
+     * @param opt_oldScale The old scale of the workspace. Undefined for a blank
+     *     event.
+     */
+    constructor(opt_top?: number, opt_left?: number, opt_scale?: number, opt_workspaceId?: string, opt_oldScale?: number);
+    /**
+     * Encode the event as JSON.
+     *
+     * @returns JSON representation.
+     */
+    toJson(): ViewportChangeJson;
+    /**
+     * Deserializes the JSON event.
+     *
+     * @param event The event to append new properties to. Should be a subclass
+     *     of Viewport, but we can't specify that due to the fact that parameters
+     *     to static methods in subclasses must be supertypes of parameters to
+     *     static methods in superclasses.
+     * @internal
+     */
+    static fromJson(json: ViewportChangeJson, workspace: Workspace, event?: any): ViewportChange;
+}
+export interface ViewportChangeJson extends AbstractEventJson {
+    viewTop: number;
+    viewLeft: number;
+    scale: number;
+    oldScale: number;
+}
+//# sourceMappingURL=events_viewport.d.ts.map

package/core/events/predicates.d.ts

@@ -0,0 +1,87 @@
+/**
+ * @license
+ * Copyright 2024 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * @file Predicates for testing Abstract event subclasses based on
+ * their .type properties.  These are useful because there are places
+ * where it is not possible to use instanceof <ClassConstructor> tests
+ * for type narrowing due to load ordering issues that would be caused
+ * by the need to import (rather than just import type) the class
+ * constructors in question.
+ */
+import type { Abstract } from './events_abstract.js';
+import type { BlockChange } from './events_block_change.js';
+import type { BlockCreate } from './events_block_create.js';
+import type { BlockDelete } from './events_block_delete.js';
+import type { BlockDrag } from './events_block_drag.js';
+import type { BlockFieldIntermediateChange } from './events_block_field_intermediate_change.js';
+import type { BlockMove } from './events_block_move.js';
+import type { BubbleOpen } from './events_bubble_open.js';
+import type { Click } from './events_click.js';
+import type { CommentChange } from './events_comment_change.js';
+import type { CommentCollapse } from './events_comment_collapse.js';
+import type { CommentCreate } from './events_comment_create.js';
+import type { CommentDelete } from './events_comment_delete.js';
+import type { CommentDrag } from './events_comment_drag.js';
+import type { CommentMove } from './events_comment_move.js';
+import type { CommentResize } from './events_comment_resize.js';
+import type { Selected } from './events_selected.js';
+import type { ThemeChange } from './events_theme_change.js';
+import type { ToolboxItemSelect } from './events_toolbox_item_select.js';
+import type { TrashcanOpen } from './events_trashcan_open.js';
+import type { VarCreate } from './events_var_create.js';
+import type { VarDelete } from './events_var_delete.js';
+import type { VarRename } from './events_var_rename.js';
+import type { ViewportChange } from './events_viewport.js';
+import type { FinishedLoading } from './workspace_events.js';
+/** @returns true iff event.type is EventType.BLOCK_CREATE */
+export declare function isBlockCreate(event: Abstract): event is BlockCreate;
+/** @returns true iff event.type is EventType.BLOCK_DELETE */
+export declare function isBlockDelete(event: Abstract): event is BlockDelete;
+/** @returns true iff event.type is EventType.BLOCK_CHANGE */
+export declare function isBlockChange(event: Abstract): event is BlockChange;
+/** @returns true iff event.type is EventType.BLOCK_FIELD_INTERMEDIATE_CHANGE */
+export declare function isBlockFieldIntermediateChange(event: Abstract): event is BlockFieldIntermediateChange;
+/** @returns true iff event.type is EventType.BLOCK_MOVE */
+export declare function isBlockMove(event: Abstract): event is BlockMove;
+/** @returns true iff event.type is EventType.VAR_CREATE */
+export declare function isVarCreate(event: Abstract): event is VarCreate;
+/** @returns true iff event.type is EventType.VAR_DELETE */
+export declare function isVarDelete(event: Abstract): event is VarDelete;
+/** @returns true iff event.type is EventType.VAR_RENAME */
+export declare function isVarRename(event: Abstract): event is VarRename;
+/** @returns true iff event.type is EventType.BLOCK_DRAG */
+export declare function isBlockDrag(event: Abstract): event is BlockDrag;
+/** @returns true iff event.type is EventType.SELECTED */
+export declare function isSelected(event: Abstract): event is Selected;
+/** @returns true iff event.type is EventType.CLICK */
+export declare function isClick(event: Abstract): event is Click;
+/** @returns true iff event.type is EventType.BUBBLE_OPEN */
+export declare function isBubbleOpen(event: Abstract): event is BubbleOpen;
+/** @returns true iff event.type is EventType.TRASHCAN_OPEN */
+export declare function isTrashcanOpen(event: Abstract): event is TrashcanOpen;
+/** @returns true iff event.type is EventType.TOOLBOX_ITEM_SELECT */
+export declare function isToolboxItemSelect(event: Abstract): event is ToolboxItemSelect;
+/** @returns true iff event.type is EventType.THEME_CHANGE */
+export declare function isThemeChange(event: Abstract): event is ThemeChange;
+/** @returns true iff event.type is EventType.VIEWPORT_CHANGE */
+export declare function isViewportChange(event: Abstract): event is ViewportChange;
+/** @returns true iff event.type is EventType.COMMENT_CREATE */
+export declare function isCommentCreate(event: Abstract): event is CommentCreate;
+/** @returns true iff event.type is EventType.COMMENT_DELETE */
+export declare function isCommentDelete(event: Abstract): event is CommentDelete;
+/** @returns true iff event.type is EventType.COMMENT_CHANGE */
+export declare function isCommentChange(event: Abstract): event is CommentChange;
+/** @returns true iff event.type is EventType.COMMENT_MOVE */
+export declare function isCommentMove(event: Abstract): event is CommentMove;
+/** @returns true iff event.type is EventType.COMMENT_RESIZE */
+export declare function isCommentResize(event: Abstract): event is CommentResize;
+/** @returns true iff event.type is EventType.COMMENT_DRAG */
+export declare function isCommentDrag(event: Abstract): event is CommentDrag;
+/** @returns true iff event.type is EventType.COMMENT_COLLAPSE */
+export declare function isCommentCollapse(event: Abstract): event is CommentCollapse;
+/** @returns true iff event.type is EventType.FINISHED_LOADING */
+export declare function isFinishedLoading(event: Abstract): event is FinishedLoading;
+//# sourceMappingURL=predicates.d.ts.map

package/core/events/type.d.ts

@@ -0,0 +1,81 @@
+/**
+ * @license
+ * Copyright 2024 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Enum of values for the .type property for event classes (concrete subclasses
+ * of Abstract).
+ */
+export declare enum EventType {
+    /** Type of event that creates a block. */
+    BLOCK_CREATE = "create",
+    /** Type of event that deletes a block. */
+    BLOCK_DELETE = "delete",
+    /** Type of event that changes a block. */
+    BLOCK_CHANGE = "change",
+    /**
+     * Type of event representing an in-progress change to a field of a
+     * block, which is expected to be followed by a block change event.
+     */
+    BLOCK_FIELD_INTERMEDIATE_CHANGE = "block_field_intermediate_change",
+    /** Type of event that moves a block. */
+    BLOCK_MOVE = "move",
+    /** Type of event that creates a variable. */
+    VAR_CREATE = "var_create",
+    /** Type of event that deletes a variable. */
+    VAR_DELETE = "var_delete",
+    /** Type of event that renames a variable. */
+    VAR_RENAME = "var_rename",
+    /** Type of event that changes the type of a variable. */
+    VAR_TYPE_CHANGE = "var_type_change",
+    /**
+     * Type of generic event that records a UI change.
+     *
+     * @deprecated Was only ever intended for internal use.
+     */
+    UI = "ui",
+    /** Type of event that drags a block. */
+    BLOCK_DRAG = "drag",
+    /** Type of event that records a change in selected element. */
+    SELECTED = "selected",
+    /** Type of event that records a click. */
+    CLICK = "click",
+    /** Type of event that records a marker move. */
+    MARKER_MOVE = "marker_move",
+    /** Type of event that records a bubble open. */
+    BUBBLE_OPEN = "bubble_open",
+    /** Type of event that records a trashcan open. */
+    TRASHCAN_OPEN = "trashcan_open",
+    /** Type of event that records a toolbox item select. */
+    TOOLBOX_ITEM_SELECT = "toolbox_item_select",
+    /** Type of event that records a theme change. */
+    THEME_CHANGE = "theme_change",
+    /** Type of event that records a viewport change. */
+    VIEWPORT_CHANGE = "viewport_change",
+    /** Type of event that creates a comment. */
+    COMMENT_CREATE = "comment_create",
+    /** Type of event that deletes a comment. */
+    COMMENT_DELETE = "comment_delete",
+    /** Type of event that changes a comment. */
+    COMMENT_CHANGE = "comment_change",
+    /** Type of event that moves a comment. */
+    COMMENT_MOVE = "comment_move",
+    /** Type of event that resizes a comment. */
+    COMMENT_RESIZE = "comment_resize",
+    /**  Type of event that drags a comment. */
+    COMMENT_DRAG = "comment_drag",
+    /** Type of event that collapses a comment. */
+    COMMENT_COLLAPSE = "comment_collapse",
+    /** Type of event that records a workspace load. */
+    FINISHED_LOADING = "finished_loading"
+}
+/**
+ * List of events that cause objects to be bumped back into the visible
+ * portion of the workspace.
+ *
+ * Not to be confused with bumping so that disconnected connections do not
+ * appear connected.
+ */
+export declare const BUMP_EVENTS: string[];
+//# sourceMappingURL=type.d.ts.map

package/core/events/utils.d.ts

@@ -0,0 +1,211 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { Block } from '../block.js';
+import type { Workspace } from '../workspace.js';
+import type { Abstract } from './events_abstract.js';
+import type { BlockCreate } from './events_block_create.js';
+import type { BlockMove } from './events_block_move.js';
+import type { CommentCreate } from './events_comment_create.js';
+import type { CommentMove } from './events_comment_move.js';
+import type { CommentResize } from './events_comment_resize.js';
+/**
+ * Sets whether events should be added to the undo stack.
+ *
+ * @param newValue True if events should be added to the undo stack.
+ */
+export declare function setRecordUndo(newValue: boolean): void;
+/**
+ * Returns whether or not events will be added to the undo stack.
+ *
+ * @returns True if events will be added to the undo stack.
+ */
+export declare function getRecordUndo(): boolean;
+/**
+ * Type of events that cause objects to be bumped back into the visible
+ * portion of the workspace.
+ *
+ * Not to be confused with bumping so that disconnected connections do not
+ * appear connected.
+ */
+export type BumpEvent = BlockCreate | BlockMove | CommentCreate | CommentMove | CommentResize;
+/**
+ * Enqueue an event to be dispatched to change listeners.
+ *
+ * Notes:
+ *
+ * - Events are enqueued until a timeout, generally after rendering is
+ *   complete or at the end of the current microtask, if not running
+ *   in a browser.
+ * - Queued events are subject to destructive modification by being
+ *   combined with later-enqueued events, but only until they are
+ *   fired.
+ * - Events are dispatched via the fireChangeListener method on the
+ *   affected workspace.
+ *
+ * @param event Any Blockly event.
+ */
+export declare function fire(event: Abstract): void;
+/**
+ * Private version of fireInternal for stubbing in tests.
+ */
+declare function fireInternal(event: Abstract): void;
+/** Dispatch all queued events. */
+declare function fireNow(): void;
+/**
+ * Enqueue an event on FIRE_QUEUE.
+ *
+ * Normally this is equivalent to FIRE_QUEUE.push(event), but if the
+ * enqueued event is a BlockChange event and the most recent event(s)
+ * on the queue are BlockMove events that (re)connect other blocks to
+ * the changed block (and belong to the same event group) then the
+ * enqueued event will be enqueued before those events rather than
+ * after.
+ *
+ * This is a workaround for a problem caused by the fact that
+ * MutatorIcon.prototype.recomposeSourceBlock can only fire a
+ * BlockChange event after the mutating block's compose method
+ * returns, meaning that if the compose method reconnects child blocks
+ * the corresponding BlockMove events are emitted _before_ the
+ * BlockChange event, causing issues with undo, mirroring, etc.; see
+ * https://github.com/google/blockly/issues/8225#issuecomment-2195751783
+ * (and following) for details.
+ */
+declare function enqueueEvent(event: Abstract): void;
+/**
+ * Filter the queued events by merging duplicates, removing null
+ * events and reording BlockChange events.
+ *
+ * History of this function:
+ *
+ * This function was originally added in commit cf257ea5 with the
+ * intention of dramatically reduing the total number of dispatched
+ * events.  Initialy it affected only BlockMove events but others were
+ * added over time.
+ *
+ * Code was added to reorder BlockChange events added in commit
+ * 5578458, for uncertain reasons but most probably as part of an
+ * only-partially-successful attemp to fix problems with event
+ * ordering during block mutations.  This code should probably have
+ * been added to the top of the function, before merging and
+ * null-removal, but was added at the bottom for now-forgotten
+ * reasons.  See these bug investigations for a fuller discussion of
+ * the underlying issue and some of the failures that arose because of
+ * this incomplete/incorrect fix:
+ *
+ * https://github.com/google/blockly/issues/8225#issuecomment-2195751783
+ * https://github.com/google/blockly/issues/2037#issuecomment-2209696351
+ *
+ * Later, in PR #1205 the original O(n^2) implementation was replaced
+ * by a linear-time implementation, though additonal fixes were made
+ * subsequently.
+ *
+ * In August 2024 a number of significant simplifications were made:
+ *
+ * This function was previously called from Workspace.prototype.undo,
+ * but the mutation of events by this function was the cause of issue
+ * #7026 (note that events would combine differently in reverse order
+ * vs. forward order).  The originally-chosen fix for this was the
+ * addition (in PR #7069) of code to fireNow to post-filter the
+ * .undoStack_ and .redoStack_ of any workspace that had just been
+ * involved in dispatching events; this apparently resolved the issue
+ * but added considerable additional complexity and made it difficult
+ * to reason about how events are processed for undo/redo, so both the
+ * call from undo and the post-processing code was removed, and
+ * forward=true was made the default while calling the function with
+ * forward=false was deprecated.
+ *
+ * At the same time, the buggy code to reorder BlockChange events was
+ * replaced by a less-buggy version of the same functionality in a new
+ * function, enqueueEvent, called from fireInternal, thus assuring
+ * that events will be in the correct order at the time filter is
+ * called.
+ *
+ * Additionally, the event merging code was modified so that only
+ * immediately adjacent events would be merged.  This simplified the
+ * implementation while ensuring that the merging of events cannot
+ * cause them to be reordered.
+ *
+ * @param queue Array of events.
+ * @returns Array of filtered events.
+ */
+export declare function filter(queue: Abstract[]): Abstract[];
+/**
+ * Modify pending undo events so that when they are fired they don't land
+ * in the undo stack.  Called by Workspace.clearUndo.
+ */
+export declare function clearPendingUndo(): void;
+/**
+ * Stop sending events.  Every call to this function MUST also call enable.
+ */
+export declare function disable(): void;
+/**
+ * Start sending events.  Unless events were already disabled when the
+ * corresponding call to disable was made.
+ */
+export declare function enable(): void;
+/**
+ * Returns whether events may be fired or not.
+ *
+ * @returns True if enabled.
+ */
+export declare function isEnabled(): boolean;
+/**
+ * Current group.
+ *
+ * @returns ID string.
+ */
+export declare function getGroup(): string;
+/**
+ * Start or stop a group.
+ *
+ * @param state True to start new group, false to end group.
+ *   String to set group explicitly.
+ */
+export declare function setGroup(state: boolean | string): void;
+/**
+ * Private version of setGroup for stubbing in tests.
+ */
+declare function setGroupInternal(state: boolean | string): void;
+/**
+ * Compute a list of the IDs of the specified block and all its descendants.
+ *
+ * @param block The root block.
+ * @returns List of block IDs.
+ * @internal
+ */
+export declare function getDescendantIds(block: Block): string[];
+/**
+ * Decode the JSON into an event.
+ *
+ * @param json JSON representation.
+ * @param workspace Target workspace for event.
+ * @returns The event represented by the JSON.
+ * @throws {Error} if an event type is not found in the registry.
+ */
+export declare function fromJson(json: any, workspace: Workspace): Abstract;
+/**
+ * Gets the class for a specific event type from the registry.
+ *
+ * @param eventType The type of the event to get.
+ * @returns The event class with the given type.
+ */
+export declare function get(eventType: string): new (...p1: any[]) => Abstract;
+/**
+ * Set if a block is disabled depending on whether it is properly connected.
+ * Use this on applications where all blocks should be connected to a top block.
+ *
+ * @param event Custom data for event.
+ */
+export declare function disableOrphans(event: Abstract): void;
+export declare const TEST_ONLY: {
+    FIRE_QUEUE: Abstract[];
+    enqueueEvent: typeof enqueueEvent;
+    fireNow: typeof fireNow;
+    fireInternal: typeof fireInternal;
+    setGroupInternal: typeof setGroupInternal;
+};
+export {};
+//# sourceMappingURL=utils.d.ts.map

package/core/events/workspace_events.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @license
+ * Copyright 2019 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { Workspace } from '../workspace.js';
+import { Abstract as AbstractEvent } from './events_abstract.js';
+import { EventType } from './type.js';
+/**
+ * Notifies listeners when the workspace has finished deserializing from
+ * JSON/XML.
+ */
+export declare class FinishedLoading extends AbstractEvent {
+    isBlank: boolean;
+    recordUndo: boolean;
+    type: EventType;
+    /**
+     * @param opt_workspace The workspace that has finished loading.  Undefined
+     *     for a blank event.
+     */
+    constructor(opt_workspace?: Workspace);
+}
+//# sourceMappingURL=workspace_events.d.ts.map

package/core/extensions.d.ts

@@ -0,0 +1,99 @@
+/**
+ * @license
+ * Copyright 2017 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { Block } from './block.js';
+export declare const TEST_ONLY: {
+    allExtensions: any;
+};
+/**
+ * Registers a new extension function. Extensions are functions that help
+ * initialize blocks, usually adding dynamic behavior such as onchange
+ * handlers and mutators. These are applied using Block.applyExtension(), or
+ * the JSON "extensions" array attribute.
+ *
+ * @param name The name of this extension.
+ * @param initFn The function to initialize an extended block.
+ * @throws {Error} if the extension name is empty, the extension is already
+ *     registered, or extensionFn is not a function.
+ */
+export declare function register<T extends Block>(name: string, initFn: (this: T) => void): void;
+/**
+ * Registers a new extension function that adds all key/value of mixinObj.
+ *
+ * @param name The name of this extension.
+ * @param mixinObj The values to mix in.
+ * @throws {Error} if the extension name is empty or the extension is already
+ *     registered.
+ */
+export declare function registerMixin(name: string, mixinObj: any): void;
+/**
+ * Registers a new extension function that adds a mutator to the block.
+ * At register time this performs some basic sanity checks on the mutator.
+ * The wrapper may also add a mutator dialog to the block, if both compose and
+ * decompose are defined on the mixin.
+ *
+ * @param name The name of this mutator extension.
+ * @param mixinObj The values to mix in.
+ * @param opt_helperFn An optional function to apply after mixing in the object.
+ * @param opt_blockList A list of blocks to appear in the flyout of the mutator
+ *     dialog.
+ * @throws {Error} if the mutation is invalid or can't be applied to the block.
+ */
+export declare function registerMutator(name: string, mixinObj: any, opt_helperFn?: () => any, opt_blockList?: string[]): void;
+/**
+ * Unregisters the extension registered with the given name.
+ *
+ * @param name The name of the extension to unregister.
+ */
+export declare function unregister(name: string): void;
+/**
+ * Returns whether an extension is registered with the given name.
+ *
+ * @param name The name of the extension to check for.
+ * @returns True if the extension is registered.  False if it is not registered.
+ */
+export declare function isRegistered(name: string): boolean;
+/**
+ * Applies an extension method to a block. This should only be called during
+ * block construction.
+ *
+ * @param name The name of the extension.
+ * @param block The block to apply the named extension to.
+ * @param isMutator True if this extension defines a mutator.
+ * @throws {Error} if the extension is not found.
+ */
+export declare function apply(name: string, block: Block, isMutator: boolean): void;
+/**
+ * Calls a function after the page has loaded, possibly immediately.
+ *
+ * @param fn Function to run.
+ * @throws Error Will throw if no global document can be found (e.g., Node.js).
+ * @internal
+ */
+export declare function runAfterPageLoad(fn: () => void): void;
+/**
+ * Builds an extension function that will map a dropdown value to a tooltip
+ * string.
+ *
+ * @param dropdownName The name of the field whose value is the key to the
+ *     lookup table.
+ * @param lookupTable The table of field values to tooltip text.
+ * @returns The extension function.
+ */
+export declare function buildTooltipForDropdown(dropdownName: string, lookupTable: {
+    [key: string]: string;
+}): (this: Block) => void;
+/**
+ * Builds an extension function that will install a dynamic tooltip. The
+ * tooltip message should include the string '%1' and that string will be
+ * replaced with the text of the named field.
+ *
+ * @param msgTemplate The template form to of the message text, with %1
+ *     placeholder.
+ * @param fieldName The field with the replacement text.
+ * @returns The extension function.
+ */
+export declare function buildTooltipWithFieldText(msgTemplate: string, fieldName: string): (this: Block) => void;
+//# sourceMappingURL=extensions.d.ts.map