fix(analytics): fix 8 frontend UX issues — routing, accessibility, error states, sort indicators

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

frontend/src/components/analytics/CoverageHeatmap.tsx

@@ -18,6 +18,18 @@ function getCellStyle(value: number, thresholds: { green: number; amber: number
   return 'bg-rose-500/10 text-rose-500'
 }
 
+function getCellTitle(value: number, label: string, thresholds: { green: number; amber: number }, inverse?: boolean): string {
+  const pct = (value * 100).toFixed(1)
+  if (inverse) {
+    if (value <= thresholds.green) return `${label}: ${pct}% (Good — below ${(thresholds.green * 100).toFixed(0)}%)`
+    if (value <= thresholds.amber) return `${label}: ${pct}% (Needs Improvement — below ${(thresholds.amber * 100).toFixed(0)}%)`
+    return `${label}: ${pct}% (Critical — above ${(thresholds.amber * 100).toFixed(0)}%)`
+  }
+  if (value >= thresholds.green) return `${label}: ${pct}% (Good — above ${(thresholds.green * 100).toFixed(0)}%)`
+  if (value >= thresholds.amber) return `${label}: ${pct}% (Needs Improvement — above ${(thresholds.amber * 100).toFixed(0)}%)`
+  return `${label}: ${pct}% (Critical — below ${(thresholds.amber * 100).toFixed(0)}%)`
+}
+
 function getFlowCountStyle(count: number) {
   if (count >= 5) return 'bg-emerald-400/10 text-emerald-400'
   if (count >= 1) return 'bg-amber-400/10 text-amber-400'
@@ -91,7 +103,10 @@ export default function CoverageHeatmap({ data }: CoverageHeatmapProps) {
                       Create Flow
                     </Link>
                   ) : (
-                    <span className={cn('inline-block rounded px-1.5 py-0.5 text-xs font-medium', getFlowCountStyle(row.flow_count))}>
+                    <span
+                      className={cn('inline-block rounded px-1.5 py-0.5 text-xs font-medium', getFlowCountStyle(row.flow_count))}
+                      title={`${row.flow_count} flow${row.flow_count !== 1 ? 's' : ''} — ${row.flow_count >= 5 ? 'Good' : row.flow_count >= 1 ? 'Needs Improvement' : 'Critical'}`}
+                    >
                       {row.flow_count}
                     </span>
                   )}
@@ -100,17 +115,26 @@ export default function CoverageHeatmap({ data }: CoverageHeatmapProps) {
                   {row.session_count}
                 </td>
                 <td className="px-3 py-2 text-sm text-right">
-                  <span className={cn('inline-block rounded px-1.5 py-0.5 text-xs font-medium', getCellStyle(row.resolution_rate, { green: 0.75, amber: 0.5 }))}>
+                  <span
+                    className={cn('inline-block rounded px-1.5 py-0.5 text-xs font-medium', getCellStyle(row.resolution_rate, { green: 0.75, amber: 0.5 }))}
+                    title={getCellTitle(row.resolution_rate, 'Resolution', { green: 0.75, amber: 0.5 })}
+                  >
                     {(row.resolution_rate * 100).toFixed(1)}%
                   </span>
                 </td>
                 <td className="px-3 py-2 text-sm text-right">
-                  <span className={cn('inline-block rounded px-1.5 py-0.5 text-xs font-medium', getCellStyle(row.escalation_rate, { green: 0.10, amber: 0.25 }, true))}>
+                  <span
+                    className={cn('inline-block rounded px-1.5 py-0.5 text-xs font-medium', getCellStyle(row.escalation_rate, { green: 0.10, amber: 0.25 }, true))}
+                    title={getCellTitle(row.escalation_rate, 'Escalation', { green: 0.10, amber: 0.25 }, true)}
+                  >
                     {(row.escalation_rate * 100).toFixed(1)}%
                   </span>
                 </td>
                 <td className="px-3 py-2 text-sm text-right">
-                  <span className={cn('inline-block rounded px-1.5 py-0.5 text-xs font-medium', getCellStyle(row.guided_rate, { green: 0.60, amber: 0.30 }))}>
+                  <span
+                    className={cn('inline-block rounded px-1.5 py-0.5 text-xs font-medium', getCellStyle(row.guided_rate, { green: 0.60, amber: 0.30 }))}
+                    title={getCellTitle(row.guided_rate, 'Guided', { green: 0.60, amber: 0.30 })}
+                  >
                     {(row.guided_rate * 100).toFixed(1)}%
                   </span>
                 </td>
@@ -128,6 +152,12 @@ export default function CoverageHeatmap({ data }: CoverageHeatmapProps) {
           )}
         </table>
       </div>
+
+      <div className="flex flex-wrap gap-4 mt-3 text-[0.625rem] font-label text-muted-foreground">
+        <span><span className="inline-block w-2 h-2 rounded-full bg-emerald-400 mr-1" />Good</span>
+        <span><span className="inline-block w-2 h-2 rounded-full bg-amber-400 mr-1" />Needs Improvement</span>
+        <span><span className="inline-block w-2 h-2 rounded-full bg-rose-500 mr-1" />Critical</span>
+      </div>
     </div>
   )
 }

frontend/src/components/analytics/FlowQualityTable.tsx

@@ -1,7 +1,8 @@
 import { useState, useMemo } from 'react'
 import { Link } from 'react-router-dom'
-import { ArrowUpDown } from 'lucide-react'
+import { ArrowUpDown, ArrowUp, ArrowDown, Info } from 'lucide-react'
 import { cn } from '@/lib/utils'
+import { getTreeEditorPath } from '@/lib/routing'
 import type { FlowQualityResponse, FlowQualityRow } from '@/types/flowpilot-analytics'
 
 interface FlowQualityTableProps {
@@ -113,21 +114,29 @@ export default function FlowQualityTable({ data }: FlowQualityTableProps) {
     )
   }
 
-  const columns: { key: SortColumn; label: string }[] = [
+  const columns: { key: SortColumn; label: string; title?: string }[] = [
     { key: 'name', label: 'Flow Name' },
     { key: 'usage_count', label: 'Usage' },
     { key: 'success_rate', label: 'Success Rate' },
     { key: 'last_matched_at', label: 'Last Used' },
     { key: 'avg_confidence', label: 'Avg Confidence' },
-    { key: 'quality_score', label: 'Quality Score' },
+    { key: 'quality_score', label: 'Quality Score', title: 'Combines success rate (50%), AI confidence (30%), and recent usage (20%)' },
   ]
 
   return (
     <div className="glass-card-static p-3 sm:p-5">
       <div className="mb-4">
-        <h3 className="font-heading text-sm font-semibold text-foreground">
+        <div className="flex items-center gap-2">
-          Flow Quality Scores
+          <h3 className="font-heading text-sm font-semibold text-foreground">
-        </h3>
+            Flow Quality Scores
+          </h3>
+          <span className="group relative">
+            <Info size={14} className="text-muted-foreground cursor-help" />
+            <div className="absolute bottom-full left-1/2 -translate-x-1/2 mb-2 w-64 p-2 rounded-lg bg-card border border-border text-xs text-muted-foreground opacity-0 group-hover:opacity-100 transition-opacity pointer-events-none z-10">
+              Quality score combines success rate (50%), AI confidence level (30%), and recent usage (20%). Higher is better.
+            </div>
+          </span>
+        </div>
         <p className="text-xs text-muted-foreground mt-1">
           Performance and usage metrics for your troubleshooting flows
         </p>
@@ -137,24 +146,31 @@ export default function FlowQualityTable({ data }: FlowQualityTableProps) {
         <table className="w-full text-sm">
           <thead>
             <tr className="border-b border-border">
-              {columns.map((col) => (
+              {columns.map((col) => {
-                <th
+                const isActive = sortCol === col.key
-                  key={col.key}
+                const SortIcon = isActive
-                  className="text-left py-2 px-2 font-label text-[0.625rem] uppercase tracking-[0.1em] text-muted-foreground cursor-pointer select-none hover:text-foreground transition-colors"
+                  ? sortDir === 'asc' ? ArrowUp : ArrowDown
-                  onClick={() => handleSort(col.key)}
+                  : ArrowUpDown
-                >
+                return (
-                  <span className="flex items-center gap-1">
+                  <th
-                    {col.label}
+                    key={col.key}
-                    <ArrowUpDown
+                    className="text-left py-2 px-2 font-label text-[0.625rem] uppercase tracking-[0.1em] text-muted-foreground cursor-pointer select-none hover:text-foreground transition-colors"
-                      size={10}
+                    onClick={() => handleSort(col.key)}
-                      className={cn(
+                    title={col.title}
-                        'transition-opacity',
+                  >
-                        sortCol === col.key ? 'opacity-100' : 'opacity-30',
+                    <span className="flex items-center gap-1">
-                      )}
+                      {col.label}
-                    />
+                      <SortIcon
-                  </span>
+                        size={10}
-                </th>
+                        className={cn(
-              ))}
+                          'transition-opacity',
+                          isActive ? 'opacity-100' : 'opacity-30',
+                        )}
+                      />
+                    </span>
+                  </th>
+                )
+              })}
             </tr>
           </thead>
           <tbody>
@@ -194,7 +210,7 @@ function FlowRow({
       <td className="py-2.5 px-2">
         <div className="flex items-center gap-2">
           <Link
-            to={`/trees/${flow.flow_id}/edit`}
+            to={getTreeEditorPath(flow.flow_id, flow.tree_type)}
             className="text-foreground hover:text-primary transition-colors font-medium truncate max-w-[200px]"
           >
             {flow.name}

frontend/src/components/analytics/PsaMetricsPanel.tsx

@@ -34,19 +34,19 @@ export default function PsaMetricsPanel({ data }: PsaMetricsPanelProps) {
       {/* Row 1 — Metric cards */}
       <div className="grid grid-cols-1 sm:grid-cols-3 gap-4">
         <div className="glass-card-static p-4">
-          <p className="text-gradient-brand font-heading text-2xl">{data.total_time_entries}</p>
+          <p className="font-label text-[0.625rem] uppercase tracking-[0.1em] text-[#5a6170]">Time Entries</p>
+          <p className="text-gradient-brand font-heading text-2xl mt-1">{data.total_time_entries}</p>
           <p className="text-xs text-muted-foreground mt-1">logged to PSA</p>
-          <p className="font-label text-[0.625rem] uppercase tracking-[0.1em] text-[#5a6170] mt-0.5">Time Entries</p>
         </div>
         <div className="glass-card-static p-4">
-          <p className="text-gradient-brand font-heading text-2xl">{data.total_hours_logged.toFixed(1)}</p>
+          <p className="font-label text-[0.625rem] uppercase tracking-[0.1em] text-[#5a6170]">Hours Logged</p>
+          <p className="text-gradient-brand font-heading text-2xl mt-1">{data.total_hours_logged.toFixed(1)}</p>
           <p className="text-xs text-muted-foreground mt-1">total hours tracked</p>
-          <p className="font-label text-[0.625rem] uppercase tracking-[0.1em] text-[#5a6170] mt-0.5">Hours Logged</p>
         </div>
         <div className="glass-card-static p-4">
-          <p className="text-gradient-brand font-heading text-2xl">{data.avg_hours_per_session.toFixed(2)}</p>
+          <p className="font-label text-[0.625rem] uppercase tracking-[0.1em] text-[#5a6170]">Avg Hours/Session</p>
+          <p className="text-gradient-brand font-heading text-2xl mt-1">{data.avg_hours_per_session.toFixed(2)}</p>
           <p className="text-xs text-muted-foreground mt-1">per resolved session</p>
-          <p className="font-label text-[0.625rem] uppercase tracking-[0.1em] text-[#5a6170] mt-0.5">Avg Hours/Session</p>
         </div>
       </div>
 

frontend/src/pages/FlowPilotAnalyticsPage.tsx

@@ -2,7 +2,7 @@ import { useState, useEffect, useRef } from 'react'
 import { Link } from 'react-router-dom'
 import {
   BarChart3, Clock, Star, CheckCircle2, ArrowUpRight,
-  AlertTriangle, Lightbulb, Loader2, Ticket,
+  AlertTriangle, Lightbulb, Loader2, Ticket, RotateCcw,
 } from 'lucide-react'
 import {
   AreaChart, Area, BarChart, Bar,
@@ -55,6 +55,12 @@ export default function FlowPilotAnalyticsPage() {
   const [psaData, setPsaData] = useState<EnhancedPsaMetrics | null>(null)
   const [psaLoading, setPsaLoading] = useState(false)
 
+  // Error states per tab
+  const [coverageError, setCoverageError] = useState(false)
+  const [qualityError, setQualityError] = useState(false)
+  const [psaError, setPsaError] = useState(false)
+  const [retryKey, setRetryKey] = useState(0)
+
   // Track which period each tab was loaded for
   const coveragePeriodRef = useRef<string | null>(null)
   const qualityPeriodRef = useRef<string | null>(null)
@@ -81,41 +87,59 @@ export default function FlowPilotAnalyticsPage() {
     setCoverageData(null)
     setQualityData(null)
     setPsaData(null)
+    setCoverageLoading(true)
+    setQualityLoading(true)
+    setPsaLoading(true)
+    setCoverageError(false)
+    setQualityError(false)
+    setPsaError(false)
   }, [period])
 
   // Lazy-load tab data on tab switch or period change
   useEffect(() => {
     if (activeTab === 'coverage' && coveragePeriodRef.current !== period) {
       setCoverageLoading(true)
+      setCoverageError(false)
       flowpilotAnalyticsApi.getCoverage(period)
         .then((data) => {
           setCoverageData(data)
           coveragePeriodRef.current = period
         })
-        .catch(() => toast.error('Failed to load coverage data'))
+        .catch(() => {
+          toast.error('Failed to load coverage data')
+          setCoverageError(true)
+        })
         .finally(() => setCoverageLoading(false))
     }
     if (activeTab === 'quality' && qualityPeriodRef.current !== period) {
       setQualityLoading(true)
+      setQualityError(false)
       flowpilotAnalyticsApi.getFlowQuality(period)
         .then((data) => {
           setQualityData(data)
           qualityPeriodRef.current = period
         })
-        .catch(() => toast.error('Failed to load flow quality data'))
+        .catch(() => {
+          toast.error('Failed to load flow quality data')
+          setQualityError(true)
+        })
         .finally(() => setQualityLoading(false))
     }
     if (activeTab === 'psa' && psaPeriodRef.current !== period) {
       setPsaLoading(true)
+      setPsaError(false)
       flowpilotAnalyticsApi.getPsaMetrics(period)
         .then((data) => {
           setPsaData(data)
           psaPeriodRef.current = period
         })
-        .catch(() => toast.error('Failed to load PSA metrics'))
+        .catch(() => {
+          toast.error('Failed to load PSA metrics')
+          setPsaError(true)
+        })
         .finally(() => setPsaLoading(false))
     }
-  }, [activeTab, period])
+  }, [activeTab, period, retryKey])
 
   if (loading) {
     return (
@@ -165,7 +189,7 @@ export default function FlowPilotAnalyticsPage() {
       </div>
 
       {/* Tab bar */}
-      <div className="flex gap-1 border-b border-border mb-6">
+      <div className="flex gap-1 border-b border-border">
         {TABS.map((tab) => (
           <button
             key={tab.id}
@@ -386,49 +410,43 @@ export default function FlowPilotAnalyticsPage() {
 
       {activeTab === 'coverage' && (
         <div>
-          {coverageLoading ? (
+          {coverageError ? (
+            <ErrorRetry label="coverage data" onRetry={() => { setCoverageError(false); coveragePeriodRef.current = null; setRetryKey((k) => k + 1) }} />
+          ) : coverageLoading ? (
             <div className="flex items-center justify-center min-h-[200px]">
               <Loader2 size={20} className="animate-spin text-muted-foreground" />
             </div>
           ) : coverageData ? (
             <CoverageHeatmap data={coverageData} />
-          ) : (
+          ) : null}
-            <div className="flex items-center justify-center min-h-[200px]">
-              <p className="text-sm text-muted-foreground">No coverage data available</p>
-            </div>
-          )}
         </div>
       )}
 
       {activeTab === 'quality' && (
         <div>
-          {qualityLoading ? (
+          {qualityError ? (
+            <ErrorRetry label="flow quality data" onRetry={() => { setQualityError(false); qualityPeriodRef.current = null; setRetryKey((k) => k + 1) }} />
+          ) : qualityLoading ? (
             <div className="flex items-center justify-center min-h-[200px]">
               <Loader2 size={20} className="animate-spin text-muted-foreground" />
             </div>
           ) : qualityData ? (
             <FlowQualityTable data={qualityData} />
-          ) : (
+          ) : null}
-            <div className="flex items-center justify-center min-h-[200px]">
-              <p className="text-sm text-muted-foreground">No flow quality data available</p>
-            </div>
-          )}
         </div>
       )}
 
       {activeTab === 'psa' && (
         <div>
-          {psaLoading ? (
+          {psaError ? (
+            <ErrorRetry label="PSA metrics" onRetry={() => { setPsaError(false); psaPeriodRef.current = null; setRetryKey((k) => k + 1) }} />
+          ) : psaLoading ? (
             <div className="flex items-center justify-center min-h-[200px]">
               <Loader2 size={20} className="animate-spin text-muted-foreground" />
             </div>
           ) : psaData ? (
             <PsaMetricsPanel data={psaData} />
-          ) : (
+          ) : null}
-            <div className="flex items-center justify-center min-h-[200px]">
-              <p className="text-sm text-muted-foreground">No PSA data available</p>
-            </div>
-          )}
         </div>
       )}
     </div>
@@ -498,6 +516,22 @@ function ConfidenceTierRow({
   )
 }
 
+function ErrorRetry({ label, onRetry }: { label: string; onRetry: () => void }) {
+  return (
+    <div className="flex flex-col items-center justify-center py-12 text-muted-foreground">
+      <AlertTriangle size={24} className="mb-2 text-amber-400" />
+      <p className="text-sm mb-3">Failed to load {label}</p>
+      <button
+        onClick={onRetry}
+        className="inline-flex items-center gap-1.5 px-3 py-1.5 text-sm rounded-[10px] bg-[rgba(255,255,255,0.04)] border border-[rgba(255,255,255,0.06)] text-foreground hover:border-[rgba(255,255,255,0.12)] transition-colors"
+      >
+        <RotateCcw size={12} />
+        Retry
+      </button>
+    </div>
+  )
+}
+
 function GapCard({ gap }: { gap: KnowledgeGap }) {
   const severityStyle = SEVERITY_STYLES[gap.severity as keyof typeof SEVERITY_STYLES] ?? SEVERITY_STYLES.low
   return (