blockly 12.3.0 → 12.4.0

package/core/utils/dom.ts

@@ -0,0 +1,356 @@
+/**
+ * @license
+ * Copyright 2019 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+// Former goog.module ID: Blockly.utils.dom
+
+import type {Svg} from './svg.js';
+
+/**
+ * Required name space for SVG elements.
+ */
+export const SVG_NS = 'http://www.w3.org/2000/svg';
+
+/**
+ * Required name space for HTML elements.
+ */
+export const HTML_NS = 'http://www.w3.org/1999/xhtml';
+
+/**
+ * Required name space for XLINK elements.
+ */
+export const XLINK_NS = 'http://www.w3.org/1999/xlink';
+
+/**
+ * Node type constants.
+ * https://developer.mozilla.org/en-US/docs/Web/API/Node/nodeType
+ */
+export enum NodeType {
+  ELEMENT_NODE = 1,
+  TEXT_NODE = 3,
+  COMMENT_NODE = 8,
+}
+
+/** Temporary cache of text widths. */
+let cacheWidths: {[key: string]: number} | null = null;
+
+/** Number of current references to cache. */
+let cacheReference = 0;
+
+/** A HTML canvas context used for computing text width. */
+let canvasContext: CanvasRenderingContext2D | null = null;
+
+/**
+ * Helper method for creating SVG elements.
+ *
+ * @param name Element's tag name.
+ * @param attrs Dictionary of attribute names and values.
+ * @param opt_parent Optional parent on which to append the element.
+ * @returns if name is a string or a more specific type if it a member of Svg.
+ */
+export function createSvgElement<T extends SVGElement>(
+  name: string | Svg<T>,
+  attrs: {[key: string]: string | number},
+  opt_parent?: Element | null,
+): T {
+  const e = document.createElementNS(SVG_NS, `${name}`) as T;
+  for (const key in attrs) {
+    e.setAttribute(key, `${attrs[key]}`);
+  }
+  if (opt_parent) {
+    opt_parent.appendChild(e);
+  }
+  return e;
+}
+
+/**
+ * Add a CSS class to a element.
+ *
+ * Handles multiple space-separated classes for legacy reasons.
+ *
+ * @param element DOM element to add class to.
+ * @param className Name of class to add.
+ * @returns True if class was added, false if already present.
+ */
+export function addClass(element: Element, className: string): boolean {
+  const classNames = className.split(' ');
+  if (classNames.every((name) => element.classList.contains(name))) {
+    return false;
+  }
+  element.classList.add(...classNames);
+  return true;
+}
+
+/**
+ * Removes multiple classes from an element.
+ *
+ * @param element DOM element to remove classes from.
+ * @param classNames A string of one or multiple class names for an element.
+ */
+export function removeClasses(element: Element, classNames: string) {
+  element.classList.remove(...classNames.split(' '));
+}
+
+/**
+ * Remove a CSS class from a element.
+ *
+ * Handles multiple space-separated classes for legacy reasons.
+ *
+ * @param element DOM element to remove class from.
+ * @param className Name of class to remove.
+ * @returns True if class was removed, false if never present.
+ */
+export function removeClass(element: Element, className: string): boolean {
+  const classNames = className.split(' ');
+  if (classNames.every((name) => !element.classList.contains(name))) {
+    return false;
+  }
+  element.classList.remove(...classNames);
+  return true;
+}
+
+/**
+ * Checks if an element has the specified CSS class.
+ *
+ * @param element DOM element to check.
+ * @param className Name of class to check.
+ * @returns True if class exists, false otherwise.
+ */
+export function hasClass(element: Element, className: string): boolean {
+  return element.classList.contains(className);
+}
+
+/**
+ * Removes a node from its parent. No-op if not attached to a parent.
+ *
+ * @param node The node to remove.
+ * @returns The node removed if removed; else, null.
+ */
+// Copied from Closure goog.dom.removeNode
+export function removeNode(node: Node | null): Node | null {
+  return node && node.parentNode ? node.parentNode.removeChild(node) : null;
+}
+
+/**
+ * Insert a node after a reference node.
+ * Contrast with node.insertBefore function.
+ *
+ * @param newNode New element to insert.
+ * @param refNode Existing element to precede new node.
+ */
+export function insertAfter(newNode: Element, refNode: Element) {
+  const siblingNode = refNode.nextSibling;
+  const parentNode = refNode.parentNode;
+  if (!parentNode) {
+    throw Error('Reference node has no parent.');
+  }
+  if (siblingNode) {
+    parentNode.insertBefore(newNode, siblingNode);
+  } else {
+    parentNode.appendChild(newNode);
+  }
+}
+
+/**
+ * Sets the CSS transform property on an element. This function sets the
+ * non-vendor-prefixed and vendor-prefixed versions for backwards compatibility
+ * with older browsers. See https://caniuse.com/#feat=transforms2d
+ *
+ * @param element Element to which the CSS transform will be applied.
+ * @param transform The value of the CSS `transform` property.
+ */
+export function setCssTransform(
+  element: HTMLElement | SVGElement,
+  transform: string,
+) {
+  element.style['transform'] = transform;
+  element.style['-webkit-transform' as any] = transform;
+}
+
+/**
+ * Start caching text widths. Every call to this function MUST also call
+ * stopTextWidthCache. Caches must not survive between execution threads.
+ */
+export function startTextWidthCache() {
+  cacheReference++;
+  if (!cacheWidths) {
+    cacheWidths = Object.create(null);
+  }
+}
+
+/**
+ * Stop caching field widths. Unless caching was already on when the
+ * corresponding call to startTextWidthCache was made.
+ */
+export function stopTextWidthCache() {
+  cacheReference--;
+  if (!cacheReference) {
+    cacheWidths = null;
+  }
+}
+
+/**
+ * Gets the width of a text element, caching it in the process.
+ *
+ * @param textElement An SVG 'text' element.
+ * @returns Width of element.
+ */
+export function getTextWidth(textElement: SVGTextElement): number {
+  const key = textElement.textContent + '\n' + textElement.className.baseVal;
+  let width;
+  // Return the cached width if it exists.
+  if (cacheWidths) {
+    width = cacheWidths[key];
+    if (width) {
+      return width;
+    }
+  }
+
+  // Compute the width of the SVG text element.
+  const style = window.getComputedStyle(textElement);
+  width = getFastTextWidthWithSizeString(
+    textElement,
+    style.fontSize,
+    style.fontWeight,
+    style.fontFamily,
+  );
+
+  // Cache the computed width and return.
+  if (cacheWidths) {
+    cacheWidths[key] = width;
+  }
+  return width;
+}
+
+/**
+ * Gets the width of a text element using a faster method than `getTextWidth`.
+ * This method requires that we know the text element's font family and size in
+ * advance. Similar to `getTextWidth`, we cache the width we compute.
+ *
+ * @param textElement An SVG 'text' element.
+ * @param fontSize The font size to use.
+ * @param fontWeight The font weight to use.
+ * @param fontFamily The font family to use.
+ * @returns Width of element.
+ */
+export function getFastTextWidth(
+  textElement: SVGTextElement,
+  fontSize: number,
+  fontWeight: string,
+  fontFamily: string,
+): number {
+  return getFastTextWidthWithSizeString(
+    textElement,
+    fontSize + 'pt',
+    fontWeight,
+    fontFamily,
+  );
+}
+
+/**
+ * Gets the width of a text element using a faster method than `getTextWidth`.
+ * This method requires that we know the text element's font family and size in
+ * advance. Similar to `getTextWidth`, we cache the width we compute.
+ * This method is similar to `getFastTextWidth` but expects the font size
+ * parameter to be a string.
+ *
+ * @param textElement An SVG 'text' element.
+ * @param fontSize The font size to use.
+ * @param fontWeight The font weight to use.
+ * @param fontFamily The font family to use.
+ * @returns Width of element.
+ */
+export function getFastTextWidthWithSizeString(
+  textElement: SVGTextElement,
+  fontSize: string,
+  fontWeight: string,
+  fontFamily: string,
+): number {
+  const text = textElement.textContent;
+  const key = text + '\n' + textElement.className.baseVal;
+  let width;
+
+  // Return the cached width if it exists.
+  if (cacheWidths) {
+    width = cacheWidths[key];
+    if (width) {
+      return width;
+    }
+  }
+
+  if (!canvasContext) {
+    // Inject the canvas element used for computing text widths.
+    const computeCanvas = document.createElement('canvas');
+    computeCanvas.className = 'blocklyComputeCanvas';
+    document.body.appendChild(computeCanvas);
+
+    // Initialize the HTML canvas context and set the font.
+    // The context font must match blocklyText's fontsize and font-family
+    // set in CSS.
+    canvasContext = computeCanvas.getContext('2d');
+  }
+
+  // Measure the text width using the helper canvas context.
+  if (text && canvasContext) {
+    // Set the desired font size and family.
+    canvasContext.font = fontWeight + ' ' + fontSize + ' ' + fontFamily;
+    width = canvasContext.measureText(text).width;
+  } else {
+    width = 0;
+  }
+
+  // Cache the computed width and return.
+  if (cacheWidths) {
+    cacheWidths[key] = width;
+  }
+  return width;
+}
+
+/**
+ * Measure a font's metrics. The height and baseline values.
+ *
+ * @param text Text to measure the font dimensions of.
+ * @param fontSize The font size to use.
+ * @param fontWeight The font weight to use.
+ * @param fontFamily The font family to use.
+ * @returns Font measurements.
+ */
+export function measureFontMetrics(
+  text: string,
+  fontSize: string,
+  fontWeight: string,
+  fontFamily: string,
+): {height: number; baseline: number} {
+  const span = document.createElement('span');
+  span.style.font = fontWeight + ' ' + fontSize + ' ' + fontFamily;
+  span.textContent = text;
+
+  const block = document.createElement('div');
+  block.style.width = '1px';
+  block.style.height = '0';
+
+  const div = document.createElement('div');
+  div.style.display = 'flex';
+  div.style.position = 'fixed';
+  div.style.top = '0';
+  div.style.left = '0';
+  div.appendChild(span);
+  div.appendChild(block);
+
+  document.body.appendChild(div);
+  const result = {
+    height: 0,
+    baseline: 0,
+  };
+  try {
+    div.style.alignItems = 'baseline';
+    result.baseline = block.offsetTop - span.offsetTop;
+    div.style.alignItems = 'flex-end';
+    result.height = block.offsetTop - span.offsetTop;
+  } finally {
+    document.body.removeChild(div);
+  }
+  return result;
+}

package/core/utils/drag.ts

@@ -0,0 +1,74 @@
+/**
+ * @license
+ * Copyright 2024 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import * as browserEvents from '../browser_events.js';
+import type {WorkspaceSvg} from '../workspace_svg.js';
+import {Coordinate} from './coordinate.js';
+
+const workspaceToDragDelta: WeakMap<WorkspaceSvg, Coordinate> = new WeakMap();
+
+/**
+ * Convert from mouse coordinates to workspace coordinates.
+ *
+ * @param workspace The workspace where the pointer event is occurring.
+ * @param e The pointer event with the source coordinates.
+ */
+function mouseToWorkspacePoint(
+  workspace: WorkspaceSvg,
+  e: PointerEvent,
+): SVGPoint {
+  const point = browserEvents.mouseToSvg(
+    e,
+    workspace.getParentSvg(),
+    workspace.getInverseScreenCTM(),
+  );
+  // Fix scale of mouse event.
+  point.x /= workspace.scale;
+  point.y /= workspace.scale;
+  return point;
+}
+
+/**
+ * Start tracking a drag of an object on this workspace by recording the offset
+ * between the pointer's current location and the object's starting location.
+ *
+ * Used for resizing block comments and workspace comments.
+ *
+ * @param workspace The workspace where the drag is occurring.
+ * @param e Pointer down event.
+ * @param xy Starting location of object.
+ */
+export function start(
+  workspace: WorkspaceSvg,
+  e: PointerEvent,
+  xy: Coordinate,
+) {
+  const point = mouseToWorkspacePoint(workspace, e);
+  // Record the starting offset between the bubble's location and the mouse.
+  workspaceToDragDelta.set(workspace, Coordinate.difference(xy, point));
+}
+
+/**
+ * Compute the new position of a dragged object in this workspace based on the
+ * current pointer position and the offset between the pointer's starting
+ * location and the object's starting location.
+ *
+ * The start function should have be called previously, when the drag started.
+ *
+ * Used for resizing block comments and workspace comments.
+ *
+ * @param workspace The workspace where the drag is occurring.
+ * @param e Pointer move event.
+ * @returns New location of object.
+ */
+export function move(workspace: WorkspaceSvg, e: PointerEvent): Coordinate {
+  const point = mouseToWorkspacePoint(workspace, e);
+  const dragDelta = workspaceToDragDelta.get(workspace);
+  if (!dragDelta) {
+    throw new Error('Drag not initialized');
+  }
+  return Coordinate.sum(dragDelta, point);
+}

package/core/utils/focusable_tree_traverser.ts

@@ -0,0 +1,126 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type {IFocusableNode} from '../interfaces/i_focusable_node.js';
+import type {IFocusableTree} from '../interfaces/i_focusable_tree.js';
+import * as dom from '../utils/dom.js';
+
+/**
+ * A helper utility for IFocusableTree implementations to aid with common
+ * tree traversals.
+ */
+export class FocusableTreeTraverser {
+  private static readonly ACTIVE_CLASS_NAME = 'blocklyActiveFocus';
+  private static readonly PASSIVE_CSS_CLASS_NAME = 'blocklyPassiveFocus';
+  private static readonly ACTIVE_FOCUS_NODE_CSS_SELECTOR = `.${FocusableTreeTraverser.ACTIVE_CLASS_NAME}`;
+  private static readonly PASSIVE_FOCUS_NODE_CSS_SELECTOR = `.${FocusableTreeTraverser.PASSIVE_CSS_CLASS_NAME}`;
+
+  /**
+   * Returns the current IFocusableNode that is styled (and thus represented) as
+   * having either passive or active focus, only considering HTML and SVG
+   * elements.
+   *
+   * This can match against the tree's root.
+   *
+   * Note that this will never return a node from a nested sub-tree as that tree
+   * should specifically be used to retrieve its focused node.
+   *
+   * @param tree The IFocusableTree in which to search for a focused node.
+   * @returns The IFocusableNode currently with focus, or null if none.
+   */
+  static findFocusedNode(tree: IFocusableTree): IFocusableNode | null {
+    const rootNode = tree.getRootFocusableNode();
+    if (!rootNode.canBeFocused()) return null;
+    const root = rootNode.getFocusableElement();
+    if (
+      dom.hasClass(root, FocusableTreeTraverser.ACTIVE_CLASS_NAME) ||
+      dom.hasClass(root, FocusableTreeTraverser.PASSIVE_CSS_CLASS_NAME)
+    ) {
+      // The root has focus.
+      return rootNode;
+    }
+
+    const activeEl = root.querySelector(this.ACTIVE_FOCUS_NODE_CSS_SELECTOR);
+    if (activeEl instanceof HTMLElement || activeEl instanceof SVGElement) {
+      const active = FocusableTreeTraverser.findFocusableNodeFor(
+        activeEl,
+        tree,
+      );
+      if (active) return active;
+    }
+
+    // At most there should be one passive indicator per tree (not considering
+    // subtrees).
+    const passiveEl = root.querySelector(this.PASSIVE_FOCUS_NODE_CSS_SELECTOR);
+    if (passiveEl instanceof HTMLElement || passiveEl instanceof SVGElement) {
+      const passive = FocusableTreeTraverser.findFocusableNodeFor(
+        passiveEl,
+        tree,
+      );
+      if (passive) return passive;
+    }
+
+    return null;
+  }
+
+  /**
+   * Returns the IFocusableNode corresponding to the specified HTML or SVG
+   * element iff it's the root element or a descendent of the root element of
+   * the specified IFocusableTree.
+   *
+   * If the element exists within the specified tree's DOM structure but does
+   * not directly correspond to a node, the nearest parent node (or the tree's
+   * root) will be returned to represent the provided element.
+   *
+   * If the tree contains another nested IFocusableTree, the nested tree may be
+   * traversed but its nodes will never be returned here per the contract of
+   * IFocusableTree.lookUpFocusableNode.
+   *
+   * The provided element must have a non-null, non-empty ID that conforms to
+   * the contract mentioned in IFocusableNode.
+   *
+   * @param element The HTML or SVG element being sought.
+   * @param tree The tree under which the provided element may be a descendant.
+   * @returns The matching IFocusableNode, or null if there is no match.
+   */
+  static findFocusableNodeFor(
+    element: HTMLElement | SVGElement,
+    tree: IFocusableTree,
+  ): IFocusableNode | null {
+    // Note that the null check is due to Element.setAttribute() converting null
+    // to a string.
+    if (!element.id || element.id === 'null') return null;
+
+    // First, match against subtrees.
+    const subTreeMatches = tree.getNestedTrees().map((tree) => {
+      return FocusableTreeTraverser.findFocusableNodeFor(element, tree);
+    });
+    if (subTreeMatches.findIndex((match) => !!match) !== -1) {
+      // At least one subtree has a match for the element so it cannot be part
+      // of the outer tree.
+      return null;
+    }
+
+    // Second, check against the tree's root.
+    const rootNode = tree.getRootFocusableNode();
+    if (rootNode.canBeFocused() && element === rootNode.getFocusableElement()) {
+      return rootNode;
+    }
+
+    // Third, check if the element has a node.
+    const matchedChildNode = tree.lookUpFocusableNode(element.id) ?? null;
+    if (matchedChildNode) return matchedChildNode;
+
+    // Fourth, recurse up to find the nearest tree/node if it's possible.
+    const elementParent = element.parentElement;
+    if (!matchedChildNode && elementParent) {
+      return FocusableTreeTraverser.findFocusableNodeFor(elementParent, tree);
+    }
+
+    // Otherwise, there's no matching node.
+    return null;
+  }
+}

package/core/utils/idgenerator.ts

@@ -0,0 +1,70 @@
+/**
+ * @license
+ * Copyright 2019 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+// Former goog.module ID: Blockly.utils.idGenerator
+
+/**
+ * Legal characters for the universally unique IDs.  Should be all on
+ * a US keyboard.  No characters that conflict with XML or JSON.
+ * Requests to remove additional 'problematic' characters from this
+ * soup will be denied.  That's your failure to properly escape in
+ * your own environment.  Issues #251, #625, #682, #1304.
+ */
+const soup =
+  '!#$%()*+,-./:;=?@[]^_`{|}~' +
+  'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
+
+/**
+ * Namespace object for internal implementations we want to be able to
+ * stub in tests. Do not use externally.
+ *
+ * @internal
+ */
+const internal = {
+  /**
+   * Generate a random unique ID.  This should be globally unique.
+   * 87 characters ^ 20 length is greater than 128 bits (better than a UUID).
+   *
+   * @returns A globally unique ID string.
+   */
+  genUid: () => {
+    const length = 20;
+    const soupLength = soup.length;
+    const id = [];
+    for (let i = 0; i < length; i++) {
+      id[i] = soup.charAt(Math.random() * soupLength);
+    }
+    return id.join('');
+  },
+};
+export const TEST_ONLY = internal;
+
+/** Next unique ID to use. */
+let nextId = 0;
+
+/**
+ * Generate the next unique element IDs.
+ * IDs are compatible with the HTML4 'id' attribute restrictions:
+ * Use only ASCII letters, digits, '_', '-' and '.'
+ *
+ * For UUIDs use genUid (below) instead; this ID generator should
+ * primarily be used for IDs that end up in the DOM.
+ *
+ * @returns The next unique identifier.
+ */
+export function getNextUniqueId(): string {
+  return 'blockly-' + (nextId++).toString(36);
+}
+
+/**
+ * Generate a random unique ID.
+ *
+ * @see internal.genUid
+ * @returns A globally unique ID string.
+ */
+export function genUid(): string {
+  return internal.genUid();
+}