@excalidraw/element 0.18.0-9ba0f5d → 0.18.0-a52cd20

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,15 +29,23 @@ 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;
-}) => boolean;
+}) => element is ExcalidrawTextContainer;
 export declare const computeContainerDimensionForBoundText: (dimension: number, containerType: ExtractSetType<typeof VALID_CONTAINER_TYPES>) => number;
 export declare const getBoundTextMaxWidth: (container: ExcalidrawElement, boundTextElement: ExcalidrawTextElement | null) => number;
 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/textWrapping.d.ts

@@ -5,9 +5,35 @@ import type { FontString } from "./types";
 export declare const containsCJK: (text: string) => boolean;
 /**
  * Breaks the line into the tokens based on the found line break opporutnities.
+ *
+ * Note: tokenization normalizes to NFC first so decomposed graphemes are treated as
+ * their composed variants for wrapping. Any code that needs exact source offsets should
+ * keep in mind that this assumes the input text is already NFC-normalized.
  */
 export declare const parseTokens: (line: string) => string[];
 /**
  * Wraps the original text into the lines based on the given width.
+ *
+ * This is a convenience adapter over `getWrappedTextLines()` for call sites
+ * that only need the rendered wrapped string and not the source offsets.
  */
 export declare const wrapText: (text: string, font: FontString, maxWidth: number) => string;
+/**
+ * A single rendered visual line produced from the original text.
+ *
+ * `start` and `end` are end-exclusive code-unit offsets into the original text, and do
+ * not include synthetic soft line breaks inserted by this module. If trailing whitespace
+ * was trimmed away at a wrap boundary, `end` points to the last rendered character.
+ */
+export type WrappedTextLine = {
+    text: string;
+    start: number;
+    end: number;
+};
+/**
+ * Returns the rendered visual lines together with their source offsets.
+ *
+ * This is the source-of-truth wrapping pipeline for callers that need more than the
+ * final wrapped string, for example caret placement or future editor/rich-text mapping.
+ */
+export declare const getWrappedTextLines: (text: string, font: FontString, maxWidth: number) => WrappedTextLine[];

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 {};

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

@@ -1,41 +1,42 @@
 import type { ElementOrToolType } from "@excalidraw/excalidraw/types";
 import type { MarkNonNullable } from "@excalidraw/common/utility-types";
-import type { ExcalidrawElement, ExcalidrawTextElement, ExcalidrawEmbeddableElement, ExcalidrawLinearElement, ExcalidrawBindableElement, ExcalidrawFreeDrawElement, InitializedExcalidrawImageElement, ExcalidrawImageElement, ExcalidrawTextElementWithContainer, ExcalidrawTextContainer, ExcalidrawFrameElement, RoundnessType, ExcalidrawFrameLikeElement, ExcalidrawElementType, ExcalidrawIframeElement, ExcalidrawIframeLikeElement, ExcalidrawMagicFrameElement, ExcalidrawArrowElement, ExcalidrawElbowArrowElement, ExcalidrawLineElement, ExcalidrawFlowchartNodeElement, ExcalidrawLinearElementSubType } from "./types";
-export declare const isInitializedImageElement: (element: ExcalidrawElement | null) => element is InitializedExcalidrawImageElement;
-export declare const isImageElement: (element: ExcalidrawElement | null) => element is ExcalidrawImageElement;
-export declare const isEmbeddableElement: (element: ExcalidrawElement | null | undefined) => element is ExcalidrawEmbeddableElement;
-export declare const isIframeElement: (element: ExcalidrawElement | null) => element is ExcalidrawIframeElement;
-export declare const isIframeLikeElement: (element: ExcalidrawElement | null) => element is ExcalidrawIframeLikeElement;
-export declare const isTextElement: (element: ExcalidrawElement | null) => element is ExcalidrawTextElement;
-export declare const isFrameElement: (element: ExcalidrawElement | null) => element is ExcalidrawFrameElement;
-export declare const isMagicFrameElement: (element: ExcalidrawElement | null) => element is ExcalidrawMagicFrameElement;
-export declare const isFrameLikeElement: (element: ExcalidrawElement | null) => element is ExcalidrawFrameLikeElement;
-export declare const isFreeDrawElement: (element?: ExcalidrawElement | null) => element is ExcalidrawFreeDrawElement;
+import type { ExcalidrawElement, ExcalidrawTextElement, ExcalidrawEmbeddableElement, ExcalidrawLinearElement, ExcalidrawBindableElement, ExcalidrawFreeDrawElement, InitializedExcalidrawImageElement, ExcalidrawImageElement, ExcalidrawTextElementWithContainer, ExcalidrawTextContainer, ExcalidrawFrameElement, RoundnessType, ExcalidrawFrameLikeElement, ExcalidrawElementType, ExcalidrawIframeElement, ExcalidrawIframeLikeElement, ExcalidrawMagicFrameElement, ExcalidrawArrowElement, ExcalidrawElbowArrowElement, ExcalidrawLineElement, ExcalidrawFlowchartNodeElement, ExcalidrawLinearElementSubType, ExcalidrawStickyNoteElement } from "./types";
+export declare const isInitializedImageElement: <T extends ExcalidrawElement>(element: T | null) => element is T & InitializedExcalidrawImageElement;
+export declare const isImageElement: <T extends ExcalidrawElement>(element: T | null) => element is T & ExcalidrawImageElement;
+export declare const isEmbeddableElement: <T extends ExcalidrawElement>(element: T | null | undefined) => element is T & ExcalidrawEmbeddableElement;
+export declare const isIframeElement: <T extends ExcalidrawElement>(element: T | null) => element is T & ExcalidrawIframeElement;
+export declare const isIframeLikeElement: <T extends ExcalidrawElement>(element: T | null) => element is T & ExcalidrawIframeLikeElement;
+export declare const isTextElement: <T extends ExcalidrawElement>(element: T | null) => element is T & ExcalidrawTextElement;
+export declare const isStickyNoteElement: <T extends ExcalidrawElement>(element: T | null | undefined) => element is T & ExcalidrawStickyNoteElement;
+export declare const isFrameElement: <T extends ExcalidrawElement>(element: T | null) => element is T & ExcalidrawFrameElement;
+export declare const isMagicFrameElement: <T extends ExcalidrawElement>(element: T | null) => element is T & ExcalidrawMagicFrameElement;
+export declare const isFrameLikeElement: <T extends ExcalidrawElement>(element: T | null) => element is T & ExcalidrawFrameLikeElement;
+export declare const isFreeDrawElement: <T extends ExcalidrawElement>(element?: T | null) => element is T & ExcalidrawFreeDrawElement;
 export declare const isFreeDrawElementType: (elementType: ExcalidrawElementType) => boolean;
-export declare const isLinearElement: (element?: ExcalidrawElement | null) => element is ExcalidrawLinearElement;
-export declare const isLineElement: (element?: ExcalidrawElement | null) => element is ExcalidrawLineElement;
-export declare const isArrowElement: (element?: ExcalidrawElement | null) => element is ExcalidrawArrowElement;
-export declare const isElbowArrow: (element?: ExcalidrawElement) => element is ExcalidrawElbowArrowElement;
+export declare const isLinearElement: <T extends ExcalidrawElement>(element?: T | null) => element is T & ExcalidrawLinearElement;
+export declare const isLineElement: <T extends ExcalidrawElement>(element?: T | null) => element is T & ExcalidrawLineElement;
+export declare const isArrowElement: <T extends ExcalidrawElement>(element?: T | null) => element is T & ExcalidrawArrowElement;
+export declare const isElbowArrow: <T extends ExcalidrawElement>(element?: T) => element is T & ExcalidrawElbowArrowElement;
 /**
  * sharp or curved arrow, but not elbow
  */
-export declare const isSimpleArrow: (element?: ExcalidrawElement) => element is ExcalidrawArrowElement;
-export declare const isSharpArrow: (element?: ExcalidrawElement) => element is ExcalidrawArrowElement;
-export declare const isCurvedArrow: (element?: ExcalidrawElement) => element is ExcalidrawArrowElement;
+export declare const isSimpleArrow: <T extends ExcalidrawElement>(element?: T) => element is T & ExcalidrawArrowElement;
+export declare const isSharpArrow: <T extends ExcalidrawElement>(element?: T) => element is T & ExcalidrawArrowElement;
+export declare const isCurvedArrow: <T extends ExcalidrawElement>(element?: T) => element is T & ExcalidrawArrowElement;
 export declare const isLinearElementType: (elementType: ElementOrToolType) => boolean;
-export declare const isBindingElement: (element?: ExcalidrawElement | null, includeLocked?: boolean) => element is ExcalidrawArrowElement;
+export declare const isBindingElement: <T extends ExcalidrawElement>(element?: T | null, includeLocked?: boolean) => element is T & ExcalidrawArrowElement;
 export declare const isBindingElementType: (elementType: ElementOrToolType) => boolean;
-export declare const isBindableElement: (element: ExcalidrawElement | null | undefined, includeLocked?: boolean) => element is ExcalidrawBindableElement;
-export declare const isRectanguloidElement: (element?: ExcalidrawElement | null) => element is ExcalidrawBindableElement;
-export declare const isRectangularElement: (element?: ExcalidrawElement | null) => element is ExcalidrawBindableElement;
-export declare const isTextBindableContainer: (element: ExcalidrawElement | null, includeLocked?: boolean) => element is ExcalidrawTextContainer;
+export declare const isBindableElement: <T extends ExcalidrawElement>(element: T | null | undefined, includeLocked?: boolean) => element is T & ExcalidrawBindableElement;
+export declare const isRectanguloidElement: <T extends ExcalidrawElement>(element?: T | null) => element is T & ExcalidrawBindableElement;
+export declare const isRectangularElement: <T extends ExcalidrawElement>(element?: T | null) => element is T & ExcalidrawBindableElement;
+export declare const isTextBindableContainer: <T extends ExcalidrawElement>(element: T | null, includeLocked?: boolean) => element is T & ExcalidrawTextContainer;
 export declare const isExcalidrawElement: (element: any) => element is ExcalidrawElement;
-export declare const isFlowchartNodeElement: (element: ExcalidrawElement) => element is ExcalidrawFlowchartNodeElement;
-export declare const hasBoundTextElement: (element: ExcalidrawElement | null) => element is MarkNonNullable<ExcalidrawBindableElement, "boundElements">;
-export declare const isBoundToContainer: (element: ExcalidrawElement | null) => element is ExcalidrawTextElementWithContainer;
+export declare const isFlowchartNodeElement: <T extends ExcalidrawElement>(element: T) => element is T & ExcalidrawFlowchartNodeElement;
+export declare const hasBoundTextElement: <T extends ExcalidrawElement>(element: T | null) => element is T & MarkNonNullable<ExcalidrawBindableElement, "boundElements">;
+export declare const isBoundToContainer: <T extends ExcalidrawElement>(element: T | null) => element is T & ExcalidrawTextElementWithContainer;
 export declare const isArrowBoundToElement: (element: ExcalidrawArrowElement) => boolean;
 export declare const isUsingAdaptiveRadius: (type: string) => type is "rectangle" | "embeddable" | "iframe" | "image";
-export declare const isUsingProportionalRadius: (type: string) => type is "line" | "arrow" | "diamond";
+export declare const isUsingProportionalRadius: (type: string) => type is "line" | "arrow" | "stickynote" | "diamond";
 export declare const canApplyRoundnessTypeToElement: (roundnessType: RoundnessType, element: ExcalidrawElement) => boolean;
 export declare const getDefaultRoundnessTypeForElement: (element: ExcalidrawElement) => {
     type: 2;
@@ -52,3 +53,4 @@ export declare const getLinearElementSubType: (element: ExcalidrawLinearElement)
  */
 export declare const isValidPolygon: (points: ExcalidrawLineElement["points"]) => boolean;
 export declare const canBecomePolygon: (points: ExcalidrawLineElement["points"]) => boolean;
+export declare const isEligibleFrameChildType: (type: ElementOrToolType) => boolean;

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

@@ -1,7 +1,7 @@
 import type { LocalPoint, Radians } from "@excalidraw/math";
 import type { FONT_FAMILY, ROUNDNESS, TEXT_ALIGN, THEME, VERTICAL_ALIGN } from "@excalidraw/common";
 import type { MakeBrand, MarkNonNullable, Merge, ValueOf } from "@excalidraw/common/utility-types";
-export type ChartType = "bar" | "line";
+export type ChartType = "bar" | "line" | "radar";
 export type FillStyle = "hachure" | "cross-hatch" | "solid" | "zigzag";
 export type FontFamilyKeys = keyof typeof FONT_FAMILY;
 export type FontFamilyValues = typeof FONT_FAMILY[FontFamilyKeys];
@@ -66,6 +66,11 @@ type _ExcalidrawElementBase = Readonly<{
     boundElements: readonly BoundElement[] | null;
     /** epoch (ms) timestamp of last element update */
     updated: number;
+    /** Client wall-clock creation time in epoch milliseconds; null if unknown.
+        Preserved for this element's lifetime, including edits and undo/redo,
+        and excluded from `ElementUpdate` (mutateElement / newElementWith).
+        Duplicating an element starts a new lifetime. Not an ordering clock. */
+    created: number | null;
     link: string | null;
     locked: boolean;
     customData?: Record<string, any>;
@@ -76,6 +81,14 @@ export type ExcalidrawSelectionElement = _ExcalidrawElementBase & {
 export type ExcalidrawRectangleElement = _ExcalidrawElementBase & {
     type: "rectangle";
 };
+export type ExcalidrawStickyNoteElement = _ExcalidrawElementBase & Readonly<{
+    type: "stickynote";
+    /**
+     * The height the user set, from which the layout derives `height`: the
+     * note grows above it to fit its label and never shrinks below it
+     */
+    baseHeight: number;
+}>;
 export type ExcalidrawDiamondElement = _ExcalidrawElementBase & {
     type: "diamond";
 };
@@ -150,31 +163,40 @@ export type ExcalidrawFrameLikeElement = ExcalidrawFrameElement | ExcalidrawMagi
  * These are elements that don't have any additional properties.
  */
 export type ExcalidrawGenericElement = ExcalidrawSelectionElement | ExcalidrawRectangleElement | ExcalidrawDiamondElement | ExcalidrawEllipseElement;
-export type ExcalidrawFlowchartNodeElement = ExcalidrawRectangleElement | ExcalidrawDiamondElement | ExcalidrawEllipseElement;
-export type ExcalidrawRectanguloidElement = ExcalidrawRectangleElement | ExcalidrawImageElement | ExcalidrawTextElement | ExcalidrawFreeDrawElement | ExcalidrawIframeLikeElement | ExcalidrawFrameLikeElement | ExcalidrawEmbeddableElement | ExcalidrawSelectionElement;
+export type ExcalidrawFlowchartNodeElement = ExcalidrawRectangleElement | ExcalidrawStickyNoteElement | ExcalidrawDiamondElement | ExcalidrawEllipseElement;
+export type ExcalidrawRectanguloidElement = ExcalidrawRectangleElement | ExcalidrawStickyNoteElement | ExcalidrawImageElement | ExcalidrawTextElement | ExcalidrawFreeDrawElement | ExcalidrawIframeLikeElement | ExcalidrawFrameLikeElement | ExcalidrawEmbeddableElement | ExcalidrawSelectionElement;
 /**
  * ExcalidrawElement should be JSON serializable and (eventually) contain
  * no computed data. The list of all ExcalidrawElements should be shareable
  * between peers and contain no state local to the peer.
  */
-export type ExcalidrawElement = ExcalidrawGenericElement | ExcalidrawTextElement | ExcalidrawLinearElement | ExcalidrawArrowElement | ExcalidrawFreeDrawElement | ExcalidrawImageElement | ExcalidrawFrameElement | ExcalidrawMagicFrameElement | ExcalidrawIframeElement | ExcalidrawEmbeddableElement;
+export type ExcalidrawElement = ExcalidrawGenericElement | ExcalidrawStickyNoteElement | ExcalidrawTextElement | ExcalidrawLinearElement | ExcalidrawArrowElement | ExcalidrawFreeDrawElement | ExcalidrawImageElement | ExcalidrawFrameElement | ExcalidrawMagicFrameElement | ExcalidrawIframeElement | ExcalidrawEmbeddableElement;
 export type ExcalidrawNonSelectionElement = Exclude<ExcalidrawElement, ExcalidrawSelectionElement>;
 export type Ordered<TElement extends ExcalidrawElement> = TElement & {
     index: FractionalIndex;
 };
 export type OrderedExcalidrawElement = Ordered<ExcalidrawElement>;
 export type NonDeleted<TElement extends ExcalidrawElement> = TElement & {
-    isDeleted: boolean;
+    isDeleted: false;
 };
 export type NonDeletedExcalidrawElement = NonDeleted<ExcalidrawElement>;
 export type ExcalidrawTextElement = _ExcalidrawElementBase & Readonly<{
     type: "text";
     fontSize: number;
     fontFamily: FontFamilyValues;
+    /**
+     * The font size the user picked, from which the layout derives `fontSize`.
+     * Today only sticky note labels have one: the auto-fit shrinks below it
+     * and never above it (compare `baseHeight`, which the note grows above).
+     * `null` for every other text. Read it through `getBaseFontSize` —
+     * generic binding repair can detach a label without clearing this, so
+     * the container decides its meaning.
+     */
+    baseFontSize: number | null;
     text: string;
     textAlign: TextAlign;
     verticalAlign: VerticalAlign;
-    containerId: ExcalidrawGenericElement["id"] | null;
+    containerId: ExcalidrawTextContainer["id"] | null;
     originalText: string;
     /**
      * If `true` the width will fit the text. If `false`, the text will
@@ -190,9 +212,16 @@ export type ExcalidrawTextElement = _ExcalidrawElementBase & Readonly<{
     lineHeight: number & {
         _brand: "unitlessLineHeight";
     };
+    /**
+     * Position of text bound to a linear element (such as an arrow),
+     * expressed as a normalized arc-length parameter (0–1) along the
+     * container's whole path. Independent of how the path is segmented,
+     * so it survives midpoint insertion and other geometry changes.
+     * */
+    labelPosition?: number | null;
 }>;
-export type ExcalidrawBindableElement = ExcalidrawRectangleElement | ExcalidrawDiamondElement | ExcalidrawEllipseElement | ExcalidrawTextElement | ExcalidrawImageElement | ExcalidrawIframeElement | ExcalidrawEmbeddableElement | ExcalidrawFrameElement | ExcalidrawMagicFrameElement;
-export type ExcalidrawTextContainer = ExcalidrawRectangleElement | ExcalidrawDiamondElement | ExcalidrawEllipseElement | ExcalidrawArrowElement;
+export type ExcalidrawBindableElement = ExcalidrawRectangleElement | ExcalidrawStickyNoteElement | ExcalidrawDiamondElement | ExcalidrawEllipseElement | ExcalidrawTextElement | ExcalidrawImageElement | ExcalidrawIframeElement | ExcalidrawEmbeddableElement | ExcalidrawFrameElement | ExcalidrawMagicFrameElement;
+export type ExcalidrawTextContainer = ExcalidrawRectangleElement | ExcalidrawStickyNoteElement | ExcalidrawDiamondElement | ExcalidrawEllipseElement | ExcalidrawArrowElement;
 export type ExcalidrawTextElementWithContainer = {
     containerId: ExcalidrawTextContainer["id"];
 } & ExcalidrawTextElement;
@@ -208,7 +237,10 @@ export type PointsPositionUpdates = Map<Index, {
     point: LocalPoint;
     isDragging?: boolean;
 }>;
-export type Arrowhead = "arrow" | "bar" | "dot" | "circle" | "circle_outline" | "triangle" | "triangle_outline" | "diamond" | "diamond_outline" | "crowfoot_one" | "crowfoot_many" | "crowfoot_one_or_many";
+export type CardinalityArrowhead = "cardinality_one" | "cardinality_many" | "cardinality_one_or_many" | "cardinality_exactly_one" | "cardinality_zero_or_one" | "cardinality_zero_or_many";
+export type ArrowheadLegacy = "dot" | "crowfoot_one" | "crowfoot_many" | "crowfoot_one_or_many";
+export type Arrowhead = "arrow" | "bar" | "circle" | "circle_outline" | "triangle" | "triangle_outline" | "diamond" | "diamond_outline" | CardinalityArrowhead;
+export type AnyArrowhead = Arrowhead | ArrowheadLegacy;
 export type ExcalidrawLinearElement = _ExcalidrawElementBase & Readonly<{
     type: "line" | "arrow";
     points: readonly LocalPoint[];
@@ -252,11 +284,17 @@ export type ExcalidrawElbowArrowElement = Merge<ExcalidrawArrowElement, {
      */
     endIsSpecial: boolean | null;
 }>;
+export type StrokeVariability = "variable" | "constant";
+export type StrokeOptions = Readonly<{
+    variability: StrokeVariability;
+    streamline: number;
+}>;
 export type ExcalidrawFreeDrawElement = _ExcalidrawElementBase & Readonly<{
     type: "freedraw";
     points: readonly LocalPoint[];
     pressures: readonly number[];
     simulatePressure: boolean;
+    strokeOptions: StrokeOptions;
 }>;
 export type FileId = string & {
     _brand: "FileId";
@@ -284,6 +322,7 @@ export type SceneElementsMap = Map<ExcalidrawElement["id"], Ordered<ExcalidrawEl
  */
 export type NonDeletedSceneElementsMap = Map<ExcalidrawElement["id"], Ordered<NonDeletedExcalidrawElement>> & MakeBrand<"NonDeletedSceneElementsMap">;
 export type ElementsMapOrArray = readonly ExcalidrawElement[] | Readonly<ElementsMap>;
+export type NonDeletedElementsMapOrArray = readonly NonDeletedExcalidrawElement[] | Readonly<NonDeletedElementsMap | NonDeletedSceneElementsMap>;
 export type ExcalidrawLinearElementSubType = "line" | "sharpArrow" | "curvedArrow" | "elbowArrow";
 export type ConvertibleGenericTypes = "rectangle" | "diamond" | "ellipse";
 export type ConvertibleLinearTypes = ExcalidrawLinearElementSubType;

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

@@ -1,14 +1,17 @@
 import { type GlobalPoint } from "@excalidraw/math";
 import type { Curve, LineSegment } from "@excalidraw/math";
-import type { Zoom } from "@excalidraw/excalidraw/types";
-import type { ElementsMap, ExcalidrawArrowElement, ExcalidrawDiamondElement, ExcalidrawElement, ExcalidrawFreeDrawElement, ExcalidrawLinearElement, ExcalidrawRectanguloidElement } from "./types";
+import type { AppState, Zoom } from "@excalidraw/excalidraw/types";
+import type { ElementsMap, ExcalidrawArrowElement, ExcalidrawBindableElement, ExcalidrawDiamondElement, ExcalidrawElement, ExcalidrawFreeDrawElement, ExcalidrawLinearElement, ExcalidrawRectanguloidElement } from "./types";
+export type LinearPathSegment = LineSegment<GlobalPoint> | Curve<GlobalPoint>;
+type ElementShape = [LineSegment<GlobalPoint>[], Curve<GlobalPoint>[]];
 /**
  * Returns the **rotated** components of freedraw, line or arrow elements.
  *
  * @param element The linear element to deconstruct
  * @returns The rotated in components.
  */
-export declare function deconstructLinearOrFreeDrawElement(element: ExcalidrawLinearElement | ExcalidrawFreeDrawElement): [LineSegment<GlobalPoint>[], Curve<GlobalPoint>[]];
+export declare function deconstructLinearOrFreeDrawElement(element: ExcalidrawLinearElement | ExcalidrawFreeDrawElement, elementsMap: ElementsMap): ElementShape;
+export declare function getLinearElementPathSegments(element: ExcalidrawLinearElement | ExcalidrawFreeDrawElement, elementsMap: ElementsMap): LinearPathSegment[];
 /**
  * Get the building components of a rectanguloid element in the form of
  * line segments and curves **unrotated**.
@@ -17,7 +20,8 @@ export declare function deconstructLinearOrFreeDrawElement(element: ExcalidrawLi
  * @param offset Optional offset to expand the rectanguloid shape
  * @returns Tuple of **unrotated** line segments (0) and curves (1)
  */
-export declare function deconstructRectanguloidElement(element: ExcalidrawRectanguloidElement, offset?: number): [LineSegment<GlobalPoint>[], Curve<GlobalPoint>[]];
+export declare function deconstructRectanguloidElement(element: ExcalidrawRectanguloidElement, offset?: number): ElementShape;
+export declare function getDiamondBaseCorners(element: ExcalidrawDiamondElement, offset?: number): Curve<GlobalPoint>[];
 /**
  * Get the **unrotated** building components of a diamond element
  * in the form of line segments and curves as a tuple, in this order.
@@ -26,9 +30,18 @@ export declare function deconstructRectanguloidElement(element: ExcalidrawRectan
  * @param offset An optional offset
  * @returns Tuple of line **unrotated** segments (0) and curves (1)
  */
-export declare function deconstructDiamondElement(element: ExcalidrawDiamondElement, offset?: number): [LineSegment<GlobalPoint>[], Curve<GlobalPoint>[]];
+export declare function deconstructDiamondElement(element: ExcalidrawDiamondElement, offset?: number): ElementShape;
 export declare const isPathALoop: (points: ExcalidrawLinearElement["points"], 
 /** supply if you want the loop detection to account for current zoom */
 zoomValue?: Zoom["value"]) => boolean;
 export declare const getCornerRadius: (x: number, element: ExcalidrawElement) => number;
-export declare const projectFixedPointOntoDiagonal: (arrow: ExcalidrawArrowElement, point: GlobalPoint, element: ExcalidrawElement, startOrEnd: "start" | "end", elementsMap: ElementsMap) => GlobalPoint | null;
+export declare const getAllMidpoints: (element: ExcalidrawBindableElement, elementsMap: ElementsMap) => GlobalPoint[];
+export declare const getElbowArrowSnapMidPoint: (point: GlobalPoint, element: ExcalidrawBindableElement, elementsMap: ElementsMap, zoom: AppState["zoom"]) => {
+    point: GlobalPoint;
+    onAxis: boolean;
+} | undefined;
+export declare const getSnapOutlineMidPoint: (point: GlobalPoint, element: ExcalidrawBindableElement, elementsMap: ElementsMap, zoom: AppState["zoom"], arrow: {
+    elbowed: boolean;
+}) => GlobalPoint | undefined;
+export declare const projectFixedPointOntoDiagonal: (arrow: ExcalidrawArrowElement, point: GlobalPoint, element: ExcalidrawBindableElement, startOrEnd: "start" | "end", elementsMap: ElementsMap, zoom: AppState["zoom"], isMidpointSnappingEnabled?: boolean) => GlobalPoint | null;
+export {};