tweak fade api a little bit

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

@@ -683,7 +683,9 @@ export default function ExampleApp({
                   }
 
                   setFadeDemoElementIds(
-                    excalidrawAPI.getSceneElements().map((element) => element.id),
+                    excalidrawAPI
+                      .getSceneElements()
+                      .map((element) => element.id),
                   );
                   excalidrawAPI.clearElementOpacityOverrides();
                   setHideAllForFadeDemo(true);
@@ -700,7 +702,9 @@ export default function ExampleApp({
 
                   const elements = excalidrawAPI
                     .getSceneElements()
-                    .filter((element) => fadeDemoElementIds.includes(element.id));
+                    .filter((element) =>
+                      fadeDemoElementIds.includes(element.id),
+                    );
 
                   if (!elements.length) {
                     return;
@@ -715,8 +719,8 @@ export default function ExampleApp({
                     excalidrawAPI.clearElementOpacityOverrides();
                   }
 
-                  excalidrawAPI.fadeElement({
-                    id: elements[nextIndex].id,
+                  excalidrawAPI.fadeElements({
+                    elements: [elements[nextIndex].id],
                     from: 0,
                     to: 100,
                     duration: 500,
@@ -735,19 +739,20 @@ export default function ExampleApp({
 
                   const elements = excalidrawAPI
                     .getSceneElements()
-                    .filter((element) => fadeDemoElementIds.includes(element.id));
+                    .filter((element) =>
+                      fadeDemoElementIds.includes(element.id),
+                    );
 
                   if (!elements.length) {
                     return;
                   }
 
-                  elements.forEach((element) => {
-                    excalidrawAPI.fadeElement({
-                      id: element.id,
-                      from: 0,
-                      to: 100,
-                      duration: 500,
-                    });
+                  excalidrawAPI.fadeElements({
+                    elements,
+                    from: 0,
+                    to: 100,
+                    duration: 500,
+                    stagger: 1000,
                   });
 
                   setFadeDemoNextIndex(elements.length);
@@ -763,7 +768,9 @@ export default function ExampleApp({
 
                   const elements = excalidrawAPI
                     .getSceneElements()
-                    .filter((element) => fadeDemoElementIds.includes(element.id));
+                    .filter((element) =>
+                      fadeDemoElementIds.includes(element.id),
+                    );
 
                   if (!elements.length) {
                     return;
@@ -778,8 +785,8 @@ export default function ExampleApp({
                     return;
                   }
 
-                  excalidrawAPI.fadeElement({
-                    id: elements[prevIndex].id,
+                  excalidrawAPI.fadeElements({
+                    elements: [elements[prevIndex].id],
                     from: 100,
                     to: 0,
                     duration: 500,

packages/excalidraw/components/App.tsx

@@ -843,7 +843,7 @@ class App extends React.Component<AppProps, AppState> {
         clear: this.resetHistory,
       },
       scrollToContent: this.scrollToContent,
-      fadeElement: this.fadeElement,
+      fadeElements: this.fadeElements,
       cancelFadeElement: this.cancelFadeElement,
       clearElementOpacityOverrides: this.clearElementOpacityOverrides,
       getSceneElements: this.getSceneElements,
@@ -4714,7 +4714,7 @@ class App extends React.Component<AppProps, AppState> {
     },
   );
 
-  public fadeElement = ({
+  private fadeElement = ({
     id,
     from,
     to = 100,
@@ -4763,6 +4763,35 @@ class App extends React.Component<AppProps, AppState> {
     this.syncFadeElementAnimations();
   };
 
+  public fadeElements = ({
+    elements,
+    from,
+    to = 100,
+    duration = 250,
+    delay = 0,
+    stagger = 0,
+  }: {
+    elements: readonly (ExcalidrawElement | ExcalidrawElement["id"])[];
+    from?: number;
+    to?: number;
+    duration?: number;
+    delay?: number;
+    stagger?: number;
+  }) => {
+    const normalizedDelay = Math.max(delay, 0);
+    const normalizedStagger = Math.max(stagger, 0);
+
+    elements.forEach((element, index) => {
+      this.fadeElement({
+        id: typeof element === "string" ? element : element.id,
+        from,
+        to,
+        duration,
+        delay: normalizedDelay + index * normalizedStagger,
+      });
+    });
+  };
+
   public cancelFadeElement = (id: string) => {
     if (!this.elementFadeStates.delete(id)) {
       return;

packages/excalidraw/types.ts

@@ -967,7 +967,7 @@ export interface ExcalidrawImperativeAPI {
   getFiles: () => InstanceType<typeof App>["files"];
   getName: InstanceType<typeof App>["getName"];
   scrollToContent: InstanceType<typeof App>["scrollToContent"];
-  fadeElement: InstanceType<typeof App>["fadeElement"];
+  fadeElements: InstanceType<typeof App>["fadeElements"];
   cancelFadeElement: InstanceType<typeof App>["cancelFadeElement"];
   clearElementOpacityOverrides: InstanceType<
     typeof App