datetime/calendar_heatmap_utils library

GitHub-style contribution-heatmap data builders — roadmap #603.

Aggregates timestamped events into per-day counts, lays them out as a week-by-week grid for a contribution-graph widget, and summarizes the totals. All keying is DATE-ONLY: every event's time component is dropped and it is bucketed under local midnight of its calendar date, so two events at 09:00 and 23:00 on the same day count as that one day.

The grid is column-major by week: each inner list is one calendar week of 7 day-counts, aligned so index 0 is the configured weekStartsOn weekday. Days before start or after end within a partial first/last week are padded with 0, so every row is always length 7.

Functions

dailyCounts(Iterable<DateTime> events) → Map<DateTime, int>

Counts how many events fall on each calendar date, keyed by date-only local midnight (the time of day is ignored).

heatmapGrid(Map<DateTime, int> daily, DateTime start, DateTime end, {int weekStartsOn = DateTime.monday}) → List<List<int>>

A list of weeks (each a length-7 list of counts) covering start..end inclusive, with each inner row beginning on weekStartsOn.

heatmapStats(Map<DateTime, int> daily) → ({int activeDays, int maxCount, int total})

Summary stats for a date-keyed count map: the busiest day's maxCount, the total across all days, and the number of activeDays with a non-zero count.