vue2-excel-grid 1.8.0 → 2.0.1

package/src/components/ExcelGrid.vue

@@ -820,13 +820,16 @@
       :visible="localSyncModal.visible"
       :grid-options="_selfComponentDef"
       :columns="_localSyncPreviewColumns"
-      :snapshot="localSyncModal.snapshot"
+      :versions="localSyncModal.versions"
+      :selected-id="localSyncModal.selectedId"
+      :selected-version="localSyncModal.selectedVersion"
       :locale="locale"
       :theme="internalTheme"
       @close="closeLocalSyncModal"
+      @select="_selectLocalSyncModalVersion"
       @save="_onLocalSyncModalSave"
-      @restore="restoreLocalSnapshot"
-      @clear="clearLocalSnapshot"
+      @restore="restoreLocalVersion"
+      @clear="_onLocalSyncModalDelete"
     />
 
     <!-- Lock/unlock state feedback — brief centered icon flash -->
@@ -944,7 +947,8 @@ import EgLocalSyncModal from './EgLocalSyncModal.vue'
 import { parseDateValue, formatDate } from '../utils/dateUtils.js'
 import { formatNumber as _formatNumber } from '../utils/numberFormat.js'
 import { Mask, MaskInput } from '../utils/mask.js'
-import { saveSnapshot, loadSnapshot, deleteSnapshot } from '../utils/idbStore.js'
+import { listVersions, getVersion, deleteVersion, saveOrTouchVersion, putBuffer, getBuffer, clearBuffer } from '../utils/idbStore.js'
+import { hashRows, hashRowsAsync } from '../utils/dataHash.js'
 
 const SIZE_CONFIG = {
   small:  { row: 22, header: 24, footer: 24, filter: 26 },
@@ -1409,34 +1413,48 @@ const ExcelGridComponent = {
     sort: { type: Object, default: null },
 
     /**
-     * Unique key that opts the grid into local autosave: whenever `data`
-     * changes, a debounced (~800ms) copy is written to the browser's
-     * IndexedDB, keyed by this string — so a page reload/crash/tab close
-     * doesn't lose in-progress work. Also adds a toolbar button ('localSync'
-     * — see the `toolbar` prop's `list`/`disabled`) that opens a modal
-     * showing the last saved copy as a read-only table, with three actions:
-     * **Save** (pushes the current `v-model` into the saved copy right now,
-     * bypassing the debounce), **Restore** (the other direction — pulls the
-     * saved copy back into `v-model`), and **Delete** (clears the saved
-     * copy).
+     * Unique key that opts the grid into local version history: when the page
+     * is being left (tab hidden/closed, or this component unmounted — NOT on
+     * every edit), the current `v-model` is content-hashed (via a Web Worker
+     * when available, so the main thread stays responsive right as the page
+     * may be unloading) and saved to the browser's IndexedDB as a **version**,
+     * keyed by this string. If the hash matches an already-saved version for
+     * this key, that version's timestamp is refreshed instead of creating a
+     * duplicate — only genuinely different content produces a new version.
+     * Also adds a toolbar button ('localSync' — see the `toolbar` prop's
+     * `list`/`disabled`) that opens a modal listing saved versions, each with
+     * a read-only preview and **Restore** / **Delete** actions, plus a
+     * **Save** button for an explicit checkpoint.
      *
      * Two different grid instances must use different keys — the same key
-     * means "the same saved copy" (last writer wins). Omit this prop
-     * entirely to opt out completely: no IndexedDB access happens at all,
-     * and the toolbar button never renders.
+     * means "the same version history" (concurrent tabs interleave). Omit
+     * this prop entirely to opt out completely: no IndexedDB access happens
+     * at all, and the toolbar button never renders.
      *
-     * See also the ref-callable methods `saveLocalSnapshot()`,
-     * `restoreLocalSnapshot()`, `clearLocalSnapshot()`, `getLocalSnapshot()`,
-     * `getLocalSnapshotInfo()`, `openLocalSyncModal()`/`closeLocalSyncModal()`,
-     * and the
-     * `local-sync-save`/`local-sync-restore`/`local-sync-clear`/`local-sync-error`
+     * See also `localSyncMaxVersions`, the ref-callable methods
+     * `listLocalVersions()`, `getLocalVersion(id)`, `restoreLocalVersion(id)`,
+     * `deleteLocalVersion(id)`, `saveLocalVersionNow()`,
+     * `openLocalSyncModal()`/`closeLocalSyncModal()`, and the
+     * `local-sync-save`/`local-sync-restore`/`local-sync-clear`/`local-sync-error`/`local-sync-available`
      * events — [details](/local-sync).
      * @type {String}
      * @default null
      * @example
      * <excel-grid :columns="columns" v-model="data" local-sync-key="invoice-42" toolbar />
      */
-    localSyncKey: { type: String, default: null }
+    localSyncKey: { type: String, default: null },
+
+    /**
+     * Maximum number of local versions kept per `localSyncKey`. Once a new
+     * version pushes the count past this, the oldest version(s) (by
+     * `createdAt`) are deleted automatically (FIFO). Has no effect without
+     * `localSyncKey`.
+     * @type {Number}
+     * @default 10
+     * @example
+     * <excel-grid :columns="columns" v-model="data" local-sync-key="invoice-42" :local-sync-max-versions="20" />
+     */
+    localSyncMaxVersions: { type: Number, default: 10 }
   },
 
   data() {
@@ -1506,12 +1524,14 @@ const ExcelGridComponent = {
       importState: { active: false, percent: 0, message: '' },
       exportState: { active: false },
 
-      // localSyncKey feature — modal state + pending debounce timer (the
-      // timer itself lives outside `data()`'s reactive tracking, see created()).
-      localSyncModal: { visible: false, snapshot: null },
-      // True when a snapshot already existed at mount and the user hasn't
-      // dealt with it yet — drives the toolbar button's "unseen draft" dot.
-      // See _checkLocalSnapshotOnMount() for the full lifecycle.
+      // localSyncKey feature — modal state: the version list (metadata only)
+      // plus which one is selected/previewed. `selectedVersion` holds that
+      // version's full { id, data, createdAt, updatedAt } for the nested-grid
+      // preview (see EgLocalSyncModal.vue).
+      localSyncModal: { visible: false, versions: [], selectedId: null, selectedVersion: null },
+      // True when one or more versions already existed at mount and the user
+      // hasn't opened the modal yet — drives the toolbar button's "unseen
+      // local versions" dot. See _loadLocalVersionsOnMount() for the full lifecycle.
       localSyncAvailable: false,
 
       resizing: {
@@ -2270,13 +2290,6 @@ const ExcelGridComponent = {
       this.$nextTick(() => this.updateVirtualScroll())
     },
 
-    // Guarded by _lockFlashArmed (set once mounted()) so an initial `locked:
-    // true` prop doesn't flash the icon before the grid has even appeared.
-    internalLocked(v) {
-      if (!this._lockFlashArmed) return
-      this._flashLock(v)
-    },
-
     autoWidth(v) {
       if (v) this._applyAutoWidth()
     },
@@ -2347,9 +2360,21 @@ const ExcelGridComponent = {
       immediate: true,
       handler(v) { this.internalCollapsedGroups = v ? [...v] : [] }
     },
+    // `immediate: true` guarantees this fires once, synchronously, right at
+    // setup regardless of `v` — that's the one reliable signal that THIS
+    // particular call is the initial sync, not a real host-driven change
+    // (e.g. via `:locked.sync`). Every call after the first is a genuine
+    // change, so only those flash. (Watching internalLocked itself for this
+    // instead — the previous approach — can't tell "initial value happened
+    // to be true" from "the user's first-ever real toggle": both look like
+    // "the first time internalLocked actually changed value".)
     locked: {
       immediate: true,
-      handler(v) { this.internalLocked = !!v }
+      handler(v) {
+        this.internalLocked = !!v
+        if (this._lockPropSynced) this._flashLock(this.internalLocked)
+        this._lockPropSynced = true
+      }
     },
     data: {
       immediate: true,
@@ -2419,6 +2444,12 @@ const ExcelGridComponent = {
     this._dragScrollRAF = null
     this._dragCleanupTimer = null
 
+    // localSyncKey — the last `data` reference a version was actually saved
+    // for. Initialized to the current (mount-time) value so an untouched grid
+    // that's merely tab-switched away from doesn't spam a "nothing happened"
+    // version on every hide — only a REAL edit (which replaces this array
+    // reference, see _emitDataChange) makes the next hide event flush.
+    this._lastFlushedDataRef = this.data
   },
 
   mounted() {
@@ -2450,8 +2481,17 @@ const ExcelGridComponent = {
       // in both modes) fresh when the host's layout changes.
       if (this.$el.parentElement) this._scrollBodyResizeObserver.observe(this.$el.parentElement)
     }
-    this._lockFlashArmed = true
-    this._checkLocalSnapshotOnMount()
+    this._loadLocalVersionsOnMount()
+    // localSyncKey — save on page-hide, not per-edit (see _flushLocalVersionOnHide).
+    // 'visibilitychange'->hidden is the primary trigger: it fires for tab
+    // switches, minimizing, AND reliably before actual tab close/navigation on
+    // both desktop and mobile, while the page is still very likely alive —
+    // giving the async worker-hash + IndexedDB write a real chance to finish.
+    // 'pagehide' is a backstop for the cases visibilitychange misses; it's
+    // idempotent with visibilitychange (same content -> same hash -> no-op
+    // beyond a timestamp touch) so firing both is harmless.
+    document.addEventListener('visibilitychange', this._onVisibilityChangeForLocalSync)
+    window.addEventListener('pagehide', this._onPageHideForLocalSync)
   },
 
   updated() {
@@ -2486,7 +2526,7 @@ const ExcelGridComponent = {
     clearTimeout(this._onInputTimer)
     clearTimeout(this._dragCleanupTimer)
     clearTimeout(this._widthSyncChainResetTimer)
-    clearTimeout(this._localSyncTimer)
+    clearTimeout(this._bufferWriteTimer)
     if (this._dragScrollRAF) cancelAnimationFrame(this._dragScrollRAF)
     document.removeEventListener('mousemove', this.onGlobalMouseMove)
     document.removeEventListener('mouseup', this.onGlobalMouseUp)
@@ -2494,6 +2534,14 @@ const ExcelGridComponent = {
     document.removeEventListener('mousedown', this._onDocMouseDownForDropdown, true)
     window.removeEventListener('resize', this.syncHeaderViewportWidth)
     window.removeEventListener('scroll', this._onWindowScrollForDropdown, true)
+    document.removeEventListener('visibilitychange', this._onVisibilityChangeForLocalSync)
+    window.removeEventListener('pagehide', this._onPageHideForLocalSync)
+    // Best-effort — the component may be torn down (SPA route change) without
+    // the page itself unloading, which visibilitychange/pagehide won't catch.
+    // sync: true — see _flushLocalVersionOnHide()'s comment; a component
+    // being destroyed is exactly the same "might not survive an async hop"
+    // situation as the other two triggers.
+    this._flushLocalVersionOnHide(false, true)
     if (this.isFullscreen) {
       document.body.style.overflow = this._prevBodyOverflow || ''
       document.removeEventListener('keydown', this._onFullscreenKeyDown)
@@ -6011,7 +6059,7 @@ const ExcelGridComponent = {
         // All edit paths already use spread ({ ...row }) so frozen rows are safe.
         const data = result.data.map(row => Object.freeze(row))
         this.$emit('input', data)
-        this._scheduleLocalAutosave()
+        this._scheduleBufferWrite(data)
         this.$emit('update:columns', columns)
 
         const hasMerges = merges && merges.length > 0
@@ -6127,7 +6175,7 @@ const ExcelGridComponent = {
         }
       }
       this.$emit('input', newData)
-      this._scheduleLocalAutosave()
+      this._scheduleBufferWrite(newData)
     },
 
     // Emit 'update:merges' and record a merges diff entry.
@@ -6161,7 +6209,7 @@ const ExcelGridComponent = {
             newData.length = entry.before.rowCount
           }
           this.$emit('input', newData)
-          this._scheduleLocalAutosave()
+          this._scheduleBufferWrite(newData)
         } else if (entry.type === 'merges') {
           this.internalMerges = entry.before.slice()
           this.$emit('update:merges', entry.before.slice())
@@ -6184,7 +6232,7 @@ const ExcelGridComponent = {
             newData[entry.after.indices[i]] = entry.after.rows[i]
           }
           this.$emit('input', newData)
-          this._scheduleLocalAutosave()
+          this._scheduleBufferWrite(newData)
         } else if (entry.type === 'merges') {
           this.internalMerges = entry.after.slice()
           this.$emit('update:merges', entry.after.slice())
@@ -6218,147 +6266,277 @@ const ExcelGridComponent = {
     },
 
     // =========================================================
-    // LOCAL SYNC — autosave `data` to IndexedDB, keyed by localSyncKey
+    // LOCAL SYNC — save `data` as a local IndexedDB *version*, keyed by
+    // localSyncKey, only when the page is being left (not per-edit).
     // =========================================================
 
-    // Internal: debounced (800ms) autosave. No-op when localSyncKey isn't
-    // set — zero IndexedDB access at all in that case.
-    //
-    // Deliberately called from the grid's OWN data-change points only
-    // (_emitDataChange, undo, redo, import) — NOT from a $watch on `data`.
-    // A watcher can't tell "the user edited a cell" from "the host replaced
-    // `data` wholesale", and the second one is the common case right after
-    // mount: a host that loads rows from an API assigns them ~100-2000ms in,
-    // which a watcher would treat as a real change and autosave over the
-    // user's previously saved draft — destroying exactly the work this
-    // feature exists to protect, before they can open the modal to restore
-    // it. Autosave must mean "the user worked", not "the data object
-    // changed". restoreLocalSnapshot() likewise does NOT call this: the
-    // snapshot it just applied is already what's stored.
-    _scheduleLocalAutosave() {
+    // Internal, called once from mounted(): populates the toolbar "unseen
+    // local versions" dot and emits local-sync-available if any versions
+    // already exist for this key (e.g. saved in an earlier visit).
+    async _loadLocalVersionsOnMount() {
       if (!this.localSyncKey) return
-      clearTimeout(this._localSyncTimer)
-      this._localSyncTimer = setTimeout(() => {
-        this.saveLocalSnapshot()
-      }, 800)
-    },
-
-    // Internal, called once from mounted(): a snapshot that already exists at
-    // mount is a draft from an EARLIER session, which the user has no way of
-    // knowing about unless they happen to click the toolbar button. Flags it
-    // so the button shows a dot, and emits local-sync-available so a host can
-    // surface its own prompt ("restore unsaved changes?") instead.
-    async _checkLocalSnapshotOnMount() {
+      await this._promoteBufferIfAny()
+      try {
+        const versions = await listVersions(this.localSyncKey)
+        if (!versions.length) return
+        this.localSyncAvailable = true
+        this.$emit('local-sync-available', {
+          key: this.localSyncKey,
+          versions: versions.length,
+          mostRecentUpdatedAt: versions[0].updatedAt
+        })
+      } catch (error) {
+        this.$emit('local-sync-error', { action: 'load', error })
+      }
+    },
+
+    // Debounced (800ms), called from the grid's own real-change points
+    // (_emitDataChange, import, undo, redo — the exact same "user worked"
+    // signal _flushLocalVersionOnHide() relies on, never a $watch on `data`,
+    // for the same reason spelled out on the localSyncKey prop's JSDoc: a
+    // host loading rows from an API must never look like a user edit).
+    //
+    // Writes to IndexedDB's 'buffer' store (idbStore.js — one row per key, no
+    // hash, no history) at a moment with no teardown race at all — the user
+    // is actively still on the page. This is what actually fixes reload/
+    // close data loss: a version-store write ATTEMPTED at the leave-signal
+    // has no guarantee of finishing before an actual page teardown (verified
+    // directly — even a trivial, unrelated IndexedDB write failed to survive
+    // a real page.reload() in Chromium), but a buffer write that already
+    // completed minutes or seconds earlier, during ordinary editing, needs no
+    // such guarantee — it's already durably there. _promoteBufferIfAny()
+    // turns it into a real version next time the grid mounts.
+    _scheduleBufferWrite(data) {
       if (!this.localSyncKey) return
-      const snapshot = await this.getLocalSnapshot()
-      if (!snapshot) return
-      this.localSyncAvailable = true
-      this.$emit('local-sync-available', {
-        key: this.localSyncKey,
-        rows: snapshot.data.length,
-        updatedAt: snapshot.updatedAt
-      })
+      clearTimeout(this._bufferWriteTimer)
+      this._bufferWriteTimer = setTimeout(() => { this._writeBufferNow(data) }, 800)
     },
 
-    // Public, ref-callable: saves the current `data` to IndexedDB right now,
-    // bypassing the debounce (e.g. a host wants to force a checkpoint before
-    // navigating away). No-op (resolves to null) when localSyncKey isn't set.
-    async saveLocalSnapshot() {
-      if (!this.localSyncKey) return null
-      clearTimeout(this._localSyncTimer)
+    async _writeBufferNow(data) {
+      if (!this.localSyncKey) return
       try {
-        const { updatedAt } = await saveSnapshot(this.localSyncKey, this.data)
-        // What's stored is now exactly what's on screen — there's no longer an
-        // older draft to go back to, so the "unseen draft" dot would mislead.
-        this.localSyncAvailable = false
-        this.$emit('local-sync-save', { key: this.localSyncKey, rows: this.data.length, updatedAt })
-        return updatedAt
+        await putBuffer(this.localSyncKey, data)
       } catch (error) {
         this.$emit('local-sync-error', { action: 'save', error })
-        return null
       }
     },
 
-    // Modal's "Save" button (push v-model -> IndexedDB — the other direction
-    // from "Restore", which pulls IndexedDB -> v-model). Unlike
-    // restoreLocalSnapshot(), this deliberately does NOT close the modal —
-    // the freshly-saved snapshot is reflected in place (updated timestamp/
-    // row count/preview) so the user sees the save actually happened.
-    async _onLocalSyncModalSave() {
-      const updatedAt = await this.saveLocalSnapshot()
-      if (updatedAt != null) {
-        this.localSyncModal.snapshot = { data: this.data, updatedAt }
+    // Called once from _loadLocalVersionsOnMount(), before this key's version
+    // list is read — folds a leftover buffer (from an edit that was saved
+    // during the PREVIOUS visit but never made it into 'versions' — the
+    // reload/close case this whole mechanism exists for) into a real version.
+    // No time pressure here, so this uses the Worker-backed hashRowsAsync()
+    // like any other non-leave-signal path.
+    async _promoteBufferIfAny() {
+      try {
+        const buffered = await getBuffer(this.localSyncKey)
+        if (!buffered) return
+        const hash = await hashRowsAsync(buffered.data)
+        const { version, overwritten } = await saveOrTouchVersion(
+          this.localSyncKey, buffered.data, hash, this.localSyncMaxVersions
+        )
+        await clearBuffer(this.localSyncKey)
+        this.$emit('local-sync-save', {
+          key: this.localSyncKey,
+          id: version.id,
+          rows: buffered.data.length,
+          updatedAt: version.updatedAt,
+          overwritten
+        })
+      } catch (error) {
+        this.$emit('local-sync-error', { action: 'save', error })
       }
     },
 
-    // Public, ref-callable: loads the IndexedDB snapshot and writes it back
-    // into v-model (input/update:data) — the modal's "Restore" button calls
-    // this too. No-op if localSyncKey isn't set or nothing is saved yet.
-    async restoreLocalSnapshot() {
+    // `sync: true` — see _flushLocalVersionOnHide()'s comment on why the
+    // passive leave-triggers can't afford a Worker round-trip.
+    _onVisibilityChangeForLocalSync() {
+      if (document.visibilityState === 'hidden') this._flushLocalVersionOnHide(false, true)
+    },
+
+    _onPageHideForLocalSync() {
+      this._flushLocalVersionOnHide(false, true)
+    },
+
+    // The core save-on-leave path — replaces a per-edit autosave (see the
+    // localSyncKey prop's JSDoc for why: an autosave tied to "data changed"
+    // can't distinguish a user's edit from a host loading rows from an API,
+    // and would silently overwrite a user's saved work the moment a host
+    // does the latter). Triggered from mounted()'s visibilitychange/pagehide
+    // listeners and beforeDestroy() — see those for the three trigger points.
+    //
+    // Content-hashes the current `data` and either touches an existing local
+    // version with the same hash (just refreshes its timestamp — "ustiga
+    // yoziladi, alohida versiya qilinmaydi") or creates a brand-new one,
+    // evicting the oldest past localSyncMaxVersions (FIFO — see idbStore.js's
+    // saveOrTouchVersion()). Never throws — IndexedDB failures become
+    // local-sync-error.
+    //
+    // `force` skips the "nothing changed since the last flush" short-circuit
+    // below. The passive triggers (visibilitychange/pagehide/beforeDestroy)
+    // fire often on an idle tab and must NOT wake IndexedDB for no reason, so
+    // they leave it in place. saveLocalVersionNow() — an explicit, infrequent,
+    // host/modal-initiated "checkpoint now" action — passes force so it never
+    // silently does nothing: even unchanged data still gets its existing
+    // version's timestamp refreshed via the same hash-dedup path, rather than
+    // the caller seeing no effect at all.
+    //
+    // `sync` picks hashRows() (main thread) over the Worker-based
+    // hashRowsAsync(). This was a real, observed bug, not a theoretical one:
+    // a Worker round-trip (postMessage out, worker computes, postMessage
+    // back) is one more hop through the event loop than a page that's
+    // actually being torn down (as opposed to merely hidden — e.g. a tab
+    // switch, where the page stays alive indefinitely and the extra hop
+    // costs nothing) can be relied on to survive. visibilitychange/pagehide/
+    // beforeDestroy all fire in exactly that "might be torn down any moment"
+    // window, so they hash synchronously to remove that hop — the whole
+    // flush then only has the unavoidable async part (the IndexedDB write
+    // itself) left, giving it the best realistic chance to land before
+    // teardown. saveLocalVersionNow() (an explicit host/modal action with no
+    // teardown racing it) keeps the Worker, so hashing a large `data` array
+    // doesn't block the main thread during ordinary use.
+    async _flushLocalVersionOnHide(force = false, sync = false) {
       if (!this.localSyncKey) return
+      if (!force && this.data === this._lastFlushedDataRef) return // nothing changed since the last flush
+      const data = this.data
+      // Fires independently of the version-save attempt below, started as
+      // early as possible — see _scheduleBufferWrite()'s comment. This is
+      // the save that's actually likely to survive an imminent teardown;
+      // the version-store write below is best-effort on top of it, reliable
+      // for the common case (tab switch/background, page stays alive).
+      clearTimeout(this._bufferWriteTimer)
+      this._writeBufferNow(data)
       try {
-        const snapshot = await loadSnapshot(this.localSyncKey)
-        if (!snapshot) return
-        this.$emit('input', snapshot.data)
-        this.$emit('update:data', snapshot.data)
-        this.localSyncAvailable = false
-        this.$emit('local-sync-restore', { key: this.localSyncKey, rows: snapshot.data.length })
-        this.closeLocalSyncModal()
+        const hash = sync ? hashRows(data) : await hashRowsAsync(data)
+        if (this.data !== data) return // data changed again mid-hash — a later flush will catch it
+        const { version, overwritten } = await saveOrTouchVersion(
+          this.localSyncKey, data, hash, this.localSyncMaxVersions
+        )
+        this._lastFlushedDataRef = data
+        // The version store now has this content durably — the buffer's job
+        // for it is done. Best-effort like everything else here: if this
+        // doesn't complete before teardown, _promoteBufferIfAny() finds the
+        // (now-redundant but harmless, dedup makes it a no-op touch) buffer
+        // on next mount anyway.
+        clearBuffer(this.localSyncKey).catch(() => {})
+        this.$emit('local-sync-save', {
+          key: this.localSyncKey,
+          id: version.id,
+          rows: data.length,
+          updatedAt: version.updatedAt,
+          overwritten
+        })
       } catch (error) {
-        this.$emit('local-sync-error', { action: 'restore', error })
+        this.$emit('local-sync-error', { action: 'save', error })
       }
     },
 
-    // Public, ref-callable: deletes the IndexedDB snapshot — the modal's
-    // "Delete" button calls this too (after its own inline confirm step).
-    async clearLocalSnapshot() {
-      if (!this.localSyncKey) return
+    // Public, ref-callable: runs the save-on-leave flow immediately, for a
+    // host that wants its own explicit "save checkpoint" button instead of
+    // waiting for a page-hide. Always goes through IndexedDB (force — see
+    // _flushLocalVersionOnHide()), but still through the same hash-dedup
+    // logic, so repeated calls with unchanged data don't spam duplicate
+    // versions — they just refresh the existing matching version.
+    async saveLocalVersionNow() {
+      await this._flushLocalVersionOnHide(true)
+    },
+
+    // Public, ref-callable: lightweight metadata for every saved version of
+    // this localSyncKey, newest first — no row data (use getLocalVersion(id)
+    // for that). Powers the built-in modal's list; also usable to build a
+    // custom UI.
+    async listLocalVersions() {
+      if (!this.localSyncKey) return []
       try {
-        await deleteSnapshot(this.localSyncKey)
-        if (this.localSyncModal.snapshot) this.localSyncModal.snapshot = null
-        this.localSyncAvailable = false
-        this.$emit('local-sync-clear', { key: this.localSyncKey })
+        const versions = await listVersions(this.localSyncKey)
+        return versions.map(v => ({ id: v.id, createdAt: v.createdAt, updatedAt: v.updatedAt, rowCount: v.data.length }))
       } catch (error) {
-        this.$emit('local-sync-error', { action: 'clear', error })
+        this.$emit('local-sync-error', { action: 'load', error })
+        return []
       }
     },
 
-    // Public, ref-callable: returns the saved copy's full { data, updatedAt }
-    // (or null) WITHOUT applying it to v-model and without opening the
-    // built-in modal — the pure "Read" a host needs to build its own custom
-    // UI (preview/inspect the saved rows, decide what to do, etc.), as
-    // opposed to restoreLocalSnapshot() which reads AND immediately commits
-    // the result into v-model as one step.
-    async getLocalSnapshot() {
-      if (!this.localSyncKey) return null
+    // Public, ref-callable: the full { id, data, createdAt, updatedAt } for
+    // one saved version, WITHOUT applying it to v-model — the pure "Read"
+    // for a custom UI (as opposed to restoreLocalVersion(), which reads AND
+    // commits in one step).
+    async getLocalVersion(id) {
       try {
-        return await loadSnapshot(this.localSyncKey)
+        return await getVersion(id)
       } catch (error) {
         this.$emit('local-sync-error', { action: 'load', error })
         return null
       }
     },
 
-    // Public, ref-callable: lightweight { updatedAt, rowCount } | null variant
-    // of getLocalSnapshot() — for a host that only wants to know whether/when
-    // something is saved (e.g. an "unsaved local changes" prompt on mount)
-    // without pulling the full row data across.
-    async getLocalSnapshotInfo() {
-      const snapshot = await this.getLocalSnapshot()
-      return snapshot ? { updatedAt: snapshot.updatedAt, rowCount: snapshot.data.length } : null
+    // Public, ref-callable: writes one saved version back into v-model
+    // (input/update:data) — the modal's "Restore" button calls this too.
+    async restoreLocalVersion(id) {
+      try {
+        const version = await this.getLocalVersion(id)
+        if (!version) return
+        this.$emit('input', version.data)
+        this.$emit('update:data', version.data)
+        this._lastFlushedDataRef = version.data // what's now on screen is already what's stored
+        this.localSyncAvailable = false
+        this.$emit('local-sync-restore', { key: this.localSyncKey, id, rows: version.data.length })
+        this.closeLocalSyncModal()
+      } catch (error) {
+        this.$emit('local-sync-error', { action: 'restore', error })
+      }
+    },
+
+    // Public, ref-callable: deletes one saved version — the modal's "Delete"
+    // button calls this too (after its own inline confirm step).
+    async deleteLocalVersion(id) {
+      try {
+        await deleteVersion(id)
+        if (this.localSyncModal.selectedId === id) {
+          this.localSyncModal.selectedId = null
+          this.localSyncModal.selectedVersion = null
+        }
+        this.localSyncModal.versions = this.localSyncModal.versions.filter(v => v.id !== id)
+        this.$emit('local-sync-clear', { key: this.localSyncKey, id })
+      } catch (error) {
+        this.$emit('local-sync-error', { action: 'clear', error })
+      }
     },
 
     // Public, ref-callable: opens the local-sync modal (also reachable via
-    // the toolbar button), loading the latest snapshot fresh each time.
+    // the toolbar button), loading the version list fresh each time.
     async openLocalSyncModal() {
       if (!this.localSyncKey) return
       this.localSyncModal.visible = true
-      this.localSyncAvailable = false // the draft has now been seen
-      try {
-        this.localSyncModal.snapshot = await loadSnapshot(this.localSyncKey)
-      } catch (error) {
-        this.localSyncModal.snapshot = null
-        this.$emit('local-sync-error', { action: 'load', error })
+      this.localSyncAvailable = false // the version(s) have now been seen
+      const versions = await this.listLocalVersions()
+      this.localSyncModal.versions = versions
+      await this._selectLocalSyncModalVersion(versions.length ? versions[0].id : null)
+    },
+
+    // Internal: modal's list-selection handler — loads the selected
+    // version's full data for the nested-grid preview (EgLocalSyncModal.vue).
+    async _selectLocalSyncModalVersion(id) {
+      this.localSyncModal.selectedId = id
+      this.localSyncModal.selectedVersion = id ? await this.getLocalVersion(id) : null
+    },
+
+    // Modal's "Save" button — same as saveLocalVersionNow(), then refreshes
+    // the modal's own list/selection in place so the user sees it happened.
+    async _onLocalSyncModalSave() {
+      await this.saveLocalVersionNow()
+      const versions = await this.listLocalVersions()
+      this.localSyncModal.versions = versions
+      await this._selectLocalSyncModalVersion(versions.length ? versions[0].id : null)
+    },
+
+    // Modal's "Delete" button (after its own inline confirm) — deletes the
+    // given version, then selects the next-most-recent one if the deleted
+    // one was selected.
+    async _onLocalSyncModalDelete(id) {
+      await this.deleteLocalVersion(id)
+      if (this.localSyncModal.selectedId == null) {
+        const remaining = this.localSyncModal.versions
+        await this._selectLocalSyncModalVersion(remaining.length ? remaining[0].id : null)
       }
     },
 
@@ -6371,6 +6549,7 @@ const ExcelGridComponent = {
       this.internalLocked = !this.internalLocked
       this.$emit('update:locked', this.internalLocked)
       this.$emit('lock-change', { locked: this.internalLocked })
+      this._flashLock(this.internalLocked)
     },
 
     // Pops a big lock/unlock icon in the center of the grid and fades it