abdullah-cse/contribution_heatmap

1. This repository is a Flutter package, not a standalone app. The primary deliverable is the contribution_heatmap library under lib/, which is published to pub.dev and exercised by a multi-platform example app plus a separate web playground.

2. The public API is thin and centered around lib/contribution_heatmap.dart and lib/src/widgets/contribution_heatmap.dart. This widget is the integration boundary for consumers: they pass contribution data, styling, date-range options, locale/weekday preferences, and an optional tap callback.

3. The core domain model is ContributionEntry in lib/src/models/contribution_entry.dart. It represents day-level contribution counts and is the input to the whole rendering pipeline. The package is designed around a date-to-count mapping rather than live state or network data.

4. Rendering is handled by a custom RenderBox in lib/src/rendering/render_contribution_heatmap.dart. This is the main architectural choice in the repo: instead of composing many Flutter widgets, the heatmap is painted directly for performance, with custom layout, drawing, and hit testing.

5. Data flow is: input entries are normalized and indexed into fast lookup structures, the date span is derived from minDate/maxDate or the data itself, and the renderer converts that timeline into a grid of cells. Each cell is painted according to contribution intensity, with optional month separators, weekday labels, and date numbers inside cells.

6. Utility code is split by concern. heatmap_utils.dart appears to handle date/grid calculations and month-splitting logic, heatmap_color_utils.dart maps counts to HeatmapColor palettes, and heatmap_localizations.dart handles locale-aware labels and translations. These utilities are the main computation layer beneath the render object.

7. The package exposes a small set of enums in lib/src/enum/, mainly HeatmapColor and WeekdayLabel. These control visual palette selection and weekday-label behavior, including the migration path from the older showWeekdayLabels boolean to the newer enum-based API.

8. Interaction is built into the rendering layer rather than added externally. Tap handling flows from hit testing in the custom render object to the onCellTap(DateTime, int) callback, so consumers can respond to user interaction without needing to wire up separate gesture widgets around the heatmap.

9. The repository includes a full example/ Flutter application scaffolded for Android, iOS, web, macOS, Linux, and Windows. That example is the integration reference for package users and demonstrates the widget in a real app shell across platforms.

10. There is also a separate contribution_heatmap_playground/ app, which is a web-focused interactive playground. Its role is product/demo infrastructure: users can experiment with settings, preview generated code, and visually inspect the widget without writing their own app first.

11. Testing is organized around the same subsystem boundaries as the library: model tests, utility tests, and widget/rendering tests under test/. That suggests the package’s risk areas are date math, color mapping, localization, and custom rendering behavior rather than business logic or backend integration.

12. CI/CD is lightweight and package-oriented. GitHub Actions workflows build and publish the package, while coverage is reported through Codecov. The repo’s lifecycle is therefore “library development → test/build → publish,” with no server-side runtime or persistent storage layer.