blockly 10.2.0-beta.0 → 10.2.0-beta.2

package/core/block.d.ts

@@ -3,6 +3,11 @@
  * Copyright 2011 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
+/**
+ * The class representing one block.
+ *
+ * @class
+ */
 import './events/events_block_change.js';
 import './events/events_block_create.js';
 import './events/events_block_delete.js';
@@ -76,8 +81,14 @@ export declare class Block implements IASTNodeLocation, IDeletable {
      * An optional serialization method for defining how to serialize the
      * block's extra state (eg mutation state) to something JSON compatible.
      * This must be coupled with defining `loadExtraState`.
+     *
+     * @param doFullSerialization Whether or not to serialize the full state of
+     *     the extra state (rather than possibly saving a reference to some
+     *     state). This is used during copy-paste. See the
+     *     {@link https://developers.devsite.google.com/blockly/guides/create-custom-blocks/extensions#full_serialization_and_backing_data | block serialization docs}
+     *     for more information.
      */
-    saveExtraState?: () => any;
+    saveExtraState?: (doFullSerialization?: boolean) => any;
     /**
      * An optional serialization method for defining how to deserialize the
      * block's extra state (eg mutation state) from something JSON compatible.
@@ -430,6 +441,11 @@ export declare class Block implements IASTNodeLocation, IDeletable {
      * @returns True if this block has been disposed of / deleted.
      */
     isDisposed(): boolean;
+    /**
+     * @returns True if this block is a value block with a single editable field.
+     * @internal
+     */
+    isSimpleReporter(): boolean;
     /**
      * Find the connection on this block that corresponds to the given connection
      * on the other block.

package/core/block_dragger.d.ts

@@ -3,6 +3,11 @@
  * Copyright 2017 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
+/**
+ * Methods for dragging a block visually.
+ *
+ * @class
+ */
 import './events/events_block_drag.js';
 import type { BlockSvg } from './block_svg.js';
 import type { Icon } from './icons/icon.js';

package/core/block_svg.d.ts

@@ -3,6 +3,11 @@
  * Copyright 2012 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
+/**
+ * Methods for graphically rendering a block as SVG.
+ *
+ * @class
+ */
 import './events/events_selected.js';
 import { Block } from './block.js';
 import { CommentIcon } from './icons/comment_icon.js';
@@ -426,9 +431,11 @@ export declare class BlockSvg extends Block implements IASTNodeLocationSvg, IBou
      * order that they are in the DOM.  By placing this block first within the
      * block group's <g>, it will render on top of any other blocks.
      *
+     * @param blockOnly: True to only move this block to the front without
+     *     adjusting its parents.
      * @internal
      */
-    bringToFront(): void;
+    bringToFront(blockOnly?: boolean): void;
     /**
      * Set whether this block can chain onto the bottom of another block.
      *
@@ -565,11 +572,14 @@ export declare class BlockSvg extends Block implements IASTNodeLocationSvg, IBou
      * or an insertion marker.
      *
      * @param sourceConnection The connection on the moving block's stack.
-     * @param targetConnection The connection that should stay stationary as this
-     *     block is positioned.
+     * @param originalOffsetToTarget The connection original offset to the target connection
+     * @param originalOffsetInBlock The connection original offset in its block
      * @internal
      */
-    positionNearConnection(sourceConnection: RenderedConnection, targetConnection: RenderedConnection): void;
+    positionNearConnection(sourceConnection: RenderedConnection, originalOffsetToTarget: {
+        x: number;
+        y: number;
+    }, originalOffsetInBlock: Coordinate): void;
     /**
      * Find all the blocks that are directly nested inside this one.
      * Includes value and statement inputs, as well as any following statement.

package/core/component_manager.d.ts

@@ -3,6 +3,11 @@
  * Copyright 2021 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
+/**
+ * Manager for all items registered with the workspace.
+ *
+ * @class
+ */
 import type { IAutoHideable } from './interfaces/i_autohideable.js';
 import type { IComponent } from './interfaces/i_component.js';
 import type { IDeleteArea } from './interfaces/i_delete_area.js';

package/core/connection.d.ts

@@ -3,6 +3,11 @@
  * Copyright 2011 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
+/**
+ * Components for creating connections between blocks.
+ *
+ * @class
+ */
 import type { Block } from './block.js';
 import type { Input } from './inputs/input.js';
 import type { IASTNodeLocationWithBlock } from './interfaces/i_ast_node_location_with_block.js';

package/core/contextmenu.d.ts

@@ -4,7 +4,9 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import type { Block } from './block.js';
+import type { BlockSvg } from './block_svg.js';
 import type { ContextMenuOption, LegacyContextMenuOption } from './contextmenu_registry.js';
+import * as serializationBlocks from './serialization/blocks.js';
 import { WorkspaceCommentSvg } from './workspace_comment_svg.js';
 import type { WorkspaceSvg } from './workspace_svg.js';
 /**
@@ -37,13 +39,13 @@ export declare function hide(): void;
 export declare function dispose(): void;
 /**
  * Create a callback function that creates and configures a block,
- *   then places the new block next to the original.
+ *   then places the new block next to the original and returns it.
  *
  * @param block Original block.
- * @param xml XML representation of new block.
+ * @param state XML or JSON object representation of the new block.
  * @returns Function that creates a block.
  */
-export declare function callbackFactory(block: Block, xml: Element): () => void;
+export declare function callbackFactory(block: Block, state: Element | serializationBlocks.State): () => BlockSvg;
 /**
  * Make a context menu option for deleting the current workspace comment.
  *

package/core/contextmenu_registry.d.ts

@@ -3,6 +3,11 @@
  * Copyright 2020 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
+/**
+ * Registry for context menu option items.
+ *
+ * @class
+ */
 import type { BlockSvg } from './block_svg.js';
 import type { WorkspaceSvg } from './workspace_svg.js';
 /**
@@ -74,7 +79,7 @@ export declare namespace ContextMenuRegistry {
     interface RegistryItem {
         callback: (p1: Scope) => void;
         scopeType: ScopeType;
-        displayText: ((p1: Scope) => string) | string;
+        displayText: ((p1: Scope) => string | HTMLElement) | string | HTMLElement;
         preconditionFn: (p1: Scope) => string;
         weight: number;
         id: string;
@@ -83,7 +88,7 @@ export declare namespace ContextMenuRegistry {
      * A menu item as presented to contextmenu.js.
      */
     interface ContextMenuOption {
-        text: string;
+        text: string | HTMLElement;
         enabled: boolean;
         callback: (p1: Scope) => void;
         scope: Scope;

package/core/drag_target.d.ts

@@ -3,6 +3,12 @@
  * Copyright 2021 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
+/**
+ * The abstract class for a component with custom behaviour when a
+ * block or bubble is dragged over or dropped on top of it.
+ *
+ * @class
+ */
 import type { IDragTarget } from './interfaces/i_drag_target.js';
 import type { IDraggable } from './interfaces/i_draggable.js';
 import type { Rect } from './utils/rect.js';

package/core/dropdowndiv.d.ts

@@ -4,6 +4,11 @@
  * All rights reserved.
  * SPDX-License-Identifier: Apache-2.0
  */
+/**
+ * A div that floats on top of the workspace, for drop-down menus.
+ *
+ * @class
+ */
 import type { BlockSvg } from './block_svg.js';
 import type { Field } from './field.js';
 /**

package/core/events/events_block_base.d.ts

@@ -3,6 +3,11 @@
  * Copyright 2018 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
+/**
+ * Base class for all types of block events.
+ *
+ * @class
+ */
 import type { Block } from '../block.js';
 import type { Workspace } from '../workspace.js';
 import { Abstract as AbstractEvent, AbstractEventJson } from './events_abstract.js';

package/core/events/events_block_change.d.ts

@@ -3,6 +3,11 @@
  * Copyright 2018 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
+/**
+ * Class for a block change event.
+ *
+ * @class
+ */
 import type { Block } from '../block.js';
 import type { BlockSvg } from '../block_svg.js';
 import { Workspace } from '../workspace.js';

package/core/events/events_block_create.d.ts

@@ -3,6 +3,11 @@
  * Copyright 2018 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
+/**
+ * Class for a block creation event.
+ *
+ * @class
+ */
 import type { Block } from '../block.js';
 import * as blocks from '../serialization/blocks.js';
 import { BlockBase, BlockBaseJson } from './events_block_base.js';

package/core/events/events_block_delete.d.ts

@@ -3,6 +3,11 @@
  * Copyright 2018 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
+/**
+ * Class for a block delete event.
+ *
+ * @class
+ */
 import type { Block } from '../block.js';
 import * as blocks from '../serialization/blocks.js';
 import { BlockBase, BlockBaseJson } from './events_block_base.js';

package/core/events/events_block_drag.d.ts

@@ -3,6 +3,11 @@
  * Copyright 2020 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
+/**
+ * Events fired as a block drag.
+ *
+ * @class
+ */
 import type { Block } from '../block.js';
 import { AbstractEventJson } from './events_abstract.js';
 import { UiBase } from './events_ui_base.js';

package/core/events/events_block_field_intermediate_change.d.ts

@@ -3,6 +3,12 @@
  * Copyright 2023 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
+/**
+ * Class for an event representing an intermediate change to a block's field's
+ * value.
+ *
+ * @class
+ */
 import type { Block } from '../block.js';
 import { Workspace } from '../workspace.js';
 import { BlockBase, BlockBaseJson } from './events_block_base.js';

package/core/events/events_block_move.d.ts

@@ -3,6 +3,11 @@
  * Copyright 2018 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
+/**
+ * Class for a block move event.
+ *
+ * @class
+ */
 import type { Block } from '../block.js';
 import { Coordinate } from '../utils/coordinate.js';
 import { BlockBase, BlockBaseJson } from './events_block_base.js';

package/core/events/events_bubble_open.d.ts

@@ -3,6 +3,11 @@
  * Copyright 2020 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
+/**
+ * Events fired as a result of bubble open.
+ *
+ * @class
+ */
 import type { AbstractEventJson } from './events_abstract.js';
 import type { BlockSvg } from '../block_svg.js';
 import { UiBase } from './events_ui_base.js';

package/core/events/events_click.d.ts

@@ -3,6 +3,11 @@
  * Copyright 2020 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
+/**
+ * Events fired as a result of UI click in Blockly's editor.
+ *
+ * @class
+ */
 import type { Block } from '../block.js';
 import { AbstractEventJson } from './events_abstract.js';
 import { UiBase } from './events_ui_base.js';

package/core/events/events_marker_move.d.ts

@@ -3,6 +3,11 @@
  * Copyright 2020 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
+/**
+ * Events fired as a result of a marker move.
+ *
+ * @class
+ */
 import type { Block } from '../block.js';
 import { ASTNode } from '../keyboard_nav/ast_node.js';
 import type { Workspace } from '../workspace.js';

package/core/events/events_ui_base.d.ts

@@ -3,6 +3,12 @@
  * Copyright 2020 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
+/**
+ * Base class for events fired as a result of UI actions in
+ * Blockly's editor.
+ *
+ * @class
+ */
 import { Abstract as AbstractEvent } from './events_abstract.js';
 /**
  * Base class for a UI event.

package/core/events/events_var_base.d.ts

@@ -3,6 +3,11 @@
  * Copyright 2018 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
+/**
+ * Abstract class for a variable event.
+ *
+ * @class
+ */
 import type { VariableModel } from '../variable_model.js';
 import { Abstract as AbstractEvent, AbstractEventJson } from './events_abstract.js';
 import type { Workspace } from '../workspace.js';

package/core/field.d.ts

@@ -3,6 +3,13 @@
  * Copyright 2012 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
+/**
+ * Field.  Used for editable titles, variables, etc.
+ * This is an abstract class that defines the UI on the block.  Actual
+ * instances would be FieldTextInput, FieldDropdown, etc.
+ *
+ * @class
+ */
 import './events/events_block_change.js';
 import type { Block } from './block.js';
 import type { Input } from './inputs/input.js';
@@ -44,9 +51,7 @@ export declare abstract class Field<T = any> implements IASTNodeLocationSvg, IAS
      * the prototype.
      *
      * Example:
-     * ```typescript
-     * FieldImage.prototype.DEFAULT_VALUE = null;
-     * ```
+     * `FieldImage.prototype.DEFAULT_VALUE = null;`
      */
     DEFAULT_VALUE: T | null;
     /** Non-breaking space. */
@@ -195,6 +200,15 @@ export declare abstract class Field<T = any> implements IASTNodeLocationSvg, IAS
      * No-op by default.
      */
     initModel(): void;
+    /**
+     * Defines whether this field should take up the full block or not.
+     *
+     * Be cautious when overriding this function. It may not work as you expect /
+     * intend because the behavior was kind of hacked in. If you are thinking
+     * about overriding this function, post on the forum with your intended
+     * behavior to see if there's another approach.
+     */
+    protected isFullBlockField(): boolean;
     /**
      * Create a field border rect element. Not to be overridden by subclasses.
      * Instead modify the result of the function inside initView, or create a
@@ -236,6 +250,9 @@ export declare abstract class Field<T = any> implements IASTNodeLocationSvg, IAS
      * @param _doFullSerialization If true, this signals to the field that if it
      *     normally just saves a reference to some state (eg variable fields) it
      *     should instead serialize the full state of the thing being referenced.
+     *     See the
+     *     {@link https://developers.devsite.google.com/blockly/guides/create-custom-blocks/fields/customizing-fields/creating#full_serialization_and_backing_data | field serialization docs}
+     *     for more information.
      * @returns JSON serializable state.
      * @internal
      */

package/core/field_checkbox.d.ts

@@ -3,6 +3,11 @@
  * Copyright 2012 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
+/**
+ * Checkbox field.  Checked or not checked.
+ *
+ * @class
+ */
 import './events/events_block_change.js';
 import { Field, FieldConfig, FieldValidator } from './field.js';
 type BoolString = 'TRUE' | 'FALSE';

package/core/field_colour.d.ts

@@ -3,8 +3,14 @@
  * Copyright 2012 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
+/**
+ * Colour input field.
+ *
+ * @class
+ */
 import './events/events_block_change.js';
 import { Field, FieldConfig, FieldValidator } from './field.js';
+import { Size } from './utils/size.js';
 /**
  * Class for a colour input field.
  */
@@ -86,10 +92,31 @@ export declare class FieldColour extends Field<string> {
      * Create the block UI for this colour field.
      */
     initView(): void;
+    protected isFullBlockField(): boolean;
     /**
      * Updates text field to match the colour/style of the block.
      */
     applyColour(): void;
+    /**
+     * Returns the height and width of the field.
+     *
+     * This should *in general* be the only place render_ gets called from.
+     *
+     * @returns Height and width.
+     */
+    getSize(): Size;
+    /**
+     * Updates the colour of the block to reflect whether this is a full
+     * block field or not.
+     */
+    protected render_(): void;
+    /**
+     * Updates the size of the field based on whether it is a full block field
+     * or not.
+     *
+     * @param margin margin to use when positioning the field.
+     */
+    protected updateSize_(margin?: number): void;
     /**
      * Ensure that the input value is a valid colour.
      *
@@ -97,13 +124,6 @@ export declare class FieldColour extends Field<string> {
      * @returns A valid colour, or null if invalid.
      */
     protected doClassValidation_(newValue?: any): string | null;
-    /**
-     * Update the value of this colour field, and update the displayed colour.
-     *
-     * @param newValue The value to be saved. The default validator guarantees
-     *     that this is a colour in '#rrggbb' format.
-     */
-    protected doValueUpdate_(newValue: string): void;
     /**
      * Get the text for this field.  Used when the block is collapsed.
      *

package/core/field_image.d.ts

@@ -3,6 +3,11 @@
  * Copyright 2012 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
+/**
+ * Image field.  Used for pictures, icons, etc.
+ *
+ * @class
+ */
 import { Field, FieldConfig } from './field.js';
 import { Size } from './utils/size.js';
 /**

package/core/field_input.d.ts

@@ -3,9 +3,15 @@
  * Copyright 2012 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
+/**
+ * Text input field.
+ *
+ * @class
+ */
 import './events/events_block_change.js';
 import { Field, FieldConfig, FieldValidator } from './field.js';
 import type { WorkspaceSvg } from './workspace_svg.js';
+import { Size } from './utils/size.js';
 /**
  * Supported types for FieldInput subclasses.
  *
@@ -48,7 +54,7 @@ export declare abstract class FieldInput<T extends InputTypes> extends Field<str
      * Whether the field should consider the whole parent block to be its click
      * target.
      */
-    fullBlockClickTarget_: boolean | null;
+    fullBlockClickTarget_: boolean;
     /** The workspace that this field belongs to. */
     protected workspace_: WorkspaceSvg | null;
     /**
@@ -75,6 +81,7 @@ export declare abstract class FieldInput<T extends InputTypes> extends Field<str
     constructor(value?: string | typeof Field.SKIP_SETUP, validator?: FieldInputValidator<T> | null, config?: FieldInputConfig);
     protected configure_(config: FieldInputConfig): void;
     initView(): void;
+    protected isFullBlockField(): boolean;
     /**
      * Called by setValue if the text input is not valid. If the field is
      * currently being edited it reverts value of the field to the previous
@@ -98,9 +105,20 @@ export declare abstract class FieldInput<T extends InputTypes> extends Field<str
      * Updates text field to match the colour/style of the block.
      */
     applyColour(): void;
+    /**
+     * Returns the height and width of the field.
+     *
+     * This should *in general* be the only place render_ gets called from.
+     *
+     * @returns Height and width.
+     */
+    getSize(): Size;
     /**
      * Updates the colour of the htmlInput given the current validity of the
      * field's value.
+     *
+     * Also updates the colour of the block to reflect whether this is a full
+     * block field or not.
      */
     protected render_(): void;
     /**

package/core/field_label_serializable.d.ts

@@ -3,6 +3,13 @@
  * Copyright 2019 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
+/**
+ * Non-editable, serializable text field. Behaves like a
+ *    normal label but is serialized to XML. It may only be
+ *    edited programmatically.
+ *
+ * @class
+ */
 import { FieldLabel, FieldLabelConfig, FieldLabelFromJsonConfig } from './field_label.js';
 /**
  * Class for a non-editable, serializable text field.

package/core/field_number.d.ts

@@ -3,6 +3,11 @@
  * Copyright 2016 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
+/**
+ * Number input field
+ *
+ * @class
+ */
 import { Field } from './field.js';
 import { FieldInput, FieldInputConfig, FieldInputValidator } from './field_input.js';
 /**

package/core/field_textinput.d.ts

@@ -3,6 +3,11 @@
  * Copyright 2012 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
+/**
+ * Text input field.
+ *
+ * @class
+ */
 import './events/events_block_change.js';
 import { Field } from './field.js';
 import { FieldInput, FieldInputConfig, FieldInputValidator } from './field_input.js';

package/core/field_variable.d.ts

@@ -3,6 +3,11 @@
  * Copyright 2012 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
+/**
+ * Variable input field.
+ *
+ * @class
+ */
 import './events/events_block_change.js';
 import type { Block } from './block.js';
 import { Field, FieldConfig } from './field.js';

package/core/flyout_metrics_manager.d.ts

@@ -3,6 +3,11 @@
  * Copyright 2021 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
+/**
+ * Calculates and reports flyout workspace metrics.
+ *
+ * @class
+ */
 import type { IFlyout } from './interfaces/i_flyout.js';
 import { ContainerRegion, MetricsManager } from './metrics_manager.js';
 import type { WorkspaceSvg } from './workspace_svg.js';