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.