blockly 11.0.0-beta.3 → 11.0.0-beta.4

package/core/insertion_marker_previewer.d.ts

@@ -0,0 +1,56 @@
+/**
+ * @license
+ * Copyright 2024 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { BlockSvg } from './block_svg.js';
+import { IConnectionPreviewer } from './interfaces/i_connection_previewer.js';
+import { RenderedConnection } from './rendered_connection.js';
+export declare class InsertionMarkerPreviewer implements IConnectionPreviewer {
+    private readonly workspace;
+    private fadedBlock;
+    private markerConn;
+    private draggedConn;
+    private staticConn;
+    constructor(draggedBlock: BlockSvg);
+    /**
+     * Display a connection preview where the draggedCon connects to the
+     * staticCon, replacing the replacedBlock (currently connected to the
+     * staticCon).
+     *
+     * @param draggedConn The connection on the block stack being dragged.
+     * @param staticConn The connection not being dragged that we are
+     *     connecting to.
+     * @param replacedBlock The block currently connected to the staticCon that
+     *     is being replaced.
+     */
+    previewReplacement(draggedConn: RenderedConnection, staticConn: RenderedConnection, replacedBlock: BlockSvg): void;
+    /**
+     * Display a connection preview where the draggedCon connects to the
+     * staticCon, and no block is being relaced.
+     *
+     * @param draggedConn The connection on the block stack being dragged.
+     * @param staticConn The connection not being dragged that we are
+     *     connecting to.
+     */
+    previewConnection(draggedConn: RenderedConnection, staticConn: RenderedConnection): void;
+    private shouldUseMarkerPreview;
+    private previewMarker;
+    private createInsertionMarker;
+    /**
+     * Gets the connection on the marker block that matches the original
+     * connection on the original block.
+     *
+     * @param orig The original block.
+     * @param marker The marker block (where we want to find the matching
+     *     connection).
+     * @param origConn The original connection.
+     */
+    private getMatchingConnection;
+    /** Hide any previews that are currently displayed. */
+    hidePreview(): void;
+    private hideInsertionMarker;
+    /** Dispose of any references held by this connection previewer. */
+    dispose(): void;
+}
+//# sourceMappingURL=insertion_marker_previewer.d.ts.map

package/core/interfaces/i_comment_icon.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @license
+ * Copyright 2024 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { IIcon } from './i_icon.js';
+import { Size } from '../utils/size.js';
+import { IHasBubble } from './i_has_bubble.js';
+export interface ICommentIcon extends IIcon, IHasBubble {
+    setText(text: string): void;
+    getText(): string;
+    setBubbleSize(size: Size): void;
+    getBubbleSize(): Size;
+}
+/** Checks whether the given object is an ICommentIcon. */
+export declare function isCommentIcon(obj: Object): obj is ICommentIcon;
+//# sourceMappingURL=i_comment_icon.d.ts.map

package/core/interfaces/i_connection_previewer.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { BlockSvg } from '../block_svg';
+import type { RenderedConnection } from '../rendered_connection';
+/**
+ * Displays visual "previews" of where a block will be connected if it is
+ * dropped.
+ */
+export interface IConnectionPreviewer {
+    /**
+     * Display a connection preview where the draggedCon connects to the
+     * staticCon, replacing the replacedBlock (currently connected to the
+     * staticCon).
+     *
+     * @param draggedCon The connection on the block stack being dragged.
+     * @param staticCon The connection not being dragged that we are
+     *     connecting to.
+     * @param replacedBlock The block currently connected to the staticCon that
+     *     is being replaced.
+     */
+    previewReplacement(draggedConn: RenderedConnection, staticConn: RenderedConnection, replacedBlock: BlockSvg): void;
+    /**
+     * Display a connection preview where the draggedCon connects to the
+     * staticCon, and no block is being relaced.
+     *
+     * @param draggedCon The connection on the block stack being dragged.
+     * @param staticCon The connection not being dragged that we are
+     *     connecting to.
+     */
+    previewConnection(draggedConn: RenderedConnection, staticConn: RenderedConnection): void;
+    /** Hide any previews that are currently displayed. */
+    hidePreview(): void;
+    /** Dispose of any references held by this connection previewer. */
+    dispose(): void;
+}
+//# sourceMappingURL=i_connection_previewer.d.ts.map

package/core/registry.d.ts

@@ -18,8 +18,9 @@ import type { Options } from './options.js';
 import type { Renderer } from './renderers/common/renderer.js';
 import type { Theme } from './theme.js';
 import type { ToolboxItem } from './toolbox/toolbox_item.js';
-import { IPaster } from './interfaces/i_paster.js';
-import { ICopyable } from './interfaces/i_copyable.js';
+import type { IPaster } from './interfaces/i_paster.js';
+import type { ICopyable } from './interfaces/i_copyable.js';
+import type { IConnectionPreviewer } from './interfaces/i_connection_previewer.js';
 export declare const TEST_ONLY: {
     typeMap: {
         [key: string]: {
@@ -45,6 +46,7 @@ export declare class Type<_T> {
      */
     toString(): string;
     static CONNECTION_CHECKER: Type<IConnectionChecker>;
+    static CONNECTION_PREVIEWER: Type<IConnectionPreviewer>;
     static CURSOR: Type<Cursor>;
     static EVENT: Type<Abstract>;
     static FIELD: Type<Field<any>>;

package/core/render_management.d.ts

@@ -4,6 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import { BlockSvg } from './block_svg.js';
+import type { WorkspaceSvg } from './workspace_svg.js';
 /**
  * Registers that the given block and all of its parents need to be rerendered,
  * and registers a callback to do so after a delay, to allowf or batching.
@@ -25,7 +26,9 @@ export declare function finishQueuedRenders(): Promise<void>;
  * cases where queueing renders breaks functionality + backwards compatibility
  * (such as rendering icons).
  *
+ * @param workspace If provided, only rerender blocks in this workspace.
+ *
  * @internal
  */
-export declare function triggerQueuedRenders(): void;
+export declare function triggerQueuedRenders(workspace?: WorkspaceSvg): void;
 //# sourceMappingURL=render_management.d.ts.map

package/core/rendered_connection.d.ts

@@ -21,7 +21,7 @@ export declare class RenderedConnection extends Connection {
     private readonly dbOpposite;
     private readonly offsetInBlock;
     private trackedState;
-    private highlightPath;
+    private highlighted;
     /** Connection this connection connects to.  Null if not connected. */
     targetConnection: RenderedConnection | null;
     /**
@@ -130,6 +130,8 @@ export declare class RenderedConnection extends Connection {
     highlight(): void;
     /** Remove the highlighting around this connection. */
     unhighlight(): void;
+    /** Returns true if this connection is highlighted, false otherwise. */
+    isHighlighted(): boolean;
     /**
      * Set whether this connections is tracked in the database or not.
      *

package/core/renderers/common/constants.d.ts

@@ -39,8 +39,8 @@ export interface PuzzleTab {
     type: number;
     width: number;
     height: number;
-    pathDown: string | ((p1: number) => string);
-    pathUp: string | ((p1: number) => string);
+    pathDown: string;
+    pathUp: string;
 }
 /**
  * An object containing sizing and path information about collapsed block
@@ -78,6 +78,10 @@ export type Shape = BaseShape | DynamicShape;
  * @returns Whether the shape is a dynamic shape or not.
  */
 export declare function isDynamicShape(shape: Shape): shape is DynamicShape;
+/** Returns whether the shape is a puzzle tab or not. */
+export declare function isPuzzleTab(shape: Shape): shape is PuzzleTab;
+/** Returns whether the shape is a notch or not. */
+export declare function isNotch(shape: Shape): shape is Notch;
 /**
  * An object that provides constants for rendering blocks.
  */

package/core/renderers/common/drawer.d.ts

@@ -5,6 +5,7 @@
  */
 import type { BlockSvg } from '../../block_svg.js';
 import { Coordinate } from '../../utils.js';
+import { Connection } from '../measurables/connection.js';
 import type { Field } from '../measurables/field.js';
 import type { Icon } from '../measurables/icon.js';
 import type { InlineInput } from '../measurables/inline_input.js';
@@ -134,5 +135,22 @@ export declare class Drawer {
     protected positionNextConnection_(): void;
     /** Position the output connection on a block. */
     protected positionOutputConnection_(): void;
+    /**
+     * Updates the path object to reflect which connections on the block are
+     * highlighted.
+     */
+    protected updateConnectionHighlights(): void;
+    /** Returns a path to highlight the given connection. */
+    drawConnectionHighlightPath(measurable: Connection): void;
+    /**
+     * Returns a path to highlight the given conneciton, assuming it is an
+     * input or output connection.
+     */
+    private getExpressionConnectionHighlightPath;
+    /**
+     * Returns a path to highlight the given conneciton, assuming it is a
+     * next or previous connection.
+     */
+    private getStatementConnectionHighlightPath;
 }
 //# sourceMappingURL=drawer.d.ts.map

package/core/renderers/common/i_path_object.d.ts

@@ -6,7 +6,8 @@
 import type { BlockStyle } from '../../theme.js';
 import type { BlockSvg } from '../../block_svg.js';
 import type { ConstantProvider } from './constants.js';
-import { RenderedConnection } from '../../rendered_connection.js';
+import type { RenderedConnection } from '../../rendered_connection.js';
+import type { Coordinate } from '../../utils/coordinate.js';
 /**
  * An interface for a block's path object.
  *
@@ -101,21 +102,11 @@ export interface IPathObject {
      * @param enable True if the block is movable, false otherwise.
      */
     updateMovable(enabled: boolean): void;
+    /** Adds the given path as a connection highlight for the given connection. */
+    addConnectionHighlight?(connection: RenderedConnection, connectionPath: string, offset: Coordinate, rtl: boolean): void;
     /**
-     * Add or remove styling that shows that if the dragging block is dropped,
-     * this block will be replaced.  If a shadow block, it will disappear.
-     * Otherwise it will bump.
-     *
-     * @param enable True if styling should be added.
-     */
-    updateReplacementFade(enabled: boolean): void;
-    /**
-     * Add or remove styling that shows that if the dragging block is dropped,
-     * this block will be connected to the input.
-     *
-     * @param conn The connection on the input to highlight.
-     * @param enable True if styling should be added.
+     * Removes any highlight associated with the given connection, if it exists.
      */
-    updateShapeForInputHighlight(conn: RenderedConnection, enable: boolean): void;
+    removeConnectionHighlight?(connection: RenderedConnection): void;
 }
 //# sourceMappingURL=i_path_object.d.ts.map

package/core/renderers/common/info.d.ts

@@ -5,6 +5,7 @@
  */
 import type { BlockSvg } from '../../block_svg.js';
 import { Input } from '../../inputs/input.js';
+import type { RenderedConnection } from '../../rendered_connection.js';
 import type { Measurable } from '../measurables/base.js';
 import { BottomRow } from '../measurables/bottom_row.js';
 import { InputRow } from '../measurables/input_row.js';
@@ -14,6 +15,7 @@ import { SpacerRow } from '../measurables/spacer_row.js';
 import { TopRow } from '../measurables/top_row.js';
 import type { ConstantProvider } from './constants.js';
 import type { Renderer } from './renderer.js';
+import { Connection } from '../measurables/connection.js';
 /**
  * An object containing all sizing information needed to draw this block.
  *
@@ -61,8 +63,7 @@ export declare class RenderInfo {
      */
     getRenderer(): Renderer;
     /**
-     * Populate and return an object containing all sizing information needed to
-     * draw this block.
+     * Populate this object with all sizing information needed to draw the block.
      *
      * This measure pass does not propagate changes to the block (although fields
      * may choose to rerender when getSize() is called).  However, calling it
@@ -194,5 +195,7 @@ export declare class RenderInfo {
      * store the y position of each row, and record the height of the full block.
      */
     protected finalize_(): void;
+    /** Returns the connection measurable associated with the given connection. */
+    getMeasureableForConnection(conn: RenderedConnection): Connection | null;
 }
 //# sourceMappingURL=info.d.ts.map

package/core/renderers/common/path_object.d.ts

@@ -5,7 +5,9 @@
  */
 import type { BlockSvg } from '../../block_svg.js';
 import type { Connection } from '../../connection.js';
+import { RenderedConnection } from '../../rendered_connection.js';
 import type { BlockStyle } from '../../theme.js';
+import { Coordinate } from '../../utils/coordinate.js';
 import type { ConstantProvider } from './constants.js';
 import type { IPathObject } from './i_path_object.js';
 /**
@@ -27,6 +29,10 @@ export declare class PathObject implements IPathObject {
     markerSvg: SVGElement | null;
     constants: ConstantProvider;
     style: BlockStyle;
+    /** Highlight paths associated with connections. */
+    private connectionHighlights;
+    /** Locations of connection highlights. */
+    private highlightOffsets;
     /**
      * @param root The root SVG element.
      * @param style The style object to use for colouring.
@@ -138,5 +144,12 @@ export declare class PathObject implements IPathObject {
      * @param _enable True if styling should be added.
      */
     updateShapeForInputHighlight(_conn: Connection, _enable: boolean): void;
+    /** Adds the given path as a connection highlight for the given connection. */
+    addConnectionHighlight(connection: RenderedConnection, connectionPath: string, offset: Coordinate, rtl: boolean): void;
+    private currentHighlightMatchesNew;
+    /**
+     * Removes any highlight associated with the given connection, if it exists.
+     */
+    removeConnectionHighlight(connection: RenderedConnection): void;
 }
 //# sourceMappingURL=path_object.d.ts.map

package/core/renderers/common/renderer.d.ts

@@ -141,6 +141,9 @@ export declare class Renderer implements IRegistrable {
      * @param local The connection currently being dragged.
      * @param topBlock The block currently being dragged.
      * @returns The preview type to display.
+     *
+     * @deprecated v10 - This function is no longer respected. A custom
+     *    IConnectionPreviewer may be able to fulfill the functionality.
      */
     getConnectionPreviewMethod(closest: RenderedConnection, local: RenderedConnection, topBlock: BlockSvg): PreviewType;
     /**

package/core/renderers/measurables/connection.d.ts

@@ -14,6 +14,7 @@ export declare class Connection extends Measurable {
     connectionModel: RenderedConnection;
     shape: Shape;
     isDynamicShape: boolean;
+    highlighted: boolean;
     /**
      * @param constants The rendering constants provider.
      * @param connectionModel The connection object on the block that this

package/core/renderers/zelos/drawer.d.ts

@@ -5,6 +5,7 @@
  */
 import type { BlockSvg } from '../../block_svg.js';
 import { Drawer as BaseDrawer } from '../common/drawer.js';
+import { Connection } from '../measurables/connection.js';
 import type { InlineInput } from '../measurables/inline_input.js';
 import type { Row } from '../measurables/row.js';
 import type { RenderInfo } from './info.js';
@@ -42,6 +43,9 @@ export declare class Drawer extends BaseDrawer {
     /** Add steps to draw a flat bottom row. */
     protected drawFlatBottom_(): void;
     drawInlineInput_(input: InlineInput): void;
+    private getInlineInputPath;
     drawStatementInput_(row: Row): void;
+    /** Returns a path to highlight the given connection. */
+    drawConnectionHighlightPath(measurable: Connection): void;
 }
 //# sourceMappingURL=drawer.d.ts.map

package/core/renderers/zelos/renderer.d.ts

@@ -4,7 +4,6 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import type { BlockSvg } from '../../block_svg.js';
-import type { Connection } from '../../connection.js';
 import { InsertionMarkerManager } from '../../insertion_marker_manager.js';
 import type { Marker } from '../../keyboard_nav/marker.js';
 import type { RenderedConnection } from '../../rendered_connection.js';
@@ -74,7 +73,10 @@ export declare class Renderer extends BaseRenderer {
      * @returns The constant provider.
      */
     getConstants(): ConstantProvider;
-    shouldHighlightConnection(conn: Connection): boolean;
+    /**
+     * @deprecated v10 - This function is no longer respected. A custom
+     *    IConnectionPreviewer may be able to fulfill the functionality.
+     */
     getConnectionPreviewMethod(closest: RenderedConnection, local: RenderedConnection, topBlock: BlockSvg): InsertionMarkerManager.PREVIEW_TYPE;
 }
 //# sourceMappingURL=renderer.d.ts.map

package/core/utils/keycodes.d.ts

@@ -16,7 +16,7 @@ export declare enum KeyCodes {
     MAC_ENTER = 3,
     BACKSPACE = 8,
     TAB = 9,
-    NUM_CENTER = 12,
+    NUM_CENTER = 12,// NUMLOCK on FF/Safari Mac
     ENTER = 13,
     SHIFT = 16,
     CTRL = 17,
@@ -25,18 +25,18 @@ export declare enum KeyCodes {
     CAPS_LOCK = 20,
     ESC = 27,
     SPACE = 32,
-    PAGE_UP = 33,
-    PAGE_DOWN = 34,
-    END = 35,
-    HOME = 36,
-    LEFT = 37,
-    UP = 38,
-    RIGHT = 39,
-    DOWN = 40,
-    PLUS_SIGN = 43,
+    PAGE_UP = 33,// also NUM_NORTH_EAST
+    PAGE_DOWN = 34,// also NUM_SOUTH_EAST
+    END = 35,// also NUM_SOUTH_WEST
+    HOME = 36,// also NUM_NORTH_WEST
+    LEFT = 37,// also NUM_WEST
+    UP = 38,// also NUM_NORTH
+    RIGHT = 39,// also NUM_EAST
+    DOWN = 40,// also NUM_SOUTH
+    PLUS_SIGN = 43,// NOT numpad plus
     PRINT_SCREEN = 44,
-    INSERT = 45,
-    DELETE = 46,
+    INSERT = 45,// also NUM_INSERT
+    DELETE = 46,// also NUM_DELETE
     ZERO = 48,
     ONE = 49,
     TWO = 50,
@@ -47,11 +47,11 @@ export declare enum KeyCodes {
     SEVEN = 55,
     EIGHT = 56,
     NINE = 57,
-    FF_SEMICOLON = 59,
-    FF_EQUALS = 61,
-    FF_DASH = 173,
+    FF_SEMICOLON = 59,// Firefox (Gecko) fires this for semicolon instead of 186
+    FF_EQUALS = 61,// Firefox (Gecko) fires this for equals instead of 187
+    FF_DASH = 173,// Firefox (Gecko) fires this for dash instead of 189
     FF_HASH = 163,
-    QUESTION_MARK = 63,
+    QUESTION_MARK = 63,// needs localization
     AT_SIGN = 64,
     A = 65,
     B = 66,
@@ -79,7 +79,7 @@ export declare enum KeyCodes {
     X = 88,
     Y = 89,
     Z = 90,
-    META = 91,
+    META = 91,// WIN_KEY_LEFT
     WIN_KEY_RIGHT = 92,
     CONTEXT_MENU = 93,
     NUM_ZERO = 96,
@@ -113,22 +113,22 @@ export declare enum KeyCodes {
     SCROLL_LOCK = 145,
     FIRST_MEDIA_KEY = 166,
     LAST_MEDIA_KEY = 183,
-    SEMICOLON = 186,
-    DASH = 189,
-    EQUALS = 187,
-    COMMA = 188,
-    PERIOD = 190,
-    SLASH = 191,
-    APOSTROPHE = 192,
-    TILDE = 192,
-    SINGLE_QUOTE = 222,
-    OPEN_SQUARE_BRACKET = 219,
-    BACKSLASH = 220,
-    CLOSE_SQUARE_BRACKET = 221,
+    SEMICOLON = 186,// needs localization
+    DASH = 189,// needs localization
+    EQUALS = 187,// needs localization
+    COMMA = 188,// needs localization
+    PERIOD = 190,// needs localization
+    SLASH = 191,// needs localization
+    APOSTROPHE = 192,// needs localization
+    TILDE = 192,// needs localization
+    SINGLE_QUOTE = 222,// needs localization
+    OPEN_SQUARE_BRACKET = 219,// needs localization
+    BACKSLASH = 220,// needs localization
+    CLOSE_SQUARE_BRACKET = 221,// needs localization
     WIN_KEY = 224,
-    MAC_FF_META = 224,
-    MAC_WK_CMD_LEFT = 91,
-    MAC_WK_CMD_RIGHT = 93,
+    MAC_FF_META = 224,// Firefox (Gecko) fires this for the meta key instead of 91
+    MAC_WK_CMD_LEFT = 91,// WebKit Left Command key fired, same as META
+    MAC_WK_CMD_RIGHT = 93,// WebKit Right Command key fired, different from META
     WIN_IME = 229,
     VK_NONAME = 252,
     PHANTOM = 255

package/core/utils/size.d.ts

@@ -30,5 +30,15 @@ export declare class Size {
      *     are null.
      */
     static equals(a: Size | null, b: Size | null): boolean;
+    /**
+     * Returns a new size with the maximum width and height values out of both
+     * sizes.
+     */
+    static max(a: Size, b: Size): Size;
+    /**
+     * Returns a new size with the minimum width and height values out of both
+     * sizes.
+     */
+    static min(a: Size, b: Size): Size;
 }
 //# sourceMappingURL=size.d.ts.map

package/core/workspace_audio.d.ts

@@ -13,6 +13,8 @@ export declare class WorkspaceAudio {
     private sounds;
     /** Time that the last sound was played. */
     private lastSound_;
+    /** Whether the audio is muted or not. */
+    private muted;
     /**
      * @param parentWorkspace The parent of the workspace this audio object
      *     belongs to, or null.
@@ -47,5 +49,13 @@ export declare class WorkspaceAudio {
      * @param opt_volume Volume of sound (0-1).
      */
     play(name: string, opt_volume?: number): void;
+    /**
+     * @param muted If true, mute sounds. Otherwise, play them.
+     */
+    setMuted(muted: boolean): void;
+    /**
+     * @returns Whether the audio is currently muted or not.
+     */
+    getMuted(): boolean;
 }
 //# sourceMappingURL=workspace_audio.d.ts.map

package/core/workspace_svg.d.ts

@@ -948,7 +948,6 @@ export declare class WorkspaceSvg extends Workspace implements IASTNodeLocationS
      * Get the grid object for this workspace, or null if there is none.
      *
      * @returns The grid object for this workspace.
-     * @internal
      */
     getGrid(): Grid | null;
     /**

package/core-node.js

@@ -0,0 +1,31 @@
+/**
+ * @license
+ * Copyright 2019 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * @file Blockly core module wrapper for node.js.  This module loads
+ * blockly_compressed.js and jsdom, then calls
+ * Blockly.utils.xml.injectDependencies to supply needed XML-handling
+ * functions to Blocky.
+ *
+ * Note that, unlike index.js, this file does not get a UMD wrapper.
+ * This is because it is only used in node.js environments and so is
+ * guaranteed to be loaded as a CJS module.
+ */
+
+/* eslint-disable */
+'use strict';
+
+const Blockly = require('./blockly_compressed.js');
+const {JSDOM} = require('jsdom');
+
+// Override textToDomDocument and provide node.js alternatives to
+// DOMParser and XMLSerializer.
+if (typeof globalThis.document !== 'object') {
+  const {window} = new JSDOM(`<!DOCTYPE html>`);
+  Blockly.utils.xml.injectDependencies(window);
+}
+
+module.exports = Blockly;