### Install Package

Source: https://github.com/devappmin/flutter_heatmap_calendar/blob/main/README.md

Run this command in your terminal to install the package after adding it to pubspec.yaml.

```bash
flutter pub add flutter_heatmap_calendar
```

--------------------------------

### HeatMap onClick Example

Source: https://github.com/devappmin/flutter_heatmap_calendar/blob/main/_autodocs/api-overview.md

Example of how to implement the onClick callback in a HeatMap widget to print the tapped date.

```dart
HeatMap(
  onClick: (tappedDate) {
    print('Tapped: $tappedDate');
  },
)
```

--------------------------------

### Colorsets Parameter Example

Source: https://github.com/devappmin/flutter_heatmap_calendar/blob/main/_autodocs/types.md

Provides an example of the colorsets parameter, a Map<int, Color>, used for color mode selection. Keys represent thresholds, and values are the corresponding Color objects.

```dart
const Map<int, Color> colorsets = {
  0: Color(0xFFEBEDF0),    // Very light
  5: Color(0xFFC6E48B),    // Light green
  10: Color(0xFF7BC96F),   // Medium green
  25: Color(0xFF239A3B),   // Dark green
  40: Color(0xFF196127),   // Very dark green
};
```

--------------------------------

### Minimal HeatMap Example

Source: https://github.com/devappmin/flutter_heatmap_calendar/blob/main/_autodocs/quick-reference.md

Demonstrates the simplest way to create a HeatMap widget. It requires defining colorsets and datasets.

```dart
HeatMap(
  colorsets: {1: Colors.blue},
  datasets: {DateTime(2021, 1, 6): 5},
)
```

--------------------------------

### Minimal HeatMapCalendar Example

Source: https://github.com/devappmin/flutter_heatmap_calendar/blob/main/_autodocs/quick-reference.md

Shows the most basic implementation of the HeatMapCalendar widget. It requires specifying colorsets and datasets.

```dart
HeatMapCalendar(
  colorsets: {1: Colors.green},
  datasets: {DateTime(2021, 1, 6): 5},
)
```

--------------------------------

### Minimal HeatMapCalendar Configuration

Source: https://github.com/devappmin/flutter_heatmap_calendar/blob/main/_autodocs/README.md

Shows the simplest setup for a HeatMapCalendar widget, which also requires a colorset.

```dart
import 'package:flutter_heatmap_calendar/flutter_heatmap_calendar.dart';

// Minimal HeatMapCalendar
HeatMapCalendar(colorsets: {1: Colors.green})
```

--------------------------------

### Colorsets Example (Opacity Mode)

Source: https://github.com/devappmin/flutter_heatmap_calendar/blob/main/_autodocs/api-overview.md

Example of a colorsets Map for ColorMode.opacity. Only the first entry's color is used, with opacity varying based on data values.

```dart
const colorsets = {
  1: Colors.blue,  // Only this used; opacity varies
};
```

--------------------------------

### Basic HeatMap Widget Configuration

Source: https://github.com/devappmin/flutter_heatmap_calendar/blob/main/README.md

Demonstrates the basic setup of the HeatMap widget with datasets, color modes, and click handling. Use this for a simple heatmap display.

```dart
import 'package:flutter_heatmap_calendar/flutter_heatmap_calendar.dart';
...
HeatMap(
  datasets: {
    DateTime(2021, 1, 6): 3,
    DateTime(2021, 1, 7): 7,
    DateTime(2021, 1, 8): 10,
    DateTime(2021, 1, 9): 13,
    DateTime(2021, 1, 13): 6,
  },
  colorMode: ColorMode.opacity,
  showText: false,
  scrollable: true,
  colorsets: {
    1: Colors.red,
    3: Colors.orange,
    5: Colors.yellow,
    7: Colors.green,
    9: Colors.blue,
    11: Colors.indigo,
    13: Colors.purple,
  },
  onClick: (value) {
    ScaffoldMessenger.of(context).showSnackBar(SnackBar(content: Text(value.toString())));
  },
);
```

--------------------------------

### Example Usage of onClick Callback

Source: https://github.com/devappmin/flutter_heatmap_calendar/blob/main/_autodocs/types.md

Demonstrates how to implement the onClick callback in a HeatMap widget to display a dialog with data for the clicked date.

```dart
HeatMap(
  onClick: (DateTime clickedDate) {
    print('User clicked: $clickedDate');
    showDialog(
      context: context,
      builder: (context) => AlertDialog(
        title: Text('Data for ${clickedDate.toLocal()}'),
        content: Text('Value: ${datasets[clickedDate]}'),
      ),
    );
  },
)
```

--------------------------------

### Colorsets Example (Color Mode)

Source: https://github.com/devappmin/flutter_heatmap_calendar/blob/main/_autodocs/api-overview.md

Example of a colorsets Map for ColorMode.color. Multiple entries define color thresholds, mapping data values to specific colors.

```dart
const colorsets = {
  1: Colors.red,
  5: Colors.yellow,
  10: Colors.green,
};
```

--------------------------------

### Basic HeatMap with Data

Source: https://github.com/devappmin/flutter_heatmap_calendar/blob/main/_autodocs/README.md

A standard example of a HeatMap widget populated with sample data and configured for opacity-based color mode.

```dart
HeatMap(
  datasets: {
    DateTime(2021, 1, 1): 5,
    DateTime(2021, 1, 2): 10,
    DateTime(2021, 1, 3): 3,
  },
  colorsets: {1: Colors.blue},
  colorMode: ColorMode.opacity,
)
```

--------------------------------

### Get Start of Month

Source: https://github.com/devappmin/flutter_heatmap_calendar/blob/main/_autodocs/utility-functions.md

Calculates the first day of the month for a given date, setting the time to midnight. Used internally for data filtering.

```dart
static DateTime startDayOfMonth(final DateTime referenceDate)
{
  // Returns: DateTime(2021, 6, 1, 0, 0, 0)
}
```

--------------------------------

### Datasets Structure Example

Source: https://github.com/devappmin/flutter_heatmap_calendar/blob/main/_autodocs/api-overview.md

Illustrates the structure of the datasets Map, used to provide data values for coloring heatmap blocks. Dates should be normalized to midnight.

```dart
final datasets = {
  DateTime(2021, 1, 1): 5,
  DateTime(2021, 1, 2): 10,
  DateTime(2021, 1, 3): 3,
  DateTime(2021, 1, 4): 7,
};
```

--------------------------------

### Example Usage of onMonthChange Callback

Source: https://github.com/devappmin/flutter_heatmap_calendar/blob/main/_autodocs/types.md

Shows how to use the onMonthChange callback in a HeatMapCalendar to log the new month and trigger data loading for that month.

```dart
HeatMapCalendar(
  onMonthChange: (DateTime newMonth) {
    print('Month changed to: ${newMonth.year}-${newMonth.month}');
    // Load data for new month
    loadMonthData(newMonth.year, newMonth.month);
  },
)
```

--------------------------------

### Proper DateTime Usage Example

Source: https://github.com/devappmin/flutter_heatmap_calendar/blob/main/_autodocs/types.md

Demonstrates the correct way to create DateTime objects for use with the heatmap calendar, emphasizing the exclusion of time components. It also shows how to structure dataset entries.

```dart
DateTime properDate = DateTime(2021, 1, 6);  // Midnight
DateTime improperDate = DateTime(2021, 1, 6, 12, 0);  // Noon

final Map<DateTime, int> datasets = {
  properDate: 5,  // Will work
  // improperDate: 10,  // May not match lookups for properDate
};
```

--------------------------------

### Margin Parameter Examples

Source: https://github.com/devappmin/flutter_heatmap_calendar/blob/main/_autodocs/types.md

Demonstrates common usages of the margin parameter, an EdgeInsets object, for controlling the spacing around heatmap blocks.

```dart
HeatMap(
  margin: EdgeInsets.all(2),           // All sides 2px
  margin: EdgeInsets.symmetric(h: 1, v: 2),  // Horizontal 1px, vertical 2px
)
```

--------------------------------

### Basic HeatMapCalendar Widget Configuration

Source: https://github.com/devappmin/flutter_heatmap_calendar/blob/main/README.md

Shows the basic setup for the HeatMapCalendar widget, including default color, flexibility, color mode, datasets, and click events. Suitable for calendar-integrated heatmaps.

```dart
import 'package:flutter_heatmap_calendar/flutter_heatmap_calendar.dart';
...
HeatMapCalendar(
  defaultColor: Colors.white,
  flexible: true,
  colorMode: ColorMode.color,
  datasets: {
    DateTime(2021, 1, 6): 3,
    DateTime(2021, 1, 7): 7,
    DateTime(2021, 1, 8): 10,
    DateTime(2021, 1, 9): 13,
    DateTime(2021, 1, 13): 6,
  },
  colorsets: const {
    1: Colors.red,
    3: Colors.orange,
    5: Colors.yellow,
    7: Colors.green,
    9: Colors.blue,
    11: Colors.indigo,
    13: Colors.purple,
  },
  onClick: (value) {
    ScaffoldMessenger.of(context).showSnackBar(SnackBar(content: Text(value.toString())));
  },
);
```

--------------------------------

### HeatMap ColorMode Configuration (Opacity)

Source: https://github.com/devappmin/flutter_heatmap_calendar/blob/main/_autodocs/configuration-reference.md

Example of using `ColorMode.opacity` with a single color. The opacity varies proportionally to the data value.

```dart
// Use single blue color with varying opacity
HeatMap(
  colorsets: {1: Colors.blue},
  colorMode: ColorMode.opacity,
)
```

--------------------------------

### HeatMap Date Range Configuration (Start and End Dates)

Source: https://github.com/devappmin/flutter_heatmap_calendar/blob/main/_autodocs/configuration-reference.md

Sets the `startDate` and `endDate` for the heatmap. The widget adjusts to display full weeks, starting from the Sunday of the week containing `startDate` and potentially extending to the Saturday of the week containing `endDate`.

```dart
HeatMap(
  startDate: DateTime(2020, 1, 1),
  endDate: DateTime(2021, 1, 1),
  // Shows 52 weeks from Jan 2020 to Jan 2021
)
```

```dart
HeatMap(
  startDate: DateTime(2021, 9, 1),
  // Automatically displays from Sunday of week containing Sep 1
)
```

```dart
HeatMap(
  endDate: DateTime(2021, 6, 30),
  // Show data up to June 30
)
```

```dart
HeatMap(
  // No endDate specified, uses today
)
```

--------------------------------

### HeatMapCalendar with Month Tracking and Callbacks

Source: https://github.com/devappmin/flutter_heatmap_calendar/blob/main/_autodocs/README.md

An example of a HeatMapCalendar with custom color thresholds, flexible layout, and event handlers for month changes and date clicks.

```dart
HeatMapCalendar(
  datasets: monthlyData,
  colorsets: {0: Colors.grey, 5: Colors.blue, 10: Colors.green},
  colorMode: ColorMode.color,
  flexible: true,
  onMonthChange: (newMonth) {
    loadDataForMonth(newMonth.year, newMonth.month);
  },
  onClick: (date) {
    showDateDetails(date);
  },
)
```

--------------------------------

### Color Tip Helper Parameter Example

Source: https://github.com/devappmin/flutter_heatmap_calendar/blob/main/_autodocs/types.md

Shows how to customize the color legend labels using the colorTipHelper parameter, a List<Widget?>. It accepts two widgets for the left and right sides of the legend.

```dart
HeatMap(
  colorTipHelper: [
    Row(
      children: [Icon(Icons.trending_down), Text('Low')],
    ),
    Row(
      children: [Icon(Icons.trending_up), Text('High')],
    ),
  ],
)
```

--------------------------------

### Basic Heatmap with Opacity Mode

Source: https://github.com/devappmin/flutter_heatmap_calendar/blob/main/_autodocs/heatmap.md

A basic heatmap example using opacity mode to represent data intensity. It includes sample datasets and a click handler to display the selected date's value.

```dart
import 'package:flutter/material.dart';
import 'package:flutter_heatmap_calendar/flutter_heatmap_calendar.dart';

class HeatMapExample extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return HeatMap(
      datasets: {
        DateTime(2021, 1, 6): 3,
        DateTime(2021, 1, 7): 7,
        DateTime(2021, 1, 8): 10,
        DateTime(2021, 1, 9): 13,
        DateTime(2021, 1, 13): 6,
      },
      colorMode: ColorMode.opacity,
      showText: false,
      scrollable: true,
      colorsets: {
        1: Colors.red,
        3: Colors.orange,
        5: Colors.yellow,
        7: Colors.green,
        9: Colors.blue,
        11: Colors.indigo,
        13: Colors.purple,
      },
      onClick: (value) {
        ScaffoldMessenger.of(context).showSnackBar(
          SnackBar(content: Text(value.toString())),
        );
      },
    );
  }
}
```

--------------------------------

### Datasets Parameter Example

Source: https://github.com/devappmin/flutter_heatmap_calendar/blob/main/_autodocs/types.md

Illustrates the structure of the datasets parameter, a Map<DateTime, int>, used to provide data values for the heatmap. Keys must be DateTime objects normalized to midnight.

```dart
final Map<DateTime, int> datasets = {
  DateTime(2021, 1, 1): 5,
  DateTime(2021, 1, 2): 10,
  DateTime(2021, 1, 3): 3,
};
```

--------------------------------

### HeatMap ColorMode Configuration (Color)

Source: https://github.com/devappmin/flutter_heatmap_calendar/blob/main/_autodocs/configuration-reference.md

Example of using `ColorMode.color` with multiple colors. Data values are mapped to discrete color ranges defined by the thresholds in `colorsets`.

```dart
// Use discrete colors for value ranges
HeatMap(
  colorsets: {0: red, 10: yellow, 20: green},
  colorMode: ColorMode.color,
)
```

--------------------------------

### Flutter Web Service Worker Setup

Source: https://github.com/devappmin/flutter_heatmap_calendar/blob/main/example/web/index.html

This JavaScript code handles the registration and management of a service worker for a Flutter web application. It includes logic for updating the service worker, waiting for activation, and falling back to a plain script tag if the service worker fails to load.

```javascript
var serviceWorkerVersion = null;
var scriptLoaded = false;

function loadMainDartJs() {
  if (scriptLoaded) {
    return;
  }
  scriptLoaded = true;
  var scriptTag = document.createElement('script');
  scriptTag.src = 'main.dart.js';
  scriptTag.type = 'application/javascript';
  document.body.append(scriptTag);
}

if ('serviceWorker' in navigator) {
  // Service workers are supported. Use them.
  window.addEventListener('load', function () {
    // Wait for registration to finish before dropping the <script> tag.
    // Otherwise, the browser will load the script multiple times,
    // potentially different versions.
    var serviceWorkerUrl = 'flutter\_service\_worker.js?v=' + serviceWorkerVersion;
    navigator.serviceWorker.register(serviceWorkerUrl)
      .then((reg) => {
        function waitForActivation(serviceWorker) {
          serviceWorker.addEventListener('statechange', () => {
            if (serviceWorker.state == 'activated') {
              console.log('Installed new service worker.');
              loadMainDartJs();
            }
          });
        }

        if (!reg.active && (reg.installing || reg.waiting)) {
          // No active web worker and we have installed or are installing
          // one for the first time. Simply wait for it to activate.
          waitForActivation(reg.installing || reg.waiting);
        } else if (!reg.active.scriptURL.endsWith(serviceWorkerVersion)) {
          // When the app updates the serviceWorkerVersion changes, so we
          // need to ask the service worker to update.
          console.log('New service worker available.');
          reg.update();
          waitForActivation(reg.installing);
        } else {
          // Existing service worker is still good.
          console.log('Loading app from service worker.');
          loadMainDartJs();
        }
      });

    // If service worker doesn't succeed in a reasonable amount of time,
    // fallback to plaint <script> tag.
    setTimeout(() => {
      if (!scriptLoaded) {
        console.warn(
          'Failed to load app from service worker. Falling back to plain <script> tag.',
        );
        loadMainDartJs();
      }
    }, 4000);
  });
} else {
  // Service workers not supported. Just drop the <script> tag.
  loadMainDartJs();
}
```

--------------------------------

### HeatMap Usage with ColorMode.opacity

Source: https://github.com/devappmin/flutter_heatmap_calendar/blob/main/_autodocs/types.md

Example of using HeatMap with ColorMode.opacity. The opacity of the first color in colorsets is adjusted based on the data value.

```dart
HeatMap(
  colorsets: {1: Colors.blue, 5: Colors.green, 10: Colors.red},
  colorMode: ColorMode.opacity,
  // ... other properties
)
```

--------------------------------

### Heatmap with Custom Date Range and Color Mode

Source: https://github.com/devappmin/flutter_heatmap_calendar/blob/main/_autodocs/heatmap.md

Configures a heatmap with a specific start and end date, custom color sets, and displays text values. Ensure 'myDatasets' is defined elsewhere.

```dart
HeatMap(
  startDate: DateTime(2020, 6, 1),
  endDate: DateTime(2021, 6, 1),
  datasets: myDatasets,
  colorsets: const {
    0: Color(0xFFEBEDF0),
    5: Color(0xFFC6E48B),
    10: Color(0xFF7BC96F),
    25: Color(0xFF239A3B),
    40: Color(0xFF196127),
  },
  colorMode: ColorMode.color,
  size: 16,
  margin: EdgeInsets.all(1),
  borderRadius: 3,
  defaultColor: Colors.white,
  textColor: Colors.black87,
  showText: true,
  showColorTip: true,
  onClick: (date) => print('Clicked: $date'),
)
```

--------------------------------

### Minimal HeatMap Configuration

Source: https://github.com/devappmin/flutter_heatmap_calendar/blob/main/_autodocs/README.md

Demonstrates the most basic configuration for a HeatMap widget, requiring only a colorset.

```dart
import 'package:flutter_heatmap_calendar/flutter_heatmap_calendar.dart';

// Minimal HeatMap
HeatMap(colorsets: {1: Colors.blue})
```

--------------------------------

### Separate Month into Weeks

Source: https://github.com/devappmin/flutter_heatmap_calendar/blob/main/_autodocs/utility-functions.md

Divides a given month into weeks, returning a list of maps where each map contains the week's start and end dates. Weeks start on Sunday and end on Saturday, and may include days from adjacent months.

```dart
static List<Map<DateTime, DateTime>> separatedMonth(final DateTime referenceDate)
{
  // Returns something like:
  // [
  //   {DateTime(2021, 5, 30): DateTime(2021, 6, 5)},
  //   {DateTime(2021, 6, 6): DateTime(2021, 6, 12)},
  //   {DateTime(2021, 6, 13): DateTime(2021, 6, 19)},
  //   ...
  // ]
}
```

--------------------------------

### Minimal HeatMap and HeatMapCalendar Configuration

Source: https://github.com/devappmin/flutter_heatmap_calendar/blob/main/_autodocs/api-overview.md

Demonstrates the most basic configuration for both HeatMap and HeatMapCalendar widgets, requiring only the 'colorsets' parameter.

```dart
HeatMap(colorsets: {1: Colors.blue})
HeatMapCalendar(colorsets: {1: Colors.green})
```

--------------------------------

### HeatMapCalendar Usage with ColorMode.color

Source: https://github.com/devappmin/flutter_heatmap_calendar/blob/main/_autodocs/types.md

Example of using HeatMapCalendar with ColorMode.color. Colors are selected from colorsets based on data value thresholds.

```dart
HeatMapCalendar(
  colorsets: {
    1: Colors.grey,
    5: Colors.blue,
    10: Colors.green,
  },
  colorMode: ColorMode.color,
  // ... other properties
)
```

--------------------------------

### DateUtil.startDayOfMonth

Source: https://github.com/devappmin/flutter_heatmap_calendar/blob/main/_autodocs/utility-functions.md

Calculates the first day of the month for a given reference date, setting the time to midnight.

```APIDOC
## DateUtil.startDayOfMonth

### Description
Calculates the first day of the month for a given reference date, setting the time to midnight.

### Method
static DateTime startDayOfMonth(final DateTime referenceDate)

### Parameters
#### Path Parameters
- **referenceDate** (DateTime) - Required - Any date in the target month

### Response
#### Success Response
- **DateTime** - The first day of the month at midnight.

### Request Example
```dart
DateTime start = DateUtil.startDayOfMonth(DateTime(2021, 6, 15));
// Returns: DateTime(2021, 6, 1, 0, 0, 0)
```
```

--------------------------------

### Full HeatMap Configuration

Source: https://github.com/devappmin/flutter_heatmap_calendar/blob/main/_autodocs/api-overview.md

Illustrates a comprehensive configuration for the HeatMap widget, including data, date range, styling, and interactivity options.

```dart
HeatMap(
  colorsets: {...},
  colorMode: ColorMode.color,
  startDate: DateTime(2020, 1, 1),
  endDate: DateTime.now(),
  datasets: data,
  defaultColor: Colors.white,
  textColor: Colors.black,
  size: 18,
  fontSize: 10,
  margin: EdgeInsets.all(1),
  borderRadius: 3,
  scrollable: true,
  showText: true,
  showColorTip: true,
  colorTipSize: 12,
  colorTipCount: 5,
  onClick: (date) => print(date),
)
```

--------------------------------

### HeatMap Constructor

Source: https://github.com/devappmin/flutter_heatmap_calendar/blob/main/_autodocs/api-overview.md

Initializes a HeatMap widget. It requires a map of colorsets and accepts various optional parameters to customize its appearance and behavior, such as date range, text color, size, click handling, and data display.

```APIDOC
## HeatMap Constructor

### Description
Initializes a HeatMap widget. It requires a map of colorsets and accepts various optional parameters to customize its appearance and behavior, such as date range, text color, size, click handling, and data display.

### Parameters
#### Required Parameters
- `colorsets` (Map<int, Color>) - Required - At least one color required

#### Optional Parameters with Defaults
- `colorMode` (ColorMode) - Optional - Default: `ColorMode.opacity`
- `size` (double) - Optional - Default: `20`
- `showText` (bool) - Optional - Default: `false`
- `showColorTip` (bool) - Optional - Default: `true`
- `scrollable` (bool) - Optional - Default: `false`

#### Optional Parameters (nullable)
- `key` (Key?)
- `startDate` (DateTime?)
- `endDate` (DateTime?)
- `textColor` (Color?)
- `fontSize` (double?)
- `onClick` (Function(DateTime)?)
- `margin` (EdgeInsets?)
- `borderRadius` (double?)
- `datasets` (Map<DateTime, int>?)
- `defaultColor` (Color?)
- `colorTipHelper` (List<Widget?>?)
- `colorTipCount` (int?)
- `colorTipSize` (double?)
```

--------------------------------

### HeatMapCalendar Constructor

Source: https://github.com/devappmin/flutter_heatmap_calendar/blob/main/_autodocs/heatmap_calendar.md

Initializes a new instance of the HeatMapCalendar widget. This widget displays a month-based heatmap calendar with navigation controls and customizable appearance.

```APIDOC
## HeatMapCalendar

### Description
A stateful widget that renders a calendar grid with month/year header, week navigation buttons, and optional color legend. It displays one month at a time with previous/next month buttons for navigation.

### Constructor
```dart
const HeatMapCalendar({
  Key? key,
  required Map<int, Color> colorsets,
  ColorMode colorMode = ColorMode.opacity,
  Color? defaultColor,
  Map<DateTime, int>? datasets,
  DateTime? initDate,
  double? size = 42,
  double? fontSize,
  double? monthFontSize,
  Color? textColor,
  double? weekFontSize,
  Color? weekTextColor,
  double? borderRadius,
  bool? flexible = false,
  EdgeInsets? margin,
  Function(DateTime)? onClick,
  Function(DateTime)? onMonthChange,
  bool? showColorTip = true,
  List<Widget?>? colorTipHelper,
  int? colorTipCount,
  double? colorTipSize,
})
```

### Parameters
#### Required Parameters
- **colorsets** (Map<int, Color>) - Required - Color mapping by threshold. At least one required. First color used if `ColorMode.opacity`.

#### Optional Parameters
- **colorMode** (ColorMode) - Optional - Defaults to `ColorMode.opacity`. How colors are applied: `opacity` or `color`.
- **defaultColor** (Color?) - Optional - Defaults to `Color(0xFFF8F9FA)`. Background color for blocks without data.
- **datasets** (Map<DateTime, int>?) - Optional - Defaults to `null`. Data values mapped by date. Normalized to midnight.
- **initDate** (DateTime?) - Optional - Defaults to `DateTime.now()`. Initial month/year to display. Uses month and year only; day is ignored.
- **size** (double?) - Optional - Defaults to `42`. Width and height of each day block in pixels. Ignored if `flexible: true`.
- **fontSize** (double?) - Optional - Defaults to `null`. Font size for day numbers in blocks.
- **monthFontSize** (double?) - Optional - Defaults to `12`. Font size for month/year header text.
- **textColor** (Color?) - Optional - Defaults to `Color(0xFF8A8A8A)`. Color for day numbers in blocks.
- **weekFontSize** (double?) - Optional - Defaults to `12`. Font size for week day labels (Sun, Mon, etc.).
- **weekTextColor** (Color?) - Optional - Defaults to `Color(0xFF758EA1)`. Color for week day labels on left side.
- **borderRadius** (double?) - Optional - Defaults to `5`. Corner radius for block containers.
- **flexible** (bool?) - Optional - Defaults to `false`. When true, expands blocks to fill available width. `size` property ignored.
- **margin** (EdgeInsets?) - Optional - Defaults to `EdgeInsets.all(2)`. Spacing around each block.
- **onClick** (Function(DateTime)?) - Optional - Defaults to `null`. Callback when a day block is clicked. Receives the clicked date.
- **onMonthChange** (Function(DateTime)?) - Optional - Defaults to `null`. Callback when month changes (prev/next clicked). Receives first day of new month.
- **showColorTip** (bool?) - Optional - Defaults to `true`. Whether to display color legend below calendar.
- **colorTipHelper** (List<Widget?>?) - Optional - Defaults to `null`. Custom widgets for legend labels. Index 0 is left (default: "less"), index 1 is right (default: "more").
- **colorTipCount** (int?) - Optional - Defaults to `7`. Number of color blocks shown in legend.
- **colorTipSize** (double?) - Optional - Defaults to `10`. Width and height of color blocks in legend.
```

--------------------------------

### Get Maximum Value from Datasets

Source: https://github.com/devappmin/flutter_heatmap_calendar/blob/main/_autodocs/utility-functions.md

Finds the maximum integer value within a dataset map. Returns 0 if the dataset is null or empty. Essential for data normalization, such as in opacity calculations.

```dart
static int getMaxValue(Map<DateTime, int>? datasets)
```

```dart
final data = {
  DateTime(2021, 6, 1): 3,
  DateTime(2021, 6, 2): 7,
  DateTime(2021, 6, 3): 5,
};

int max = DatasetsUtil.getMaxValue(data);
// Returns: 7
```

--------------------------------

### Recommended HeatMapCalendar Configuration

Source: https://github.com/devappmin/flutter_heatmap_calendar/blob/main/_autodocs/configuration-reference.md

A balanced configuration for HeatMapCalendar, emphasizing responsiveness and user interaction. Includes color bands and month change handling.

```dart
HeatMapCalendar(
  colorsets: {0: Colors.grey, 5: Colors.blue, 10: Colors.green},
  colorMode: ColorMode.color,
  datasets: myData,
  flexible: true,
  margin: EdgeInsets.all(2),
  borderRadius: 5,
  showColorTip: true,
  onMonthChange: (month) => loadData(month),
  onClick: (date) => print('Clicked: $date'),
)
```

--------------------------------

### Recommended HeatMap Configuration

Source: https://github.com/devappmin/flutter_heatmap_calendar/blob/main/_autodocs/configuration-reference.md

A balanced configuration for HeatMap, suitable for most use cases. Includes color bands, data display, and scrollability.

```dart
HeatMap(
  colorsets: {0: Colors.grey, 5: Colors.blue, 10: Colors.green},
  colorMode: ColorMode.color,
  datasets: myData,
  size: 18,
  margin: EdgeInsets.all(1),
  borderRadius: 4,
  showText: false,
  showColorTip: true,
  scrollable: true,
  onClick: (date) => print('Clicked: $date'),
)
```

--------------------------------

### Get End of Month

Source: https://github.com/devappmin/flutter_heatmap_calendar/blob/main/_autodocs/utility-functions.md

Calculates the last day of the month for a given date, setting the time to midnight. It leverages a quirk where DateTime(year, month + 1, 0) resolves to the last day of the previous month.

```dart
static DateTime endDayOfMonth(final DateTime referenceDate)
{
  // Returns: DateTime(2021, 7, 0, 0, 0, 0) which is June 30, 2021
}
```

--------------------------------

### HeatMap Datasets Common Patterns

Source: https://github.com/devappmin/flutter_heatmap_calendar/blob/main/_autodocs/configuration-reference.md

Illustrates common patterns for providing data to the `datasets` parameter, including fetching data dynamically from an API, filtering data for a specific period, and performing monthly aggregation.

```dart
// Dynamic dataset from API
final data = await fetchData();
HeatMap(datasets: data)
```

```dart
// Filtered data for specific period
final filtered = data.entries
  .where((e) => e.key.isAfter(startDate) && e.key.isBefore(endDate))
  .toMap();
HeatMap(datasets: filtered)
```

```dart
// Monthly aggregation
final monthly = <DateTime, int>{};
for (var entry in daily) {
  final monthKey = DateTime(entry.key.year, entry.key.month);
  monthly[monthKey] = (monthly[monthKey] ?? 0) + entry.value;
}
HeatMap(datasets: monthly)
```

--------------------------------

### Get Color from Thresholds

Source: https://github.com/devappmin/flutter_heatmap_calendar/blob/main/_autodocs/utility-functions.md

Retrieves a color from a color set based on a data value. It finds the largest threshold key that is less than or equal to the data value. Returns null if no suitable threshold is found or if inputs are null.

```dart
static Color? getColor(Map<int, Color>? colorsets, int? dataValue)
```

```dart
const colorsets = {
  1: Colors.red,
  5: Colors.yellow,
  10: Colors.green,
};

Color? color3 = DatasetsUtil.getColor(colorsets, 3);
// Returns: Colors.red (threshold 1 is the highest ≤ 3)

Color? color7 = DatasetsUtil.getColor(colorsets, 7);
// Returns: Colors.yellow (threshold 5 is the highest ≤ 7)

Color? color0 = DatasetsUtil.getColor(colorsets, 0);
// Returns: null (no threshold ≤ 0)

Color? colorNull = DatasetsUtil.getColor(colorsets, null);
// Returns: null
```

--------------------------------

### Calculating Days Since Sunday and Moving to Sunday

Source: https://github.com/devappmin/flutter_heatmap_calendar/blob/main/_autodocs/internal-architecture.md

Illustrates how to calculate the number of days since Sunday for a given date and how to adjust the date to the Sunday of the same week. This is useful for aligning week-based calculations.

```dart
DateTime date = DateTime(2021, 1, 6);  // Wednesday
int weekday = date.weekday;             // Returns 4

// Calculate days since Sunday:
int daysSinceSunday = weekday % 7;      // 4 % 7 = 4

// Move to Sunday of same week:
DateTime sunday = DateUtil.changeDay(date, -daysSinceSunday);
```

--------------------------------

### Date Normalization to Midnight

Source: https://github.com/devappmin/flutter_heatmap_calendar/blob/main/_autodocs/internal-architecture.md

Demonstrates how the library normalizes all dates to midnight (00:00:00) for consistent comparisons and storage within datasets. Input dates with time components are effectively truncated.

```dart
// Input
DateTime input = DateTime(2021, 1, 6, 14, 30, 45);

// Normalized
DateTime normalized = DateTime(2021, 1, 6);  // Time dropped

// In datasets, dates are auto-normalized:
datasets[DateTime(2021, 1, 6, 14, 30)] // May not match
datasets[DateTime(2021, 1, 6)]          // Will match
```

--------------------------------

### HeatMapCalendar Initial Date

Source: https://github.com/devappmin/flutter_heatmap_calendar/blob/main/_autodocs/configuration-reference.md

Specifies the initial month and year to display. Defaults to the current month. Only the year and month are used.

```dart
HeatMapCalendar(
  initDate: DateTime(2021, 6, 15),  // Displays June 2021 (day ignored)
)
```

```dart
HeatMapCalendar(
  // Displays current month (no initDate specified)
)
```

--------------------------------

### Implement Click Callback for Heatmap Blocks

Source: https://github.com/devappmin/flutter_heatmap_calendar/blob/main/_autodocs/configuration-reference.md

Provide an `onClick` callback function to handle user taps on heatmap blocks. The function receives the `DateTime` of the clicked block. Defaults to null (no interaction).

```dart
HeatMap(
  onClick: (date) {
    print('Clicked: $date');
  },
)
```

```dart
HeatMap(
  onClick: (date) {
    showDialog(
      context: context,
      builder: (_) => DateDetailsDialog(date),
    );
  },
)
```

```dart
HeatMap(
  onClick: (date) {
    setState(() {
      selectedDate = date;
    });
  },
)
```

--------------------------------

### HeatMap Datasets Configuration

Source: https://github.com/devappmin/flutter_heatmap_calendar/blob/main/_autodocs/configuration-reference.md

Provides data values for each date using the `datasets` parameter. Keys are `DateTime` objects (normalized to midnight) and values are integers representing the data count.

```dart
final data = {
  DateTime(2021, 1, 1): 5,
  DateTime(2021, 1, 2): 10,
  DateTime(2021, 1, 3): 3,
};

HeatMap(
  datasets: data,
  colorsets: {1: Colors.blue},
)
```

--------------------------------

### Basic Month Calendar

Source: https://github.com/devappmin/flutter_heatmap_calendar/blob/main/_autodocs/heatmap_calendar.md

A simple heatmap calendar displaying data for a specific month. It uses default colors and a basic click handler.

```dart
import 'package:flutter/material.dart';
import 'package:flutter_heatmap_calendar/flutter_heatmap_calendar.dart';

class CalendarExample extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return HeatMapCalendar(
      defaultColor: Colors.white,
      flexible: true,
      colorMode: ColorMode.color,
      datasets: {
        DateTime(2021, 1, 6): 3,
        DateTime(2021, 1, 7): 7,
        DateTime(2021, 1, 8): 10,
        DateTime(2021, 1, 9): 13,
        DateTime(2021, 1, 13): 6,
      },
      colorsets: const {
        1: Colors.red,
        3: Colors.orange,
        5: Colors.yellow,
        7: Colors.green,
        9: Colors.blue,
        11: Colors.indigo,
        13: Colors.purple,
      },
      onClick: (value) {
        ScaffoldMessenger.of(context).showSnackBar(
          SnackBar(content: Text(value.toString())),
        );
      },
    );
  }
}
```

--------------------------------

### HeatMapCalendar Constructor

Source: https://github.com/devappmin/flutter_heatmap_calendar/blob/main/_autodocs/heatmap_calendar.md

This is the constructor for the HeatMapCalendar widget. It takes various parameters to customize the appearance and behavior of the calendar, including colorsets, datasets, initial date, sizes, fonts, colors, and callbacks.

```dart
const HeatMapCalendar({
  Key? key,
  required Map<int, Color> colorsets,
  ColorMode colorMode = ColorMode.opacity,
  Color? defaultColor,
  Map<DateTime, int>? datasets,
  DateTime? initDate,
  double? size = 42,
  double? fontSize,
  double? monthFontSize,
  Color? textColor,
  double? weekFontSize,
  Color? weekTextColor,
  double? borderRadius,
  bool? flexible = false,
  EdgeInsets? margin,
  Function(DateTime)? onClick,
  Function(DateTime)? onMonthChange,
  bool? showColorTip = true,
  List<Widget?>? colorTipHelper,
  int? colorTipCount,
  double? colorTipSize,
})
```

--------------------------------

### HeatMapCalendar Flexible Sizing

Source: https://github.com/devappmin/flutter_heatmap_calendar/blob/main/_autodocs/configuration-reference.md

Enables blocks to expand and fill available width while maintaining a 1:1 aspect ratio. The 'size' parameter is ignored when true. This is beneficial for responsive layouts.

```dart
bool? flexible = false
```

```dart
HeatMapCalendar(
  flexible: true,
  // Blocks expand to fill screen width
)
```

```dart
HeatMapCalendar(
  flexible: false,
  size: 50,
  // Fixed 50x50 blocks
)
```

--------------------------------

### HeatMap Data Flow

Source: https://github.com/devappmin/flutter_heatmap_calendar/blob/main/_autodocs/internal-architecture.md

Describes the sequence of operations from user instantiation to rendering of individual day blocks and the color tip in the HeatMap widget.

```plaintext
1. User instantiates `HeatMap` with parameters
2. `_HeatMap` state builds the widget tree
3. If `scrollable: true`, wraps in `SingleChildScrollView` with horizontal scrolling
4. `HeatMapPage` calculates date range and creates columns
5. `HeatMapColumn` creates individual day containers
6. `HeatMapContainer` renders a single day block with optional text and color
7. `HeatMapColorTip` renders color legend if enabled
```

--------------------------------

### HeatMapCalendar Widget Hierarchy

Source: https://github.com/devappmin/flutter_heatmap_calendar/blob/main/_autodocs/internal-architecture.md

Illustrates the composition of the HeatMapCalendar widget, showing its header, week labels, calendar pages, and optional color tip.

```plaintext
HeatMapCalendar (StatefulWidget)
└── _HeatMapCalendar (State)
    └── IntrinsicWidth (conditional, if flexible: false)
        └── Column
            ├── Row (Header)
            │   ├── IconButton (Previous month)
            │   ├── Text (Month/Year)
            │   └── IconButton (Next month)
            ├── Row (Week labels)
            │   └── HeatMapWeekText
            ├── HeatMapCalendarPage
            │   └── Column
            │       └── HeatMapCalendarRow × N
            │           └── Row
            │               └── HeatMapContainer (via flexibleContainer) × 7
            └── HeatMapColorTip (conditional, if showColorTip: true)
```

--------------------------------

### HeatMapColumn Widget

Source: https://github.com/devappmin/flutter_heatmap_calendar/blob/main/_autodocs/internal-architecture.md

Renders a single vertical column representing one week in the heatmap. It contains 7 day containers and fills any remaining space with empty containers if the week is partial.

```dart
class HeatMapColumn extends StatelessWidget {
  final DateTime startDate;
  final DateTime endDate;
  final int numDays;  // Usually 7, can be less for partial weeks
  final List<Widget> dayContainers;
  final List<Widget> emptySpace;
  
  HeatMapColumn({...}) :
    dayContainers = List.generate(numDays, (i) => HeatMapContainer(...)),
    emptySpace = numDays != 7 ? List.generate(7 - numDays, ...) : [];
  
  Widget build(BuildContext context) {
    return Column(
      children: [...dayContainers, ...emptySpace],
    );
  }
}
```

--------------------------------

### Import Heatmap Calendar

Source: https://github.com/devappmin/flutter_heatmap_calendar/blob/main/README.md

Import the necessary package to use the Heatmap widgets in your Dart code.

```dart
import 'package:flutter_heatmap_calendar/flutter_heatmap_calendar.dart';
```

--------------------------------

### Show Details Dialog on Heatmap Click

Source: https://github.com/devappmin/flutter_heatmap_calendar/blob/main/_autodocs/quick-reference.md

Display a dialog with date and value details when a heatmap cell is clicked. This enhances user experience by providing immediate feedback.

```dart
HeatMap(
  onClick: (date) {
    showDialog(
      context: context,
      builder: (ctx) => AlertDialog(
        title: Text(date.toString()),
        content: Text('Value: ${datasets[date] ?? 0}'),
      ),
    );
  },
)
```

--------------------------------

### HeatMap Widget Constructor

Source: https://github.com/devappmin/flutter_heatmap_calendar/blob/main/_autodocs/heatmap.md

This is the constructor for the HeatMap widget. It takes various parameters to customize the appearance and behavior of the heatmap, including color sets, date ranges, data, and click handling.

```dart
const HeatMap({
  Key? key,
  required Map<int, Color> colorsets,
  ColorMode colorMode = ColorMode.opacity,
  DateTime? startDate,
  DateTime? endDate,
  Color? textColor,
  double? size = 20,
  double? fontSize,
  Function(DateTime)? onClick,
  EdgeInsets? margin,
  double? borderRadius,
  Map<DateTime, int>? datasets,
  Color? defaultColor,
  bool? showText = false,
  bool? showColorTip = true,
  bool scrollable = false,
  List<Widget?>? colorTipHelper,
  int? colorTipCount,
  double? colorTipSize,
})
```

--------------------------------

### GitHub-style Color Scheme

Source: https://github.com/devappmin/flutter_heatmap_calendar/blob/main/_autodocs/quick-reference.md

A predefined color scheme that mimics the GitHub contribution graph, using a green gradient.

```dart
const githubColors = {
  0: Color(0xFFEBEDF0),
  1: Color(0xFFC6E48B),
  3: Color(0xFF7BC96F),
  5: Color(0xFF239A3B),
  7: Color(0xFF196127),
};
```

--------------------------------

### flexibleContainer

Source: https://github.com/devappmin/flutter_heatmap_calendar/blob/main/_autodocs/utility-functions.md

Creates a flexible or square container based on provided booleans. If `isFlexible` is true, it wraps the child in an `Expanded` widget. If `isSquare` is also true, it further enforces a 1:1 aspect ratio within the `Expanded` widget.

```APIDOC
## flexibleContainer

### Description
Wraps a given widget in an `Expanded` widget to allow it to fill available space. Optionally enforces a square aspect ratio if `isSquare` is true. If `isFlexible` is false, the original widget is returned without modification.

### Method Signature
`static Widget flexibleContainer(bool isFlexible, bool isSquare, Widget child)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **isFlexible** (bool) - Required - Determines if the container should be flexible (expandable).
- **isSquare** (bool) - Required - Determines if the container should maintain a 1:1 aspect ratio. This is only applied when `isFlexible` is true.
- **child** (Widget) - Required - The widget to be wrapped or returned.

### Request Example
```dart
// Non-flexible: returns child unchanged
Widget fixed = WidgetUtil.flexibleContainer(false, false, Container(
  width: 42,
  height: 42,
));

// Flexible without aspect ratio constraint
Widget flexible = WidgetUtil.flexibleContainer(true, false, Container());

// Flexible with square aspect ratio
Widget square = WidgetUtil.flexibleContainer(true, true, Container());
```

### Response
#### Success Response
- **Widget** - Returns either an `Expanded` widget (potentially with an `AspectRatio` child) or the original `child` widget.

#### Response Example
```dart
// For isFlexible: false
Container(width: 42, height: 42)

// For isFlexible: true, isSquare: false
Expanded(child: Container())

// For isFlexible: true, isSquare: true
Expanded(child: AspectRatio(aspectRatio: 1, child: Container()))
```
```

--------------------------------

### HeatMap Widget Constructor

Source: https://github.com/devappmin/flutter_heatmap_calendar/blob/main/_autodocs/heatmap.md

The HeatMap widget is a stateful widget that renders a heatmap visualization. It accepts various properties to customize its appearance and behavior, including color sets, date ranges, data, and click interactions.

```APIDOC
## Class: HeatMap

### Constructor

```dart
const HeatMap({
  Key? key,
  required Map<int, Color> colorsets,
  ColorMode colorMode = ColorMode.opacity,
  DateTime? startDate,
  DateTime? endDate,
  Color? textColor,
  double? size = 20,
  double? fontSize,
  Function(DateTime)? onClick,
  EdgeInsets? margin,
  double? borderRadius,
  Map<DateTime, int>? datasets,
  Color? defaultColor,
  bool? showText = false,
  bool? showColorTip = true,
  bool scrollable = false,
  List<Widget?>? colorTipHelper,
  int? colorTipCount,
  double? colorTipSize,
})
```

### Properties

| Property | Type | Required | Default | Description |
|----------|------|----------|---------|-------------|
| colorsets | `Map<int, Color>` | Yes | — | Color mapping by threshold value. At least one color required. First color used if `ColorMode.opacity`. |
| colorMode | `ColorMode` | No | `ColorMode.opacity` | Determines how colors are applied to blocks. `opacity` changes transparency; `color` uses threshold-based colors. |
| startDate | `DateTime?` | No | 1 year before `endDate` | First day to display in heatmap. Shows the Sunday of the week containing this date. |
| endDate | `DateTime?` | No | `DateTime.now()` | Last day to display in heatmap. |
| datasets | `Map<DateTime, int>?` | No | `null` | Data values mapped by date. Keys must be normalized to midnight (no time component). |
| defaultColor | `Color?` | No | `Color(0xFFF8F9FA)` | Background color for blocks without data. |
| textColor | `Color?` | No | `Color(0xFF8A8A8A)` | Color for day numbers displayed in blocks. |
| size | `double?` | No | `20` | Width and height of each block in pixels. |
| fontSize | `double?` | No | `null` | Font size for day numbers in blocks. If null, uses default. |
| onClick | `Function(DateTime)?` | No | `null` | Callback when a block is clicked. Receives the clicked date. |
| margin | `EdgeInsets?` | No | `EdgeInsets.all(2)` | Spacing around each block. |
| borderRadius | `double?` | No | `5` | Corner radius for block containers. |
| showText | `bool?` | No | `false` | Whether to display day numbers in blocks. |
| showColorTip | `bool?` | No | `true` | Whether to display color legend below heatmap. |
| scrollable | `bool` | No | `false` | When true, wraps heatmap in horizontal scroll view for wide date ranges. |
| colorTipHelper | `List<Widget?>?` | No | `null` | Custom widgets for legend labels. Index 0 is left (default: "less"), index 1 is right (default: "more"). |
| colorTipCount | `int?` | No | `7` | Number of color blocks shown in legend. |
| colorTipSize | `double?` | No | `10` | Width and height of color blocks in legend. |

```

--------------------------------

### Flexible Calendar with Custom Colors and Sizing

Source: https://github.com/devappmin/flutter_heatmap_calendar/blob/main/_autodocs/heatmap_calendar.md

A flexible heatmap calendar with custom colors, sizing, margins, and font sizes for different text elements. It also includes a month change callback.

```dart
HeatMapCalendar(
  initDate: DateTime(2021, 6, 1),
  datasets: data,
  colorsets: const {
    1: Color(0xFFEBEDF0),
    5: Color(0xFFC6E48B),
    10: Color(0xFF7BC96F),
    25: Color(0xFF239A3B),
    40: Color(0xFF196127),
  },
  colorMode: ColorMode.color,
  flexible: true,
  size: 50, // Ignored when flexible: true
  margin: EdgeInsets.all(1),
  fontSize: 10,
  monthFontSize: 14,
  weekFontSize: 10,
  borderRadius: 2,
  defaultColor: Color(0xFFF0F0F0),
  textColor: Colors.black87,
  weekTextColor: Colors.grey,
  onMonthChange: (date) {
    print('Month changed to: ${date.year}-${date.month}');
  },
)
```

--------------------------------

### Add Dependency to pubspec.yaml

Source: https://github.com/devappmin/flutter_heatmap_calendar/blob/main/README.md

Add the flutter_heatmap_calendar package to your project's dependencies in pubspec.yaml.

```yaml
dependencies:
  flutter_heatmap_calendar: ^1.0.5
```