fix(charts): distinguish offline from loading; make retry reachable [PERA-4581]

[fmsouza]

Description

Charts previously collapsed every failure mode into isPending ? spinner : isError ? error : …. A query paused offline reports isPending: true forever, so true offline meant an eternal spinner with an unreachable retry, and chart data was never persisted, so cold offline starts had nothing to show. This PR makes the chart stack paused-aware and cache-friendly:

• New useBalanceLineChart hook (colocated with BalanceLineChart) implementing the epic's data-first state contract: chart (fresh or stale) → offline → error → loading → empty. Stale data always beats state screens; a paused query renders a localized offline state (common.offline_mode / common.offline_refresh_body — no new i18n strings) instead of the spinner.
• Offline-guarded retry: the retry button reads useNetworkStatusStore.getState().hasInternet at press time and short-circuits while offline instead of dispatching a doomed 30 s request; an errored query on a known-offline device also collapses into the offline surface. Refetch auto-resumes on reconnect via the existing onlineManager wiring.
• isPaused threaded from the raw query results through WealthChart, AssetPriceChart, and AssetWealthChart; PriceTrend logic extracted into a colocated usePriceTrend hook that hides the trend (instead of showing a fake 0.00%) when paused with no data.
• Persistence allowlist: shouldDehydrateQuery extracted from QueryProvider into a testable apps/mobile/src/providers/query-persistence.ts; successful ['accounts','balance-history',…] and ['assets','prices','history',…] snapshots are now dehydrated (network-only, no SQLite table backs them, no PII) so last-known charts survive restarts within reactQueryPersistenceAge. New key predicates isAccountBalancesHistoryQuery / isAssetPriceHistoryQuery live in their packages; the per-account asset-history key is deliberately NOT allowlisted (ticket scope).
• CHART_QUERY_TIMEOUT_MS kept at 30 s — decision documented in docs/OFFLINE_PAUSED_STATE.md: no production latency data to justify lowering it, the endpoints are documented as routinely exceeding ky's 10 s default, and the offline short-circuit removes the doomed-wait UX that motivated reconsidering it.
• Online behavior unchanged: LineChart props, intervals, ranges, and pointer interactions untouched; chart queries stay pure-network (networkMode untouched, per the paused-state contract doc).

Related Issues

• Closes https://algorandfoundation.atlassian.net/browse/PERA-4581
• Epic: https://algorandfoundation.atlassian.net/browse/PERA-4569 ([RN] Offline Resilience, wave 2; depends on PERA-4572 / PERA-4574, both landed)

Checklist

• Have you tested your changes locally? (pnpm pre-push green; full pnpm test green — 549 files / 3937 mobile tests; every change built TDD red→green)
• Have you reviewed the code for any potential issues?
• Have you documented any necessary changes in the project's documentation? (docs/OFFLINE_PAUSED_STATE.md: chart adoption of the paused-state contract, persistence allowlist rationale, timeout decision)
• Have you added any necessary tests for your changes? (hook specs for useBalanceLineChart + usePriceTrend, component branch tests incl. paused/offline-retry, query-persistence eligibility spec, package-level key-predicate tests)
• Have you updated any relevant dependencies? (N/A — no dependency changes)

Additional Notes

• Design/QA glance suggested (offline-only visual nit): when PriceTrend hides offline, the AssetMarkets trend row's space-between layout left-aligns the lone date text.
• AssetWealthChart got isPaused threading (same shared component, same eternal-spinner bug) but its query key is intentionally outside the persistence allowlist, matching the ticket's explicit scope.

🤖 Generated with Claude Code

[yasin-ce]

🔴 Blocking

• common.offline_refresh_body no longer exists on main — the offline body will render the raw key after rebase. (BalanceLineChart.tsx:96)

  The PR branch is 3 commits behind main and its en.json still carries this key via an inherited pre-revert merge — but #1014 (75f5fe049, the PERA-4586 revert) removed it from main, and no commit unique to this PR re-adds it. So on the branch it works, but once you bring main in (which you must to merge), t('common.offline_refresh_body') falls through to the literal string and the user sees common.offline_refresh_body as the offline body.

  The PR description's "reuses existing common.offline_mode / common.offline_refresh_body" is only true against the stale base — on current main, offline_mode survives (it predates #986) but offline_refresh_body does not.

  Fix: add common.offline_refresh_body to en.json in this PR. (Rebase first — the tests import real i18n, so a rebased branch would surface this immediately.)

🟡 Should-fix

Nothing blocking-adjacent. The one real item is above.

⚪ Nits

• period ?? 'one-week' in usePriceTrend.ts:749 is dead — UsePriceTrendParams.period is the required HistoryPeriod, so the fallback can't fire. It's faithfully carried over from the old inline code, so not a regression; either drop the ?? 'one-week' or make the param period?: if callers can actually pass undefined.
• A couple of the intent comments run long (the renderState and allowlist blocks). They explain real gotchas so I'd keep them, but we've been trimming comment verbosity lately — could tighten.

🔵 Questions / awareness

• Retry button in the offline state is visible but no-ops while offline (useBalanceLineChart.ts:412-419). The guard is sound (skip the doomed 30s request), but should we show a button that silently does nothing when tapped, given the copy already promises an auto-refresh on reconnect? Not blocking — the same button works the instant connectivity returns — just worth a UX confirm.
• usePriceTrend's isHidden = isPaused && !chartData treats an empty array as "has data" (![] is false), so a paused query resolved with [] would render a 0.00% trend rather than hiding. Edge-y (a paused query rarely carries data: []) — flag for awareness, not a change.
• The shouldDehydrateQuery allowlist correctly runs ahead of the exclusion block (a balance-history key also matches isAccountQuery, so order matters) — nicely done and tested. Confirm the two predicates stay prefix-only ([0]/[1], and [2] for price history) if the query-key shapes ever change; the negative tests guard exactly this.

[wjbeau]

nit: this nested ternary thing is super hard to read - might be worth a renderEmptyView() function or something to do it with some slightly saner branching or switches