UI/UX Enhancement: Interactive Hover Tooltips on Customize Page Monolith Preview (JhaSourav07#1770)

## Description

Fixes JhaSourav07#1730 

### Summary of Changes:
* **SVG Interactive Layers, DRY Styles & Sanitization (`lib/svg/`)**:
- Embedded `data-date`, `data-count`, and `data-metric` attributes
directly onto the SVG towers.
- XML-escaped interpolated attributes (`escapeXML`) to ensure total SVG
validity and XSS safety.
- Disabled pointer-events on ambient heat particles so they do not steal
hover/touch actions from the underlying columns.
- Scoped hover transition rules inside SVG `<style>` stylesheets to
raise columns by `4px` and add matching alpha glows on cursor hover.
Created a DRY helper function `getInteractiveTowerCSS` to generate and
apply these interactive styles cleanly across both static and
auto-themed badges.
* **Inline Dynamic Preview & Secure Input (`app/customize/page.tsx`)**:
- Swapped out the static `<img>` preview wrapper for inline SVG text
dynamically fetched on parameter change and injected using a sanitized
DOM updater to block any custom script tags or event handlers.
- Decoupled rate limiting (HTTP 429) cleanly from not found states,
providing helpful rate-limit warnings.
- Ensured deterministic error state transitions by resetting
`errorMessage` directly at the start of the `useEffect` body.
* **React Portal & High-Frequency Performance Optimization
(`components/InteractiveViewer.tsx`)**:
- Implemented high-performance event delegation listeners
(`onPointerMove`, `onPointerDown`, `onPointerUp`, `onPointerLeave`) to
detect hover/tap actions on columns.
- Optimized the move handler utilizing a React `useRef` to track
`activeTooltipRef`. Renders and bounds calculation are triggered **only
when the hovered column date actually changes**, eliminating redundant
layout thrashing and continuous state updates.
- Resolved mobile touch-taps using `document.elementFromPoint(clientX,
clientY)` to bypass pointer capture limitations on `pointerup`.
- Positioned the premium glassy `<VisualizationTooltip>` utilizing a
**React Portal** (`createPortal`), ensuring it renders directly under
`document.body` to completely bypass transformed containers' local
stacking coordinate misalignments.
- Refactored `formatDate` to be extremely robust against empty or
malformed inputs, verifying date pieces before parsing.
* **TypeScript Compilation Fix (`lib/export3d.test.ts`)**:
- Integrated mock `date` fields across all test mock `TowerData` objects
in `lib/export3d.test.ts` to fully resolve the compiler and type-checker
warnings.

---

## Pillar

- [ ] 🎨 Pillar 1 – New Theme Design
- [x] 📐 Pillar 2 – Geometric SVG Improvement
- [ ] ⚙️ Pillar 3 – Timezone Logic Optimization
- [ ] 🛠️ Other (Bug fix, refactoring, docs)

---

## Visual Preview

| Desktop Hover Interaction | Mobile Tap / Touch Interaction |
| --- | --- |
| *(Hovering centers the glassy tooltip perfectly above the tower,
applying a subtle elevation rise and accent glow)* | *(Tapping the
columns triggers responsive tooltips instantly, with touch-drag panning
correctly hiding the tooltip)* |

---

## Checklist before requesting a review:

- [x] I have read the `CONTRIBUTING.md` file.
- [x] I have tested these changes locally
(`localhost:3000/api/streak?user=YOUR_USERNAME`).
- [x] I have run `npm run format` and `npm run lint` locally and
resolved all errors (CI will fail otherwise).
- [x] My commits follow the Conventional Commits format (e.g.,
`feat(themes): ...`, `fix(calculate): ...`).
- [x] I have updated `README.md` if I added a new theme or URL
parameter.
- [x] I have started the repo.
- [x] I have made sure that I have only one commit to merge in this PR.
- [x] The SVG output matches the CommitPulse "premium quality" aesthetic
standard (no raw elements, smooth animation: ...).
- [x] (Recommended) I joined the CommitPulse Discord server for faster
collaboration, mentorship, and PR support.

Author: JhaSourav07

app/customize/page.tsx

@@ -46,6 +46,9 @@ export default function CustomizePage(): ReactElement {
   const [copied, setCopied] = useState(false);
   const [copyStatusMessage, setCopyStatusMessage] = useState('');
   const copyResetTimeoutRef = useRef<number | null>(null);
+  const [svgContent, setSvgContent] = useState<string>('');
+  const [svgState, setSvgState] = useState<'idle' | 'loading' | 'loaded' | 'error'>('idle');
+  const [errorMessage, setErrorMessage] = useState<string | null>(null);
   const trimmedUsername = username.trim();
   const hasUsername = trimmedUsername.length > 0;
   const isAutoTheme = theme === 'auto';
@@ -156,6 +159,55 @@ export default function CustomizePage(): ReactElement {
 
   const queryString = buildQueryParams();
   const previewSrc = `/api/streak?${queryString}`;
+
+  useEffect(() => {
+    // eslint-disable-next-line react-hooks/set-state-in-effect
+    setErrorMessage(null);
+    if (!hasUsername) {
+      setSvgContent('');
+      setSvgState('idle');
+      return;
+    }
+
+    setSvgState('loading');
+    const controller = new AbortController();
+
+    fetch(previewSrc, { signal: controller.signal })
+      .then(async (res) => {
+        const text = await res.text();
+        if (!res.ok) {
+          setSvgContent('');
+          setSvgState('error');
+          if (res.status === 404 || res.status === 400) {
+            setErrorMessage('GitHub user not found');
+          } else if (res.status === 429) {
+            setErrorMessage('Rate limit exceeded. Please try again later.');
+          } else {
+            setErrorMessage('Failed to load badge');
+          }
+          return;
+        }
+        return text;
+      })
+      .then((text) => {
+        if (!text) return;
+        // Basic SVG sanitization to prevent XSS (strip scripts and inline event handlers)
+        const sanitized = text
+          .replace(/<script[\s\S]*?>[\s\S]*?<\/script>/gi, '')
+          .replace(/on\w+\s*=\s*("[^"]*"|'[^']*')/gi, '');
+        setSvgContent(sanitized);
+        setSvgState('loaded');
+        setErrorMessage(null);
+      })
+      .catch((err) => {
+        if (err.name === 'AbortError') return;
+        setSvgState('error');
+        setErrorMessage('Failed to load badge');
+      });
+
+    return () => controller.abort();
+  }, [previewSrc, hasUsername]);
+
   const exportSnippet = getExportSnippet(exportFormat, queryString);
 
   const fallbackCopyToClipboard = (text: string): boolean => {
@@ -371,17 +423,62 @@ export default function CustomizePage(): ReactElement {
                   <div className="absolute inset-0 bg-gradient-to-b from-transparent via-emerald-500/3 to-transparent animate-[pulse_3s_ease-in-out_infinite] pointer-events-none" />
 
                   {hasUsername ? (
-                    <>
-                      {/* eslint-disable-next-line @next/next/no-img-element */}
-                      <img
-                        key={previewSrc}
-                        src={previewSrc}
-                        alt="CommitPulse live preview"
-                        width={600}
-                        height={420}
-                        className="max-w-full h-auto drop-shadow-[0_20px_60px_rgba(0,0,0,0.6)] transition-opacity duration-300"
-                      />
-                    </>
+                    <div className="w-full flex items-center justify-center">
+                      {svgState === 'loading' && (
+                        <div className="h-[240px] w-full max-w-[600px] rounded-2xl bg-black/5 dark:bg-white/5 animate-pulse flex items-center justify-center text-sm text-gray-500 dark:text-white/40">
+                          Loading preview...
+                        </div>
+                      )}
+                      {svgState === 'error' && errorMessage === 'GitHub user not found' && (
+                        <div className="flex flex-col items-center justify-center gap-4 py-12 text-center">
+                          <div className="flex h-16 w-16 items-center justify-center rounded-3xl border border-red-500/20 bg-red-500/10 shadow-inner">
+                            <svg
+                              xmlns="http://www.w3.org/2000/svg"
+                              className="h-8 w-8 text-red-500"
+                              viewBox="0 0 24 24"
+                              fill="none"
+                              stroke="currentColor"
+                              strokeWidth="2.5"
+                              strokeLinecap="round"
+                              strokeLinejoin="round"
+                            >
+                              <line x1="18" y1="6" x2="6" y2="18"></line>
+                              <line x1="6" y1="6" x2="18" y2="18"></line>
+                            </svg>
+                          </div>
+                          <div>
+                            <p className="text-lg font-bold text-gray-900 dark:text-white tracking-tight">
+                              GitHub user not found
+                            </p>
+                            <p className="text-sm text-gray-500 dark:text-gray-400 mt-1">
+                              Please check the username and try again.
+                            </p>
+                          </div>
+                        </div>
+                      )}
+                      {svgState === 'error' && errorMessage !== 'GitHub user not found' && (
+                        <div className="flex flex-col items-center justify-center gap-2 text-center py-8">
+                          <p className="text-sm font-semibold text-red-500 dark:text-red-400">
+                            Failed to load badge
+                          </p>
+                          <p className="text-xs text-gray-500 dark:text-white/45">
+                            The API may be unavailable. Please try again.
+                          </p>
+                        </div>
+                      )}
+                      {svgState === 'loaded' && svgContent && (
+                        <motion.div
+                          initial={{ opacity: 0, scale: 0.95 }}
+                          animate={{ opacity: 1, scale: 1 }}
+                          transition={{ duration: 0.5, ease: 'easeOut' }}
+                          className="cp-svg-container w-full max-w-[600px] drop-shadow-[0_30px_60px_rgba(0,0,0,0.15)] dark:drop-shadow-[0_30px_60px_rgba(0,0,0,0.5)] [&>svg]:w-full [&>svg]:h-auto"
+                          dangerouslySetInnerHTML={{ __html: svgContent }}
+                        />
+                      )}
+                      {svgState === 'loaded' && !svgContent && errorMessage && (
+                        <p className="text-red-400 text-sm text-center">{errorMessage}</p>
+                      )}
+                    </div>
                   ) : (
                     <div className="relative z-10 flex w-full max-w-xl flex-col items-center justify-center rounded-[1.25rem] border border-dashed border-black/10 bg-gray-100/80 backdrop-blur-md dark:border-white/10 dark:bg-white/[0.03] px-6 py-12 text-center">
                       <div className="mb-4 flex h-14 w-14 items-center justify-center rounded-2xl border border-black/10 bg-gray-100/80 dark:border-white/10 dark:bg-white/[0.04] text-gray-500 dark:text-emerald-300/70">

components/InteractiveViewer.tsx

@@ -1,6 +1,9 @@
 'use client';
 
-import React, { useState, useRef, ReactNode, useMemo, type ReactElement } from 'react';
+import React, { useState, useRef, ReactNode, useMemo, useEffect, type ReactElement } from 'react';
+import { createPortal } from 'react-dom';
+import { AnimatePresence } from 'framer-motion';
+import VisualizationTooltip from './dashboard/VisualizationTooltip';
 
 // ── Parallax particle configuration ──────────────────────────────────────────
 // Particles are generated deterministically so SSR and client renders match,
@@ -45,6 +48,35 @@ function buildParticles(): ParallaxParticle[] {
 // container edge. Shallower particles shift proportionally less.
 const PARALLAX_STRENGTH = 80;
 
+interface ActiveTooltipState {
+  date: string;
+  count: number;
+  metric: string;
+  x: number;
+  y: number;
+}
+
+const formatDate = (dateStr: string): string => {
+  if (!dateStr) return '';
+  const parts = dateStr.split('-');
+  if (parts.length !== 3) return dateStr;
+  const year = parseInt(parts[0], 10);
+  const month = parseInt(parts[1], 10);
+  const day = parseInt(parts[2], 10);
+  if (isNaN(year) || isNaN(month) || isNaN(day)) return dateStr;
+  try {
+    const date = new Date(year, month - 1, day);
+    const formatted = date.toLocaleDateString('en-US', {
+      month: 'short',
+      day: 'numeric',
+      year: 'numeric',
+    });
+    return formatted === 'Invalid Date' ? dateStr : formatted;
+  } catch {
+    return dateStr;
+  }
+};
+
 interface InteractiveViewerProps {
   children: ReactNode;
   className?: string;
@@ -66,6 +98,14 @@ export default function InteractiveViewer({
   const isDragging = useRef(false);
   const [isDraggingState, setIsDraggingState] = useState(false);
   const lastMousePos = useRef({ x: 0, y: 0 });
+  const [activeTooltip, setActiveTooltip] = useState<ActiveTooltipState | null>(null);
+  const activeTooltipRef = useRef<ActiveTooltipState | null>(null);
+  const startPointerPos = useRef({ x: 0, y: 0 });
+  const [mounted, setMounted] = useState(false);
+  useEffect(() => {
+    // eslint-disable-next-line react-hooks/set-state-in-effect
+    setMounted(true);
+  }, []);
 
   // Stable particle list — generated once on mount, never re-shuffled.
   const particles = useMemo((): ParallaxParticle[] => buildParticles(), []);
@@ -131,6 +171,7 @@ export default function InteractiveViewer({
     isDragging.current = true;
     setIsDraggingState(true);
     lastMousePos.current = { x: e.clientX, y: e.clientY };
+    startPointerPos.current = { x: e.clientX, y: e.clientY };
     e.currentTarget.setPointerCapture(e.pointerId);
   };
 
@@ -145,17 +186,80 @@ export default function InteractiveViewer({
     }
 
     // Only apply pan logic when actively dragging
-    if (!isDragging.current) return;
-    const dx = e.clientX - lastMousePos.current.x;
-    const dy = e.clientY - lastMousePos.current.y;
-    setPan((p) => ({ x: p.x + dx, y: p.y + dy }));
-    lastMousePos.current = { x: e.clientX, y: e.clientY };
+    if (isDragging.current) {
+      const dx = e.clientX - lastMousePos.current.x;
+      const dy = e.clientY - lastMousePos.current.y;
+      setPan((p) => ({ x: p.x + dx, y: p.y + dy }));
+      lastMousePos.current = { x: e.clientX, y: e.clientY };
+      // Hide tooltip during active drag/pan
+      activeTooltipRef.current = null;
+      setActiveTooltip(null);
+      return;
+    }
+
+    // Detect if we are hovering over an interactive tower
+    const targetElement = e.target as HTMLElement;
+    const tower = targetElement.closest('.interactive-tower');
+    if (tower) {
+      const date = tower.getAttribute('data-date');
+      const countStr = tower.getAttribute('data-count');
+      const metric = tower.getAttribute('data-metric');
+      if (date && countStr && metric) {
+        if (!activeTooltipRef.current || activeTooltipRef.current.date !== date) {
+          const count = parseInt(countStr, 10);
+          const towerRect = tower.getBoundingClientRect();
+          const newTooltip = {
+            date,
+            count,
+            metric,
+            x: towerRect.left + towerRect.width / 2,
+            y: towerRect.top,
+          };
+          activeTooltipRef.current = newTooltip;
+          setActiveTooltip(newTooltip);
+        }
+      }
+    } else {
+      if (activeTooltipRef.current) {
+        activeTooltipRef.current = null;
+        setActiveTooltip(null);
+      }
+    }
   };
 
   const handlePointerUp = (e: React.PointerEvent): void => {
     isDragging.current = false;
     setIsDraggingState(false);
     e.currentTarget.releasePointerCapture(e.pointerId);
+
+    // If it was a tap (moved very little), show/toggle the tooltip!
+    const dx = Math.abs(e.clientX - startPointerPos.current.x);
+    const dy = Math.abs(e.clientY - startPointerPos.current.y);
+    if (dx < 5 && dy < 5) {
+      const targetElement = document.elementFromPoint(e.clientX, e.clientY) as HTMLElement;
+      const tower = targetElement?.closest('.interactive-tower');
+      if (tower) {
+        const date = tower.getAttribute('data-date');
+        const countStr = tower.getAttribute('data-count');
+        const metric = tower.getAttribute('data-metric');
+        if (date && countStr && metric) {
+          const count = parseInt(countStr, 10);
+          const towerRect = tower.getBoundingClientRect();
+          const newTooltip = {
+            date,
+            count,
+            metric,
+            x: towerRect.left + towerRect.width / 2,
+            y: towerRect.top,
+          };
+          activeTooltipRef.current = newTooltip;
+          setActiveTooltip(newTooltip);
+          return;
+        }
+      }
+    }
+    activeTooltipRef.current = null;
+    setActiveTooltip(null);
   };
 
   const handlePointerEnter = (): void => setIsHovering(true);
@@ -164,6 +268,8 @@ export default function InteractiveViewer({
     setIsHovering(false);
     // Reset cursor position to center so the glow fades out gracefully from center
     setMousePos({ x: 0.5, y: 0.5 });
+    activeTooltipRef.current = null;
+    setActiveTooltip(null);
   };
 
   const handleWheel = (e: React.WheelEvent): void => {
@@ -278,6 +384,52 @@ export default function InteractiveViewer({
       >
         {children}
       </div>
+
+      {mounted &&
+        createPortal(
+          <AnimatePresence>
+            {activeTooltip && (
+              <VisualizationTooltip
+                title={formatDate(activeTooltip.date)}
+                x={activeTooltip.x}
+                y={activeTooltip.y}
+              >
+                <div className="flex flex-col gap-1.5 min-w-[140px] p-0.5">
+                  <div className="text-[11px] font-semibold text-gray-900 dark:text-zinc-100 flex justify-between items-center">
+                    <span>Contributions</span>
+                    <span className="text-emerald-500 dark:text-emerald-400 font-bold bg-emerald-500/10 px-1.5 py-0.5 rounded text-[10px] min-w-[1.5rem] text-center">
+                      {activeTooltip.count}
+                    </span>
+                  </div>
+                  <div className="h-px bg-black/5 dark:bg-white/5 w-full" />
+                  <div className="flex items-center gap-1.5">
+                    <span
+                      className={`inline-block w-1.5 h-1.5 rounded-full ${
+                        activeTooltip.metric === 'Peak day'
+                          ? 'bg-emerald-500 shadow-[0_0_6px_#10b981]'
+                          : activeTooltip.metric === 'Active day'
+                            ? 'bg-cyan-500 shadow-[0_0_6px_#06b6d4]'
+                            : 'bg-zinc-400 dark:bg-zinc-500'
+                      }`}
+                    />
+                    <span
+                      className={`text-[9px] font-bold uppercase tracking-wider ${
+                        activeTooltip.metric === 'Peak day'
+                          ? 'text-emerald-500 dark:text-emerald-400'
+                          : activeTooltip.metric === 'Active day'
+                            ? 'text-cyan-500 dark:text-cyan-400'
+                            : 'text-zinc-500 dark:text-zinc-400'
+                      }`}
+                    >
+                      {activeTooltip.metric}
+                    </span>
+                  </div>
+                </div>
+              </VisualizationTooltip>
+            )}
+          </AnimatePresence>,
+          document.body
+        )}
     </div>
   );
 }

lib/export3d.test.ts

@@ -15,6 +15,7 @@ describe('generateMonolithSTL', () => {
         isToday: false,
         isTodayWithCommits: false,
         tooltip: '',
+        date: '',
         contributionCount: 5,
         faceOpacity: { left: 1, right: 1, top: 1 },
         strokeOpacity: 1,
@@ -32,6 +33,7 @@ describe('generateMonolithSTL', () => {
         isToday: false,
         isTodayWithCommits: false,
         tooltip: '',
+        date: '',
         contributionCount: 0,
         faceOpacity: { left: 1, right: 1, top: 1 },
         strokeOpacity: 1,
@@ -63,6 +65,7 @@ it('generates structurally valid ASCII STL facets', () => {
       isToday: false,
       isTodayWithCommits: false,
       tooltip: '',
+      date: '',
       contributionCount: 5,
       faceOpacity: { left: 1, right: 1, top: 1 },
       strokeOpacity: 1,
@@ -111,6 +114,7 @@ it('skips ghost towers (h=0) while still generating the base plate', () => {
       isToday: false,
       isTodayWithCommits: false,
       tooltip: '',
+      date: '',
       contributionCount: 0,
       faceOpacity: { left: 1, right: 1, top: 1 },
       strokeOpacity: 1,

lib/svg/generator.test.ts

@@ -1099,7 +1099,7 @@ describe('shading', () => {
       shadingCalendar
     );
     // The shaded SVG should still contain the tower paths
-    expect(svgShading).toContain('class="cp-tower"');
+    expect(svgShading).toContain('class="cp-tower interactive-tower"');
     // For level 1 (mult=0.4), base top face opacity 0.7 becomes 0.28
     // Check for that specific derived value to ensure shading actually multiplied it.
     expect(svgShading).toContain('fill-opacity="0.28"');