Refactor RecentThroughputHeatmapWidget and HeatmapService for enhanced scalability and flexibility

- Updated caching key version to `v14` for invalidation logic.
- Improved legend rendering with dynamic vertical padding and tick density scaling.
- Refined tooltip logic for better differentiation of empty vs. feathered cells.
- Optimized legend tick generation with adaptive intervals, precision formatting, and clamping logic.
- Introduced adaptive tick label anchoring to ensure proper positioning within the legend bounds.
- Enhanced layout styling for consistency and visual clarity.

Author: justinoakenfull

app/Filament/Widgets/RecentThroughputHeatmapWidget.php

@@ -60,7 +60,7 @@ public function paletteOptions(): array
     protected function getViewData(): array
     {
         $cfgHash = md5(json_encode(\App\Services\Heatmap\HeatmapConfig::forCompute()));
-        $cacheKey = sprintf('heatmap:composite:v12:%s:%s', $this->palette, $cfgHash);
+        $cacheKey = sprintf('heatmap:composite:v14:%s:%s', $this->palette, $cfgHash);
 
         $panels = Cache::remember($cacheKey, HeatmapConfig::cacheTtl(), function () {
             /** @var HeatmapService $svc */

app/Services/Heatmap/HeatmapService.php

@@ -155,14 +155,34 @@ private function composePanel(
         float $clampMin,
         float $clampMax
     ): array {
+        // --- Auto-scale legend tick label density by available pixels ---
+        // Legend column in Blade is set to 85% of the chart height.
+        $legendPixelHeight = (int) floor($size * 0.85);
+
+        // Minimum vertical spacing (in px) between labels so they don’t overlap.
+        // 16px works well for 11–12px font; tweak if your legend font changes.
+        $minTickSpacingPx = 16;
+
+        // Convert available pixels to a reasonable number of intervals.
+        // Clamp to avoid silly extremes (2..20 intervals -> 3..21 labels).
+        $autoIntervals = max(2, min(20, (int) floor($legendPixelHeight / max($minTickSpacingPx, 1))));
+
+        // Allow config to override; when null/absent we use the auto value.
+        // NOTE: HeatmapConfig::forCompute() should return 'legend_tick_intervals' as int|null.
+        $tickIntervals = $cfg['legend_tick_intervals'] ?? null;
+        if ($tickIntervals === null) {
+            $tickIntervals = $autoIntervals;
+        } else {
+            $tickIntervals = max(1, (int) $tickIntervals);
+        }
         return [
             'title' => $title,
             'xAxisTitle' => $xAxisTitle,
             'yAxisTitle' => $yAxisTitle,
             'xLabels' => $xLabels,
             'yLabels' => $yLabels,
-            'xTickEvery' => $this->tickEvery($cols, 12),
-            'yTickEvery' => $this->tickEvery($rows, 10),
+            'xTickEvery' => $this->tickEvery($cols, $cfg['axis_x_tick_target']),
+            'yTickEvery' => $this->tickEvery($rows, $cfg['axis_y_tick_target']),
             'width' => $size,
             'height' => $size,
             'gap' => $cfg['gap'],
@@ -172,7 +192,7 @@ private function composePanel(
                 $cfg['tile'], $cfg['gap'], $cfg['color_empty']
             ),
             'legendBar' => $this->legendBar($palette, $cfg['legend_steps']),
-            'legendTicks' => $this->legendTicks($clampMin, $clampMax, 6),
+            'legendTicks' => $this->legendTicks($clampMin, $clampMax, $tickIntervals),
             'tileStrokeColor' => $cfg['tile_stroke_color'],
             'tileStrokeWidth' => $cfg['tile_stroke_width'],
         ];
@@ -505,6 +525,7 @@ private function buildTiles(
         bool $colorEmptyCells
     ): array {
         $tiles = [];
+        $epsilon = 1e-12;
 
         $pitch = $tileSize + $tileGap;
 
@@ -522,12 +543,16 @@ private function buildTiles(
                 // we still color by feathered density but label as "feathered".
                 if ($hasRawData) {
                     $normalized = $this->scaleValue($densityValue, $legendMin, $legendMax, $valueScaleMode);
-                    $fillColor = HeatmapPalettes::colorAt($paletteName, $normalized);
-                    $tooltip = 'samples: '.(int) $rawCount;
-                } elseif ($colorEmptyCells) {
+                    $fillColor  = HeatmapPalettes::colorAt($paletteName, $normalized);
+                    $tooltip    = 'samples: ' . (int) $rawCount;
+                } elseif ($colorEmptyCells && $densityValue > $epsilon) {
                     $normalized = $this->scaleValue($densityValue, $legendMin, $legendMax, $valueScaleMode);
-                    $fillColor = HeatmapPalettes::colorAt($paletteName, $normalized);
-                    $tooltip = 'feathered';
+                    $fillColor  = HeatmapPalettes::colorAt($paletteName, $normalized);
+                    $tooltip    = 'feathered';
+                } else {
+                    // Force to lowest palette colour
+                    $fillColor  = HeatmapPalettes::colorAt($paletteName, 0.0);
+                    $tooltip    = 'no data';
                 }
 
                 // Positioning:
@@ -599,28 +624,62 @@ private function legendBar(string $paletteName, int $stepCount): array
      *                                                   'pos' => percentage from top (0..100), for CSS positioning,
      *                                                   'value' => integer-rounded numeric value at the tick.
      */
-    private function legendTicks(float $domainMin, float $domainMax, int $legendTickIntervals): array
+    private function legendTicks(float $domainMin, float $domainMax, int $targetIntervals): array
     {
+        $span = max($domainMax - $domainMin, 1e-9);
+        $step = $this->niceStep($span, $targetIntervals);
+
+        $start = $this->niceFloor($domainMin, $step);
+        $end   = $this->niceCeil($domainMax, $step);
+
+        $decimals = max(0, min(6, -(int) floor(log10(max($step, 1e-9)))));
+
         $ticks = [];
+        $lastLabel = null;
+
+        for ($v = $start; $v <= $end + 1e-9; $v += $step) {
+            // 0..1 where 0=domainMin, 1=domainMax
+            $t = ($v - $domainMin) / $span;
 
-        for ($i = 0; $i <= $legendTickIntervals; $i++) {
-            // Fraction across the legend scale, 0..1 inclusive.
-            $t = $i / max($legendTickIntervals, 1);
+            // Clamp for layout; we’ll keep value/label unchanged for integrity.
+            $tClamped = max(0.0, min(1.0, $t));
 
-            // Position in % from TOP:
-            // Magic: (1 - t) * 100 flips so that larger values are at the top of a
-            // vertical legend (CSS top origin). If your legend grows bottom→top, keep this.
-            $positionPercentFromTop = 100 * (1 - $t);
+            // Convert to top-from-percentage (UI has top=0 at legend's top).
+            $posTop = 100 * (1 - $tClamped);
 
-            // Interpolate the numeric value for the tick.
-            $valueAtTick = $domainMin + $t * ($domainMax - $domainMin);
+            // Choose anchor to avoid overflow at extremes
+            $anchor = 'middle';
+            if ($t <= 0.0 + 1e-9) {
+                $anchor = 'bottom';      // place label fully inside at top
+            } elseif ($t >= 1.0 - 1e-9) {
+                $anchor = 'top';   // place label fully inside at bottom
+            }
+
+            // Format label
+            $rounded = round($v, $decimals);
+            if (abs($rounded) < pow(10, -$decimals)) {
+                $rounded = 0.0;
+            }
+            $label = $decimals > 0 ? number_format($rounded, $decimals, '.', '') : (string) (int) round($rounded);
+
+            if ($label === $lastLabel) {
+                continue;
+            }
+            $lastLabel = $label;
 
             $ticks[] = [
-                'pos' => $positionPercentFromTop,
-                'value' => (int) round($valueAtTick),
+                'pos'    => $posTop,   // 0..100
+                'value'  => $rounded,  // numeric
+                'label'  => $label,    // string
+                'anchor' => $anchor,   // 'top' | 'middle' | 'bottom'
             ];
         }
 
+        if (!$ticks) {
+            $ticks[] = ['pos' => 100, 'value' => $domainMin, 'label' => (string)$domainMin, 'anchor' => 'bottom'];
+            $ticks[] = ['pos' => 0,   'value' => $domainMax, 'label' => (string)$domainMax, 'anchor' => 'top'];
+        }
+
         return $ticks;
     }
 
@@ -674,7 +733,7 @@ private function emptyPanel(string $title, array $cfg): array
             // - Palette 'viridis' with 48 steps (smooth enough for placeholders).
             // - Legend ticks from 0..6 with 6 intervals → 7 ticks.
             'tiles' => $tiles,
-            'legendBar' => $this->legendBar('viridis', 48),
+            'legendBar' => $this->legendBar(HeatmapConfig::defaultPalette(), $cfg['legend_steps']),
             'legendTicks' => $this->legendTicks(0, 6, 6),
 
             'tileStrokeColor' => $cfg['tile_stroke_color'],
@@ -1172,6 +1231,7 @@ private function legendClamp(array $densityGrid, string $scaleMode): array
             case 'p99':
                 $legendMax = max(1.0, $p99Value);
                 break;
+            case 'adaptive':
             default: // 'auto'
                 $legendMax = max(1.0, $p99Value);
                 // If there's an extreme outlier, allow expansion

resources/views/filament/widgets/recent-throughput-heatmap.blade.php

@@ -149,8 +149,10 @@ class="hm-tip pointer-events-none absolute z-20 min-w-[180px] shadow-lg">
                                 </div>
 
                                 <div class="w-16 sm:w-20 shrink-0 relative hm-legend">
-                                    <div class="h-full relative" style="height: 85%;">
-                                        <div class="absolute inset-y-0 left-0 w-4 sm:w-5 rounded-md overflow-hidden hm-legend-bar">
+                                    <div class="h-full relative overflow-hidden hm-legend-wrap" style="--vpad:12px;">
+                                        {{-- gradient bar with vertical padding --}}
+                                        <div class="absolute left-0 rounded-md overflow-hidden hm-legend-bar"
+                                             style="top: var(--vpad); bottom: var(--vpad); width: 1.25rem;">
                                             <div class="flex h-full w-full flex-col">
                                                 @foreach ($legendBar as $color)
                                                     <span style="background: {{ $color }}; height: {{ 100 / max(count($legendBar),1) }}%;"></span>
@@ -159,11 +161,29 @@ class="hm-tip pointer-events-none absolute z-20 min-w-[180px] shadow-lg">
                                         </div>
 
                                         @foreach ($legendTicks as $tick)
-                                            <div class="absolute flex items-center gap-2"
-                                                 style="left: calc(1.25rem + 4px); top: {{ $tick['pos'] }}%; transform: translateY(-50%);">
-                                                <span class="hm-legend-line"></span>
-                                                <span class="hm-legend-label">{{ $tick['value'] }}</span>
-                                            </div>
+                                            @php
+                                                $anchor    = $tick['anchor'] ?? 'middle';
+                                                $translate = match($anchor) {
+                                                    'top'    => 'translateY(0%)',
+                                                    'bottom' => 'translateY(-100%)',
+                                                    default  => 'translateY(-50%)',
+                                                };
+                                                // keep the raw % from service (0..100 from top)
+                                                $pos = (float) $tick['pos'];
+                                            @endphp
+
+                                            {{-- 1px rule at the exact value, adjusted for vertical padding --}}
+                                            <span class="hm-legend-line absolute"
+                                                  style="left: calc(1.25rem + 4px);
+                         top: calc(var(--vpad) + ({{ $pos }}% * (100% - (2 * var(--vpad))) / 100));"></span>
+
+                                            {{-- label at the same position, anchored to stay inside --}}
+                                            <span class="hm-legend-label absolute"
+                                                  style="left: calc(1.25rem + 4px + 12px);
+                         top: calc(var(--vpad) + ({{ $pos }}% * (100% - (2 * var(--vpad))) / 100));
+                         transform: {{ $translate }};">
+                {{ $tick['value'] }}
+            </span>
                                         @endforeach
                                     </div>
 
@@ -182,6 +202,15 @@ class="hm-tip pointer-events-none absolute z-20 min-w-[180px] shadow-lg">
             .vertical-text{ writing-mode: vertical-rl; text-orientation: mixed; }
             [x-cloak]{ display:none !important; }
 
+            .hm-legend-line{
+                width: 8px;
+                height: 1px;
+                background-color: rgba(255,255,255,.5);
+                display: inline-block;
+                transform: translateY(-0.5px);
+            }
+            .hm-legend-label{ color:#fff; font-size:11px; white-space:nowrap; }
+
             .hm-tip{
                 font-size: var(--font-size, 12px);
                 font-family: var(--ff, 'Helvetica Neue', 'Helvetica', 'Arial', sans-serif);
@@ -200,6 +229,7 @@ class="hm-tip pointer-events-none absolute z-20 min-w-[180px] shadow-lg">
                 --caret-size: 5px;
                 --caret-pad: 2px;
                 --caret-x: 12px;
+                --vpad: 16px;
                 background: var(--bg);
                 color: var(--body-color);
                 padding: var(--pad);
@@ -231,8 +261,6 @@ class="hm-tip pointer-events-none absolute z-20 min-w-[180px] shadow-lg">
             .hm-footer{ color: var(--footer-color); font-weight: 700; margin-top: var(--footer-mt); }
 
             .hm-legend-bar{ border: 0 solid rgba(0,0,0,0); border-radius: 6px; }
-            .hm-legend-line{ width: 8px; height: 1px; background-color: rgba(255,255,255,.5); display:inline-block; }
-            .hm-legend-label{ color: #fff; font-size: 11px; }
         </style>
 
         <script>