blockly 12.3.1 → 12.4.0

package/core/bubbles/mini_workspace_bubble.ts

@@ -0,0 +1,292 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type {BlocklyOptions} from '../blockly_options.js';
+import {Abstract as AbstractEvent} from '../events/events_abstract.js';
+import {Options} from '../options.js';
+import {Coordinate} from '../utils/coordinate.js';
+import * as dom from '../utils/dom.js';
+import type {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 {Bubble} from './bubble.js';
+
+/**
+ * A bubble that contains a mini-workspace which can hold arbitrary blocks.
+ * Used by the mutator icon.
+ */
+export class MiniWorkspaceBubble extends Bubble {
+  /**
+   * The minimum amount of change to the mini workspace view to trigger
+   * resizing the bubble.
+   */
+  private static readonly MINIMUM_VIEW_CHANGE = 10;
+
+  /**
+   * An arbitrary margin of whitespace to put around the blocks in the
+   * workspace.
+   */
+  private static readonly MARGIN = Bubble.DOUBLE_BORDER * 3;
+
+  /** The root svg element containing the workspace. */
+  private svgDialog: SVGElement;
+
+  /** The workspace that gets shown within this bubble. */
+  private miniWorkspace: WorkspaceSvg;
+
+  /**
+   * Should this bubble automatically reposition itself when it resizes?
+   * Becomes false after this bubble is first dragged.
+   */
+  private autoLayout = true;
+
+  /** @internal */
+  constructor(
+    workspaceOptions: BlocklyOptions,
+    public readonly workspace: WorkspaceSvg,
+    protected anchor: Coordinate,
+    protected ownerRect?: Rect,
+  ) {
+    super(workspace, anchor, ownerRect);
+    const options = new Options(workspaceOptions);
+    this.validateWorkspaceOptions(options);
+
+    this.svgDialog = dom.createSvgElement(
+      Svg.SVG,
+      {
+        'x': Bubble.BORDER_WIDTH,
+        'y': Bubble.BORDER_WIDTH,
+      },
+      this.contentContainer,
+    );
+    workspaceOptions.parentWorkspace = this.workspace;
+    this.miniWorkspace = this.newWorkspaceSvg(new Options(workspaceOptions));
+    // TODO (#7422): Change this to `internalIsMiniWorkspace` or something. Not
+    //   all mini workspaces are necessarily mutators.
+    this.miniWorkspace.internalIsMutator = true;
+    const background = this.miniWorkspace.createDom('blocklyMutatorBackground');
+    this.svgDialog.appendChild(background);
+    if (options.languageTree) {
+      background.insertBefore(
+        this.miniWorkspace.addFlyout(Svg.G),
+        this.miniWorkspace.getCanvas(),
+      );
+      const flyout = this.miniWorkspace.getFlyout();
+      flyout?.init(this.miniWorkspace);
+      flyout?.show(options.languageTree);
+    }
+
+    dom.addClass(this.svgRoot, 'blocklyMiniWorkspaceBubble');
+    this.miniWorkspace.addChangeListener(this.onWorkspaceChange.bind(this));
+    this.miniWorkspace
+      .getFlyout()
+      ?.getWorkspace()
+      ?.addChangeListener(this.onWorkspaceChange.bind(this));
+    this.updateBubbleSize();
+  }
+
+  dispose() {
+    this.miniWorkspace.dispose();
+    super.dispose();
+  }
+
+  /** @internal */
+  getWorkspace(): WorkspaceSvg {
+    return this.miniWorkspace;
+  }
+
+  /** Adds a change listener to the mini workspace. */
+  addWorkspaceChangeListener(listener: (e: AbstractEvent) => void) {
+    this.miniWorkspace.addChangeListener(listener);
+  }
+
+  /**
+   * Validates the workspace options to make sure folks aren't trying to
+   * enable things the miniworkspace doesn't support.
+   */
+  private validateWorkspaceOptions(options: Options) {
+    if (options.hasCategories) {
+      throw new Error(
+        'The miniworkspace bubble does not support toolboxes with categories',
+      );
+    }
+    if (options.hasTrashcan) {
+      throw new Error('The miniworkspace bubble does not support trashcans');
+    }
+    if (
+      options.zoomOptions.controls ||
+      options.zoomOptions.wheel ||
+      options.zoomOptions.pinch
+    ) {
+      throw new Error('The miniworkspace bubble does not support zooming');
+    }
+    if (
+      options.moveOptions.scrollbars ||
+      options.moveOptions.wheel ||
+      options.moveOptions.drag
+    ) {
+      throw new Error(
+        'The miniworkspace bubble does not scrolling/moving the workspace',
+      );
+    }
+    if (options.horizontalLayout) {
+      throw new Error(
+        'The miniworkspace bubble does not support horizontal layouts',
+      );
+    }
+  }
+
+  private onWorkspaceChange() {
+    this.bumpBlocksIntoBounds();
+    this.updateBubbleSize();
+  }
+
+  /**
+   * Bumps blocks that are above the top or outside the start-side of the
+   * workspace back within the workspace.
+   *
+   * Blocks that are below the bottom or outside the end-side of the workspace
+   * are dealt with by resizing the workspace to show them.
+   */
+  private bumpBlocksIntoBounds() {
+    if (
+      this.miniWorkspace.isDragging() &&
+      !this.miniWorkspace.keyboardMoveInProgress
+    )
+      return;
+
+    const MARGIN = 20;
+
+    for (const block of this.miniWorkspace.getTopBlocks(false)) {
+      const blockXY = block.getRelativeToSurfaceXY();
+
+      // Bump any block that's above the top back inside.
+      if (blockXY.y < MARGIN) {
+        block.moveBy(0, MARGIN - blockXY.y);
+      }
+      // Bump any block overlapping the flyout back inside.
+      if (block.RTL) {
+        let right = -MARGIN;
+        const flyout = this.miniWorkspace.getFlyout();
+        if (flyout) {
+          right -= flyout.getWidth();
+        }
+        if (blockXY.x > right) {
+          block.moveBy(right - blockXY.x, 0);
+        }
+      } else if (blockXY.x < MARGIN) {
+        block.moveBy(MARGIN - blockXY.x, 0);
+      }
+    }
+  }
+
+  /**
+   * Updates the size of this bubble to account for the size of the
+   * mini workspace.
+   */
+  private updateBubbleSize() {
+    if (
+      this.miniWorkspace.isDragging() &&
+      !this.miniWorkspace.keyboardMoveInProgress
+    )
+      return;
+
+    // Disable autolayout if a keyboard move is in progress to prevent the
+    // mutator bubble from jumping around.
+    this.autoLayout &&= !this.miniWorkspace.keyboardMoveInProgress;
+
+    const currSize = this.getSize();
+    const newSize = this.calculateWorkspaceSize();
+    if (
+      Math.abs(currSize.width - newSize.width) <
+        MiniWorkspaceBubble.MINIMUM_VIEW_CHANGE &&
+      Math.abs(currSize.height - newSize.height) <
+        MiniWorkspaceBubble.MINIMUM_VIEW_CHANGE
+    ) {
+      // Only resize if the size has noticeably changed.
+      return;
+    }
+    this.svgDialog.setAttribute('width', `${newSize.width}px`);
+    this.svgDialog.setAttribute('height', `${newSize.height}px`);
+    this.miniWorkspace.setCachedParentSvgSize(newSize.width, newSize.height);
+    if (this.miniWorkspace.RTL) {
+      // Scroll the workspace to always left-align.
+      this.miniWorkspace
+        .getCanvas()
+        .setAttribute('transform', `translate(${newSize.width}, 0)`);
+    }
+    this.setSize(
+      new Size(
+        newSize.width + Bubble.DOUBLE_BORDER,
+        newSize.height + Bubble.DOUBLE_BORDER,
+      ),
+      this.autoLayout,
+    );
+    this.miniWorkspace.resize();
+    this.miniWorkspace.recordDragTargets();
+  }
+
+  /**
+   * Calculates the size of the mini workspace for use in resizing the bubble.
+   */
+  private calculateWorkspaceSize(): Size {
+    const workspaceSize = this.miniWorkspace.getCanvas().getBBox();
+    let width = workspaceSize.width + MiniWorkspaceBubble.MARGIN;
+    let height = workspaceSize.height + MiniWorkspaceBubble.MARGIN;
+
+    const flyout = this.miniWorkspace.getFlyout();
+    if (flyout) {
+      const flyoutScrollMetrics = flyout
+        .getWorkspace()
+        .getMetricsManager()
+        .getScrollMetrics();
+      height = Math.max(height, flyoutScrollMetrics.height + 20);
+      width += flyout.getWidth();
+    }
+    return new Size(width, height);
+  }
+
+  /** Reapplies styles to all of the blocks in the mini workspace. */
+  updateBlockStyles() {
+    for (const block of this.miniWorkspace.getAllBlocks(false)) {
+      block.setStyle(block.getStyleName());
+    }
+
+    const flyoutWs = this.miniWorkspace.getFlyout()?.getWorkspace();
+    if (flyoutWs) {
+      for (const block of flyoutWs.getAllBlocks(false)) {
+        block.setStyle(block.getStyleName());
+      }
+    }
+  }
+
+  /**
+   * Move this bubble during a drag.
+   *
+   * @param newLoc The location to translate to, in workspace coordinates.
+   * @internal
+   */
+  moveDuringDrag(newLoc: Coordinate): void {
+    super.moveDuringDrag(newLoc);
+    this.autoLayout = false;
+  }
+
+  /** @internal */
+  moveTo(x: number, y: number): void {
+    super.moveTo(x, y);
+    this.miniWorkspace.recordDragTargets();
+  }
+
+  /** @internal */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  newWorkspaceSvg(options: Options): WorkspaceSvg {
+    throw new Error(
+      'The implementation of newWorkspaceSvg should be ' +
+        'monkey-patched in by blockly.ts',
+    );
+  }
+}

package/core/bubbles/text_bubble.ts

@@ -0,0 +1,112 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {Coordinate} from '../utils/coordinate.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 {WorkspaceSvg} from '../workspace_svg.js';
+import {Bubble} from './bubble.js';
+
+/**
+ * A bubble that displays non-editable text. Used by the warning icon.
+ */
+export class TextBubble extends Bubble {
+  private paragraph: SVGGElement;
+
+  constructor(
+    private text: string,
+    public readonly workspace: WorkspaceSvg,
+    protected anchor: Coordinate,
+    protected ownerRect?: Rect,
+  ) {
+    super(workspace, anchor, ownerRect);
+    this.paragraph = this.stringToSvg(text, this.contentContainer);
+    this.updateBubbleSize();
+    dom.addClass(this.svgRoot, 'blocklyTextBubble');
+  }
+
+  /** @returns the current text of this text bubble. */
+  getText(): string {
+    return this.text;
+  }
+
+  /** Sets the current text of this text bubble, and updates the display. */
+  setText(text: string) {
+    this.text = text;
+    dom.removeNode(this.paragraph);
+    this.paragraph = this.stringToSvg(text, this.contentContainer);
+    this.updateBubbleSize();
+  }
+
+  /**
+   * Converts the given string into an svg containing that string,
+   * broken up by newlines.
+   */
+  private stringToSvg(text: string, container: SVGGElement) {
+    const paragraph = this.createParagraph(container);
+    const fragments = this.createTextFragments(paragraph, text);
+    if (this.workspace.RTL)
+      this.rightAlignTextFragments(paragraph.getBBox().width, fragments);
+    return paragraph;
+  }
+
+  /** Creates the paragraph container for this bubble's view's text fragments. */
+  private createParagraph(container: SVGGElement): SVGGElement {
+    return dom.createSvgElement(
+      Svg.G,
+      {
+        'class': 'blocklyText blocklyBubbleText blocklyNoPointerEvents',
+        'transform': `translate(0,${Bubble.BORDER_WIDTH})`,
+        'style': `direction: ${this.workspace.RTL ? 'rtl' : 'ltr'}`,
+      },
+      container,
+    );
+  }
+
+  /** Creates the text fragments visualizing the text of this bubble. */
+  private createTextFragments(
+    parent: SVGGElement,
+    text: string,
+  ): SVGTextElement[] {
+    let lineNum = 1;
+    return text.split('\n').map((line) => {
+      const fragment = dom.createSvgElement(
+        Svg.TEXT,
+        {'y': `${lineNum}em`, 'x': Bubble.BORDER_WIDTH},
+        parent,
+      );
+      const textNode = document.createTextNode(line);
+      fragment.appendChild(textNode);
+      lineNum += 1;
+      return fragment;
+    });
+  }
+
+  /** Right aligns the given text fragments. */
+  private rightAlignTextFragments(
+    maxWidth: number,
+    fragments: SVGTextElement[],
+  ) {
+    for (const text of fragments) {
+      text.setAttribute('text-anchor', 'start');
+      text.setAttribute('x', `${maxWidth + Bubble.BORDER_WIDTH}`);
+    }
+  }
+
+  /** Updates the size of this bubble to account for the size of the text. */
+  private updateBubbleSize() {
+    const bbox = this.paragraph.getBBox();
+    this.setSize(
+      new Size(
+        bbox.width + Bubble.BORDER_WIDTH * 2,
+        bbox.height + Bubble.BORDER_WIDTH * 2,
+      ),
+      true,
+    );
+  }
+}

package/core/bubbles/textinput_bubble.ts

@@ -0,0 +1,296 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {CommentEditor} from '../comments/comment_editor.js';
+import * as Css from '../css.js';
+import {getFocusManager} from '../focus_manager.js';
+import type {IFocusableNode} from '../interfaces/i_focusable_node.js';
+import type {IHasBubble} from '../interfaces/i_has_bubble.js';
+import * as touch from '../touch.js';
+import {browserEvents} from '../utils.js';
+import {Coordinate} from '../utils/coordinate.js';
+import * as dom from '../utils/dom.js';
+import * as drag from '../utils/drag.js';
+import {Rect} from '../utils/rect.js';
+import {Size} from '../utils/size.js';
+import {Svg} from '../utils/svg.js';
+import {WorkspaceSvg} from '../workspace_svg.js';
+import {Bubble} from './bubble.js';
+
+/**
+ * A bubble that displays editable text. It can also be resized by the user.
+ * Used by the comment icon.
+ */
+export class TextInputBubble extends Bubble {
+  /** The group containing the lines indicating the bubble is resizable. */
+  private resizeGroup: SVGGElement;
+
+  /**
+   * Event data associated with the listener for pointer up events on the
+   * resize group.
+   */
+  private resizePointerUpListener: browserEvents.Data | null = null;
+
+  /**
+   * Event data associated with the listener for pointer move events on the
+   * resize group.
+   */
+  private resizePointerMoveListener: browserEvents.Data | null = null;
+
+  /** Functions listening for changes to the size of this bubble. */
+  private sizeChangeListeners: (() => void)[] = [];
+
+  /** Functions listening for changes to the location of this bubble. */
+  private locationChangeListeners: (() => void)[] = [];
+
+  /** The default size of this bubble, including borders. */
+  private readonly DEFAULT_SIZE = new Size(
+    160 + Bubble.DOUBLE_BORDER,
+    80 + Bubble.DOUBLE_BORDER,
+  );
+
+  /** The minimum size of this bubble, including borders. */
+  private readonly MIN_SIZE = new Size(
+    45 + Bubble.DOUBLE_BORDER,
+    20 + Bubble.DOUBLE_BORDER,
+  );
+
+  private editable = true;
+
+  /** View responsible for supporting text editing. */
+  private editor: CommentEditor;
+
+  /**
+   * @param workspace The workspace this bubble belongs to.
+   * @param anchor The anchor location of the thing this bubble is attached to.
+   *     The tail of the bubble will point to this location.
+   * @param ownerRect An optional rect we don't want the bubble to overlap with
+   *     when automatically positioning.
+   * @param owner The object that owns/hosts this bubble.
+   */
+  constructor(
+    public readonly workspace: WorkspaceSvg,
+    protected anchor: Coordinate,
+    protected ownerRect?: Rect,
+    protected owner?: IHasBubble & IFocusableNode,
+  ) {
+    super(workspace, anchor, ownerRect, undefined, owner);
+    dom.addClass(this.svgRoot, 'blocklyTextInputBubble');
+    this.editor = new CommentEditor(workspace, this.id, () => {
+      getFocusManager().focusNode(this);
+    });
+    this.contentContainer.appendChild(this.editor.getDom());
+    this.resizeGroup = this.createResizeHandle(this.svgRoot, workspace);
+    this.setSize(this.DEFAULT_SIZE, true);
+  }
+
+  /** @returns the text of this bubble. */
+  getText(): string {
+    return this.editor.getText();
+  }
+
+  /** Sets the text of this bubble. Calls change listeners. */
+  setText(text: string) {
+    this.editor.setText(text);
+  }
+
+  /** Sets whether or not the text in the bubble is editable. */
+  setEditable(editable: boolean) {
+    this.editable = editable;
+    this.editor.setEditable(editable);
+  }
+
+  /** Returns whether or not the text in the bubble is editable. */
+  isEditable(): boolean {
+    return this.editable;
+  }
+
+  /** Adds a change listener to be notified when this bubble's text changes. */
+  addTextChangeListener(listener: () => void) {
+    this.editor.addTextChangeListener(listener);
+  }
+
+  /** Adds a change listener to be notified when this bubble's size changes. */
+  addSizeChangeListener(listener: () => void) {
+    this.sizeChangeListeners.push(listener);
+  }
+
+  /** Adds a change listener to be notified when this bubble's location changes. */
+  addLocationChangeListener(listener: () => void) {
+    this.locationChangeListeners.push(listener);
+  }
+
+  /** Creates the resize handler elements and binds events to them. */
+  private createResizeHandle(
+    container: SVGGElement,
+    workspace: WorkspaceSvg,
+  ): SVGGElement {
+    const resizeHandle = dom.createSvgElement(
+      Svg.IMAGE,
+      {
+        'class': 'blocklyResizeHandle',
+        'href': `${workspace.options.pathToMedia}resize-handle.svg`,
+      },
+      container,
+    );
+
+    browserEvents.conditionalBind(
+      resizeHandle,
+      'pointerdown',
+      this,
+      this.onResizePointerDown,
+    );
+
+    return resizeHandle;
+  }
+
+  /**
+   * Sets the size of this bubble, including the border.
+   *
+   * @param size Sets the size of this bubble, including the border.
+   * @param relayout If true, reposition the bubble from scratch so that it is
+   *     optimally visible. If false, reposition it so it maintains the same
+   *     position relative to the anchor.
+   */
+  setSize(size: Size, relayout = false) {
+    size.width = Math.max(size.width, this.MIN_SIZE.width);
+    size.height = Math.max(size.height, this.MIN_SIZE.height);
+
+    const widthMinusBorder = size.width - Bubble.DOUBLE_BORDER;
+    const heightMinusBorder = size.height - Bubble.DOUBLE_BORDER;
+    this.editor.updateSize(
+      new Size(widthMinusBorder, heightMinusBorder),
+      new Size(0, 0),
+    );
+    this.editor.getDom().setAttribute('x', `${Bubble.DOUBLE_BORDER / 2}`);
+    this.editor.getDom().setAttribute('y', `${Bubble.DOUBLE_BORDER / 2}`);
+
+    this.resizeGroup.setAttribute('y', `${heightMinusBorder}`);
+    if (this.workspace.RTL) {
+      this.resizeGroup.setAttribute('x', `${-Bubble.DOUBLE_BORDER}`);
+    } else {
+      this.resizeGroup.setAttribute('x', `${widthMinusBorder}`);
+    }
+
+    super.setSize(size, relayout);
+    this.onSizeChange();
+  }
+
+  /** @returns the size of this bubble. */
+  getSize(): Size {
+    // Overridden to be public.
+    return super.getSize();
+  }
+
+  override moveDuringDrag(newLoc: Coordinate) {
+    super.moveDuringDrag(newLoc);
+    this.onLocationChange();
+  }
+
+  override setPositionRelativeToAnchor(left: number, top: number) {
+    super.setPositionRelativeToAnchor(left, top);
+    this.onLocationChange();
+  }
+
+  protected override positionByRect(rect = new Rect(0, 0, 0, 0)) {
+    super.positionByRect(rect);
+    this.onLocationChange();
+  }
+
+  /** Handles mouse down events on the resize target. */
+  private onResizePointerDown(e: PointerEvent) {
+    this.bringToFront();
+    if (browserEvents.isRightButton(e)) {
+      e.stopPropagation();
+      return;
+    }
+
+    drag.start(
+      this.workspace,
+      e,
+      new Coordinate(
+        this.workspace.RTL ? -this.getSize().width : this.getSize().width,
+        this.getSize().height,
+      ),
+    );
+
+    this.resizePointerUpListener = browserEvents.conditionalBind(
+      document,
+      'pointerup',
+      this,
+      this.onResizePointerUp,
+    );
+    this.resizePointerMoveListener = browserEvents.conditionalBind(
+      document,
+      'pointermove',
+      this,
+      this.onResizePointerMove,
+    );
+    this.workspace.hideChaff();
+    // This event has been handled.  No need to bubble up to the document.
+    e.stopPropagation();
+  }
+
+  /** Handles pointer up events on the resize target. */
+  private onResizePointerUp(_e: PointerEvent) {
+    touch.clearTouchIdentifier();
+    if (this.resizePointerUpListener) {
+      browserEvents.unbind(this.resizePointerUpListener);
+      this.resizePointerUpListener = null;
+    }
+    if (this.resizePointerMoveListener) {
+      browserEvents.unbind(this.resizePointerMoveListener);
+      this.resizePointerMoveListener = null;
+    }
+  }
+
+  /** Handles pointer move events on the resize target. */
+  private onResizePointerMove(e: PointerEvent) {
+    const delta = drag.move(this.workspace, e);
+    this.setSize(
+      new Size(this.workspace.RTL ? -delta.x : delta.x, delta.y),
+      false,
+    );
+    this.onSizeChange();
+  }
+
+  /** Handles a size change event for the text area. Calls event listeners. */
+  private onSizeChange() {
+    for (const listener of this.sizeChangeListeners) {
+      listener();
+    }
+  }
+
+  /** Handles a location change event for the text area. Calls event listeners. */
+  private onLocationChange() {
+    for (const listener of this.locationChangeListeners) {
+      listener();
+    }
+  }
+
+  /**
+   * Returns the text editor component of this bubble.
+   *
+   * @internal
+   */
+  getEditor() {
+    return this.editor;
+  }
+}
+
+Css.register(`
+.blocklyTextInputBubble .blocklyTextarea {
+  background-color: var(--commentFillColour);
+  border: 0;
+  box-sizing: border-box;
+  display: block;
+  outline: 0;
+  padding: 5px;
+  resize: none;
+  width: 100%;
+  height: 100%;
+}
+`);

package/core/bubbles.ts

@@ -0,0 +1,12 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {Bubble} from './bubbles/bubble.js';
+import {MiniWorkspaceBubble} from './bubbles/mini_workspace_bubble.js';
+import {TextBubble} from './bubbles/text_bubble.js';
+import {TextInputBubble} from './bubbles/textinput_bubble.js';
+
+export {Bubble, MiniWorkspaceBubble, TextBubble, TextInputBubble};