scratch-blocks 1.1.206 → 2.0.0-beta.1

package/blockly-rc/core/interfaces/i_legacy_procedure_blocks.ts

@@ -0,0 +1,50 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Legacy means of representing a procedure signature. The elements are
+ * respectively: name, parameter names, and whether it has a return value.
+ */
+export type ProcedureTuple = [string, string[], boolean];
+
+/**
+ * Procedure block type.
+ *
+ * @internal
+ */
+export interface ProcedureBlock {
+  getProcedureCall: () => string;
+  renameProcedure: (p1: string, p2: string) => void;
+  getProcedureDef: () => ProcedureTuple;
+}
+
+/** @internal */
+export interface LegacyProcedureDefBlock {
+  getProcedureDef: () => ProcedureTuple;
+}
+
+/** @internal */
+export function isLegacyProcedureDefBlock(
+  block: Object,
+): block is LegacyProcedureDefBlock {
+  return (block as any).getProcedureDef !== undefined;
+}
+
+/** @internal */
+export interface LegacyProcedureCallBlock {
+  getProcedureCall: () => string;
+  renameProcedure: (p1: string, p2: string) => void;
+}
+
+/** @internal */
+export function isLegacyProcedureCallBlock(
+  block: Object,
+): block is LegacyProcedureCallBlock {
+  return (
+    (block as any).getProcedureCall !== undefined &&
+    (block as any).renameProcedure !== undefined
+  );
+}

package/blockly-rc/core/interfaces/i_metrics_manager.ts

@@ -0,0 +1,149 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type {
+  ContainerRegion,
+  ToolboxMetrics,
+  AbsoluteMetrics,
+  UiMetrics,
+} from '../metrics_manager.js';
+import type {Size} from '../utils/size.js';
+import type {Metrics} from '../utils/metrics.js';
+// Former goog.module ID: Blockly.IMetricsManager
+
+/**
+ * Interface for a metrics manager.
+ */
+export interface IMetricsManager {
+  /**
+   * Returns whether the scroll area has fixed edges.
+   *
+   * @returns Whether the scroll area has fixed edges.
+   * @internal
+   */
+  hasFixedEdges(): boolean;
+
+  /**
+   * Returns the metrics for the scroll area of the workspace.
+   *
+   * @param opt_getWorkspaceCoordinates True to get the scroll metrics in
+   *     workspace coordinates, false to get them in pixel coordinates.
+   * @param opt_viewMetrics The view metrics if they have been previously
+   *     computed. Passing in null may cause the view metrics to be computed
+   *     again, if it is needed.
+   * @param opt_contentMetrics The content metrics if they have been previously
+   *     computed. Passing in null may cause the content metrics to be computed
+   *     again, if it is needed.
+   * @returns The metrics for the scroll container
+   */
+  getScrollMetrics(
+    opt_getWorkspaceCoordinates?: boolean,
+    opt_viewMetrics?: ContainerRegion,
+    opt_contentMetrics?: ContainerRegion,
+  ): ContainerRegion;
+
+  /**
+   * Gets the width and the height of the flyout in pixel
+   * coordinates. By default, will get metrics for either a simple flyout (owned
+   * directly by the workspace) or for the flyout owned by the toolbox. If you
+   * pass `opt_own` as `true` then only metrics for the simple flyout will be
+   * returned, and it will return 0 for the width and height if the workspace
+   * has a category toolbox instead of a simple toolbox.
+   *
+   * @param opt_own Whether to only return the workspace's own flyout metrics.
+   * @returns The width and height of the flyout.
+   */
+  getFlyoutMetrics(opt_own?: boolean): ToolboxMetrics;
+
+  /**
+   * Gets the width, height and position of the toolbox on the workspace in
+   * pixel coordinates. Returns 0 for the width and height if the workspace has
+   * a simple toolbox instead of a category toolbox. To get the width and height
+   * of a simple toolbox, see {@link IMetricsManager#getFlyoutMetrics}.
+   *
+   * @returns The object with the width, height and position of the toolbox.
+   */
+  getToolboxMetrics(): ToolboxMetrics;
+
+  /**
+   * Gets the width and height of the workspace's parent SVG element in pixel
+   * coordinates. This area includes the toolbox and the visible workspace area.
+   *
+   * @returns The width and height of the workspace's parent SVG element.
+   */
+  getSvgMetrics(): Size;
+
+  /**
+   * Gets the absolute left and absolute top in pixel coordinates.
+   * This is where the visible workspace starts in relation to the SVG
+   * container.
+   *
+   * @returns The absolute metrics for the workspace.
+   */
+  getAbsoluteMetrics(): AbsoluteMetrics;
+
+  /**
+   * Gets the metrics for the visible workspace in either pixel or workspace
+   * coordinates. The visible workspace does not include the toolbox or flyout.
+   *
+   * @param opt_getWorkspaceCoordinates True to get the view metrics in
+   *     workspace coordinates, false to get them in pixel coordinates.
+   * @returns The width, height, top and left of the viewport in either
+   *     workspace coordinates or pixel coordinates.
+   */
+  getViewMetrics(opt_getWorkspaceCoordinates?: boolean): ContainerRegion;
+
+  /**
+   * Gets content metrics in either pixel or workspace coordinates.
+   * The content area is a rectangle around all the top bounded elements on the
+   * workspace (workspace comments and blocks).
+   *
+   * @param opt_getWorkspaceCoordinates True to get the content metrics in
+   *     workspace coordinates, false to get them in pixel coordinates.
+   * @returns The metrics for the content container.
+   */
+  getContentMetrics(opt_getWorkspaceCoordinates?: boolean): ContainerRegion;
+
+  /**
+   * Returns an object with all the metrics required to size scrollbars for a
+   * top level workspace.  The following properties are computed:
+   * Coordinate system: pixel coordinates, -left, -up, +right, +down
+   * .viewHeight: Height of the visible portion of the workspace.
+   * .viewWidth: Width of the visible portion of the workspace.
+   * .contentHeight: Height of the content.
+   * .contentWidth: Width of the content.
+   * .svgHeight: Height of the Blockly div (the view + the toolbox,
+   *    simple or otherwise),
+   * .svgWidth: Width of the Blockly div (the view + the toolbox,
+   *    simple or otherwise),
+   * .viewTop: Top-edge of the visible portion of the workspace, relative to
+   *     the workspace origin.
+   * .viewLeft: Left-edge of the visible portion of the workspace, relative to
+   *     the workspace origin.
+   * .contentTop: Top-edge of the content, relative to the workspace origin.
+   * .contentLeft: Left-edge of the content relative to the workspace origin.
+   * .absoluteTop: Top-edge of the visible portion of the workspace, relative
+   *     to the blocklyDiv.
+   * .absoluteLeft: Left-edge of the visible portion of the workspace, relative
+   *     to the blocklyDiv.
+   * .toolboxWidth: Width of the toolbox, if it exists.  Otherwise zero.
+   * .toolboxHeight: Height of the toolbox, if it exists.  Otherwise zero.
+   * .flyoutWidth: Width of the flyout if it is always open.  Otherwise zero.
+   * .flyoutHeight: Height of the flyout if it is always open.  Otherwise zero.
+   * .toolboxPosition: Top, bottom, left or right. Use TOOLBOX_AT constants to
+   *     compare.
+   *
+   * @returns Contains size and position metrics of a top level workspace.
+   */
+  getMetrics(): Metrics;
+
+  /**
+   * Returns common metrics used by UI elements.
+   *
+   * @returns The UI metrics.
+   */
+  getUiMetrics(): UiMetrics;
+}

package/blockly-rc/core/interfaces/i_movable.ts

@@ -0,0 +1,19 @@
+/**
+ * @license
+ * Copyright 2019 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+// Former goog.module ID: Blockly.IMovable
+
+/**
+ * The interface for an object that is movable.
+ */
+export interface IMovable {
+  /**
+   * Get whether this is movable or not.
+   *
+   * @returns True if movable.
+   */
+  isMovable(): boolean;
+}

package/blockly-rc/core/interfaces/i_observable.ts

@@ -0,0 +1,24 @@
+/**
+ * @license
+ * Copyright 2022 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * An object that fires events optionally.
+ *
+ * @internal
+ */
+export interface IObservable {
+  startPublishing(): void;
+  stopPublishing(): void;
+}
+
+/**
+ * Type guard for checking if an object fulfills IObservable.
+ *
+ * @internal
+ */
+export function isObservable(obj: any): obj is IObservable {
+  return obj.startPublishing !== undefined && obj.stopPublishing !== undefined;
+}

package/blockly-rc/core/interfaces/i_parameter_model.ts

@@ -0,0 +1,51 @@
+/**
+ * @license
+ * Copyright 2022 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {ParameterState} from '../serialization/procedures';
+import {IProcedureModel} from './i_procedure_model';
+
+/**
+ * A data model for a procedure.
+ */
+export interface IParameterModel {
+  /**
+   * Sets the name of this parameter to the given name.
+   */
+  setName(name: string): this;
+
+  /**
+   * Sets the types of this parameter to the given type.
+   */
+  setTypes(types: string[]): this;
+
+  /**
+   * Returns the name of this parameter.
+   */
+  getName(): string;
+
+  /**
+   * Return the types of this parameter.
+   */
+  getTypes(): string[];
+
+  /**
+   * Returns the unique language-neutral ID for the parameter.
+   *
+   * This represents the identify of the variable model which does not change
+   * over time.
+   */
+  getId(): string;
+
+  /** Sets the procedure model this parameter is associated with. */
+  setProcedureModel(model: IProcedureModel): this;
+
+  /**
+   * Serializes the state of the parameter to JSON.
+   *
+   * @returns JSON serializable state of the parameter.
+   */
+  saveState(): ParameterState;
+}

package/blockly-rc/core/interfaces/i_paster.ts

@@ -0,0 +1,25 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {Coordinate} from '../utils/coordinate.js';
+import {WorkspaceSvg} from '../workspace_svg.js';
+import {ICopyable, ICopyData} from './i_copyable.js';
+
+/** An object that can paste data into a workspace. */
+export interface IPaster<U extends ICopyData, T extends ICopyable<U>> {
+  paste(
+    copyData: U,
+    workspace: WorkspaceSvg,
+    coordinate?: Coordinate,
+  ): T | null;
+}
+
+/** @returns True if the given object is a paster. */
+export function isPaster(
+  obj: any,
+): obj is IPaster<ICopyData, ICopyable<ICopyData>> {
+  return obj.paste !== undefined;
+}

package/blockly-rc/core/interfaces/i_positionable.ts

@@ -0,0 +1,33 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type {Rect} from '../utils/rect.js';
+import type {UiMetrics} from '../metrics_manager.js';
+// Former goog.module ID: Blockly.IPositionable
+
+import type {IComponent} from './i_component.js';
+
+/**
+ * Interface for a component that is positioned on top of the workspace.
+ */
+export interface IPositionable extends IComponent {
+  /**
+   * Positions the element. Called when the window is resized.
+   *
+   * @param metrics The workspace metrics.
+   * @param savedPositions List of rectangles that are already on the workspace.
+   */
+  position(metrics: UiMetrics, savedPositions: Rect[]): void;
+
+  /**
+   * Returns the bounding rectangle of the UI element in pixel units relative to
+   * the Blockly injection div.
+   *
+   * @returns The UI elements's bounding box. Null if bounding box should be
+   *     ignored by other UI elements.
+   */
+  getBoundingRectangle(): Rect | null;
+}

package/blockly-rc/core/interfaces/i_procedure_block.ts

@@ -0,0 +1,27 @@
+/**
+ * @license
+ * Copyright 2022 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type {Block} from '../block.js';
+import {IProcedureModel} from './i_procedure_model.js';
+// Former goog.module ID: Blockly.procedures.IProcedureBlock
+
+/** The interface for a block which models a procedure. */
+export interface IProcedureBlock {
+  getProcedureModel(): IProcedureModel;
+  doProcedureUpdate(): void;
+  isProcedureDef(): boolean;
+}
+
+/** A type guard which checks if the given block is a procedure block. */
+export function isProcedureBlock(
+  block: Block | IProcedureBlock,
+): block is IProcedureBlock {
+  return (
+    (block as IProcedureBlock).getProcedureModel !== undefined &&
+    (block as IProcedureBlock).doProcedureUpdate !== undefined &&
+    (block as IProcedureBlock).isProcedureDef !== undefined
+  );
+}

package/blockly-rc/core/interfaces/i_procedure_map.ts

@@ -0,0 +1,18 @@
+/**
+ * @license
+ * Copyright 2022 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {IProcedureModel} from './i_procedure_model.js';
+
+export interface IProcedureMap extends Map<string, IProcedureModel> {
+  /**
+   * Adds the given ProcedureModel to the map of procedure models, so that
+   * blocks can find it.
+   */
+  add(proc: IProcedureModel): this;
+
+  /** Returns all of the procedures stored in this map. */
+  getProcedures(): IProcedureModel[];
+}

package/blockly-rc/core/interfaces/i_procedure_model.ts

@@ -0,0 +1,71 @@
+/**
+ * @license
+ * Copyright 2022 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {State} from '../serialization/procedures.js';
+import {IParameterModel} from './i_parameter_model.js';
+
+/**
+ * A data model for a procedure.
+ */
+export interface IProcedureModel {
+  /** Sets the human-readable name of the procedure. */
+  setName(name: string): this;
+
+  /**
+   * Inserts a parameter into the list of parameters.
+   *
+   * To move a parameter, first delete it, and then re-insert.
+   */
+  insertParameter(parameterModel: IParameterModel, index: number): this;
+
+  /** Removes the parameter at the given index from the parameter list. */
+  deleteParameter(index: number): this;
+
+  /**
+   * Sets the return type(s) of the procedure.
+   *
+   * Pass null to represent a procedure that does not return.
+   */
+  setReturnTypes(types: string[] | null): this;
+
+  /**
+   * Sets whether this procedure is enabled/disabled. If a procedure is disabled
+   * all procedure caller blocks should be disabled as well.
+   */
+  setEnabled(enabled: boolean): this;
+
+  /** Returns the unique language-neutral ID for the procedure. */
+  getId(): string;
+
+  /** Returns the human-readable name of the procedure. */
+  getName(): string;
+
+  /** Returns the parameter at the given index in the parameter list. */
+  getParameter(index: number): IParameterModel;
+
+  /** Returns an array of all of the parameters in the parameter list. */
+  getParameters(): IParameterModel[];
+
+  /**
+   * Returns the return type(s) of the procedure.
+   *
+   * Null represents a procedure that does not return a value.
+   */
+  getReturnTypes(): string[] | null;
+
+  /**
+   * Returns whether the procedure is enabled/disabled. If a procedure is
+   * disabled, all procedure caller blocks should be disabled as well.
+   */
+  getEnabled(): boolean;
+
+  /**
+   * Serializes the state of the procedure to JSON.
+   *
+   * @returns JSON serializable state of the procedure.
+   */
+  saveState(): State;
+}

package/blockly-rc/core/interfaces/i_registrable.ts

@@ -0,0 +1,12 @@
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+// Former goog.module ID: Blockly.IRegistrable
+
+/**
+ * The interface for a Blockly component that can be registered.
+ */
+export interface IRegistrable {}

package/blockly-rc/core/interfaces/i_rendered_element.ts

@@ -0,0 +1,22 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/** @internal */
+export interface IRenderedElement {
+  /**
+   * @returns The root SVG element of htis rendered element.
+   */
+  getSvgRoot(): SVGElement;
+}
+
+/**
+ * @returns True if the given object is an IRenderedElement.
+ *
+ * @internal
+ */
+export function isRenderedElement(obj: any): obj is IRenderedElement {
+  return obj['getSvgRoot'] !== undefined;
+}

package/blockly-rc/core/interfaces/i_selectable.ts

@@ -0,0 +1,34 @@
+/**
+ * @license
+ * Copyright 2019 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+// Former goog.module ID: Blockly.ISelectable
+
+import type {Workspace} from '../workspace.js';
+
+/**
+ * The interface for an object that is selectable.
+ */
+export interface ISelectable {
+  id: string;
+
+  workspace: Workspace;
+
+  /** Select this.  Highlight it visually. */
+  select(): void;
+
+  /** Unselect this.  Unhighlight it visually. */
+  unselect(): void;
+}
+
+/** Checks whether the given object is an ISelectable. */
+export function isSelectable(obj: Object): obj is ISelectable {
+  return (
+    typeof (obj as any).id === 'string' &&
+    (obj as any).workspace !== undefined &&
+    (obj as any).select !== undefined &&
+    (obj as any).unselect !== undefined
+  );
+}

package/blockly-rc/core/interfaces/i_selectable_toolbox_item.ts

@@ -0,0 +1,63 @@
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type {FlyoutItemInfoArray} from '../utils/toolbox';
+// Former goog.module ID: Blockly.ISelectableToolboxItem
+
+import type {IToolboxItem} from './i_toolbox_item.js';
+
+/**
+ * Interface for an item in the toolbox that can be selected.
+ */
+export interface ISelectableToolboxItem extends IToolboxItem {
+  /**
+   * Gets the name of the toolbox item. Used for emitting events.
+   *
+   * @returns The name of the toolbox item.
+   */
+  getName(): string;
+
+  /**
+   * Gets the contents of the toolbox item. These are items that are meant to be
+   * displayed in the flyout.
+   *
+   * @returns The definition of items to be displayed in the flyout.
+   */
+  getContents(): FlyoutItemInfoArray | string;
+
+  /**
+   * Sets the current toolbox item as selected.
+   *
+   * @param _isSelected True if this category is selected, false otherwise.
+   */
+  setSelected(_isSelected: boolean): void;
+
+  /**
+   * Gets the HTML element that is clickable.
+   * The parent toolbox element receives clicks. The parent toolbox will add an
+   * ID to this element so it can pass the onClick event to the correct
+   * toolboxItem.
+   *
+   * @returns The HTML element that receives clicks.
+   */
+  getClickTarget(): Element;
+
+  /**
+   * Handles when the toolbox item is clicked.
+   *
+   * @param _e Click event to handle.
+   */
+  onClick(_e: Event): void;
+}
+
+/**
+ * Type guard that checks whether an IToolboxItem is an ISelectableToolboxItem.
+ */
+export function isSelectableToolboxItem(
+  toolboxItem: IToolboxItem,
+): toolboxItem is ISelectableToolboxItem {
+  return toolboxItem.isSelectable();
+}

package/blockly-rc/core/interfaces/i_serializable.ts

@@ -0,0 +1,28 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export interface ISerializable {
+  /**
+   * @param doFullSerialization If true, this signals that any backing data
+   *     structures used by this ISerializable should also be serialized. This
+   *     is used for copy-paste.
+   * @returns a JSON serializable value that records the ISerializable's state.
+   */
+  saveState(doFullSerialization: boolean): any;
+
+  /**
+   * Takes in a JSON serializable value and sets the ISerializable's state
+   * based on that.
+   *
+   * @param state The state to apply to the ISerializable.
+   */
+  loadState(state: any): void;
+}
+
+/** Type guard that checks whether the given object is a ISerializable. */
+export function isSerializable(obj: any): obj is ISerializable {
+  return obj.saveState !== undefined && obj.loadState !== undefined;
+}

package/blockly-rc/core/interfaces/i_serializer.ts

@@ -0,0 +1,55 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+// Former goog.module ID: Blockly.serialization.ISerializer
+
+import type {Workspace} from '../workspace.js';
+
+/**
+ * Serializes and deserializes a plugin or system.
+ */
+export interface ISerializer {
+  /**
+   * A priority value used to determine the order of deserializing state.
+   * More positive priorities are deserialized before less positive
+   * priorities. Eg if you have priorities (0, -10, 10, 100) the order of
+   * deserialiation will be (100, 10, 0, -10).
+   * If two serializers have the same priority, they are deserialized in an
+   * arbitrary order relative to each other.
+   */
+  priority: number;
+
+  /* eslint-disable no-unused-vars, valid-jsdoc */
+
+  /**
+   * Saves the state of the plugin or system.
+   *
+   * @param workspace The workspace the system to serialize is associated with.
+   * @returns A JS object containing the system's state, or null if there is no
+   *     state to record.
+   */
+  save(workspace: Workspace): Object | null;
+  /* eslint-enable valid-jsdoc */
+
+  /**
+   * Loads the state of the plugin or system.
+   *
+   * @param state The state of the system to deserialize. This will always be
+   *     non-null.
+   * @param workspace The workspace the system to deserialize is associated
+   *     with.
+   */
+  load(state: Object, workspace: Workspace): void;
+
+  /**
+   * Clears the state of the plugin or system.
+   *
+   * @param workspace The workspace the system to clear the state of is
+   *     associated with.
+   */
+  clear(workspace: Workspace): void;
+}
+/* eslint-enable no-unused-vars */