8739805f99
Some checks failed
Auto-update PR branches / Update open PR branches (push) Has been cancelled
CI / Frontend Static Quality Checks (push) Has been cancelled
CI / Frontend Tests & Coverage (push) Has been cancelled
CI / Rust Tests & Quality Checks (push) Has been cancelled
CI / Linux build verification (push) Has been cancelled
Release (Alpha) / Compute alpha version (push) Has been cancelled
Release (Alpha) / Build release artifacts (push) Has been cancelled
Release (Alpha) / GitHub Release (alpha) (push) Has been cancelled
Release (Alpha) / Update docs and release pages (push) Has been cancelled
Deploy docs / Build VitePress site (push) Has been cancelled
Deploy docs / Deploy to GitHub Pages (push) Has been cancelled
1.9 KiB
1.9 KiB
type, id, title, status, date
| type | id | title | status | date |
|---|---|---|---|---|
| ADR | 0060 | Network-aware UI gating for remote-dependent features | active | 2026-04-13 |
Context
Some app features require an active internet connection (e.g., cloning the Getting Started vault template from GitHub). Prior to this decision, the UI would attempt the operation and surface a generic error only after failure. Users on first launch in offline environments got a confusing error when trying to use the template.
Decision
Introduce a useNetworkStatus hook that tracks navigator.onLine via online/offline DOM events, and use it to proactively gate UI surfaces that require a network. Features that depend on remote access (clone, sync) show an explanatory message and disable their action button when the device is offline, rather than failing silently at execution time.
Options considered
- Option A (chosen):
useNetworkStatushook + proactive UI disable — disables the action before the user tries it, with inline copy explaining the offline state. - Option B: Attempt and catch — let the operation run and surface the error in a toast. Simpler, but poor UX for first-launch users who don't know what went wrong.
- Option C: Check connectivity with a ping on demand — more accurate but adds latency and complexity;
navigator.onLineis sufficient for the use case.
Consequences
- Positive: cleaner first-run experience for offline users; no misleading error messages.
- Positive:
useNetworkStatusis a reusable hook for future remote-gated features. - Negative:
navigator.onLinecan returntrueon a captive-portal / no-internet network — the hook reflects OS-level connectivity, not end-to-end reachability. The operation may still fail with a network error, which must still be handled. - Re-evaluate if the app adds more remote features that need finer-grained reachability checks.