tryramadan-local-storage-and-persistence

name	tryramadan-local-storage-and-persistence
description	Local storage and persistence in TryRamadan. Covers useLocalStorage hook, persistPreferencesSync and persistQuickActionsSync, cache keys for preferences progress prayer times and Ramadan month, and when to persist before navigation. Use when adding or changing stored state, onboarding completion, or any feature that reads/writes localStorage.

Local Storage and Persistence (TryRamadan)

Use this skill when adding or changing stored state, onboarding completion, or sync before navigation so the app and dashboard read fresh data.

---

1. Core hook: useLocalStorage

• Location: src/hooks/useLocalStorage.ts.
• Signature: useLocalStorage<T>(key: string, initialValue: T): [T, (value: T | ((prev: T) => T)) => void].
• Behavior: Reads from localStorage on mount (falls back to initialValue on parse error). Writes to localStorage in useEffect whenever state changes. Key must be unique per store.

---

2. Preferences and quick actions (sync before navigation)

• Preferences: persistPreferencesSync(partial) merges partial into current preferences and writes to tryramadan-preferences. Call before navigating away from onboarding so Dashboard sees up-to-date preferences (e.g. onboardingComplete, location, timezone).
• Quick actions: persistQuickActionsSync(order) writes dashboard quick-action order to tryramadan-dashboard-quick-actions. Call before navigation when order was updated (e.g. from onboarding or Settings).
• Usage: OnboardingGoals and OnboardingLayout call persistPreferencesSync(newPrefs) and persistQuickActionsSync(getQuickActionOrderFromPriorities(priorities)) before navigating to dashboard.

---

3. Main storage keys

Key	Purpose
tryramadan-preferences	User preferences (theme, location, timezone, priorities, macro/sex/weight, etc.).
tryramadan-progress	Fasting progress (completedDays, fastingLog).
tryramadan-daily-goals	Daily calorie and macro goals.
tryramadan-dashboard-quick-actions	Ordered list of quick-action IDs.
tryramadan-prayer-times-cache	Single entry: today’s prayer times for (dateStr, lat, lng).
tryramadan-ramadan-prayers	Ramadan month prayer times by lat_lng_year.
tryramadan-notifications	Notification settings (suhoor/iftar minutes before, etc.).
tryramadan-today	Per-date today data (hydration, energy, intention).
tryramadan-journal	Journal entries.
tryramadan-daily-goals	Calories, protein, carbs, fat goals.

---

4. "Today" and location-based date

• Fasting log / completion: When displayTimezone is set, "today" should be location’s date (getTodayStringInTimezone(displayTimezone)). Helpers accept optional todayOverride: getTodayFastingLog(progress, todayOverride), isFastingToday(progress, todayOverride), startFastingToday(..., todayOverride), etc. Pass todayStr from the component when it’s derived from display timezone so countdowns and log stay in sync.
• Dashboard / FastingBottomBar: Compute todayStr from displayTimezone when set and pass it into these helpers and into start/complete/break/uncomplete.

---

5. Cache invalidation

• Prayer times (today): Cache is keyed by (dateStr, lat, lng). New day or new location → cache miss → fetch. See timezone-and-countdown skill.
• Ramadan month: Keyed by lat, lng, Ramadan year. New location or new year → new key → fetch. Stale after 7 days.
• Preferences: No automatic invalidation; user changes location/settings in Settings and state updates.

---

6. Tests

• File: src/test/localStorage.test.ts – persistPreferencesSync, persistQuickActionsSync, useLocalStorage (initial, read, write, invalid JSON), getSuggestedCalories, daily goals persistence.
• When adding new keys or sync logic, add tests for round-trip and merge behavior where applicable.