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

package/dist/types/element/src/newElement.d.ts

@@ -1,9 +1,29 @@
 import type { MarkOptional } from "@excalidraw/common/utility-types";
-import type { ExcalidrawImageElement, ExcalidrawTextElement, ExcalidrawLinearElement, ExcalidrawGenericElement, NonDeleted, TextAlign, VerticalAlign, Arrowhead, ExcalidrawFreeDrawElement, FontFamilyValues, ExcalidrawTextContainer, ExcalidrawFrameElement, ExcalidrawEmbeddableElement, ExcalidrawMagicFrameElement, ExcalidrawIframeElement, ElementsMap, ExcalidrawArrowElement, ExcalidrawElbowArrowElement, ExcalidrawLineElement } from "./types";
-export type ElementConstructorOpts = MarkOptional<Omit<ExcalidrawGenericElement, "id" | "type" | "isDeleted" | "updated">, "width" | "height" | "angle" | "groupIds" | "frameId" | "index" | "boundElements" | "seed" | "version" | "versionNonce" | "link" | "strokeStyle" | "fillStyle" | "strokeColor" | "backgroundColor" | "roughness" | "strokeWidth" | "roundness" | "locked" | "opacity" | "customData">;
+import type { ExcalidrawImageElement, ExcalidrawTextElement, ExcalidrawLinearElement, ExcalidrawGenericElement, NonDeleted, TextAlign, VerticalAlign, Arrowhead, ExcalidrawFreeDrawElement, FontFamilyValues, ExcalidrawTextContainer, ExcalidrawFrameElement, ExcalidrawEmbeddableElement, ExcalidrawMagicFrameElement, ExcalidrawIframeElement, ElementsMap, ExcalidrawArrowElement, ExcalidrawElbowArrowElement, ExcalidrawLineElement, ExcalidrawStickyNoteElement } from "./types";
+export type ElementConstructorOpts = MarkOptional<Omit<ExcalidrawGenericElement, "id" | "type" | "isDeleted" | "updated">, "width" | "height" | "angle" | "groupIds" | "frameId" | "index" | "boundElements" | "seed" | "version" | "versionNonce" | "link" | "strokeStyle" | "fillStyle" | "strokeColor" | "backgroundColor" | "roughness" | "strokeWidth" | "roundness" | "locked" | "opacity" | "customData" | "created">;
 export declare const newElement: (opts: {
     type: ExcalidrawGenericElement["type"];
 } & ElementConstructorOpts) => NonDeleted<ExcalidrawGenericElement>;
+/**
+ * Style invariants of a sticky note: never-transparent colors, solid fill.
+ * Applied by the constructor and by every normalization pass. Returns the
+ * same object when nothing needs fixing.
+ */
+export declare const normalizeStickyNoteStyle: <T extends ExcalidrawStickyNoteElement>(element: T) => T;
+/**
+ * Geometry invariants of a *finalized* sticky note: minimum size and
+ * `baseHeight ≤ height`. Deliberately not part of the constructor — a
+ * pointer-down draft starts at 0×0 like every other tool and is previewed at
+ * its true dragged size; pointer-up, restore, the skeleton path and the
+ * action post-passes enforce this.
+ */
+export declare const normalizeStickyNoteGeometry: <T extends ExcalidrawStickyNoteElement>(element: T) => T;
+/** all sticky note invariants (style + finalized geometry) */
+export declare const normalizeStickyNote: <T extends ExcalidrawStickyNoteElement>(element: T) => T;
+export declare const newStickyNoteElement: (opts: {
+    type: "stickynote";
+    baseHeight?: number;
+} & ElementConstructorOpts) => NonDeleted<ExcalidrawStickyNoteElement>;
 export declare const newEmbeddableElement: (opts: {
     type: "embeddable";
 } & ElementConstructorOpts) => NonDeleted<ExcalidrawEmbeddableElement>;
@@ -16,6 +36,19 @@ export declare const newFrameElement: (opts: {
 export declare const newMagicFrameElement: (opts: {
     name?: string;
 } & ElementConstructorOpts) => NonDeleted<ExcalidrawMagicFrameElement>;
+/**
+ * The point of the text box its alignment pins, as ratios of width/height.
+ *
+ * This is the point that stays put as the text grows — see the sides passed to
+ * `adjustXYWithRotation` in `getAdjustedDimensions`.
+ */
+export declare const getTextAnchorRatios: (opts: {
+    textAlign: ExcalidrawTextElement["textAlign"];
+    verticalAlign: ExcalidrawTextElement["verticalAlign"];
+}) => {
+    x: number;
+    y: number;
+};
 export declare const newTextElement: (opts: {
     text: string;
     originalText?: string;
@@ -26,8 +59,24 @@ export declare const newTextElement: (opts: {
     containerId?: ExcalidrawTextContainer["id"] | null;
     lineHeight?: ExcalidrawTextElement["lineHeight"];
     autoResize?: ExcalidrawTextElement["autoResize"];
+    labelPosition?: ExcalidrawTextElement["labelPosition"];
+    baseFontSize?: ExcalidrawTextElement["baseFontSize"];
 } & ElementConstructorOpts) => NonDeleted<ExcalidrawTextElement>;
-export declare const refreshTextDimensions: (textElement: ExcalidrawTextElement, container: ExcalidrawTextContainer | null, elementsMap: ElementsMap, text?: string) => {
+export declare const refreshTextDimensions: (textElement: ExcalidrawTextElement, container: ExcalidrawTextContainer | null, elementsMap: ElementsMap, text?: string, 
+/**
+ * For a free text that grows with its content (`autoResize`): the widest
+ * it may grow to. Crossing it, the text stops growing and wraps at this
+ * width from then on (`autoResize: false`), anchored as its growth was. A
+ * text that is already wider keeps growing.
+ */
+maxWidth?: number) => {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    text: string;
+    autoResize: boolean;
+} | {
     x: number;
     y: number;
     width: number;
@@ -38,6 +87,7 @@ export declare const newFreeDrawElement: (opts: {
     type: "freedraw";
     points?: ExcalidrawFreeDrawElement["points"];
     simulatePressure: boolean;
+    strokeOptions?: ExcalidrawFreeDrawElement["strokeOptions"];
     pressures?: ExcalidrawFreeDrawElement["pressures"];
 } & ElementConstructorOpts) => NonDeleted<ExcalidrawFreeDrawElement>;
 export declare const newLinearElement: (opts: {

package/dist/types/element/src/renderElement.d.ts

@@ -1,25 +1,39 @@
 import { type GlobalPoint } from "@excalidraw/math";
-import type { AppState, StaticCanvasAppState, InteractiveCanvasAppState, ElementsPendingErasure, PendingExcalidrawElements } from "@excalidraw/excalidraw/types";
+import type { AppState, StaticCanvasAppState, InteractiveCanvasAppState, ElementRenderOverrides } from "@excalidraw/excalidraw/types";
 import type { StaticCanvasRenderConfig, RenderableElementsMap, InteractiveCanvasRenderConfig } from "@excalidraw/excalidraw/scene/types";
-import type { ExcalidrawElement, ExcalidrawTextElement, NonDeletedExcalidrawElement, ExcalidrawFreeDrawElement, ExcalidrawImageElement, ExcalidrawFrameLikeElement, NonDeletedSceneElementsMap, ElementsMap } from "./types";
+import type { ExcalidrawElement, ExcalidrawTextElement, NonDeletedExcalidrawElement, ExcalidrawFreeDrawElement, ExcalidrawImageElement, NonDeletedSceneElementsMap, ElementsMap } from "./types";
 import type { RoughCanvas } from "roughjs/bin/canvas";
-export declare const getRenderOpacity: (element: ExcalidrawElement, containingFrame: ExcalidrawFrameLikeElement | null, elementsPendingErasure: ElementsPendingErasure, pendingNodes: Readonly<PendingExcalidrawElements> | null, globalAlpha?: number) => number;
+export type RenderPositionOffset = Readonly<{
+    x: number;
+    y: number;
+}>;
+/** Bound labels follow their container; a label's own offset is ignored. */
+export declare const getElementRenderOffset: (element: ExcalidrawElement, elementsMap: ElementsMap, overrides: ElementRenderOverrides | undefined) => RenderPositionOffset | undefined;
+export declare const getRenderElementWithPositionOverride: <TElement extends ExcalidrawElement>(element: TElement, positionOffset: RenderPositionOffset) => TElement;
+export type ElementRenderState = Readonly<{
+    /** Alpha including frame opacity and pending erasure; selection dimming is separate. */
+    opacity: number;
+    offset: RenderPositionOffset;
+}>;
+/** Resolve visual state at the drawing boundary, preserving document cache keys. */
+export declare const resolveElementRenderState: (element: ExcalidrawElement, elementsMap: ElementsMap, renderConfig: Pick<StaticCanvasRenderConfig, "elementRenderOverrides" | "elementsPendingErasure" | "pendingFlowchartNodes">, allElementsMap?: ElementsMap) => ElementRenderState;
 export interface ExcalidrawElementWithCanvas {
     element: ExcalidrawElement | ExcalidrawTextElement;
     canvas: HTMLCanvasElement;
     theme: AppState["theme"];
     scale: number;
-    angle: number;
     zoomValue: AppState["zoom"]["value"];
     canvasOffsetX: number;
     canvasOffsetY: number;
-    boundTextElementVersion: number | null;
     imageCrop: ExcalidrawImageElement["crop"] | null;
     containingFrameOpacity: number;
-    boundTextCanvas: HTMLCanvasElement;
 }
 export declare const DEFAULT_LINK_SIZE = 14;
 export declare const elementWithCanvasCache: WeakMap<ExcalidrawElement, ExcalidrawElementWithCanvas>;
 export declare const renderSelectionElement: (element: NonDeletedExcalidrawElement, context: CanvasRenderingContext2D, appState: InteractiveCanvasAppState, selectionColor: InteractiveCanvasRenderConfig["selectionColor"]) => void;
-export declare const renderElement: (element: NonDeletedExcalidrawElement, elementsMap: RenderableElementsMap, allElementsMap: NonDeletedSceneElementsMap, rc: RoughCanvas, context: CanvasRenderingContext2D, renderConfig: StaticCanvasRenderConfig, appState: StaticCanvasAppState | InteractiveCanvasAppState) => void;
+export declare const renderElement: (element: NonDeletedExcalidrawElement, elementsMap: RenderableElementsMap, allElementsMap: NonDeletedSceneElementsMap, rc: RoughCanvas, context: CanvasRenderingContext2D, renderConfig: StaticCanvasRenderConfig, appState: StaticCanvasAppState | InteractiveCanvasAppState, renderState?: Readonly<{
+    /** Alpha including frame opacity and pending erasure; selection dimming is separate. */
+    opacity: number;
+    offset: RenderPositionOffset;
+}>) => void;
 export declare function getFreedrawOutlineAsSegments(element: ExcalidrawFreeDrawElement, points: [number, number][], elementsMap: ElementsMap): import("@excalidraw/math").LineSegment<GlobalPoint>[];

package/dist/types/element/src/resizeElements.d.ts

@@ -3,7 +3,7 @@ import type { PointerDownState } from "@excalidraw/excalidraw/types";
 import type { Scene } from "./Scene";
 import type { BoundingBox } from "./bounds";
 import type { MaybeTransformHandleType, TransformHandleDirection } from "./transformHandles";
-import type { ExcalidrawLinearElement, ExcalidrawTextElement, NonDeletedExcalidrawElement, NonDeleted, ExcalidrawElement, ElementsMap } from "./types";
+import type { ExcalidrawLinearElement, ExcalidrawTextElement, NonDeletedExcalidrawElement, NonDeleted, ElementsMap } from "./types";
 export declare const transformElements: (originalElements: PointerDownState["originalElements"], transformHandleType: MaybeTransformHandleType, selectedElements: readonly NonDeletedExcalidrawElement[], scene: Scene, shouldRotateWithDiscreteAngle: boolean, shouldResizeFromCenter: boolean, shouldMaintainAspectRatio: boolean, pointerX: number, pointerY: number, centerX: number, centerY: number) => boolean;
 export declare const rescalePointsInElement: (element: NonDeletedExcalidrawElement, width: number, height: number, normalizePoints: boolean) => {
     points: LocalPoint[];
@@ -16,7 +16,7 @@ export declare const measureFontSizeFromWidth: (element: NonDeleted<ExcalidrawTe
 export declare const resizeSingleTextElement: (origElement: NonDeleted<ExcalidrawTextElement>, element: NonDeleted<ExcalidrawTextElement>, scene: Scene, transformHandleType: TransformHandleDirection, shouldResizeFromCenter: boolean, nextWidth: number, nextHeight: number) => void;
 export declare const getResizeOffsetXY: (transformHandleType: MaybeTransformHandleType, selectedElements: NonDeletedExcalidrawElement[], elementsMap: ElementsMap, x: number, y: number) => [number, number];
 export declare const getResizeArrowDirection: (transformHandleType: MaybeTransformHandleType, element: NonDeleted<ExcalidrawLinearElement>) => "origin" | "end";
-export declare const resizeSingleElement: (nextWidth: number, nextHeight: number, latestElement: ExcalidrawElement, origElement: ExcalidrawElement, originalElementsMap: ElementsMap, scene: Scene, handleDirection: TransformHandleDirection, { shouldInformMutation, shouldMaintainAspectRatio, shouldResizeFromCenter, }?: {
+export declare const resizeSingleElement: (nextWidth: number, nextHeight: number, latestElement: NonDeletedExcalidrawElement, origElement: NonDeletedExcalidrawElement, originalElementsMap: ElementsMap, scene: Scene, handleDirection: TransformHandleDirection, { shouldInformMutation, shouldMaintainAspectRatio, shouldResizeFromCenter, }?: {
     shouldMaintainAspectRatio?: boolean;
     shouldResizeFromCenter?: boolean;
     shouldInformMutation?: boolean;

package/dist/types/element/src/selection.d.ts

@@ -1,4 +1,4 @@
-import type { AppState, InteractiveCanvasAppState } from "@excalidraw/excalidraw/types";
+import type { AppState, BoxSelectionMode, InteractiveCanvasAppState } from "@excalidraw/excalidraw/types";
 import { LinearElementEditor } from "./linearElementEditor";
 import type { ElementsMap, ElementsMapOrArray, ExcalidrawElement, NonDeleted, NonDeletedExcalidrawElement } from "./types";
 /**
@@ -8,8 +8,8 @@ import type { ElementsMap, ElementsMapOrArray, ExcalidrawElement, NonDeleted, No
  * @param selectedElements
  */
 export declare const excludeElementsInFramesFromSelection: <T extends ExcalidrawElement>(selectedElements: readonly T[]) => T[];
-export declare const getElementsWithinSelection: (elements: readonly NonDeletedExcalidrawElement[], selection: NonDeletedExcalidrawElement, elementsMap: ElementsMap, excludeElementsInFrames?: boolean) => NonDeletedExcalidrawElement[];
-export declare const getVisibleAndNonSelectedElements: (elements: readonly NonDeletedExcalidrawElement[], selectedElements: readonly NonDeletedExcalidrawElement[], appState: AppState, elementsMap: ElementsMap) => NonDeletedExcalidrawElement[];
+export declare const getElementsWithinSelection: <T extends ExcalidrawElement>(elements: readonly T[], selection: ExcalidrawElement, elementsMap: ElementsMap, excludeElementsInFrames?: boolean, boxSelectionMode?: BoxSelectionMode) => T[];
+export declare const getVisibleAndNonSelectedElements: <T extends NonDeletedExcalidrawElement>(elements: readonly T[], selectedElements: readonly ExcalidrawElement[], appState: AppState, elementsMap: ElementsMap) => T[];
 export declare const isSomeElementSelected: {
     (elements: readonly NonDeletedExcalidrawElement[], appState: Pick<AppState, "selectedElementIds">): boolean;
     clearCache(): void;
@@ -17,8 +17,8 @@ export declare const isSomeElementSelected: {
 export declare const getSelectedElements: (elements: ElementsMapOrArray, appState: Pick<InteractiveCanvasAppState, "selectedElementIds">, opts?: {
     includeBoundTextElement?: boolean;
     includeElementsInFrames?: boolean;
-}) => ExcalidrawElement[];
-export declare const getTargetElements: (elements: ElementsMapOrArray, appState: Pick<AppState, "selectedElementIds" | "editingTextElement" | "newElement">) => ExcalidrawElement[];
+}) => NonDeletedExcalidrawElement[];
+export declare const getTargetElements: (elements: ElementsMapOrArray, appState: Pick<AppState, "selectedElementIds" | "editingTextElement" | "newElement" | "activeTool">) => NonDeletedExcalidrawElement[] | import("./types").ExcalidrawTextElement[];
 /**
  * returns prevState's selectedElementids if no change from previous, so as to
  * retain reference identity for memoization
@@ -26,7 +26,7 @@ export declare const getTargetElements: (elements: ElementsMapOrArray, appState:
 export declare const makeNextSelectedElementIds: (nextSelectedElementIds: AppState["selectedElementIds"], prevState: Pick<AppState, "selectedElementIds">) => Readonly<{
     [id: string]: true;
 }>;
-export declare const getSelectionStateForElements: (targetElements: readonly ExcalidrawElement[], allElements: readonly NonDeletedExcalidrawElement[], appState: AppState) => {
+export declare const getSelectionStateForElements: (targetElements: readonly NonDeletedExcalidrawElement[], allElements: readonly NonDeletedExcalidrawElement[], appState: AppState) => {
     editingGroupId: AppState["editingGroupId"];
     selectedElementIds: AppState["selectedElementIds"];
     selectedGroupIds: AppState["selectedGroupIds"];

package/dist/types/element/src/shape.d.ts

@@ -1,6 +1,6 @@
 import { type GeometricShape } from "@excalidraw/utils/shape";
 import { type LocalPoint } from "@excalidraw/math";
-import type { GlobalPoint } from "@excalidraw/math";
+import type { GlobalPoint, Polygon } from "@excalidraw/math";
 import type { AppState, EmbedsValidationStatus } from "@excalidraw/excalidraw/types";
 import type { ElementShape, ElementShapes } from "@excalidraw/excalidraw/scene/types";
 import type { ExcalidrawElement, ExcalidrawSelectionElement, ExcalidrawLinearElement, ExcalidrawFreeDrawElement, ElementsMap, ExcalidrawLineElement } from "./types";
@@ -27,6 +27,11 @@ export declare class ShapeCache {
     } | null) => ((T["type"] extends keyof ElementShapes ? ElementShapes[T["type"]] | undefined : ElementShape | undefined) & {}) | (T["type"] extends keyof ElementShapes ? ElementShapes[T["type"]] : Drawable | null);
 }
 export declare const generateRoughOptions: (element: ExcalidrawElement, continuousPath?: boolean, isDarkMode?: boolean) => Options;
+/**
+ * Returns the flattened fill contour of a freedraw loop in local, unrotated
+ * coordinates, following the rendered fill rather than the stroke outline.
+ */
+export declare const getFreedrawFillPolygon: (element: ExcalidrawFreeDrawElement) => Polygon<LocalPoint>;
 export declare const generateLinearCollisionShape: (element: ExcalidrawLinearElement | ExcalidrawFreeDrawElement, elementsMap: ElementsMap) => {
     op: string;
     data: number[];
@@ -41,3 +46,24 @@ export declare const toggleLinePolygonState: (element: ExcalidrawLineElement, ne
     points: ExcalidrawLineElement["points"];
 } | null;
 export declare const getFreedrawOutlinePoints: (element: ExcalidrawFreeDrawElement) => [number, number][];
+/**
+ * Upper bound on how far a freedraw stroke's ink reaches past its centerline
+ * points. Both stroke generators scale the stroke size by at most 1 (easing
+ * or pressure), so the size itself bounds the radius, except for
+ * perfect-freehand's short strokes: under 3px long, the start cap is drawn
+ * around the first point from an outline point of the last one (reaching
+ * sqrt(size² + 3²)), and a single point gets a synthetic neighbor 1px away.
+ */
+export declare const getFreedrawMaxStrokeRadius: (element: ExcalidrawFreeDrawElement) => number;
+/**
+ * The streamline-smoothed centerline the freedraw stroke is rendered
+ * around, in element-local coordinates. Boundary-sensitive consumers (e.g.
+ * bucket fill) should use this instead of `element.points`: raw input
+ * points can sit 20px+ apart and the rendered stroke is smoothed between
+ * them, so raw chords visibly deviate from what's on screen.
+ *
+ * Constant-width ("laser geometry") strokes technically smooth via
+ * `LaserPointer` instead; the perfect-freehand centerline with the same
+ * `streamline` is a close approximation the stroke width hides.
+ */
+export declare const getFreedrawStrokeCenterPoints: (element: ExcalidrawFreeDrawElement) => [number, number][];

package/dist/types/element/src/sizeHelpers.d.ts

@@ -1,5 +1,11 @@
 import type { AppState, Offsets, Zoom } from "@excalidraw/excalidraw/types";
 import type { ElementsMap, ExcalidrawElement } from "./types";
+export type VerticalResizeAnchor = "top" | "bottom" | "center";
+/** Keeps the chosen edge or center fixed when an element's height changes. */
+export declare const getPositionAfterHeightChange: (element: Pick<ExcalidrawElement, "x" | "y" | "height" | "angle">, nextHeight: number, anchor?: VerticalResizeAnchor) => {
+    x: number;
+    y: number;
+};
 export declare const INVISIBLY_SMALL_ELEMENT_SIZE = 0.1;
 export declare const isInvisiblySmallElement: (element: ExcalidrawElement) => boolean;
 export declare const isElementInViewport: (element: ExcalidrawElement, width: number, height: number, viewTransformations: {

package/dist/types/element/src/sortElements.d.ts

@@ -1,2 +1,12 @@
 import type { ExcalidrawElement } from "./types";
+/**
+ * In theory, when we have text elements bound to a container, they
+ * should be right after the container element in the elements array.
+ * However, this is not guaranteed due to old and potential future bugs.
+ *
+ * This function sorts containers and their bound texts together. It prefers
+ * original z-index of container (i.e. it moves bound text elements after
+ * containers).
+ */
+export declare const normalizeBoundElementsOrder: <T extends ExcalidrawElement>(elements: readonly T[]) => readonly T[];
 export declare const normalizeElementOrder: (elements: readonly ExcalidrawElement[]) => readonly ExcalidrawElement[];

package/dist/types/element/src/stickyNote.d.ts

@@ -0,0 +1,183 @@
+import type { Scene } from "./Scene";
+import type { VerticalResizeAnchor } from "./sizeHelpers";
+import type { TransformHandleDirection } from "./transformHandles";
+import type { ElementsMap, ExcalidrawElement, ExcalidrawStickyNoteElement, ExcalidrawTextElement, NonDeletedExcalidrawElement } from "./types";
+export type StickyNoteRenderPoint = {
+    x: number;
+    y: number;
+};
+export type StickyNotePathCommand = {
+    type: "move";
+    point: StickyNoteRenderPoint;
+} | {
+    type: "line";
+    point: StickyNoteRenderPoint;
+} | {
+    type: "quadratic";
+    control: StickyNoteRenderPoint;
+    point: StickyNoteRenderPoint;
+};
+export declare const normalizeStickyNoteStrokeColor: (strokeColor: string | null | undefined) => string;
+export declare const normalizeStickyNoteBackgroundColor: (backgroundColor: string | null | undefined) => string;
+/**
+ * The update that applies a picked color to an element under the sticky
+ * note policy: a note is always filled and its label — the visible text,
+ * which the note's own `strokeColor` seeds — never goes transparent. Every
+ * color surface (actions, both eyedroppers, paste styles, bind) routes
+ * through this instead of re-deriving the rule.
+ */
+/**
+ * The element a color pick on `element` lands on. A note's label has no fill
+ * of its own, so a background pick on the label — the styles panel while
+ * editing it — goes to the note; everything else colors itself.
+ */
+export declare const getColorTargetElement: (element: ExcalidrawElement, property: "strokeColor" | "backgroundColor", elementsMap: ElementsMap) => ExcalidrawElement;
+export declare const getColorUpdate: (element: ExcalidrawElement, property: "strokeColor" | "backgroundColor", color: string, elementsMap: ElementsMap) => {
+    strokeColor: string;
+} | {
+    backgroundColor: string;
+};
+/**
+ * A note's ink is one color: the container's `strokeColor` — the seed for a
+ * new label and what the creation-date footer paints with — and its label's.
+ * Run after a property write to copy the side that changed onto the other;
+ * when both changed, or neither (data that drifted), the label wins: it is
+ * the text the user styled. A transparent label always takes the note's
+ * color. Returns the same array when nothing needs to change.
+ */
+export declare const syncStickyNoteInk: <T extends ExcalidrawElement>(elements: readonly T[], prevElementsMap: ElementsMap) => readonly T[];
+export declare const getStickyNoteCornerRadius: (element: ExcalidrawStickyNoteElement) => number;
+export declare const getStickyNoteRenderPoints: (element: ExcalidrawStickyNoteElement, { offsetX, offsetY, seedOffset, }?: {
+    offsetX?: number;
+    offsetY?: number;
+    seedOffset?: number;
+}) => StickyNoteRenderPoint[];
+export declare const getStickyNotePathCommands: (element: ExcalidrawStickyNoteElement, { shadow }?: {
+    shadow?: boolean;
+}) => StickyNotePathCommand[];
+export declare const normalizeStickyNoteFontSize: (fontSize: number) => number;
+/** whether the text element is the label of a sticky note */
+export declare const isStickyNoteBoundText: (textElement: ExcalidrawTextElement, elementsMap: ElementsMap) => boolean;
+/**
+ * The font size the user picked: the ceiling the auto-fit shrinks from for a
+ * sticky note label, plain `fontSize` for any other text.
+ *
+ * Container-aware on purpose — generic binding repair (duplication, history)
+ * rewrites `containerId` without touching the ceiling, so a numeric
+ * `baseFontSize` alone does not prove the text is still sticky-bound.
+ */
+export declare const getBaseFontSize: (textElement: ExcalidrawTextElement, elementsMap: ElementsMap) => number;
+/** the update that applies a user-picked font size (see `getBaseFontSize`) */
+export declare const getBaseFontSizeUpdate: (textElement: ExcalidrawTextElement, fontSize: number, elementsMap: ElementsMap) => {
+    fontSize: number;
+} | {
+    baseFontSize: number;
+};
+/**
+ * The creation-date label: absolute, so painting needs no clock and exports
+ * don't go stale, and short ("7 Sep") while the year is the current one.
+ * `null` when the note has no usable timestamp (files restored without one).
+ * Fixed English in the viewer's local time zone — the element package has no
+ * locale, and the footer is chosen by width bucket rather than measured.
+ */
+export declare const getStickyNoteDateLabel: (created: ExcalidrawStickyNoteElement["created"], { short, now }?: {
+    short?: boolean;
+    now?: number;
+}) => string | null;
+/**
+ * What the footer paints and where, in note-local coordinates — shared by the
+ * canvas and SVG renderers, which take the font and opacity from
+ * `STICKY_NOTE_FOOTER`. `null` for the 0×0 creation draft and anything under
+ * the data floor, where the band would overlap the top padding.
+ */
+export declare const getStickyNoteFooter: (element: Pick<ExcalidrawStickyNoteElement, "created" | "width" | "height">, now?: number) => {
+    text: string;
+    x: number;
+    y: number;
+} | null;
+/**
+ * The smallest note the UI lets a user create or resize to: one line at the
+ * label's font ceiling plus padding (and, vertically, the footer), never below
+ * `STICKY_NOTE_MIN_SIZE`. Without the font term a fresh note would grow on
+ * the very first keystroke. Data-level passes (restore, action post-passes)
+ * only enforce the constant floor — the layout grows a note as needed.
+ */
+export declare const getStickyNoteMinSize: ({ fontSize, fontFamily, }: Pick<ExcalidrawTextElement, "fontSize" | "fontFamily">) => {
+    width: number;
+    height: number;
+};
+export type StickyNoteLayoutAnchor = VerticalResizeAnchor;
+export type StickyNoteLayoutOpts = {
+    /** unwrapped text to lay out; defaults to the label's `originalText` */
+    originalText?: string;
+    /**
+     * absolute base-height intent — the gesture-start value to preserve, or the
+     * height a resize asked for. Omitted = keep the note's live `baseHeight`
+     * (typing, style changes, restore).
+     */
+    baseHeight?: number;
+    /**
+     * absolute font-ceiling intent (a proportional resize passes
+     * `gesture-start ceiling × scale`). Omitted = keep the label's live ceiling.
+     * Never a multiplier on the live value — that compounds across pointer-moves.
+     */
+    baseFontSize?: number;
+    /** the edge that stays put when the content correction changes the height */
+    anchor?: StickyNoteLayoutAnchor;
+};
+export type StickyNoteLayout = {
+    container: Pick<ExcalidrawStickyNoteElement, "x" | "y" | "width" | "height" | "baseHeight">;
+    text: Pick<ExcalidrawTextElement, "text" | "fontSize" | "baseFontSize" | "width" | "height" | "x" | "y" | "angle"> | null;
+};
+/**
+ * The single source of truth for a sticky note's geometry: wraps the label at
+ * the note's width, fits the font under the ceiling, grows the note past
+ * `baseHeight` only when the text still overflows at the minimum size, and
+ * positions the label inside. Pure — returns the updates for both elements.
+ */
+export declare const getStickyNoteLayout: (container: ExcalidrawStickyNoteElement, textElement: ExcalidrawTextElement | null, opts?: StickyNoteLayoutOpts) => StickyNoteLayout;
+/**
+ * Resize intents for a sticky note — the §3.3 matrix of the plan. Every value
+ * is absolute and derived from the gesture-start snapshot on each pointer-move,
+ * so releasing Shift (or Alt) mid-gesture restores the original base height
+ * and ceiling instead of keeping values a previous move scaled.
+ *
+ * - width-only gestures (free E/W, Stats W) preserve the base height
+ * - height-changing gestures use the requested height as the new base
+ * - proportional gestures (Shift on any handle, aspect-locked multi-select,
+ *   Stats group) additionally scale the font ceiling with the note
+ * - flips preserve everything
+ * - the content correction anchors at the edge the gesture holds still
+ */
+export declare const getStickyNoteResizeIntent: (
+/** the note with the requested geometry already applied */
+container: ExcalidrawStickyNoteElement, originalElementsMap: ElementsMap, handleDirection: TransformHandleDirection, { proportional, fromCenter, flip, }: {
+    proportional: boolean;
+    fromCenter: boolean;
+    flip?: boolean;
+}) => Pick<StickyNoteLayoutOpts, "baseHeight" | "baseFontSize" | "anchor">;
+/**
+ * Applies `getStickyNoteLayout` to a live scene, then runs the bound-arrow
+ * pass unless the caller already owns one (`bindings: false`) or needs to
+ * forward its context (`bindings: { simultaneouslyUpdated }` — arrows resized
+ * in the same gesture must not be moved by the pass, `updateBoundElements`
+ * skips them only when told).
+ */
+export declare const updateStickyNoteLayout: (container: ExcalidrawStickyNoteElement, scene: Scene, { text, bindings, ...layoutOpts }?: StickyNoteLayoutOpts & {
+    /** the label to lay out when it is an uncommitted clone (font actions clone before install) */
+    text?: ExcalidrawTextElement | null;
+    bindings?: {
+        simultaneouslyUpdated?: readonly NonDeletedExcalidrawElement[];
+    } | false;
+}) => StickyNoteLayout;
+/**
+ * Applies `getStickyNoteLayout` inside an immutable elements array (property
+ * actions, paste styles, restore): the notes among `affectedIds` — or the
+ * notes whose labels are — get both halves merged into their clones. Elements
+ * that need no change keep their identity and version; when `prevElementsMap`
+ * is given, notes whose layout inputs did not change skip the fit entirely.
+ * Bound arrows are the caller's job once the result is installed.
+ */
+export declare const relayoutStickyNotes: <T extends ExcalidrawElement>(elements: readonly T[], affectedIds: ReadonlySet<ExcalidrawElement["id"]>, opts?: {
+    prevElementsMap?: ElementsMap;
+}) => readonly T[];

package/dist/types/element/src/textElement.d.ts

@@ -1,23 +1,26 @@
 import { type Radians } from "@excalidraw/math";
-import type { AppState } from "@excalidraw/excalidraw/types";
 import type { ExtractSetType } from "@excalidraw/common/utility-types";
 import type { Scene } from "./Scene";
 import type { MaybeTransformHandleType } from "./transformHandles";
-import type { ElementsMap, ExcalidrawElement, ExcalidrawElementType, ExcalidrawTextContainer, ExcalidrawTextElement, ExcalidrawTextElementWithContainer, NonDeletedExcalidrawElement } from "./types";
+import type { ElementsMap, ExcalidrawElement, ExcalidrawElementType, ExcalidrawTextContainer, ExcalidrawTextElement, ExcalidrawTextElementWithContainer, NonDeleted } from "./types";
 export declare const redrawTextBoundingBox: (textElement: ExcalidrawTextElement, container: ExcalidrawElement | null, scene: Scene) => void;
-export declare const handleBindTextResize: (container: NonDeletedExcalidrawElement, scene: Scene, transformHandleType: MaybeTransformHandleType, shouldMaintainAspectRatio?: boolean) => void;
+export declare const handleBindTextResize: (container: ExcalidrawElement, scene: Scene, transformHandleType: MaybeTransformHandleType, shouldMaintainAspectRatio?: boolean, shouldResizeFromCenter?: boolean, flipByY?: boolean) => void;
 export declare const computeBoundTextPosition: (container: ExcalidrawElement, boundTextElement: ExcalidrawTextElementWithContainer, elementsMap: ElementsMap) => {
     x: number;
     y: number;
 };
 export declare const getBoundTextElementId: (container: ExcalidrawElement | null) => string | null;
-export declare const getBoundTextElement: (element: ExcalidrawElement | null, elementsMap: ElementsMap) => ExcalidrawTextElementWithContainer | null;
-export declare const getContainerElement: (element: ExcalidrawTextElement | null, elementsMap: ElementsMap) => ExcalidrawTextContainer | null;
-export declare const getContainerCenter: (container: ExcalidrawElement, appState: AppState, elementsMap: ElementsMap) => {
+export declare const getBoundTextElement: (element: ExcalidrawElement | null, elementsMap: ElementsMap) => NonDeleted<ExcalidrawTextElementWithContainer> | null;
+export declare const getContainerElement: <T extends ExcalidrawTextElement, R extends ExcalidrawTextContainer>(element: T | null, elementsMap: ElementsMap) => R | null;
+/**
+ * The point a text bound to this container centers on — and, for arrows, the
+ * point the text tool snaps a new label to.
+ */
+export declare const getContainerCenter: (container: ExcalidrawElement, elementsMap: ElementsMap) => {
     x: number;
     y: number;
 };
-export declare const getContainerCoords: (container: NonDeletedExcalidrawElement) => {
+export declare const getContainerCoords: (container: ExcalidrawElement) => {
     x: number;
     y: number;
 };
@@ -26,8 +29,15 @@ export declare const getBoundTextElementPosition: (container: ExcalidrawElement,
     x: number;
     y: number;
 } | undefined;
-export declare const shouldAllowVerticalAlign: (selectedElements: NonDeletedExcalidrawElement[], elementsMap: ElementsMap) => boolean;
-export declare const suppportsHorizontalAlign: (selectedElements: NonDeletedExcalidrawElement[], elementsMap: ElementsMap) => boolean;
+/**
+ * Returns the text element with its accurate coords. An arrow label's
+ * position is derived from the arrow at render time rather than kept in
+ * sync on the element itself (see getBoundTextElementPosition), so
+ * consumers reading a label's coords directly must go through this helper.
+ */
+export declare const getTextElementWithAccuratePosition: <T extends ExcalidrawTextElement>(textElement: T, elementsMap: ElementsMap) => T;
+export declare const shouldAllowVerticalAlign: (selectedElements: readonly ExcalidrawElement[], elementsMap: ElementsMap) => boolean;
+export declare const suppportsHorizontalAlign: (selectedElements: readonly ExcalidrawElement[], elementsMap: ElementsMap) => boolean;
 declare const VALID_CONTAINER_TYPES: Set<string>;
 export declare const isValidTextContainer: (element: {
     type: ExcalidrawElementType;
@@ -37,4 +47,5 @@ export declare const getBoundTextMaxWidth: (container: ExcalidrawElement, boundT
 export declare const getBoundTextMaxHeight: (container: ExcalidrawElement, boundTextElement: ExcalidrawTextElementWithContainer) => number;
 /** retrieves text from text elements and concatenates to a single string */
 export declare const getTextFromElements: (elements: readonly ExcalidrawElement[], separator?: string) => string;
+export declare const DEFAULT_BOUND_TEXT_LABEL_POSITION = 0.5;
 export {};

package/dist/types/element/src/transform.d.ts

@@ -1,6 +1,12 @@
 import type { MarkOptional } from "@excalidraw/common/utility-types";
 import { type ElementConstructorOpts } from "./newElement";
-import type { ExcalidrawBindableElement, ExcalidrawElement, ExcalidrawFrameElement, ExcalidrawFreeDrawElement, ExcalidrawGenericElement, ExcalidrawIframeLikeElement, ExcalidrawImageElement, ExcalidrawLinearElement, ExcalidrawMagicFrameElement, ExcalidrawSelectionElement, ExcalidrawTextElement, FileId, FontFamilyValues, TextAlign, VerticalAlign } from "./types";
+import type { ExcalidrawBindableElement, ExcalidrawElement, ExcalidrawFrameElement, ExcalidrawFreeDrawElement, ExcalidrawGenericElement, ExcalidrawIframeLikeElement, ExcalidrawImageElement, ExcalidrawLinearElement, ExcalidrawMagicFrameElement, ExcalidrawSelectionElement, ExcalidrawTextElement, FileId, FontFamilyValues, NonDeletedExcalidrawElement, Ordered, TextAlign, VerticalAlign, ExcalidrawStickyNoteElement } from "./types";
+/**
+ * Options for elements generated from a skeleton fragment (bound labels and
+ * binding endpoints). Such elements are always constructed fresh, hence they
+ * never carry a creation time of their own.
+ */
+type FragmentConstructorOpts = MarkOptional<Omit<ElementConstructorOpts, "created">, "x" | "y">;
 export type ValidLinearElement = {
     type: "arrow" | "line";
     x: number;
@@ -11,7 +17,7 @@ export type ValidLinearElement = {
         fontFamily?: FontFamilyValues;
         textAlign?: TextAlign;
         verticalAlign?: VerticalAlign;
-    } & MarkOptional<ElementConstructorOpts, "x" | "y">;
+    } & FragmentConstructorOpts;
     end?: (({
         type: Exclude<ExcalidrawBindableElement["type"], "image" | "text" | "frame" | "magicframe" | "embeddable" | "iframe">;
         id?: ExcalidrawGenericElement["id"];
@@ -25,7 +31,7 @@ export type ValidLinearElement = {
         type?: "text";
         id: ExcalidrawTextElement["id"];
         text: string;
-    }) & Partial<ExcalidrawTextElement>)) & MarkOptional<ElementConstructorOpts, "x" | "y">;
+    }) & Partial<Omit<ExcalidrawTextElement, "created">>)) & FragmentConstructorOpts;
     start?: (({
         type: Exclude<ExcalidrawBindableElement["type"], "image" | "text" | "frame" | "magicframe" | "embeddable" | "iframe">;
         id?: ExcalidrawGenericElement["id"];
@@ -39,7 +45,7 @@ export type ValidLinearElement = {
         type?: "text";
         id: ExcalidrawTextElement["id"];
         text: string;
-    }) & Partial<ExcalidrawTextElement>)) & MarkOptional<ElementConstructorOpts, "x" | "y">;
+    }) & Partial<Omit<ExcalidrawTextElement, "created">>)) & FragmentConstructorOpts;
 } & Partial<ExcalidrawLinearElement>;
 export type ValidContainer = {
     type: Exclude<ExcalidrawGenericElement["type"], "selection">;
@@ -50,13 +56,25 @@ export type ValidContainer = {
         fontFamily?: FontFamilyValues;
         textAlign?: TextAlign;
         verticalAlign?: VerticalAlign;
-    } & MarkOptional<ElementConstructorOpts, "x" | "y">;
+    } & FragmentConstructorOpts;
 } & ElementConstructorOpts;
+/**
+ * A sticky note: an always-filled note whose label auto-fits. `label.fontSize`
+ * is the font ceiling the fit shrinks from; the note grows past its height
+ * (kept as `baseHeight`) only once the label hits the minimum font size.
+ */
+export type ValidStickyNote = {
+    type: "stickynote";
+    id?: ExcalidrawStickyNoteElement["id"];
+    label?: Extract<ValidContainer, {
+        label?: unknown;
+    }>["label"];
+} & ElementConstructorOpts & Partial<Pick<ExcalidrawStickyNoteElement, "baseHeight">>;
 export type ExcalidrawElementSkeleton = Extract<Exclude<ExcalidrawElement, ExcalidrawSelectionElement>, ExcalidrawIframeLikeElement | ExcalidrawFreeDrawElement> | ({
     type: Extract<ExcalidrawLinearElement["type"], "line">;
     x: number;
     y: number;
-} & Partial<ExcalidrawLinearElement>) | ValidContainer | ValidLinearElement | ({
+} & Partial<ExcalidrawLinearElement>) | ValidContainer | ValidStickyNote | ValidLinearElement | ({
     type: "text";
     text: string;
     x: number;
@@ -78,4 +96,5 @@ export type ExcalidrawElementSkeleton = Extract<Exclude<ExcalidrawElement, Excal
 } & Partial<ExcalidrawMagicFrameElement>);
 export declare const convertToExcalidrawElements: (elementsSkeleton: ExcalidrawElementSkeleton[] | null, opts?: {
     regenerateIds: boolean;
-}) => import("./types").OrderedExcalidrawElement[];
+}) => Ordered<NonDeletedExcalidrawElement>[];
+export {};