blockly 12.4.0 → 12.4.1

package/core/interfaces/i_flyout.ts

@@ -1,190 +0,0 @@
-/**
- * @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

@@ -1,51 +0,0 @@
-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

@@ -1,120 +0,0 @@
-/**
- * @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

@@ -1,144 +0,0 @@
-/**
- * @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

@@ -1,37 +0,0 @@
-/**
- * @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

@@ -1,116 +0,0 @@
-/**
- * @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

@@ -1,22 +0,0 @@
-/**
- * @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;
-}