blockly 12.4.0 → 12.5.0

package/core/inputs/input.ts

@@ -1,317 +0,0 @@
-/**
- * @license
- * Copyright 2012 Google LLC
- * SPDX-License-Identifier: Apache-2.0
- */
-
-/**
- * Object representing an input (value, statement, or dummy).
- *
- * @class
- */
-// Former goog.module ID: Blockly.Input
-
-// Unused import preserved for side-effects. Remove if unneeded.
-import '../field_label.js';
-
-import type {Block} from '../block.js';
-import type {BlockSvg} from '../block_svg.js';
-import type {Connection} from '../connection.js';
-import type {ConnectionType} from '../connection_type.js';
-import type {Field} from '../field.js';
-import * as fieldRegistry from '../field_registry.js';
-import {RenderedConnection} from '../rendered_connection.js';
-import {Align} from './align.js';
-import {inputTypes} from './input_types.js';
-
-/** Class for an input with optional fields. */
-export class Input {
-  fieldRow: Field[] = [];
-  /** Alignment of input's fields (left, right or centre). */
-  align = Align.LEFT;
-
-  /** Is the input visible? */
-  private visible = true;
-
-  public readonly type: inputTypes = inputTypes.CUSTOM;
-
-  public connection: Connection | null = null;
-
-  /**
-   * @param name Language-neutral identifier which may used to find this input
-   *     again.
-   * @param sourceBlock The block containing this input.
-   */
-  constructor(
-    public name: string,
-    private sourceBlock: Block,
-  ) {}
-
-  /**
-   * Get the source block for this input.
-   *
-   * @returns The block this input is part of.
-   */
-  getSourceBlock(): Block {
-    return this.sourceBlock;
-  }
-
-  /**
-   * Add a field (or label from string), and all prefix and suffix fields, to
-   * the end of the input's field row.
-   *
-   * @param field Something to add as a field.
-   * @param opt_name Language-neutral identifier which may used to find this
-   *     field again.  Should be unique to the host block.
-   * @returns The input being append to (to allow chaining).
-   */
-  appendField<T>(field: string | Field<T>, opt_name?: string): Input {
-    this.insertFieldAt(this.fieldRow.length, field, opt_name);
-    return this;
-  }
-
-  /**
-   * Inserts a field (or label from string), and all prefix and suffix fields,
-   * at the location of the input's field row.
-   *
-   * @param index The index at which to insert field.
-   * @param field Something to add as a field.
-   * @param opt_name Language-neutral identifier which may used to find this
-   *     field again.  Should be unique to the host block.
-   * @returns The index following the last inserted field.
-   */
-  insertFieldAt<T>(
-    index: number,
-    field: string | Field<T>,
-    opt_name?: string,
-  ): number {
-    if (index < 0 || index > this.fieldRow.length) {
-      throw Error('index ' + index + ' out of bounds.');
-    }
-    // Falsy field values don't generate a field, unless the field is an empty
-    // string and named.
-    if (!field && !(field === '' && opt_name)) {
-      return index;
-    }
-
-    // Generate a FieldLabel when given a plain text field.
-    if (typeof field === 'string') {
-      field = fieldRegistry.fromJson({
-        type: 'field_label',
-        text: field,
-      })!;
-    }
-
-    field.setSourceBlock(this.sourceBlock);
-    if (this.sourceBlock.initialized) this.initField(field);
-    field.name = opt_name;
-    field.setVisible(this.isVisible());
-
-    if (field.prefixField) {
-      // Add any prefix.
-      index = this.insertFieldAt(index, field.prefixField);
-    }
-    // Add the field to the field row.
-    this.fieldRow.splice(index, 0, field as Field);
-    index++;
-    if (field.suffixField) {
-      // Add any suffix.
-      index = this.insertFieldAt(index, field.suffixField);
-    }
-
-    if (this.sourceBlock.rendered) {
-      (this.sourceBlock as BlockSvg).queueRender();
-    }
-    return index;
-  }
-
-  /**
-   * Remove a field from this input.
-   *
-   * @param name The name of the field.
-   * @param opt_quiet True to prevent an error if field is not present.
-   * @returns True if operation succeeds, false if field is not present and
-   *     opt_quiet is true.
-   * @throws {Error} if the field is not present and opt_quiet is false.
-   */
-  removeField(name: string, opt_quiet?: boolean): boolean {
-    for (let i = 0, field; (field = this.fieldRow[i]); i++) {
-      if (field.name === name) {
-        field.dispose();
-        this.fieldRow.splice(i, 1);
-        if (this.sourceBlock.rendered) {
-          (this.sourceBlock as BlockSvg).queueRender();
-        }
-        return true;
-      }
-    }
-    if (opt_quiet) {
-      return false;
-    }
-    throw Error('Field "' + name + '" not found.');
-  }
-
-  /**
-   * Gets whether this input is visible or not.
-   *
-   * @returns True if visible.
-   */
-  isVisible(): boolean {
-    return this.visible;
-  }
-
-  /**
-   * Sets whether this input is visible or not.
-   * Should only be used to collapse/uncollapse a block.
-   *
-   * @param visible True if visible.
-   * @returns List of blocks to render.
-   * @internal
-   */
-  setVisible(visible: boolean): BlockSvg[] {
-    // Note: Currently there are only unit tests for block.setCollapsed()
-    // because this function is package. If this function goes back to being a
-    // public API tests (lots of tests) should be added.
-    let renderList: BlockSvg[] = [];
-    if (this.visible === visible) {
-      return renderList;
-    }
-    this.visible = visible;
-
-    for (let y = 0, field; (field = this.fieldRow[y]); y++) {
-      field.setVisible(visible);
-    }
-    if (this.connection && this.connection instanceof RenderedConnection) {
-      // Has a connection.
-      if (visible) {
-        renderList = this.connection.startTrackingAll();
-      } else {
-        this.connection.stopTrackingAll();
-      }
-      const child = this.connection.targetBlock();
-      if (child) {
-        child.getSvgRoot().style.display = visible ? 'block' : 'none';
-      }
-    }
-    return renderList;
-  }
-
-  /**
-   * Mark all fields on this input as dirty.
-   *
-   * @internal
-   */
-  markDirty() {
-    for (let y = 0, field; (field = this.fieldRow[y]); y++) {
-      field.markDirty();
-    }
-  }
-
-  /**
-   * Change a connection's compatibility.
-   *
-   * @param check Compatible value type or list of value types.  Null if all
-   *     types are compatible.
-   * @returns The input being modified (to allow chaining).
-   */
-  setCheck(check: string | string[] | null): Input {
-    if (!this.connection) {
-      throw Error('This input does not have a connection.');
-    }
-    this.connection.setCheck(check);
-    return this;
-  }
-
-  /**
-   * Change the alignment of the connection's field(s).
-   *
-   * @param align One of the values of Align.  In RTL mode directions
-   *     are reversed, and Align.RIGHT aligns to the left.
-   * @returns The input being modified (to allow chaining).
-   */
-  setAlign(align: Align): Input {
-    this.align = align;
-    if (this.sourceBlock.rendered) {
-      const sourceBlock = this.sourceBlock as BlockSvg;
-      sourceBlock.queueRender();
-    }
-    return this;
-  }
-
-  /**
-   * Changes the connection's shadow block.
-   *
-   * @param shadow DOM representation of a block or null.
-   * @returns The input being modified (to allow chaining).
-   */
-  setShadowDom(shadow: Element | null): Input {
-    if (!this.connection) {
-      throw Error('This input does not have a connection.');
-    }
-    this.connection.setShadowDom(shadow);
-    return this;
-  }
-
-  /**
-   * Returns the XML representation of the connection's shadow block.
-   *
-   * @returns Shadow DOM representation of a block or null.
-   */
-  getShadowDom(): Element | null {
-    if (!this.connection) {
-      throw Error('This input does not have a connection.');
-    }
-    return this.connection.getShadowDom();
-  }
-
-  /** Initialize the fields on this input. */
-  init() {
-    for (const field of this.fieldRow) {
-      field.init();
-    }
-  }
-
-  /**
-   * Initializes the fields on this input for a headless block.
-   *
-   * @internal
-   */
-  public initModel() {
-    for (const field of this.fieldRow) {
-      field.initModel();
-    }
-  }
-
-  /** Initializes the given field. */
-  private initField(field: Field) {
-    if (this.sourceBlock.rendered) {
-      field.init();
-    } else {
-      field.initModel();
-    }
-  }
-
-  /**
-   * Sever all links to this input.
-   */
-  dispose() {
-    for (let i = 0, field; (field = this.fieldRow[i]); i++) {
-      field.dispose();
-    }
-    if (this.connection) {
-      this.connection.dispose();
-    }
-  }
-
-  /**
-   * Constructs a connection based on the type of this input's source block.
-   * Properly handles constructing headless connections for headless blocks
-   * and rendered connections for rendered blocks.
-   *
-   * @returns a connection of the given type, which is either a headless
-   *     or rendered connection, based on the type of this input's source block.
-   */
-  protected makeConnection(type: ConnectionType): Connection {
-    return this.sourceBlock.makeConnection_(type);
-  }
-}

package/core/inputs/input_types.ts

@@ -1,27 +0,0 @@
-/**
- * @license
- * Copyright 2021 Google LLC
- * SPDX-License-Identifier: Apache-2.0
- */
-
-// Former goog.module ID: Blockly.inputTypes
-
-import {ConnectionType} from '../connection_type.js';
-
-/**
- * Enum for the type of a connection or input.
- */
-export enum inputTypes {
-  // A right-facing value input.  E.g. 'set item to' or 'return'.
-  VALUE = ConnectionType.INPUT_VALUE,
-  // A down-facing block stack.  E.g. 'if-do' or 'else'.
-  STATEMENT = ConnectionType.NEXT_STATEMENT,
-  // A dummy input.  Used to add field(s) with no input.
-  DUMMY = 5,
-  // An unknown type of input defined by an external developer.
-  CUSTOM = 6,
-  // An input with no connections that is always the last input of a row. Any
-  // subsequent input will be rendered on the next row. Any newline character in
-  // a JSON block definition's message will be parsed as an end-row input.
-  END_ROW = 7,
-}

package/core/inputs/statement_input.ts

@@ -1,34 +0,0 @@
-/**
- * @license
- * Copyright 2023 Google LLC
- * SPDX-License-Identifier: Apache-2.0
- */
-
-import type {Block} from '../block.js';
-import type {Connection} from '../connection.js';
-import {ConnectionType} from '../connection_type.js';
-import {Input} from './input.js';
-import {inputTypes} from './input_types.js';
-
-/** Represents an input on a block with a statement connection. */
-export class StatementInput extends Input {
-  readonly type = inputTypes.STATEMENT;
-
-  public connection: Connection;
-
-  /**
-   * @param name Language-neutral identifier which may used to find this input
-   *     again.
-   * @param block The block containing this input.
-   */
-  constructor(
-    public name: string,
-    block: Block,
-  ) {
-    // Errors are maintained for people not using typescript.
-    if (!name) throw new Error('Statement inputs must have a non-empty name');
-
-    super(name, block);
-    this.connection = this.makeConnection(ConnectionType.NEXT_STATEMENT);
-  }
-}

package/core/inputs/value_input.ts

@@ -1,30 +0,0 @@
-/**
- * @license
- * Copyright 2023 Google LLC
- * SPDX-License-Identifier: Apache-2.0
- */
-
-import type {Block} from '../block.js';
-import {ConnectionType} from '../connection_type.js';
-import {Input} from './input.js';
-import {inputTypes} from './input_types.js';
-
-/** Represents an input on a block with a value connection. */
-export class ValueInput extends Input {
-  readonly type = inputTypes.VALUE;
-
-  /**
-   * @param name Language-neutral identifier which may used to find this input
-   *     again.
-   * @param block The block containing this input.
-   */
-  constructor(
-    public name: string,
-    block: Block,
-  ) {
-    // Errors are maintained for people not using typescript.
-    if (!name) throw new Error('Value inputs must have a non-empty name');
-    super(name, block);
-    this.connection = this.makeConnection(ConnectionType.INPUT_VALUE);
-  }
-}

package/core/inputs.ts

@@ -1,23 +0,0 @@
-/**
- * @license
- * Copyright 2023 Google LLC
- * SPDX-License-Identifier: Apache-2.0
- */
-
-import {Align} from './inputs/align.js';
-import {DummyInput} from './inputs/dummy_input.js';
-import {EndRowInput} from './inputs/end_row_input.js';
-import {Input} from './inputs/input.js';
-import {inputTypes} from './inputs/input_types.js';
-import {StatementInput} from './inputs/statement_input.js';
-import {ValueInput} from './inputs/value_input.js';
-
-export {
-  Align,
-  DummyInput,
-  EndRowInput,
-  Input,
-  inputTypes,
-  StatementInput,
-  ValueInput,
-};

package/core/insertion_marker_previewer.ts

@@ -1,268 +0,0 @@
-/**
- * @license
- * Copyright 2024 Google LLC
- * SPDX-License-Identifier: Apache-2.0
- */
-
-import {BlockSvg} from './block_svg.js';
-import {ConnectionType} from './connection_type.js';
-import * as eventUtils from './events/utils.js';
-import {IConnectionPreviewer} from './interfaces/i_connection_previewer.js';
-import * as registry from './registry.js';
-import * as renderManagement from './render_management.js';
-import {RenderedConnection} from './rendered_connection.js';
-import {Renderer as ZelosRenderer} from './renderers/zelos/renderer.js';
-import * as blocks from './serialization/blocks.js';
-import {WorkspaceSvg} from './workspace_svg.js';
-
-export class InsertionMarkerPreviewer implements IConnectionPreviewer {
-  private readonly workspace: WorkspaceSvg;
-
-  private fadedBlock: BlockSvg | null = null;
-
-  private markerConn: RenderedConnection | null = null;
-
-  private draggedConn: RenderedConnection | null = null;
-
-  private staticConn: RenderedConnection | null = null;
-
-  constructor(draggedBlock: BlockSvg) {
-    this.workspace = draggedBlock.workspace;
-  }
-
-  /**
-   * 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,
-  ) {
-    eventUtils.disable();
-    try {
-      this.hidePreview();
-      this.fadedBlock = replacedBlock;
-      replacedBlock.fadeForReplacement(true);
-      if (this.workspace.getRenderer().shouldHighlightConnection(staticConn)) {
-        staticConn.highlight();
-        this.staticConn = staticConn;
-      }
-    } finally {
-      eventUtils.enable();
-    }
-  }
-
-  /**
-   * 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,
-  ) {
-    if (draggedConn === this.draggedConn && staticConn === this.staticConn) {
-      return;
-    }
-
-    eventUtils.disable();
-    try {
-      this.hidePreview();
-
-      // TODO(7898): Instead of special casing, we should change the dragger to
-      //   track the change in distance between the dragged connection and the
-      //   static connection, so that it doesn't disconnect  unless that
-      //   (+ a bit) has been exceeded.
-      if (this.shouldUseMarkerPreview(draggedConn, staticConn)) {
-        this.markerConn = this.previewMarker(draggedConn, staticConn);
-      }
-
-      if (this.workspace.getRenderer().shouldHighlightConnection(staticConn)) {
-        staticConn.highlight();
-      }
-
-      this.draggedConn = draggedConn;
-      this.staticConn = staticConn;
-    } finally {
-      eventUtils.enable();
-    }
-  }
-
-  private shouldUseMarkerPreview(
-    _draggedConn: RenderedConnection,
-    staticConn: RenderedConnection,
-  ): boolean {
-    return (
-      staticConn.type === ConnectionType.PREVIOUS_STATEMENT ||
-      staticConn.type === ConnectionType.NEXT_STATEMENT ||
-      !(this.workspace.getRenderer() instanceof ZelosRenderer)
-    );
-  }
-
-  private previewMarker(
-    draggedConn: RenderedConnection,
-    staticConn: RenderedConnection,
-  ): RenderedConnection | null {
-    const dragged = draggedConn.getSourceBlock();
-    const marker = this.createInsertionMarker(dragged);
-    const markerConn = this.getMatchingConnection(dragged, marker, draggedConn);
-    if (!markerConn) return null;
-
-    // Render disconnected from everything else so that we have a valid
-    // connection location.
-    marker.queueRender();
-    renderManagement.triggerQueuedRenders();
-
-    // Connect() also renders the insertion marker.
-    markerConn.connect(staticConn);
-
-    const originalOffsetToTarget = {
-      x: staticConn.x - markerConn.x,
-      y: staticConn.y - markerConn.y,
-    };
-    const originalOffsetInBlock = markerConn.getOffsetInBlock().clone();
-    renderManagement.finishQueuedRenders().then(() => {
-      if (marker.isDeadOrDying()) return;
-      eventUtils.disable();
-      try {
-        // Position so that the existing block doesn't move.
-        marker?.positionNearConnection(
-          markerConn,
-          originalOffsetToTarget,
-          originalOffsetInBlock,
-        );
-        marker?.getSvgRoot().setAttribute('visibility', 'visible');
-      } finally {
-        eventUtils.enable();
-      }
-    });
-    return markerConn;
-  }
-
-  /**
-   * Transforms the given block into a JSON representation used to construct an
-   * insertion marker.
-   *
-   * @param block The block to serialize and use as an insertion marker.
-   * @returns A JSON-formatted string corresponding to a serialized
-   *     representation of the given block suitable for use as an insertion
-   *     marker.
-   */
-  protected serializeBlockToInsertionMarker(block: BlockSvg) {
-    const blockJson = blocks.save(block, {
-      addCoordinates: false,
-      addInputBlocks: false,
-      addNextBlocks: false,
-      doFullSerialization: false,
-    });
-
-    if (!blockJson) {
-      throw new Error(
-        `Failed to serialize source block. ${block.toDevString()}`,
-      );
-    }
-
-    return blockJson;
-  }
-
-  private createInsertionMarker(origBlock: BlockSvg) {
-    const blockJson = this.serializeBlockToInsertionMarker(origBlock);
-    const result = blocks.append(blockJson, this.workspace) as BlockSvg;
-
-    // Turn shadow blocks that are created programmatically during
-    // initalization to insertion markers too.
-    for (const block of result.getDescendants(false)) {
-      block.setInsertionMarker(true);
-    }
-
-    result.initSvg();
-    result.getSvgRoot().setAttribute('visibility', 'hidden');
-    return result;
-  }
-
-  /**
-   * 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(
-    orig: BlockSvg,
-    marker: BlockSvg,
-    origConn: RenderedConnection,
-  ): RenderedConnection | null {
-    const origConns = orig.getConnections_(true);
-    const markerConns = marker.getConnections_(true);
-    if (origConns.length !== markerConns.length) return null;
-    for (let i = 0; i < origConns.length; i++) {
-      if (origConns[i] === origConn) {
-        return markerConns[i];
-      }
-    }
-    return null;
-  }
-
-  /** Hide any previews that are currently displayed. */
-  hidePreview() {
-    eventUtils.disable();
-    try {
-      if (this.staticConn) {
-        this.staticConn.unhighlight();
-        this.staticConn = null;
-      }
-      if (this.fadedBlock) {
-        this.fadedBlock.fadeForReplacement(false);
-        this.fadedBlock = null;
-      }
-      if (this.markerConn) {
-        this.hideInsertionMarker(this.markerConn);
-        this.markerConn = null;
-        this.draggedConn = null;
-      }
-    } finally {
-      eventUtils.enable();
-    }
-  }
-
-  private hideInsertionMarker(markerConn: RenderedConnection) {
-    const marker = markerConn.getSourceBlock();
-    const markerPrev = marker.previousConnection;
-    const markerOutput = marker.outputConnection;
-
-    if (!markerPrev?.targetConnection && !markerOutput?.targetConnection) {
-      // If we are the top block, unplugging doesn't do anything.
-      // The marker connection may not have a target block if we are hiding
-      // as part of applying connections.
-      markerConn.targetBlock()?.unplug(false);
-    } else {
-      marker.unplug(true);
-    }
-
-    marker.dispose();
-  }
-
-  /** Dispose of any references held by this connection previewer. */
-  dispose() {
-    this.hidePreview();
-  }
-}
-
-registry.register(
-  registry.Type.CONNECTION_PREVIEWER,
-  registry.DEFAULT,
-  InsertionMarkerPreviewer,
-);