From 5bbbef53057c3539c510562304cefa83c63d058e Mon Sep 17 00:00:00 2001
From: Peak Twilight <77903714+peaktwilight@users.noreply.github.com>
Date: Sat, 12 Jul 2025 13:34:33 +0200
Subject: [PATCH] feat: Add heartbeat tooltip while hovering over status page
 heartbeats (#5929)

Co-authored-by: Frank Elsinga <frank@elsinga.de>
---
 src/components/HeartbeatBar.vue | 200 +++++++++++++++++++++--
 src/components/Tooltip.vue      | 276 ++++++++++++++++++++++++++++++++
 2 files changed, 466 insertions(+), 10 deletions(-)
 create mode 100644 src/components/Tooltip.vue

diff --git a/src/components/HeartbeatBar.vue b/src/components/HeartbeatBar.vue
index 429ca9f91..ad133821e 100644
--- a/src/components/HeartbeatBar.vue
+++ b/src/components/HeartbeatBar.vue
@@ -7,11 +7,17 @@
                 class="beat-hover-area"
                 :class="{ 'empty': (beat === 0) }"
                 :style="beatHoverAreaStyle"
-                :title="getBeatTitle(beat)"
+                :aria-label="getBeatAriaLabel(beat)"
+                role="status"
+                tabindex="0"
+                @mouseenter="showTooltip(beat, $event)"
+                @mouseleave="hideTooltip"
+                @focus="showTooltip(beat, $event)"
+                @blur="hideTooltip"
             >
                 <div
                     class="beat"
-                    :class="{ 'empty': (beat === 0), 'down': (beat.status === 0), 'pending': (beat.status === 2), 'maintenance': (beat.status === 3) }"
+                    :class="{ 'empty': (beat === 0 || beat === null || beat.status === null), 'down': (beat.status === DOWN), 'pending': (beat.status === PENDING), 'maintenance': (beat.status === MAINTENANCE) }"
                     :style="beatStyle"
                 />
             </div>
@@ -24,13 +30,27 @@
             <div v-if="$root.styleElapsedTime === 'with-line'" class="connecting-line"></div>
             <div>{{ timeSinceLastBeat }}</div>
         </div>
+
+        <!-- Custom Tooltip -->
+        <Tooltip
+            :visible="tooltipVisible"
+            :content="tooltipContent"
+            :x="tooltipX"
+            :y="tooltipY"
+            :position="tooltipPosition"
+        />
     </div>
 </template>
 
 <script>
 import dayjs from "dayjs";
+import { DOWN, UP, PENDING, MAINTENANCE } from "../util.ts";
+import Tooltip from "./Tooltip.vue";
 
 export default {
+    components: {
+        Tooltip,
+    },
     props: {
         /** Size of the heartbeat bar */
         size: {
@@ -46,6 +66,11 @@ export default {
         heartbeatList: {
             type: Array,
             default: null,
+        },
+        /** Heartbeat bar days */
+        heartbeatBarDays: {
+            type: Number,
+            default: 0
         }
     },
     data() {
@@ -56,10 +81,25 @@ export default {
             beatHoverAreaPadding: 4,
             move: false,
             maxBeat: -1,
+            // Tooltip data
+            tooltipVisible: false,
+            tooltipContent: null,
+            tooltipX: 0,
+            tooltipY: 0,
+            tooltipPosition: "below",
+            tooltipTimeoutId: null,
         };
     },
     computed: {
 
+        /**
+         * Normalized heartbeatBarDays as a number
+         * @returns {number} Number of days for heartbeat bar
+         */
+        normalizedHeartbeatBarDays() {
+            return Math.max(0, Math.min(365, Math.floor(this.heartbeatBarDays || 0)));
+        },
+
         /**
          * If heartbeatList is null, get it from $root.heartbeatList
          * @returns {object} Heartbeat list
@@ -80,6 +120,12 @@ export default {
             if (!this.beatList) {
                 return 0;
             }
+
+            // For configured ranges, no padding needed since we show all beats
+            if (this.normalizedHeartbeatBarDays > 0) {
+                return 0;
+            }
+
             let num = this.beatList.length - this.maxBeat;
 
             if (this.move) {
@@ -98,8 +144,20 @@ export default {
                 return [];
             }
 
+            // If heartbeat days is configured (not auto), data is already aggregated from server
+            if (this.normalizedHeartbeatBarDays > 0 && this.beatList.length > 0) {
+                // Show all beats from server - they are already properly aggregated
+                return this.beatList;
+            }
+
+            // Original logic for auto mode (heartbeatBarDays = 0)
             let placeholders = [];
 
+            // Handle case where maxBeat is -1 (no limit)
+            if (this.maxBeat <= 0) {
+                return this.beatList;
+            }
+
             let start = this.beatList.length - this.maxBeat;
 
             if (this.move) {
@@ -172,13 +230,17 @@ export default {
          * @returns {string} The time elapsed in minutes or hours.
          */
         timeSinceFirstBeat() {
+            if (this.normalizedHeartbeatBarDays === 1) {
+                return (this.normalizedHeartbeatBarDays * 24) + "h";
+            }
+            if (this.normalizedHeartbeatBarDays >= 2) {
+                return this.normalizedHeartbeatBarDays + "d";
+            }
+
+            // Need to calculate from actual data
             const firstValidBeat = this.shortBeatList.at(this.numPadding);
             const minutes = dayjs().diff(dayjs.utc(firstValidBeat?.time), "minutes");
-            if (minutes > 60) {
-                return (minutes / 60).toFixed(0) + "h";
-            } else {
-                return minutes + "m";
-            }
+            return minutes > 60 ? Math.floor(minutes / 60) + "h" : minutes + "m";
         },
 
         /**
@@ -205,7 +267,7 @@ export default {
     },
     watch: {
         beatList: {
-            handler(val, oldVal) {
+            handler() {
                 this.move = true;
 
                 setTimeout(() => {
@@ -217,6 +279,10 @@ export default {
     },
     unmounted() {
         window.removeEventListener("resize", this.resize);
+        // Clean up tooltip timeout
+        if (this.tooltipTimeoutId) {
+            clearTimeout(this.tooltipTimeoutId);
+        }
     },
     beforeMount() {
         if (this.heartbeatList === null) {
@@ -256,7 +322,23 @@ export default {
          */
         resize() {
             if (this.$refs.wrap) {
-                this.maxBeat = Math.floor(this.$refs.wrap.clientWidth / (this.beatWidth + this.beatHoverAreaPadding * 2));
+                const newMaxBeat = Math.floor(this.$refs.wrap.clientWidth / (this.beatWidth + this.beatHoverAreaPadding * 2));
+
+                // If maxBeat changed and we're in configured days mode, notify parent to reload data
+                if (newMaxBeat !== this.maxBeat && this.normalizedHeartbeatBarDays > 0) {
+                    this.maxBeat = newMaxBeat;
+
+                    // Find the closest parent with reloadHeartbeatData method (StatusPage)
+                    let parent = this.$parent;
+                    while (parent && !parent.reloadHeartbeatData) {
+                        parent = parent.$parent;
+                    }
+                    if (parent && parent.reloadHeartbeatData) {
+                        parent.reloadHeartbeatData(newMaxBeat);
+                    }
+                } else {
+                    this.maxBeat = newMaxBeat;
+                }
             }
         },
 
@@ -267,7 +349,105 @@ export default {
          * @returns {string} Beat title
          */
         getBeatTitle(beat) {
-            return `${this.$root.datetime(beat.time)}` + ((beat.msg) ? ` - ${beat.msg}` : "");
+            if (!beat) {
+                return "";
+            }
+
+            // Show timestamp for all beats (both individual and aggregated)
+            return `${this.$root.datetime(beat.time)}${beat.msg ? ` - ${beat.msg}` : ""}`;
+        },
+
+        /**
+         * Get the aria-label for accessibility
+         * @param {object} beat Beat to get aria-label from
+         * @returns {string} Aria label
+         */
+        getBeatAriaLabel(beat) {
+            switch (beat?.status) {
+                case DOWN:
+                    return `Down at ${this.$root.datetime(beat.time)}`;
+                case UP:
+                    return `Up at ${this.$root.datetime(beat.time)}`;
+                case PENDING:
+                    return `Pending at ${this.$root.datetime(beat.time)}`;
+                case MAINTENANCE:
+                    return `Maintenance at ${this.$root.datetime(beat.time)}`;
+                default:
+                    return "No data";
+            }
+        },
+
+        /**
+         * Show custom tooltip
+         * @param {object} beat Beat data
+         * @param {Event} event Mouse event
+         * @returns {void}
+         */
+        showTooltip(beat, event) {
+            if (beat === 0 || !beat) {
+                this.hideTooltip();
+                return;
+            }
+
+            // Clear any existing timeout
+            if (this.tooltipTimeoutId) {
+                clearTimeout(this.tooltipTimeoutId);
+            }
+
+            // Small delay for better UX
+            this.tooltipTimeoutId = setTimeout(() => {
+                this.tooltipContent = beat;
+
+                // Calculate position relative to viewport
+                const rect = event.target.getBoundingClientRect();
+
+                // Position relative to viewport
+                const x = rect.left + (rect.width / 2);
+                const y = rect.top;
+
+                // Check if tooltip would go off-screen and adjust position
+                const tooltipHeight = 80; // Approximate tooltip height
+                const viewportHeight = window.innerHeight;
+                const spaceAbove = y;
+                const spaceBelow = viewportHeight - y - rect.height;
+
+                if (spaceAbove > tooltipHeight && spaceBelow < tooltipHeight) {
+                    // Show above - arrow points down
+                    this.tooltipPosition = "above";
+                    this.tooltipY = y - 10;
+                } else {
+                    // Show below - arrow points up
+                    this.tooltipPosition = "below";
+                    this.tooltipY = y + rect.height + 10;
+                }
+
+                // Ensure tooltip doesn't go off the left or right edge
+                const tooltipWidth = 120; // Approximate tooltip width
+                let adjustedX = x;
+
+                if ((x - tooltipWidth / 2) < 10) {
+                    adjustedX = tooltipWidth / 2 + 10;
+                } else if ((x + tooltipWidth / 2) > (window.innerWidth - 10)) {
+                    adjustedX = window.innerWidth - tooltipWidth / 2 - 10;
+                }
+
+                this.tooltipX = adjustedX;
+                this.tooltipVisible = true;
+            }, 150);
+        },
+
+        /**
+         * Hide custom tooltip
+         * @returns {void}
+         */
+        hideTooltip() {
+            if (this.tooltipTimeoutId) {
+                clearTimeout(this.tooltipTimeoutId);
+                this.tooltipTimeoutId = null;
+            }
+
+            this.tooltipVisible = false;
+            this.tooltipContent = null;
         },
 
     },
diff --git a/src/components/Tooltip.vue b/src/components/Tooltip.vue
new file mode 100644
index 000000000..69af9ec5a
--- /dev/null
+++ b/src/components/Tooltip.vue
@@ -0,0 +1,276 @@
+<template>
+    <teleport to="body">
+        <div
+            v-if="content"
+            ref="tooltip"
+            class="tooltip-wrapper"
+            :style="tooltipStyle"
+            :class="{ 'tooltip-above': position === 'above' }"
+        >
+            <div class="tooltip-content">
+                <slot :content="content">
+                    <!-- Default content if no slot provided -->
+                    <div class="tooltip-status" :class="statusClass">
+                        {{ statusText }}
+                    </div>
+                    <div class="tooltip-time">{{ timeText }}</div>
+                    <div v-if="content?.msg" class="tooltip-message">{{ content.msg }}</div>
+                </slot>
+            </div>
+            <div class="tooltip-arrow" :class="{ 'arrow-above': position === 'above' }"></div>
+        </div>
+    </teleport>
+</template>
+
+<script>
+import { DOWN, UP, PENDING, MAINTENANCE } from "../util.ts";
+
+export default {
+    name: "Tooltip",
+    props: {
+        /** Whether tooltip is visible */
+        visible: {
+            type: Boolean,
+            default: false
+        },
+        /** Content object to display */
+        content: {
+            type: Object,
+            default: null
+        },
+        /** X position (viewport coordinates) */
+        x: {
+            type: Number,
+            default: 0
+        },
+        /** Y position (viewport coordinates) */
+        y: {
+            type: Number,
+            default: 0
+        },
+        /** Position relative to target element */
+        position: {
+            type: String,
+            default: "below",
+            validator: (value) => [ "above", "below" ].includes(value)
+        }
+    },
+    computed: {
+        tooltipStyle() {
+            return {
+                left: this.x + "px",
+                top: this.y + "px",
+            };
+        },
+
+        statusText() {
+            if (!this.content || this.content === 0) {
+                return this.$t("Unknown");
+            }
+
+            switch (this.content.status) {
+                case DOWN:
+                    return this.$t("Down");
+                case UP:
+                    return this.$t("Up");
+                case PENDING:
+                    return this.$t("Pending");
+                case MAINTENANCE:
+                    return this.$t("Maintenance");
+                default:
+                    return this.$t("Unknown");
+            }
+        },
+
+        statusClass() {
+            if (!this.content || this.content === 0) {
+                return "status-empty";
+            }
+
+            switch (this.content.status) {
+                case DOWN:
+                    return "status-down";
+                case UP:
+                    return "status-up";
+                case PENDING:
+                    return "status-pending";
+                case MAINTENANCE:
+                    return "status-maintenance";
+                default:
+                    return "status-unknown";
+            }
+        },
+
+        timeText() {
+            if (!this.content || this.content === 0) {
+                return "";
+            }
+            return this.$root.datetime(this.content.time);
+        },
+    }
+};
+</script>
+
+<style lang="scss" scoped>
+@import "../assets/vars.scss";
+
+.tooltip-wrapper {
+    position: fixed;
+    z-index: 9999;
+    pointer-events: none;
+    transform: translateX(-50%);
+
+    .tooltip-content {
+        background: rgba(17, 24, 39, 0.95);
+        backdrop-filter: blur(8px);
+        border: 1px solid rgba(75, 85, 99, 0.3);
+        border-radius: 8px;
+        padding: 8px 12px;
+        box-shadow: 0 10px 25px rgba(0, 0, 0, 0.25);
+        min-width: 120px;
+        text-align: center;
+        position: relative;
+
+        &::before {
+            content: "";
+            position: absolute;
+            left: 50%;
+            transform: translateX(-50%);
+            width: 14px;
+            height: 2px;
+            background: rgba(17, 24, 39, 0.95);
+            top: -1px;
+        }
+
+        .tooltip-status {
+            font-size: 16px;
+            font-weight: 600;
+            margin-bottom: 4px;
+            text-transform: uppercase;
+            letter-spacing: 0.5px;
+
+            &.status-up {
+                color: $primary;
+            }
+
+            &.status-down {
+                color: $danger;
+            }
+
+            &.status-pending {
+                color: $warning;
+            }
+
+            &.status-maintenance {
+                color: $maintenance;
+            }
+
+            &.status-empty {
+                color: $secondary-text;
+            }
+        }
+
+        .tooltip-time {
+            color: #d1d5db;
+            font-size: 13px;
+            margin-bottom: 2px;
+        }
+
+        .tooltip-message {
+            color: #f3f4f6;
+            font-size: 12px;
+            margin-top: 4px;
+            padding-top: 4px;
+            border-top: 1px solid rgba(75, 85, 99, 0.3);
+        }
+    }
+
+    .tooltip-arrow {
+        position: absolute;
+        left: 50%;
+        transform: translateX(-50%);
+        width: 12px;
+        height: 6px;
+        overflow: hidden;
+        top: -6px;
+
+        &::before {
+            content: "";
+            position: absolute;
+            left: 50%;
+            top: 100%;
+            transform: translateX(-50%) translateY(-50%) rotate(45deg);
+            width: 8px;
+            height: 8px;
+            background: rgba(17, 24, 39, 0.95);
+            border: 1px solid rgba(75, 85, 99, 0.3);
+            border-bottom: none;
+            border-right: none;
+        }
+
+        &.arrow-above {
+            top: auto;
+            bottom: -6px;
+
+            &::before {
+                top: 0%;
+                transform: translateX(-50%) translateY(-50%) rotate(225deg);
+                border: 1px solid rgba(75, 85, 99, 0.3);
+                border-bottom: none;
+                border-right: none;
+            }
+        }
+    }
+
+    // Smooth entrance animation
+    animation: tooltip-fade-in 0.2s $easing-out;
+
+    &.tooltip-above {
+        transform: translateX(-50%) translateY(-8px);
+
+        .tooltip-content::before {
+            top: auto;
+            bottom: -1px;
+        }
+    }
+}
+
+// Dark theme adjustments
+.dark .tooltip-wrapper {
+    .tooltip-content {
+        background: rgba(31, 41, 55, 0.95);
+        border-color: rgba(107, 114, 128, 0.3);
+
+        &::before {
+            background: rgba(31, 41, 55, 0.95);
+        }
+    }
+
+    .tooltip-arrow {
+        &::before {
+            background: rgba(31, 41, 55, 0.95);
+            border-color: rgba(107, 114, 128, 0.3);
+        }
+    }
+}
+
+@keyframes tooltip-fade-in {
+    from {
+        opacity: 0;
+        transform: translateX(-50%) translateY(4px);
+    }
+
+    to {
+        opacity: 1;
+        transform: translateX(-50%) translateY(0);
+    }
+}
+
+// Accessibility improvements
+
+@media (prefers-reduced-motion: reduce) {
+    .tooltip-wrapper {
+        animation: none !important;
+    }
+}
+</style>