blockly 12.4.0 → 12.5.0

package/core/flyout_metrics_manager.d.ts

@@ -0,0 +1,46 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Calculates and reports flyout workspace metrics.
+ *
+ * @class
+ */
+import type { IFlyout } from './interfaces/i_flyout.js';
+import { ContainerRegion, MetricsManager } from './metrics_manager.js';
+import type { WorkspaceSvg } from './workspace_svg.js';
+/**
+ * Calculates metrics for a flyout's workspace.
+ * The metrics are mainly used to size scrollbars for the flyout.
+ */
+export declare class FlyoutMetricsManager extends MetricsManager {
+    /** The flyout that owns the workspace to calculate metrics for. */
+    protected flyout_: IFlyout;
+    /**
+     * @param workspace The flyout's workspace.
+     * @param flyout The flyout.
+     */
+    constructor(workspace: WorkspaceSvg, flyout: IFlyout);
+    /**
+     * Gets the bounding box of the blocks on the flyout's workspace.
+     * This is in workspace coordinates.
+     *
+     * @returns The bounding box of the blocks on the workspace.
+     */
+    private getBoundingBox;
+    getContentMetrics(opt_getWorkspaceCoordinates?: boolean): {
+        height: number;
+        width: number;
+        top: number;
+        left: number;
+    };
+    getScrollMetrics(opt_getWorkspaceCoordinates?: boolean, opt_viewMetrics?: ContainerRegion, opt_contentMetrics?: ContainerRegion): {
+        height: number;
+        width: number;
+        top: number;
+        left: number;
+    };
+}
+//# sourceMappingURL=flyout_metrics_manager.d.ts.map

package/core/flyout_navigator.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { IFlyout } from './interfaces/i_flyout.js';
+import { Navigator } from './navigator.js';
+export declare class FlyoutNavigator extends Navigator {
+    constructor(flyout: IFlyout);
+}
+//# sourceMappingURL=flyout_navigator.d.ts.map

package/core/flyout_separator.d.ts

@@ -0,0 +1,64 @@
+/**
+ * @license
+ * Copyright 2024 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { IBoundedElement } from './interfaces/i_bounded_element.js';
+import type { IFocusableNode } from './interfaces/i_focusable_node.js';
+import type { IFocusableTree } from './interfaces/i_focusable_tree.js';
+import { Rect } from './utils/rect.js';
+/**
+ * Representation of a gap between elements in a flyout.
+ */
+export declare class FlyoutSeparator implements IBoundedElement, IFocusableNode {
+    private gap;
+    private axis;
+    private x;
+    private y;
+    /**
+     * Creates a new separator.
+     *
+     * @param gap The amount of space this separator should occupy.
+     * @param axis The axis along which this separator occupies space.
+     */
+    constructor(gap: number, axis: SeparatorAxis);
+    /**
+     * Returns the bounding box of this separator.
+     *
+     * @returns The bounding box of this separator.
+     */
+    getBoundingRectangle(): Rect;
+    /**
+     * Repositions this separator.
+     *
+     * @param dx The distance to move this separator on the X axis.
+     * @param dy The distance to move this separator on the Y axis.
+     * @param _reason The reason this move was initiated.
+     */
+    moveBy(dx: number, dy: number, _reason?: string[]): void;
+    /**
+     * Returns false to prevent this separator from being navigated to by the
+     * keyboard.
+     *
+     * @returns False.
+     */
+    isNavigable(): boolean;
+    /** See IFocusableNode.getFocusableElement. */
+    getFocusableElement(): HTMLElement | SVGElement;
+    /** See IFocusableNode.getFocusableTree. */
+    getFocusableTree(): IFocusableTree;
+    /** See IFocusableNode.onNodeFocus. */
+    onNodeFocus(): void;
+    /** See IFocusableNode.onNodeBlur. */
+    onNodeBlur(): void;
+    /** See IFocusableNode.canBeFocused. */
+    canBeFocused(): boolean;
+}
+/**
+ * Representation of an axis along which a separator occupies space.
+ */
+export declare const enum SeparatorAxis {
+    X = "x",
+    Y = "y"
+}
+//# sourceMappingURL=flyout_separator.d.ts.map

package/core/flyout_vertical.d.ts

@@ -0,0 +1,88 @@
+/**
+ * @license
+ * Copyright 2017 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Flyout } from './flyout_base.js';
+import type { FlyoutItem } from './flyout_item.js';
+import type { Options } from './options.js';
+import type { Coordinate } from './utils/coordinate.js';
+import { Rect } from './utils/rect.js';
+/**
+ * Class for a flyout.
+ */
+export declare class VerticalFlyout extends Flyout {
+    /** The name of the vertical flyout in the registry. */
+    static registryName: string;
+    /** @param workspaceOptions Dictionary of options for the workspace. */
+    constructor(workspaceOptions: Options);
+    /**
+     * Sets the translation of the flyout to match the scrollbars.
+     *
+     * @param xyRatio Contains a y property which is a float between 0 and 1
+     *     specifying the degree of scrolling and a similar x property.
+     */
+    protected setMetrics_(xyRatio: {
+        x: number;
+        y: number;
+    }): void;
+    /**
+     * 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;
+    /** Move the flyout to the edge of the workspace. */
+    position(): void;
+    /**
+     * Create and set the path for the visible boundaries of the flyout.
+     *
+     * @param width The width of the flyout, not including the rounded corners.
+     * @param height The height of the flyout, not including rounded corners.
+     */
+    private setBackgroundPath;
+    /** Scroll the flyout to the top. */
+    scrollToStart(): void;
+    /**
+     * Scroll the flyout.
+     *
+     * @param e Mouse wheel scroll event.
+     */
+    protected wheel_(e: WheelEvent): void;
+    /**
+     * Lay out the blocks in the flyout.
+     *
+     * @param contents The flyout items to lay out.
+     */
+    protected layout_(contents: FlyoutItem[]): 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;
+    /**
+     * 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;
+    /**
+     * Compute width of flyout.
+     * For RTL: Lay out the blocks and buttons to be right-aligned.
+     */
+    protected reflowInternal_(): void;
+}
+//# sourceMappingURL=flyout_vertical.d.ts.map

package/core/focus_manager.d.ts

@@ -0,0 +1,266 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { IFocusableNode } from './interfaces/i_focusable_node.js';
+import type { IFocusableTree } from './interfaces/i_focusable_tree.js';
+/**
+ * Type declaration for returning focus to FocusManager upon completing an
+ * ephemeral UI flow (such as a dialog).
+ *
+ * See FocusManager.takeEphemeralFocus for more details.
+ */
+export type ReturnEphemeralFocus = () => void;
+/**
+ * A per-page singleton that manages Blockly focus across one or more
+ * IFocusableTrees, and bidirectionally synchronizes this focus with the DOM.
+ *
+ * Callers that wish to explicitly change input focus for select Blockly
+ * components on the page should use the focus functions in this manager.
+ *
+ * The manager is responsible for handling focus events from the DOM (which may
+ * may arise from users clicking on page elements) and ensuring that
+ * corresponding IFocusableNodes are clearly marked as actively/passively
+ * highlighted in the same way that this would be represented with calls to
+ * focusNode().
+ */
+export declare class FocusManager {
+    /**
+     * The CSS class assigned to IFocusableNode elements that presently have
+     * active DOM and Blockly focus.
+     *
+     * This should never be used directly. Instead, rely on FocusManager to ensure
+     * nodes have active focus (either automatically through DOM focus or manually
+     * through the various focus* methods provided by this class).
+     *
+     * It's recommended to not query using this class name, either. Instead, use
+     * FocusableTreeTraverser or IFocusableTree's methods to find a specific node.
+     */
+    static readonly ACTIVE_FOCUS_NODE_CSS_CLASS_NAME = "blocklyActiveFocus";
+    /**
+     * The CSS class assigned to IFocusableNode elements that presently have
+     * passive focus (that is, they were the most recent node in their relative
+     * tree to have active focus--see ACTIVE_FOCUS_NODE_CSS_CLASS_NAME--and will
+     * receive active focus again if their surrounding tree is requested to become
+     * focused, i.e. using focusTree below).
+     *
+     * See ACTIVE_FOCUS_NODE_CSS_CLASS_NAME for caveats and limitations around
+     * using this constant directly (generally it never should need to be used).
+     */
+    static readonly PASSIVE_FOCUS_NODE_CSS_CLASS_NAME = "blocklyPassiveFocus";
+    private focusedNode;
+    private previouslyFocusedNode;
+    private registeredTrees;
+    private currentlyHoldsEphemeralFocus;
+    private lockFocusStateChanges;
+    private recentlyLostAllFocus;
+    private isUpdatingFocusedNode;
+    constructor(addGlobalEventListener: (type: string, listener: EventListener) => void);
+    /**
+     * Registers a new IFocusableTree for automatic focus management.
+     *
+     * If the tree currently has an element with DOM focus, it will not affect the
+     * internal state in this manager until the focus changes to a new,
+     * now-monitored element/node.
+     *
+     * This function throws if the provided tree is already currently registered
+     * in this manager. Use isRegistered to check in cases when it can't be
+     * certain whether the tree has been registered.
+     *
+     * The tree's registration can be customized to configure automatic tab stops.
+     * This specifically provides capability for the user to be able to tab
+     * navigate to the root of the tree but only when the tree doesn't hold active
+     * focus. If this functionality is disabled then the tree's root will
+     * automatically be made focusable (but not tabbable) when it is first focused
+     * in the same way as any other focusable node.
+     *
+     * @param tree The IFocusableTree to register.
+     * @param rootShouldBeAutoTabbable Whether the root of this tree should be
+     *     added as a top-level page tab stop when it doesn't hold active focus.
+     */
+    registerTree(tree: IFocusableTree, rootShouldBeAutoTabbable?: boolean): void;
+    /**
+     * Returns whether the specified tree has already been registered in this
+     * manager using registerTree and hasn't yet been unregistered using
+     * unregisterTree.
+     */
+    isRegistered(tree: IFocusableTree): boolean;
+    /**
+     * Returns the TreeRegistration for the specified tree, or null if the tree is
+     * not currently registered.
+     */
+    private lookUpRegistration;
+    /**
+     * Unregisters a IFocusableTree from automatic focus management.
+     *
+     * If the tree had a previous focused node, it will have its highlight
+     * removed. This function does NOT change DOM focus.
+     *
+     * This function throws if the provided tree is not currently registered in
+     * this manager.
+     *
+     * This function will reset the tree's root element tabindex if the tree was
+     * registered with automatic tab management.
+     */
+    unregisterTree(tree: IFocusableTree): void;
+    /**
+     * Returns the current IFocusableTree that has focus, or null if none
+     * currently do.
+     *
+     * Note also that if ephemeral focus is currently captured (e.g. using
+     * takeEphemeralFocus) then the returned tree here may not currently have DOM
+     * focus.
+     */
+    getFocusedTree(): IFocusableTree | null;
+    /**
+     * Returns the current IFocusableNode with focus (which is always tied to a
+     * focused IFocusableTree), or null if there isn't one.
+     *
+     * Note that this function will maintain parity with
+     * IFocusableTree.getFocusedNode(). That is, if a tree itself has focus but
+     * none of its non-root children do, this will return null but
+     * getFocusedTree() will not.
+     *
+     * Note also that if ephemeral focus is currently captured (e.g. using
+     * takeEphemeralFocus) then the returned node here may not currently have DOM
+     * focus.
+     */
+    getFocusedNode(): IFocusableNode | null;
+    /**
+     * Focuses the specific IFocusableTree. This either means restoring active
+     * focus to the tree's passively focused node, or focusing the tree's root
+     * node.
+     *
+     * Note that if the specified tree already has a focused node then this will
+     * not change any existing focus (unless that node has passive focus, then it
+     * will be restored to active focus).
+     *
+     * See getFocusedNode for details on how other nodes are affected.
+     *
+     * @param focusableTree The tree that should receive active
+     *     focus.
+     */
+    focusTree(focusableTree: IFocusableTree): void;
+    /**
+     * Focuses DOM input on the specified node, and marks it as actively focused.
+     *
+     * Any previously focused node will be updated to be passively highlighted (if
+     * it's in a different focusable tree) or blurred (if it's in the same one).
+     *
+     * **Important**: If the provided node is not able to be focused (e.g. its
+     * canBeFocused() method returns false), it will be ignored and any existing
+     * focus state will remain unchanged.
+     *
+     * Note that this may update the specified node's element's tabindex to ensure
+     * that it can be properly read out by screenreaders while focused.
+     *
+     * The focused node will not be automatically scrolled into view.
+     *
+     * @param focusableNode The node that should receive active focus.
+     */
+    focusNode(focusableNode: IFocusableNode): void;
+    /**
+     * Ephemerally captures focus for a specific element until the returned lambda
+     * is called. This is expected to be especially useful for ephemeral UI flows
+     * like dialogs.
+     *
+     * IMPORTANT: the returned lambda *must* be called, otherwise automatic focus
+     * will no longer work anywhere on the page. It is highly recommended to tie
+     * the lambda call to the closure of the corresponding UI so that if input is
+     * manually changed to an element outside of the ephemeral UI, the UI should
+     * close and automatic input restored. Note that this lambda must be called
+     * exactly once and that subsequent calls will throw an error.
+     *
+     * Note that the manager will continue to track DOM input signals even when
+     * ephemeral focus is active, but it won't actually change node state until
+     * the returned lambda is called. Additionally, only 1 ephemeral focus context
+     * can be active at any given time (attempting to activate more than one
+     * simultaneously will result in an error being thrown).
+     *
+     * This method does not scroll the ephemerally focused element into view.
+     */
+    takeEphemeralFocus(focusableElement: HTMLElement | SVGElement): ReturnEphemeralFocus;
+    /**
+     * @returns whether something is currently holding ephemeral focus
+     */
+    ephemeralFocusTaken(): boolean;
+    /**
+     * Ensures that the manager is currently allowing operations that change its
+     * internal focus state (such as via focusNode()).
+     *
+     * If the manager is currently not allowing state changes, an exception is
+     * thrown.
+     */
+    private ensureManagerIsUnlocked;
+    /**
+     * Updates the internally tracked focused node to the specified node, or null
+     * if focus is being lost. This also updates previous focus tracking.
+     *
+     * @param newFocusedNode The new node to set as focused.
+     */
+    private updateFocusedNode;
+    /**
+     * Defocuses the current actively focused node tracked by the manager, iff
+     * there's a node being tracked and the manager doesn't have ephemeral focus.
+     */
+    private defocusCurrentFocusedNode;
+    /**
+     * Marks the specified node as actively focused, also calling related
+     * lifecycle callback methods for both the node and its parent tree. This
+     * ensures that the node is properly styled to indicate its active focus.
+     *
+     * This does not change the manager's currently tracked node, nor does it
+     * change any other nodes.
+     *
+     * @param node The node to be actively focused.
+     * @param prevTree The tree of the previously actively focused node, or null
+     *     if there wasn't a previously actively focused node.
+     */
+    private activelyFocusNode;
+    /**
+     * Marks the specified node as passively focused, also calling related
+     * lifecycle callback methods for both the node and its parent tree. This
+     * ensures that the node is properly styled to indicate its passive focus.
+     *
+     * This does not change the manager's currently tracked node, nor does it
+     * change any other nodes.
+     *
+     * @param node The node to be passively focused.
+     * @param nextTree The tree of the node receiving active focus, or null if no
+     *     node will be actively focused.
+     */
+    private passivelyFocusNode;
+    /**
+     * Updates the node's styling to indicate that it should have an active focus
+     * indicator.
+     *
+     * @param node The node to be styled for active focus.
+     */
+    private setNodeToVisualActiveFocus;
+    /**
+     * Updates the node's styling to indicate that it should have a passive focus
+     * indicator.
+     *
+     * @param node The node to be styled for passive focus.
+     */
+    private setNodeToVisualPassiveFocus;
+    /**
+     * Removes any active/passive indicators for the specified node.
+     *
+     * @param node The node which should have neither passive nor active focus
+     *     indication.
+     */
+    private removeHighlight;
+    private static focusManager;
+    /**
+     * Returns the page-global FocusManager.
+     *
+     * The returned instance is guaranteed to not change across function calls,
+     * but may change across page loads.
+     */
+    static getFocusManager(): FocusManager;
+}
+/** Convenience function for FocusManager.getFocusManager. */
+export declare function getFocusManager(): FocusManager;
+//# sourceMappingURL=focus_manager.d.ts.map