From defd34923a419ebe8adeb21c2799cbd2ab441b7f Mon Sep 17 00:00:00 2001
From: David Luzar <5153846+dwelle@users.noreply.github.com>
Date: Wed, 22 May 2024 13:40:23 +0200
Subject: [PATCH] docs: fix `updateScene` `storeAction` default tsdoc &
 document types (#8048)

---
 packages/excalidraw/components/App.tsx |  2 +-
 packages/excalidraw/store.ts           | 36 ++++++++++++++++++++++----
 2 files changed, 32 insertions(+), 6 deletions(-)

diff --git a/packages/excalidraw/components/App.tsx b/packages/excalidraw/components/App.tsx
index 241d07feb..4174011b7 100644
--- a/packages/excalidraw/components/App.tsx
+++ b/packages/excalidraw/components/App.tsx
@@ -3708,7 +3708,7 @@ class App extends React.Component<AppProps, AppState> {
       elements?: SceneData["elements"];
       appState?: Pick<AppState, K> | null;
       collaborators?: SceneData["collaborators"];
-      /** @default StoreAction.CAPTURE */
+      /** @default StoreAction.NONE */
       storeAction?: SceneData["storeAction"];
     }) => {
       const nextElements = syncInvalidIndices(sceneData.elements ?? []);
diff --git a/packages/excalidraw/store.ts b/packages/excalidraw/store.ts
index 62223a8b5..8e934ccba 100644
--- a/packages/excalidraw/store.ts
+++ b/packages/excalidraw/store.ts
@@ -6,6 +6,7 @@ import { deepCopyElement } from "./element/newElement";
 import type { OrderedExcalidrawElement } from "./element/types";
 import { Emitter } from "./emitter";
 import type { AppState, ObservedAppState } from "./types";
+import type { ValueOf } from "./utility-types";
 import { isShallowEqual } from "./utils";
 
 // hidden non-enumerable property for runtime checks
@@ -35,16 +36,41 @@ const isObservedAppState = (
 ): appState is ObservedAppState =>
   !!Reflect.get(appState, hiddenObservedAppStateProp);
 
-export type StoreActionType = "capture" | "update" | "none";
-
-export const StoreAction: {
-  [K in Uppercase<StoreActionType>]: StoreActionType;
-} = {
+export const StoreAction = {
+  /**
+   * Immediately undoable.
+   *
+   * Use for updates which should be captured.
+   * Should be used for most of the local updates.
+   *
+   * These updates will _immediately_ make it to the local undo / redo stacks.
+   */
   CAPTURE: "capture",
+  /**
+   * Never undoable.
+   *
+   * Use for updates which should never be recorded, such as remote updates
+   * or scene initialization.
+   *
+   * These updates will _never_ make it to the local undo / redo stacks.
+   */
   UPDATE: "update",
+  /**
+   * Eventually undoable.
+   *
+   * Use for updates which should not be captured immediately - likely
+   * exceptions which are part of some async multi-step process. Otherwise, all
+   * such updates would end up being captured with the next
+   * `StoreAction.CAPTURE` - triggered either by the next `updateScene`
+   * or internally by the editor.
+   *
+   * These updates will _eventually_ make it to the local undo / redo stacks.
+   */
   NONE: "none",
 } as const;
 
+export type StoreActionType = ValueOf<typeof StoreAction>;
+
 /**
  * Represent an increment to the Store.
  */