@growth-labs/cms 0.8.20 → 0.8.23

package/src/ui/nav.ts

@@ -26,6 +26,7 @@ export const NAV_MODEL: NavGroup[] = [
 			{ id: 'calendar', label: 'Calendar', icon: 'calendar' },
 			{ id: 'media', label: 'Media', icon: 'media' },
 			{ id: 'analytics', label: 'Analytics', icon: 'chart' },
+			{ id: 'podcasts', label: 'Podcasts', icon: 'mic' },
 		],
 	},
 	{

package/src/ui/screens/AnalyticsScreen.tsx

@@ -32,7 +32,9 @@ import {
 	normalizeAnalyticsData,
 	normalizeArticleAnalyticsDetail,
 	type ReadsPoint,
+	TRAFFIC_SOURCES_CAPTION,
 	type TrafficSource,
+	uniqueVisitorsKpiLabel,
 } from './analytics-data.js'
 import {
 	formatKpi,
@@ -201,7 +203,9 @@ export function AnalyticsScreen() {
 				</div>
 			)}
 
-			{!s.loading && !s.error && s.data && <AnalyticsBody data={s.data} isPartial={isPartial} />}
+			{!s.loading && !s.error && s.data && (
+				<AnalyticsBody data={s.data} isPartial={isPartial} rangeDays={Number.parseInt(range, 10)} />
+			)}
 		</div>
 	)
 }
@@ -579,7 +583,15 @@ function RangeSegment({
 // AnalyticsBody
 // ---------------------------------------------------------------------------
 
-function AnalyticsBody({ data, isPartial }: { data: AnalyticsData; isPartial: boolean }) {
+function AnalyticsBody({
+	data,
+	isPartial,
+	rangeDays,
+}: {
+	data: AnalyticsData
+	isPartial: boolean
+	rangeDays: number
+}) {
 	return (
 		<div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--gap)' }}>
 			{isPartial && (
@@ -587,7 +599,7 @@ function AnalyticsBody({ data, isPartial }: { data: AnalyticsData; isPartial: bo
 			)}
 
 			{/* KPI cards */}
-			<KpiCards kpis={data.kpis} />
+			<KpiCards kpis={data.kpis} rangeDays={rangeDays} />
 
 			{/* Reads over time + traffic sources */}
 			<div className="grid-split-wide">
@@ -638,7 +650,13 @@ const KPI_DEFS: Array<{
 	},
 ]
 
-export function KpiCards({ kpis }: { kpis: ProviderResult<Record<string, number | null>> }) {
+export function KpiCards({
+	kpis,
+	rangeDays = 7,
+}: {
+	kpis: ProviderResult<Record<string, number | null>>
+	rangeDays?: number
+}) {
 	const kpiStatus = selectKpiState(kpis)
 
 	if (kpiStatus === 'empty') {
@@ -666,7 +684,7 @@ export function KpiCards({ kpis }: { kpis: ProviderResult<Record<string, number
 				return (
 					<KpiCard
 						key={def.key}
-						label={def.label}
+						label={def.key === 'uniqueVisitors' ? uniqueVisitorsKpiLabel(rangeDays) : def.label}
 						status={isUnmeasured ? 'partial' : kpiStatus}
 						value={displayValue}
 						note={displayNote}
@@ -813,7 +831,7 @@ function ReadsChart({ series }: { series: ProviderResult<ReadsPoint[]> }) {
 // TrafficSources
 // ---------------------------------------------------------------------------
 
-function TrafficSources({ result }: { result: ProviderResult<TrafficSource[]> }) {
+export 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." />
 	}
@@ -836,6 +854,16 @@ function TrafficSources({ result }: { result: ProviderResult<TrafficSource[]> })
 					<span style={{ fontSize: 11, fontWeight: 600, color: 'var(--amber)' }}>Partial</span>
 				)}
 			</div>
+			<div
+				style={{
+					fontSize: 11,
+					color: 'var(--ink-faint)',
+					marginTop: -10,
+					marginBottom: 14,
+				}}
+			>
+				{TRAFFIC_SOURCES_CAPTION}
+			</div>
 			{sources.map((src) => {
 				const pct = (src.sessions / maxSessions) * 100
 				return (

package/src/ui/screens/PodcastListeningScreen.tsx

@@ -0,0 +1,529 @@
+// src/ui/screens/PodcastListeningScreen.tsx — the "Podcasts" listening panel.
+//
+// Backed by AnalyticsProvider.getPodcastListening via
+// GET /admin/api/analytics?type=podcastListening&range=<Nd>. The provider
+// returns null on sites with no podcast listening analytics — the route 404s
+// and this screen shows an explicit "not available" state, never zeros.
+//
+// States, each visually distinct (the live/partial/empty convention adapted
+// to this panel):
+//   - loading          → kicker
+//   - HTTP error       → red error line + Retry (a provider that is
+//                        implemented but fails throws; the route 500s loudly)
+//   - 404              → "not available on this site" panel
+//   - no episodes      → honest empty panel
+//   - data             → totals cards + sortable episode table with inline
+//                        drop-off bars (10→100%)
+//
+// Listening seconds come from the `audio_played` event, which the player
+// reports only after the listening-time instrumentation ships. Until then
+// every listening cell reads "—" and a banner explains why — an unmeasured
+// metric must look different from zero minutes listened.
+
+import { useCallback, useEffect, useReducer, useState } from 'react'
+import type { PodcastListening, PodcastListeningEpisode } from '../../providers/types.js'
+import { Icon } from '../icons.js'
+import {
+	episodeLabel,
+	normalizePodcastListening,
+	type PodcastSortKey,
+	sortEpisodes,
+} from './podcast-listening-data.js'
+
+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' },
+]
+
+// Workers Analytics Engine retains roughly 90 days of events; the widest
+// picker is therefore 90 days and the header says so.
+const RETENTION_NOTE = 'Event analytics retain about 90 days.'
+
+// ---------------------------------------------------------------------------
+// Reducer
+// ---------------------------------------------------------------------------
+
+interface PodcastState {
+	loading: boolean
+	// 'unavailable' = the provider returned null (route 404); the panel is not
+	// offered on this site. 'error' = the fetch failed or the route 500ed.
+	state: 'loading' | 'unavailable' | 'error' | 'data'
+	error: string | null
+	data: PodcastListening | null
+}
+
+type PodcastAction =
+	| { type: 'fetch-start' }
+	| { type: 'fetch-unavailable' }
+	| { type: 'fetch-ok'; data: PodcastListening }
+	| { type: 'fetch-error'; error: string }
+
+function init(): PodcastState {
+	return { loading: true, state: 'loading', error: null, data: null }
+}
+
+function reducer(state: PodcastState, action: PodcastAction): PodcastState {
+	switch (action.type) {
+		case 'fetch-start':
+			return { ...state, loading: true, error: null }
+		case 'fetch-unavailable':
+			return { loading: false, state: 'unavailable', error: null, data: null }
+		case 'fetch-ok':
+			return { loading: false, state: 'data', error: null, data: action.data }
+		case 'fetch-error':
+			return { loading: false, state: 'error', error: action.error, data: null }
+		default:
+			return state
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Screen
+// ---------------------------------------------------------------------------
+
+export function PodcastListeningScreen() {
+	const [range, setRange] = useState<RangeOption>('30d')
+	const [s, dispatch] = useReducer(reducer, undefined, init)
+
+	const fetchData = useCallback(async (r: RangeOption) => {
+		dispatch({ type: 'fetch-start' })
+		try {
+			const res = await fetch(`/admin/api/analytics?type=podcastListening&range=${r}`)
+			if (res.status === 404) {
+				dispatch({ type: 'fetch-unavailable' })
+				return
+			}
+			if (!res.ok) {
+				dispatch({ type: 'fetch-error', error: `${res.status} ${res.statusText}` })
+				return
+			}
+			const body = await res.json()
+			const data = normalizePodcastListening(body)
+			if (!data) {
+				dispatch({ type: 'fetch-error', error: 'malformed podcast listening payload' })
+				return
+			}
+			dispatch({ type: 'fetch-ok', data })
+		} catch (err) {
+			dispatch({ type: 'fetch-error', error: String(err) })
+		}
+	}, [])
+
+	useEffect(() => {
+		void fetchData(range)
+	}, [fetchData, range])
+
+	return (
+		<div className="page page-wide podcasts-screen fade-in" style={{ maxWidth: 1340 }}>
+			<div className="page-head">
+				<div>
+					<h1 className="page-title">Podcasts</h1>
+					<div className="page-sub">
+						How far listeners get into each episode, and how long they listen. {RETENTION_NOTE}
+					</div>
+				</div>
+				<RangeSegment value={range} onChange={setRange} />
+			</div>
+
+			{s.state === 'loading' && <div className="kicker">Loading podcast listening…</div>}
+
+			{s.state === '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.state === 'unavailable' && (
+				<EmptyPanel
+					icon="mic"
+					message="Podcast listening analytics is not available on this site."
+				/>
+			)}
+
+			{s.state === 'data' && s.data && <PodcastListeningBody data={s.data} />}
+		</div>
+	)
+}
+
+function PodcastListeningBody({ data }: { data: PodcastListening }) {
+	if (data.episodes.length === 0) {
+		return <EmptyPanel icon="mic" message="No podcast listening data in this range yet." />
+	}
+
+	const listeningMeasured = data.totals.totalListeningSeconds !== null
+
+	return (
+		<div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--gap)' }}>
+			{!listeningMeasured && <ListeningPendingBanner />}
+			<PodcastTotalsCards data={data} />
+			<PodcastEpisodeTable episodes={data.episodes} />
+		</div>
+	)
+}
+
+function ListeningPendingBanner() {
+	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} />
+			Listening time is not reported yet — it appears here from the date the player starts sending
+			listening events. Until then those cells read “—”, not zero.
+		</div>
+	)
+}
+
+// ---------------------------------------------------------------------------
+// Totals cards
+// ---------------------------------------------------------------------------
+
+function PodcastTotalsCards({ data }: { data: PodcastListening }) {
+	const t = data.totals
+	const cards: Array<{ label: string; value: string; note: string | null }> = [
+		{ label: 'Episodes played', value: formatNumber(t.episodes), note: null },
+		{ label: 'Plays', value: formatNumber(t.plays), note: 'user-initiated' },
+		{ label: 'Listeners', value: formatNumber(t.listeners), note: 'distinct sessions' },
+		{ label: 'Completes', value: formatNumber(t.completes), note: null },
+		{ label: 'Completion', value: formatPercent(t.completionRate), note: 'completes / plays' },
+		{
+			label: 'Listening time',
+			value: t.totalListeningSeconds === null ? '—' : formatDuration(t.totalListeningSeconds),
+			note: t.totalListeningSeconds === null ? 'not reported yet' : 'total, all episodes',
+		},
+	]
+	return (
+		<div className="grid-stats">
+			{cards.map((card) => (
+				<div key={card.label} className="panel panel-pad">
+					<div className="kicker">{card.label}</div>
+					<div
+						className="serif tnum"
+						style={{ fontSize: 26, fontWeight: 600, color: 'var(--ink)', margin: '6px 0 4px' }}
+					>
+						{card.value === '—' ? (
+							<span style={{ fontSize: 18, color: 'var(--ink-muted)' }}>—</span>
+						) : (
+							card.value
+						)}
+					</div>
+					{card.note && (
+						<span style={{ fontSize: 12, color: 'var(--ink-faint)' }}>{card.note}</span>
+					)}
+				</div>
+			))}
+		</div>
+	)
+}
+
+// ---------------------------------------------------------------------------
+// Episode table (sortable, with inline drop-off bars)
+// ---------------------------------------------------------------------------
+
+interface ColumnDef {
+	key: PodcastSortKey
+	label: string
+	align: 'left' | 'right'
+}
+
+const COLUMNS: ColumnDef[] = [
+	{ key: 'episode', label: 'Episode', align: 'left' },
+	{ key: 'plays', label: 'Plays', align: 'right' },
+	{ key: 'listeners', label: 'Listeners', align: 'right' },
+	{ key: 'reached10', label: '10%', align: 'right' },
+	{ key: 'reached25', label: '25%', align: 'right' },
+	{ key: 'reached50', label: '50%', align: 'right' },
+	{ key: 'reached75', label: '75%', align: 'right' },
+	{ key: 'reached90', label: '90%', align: 'right' },
+	{ key: 'completes', label: 'Done', align: 'right' },
+	{ key: 'completionRate', label: 'Rate', align: 'right' },
+	{ key: 'totalListeningSeconds', label: 'Listening', align: 'right' },
+]
+
+export function PodcastEpisodeTable({
+	episodes,
+}: {
+	episodes: readonly PodcastListeningEpisode[]
+}) {
+	const [sortKey, setSortKey] = useState<PodcastSortKey>('plays')
+	const [sortDir, setSortDir] = useState<'asc' | 'desc'>('desc')
+
+	const handleSort = (key: PodcastSortKey) => {
+		if (key === sortKey) {
+			setSortDir(sortDir === 'desc' ? 'asc' : 'desc')
+		} else {
+			setSortKey(key)
+			setSortDir(key === 'episode' ? 'asc' : 'desc')
+		}
+	}
+
+	const rows = sortEpisodes(episodes, sortKey, sortDir)
+
+	return (
+		<div className="panel" style={{ overflow: 'hidden' }}>
+			<div
+				style={{
+					display: 'flex',
+					justifyContent: 'space-between',
+					alignItems: 'baseline',
+					padding: '16px 18px 12px',
+				}}
+			>
+				<div className="card-title">Episodes</div>
+				<div className="kicker" style={{ fontSize: 10.5 }}>
+					Drop-off 10 → 100% per episode
+				</div>
+			</div>
+			<hr className="masthead-rule" style={{ margin: '0 18px' }} />
+			<div style={{ overflowX: 'auto' }}>
+				<table className="tbl">
+					<thead>
+						<tr>
+							{COLUMNS.map((col) => (
+								<th
+									key={col.key}
+									style={{
+										paddingLeft: col.key === 'episode' ? 18 : undefined,
+										textAlign: col.align,
+										whiteSpace: 'nowrap',
+									}}
+								>
+									<button
+										type="button"
+										onClick={() => handleSort(col.key)}
+										style={{
+											all: 'unset',
+											cursor: 'pointer',
+											display: 'inline-flex',
+											alignItems: 'center',
+											gap: 4,
+											fontWeight: sortKey === col.key ? 700 : undefined,
+											color: sortKey === col.key ? 'var(--ink)' : 'inherit',
+										}}
+										title={`Sort by ${col.label}`}
+										data-sort-active={sortKey === col.key ? 'true' : undefined}
+									>
+										{col.label}
+										{sortKey === col.key && (
+											<span style={{ fontSize: 9 }}>{sortDir === 'desc' ? '▼' : '▲'}</span>
+										)}
+									</button>
+								</th>
+							))}
+							<th
+								style={{ paddingRight: 18 }}
+								title="Share of plays reaching each mark; the last bar is completes"
+							>
+								Drop-off
+							</th>
+						</tr>
+					</thead>
+					<tbody>
+						{rows.map((episode) => (
+							<tr key={episode.slug}>
+								<td style={{ paddingLeft: 18, maxWidth: 360 }}>
+									<div
+										style={{
+											fontWeight: 600,
+											color: 'var(--ink)',
+											whiteSpace: 'nowrap',
+											overflow: 'hidden',
+											textOverflow: 'ellipsis',
+										}}
+										title={episode.slug}
+									>
+										{episodeLabel(episode)}
+									</div>
+									{episode.title && (
+										<div
+											style={{
+												fontSize: 11,
+												color: 'var(--ink-faint)',
+												whiteSpace: 'nowrap',
+												overflow: 'hidden',
+												textOverflow: 'ellipsis',
+											}}
+										>
+											{episode.slug}
+										</div>
+									)}
+								</td>
+								<td className="tnum" style={{ fontWeight: 600, textAlign: 'right' }}>
+									{formatNumber(episode.plays)}
+								</td>
+								<td className="tnum" style={{ textAlign: 'right' }}>
+									{formatNumber(episode.listeners)}
+								</td>
+								<td className="tnum" style={{ textAlign: 'right' }}>
+									{formatNumber(episode.reached10)}
+								</td>
+								<td className="tnum" style={{ textAlign: 'right' }}>
+									{formatNumber(episode.reached25)}
+								</td>
+								<td className="tnum" style={{ textAlign: 'right' }}>
+									{formatNumber(episode.reached50)}
+								</td>
+								<td className="tnum" style={{ textAlign: 'right' }}>
+									{formatNumber(episode.reached75)}
+								</td>
+								<td className="tnum" style={{ textAlign: 'right' }}>
+									{formatNumber(episode.reached90)}
+								</td>
+								<td className="tnum" style={{ textAlign: 'right' }}>
+									{formatNumber(episode.completes)}
+								</td>
+								<td className="tnum" style={{ textAlign: 'right' }}>
+									{formatPercent(episode.completionRate)}
+								</td>
+								<td className="tnum" style={{ textAlign: 'right' }}>
+									{episode.totalListeningSeconds === null ? (
+										<span title="No listening events in this range yet">—</span>
+									) : (
+										formatDuration(episode.totalListeningSeconds)
+									)}
+								</td>
+								<td style={{ paddingRight: 18 }}>
+									<DropoffBars episode={episode} />
+								</td>
+							</tr>
+						))}
+					</tbody>
+				</table>
+			</div>
+		</div>
+	)
+}
+
+/**
+ * Six inline bars: the share of an episode's plays that reached 10/25/50/75/90
+ * percent, with the sixth bar completes (the 100% mark). Height is relative to
+ * plays; an episode with zero plays renders flat bars — an honest zero.
+ */
+function DropoffBars({ episode }: { episode: PodcastListeningEpisode }) {
+	const stages: Array<{ label: string; count: number }> = [
+		{ label: '10%', count: episode.reached10 },
+		{ label: '25%', count: episode.reached25 },
+		{ label: '50%', count: episode.reached50 },
+		{ label: '75%', count: episode.reached75 },
+		{ label: '90%', count: episode.reached90 },
+		{ label: '100%', count: episode.completes },
+	]
+	const base = Math.max(episode.plays, 1)
+	return (
+		<div
+			style={{ display: 'inline-flex', alignItems: 'flex-end', gap: 3, height: 22 }}
+			title={stages
+				.map((s) => `${s.label}: ${formatNumber(s.count)} (${formatPercent(s.count / base)})`)
+				.join(' · ')}
+		>
+			{stages.map((stage) => {
+				const pct = Math.max(0, Math.min(100, (stage.count / base) * 100))
+				return (
+					<div
+						key={stage.label}
+						style={{
+							width: 7,
+							height: `${Math.max(pct, 2)}%`,
+							minHeight: 1,
+							background:
+								stage.label === '100%'
+									? 'var(--accent)'
+									: 'color-mix(in srgb, var(--accent) 45%, transparent)',
+							borderRadius: '2px 2px 0 0',
+						}}
+					/>
+				)
+			})}
+		</div>
+	)
+}
+
+// ---------------------------------------------------------------------------
+// Shared micro-components
+// ---------------------------------------------------------------------------
+
+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>
+	)
+}
+
+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 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 `${(Math.max(0, value) * 100).toFixed(1)}%`
+}