blockly 12.3.1 → 12.4.0

package/core/grid.ts

@@ -0,0 +1,267 @@
+/**
+ * @license
+ * Copyright 2017 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Object for configuring and updating a workspace grid in
+ * Blockly.
+ *
+ * @class
+ */
+// Former goog.module ID: Blockly.Grid
+
+import {GridOptions} from './options.js';
+import {Coordinate} from './utils/coordinate.js';
+import * as dom from './utils/dom.js';
+import {Svg} from './utils/svg.js';
+
+/**
+ * Class for a workspace's grid.
+ */
+export class Grid {
+  private spacing: number;
+  private length: number;
+  private scale: number = 1;
+  private readonly line1: SVGElement;
+  private readonly line2: SVGElement;
+  private snapToGrid: boolean;
+
+  /**
+   * @param pattern The grid's SVG pattern, created during injection.
+   * @param options A dictionary of normalized options for the grid.
+   *     See grid documentation:
+   *     https://developers.google.com/blockly/guides/configure/web/grid
+   */
+  constructor(
+    private pattern: SVGElement,
+    options: GridOptions,
+  ) {
+    /** The spacing of the grid lines (in px). */
+    this.spacing = options['spacing'] ?? 0;
+
+    /** How long the grid lines should be (in px). */
+    this.length = options['length'] ?? 1;
+
+    /** The horizontal grid line, if it exists. */
+    this.line1 = pattern.firstChild as SVGElement;
+
+    /** The vertical grid line, if it exists. */
+    this.line2 = this.line1 && (this.line1.nextSibling as SVGElement);
+
+    /** Whether blocks should snap to the grid. */
+    this.snapToGrid = options['snap'] ?? false;
+  }
+
+  /**
+   * Sets the spacing between the centers of the grid lines.
+   *
+   * This does not trigger snapping to the newly spaced grid. If you want to
+   * snap blocks to the grid programmatically that needs to be triggered
+   * on individual top-level blocks. The next time a block is dragged and
+   * dropped it will snap to the grid if snapping to the grid is enabled.
+   */
+  setSpacing(spacing: number) {
+    this.spacing = spacing;
+    this.update(this.scale);
+  }
+
+  /**
+   * Get the spacing of the grid points (in px).
+   *
+   * @returns The spacing of the grid points.
+   */
+  getSpacing(): number {
+    return this.spacing;
+  }
+
+  /** Sets the length of the grid lines. */
+  setLength(length: number) {
+    this.length = length;
+    this.update(this.scale);
+  }
+
+  /** Get the length of the grid lines (in px). */
+  getLength(): number {
+    return this.length;
+  }
+
+  /**
+   * Sets whether blocks should snap to the grid or not.
+   *
+   * Setting this to true does not trigger snapping. If you want to snap blocks
+   * to the grid programmatically that needs to be triggered on individual
+   * top-level blocks. The next time a block is dragged and dropped it will
+   * snap to the grid.
+   */
+  setSnapToGrid(snap: boolean) {
+    this.snapToGrid = snap;
+  }
+
+  /**
+   * Whether blocks should snap to the grid.
+   *
+   * @returns True if blocks should snap, false otherwise.
+   */
+  shouldSnap(): boolean {
+    return this.snapToGrid;
+  }
+
+  /**
+   * Get the ID of the pattern element, which should be randomized to avoid
+   * conflicts with other Blockly instances on the page.
+   *
+   * @returns The pattern ID.
+   * @internal
+   */
+  getPatternId(): string {
+    return this.pattern.id;
+  }
+
+  /**
+   * Update the grid with a new scale.
+   *
+   * @param scale The new workspace scale.
+   * @internal
+   */
+  update(scale: number) {
+    this.scale = scale;
+    const safeSpacing = this.spacing * scale;
+
+    this.pattern.setAttribute('width', `${safeSpacing}`);
+    this.pattern.setAttribute('height', `${safeSpacing}`);
+
+    let half = Math.floor(this.spacing / 2) + 0.5;
+    let start = half - this.length / 2;
+    let end = half + this.length / 2;
+
+    half *= scale;
+    start *= scale;
+    end *= scale;
+
+    this.setLineAttributes(this.line1, scale, start, end, half, half);
+    this.setLineAttributes(this.line2, scale, half, half, start, end);
+  }
+
+  /**
+   * Set the attributes on one of the lines in the grid.  Use this to update the
+   * length and stroke width of the grid lines.
+   *
+   * @param line Which line to update.
+   * @param width The new stroke size (in px).
+   * @param x1 The new x start position of the line (in px).
+   * @param x2 The new x end position of the line (in px).
+   * @param y1 The new y start position of the line (in px).
+   * @param y2 The new y end position of the line (in px).
+   */
+  private setLineAttributes(
+    line: SVGElement,
+    width: number,
+    x1: number,
+    x2: number,
+    y1: number,
+    y2: number,
+  ) {
+    if (line) {
+      line.setAttribute('stroke-width', `${width}`);
+      line.setAttribute('x1', `${x1}`);
+      line.setAttribute('y1', `${y1}`);
+      line.setAttribute('x2', `${x2}`);
+      line.setAttribute('y2', `${y2}`);
+    }
+  }
+
+  /**
+   * Move the grid to a new x and y position, and make sure that change is
+   * visible.
+   *
+   * @param x The new x position of the grid (in px).
+   * @param y The new y position of the grid (in px).
+   * @internal
+   */
+  moveTo(x: number, y: number) {
+    this.pattern.setAttribute('x', `${x}`);
+    this.pattern.setAttribute('y', `${y}`);
+  }
+
+  /**
+   * 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 {
+    const spacing = this.getSpacing();
+    const half = spacing / 2;
+    const x = Math.round(Math.round((xy.x - half) / spacing) * spacing + half);
+    const y = Math.round(Math.round((xy.y - half) / spacing) * spacing + half);
+    if (x === xy.x && y === xy.y) {
+      // No change.
+      return xy;
+    }
+    return new Coordinate(x, y);
+  }
+
+  /**
+   * Create the DOM for the grid described by options.
+   *
+   * @param rnd A random ID to append to the pattern's ID.
+   * @param gridOptions The object containing grid configuration.
+   * @param defs The root SVG element for this workspace's defs.
+   * @param injectionDiv The div containing the parent workspace and all related
+   *   workspaces and block containers. CSS variables representing SVG patterns
+   *   will be scoped to this container.
+   * @returns The SVG element for the grid pattern.
+   * @internal
+   */
+  static createDom(
+    rnd: string,
+    gridOptions: GridOptions,
+    defs: SVGElement,
+    injectionDiv?: HTMLElement,
+  ): SVGElement {
+    /*
+          <pattern id="blocklyGridPattern837493" patternUnits="userSpaceOnUse">
+            <rect stroke="#888" />
+            <rect stroke="#888" />
+          </pattern>
+        */
+    const gridPattern = dom.createSvgElement(
+      Svg.PATTERN,
+      {'id': 'blocklyGridPattern' + rnd, 'patternUnits': 'userSpaceOnUse'},
+      defs,
+    );
+    // x1, y1, x1, x2 properties will be set later in update.
+    if ((gridOptions['length'] ?? 1) > 0 && (gridOptions['spacing'] ?? 0) > 0) {
+      dom.createSvgElement(
+        Svg.LINE,
+        {'stroke': gridOptions['colour']},
+        gridPattern,
+      );
+      if (gridOptions['length'] ?? 1 > 1) {
+        dom.createSvgElement(
+          Svg.LINE,
+          {'stroke': gridOptions['colour']},
+          gridPattern,
+        );
+      }
+    } else {
+      // Edge 16 doesn't handle empty patterns
+      dom.createSvgElement(Svg.LINE, {}, gridPattern);
+    }
+
+    if (injectionDiv) {
+      // Add CSS variables scoped to the injection div referencing the created
+      // patterns so that CSS can apply the patterns to any element in the
+      // injection div.
+      injectionDiv.style.setProperty(
+        '--blocklyGridPattern',
+        `url(#${gridPattern.id})`,
+      );
+    }
+
+    return gridPattern;
+  }
+}

package/core/icons/comment_icon.ts

@@ -0,0 +1,429 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+// Former goog.module ID: Blockly.Comment
+
+import type {Block} from '../block.js';
+import type {BlockSvg} from '../block_svg.js';
+import {TextInputBubble} from '../bubbles/textinput_bubble.js';
+import {EventType} from '../events/type.js';
+import * as eventUtils from '../events/utils.js';
+import type {IHasBubble} from '../interfaces/i_has_bubble.js';
+import type {ISerializable} from '../interfaces/i_serializable.js';
+import * as renderManagement from '../render_management.js';
+import {Coordinate} from '../utils.js';
+import * as dom from '../utils/dom.js';
+import {Rect} from '../utils/rect.js';
+import {Size} from '../utils/size.js';
+import {Svg} from '../utils/svg.js';
+import type {WorkspaceSvg} from '../workspace_svg.js';
+import {Icon} from './icon.js';
+import {IconType} from './icon_types.js';
+import * as registry from './registry.js';
+
+/** The size of the comment icon in workspace-scale units. */
+const SIZE = 17;
+
+/** The default width in workspace-scale units of the text input bubble. */
+const DEFAULT_BUBBLE_WIDTH = 160;
+
+/** The default height in workspace-scale units of the text input bubble. */
+const DEFAULT_BUBBLE_HEIGHT = 80;
+
+/**
+ * An icon which allows the user to add comment text to a block.
+ */
+export class CommentIcon extends Icon implements IHasBubble, ISerializable {
+  /** The type string used to identify this icon. */
+  static readonly TYPE = IconType.COMMENT;
+
+  /**
+   * The weight this icon has relative to other icons. Icons with more positive
+   * weight values are rendered farther toward the end of the block.
+   */
+  static readonly WEIGHT = 3;
+
+  /** The bubble used to show comment text to the user. */
+  private textInputBubble: TextInputBubble | null = null;
+
+  /** The text of this comment. */
+  private text = '';
+
+  /** The size of this comment (which is applied to the editable bubble). */
+  private bubbleSize = new Size(DEFAULT_BUBBLE_WIDTH, DEFAULT_BUBBLE_HEIGHT);
+
+  /** The location of the comment bubble in workspace coordinates. */
+  private bubbleLocation?: Coordinate;
+
+  /**
+   * The visibility of the bubble for this comment.
+   *
+   * This is used to track what the visible state /should/ be, not necessarily
+   * what it currently /is/. E.g. sometimes this will be true, but the block
+   * hasn't been rendered yet, so the bubble will not currently be visible.
+   */
+  private bubbleVisiblity = false;
+
+  constructor(protected readonly sourceBlock: Block) {
+    super(sourceBlock);
+  }
+
+  override getType(): IconType<CommentIcon> {
+    return CommentIcon.TYPE;
+  }
+
+  override initView(pointerdownListener: (e: PointerEvent) => void): void {
+    if (this.svgRoot) return; // Already initialized.
+
+    super.initView(pointerdownListener);
+
+    // Circle.
+    dom.createSvgElement(
+      Svg.CIRCLE,
+      {'class': 'blocklyIconShape', 'r': '8', 'cx': '8', 'cy': '8'},
+      this.svgRoot,
+    );
+    // Can't use a real '?' text character since different browsers and
+    // operating systems render it differently. Body of question mark.
+    dom.createSvgElement(
+      Svg.PATH,
+      {
+        'class': 'blocklyIconSymbol',
+        'd':
+          'm6.8,10h2c0.003,-0.617 0.271,-0.962 0.633,-1.266 2.875,-2.405' +
+          '0.607,-5.534 -3.765,-3.874v1.7c3.12,-1.657 3.698,0.118 2.336,1.25' +
+          '-1.201,0.998 -1.201,1.528 -1.204,2.19z',
+      },
+      this.svgRoot,
+    );
+    // Dot of question mark.
+    dom.createSvgElement(
+      Svg.RECT,
+      {
+        'class': 'blocklyIconSymbol',
+        'x': '6.8',
+        'y': '10.78',
+        'height': '2',
+        'width': '2',
+      },
+      this.svgRoot,
+    );
+    dom.addClass(this.svgRoot!, 'blocklyCommentIcon');
+  }
+
+  override dispose() {
+    super.dispose();
+    this.textInputBubble?.dispose();
+  }
+
+  override getWeight(): number {
+    return CommentIcon.WEIGHT;
+  }
+
+  override getSize(): Size {
+    return new Size(SIZE, SIZE);
+  }
+
+  override applyColour(): void {
+    super.applyColour();
+    const colour = (this.sourceBlock as BlockSvg).getColour();
+    this.textInputBubble?.setColour(colour);
+  }
+
+  /**
+   * Updates the state of the bubble (editable / noneditable) to reflect the
+   * state of the bubble if the bubble is currently shown.
+   */
+  override async updateEditable(): Promise<void> {
+    super.updateEditable();
+    if (this.bubbleIsVisible()) {
+      // Close and reopen the bubble to display the correct UI.
+      await this.setBubbleVisible(false);
+      await this.setBubbleVisible(true);
+    }
+  }
+
+  override onLocationChange(blockOrigin: Coordinate): void {
+    const oldLocation = this.workspaceLocation;
+    super.onLocationChange(blockOrigin);
+    if (this.bubbleLocation) {
+      const newLocation = this.workspaceLocation;
+      const delta = Coordinate.difference(newLocation, oldLocation);
+      this.bubbleLocation = Coordinate.sum(this.bubbleLocation, delta);
+    }
+    const anchorLocation = this.getAnchorLocation();
+    this.textInputBubble?.setAnchorLocation(anchorLocation);
+  }
+
+  /** Sets the text of this comment. Updates any bubbles if they are visible. */
+  setText(text: string) {
+    const oldText = this.text;
+    eventUtils.fire(
+      new (eventUtils.get(EventType.BLOCK_CHANGE))(
+        this.sourceBlock,
+        'comment',
+        null,
+        oldText,
+        text,
+      ),
+    );
+    this.text = text;
+    this.textInputBubble?.setText(this.text);
+  }
+
+  /** Returns the text of this comment. */
+  getText(): string {
+    return this.text;
+  }
+
+  /**
+   * Sets the size of the editable bubble for this comment. Resizes the
+   * bubble if it is visible.
+   */
+  setBubbleSize(size: Size) {
+    this.bubbleSize = size;
+    this.textInputBubble?.setSize(this.bubbleSize, true);
+  }
+
+  /** @returns the size of the editable bubble for this comment. */
+  getBubbleSize(): Size {
+    return this.bubbleSize;
+  }
+
+  /**
+   * Sets the location of the comment bubble in the workspace.
+   */
+  setBubbleLocation(location: Coordinate) {
+    this.bubbleLocation = location;
+    this.textInputBubble?.moveDuringDrag(location);
+  }
+
+  /**
+   * @returns the location of the comment bubble in the workspace.
+   */
+  getBubbleLocation(): Coordinate | undefined {
+    return this.bubbleLocation;
+  }
+
+  /**
+   * @returns the state of the comment as a JSON serializable value if the
+   * comment has text. Otherwise returns null.
+   */
+  saveState(): CommentState | null {
+    if (this.text) {
+      const state: CommentState = {
+        'text': this.text,
+        'pinned': this.bubbleIsVisible(),
+        'height': this.bubbleSize.height,
+        'width': this.bubbleSize.width,
+      };
+      const location = this.getBubbleLocation();
+      if (location) {
+        state['x'] = this.sourceBlock.workspace.RTL
+          ? this.sourceBlock.workspace.getWidth() -
+            (location.x + this.bubbleSize.width)
+          : location.x;
+        state['y'] = location.y;
+      }
+      return state;
+    }
+    return null;
+  }
+
+  /** Applies the given state to this comment. */
+  loadState(state: CommentState) {
+    this.text = state['text'] ?? '';
+    this.bubbleSize = new Size(
+      state['width'] ?? DEFAULT_BUBBLE_WIDTH,
+      state['height'] ?? DEFAULT_BUBBLE_HEIGHT,
+    );
+    this.bubbleVisiblity = state['pinned'] ?? false;
+    this.setBubbleVisible(this.bubbleVisiblity);
+    let x = state['x'];
+    const y = state['y'];
+    renderManagement.finishQueuedRenders().then(() => {
+      if (x && y) {
+        x = this.sourceBlock.workspace.RTL
+          ? this.sourceBlock.workspace.getWidth() - (x + this.bubbleSize.width)
+          : x;
+        this.setBubbleLocation(new Coordinate(x, y));
+      }
+    });
+  }
+
+  override onClick(): void {
+    super.onClick();
+    this.setBubbleVisible(!this.bubbleIsVisible());
+  }
+
+  override isClickableInFlyout(): boolean {
+    return false;
+  }
+
+  /**
+   * Updates the text of this comment in response to changes in the text of
+   * the input bubble.
+   */
+  onTextChange(): void {
+    if (!this.textInputBubble) return;
+
+    const newText = this.textInputBubble.getText();
+    if (this.text === newText) return;
+
+    eventUtils.fire(
+      new (eventUtils.get(EventType.BLOCK_CHANGE))(
+        this.sourceBlock,
+        'comment',
+        null,
+        this.text,
+        newText,
+      ),
+    );
+    this.text = newText;
+  }
+
+  /**
+   * Updates the size of this icon in response to changes in the size of the
+   * input bubble.
+   */
+  onSizeChange(): void {
+    if (this.textInputBubble) {
+      this.bubbleSize = this.textInputBubble.getSize();
+    }
+  }
+
+  onBubbleLocationChange(): void {
+    if (this.textInputBubble) {
+      this.bubbleLocation = this.textInputBubble.getRelativeToSurfaceXY();
+    }
+  }
+
+  bubbleIsVisible(): boolean {
+    return this.bubbleVisiblity;
+  }
+
+  async setBubbleVisible(visible: boolean): Promise<void> {
+    if (this.bubbleVisiblity === visible) return;
+    this.bubbleVisiblity = visible;
+
+    await renderManagement.finishQueuedRenders();
+
+    if (
+      !this.sourceBlock.rendered ||
+      this.sourceBlock.isInFlyout ||
+      this.sourceBlock.isInsertionMarker()
+    )
+      return;
+
+    if (visible) {
+      if (this.sourceBlock.isEditable()) {
+        this.showEditableBubble();
+      } else {
+        this.showNonEditableBubble();
+      }
+      this.applyColour();
+    } else {
+      this.hideBubble();
+    }
+
+    eventUtils.fire(
+      new (eventUtils.get(EventType.BUBBLE_OPEN))(
+        this.sourceBlock,
+        visible,
+        'comment',
+      ),
+    );
+  }
+
+  /** See IHasBubble.getBubble. */
+  getBubble(): TextInputBubble | null {
+    return this.textInputBubble;
+  }
+
+  /**
+   * Shows the editable text bubble for this comment, and adds change listeners
+   * to update the state of this icon in response to changes in the bubble.
+   */
+  private showEditableBubble() {
+    this.createBubble();
+    this.textInputBubble?.addTextChangeListener(() => this.onTextChange());
+    this.textInputBubble?.addSizeChangeListener(() => this.onSizeChange());
+  }
+
+  /** Shows the non editable text bubble for this comment. */
+  private showNonEditableBubble() {
+    this.createBubble();
+    this.textInputBubble?.setEditable(false);
+  }
+
+  protected createBubble() {
+    this.textInputBubble = new TextInputBubble(
+      this.sourceBlock.workspace as WorkspaceSvg,
+      this.getAnchorLocation(),
+      this.getBubbleOwnerRect(),
+      this,
+    );
+    this.textInputBubble.setText(this.getText());
+    this.textInputBubble.setSize(this.bubbleSize, true);
+    if (this.bubbleLocation) {
+      this.textInputBubble.moveDuringDrag(this.bubbleLocation);
+    }
+    this.textInputBubble.addTextChangeListener(() => this.onTextChange());
+    this.textInputBubble.addSizeChangeListener(() => this.onSizeChange());
+    this.textInputBubble.addLocationChangeListener(() =>
+      this.onBubbleLocationChange(),
+    );
+  }
+
+  /** Hides any open bubbles owned by this comment. */
+  private hideBubble() {
+    this.textInputBubble?.dispose();
+    this.textInputBubble = null;
+  }
+
+  /**
+   * @returns the location the bubble should be anchored to.
+   *     I.E. the middle of this icon.
+   */
+  private getAnchorLocation(): Coordinate {
+    const midIcon = SIZE / 2;
+    return Coordinate.sum(
+      this.workspaceLocation,
+      new Coordinate(midIcon, midIcon),
+    );
+  }
+
+  /**
+   * @returns the rect the bubble should avoid overlapping.
+   *     I.E. the block that owns this icon.
+   */
+  private getBubbleOwnerRect(): Rect {
+    return (this.sourceBlock as BlockSvg).getBoundingRectangleWithoutChildren();
+  }
+}
+
+/** The save state format for a comment icon. */
+export interface CommentState {
+  /** The text of the comment. */
+  text?: string;
+
+  /** True if the comment is open, false otherwise. */
+  pinned?: boolean;
+
+  /** The height of the comment bubble. */
+  height?: number;
+
+  /** The width of the comment bubble. */
+  width?: number;
+
+  /** The X coordinate of the comment bubble. */
+  x?: number;
+
+  /** The Y coordinate of the comment bubble. */
+  y?: number;
+}
+
+registry.register(CommentIcon.TYPE, CommentIcon);

package/core/icons/exceptions.ts

@@ -0,0 +1,23 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type {IIcon} from '../interfaces/i_icon.js';
+
+/**
+ * Thrown when you add more than one icon of the same type to a block.
+ */
+export class DuplicateIconType extends Error {
+  /**
+   * @internal
+   */
+  constructor(public icon: IIcon) {
+    super(
+      `Tried to append an icon of type ${icon.getType()} when an icon of ` +
+        `that type already exists on the block. ` +
+        `Use getIcon to access the existing icon.`,
+    );
+  }
+}