scratch-blocks 1.1.206 → 2.0.0-beta.1

package/blockly-rc/core/interfaces/i_contextmenu.ts

@@ -0,0 +1,16 @@
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+// Former goog.module ID: Blockly.IContextMenu
+
+export interface IContextMenu {
+  /**
+   * Show the context menu for this object.
+   *
+   * @param e Mouse event.
+   */
+  showContextMenu(e: Event): void;
+}

package/blockly-rc/core/interfaces/i_copyable.ts

@@ -0,0 +1,31 @@
+/**
+ * @license
+ * Copyright 2019 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+// Former goog.module ID: Blockly.ICopyable
+
+import type {ISelectable} from './i_selectable.js';
+
+export interface ICopyable<T extends ICopyData> extends ISelectable {
+  /**
+   * Encode for copying.
+   *
+   * @returns Copy metadata.
+   */
+  toCopyData(): T | null;
+}
+
+export namespace ICopyable {
+  export interface ICopyData {
+    paster: string;
+  }
+}
+
+export type ICopyData = ICopyable.ICopyData;
+
+/** @returns true if the given object is copyable. */
+export function isCopyable(obj: any): obj is ICopyable<ICopyData> {
+  return obj.toCopyData !== undefined;
+}

package/blockly-rc/core/interfaces/i_deletable.ts

@@ -0,0 +1,34 @@
+/**
+ * @license
+ * Copyright 2019 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+// Former goog.module ID: Blockly.IDeletable
+
+/**
+ * The interface for an object that can be deleted.
+ */
+export interface IDeletable {
+  /**
+   * Get whether this object is deletable or not.
+   *
+   * @returns True if deletable.
+   */
+  isDeletable(): boolean;
+
+  /** Disposes of this object, cleaning up any references or DOM elements. */
+  dispose(): void;
+
+  /** Visually indicates that the object is pending deletion. */
+  setDeleteStyle(wouldDelete: boolean): void;
+}
+
+/** Returns whether the given object is an IDeletable. */
+export function isDeletable(obj: any): obj is IDeletable {
+  return (
+    obj['isDeletable'] !== undefined &&
+    obj['dispose'] !== undefined &&
+    obj['setDeleteStyle'] !== undefined
+  );
+}

package/blockly-rc/core/interfaces/i_delete_area.ts

@@ -0,0 +1,28 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+// Former goog.module ID: Blockly.IDeleteArea
+
+import type {IDragTarget} from './i_drag_target.js';
+import type {IDraggable} from './i_draggable.js';
+
+/**
+ * Interface for a component that can delete a block or bubble that is dropped
+ * on top of it.
+ */
+export interface IDeleteArea extends IDragTarget {
+  /**
+   * Returns whether the provided block or bubble would be deleted if dropped on
+   * this area.
+   * This method should check if the element is deletable and is always called
+   * before onDragEnter/onDragOver/onDragExit.
+   *
+   * @param element The block or bubble currently being dragged.
+   * @returns Whether the element provided would be deleted if dropped on this
+   *     area.
+   */
+  wouldDelete(element: IDraggable): boolean;
+}

package/blockly-rc/core/interfaces/i_drag_target.ts

@@ -0,0 +1,69 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {Rect} from '../utils/rect.js';
+
+import {IDraggable} from './i_draggable.js';
+
+// Former goog.module ID: Blockly.IDragTarget
+
+import type {IComponent} from './i_component.js';
+
+/**
+ * Interface for a component with custom behaviour when a block or bubble is
+ * dragged over or dropped on top of it.
+ */
+export interface IDragTarget extends IComponent {
+  /**
+   * Returns the bounding rectangle of the drag target area in pixel units
+   * relative to viewport.
+   *
+   * @returns The component's bounding box. Null if drag target area should be
+   *     ignored.
+   */
+  getClientRect(): Rect | null;
+
+  /**
+   * Handles when a cursor with a block or bubble enters this drag target.
+   *
+   * @param dragElement The block or bubble currently being dragged.
+   */
+  onDragEnter(dragElement: IDraggable): void;
+
+  /**
+   * Handles when a cursor with a block or bubble is dragged over this drag
+   * target.
+   *
+   * @param dragElement The block or bubble currently being dragged.
+   */
+  onDragOver(dragElement: IDraggable): void;
+
+  /**
+   * Handles when a cursor with a block or bubble exits this drag target.
+   *
+   * @param dragElement The block or bubble currently being dragged.
+   */
+  onDragExit(dragElement: IDraggable): void;
+
+  /**
+   * Handles when a block or bubble is dropped on this component.
+   * Should not handle delete here.
+   *
+   * @param dragElement The block or bubble currently being dragged.
+   */
+  onDrop(dragElement: IDraggable): void;
+
+  /**
+   * Returns whether the provided block or bubble should not be moved after
+   * being dropped on this component. If true, the element will return to where
+   * it was when the drag started.
+   *
+   * @param dragElement The block or bubble currently being dragged.
+   * @returns Whether the block or bubble provided should be returned to drag
+   *     start.
+   */
+  shouldPreventMove(dragElement: IDraggable): boolean;
+}

package/blockly-rc/core/interfaces/i_draggable.ts

@@ -0,0 +1,72 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {Coordinate} from '../utils/coordinate';
+
+/**
+ * Represents an object that can be dragged.
+ */
+export interface IDraggable extends IDragStrategy {
+  /**
+   * Returns the current location of the draggable in workspace
+   * coordinates.
+   *
+   * @returns Coordinate of current location on workspace.
+   */
+  getRelativeToSurfaceXY(): Coordinate;
+}
+
+export interface IDragStrategy {
+  /** Returns true iff the element is currently movable. */
+  isMovable(): boolean;
+
+  /**
+   * Handles any drag startup (e.g moving elements to the front of the
+   * workspace).
+   *
+   * @param e PointerEvent that started the drag; can be used to
+   *     check modifier keys, etc.  May be missing when dragging is
+   *     triggered programatically rather than by user.
+   */
+  startDrag(e?: PointerEvent): void;
+
+  /**
+   * Handles moving elements to the new location, and updating any
+   * visuals based on that (e.g connection previews for blocks).
+   *
+   * @param newLoc Workspace coordinate to which the draggable has
+   *     been dragged.
+   * @param e PointerEvent that continued the drag.  Can be
+   *     used to check modifier keys, etc.
+   */
+  drag(newLoc: Coordinate, e?: PointerEvent): void;
+
+  /**
+   * Handles any drag cleanup, including e.g. connecting or deleting
+   * blocks.
+   *
+   * @param newLoc Workspace coordinate at which the drag finished.
+   *     been dragged.
+   * @param e PointerEvent that finished the drag.  Can be
+   *     used to check modifier keys, etc.
+   */
+  endDrag(e?: PointerEvent): void;
+
+  /** Moves the draggable back to where it was at the start of the drag. */
+  revertDrag(): void;
+}
+
+/** Returns whether the given object is an IDraggable or not. */
+export function isDraggable(obj: any): obj is IDraggable {
+  return (
+    obj.getRelativeToSurfaceXY !== undefined &&
+    obj.isMovable !== undefined &&
+    obj.startDrag !== undefined &&
+    obj.drag !== undefined &&
+    obj.endDrag !== undefined &&
+    obj.revertDrag !== undefined
+  );
+}

package/blockly-rc/core/interfaces/i_dragger.ts

@@ -0,0 +1,35 @@
+/**
+ * @license
+ * Copyright 2024 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {Coordinate} from '../utils/coordinate';
+
+export interface IDragger {
+  /**
+   * Handles any drag startup.
+   *
+   * @param e PointerEvent that started the drag.
+   */
+  onDragStart(e: PointerEvent): void;
+
+  /**
+   * Handles dragging, including calculating where the element should
+   * actually be moved to.
+   *
+   * @param e PointerEvent that continued the drag.
+   * @param totalDelta The total distance, in pixels, that the mouse
+   *     has moved since the start of the drag.
+   */
+  onDrag(e: PointerEvent, totalDelta: Coordinate): void;
+
+  /**
+   * Handles any drag cleanup.
+   *
+   * @param e PointerEvent that finished the drag.
+   * @param totalDelta The total distance, in pixels, that the mouse
+   *     has moved since the start of the drag.
+   */
+  onDragEnd(e: PointerEvent, totalDelta: Coordinate): void;
+}

package/blockly-rc/core/interfaces/i_flyout.ts

@@ -0,0 +1,189 @@
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+// Former goog.module ID: Blockly.IFlyout
+
+import type {WorkspaceSvg} from '../workspace_svg.js';
+import type {BlockSvg} from '../block_svg.js';
+import type {Coordinate} from '../utils/coordinate.js';
+import type {FlyoutDefinition} from '../utils/toolbox.js';
+import type {Svg} from '../utils/svg.js';
+import type {IRegistrable} from './i_registrable.js';
+import {FlyoutItem} from '../flyout_base.js';
+
+/**
+ * Interface for a flyout.
+ */
+export interface IFlyout extends IRegistrable {
+  /** 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/blockly-rc/core/interfaces/i_flyout_inflater.ts

@@ -0,0 +1,41 @@
+import type {IBoundedElement} from './i_bounded_element.js';
+import type {WorkspaceSvg} from '../workspace_svg.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 flyoutWorkspace The flyout's workspace, where 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, flyoutWorkspace: WorkspaceSvg): IBoundedElement;
+
+  /**
+   * 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.
+   */
+  gapForElement(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.
+   */
+  disposeElement(element: IBoundedElement): void;
+}

package/blockly-rc/core/interfaces/i_has_bubble.ts

@@ -0,0 +1,20 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+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>;
+}
+
+/** Type guard that checks whether the given object is a IHasBubble. */
+export function hasBubble(obj: any): obj is IHasBubble {
+  return (
+    obj.bubbleIsVisible !== undefined && obj.setBubbleVisible !== undefined
+  );
+}

package/blockly-rc/core/interfaces/i_icon.ts

@@ -0,0 +1,114 @@
+/**
+ * @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';
+
+export interface IIcon {
+  /**
+   * @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 (
+    obj.getType !== undefined &&
+    obj.initView !== undefined &&
+    obj.dispose !== undefined &&
+    obj.getWeight !== undefined &&
+    obj.getSize !== undefined &&
+    obj.applyColour !== undefined &&
+    obj.hideForInsertionMarker !== undefined &&
+    obj.updateEditable !== undefined &&
+    obj.updateCollapsed !== undefined &&
+    obj.isShownWhenCollapsed !== undefined &&
+    obj.setOffsetInBlock !== undefined &&
+    obj.onLocationChange !== undefined &&
+    obj.onClick !== undefined
+  );
+}

package/blockly-rc/core/interfaces/i_keyboard_accessible.ts

@@ -0,0 +1,21 @@
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {KeyboardShortcut} from '../shortcut_registry.js';
+// Former goog.module ID: Blockly.IKeyboardAccessible
+
+/**
+ * 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;
+}