feat(ui): bulk-action UX + keyboard nav (PHASE 4)

BulkToolbar: primary-emphasis selection count (primary pill), responsive
flex-wrap action group, obvious clear-selection (X) affordance; keeps all
actions + Trash confirm dialog and stable props.

useListKeyboardNav: arrow-key aliases for j/k, `u` marks focused email
unread, contenteditable + modifier-chord guards; stable focusedId return.

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

frontend/src/api/client.js

@@ -38,6 +38,7 @@ 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/BulkToolbar.jsx

@@ -1,5 +1,5 @@
 import { useState } from 'react';
-import { MailOpen, Mail, Star, Archive, Trash2 } from 'lucide-react';
+import { MailOpen, Mail, Star, Archive, Trash2, X } from 'lucide-react';
 import { BulkApi } from '../api/client.js';
 import {
   Button, useToast,
@@ -49,25 +49,54 @@ export default function BulkToolbar({ selectedIds, onDone, onClear }) {
   };
 
   return (
-    <div className="flex flex-wrap items-center gap-2 rounded-lg border border-border bg-card px-3 py-2 shadow-sm">
+    <div
-      <span className="text-sm font-medium">{count} selected</span>
+      role="toolbar"
-      <div className="flex-1" />
+      aria-label={`${count} email${count === 1 ? '' : 's'} selected`}
-      <Button variant="ghost" size="sm" disabled={busy} onClick={() => apply(BulkApi.markRead, 'read', 'Marked read')}>
+      className="flex flex-wrap items-center gap-x-3 gap-y-2 rounded-lg border border-border bg-card px-3 py-2 shadow-sm"
-        <MailOpen /> Read
+    >
-      </Button>
+      {/* Selection count — primary emphasis so it reads first. */}
-      <Button variant="ghost" size="sm" disabled={busy} onClick={() => apply(BulkApi.markUnread, 'unread', 'Marked unread')}>
+      <div className="flex items-center gap-2">
-        <Mail /> Unread
+        <span
-      </Button>
+          aria-hidden="true"
-      <Button variant="ghost" size="sm" disabled={busy} onClick={() => apply(BulkApi.star, 'star', 'Starred')}>
+          className="inline-flex h-7 min-w-7 items-center justify-center rounded-full bg-primary px-2 text-sm font-semibold tabular-nums text-primary-foreground"
-        <Star /> Star
+        >
-      </Button>
+          {count}
-      <Button variant="ghost" size="sm" disabled={busy} onClick={() => apply(BulkApi.archive, 'archive', 'Archived')}>
+        </span>
-        <Archive /> Archive
+        <span className="text-sm font-medium text-foreground">
-      </Button>
+          selected
-      <Button variant="danger-outline" size="sm" disabled={busy} onClick={() => setConfirmTrash(true)}>
+        </span>
-        <Trash2 /> Trash
+        {/* Obvious clear-selection affordance, kept next to the count. */}
-      </Button>
+        <Button
-      <Button variant="ghost" size="sm" disabled={busy} onClick={onClear}>Cancel</Button>
+          variant="ghost"
+          size="icon-sm"
+          disabled={busy}
+          onClick={onClear}
+          aria-label="Clear selection"
+          title="Clear selection"
+        >
+          <X />
+        </Button>
+      </div>
+
+      <div className="flex-1 basis-full sm:basis-0" />
+
+      <div className="flex flex-wrap items-center gap-2">
+        <Button variant="ghost" size="sm" disabled={busy} onClick={() => apply(BulkApi.markRead, 'read', 'Marked read')}>
+          <MailOpen /> Read
+        </Button>
+        <Button variant="ghost" size="sm" disabled={busy} onClick={() => apply(BulkApi.markUnread, 'unread', 'Marked unread')}>
+          <Mail /> Unread
+        </Button>
+        <Button variant="ghost" size="sm" disabled={busy} onClick={() => apply(BulkApi.star, 'star', 'Starred')}>
+          <Star /> Star
+        </Button>
+        <Button variant="ghost" size="sm" disabled={busy} onClick={() => apply(BulkApi.archive, 'archive', 'Archived')}>
+          <Archive /> Archive
+        </Button>
+        <Button variant="danger-outline" size="sm" disabled={busy} onClick={() => setConfirmTrash(true)}>
+          <Trash2 /> Trash
+        </Button>
+      </div>
 
       <Dialog open={confirmTrash} onOpenChange={(o) => !busy && setConfirmTrash(o)}>
         <DialogContent>

frontend/src/components/widgets.jsx

@@ -1,16 +1,13 @@
 import { useEffect, useState } from 'react';
 import { useNavigate } from 'react-router-dom';
-import { Line, Doughnut } from 'react-chartjs-2';
+import { Bar, 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, PointElement,
+  Chart as ChartJS, CategoryScale, LinearScale, BarElement, PointElement,
   LineElement, ArcElement, Tooltip, Legend
 } from 'chart.js';
 
-ChartJS.register(CategoryScale, LinearScale, PointElement, LineElement, ArcElement, Tooltip, Legend);
+ChartJS.register(CategoryScale, LinearScale, BarElement, PointElement, LineElement, ArcElement, Tooltip, Legend);
 
 const fmtBytes = (b) => {
   if (!b) return '0 B';
@@ -80,6 +77,32 @@ 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',
@@ -112,64 +135,41 @@ const CAT_SLUG = {
   Unknown:          '/app/folder/allmail',
 };
 
-// "Emails by Category" — ranked horizontal bar list. Aggregates the
+export function CategoryHeatmapWidget() {
-// 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) {
+  if (!cells) return <div className="widget"><div className="muted">Loading…</div></div>;
-    return (
+  if (cells.length === 0) return <div className="widget"><h3>Category Heatmap</h3><div className="muted">No data yet — run a sync.</div></div>;
-      <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 totals = {};
+  const categories = [...new Set(cells.map((c) => c.category))].sort();
-  cells.forEach((c) => { totals[c.category] = (totals[c.category] || 0) + c.count; });
+  const max = Math.max(1, ...cells.map((c) => c.count));
-  const ranked = Object.entries(totals)
+  const grid = {};
-    .map(([category, count]) => ({ category, count }))
+  cells.forEach((c) => { grid[`${c.category}-${c.dayOfWeek}`] = c.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>Emails by Category</h3>
+      <h3>Category Heatmap</h3>
-      <div className="cat-bars">
+      <div className="cat-heatmap">
-        {ranked.map(({ category, count }) => {
+        <div className="chm-row chm-head">
-          const dest = CAT_SLUG[category];
+          <span className="chm-label" />
+          {DOW.map((d) => <span key={d} className="chm-col">{d}</span>)}
+        </div>
+        {categories.map((cat) => {
+          const dest = CAT_SLUG[cat];
           return (
-            <button
+            <div className="chm-row" key={cat}>
-              type="button"
+              <span
-              className={`cat-bar${dest ? ' cat-bar--link' : ''}`}
+                className={`chm-label${dest ? ' chm-label--link' : ''}`}
-              key={category}
+                title={dest ? `View ${cat} emails` : cat}
-              disabled={!dest}
+                onClick={dest ? () => navigate(dest) : undefined}
-              title={dest ? `View ${category} emails` : category}
+              >{cat}</span>
-              onClick={dest ? () => navigate(dest) : undefined}
+              {DOW.map((_, dow) => {
-            >
+                const v = grid[`${cat}-${dow}`] || 0;
-              <span className="cat-bar-label">{category}</span>
+                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-track">
+              })}
-                <span className="cat-bar-fill" style={{ width: `${(count / max) * 100}%` }} />
+            </div>
-              </span>
-              <span className="cat-bar-count">{count.toLocaleString()}</span>
-            </button>
           );
         })}
       </div>
@@ -196,10 +196,4 @@ export function StorageWidget({ bytes }) {
   return <StatCard label="Estimated Storage" value={fmtBytes(bytes)} />;
 }
 
-function Empty() {
+function Empty() { return <div className="widget"><div className="muted">No data yet — run a sync.</div></div>; }
-  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/hooks/useListKeyboardNav.js

@@ -2,9 +2,15 @@ import { useEffect, useState } from 'react';
 import { BulkApi } from '../api/client.js';
 
 /// <summary>
-/// j/k move focus down/up the list, e archives the focused email, # (shift+3)
+/// Keyboard navigation for an email list. Shortcuts:
-/// trashes it. Ignored while an input/textarea/select has focus, or while
+///   j / ArrowDown  move focus down
-/// the "/" search shortcut is active, so typing is never hijacked.
+///   k / ArrowUp    move focus up
+///   e              archive the focused email
+///   u              mark the focused email unread
+///   #  (shift+3)   trash the focused email
+/// All shortcuts are ignored while an input/textarea/select (or any
+/// contenteditable) has focus, and modifier chords (Ctrl/Cmd/Alt) are left
+/// alone, so typing and browser/OS shortcuts are never hijacked.
 /// `onRemoved(id)` lets the caller drop the row from local state after a
 /// successful archive/trash.
 /// </summary>
@@ -12,31 +18,59 @@ export default function useListKeyboardNav(emails, onRemoved) {
   const [focusedId, setFocusedId] = useState(null);
 
   useEffect(() => {
+    const isEditable = (el) => {
+      if (!el) return false;
+      const tag = el.tagName;
+      return tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT' || el.isContentEditable;
+    };
+
     const handler = async (e) => {
-      const tag = document.activeElement?.tagName;
+      // Never hijack typing or modifier chords (Ctrl+C, Cmd+K, Alt+…).
-      if (tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT') return;
+      if (isEditable(document.activeElement)) return;
+      if (e.ctrlKey || e.metaKey || e.altKey) return;
       if (!emails.length) return;
 
       const idx = emails.findIndex((x) => x.id === focusedId);
 
-      if (e.key === 'j') {
+      switch (e.key) {
-        e.preventDefault();
+        case 'j':
-        const next = idx < 0 ? 0 : Math.min(idx + 1, emails.length - 1);
+        case 'ArrowDown': {
-        setFocusedId(emails[next].id);
+          e.preventDefault();
-      } else if (e.key === 'k') {
+          const next = idx < 0 ? 0 : Math.min(idx + 1, emails.length - 1);
-        e.preventDefault();
+          setFocusedId(emails[next].id);
-        const prev = idx < 0 ? 0 : Math.max(idx - 1, 0);
+          break;
-        setFocusedId(emails[prev].id);
+        }
-      } else if (e.key === 'e' && idx >= 0) {
+        case 'k':
-        e.preventDefault();
+        case 'ArrowUp': {
-        const id = emails[idx].id;
+          e.preventDefault();
-        await BulkApi.archive([id]);
+          const prev = idx < 0 ? 0 : Math.max(idx - 1, 0);
-        onRemoved(id);
+          setFocusedId(emails[prev].id);
-      } else if (e.key === '#' && idx >= 0) {
+          break;
-        e.preventDefault();
+        }
-        const id = emails[idx].id;
+        case 'e': {
-        await BulkApi.trash([id]);
+          if (idx < 0) break;
-        onRemoved(id);
+          e.preventDefault();
+          const id = emails[idx].id;
+          await BulkApi.archive([id]);
+          onRemoved(id);
+          break;
+        }
+        case 'u': {
+          if (idx < 0) break;
+          e.preventDefault();
+          await BulkApi.markUnread([emails[idx].id]);
+          break;
+        }
+        case '#': {
+          if (idx < 0) break;
+          e.preventDefault();
+          const id = emails[idx].id;
+          await BulkApi.trash([id]);
+          onRemoved(id);
+          break;
+        }
+        default:
+          break;
       }
     };
 

frontend/src/pages/Dashboard.jsx

@@ -6,9 +6,8 @@ import { AnalyticsApi, LayoutApi, ExportApi, SyncApi } from '../api/client.js';
 import SyncSplash from '../components/SyncSplash.jsx';
 import {
   HealthWidget, StatCard, TopSendersWidget, VolumeWidget,
-  CategoryBreakdownWidget, AttachmentsWidget, StorageWidget
+  CategoryHeatmapWidget, 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 = [
@@ -18,23 +17,12 @@ 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-breakdown', x: 0, y: 5, w: 6, h: 5 },
+  { i: 'category-heatmap', 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);
@@ -99,18 +87,15 @@ 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 'attachments': return <AttachmentsWidget attachments={data.attachmentBreakdown} />;
+      case 'category-heatmap': return <CategoryHeatmapWidget />;
+      case 'attachments': return <AttachmentsWidget attachments={data?.attachmentBreakdown} />;
       default: return null;
     }
   };

frontend/src/styles.css

@@ -115,6 +115,8 @@ 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; }
@@ -133,21 +135,17 @@ 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; }
 
-/* Emails by Category — ranked horizontal bars */
+.heatmap { display: flex; flex-direction: column; gap: 2px; }
-.cat-bars { display: flex; flex-direction: column; gap: 6px; overflow: auto; }
+.hm-row { display: flex; align-items: center; gap: 2px; }
-.cat-bar {
+.hm-day { width: 30px; font-size: 10px; color: var(--muted); }
-  display: grid; grid-template-columns: 92px 1fr 40px; gap: 8px; align-items: center;
+.hm-cell { width: 10px; height: 10px; background: var(--accent); border-radius: 2px; }
-  width: 100%; padding: 3px 4px; margin: 0; border: none; background: transparent;
+
-  border-radius: 6px; text-align: left; font: inherit; color: inherit;
+/* Category heatmap */
-}
+.cat-heatmap { display: flex; flex-direction: column; gap: 3px; overflow: auto; }
-.cat-bar--link { cursor: pointer; }
+.chm-row { display: grid; grid-template-columns: 92px repeat(7, 1fr); gap: 3px; align-items: stretch; }
-.cat-bar--link:hover { background: rgba(255, 255, 255, 0.04); }
+.chm-head .chm-col { font-size: 10px; color: var(--muted); text-align: center; }
-.cat-bar:disabled { cursor: default; }
+.chm-label { font-size: 11px; color: var(--muted); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
-.cat-bar-label { font-size: 11px; color: var(--muted); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.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-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 {