feat(ui): replace heatmap with category breakdown + skeletons

Remove dead HeatmapWidget and the category heatmap grid. Replace with an
"Emails by Category" ranked horizontal bar list (top 8), each bar a
clickable button routing to the category folder via CAT_SLUG. Add Skeleton
loading placeholders and richer EmptyState fallbacks to dashboard widgets.
Drop the unused AnalyticsApi.heatmap client method and dead heatmap CSS.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

frontend/src/api/client.js

@@ -38,7 +38,6 @@ export const AnalyticsApi = {
   health: () => api.get('/analytics/health').then((r) => r.data),
   topSenders: (take = 20) => api.get(`/analytics/top-senders?take=${take}`).then((r) => r.data),
   volume: (days = 90) => api.get(`/analytics/volume?days=${days}`).then((r) => r.data),
-  heatmap: () => api.get('/analytics/heatmap').then((r) => r.data),
   categoryHeatmap: () => api.get('/analytics/category-heatmap').then((r) => r.data),
   attachments: () => api.get('/analytics/attachments').then((r) => r.data),
   sidebarCounts: () => api.get('/analytics/sidebar-counts').then((r) => r.data),

frontend/src/components/EmailRow.jsx

@@ -1,6 +1,5 @@
 import { useState } from 'react';
 import { EmailApi } from '../api/client.js';
-import { Checkbox } from './ui/checkbox.jsx';
 
 const fmtDate = (iso) => {
   const d = new Date(iso);
@@ -17,7 +16,7 @@ const fmtSize = (b) => {
   return `${(b / 1048576).toFixed(1)} MB`;
 };
 
-export default function EmailRow({ email: initial, onRemove, selected, onToggleSelect, focused, onOpen }) {
+export default function EmailRow({ email: initial, onRemove, selected, onToggleSelect, focused }) {
   const [email, setEmail] = useState(initial);
   const [acting, setActing] = useState(false);
 
@@ -70,16 +69,12 @@ export default function EmailRow({ email: initial, onRemove, selected, onToggleS
   return (
     <tr
       className={`email-row${email.isUnread ? ' email-row--unread' : ''}${acting ? ' email-row--acting' : ''}${focused ? ' email-row--focused' : ''}`}
-      onClick={() => onOpen ? onOpen(email) : openInGmail()}
+      onClick={openInGmail}
-      title={onOpen ? 'Open' : 'Open in Gmail'}
+      title="Open in Gmail"
     >
       {onToggleSelect && (
         <td className="el-select" onClick={(e) => e.stopPropagation()}>
-          <Checkbox
+          <input type="checkbox" checked={!!selected} onChange={() => onToggleSelect(email.id)} />
-            checked={!!selected}
-            onCheckedChange={() => onToggleSelect(email.id)}
-            aria-label={selected ? 'Deselect email' : 'Select email'}
-          />
         </td>
       )}
       <td className="el-unread">{email.isUnread && <span className="unread-dot" />}</td>
@@ -88,7 +83,7 @@ export default function EmailRow({ email: initial, onRemove, selected, onToggleS
       </td>
       <td className="el-subject">
         <span className="el-subj-text">{email.subject || '(no subject)'}</span>
-        {email.snippet && <span className="el-snippet">{email.snippet}</span>}
+        {email.snippet && <span className="el-snippet"> — {email.snippet}</span>}
       </td>
       <td className="el-meta">
         {email.hasAttachments && <span className="el-attach" title="Has attachment">📎</span>}
@@ -118,11 +113,6 @@ export default function EmailRow({ email: initial, onRemove, selected, onToggleS
             disabled={email._unsubDone}
           >{email._unsubDone ? '✓' : '✉✕'}</button>
         )}
-        <button
-          className="action-btn"
-          title="Open in Gmail"
-          onClick={(e) => { e.stopPropagation(); openInGmail(); }}
-        >↗</button>
         <button
           className="action-btn action-btn--danger"
           title="Move to trash"

frontend/src/components/ui/checkbox.jsx

@@ -1,43 +0,0 @@
-import { forwardRef } from 'react';
-import * as CheckboxPrimitive from '@radix-ui/react-checkbox';
-import { Check } from 'lucide-react';
-import { cn } from '../../lib/utils.js';
-
-/**
- * Accessible, design-token styled checkbox.
- * Wraps Radix Checkbox so it is keyboard-accessible with a visible focus ring.
- * Accepts `checked`, `onCheckedChange` (Radix) and, for convenience, `onChange`
- * (called with a synthetic-ish `{ target: { checked } }`) so it can drop into
- * places that previously used a bare <input type="checkbox">.
- */
-const Checkbox = forwardRef(function Checkbox(
-  { className, onCheckedChange, onChange, ...props },
-  ref
-) {
-  const handleCheckedChange = (checked) => {
-    onCheckedChange?.(checked);
-    onChange?.({ target: { checked } });
-  };
-
-  return (
-    <CheckboxPrimitive.Root
-      ref={ref}
-      onCheckedChange={handleCheckedChange}
-      className={cn(
-        'peer inline-flex h-4 w-4 shrink-0 items-center justify-center rounded-[4px] border border-border bg-card transition-colors',
-        'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1 focus-visible:ring-offset-background',
-        'hover:border-primary/60',
-        'disabled:cursor-not-allowed disabled:opacity-50',
-        'data-[state=checked]:border-primary data-[state=checked]:bg-primary data-[state=checked]:text-primary-foreground',
-        className
-      )}
-      {...props}
-    >
-      <CheckboxPrimitive.Indicator className="flex items-center justify-center text-current">
-        <Check className="h-3 w-3" strokeWidth={3} />
-      </CheckboxPrimitive.Indicator>
-    </CheckboxPrimitive.Root>
-  );
-});
-
-export { Checkbox };

frontend/src/components/ui/index.js

@@ -2,7 +2,6 @@
 export { Button, buttonVariants } from './button.jsx';
 export { Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter } from './card.jsx';
 export { Badge, badgeVariants } from './badge.jsx';
-export { Checkbox } from './checkbox.jsx';
 export { Input, Textarea } from './input.jsx';
 export { Switch } from './switch.jsx';
 export { Separator } from './separator.jsx';

frontend/src/components/widgets.jsx

@@ -1,13 +1,16 @@
 import { useEffect, useState } from 'react';
 import { useNavigate } from 'react-router-dom';
-import { Bar, Line, Doughnut } from 'react-chartjs-2';
+import { Line, Doughnut } from 'react-chartjs-2';
+import { Inbox } from 'lucide-react';
 import { AnalyticsApi } from '../api/client.js';
+import { Skeleton } from './ui/skeleton.jsx';
+import { EmptyState } from './ui/misc.jsx';
 import {
-  Chart as ChartJS, CategoryScale, LinearScale, BarElement, PointElement,
+  Chart as ChartJS, CategoryScale, LinearScale, PointElement,
   LineElement, ArcElement, Tooltip, Legend
 } from 'chart.js';
 
-ChartJS.register(CategoryScale, LinearScale, BarElement, PointElement, LineElement, ArcElement, Tooltip, Legend);
+ChartJS.register(CategoryScale, LinearScale, PointElement, LineElement, ArcElement, Tooltip, Legend);
 
 const fmtBytes = (b) => {
   if (!b) return '0 B';
@@ -77,32 +80,6 @@ export function VolumeWidget({ volume }) {
   );
 }
 
-export function HeatmapWidget({ heatmap }) {
-  if (!heatmap) return <Empty />;
-  const days = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'];
-  const max = Math.max(1, ...heatmap.map((c) => c.count));
-  const grid = {};
-  heatmap.forEach((c) => { grid[`${c.dayOfWeek}-${c.hour}`] = c.count; });
-  return (
-    <div className="widget">
-      <h3>Activity Heatmap</h3>
-      <div className="heatmap">
-        {days.map((d, dow) => (
-          <div className="hm-row" key={dow}>
-            <span className="hm-day">{d}</span>
-            {Array.from({ length: 24 }, (_, h) => {
-              const v = grid[`${dow}-${h}`] || 0;
-              return <span key={h} className="hm-cell" style={{ opacity: 0.1 + 0.9 * (v / max) }} title={`${d} ${h}:00 — ${v}`} />;
-            })}
-          </div>
-        ))}
-      </div>
-    </div>
-  );
-}
-
-const DOW = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'];
-
 // Maps EmailCategory enum name → folder slug or search query
 const CAT_SLUG = {
   Finance:          '/app/folder/finance',
@@ -135,41 +112,64 @@ const CAT_SLUG = {
   Unknown:          '/app/folder/allmail',
 };
 
-export function CategoryHeatmapWidget() {
+// "Emails by Category" — ranked horizontal bar list. Aggregates the
+// category×day-of-week cells into per-category totals; each bar links to
+// that category's folder via CAT_SLUG.
+export function CategoryBreakdownWidget() {
   const [cells, setCells] = useState(null);
   const navigate = useNavigate();
   useEffect(() => { AnalyticsApi.categoryHeatmap().then(setCells).catch(() => setCells([])); }, []);
 
-  if (!cells) return <div className="widget"><div className="muted">Loading…</div></div>;
+  if (!cells) {
-  if (cells.length === 0) return <div className="widget"><h3>Category Heatmap</h3><div className="muted">No data yet — run a sync.</div></div>;
+    return (
+      <div className="widget">
+        <h3>Emails by Category</h3>
+        <div className="cat-bars">
+          {Array.from({ length: 6 }, (_, i) => <Skeleton key={i} className="h-6 w-full" />)}
+        </div>
+      </div>
+    );
+  }
 
-  const categories = [...new Set(cells.map((c) => c.category))].sort();
+  const totals = {};
-  const max = Math.max(1, ...cells.map((c) => c.count));
+  cells.forEach((c) => { totals[c.category] = (totals[c.category] || 0) + c.count; });
-  const grid = {};
+  const ranked = Object.entries(totals)
-  cells.forEach((c) => { grid[`${c.category}-${c.dayOfWeek}`] = c.count; });
+    .map(([category, count]) => ({ category, count }))
+    .sort((a, b) => b.count - a.count)
+    .slice(0, 8);
+
+  if (ranked.length === 0) {
+    return (
+      <div className="widget">
+        <h3>Emails by Category</h3>
+        <EmptyState icon={Inbox} title="No data yet — run a sync" description="Category totals appear once your inbox has been synced." />
+      </div>
+    );
+  }
+
+  const max = Math.max(1, ...ranked.map((r) => r.count));
 
   return (
     <div className="widget">
-      <h3>Category Heatmap</h3>
+      <h3>Emails by Category</h3>
-      <div className="cat-heatmap">
+      <div className="cat-bars">
-        <div className="chm-row chm-head">
+        {ranked.map(({ category, count }) => {
-          <span className="chm-label" />
+          const dest = CAT_SLUG[category];
-          {DOW.map((d) => <span key={d} className="chm-col">{d}</span>)}
-        </div>
-        {categories.map((cat) => {
-          const dest = CAT_SLUG[cat];
           return (
-            <div className="chm-row" key={cat}>
+            <button
-              <span
+              type="button"
-                className={`chm-label${dest ? ' chm-label--link' : ''}`}
+              className={`cat-bar${dest ? ' cat-bar--link' : ''}`}
-                title={dest ? `View ${cat} emails` : cat}
+              key={category}
+              disabled={!dest}
+              title={dest ? `View ${category} emails` : category}
               onClick={dest ? () => navigate(dest) : undefined}
-              >{cat}</span>
+            >
-              {DOW.map((_, dow) => {
+              <span className="cat-bar-label">{category}</span>
-                const v = grid[`${cat}-${dow}`] || 0;
+              <span className="cat-bar-track">
-                return <span key={dow} className="chm-cell" style={{ opacity: 0.12 + 0.88 * (v / max) }} title={`${cat} · ${DOW[dow]} — ${v}`}>{v || ''}</span>;
+                <span className="cat-bar-fill" style={{ width: `${(count / max) * 100}%` }} />
-              })}
+              </span>
-            </div>
+              <span className="cat-bar-count">{count.toLocaleString()}</span>
+            </button>
           );
         })}
       </div>
@@ -196,4 +196,10 @@ export function StorageWidget({ bytes }) {
   return <StatCard label="Estimated Storage" value={fmtBytes(bytes)} />;
 }
 
-function Empty() { return <div className="widget"><div className="muted">No data yet — run a sync.</div></div>; }
+function Empty() {
+  return (
+    <div className="widget">
+      <EmptyState icon={Inbox} title="No data yet — run a sync" description="This widget populates after your inbox has been synced." />
+    </div>
+  );
+}

frontend/src/pages/Dashboard.jsx

@@ -6,8 +6,9 @@ import { AnalyticsApi, LayoutApi, ExportApi, SyncApi } from '../api/client.js';
 import SyncSplash from '../components/SyncSplash.jsx';
 import {
   HealthWidget, StatCard, TopSendersWidget, VolumeWidget,
-  CategoryHeatmapWidget, AttachmentsWidget, StorageWidget
+  CategoryBreakdownWidget, AttachmentsWidget, StorageWidget
 } from '../components/widgets.jsx';
+import { Skeleton } from '../components/ui/skeleton.jsx';
 
 // Default grid geometry; overridden by the user's saved layout.
 const DEFAULT_LAYOUT = [
@@ -17,12 +18,23 @@ const DEFAULT_LAYOUT = [
   { i: 'storage', x: 7, y: 0, w: 2, h: 2 },
   { i: 'top-senders', x: 3, y: 2, w: 3, h: 5 },
   { i: 'volume', x: 6, y: 2, w: 6, h: 4 },
-  { i: 'category-heatmap', x: 0, y: 5, w: 6, h: 5 },
+  { i: 'category-breakdown', x: 0, y: 5, w: 6, h: 5 },
   { i: 'attachments', x: 6, y: 6, w: 4, h: 4 },
 ];
 
 const ALL_WIDGETS = DEFAULT_LAYOUT.map((l) => l.i);
 
+function WidgetSkeleton() {
+  return (
+    <div className="widget">
+      <Skeleton className="mb-3 h-4 w-1/3" />
+      <Skeleton className="mb-2 h-3 w-full" />
+      <Skeleton className="mb-2 h-3 w-5/6" />
+      <Skeleton className="h-3 w-2/3" />
+    </div>
+  );
+}
+
 export default function Dashboard() {
   const [data, setData] = useState(null);
   const [layout, setLayout] = useState(DEFAULT_LAYOUT);
@@ -87,15 +99,18 @@ export default function Dashboard() {
   const visibleLayout = useMemo(() => layout.filter((l) => !hidden.includes(l.i)), [layout, hidden]);
 
   const render = (key) => {
+    // category-breakdown self-fetches, so it renders regardless of dashboard load state.
+    if (key === 'category-breakdown') return <CategoryBreakdownWidget />;
+    // While the dashboard payload loads, show a skeleton placeholder per widget.
+    if (!data) return <WidgetSkeleton />;
     switch (key) {
-      case 'inbox-health': return <HealthWidget health={data?.health} />;
+      case 'inbox-health': return <HealthWidget health={data.health} />;
-      case 'total-emails': return <StatCard label="Total Emails" value={(data?.totalEmails ?? 0).toLocaleString()} to="/app/folder/allmail" />;
+      case 'total-emails': return <StatCard label="Total Emails" value={(data.totalEmails ?? 0).toLocaleString()} to="/app/folder/allmail" />;
-      case 'unread-emails': return <StatCard label="Unread" value={(data?.unreadEmails ?? 0).toLocaleString()} to="/app/folder/unread" />;
+      case 'unread-emails': return <StatCard label="Unread" value={(data.unreadEmails ?? 0).toLocaleString()} to="/app/folder/unread" />;
-      case 'storage': return <StorageWidget bytes={data?.storageEstimateBytes} />;
+      case 'storage': return <StorageWidget bytes={data.storageEstimateBytes} />;
-      case 'top-senders': return <TopSendersWidget senders={data?.topSenders} />;
+      case 'top-senders': return <TopSendersWidget senders={data.topSenders} />;
-      case 'volume': return <VolumeWidget volume={data?.volumeOverTime} />;
+      case 'volume': return <VolumeWidget volume={data.volumeOverTime} />;
-      case 'category-heatmap': return <CategoryHeatmapWidget />;
+      case 'attachments': return <AttachmentsWidget attachments={data.attachmentBreakdown} />;
-      case 'attachments': return <AttachmentsWidget attachments={data?.attachmentBreakdown} />;
       default: return null;
     }
   };

frontend/src/styles.css

@@ -115,8 +115,6 @@ button:disabled { opacity: 0.5; cursor: default; }
 .widget--link:hover { border-color: var(--accent); }
 .mini-row--link { cursor: pointer; }
 .mini-row--link:hover td { color: var(--accent); }
-.chm-label--link { cursor: pointer; text-decoration: underline dotted; }
-.chm-label--link:hover { color: var(--accent); }
 .widget canvas { flex: 1; min-height: 0; }
 
 .stat { align-items: flex-start; justify-content: center; }
@@ -135,17 +133,21 @@ table.grid th, table.grid td { padding: 8px; border-bottom: 1px solid #2c3550; t
 .num { text-align: right; }
 .muted { color: var(--muted); font-size: 12px; }
 
-.heatmap { display: flex; flex-direction: column; gap: 2px; }
+/* Emails by Category — ranked horizontal bars */
-.hm-row { display: flex; align-items: center; gap: 2px; }
+.cat-bars { display: flex; flex-direction: column; gap: 6px; overflow: auto; }
-.hm-day { width: 30px; font-size: 10px; color: var(--muted); }
+.cat-bar {
-.hm-cell { width: 10px; height: 10px; background: var(--accent); border-radius: 2px; }
+  display: grid; grid-template-columns: 92px 1fr 40px; gap: 8px; align-items: center;
-
+  width: 100%; padding: 3px 4px; margin: 0; border: none; background: transparent;
-/* Category heatmap */
+  border-radius: 6px; text-align: left; font: inherit; color: inherit;
-.cat-heatmap { display: flex; flex-direction: column; gap: 3px; overflow: auto; }
+}
-.chm-row { display: grid; grid-template-columns: 92px repeat(7, 1fr); gap: 3px; align-items: stretch; }
+.cat-bar--link { cursor: pointer; }
-.chm-head .chm-col { font-size: 10px; color: var(--muted); text-align: center; }
+.cat-bar--link:hover { background: rgba(255, 255, 255, 0.04); }
-.chm-label { font-size: 11px; color: var(--muted); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.cat-bar:disabled { cursor: default; }
-.chm-cell { background: var(--accent); border-radius: 3px; min-height: 22px; display: flex; align-items: center; justify-content: center; font-size: 10px; color: #fff; }
+.cat-bar-label { font-size: 11px; color: var(--muted); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.cat-bar-track { height: 14px; background: rgba(255, 255, 255, 0.06); border-radius: 4px; overflow: hidden; }
+.cat-bar-fill { display: block; height: 100%; background: var(--accent); border-radius: 4px; min-width: 2px; }
+.cat-bar-count { font-size: 11px; color: var(--muted); text-align: right; font-variant-numeric: tabular-nums; }
+.cat-bar--link:hover .cat-bar-label { color: var(--accent); }
 
 /* react-grid-layout resize handle — make it clearly visible on the dark theme */
 .react-resizable-handle {
@@ -294,57 +296,32 @@ input, select { background: var(--panel-2); border: 1px solid #2c3550; color: va
 .fv-error { color: var(--danger); font-size: 14px; padding: 12px 0; }
 
 .email-list { width: 100%; border-collapse: collapse; font-size: 13px; }
-.email-row {
+.email-row { border-bottom: 1px solid #2c3550; cursor: pointer; }
-  height: 44px;
-  border-bottom: 1px solid #2c3550;
-  cursor: pointer;
-  transition: background 0.1s ease;
-}
-.email-row > td { padding-top: 0; padding-bottom: 0; vertical-align: middle; }
-/* Single, consistent hover state for the whole row. */
 .email-row:hover { background: var(--panel); }
-/* Unread: prominent subject, keep sender readable but not shouty. */
+.email-row--unread .el-sender,
 .email-row--unread .el-subj-text { font-weight: 700; color: var(--text); }
-.email-row--unread .el-sender { font-weight: 600; color: var(--text); }
 
-.el-select { width: 34px; padding: 0 4px 0 10px; text-align: center; }
+.el-unread { width: 14px; padding: 10px 4px 10px 0; }
-.el-select > * { vertical-align: middle; }
-
-.el-unread { width: 14px; padding: 0 4px 0 0; text-align: center; }
 .unread-dot { display: inline-block; width: 7px; height: 7px; border-radius: 50%; background: var(--accent); }
-
+.el-sender { width: 180px; padding: 10px 12px 10px 4px; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; color: var(--muted); }
-/* Sender: secondary in the hierarchy — muted by default. */
+.el-subject { padding: 10px 8px; overflow: hidden; }
-.el-sender {
-  width: 180px; padding: 0 12px 0 4px;
-  white-space: nowrap; overflow: hidden; text-overflow: ellipsis;
-  color: var(--muted); font-size: 12.5px;
-}
-
-/* Subject + snippet share one line: subject prominent, snippet muted. */
-.el-subject { padding: 0 8px; overflow: hidden; max-width: 0; white-space: nowrap; text-overflow: ellipsis; }
 .el-subj-text { color: var(--text); }
-.el-snippet {
+.el-snippet { color: var(--muted); }
-  color: var(--muted); font-size: 12.5px;
+.el-meta { width: 80px; padding: 10px 8px; text-align: right; white-space: nowrap; }
-}
-.el-snippet::before { content: '—'; margin: 0 6px; opacity: 0.55; }
-
-.el-meta { width: 80px; padding: 0 8px; text-align: right; white-space: nowrap; }
 .el-attach { margin-right: 4px; font-size: 12px; }
 .el-size { font-size: 11px; color: var(--muted); }
-.el-date { width: 70px; padding: 0 0 0 8px; text-align: right; color: var(--muted); white-space: nowrap; font-size: 12px; }
+.el-date { width: 70px; padding: 10px 0 10px 8px; text-align: right; color: var(--muted); white-space: nowrap; font-size: 12px; }
 
-.el-actions { width: 96px; padding: 0 6px; text-align: right; white-space: nowrap; }
+.el-actions { width: 80px; padding: 0 6px; text-align: right; white-space: nowrap; }
 .action-btn {
-  background: none; border: none; padding: 4px 5px; cursor: pointer;
+  background: none; border: none; padding: 3px 4px; cursor: pointer;
-  font-size: 13px; line-height: 1; opacity: 0;
+  font-size: 13px; opacity: 0; transition: opacity 0.1s, color 0.1s;
-  transition: opacity 0.1s ease, color 0.1s ease, background 0.1s ease;
   border-radius: 4px; color: var(--muted);
 }
-.action-btn:hover { background: var(--panel-2); color: var(--text); opacity: 1 !important; }
+.action-btn:hover { background: var(--panel-2); opacity: 1 !important; }
 .action-btn--active { opacity: 1 !important; }
 .action-btn--danger:hover { color: var(--danger); }
-.email-row:hover .action-btn { opacity: 0.65; }
+.email-row:hover .action-btn { opacity: 0.6; }
-.action-btn:focus-visible { opacity: 1 !important; outline: 2px solid var(--accent); outline-offset: 1px; }
 .email-row--acting { opacity: 0.6; pointer-events: none; }
 .action-btn--unsub { font-size: 11px; }
 .action-btn--done { opacity: 1 !important; color: var(--ok); }
@@ -428,6 +405,7 @@ input, select { background: var(--panel-2); border: 1px solid #2c3550; color: va
 }
 .bulk-btn:hover { border-color: var(--accent); }
 .bulk-btn--danger:hover { border-color: var(--danger); color: var(--danger); }
+.el-select { width: 28px; text-align: center; }
 
 /* ── Keyboard shortcut help ──────────────────────────────────────────────── */
 .kbd-hint { position: fixed; bottom: 14px; right: 14px; font-size: 11px; color: var(--muted); background: var(--panel); border: 1px solid #2c3550; border-radius: 6px; padding: 4px 10px; opacity: 0.7; }