Ivy.Widgets.ActivityHeatmap 1.3.21

Ivy.Widgets.ActivityHeatmap

GitHub-style activity heatmap widget for Ivy Framework. Renders an activity graph grid, either day-by-day (52-week × 7-day) or hour-by-hour.

Usage

The recommended way to build a heatmap is the ToActivityHeatmap() builder, which projects any IEnumerable<T> / IQueryable<T> into the grid using a dimension (the date/time axis) and a measure (the aggregated value per cell).

using Ivy.Widgets.ActivityHeatmap;

public record RepoStats(DateOnly Date, DateTime Timestamp, int Stars, int Downloads);

public class ActivityHeatmapDemo : ViewBase
{
    public override object Build()
    {
        var repoService = UseService<IMyRepoService>();
        var dailyStats = repoService.GetDailyStats().ToList();

        return dailyStats.ToActivityHeatmap(
            dimension: e => e.Date,
            measure: e => e.Downloads);
    }
}

Values are summed per cell. The measure supports int, long, float, double, decimal, and their nullable variants. To count events per cell, use a constant measure such as measure: _ => 1.

For a custom aggregator, call .Measure(name, q => ...) on the returned builder.

Daily vs. hourly intervals

The Interval controls whether each cell represents a day or an hour:

• ActivityInterval.Daily — a 52-week × 7-day grid (GitHub contributions style).
• ActivityInterval.Hourly — an hour-by-hour grid.

If you don't set Interval explicitly, the builder auto-detects it: when the dimension values carry a non-zero time component, it uses Hourly; otherwise Daily. Set it explicitly with .Interval(...) to override.

Low-level widget

You can also construct the widget directly and supply pre-aggregated data. Each Activity should be unique per cell (one entry per day, or per day+hour for hourly):

var data = new[]
{
    new Activity { Date = DateOnly.FromDateTime(DateTime.Today), Count = 5 },
};

new ActivityHeatmap()
    .Data(data)
    .ColorScheme(Colors.Green)
    .OnDayClick(day => Console.WriteLine($"Clicked {day.Date}: {day.Count}"));

Builder API

The builder (ToActivityHeatmap()) exposes the configuration below in addition to the widget props.

Props

These props apply to the ActivityHeatmap widget (the builder forwards most of them).

If both StartDate and EndDate are set and EndDate is before StartDate, the widget treats the range in chronological order (same as swapping the two values), so the grid still renders instead of collapsing to zero weeks.

Activity

Activity is the per-cell data record:

Data Constraints

• Duplicate cells in Data are not supported — provide at most one Activity per DateOnly (daily) or per DateOnly + Hour (hourly).
• If your source can produce duplicates, aggregate them first (for example by summing counts per cell) before passing data to ActivityHeatmap. The ToActivityHeatmap() builder handles this aggregation for you.

Events

Development

Building

1. Install frontend dependencies:

   cd frontend
   pnpm install
   

2. Build the frontend:

   pnpm build
   

3. Build the widget (repository root, or any path that builds Ivy.Widgets.ActivityHeatmap.csproj):

   dotnet build
   

   The widget project uses Ivy’s external-widget MSBuild targets: dotnet build runs vp install / vp build in frontend when needed, so after dependencies exist you can rely on that instead of repeating steps 1–2.

Frontend watch

While changing React/TypeScript under frontend/src, run a watch build in another terminal:

cd frontend
pnpm exec vp build --watch

Sample app

cd .samples
dotnet run