blockly 12.3.0 → 12.4.0

package/core/interfaces/i_flyout.ts

@@ -0,0 +1,190 @@
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+// Former goog.module ID: Blockly.IFlyout
+
+import type {BlockSvg} from '../block_svg.js';
+import type {FlyoutItem} from '../flyout_item.js';
+import type {Coordinate} from '../utils/coordinate.js';
+import type {Svg} from '../utils/svg.js';
+import type {FlyoutDefinition} from '../utils/toolbox.js';
+import type {WorkspaceSvg} from '../workspace_svg.js';
+import {IFocusableTree} from './i_focusable_tree.js';
+import type {IRegistrable} from './i_registrable.js';
+
+/**
+ * Interface for a flyout.
+ */
+export interface IFlyout extends IRegistrable, IFocusableTree {
+  /** Whether the flyout is laid out horizontally or not. */
+  horizontalLayout: boolean;
+
+  /** Is RTL vs LTR. */
+  RTL: boolean;
+
+  /** The target workspace */
+  targetWorkspace: WorkspaceSvg | null;
+
+  /** Margin around the edges of the blocks in the flyout. */
+  readonly MARGIN: number;
+
+  /** Does the flyout automatically close when a block is created? */
+  autoClose: boolean;
+
+  /** Corner radius of the flyout background. */
+  readonly CORNER_RADIUS: number;
+
+  /**
+   * Creates the flyout's DOM.  Only needs to be called once.  The flyout can
+   * either exist as its own svg element or be a g element nested inside a
+   * separate svg element.
+   *
+   * @param tagName The type of tag to put the flyout in. This should be <svg>
+   *     or <g>.
+   * @returns The flyout's SVG group.
+   */
+  createDom(
+    tagName: string | Svg<SVGSVGElement> | Svg<SVGGElement>,
+  ): SVGElement;
+
+  /**
+   * Initializes the flyout.
+   *
+   * @param targetWorkspace The workspace in which to create new blocks.
+   */
+  init(targetWorkspace: WorkspaceSvg): void;
+
+  /**
+   * Dispose of this flyout.
+   * Unlink from all DOM elements to prevent memory leaks.
+   */
+  dispose(): void;
+
+  /**
+   * Get the width of the flyout.
+   *
+   * @returns The width of the flyout.
+   */
+  getWidth(): number;
+
+  /**
+   * Get the height of the flyout.
+   *
+   * @returns The height of the flyout.
+   */
+  getHeight(): number;
+
+  /**
+   * Get the workspace inside the flyout.
+   *
+   * @returns The workspace inside the flyout.
+   */
+  getWorkspace(): WorkspaceSvg;
+
+  /**
+   * Is the flyout visible?
+   *
+   * @returns True if visible.
+   */
+  isVisible(): boolean;
+
+  /**
+   * Set whether the flyout is visible. A value of true does not necessarily
+   * mean that the flyout is shown. It could be hidden because its container is
+   * hidden.
+   *
+   * @param visible True if visible.
+   */
+  setVisible(visible: boolean): void;
+
+  /**
+   * Set whether this flyout's container is visible.
+   *
+   * @param visible Whether the container is visible.
+   */
+  setContainerVisible(visible: boolean): void;
+
+  /** Hide and empty the flyout. */
+  hide(): void;
+
+  /**
+   * Show and populate the flyout.
+   *
+   * @param flyoutDef Contents to display in the flyout. This is either an array
+   *     of Nodes, a NodeList, a toolbox definition, or a string with the name
+   *     of the dynamic category.
+   */
+  show(flyoutDef: FlyoutDefinition | string): void;
+
+  /**
+   * Returns the list of flyout items currently present in the flyout.
+   * The `show` method parses the flyout definition into a list of actual
+   * flyout items. This method should return those concrete items, which
+   * may be used for e.g. keyboard navigation.
+   *
+   * @returns List of flyout items.
+   */
+  getContents(): FlyoutItem[];
+
+  /**
+   * Create a copy of this block on the workspace.
+   *
+   * @param originalBlock The block to copy from the flyout.
+   * @returns The newly created block.
+   * @throws {Error} if something went wrong with deserialization.
+   */
+  createBlock(originalBlock: BlockSvg): BlockSvg;
+
+  /** Reflow blocks and their mats. */
+  reflow(): void;
+
+  /**
+   * @returns True if this flyout may be scrolled with a scrollbar or by
+   *     dragging.
+   */
+  isScrollable(): boolean;
+
+  /**
+   * Calculates the x coordinate for the flyout position.
+   *
+   * @returns X coordinate.
+   */
+  getX(): number;
+
+  /**
+   * Calculates the y coordinate for the flyout position.
+   *
+   * @returns Y coordinate.
+   */
+  getY(): number;
+
+  /** Position the flyout. */
+  position(): void;
+
+  /**
+   * Determine if a drag delta is toward the workspace, based on the position
+   * and orientation of the flyout. This is used in determineDragIntention_ to
+   * determine if a new block should be created or if the flyout should scroll.
+   *
+   * @param currentDragDeltaXY How far the pointer has moved from the position
+   *     at mouse down, in pixel units.
+   * @returns True if the drag is toward the workspace.
+   */
+  isDragTowardWorkspace(currentDragDeltaXY: Coordinate): boolean;
+
+  /**
+   * Does this flyout allow you to create a new instance of the given block?
+   * Used for deciding if a block can be "dragged out of" the flyout.
+   *
+   * @param block The block to copy from the flyout.
+   * @returns True if you can create a new instance of the block, false
+   *     otherwise.
+   */
+  isBlockCreatable(block: BlockSvg): boolean;
+
+  /** Scroll the flyout to the beginning of its contents. */
+  scrollToStart(): void;
+}

package/core/interfaces/i_flyout_inflater.ts

@@ -0,0 +1,51 @@
+import type {FlyoutItem} from '../flyout_item.js';
+import type {IFlyout} from './i_flyout.js';
+
+export interface IFlyoutInflater {
+  /**
+   * Loads the object represented by the given state onto the workspace.
+   *
+   * Note that this method's interface is identical to that in ISerializer, to
+   * allow for code reuse.
+   *
+   * @param state A JSON representation of an element to inflate on the flyout.
+   * @param flyout The flyout on whose workspace the inflated element
+   *    should be created. If the inflated element is an `IRenderedElement` it
+   *    itself or the inflater should append it to the workspace; the flyout
+   *    will not do so itself. The flyout is responsible for positioning the
+   *    element, however.
+   * @returns The newly inflated flyout element.
+   */
+  load(state: object, flyout: IFlyout): FlyoutItem;
+
+  /**
+   * Returns the amount of spacing that should follow the element corresponding
+   * to the given JSON representation.
+   *
+   * @param state A JSON representation of the element preceding the gap.
+   * @param defaultGap The default gap for elements in this flyout.
+   * @returns The gap that should follow the given element.
+   */
+  gapForItem(state: object, defaultGap: number): number;
+
+  /**
+   * Disposes of the given element.
+   *
+   * If the element in question resides on the flyout workspace, it should remove
+   * itself. Implementers are not otherwise required to fully dispose of the
+   * element; it may be e.g. cached for performance purposes.
+   *
+   * @param element The flyout element to dispose of.
+   */
+  disposeItem(item: FlyoutItem): void;
+
+  /**
+   * Returns the type of items that this inflater is responsible for inflating.
+   * This should be the same as the name under which this inflater registers
+   * itself, as well as the value returned by `getType()` on the `FlyoutItem`
+   * objects returned by `load()`.
+   *
+   * @returns The type of items this inflater creates.
+   */
+  getType(): string;
+}

package/core/interfaces/i_focusable_node.ts

@@ -0,0 +1,120 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type {IFocusableTree} from './i_focusable_tree.js';
+
+/** Represents anything that can have input focus. */
+export interface IFocusableNode {
+  /**
+   * Returns the DOM element that can be explicitly requested to receive focus.
+   *
+   * IMPORTANT: Please note that this element is expected to have a visual
+   * presence on the page as it will both be explicitly focused and have its
+   * style changed depending on its current focus state (i.e. blurred, actively
+   * focused, and passively focused). The element will have one of two styles
+   * attached (where no style indicates blurred/not focused):
+   * - blocklyActiveFocus
+   * - blocklyPassiveFocus
+   *
+   * The returned element must also have a valid ID specified, and this ID
+   * should be unique across the entire page. Failing to have a properly unique
+   * ID could result in trying to focus one node (such as via a mouse click)
+   * leading to another node with the same ID actually becoming focused by
+   * FocusManager.
+   *
+   * The returned element must be visible if the node is ever focused via
+   * FocusManager.focusNode() or FocusManager.focusTree(). It's allowed for an
+   * element to be hidden until onNodeFocus() is called, or become hidden with a
+   * call to onNodeBlur().
+   *
+   * It's expected the actual returned element will not change for the lifetime
+   * of the node (that is, its properties can change but a new element should
+   * never be returned). Also, the returned element will have its tabindex
+   * overwritten throughout the lifecycle of this node and FocusManager.
+   *
+   * If a node requires the ability to be focused directly without first being
+   * focused via FocusManager then it must set its own tab index.
+   *
+   * @returns The HTMLElement or SVGElement which can both receive focus and be
+   *     visually represented as actively or passively focused for this node.
+   */
+  getFocusableElement(): HTMLElement | SVGElement;
+
+  /**
+   * Returns the closest parent tree of this node (in cases where a tree has
+   * distinct trees underneath it), which represents the tree to which this node
+   * belongs.
+   *
+   * @returns The node's IFocusableTree.
+   */
+  getFocusableTree(): IFocusableTree;
+
+  /**
+   * Called when this node receives active focus.
+   *
+   * Note that it's fine for implementations to change visibility modifiers, but
+   * they should avoid the following:
+   * - Creating or removing DOM elements (including via the renderer or drawer).
+   * - Affecting focus via DOM focus() calls or the FocusManager.
+   *
+   * Implementations may consider scrolling themselves into view here; that is
+   * not handled by the focus manager.
+   */
+  onNodeFocus(): void;
+
+  /**
+   * Called when this node loses active focus. It may still have passive focus.
+   *
+   * This has the same implementation restrictions as onNodeFocus().
+   */
+  onNodeBlur(): void;
+
+  /**
+   * Indicates whether this node allows focus. If this returns false then none
+   * of the other IFocusableNode methods will be called.
+   *
+   * Note that special care must be taken if implementations of this function
+   * dynamically change their return value value over the lifetime of the node
+   * as certain environment conditions could affect the focusability of this
+   * node's DOM element (such as whether the element has a positive or zero
+   * tabindex). Also, changing from a true to a false value while the node holds
+   * focus will not immediately change the current focus of the node nor
+   * FocusManager's internal state, and thus may result in some of the node's
+   * functions being called later on when defocused (since it was previously
+   * considered focusable at the time of being focused).
+   *
+   * Implementations should generally always return true here unless there are
+   * circumstances under which this node should be skipped for focus
+   * considerations. Examples may include being disabled, read-only, a purely
+   * visual decoration, or a node with no visual representation that must
+   * implement this interface (e.g. due to a parent interface extending it).
+   * Keep in mind accessibility best practices when determining whether a node
+   * should be focusable since even disabled and read-only elements are still
+   * often relevant to providing organizational context to users (particularly
+   * when using a screen reader).
+   *
+   * @returns Whether this node can be focused by FocusManager.
+   */
+  canBeFocused(): boolean;
+}
+
+/**
+ * Determines whether the provided object fulfills the contract of
+ * IFocusableNode.
+ *
+ * @param obj The object to test.
+ * @returns Whether the provided object can be used as an IFocusableNode.
+ */
+export function isFocusableNode(obj: any): obj is IFocusableNode {
+  return (
+    obj &&
+    typeof obj.getFocusableElement === 'function' &&
+    typeof obj.getFocusableTree === 'function' &&
+    typeof obj.onNodeFocus === 'function' &&
+    typeof obj.onNodeBlur === 'function' &&
+    typeof obj.canBeFocused === 'function'
+  );
+}

package/core/interfaces/i_focusable_tree.ts

@@ -0,0 +1,144 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type {IFocusableNode} from './i_focusable_node.js';
+
+/**
+ * Represents a tree of focusable elements with its own active/passive focus
+ * context.
+ *
+ * Note that focus is handled by FocusManager, and tree implementations can have
+ * at most one IFocusableNode focused at one time. If the tree itself has focus,
+ * then the tree's focused node is considered 'active' ('passive' if another
+ * tree has focus).
+ *
+ * Focus is shared between one or more trees, where each tree can have exactly
+ * one active or passive node (and only one active node can exist on the whole
+ * page at any given time). The idea of passive focus is to provide context to
+ * users on where their focus will be restored upon navigating back to a
+ * previously focused tree.
+ *
+ * Note that if the tree's current focused node (passive or active) is needed,
+ * FocusableTreeTraverser.findFocusedNode can be used.
+ *
+ * Note that if specific nodes are needed to be retrieved for this tree, either
+ * use lookUpFocusableNode or FocusableTreeTraverser.findFocusableNodeFor.
+ */
+export interface IFocusableTree {
+  /**
+   * Returns the top-level focusable node of the tree.
+   *
+   * It's expected that the returned node will be focused in cases where
+   * FocusManager wants to focus a tree in a situation where it does not
+   * currently have a focused node.
+   */
+  getRootFocusableNode(): IFocusableNode;
+
+  /**
+   * Returns the IFocusableNode of this tree that should receive active focus
+   * when the tree itself has focus returned to it.
+   *
+   * There are some very important notes to consider about a tree's focus
+   * lifecycle when implementing a version of this method that doesn't return
+   * null:
+   * 1. A null previousNode does not guarantee first-time focus state as nodes
+   *    can be deleted.
+   * 2. This method is only used when the tree itself is focused, either through
+   *    tab navigation or via FocusManager.focusTree(). In many cases, the
+   *    previously focused node will be directly focused instead which will
+   *    bypass this method.
+   * 3. The default behavior (i.e. returning null here) involves either
+   *    restoring the previous node (previousNode) or focusing the tree's root.
+   * 4. The provided node may sometimes no longer be valid, such as in the case
+   *    an attempt is made to focus a node that has been recently removed from
+   *    its parent tree. Implementations can check for the validity of the node
+   *    in order to specialize the node to which focus should fall back.
+   *
+   * This method is largely intended to provide tree implementations with the
+   * means of specifying a better default node than their root.
+   *
+   * @param previousNode The node that previously held passive focus for this
+   *     tree, or null if the tree hasn't yet been focused.
+   * @returns The IFocusableNode that should now receive focus, or null if
+   *     default behavior should be used, instead.
+   */
+  getRestoredFocusableNode(
+    previousNode: IFocusableNode | null,
+  ): IFocusableNode | null;
+
+  /**
+   * Returns all directly nested trees under this tree.
+   *
+   * Note that the returned list of trees doesn't need to be stable, however all
+   * returned trees *do* need to be registered with FocusManager. Additionally,
+   * this must return actual nested trees as omitting a nested tree will affect
+   * how focus changes map to a specific node and its tree, potentially leading
+   * to user confusion.
+   */
+  getNestedTrees(): Array<IFocusableTree>;
+
+  /**
+   * Returns the IFocusableNode corresponding to the specified element ID, or
+   * null if there's no exact node within this tree with that ID or if the ID
+   * corresponds to the root of the tree.
+   *
+   * This will never match against nested trees.
+   *
+   * @param id The ID of the node's focusable HTMLElement or SVGElement.
+   */
+  lookUpFocusableNode(id: string): IFocusableNode | null;
+
+  /**
+   * Called when a node of this tree has received active focus.
+   *
+   * Note that a null previousTree does not necessarily indicate that this is
+   * the first time Blockly is receiving focus. In fact, few assumptions can be
+   * made about previous focus state as a previous null tree simply indicates
+   * that Blockly did not hold active focus prior to this tree becoming focused
+   * (which can happen due to focus exiting the Blockly injection div, or for
+   * other cases like ephemeral focus).
+   *
+   * See IFocusableNode.onNodeFocus() as implementations have the same
+   * restrictions as with that method.
+   *
+   * @param node The node receiving active focus.
+   * @param previousTree The previous tree that held active focus, or null if
+   *     none.
+   */
+  onTreeFocus(node: IFocusableNode, previousTree: IFocusableTree | null): void;
+
+  /**
+   * Called when the previously actively focused node of this tree is now
+   * passively focused and there is no other active node of this tree taking its
+   * place.
+   *
+   * This has the same implementation restrictions and considerations as
+   * onTreeFocus().
+   *
+   * @param nextTree The next tree receiving active focus, or null if none (such
+   *     as in the case that Blockly is entirely losing DOM focus).
+   */
+  onTreeBlur(nextTree: IFocusableTree | null): void;
+}
+
+/**
+ * Determines whether the provided object fulfills the contract of
+ * IFocusableTree.
+ *
+ * @param obj The object to test.
+ * @returns Whether the provided object can be used as an IFocusableTree.
+ */
+export function isFocusableTree(obj: any): obj is IFocusableTree {
+  return (
+    obj &&
+    typeof obj.getRootFocusableNode === 'function' &&
+    typeof obj.getRestoredFocusableNode === 'function' &&
+    typeof obj.getNestedTrees === 'function' &&
+    typeof obj.lookUpFocusableNode === 'function' &&
+    typeof obj.onTreeFocus === 'function' &&
+    typeof obj.onTreeBlur === 'function'
+  );
+}

package/core/interfaces/i_has_bubble.ts

@@ -0,0 +1,37 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type {IBubble} from './i_bubble';
+
+export interface IHasBubble {
+  /** @returns True if the bubble is currently open, false otherwise. */
+  bubbleIsVisible(): boolean;
+
+  /** Sets whether the bubble is open or not. */
+  setBubbleVisible(visible: boolean): Promise<void>;
+
+  /**
+   * Returns the current IBubble that implementations are managing, or null if
+   * there isn't one.
+   *
+   * Note that this cannot be expected to return null if bubbleIsVisible()
+   * returns false, i.e., the nullability of the returned bubble does not
+   * necessarily imply visibility.
+   *
+   * @returns The current IBubble maintained by implementations, or null if
+   *     there is not one.
+   */
+  getBubble(): IBubble | null;
+}
+
+/** Type guard that checks whether the given object is a IHasBubble. */
+export function hasBubble(obj: any): obj is IHasBubble {
+  return (
+    typeof obj.bubbleIsVisible === 'function' &&
+    typeof obj.setBubbleVisible === 'function' &&
+    typeof obj.getBubble === 'function'
+  );
+}

package/core/interfaces/i_icon.ts

@@ -0,0 +1,116 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type {IconType} from '../icons/icon_types.js';
+import type {Coordinate} from '../utils/coordinate.js';
+import type {Size} from '../utils/size.js';
+import {IFocusableNode, isFocusableNode} from './i_focusable_node.js';
+
+export interface IIcon extends IFocusableNode {
+  /**
+   * @returns the IconType representing the type of the icon. This value should
+   *     also be used to register the icon via `Blockly.icons.registry.register`.
+   */
+  getType(): IconType<IIcon>;
+
+  /**
+   * Creates the SVG elements for the icon that will live on the block.
+   *
+   * @param pointerdownListener An event listener that must be attached to the
+   *     root SVG element by the implementation of `initView`. Used by Blockly's
+   *     gesture system to properly handle clicks and drags.
+   */
+  initView(pointerdownListener: (e: PointerEvent) => void): void;
+
+  /**
+   * Disposes of any elements of the icon.
+   *
+   * @remarks
+   *
+   * In particular, if this icon is currently showing a bubble, this should be
+   * used to hide it.
+   */
+  dispose(): void;
+
+  /**
+   * @returns the "weight" of the icon, which determines the static order which
+   *     icons should be rendered in. More positive numbers are rendered farther
+   *     toward the end of the block.
+   */
+  getWeight(): number;
+
+  /** @returns The dimensions of the icon for use in rendering. */
+  getSize(): Size;
+
+  /** Updates the icon's color when the block's color changes.. */
+  applyColour(): void;
+
+  /** Hides the icon when it is part of an insertion marker. */
+  hideForInsertionMarker(): void;
+
+  /** Updates the icon's editability when the block's editability changes. */
+  updateEditable(): void;
+
+  /**
+   * Updates the icon's collapsed-ness/view when the block's collapsed-ness
+   * changes.
+   */
+  updateCollapsed(): void;
+
+  /**
+   * @returns Whether this icon is shown when the block is collapsed. Used
+   *     to allow renderers to account for padding.
+   */
+  isShownWhenCollapsed(): boolean;
+
+  /**
+   * Notifies the icon where it is relative to its block's top-start, in
+   * workspace units.
+   */
+  setOffsetInBlock(offset: Coordinate): void;
+
+  /**
+   * Notifies the icon that it has changed locations.
+   *
+   * @param blockOrigin The location of this icon's block's top-start corner
+   *     in workspace coordinates.
+   */
+  onLocationChange(blockOrigin: Coordinate): void;
+
+  /**
+   * Notifies the icon that it has been clicked.
+   */
+  onClick(): void;
+
+  /**
+   * Check whether the icon should be clickable while the block is in a flyout.
+   * If this function is not defined, the icon will be clickable in all flyouts.
+   *
+   * @param autoClosingFlyout true if the containing flyout is an auto-closing one.
+   * @returns Whether the icon should be clickable while the block is in a flyout.
+   */
+  isClickableInFlyout?(autoClosingFlyout: boolean): boolean;
+}
+
+/** Type guard that checks whether the given object is an IIcon. */
+export function isIcon(obj: any): obj is IIcon {
+  return (
+    isFocusableNode(obj) &&
+    typeof (obj as IIcon).getType === 'function' &&
+    typeof (obj as IIcon).initView === 'function' &&
+    typeof (obj as IIcon).dispose === 'function' &&
+    typeof (obj as IIcon).getWeight === 'function' &&
+    typeof (obj as IIcon).getSize === 'function' &&
+    typeof (obj as IIcon).applyColour === 'function' &&
+    typeof (obj as IIcon).hideForInsertionMarker === 'function' &&
+    typeof (obj as IIcon).updateEditable === 'function' &&
+    typeof (obj as IIcon).updateCollapsed === 'function' &&
+    typeof (obj as IIcon).isShownWhenCollapsed === 'function' &&
+    typeof (obj as IIcon).setOffsetInBlock === 'function' &&
+    typeof (obj as IIcon).onLocationChange === 'function' &&
+    typeof (obj as IIcon).onClick === 'function'
+  );
+}

package/core/interfaces/i_keyboard_accessible.ts

@@ -0,0 +1,22 @@
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+// Former goog.module ID: Blockly.IKeyboardAccessible
+
+import {KeyboardShortcut} from '../shortcut_registry.js';
+
+/**
+ * An interface for an object that handles keyboard shortcuts.
+ */
+export interface IKeyboardAccessible {
+  /**
+   * Handles the given keyboard shortcut.
+   *
+   * @param shortcut The shortcut to be handled.
+   * @returns True if the shortcut has been handled, false otherwise.
+   */
+  onShortcut(shortcut: KeyboardShortcut): boolean;
+}