blockly 11.0.0-beta.8 → 11.0.0

package/core/block.d.ts

@@ -123,7 +123,7 @@ export declare class Block implements IASTNodeLocation {
     inputList: Input[];
     inputsInline?: boolean;
     icons: IIcon[];
-    private disabled;
+    private disabledReasons;
     tooltip: Tooltip.TipInfo;
     contextMenu: boolean;
     protected parentBlock_: this | null;
@@ -320,6 +320,12 @@ export declare class Block implements IASTNodeLocation {
      * @internal
      */
     getTopStackBlock(): this;
+    /**
+     * Returns this block if it is a shadow block, or the first non-shadow parent.
+     *
+     * @internal
+     */
+    getFirstNonShadowBlock(): this;
     /**
      * Find all the blocks that are directly nested inside this one.
      * Includes value and statement inputs, as well as any following statement.
@@ -627,17 +633,44 @@ export declare class Block implements IASTNodeLocation {
      */
     getOutputShape(): number | null;
     /**
-     * Get whether this block is enabled or not.
+     * Get whether this block is enabled or not. A block is considered enabled
+     * if there aren't any reasons why it would be disabled. A block may still
+     * be disabled for other reasons even if the user attempts to manually
+     * enable it, such as when the block is in an invalid location.
      *
      * @returns True if enabled.
      */
     isEnabled(): boolean;
-    /**
-     * Set whether the block is enabled or not.
+    /** @deprecated v11 - Get whether the block is manually disabled. */
+    private get disabled();
+    /** @deprecated v11 - Set whether the block is manually disabled. */
+    private set disabled(value);
+    /**
+     * @deprecated v11 - Set whether the block is manually enabled or disabled.
+     * The user can toggle whether a block is disabled from a context menu
+     * option. A block may still be disabled for other reasons even if the user
+     * attempts to manually enable it, such as when the block is in an invalid
+     * location. This method is deprecated and setDisabledReason should be used
+     * instead.
      *
      * @param enabled True if enabled.
      */
     setEnabled(enabled: boolean): void;
+    /**
+     * Add or remove a reason why the block might be disabled. If a block has
+     * any reasons to be disabled, then the block itself will be considered
+     * disabled. A block could be disabled for multiple independent reasons
+     * simultaneously, such as when the user manually disables it, or the block
+     * is invalid.
+     *
+     * @param disabled If true, then the block should be considered disabled for
+     *     at least the provided reason, otherwise the block is no longer disabled
+     *     for that reason.
+     * @param reason A language-neutral identifier for a reason why the block
+     *     could be disabled. Call this method again with the same identifier to
+     *     update whether the block is currently disabled for this reason.
+     */
+    setDisabledReason(disabled: boolean, reason: string): void;
     /**
      * Get whether the block is disabled or not due to parents.
      * The block's own disabled property is not considered.
@@ -645,6 +678,21 @@ export declare class Block implements IASTNodeLocation {
      * @returns True if disabled.
      */
     getInheritedDisabled(): boolean;
+    /**
+     * Get whether the block is currently disabled for the provided reason.
+     *
+     * @param reason A language-neutral identifier for a reason why the block
+     *     could be disabled.
+     * @returns Whether the block is disabled for the provided reason.
+     */
+    hasDisabledReason(reason: string): boolean;
+    /**
+     * Get a set of reasons why the block is currently disabled, if any. If the
+     * block is enabled, this set will be empty.
+     *
+     * @returns The set of reasons why the block is disabled, if any.
+     */
+    getDisabledReasons(): ReadonlySet<string>;
     /**
      * Get whether the block is collapsed or not.
      *

package/core/block_svg.d.ts

@@ -238,7 +238,7 @@ export declare class BlockSvg extends Block implements IASTNodeLocationSvg, IBou
      * @param e Mouse event.
      * @internal
      */
-    showContextMenu(e: Event): void;
+    showContextMenu(e: PointerEvent): void;
     /**
      * Updates the locations of any parts of the block that need to know where
      * they are (e.g. connections, icons).
@@ -356,11 +356,31 @@ export declare class BlockSvg extends Block implements IASTNodeLocationSvg, IBou
     private createIconPointerDownListener;
     removeIcon(type: IconType<IIcon>): boolean;
     /**
-     * Set whether the block is enabled or not.
+     * @deprecated v11 - Set whether the block is manually enabled or disabled.
+     * The user can toggle whether a block is disabled from a context menu
+     * option. A block may still be disabled for other reasons even if the user
+     * attempts to manually enable it, such as when the block is in an invalid
+     * location. This method is deprecated and setDisabledReason should be used
+     * instead.
      *
      * @param enabled True if enabled.
      */
     setEnabled(enabled: boolean): void;
+    /**
+     * Add or remove a reason why the block might be disabled. If a block has
+     * any reasons to be disabled, then the block itself will be considered
+     * disabled. A block could be disabled for multiple independent reasons
+     * simultaneously, such as when the user manually disables it, or the block
+     * is invalid.
+     *
+     * @param disabled If true, then the block should be considered disabled for
+     *     at least the provided reason, otherwise the block is no longer disabled
+     *     for that reason.
+     * @param reason A language-neutral identifier for a reason why the block
+     *     could be disabled. Call this method again with the same identifier to
+     *     update whether the block is currently disabled for this reason.
+     */
+    setDisabledReason(disabled: boolean, reason: string): void;
     /**
      * Set whether the block is highlighted or not.  Block highlighting is
      * often used to visually mark blocks currently being executed.

package/core/blockly.d.ts

@@ -141,8 +141,6 @@ import * as VariablesDynamic from './variables_dynamic.js';
 import * as WidgetDiv from './widgetdiv.js';
 import { Workspace } from './workspace.js';
 import { WorkspaceAudio } from './workspace_audio.js';
-import { WorkspaceComment } from './workspace_comment.js';
-import { WorkspaceCommentSvg } from './workspace_comment_svg.js';
 import { WorkspaceDragger } from './workspace_dragger.js';
 import { WorkspaceSvg } from './workspace_svg.js';
 import * as Xml from './xml.js';
@@ -397,8 +395,6 @@ export { VariableModel };
 export { VerticalFlyout };
 export { Workspace };
 export { WorkspaceAudio };
-export { WorkspaceComment };
-export { WorkspaceCommentSvg };
 export { WorkspaceDragger };
 export { WorkspaceSvg };
 export { ZoomControls };

package/core/clipboard/block_paster.d.ts

@@ -20,9 +20,11 @@ export declare class BlockPaster implements IPaster<BlockCopyData, BlockSvg> {
  * Exported for testing.
  *
  * @param block The block to move to an unambiguous location.
+ * @param originalPosition The initial coordinate to start searching from,
+ *    likely the position of the copied block.
  * @internal
  */
-export declare function moveBlockToNotConflict(block: BlockSvg): void;
+export declare function moveBlockToNotConflict(block: BlockSvg, originalPosition: Coordinate): void;
 export interface BlockCopyData extends ICopyData {
     blockState: State;
     typeCounts: {

package/core/clipboard/workspace_comment_paster.d.ts

@@ -7,12 +7,13 @@ import { IPaster } from '../interfaces/i_paster.js';
 import { ICopyData } from '../interfaces/i_copyable.js';
 import { Coordinate } from '../utils/coordinate.js';
 import { WorkspaceSvg } from '../workspace_svg.js';
-import { WorkspaceCommentSvg } from '../workspace_comment_svg.js';
-export declare class WorkspaceCommentPaster implements IPaster<WorkspaceCommentCopyData, WorkspaceCommentSvg> {
+import * as commentSerialiation from '../serialization/workspace_comments.js';
+import { RenderedWorkspaceComment } from '../comments/rendered_workspace_comment.js';
+export declare class WorkspaceCommentPaster implements IPaster<WorkspaceCommentCopyData, RenderedWorkspaceComment> {
     static TYPE: string;
-    paste(copyData: WorkspaceCommentCopyData, workspace: WorkspaceSvg, coordinate?: Coordinate): WorkspaceCommentSvg;
+    paste(copyData: WorkspaceCommentCopyData, workspace: WorkspaceSvg, coordinate?: Coordinate): RenderedWorkspaceComment | null;
 }
 export interface WorkspaceCommentCopyData extends ICopyData {
-    commentState: Element;
+    commentState: commentSerialiation.State;
 }
 //# sourceMappingURL=workspace_comment_paster.d.ts.map

package/core/comments/comment_view.d.ts

@@ -83,7 +83,10 @@ export declare class CommentView implements IRenderedElement {
     private createResizeHandle;
     /** Returns the root SVG group element of the comment view. */
     getSvgRoot(): SVGGElement;
-    /** Returns the current size of the comment in workspace units. */
+    /**
+     * Returns the current size of the comment in workspace units.
+     * Respects collapsing.
+     */
     getSize(): Size;
     /**
      * Sets the size of the comment in workspace units, and updates the view
@@ -103,6 +106,8 @@ export declare class CommentView implements IRenderedElement {
     private calcDeleteMargin;
     /** Calculates the margin that should exist around the foldout icon. */
     private calcFoldoutMargin;
+    /** Updates the size of the highlight rect to reflect the new size. */
+    private updateHighlightRect;
     /** Updates the size of the top bar to reflect the new size. */
     private updateTopBarSize;
     /** Updates the size of the text area elements to reflect the new size. */

package/core/comments/rendered_workspace_comment.d.ts

@@ -13,7 +13,10 @@ import { IRenderedElement } from '../interfaces/i_rendered_element.js';
 import { IDraggable } from '../interfaces/i_draggable.js';
 import { ISelectable } from '../interfaces/i_selectable.js';
 import { IDeletable } from '../interfaces/i_deletable.js';
-export declare class RenderedWorkspaceComment extends WorkspaceComment implements IBoundedElement, IRenderedElement, IDraggable, ISelectable, IDeletable {
+import { ICopyable } from '../interfaces/i_copyable.js';
+import { WorkspaceCommentCopyData } from '../clipboard/workspace_comment_paster.js';
+import { IContextMenu } from '../interfaces/i_contextmenu.js';
+export declare class RenderedWorkspaceComment extends WorkspaceComment implements IBoundedElement, IRenderedElement, IDraggable, ISelectable, IDeletable, ICopyable<WorkspaceCommentCopyData>, IContextMenu {
     /** The class encompassing the svg elements making up the workspace comment. */
     private view;
     readonly workspace: WorkspaceSvg;
@@ -35,7 +38,15 @@ export declare class RenderedWorkspaceComment extends WorkspaceComment implement
     setEditable(editable: boolean): void;
     /** Returns the root SVG element of this comment. */
     getSvgRoot(): SVGElement;
-    /** Returns the bounding rectangle of this comment in workspace coordinates. */
+    /**
+     * Returns the comment's size in workspace units.
+     * Does not respect collapsing.
+     */
+    getSize(): Size;
+    /**
+     * Returns the bounding rectangle of this comment in workspace coordinates.
+     * Respects collapsing.
+     */
     getBoundingRectangle(): Rect;
     /** Move the comment by the given amounts in workspace coordinates. */
     moveBy(dx: number, dy: number, reason?: string[] | undefined): void;
@@ -60,8 +71,6 @@ export declare class RenderedWorkspaceComment extends WorkspaceComment implement
      * (that wasn't otherwise gobbled up, e.g. by resizing).
      */
     private startGesture;
-    /** Returns whether this comment is deletable or not. */
-    isDeletable(): boolean;
     /** Visually indicates that this comment would be deleted if dropped. */
     setDeleteStyle(wouldDelete: boolean): void;
     /** Returns whether this comment is movable or not. */
@@ -78,5 +87,14 @@ export declare class RenderedWorkspaceComment extends WorkspaceComment implement
     select(): void;
     /** Visually unhighlights the comment. */
     unselect(): void;
+    /**
+     * Returns a JSON serializable representation of this comment's state that
+     * can be used for pasting.
+     */
+    toCopyData(): WorkspaceCommentCopyData | null;
+    /** Show a context menu for this comment. */
+    showContextMenu(e: PointerEvent): void;
+    /** Snap this comment to the nearest grid point. */
+    snapToGrid(): void;
 }
 //# sourceMappingURL=rendered_workspace_comment.d.ts.map

package/core/constants.d.ts

@@ -11,4 +11,9 @@ export declare const COLLAPSED_INPUT_NAME = "_TEMP_COLLAPSED_INPUT";
  * The language-neutral ID given to the collapsed field.
  */
 export declare const COLLAPSED_FIELD_NAME = "_TEMP_COLLAPSED_FIELD";
+/**
+ * The language-neutral ID for when the reason why a block is disabled is
+ * because the user manually disabled it, such as via the context menu.
+ */
+export declare const MANUALLY_DISABLED = "MANUALLY_DISABLED";
 //# sourceMappingURL=constants.d.ts.map

package/core/contextmenu.d.ts

@@ -7,8 +7,6 @@ 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';
 /**
  * Gets the block the context menu is currently attached to.
  *
@@ -28,7 +26,7 @@ export declare function setCurrentBlock(block: Block | null): void;
  * @param options Array of menu options.
  * @param rtl True if RTL, false if LTR.
  */
-export declare function show(e: Event, options: (ContextMenuOption | LegacyContextMenuOption)[], rtl: boolean): void;
+export declare function show(e: PointerEvent, options: (ContextMenuOption | LegacyContextMenuOption)[], rtl: boolean): void;
 /**
  * Hide the context menu.
  */
@@ -46,35 +44,4 @@ export declare function dispose(): void;
  * @returns Function that creates a block.
  */
 export declare function callbackFactory(block: Block, state: Element | serializationBlocks.State): () => BlockSvg;
-/**
- * Make a context menu option for deleting the current workspace comment.
- *
- * @param comment The workspace comment where the
- *     right-click originated.
- * @returns A menu option,
- *     containing text, enabled, and a callback.
- * @internal
- */
-export declare function commentDeleteOption(comment: WorkspaceCommentSvg): LegacyContextMenuOption;
-/**
- * Make a context menu option for duplicating the current workspace comment.
- *
- * @param comment The workspace comment where the
- *     right-click originated.
- * @returns A menu option,
- *     containing text, enabled, and a callback.
- * @internal
- */
-export declare function commentDuplicateOption(comment: WorkspaceCommentSvg): LegacyContextMenuOption;
-/**
- * Make a context menu option for adding a comment on the workspace.
- *
- * @param ws The workspace where the right-click
- *     originated.
- * @param e The right-click mouse event.
- * @returns A menu option, containing text, enabled, and a callback.
- *     comments are not bundled in.
- * @internal
- */
-export declare function workspaceCommentOption(ws: WorkspaceSvg, e: Event): ContextMenuOption;
 //# sourceMappingURL=contextmenu.d.ts.map

package/core/contextmenu_items.d.ts

@@ -55,6 +55,14 @@ export declare function registerDelete(): void;
  * Option to open help for a block.
  */
 export declare function registerHelp(): void;
+/** Registers an option for deleting a workspace comment. */
+export declare function registerCommentDelete(): void;
+/** Registers an option for duplicating a workspace comment. */
+export declare function registerCommentDuplicate(): void;
+/** Registers an option for adding a workspace comment to the workspace. */
+export declare function registerCommentCreate(): void;
+/** Registers all workspace comment related menu items. */
+export declare function registerCommentOptions(): void;
 /**
  * Registers all default context menu items. This should be called once per
  * instance of ContextMenuRegistry.

package/core/contextmenu_registry.d.ts

@@ -9,6 +9,7 @@
  * @class
  */
 import type { BlockSvg } from './block_svg.js';
+import { RenderedWorkspaceComment } from './comments/rendered_workspace_comment.js';
 import type { WorkspaceSvg } from './workspace_svg.js';
 /**
  * Class for the registry of context menu items. This is intended to be a
@@ -63,7 +64,8 @@ export declare namespace ContextMenuRegistry {
      */
     enum ScopeType {
         BLOCK = "block",
-        WORKSPACE = "workspace"
+        WORKSPACE = "workspace",
+        COMMENT = "comment"
     }
     /**
      * The actual workspace/block where the menu is being rendered. This is passed
@@ -72,12 +74,19 @@ export declare namespace ContextMenuRegistry {
     interface Scope {
         block?: BlockSvg;
         workspace?: WorkspaceSvg;
+        comment?: RenderedWorkspaceComment;
     }
     /**
      * A menu item as entered in the registry.
      */
     interface RegistryItem {
-        callback: (p1: Scope) => void;
+        /**
+         * @param scope Object that provides a reference to the thing that had its
+         *     context menu opened.
+         * @param e The original event that triggered the context menu to open. Not
+         *     the event that triggered the click on the option.
+         */
+        callback: (scope: Scope, e: PointerEvent) => void;
         scopeType: ScopeType;
         displayText: ((p1: Scope) => string | HTMLElement) | string | HTMLElement;
         preconditionFn: (p1: Scope) => string;
@@ -90,7 +99,13 @@ export declare namespace ContextMenuRegistry {
     interface ContextMenuOption {
         text: string | HTMLElement;
         enabled: boolean;
-        callback: (p1: Scope) => void;
+        /**
+         * @param scope Object that provides a reference to the thing that had its
+         *     context menu opened.
+         * @param e The original event that triggered the context menu to open. Not
+         *     the event that triggered the click on the option.
+         */
+        callback: (scope: Scope, e: PointerEvent) => void;
         scope: Scope;
         weight: number;
     }

package/core/dragging/block_drag_strategy.d.ts

@@ -20,11 +20,6 @@ export declare class BlockDragStrategy implements IDragStrategy {
     private connectionCandidate;
     private connectionPreviewer;
     private dragging;
-    /**
-     * If this is a shadow block, the offset between this block and the parent
-     * block, to add to the drag location. In workspace units.
-     */
-    private dragOffset;
     constructor(block: BlockSvg);
     /** Returns true if the block is currently movable. False otherwise. */
     isMovable(): boolean;
@@ -33,8 +28,6 @@ export declare class BlockDragStrategy implements IDragStrategy {
      * from any parent blocks.
      */
     startDrag(e?: PointerEvent): void;
-    /** Starts a drag on a shadow, recording the drag offset. */
-    private startDraggingShadow;
     /**
      * Whether or not we should disconnect the block when a drag is started.
      *
@@ -93,7 +86,7 @@ export declare class BlockDragStrategy implements IDragStrategy {
      * Cleans up any state at the end of the drag. Applies any pending
      * connections.
      */
-    endDrag(e?: PointerEvent): void;
+    endDrag(): void;
     /** Connects the given candidate connections. */
     private applyConnections;
     /**

package/core/dragging/comment_drag_strategy.d.ts

@@ -15,6 +15,7 @@ export declare class CommentDragStrategy implements IDragStrategy {
     startDrag(): void;
     drag(newLoc: Coordinate): void;
     endDrag(): void;
+    private fireMoveEvent;
     revertDrag(): void;
 }
 //# sourceMappingURL=comment_drag_strategy.d.ts.map

package/core/events/events_block_change.d.ts

@@ -29,6 +29,11 @@ export declare class BlockChange extends BlockBase {
     oldValue: unknown;
     /** The new value of the element. */
     newValue: unknown;
+    /**
+     * If element is 'disabled', this is the language-neutral identifier of the
+     * reason why the block was or was not disabled.
+     */
+    private disabledReason?;
     /**
      * @param opt_block The changed block.  Undefined for a blank event.
      * @param opt_element One of 'field', 'comment', 'disabled', etc.
@@ -53,6 +58,15 @@ export declare class BlockChange extends BlockBase {
      * @internal
      */
     static fromJson(json: BlockChangeJson, workspace: Workspace, event?: any): BlockChange;
+    /**
+     * Set the language-neutral identifier for the reason why the block was or was
+     * not disabled. This is only valid for events where element is 'disabled'.
+     * Defaults to 'MANUALLY_DISABLED'.
+     *
+     * @param disabledReason The identifier of the reason why the block was or was
+     *     not disabled.
+     */
+    setDisabledReason(disabledReason: string): void;
     /**
      * Does this event record any change of state?
      *
@@ -80,5 +94,6 @@ export interface BlockChangeJson extends BlockBaseJson {
     name?: string;
     newValue: unknown;
     oldValue: unknown;
+    disabledReason?: string;
 }
 //# sourceMappingURL=events_block_change.d.ts.map

package/core/events/utils.d.ts

@@ -231,10 +231,8 @@ export declare function fromJson(json: any, workspace: Workspace): Abstract;
  */
 export declare function get(eventType: string): new (...p1: any[]) => Abstract;
 /**
- * Enable/disable a block depending on whether it is properly connected.
+ * 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.
- * Recommend setting the 'disable' option to 'false' in the config so that
- * users don't try to re-enable disabled orphan blocks.
  *
  * @param event Custom data for event.
  */

package/core/field.d.ts

@@ -561,6 +561,7 @@ export declare abstract class Field<T = any> implements IASTNodeLocationSvg, IAS
      *
      * @param newValue New value.
      * @param validatedValue Validated value.
+     * @param fireChangeEvent Whether to fire a change event if the value changes.
      * @returns New value, or an Error object.
      */
     private processValidation_;
@@ -605,8 +606,9 @@ export declare abstract class Field<T = any> implements IASTNodeLocationSvg, IAS
      * No-op by default.
      *
      * @param _invalidValue The input value that was determined to be invalid.
+     * @param _fireChangeEvent Whether to fire a change event if the value changes.
      */
-    protected doValueInvalid_(_invalidValue: any): void;
+    protected doValueInvalid_(_invalidValue: any, _fireChangeEvent?: boolean): void;
     /**
      * Handle a pointerdown event on a field.
      *
@@ -706,6 +708,17 @@ export declare abstract class Field<T = any> implements IASTNodeLocationSvg, IAS
      * @internal
      */
     updateMarkers_(): void;
+    /**
+     * Subclasses should reimplement this method to construct their Field
+     * subclass from a JSON arg object.
+     *
+     * It is an error to attempt to register a field subclass in the
+     * FieldRegistry if that subclass has not overridden this method.
+     *
+     * @param _options JSON configuration object with properties needed
+     *    to configure a specific field.
+     */
+    static fromJson(_options: FieldConfig): Field;
 }
 /**
  * Extra configuration options for the base field.
@@ -714,12 +727,14 @@ export interface FieldConfig {
     tooltip?: string;
 }
 /**
- * For use by Field and descendants of Field. Constructors can change
+ * Represents an object that has all the prototype properties of the `Field`
+ * class. This is necessary because constructors can change
  * in descendants, though they should contain all of Field's prototype methods.
  *
- * @internal
+ * This type should only be used in places where we directly access the prototype
+ * of a Field class or subclass.
  */
-export type FieldProto = Pick<typeof Field, 'prototype'>;
+type FieldProto = Pick<typeof Field, 'prototype'>;
 /**
  * Represents an error where the field is trying to access its block or
  * information about its block before it has actually been attached to said
@@ -729,4 +744,5 @@ export declare class UnattachedFieldError extends Error {
     /** @internal */
     constructor();
 }
+export {};
 //# sourceMappingURL=field.d.ts.map

package/core/field_input.d.ts

@@ -88,10 +88,11 @@ export declare abstract class FieldInput<T extends InputTypes> extends Field<str
      * value while allowing the display text to be handled by the htmlInput_.
      *
      * @param _invalidValue The input value that was determined to be invalid.
-     *    This is not used by the text input because its display value is stored
-     * on the htmlInput_.
+     *     This is not used by the text input because its display value is stored
+     *     on the htmlInput_.
+     * @param fireChangeEvent Whether to fire a change event if the value changes.
      */
-    protected doValueInvalid_(_invalidValue: any): void;
+    protected doValueInvalid_(_invalidValue: any, fireChangeEvent?: boolean): void;
     /**
      * Called by setValue if the text input is valid. Updates the value of the
      * field, and updates the text of the field if it is not currently being

package/core/field_registry.d.ts

@@ -3,10 +3,42 @@
  * Copyright 2019 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import type { Field, FieldProto } from './field.js';
-interface RegistryOptions {
+import type { Field, FieldConfig } from './field.js';
+/**
+ * When constructing a field from JSON using the registry, the
+ * `fromJson` method in this file is called with an options parameter
+ * object consisting of the "type" which is the name of the field, and
+ * other options that are part of the field's config object.
+ *
+ * These options are then passed to the field's static `fromJson`
+ * method. That method accepts an options parameter with a type that usually
+ * extends from FieldConfig, and may or may not have a "type" attribute (in
+ * fact, it shouldn't, because we'd overwrite it as described above!)
+ *
+ * Unfortunately the registry has no way of knowing the actual Field subclass
+ * that will be returned from passing in the name of the field. Therefore it
+ * also has no way of knowing that the options object not only implements
+ * `FieldConfig`, but it also should satisfy the Config that belongs to that
+ * specific class's `fromJson` method.
+ *
+ * Because of this uncertainty, we just give up on type checking the properties
+ * passed to the `fromJson` method, and allow arbitrary string keys with
+ * unknown types.
+ */
+type RegistryOptions = FieldConfig & {
     type: string;
     [key: string]: unknown;
+};
+/**
+ * Represents the static methods that must be defined on any
+ * field that is registered, i.e. the constructor and fromJson methods.
+ *
+ * Because we don't know which Field subclass will be registered, we
+ * are unable to typecheck the parameters of the constructor.
+ */
+export interface RegistrableField {
+    new (...args: any[]): Field;
+    fromJson(options: FieldConfig): Field;
 }
 /**
  * Registers a field type.
@@ -19,7 +51,7 @@ interface RegistryOptions {
  * @throws {Error} if the type name is empty, the field is already registered,
  *     or the fieldClass is not an object containing a fromJson function.
  */
-export declare function register(type: string, fieldClass: FieldProto): void;
+export declare function register(type: string, fieldClass: RegistrableField): void;
 /**
  * Unregisters the field registered with the given type.
  *

package/core/flyout_base.d.ts

@@ -8,6 +8,7 @@ import { DeleteArea } from './delete_area.js';
 import { FlyoutButton } from './flyout_button.js';
 import type { IFlyout } from './interfaces/i_flyout.js';
 import type { Options } from './options.js';
+import * as blocks from './serialization/blocks.js';
 import { Coordinate } from './utils/coordinate.js';
 import { Svg } from './utils/svg.js';
 import * as toolbox from './utils/toolbox.js';
@@ -505,6 +506,13 @@ export declare abstract class Flyout extends DeleteArea implements IAutoHideable
      * @returns The new block in the main workspace.
      */
     private placeNewBlock;
+    /**
+     * Serialize a block to JSON.
+     *
+     * @param block The block to serialize.
+     * @returns A serialized representation of the block.
+     */
+    protected serializeBlock(block: BlockSvg): blocks.State;
     /**
      * Positions a block on the target workspace.
      *

package/core/grid.d.ts

@@ -3,6 +3,7 @@
  * Copyright 2017 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
+import { Coordinate } from './utils/coordinate.js';
 import { GridOptions } from './options.js';
 /**
  * Class for a workspace's grid.
@@ -92,6 +93,14 @@ export declare class Grid {
      * @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.
      *