ramadan-calendar-and-fasting-logic

name	ramadan-calendar-and-fasting-logic
description	Ramadan calendar (start/end, day number, year boundary), fasting states (completed/skipped/broken), streak and todayOverride in TryRamadan. Use when editing src/lib/ramadan.ts, fasting state transitions, streak calculation, or Ramadan day labels.

Ramadan Calendar and Fasting Logic (TryRamadan)

Use this skill when working on Ramadan dates, fasting state (completed/skipped/broken), streak, or "today" vs timezone so behavior stays consistent with the documented model.

---

1. Ramadan calendar (src/lib/ramadan.ts)

• Start/end: RAMADAN_START_BY_YEAR (Gregorian); getRamadanStartForYear, getRamadanEndForYear. Cross-year Ramadan (e.g. 2030-12-26 → 2031-01-23) is handled in isRamadanDay and getRamadanDayNumber.
• Missing year: Code falls back to ~11 days earlier from a reference year; add a test for missing year and consider logging or in-app note when using fallback.
• Tests: src/test/ramadan.test.ts. See docs/QA-RAMADAN-LOGIC-AND-TEST-CASES.md and docs/EDGE-CASE-TEST-SCENARIOS.md (calendar & Ramadan boundaries).

---

2. Fasting states (per day)

• Data: progress.completedDays, progress.skippedDays, progress.fastingLog (entries with status: 'in_progress' | 'completed' | 'broken', optional brokenReason).
• Transitions: startFastingToday → in_progress; completeFastingToday → completed + add to completedDays; breakFastingToday → broken (remove from completedDays, store reason); setDaySkipped → skipped (remove from completedDays, clear log for that date); uncompleteFastingToday / setDayCompleted(..., false) → remove from completedDays.
• Excused: brokenReason in ['illness','travel','menstruation','medical'] = excused; stats and streak treat excused as streak-preserving (see streaks-stats-gamification skill).
• State-transition table and invalid transitions: docs/STATE-TRANSITION-TESTING-FASTING.md. When changing transitions, ensure UI blocks or warns on invalid transitions.

---

3. "Today" and todayOverride

• Display timezone: When displayTimezone is set, "today" = location's date (getTodayStringInTimezone(displayTimezone)). Pass this as todayOverride into: getTodayFastingLog(progress, todayOverride), isFastingToday(progress, todayOverride), startFastingToday(..., todayOverride), completeFastingToday(..., todayOverride), breakFastingToday(..., todayOverride), getStreakDays(progress, todayOverride), calculateStreak(progress, todayOverride).
• Dashboard, Today, Progress, Settings, Achievements: All use todayStr from display timezone when set and pass it into streak and fasting helpers so streak and day label stay in sync.
• Bug risk: If streak or "today" uses device-local date while the rest of the app uses display timezone, streak can show 0 or wrong day. Always pass the same "today" used for the UI.

---

4. Ramadan calendar override (user-defined Ramadan days)

• Doc: docs/RAMADAN-CALENDAR-ROBUSTNESS-AND-OVERRIDE.md. Covers app vs community start/end difference, manual override of "Ramadan days," and edge cases (logging before/after app’s Ramadan, voluntary fasts still labeled Ramadan). Implement override and labeling so the experience stays coherent with user control.

---

5. Tests

• Ramadan dates: src/test/ramadan.test.ts.
• Fasting / streak / todayOverride: src/test/loggingAndTracking.test.ts (including Regression: BUG-STRK-001).
• When changing Ramadan or fasting logic, add or update tests and check STATE-TRANSITION-TESTING-FASTING and EDGE-CASE-TEST-SCENARIOS for coverage.