blockly 12.3.1 → 12.4.0

package/core/comments.ts

@@ -0,0 +1,13 @@
+/**
+ * @license
+ * Copyright 2024 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export {CollapseCommentBarButton} from './comments/collapse_comment_bar_button.js';
+export {CommentBarButton} from './comments/comment_bar_button.js';
+export {CommentEditor} from './comments/comment_editor.js';
+export {CommentView} from './comments/comment_view.js';
+export {DeleteCommentBarButton} from './comments/delete_comment_bar_button.js';
+export {RenderedWorkspaceComment} from './comments/rendered_workspace_comment.js';
+export {WorkspaceComment} from './comments/workspace_comment.js';

package/core/common.ts

@@ -0,0 +1,347 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+// Former goog.module ID: Blockly.common
+
+import type {Block} from './block.js';
+import {BlockDefinition, Blocks} from './blocks.js';
+import * as browserEvents from './browser_events.js';
+import type {Connection} from './connection.js';
+import {EventType} from './events/type.js';
+import * as eventUtils from './events/utils.js';
+import {getFocusManager} from './focus_manager.js';
+import {ISelectable, isSelectable} from './interfaces/i_selectable.js';
+import {ShortcutRegistry} from './shortcut_registry.js';
+import type {Workspace} from './workspace.js';
+import type {WorkspaceSvg} from './workspace_svg.js';
+
+/** Database of all workspaces. */
+const WorkspaceDB_ = Object.create(null);
+
+/**
+ * Find the workspace with the specified ID.
+ *
+ * @param id ID of workspace to find.
+ * @returns The sought after workspace or null if not found.
+ */
+export function getWorkspaceById(id: string): Workspace | null {
+  return WorkspaceDB_[id] || null;
+}
+
+/**
+ * Find all workspaces.
+ *
+ * @returns Array of workspaces.
+ */
+export function getAllWorkspaces(): Workspace[] {
+  const workspaces = [];
+  for (const workspaceId in WorkspaceDB_) {
+    workspaces.push(WorkspaceDB_[workspaceId]);
+  }
+  return workspaces;
+}
+
+/**
+ * Register a workspace in the workspace db.
+ *
+ * @param workspace
+ */
+export function registerWorkspace(workspace: Workspace) {
+  WorkspaceDB_[workspace.id] = workspace;
+}
+
+/**
+ * Unregister a workspace from the workspace db.
+ *
+ * @param workspace
+ */
+export function unregisterWorkpace(workspace: Workspace) {
+  delete WorkspaceDB_[workspace.id];
+}
+
+/**
+ * The main workspace most recently used.
+ * Set by Blockly.WorkspaceSvg.prototype.markFocused
+ */
+let mainWorkspace: Workspace;
+
+/**
+ * Returns the last used top level workspace (based on focus).  Try not to use
+ * this function, particularly if there are multiple Blockly instances on a
+ * page.
+ *
+ * @returns The main workspace.
+ */
+export function getMainWorkspace(): Workspace {
+  return mainWorkspace;
+}
+
+/**
+ * Sets last used main workspace.
+ *
+ * @param workspace The most recently used top level workspace.
+ */
+export function setMainWorkspace(workspace: Workspace) {
+  mainWorkspace = workspace;
+}
+
+/**
+ * Returns the current selection.
+ */
+export function getSelected(): ISelectable | null {
+  const focused = getFocusManager().getFocusedNode();
+  if (focused && isSelectable(focused)) return focused;
+  return null;
+}
+
+/**
+ * Sets the current selection.
+ *
+ * To clear the current selection, select another ISelectable or focus a
+ * non-selectable (like the workspace root node).
+ *
+ * @param newSelection The new selection to make.
+ * @internal
+ */
+export function setSelected(newSelection: ISelectable) {
+  getFocusManager().focusNode(newSelection);
+}
+
+/**
+ * Fires a selection change event based on the new selection.
+ *
+ * This is only expected to be called by ISelectable implementations and should
+ * always be called before updating the current selection state. It does not
+ * change focus or selection state.
+ *
+ * @param newSelection The new selection.
+ * @internal
+ */
+export function fireSelectedEvent(newSelection: ISelectable | null) {
+  const selected = getSelected();
+  const event = new (eventUtils.get(EventType.SELECTED))(
+    selected?.id ?? null,
+    newSelection?.id ?? null,
+    newSelection?.workspace.id ?? selected?.workspace.id ?? '',
+  );
+  eventUtils.fire(event);
+}
+
+/**
+ * Container element in which to render the WidgetDiv, DropDownDiv and Tooltip.
+ */
+let parentContainer: Element | null;
+
+/**
+ * Get the container element in which to render the WidgetDiv, DropDownDiv and
+ * Tooltip.
+ *
+ * @returns The parent container.
+ */
+export function getParentContainer(): Element | null {
+  return parentContainer;
+}
+
+/**
+ * Set the parent container.  This is the container element that the WidgetDiv,
+ * DropDownDiv, and Tooltip are rendered into the first time `Blockly.inject`
+ * is called.
+ * This method is a NOP if called after the first `Blockly.inject`.
+ *
+ * @param newParent The container element.
+ */
+export function setParentContainer(newParent: Element) {
+  parentContainer = newParent;
+}
+
+/**
+ * Size the SVG image to completely fill its container. Call this when the view
+ * actually changes sizes (e.g. on a window resize/device orientation change).
+ * See workspace.resizeContents to resize the workspace when the contents
+ * change (e.g. when a block is added or removed).
+ * Record the height/width of the SVG image.
+ *
+ * @param workspace Any workspace in the SVG.
+ */
+export function svgResize(workspace: WorkspaceSvg) {
+  let mainWorkspace = workspace;
+  while (mainWorkspace.options.parentWorkspace) {
+    mainWorkspace = mainWorkspace.options.parentWorkspace;
+  }
+  const svg = mainWorkspace.getParentSvg();
+  const cachedSize = mainWorkspace.getCachedParentSvgSize();
+  const div = svg.parentElement;
+  if (!(div instanceof HTMLElement)) {
+    // Workspace deleted, or something.
+    return;
+  }
+
+  const width = div.offsetWidth;
+  const height = div.offsetHeight;
+  if (cachedSize.width !== width) {
+    svg.setAttribute('width', width + 'px');
+    mainWorkspace.setCachedParentSvgSize(width, null);
+  }
+  if (cachedSize.height !== height) {
+    svg.setAttribute('height', height + 'px');
+    mainWorkspace.setCachedParentSvgSize(null, height);
+  }
+  mainWorkspace.resize();
+}
+
+/**
+ * All of the connections on blocks that are currently being dragged.
+ */
+export const draggingConnections: Connection[] = [];
+
+/**
+ * Get a map of all the block's descendants mapping their type to the number of
+ *    children with that type.
+ *
+ * @param block The block to map.
+ * @param opt_stripFollowing Optionally ignore all following
+ *    statements (blocks that are not inside a value or statement input
+ *    of the block).
+ * @returns Map of types to type counts for descendants of the bock.
+ */
+export function getBlockTypeCounts(
+  block: Block,
+  opt_stripFollowing?: boolean,
+): {[key: string]: number} {
+  const typeCountsMap = Object.create(null);
+  const descendants = block.getDescendants(true);
+  if (opt_stripFollowing) {
+    const nextBlock = block.getNextBlock();
+    if (nextBlock) {
+      const index = descendants.indexOf(nextBlock);
+      descendants.splice(index, descendants.length - index);
+    }
+  }
+  for (let i = 0, checkBlock; (checkBlock = descendants[i]); i++) {
+    if (typeCountsMap[checkBlock.type]) {
+      typeCountsMap[checkBlock.type]++;
+    } else {
+      typeCountsMap[checkBlock.type] = 1;
+    }
+  }
+  return typeCountsMap;
+}
+
+/**
+ * Helper function for defining a block from JSON.  The resulting function has
+ * the correct value of jsonDef at the point in code where jsonInit is called.
+ *
+ * @param jsonDef The JSON definition of a block.
+ * @returns A function that calls jsonInit with the correct value
+ *     of jsonDef.
+ */
+function jsonInitFactory(jsonDef: AnyDuringMigration): () => void {
+  return function (this: Block) {
+    this.jsonInit(jsonDef);
+  };
+}
+
+/**
+ * Define blocks from an array of JSON block definitions, as might be generated
+ * by the Blockly Developer Tools.
+ *
+ * @param jsonArray An array of JSON block definitions.
+ */
+export function defineBlocksWithJsonArray(jsonArray: AnyDuringMigration[]) {
+  TEST_ONLY.defineBlocksWithJsonArrayInternal(jsonArray);
+}
+
+/**
+ * Private version of defineBlocksWithJsonArray for stubbing in tests.
+ */
+function defineBlocksWithJsonArrayInternal(jsonArray: AnyDuringMigration[]) {
+  defineBlocks(createBlockDefinitionsFromJsonArray(jsonArray));
+}
+
+/**
+ * Define blocks from an array of JSON block definitions, as might be generated
+ * by the Blockly Developer Tools.
+ *
+ * @param jsonArray An array of JSON block definitions.
+ * @returns A map of the block
+ *     definitions created.
+ */
+export function createBlockDefinitionsFromJsonArray(
+  jsonArray: AnyDuringMigration[],
+): {[key: string]: BlockDefinition} {
+  const blocks: {[key: string]: BlockDefinition} = {};
+  for (let i = 0; i < jsonArray.length; i++) {
+    const elem = jsonArray[i];
+    if (!elem) {
+      console.warn(`Block definition #${i} in JSON array is ${elem}. Skipping`);
+      continue;
+    }
+    const type = elem['type'];
+    if (!type) {
+      console.warn(
+        `Block definition #${i} in JSON array is missing a type attribute. ` +
+          'Skipping.',
+      );
+      continue;
+    }
+    blocks[type] = {init: jsonInitFactory(elem)};
+  }
+  return blocks;
+}
+
+/**
+ * Add the specified block definitions to the block definitions
+ * dictionary (Blockly.Blocks).
+ *
+ * @param blocks A map of block
+ *     type names to block definitions.
+ */
+export function defineBlocks(blocks: {[key: string]: BlockDefinition}) {
+  // Iterate over own enumerable properties.
+  for (const type of Object.keys(blocks)) {
+    const definition = blocks[type];
+    if (type in Blocks) {
+      console.warn(
+        `Block definition "${type}" overwrites previous definition.`,
+      );
+    }
+    Blocks[type] = definition;
+  }
+}
+
+/**
+ * Handle a key-down on SVG drawing surface. Does nothing if the main workspace
+ * is not visible.
+ *
+ * @internal
+ * @param e Key down event.
+ */
+export function globalShortcutHandler(e: KeyboardEvent) {
+  // This would ideally just be a `focusedTree instanceof WorkspaceSvg`, but
+  // importing `WorkspaceSvg` (as opposed to just its type) causes cycles.
+  let workspace: WorkspaceSvg = getMainWorkspace() as WorkspaceSvg;
+  const focusedTree = getFocusManager().getFocusedTree();
+  for (const ws of getAllWorkspaces()) {
+    if (focusedTree === (ws as WorkspaceSvg)) {
+      workspace = ws as WorkspaceSvg;
+      break;
+    }
+  }
+
+  if (
+    browserEvents.isTargetInput(e) ||
+    !workspace ||
+    (workspace.rendered && !workspace.isFlyout && !workspace.isVisible())
+  ) {
+    // When focused on an HTML text input widget, don't trap any keys.
+    // Ignore keypresses on rendered workspaces that have been explicitly
+    // hidden.
+    return;
+  }
+  ShortcutRegistry.registry.onKeyDown(workspace, e);
+}
+
+export const TEST_ONLY = {defineBlocksWithJsonArrayInternal};

package/core/component_manager.ts

@@ -0,0 +1,247 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Manager for all items registered with the workspace.
+ *
+ * @class
+ */
+// Former goog.module ID: Blockly.ComponentManager
+
+import type {IAutoHideable} from './interfaces/i_autohideable.js';
+import type {IComponent} from './interfaces/i_component.js';
+import type {IDeleteArea} from './interfaces/i_delete_area.js';
+import type {IDragTarget} from './interfaces/i_drag_target.js';
+import type {IPositionable} from './interfaces/i_positionable.js';
+import * as arrayUtils from './utils/array.js';
+
+class Capability<_T> {
+  static POSITIONABLE = new Capability<IPositionable>('positionable');
+  static DRAG_TARGET = new Capability<IDragTarget>('drag_target');
+  static DELETE_AREA = new Capability<IDeleteArea>('delete_area');
+  static AUTOHIDEABLE = new Capability<IAutoHideable>('autohideable');
+  private readonly name: string;
+  /** @param name The name of the component capability. */
+  constructor(name: string) {
+    this.name = name;
+  }
+
+  /**
+   * Returns the name of the capability.
+   *
+   * @returns The name.
+   */
+  toString(): string {
+    return this.name;
+  }
+}
+
+/**
+ * Manager for all items registered with the workspace.
+ */
+export class ComponentManager {
+  static Capability = Capability;
+
+  /**
+   * A map of the components registered with the workspace, mapped to id.
+   */
+  private readonly componentData = new Map<string, ComponentDatum>();
+
+  /** A map of capabilities to component IDs. */
+  private readonly capabilityToComponentIds = new Map<string, string[]>();
+
+  /**
+   * Adds a component.
+   *
+   * @param componentInfo The data for the component to register.
+   * @param opt_allowOverrides True to prevent an error when overriding an
+   *     already registered item.
+   */
+  addComponent(componentInfo: ComponentDatum, opt_allowOverrides?: boolean) {
+    // Don't throw an error if opt_allowOverrides is true.
+    const id = componentInfo.component.id;
+    if (!opt_allowOverrides && this.componentData.has(id)) {
+      throw Error(
+        'Plugin "' +
+          id +
+          '" with capabilities "' +
+          this.componentData.get(id)?.capabilities +
+          '" already added.',
+      );
+    }
+    this.componentData.set(id, componentInfo);
+    const stringCapabilities = [];
+    for (let i = 0; i < componentInfo.capabilities.length; i++) {
+      const capability = String(componentInfo.capabilities[i]).toLowerCase();
+      stringCapabilities.push(capability);
+      if (!this.capabilityToComponentIds.has(capability)) {
+        this.capabilityToComponentIds.set(capability, [id]);
+      } else {
+        this.capabilityToComponentIds.get(capability)?.push(id);
+      }
+    }
+    this.componentData.get(id)!.capabilities = stringCapabilities;
+  }
+
+  /**
+   * Removes a component.
+   *
+   * @param id The ID of the component to remove.
+   */
+  removeComponent(id: string) {
+    const componentInfo = this.componentData.get(id);
+    if (!componentInfo) {
+      return;
+    }
+    for (let i = 0; i < componentInfo.capabilities.length; i++) {
+      const capability = String(componentInfo.capabilities[i]).toLowerCase();
+      arrayUtils.removeElem(this.capabilityToComponentIds.get(capability)!, id);
+    }
+    this.componentData.delete(id);
+  }
+
+  /**
+   * Adds a capability to a existing registered component.
+   *
+   * @param id The ID of the component to add the capability to.
+   * @param capability The capability to add.
+   */
+  addCapability<T>(id: string, capability: string | Capability<T>) {
+    if (!this.getComponent(id)) {
+      throw Error(
+        'Cannot add capability, "' +
+          capability +
+          '". Plugin "' +
+          id +
+          '" has not been added to the ComponentManager',
+      );
+    }
+    if (this.hasCapability(id, capability)) {
+      console.warn(
+        'Plugin "' + id + 'already has capability "' + capability + '"',
+      );
+      return;
+    }
+    capability = `${capability}`.toLowerCase();
+    this.componentData.get(id)?.capabilities.push(capability);
+    this.capabilityToComponentIds.get(capability)?.push(id);
+  }
+
+  /**
+   * Removes a capability from an existing registered component.
+   *
+   * @param id The ID of the component to remove the capability from.
+   * @param capability The capability to remove.
+   */
+  removeCapability<T>(id: string, capability: string | Capability<T>) {
+    if (!this.getComponent(id)) {
+      throw Error(
+        'Cannot remove capability, "' +
+          capability +
+          '". Plugin "' +
+          id +
+          '" has not been added to the ComponentManager',
+      );
+    }
+    if (!this.hasCapability(id, capability)) {
+      console.warn(
+        'Plugin "' +
+          id +
+          'doesn\'t have capability "' +
+          capability +
+          '" to remove',
+      );
+      return;
+    }
+    capability = `${capability}`.toLowerCase();
+    arrayUtils.removeElem(this.componentData.get(id)!.capabilities, capability);
+    arrayUtils.removeElem(this.capabilityToComponentIds.get(capability)!, id);
+  }
+
+  /**
+   * Returns whether the component with this id has the specified capability.
+   *
+   * @param id The ID of the component to check.
+   * @param capability The capability to check for.
+   * @returns Whether the component has the capability.
+   */
+  hasCapability<T>(id: string, capability: string | Capability<T>): boolean {
+    capability = `${capability}`.toLowerCase();
+    return (
+      this.componentData.has(id) &&
+      this.componentData.get(id)!.capabilities.includes(capability)
+    );
+  }
+
+  /**
+   * Gets the component with the given ID.
+   *
+   * @param id The ID of the component to get.
+   * @returns The component with the given name or undefined if not found.
+   */
+  getComponent(id: string): IComponent | undefined {
+    return this.componentData.get(id)?.component;
+  }
+
+  /**
+   * Gets all the components with the specified capability.
+   *
+   * @param capability The capability of the component.
+   * @param sorted Whether to return list ordered by weights.
+   * @returns The components that match the specified capability.
+   */
+  getComponents<T extends IComponent>(
+    capability: string | Capability<T>,
+    sorted: boolean,
+  ): T[] {
+    capability = `${capability}`.toLowerCase();
+    const componentIds = this.capabilityToComponentIds.get(capability);
+    if (!componentIds) {
+      return [];
+    }
+    const components: T[] = [];
+    if (sorted) {
+      const componentDataList: ComponentDatum[] = [];
+      componentIds.forEach((id) => {
+        componentDataList.push(this.componentData.get(id)!);
+      });
+      componentDataList.sort(function (a, b) {
+        return a.weight - b.weight;
+      });
+      componentDataList.forEach(function (componentDatum) {
+        components.push(componentDatum.component as T);
+      });
+    } else {
+      componentIds.forEach((id) => {
+        components.push(this.componentData.get(id)!.component as T);
+      });
+    }
+    return components;
+  }
+}
+
+export namespace ComponentManager {
+  export enum ComponentWeight {
+    // The toolbox weight is lower (higher precedence) than the flyout, so that
+    // if both are under the pointer, the toolbox takes precedence even though
+    // the flyout's drag target area is large enough to include the toolbox.
+    TOOLBOX_WEIGHT = 0,
+    FLYOUT_WEIGHT = 1,
+    TRASHCAN_WEIGHT = 2,
+    ZOOM_CONTROLS_WEIGHT = 3,
+  }
+
+  /** An object storing component information. */
+  export interface ComponentDatum {
+    component: IComponent;
+    capabilities: Array<string | Capability<IComponent>>;
+    weight: number;
+  }
+}
+
+export type ComponentWeight = ComponentManager.ComponentWeight;
+export const ComponentWeight = ComponentManager.ComponentWeight;
+export type ComponentDatum = ComponentManager.ComponentDatum;

package/core/config.ts

@@ -0,0 +1,65 @@
+/**
+ * @license
+ * Copyright 2022 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+// Former goog.module ID: Blockly.config
+
+/**
+ * All the values that we expect developers to be able to change
+ * before injecting Blockly.
+ */
+interface Config {
+  dragRadius: number;
+  flyoutDragRadius: number;
+  snapRadius: number;
+  currentConnectionPreference: number;
+  bumpDelay: number;
+  connectingSnapRadius: number;
+}
+
+/** Default snap radius. */
+const DEFAULT_SNAP_RADIUS = 28;
+
+/**
+ * Object holding all the values on Blockly that we expect developers to be
+ * able to change.
+ */
+export const config: Config = {
+  /**
+   * Number of pixels the mouse must move before a drag starts.
+   *
+   */
+  dragRadius: 5,
+  /**
+   * Number of pixels the mouse must move before a drag/scroll starts from the
+   * flyout.  Because the drag-intention is determined when this is reached, it
+   * is larger than dragRadius so that the drag-direction is clearer.
+   *
+   */
+  flyoutDragRadius: 10,
+  /**
+   * Maximum misalignment between connections for them to snap together.
+   *
+   */
+  snapRadius: DEFAULT_SNAP_RADIUS,
+  /**
+   * Maximum misalignment between connections for them to snap together.
+   * This should be the same as the snap radius.
+   */
+  connectingSnapRadius: DEFAULT_SNAP_RADIUS,
+  /**
+   * How much to prefer staying connected to the current connection over moving
+   * to a new connection.  The current previewed connection is considered to be
+   * this much closer to the matching connection on the block than it actually
+   * is.
+   *
+   */
+  currentConnectionPreference: 8,
+  /**
+   * Delay in ms between trigger and bumping unconnected block out of alignment.
+   *
+   */
+  bumpDelay: 250,
+};