blockly 12.4.0 → 12.4.1

package/core/scrollbar.d.ts

@@ -0,0 +1,348 @@
+/**
+ * @license
+ * Copyright 2011 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Object representing a scrollbar.
+ *
+ * @class
+ */
+import * as browserEvents from './browser_events.js';
+import { Coordinate } from './utils/coordinate.js';
+import type { Metrics } from './utils/metrics.js';
+import type { WorkspaceSvg } from './workspace_svg.js';
+/**
+ * A note on units: most of the numbers that are in CSS pixels are scaled if the
+ * scrollbar is in a mutator.
+ */
+/**
+ * Class for a pure SVG scrollbar.
+ * This technique offers a scrollbar that is guaranteed to work, but may not
+ * look or behave like the system's scrollbars.
+ */
+export declare class Scrollbar {
+    private workspace;
+    private readonly horizontal;
+    /**
+     * Width of vertical scrollbar or height of horizontal scrollbar in CSS
+     * pixels. Scrollbars should be larger on touch devices.
+     */
+    static scrollbarThickness: number;
+    /**
+     * Default margin around the scrollbar (between the scrollbar and the edge of
+     * the viewport in pixels).
+     *
+     * @internal
+     */
+    static readonly DEFAULT_SCROLLBAR_MARGIN = 0.5;
+    /** Whether this scrollbar is part of a pair. */
+    private readonly pair;
+    /**
+     * Margin around the scrollbar (between the scrollbar and the edge of the
+     * viewport in pixels).
+     */
+    private readonly margin;
+    /** Previously recorded metrics from the workspace. */
+    private oldHostMetrics;
+    /**
+     * The ratio of handle position offset to workspace content displacement.
+     *
+     * @internal
+     */
+    ratio: number;
+    /**
+     * The location of the origin of the workspace that the scrollbar is in,
+     * measured in CSS pixels relative to the injection div origin.  This is
+     * usually (0, 0).  When the scrollbar is in a flyout it may have a
+     * different origin.
+     */
+    private origin;
+    /**
+     * The position of the mouse along this scrollbar's major axis at the start
+     * of the most recent drag. Units are CSS pixels, with (0, 0) at the top
+     * left of the browser window. For a horizontal scrollbar this is the x
+     * coordinate of the mouse down event; for a vertical scrollbar it's the y
+     * coordinate of the mouse down event.
+     */
+    private startDragMouse;
+    /**
+     * The length of the scrollbars (including the handle and the background),
+     * in CSS pixels. This is equivalent to scrollbar background length and the
+     * area within which the scrollbar handle can move.
+     */
+    private scrollbarLength;
+    /** The length of the scrollbar handle in CSS pixels. */
+    private handleLength;
+    /**
+     * The offset of the start of the handle from the scrollbar position, in CSS
+     * pixels.
+     */
+    private handlePosition;
+    private startDragHandle;
+    /** Whether the scrollbar handle is visible. */
+    private isHandleVisible;
+    /** Whether the workspace containing this scrollbar is visible. */
+    private containerVisible;
+    /** The transparent background behind the handle. */
+    private svgBackground;
+    /** The visible handle that can be dragged around. */
+    private svgHandle;
+    /** The outermost SVG element, which contains all parts of the scrollbar. */
+    private outerSvg;
+    /**
+     * The upper left corner of the scrollbar's SVG group in CSS pixels relative
+     * to the scrollbar's origin.  This is usually relative to the injection div
+     * origin.
+     *
+     * @internal
+     */
+    position: Coordinate;
+    /**
+     * The DOM attribute that controls the length of the scrollbar. Different
+     * for horizontal and vertical scrollbars.
+     */
+    lengthAttribute_: string;
+    /**
+     * The DOM attribute that controls the position of the scrollbar.
+     * Different for horizontal and vertical scrollbars.
+     */
+    positionAttribute_: string;
+    /** Handler for mouse down events on the background of the scrollbar. */
+    onMouseDownBarWrapper_: browserEvents.Data;
+    /** Handler for mouse down events on the handle of the scrollbar. */
+    onMouseDownHandleWrapper_: browserEvents.Data;
+    /** Handler for mouse move events during scrollbar drags. */
+    onMouseUpWrapper_: browserEvents.Data | null;
+    /** Handler for mouse up events to end scrollbar drags. */
+    onMouseMoveWrapper_: browserEvents.Data | null;
+    /**
+     * @param workspace Workspace to bind the scrollbar to.
+     * @param horizontal True if horizontal, false if vertical.
+     * @param opt_pair True if scrollbar is part of a horiz/vert pair.
+     * @param opt_class A class to be applied to this scrollbar.
+     * @param opt_margin The margin to apply to this scrollbar.
+     */
+    constructor(workspace: WorkspaceSvg, horizontal: boolean, opt_pair?: boolean, opt_class?: string, opt_margin?: number);
+    /**
+     * Set the size of the scrollbar DOM elements along the minor axis.
+     */
+    private setInitialThickness;
+    /**
+     * Dispose of this scrollbar. Remove DOM elements, event listeners,
+     * and theme subscriptions.
+     */
+    dispose(): void;
+    /**
+     * Constrain the handle's length within the minimum (0) and maximum
+     * (scrollbar background) values allowed for the scrollbar.
+     *
+     * @param value Value that is potentially out of bounds, in CSS pixels.
+     * @returns Constrained value, in CSS pixels.
+     */
+    private constrainHandleLength;
+    /**
+     * Set the length of the scrollbar's handle and change the SVG attribute
+     * accordingly.
+     *
+     * @param newLength The new scrollbar handle length in CSS pixels.
+     */
+    private setHandleLength;
+    /**
+     * Constrain the handle's position within the minimum (0) and maximum values
+     * allowed for the scrollbar.
+     *
+     * @param value Value that is potentially out of bounds, in CSS pixels.
+     * @returns Constrained value, in CSS pixels.
+     */
+    private constrainHandlePosition;
+    /**
+     * Set the offset of the scrollbar's handle from the scrollbar's position, and
+     * change the SVG attribute accordingly.
+     *
+     * @param newPosition The new scrollbar handle offset in CSS pixels.
+     */
+    setHandlePosition(newPosition: number): void;
+    /**
+     * Set the size of the scrollbar's background and change the SVG attribute
+     * accordingly.
+     *
+     * @param newSize The new scrollbar background length in CSS pixels.
+     */
+    private setScrollbarLength;
+    /**
+     * Set the position of the scrollbar's SVG group in CSS pixels relative to the
+     * scrollbar's origin.  This sets the scrollbar's location within the
+     * workspace.
+     *
+     * @param x The new x coordinate.
+     * @param y The new y coordinate.
+     * @internal
+     */
+    setPosition(x: number, y: number): void;
+    /**
+     * Recalculate the scrollbar's location and its length.
+     *
+     * @param opt_metrics A data structure of from the describing all the required
+     *     dimensions.  If not provided, it will be fetched from the host object.
+     */
+    resize(opt_metrics?: Metrics): void;
+    /**
+     * Returns whether the a resizeView is necessary by comparing the passed
+     * hostMetrics with cached old host metrics.
+     *
+     * @param hostMetrics A data structure describing all the required dimensions,
+     *     possibly fetched from the host object.
+     * @returns Whether a resizeView is necessary.
+     */
+    private requiresViewResize;
+    /**
+     * Recalculate a horizontal scrollbar's location and length.
+     *
+     * @param hostMetrics A data structure describing all the required dimensions,
+     *     possibly fetched from the host object.
+     */
+    private resizeHorizontal;
+    /**
+     * Recalculate a horizontal scrollbar's location on the screen and path
+     * length. This should be called when the layout or size of the window has
+     * changed.
+     *
+     * @param hostMetrics A data structure describing all the required dimensions,
+     *     possibly fetched from the host object.
+     */
+    resizeViewHorizontal(hostMetrics: Metrics): void;
+    /**
+     * Recalculate a horizontal scrollbar's location within its path and length.
+     * This should be called when the contents of the workspace have changed.
+     *
+     * @param hostMetrics A data structure describing all the required dimensions,
+     *     possibly fetched from the host object.
+     */
+    resizeContentHorizontal(hostMetrics: Metrics): void;
+    /**
+     * Recalculate a vertical scrollbar's location and length.
+     *
+     * @param hostMetrics A data structure describing all the required dimensions,
+     *     possibly fetched from the host object.
+     */
+    private resizeVertical;
+    /**
+     * Recalculate a vertical scrollbar's location on the screen and path length.
+     * This should be called when the layout or size of the window has changed.
+     *
+     * @param hostMetrics A data structure describing all the required dimensions,
+     *     possibly fetched from the host object.
+     */
+    resizeViewVertical(hostMetrics: Metrics): void;
+    /**
+     * Recalculate a vertical scrollbar's location within its path and length.
+     * This should be called when the contents of the workspace have changed.
+     *
+     * @param hostMetrics A data structure describing all the required dimensions,
+     *     possibly fetched from the host object.
+     */
+    resizeContentVertical(hostMetrics: Metrics): void;
+    /**
+     * Is the scrollbar visible.  Non-paired scrollbars disappear when they aren't
+     * needed.
+     *
+     * @returns True if visible.
+     */
+    isVisible(): boolean;
+    /**
+     * Set whether the scrollbar's container is visible and update
+     * display accordingly if visibility has changed.
+     *
+     * @param visible Whether the container is visible
+     */
+    setContainerVisible(visible: boolean): void;
+    /**
+     * Set whether the scrollbar is visible.
+     * Only applies to non-paired scrollbars.
+     *
+     * @param visible True if visible.
+     */
+    setVisible(visible: boolean): void;
+    /**
+     * Set whether the scrollbar is visible. Bypasses checking whether this
+     * scrollbar is part of a pair so that it can be toggled by the scrollbar
+     * pair.
+     *
+     * @param visible True if visible.
+     * @internal
+     */
+    setVisibleInternal(visible: boolean): void;
+    /**
+     * Update visibility of scrollbar based on whether it thinks it should
+     * be visible and whether its containing workspace is visible.
+     * We cannot rely on the containing workspace being hidden to hide us
+     * because it is not necessarily our parent in the DOM.
+     */
+    updateDisplay_(): void;
+    /**
+     * Scroll by one pageful.
+     * Called when scrollbar background is clicked.
+     *
+     * @param e Mouse down event.
+     */
+    private onMouseDownBar;
+    /**
+     * Start a dragging operation.
+     * Called when scrollbar handle is clicked.
+     *
+     * @param e Mouse down event.
+     */
+    private onMouseDownHandle;
+    /**
+     * Drag the scrollbar's handle.
+     *
+     * @param e Mouse move event.
+     */
+    private onMouseMoveHandle;
+    /** Release the scrollbar handle and reset state accordingly. */
+    private onMouseUpHandle;
+    /**
+     * Hide chaff and stop binding to mouseup and mousemove events.  Call this to
+     * wrap up loose ends associated with the scrollbar.
+     */
+    private cleanUp;
+    /**
+     * Helper to calculate the ratio of handle position to scrollbar view size.
+     *
+     * @returns Ratio.
+     * @internal
+     */
+    getRatio_(): number;
+    /**
+     * Updates workspace metrics based on new scroll ratio. Called when scrollbar
+     * is moved.
+     */
+    private updateMetrics;
+    /**
+     * Set the scrollbar handle's position.
+     *
+     * @param value The content displacement, relative to the view in pixels.
+     * @param updateMetrics Whether to update metrics on this set call.
+     *    Defaults to true.
+     */
+    set(value: number, updateMetrics?: boolean): void;
+    /**
+     * Record the origin of the workspace that the scrollbar is in, in pixels
+     * relative to the injection div origin. This is for times when the scrollbar
+     * is used in an object whose origin isn't the same as the main workspace
+     * (e.g. in a flyout.)
+     *
+     * @param x The x coordinate of the scrollbar's origin, in CSS pixels.
+     * @param y The y coordinate of the scrollbar's origin, in CSS pixels.
+     */
+    setOrigin(x: number, y: number): void;
+    /**
+     * @param first An object containing computed measurements of a workspace.
+     * @param second Another object containing computed measurements of a
+     *     workspace.
+     * @returns Whether the two sets of metrics are equivalent.
+     */
+    private static metricsAreEquivalent;
+}
+//# sourceMappingURL=scrollbar.d.ts.map

package/core/scrollbar_pair.d.ts

@@ -0,0 +1,121 @@
+/**
+ * @license
+ * Copyright 2011 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Scrollbar } from './scrollbar.js';
+import type { Metrics } from './utils/metrics.js';
+import type { WorkspaceSvg } from './workspace_svg.js';
+/**
+ * Class for a pair of scrollbars.  Horizontal and vertical.
+ */
+export declare class ScrollbarPair {
+    private workspace;
+    hScroll: Scrollbar | null;
+    vScroll: Scrollbar | null;
+    corner_: SVGRectElement | null;
+    /** Previously recorded metrics from the workspace. */
+    private oldHostMetrics;
+    /**
+     * @param workspace Workspace to bind the scrollbars to.
+     * @param addHorizontal Whether to add a horizontal scrollbar.
+     *    Defaults to true.
+     * @param addVertical Whether to add a vertical scrollbar. Defaults to true.
+     * @param opt_class A class to be applied to these scrollbars.
+     * @param opt_margin The margin to apply to these scrollbars.
+     */
+    constructor(workspace: WorkspaceSvg, addHorizontal?: boolean, addVertical?: boolean, opt_class?: string, opt_margin?: number);
+    /**
+     * Dispose of this pair of scrollbars.
+     * Unlink from all DOM elements to prevent memory leaks.
+     */
+    dispose(): void;
+    /**
+     * Recalculate both of the scrollbars' locations and lengths.
+     * Also reposition the corner rectangle.
+     */
+    resize(): void;
+    /**
+     * Returns whether scrolling horizontally is enabled.
+     *
+     * @returns True if horizontal scroll is enabled.
+     */
+    canScrollHorizontally(): boolean;
+    /**
+     * Returns whether scrolling vertically is enabled.
+     *
+     * @returns True if vertical scroll is enabled.
+     */
+    canScrollVertically(): boolean;
+    /**
+     * Record the origin of the workspace that the scrollbar is in, in pixels
+     * relative to the injection div origin. This is for times when the scrollbar
+     * is used in an object whose origin isn't the same as the main workspace
+     * (e.g. in a flyout.)
+     *
+     * @param x The x coordinate of the scrollbar's origin, in CSS pixels.
+     * @param y The y coordinate of the scrollbar's origin, in CSS pixels.
+     * @internal
+     */
+    setOrigin(x: number, y: number): void;
+    /**
+     * Set the handles of both scrollbars.
+     *
+     * @param x The horizontal content displacement, relative to the view in
+     *     pixels.
+     * @param y The vertical content displacement, relative to the view in pixels.
+     * @param updateMetrics Whether to update metrics on this set call.
+     *    Defaults to true.
+     */
+    set(x: number, y: number, updateMetrics: boolean): void;
+    /**
+     * Set the handle of the horizontal scrollbar to be at a certain position in
+     *    CSS pixels relative to its parents.
+     *
+     * @param x Horizontal scroll value.
+     */
+    setX(x: number): void;
+    /**
+     * Set the handle of the vertical scrollbar to be at a certain position in
+     *    CSS pixels relative to its parents.
+     *
+     * @param y Vertical scroll value.
+     */
+    setY(y: number): void;
+    /**
+     * Set whether this scrollbar's container is visible.
+     *
+     * @param visible Whether the container is visible.
+     */
+    setContainerVisible(visible: boolean): void;
+    /**
+     * If any of the scrollbars are visible. Non-paired scrollbars may disappear
+     * when they aren't needed.
+     *
+     * @returns True if visible.
+     */
+    isVisible(): boolean;
+    /**
+     * Sets the visibility of any existing scrollbars.
+     *
+     * @param visible True if visible.
+     */
+    setVisible(visible: boolean): void;
+    /**
+     * Recalculates the scrollbars' locations within their path and length.
+     * This should be called when the contents of the workspace have changed.
+     *
+     * @param hostMetrics A data structure describing all the required dimensions,
+     *     possibly fetched from the host object.
+     */
+    resizeContent(hostMetrics: Metrics): void;
+    /**
+     * Recalculates the scrollbars' locations on the screen and path length.
+     * This should be called when the layout or size of the window has changed.
+     *
+     * @param hostMetrics A data structure describing all the required dimensions,
+     *     possibly fetched from the host object.
+     */
+    resizeView(hostMetrics: Metrics): void;
+}
+//# sourceMappingURL=scrollbar_pair.d.ts.map

package/core/separator_flyout_inflater.d.ts

@@ -0,0 +1,57 @@
+/**
+ * @license
+ * Copyright 2024 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { FlyoutItem } from './flyout_item.js';
+import type { IFlyout } from './interfaces/i_flyout.js';
+import type { IFlyoutInflater } from './interfaces/i_flyout_inflater.js';
+/**
+ * @internal
+ */
+export declare const SEPARATOR_TYPE = "sep";
+/**
+ * Class responsible for creating separators for flyouts.
+ */
+export declare class SeparatorFlyoutInflater implements IFlyoutInflater {
+    /**
+     * Inflates a dummy flyout separator.
+     *
+     * The flyout automatically creates separators between every element with a
+     * size determined by calling gapForElement on the relevant inflater.
+     * Additionally, users can explicitly add separators in the flyout definition.
+     * When separators (implicitly or explicitly created) follow one another, the
+     * gap of the last one propagates backwards and flattens to one separator.
+     * This flattening is not additive; if there are initially separators of 2, 3,
+     * and 4 pixels, after normalization there will be one separator of 4 pixels.
+     * Therefore, this method returns a zero-width separator, which will be
+     * replaced by the one implicitly created by the flyout based on the value
+     * returned by gapForElement, which knows the default gap, unlike this method.
+     *
+     * @param _state A JSON representation of a flyout separator.
+     * @param flyout The flyout to create the separator for.
+     * @returns A newly created FlyoutSeparator.
+     */
+    load(_state: object, flyout: IFlyout): FlyoutItem;
+    /**
+     * Returns the size of the separator. See `load` for more details.
+     *
+     * @param state A JSON representation of a flyout separator.
+     * @param defaultGap The default spacing for flyout items.
+     * @returns The desired size of the separator.
+     */
+    gapForItem(state: object, defaultGap: number): number;
+    /**
+     * Disposes of the given separator. Intentional no-op.
+     *
+     * @param _item The flyout separator to dispose of.
+     */
+    disposeItem(_item: FlyoutItem): void;
+    /**
+     * Returns the type of items this inflater is responsible for creating.
+     *
+     * @returns An identifier for the type of items this inflater creates.
+     */
+    getType(): string;
+}
+//# sourceMappingURL=separator_flyout_inflater.d.ts.map

package/core/serialization/blocks.d.ts

@@ -0,0 +1,138 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { Block } from '../block.js';
+import type { Connection } from '../connection.js';
+import type { ISerializer } from '../interfaces/i_serializer.js';
+import type { Workspace } from '../workspace.js';
+/**
+ * Represents the state of a connection.
+ */
+export interface ConnectionState {
+    shadow?: State;
+    block?: State;
+}
+/**
+ * Represents the state of a given block.
+ */
+export interface State {
+    type: string;
+    id?: string;
+    x?: number;
+    y?: number;
+    collapsed?: boolean;
+    deletable?: boolean;
+    movable?: boolean;
+    editable?: boolean;
+    enabled?: boolean;
+    disabledReasons?: string[];
+    inline?: boolean;
+    data?: string;
+    extraState?: any;
+    icons?: {
+        [key: string]: any;
+    };
+    fields?: {
+        [key: string]: any;
+    };
+    inputs?: {
+        [key: string]: ConnectionState;
+    };
+    next?: ConnectionState;
+}
+/**
+ * Returns the state of the given block as a plain JavaScript object.
+ *
+ * @param block The block to serialize.
+ * @param param1 addCoordinates: If true, the coordinates of the block are added
+ *     to the serialized state. False by default. addinputBlocks: If true,
+ *     children of the block which are connected to inputs will be serialized.
+ *     True by default. addNextBlocks: If true, children of the block which are
+ *     connected to the block's next connection (if it exists) will be
+ *     serialized. True by default. doFullSerialization: If true, fields that
+ *     normally just save a reference to some external state (eg variables) will
+ *     instead serialize all of the info about that state. This supports
+ *     deserializing the block into a workspace where that state doesn't yet
+ *     exist. True by default.
+ * @returns The serialized state of the block, or null if the block could not be
+ *     serialied (eg it was an insertion marker).
+ */
+export declare function save(block: Block, { addCoordinates, addInputBlocks, addNextBlocks, doFullSerialization, saveIds, }?: {
+    addCoordinates?: boolean;
+    addInputBlocks?: boolean;
+    addNextBlocks?: boolean;
+    doFullSerialization?: boolean;
+    saveIds?: boolean;
+}): State | null;
+/**
+ * Loads the block represented by the given state into the given workspace.
+ *
+ * @param state The state of a block to deserialize into the workspace.
+ * @param workspace The workspace to add the block to.
+ * @param param1 recordUndo: If true, events triggered by this function will be
+ *     undo-able by the user. False by default.
+ * @returns The block that was just loaded.
+ */
+export declare function append(state: State, workspace: Workspace, { recordUndo }?: {
+    recordUndo?: boolean;
+}): Block;
+/**
+ * Loads the block represented by the given state into the given workspace.
+ * This is defined internally so that the extra parameters don't clutter our
+ * external API.
+ * But it is exported so that other places within Blockly can call it directly
+ * with the extra parameters.
+ *
+ * @param state The state of a block to deserialize into the workspace.
+ * @param workspace The workspace to add the block to.
+ * @param param1 parentConnection: If provided, the system will attempt to
+ *     connect the block to this connection after it is created. Undefined by
+ *     default. isShadow: If true, the block will be set to a shadow block after
+ *     it is created. False by default. recordUndo: If true, events triggered by
+ *     this function will be undo-able by the user. False by default.
+ * @returns The block that was just appended.
+ * @internal
+ */
+export declare function appendInternal(state: State, workspace: Workspace, { parentConnection, isShadow, recordUndo, }?: {
+    parentConnection?: Connection;
+    isShadow?: boolean;
+    recordUndo?: boolean;
+}): Block;
+/**
+ * Serializer for saving and loading block state.
+ */
+export declare class BlockSerializer implements ISerializer {
+    priority: number;
+    constructor();
+    /**
+     * Serializes the blocks of the given workspace.
+     *
+     * @param workspace The workspace to save the blocks of.
+     * @returns The state of the workspace's blocks, or null if there are no
+     *     blocks.
+     */
+    save(workspace: Workspace): {
+        languageVersion: number;
+        blocks: State[];
+    } | null;
+    /**
+     * Deserializes the blocks defined by the given state into the given
+     * workspace.
+     *
+     * @param state The state of the blocks to deserialize.
+     * @param workspace The workspace to deserialize into.
+     */
+    load(state: {
+        languageVersion: number;
+        blocks: State[];
+    }, workspace: Workspace): void;
+    /**
+     * Disposes of any blocks that exist on the workspace.
+     *
+     * @param workspace The workspace to clear the blocks of.
+     */
+    clear(workspace: Workspace): void;
+}
+//# sourceMappingURL=blocks.d.ts.map