Enhanced animations API.

examples/with-nextjs/src/excalidrawWrapper.tsx

@@ -1,4 +1,5 @@
 "use client";
+
 import * as excalidrawLib from "@excalidraw/excalidraw";
 import { Excalidraw } from "@excalidraw/excalidraw";
 
@@ -13,6 +14,7 @@ const ExcalidrawWrapper: React.FC = () => {
         appTitle={"Excalidraw with Nextjs Example"}
         useCustom={(api: any, args?: any[]) => {}}
         excalidrawLib={excalidrawLib}
+        showFadeDemo={true}
       >
         <Excalidraw />
       </App>

examples/with-script-in-browser/components/ExampleApp.tsx

@@ -70,6 +70,7 @@ export interface AppProps {
   customArgs?: any[];
   children: React.ReactNode;
   excalidrawLib: typeof TExcalidraw;
+  showFadeDemo?: boolean;
 }
 
 export default function ExampleApp({
@@ -78,6 +79,7 @@ export default function ExampleApp({
   customArgs,
   children,
   excalidrawLib,
+  showFadeDemo = false,
 }: AppProps) {
   const {
     exportToCanvas,
@@ -116,6 +118,19 @@ export default function ExampleApp({
     {},
   );
   const [comment, setComment] = useState<Comment | null>(null);
+  const [hideAllForFadeDemo, setHideAllForFadeDemo] = useState(false);
+  const [fadeDemoNextIndex, setFadeDemoNextIndex] = useState(0);
+  const [fadeDemoElementIds, setFadeDemoElementIds] = useState<string[]>([]);
+  const [demoAnimationType, setDemoAnimationType] = useState<"fade" | "fly">(
+    "fade",
+  );
+  const [demoAnimationDuration, setDemoAnimationDuration] = useState(500);
+  const [demoFlyFrom, setDemoFlyFrom] = useState<
+    "left" | "right" | "top" | "bottom"
+  >("left");
+  const [demoAnimationEasing, setDemoAnimationEasing] = useState<
+    "linear" | "easeOut" | "easeInOut"
+  >("easeOut");
 
   const initialStatePromiseRef = useRef<{
     promise: ResolvablePromise<ExcalidrawInitialDataState | null>;
@@ -178,7 +193,8 @@ export default function ExampleApp({
     const newElement = cloneElement(
       Excalidraw,
       {
-        excalidrawAPI: (api: ExcalidrawImperativeAPI) => setExcalidrawAPI(api),
+        onExcalidrawAPI: (api: ExcalidrawImperativeAPI | null) =>
+          setExcalidrawAPI(api),
         initialData: initialStatePromiseRef.current.promise,
         onChange: (
           elements: NonDeletedExcalidrawElement[],
@@ -208,6 +224,10 @@ export default function ExampleApp({
         onPointerDown,
         onScrollChange: rerenderCommentIcons,
         validateEmbeddable: true,
+        resolveRenderOpacity: hideAllForFadeDemo
+          ? (element: NonDeletedExcalidrawElement) =>
+              fadeDemoElementIds.includes(element.id) ? 0 : undefined
+          : undefined,
       },
       <>
         {excalidrawAPI && (
@@ -664,6 +684,229 @@ export default function ExampleApp({
           >
             Reset Scene
           </button>
+          {showFadeDemo && (
+            <>
+              <label>
+                Animation type
+                <select
+                  value={demoAnimationType}
+                  onChange={(event) =>
+                    setDemoAnimationType(
+                      event.target.value as "fade" | "fly",
+                    )
+                  }
+                >
+                  <option value="fade">fade</option>
+                  <option value="fly">fly</option>
+                </select>
+              </label>
+              <label>
+                Duration
+                <input
+                  type="number"
+                  value={demoAnimationDuration}
+                  onChange={(event) =>
+                    setDemoAnimationDuration(Number(event.target.value) || 0)
+                  }
+                />
+              </label>
+              <label>
+                Easing
+                <select
+                  value={demoAnimationEasing}
+                  onChange={(event) =>
+                    setDemoAnimationEasing(
+                      event.target.value as "linear" | "easeOut" | "easeInOut",
+                    )
+                  }
+                >
+                  <option value="linear">linear</option>
+                  <option value="easeOut">easeOut</option>
+                  <option value="easeInOut">easeInOut</option>
+                </select>
+              </label>
+              {demoAnimationType === "fly" && (
+                <label>
+                  Fly from
+                  <select
+                    value={demoFlyFrom}
+                    onChange={(event) =>
+                      setDemoFlyFrom(
+                        event.target.value as
+                          | "left"
+                          | "right"
+                          | "top"
+                          | "bottom",
+                      )
+                    }
+                  >
+                    <option value="left">left</option>
+                    <option value="right">right</option>
+                    <option value="top">top</option>
+                    <option value="bottom">bottom</option>
+                  </select>
+                </label>
+              )}
+              <button
+                onClick={() => {
+                  if (!excalidrawAPI) {
+                    return;
+                  }
+
+                  setFadeDemoElementIds(
+                    excalidrawAPI
+                      .getSceneElements()
+                      .map((element) => element.id),
+                  );
+                  excalidrawAPI.clearElementAnimationOverrides();
+                  setHideAllForFadeDemo(true);
+                  setFadeDemoNextIndex(0);
+                }}
+              >
+                Hide every element
+              </button>
+              <button
+                onClick={() => {
+                  if (!excalidrawAPI || !hideAllForFadeDemo) {
+                    return;
+                  }
+
+                  const elements = excalidrawAPI
+                    .getSceneElements()
+                    .filter((element) =>
+                      fadeDemoElementIds.includes(element.id),
+                    );
+
+                  if (!elements.length) {
+                    return;
+                  }
+
+                  const nextIndex =
+                    fadeDemoNextIndex >= elements.length
+                      ? 0
+                      : fadeDemoNextIndex;
+
+                  if (nextIndex === 0) {
+                    excalidrawAPI.clearElementAnimationOverrides();
+                  }
+
+                  if (demoAnimationType === "fly") {
+                    excalidrawAPI.animateElements({
+                      elements: [elements[nextIndex].id],
+                      type: "fly",
+                      from: demoFlyFrom,
+                      duration: demoAnimationDuration,
+                      phase: "in",
+                      easing: demoAnimationEasing,
+                    });
+                  } else {
+                    excalidrawAPI.animateElements({
+                      elements: [elements[nextIndex].id],
+                      type: "fade",
+                      duration: demoAnimationDuration,
+                      phase: "in",
+                      easing: demoAnimationEasing,
+                    });
+                  }
+
+                  setFadeDemoNextIndex(nextIndex + 1);
+                }}
+              >
+                Animate in next element
+              </button>
+              <button
+                onClick={() => {
+                  if (!excalidrawAPI || !hideAllForFadeDemo) {
+                    return;
+                  }
+
+                  const elements = excalidrawAPI
+                    .getSceneElements()
+                    .filter((element) =>
+                      fadeDemoElementIds.includes(element.id),
+                    );
+
+                  if (!elements.length) {
+                    return;
+                  }
+
+                  if (demoAnimationType === "fly") {
+                    excalidrawAPI.animateElements({
+                      elements,
+                      type: "fly",
+                      from: demoFlyFrom,
+                      duration: demoAnimationDuration,
+                      stagger: 120,
+                      phase: "in",
+                      easing: demoAnimationEasing,
+                    });
+                  } else {
+                    excalidrawAPI.animateElements({
+                      elements,
+                      type: "fade",
+                      duration: demoAnimationDuration,
+                      stagger: 120,
+                      phase: "in",
+                      easing: demoAnimationEasing,
+                    });
+                  }
+
+                  setFadeDemoNextIndex(elements.length);
+                }}
+              >
+                Animate in all
+              </button>
+              <button
+                onClick={() => {
+                  if (!excalidrawAPI || !hideAllForFadeDemo) {
+                    return;
+                  }
+
+                  const elements = excalidrawAPI
+                    .getSceneElements()
+                    .filter((element) =>
+                      fadeDemoElementIds.includes(element.id),
+                    );
+
+                  if (!elements.length) {
+                    return;
+                  }
+
+                  const prevIndex = Math.min(
+                    fadeDemoNextIndex - 1,
+                    elements.length - 1,
+                  );
+
+                  if (prevIndex < 0) {
+                    return;
+                  }
+
+                  if (demoAnimationType === "fly") {
+                    excalidrawAPI.animateElements({
+                      elements: [elements[prevIndex].id],
+                      type: "fly",
+                      from: demoFlyFrom,
+                      duration: demoAnimationDuration,
+                      phase: "out",
+                      easing: demoAnimationEasing,
+                    });
+                  } else {
+                    excalidrawAPI.animateElements({
+                      elements: [elements[prevIndex].id],
+                      type: "fade",
+                      duration: demoAnimationDuration,
+                      phase: "out",
+                      easing: demoAnimationEasing,
+                    });
+                  }
+
+                  setFadeDemoNextIndex(prevIndex);
+                }}
+              >
+                Animate out prev element
+              </button>
+            </>
+          )}
           <button
             onClick={() => {
               const libraryItems: LibraryItems = [

examples/with-script-in-browser/initialData.tsx

@@ -2,6 +2,28 @@ import type { ExcalidrawElementSkeleton } from "@excalidraw/excalidraw/element/t
 import type { FileId } from "@excalidraw/excalidraw/element/types";
 
 const elements: ExcalidrawElementSkeleton[] = [
+  // {
+  //   type: "arrow",
+  //   x: 100,
+  //   y: 500,
+  // },
+  // {
+  //   type: "arrow",
+  //   x: 250,
+  //   y: 250,
+  //   label: {
+  //     text: "HELLO WORLD!!",
+  //   },
+  //   start: {
+  //     type: "rectangle",
+  //     // x: -100,
+  //   },
+  //   end: {
+  //     type: "ellipse",
+  //     // x: 300,
+  //   },
+  // },
+
   {
     type: "rectangle",
     x: 10,
@@ -22,14 +44,14 @@ const elements: ExcalidrawElementSkeleton[] = [
     },
     id: "2",
   },
-  {
-    type: "arrow",
-    x: 100,
-    y: 200,
-    label: { text: "HELLO WORLD!!" },
-    start: { type: "rectangle" },
-    end: { type: "ellipse" },
-  },
+  // {
+  //   type: "arrow",
+  //   x: 100,
+  //   y: 200,
+  //   label: { text: "HELLO WORLD!!" },
+  //   start: { type: "rectangle" },
+  //   end: { type: "ellipse" },
+  // },
   {
     type: "image",
     x: 606.1042326312408,
@@ -38,11 +60,11 @@ const elements: ExcalidrawElementSkeleton[] = [
     height: 230,
     fileId: "rocket" as FileId,
   },
-  {
-    type: "frame",
-    children: ["1", "2"],
-    name: "My frame",
-  },
+  // {
+  //   type: "frame",
+  //   children: ["1", "2"],
+  //   name: "My frame",
+  // },
 ];
 export default {
   elements,

packages/element/src/arrows/focus.ts

@@ -27,7 +27,6 @@ import type {
   ElementsMap,
   ExcalidrawArrowElement,
   ExcalidrawBindableElement,
-  FixedPointBinding,
   NonDeletedSceneElementsMap,
   PointsPositionUpdates,
 } from "../types";
@@ -111,17 +110,10 @@ const focusPointUpdate = (
 ) => {
   const pointUpdates = new Map();
 
-  const originalAdjacentBinding =
-    appState.selectedLinearElement?.initialState
-      .arrowOtherEndpointInitialBinding;
   const bindingField = isStartBinding ? "startBinding" : "endBinding";
   const adjacentBindingField = isStartBinding ? "endBinding" : "startBinding";
   let currentBinding = arrow[bindingField];
-  let adjacentBinding =
-    originalAdjacentBinding?.mode === "orbit" &&
-    arrow[adjacentBindingField]?.mode === "inside"
-      ? originalAdjacentBinding
-      : arrow[adjacentBindingField];
+  let adjacentBinding = arrow[adjacentBindingField];
 
   // Update the dragged focus point related end
   if (currentBinding && bindableElement) {
@@ -171,7 +163,7 @@ const focusPointUpdate = (
       // Same shape bound on both ends
       const boundToSameElementAfterUpdate =
         bindableElement && adjacentBinding.elementId === bindableElement.id;
-      if (boundToSameElementAfterUpdate) {
+      if (switchToInsideBinding || boundToSameElementAfterUpdate) {
         adjacentBinding = {
           ...adjacentBinding,
           mode: "inside",
@@ -347,7 +339,6 @@ export const handleFocusPointPointerDown = (
 ): {
   hitFocusPoint: "start" | "end" | null;
   pointerOffset: { x: number; y: number };
-  arrowOtherEndpointInitialBinding: FixedPointBinding | null;
 } => {
   const pointerPos = pointFrom(
     pointerDownState.origin.x,
@@ -385,7 +376,6 @@ export const handleFocusPointPointerDown = (
             x: pointerPos[0] - focusPoint[0],
             y: pointerPos[1] - focusPoint[1],
           },
-          arrowOtherEndpointInitialBinding: arrow.endBinding,
         };
       }
     }
@@ -421,7 +411,6 @@ export const handleFocusPointPointerDown = (
             x: pointerPos[0] - focusPoint[0],
             y: pointerPos[1] - focusPoint[1],
           },
-          arrowOtherEndpointInitialBinding: arrow.startBinding,
         };
       }
     }
@@ -430,14 +419,13 @@ export const handleFocusPointPointerDown = (
   return {
     hitFocusPoint: null,
     pointerOffset: { x: 0, y: 0 },
-    arrowOtherEndpointInitialBinding: null,
   };
 };
 
 export const handleFocusPointPointerUp = (
   linearElementEditor: LinearElementEditor,
   scene: Scene,
-): { arrowOtherEndpointInitialBinding: FixedPointBinding | null } => {
+) => {
   invariant(
     linearElementEditor.draggedFocusPointBinding,
     "Must have a dragged focus point at pointer release",
@@ -495,10 +483,6 @@ export const handleFocusPointPointerUp = (
       ],
     });
   }
-
-  return {
-    arrowOtherEndpointInitialBinding: null,
-  };
 };
 
 export const handleFocusPointHover = (

packages/element/src/binding.ts

@@ -694,7 +694,6 @@ const getBindingStrategyForDraggingBindingElementEndpoints_simple = (
     localPoint,
     elementsMap,
   );
-
   const hit = getHoveredElementForBinding(
     globalPoint,
     elements,
@@ -749,15 +748,6 @@ const getBindingStrategyForDraggingBindingElementEndpoints_simple = (
           : // NOTE: Can only affect the start point because new arrows always drag the end point
           opts?.newArrow
           ? appState.selectedLinearElement!.initialState.origin!
-          : otherBindableElement &&
-            appState.selectedLinearElement?.initialState
-              ?.arrowOtherEndpointInitialBinding?.fixedPoint
-          ? getGlobalFixedPointForBindableElement(
-              appState.selectedLinearElement?.initialState
-                .arrowOtherEndpointInitialBinding.fixedPoint,
-              otherBindableElement,
-              elementsMap,
-            )
           : LinearElementEditor.getPointAtIndexGlobalCoordinates(
               arrow,
               0,
@@ -769,15 +759,6 @@ const getBindingStrategyForDraggingBindingElementEndpoints_simple = (
         element: hit,
         focusPoint: endDragged
           ? globalPoint
-          : otherBindableElement &&
-            appState.selectedLinearElement?.initialState
-              ?.arrowOtherEndpointInitialBinding?.fixedPoint
-          ? getGlobalFixedPointForBindableElement(
-              appState.selectedLinearElement?.initialState
-                .arrowOtherEndpointInitialBinding.fixedPoint,
-              otherBindableElement,
-              elementsMap,
-            )
           : LinearElementEditor.getPointAtIndexGlobalCoordinates(
               arrow,
               -1,
@@ -850,57 +831,36 @@ const getBindingStrategyForDraggingBindingElementEndpoints_simple = (
       threshold: maxBindingDistance_simple(appState.zoom),
       overrideShouldTestInside: true,
     });
-  const otherPointWasInsideAtStart =
-    appState.selectedLinearElement?.initialState
-      .arrowOtherEndpointInitialBinding?.mode === "inside";
   const otherNeverOverride = opts?.newArrow
     ? appState.selectedLinearElement?.initialState.arrowStartIsInside
-    : otherBinding?.mode === "inside" && otherPointWasInsideAtStart;
-
-  let other: BindingStrategy = { mode: undefined };
-  if (!otherNeverOverride) {
-    if (
-      otherBinding?.mode === "inside" &&
-      !otherPointWasInsideAtStart &&
-      otherBindableElement
-    ) {
-      other = {
-        mode: "orbit",
-        element: otherBindableElement,
-        focusPoint: getGlobalFixedPointForBindableElement(
-          otherBinding.fixedPoint,
-          otherBindableElement,
-          elementsMap,
-        ),
-      };
-    } else if (
-      otherBindableElement &&
+    : otherBinding?.mode === "inside";
+  const other: BindingStrategy = !otherNeverOverride
+    ? otherBindableElement &&
       !otherFocusPointIsInElement &&
       !pointIsCloseToOtherElement &&
       appState.selectedLinearElement?.initialState.altFocusPoint
-    ) {
-      other = {
-        mode: "orbit",
-        element: otherBindableElement,
-        focusPoint: appState.selectedLinearElement.initialState.altFocusPoint,
-      };
-    } else if (opts?.angleLocked && otherBindableElement) {
-      other = {
-        mode: "orbit",
-        element: otherBindableElement,
-        focusPoint:
-          projectFixedPointOntoDiagonal(
-            arrow,
-            otherEndpoint,
-            otherBindableElement,
-            startDragged ? "end" : "start",
-            elementsMap,
-            appState.zoom,
-            appState.isMidpointSnappingEnabled,
-          ) || otherEndpoint,
-      };
-    }
-  }
+      ? {
+          mode: "orbit",
+          element: otherBindableElement,
+          focusPoint: appState.selectedLinearElement.initialState.altFocusPoint,
+        }
+      : opts?.angleLocked && otherBindableElement
+      ? {
+          mode: "orbit",
+          element: otherBindableElement,
+          focusPoint:
+            projectFixedPointOntoDiagonal(
+              arrow,
+              otherEndpoint,
+              otherBindableElement,
+              startDragged ? "end" : "start",
+              elementsMap,
+              appState.zoom,
+              appState.isMidpointSnappingEnabled,
+            ) || otherEndpoint,
+        }
+      : { mode: undefined }
+    : { mode: undefined };
 
   return {
     start: startDragged ? current : other,

packages/element/src/linearElementEditor.ts

@@ -141,7 +141,6 @@ export class LinearElementEditor {
     };
     arrowStartIsInside: boolean;
     altFocusPoint: Readonly<GlobalPoint> | null;
-    arrowOtherEndpointInitialBinding: FixedPointBinding | null;
   }>;
 
   /** whether you're dragging a point */
@@ -194,7 +193,6 @@ export class LinearElementEditor {
         added: false,
       },
       arrowStartIsInside: false,
-      arrowOtherEndpointInitialBinding: null,
       altFocusPoint: null,
     };
     this.hoverPointIndex = -1;
@@ -766,7 +764,6 @@ export class LinearElementEditor {
         ...editingLinearElement.initialState,
         origin: null,
         arrowStartIsInside: false,
-        arrowOtherEndpointInitialBinding: null,
       },
     };
   }
@@ -1088,7 +1085,6 @@ export class LinearElementEditor {
             !!app.state.newElement &&
             (app.state.bindMode === "inside" || app.state.bindMode === "skip"),
           altFocusPoint: null,
-          arrowOtherEndpointInitialBinding: element.startBinding,
         },
         selectedPointsIndices: [element.points.length - 1],
         lastUncommittedPoint: null,
@@ -1151,9 +1147,6 @@ export class LinearElementEditor {
           !!app.state.newElement &&
           (app.state.bindMode === "inside" || app.state.bindMode === "skip"),
         altFocusPoint: null,
-        arrowOtherEndpointInitialBinding: nextSelectedPointsIndices?.includes(0)
-          ? element.endBinding
-          : element.startBinding,
       },
       selectedPointsIndices: nextSelectedPointsIndices,
       pointerOffset: targetPoint
@@ -2416,21 +2409,22 @@ const pointDraggingUpdates = (
       )! as ExcalidrawBindableElement)
     : null;
 
-  const endLocalPoint =
-    endIsDraggingOverStartElement &&
-    app.state.bindMode !== "inside" &&
-    getFeatureFlag("COMPLEX_BINDINGS")
-      ? nextArrow.points[0]
-      : endBindable
-      ? updateBoundPoint(
-          nextArrow,
-          "endBinding",
-          nextArrow.endBinding,
-          endBindable,
-          elementsMap,
-          endIsDragged,
-        ) || nextArrow.points[nextArrow.points.length - 1]
-      : nextArrow.points[nextArrow.points.length - 1];
+  const endLocalPoint = startIsDraggingOverEndElement
+    ? nextArrow.points[nextArrow.points.length - 1]
+    : endIsDraggingOverStartElement &&
+      app.state.bindMode !== "inside" &&
+      getFeatureFlag("COMPLEX_BINDINGS")
+    ? nextArrow.points[0]
+    : endBindable
+    ? updateBoundPoint(
+        nextArrow,
+        "endBinding",
+        nextArrow.endBinding,
+        endBindable,
+        elementsMap,
+        endIsDragged,
+      ) || nextArrow.points[nextArrow.points.length - 1]
+    : nextArrow.points[nextArrow.points.length - 1];
 
   // We need to keep the simulated next arrow up-to-date, because
   // updateBoundPoint looks at the opposite point
@@ -2464,11 +2458,13 @@ const pointDraggingUpdates = (
       : nextArrow.points[0];
 
   const endChanged =
+    !startIsDraggingOverEndElement &&
     !(
       endIsDraggingOverStartElement &&
       app.state.bindMode !== "inside" &&
       getFeatureFlag("COMPLEX_BINDINGS")
-    ) && !!endBindable;
+    ) &&
+    !!endBindable;
   const startChanged =
     pointDistance(startLocalPoint, nextArrow.points[0]) !== 0;
 

packages/element/src/renderElement.ts

@@ -1,6 +1,7 @@
 import rough from "roughjs/bin/rough";
 
 import {
+  clamp,
   type GlobalPoint,
   isRightAngleRads,
   lineSegment,
@@ -105,8 +106,62 @@ const getCanvasPadding = (element: ExcalidrawElement) => {
   }
 };
 
+export const resolveRenderOpacity = (
+  element: ExcalidrawElement,
+  renderConfig: Pick<
+    StaticCanvasRenderConfig,
+    "elementOpacityOverrides" | "resolveRenderOpacity"
+  >,
+) => {
+  const override = renderConfig.elementOpacityOverrides?.get(element.id);
+
+  if (override !== undefined) {
+    return clamp(override, 0, 100);
+  }
+
+  const resolvedOpacity = renderConfig.resolveRenderOpacity?.(
+    element as NonDeletedExcalidrawElement,
+  );
+
+  if (resolvedOpacity !== undefined) {
+    return clamp(resolvedOpacity, 0, 100);
+  }
+
+  return element.opacity;
+};
+
+export const resolveRenderPositionOffset = (
+  element: ExcalidrawElement,
+  renderConfig: Pick<StaticCanvasRenderConfig, "elementPositionOverrides">,
+) => {
+  return renderConfig.elementPositionOverrides?.get(element.id) ?? { x: 0, y: 0 };
+};
+
+export const getRenderElementWithPositionOverride = <
+  TElement extends NonDeletedExcalidrawElement,
+>(
+  element: TElement,
+  renderConfig: Pick<StaticCanvasRenderConfig, "elementPositionOverrides">,
+): TElement => {
+  const positionOffset = resolveRenderPositionOffset(element, renderConfig);
+
+  if (positionOffset.x === 0 && positionOffset.y === 0) {
+    return element;
+  }
+
+  return {
+    ...element,
+    x: element.x + positionOffset.x,
+    y: element.y + positionOffset.y,
+  } as TElement;
+};
+
 export const getRenderOpacity = (
   element: ExcalidrawElement,
+  renderConfig: Pick<
+    StaticCanvasRenderConfig,
+    "elementOpacityOverrides" | "resolveRenderOpacity"
+  >,
   containingFrame: ExcalidrawFrameLikeElement | null,
   elementsPendingErasure: ElementsPendingErasure,
   pendingNodes: Readonly<PendingExcalidrawElements> | null,
@@ -115,7 +170,8 @@ export const getRenderOpacity = (
   // multiplying frame opacity with element opacity to combine them
   // (e.g. frame 50% and element 50% opacity should result in 25% opacity)
   let opacity =
-    (((containingFrame?.opacity ?? 100) * element.opacity) / 10000) *
+    (((containingFrame?.opacity ?? 100) * resolveRenderOpacity(element, renderConfig)) /
+      10000) *
     globalAlpha;
 
   // if pending erasure, multiply again to combine further
@@ -791,8 +847,11 @@ export const renderElement = (
     !appState.selectedElementIds[element.id] &&
     !appState.hoveredElementIds[element.id];
 
+  element = getRenderElementWithPositionOverride(element, renderConfig);
+
   context.globalAlpha = getRenderOpacity(
     element,
+    renderConfig,
     getContainingFrame(element, elementsMap),
     renderConfig.elementsPendingErasure,
     renderConfig.pendingFlowchartNodes,

packages/excalidraw/components/App.tsx

@@ -207,10 +207,12 @@ import {
   getLineHeightInPx,
   getApproxMinLineWidth,
   getApproxMinLineHeight,
-  getMinTextElementWidth,
-  ShapeCache,
-  getRenderOpacity,
-  editGroupForSelectedElement,
+   getMinTextElementWidth,
+   ShapeCache,
+   getRenderOpacity,
+   resolveRenderPositionOffset,
+   resolveRenderOpacity,
+   editGroupForSelectedElement,
   getElementsInGroup,
   getSelectedGroupIdForElement,
   getSelectedGroupIds,
@@ -450,6 +452,7 @@ import { searchItemInFocusAtom } from "./SearchMenu";
 import { isSidebarDockedAtom } from "./Sidebar/Sidebar";
 import { StaticCanvas, InteractiveCanvas } from "./canvases";
 import NewElementCanvas from "./canvases/NewElementCanvas";
+import { AnimationController } from "../renderer/animation";
 import { isPointHittingLink } from "./hyperlink/helpers";
 import { MagicIcon, copyIcon, fullscreenIcon } from "./icons";
 import { AppStateObserver, type OnStateChange } from "./AppStateObserver";
@@ -740,6 +743,235 @@ class App extends React.Component<AppProps, AppState> {
   onRemoveEventListenersEmitter = new Emitter<[]>();
 
   api: ExcalidrawImperativeAPI;
+  private renderAnimationVersion = 0;
+  private elementOpacityOverrides = new Map<string, number>();
+  private elementPositionOverrides = new Map<string, { x: number; y: number }>();
+  private elementAnimationStates = new Map<
+    string,
+    {
+      opacityFrom: number;
+      opacityTo: number;
+      positionFrom: { x: number; y: number };
+      positionTo: { x: number; y: number };
+      easing: "linear" | "easeOut" | "easeInOut";
+      duration: number;
+      delay: number;
+      elapsed: number;
+    }
+  >();
+
+  private getElementAnimationKey = () => `${this.id}:animate-element`;
+
+  private bumpRenderAnimationVersion = () => {
+    this.renderAnimationVersion++;
+    this.setState({});
+  };
+
+  private getRenderOpacityConfig = () => ({
+    elementOpacityOverrides: this.elementOpacityOverrides,
+    elementPositionOverrides: this.elementPositionOverrides,
+    resolveRenderOpacity: this.props.resolveRenderOpacity,
+  });
+
+  private getResolvedElementOpacity = (element: NonDeletedExcalidrawElement) => {
+    return resolveRenderOpacity(element, this.getRenderOpacityConfig());
+  };
+
+  private getElementVisibleOpacity = (element: NonDeletedExcalidrawElement) => {
+    return clamp(element.opacity, 0, 100);
+  };
+
+  private applyAnimationEasing = (
+    progress: number,
+    easing: "linear" | "easeOut" | "easeInOut",
+  ) => {
+    switch (easing) {
+      case "linear":
+        return progress;
+      case "easeOut":
+        return easeOut(progress);
+      case "easeInOut":
+        return progress < 0.5
+          ? 4 * progress * progress * progress
+          : 1 - Math.pow(-2 * progress + 2, 3) / 2;
+    }
+  };
+
+  private getFlyPositionOffset = (
+    element: NonDeletedExcalidrawElement,
+    from: "left" | "right" | "top" | "bottom",
+  ) => {
+    const [x1, y1, x2, y2] = getElementAbsoluteCoords(
+      element,
+      this.scene.getNonDeletedElementsMap(),
+    );
+    const viewportWidth = this.state.width / this.state.zoom.value;
+    const viewportHeight = this.state.height / this.state.zoom.value;
+    const elementWidth = x2 - x1;
+    const elementHeight = y2 - y1;
+
+    switch (from) {
+      case "left":
+        return { x: -(Math.max(viewportWidth, elementWidth) + 64), y: 0 };
+      case "right":
+        return { x: Math.max(viewportWidth, elementWidth) + 64, y: 0 };
+      case "top":
+        return { x: 0, y: -(Math.max(viewportHeight, elementHeight) + 64) };
+      case "bottom":
+        return { x: 0, y: Math.max(viewportHeight, elementHeight) + 64 };
+    }
+  };
+
+  private animateElement = ({
+    id,
+    opacityFrom,
+    opacityTo,
+    positionFrom = { x: 0, y: 0 },
+    positionTo = { x: 0, y: 0 },
+    easing,
+    duration,
+    delay,
+  }: {
+    id: string;
+    opacityFrom: number;
+    opacityTo: number;
+    positionFrom?: { x: number; y: number };
+    positionTo?: { x: number; y: number };
+    easing: "linear" | "easeOut" | "easeInOut";
+    duration: number;
+    delay: number;
+  }) => {
+    const normalizedOpacityFrom = clamp(opacityFrom, 0, 100);
+    const normalizedOpacityTo = clamp(opacityTo, 0, 100);
+    const normalizedDuration = Math.max(duration, 0);
+    const normalizedDelay = Math.max(delay, 0);
+
+    this.elementOpacityOverrides.set(id, normalizedOpacityFrom);
+
+    if (positionFrom.x !== 0 || positionFrom.y !== 0) {
+      this.elementPositionOverrides.set(id, positionFrom);
+    } else {
+      this.elementPositionOverrides.delete(id);
+    }
+
+    if (normalizedDuration === 0 && normalizedDelay === 0) {
+      this.elementAnimationStates.delete(id);
+      this.elementOpacityOverrides.set(id, normalizedOpacityTo);
+
+      if (positionTo.x !== 0 || positionTo.y !== 0) {
+        this.elementPositionOverrides.set(id, positionTo);
+      } else {
+        this.elementPositionOverrides.delete(id);
+      }
+
+      this.bumpRenderAnimationVersion();
+      return;
+    }
+
+    this.elementAnimationStates.set(id, {
+      opacityFrom: normalizedOpacityFrom,
+      opacityTo: normalizedOpacityTo,
+      positionFrom,
+      positionTo,
+      easing,
+      duration: normalizedDuration,
+      delay: normalizedDelay,
+      elapsed: 0,
+    });
+
+    this.bumpRenderAnimationVersion();
+    this.syncElementAnimations();
+  };
+
+  private syncElementAnimations = () => {
+    const animationKey = this.getElementAnimationKey();
+
+    if (this.elementAnimationStates.size === 0) {
+      AnimationController.cancel(animationKey);
+      return;
+    }
+
+    if (AnimationController.running(animationKey)) {
+      return;
+    }
+
+    AnimationController.start(animationKey, ({ deltaTime }) => {
+      let shouldRerender = false;
+
+      for (const [id, animation] of this.elementAnimationStates) {
+        const element = this.scene.getNonDeletedElement(id);
+
+        if (!element) {
+          this.elementAnimationStates.delete(id);
+          shouldRerender =
+            this.elementOpacityOverrides.delete(id) || shouldRerender;
+          shouldRerender =
+            this.elementPositionOverrides.delete(id) || shouldRerender;
+          continue;
+        }
+
+        animation.elapsed += deltaTime;
+
+        const progress =
+          animation.elapsed <= animation.delay
+            ? 0
+            : animation.duration === 0
+              ? 1
+              : Math.min(
+                  (animation.elapsed - animation.delay) / animation.duration,
+                  1,
+                );
+        const easedProgress = this.applyAnimationEasing(
+          progress,
+          animation.easing,
+        );
+
+        const nextOpacity =
+          animation.opacityFrom +
+          (animation.opacityTo - animation.opacityFrom) * easedProgress;
+        const nextPosition = {
+          x:
+            animation.positionFrom.x +
+            (animation.positionTo.x - animation.positionFrom.x) * easedProgress,
+          y:
+            animation.positionFrom.y +
+            (animation.positionTo.y - animation.positionFrom.y) * easedProgress,
+        };
+
+        const clampedOpacity = clamp(nextOpacity, 0, 100);
+
+        if (this.elementOpacityOverrides.get(id) !== clampedOpacity) {
+          this.elementOpacityOverrides.set(id, clampedOpacity);
+          shouldRerender = true;
+        }
+
+        const currentPositionOverride =
+          this.elementPositionOverrides.get(id) ?? ({ x: 0, y: 0 } as const);
+
+        if (
+          currentPositionOverride.x !== nextPosition.x ||
+          currentPositionOverride.y !== nextPosition.y
+        ) {
+          if (nextPosition.x === 0 && nextPosition.y === 0) {
+            this.elementPositionOverrides.delete(id);
+          } else {
+            this.elementPositionOverrides.set(id, nextPosition);
+          }
+          shouldRerender = true;
+        }
+
+        if (animation.elapsed >= animation.delay + animation.duration) {
+          this.elementAnimationStates.delete(id);
+        }
+      }
+
+      if (shouldRerender) {
+        this.bumpRenderAnimationVersion();
+      }
+
+      return this.elementAnimationStates.size > 0 ? {} : undefined;
+    });
+  };
 
   private createExcalidrawAPI(): ExcalidrawImperativeAPI {
     const api: ExcalidrawImperativeAPI = {
@@ -757,6 +989,9 @@ class App extends React.Component<AppProps, AppState> {
         clear: this.resetHistory,
       },
       scrollToContent: this.scrollToContent,
+      animateElements: this.animateElements,
+      cancelElementAnimation: this.cancelElementAnimation,
+      clearElementAnimationOverrides: this.clearElementAnimationOverrides,
       getSceneElements: this.getSceneElements,
       getAppState: () => this.state,
       getFiles: () => this.files,
@@ -1734,6 +1969,10 @@ class App extends React.Component<AppProps, AppState> {
           const isHovered =
             this.state.activeEmbeddable?.element === el &&
             this.state.activeEmbeddable?.state === "hover";
+          const renderPositionOffset = resolveRenderPositionOffset(
+            el,
+            this.getRenderOpacityConfig(),
+          );
 
           // scale video embeds based on zoom (capped) so that smaller embeds
           // on canvas when zoomed are still of legible quality
@@ -1755,13 +1994,14 @@ class App extends React.Component<AppProps, AppState> {
               })}
               style={{
                 transform: isVisible
-                  ? `translate(${x - this.state.offsetLeft}px, ${
-                      y - this.state.offsetTop
+                  ? `translate(${x + renderPositionOffset.x * this.state.zoom.value - this.state.offsetLeft}px, ${
+                      y + renderPositionOffset.y * this.state.zoom.value - this.state.offsetTop
                     }px) scale(${scale})`
                   : "none",
                 display: isVisible ? "block" : "none",
                 opacity: getRenderOpacity(
                   el,
+                  this.getRenderOpacityConfig(),
                   getContainingFrame(el, this.scene.getNonDeletedElementsMap()),
                   this.elementsPendingErasure,
                   null,
@@ -2351,6 +2591,9 @@ class App extends React.Component<AppProps, AppState> {
                               pendingFlowchartNodes:
                                 this.flowChartCreator.pendingNodes,
                               theme: this.state.theme,
+                              ...this.getRenderOpacityConfig(),
+                              renderAnimationVersion:
+                                this.renderAnimationVersion,
                             }}
                           />
                           {newElementCanvasElement && (
@@ -2373,6 +2616,9 @@ class App extends React.Component<AppProps, AppState> {
                                   this.elementsPendingErasure,
                                 pendingFlowchartNodes: null,
                                 theme: this.state.theme,
+                                ...this.getRenderOpacityConfig(),
+                                renderAnimationVersion:
+                                  this.renderAnimationVersion,
                               }}
                             />
                           )}
@@ -3206,6 +3452,7 @@ class App extends React.Component<AppProps, AppState> {
     this.editorLifecycleEvents.emit("editor:unmount");
     this.props.onUnmount?.();
     this.props.onExcalidrawAPI?.(null);
+    AnimationController.cancel(this.getElementAnimationKey());
 
     (window as any).launchQueue?.setConsumer(() => {});
 
@@ -4618,6 +4865,98 @@ class App extends React.Component<AppProps, AppState> {
     },
   );
 
+  public animateElements = ({
+    elements,
+    duration = 250,
+    delay = 0,
+    stagger = 0,
+    phase = "in",
+    easing,
+    ...animation
+  }:
+    | {
+        elements: readonly (ExcalidrawElement | ExcalidrawElement["id"])[];
+        type: "fade";
+        duration?: number;
+        delay?: number;
+        stagger?: number;
+        phase?: "in" | "out";
+        easing?: "linear" | "easeOut" | "easeInOut";
+      }
+    | {
+        elements: readonly (ExcalidrawElement | ExcalidrawElement["id"])[];
+        type: "fly";
+        from: "left" | "right" | "top" | "bottom";
+        duration?: number;
+        delay?: number;
+        stagger?: number;
+        phase?: "in" | "out";
+        easing?: "linear" | "easeOut" | "easeInOut";
+      }) => {
+    const normalizedDelay = Math.max(delay, 0);
+    const normalizedStagger = Math.max(stagger, 0);
+
+    elements.forEach((elementOrId, index) => {
+      const id = typeof elementOrId === "string" ? elementOrId : elementOrId.id;
+      const element = this.scene.getNonDeletedElement(id);
+
+      if (!element) {
+        return;
+      }
+
+      if (animation.type === "fade") {
+        this.animateElement({
+          id,
+          opacityFrom:
+            phase === "in" ? 0 : this.getElementVisibleOpacity(element),
+          opacityTo:
+            phase === "in" ? this.getElementVisibleOpacity(element) : 0,
+          easing: easing ?? "easeInOut",
+          duration,
+          delay: normalizedDelay + index * normalizedStagger,
+        });
+        return;
+      }
+
+      const flyOffset = this.getFlyPositionOffset(element, animation.from);
+
+      this.animateElement({
+        id,
+        opacityFrom: phase === "in" ? 0 : this.getElementVisibleOpacity(element),
+        opacityTo: phase === "in" ? this.getElementVisibleOpacity(element) : 0,
+        positionFrom: phase === "in" ? flyOffset : { x: 0, y: 0 },
+        positionTo: phase === "in" ? { x: 0, y: 0 } : flyOffset,
+        easing: easing ?? "easeOut",
+        duration,
+        delay: normalizedDelay + index * normalizedStagger,
+      });
+    });
+  };
+
+  public cancelElementAnimation = (id: string) => {
+    if (!this.elementAnimationStates.delete(id)) {
+      return;
+    }
+
+    this.syncElementAnimations();
+  };
+
+  public clearElementAnimationOverrides = () => {
+    if (
+      this.elementOpacityOverrides.size === 0 &&
+      this.elementPositionOverrides.size === 0 &&
+      this.elementAnimationStates.size === 0
+    ) {
+      return;
+    }
+
+    this.elementAnimationStates.clear();
+    this.elementOpacityOverrides.clear();
+    this.elementPositionOverrides.clear();
+    this.syncElementAnimations();
+    this.bumpRenderAnimationVersion();
+  };
+
   public applyDeltas = (
     deltas: StoreDelta[],
     options?: ApplyToOptions,
@@ -8618,16 +8957,13 @@ class App extends React.Component<AppProps, AppState> {
           ) as any;
 
           if (arrow && isBindingElement(arrow)) {
-            const {
-              hitFocusPoint,
-              pointerOffset,
-              arrowOtherEndpointInitialBinding,
-            } = handleFocusPointPointerDown(
-              arrow,
-              pointerDownState,
-              elementsMap,
-              this.state,
-            );
+            const { hitFocusPoint, pointerOffset } =
+              handleFocusPointPointerDown(
+                arrow,
+                pointerDownState,
+                elementsMap,
+                this.state,
+              );
 
             // If focus point is hit, update state and prevent element selection
             if (hitFocusPoint) {
@@ -8637,10 +8973,6 @@ class App extends React.Component<AppProps, AppState> {
                   hoveredFocusPointBinding: hitFocusPoint,
                   draggedFocusPointBinding: hitFocusPoint,
                   pointerOffset,
-                  initialState: {
-                    ...linearElementEditor.initialState,
-                    arrowOtherEndpointInitialBinding,
-                  },
                 },
               });
               return false;
@@ -10763,19 +11095,14 @@ class App extends React.Component<AppProps, AppState> {
         }
 
         if (this.state.selectedLinearElement.draggedFocusPointBinding) {
-          const { arrowOtherEndpointInitialBinding } =
-            handleFocusPointPointerUp(
-              this.state.selectedLinearElement,
-              this.scene,
-            );
+          handleFocusPointPointerUp(
+            this.state.selectedLinearElement,
+            this.scene,
+          );
           this.setState({
             selectedLinearElement: {
               ...this.state.selectedLinearElement,
               draggedFocusPointBinding: null,
-              initialState: {
-                ...this.state.selectedLinearElement.initialState,
-                arrowOtherEndpointInitialBinding,
-              },
             },
           });
         } else if (

packages/excalidraw/index.tsx

@@ -99,6 +99,7 @@ const ExcalidrawBase = (props: ExcalidrawProps) => {
     children,
     validateEmbeddable,
     renderEmbeddable,
+    resolveRenderOpacity,
     aiEnabled,
     showDeprecatedFonts,
     renderScrollbars,
@@ -217,6 +218,7 @@ const ExcalidrawBase = (props: ExcalidrawProps) => {
           onDuplicate={onDuplicate}
           validateEmbeddable={validateEmbeddable}
           renderEmbeddable={renderEmbeddable}
+          resolveRenderOpacity={resolveRenderOpacity}
           aiEnabled={aiEnabled !== false}
           showDeprecatedFonts={showDeprecatedFonts}
           renderScrollbars={renderScrollbars}

packages/excalidraw/renderer/staticScene.ts

@@ -14,11 +14,16 @@ import {
 } from "@excalidraw/element";
 import {
   elementOverlapsWithFrame,
+  getContainingFrame,
   getTargetFrame,
   shouldApplyFrameClip,
 } from "@excalidraw/element";
 
-import { renderElement } from "@excalidraw/element";
+import {
+  getRenderElementWithPositionOverride,
+  getRenderOpacity,
+  renderElement,
+} from "@excalidraw/element";
 
 import { getElementAbsoluteCoords } from "@excalidraw/element";
 
@@ -170,7 +175,10 @@ const renderLinkIcon = (
   context: CanvasRenderingContext2D,
   appState: StaticCanvasAppState,
   elementsMap: ElementsMap,
+  renderConfig: StaticCanvasRenderConfig,
 ) => {
+  element = getRenderElementWithPositionOverride(element, renderConfig);
+
   if (element.link && !appState.selectedElementIds[element.id]) {
     const [x1, y1, x2, y2] = getElementAbsoluteCoords(element, elementsMap);
     const [x, y, width, height] = getLinkHandleFromCoords(
@@ -221,7 +229,13 @@ const renderLinkIcon = (
 
       linkCanvasCacheContext.restore();
     }
-    context.globalAlpha = element.opacity / 100;
+    context.globalAlpha = getRenderOpacity(
+      element,
+      renderConfig,
+      getContainingFrame(element, elementsMap),
+      renderConfig.elementsPendingErasure,
+      renderConfig.pendingFlowchartNodes,
+    );
     context.drawImage(linkCanvas, x - centerX, y - centerY, width, height);
     context.restore();
   }
@@ -370,7 +384,7 @@ const _renderStaticScene = ({
         context.restore();
 
         if (!isExporting) {
-          renderLinkIcon(element, context, appState, elementsMap);
+          renderLinkIcon(element, context, appState, elementsMap, renderConfig);
         }
       } catch (error: any) {
         console.error(
@@ -421,7 +435,7 @@ const _renderStaticScene = ({
             );
           }
           if (!isExporting) {
-            renderLinkIcon(element, context, appState, elementsMap);
+            renderLinkIcon(element, context, appState, elementsMap, renderConfig);
           }
         };
         // - when exporting the whole canvas, we DO NOT apply clipping

packages/excalidraw/scene/types.ts

@@ -12,6 +12,7 @@ import type {
   AppClassProperties,
   AppState,
   EmbedsValidationStatus,
+  RenderOpacityResolver,
   ElementsPendingErasure,
   InteractiveCanvasAppState,
   StaticCanvasAppState,
@@ -37,6 +38,13 @@ export type StaticCanvasRenderConfig = {
   elementsPendingErasure: ElementsPendingErasure;
   pendingFlowchartNodes: PendingExcalidrawElements | null;
   theme: AppState["theme"];
+  resolveRenderOpacity?: RenderOpacityResolver;
+  elementOpacityOverrides?: ReadonlyMap<ExcalidrawElement["id"], number>;
+  elementPositionOverrides?: ReadonlyMap<
+    ExcalidrawElement["id"],
+    { x: number; y: number }
+  >;
+  renderAnimationVersion?: number;
 };
 
 export type SVGRenderConfig = {

packages/excalidraw/tests/__snapshots__/regressionTests.test.tsx.snap

@@ -8665,7 +8665,6 @@ exports[`regression tests > key 5 selects arrow tool > [end of test] appState 1`
     "hoveredFocusPointBinding": null,
     "initialState": {
       "altFocusPoint": null,
-      "arrowOtherEndpointInitialBinding": null,
       "arrowStartIsInside": false,
       "lastClickedPoint": -1,
       "origin": null,
@@ -8899,7 +8898,6 @@ exports[`regression tests > key 6 selects line tool > [end of test] appState 1`]
     "hoveredFocusPointBinding": null,
     "initialState": {
       "altFocusPoint": null,
-      "arrowOtherEndpointInitialBinding": null,
       "arrowStartIsInside": false,
       "lastClickedPoint": -1,
       "origin": null,
@@ -9323,7 +9321,6 @@ exports[`regression tests > key a selects arrow tool > [end of test] appState 1`
     "hoveredFocusPointBinding": null,
     "initialState": {
       "altFocusPoint": null,
-      "arrowOtherEndpointInitialBinding": null,
       "arrowStartIsInside": false,
       "lastClickedPoint": -1,
       "origin": null,
@@ -9737,7 +9734,6 @@ exports[`regression tests > key l selects line tool > [end of test] appState 1`]
     "hoveredFocusPointBinding": null,
     "initialState": {
       "altFocusPoint": null,
-      "arrowOtherEndpointInitialBinding": null,
       "arrowStartIsInside": false,
       "lastClickedPoint": -1,
       "origin": null,

packages/excalidraw/types.ts

@@ -567,6 +567,10 @@ export type OnExportProgress = {
   progress?: number;
 };
 
+export type RenderOpacityResolver = (
+  element: NonDeletedExcalidrawElement,
+) => ExcalidrawElement["opacity"] | undefined;
+
 export interface ExcalidrawProps {
   onChange?: (
     elements: readonly OrderedExcalidrawElement[],
@@ -682,6 +686,7 @@ export interface ExcalidrawProps {
     element: NonDeleted<ExcalidrawEmbeddableElement>,
     appState: AppState,
   ) => JSX.Element | null;
+  resolveRenderOpacity?: RenderOpacityResolver;
   aiEnabled?: boolean;
   showDeprecatedFonts?: boolean;
   renderScrollbars?: boolean;
@@ -962,6 +967,11 @@ export interface ExcalidrawImperativeAPI {
   getFiles: () => InstanceType<typeof App>["files"];
   getName: InstanceType<typeof App>["getName"];
   scrollToContent: InstanceType<typeof App>["scrollToContent"];
+  animateElements: InstanceType<typeof App>["animateElements"];
+  cancelElementAnimation: InstanceType<typeof App>["cancelElementAnimation"];
+  clearElementAnimationOverrides: InstanceType<
+    typeof App
+  >["clearElementAnimationOverrides"];
   registerAction: (action: Action) => void;
   refresh: InstanceType<typeof App>["refresh"];
   setToast: InstanceType<typeof App>["setToast"];