@excalidraw/element 0.18.0-4a5c9e9 → 0.18.0-4ce38fb

package/dist/types/excalidraw/components/App.duplicate.d.ts

@@ -0,0 +1,101 @@
+import { duplicateElements } from "@excalidraw/element";
+import type { ExcalidrawElement, ExcalidrawTextElement } from "@excalidraw/element/types";
+import type { PointerDownState } from "../types";
+import type App from "./App";
+type Duplication = Pick<ReturnType<typeof duplicateElements>, "duplicatedElements" | "duplicateElementsMap" | "origElementsMap" | "origIdToDuplicateId" | "duplicateIdToOrigId">;
+/**
+ * Owns the duplication paths which involve the host (`props.onDuplicate`):
+ * duplicating elements into the scene (paste, library insert etc.), and
+ * duplicating the dragged selection (alt-drag). The duplicate action shares
+ * `runOnDuplicate()`.
+ */
+export declare class AppDuplicate {
+    private app;
+    private dependencies;
+    constructor(app: App, dependencies: {
+        /** pointers currently down */
+        getPointerCount: () => number;
+    });
+    /**
+     * Hands the duplication over to the host's `props.onDuplicate` (if any),
+     * and reconciles what it returned with the duplicates.
+     *
+     * @returns next elements, and the duplicates that weren't vetoed
+     */
+    runOnDuplicate: (duplication: Duplication, nextElements: ExcalidrawElement[], 
+    /** excludes the duplicated elements */
+    prevElements: readonly ExcalidrawElement[]) => {
+        elements: ExcalidrawElement[];
+        duplicatedElements: import("@excalidraw/element/types").NonDeletedExcalidrawElement[];
+    };
+    /**
+     * Runs `update` once what's pending is committed, capturing what it changes
+     * (if it returns `true`) as a separate undo step.
+     */
+    private afterCommit;
+    /**
+     * Advances the list markers of the duplicated texts (`1.` -> `2.`) once
+     * the duplication is committed, as a separate undo step, so that undo
+     * reverts the markers first.
+     */
+    advanceListMarkers: (duplicatedElements: readonly ExcalidrawElement[]) => void;
+    /**
+     * The text whose editing an alt-press on it ended, while the press is
+     * handed over to the canvas (see `handOverTextEditorPress()`).
+     */
+    handedOverTextId: ExcalidrawTextElement["id"] | null;
+    /**
+     * An alt-press on the text being edited, once it ended the editing, is
+     * handed over to the canvas, for the text to be alt-dragged (duplicated) as
+     * on the canvas — its duplicate is then edited on drop.
+     */
+    handOverTextEditorPress: (event: PointerEvent, textElementId: ExcalidrawTextElement["id"]) => void;
+    /**
+     * The pointer down a handed-over press is replayed as (see
+     * `handOverTextEditorPress()`) moves what was edited — the text, or its
+     * container — and nothing beneath the editor, which reaches past the text:
+     * no resize handle, nor an arrow's point, midpoint or label.
+     *
+     * @returns `false` if the pointer down isn't a handed-over press
+     */
+    hitEditedElement: (pointerDownState: PointerDownState) => boolean;
+    /**
+     * On alt-drag drop: the list markers advanced along with the drag go back,
+     * for the drag to be committed as is, and forth again once it is, as
+     * a separate undo step (before the browser gets to paint either).
+     *
+     * A duplicate is then edited (once the drop is committed): a single list
+     * item with text after its marker, with that text selected (`1. |foo|`),
+     * as it's likely to differ from the original's — or else the duplicate of
+     * the text the drag ended the editing of, with all of it selected.
+     */
+    commitDraggedDuplicates: ({ hit }: PointerDownState, { editText, }: {
+        /** `false` if the drag didn't end with a genuine pointerup */
+        editText: boolean;
+    }) => void;
+    private editDuplicatedText;
+    /**
+     * Duplicates elements so that they end up centered at the scene coords
+     * (and in the frame at that point, if any). Doesn't update the scene.
+     *
+     * @returns `null` if the host vetoed the duplication
+     */
+    duplicateAtSceneCoords: (elements: readonly ExcalidrawElement[], { x, y }: {
+        x: number;
+        y: number;
+    }, opts?: {
+        retainSeed?: boolean;
+        preserveFrameChildrenOrder?: boolean;
+    }) => {
+        nextElements: ExcalidrawElement[];
+        duplicatedElements: import("@excalidraw/element/types").NonDeletedExcalidrawElement[];
+    } | null;
+    /**
+     * Duplicates the selection being dragged: the originals go back to where
+     * the drag started, and the drag continues with the duplicates.
+     *
+     * If the host vetoes the duplication, the originals keep being dragged.
+     */
+    duplicateDraggedSelection: (pointerDownState: PointerDownState, event: PointerEvent) => void;
+}
+export {};

package/dist/types/excalidraw/components/App.flowchart.d.ts

@@ -0,0 +1,21 @@
+import type React from "react";
+import type App from "./App";
+import type { PendingExcalidrawElements } from "../types";
+/**
+ * Captures the App state management for the flowchart functionality.
+ */
+export declare class AppFlowchart {
+    private app;
+    private creator;
+    private navigator;
+    constructor(app: App);
+    get pendingNodes(): PendingExcalidrawElements | null;
+    get isCreatingChart(): boolean;
+    /** ends any in-progress flowchart creation/navigation session */
+    clear: () => void;
+    handleKeyEvent: (event: React.KeyboardEvent | KeyboardEvent) => boolean;
+    private resolveKeyboardEventToOperation;
+    private selectAndReveal;
+    private captureUpdate;
+    private static getLinkDirectionFromKey;
+}

package/dist/types/excalidraw/components/App.pan.d.ts

@@ -0,0 +1,62 @@
+import type React from "react";
+import type App from "./App";
+/**
+ * The drag-pan: a pointer drag that moves the canvas — the wheel or the
+ * secondary button, the main button while space is held or the hand tool
+ * is active, or any button in view mode. One session at a time, owning its
+ * window listeners and teardown; wheel input is gated on it (see
+ * `AppWheel`).
+ *
+ * A secondary-button session is a pan only once the pointer travels past
+ * the drag threshold; released before that, it is a right-click. The
+ * platform's `contextmenu` event opens the menu for a right-click where it
+ * follows the release (Windows), as it always has; where it comes with the
+ * press (macOS, Linux) it is swallowed — a drag cannot be told from a
+ * click yet — and the session opens the menu on release instead.
+ */
+export declare class AppPan {
+    private app;
+    private dependencies;
+    /** space held down turns a main-button drag into a pan */
+    private spaceHeld;
+    private active;
+    /** the secondary-button session, while one is active */
+    private secondary;
+    /** the platform fires `contextmenu` on mouseup (Windows) or on mousedown
+     * (macOS, Linux); the one belonging to a secondary-button session is not a
+     * new click, whichever side of the session it lands on */
+    private suppressNextContextMenu;
+    /** applies the pointer move the session is holding back for its next
+     * frame, if any */
+    private pendingMoveFlush;
+    private teardown;
+    constructor(app: App, dependencies: {
+        /** pointers currently down (a two-finger gesture is not a pan) */
+        getPointerCount: () => number;
+        /** a scrollbar being dragged (App's own drag, not a pan session) */
+        isDraggingScrollBar: () => boolean;
+    });
+    isActive: () => boolean;
+    isSpaceHeld: () => boolean;
+    setSpaceHeld: (held: boolean) => void;
+    /**
+     * Whether the pointer is navigating the viewport rather than acting on the
+     * scene — space held to pan, a pan in progress, a scrollbar drag, or the
+     * hand tool. Hover and cursor then belong to the navigation.
+     */
+    isNavigating: () => boolean;
+    /** applies the pointer move still waiting for its frame, if any */
+    flushMove: () => void;
+    /** ends the active session, if any — pointerup may never arrive (the user
+     * tabs away, a new pointerdown lands first) */
+    end: () => void;
+    /**
+     * Whether a `contextmenu` event belongs to a secondary-button session and
+     * must not open the menu: it came with the press (the session decides on
+     * release), or it follows a release that turned out to be a drag.
+     */
+    consumesContextMenuEvent: () => boolean;
+    /** starts a session for the pointerdown if it qualifies; returns whether
+     * it did */
+    start: (event: React.PointerEvent<HTMLElement> | MouseEvent) => boolean;
+}

package/dist/types/excalidraw/components/App.text.d.ts

@@ -0,0 +1,146 @@
+import { type Bounds, type StylesPanelMode } from "@excalidraw/common";
+import type { ArrowEndpoint } from "@excalidraw/element";
+import type { ExcalidrawElement, ExcalidrawTextContainer, ExcalidrawTextElement, NonDeleted, NonDeletedExcalidrawElement } from "@excalidraw/element/types";
+import { textWysiwyg } from "../wysiwyg/textWysiwyg";
+import type App from "./App";
+import type { AppState, Offsets, ViewportUIName } from "../types";
+type AppTextDependencies = {
+    getContainer: () => HTMLDivElement | null;
+    getStylesPanelMode: () => StylesPanelMode;
+};
+/**
+ * Texts, but for the text tool's pointer interaction (`AppTextTool`):
+ *
+ * - the editing session: what text to edit, or create, and where
+ *   (`startTextEditing`), and the editor's lifecycle (`handleTextWysiwyg`)
+ * - the part of the canvas a typed or pasted text is kept within
+ *   (`getTextViewportOffsets`, `getMaxTextWidth`)
+ * - the queries that find the text or container to edit at a position
+ * - the handle that turns a fixed-width text back into a growing one
+ *
+ * Every way into editing ends up here: Enter, double-click, pointerup on a
+ * selected text or container, the text tool, a drag-created text or sticky
+ * note, and a sticky note dropped from the toolbar.
+ */
+export declare class AppText {
+    private app;
+    private dependencies;
+    constructor(app: App, dependencies: AppTextDependencies);
+    textWysiwygSubmitHandler: ReturnType<typeof textWysiwyg> | null;
+    private getTextCreationGridPoint;
+    /**
+     * The side panels, besides the sidebar, that a typed or pasted text is
+     * kept clear of: the stats panel, and the full styles panel (desktop),
+     * which shows next to a text while it's edited, and once it's pasted and
+     * selected.
+     */
+    getTextSidePanels: () => ViewportUIName[];
+    /**
+     * The part of the canvas a typed or pasted text is kept within, as offsets
+     * from its edges (screen px): all of it but the sidebar and the side
+     * panels (see getTextSidePanels), less some room at each side. The stats
+     * panel covers the top of a side only, and counts only for a text beside
+     * it: one (given by its scene bounds) with rows within that room of it.
+     */
+    getTextViewportOffsets: (textBounds?: Bounds) => Required<Offsets>;
+    /**
+     * The widest a text may grow to as it's typed or pasted, in scene units:
+     * TEXT_MAX_WRAP_WIDTH, or less, so that a text never outgrows the part of
+     * the canvas it's kept within.
+     */
+    getMaxTextWidth: (offsets: Required<Offsets>) => number;
+    handleTextWysiwyg(element: NonDeleted<ExcalidrawTextElement>, { isExistingElement, initialCaretSceneCoords, initialSelection, }: {
+        isExistingElement?: boolean;
+        /**
+         * supply null if no caret positioning is desired, and instead
+         * text should be auto-selected
+         */
+        initialCaretSceneCoords?: {
+            x: number;
+            y: number;
+        } | null;
+        /** range of the text to select (takes precedence over the caret) */
+        initialSelection?: {
+            start: number;
+            end: number;
+        } | null;
+    }): void;
+    private getSelectedTextElement;
+    getSelectedTextEditingContainerAtPosition(hitElement: NonDeletedExcalidrawElement | null, sceneCoords: {
+        x: number;
+        y: number;
+    }): ExcalidrawTextContainer | null | undefined;
+    getTextElementAtPosition(x: number, y: number): NonDeleted<ExcalidrawTextElement> | null;
+    isHittingTextAutoResizeHandle: (selectedElements: NonDeleted<ExcalidrawElement>[], point: Readonly<{
+        x: number;
+        y: number;
+    }>) => boolean;
+    handleTextAutoResizeHandlePointerDown: (selectedElements: NonDeleted<ExcalidrawElement>[], point: Readonly<{
+        x: number;
+        y: number;
+    }>) => boolean;
+    /**
+     * The text container at a position — an arrow hit on its path, any other
+     * container hit anywhere in its bounds (frames are skipped so a container
+     * inside one can be hit, and a frame's children are only hit inside it,
+     * where they are drawn). Purely positional: the selection plays no part.
+     *
+     * Only what hides the rest ends the search — a filled element or an image
+     * (as for arrow binding), or an arrow — so containers below a transparent
+     * one stay in reach whatever their z-order. Of the containers found, the
+     * innermost one centered on the position wins, since that is where its
+     * label would go (an arrow counting as innermost: it is pointed at, not just
+     * enclosing); failing that, the top-most.
+     */
+    getTextBindableContainerAtPosition(x: number, y: number): NonDeleted<ExcalidrawTextContainer>;
+    /**
+     * Whether a text element's content is still being authored.
+     *
+     * Creating a text reverts the tool to selection during pointerdown, so the
+     * pointerup that follows looks like an ordinary canvas click and would
+     * capture the still-empty element as a history entry of its own. Undo would
+     * then rewind only the typing, restoring an invisible, zero-content element
+     * (and, for an endpoint label, leaving the arrow bound to it) rather than
+     * removing it. The editor's own submit captures the finished text instead,
+     * so the whole create-and-type lands in a single entry.
+     */
+    isEditingTextContent(): boolean;
+    startTextEditing: ({ sceneX, sceneY, insertAtParentCenter, container, autoEdit, initialCaretSceneCoords, initialSelection, arrowEndpoint, textElement, }: {
+        /** X position to insert text at */
+        sceneX: number;
+        /** Y position to insert text at */
+        sceneY: number;
+        /** whether to attempt to insert at element center if applicable */
+        insertAtParentCenter?: boolean;
+        container?: ExcalidrawTextContainer | null;
+        autoEdit?: boolean;
+        initialCaretSceneCoords?: {
+            x: number;
+            y: number;
+        };
+        /** range of an existing text to select (takes precedence over the caret) */
+        initialSelection?: {
+            start: number;
+            end: number;
+        };
+        /**
+         * creates the text as a label for this arrow endpoint: the binding then
+         * dictates the text's position and alignment, overriding (sceneX, sceneY)
+         */
+        arrowEndpoint?: ArrowEndpoint | null;
+        /**
+         * the text to edit: an element to edit exactly that one; `null` to always
+         * create, never adopting a selected text or one under the pointer;
+         * `undefined` to resolve it here — a single selected text, the label of a
+         * selected or passed arrow container, else the text at (sceneX, sceneY)
+         */
+        textElement?: NonDeleted<ExcalidrawTextElement> | null;
+    }) => void;
+    getTextWysiwygSnappedToCenterPosition(x: number, y: number, appState: AppState, container?: ExcalidrawTextContainer | null): {
+        viewportX: number;
+        viewportY: number;
+        elementCenterX: number;
+        elementCenterY: number;
+    } | undefined;
+}
+export {};

package/dist/types/excalidraw/components/App.textTool.d.ts

@@ -0,0 +1,140 @@
+import type { ArrowEndpoint } from "@excalidraw/element";
+import type { ExcalidrawTextContainer, ExcalidrawTextElement, NonDeleted } from "@excalidraw/element/types";
+import type React from "react";
+import type App from "./App";
+import type { PointerDownState } from "../types";
+type ScenePoint = {
+    x: number;
+    y: number;
+};
+/** the modifier state a target depends on — off a pointer or keyboard event */
+export type Modifiers = Pick<KeyboardEvent, "ctrlKey" | "metaKey">;
+/** What a text-tool click at a position does. */
+export type TextToolTarget = 
+/** binds a new text to a free arrow endpoint */
+{
+    type: "endpoint";
+    endpoint: ArrowEndpoint;
+}
+/** edits this text (a label included, at its derived position) */
+ | {
+    type: "text";
+    element: NonDeleted<ExcalidrawTextElement>;
+}
+/** binds a new label to this empty container (an arrow included) */
+ | {
+    type: "container";
+    element: NonDeleted<ExcalidrawTextContainer>;
+}
+/** creates free text at the pointer */
+ | {
+    type: "free";
+};
+/**
+ * The text tool's pointer interaction.
+ *
+ * Everything hangs off one question — what would a click at this position
+ * do (`getTargetAt`)? — answered once and used for the hover affordance
+ * (`appState.textToolHover`), the cursor and the pointerdown itself, so the
+ * affordance can never promise something the click won't deliver.
+ *
+ * A click on an empty container's center is armed on pointerdown and
+ * committed on pointerup as a bound label; dragging past the autowrap
+ * threshold first turns it into a free fixed-width text at the origin
+ * instead.
+ *
+ * Text editing itself (`app.text.startTextEditing`, see `AppText`) is
+ * shared with Enter, double-click and the other entry points.
+ */
+export declare class AppTextTool {
+    private app;
+    constructor(app: App);
+    /**
+     * A click on an empty container's center, armed on pointerdown and decided
+     * on the pointer's way out: a click binds a label, a drag creates free
+     * text instead. Deferring is what keeps the drag from first binding to
+     * (and provisionally enlarging) the container.
+     */
+    private pending;
+    /**
+     * The modifiers the hover was last resolved with — what a refresh without
+     * an event of its own (the viewport moving under a still pointer) uses.
+     */
+    private lastModifiers;
+    /**
+     * What a click at this position would do, in the order the click resolves
+     * it: a free arrow endpoint (the smaller, more deliberate target; z-aware,
+     * and off while ctrl/cmd disables binding) → the text under the pointer,
+     * which the click edits → an empty container near its center, which gets
+     * a label unless ctrl/cmd opts out → free text at the pointer.
+     *
+     * Ctrl/cmd is "no binding" throughout the tool, as elsewhere in the
+     * editor. For the container it is read off the event rather than the
+     * arrow-binding preference: a label is not an arrow binding.
+     */
+    getTargetAt: (scenePointer: ScenePoint, modifiers: Modifiers) => TextToolTarget;
+    /**
+     * Keeps `appState.textToolHover` — the affordance for what a click would
+     * do — in sync with the pointer, and returns the target (for the cursor).
+     * Suppressed while something else owns the interaction: a text being
+     * edited or drag-sized, a multi-point element, a box selection, a drag of
+     * the selection, or the pointer over a scrollbar.
+     */
+    updateHover: (scenePointer: ScenePoint, modifiers: Modifiers, isOverScrollBar?: boolean) => TextToolTarget | null;
+    /**
+     * Re-resolves the hover — and the cursor that goes with it — where the
+     * pointer last was, for what changes a click's outcome without the pointer
+     * moving: the ctrl/cmd toggle (pass its event), or the viewport scrolling
+     * or zooming under the pointer (no event; the last modifiers stand). The
+     * scene position is re-derived from the pointer's viewport position, so a
+     * moved viewport resolves what is under the pointer now.
+     *
+     * Nothing to refresh with another tool or without a hovering pointer — a
+     * finger never hovers (its last move is where it lifted), and the
+     * affordance a press armed is cleared when the press resolves or is
+     * canceled. The cursor is left to viewport navigation (space/wheel
+     * panning, a scrollbar drag, the hand tool), as on pointermove.
+     */
+    refresh: (modifiers?: Modifiers) => void;
+    /**
+     * Drops a pending center click without acting on it — the tool was left,
+     * the browser took the pointer (pointercancel), or a second finger turned
+     * the press into a pinch/pan — so no pointerup of ours will decide it. The
+     * outline it armed goes with it: while pending, the hover is that click's.
+     */
+    cancel: () => void;
+    clearHover: () => void;
+    private setHover;
+    /**
+     * The cursor for what a click would do: a pointer over the arrow anchors
+     * text would attach to, a text cursor over text the click would edit, the
+     * tool's crosshair otherwise — also while the affordance is suppressed
+     * (editing, drag-sizing), where a click has nothing to point at.
+     */
+    cursorFor: (target: TextToolTarget | null) => string;
+    handlePointerDown: (event: React.PointerEvent<HTMLElement>, pointerDownState: PointerDownState) => void;
+    /**
+     * The pointer-move half of a pending center click. Once the pointer has
+     * moved past the autowrap threshold the click is a drag: free text is
+     * created at the origin and sized by the drag from here on. Horizontal
+     * only (a text is only ever sized that way) and in screen space, and
+     * deliberately wider than the generic drag threshold so a jittery click
+     * still binds. Returns whether a pending click owned the move.
+     */
+    handlePointerMove: (event: PointerEvent, pointerDownState: PointerDownState) => boolean;
+    /**
+     * The pointer-up half: a genuine pointerup binds the label. The
+     * missing-pointerup cleanup replays this with the pointerdown event (a
+     * second finger landing mid-press), and a tool switch orphans the click —
+     * both discard it instead.
+     */
+    handlePointerUp: (event: PointerEvent, pointerDownState: PointerDownState) => void;
+    private isDrag;
+    private resolvePending;
+    /**
+     * The click has been acted on: drop the affordance, revert the tool unless
+     * it is locked, restore the cursor.
+     */
+    private finish;
+}
+export {};

package/dist/types/excalidraw/components/App.toolDrag.d.ts

@@ -0,0 +1,63 @@
+import type { ExcalidrawNonSelectionElement, NonDeleted } from "@excalidraw/element/types";
+import type App from "./App";
+import type { ToolType } from "../types";
+type ScenePoint = {
+    x: number;
+    y: number;
+};
+/** what a drag places: any element the new-element canvas can preview */
+type DraggedElement = NonDeleted<ExcalidrawNonSelectionElement>;
+/**
+ * A tool the user can drag out of the toolbar to drop a default-sized element
+ * where the pointer is released.
+ */
+type DraggableTool = {
+    /** the element the drop creates, centered on the pointer */
+    createElement: (app: App, center: ScenePoint) => DraggedElement;
+    /** what the tool does once its element is on the canvas (e.g. start editing) */
+    onDrop?: (app: App, element: DraggedElement) => void;
+};
+/**
+ * The tools that can be dragged out of the toolbar. Add an entry to make a
+ * tool's button draggable — the gesture, preview and drop are shared.
+ */
+export declare const DRAGGABLE_TOOLS: Partial<Record<ToolType, DraggableTool>>;
+/** CSS opacity of the preview canvas while dragging */
+export declare const TOOL_DRAG_PREVIEW_OPACITY = 0.5;
+/**
+ * Dragging a tool out of the toolbar. The preview element exists only here
+ * until the drop — it is not in the scene, the store or the history, so
+ * collaborators never see it and an aborted drag leaves nothing behind. It
+ * is painted by the `NewElementCanvas`, drawn exactly as it will land, with
+ * the canvas itself made translucent.
+ *
+ * The button arms on pointerdown; the drag starts once the pointer has
+ * moved `DRAGGING_THRESHOLD`, so a plain click still selects the tool. The
+ * gesture lives on the owner window (the pointer leaves the button at once),
+ * like the other pointer gestures in `App`.
+ */
+export declare class AppToolDrag {
+    private app;
+    constructor(app: App);
+    /** the element under the pointer while dragging, `null` otherwise */
+    preview: DraggedElement | null;
+    private armed;
+    private tool;
+    private type;
+    static isDraggable: (type: ToolType) => boolean;
+    isDragging: () => boolean;
+    /**
+     * Arm a drag from a tool button's pointerdown. Returns whether the tool is
+     * draggable (the caller lets a non-draggable press fall through).
+     */
+    handleButtonPointerDown: (type: ToolType, event: PointerEvent) => boolean;
+    private onPointerMove;
+    private onPointerUp;
+    private onKeyDown;
+    /** drop the gesture without a trace */
+    cancel: () => void;
+    private isOverCanvas;
+    private addListeners;
+    private removeListeners;
+}
+export {};

package/dist/types/excalidraw/components/App.viewport.d.ts

@@ -0,0 +1,113 @@
+import { type StylesPanelMode } from "@excalidraw/common";
+import type { NonDeletedSceneElementsMap } from "@excalidraw/element/types";
+import { type SetViewportOptions } from "../viewport";
+import type { AppProps, AppState, Offsets, ScrollConstraints, ViewportOffsets, ViewportOffsetsOptions, ViewportUIName } from "../types";
+import type App from "./App";
+export declare const SCROLL_TO_CONTENT_ANIMATION_KEY = "animateScrollToContent";
+export declare const SCROLL_CONSTRAINTS_SNAP_BACK_ANIMATION_KEY = "animateScrollConstraintsSnapBack";
+/** single source of truth for the `--right-sidebar-width` CSS variable */
+export declare const RIGHT_SIDEBAR_WIDTH = 302;
+type Viewport = Pick<AppState, "scrollX" | "scrollY" | "zoom">;
+type AppViewportDependencies = {
+    getContainer: () => HTMLDivElement | null;
+    getStylesPanelMode: () => StylesPanelMode;
+    isGestureActive: () => boolean;
+};
+/**
+ * Rubberband snap-back: animates the viewport from its current (possibly
+ * overscrolled) position back inside the lock box via the shared
+ * AnimationController. No-op when already within the hard bounds (or when
+ * there is no lock).
+ */
+export declare const snapBackToConstraints: (state: Pick<AppState, "scrollX" | "scrollY" | "zoom" | "width" | "height" | "scrollConstraints">, onFrame: (updater: (state: Pick<AppState, "scrollX" | "scrollY" | "zoom" | "width" | "height" | "scrollConstraints">) => Viewport | null) => void, duration?: number) => void;
+/**
+ * Owns viewport state transitions and App-bound viewport concerns. Pure
+ * viewport geometry remains in `viewport.ts` so actions and public helpers can
+ * calculate state without an App instance.
+ */
+export declare class AppViewport {
+    private app;
+    private dependencies;
+    lastPosition: {
+        x: number;
+        y: number;
+    };
+    private activeTransition;
+    private uiLastMeasured;
+    constructor(app: App, dependencies: AppViewportDependencies);
+    get isAnimating(): boolean;
+    /** Whether a programmatic transition into a locked viewport currently owns
+     * user pan/zoom input. */
+    get isLockedTransitionPending(): boolean;
+    invalidateUIOffset: (name: ViewportUIName) => void;
+    /**
+     * The side a rendered side UI (`data-viewport-ui="side"`) docks to, and
+     * how far it reaches into the canvas from it, in screen px.
+     */
+    private measureSide;
+    /**
+     * The side a named surface docks to while it's hidden, and how far it
+     * reaches into the canvas from it: as last measured, else approximately.
+     */
+    private getReservedSide;
+    private querySideUI;
+    /**
+     * Where a rendered side UI is, relative to the editor's container, in
+     * screen px; null when it isn't rendered.
+     */
+    getSideUIRect: (name: ViewportUIName) => {
+        left: number;
+        right: number;
+        top: number;
+        bottom: number;
+    } | null;
+    /**
+     * How far the named side UIs reach into the canvas, in screen px, from
+     * the left and the right: the part of the canvas they cover. Zero at a
+     * side none of them is rendered at — e.g. with the sidebar closed, or on
+     * phones, where it's an overlay that doesn't count as viewport UI — unless
+     * a hidden one is reserved (see `ViewportOffsetsOptions.reserve`).
+     */
+    getSideInsets: (names: readonly ViewportUIName[], opts?: Pick<ViewportOffsetsOptions, "reserve">) => {
+        left: number;
+        right: number;
+    };
+    /** How far the sidebar reaches into the canvas (see `getSideInsets`). */
+    getSidebarInsets: () => {
+        left: number;
+        right: number;
+    };
+    /**
+     * Resolves user-supplied viewport offsets into concrete per-side pixel
+     * values. Static sides take precedence over UI-derived sides.
+     */
+    resolveOffsets: (offsets: ViewportOffsets | undefined) => Offsets | undefined;
+    /**
+     * Measures the currently rendered editor UI and returns the usable viewport
+     * offsets, including optional padding and reserved hidden surfaces.
+     */
+    getOffsets: (opts?: ViewportOffsetsOptions) => Offsets;
+    /** Resolves the host-supplied initial viewport against restored scene data. */
+    resolveInitialViewport: (opts: Omit<SetViewportOptions, "animation">, elementsMap: NonDeletedSceneElementsMap, appState: AppState) => (Viewport & {
+        scrollConstraints: ScrollConstraints | null;
+    }) | null;
+    /**
+     * Navigates to a target and optionally installs scroll/zoom constraints.
+     * Navigating stops following a collaborator, as a user's pan does.
+     */
+    setViewport: (opts: SetViewportOptions | null) => void;
+    /** Use when changing scrollX/scrollY/zoom based on user interaction. */
+    translate: <K extends keyof AppState>(state: AppState | Pick<AppState, K> | null | ((prevState: Readonly<AppState>, props: Readonly<AppProps>) => AppState | Pick<AppState, K> | null), opts?: {
+        zoomPreConstrained?: boolean;
+        preserveScrollConstraintsSnapBack?: boolean;
+    }) => boolean;
+    /** Clamps the viewport into the active scroll constraints. */
+    constrain: (overscroll?: number) => void;
+    /** Releases a held rubberband overscroll. */
+    releaseOverscroll: () => void;
+    private snapBack;
+    private snapBackDebounced;
+    private cancelTransition;
+    destroy: () => void;
+}
+export {};

package/dist/types/excalidraw/components/App.wheel.d.ts

@@ -0,0 +1,26 @@
+import type App from "./App";
+/**
+ * Wheel input over the editor: pans the canvas, or zooms it around the
+ * pointer (`viewport.lastPosition`) — on ctrl/cmd+wheel (which is also how
+ * a trackpad pinch is delivered), while the wheel button itself is held
+ * down, or on a plain wheel when the input device is a mouse
+ * (`appState.inputDevice`). Shift+wheel pans horizontally;
+ * ctrl/cmd+shift+wheel pans vertically.
+ */
+export declare class AppWheel {
+    private app;
+    constructor(app: App);
+    /** the editor surfaces whose wheel input the editor consumes; everywhere
+     * else (menus, sidebars, …) the DOM keeps scrolling. The frame-name labels
+     * are DOM, but sit inside the container this listener is attached to */
+    private isOverEditorSurface;
+    handle: (event: WheelEvent) => void;
+    /**
+     * Prevents the browser's own zoom over the non-interactive editor while
+     * letting regular scroll through (trackpad pinch is delivered as
+     * ctrl+wheel).
+     */
+    preventBrowserZoom: (event: WheelEvent) => void;
+    /** zooms around the pointer by a wheel delta (positive = zoom out) */
+    private zoomBy;
+}