@growth-labs/cms 0.1.0

package/src/ui/screens/AnalyticsScreen.tsx

@@ -0,0 +1,938 @@
+// src/ui/screens/AnalyticsScreen.tsx — Analytics screen (P5 Task 10).
+//
+// Renders the four analytics surfaces — KPI cards, reads-over-time bars,
+// traffic-source bars, and top-content table — backed entirely by the
+// AnalyticsProvider via GET /admin/api/analytics?type=<handler>&range=<Nd>.
+//
+// All data honours the ProviderResult live/partial/empty convention:
+//   - live   → render the real value
+//   - partial → render the value with an explicit "partial" affordance
+//   - empty  → render an honest "no data yet" state
+//
+// A null individual KPI value (e.g. conversion = null) renders as
+// "—" (via formatKpi's { pending: true } sentinel) — NEVER as "0" / "0%".
+//
+// A single partial banner is shown at the top whenever any result is partial,
+// explaining that reads are available but the full rollup is still pending.
+//
+// Re-skinned to the Broadsheet idiom: .page.page-wide / .page-head / .page-title,
+// .seg range switch, .grid-stats KPI cards (.kicker label + .serif.tnum stat),
+// .grid-split-wide for reads-chart + traffic, and a .tbl top-content table under
+// a .card-title + .masthead-rule hairline. NO BData, NO mock numbers.
+
+import { useCallback, useEffect, useReducer, useState } from 'react'
+import type { ArticleAnalyticsDetail, ProviderResult } from '../../providers/types.js'
+import { Icon } from '../icons.js'
+import {
+	type AnalyticsData,
+	normalizeAnalyticsData,
+	normalizeArticleAnalyticsDetail,
+	type ReadsPoint,
+	type TrafficSource,
+} from './analytics-data.js'
+import {
+	formatKpi,
+	type KpiPending,
+	mergeTopContent,
+	selectKpiState,
+	type TopContentProvider,
+} from './render-state.js'
+
+// ---------------------------------------------------------------------------
+// Range options
+// ---------------------------------------------------------------------------
+
+type RangeOption = '7d' | '30d' | '90d'
+
+const RANGE_LABELS: Array<{ value: RangeOption; label: string }> = [
+	{ value: '7d', label: '7 days' },
+	{ value: '30d', label: '30 days' },
+	{ value: '90d', label: '90 days' },
+]
+
+function articleSlugFromHash(hash: string): string | null {
+	const raw = hash.replace(/^#\/?/, '').split('?')[0] ?? ''
+	const parts = raw.split('/')
+	if (parts[0] !== 'analytics' || parts[1] !== 'articles' || !parts[2]) return null
+	try {
+		return decodeURIComponent(parts[2])
+	} catch {
+		return null
+	}
+}
+
+function openArticleAnalytics(slug: string) {
+	window.location.hash = `#/analytics/articles/${encodeURIComponent(slug)}`
+}
+
+// ---------------------------------------------------------------------------
+// Reducer
+// ---------------------------------------------------------------------------
+
+interface AnalyticsState {
+	loading: boolean
+	error: string | null
+	data: AnalyticsData | null
+}
+
+type AnalyticsAction =
+	| { type: 'fetch-start' }
+	| { type: 'fetch-ok'; data: AnalyticsData }
+	| { type: 'fetch-error'; error: string }
+
+function init(): AnalyticsState {
+	return { loading: true, error: null, data: null }
+}
+
+function reducer(state: AnalyticsState, action: AnalyticsAction): AnalyticsState {
+	switch (action.type) {
+		case 'fetch-start':
+			return { ...state, loading: true, error: null }
+		case 'fetch-ok':
+			return { loading: false, error: null, data: action.data }
+		case 'fetch-error':
+			return { loading: false, error: action.error, data: null }
+		default:
+			return state
+	}
+}
+
+// ---------------------------------------------------------------------------
+// AnalyticsScreen
+// ---------------------------------------------------------------------------
+
+export function AnalyticsScreen() {
+	const [articleSlug, setArticleSlug] = useState<string | null>(() =>
+		typeof window === 'undefined' ? null : articleSlugFromHash(window.location.hash),
+	)
+	const [range, setRange] = useState<RangeOption>('30d')
+	const [s, dispatch] = useReducer(reducer, undefined, init)
+
+	useEffect(() => {
+		const syncSlug = () => setArticleSlug(articleSlugFromHash(window.location.hash))
+		window.addEventListener('hashchange', syncSlug)
+		return () => window.removeEventListener('hashchange', syncSlug)
+	}, [])
+
+	const fetchData = useCallback(async (r: RangeOption) => {
+		dispatch({ type: 'fetch-start' })
+		try {
+			const base = `/admin/api/analytics?range=${r}`
+			const [kpisRes, seriesRes, topRes, sourcesRes] = await Promise.all([
+				fetch(`${base}&type=kpis`),
+				fetch(`${base}&type=readsTimeSeries`),
+				fetch(`${base}&type=topContent`),
+				fetch(`${base}&type=trafficSources`),
+			])
+
+			if (!kpisRes.ok || !seriesRes.ok || !topRes.ok || !sourcesRes.ok) {
+				const bad = [kpisRes, seriesRes, topRes, sourcesRes].find((r) => !r.ok)!
+				dispatch({ type: 'fetch-error', error: `${bad.status} ${bad.statusText}` })
+				return
+			}
+
+			const [kpis, readsTimeSeries, topContent, trafficSources] = await Promise.all([
+				kpisRes.json(),
+				seriesRes.json(),
+				topRes.json(),
+				sourcesRes.json(),
+			])
+
+			dispatch({
+				type: 'fetch-ok',
+				data: normalizeAnalyticsData({ kpis, readsTimeSeries, topContent, trafficSources }),
+			})
+		} catch (err) {
+			dispatch({ type: 'fetch-error', error: String(err) })
+		}
+	}, [])
+
+	useEffect(() => {
+		if (articleSlug) return
+		void fetchData(range)
+	}, [articleSlug, fetchData, range])
+
+	const handleRangeChange = (r: RangeOption) => {
+		setRange(r)
+	}
+
+	if (articleSlug) {
+		return <ArticleAnalyticsDetailScreen slug={articleSlug} />
+	}
+
+	// Optional chaining: a provider that returns a null/absent result for any
+	// metric must not throw on `.status` (that crash blanked the whole screen).
+	const isPartial =
+		s.data != null &&
+		(s.data.kpis?.status === 'partial' ||
+			s.data.readsTimeSeries?.status === 'partial' ||
+			s.data.topContent?.status === 'partial' ||
+			s.data.trafficSources?.status === 'partial')
+
+	return (
+		<div className="page page-wide analytics-screen fade-in" style={{ maxWidth: 1340 }}>
+			{/* Header */}
+			<div className="page-head">
+				<div>
+					<h1 className="page-title">Analytics</h1>
+					<div className="page-sub">Reads, traffic, and audience trends.</div>
+				</div>
+				<RangeSegment value={range} onChange={handleRangeChange} />
+			</div>
+
+			{/* Body */}
+			{s.loading && <div className="kicker">Loading analytics…</div>}
+
+			{!s.loading && s.error && (
+				<div style={{ color: 'var(--red)', fontSize: 13.5 }}>
+					{s.error}
+					<button
+						type="button"
+						className="btn sm"
+						onClick={() => void fetchData(range)}
+						style={{ marginLeft: 12 }}
+					>
+						Retry
+					</button>
+				</div>
+			)}
+
+			{!s.loading && !s.error && s.data && <AnalyticsBody data={s.data} isPartial={isPartial} />}
+		</div>
+	)
+}
+
+interface ArticleDetailState {
+	loading: boolean
+	error: string | null
+	result: ProviderResult<ArticleAnalyticsDetail | null> | null
+}
+
+function ArticleAnalyticsDetailScreen({ slug }: { slug: string }) {
+	const [range, setRange] = useState<RangeOption>('30d')
+	const [state, setState] = useState<ArticleDetailState>({
+		loading: true,
+		error: null,
+		result: null,
+	})
+
+	const fetchDetail = useCallback(async (r: RangeOption, articleSlug: string) => {
+		setState((prev) => ({ ...prev, loading: true, error: null }))
+		try {
+			const res = await fetch(
+				`/admin/api/analytics?type=articleDetail&range=${r}&slug=${encodeURIComponent(articleSlug)}`,
+			)
+			if (!res.ok) {
+				setState({ loading: false, error: `${res.status} ${res.statusText}`, result: null })
+				return
+			}
+			const body = await res.json()
+			setState({
+				loading: false,
+				error: null,
+				result: normalizeArticleAnalyticsDetail(body),
+			})
+		} catch (err) {
+			setState({ loading: false, error: String(err), result: null })
+		}
+	}, [])
+
+	useEffect(() => {
+		void fetchDetail(range, slug)
+	}, [fetchDetail, range, slug])
+
+	const detail = state.result?.data ?? null
+	const title = detail?.title || slug
+
+	return (
+		<div className="page page-wide analytics-screen fade-in" style={{ maxWidth: 1340 }}>
+			<div className="page-head">
+				<div style={{ minWidth: 0 }}>
+					<button
+						type="button"
+						className="btn sm"
+						onClick={() => {
+							window.location.hash = '#/analytics'
+						}}
+						style={{ marginBottom: 12 }}
+					>
+						<Icon name="chevLeft" size={14} />
+						Back
+					</button>
+					<h1 className="page-title" title={title}>
+						{title}
+					</h1>
+					<div className="page-sub">
+						{detail?.canonicalUrl ?? `/article/${slug}`}
+						{detail?.freshness?.latestDate ? ` · through ${detail.freshness.latestDate}` : ''}
+					</div>
+				</div>
+				<RangeSegment value={range} onChange={setRange} />
+			</div>
+
+			{state.loading && <div className="kicker">Loading article analytics…</div>}
+
+			{!state.loading && state.error && (
+				<div style={{ color: 'var(--red)', fontSize: 13.5 }}>
+					{state.error}
+					<button
+						type="button"
+						className="btn sm"
+						onClick={() => void fetchDetail(range, slug)}
+						style={{ marginLeft: 12 }}
+					>
+						Retry
+					</button>
+				</div>
+			)}
+
+			{!state.loading && !state.error && (!state.result || !detail) && (
+				<EmptyPanel icon="chart" message="No article analytics data yet." />
+			)}
+
+			{!state.loading && !state.error && state.result && detail && (
+				<ArticleAnalyticsDetailBody result={state.result} detail={detail} />
+			)}
+		</div>
+	)
+}
+
+function ArticleAnalyticsDetailBody({
+	result,
+	detail,
+}: {
+	result: ProviderResult<ArticleAnalyticsDetail | null>
+	detail: ArticleAnalyticsDetail
+}) {
+	const isPartial = result.status === 'partial' || detail.freshness?.status === 'partial'
+	const readsResult: ProviderResult<ReadsPoint[]> = {
+		status: result.status,
+		data: detail.readsTimeSeries,
+	}
+
+	return (
+		<div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--gap)' }}>
+			{isPartial && (
+				<PartialBanner message="Showing available article metrics — source or rollup detail may still be pending." />
+			)}
+
+			<div className="grid-stats">
+				<KpiCard
+					label="Reads"
+					status={result.status}
+					value={formatNumber(detail.summary.reads)}
+					note={null}
+				/>
+				<KpiCard
+					label="Unique visitors"
+					status={result.status}
+					value={formatNumber(detail.summary.uniqueVisitors)}
+					note={null}
+				/>
+				<KpiCard
+					label="Avg read time"
+					status={result.status}
+					value={formatDuration(detail.summary.avgReadSeconds)}
+					note={null}
+				/>
+				<KpiCard
+					label="Paid starts"
+					status={result.status}
+					value={formatNumber(detail.summary.paidStarts)}
+					note={`${formatPercent(detail.summary.conversionRateBySessions)} of sessions`}
+				/>
+				<KpiCard
+					label="Revenue"
+					status={result.status}
+					value={formatCurrencyCents(
+						detail.summary.attributedRevenueCents,
+						detail.summary.attributedRevenueCurrency,
+					)}
+					note={`${formatNumber(detail.summary.revenueBackedStarts)} first payments`}
+				/>
+				<KpiCard
+					label="Conversion"
+					status={result.status}
+					value={formatPercent(detail.summary.conversionRateByReads)}
+					note="by reads"
+				/>
+			</div>
+
+			<div className="grid-split-wide">
+				<ReadsChart series={readsResult} />
+				<ScrollDepthPanel detail={detail} />
+			</div>
+
+			<ArticleSourceTable detail={detail} />
+		</div>
+	)
+}
+
+function ScrollDepthPanel({ detail }: { detail: ArticleAnalyticsDetail }) {
+	const rows = [
+		{ label: '25%', count: detail.scrollDepth.scroll25, rate: detail.scrollDepth.scroll25Rate },
+		{ label: '50%', count: detail.scrollDepth.scroll50, rate: detail.scrollDepth.scroll50Rate },
+		{ label: '75%', count: detail.scrollDepth.scroll75, rate: detail.scrollDepth.scroll75Rate },
+		{ label: '90%', count: detail.scrollDepth.scroll90, rate: detail.scrollDepth.scroll90Rate },
+	]
+
+	return (
+		<div className="panel panel-pad">
+			<div className="card-title" style={{ marginBottom: 18 }}>
+				Scroll depth
+			</div>
+			{rows.map((row) => (
+				<div key={row.label} style={{ marginBottom: 14 }}>
+					<div
+						style={{
+							display: 'flex',
+							justifyContent: 'space-between',
+							fontSize: 12.5,
+							marginBottom: 5,
+						}}
+					>
+						<span style={{ color: 'var(--ink-soft)', fontWeight: 600 }}>{row.label}</span>
+						<span className="tnum" style={{ color: 'var(--ink-muted)' }}>
+							{formatPercent(row.rate)} · {formatNumber(row.count)}
+						</span>
+					</div>
+					<div
+						style={{ height: 7, background: 'var(--hover)', borderRadius: 4, overflow: 'hidden' }}
+					>
+						<div
+							style={{
+								width: `${Math.max(0, Math.min(100, row.rate * 100))}%`,
+								height: '100%',
+								background: 'var(--accent)',
+								borderRadius: 4,
+							}}
+						/>
+					</div>
+				</div>
+			))}
+		</div>
+	)
+}
+
+function ArticleSourceTable({ detail }: { detail: ArticleAnalyticsDetail }) {
+	if (detail.sources.length === 0) {
+		return <EmptyPanel icon="globe" message="No source data yet for this article." />
+	}
+
+	return (
+		<div className="panel" style={{ overflow: 'hidden' }}>
+			<div className="card-title" style={{ padding: '16px 18px 12px' }}>
+				Article sources
+			</div>
+			<hr className="masthead-rule" style={{ margin: '0 18px' }} />
+			<table className="tbl">
+				<thead>
+					<tr>
+						<th style={{ paddingLeft: 18 }}>Source</th>
+						<th>Medium</th>
+						<th>Campaign</th>
+						<th>Reads</th>
+						<th>Visitors</th>
+						<th>Sessions</th>
+						<th>Paid starts</th>
+					</tr>
+				</thead>
+				<tbody>
+					{detail.sources.map((source) => (
+						<tr
+							key={`${source.source}:${source.medium}:${source.campaign}:${source.derivedSource}`}
+						>
+							<td style={{ paddingLeft: 18, fontWeight: 600 }}>{source.source || 'direct'}</td>
+							<td>{source.medium || '—'}</td>
+							<td>{source.campaign || '—'}</td>
+							<td className="tnum">{formatNumber(source.reads)}</td>
+							<td className="tnum">{formatNumber(source.uniqueVisitors)}</td>
+							<td className="tnum">{formatNumber(source.sessions)}</td>
+							<td className="tnum">{formatNumber(source.paidStarts)}</td>
+						</tr>
+					))}
+				</tbody>
+			</table>
+		</div>
+	)
+}
+
+function formatNumber(value: number): string {
+	return Math.round(value).toLocaleString('en-US')
+}
+
+function formatDuration(seconds: number): string {
+	const rounded = Math.max(0, Math.round(seconds))
+	const minutes = Math.floor(rounded / 60)
+	const rest = rounded % 60
+	if (minutes === 0) return `${rest}s`
+	return rest === 0 ? `${minutes}m` : `${minutes}m ${rest}s`
+}
+
+function formatPercent(value: number): string {
+	return `${(value * 100).toFixed(1)}%`
+}
+
+function formatCurrencyCents(cents: number, currency: string): string {
+	try {
+		return new Intl.NumberFormat(undefined, {
+			style: 'currency',
+			currency,
+			maximumFractionDigits: cents % 100 === 0 ? 0 : 2,
+		}).format(cents / 100)
+	} catch {
+		return `$${(cents / 100).toFixed(2)}`
+	}
+}
+
+// ---------------------------------------------------------------------------
+// RangeSegment — broadsheet segmented control
+// ---------------------------------------------------------------------------
+
+function RangeSegment({
+	value,
+	onChange,
+}: {
+	value: RangeOption
+	onChange: (r: RangeOption) => void
+}) {
+	return (
+		<div className="seg">
+			{RANGE_LABELS.map((opt) => (
+				<button
+					key={opt.value}
+					type="button"
+					className={value === opt.value ? 'on' : ''}
+					onClick={() => onChange(opt.value)}
+				>
+					{opt.label}
+				</button>
+			))}
+		</div>
+	)
+}
+
+// ---------------------------------------------------------------------------
+// AnalyticsBody
+// ---------------------------------------------------------------------------
+
+function AnalyticsBody({ data, isPartial }: { data: AnalyticsData; isPartial: boolean }) {
+	return (
+		<div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--gap)' }}>
+			{isPartial && (
+				<PartialBanner message="Showing reads only — full metrics arrive with the analytics rollup." />
+			)}
+
+			{/* KPI cards */}
+			<KpiCards kpis={data.kpis} />
+
+			{/* Reads over time + traffic sources */}
+			<div className="grid-split-wide">
+				<ReadsChart series={data.readsTimeSeries} />
+				<TrafficSources result={data.trafficSources} />
+			</div>
+
+			{/* Top content table */}
+			<TopContentTable result={data.topContent} />
+		</div>
+	)
+}
+
+// ---------------------------------------------------------------------------
+// KpiCards
+// ---------------------------------------------------------------------------
+
+const KPI_DEFS: Array<{
+	key: string
+	label: string
+	fmt: 'num' | 'pct' | 'usd'
+	emptyNote: string
+}> = [
+	{ key: 'reads', label: 'Total reads', fmt: 'num', emptyNote: 'No reads data' },
+	{
+		key: 'avgReadSeconds',
+		label: 'Avg read time',
+		fmt: 'num',
+		emptyNote: 'No read-time data',
+	},
+	{
+		key: 'uniqueVisitors',
+		label: 'Unique visitors',
+		fmt: 'num',
+		emptyNote: 'No visitor data',
+	},
+	{
+		key: 'conversionRate',
+		label: 'Conversion',
+		fmt: 'pct',
+		emptyNote: 'No conversion data',
+	},
+]
+
+function KpiCards({ kpis }: { kpis: ProviderResult<Record<string, number | null>> }) {
+	const kpiStatus = selectKpiState(kpis)
+
+	if (kpiStatus === 'empty') {
+		return (
+			<EmptyPanel
+				icon="chart"
+				message="No analytics data yet — the analytics provider is not configured."
+			/>
+		)
+	}
+
+	return (
+		<div className="grid-stats">
+			{KPI_DEFS.map((def) => {
+				const raw = kpis.data?.[def.key] ?? null
+				const formatted = formatKpi(raw, def.fmt)
+				const isPending =
+					formatted !== null && typeof formatted === 'object' && (formatted as KpiPending).pending
+
+				const displayValue = isPending ? null : (formatted as string)
+				const displayNote = isPending ? '— pending backfill' : null
+
+				return (
+					<KpiCard
+						key={def.key}
+						label={def.label}
+						status={isPending ? 'partial' : kpiStatus}
+						value={displayValue}
+						note={displayNote}
+					/>
+				)
+			})}
+		</div>
+	)
+}
+
+function KpiCard({
+	label,
+	status,
+	value,
+	note,
+}: {
+	label: string
+	status: 'live' | 'partial' | 'empty'
+	value: string | null
+	note: string | null
+}) {
+	const empty = status === 'empty' || value === null
+	return (
+		<div className="panel panel-pad">
+			<div className="kicker">{label}</div>
+			<div
+				className="serif tnum"
+				style={{ fontSize: 30, fontWeight: 600, color: 'var(--ink)', margin: '6px 0 4px' }}
+			>
+				{empty ? <span style={{ fontSize: 18, color: 'var(--ink-muted)' }}>—</span> : value}
+			</div>
+			{note && <span style={{ fontSize: 12, color: 'var(--ink-faint)' }}>{note}</span>}
+			{status === 'partial' && !note && (
+				<span style={{ fontSize: 11, fontWeight: 600, color: 'var(--amber)' }}>partial</span>
+			)}
+		</div>
+	)
+}
+
+// ---------------------------------------------------------------------------
+// ReadsChart — bar chart for reads-over-time
+// ---------------------------------------------------------------------------
+
+function ReadsChart({ series }: { series: ProviderResult<ReadsPoint[]> }) {
+	if (!series || series.status === 'empty' || !series.data || series.data.length === 0) {
+		return <EmptyPanel icon="chart" message="No read data yet — analytics rollup pending." />
+	}
+
+	const points = series.data
+	const maxReads = Math.max(...points.map((p) => p.reads), 1)
+	const lastIdx = points.length - 1
+
+	return (
+		<div className="panel panel-pad">
+			<div
+				style={{
+					display: 'flex',
+					justifyContent: 'space-between',
+					alignItems: 'baseline',
+					marginBottom: 18,
+				}}
+			>
+				<div className="card-title">Reads over time</div>
+				<div className="kicker">
+					{series.status === 'partial' ? 'Partial · rollup pending' : `Last ${points.length} days`}
+				</div>
+			</div>
+			<div style={{ display: 'flex', alignItems: 'flex-end', gap: 8, height: 180 }}>
+				{points.map((pt, i) => {
+					const heightPct = maxReads === 0 ? 0 : (pt.reads / maxReads) * 100
+					const date = new Date(pt.t * 1000)
+					const label = date.toLocaleDateString(undefined, { month: 'short', day: 'numeric' })
+					return (
+						<div
+							key={pt.t}
+							title={`${label}: ${pt.reads.toLocaleString('en-US')} reads`}
+							style={{
+								flex: 1,
+								display: 'flex',
+								flexDirection: 'column',
+								height: '100%',
+								justifyContent: 'flex-end',
+								alignItems: 'center',
+								gap: 6,
+							}}
+						>
+							<div
+								style={{
+									width: '100%',
+									height: `${Math.max(heightPct, 2)}%`,
+									minHeight: 2,
+									background:
+										i === lastIdx
+											? 'var(--accent)'
+											: 'color-mix(in srgb, var(--accent) 45%, transparent)',
+									borderRadius: '4px 4px 0 0',
+									transition: 'height .5s ease',
+								}}
+							/>
+						</div>
+					)
+				})}
+			</div>
+			<div
+				style={{
+					marginTop: 8,
+					display: 'flex',
+					justifyContent: 'space-between',
+					fontSize: 11,
+					color: 'var(--ink-faint)',
+				}}
+				className="mono"
+			>
+				{points.length > 0 && (
+					<>
+						<span>
+							{new Date(points[0]!.t * 1000).toLocaleDateString(undefined, {
+								month: 'short',
+								day: 'numeric',
+							})}
+						</span>
+						<span>
+							{new Date(points[lastIdx]!.t * 1000).toLocaleDateString(undefined, {
+								month: 'short',
+								day: 'numeric',
+							})}
+						</span>
+					</>
+				)}
+			</div>
+		</div>
+	)
+}
+
+// ---------------------------------------------------------------------------
+// TrafficSources
+// ---------------------------------------------------------------------------
+
+function TrafficSources({ result }: { result: ProviderResult<TrafficSource[]> }) {
+	if (!result || result.status === 'empty' || !result.data || result.data.length === 0) {
+		return <EmptyPanel icon="globe" message="No traffic source data yet." />
+	}
+
+	const sources = result.data
+	const maxSessions = Math.max(...sources.map((s) => s.sessions), 1)
+
+	return (
+		<div className="panel panel-pad">
+			<div
+				style={{
+					display: 'flex',
+					justifyContent: 'space-between',
+					alignItems: 'baseline',
+					marginBottom: 18,
+				}}
+			>
+				<div className="card-title">Traffic sources</div>
+				{result.status === 'partial' && (
+					<span style={{ fontSize: 11, fontWeight: 600, color: 'var(--amber)' }}>Partial</span>
+				)}
+			</div>
+			{sources.map((src) => {
+				const pct = (src.sessions / maxSessions) * 100
+				return (
+					<div key={src.source} style={{ marginBottom: 14 }}>
+						<div
+							style={{
+								display: 'flex',
+								justifyContent: 'space-between',
+								fontSize: 12.5,
+								marginBottom: 5,
+							}}
+						>
+							<span style={{ color: 'var(--ink-soft)', fontWeight: 600 }}>{src.source}</span>
+							<span className="tnum" style={{ color: 'var(--ink-muted)' }}>
+								{src.sessions.toLocaleString('en-US')}
+							</span>
+						</div>
+						<div
+							style={{ height: 7, background: 'var(--hover)', borderRadius: 4, overflow: 'hidden' }}
+						>
+							<div
+								style={{
+									width: `${pct}%`,
+									height: '100%',
+									background: 'var(--accent)',
+									borderRadius: 4,
+								}}
+							/>
+						</div>
+					</div>
+				)
+			})}
+		</div>
+	)
+}
+
+// ---------------------------------------------------------------------------
+// TopContentTable
+// ---------------------------------------------------------------------------
+
+function TopContentTable({ result }: { result: ProviderResult<TopContentProvider[]> }) {
+	if (!result || result.status === 'empty' || !result.data || result.data.length === 0) {
+		return (
+			<EmptyPanel
+				icon="star"
+				message="No top content data yet — configure the analytics provider."
+			/>
+		)
+	}
+
+	// Titles are already hydrated by the route (provider supplies them)
+	const items = mergeTopContent(result.data, {})
+
+	return (
+		<div className="panel" style={{ overflow: 'hidden' }}>
+			<div className="card-title" style={{ padding: '16px 18px 12px' }}>
+				Top content
+			</div>
+			<hr className="masthead-rule" style={{ margin: '0 18px' }} />
+			{result.status === 'partial' && (
+				<div
+					style={{
+						padding: '6px 18px',
+						background: 'color-mix(in srgb, var(--amber) 7%, transparent)',
+						borderBottom: '1px solid var(--border)',
+						fontSize: 11,
+						color: 'var(--amber)',
+					}}
+				>
+					Partial data — full reads pending
+				</div>
+			)}
+			<table className="tbl">
+				<thead>
+					<tr>
+						<th style={{ paddingLeft: 18 }}>#</th>
+						<th>Title</th>
+						<th>Reads</th>
+					</tr>
+				</thead>
+				<tbody>
+					{items.map((item, i) => (
+						<tr
+							key={item.id}
+							tabIndex={0}
+							onClick={() => openArticleAnalytics(item.id)}
+							onKeyDown={(event) => {
+								if (event.key === 'Enter' || event.key === ' ') {
+									event.preventDefault()
+									openArticleAnalytics(item.id)
+								}
+							}}
+							style={{ cursor: 'pointer' }}
+							title="Open article analytics"
+						>
+							<td
+								className="tnum"
+								style={{ paddingLeft: 18, color: 'var(--ink-faint)', fontWeight: 600 }}
+							>
+								{i + 1}
+							</td>
+							<td style={{ maxWidth: 480 }}>
+								<div
+									style={{
+										fontWeight: 600,
+										color: 'var(--ink)',
+										whiteSpace: 'nowrap',
+										overflow: 'hidden',
+										textOverflow: 'ellipsis',
+									}}
+								>
+									{item.title ?? '(untitled)'}
+								</div>
+							</td>
+							<td className="tnum" style={{ fontWeight: 600 }}>
+								<span style={{ display: 'inline-flex', alignItems: 'center', gap: 5 }}>
+									{item.reads !== null ? item.reads.toLocaleString('en-US') : '—'}
+									<Icon name="eye" size={12} style={{ color: 'var(--ink-faint)' }} />
+								</span>
+							</td>
+						</tr>
+					))}
+				</tbody>
+			</table>
+		</div>
+	)
+}
+
+// ---------------------------------------------------------------------------
+// Shared micro-components
+// ---------------------------------------------------------------------------
+
+function EmptyPanel({
+	icon,
+	message,
+}: {
+	icon: Parameters<typeof Icon>[0]['name']
+	message: string
+}) {
+	return (
+		<div
+			className="panel panel-pad"
+			style={{
+				textAlign: 'center',
+				fontSize: 13,
+				color: 'var(--ink-muted)',
+				display: 'flex',
+				flexDirection: 'column',
+				alignItems: 'center',
+				gap: 8,
+				padding: '28px 20px',
+			}}
+		>
+			<Icon name={icon} size={22} style={{ color: 'var(--border)', opacity: 0.7 }} />
+			<span>{message}</span>
+		</div>
+	)
+}
+
+function PartialBanner({ message }: { message: string }) {
+	return (
+		<div
+			style={{
+				padding: '8px 14px',
+				background: 'color-mix(in srgb, var(--amber) 8%, transparent)',
+				border: '1px solid color-mix(in srgb, var(--amber) 20%, transparent)',
+				borderRadius: 'var(--radius-sm)',
+				fontSize: 12,
+				color: 'var(--amber)',
+				display: 'flex',
+				alignItems: 'center',
+				gap: 7,
+			}}
+		>
+			<Icon name="bolt" size={13} />
+			{message}
+		</div>
+	)
+}