blockly 8.0.4 → 8.0.5-beta.0

package/core/grid.d.ts

@@ -0,0 +1,83 @@
+/**
+ * @license
+ * Copyright 2017 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { GridOptions } from './blockly_options.js';
+/**
+ * Class for a workspace's grid.
+ * @alias Blockly.Grid
+ */
+export declare class Grid {
+    private pattern;
+    /**
+     * The scale of the grid, used to set stroke width on grid lines.
+     * This should always be the same as the workspace scale.
+     */
+    private scale_;
+    private readonly spacing_;
+    private readonly length_;
+    private readonly line1_;
+    private readonly line2_;
+    private readonly snapToGrid_;
+    /**
+     * @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(pattern: SVGElement, options: GridOptions);
+    /**
+     * Whether blocks should snap to the grid, based on the initial configuration.
+     * @return True if blocks should snap, false otherwise.
+     * @internal
+     */
+    shouldSnap(): boolean;
+    /**
+     * Get the spacing of the grid points (in px).
+     * @return The spacing of the grid points.
+     * @internal
+     */
+    getSpacing(): number;
+    /**
+     * Get the ID of the pattern element, which should be randomized to avoid
+     * conflicts with other Blockly instances on the page.
+     * @return The pattern ID.
+     * @internal
+     */
+    getPatternId(): string;
+    /**
+     * Update the grid with a new scale.
+     * @param scale The new workspace scale.
+     * @internal
+     */
+    update(scale: number): void;
+    /**
+     * 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_;
+    /**
+     * 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): void;
+    /**
+     * 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.
+     * @return The SVG element for the grid pattern.
+     * @internal
+     */
+    static createDom(rnd: string, gridOptions: GridOptions, defs: SVGElement): SVGElement;
+}

package/core/grid.ts

@@ -0,0 +1,192 @@
+/**
+ * @license
+ * Copyright 2017 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * @fileoverview Object for configuring and updating a workspace grid in
+ * Blockly.
+ */
+
+/**
+ * Object for configuring and updating a workspace grid in
+ * Blockly.
+ * @class
+ */
+import * as goog from '../closure/goog/goog.js';
+goog.declareModuleId('Blockly.Grid');
+
+import * as dom from './utils/dom.js';
+import {Svg} from './utils/svg.js';
+import * as userAgent from './utils/useragent.js';
+import {GridOptions} from './blockly_options.js';
+
+
+/**
+ * Class for a workspace's grid.
+ * @alias Blockly.Grid
+ */
+export class Grid {
+  /**
+   * The scale of the grid, used to set stroke width on grid lines.
+   * This should always be the same as the workspace scale.
+   */
+  private scale_ = 1;
+  private readonly spacing_: number;
+  private readonly length_: number;
+  private readonly line1_: SVGElement;
+  private readonly line2_: SVGElement;
+  private readonly 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;
+  }
+
+  /**
+   * Whether blocks should snap to the grid, based on the initial configuration.
+   * @return True if blocks should snap, false otherwise.
+   * @internal
+   */
+  shouldSnap(): boolean {
+    return this.snapToGrid_;
+  }
+
+  /**
+   * Get the spacing of the grid points (in px).
+   * @return The spacing of the grid points.
+   * @internal
+   */
+  getSpacing(): number {
+    return this.spacing_;
+  }
+
+  /**
+   * Get the ID of the pattern element, which should be randomized to avoid
+   * conflicts with other Blockly instances on the page.
+   * @return 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;
+    // MSIE freaks if it sees a 0x0 pattern, so set empty patterns to 100x100.
+    const safeSpacing = this.spacing_ * scale || 100;
+
+    this.pattern.setAttribute('width', safeSpacing.toString());
+    this.pattern.setAttribute('height', safeSpacing.toString());
+
+    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.toString());
+      line.setAttribute('x1', x1.toString());
+      line.setAttribute('y1', y1.toString());
+      line.setAttribute('x2', x2.toString());
+      line.setAttribute('y2', y2.toString());
+    }
+  }
+
+  /**
+   * 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.toString());
+    this.pattern.setAttribute('y', y.toString());
+
+    if (userAgent.IE || userAgent.EDGE) {
+      // IE/Edge doesn't notice that the x/y offsets have changed.
+      // Force an update.
+      this.update(this.scale_);
+    }
+  }
+
+  /**
+   * 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.
+   * @return The SVG element for the grid pattern.
+   * @internal
+   */
+  static createDom(rnd: string, gridOptions: GridOptions, defs: SVGElement):
+      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);
+    }
+    return gridPattern;
+  }
+}

package/core/icon.d.ts

@@ -0,0 +1,78 @@
+/**
+ * @license
+ * Copyright 2013 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { BlockSvg } from './block_svg.js';
+import type { Bubble } from './bubble.js';
+import { Coordinate } from './utils/coordinate.js';
+import { Size } from './utils/size.js';
+/**
+ * Class for an icon.
+ * @alias Blockly.Icon
+ */
+export declare abstract class Icon {
+    protected block_: BlockSvg;
+    /** The icon SVG group. */
+    iconGroup_: SVGGElement | null;
+    /** Whether this icon gets hidden when the block is collapsed. */
+    collapseHidden: boolean;
+    /** Height and width of icons. */
+    readonly SIZE = 17;
+    /** Bubble UI (if visible). */
+    protected bubble_: Bubble | null;
+    /** Absolute coordinate of icon's center. */
+    protected iconXY_: Coordinate | null;
+    /** @param block The block associated with this icon. */
+    constructor(block: BlockSvg);
+    /** Create the icon on the block. */
+    createIcon(): void;
+    /** Dispose of this icon. */
+    dispose(): void;
+    /** Add or remove the UI indicating if this icon may be clicked or not. */
+    updateEditable(): void;
+    /**
+     * Is the associated bubble visible?
+     * @return True if the bubble is visible.
+     */
+    isVisible(): boolean;
+    /**
+     * Clicking on the icon toggles if the bubble is visible.
+     * @param e Mouse click event.
+     */
+    protected iconClick_(e: MouseEvent): void;
+    /** Change the colour of the associated bubble to match its block. */
+    applyColour(): void;
+    /**
+     * Notification that the icon has moved.  Update the arrow accordingly.
+     * @param xy Absolute location in workspace coordinates.
+     */
+    setIconLocation(xy: Coordinate): void;
+    /**
+     * Notification that the icon has moved, but we don't really know where.
+     * Recompute the icon's location from scratch.
+     */
+    computeIconLocation(): void;
+    /**
+     * Returns the center of the block's icon relative to the surface.
+     * @return Object with x and y properties in workspace coordinates.
+     */
+    getIconLocation(): Coordinate | null;
+    /**
+     * Get the size of the icon as used for rendering.
+     * This differs from the actual size of the icon, because it bulges slightly
+     * out of its row rather than increasing the height of its row.
+     * @return Height and width.
+     */
+    getCorrectedSize(): Size;
+    /**
+     * Draw the icon.
+     * @param _group The icon group.
+     */
+    protected drawIcon_(_group: Element): void;
+    /**
+     * Show or hide the icon.
+     * @param _visible True if the icon should be visible.
+     */
+    setVisible(_visible: boolean): void;
+}

package/core/icon.ts

@@ -0,0 +1,189 @@
+/**
+ * @license
+ * Copyright 2013 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * @fileoverview Object representing an icon on a block.
+ */
+
+/**
+ * Object representing an icon on a block.
+ * @class
+ */
+import * as goog from '../closure/goog/goog.js';
+goog.declareModuleId('Blockly.Icon');
+
+import type {BlockSvg} from './block_svg.js';
+import * as browserEvents from './browser_events.js';
+import type {Bubble} from './bubble.js';
+import {Coordinate} from './utils/coordinate.js';
+import * as dom from './utils/dom.js';
+import {Size} from './utils/size.js';
+import {Svg} from './utils/svg.js';
+import * as svgMath from './utils/svg_math.js';
+
+
+/**
+ * Class for an icon.
+ * @alias Blockly.Icon
+ */
+export abstract class Icon {
+  protected block_: BlockSvg;
+  /** The icon SVG group. */
+  iconGroup_: SVGGElement|null = null;
+
+  /** Whether this icon gets hidden when the block is collapsed. */
+  collapseHidden = true;
+
+  /** Height and width of icons. */
+  readonly SIZE = 17;
+
+  /** Bubble UI (if visible). */
+  protected bubble_: Bubble|null = null;
+
+  /** Absolute coordinate of icon's center. */
+  protected iconXY_: Coordinate|null = null;
+
+  /** @param block The block associated with this icon. */
+  constructor(block: BlockSvg) {
+    this.block_ = block;
+  }
+
+  /** Create the icon on the block. */
+  createIcon() {
+    if (this.iconGroup_) {
+      // Icon already exists.
+      return;
+    }
+    /* Here's the markup that will be generated:
+        <g class="blocklyIconGroup">
+          ...
+        </g>
+        */
+    this.iconGroup_ =
+        dom.createSvgElement(Svg.G, {'class': 'blocklyIconGroup'});
+    if (this.block_.isInFlyout) {
+      dom.addClass(this.iconGroup_ as Element, 'blocklyIconGroupReadonly');
+    }
+    // AnyDuringMigration because:  Argument of type 'SVGGElement | null' is not
+    // assignable to parameter of type 'Element'.
+    this.drawIcon_(this.iconGroup_ as AnyDuringMigration);
+
+    // AnyDuringMigration because:  Argument of type 'SVGGElement | null' is not
+    // assignable to parameter of type 'Node'.
+    this.block_.getSvgRoot().appendChild(this.iconGroup_ as AnyDuringMigration);
+    // AnyDuringMigration because:  Argument of type 'SVGGElement | null' is not
+    // assignable to parameter of type 'EventTarget'.
+    browserEvents.conditionalBind(
+        this.iconGroup_ as AnyDuringMigration, 'mouseup', this,
+        this.iconClick_);
+    this.updateEditable();
+  }
+
+  /** Dispose of this icon. */
+  dispose() {
+    // Dispose of and unlink the icon.
+    dom.removeNode(this.iconGroup_);
+    this.iconGroup_ = null;
+    // Dispose of and unlink the bubble.
+    this.setVisible(false);
+    // AnyDuringMigration because:  Type 'null' is not assignable to type
+    // 'BlockSvg'.
+    this.block_ = null as AnyDuringMigration;
+  }
+
+  /** Add or remove the UI indicating if this icon may be clicked or not. */
+  updateEditable() {}
+  // No-op on the base class.
+
+  /**
+   * Is the associated bubble visible?
+   * @return True if the bubble is visible.
+   */
+  isVisible(): boolean {
+    return !!this.bubble_;
+  }
+
+  /**
+   * Clicking on the icon toggles if the bubble is visible.
+   * @param e Mouse click event.
+   */
+  protected iconClick_(e: MouseEvent) {
+    if (this.block_.workspace.isDragging()) {
+      // Drag operation is concluding.  Don't open the editor.
+      return;
+    }
+    if (!this.block_.isInFlyout && !browserEvents.isRightButton(e)) {
+      this.setVisible(!this.isVisible());
+    }
+  }
+
+  /** Change the colour of the associated bubble to match its block. */
+  applyColour() {
+    if (this.isVisible()) {
+      this.bubble_!.setColour(this.block_.style.colourPrimary);
+    }
+  }
+
+  /**
+   * Notification that the icon has moved.  Update the arrow accordingly.
+   * @param xy Absolute location in workspace coordinates.
+   */
+  setIconLocation(xy: Coordinate) {
+    this.iconXY_ = xy;
+    if (this.isVisible()) {
+      this.bubble_!.setAnchorLocation(xy);
+    }
+  }
+
+  /**
+   * Notification that the icon has moved, but we don't really know where.
+   * Recompute the icon's location from scratch.
+   */
+  computeIconLocation() {
+    // Find coordinates for the centre of the icon and update the arrow.
+    const blockXY = this.block_.getRelativeToSurfaceXY();
+    const iconXY = svgMath.getRelativeXY(this.iconGroup_ as SVGElement);
+    const newXY = new Coordinate(
+        blockXY.x + iconXY.x + this.SIZE / 2,
+        blockXY.y + iconXY.y + this.SIZE / 2);
+    if (!Coordinate.equals(this.getIconLocation(), newXY)) {
+      this.setIconLocation(newXY);
+    }
+  }
+
+  /**
+   * Returns the center of the block's icon relative to the surface.
+   * @return Object with x and y properties in workspace coordinates.
+   */
+  getIconLocation(): Coordinate|null {
+    return this.iconXY_;
+  }
+
+  /**
+   * Get the size of the icon as used for rendering.
+   * This differs from the actual size of the icon, because it bulges slightly
+   * out of its row rather than increasing the height of its row.
+   * @return Height and width.
+   */
+  getCorrectedSize(): Size {
+    // TODO (#2562): Remove getCorrectedSize.
+    return new Size(this.SIZE, this.SIZE - 2);
+  }
+
+  /**
+   * Draw the icon.
+   * @param _group The icon group.
+   */
+  protected drawIcon_(_group: Element) {}
+  // No-op on base class.
+
+  /**
+   * Show or hide the icon.
+   * @param _visible True if the icon should be visible.
+   */
+  setVisible(_visible: boolean) {}
+}
+// No-op on base class

package/core/inject.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @license
+ * Copyright 2011 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { BlocklyOptions } from './blockly_options.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.
+ * @return Newly created main workspace.
+ * @alias Blockly.inject
+ */
+export declare function inject(container: Element | string, opt_options?: BlocklyOptions): WorkspaceSvg;