blockly 12.4.0 → 12.5.0

package/core/keyboard_nav/block_navigation_policy.ts

@@ -1,213 +0,0 @@
-/**
- * @license
- * Copyright 2025 Google LLC
- * SPDX-License-Identifier: Apache-2.0
- */
-
-import {BlockSvg} from '../block_svg.js';
-import {ConnectionType} from '../connection_type.js';
-import type {Field} from '../field.js';
-import type {Icon} from '../icons/icon.js';
-import type {IBoundedElement} from '../interfaces/i_bounded_element.js';
-import type {IFocusableNode} from '../interfaces/i_focusable_node.js';
-import {isFocusableNode} from '../interfaces/i_focusable_node.js';
-import type {INavigationPolicy} from '../interfaces/i_navigation_policy.js';
-import type {ISelectable} from '../interfaces/i_selectable.js';
-import {RenderedConnection} from '../rendered_connection.js';
-import {WorkspaceSvg} from '../workspace_svg.js';
-
-/**
- * Set of rules controlling keyboard navigation from a block.
- */
-export class BlockNavigationPolicy implements INavigationPolicy<BlockSvg> {
-  /**
-   * Returns the first child of the given block.
-   *
-   * @param current The block to return the first child of.
-   * @returns The first field or input of the given block, if any.
-   */
-  getFirstChild(current: BlockSvg): IFocusableNode | null {
-    const candidates = getBlockNavigationCandidates(current, true);
-    return candidates[0];
-  }
-
-  /**
-   * Returns the parent of the given block.
-   *
-   * @param current The block to return the parent of.
-   * @returns The top block of the given block's stack, or the connection to
-   *     which it is attached.
-   */
-  getParent(current: BlockSvg): IFocusableNode | null {
-    if (current.previousConnection?.targetBlock()) {
-      const surroundParent = current.getSurroundParent();
-      if (surroundParent) return surroundParent;
-    } else if (current.outputConnection?.targetBlock()) {
-      return current.outputConnection.targetBlock();
-    }
-
-    return current.workspace;
-  }
-
-  /**
-   * Returns the next peer node of the given block.
-   *
-   * @param current The block to find the following element of.
-   * @returns The first node of the next input/stack if the given block is a terminal
-   *     block, or its next connection.
-   */
-  getNextSibling(current: BlockSvg): IFocusableNode | null {
-    if (current.nextConnection?.targetBlock()) {
-      return current.nextConnection?.targetBlock();
-    } else if (current.outputConnection?.targetBlock()) {
-      return navigateBlock(current, 1);
-    } else if (current.getSurroundParent()) {
-      return navigateBlock(current.getTopStackBlock(), 1);
-    } else if (this.getParent(current) instanceof WorkspaceSvg) {
-      return navigateStacks(current, 1);
-    }
-
-    return null;
-  }
-
-  /**
-   * Returns the previous peer node of the given block.
-   *
-   * @param current The block to find the preceding element of.
-   * @returns The block's previous/output connection, or the last
-   *     connection/block of the previous block stack if it is a root block.
-   */
-  getPreviousSibling(current: BlockSvg): IFocusableNode | null {
-    if (current.previousConnection?.targetBlock()) {
-      return current.previousConnection?.targetBlock();
-    } else if (current.outputConnection?.targetBlock()) {
-      return navigateBlock(current, -1);
-    } else if (this.getParent(current) instanceof WorkspaceSvg) {
-      return navigateStacks(current, -1);
-    }
-
-    return null;
-  }
-
-  /**
-   * Returns whether or not the given block can be navigated to.
-   *
-   * @param current The instance to check for navigability.
-   * @returns True if the given block can be focused.
-   */
-  isNavigable(current: BlockSvg): boolean {
-    return current.canBeFocused();
-  }
-
-  /**
-   * Returns whether the given object can be navigated from by this policy.
-   *
-   * @param current The object to check if this policy applies to.
-   * @returns True if the object is a BlockSvg.
-   */
-  isApplicable(current: any): current is BlockSvg {
-    return current instanceof BlockSvg;
-  }
-}
-
-/**
- * Returns a list of the navigable children of the given block.
- *
- * @param block The block to retrieve the navigable children of.
- * @returns A list of navigable/focusable children of the given block.
- */
-function getBlockNavigationCandidates(
-  block: BlockSvg,
-  forward: boolean,
-): IFocusableNode[] {
-  const candidates: IFocusableNode[] = block.getIcons();
-
-  for (const input of block.inputList) {
-    if (!input.isVisible()) continue;
-    candidates.push(...input.fieldRow);
-    if (input.connection?.targetBlock()) {
-      const connectedBlock = input.connection.targetBlock() as BlockSvg;
-      if (input.connection.type === ConnectionType.NEXT_STATEMENT && !forward) {
-        const lastStackBlock = connectedBlock
-          .lastConnectionInStack(false)
-          ?.getSourceBlock();
-        if (lastStackBlock) {
-          candidates.push(lastStackBlock);
-        }
-      } else {
-        candidates.push(connectedBlock);
-      }
-    } else if (input.connection?.type === ConnectionType.INPUT_VALUE) {
-      candidates.push(input.connection as RenderedConnection);
-    }
-  }
-
-  return candidates;
-}
-
-/**
- * Returns the next/previous stack relative to the given element's stack.
- *
- * @param current The element whose stack will be navigated relative to.
- * @param delta The difference in index to navigate; positive values navigate
- *     to the nth next stack, while negative values navigate to the nth previous
- *     stack.
- * @returns The first element in the stack offset by `delta` relative to the
- *     current element's stack, or the last element in the stack offset by
- * `delta` relative to the current element's stack when navigating backwards.
- */
-export function navigateStacks(current: ISelectable, delta: number) {
-  const stacks: IFocusableNode[] = (current.workspace as WorkspaceSvg)
-    .getTopBoundedElements(true)
-    .filter((element: IBoundedElement) => isFocusableNode(element));
-  const currentIndex = stacks.indexOf(
-    current instanceof BlockSvg ? current.getRootBlock() : current,
-  );
-  const targetIndex = currentIndex + delta;
-  let result: IFocusableNode | null = null;
-  if (targetIndex >= 0 && targetIndex < stacks.length) {
-    result = stacks[targetIndex];
-  } else if (targetIndex < 0) {
-    result = stacks[stacks.length - 1];
-  } else if (targetIndex >= stacks.length) {
-    result = stacks[0];
-  }
-
-  // When navigating to a previous block stack, our previous sibling is the last
-  // block in it.
-  if (delta < 0 && result instanceof BlockSvg) {
-    return result.lastConnectionInStack(false)?.getSourceBlock() ?? result;
-  }
-
-  return result;
-}
-
-/**
- * Returns the next navigable item relative to the provided block child.
- *
- * @param current The navigable block child item to navigate relative to.
- * @param delta The difference in index to navigate; positive values navigate
- *     forward by n, while negative values navigate backwards by n.
- * @returns The navigable block child offset by `delta` relative to `current`.
- */
-export function navigateBlock(
-  current: Icon | Field | RenderedConnection | BlockSvg,
-  delta: number,
-): IFocusableNode | null {
-  const block =
-    current instanceof BlockSvg
-      ? (current.outputConnection?.targetBlock() ?? current.getSurroundParent())
-      : current.getSourceBlock();
-  if (!(block instanceof BlockSvg)) return null;
-
-  const candidates = getBlockNavigationCandidates(block, delta > 0);
-  const currentIndex = candidates.indexOf(current);
-  if (currentIndex === -1) return null;
-
-  const targetIndex = currentIndex + delta;
-  if (targetIndex >= 0 && targetIndex < candidates.length) {
-    return candidates[targetIndex];
-  }
-
-  return null;
-}

package/core/keyboard_nav/comment_bar_button_navigation_policy.ts

@@ -1,88 +0,0 @@
-/**
- * @license
- * Copyright 2025 Google LLC
- * SPDX-License-Identifier: Apache-2.0
- */
-
-import {CommentBarButton} from '../comments/comment_bar_button.js';
-import type {IFocusableNode} from '../interfaces/i_focusable_node.js';
-import type {INavigationPolicy} from '../interfaces/i_navigation_policy.js';
-
-/**
- * Set of rules controlling keyboard navigation from a CommentBarButton.
- */
-export class CommentBarButtonNavigationPolicy
-  implements INavigationPolicy<CommentBarButton>
-{
-  /**
-   * Returns the first child of the given CommentBarButton.
-   *
-   * @param _current The CommentBarButton to return the first child of.
-   * @returns Null.
-   */
-  getFirstChild(_current: CommentBarButton): IFocusableNode | null {
-    return null;
-  }
-
-  /**
-   * Returns the parent of the given CommentBarButton.
-   *
-   * @param current The CommentBarButton to return the parent of.
-   * @returns The parent comment of the given CommentBarButton.
-   */
-  getParent(current: CommentBarButton): IFocusableNode | null {
-    return current
-      .getCommentView()
-      .workspace.getCommentById(current.getCommentView().commentId);
-  }
-
-  /**
-   * Returns the next peer node of the given CommentBarButton.
-   *
-   * @param current The CommentBarButton to find the following element of.
-   * @returns The next CommentBarButton, if any.
-   */
-  getNextSibling(current: CommentBarButton): IFocusableNode | null {
-    const children = current.getCommentView().getCommentBarButtons();
-    const currentIndex = children.indexOf(current);
-    if (currentIndex >= 0 && currentIndex + 1 < children.length) {
-      return children[currentIndex + 1];
-    }
-    return null;
-  }
-
-  /**
-   * Returns the previous peer node of the given CommentBarButton.
-   *
-   * @param current The CommentBarButton to find the preceding element of.
-   * @returns The CommentBarButton's previous CommentBarButton, if any.
-   */
-  getPreviousSibling(current: CommentBarButton): IFocusableNode | null {
-    const children = current.getCommentView().getCommentBarButtons();
-    const currentIndex = children.indexOf(current);
-    if (currentIndex > 0) {
-      return children[currentIndex - 1];
-    }
-    return null;
-  }
-
-  /**
-   * Returns whether or not the given CommentBarButton can be navigated to.
-   *
-   * @param current The instance to check for navigability.
-   * @returns True if the given CommentBarButton can be focused.
-   */
-  isNavigable(current: CommentBarButton): boolean {
-    return current.canBeFocused();
-  }
-
-  /**
-   * Returns whether the given object can be navigated from by this policy.
-   *
-   * @param current The object to check if this policy applies to.
-   * @returns True if the object is an CommentBarButton.
-   */
-  isApplicable(current: any): current is CommentBarButton {
-    return current instanceof CommentBarButton;
-  }
-}

package/core/keyboard_nav/comment_editor_navigation_policy.ts

@@ -1,54 +0,0 @@
-/**
- * @license
- * Copyright 2025 Google LLC
- * SPDX-License-Identifier: Apache-2.0
- */
-
-import {CommentEditor} from '../comments/comment_editor.js';
-import type {IFocusableNode} from '../interfaces/i_focusable_node.js';
-import type {INavigationPolicy} from '../interfaces/i_navigation_policy.js';
-
-/**
- * Set of rules controlling keyboard navigation from a comment editor.
- * This is a no-op placeholder (other than isNavigable/isApplicable) since
- * comment editors handle their own navigation when editing ends.
- */
-export class CommentEditorNavigationPolicy
-  implements INavigationPolicy<CommentEditor>
-{
-  getFirstChild(_current: CommentEditor): IFocusableNode | null {
-    return null;
-  }
-
-  getParent(_current: CommentEditor): IFocusableNode | null {
-    return null;
-  }
-
-  getNextSibling(_current: CommentEditor): IFocusableNode | null {
-    return null;
-  }
-
-  getPreviousSibling(_current: CommentEditor): IFocusableNode | null {
-    return null;
-  }
-
-  /**
-   * Returns whether or not the given comment editor can be navigated to.
-   *
-   * @param current The instance to check for navigability.
-   * @returns False.
-   */
-  isNavigable(current: CommentEditor): boolean {
-    return current.canBeFocused();
-  }
-
-  /**
-   * Returns whether the given object can be navigated from by this policy.
-   *
-   * @param current The object to check if this policy applies to.
-   * @returns True if the object is a CommentEditor.
-   */
-  isApplicable(current: any): current is CommentEditor {
-    return current instanceof CommentEditor;
-  }
-}

package/core/keyboard_nav/connection_navigation_policy.ts

@@ -1,155 +0,0 @@
-/**
- * @license
- * Copyright 2025 Google LLC
- * SPDX-License-Identifier: Apache-2.0
- */
-
-import type {BlockSvg} from '../block_svg.js';
-import {ConnectionType} from '../connection_type.js';
-import type {IFocusableNode} from '../interfaces/i_focusable_node.js';
-import type {INavigationPolicy} from '../interfaces/i_navigation_policy.js';
-import {RenderedConnection} from '../rendered_connection.js';
-import {navigateBlock} from './block_navigation_policy.js';
-
-/**
- * Set of rules controlling keyboard navigation from a connection.
- */
-export class ConnectionNavigationPolicy
-  implements INavigationPolicy<RenderedConnection>
-{
-  /**
-   * Returns the first child of the given connection.
-   *
-   * @param current The connection to return the first child of.
-   * @returns The connection's first child element, or null if not none.
-   */
-  getFirstChild(current: RenderedConnection): IFocusableNode | null {
-    if (current.getParentInput()) {
-      return current.targetConnection;
-    }
-
-    return null;
-  }
-
-  /**
-   * Returns the parent of the given connection.
-   *
-   * @param current The connection to return the parent of.
-   * @returns The given connection's parent connection or block.
-   */
-  getParent(current: RenderedConnection): IFocusableNode | null {
-    return current.getSourceBlock();
-  }
-
-  /**
-   * Returns the next element following the given connection.
-   *
-   * @param current The connection to navigate from.
-   * @returns The field, input connection or block following this connection.
-   */
-  getNextSibling(current: RenderedConnection): IFocusableNode | null {
-    if (current.getParentInput()) {
-      return navigateBlock(current, 1);
-    } else if (current.type === ConnectionType.NEXT_STATEMENT) {
-      const nextBlock = current.targetConnection;
-      // If this connection is the last one in the stack, our next sibling is
-      // the next block stack.
-      const sourceBlock = current.getSourceBlock();
-      if (
-        !nextBlock &&
-        sourceBlock.getRootBlock().lastConnectionInStack(false) === current
-      ) {
-        const topBlocks = sourceBlock.workspace.getTopBlocks(true);
-        let targetIndex = topBlocks.indexOf(sourceBlock.getRootBlock()) + 1;
-        if (targetIndex >= topBlocks.length) {
-          targetIndex = 0;
-        }
-        const nextBlock = topBlocks[targetIndex];
-        return this.getParentConnection(nextBlock) ?? nextBlock;
-      }
-
-      return nextBlock;
-    }
-
-    return current.getSourceBlock();
-  }
-
-  /**
-   * Returns the element preceding the given connection.
-   *
-   * @param current The connection to navigate from.
-   * @returns The field, input connection or block preceding this connection.
-   */
-  getPreviousSibling(current: RenderedConnection): IFocusableNode | null {
-    if (current.getParentInput()) {
-      return navigateBlock(current, -1);
-    } else if (
-      current.type === ConnectionType.PREVIOUS_STATEMENT ||
-      current.type === ConnectionType.OUTPUT_VALUE
-    ) {
-      const previousConnection =
-        current.targetConnection && !current.targetConnection.getParentInput()
-          ? current.targetConnection
-          : null;
-
-      // If this connection is a disconnected previous/output connection, our
-      // previous sibling is the previous block stack's last connection/block.
-      const sourceBlock = current.getSourceBlock();
-      if (
-        !previousConnection &&
-        this.getParentConnection(sourceBlock.getRootBlock()) === current
-      ) {
-        const topBlocks = sourceBlock.workspace.getTopBlocks(true);
-        let targetIndex = topBlocks.indexOf(sourceBlock.getRootBlock()) - 1;
-        if (targetIndex < 0) {
-          targetIndex = topBlocks.length - 1;
-        }
-        const previousRootBlock = topBlocks[targetIndex];
-        return (
-          previousRootBlock.lastConnectionInStack(false) ?? previousRootBlock
-        );
-      }
-
-      return previousConnection;
-    } else if (current.type === ConnectionType.NEXT_STATEMENT) {
-      return current.getSourceBlock();
-    }
-    return null;
-  }
-
-  /**
-   * Gets the parent connection on a block.
-   * This is either an output connection, previous connection or undefined.
-   * If both connections exist return the one that is actually connected
-   * to another block.
-   *
-   * @param block The block to find the parent connection on.
-   * @returns The connection connecting to the parent of the block.
-   */
-  protected getParentConnection(block: BlockSvg) {
-    if (!block.outputConnection || block.previousConnection?.isConnected()) {
-      return block.previousConnection;
-    }
-    return block.outputConnection;
-  }
-
-  /**
-   * Returns whether or not the given connection can be navigated to.
-   *
-   * @param current The instance to check for navigability.
-   * @returns True if the given connection can be focused.
-   */
-  isNavigable(current: RenderedConnection): boolean {
-    return current.canBeFocused();
-  }
-
-  /**
-   * Returns whether the given object can be navigated from by this policy.
-   *
-   * @param current The object to check if this policy applies to.
-   * @returns True if the object is a RenderedConnection.
-   */
-  isApplicable(current: any): current is RenderedConnection {
-    return current instanceof RenderedConnection;
-  }
-}

package/core/keyboard_nav/field_navigation_policy.ts

@@ -1,85 +0,0 @@
-/**
- * @license
- * Copyright 2025 Google LLC
- * SPDX-License-Identifier: Apache-2.0
- */
-
-import type {BlockSvg} from '../block_svg.js';
-import {Field} from '../field.js';
-import type {IFocusableNode} from '../interfaces/i_focusable_node.js';
-import type {INavigationPolicy} from '../interfaces/i_navigation_policy.js';
-import {navigateBlock} from './block_navigation_policy.js';
-
-/**
- * Set of rules controlling keyboard navigation from a field.
- */
-export class FieldNavigationPolicy implements INavigationPolicy<Field<any>> {
-  /**
-   * Returns null since fields do not have children.
-   *
-   * @param _current The field to navigate from.
-   * @returns Null.
-   */
-  getFirstChild(_current: Field<any>): IFocusableNode | null {
-    return null;
-  }
-
-  /**
-   * Returns the parent block of the given field.
-   *
-   * @param current The field to navigate from.
-   * @returns The given field's parent block.
-   */
-  getParent(current: Field<any>): IFocusableNode | null {
-    return current.getSourceBlock() as BlockSvg;
-  }
-
-  /**
-   * Returns the next field or input following the given field.
-   *
-   * @param current The field to navigate from.
-   * @returns The next field or input in the given field's block.
-   */
-  getNextSibling(current: Field<any>): IFocusableNode | null {
-    return navigateBlock(current, 1);
-  }
-
-  /**
-   * Returns the field or input preceding the given field.
-   *
-   * @param current The field to navigate from.
-   * @returns The preceding field or input in the given field's block.
-   */
-  getPreviousSibling(current: Field<any>): IFocusableNode | null {
-    return navigateBlock(current, -1);
-  }
-
-  /**
-   * Returns whether or not the given field can be navigated to.
-   *
-   * @param current The instance to check for navigability.
-   * @returns True if the given field can be focused and navigated to.
-   */
-  isNavigable(current: Field<any>): boolean {
-    return (
-      current.canBeFocused() &&
-      current.isVisible() &&
-      (current.isClickable() || current.isCurrentlyEditable()) &&
-      !(
-        current.getSourceBlock()?.isSimpleReporter() &&
-        current.isFullBlockField()
-      ) &&
-      current.getParentInput().isVisible()
-    );
-  }
-
-  /**
-   * Returns whether the given object can be navigated from by this policy.
-   *
-   * @param current The object to check if this policy applies to.
-   * @returns True if the object is a Field.
-   */
-  isApplicable(current: any): current is Field {
-    return current instanceof Field;
-  }
-}

package/core/keyboard_nav/flyout_button_navigation_policy.ts

@@ -1,76 +0,0 @@
-/**
- * @license
- * Copyright 2025 Google LLC
- * SPDX-License-Identifier: Apache-2.0
- */
-
-import {FlyoutButton} from '../flyout_button.js';
-import type {IFocusableNode} from '../interfaces/i_focusable_node.js';
-import type {INavigationPolicy} from '../interfaces/i_navigation_policy.js';
-
-/**
- * Set of rules controlling keyboard navigation from a flyout button.
- */
-export class FlyoutButtonNavigationPolicy
-  implements INavigationPolicy<FlyoutButton>
-{
-  /**
-   * Returns null since flyout buttons have no children.
-   *
-   * @param _current The FlyoutButton instance to navigate from.
-   * @returns Null.
-   */
-  getFirstChild(_current: FlyoutButton): IFocusableNode | null {
-    return null;
-  }
-
-  /**
-   * Returns the parent workspace of the given flyout button.
-   *
-   * @param current The FlyoutButton instance to navigate from.
-   * @returns The given flyout button's parent workspace.
-   */
-  getParent(current: FlyoutButton): IFocusableNode | null {
-    return current.getWorkspace();
-  }
-
-  /**
-   * Returns null since inter-item navigation is done by FlyoutNavigationPolicy.
-   *
-   * @param _current The FlyoutButton instance to navigate from.
-   * @returns Null.
-   */
-  getNextSibling(_current: FlyoutButton): IFocusableNode | null {
-    return null;
-  }
-
-  /**
-   * Returns null since inter-item navigation is done by FlyoutNavigationPolicy.
-   *
-   * @param _current The FlyoutButton instance to navigate from.
-   * @returns Null.
-   */
-  getPreviousSibling(_current: FlyoutButton): IFocusableNode | null {
-    return null;
-  }
-
-  /**
-   * Returns whether or not the given flyout button can be navigated to.
-   *
-   * @param current The instance to check for navigability.
-   * @returns True if the given flyout button can be focused.
-   */
-  isNavigable(current: FlyoutButton): boolean {
-    return current.canBeFocused();
-  }
-
-  /**
-   * Returns whether the given object can be navigated from by this policy.
-   *
-   * @param current The object to check if this policy applies to.
-   * @returns True if the object is a FlyoutButton.
-   */
-  isApplicable(current: any): current is FlyoutButton {
-    return current instanceof FlyoutButton;
-  }
-}