feat: Add flexible date range picker for contribution heatmap with presets, custom ranges, and persistence

[YamiNo-Okami]

Summary

This PR enhances the contribution heatmap by introducing a flexible date range selection system. Users can now inspect specific time windows such as recent activity, sprint periods, quarterly reviews, or fully custom ranges instead of being restricted to a fixed 365-day view.

The update also improves heatmap readability, URL shareability, and overall UX consistency.

Note: Around 40–50% AI assistance was used for understanding parts of the existing codebase structure, exploring implementation approaches, and helping refine/refactor some logic and UI behavior. All final integration, debugging, validation, and feature adjustments were manually reviewed and implemented.

---

Closes #939

Type of Change

• Bug fix
• New feature
• Documentation update
• Refactor / code cleanup

---

Changes Made

Features

• Preset range buttons: Quick access to 30d, 90d, 6mo, 1yr views
• Custom date range picker: Popover UI for selecting any custom date range
  • With validation: start < end, end not in future, max 2-year range
  • Clean error messaging for invalid selections
• URL query parameters: Date ranges now encoded in query params (?from=YYYY-MM-DD&to=YYYY-MM-DD)
  • Enables shareable links with preserved date context
• localStorage persistence: Selected range preference survives page reloads
• Dynamic heatmap rendering: Only displays cells relevant to selected range (not padded to full year)

Improvements

• Increased cell size (12px → 14px) for better visibility
• Improved cell opacity handling (40% for out-of-range, 100% for in-range)
• Fixed month label overlap with intelligent width calculation
• Enhanced header styling for better readability
• Integrated popover UI pattern (matching ContributionGraph component)

Technical

• Extended buildHeatmap() function to accept custom date ranges
• Refactored date calculation to use currentFrom/currentTo instead of just days
• Implemented popover dismiss handling (Escape key, click-outside)
• Added comprehensive date validation with user-friendly errors

API Integration

• Leverages existing /api/metrics/contributions endpoint support for ?from= and ?to= parameters
• Cache keys already include fromDate, so custom ranges are properly cached separately

Screenshots (if UI change)

For last 30 Days

For last 90 Days

For last 6 Months

For last Year

For Custom Date

Checklist

• Linked issue in summary
• npm run lint passes locally
• No TypeScript errors (npm run type-check)
• Self-reviewed the diff
• Added/updated tests if applicable

[vercel]

@YamiNo-Okami is attempting to deploy a commit to the PRIYANSHU DOSHI's projects Team on Vercel.

A member of the Team first needs to authorize it.

[github-actions]

Thanks for your first PR on DevTrack! 🎉

A maintainer will review it within 48 hours. While you wait:

• Make sure CI is passing (type-check + lint)
• Double-check the PR description is filled out and the issue is linked
• Feel free to ask questions in Discussions if you need help

If you find DevTrack useful, a ⭐ star on the repo is always appreciated — it helps the project grow and attract more contributors!

[github-actions]

GSSoC Label Checklist 🏷️

@Priyanshu-byte-coder — please apply the appropriate labels before merging:

Difficulty (pick one):

• level:beginner — 20 pts
• level:intermediate — 35 pts
• level:advanced — 55 pts
• level:critical — 80 pts

Quality (optional):

• quality:clean — ×1.2 multiplier
• quality:exceptional — ×1.5 multiplier

Validation (required to score):

• gssoc:approved — counts for points
• gssoc:invalid / gssoc:spam / gssoc:ai-slop — does not score

Type labels (type:*) are auto-detected from files and title. Review and adjust if needed.
Points formula: (difficulty × quality_multiplier) + type_bonus