blockly 12.3.1 → 12.4.0

package/core/icons/warning_icon.ts

@@ -0,0 +1,226 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+// Former goog.module ID: Blockly.Warning
+
+import type {BlockSvg} from '../block_svg.js';
+import {TextBubble} from '../bubbles/text_bubble.js';
+import {EventType} from '../events/type.js';
+import * as eventUtils from '../events/utils.js';
+import type {IBubble} from '../interfaces/i_bubble.js';
+import type {IHasBubble} from '../interfaces/i_has_bubble.js';
+import * as renderManagement from '../render_management.js';
+import {Size} from '../utils.js';
+import {Coordinate} from '../utils/coordinate.js';
+import * as dom from '../utils/dom.js';
+import {Rect} from '../utils/rect.js';
+import {Svg} from '../utils/svg.js';
+import {Icon} from './icon.js';
+import {IconType} from './icon_types.js';
+
+/** The size of the warning icon in workspace-scale units. */
+const SIZE = 17;
+
+/**
+ * An icon that warns the user that something is wrong with their block.
+ *
+ * For example, this could be used to warn them about incorrect field values,
+ * or incorrect placement of the block (putting it somewhere it doesn't belong).
+ */
+export class WarningIcon extends Icon implements IHasBubble {
+  /** The type string used to identify this icon. */
+  static readonly TYPE = IconType.WARNING;
+
+  /**
+   * 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 = 2;
+
+  /** A map of warning IDs to warning text. */
+  private textMap: Map<string, string> = new Map();
+
+  /** The bubble used to display the warnings to the user. */
+  private textBubble: TextBubble | null = null;
+
+  /** @internal */
+  constructor(protected readonly sourceBlock: BlockSvg) {
+    super(sourceBlock);
+  }
+
+  override getType(): IconType<WarningIcon> {
+    return WarningIcon.TYPE;
+  }
+
+  override initView(pointerdownListener: (e: PointerEvent) => void): void {
+    if (this.svgRoot) return; // Already initialized.
+
+    super.initView(pointerdownListener);
+
+    // Triangle with rounded corners.
+    dom.createSvgElement(
+      Svg.PATH,
+      {
+        'class': 'blocklyIconShape',
+        'd': 'M2,15Q-1,15 0.5,12L6.5,1.7Q8,-1 9.5,1.7L15.5,12Q17,15 14,15z',
+      },
+      this.svgRoot,
+    );
+    // Can't use a real '!' text character since different browsers and
+    // operating systems render it differently. Body of exclamation point.
+    dom.createSvgElement(
+      Svg.PATH,
+      {
+        'class': 'blocklyIconSymbol',
+        'd': 'm7,4.8v3.16l0.27,2.27h1.46l0.27,-2.27v-3.16z',
+      },
+      this.svgRoot,
+    );
+    // Dot of exclamation point.
+    dom.createSvgElement(
+      Svg.RECT,
+      {
+        'class': 'blocklyIconSymbol',
+        'x': '7',
+        'y': '11',
+        'height': '2',
+        'width': '2',
+      },
+      this.svgRoot,
+    );
+    dom.addClass(this.svgRoot!, 'blocklyWarningIcon');
+  }
+
+  override dispose() {
+    super.dispose();
+    this.textBubble?.dispose();
+  }
+
+  override getWeight(): number {
+    return WarningIcon.WEIGHT;
+  }
+
+  override getSize(): Size {
+    return new Size(SIZE, SIZE);
+  }
+
+  override applyColour(): void {
+    super.applyColour();
+    this.textBubble?.setColour(this.sourceBlock.getColour());
+  }
+
+  override updateCollapsed(): void {
+    // We are shown when collapsed, so do nothing! I.e. skip the default
+    // behavior of hiding.
+  }
+
+  /** Tells blockly that this icon is shown when the block is collapsed. */
+  override isShownWhenCollapsed(): boolean {
+    return true;
+  }
+
+  /** Updates the location of the icon's bubble if it is open. */
+  override onLocationChange(blockOrigin: Coordinate): void {
+    super.onLocationChange(blockOrigin);
+    this.textBubble?.setAnchorLocation(this.getAnchorLocation());
+  }
+
+  /**
+   * Adds a warning message to this warning icon.
+   *
+   * @param text The text of the message to add.
+   * @param id The id of the message to add.
+   * @internal
+   */
+  addMessage(text: string, id: string): this {
+    if (this.textMap.get(id) === text) return this;
+
+    if (text) {
+      this.textMap.set(id, text);
+    } else {
+      this.textMap.delete(id);
+    }
+
+    this.textBubble?.setText(this.getText());
+    return this;
+  }
+
+  /**
+   * @returns the display text for this icon. Includes all warning messages
+   *     concatenated together with newlines.
+   * @internal
+   */
+  getText(): string {
+    return [...this.textMap.values()].join('\n');
+  }
+
+  /** Toggles the visibility of the bubble. */
+  override onClick(): void {
+    super.onClick();
+    this.setBubbleVisible(!this.bubbleIsVisible());
+  }
+
+  override isClickableInFlyout(): boolean {
+    return false;
+  }
+
+  bubbleIsVisible(): boolean {
+    return !!this.textBubble;
+  }
+
+  async setBubbleVisible(visible: boolean): Promise<void> {
+    if (this.bubbleIsVisible() === visible) return;
+
+    await renderManagement.finishQueuedRenders();
+
+    if (visible) {
+      this.textBubble = new TextBubble(
+        this.getText(),
+        this.sourceBlock.workspace,
+        this.getAnchorLocation(),
+        this.getBubbleOwnerRect(),
+      );
+      this.applyColour();
+    } else {
+      this.textBubble?.dispose();
+      this.textBubble = null;
+    }
+
+    eventUtils.fire(
+      new (eventUtils.get(EventType.BUBBLE_OPEN))(
+        this.sourceBlock,
+        visible,
+        'warning',
+      ),
+    );
+  }
+
+  /** See IHasBubble.getBubble. */
+  getBubble(): IBubble | null {
+    return this.textBubble;
+  }
+
+  /**
+   * @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 {
+    const bbox = this.sourceBlock.getSvgRoot().getBBox();
+    return new Rect(bbox.y, bbox.y + bbox.height, bbox.x, bbox.x + bbox.width);
+  }
+}

package/core/icons.ts

@@ -0,0 +1,24 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {CommentIcon, CommentState} from './icons/comment_icon.js';
+import * as exceptions from './icons/exceptions.js';
+import {Icon} from './icons/icon.js';
+import {IconType} from './icons/icon_types.js';
+import {MutatorIcon} from './icons/mutator_icon.js';
+import * as registry from './icons/registry.js';
+import {WarningIcon} from './icons/warning_icon.js';
+
+export {
+  CommentIcon,
+  CommentState,
+  exceptions,
+  Icon,
+  IconType,
+  MutatorIcon,
+  registry,
+  WarningIcon,
+};

package/core/inject.ts

@@ -0,0 +1,332 @@
+/**
+ * @license
+ * Copyright 2011 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+// Former goog.module ID: Blockly.inject
+
+import type {BlocklyOptions} from './blockly_options.js';
+import * as browserEvents from './browser_events.js';
+import * as bumpObjects from './bump_objects.js';
+import * as common from './common.js';
+import * as Css from './css.js';
+import * as dropDownDiv from './dropdowndiv.js';
+import {Grid} from './grid.js';
+import {Options} from './options.js';
+import {ScrollbarPair} from './scrollbar_pair.js';
+import * as Tooltip from './tooltip.js';
+import * as Touch from './touch.js';
+import * as dom from './utils/dom.js';
+import {Svg} from './utils/svg.js';
+import * as WidgetDiv from './widgetdiv.js';
+import {WorkspaceSvg} from './workspace_svg.js';
+
+/**
+ * Inject a Blockly editor into the specified container element (usually a div).
+ *
+ * @param container Containing element, or its ID, or a CSS selector.
+ * @param opt_options Optional dictionary of options.
+ * @returns Newly created main workspace.
+ */
+export function inject(
+  container: Element | string,
+  opt_options?: BlocklyOptions,
+): WorkspaceSvg {
+  let containerElement: Element | null = null;
+  if (typeof container === 'string') {
+    containerElement =
+      document.getElementById(container) || document.querySelector(container);
+  } else {
+    containerElement = container;
+  }
+  // Verify that the container is in document.
+  if (
+    !document.contains(containerElement) &&
+    document !== containerElement?.ownerDocument
+  ) {
+    throw Error('Error: container is not in current document');
+  }
+  const options = new Options(opt_options || ({} as BlocklyOptions));
+  const subContainer = document.createElement('div');
+  dom.addClass(subContainer, 'injectionDiv');
+  if (opt_options?.rtl) {
+    dom.addClass(subContainer, 'blocklyRTL');
+  }
+
+  containerElement!.appendChild(subContainer);
+  const svg = createDom(subContainer, options);
+
+  const workspace = createMainWorkspace(subContainer, svg, options);
+
+  init(workspace);
+
+  // Keep focus on the first workspace so entering keyboard navigation looks
+  // correct.
+  common.setMainWorkspace(workspace);
+
+  common.svgResize(workspace);
+
+  subContainer.addEventListener('focusin', function () {
+    common.setMainWorkspace(workspace);
+  });
+
+  browserEvents.conditionalBind(
+    subContainer,
+    'keydown',
+    null,
+    common.globalShortcutHandler,
+  );
+
+  return workspace;
+}
+
+/**
+ * Create the SVG image.
+ *
+ * @param container Containing element.
+ * @param options Dictionary of options.
+ * @returns Newly created SVG image.
+ */
+function createDom(container: HTMLElement, options: Options): SVGElement {
+  // Sadly browsers (Chrome vs Firefox) are currently inconsistent in laying
+  // out content in RTL mode.  Therefore Blockly forces the use of LTR,
+  // then manually positions content in RTL as needed.
+  container.setAttribute('dir', 'LTR');
+
+  // Load CSS.
+  Css.inject(options.hasCss, options.pathToMedia);
+
+  // Build the SVG DOM.
+  /*
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      xmlns:html="http://www.w3.org/1999/xhtml"
+      xmlns:xlink="http://www.w3.org/1999/xlink"
+      version="1.1"
+      class="blocklySvg">
+      ...
+    </svg>
+    */
+  const svg = dom.createSvgElement(
+    Svg.SVG,
+    {
+      'xmlns': dom.SVG_NS,
+      'xmlns:html': dom.HTML_NS,
+      'xmlns:xlink': dom.XLINK_NS,
+      'version': '1.1',
+      'class': 'blocklySvg',
+    },
+    container,
+  );
+  /*
+    <defs>
+      ... filters go here ...
+    </defs>
+    */
+  const defs = dom.createSvgElement(Svg.DEFS, {}, svg);
+  // Each filter/pattern needs a unique ID for the case of multiple Blockly
+  // instances on a page.  Browser behaviour becomes undefined otherwise.
+  // https://neil.fraser.name/news/2015/11/01/
+  const rnd = String(Math.random()).substring(2);
+
+  options.gridPattern = Grid.createDom(
+    rnd,
+    options.gridOptions,
+    defs,
+    container,
+  );
+  return svg;
+}
+
+/**
+ * Create a main workspace and add it to the SVG.
+ *
+ * @param svg SVG element with pattern defined.
+ * @param options Dictionary of options.
+ * @returns Newly created main workspace.
+ */
+function createMainWorkspace(
+  injectionDiv: HTMLElement,
+  svg: SVGElement,
+  options: Options,
+): WorkspaceSvg {
+  options.parentWorkspace = null;
+  const mainWorkspace = new WorkspaceSvg(options);
+  const wsOptions = mainWorkspace.options;
+  mainWorkspace.scale = wsOptions.zoomOptions.startScale;
+  svg.appendChild(
+    mainWorkspace.createDom('blocklyMainBackground', injectionDiv),
+  );
+
+  // Set the theme name and renderer name onto the injection div.
+  const rendererClassName = mainWorkspace.getRenderer().getClassName();
+  if (rendererClassName) {
+    dom.addClass(injectionDiv, rendererClassName);
+  }
+  const themeClassName = mainWorkspace.getTheme().getClassName();
+  if (themeClassName) {
+    dom.addClass(injectionDiv, themeClassName);
+  }
+
+  if (!wsOptions.hasCategories && wsOptions.languageTree) {
+    // Add flyout as an <svg> that is a sibling of the workspace SVG.
+    const flyout = mainWorkspace.addFlyout(Svg.SVG);
+    dom.insertAfter(flyout, svg);
+  }
+  if (wsOptions.hasTrashcan) {
+    mainWorkspace.addTrashcan();
+  }
+  if (wsOptions.zoomOptions && wsOptions.zoomOptions.controls) {
+    mainWorkspace.addZoomControls();
+  }
+  // Register the workspace svg as a UI component.
+  mainWorkspace
+    .getThemeManager()
+    .subscribe(svg, 'workspaceBackgroundColour', 'background-color');
+
+  // A null translation will also apply the correct initial scale.
+  mainWorkspace.translate(0, 0);
+
+  mainWorkspace.addChangeListener(
+    bumpObjects.bumpIntoBoundsHandler(mainWorkspace),
+  );
+
+  // The SVG is now fully assembled.
+  common.svgResize(mainWorkspace);
+  WidgetDiv.createDom();
+  dropDownDiv.createDom();
+  Tooltip.createDom();
+  return mainWorkspace;
+}
+
+/**
+ * Initialize Blockly with various handlers.
+ *
+ * @param mainWorkspace Newly created main workspace.
+ */
+function init(mainWorkspace: WorkspaceSvg) {
+  const options = mainWorkspace.options;
+  const svg = mainWorkspace.getParentSvg();
+
+  // Suppress the browser's context menu.
+  browserEvents.conditionalBind(
+    svg.parentNode as Element,
+    'contextmenu',
+    null,
+    function (e: Event) {
+      if (!browserEvents.isTargetInput(e)) {
+        e.preventDefault();
+      }
+    },
+  );
+
+  const workspaceResizeHandler = browserEvents.conditionalBind(
+    window,
+    'resize',
+    null,
+    function () {
+      // Don't hide all the chaff. Leave the dropdown and widget divs open if
+      // possible.
+      Tooltip.hide();
+      mainWorkspace.hideComponents(true);
+      dropDownDiv.repositionForWindowResize();
+      WidgetDiv.repositionForWindowResize();
+      common.svgResize(mainWorkspace);
+      bumpObjects.bumpTopObjectsIntoBounds(mainWorkspace);
+    },
+  );
+  mainWorkspace.setResizeHandlerWrapper(workspaceResizeHandler);
+
+  bindDocumentEvents();
+
+  if (options.languageTree) {
+    const toolbox = mainWorkspace.getToolbox();
+    const flyout = mainWorkspace.getFlyout(true);
+    if (toolbox) {
+      toolbox.init();
+    } else if (flyout) {
+      // Build a fixed flyout with the root blocks.
+      flyout.init(mainWorkspace);
+      flyout.show(options.languageTree);
+      if (typeof flyout.scrollToStart === 'function') {
+        flyout.scrollToStart();
+      }
+    }
+  }
+
+  if (options.hasTrashcan) {
+    mainWorkspace.trashcan!.init();
+  }
+  if (options.zoomOptions && options.zoomOptions.controls) {
+    mainWorkspace.zoomControls_!.init();
+  }
+
+  if (options.moveOptions && options.moveOptions.scrollbars) {
+    const horizontalScroll =
+      options.moveOptions.scrollbars === true ||
+      !!options.moveOptions.scrollbars.horizontal;
+    const verticalScroll =
+      options.moveOptions.scrollbars === true ||
+      !!options.moveOptions.scrollbars.vertical;
+    mainWorkspace.scrollbar = new ScrollbarPair(
+      mainWorkspace,
+      horizontalScroll,
+      verticalScroll,
+      'blocklyMainWorkspaceScrollbar',
+    );
+    mainWorkspace.scrollbar.resize();
+  } else {
+    mainWorkspace.setMetrics({x: 0.5, y: 0.5});
+  }
+
+  // Load the sounds.
+  if (options.hasSounds) {
+    loadSounds(options.pathToMedia, mainWorkspace);
+  }
+}
+
+/**
+ * Whether event handlers have been bound. Document event handlers will only
+ * be bound once, even if Blockly is destroyed and reinjected.
+ */
+let documentEventsBound = false;
+
+/**
+ * Bind document events, but only once.  Destroying and reinjecting Blockly
+ * should not bind again.
+ * Bind events for scrolling the workspace.
+ * Most of these events should be bound to the SVG's surface.
+ * However, 'mouseup' has to be on the whole document so that a block dragged
+ * out of bounds and released will know that it has been released.
+ */
+function bindDocumentEvents() {
+  if (!documentEventsBound) {
+    browserEvents.conditionalBind(document, 'scroll', null, function () {
+      const workspaces = common.getAllWorkspaces();
+      for (let i = 0, workspace; (workspace = workspaces[i]); i++) {
+        if (workspace instanceof WorkspaceSvg) {
+          workspace.updateInverseScreenCTM();
+        }
+      }
+    });
+    // longStop needs to run to stop the context menu from showing up.  It
+    // should run regardless of what other touch event handlers have run.
+    browserEvents.bind(document, 'touchend', null, Touch.longStop);
+    browserEvents.bind(document, 'touchcancel', null, Touch.longStop);
+  }
+  documentEventsBound = true;
+}
+
+/**
+ * Load sounds for the given workspace.
+ *
+ * @param pathToMedia The path to the media directory.
+ * @param workspace The workspace to load sounds for.
+ */
+function loadSounds(pathToMedia: string, workspace: WorkspaceSvg) {
+  const audioMgr = workspace.getAudioManager();
+  audioMgr.load([`${pathToMedia}click.mp3`], 'click');
+  audioMgr.load([`${pathToMedia}disconnect.mp3`], 'disconnect');
+  audioMgr.load([`${pathToMedia}delete.mp3`], 'delete');
+}

package/core/inputs/align.ts

@@ -0,0 +1,14 @@
+/**
+ * @license
+ * Copyright 2012 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Enum for alignment of inputs.
+ */
+export enum Align {
+  LEFT = -1,
+  CENTRE = 0,
+  RIGHT = 1,
+}

package/core/inputs/dummy_input.ts

@@ -0,0 +1,26 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type {Block} from '../block.js';
+import {Input} from './input.js';
+import {inputTypes} from './input_types.js';
+
+/** Represents an input on a block with no connection. */
+export class DummyInput extends Input {
+  readonly type = inputTypes.DUMMY;
+
+  /**
+   * @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,
+  ) {
+    super(name, block);
+  }
+}

package/core/inputs/end_row_input.ts

@@ -0,0 +1,31 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type {Block} from '../block.js';
+import {Input} from './input.js';
+import {inputTypes} from './input_types.js';
+
+/**
+ * Represents an input on a block that is always the last input in the row. Any
+ * following input will be rendered on the next row even if the block has inline
+ * inputs. Any newline character in a JSON block definition's message will
+ * automatically be parsed as an end-row input.
+ */
+export class EndRowInput extends Input {
+  readonly type = inputTypes.END_ROW;
+
+  /**
+   * @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,
+  ) {
+    super(name, block);
+  }
+}