Activity Grid

# Brok UI: Heatmap (`heatmap`)

A calendar contribution heatmap with discrete or interpolated colour scales, square or bubble cells.

Brok UI is a Laravel Blade component registry. Installed components are plain Blade files the app owns.

## Install

```bash
php artisan ui:add heatmap
```

## Usage

```blade
@php
    // Deterministic sample data so the preview/test render is stable.
    $start = \Illuminate\Support\Carbon::create(2026, 1, 1);
    $end = \Illuminate\Support\Carbon::create(2026, 4, 1);
    $data = [];
    $seed = 7;
    for ($d = $start->copy(); $d->lte($end); $d->addDay()) {
        $seed = ($seed * 1103515245 + 12345) % 2147483648;
        $v = $seed % 6;
        if ($v > 0) {
            $data[] = ['date' => $d->toDateString(), 'value' => $v];
        }
    }
@endphp

<x-ui.heatmap :data="$data" :start-date="$start->toDateString()" :end-date="$end->toDateString()" />
```

## Props

- `data` (array, default `[]`) — Daily values: a list of {date, value} rows (count is accepted as an alias of value), or a date => value map.
- `startDate` (mixed|null, default `null`) — First date of the grid; defaults to the earliest date in data.
- `endDate` (mixed|null, default `null`) — Last date of the grid; defaults to the latest date in data.
- `weeks` (mixed|null, default `null`) — Alternative to startDate: shows the last N weeks ending on endDate.
- `showMonths` (bool, default `true`) — Shows the row of month labels above the grid.
- `showLegend` (bool, default `false`) — Shows a "Less … More" swatch legend below the grid.
- `cellSize` (int, default `16`) — Cell width and height in pixels.
- `gap` (int, default `4`) — Gap in pixels between cells.
- `daysOfTheWeek` (string, default `MWF`) — Which weekday row labels to show: MWF, all, single (single letter), or none.
- `displayStyle` (string, default `squares`) — Renders cells as squares or as bubbles sized by value.
- `colorMode` (string, default `discrete`) — discrete buckets values into colorScale levels; interpolate blends continuously between minColor and maxColor.
- `colorScale` (mixed|null, default `null`) — Custom discrete colour levels, low to high; defaults to a four-step success-token scale.
- `maxColor` (mixed|null, default `null`) — High end of a custom interpolated scale, used with minColor and colorMode="interpolate".
- `minColor` (mixed|null, default `null`) — Low end of a custom interpolated scale, used with maxColor and colorMode="interpolate".
- `interpolation` (string, default `linear`) — Curve mapping value to colour intensity: linear, sqrt, or log.

## Use when

- Use when trend, distribution, flow, intensity, or relationship questions are easier to answer visually than in raw numbers.
- Showing daily activity density over a calendar range, GitHub contribution-grid style.
- Needing either a fixed date range or a rolling N-week window ending on a given date.

## Avoid when

- Do not use a chart when users mainly need exact lookup or when a single metric would be clearer as text or a stat.
- The data is a matrix of two categorical axes rather than a daily calendar; use chart's heatmap type instead.
- The dataset spans a long custom time series better read as a line or area trend; use chart instead.

## Anti-patterns

- Decorative charts without a meaningful question

## Rules

- Use the `<brok:heatmap>` tag (or `<x-ui.heatmap>`) in Blade; do not rewrite the component.
- Prefer the documented props and variants over utility-class overrides; when a utility must win, use the `!` important modifier.
- Use semantic design tokens (`bg-primary`, `text-muted-foreground`), never raw colour utilities.
- Keep the `data-slot` attributes; they are the styling and test hooks.

## Links

- Docs: https://brokui.dev/docs/components/heatmap
- Registry JSON (files, props, contract): https://brokui.dev/r/open/heatmap.json

@props([
    'data' => [],
    'startDate' => null,
    'endDate' => null,
    // Alternative to `startDate`: show the last N weeks ending on `endDate`
    // (the GitHub contribution-grid framing).
    'weeks' => null,
    'showMonths' => true,
    // A "Less … More" swatch legend (discrete mode; interpolated scales show
    // their two ends).
    'showLegend' => false,
    'cellSize' => 16,
    'gap' => 4,
    'daysOfTheWeek' => 'MWF',
    'displayStyle' => 'squares',
    'colorMode' => 'discrete',
    'colorScale' => null,
    'maxColor' => null,
    'minColor' => null,
    'interpolation' => 'linear',
])

@php
    use Illuminate\Support\Carbon;

    // ── Normalise inputs ────────────────────────────────────────────────────
    // `data` accepts either [['date' => 'Y-m-d', 'value' => n], ...] (`count`
    // is read as an alias of `value`) or a map
    // ['Y-m-d' => n, ...]. Build a date => value lookup either way.
    $values = [];
    foreach ($data as $key => $row) {
        if (is_array($row)) {
            $d = $row['date'] ?? null;
            $v = (float) ($row['value'] ?? $row['count'] ?? 0);
        } else {
            $d = $key;
            $v = (float) $row;
        }
        if ($d !== null) {
            $values[Carbon::parse($d)->toDateString()] = $v;
        }
    }

    $showMonths = filter_var($showMonths, FILTER_VALIDATE_BOOLEAN);
    $showLegend = filter_var($showLegend, FILTER_VALIDATE_BOOLEAN);

    $end = Carbon::parse($endDate ?: (array_key_last($values) ?: 'now'))->startOfDay();
    $start = $weeks !== null
        ? $end->copy()->endOfWeek(Carbon::SATURDAY)->subWeeks(max(1, min(53, (int) $weeks)) - 1)->startOfWeek(Carbon::SUNDAY)
        : Carbon::parse($startDate ?: (array_key_first($values) ?: 'now'))->startOfDay();
    if ($end->lt($start)) {
        [$start, $end] = [$end, $start];
    }

    $max = $values ? max(max($values), 0.0) : 0.0;

    // Grid starts on the Sunday on/just before the start date (GitHub layout:
    // columns = weeks, 7 rows = Sun..Sat).
    $gridStart = $start->copy()->startOfWeek(Carbon::SUNDAY);

    $cell = (int) $cellSize;
    $gapPx = (int) $gap;

    // ── Colour resolution ───────────────────────────────────────────────────
    // Default discrete palette themes via the success token (level 0 = muted).
    $defaultLevels = ['color-mix(in oklab, var(--success-color, hsl(var(--success))) calc(0.20 * 100%), transparent)', 'color-mix(in oklab, var(--success-color, hsl(var(--success))) calc(0.40 * 100%), transparent)', 'color-mix(in oklab, var(--success-color, hsl(var(--success))) calc(0.65 * 100%), transparent)', 'color-mix(in oklab, var(--success-color, hsl(var(--success))) calc(1 * 100%), transparent)'];
    $scale = is_array($colorScale) && $colorScale ? $colorScale : $defaultLevels;
    $levelCount = count($scale);
    $usesCustomInterpolation = is_string($minColor) && $minColor !== '' && is_string($maxColor) && $maxColor !== '';

    $ratioOf = function (float $v) use ($max, $interpolation): float {
        if ($max <= 0 || $v <= 0) {
            return 0.0;
        }
        $r = $v / $max;
        return match ($interpolation) {
            'sqrt' => sqrt($r),
            'log' => log($v + 1) / log($max + 1),
            default => $r,
        };
    };

    $colorFor = function (float $v) use ($colorMode, $scale, $levelCount, $ratioOf, $usesCustomInterpolation, $minColor, $maxColor) {
        if ($v <= 0) {
            return 'var(--muted-color, hsl(var(--muted)))';
        }
        if ($colorMode === 'interpolate') {
            $t = $ratioOf($v);
            if ($usesCustomInterpolation) {
                return sprintf('color-mix(in srgb, %s %d%%, %s)', $maxColor, (int) round($t * 100), $minColor);
            }
            $alpha = number_format(0.20 + ($t * 0.80), 2, '.', '');
            return "color-mix(in oklab, var(--success-color, hsl(var(--success))) calc({$alpha} * 100%), transparent)";
        }
        // discrete: bucket the ratio across the available levels
        $idx = (int) ceil($ratioOf($v) * $levelCount) - 1;
        $idx = max(0, min($levelCount - 1, $idx));
        return $scale[$idx];
    };

    // ── Build week columns ──────────────────────────────────────────────────
    // Cells before $start or after $rangeEnd render transparent so the grid is
    // a clean rectangle without implying data outside the requested window.
    $rangeEnd = $end->copy();
    $gridEnd = $end->copy()->endOfWeek(Carbon::SATURDAY);
    $weeks = [];
    $total = 0.0;
    $cursor = $gridStart->copy();
    while ($cursor->lte($gridEnd)) {
        $week = [];
        for ($i = 0; $i < 7; $i++) {
            $ds = $cursor->toDateString();
            $inRange = $cursor->gte($start) && $cursor->lte($rangeEnd);
            $dayValue = $values[$ds] ?? 0.0;
            if ($inRange) {
                $total += $dayValue;
            }
            $week[] = [
                'date' => $cursor->copy(),
                'inRange' => $inRange,
                'value' => $dayValue,
            ];
            $cursor->addDay();
        }
        $weeks[] = $week;
    }

    // Summary label so keyboard / screen-reader users get the whole dataset —
    // the per-cell `title` tooltips are hover-only. `role="img"` + this label
    // matches every other Charts/Diagrams item.
    $totalLabel = rtrim(rtrim(number_format($total, 2, '.', ''), '0'), '.');
    $summaryLabel = __('Activity heatmap, :start to :end, :count event(s).', [
        'start' => $start->toFormattedDayDateString(),
        'end' => $rangeEnd->toFormattedDayDateString(),
        'count' => $totalLabel,
    ]);

    // Weekday labels (row index 0 = Sunday).
    $weekdayLabels = match ($daysOfTheWeek) {
        'all' => ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'],
        'single letter', 'single' => ['S', 'M', 'T', 'W', 'T', 'F', 'S'],
        'none' => [],
        default => [1 => 'Mon', 3 => 'Wed', 5 => 'Fri'], // MWF
    };
    $showWeekdays = $daysOfTheWeek !== 'none';
    $labelColW = $showWeekdays ? ($daysOfTheWeek === 'all' ? 30 : 18) : 0;
@endphp

<div
    data-slot="heatmap"
    data-color-mode="{{ $colorMode }}"
    role="img"
    aria-label="{{ $summaryLabel }}"
    {{ $attributes->merge(['class' => 'inline-flex flex-col gap-1 text-2xs text-muted-foreground']) }}
>
    {{-- Month labels --}}
    @if ($showMonths)
    @php
        // One label per month, on the first column that starts in it. A month
        // that owns only the first column is left unlabelled so its name does
        // not collide with the next one ("DecJan").
        $monthLabels = [];
        $lastMonth = null;
        foreach ($weeks as $wi => $week) {
            $top = $week[0]['date'];
            $monthLabels[$wi] = '';
            if ($top->month !== $lastMonth) {
                $monthLabels[$wi] = $top->format('M');
                $lastMonth = $top->month;
            }
        }
        if (count($weeks) > 1 && $weeks[1][0]['date']->month !== $weeks[0][0]['date']->month) {
            $monthLabels[0] = '';
        }
    @endphp
    <div class="flex" style="margin-inline-start: {{ $labelColW }}px; gap: {{ $gapPx }}px;" aria-hidden="true">
        @foreach ($weeks as $wi => $week)
            <div style="width: {{ $cell }}px;" class="overflow-visible whitespace-nowrap">{{ $monthLabels[$wi] }}</div>
        @endforeach
    </div>
    @endif

    <div class="flex" style="gap: {{ $gapPx }}px;" aria-hidden="true">
        {{-- Weekday labels --}}
        @if ($showWeekdays)
            <div class="flex flex-col" style="gap: {{ $gapPx }}px; width: {{ $labelColW }}px;">
                @for ($r = 0; $r < 7; $r++)
                    <div class="flex items-center" style="height: {{ $cell }}px;">{{ $weekdayLabels[$r] ?? '' }}</div>
                @endfor
            </div>
        @endif

        {{-- Week columns --}}
        @foreach ($weeks as $week)
            <div class="flex flex-col" style="gap: {{ $gapPx }}px;">
                @foreach ($week as $day)
                    @php
                        $v = $day['value'];
                        $visible = $day['inRange'];
                        $bg = $visible ? $colorFor($v) : 'transparent';
                        $tip = $visible ? $day['date']->toFormattedDayDateString().': '.rtrim(rtrim(number_format($v, 2, '.', ''), '0'), '.').' event(s)' : '';
                        if ($displayStyle === 'bubbles') {
                            $ratio = $max > 0 && $v > 0 ? max(0.35, $v / $max) : 0.35;
                            $inner = (int) round($cell * $ratio);
                        }
                    @endphp
                    @if ($displayStyle === 'bubbles')
                        <div class="flex items-center justify-center" style="width: {{ $cell }}px; height: {{ $cell }}px;"
                             @if ($visible) title="{{ $tip }}" @endif>
                            <div class="rounded-full" style="width: {{ $inner }}px; height: {{ $inner }}px; background-color: {{ $bg }};"></div>
                        </div>
                    @else
                        <div
                            class="rounded-[2px]"
                            style="width: {{ $cell }}px; height: {{ $cell }}px; background-color: {{ $bg }};"
                            @if ($visible) title="{{ $tip }}" @endif
                        ></div>
                    @endif
                @endforeach
            </div>
        @endforeach
    </div>

    @if ($showLegend)
        <div class="flex items-center gap-1 self-end" aria-hidden="true">
            <span>{{ __('Less') }}</span>
            @foreach ($colorMode === 'interpolate' ? [0.0, 0.25, 0.5, 0.75, 1.0] : array_merge([0.0], array_map(fn ($i) => ($i + 1) / $levelCount, range(0, $levelCount - 1))) as $t)
                <span class="{{ $displayStyle === 'bubbles' ? 'rounded-full' : 'rounded-[2px]' }}" style="width: {{ $cell }}px; height: {{ $cell }}px; background-color: {{ $t <= 0 ? 'var(--muted-color, hsl(var(--muted)))' : $colorFor($t * max($max, 1)) }};"></span>
            @endforeach
            <span>{{ __('More') }}</span>
        </div>
    @endif
</div>