Skip to content

v1.18.0: Backup status in the sync badge; save before leaving - #23

Open
gitluis wants to merge 5 commits into
settings-database-tabfrom
save-status-indicator
Open

gitluis wants to merge 5 commits into
settings-database-tabfrom
save-status-indicator

Conversation

@gitluis

@gitluis gitluis commented Nov 2, 2026 •

Copy link
Copy Markdown
Owner

Stacked on #10 (settings-database-tab), the last PR of the Clarity redesign and fix stack. Merge order: #16, #17, #19, #20, #21, #24–#38, #39–#50, then #10, then this.
Latest merge 819e809 brings in #39–#50 through #10 (no code conflicts). The full set ran on it, every base suite and every fix test of the stack: all pass, race.js 0 errors. Three tests needed test-only changes there: test-drawer-fields.js waits after Re-categorize all (async since #48), test-card-override.js sets aside #45's trend lines, and test-minor-fixes.js reports #10's db-tools view instead of failing on it. test-dbtab.js now expects 1.18.0, 1.17.0, 1.16.27 … 1.16.0.

Summary

The app bar's sync badge now says whether finlens-state.json is up to date, and FinLens stops the backup from falling behind when you leave right after a change. This is #23 rebuilt on the Clarity redesign. The original put a status line in the old sidebar, which the redesign removed.

Badge When Tooltip Click
Synced The last save worked and nothing is waiting "Saved at 10:42 AM to finlens-state.json in “FinLens Data”." Opens Settings → Import
Saving… From a change until it's written (the 1.5 s wait, then the write) "Saving your changes to finlens-state.json in “FinLens Data”." Opens Settings → Import
Not synced No folder connected "…no folder is connected, so changes are saved in this browser only…" Opens Settings → Import
Not synced Folder access lapsed "…FinLens needs your permission again to save to “FinLens Data”…" Reconnect
Not synced The last save failed "…the last save to “FinLens Data” failed (disk full)…" Retry (save now)
  • Leave warning: while a save is waiting or running and the folder is writable, closing or reloading starts the save at once and the browser asks "Leave site?".
  • Tab hidden: switching tabs or minimizing writes a waiting save right away.
  • Shorter wait: 1.5 s after the last change instead of 5 s.

What changed

Kept from the original #23

  • The save scheduler (_saveStateDebounced(), SAVE_DELAY_MS = 1500, State._savePending, State._saving), flushPendingSave(), backupWouldBeLost(), and the visibilitychange flush, in js/core.js.
  • A manual save cancels a waiting one, since it writes State as it is at that moment.
  • When the leave warning doesn't appear: no folder, access lapsed, Start over in progress, nothing waiting.
  • The five statuses, now folded into the badge (table above).

Changed for the app bar

  • One badge, Luis's wording at rest. v1.18.0: Backup status in the sync badge; save before leaving #23's "Saved 10:42 AM", "Backups paused · Reconnect", "Backup failed · Retry" and "Backups off" became Synced and Not synced; the tooltip says which case and what a click does. Saving… is new to the badge.
  • The click matches the state. syncBadgeState() (views-data.js) gives each state its label, tooltip, accessible name and action; updateSyncBadge() draws it and syncBadgeClick() runs it. Before this PR the badge's click for a failed save only opened Settings; now it retries (syncRetryClick()). Reconnect and Retry run from the click, as §14 requires.
  • Saving… doesn't flicker. A burst of edits keeps it on Saving… until one write, the pill is neutral (--muted, --text-2) with a slowly pulsing dot (steady with reduced motion), and a min-width makes Synced and Saving… the same width.
  • Accessibility. The button's name starts with the visible label and ends with its action ("Not synced, folder access lapsed. Reconnect folder"). A polite role="status" region (#syncStatus) announces when backups stop or come back. It never announces Saving…, or Synced after an ordinary save.
  • The leave listener is attached only while it's needed (_syncLeaveGuard()). v1.18.0: Backup status in the sync badge; save before leaving #23 kept one attached all the time and checked inside it. An always-on beforeunload listener can keep the page out of the back/forward cache.
  • Folder detection uses the redesign's State._folderLinked (a stored handle). v1.18.0: Backup status in the sync badge; save before leaving #23's State._noBackupFolder and hasBackupFolder() did the same job and are dropped.
  • The leave listener stays attached until the prompt is answered. Testing found that when the save finishes inside the beforeunload event (a fast write completes in its microtasks), removing the listener then cancels Chromium's prompt. _leaveGuardHold keeps it until the prompt closes. The original v1.18.0: Backup status in the sync badge; save before leaving #23 didn't hit this, because its listener was never removed.
  • Start over: State._resetInProgress now also cancels a waiting save, so nothing is scheduled or written during the reset.
  • Kept from v1.10.5: fix Import Logs throwing when the view is left before it loads #18 / §14 unchanged: State._folderNeedsAccess, the Reconnect banner, State._lastSaveError, the folder-permission checks.
  • Dropped: the sidebar status element, its CSS and the --sidebar-bad token (no sidebar any more); v1.18.0: Backup status in the sync badge; save before leaving #23's [1.17.0] CHANGELOG entry and version strings (v1.17.0: Settings → Database tab (DB Inspector, DB Schema), rebuilt on the Clarity redesign #10 is v1.17.0).

Files: js/core.js, js/views-data.js, index.html (badge style, live region, footer), README.md, CLAUDE.md (§1, §4.5, §6, §8, §9, §12, §14, Last updated), CHANGELOG.md, js/views-settings.js. Version v1.18.0.

Merge: settings-database-tab was merged into this branch first. All seven files #23 touched conflicted; each was resolved by taking the redesign's version, and the feature was rebuilt in the next commit.

Not verified

  • A real folder picked with the system dialog, the real permission prompt, and a real disk error. The tests use a fake handle; headless Chrome can't show the folder picker.
  • Closing the whole browser (not a tab) with a save waiting. Browsers often skip the prompt then; the save may not finish.
  • A screen reader. The accessible names and the live region were checked in the accessibility tree and the DOM, not with NVDA, JAWS or VoiceOver.
  • An announcement while a drawer is open is lost: the drawer makes the app bar inert. Saves run 1.5 s after a drawer closes, so this only happens when a save finishes or fails while a drawer is open; the badge still shows it.
  • Phone widths (desktop only, Luis's decision).
Automated checks: earlier run, not re-run · 60c9c7c

Moved unchanged from this PR's "Test results" comment on 2026-11-04; not re-run, so not in the new table format. Originally a description section titled "How it was tested".

Headless Chromium (Playwright), samples only, at 1280px, in light and dark. CDNs are served from npm (the SRI hashes still verify).

All on 60c9c7c, one suite at a time:

Suite Result
test-clarity.dbtab 55/55
test-insights.dbtab 137/137
test-finances 126/126
test-plan 127/127
test-clear-edits 47/47
test-rebuild-folder 57/57
test-partial-import 47/47
test-json-import 28/28
test-new-browser-copy 10/10
test-json-export 31/31
test-plan-links 60/60
test-rule-flags 67/67
test-drawer-flags 36/36
test-start-balance 193/193
test-ai-summary-period 78/78
test-account-names 40/40
test-account-order 32/32
test-drawer-focus 167/167
test-cleanup 21/21
test-dbtab 73/73
test-master-port (#14, #15) 16/16
test-save-status (new) 64/64
boot 257 transactions, 25 views, 0 errors
race (every screen, no pause) 25 views, 0 errors

That's 1,512 checks. The same suites (without test-save-status) passed 1,448/1,448 on the merge commit before the rebuild.

New suite test-save-status.js (64 checks). It uses a fake folder handle installed in front of init.js, as test-clear-edits.js does, with switches for a lapsed permission, a write that throws and a write held open. It covers #23's own checks and:

  • every badge state's label, tooltip, accessible name (getByRole('button', { name })) and click;
  • Saving… during the 1.5 s wait and during the write, then Synced; a burst of two changes 0.8 s apart makes one write; ten changes 100 ms apart change the label only twice (Saving…, Synced);
  • the beforeunload listener attached only while a save is pending (counted with CDP DOMDebugger.getEventListeners);
  • closing with a save waiting shows the dialog, and after staying the file has the change; closing with nothing waiting shows none;
  • tab hidden writes a waiting save within 300 ms;
  • access lapsed → Reconnect from the click (the fake records that requestPermission() ran with user activation); a failing Retry is announced again; a Retry refused at the prompt moves to Reconnect;
  • Start over: nothing scheduled or written while it runs, no "Leave site?", the file stays gone;
  • the live region's announcements; the dot's animation off with reduced motion;
  • AA contrast of the badge text in every state, both themes;
  • every view on http:// with saves in flight and on file://, with no errors.

Existing checks changed in my copy: two suites, for reasons this PR changes on purpose:

  • test-clarity.dbtab, Synced state and A failed save shows "Not synced" with the reason: the test fakes badge states with updateSyncBadge() about 0.3 s after a theme change. That change's real save is still waiting then, so the badge now rightly says "Saving…". And at 1.5 s (5 s before) the save runs during the sequence, finds no folder and resets _folderLinked. Fix: wait for !State._savePending && !State._saving before faking. No assertion changed.
  • test-dbtab, the three version checks: v1.18.0 is now current (footer, Settings → General, README, CLAUDE.md §1 and Last updated), and the CHANGELOG runs [1.18.0], [1.17.0], 1.16.15 … 1.16.0.

Screenshots of the badge in every state, light and dark, were reviewed (Synced, Saving…, and Not synced for no folder, access lapsed and a failed save). Synced and Saving… are the same width; text is clear in every state. Measured contrast: 6.4–6.9:1 light, 7.3–10.9:1 dark.

Manual QA steps

Setup

  1. git checkout save-status-indicator.
  2. Copy the three CSVs from samples/ into a new scratch folder, e.g. C:\temp\finlens-23. This PR is about saving finlens-state.json, so never use your real folder.
  3. Open index.html in Edge. Keep F12 → Console open for the whole run: each write logs [FinLens] Auto-saved state to finlens-state.json.

The badge is the pill at the right of the app bar, left of the date-range button. Hover over it to see its tooltip.

1. No folder: Not synced, and the click opens Import

  1. With no folder connected (a fresh browser, or right after Setup step 3), look at the badge.
  2. Hover over it.
  3. Click it.

Expected:

  • Amber Not synced. Tooltip: "Not synced: no folder is connected, so changes are saved in this browser only. Click to pick a folder in Settings → Import."
  • The click opens Settings → Import.
  • Changing something (e.g. Settings → General → Dark) never shows Saving…, and nothing is logged.

2. Connect the folder: Synced, with the save time

  1. On Settings → Import, click Pick a folder, choose the scratch folder, allow read and write access.
  2. Wait 2 seconds and look at the badge. Hover over it.
  3. Look at the Auto-save tile on the Import tab.

Expected:

  • Green Synced. Tooltip: "Saved at to finlens-state.json in “finlens-23”." (or "Synced: changes are saved…" if no save has happened yet in this page).
  • Auto-save reads 1.5 seconds after a change (was 5 seconds).
  • finlens-state.json now exists in the scratch folder.

3. A change shows Saving… for about 1.5 s, then Synced

  1. Go to Settings → General. Click Dark, then Light, then Dark quickly (under a second apart).
  2. Watch the badge.
  3. Hover over it while it says Saving….

Expected:

  • The badge goes to grey Saving… with a pulsing dot, stays there through the burst, then turns Synced about 1.5 s after the last click.
  • The Console shows one Auto-saved state to finlens-state.json for the burst, not three.
  • Tooltip while saving: "Saving your changes to finlens-state.json in “finlens-23”."
  • The pill doesn't change width between Synced and Saving….
  • Clicking the badge while it says Saving… or Synced opens Settings → Import.

Before this PR: the badge stayed Synced during the 5-second wait, with no sign a save was pending.

4. Leaving right after a change asks "Leave site?" and writes the save

  1. Click anywhere in the page once (the browser only asks after a click or keypress).
  2. Go to Transactions, open a row, change its Description to LEAVE TEST, click Save changes.
  3. Within 1 second, press F5.
  4. In the "Leave site?" dialog, click Cancel.
  5. Repeat steps 2–3 with LEAVE TEST 2, and this time click Reload (or Leave).
  6. After the reload, open finlens-state.json in a text editor and search for LEAVE TEST 2.

Expected:

  • The browser's "Leave site?" dialog appears in both runs.
  • After Cancel, the badge turns Synced within a moment (the save ran when you tried to leave).
  • After Reload, the file contains LEAVE TEST 2.
  • Wait 3 seconds after a change, then press F5: no dialog.

5. Switching tabs writes a waiting save at once

  1. Make a change (e.g. Settings → General → Light).
  2. Within 1 second, press Ctrl+T to open a new tab, then come back.

Expected:

  • The Console shows Auto-saved state to finlens-state.json logged at the moment you switched, not 1.5 s later. The badge reads Synced when you return.

6. Folder access lapsed: Not synced, the click reconnects, no leave prompt

  1. Close the FinLens tab (not just F5: access only lapses when the tab is closed and reopened).
  2. Open index.html again in a new tab.
  3. Look at the badge and the banner, hover over the badge.
  4. Make a change (e.g. Settings → General → Dark) and press F5 within 1 second.
  5. Click the badge.

Expected:

  • Amber Not synced; tooltip: "Not synced: FinLens needs your permission again to save to “finlens-23”. Your data is safe in this browser. Click to reconnect." The Backups paused banner shows Reconnect folder.
  • Step 4: no "Leave site?" dialog (nothing can be saved, so nothing to wait for).
  • The badge click shows the browser's permission prompt. After Allow, the badge turns Synced and the banner goes.

7. A failed save: Not synced, the click retries

  1. With the folder connected and Synced, rename the scratch folder in File Explorer (e.g. to finlens-23-x).
  2. Make a change (Settings → General → Light) and wait 2 seconds.
  3. Hover over the badge.
  4. Rename the folder back to finlens-23.
  5. Click the badge.

Expected:

  • After step 2: amber Not synced; tooltip "Not synced: the last save to “finlens-23” failed (). Your data is safe in this browser. Click to try again." The Console shows Failed to save state to file.
  • After step 5: the badge goes Saving… then Synced, without opening Settings.
  • Clicking the badge while the folder is still renamed leaves it at Not synced.

If renaming the folder doesn't make the save fail on your machine, note it: I couldn't confirm from the code which error Edge gives for a moved folder.

8. Regression: Save now, Start over, and the screen-reader text

  1. On Settings → Import, click Save now.
  2. Inspect the badge (F12 → Elements, Ctrl+Shift+C on the badge) and read its aria-label.
  3. On a throwaway copy: Settings → Data & reset → Start over, type RESET, click Erase and start over.

Expected:

  • Save now shows its usual ✓ message and the badge reads Synced.
  • aria-label starts with the visible text, e.g. "Synced, saved at 10:42 AM. Open Import settings".
  • Start over reloads the app with no "Leave site?" dialog, and finlens-state.json is not re-created in the folder (you'll see only the backup copy if you chose Keep a copy).
  • Settings → General → Version reads FinLens v1.18.0.

Please check before merging

  • Connect your folder, edit something, and watch the badge go Saving… → Synced. Hover it: the tooltip gives the time and folder.
  • Edit something and close the tab within a second: you should get "Leave site?", and after staying, the file should have the change.
  • Close and reopen the browser: the badge should say Not synced, the tooltip should say FinLens needs permission, and clicking it should ask for access.
  • The wording: Saving… is new next to your Synced / Not synced. Is it what you want, and is the neutral grey pill right for it?
  • A failed save's badge click now retries instead of opening Settings → Import. OK?
  • Merge order: after v1.17.0: Settings → Database tab (DB Inspector, DB Schema), rebuilt on the Clarity redesign #10 merges, retarget this PR to master if GitHub doesn't.
  • Manual QA passed in Edge/Chrome with a real folder

https://claude.ai/code/session_013Z8iBXzUjiQbYziDZ8CZft


Generated by Claude Code

- Sidebar status for finlens-state.json: Saving…, Saved h:mm, Backups paused
  (Reconnect), Backup failed (Retry), Backups off.
- beforeunload flushes a waiting save and asks the browser to confirm while
  a save is waiting or running and the folder is writable.
- Tab hidden flushes a waiting save immediately.
- Save delay 5 s -> 1.5 s; a manual save cancels a waiting one.
- CLAUDE.md §4.5/§8, README, Import tab text, CHANGELOG, version v1.17.0.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013Z8iBYnr2QiFrzchNxfCti
…e-status-indicator

Brings the Clarity redesign and fix stack (#16-#21, #24-#38, #10) into #23,
so its backup status can be rebuilt on the app bar.

All seven files #23 touched conflicted (CHANGELOG.md, CLAUDE.md, README.md,
index.html, js/core.js, js/views-data.js, js/views-settings.js). Each was
resolved by taking the redesign's version: the sidebar #23 built on is gone.
The tree now equals settings-database-tab at 477f357. The next commit
rebuilds #23's changes on the app bar's sync badge.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013Z8iBXzUjiQbYziDZ8CZft
Rebuilds PR #23 on the Clarity app bar. #23 put a backup status line in the
old sidebar, which the redesign removed; this folds it into the sync badge
and keeps Luis's resting wording.

- Badge: "Synced" (tooltip "Saved at 10:42 AM to finlens-state.json in ..."),
  "Saving..." while a save waits or runs (neutral pill, pulsing dot, same
  width as Synced), "Not synced" for no folder, access lapsed or a failed
  save. The tooltip gives the cause; the click opens Settings -> Import,
  reconnects, or retries the save (syncRetryClick). syncBadgeState() picks
  label, tooltip, accessible name and action in one place.
- Accessibility: the button's name starts with the label and ends with its
  action; a polite status region (#syncStatus) announces only when backups
  stop or come back, never "Saving...".
- Saves wait 1.5 s instead of 5 s (SAVE_DELAY_MS); a manual save cancels a
  waiting one; tab hidden flushes a waiting save.
- beforeunload: attached only while a save is waiting or running and the
  folder is connected and writable; flushes and asks the browser to confirm.
  The listener stays attached until the prompt is answered, since removing
  it during the event cancels the prompt.
- Start over (State._resetInProgress) cancels a waiting save and writes
  nothing. _folderNeedsAccess, the Reconnect banner, _lastSaveError and the
  permission checks are unchanged. #23's _noBackupFolder/hasBackupFolder()
  are replaced by the redesign's State._folderLinked.
- Import tab: "1.5 seconds after a change". README, CLAUDE.md (§1, §4.5,
  §6, §8, §9, §12, §14, Last updated), CHANGELOG; version v1.18.0.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013Z8iBXzUjiQbYziDZ8CZft
@gitluis gitluis changed the title v1.17.0: backup status in the sidebar; save before leaving v1.18.0: backup status in the sync badge; save before leaving Nov 2, 2026
@gitluis
gitluis changed the base branch from master to settings-database-tab November 2, 2026 15:38

gitluis commented Nov 2, 2026

Copy link
Copy Markdown
Owner Author

Rebuilt on the Clarity redesign.

🤖 Generated with Claude Code

https://claude.ai/code/session_013Z8iBXzUjiQbYziDZ8CZft


Generated by Claude Code

…s-indicator

Brings in the second fix chain through #10. Version stays v1.18.0; CHANGELOG
runs 1.18.0, 1.17.0, 1.16.27 ... (merged without conflict).

Conflicts (CLAUDE.md only):
- Section 14, prompting code: this branch's sync badge line, with the tab
  name the chain corrected ("Data & reset").
- Last updated: this branch's note, then #10's from v1.17.0 with the chain's
  history from v1.16.27.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013Z8iBXzUjiQbYziDZ8CZft
This was referenced Nov 2, 2026
…ve-status-indicator

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013Z8iBUZo6LRYpLthSp2PRi

# Conflicts:
#	CLAUDE.md
#	js/views-settings.js

gitluis commented Nov 4, 2026

Copy link
Copy Markdown
Owner Author

Dark theme taken out of the stack (Luis, 2026-11-04). #17 is light only for now: no ◐ toggle, no Light / Dark / Match system setting, no dark tokens. It comes back later in its own PR. #17's change was merged forward into this branch (no force push).


🤖 Generated with Claude Code

https://claude.ai/code/session_013Z8iBUZo6LRYpLthSp2PRi


Generated by Claude Code

@gitluis gitluis changed the title v1.18.0: backup status in the sync badge; save before leaving v1.18.0: Backup status in the sync badge; save before leaving Nov 5, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants