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

[Priyanshu-byte-coder]

Thanks @YamiNo-Okami for the date range picker! The preset range buttons and custom date support look great for the heatmap. However, there's one issue that blocks merging:

Please remove .gitignore and package-lock.json changes from this PR.

Adding package-lock.json to .gitignore is not correct — it should remain tracked so that CI and installs are reproducible. The heatmap feature in ContributionHeatmap.tsx is the valuable part of this PR and can merge on its own.

Please update your branch to remove those two files from the diff, and we'll merge the heatmap changes!

[YamiNo-Okami]

@Priyanshu-byte-coder , Removed changes as requested and updated branch with new changes, please review

[github-actions]

🎉 Merged! Thanks for contributing to DevTrack.

If the project has been useful to you, a ⭐ star on the repo is the easiest way to support it — it helps DevTrack get discovered by more developers.

Keep an eye on open issues for your next contribution!

[YamiNo-Okami]

Thank you @Priyanshu-byte-coder for accepting my contribution. I really enjoyed contributing to the project.

Please let me know if there are any available issues I can work on. I’d love to contribute more.

Thanks!