From f292d3f9b6d3da5eec4d8712f0b6db3f177e1ffb Mon Sep 17 00:00:00 2001
From: Ewan Croft <contact@ewancroft.uk>
Date: Thu, 13 Aug 2026 15:35:47 +0100
Subject: [PATCH] feat(tourmaline): add dataset explorer with per-item detail
 modal
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Ports lastfm-stats-web's dataset table: a sortable/searchable table over
the top-50 artists/tracks/albums with CSV export, plus a click-through
detail modal showing animated stats (scrobbles, weeks active, best rank,
best month) and an artist rank-over-time line chart.

Scoped to the aggregator's existing top-50 cap rather than the full
listening history — lifting that cap would need aggregator.ts changes
that are out of scope here. Registers Chart.js's LineController, needed
for the new rank-over-time chart and not previously used by any chart.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 packages/tourmaline/src/lib/chart.ts          |   2 +
 .../src/routes/profile/[did]/+page.svelte     |  10 +
 .../src/routes/profile/[did]/CountUp.svelte   |  41 ++++
 .../src/routes/profile/[did]/Dataset.svelte   | 231 ++++++++++++++++++
 .../profile/[did]/DatasetItemModal.svelte     | 144 +++++++++++
 .../profile/[did]/DatasetRankChart.svelte     |  85 +++++++
 6 files changed, 513 insertions(+)
 create mode 100644 packages/tourmaline/src/routes/profile/[did]/CountUp.svelte
 create mode 100644 packages/tourmaline/src/routes/profile/[did]/Dataset.svelte
 create mode 100644 packages/tourmaline/src/routes/profile/[did]/DatasetItemModal.svelte
 create mode 100644 packages/tourmaline/src/routes/profile/[did]/DatasetRankChart.svelte

diff --git a/packages/tourmaline/src/lib/chart.ts b/packages/tourmaline/src/lib/chart.ts
index d1a9e24..4eb4338 100644
--- a/packages/tourmaline/src/lib/chart.ts
+++ b/packages/tourmaline/src/lib/chart.ts
@@ -11,6 +11,7 @@ import {
   BarController,
   BarElement,
   RadarController,
+  LineController,
   PointElement,
   LineElement,
   RadialLinearScale,
@@ -25,6 +26,7 @@ Chart.register(
   BarController,
   BarElement,
   RadarController,
+  LineController,
   PointElement,
   LineElement,
   RadialLinearScale,
diff --git a/packages/tourmaline/src/routes/profile/[did]/+page.svelte b/packages/tourmaline/src/routes/profile/[did]/+page.svelte
index 3029751..3046457 100644
--- a/packages/tourmaline/src/routes/profile/[did]/+page.svelte
+++ b/packages/tourmaline/src/routes/profile/[did]/+page.svelte
@@ -49,6 +49,7 @@
 	import HabitsTab from './HabitsTab.svelte';
 	import CatalogueTab from './CatalogueTab.svelte';
 	import PunchcardHeatmap from './PunchcardHeatmap.svelte';
+	import Dataset from './Dataset.svelte';
 	import EddingtonChart from './EddingtonChart.svelte';
 	import Recommendations from './Recommendations.svelte';
 	import TrackPreview from '$lib/components/TrackPreview.svelte';
@@ -512,6 +513,15 @@
 
 		<!-- ── Catalogue tab ─────────────────────────────── -->
 		{:else if activeTab === 'catalogue'}
+			<Dataset
+				topArtists={profile.topArtists}
+				topTracks={profile.topTracks}
+				topAlbums={profile.topAlbums}
+				artistRankHistory={profile.artistRankHistory}
+				topArtistsByWeeksActive={profile.topArtistsByWeeksActive}
+				monthlyArtistPlays={profile.monthlyArtistPlays}
+			/>
+
 			<!-- Top artists -->
 			<div class="mb-6 overflow-hidden rounded border border-[var(--border)] bg-[var(--surface)] p-3 sm:mb-8 sm:p-4">
 				<div class="mb-3 flex items-center justify-between sm:mb-4">
diff --git a/packages/tourmaline/src/routes/profile/[did]/CountUp.svelte b/packages/tourmaline/src/routes/profile/[did]/CountUp.svelte
new file mode 100644
index 0000000..1cc04c7
--- /dev/null
+++ b/packages/tourmaline/src/routes/profile/[did]/CountUp.svelte
@@ -0,0 +1,41 @@
+<script lang="ts">
+	/**
+	 * Small reusable "count up from 0" number, used by the dataset detail
+	 * modal's stat tiles. Re-runs whenever `value` changes (e.g. a new item
+	 * is selected), so it's safe to mount once and swap props.
+	 */
+	let {
+		value,
+		duration = 700,
+		formatter = (n: number) => Math.round(n).toLocaleString()
+	}: {
+		value: number;
+		duration?: number;
+		formatter?: (n: number) => string;
+	} = $props();
+
+	let display = $state(0);
+
+	$effect(() => {
+		const target = value;
+		const start = performance.now();
+		let raf: number;
+
+		function tick(now: number) {
+			const elapsed = now - start;
+			const t = Math.min(1, duration <= 0 ? 1 : elapsed / duration);
+			// ease-out cubic
+			const eased = 1 - Math.pow(1 - t, 3);
+			display = target * eased;
+			if (t < 1) {
+				raf = requestAnimationFrame(tick);
+			} else {
+				display = target;
+			}
+		}
+		raf = requestAnimationFrame(tick);
+		return () => cancelAnimationFrame(raf);
+	});
+</script>
+
+{formatter(display)}
diff --git a/packages/tourmaline/src/routes/profile/[did]/Dataset.svelte b/packages/tourmaline/src/routes/profile/[did]/Dataset.svelte
new file mode 100644
index 0000000..ba111a1
--- /dev/null
+++ b/packages/tourmaline/src/routes/profile/[did]/Dataset.svelte
@@ -0,0 +1,231 @@
+<script lang="ts">
+	/**
+	 * Sortable, searchable dataset explorer over the top-50 artists/tracks/
+	 * albums, with CSV export and a per-item detail modal. Ported (in
+	 * spirit) from lastfm-stats-web's dataset table — scoped down to the
+	 * aggregator's top-50 cap rather than the full listening history, since
+	 * lifting that cap needs aggregator.ts changes out of scope here.
+	 */
+	import { Table2, Search, ArrowUp, ArrowDown, ArrowUpDown, Download } from '@lucide/svelte';
+	import type { RankSnapshot } from '$lib/analysis/rank-history';
+	import DatasetItemModal, { type DatasetCategory, type DatasetRow } from './DatasetItemModal.svelte';
+
+	let {
+		topArtists,
+		topTracks,
+		topAlbums,
+		artistRankHistory,
+		topArtistsByWeeksActive,
+		monthlyArtistPlays
+	}: {
+		topArtists: Array<{ name: string; count: number; imageUrl?: string }>;
+		topTracks: Array<{ name: string; artist: string; count: number }>;
+		topAlbums: Array<{ name: string; artist: string; count: number }>;
+		artistRankHistory: Array<[string, RankSnapshot[]]>;
+		topArtistsByWeeksActive: Array<{ name: string; weeksActive: number; count: number }>;
+		monthlyArtistPlays: Array<[string, Array<[string, number]>]>;
+	} = $props();
+
+	const CATEGORIES: Array<{ id: DatasetCategory; label: string }> = [
+		{ id: 'artists', label: 'Artists' },
+		{ id: 'tracks', label: 'Tracks' },
+		{ id: 'albums', label: 'Albums' }
+	];
+
+	type SortKey = 'rank' | 'name' | 'artist' | 'count';
+
+	let category = $state<DatasetCategory>('artists');
+	let search = $state('');
+	let sortKey = $state<SortKey>('rank');
+	let sortDir = $state<'asc' | 'desc'>('asc');
+	let selected = $state<DatasetRow | null>(null);
+
+	const baseRows = $derived.by((): DatasetRow[] => {
+		if (category === 'artists') {
+			return topArtists.map((a, i) => ({ rank: i + 1, name: a.name, count: a.count }));
+		}
+		if (category === 'tracks') {
+			return topTracks.map((t, i) => ({ rank: i + 1, name: t.name, artist: t.artist, count: t.count }));
+		}
+		return topAlbums.map((a, i) => ({ rank: i + 1, name: a.name, artist: a.artist, count: a.count }));
+	});
+
+	const rows = $derived.by(() => {
+		const q = search.trim().toLowerCase();
+		const filtered = q
+			? baseRows.filter((r) => r.name.toLowerCase().includes(q) || (r.artist ?? '').toLowerCase().includes(q))
+			: baseRows;
+
+		const sorted = [...filtered].sort((a, b) => {
+			let cmp = 0;
+			if (sortKey === 'rank') cmp = a.rank - b.rank;
+			else if (sortKey === 'name') cmp = a.name.localeCompare(b.name);
+			else if (sortKey === 'artist') cmp = (a.artist ?? '').localeCompare(b.artist ?? '');
+			else cmp = a.count - b.count;
+			return sortDir === 'asc' ? cmp : -cmp;
+		});
+		return sorted;
+	});
+
+	function sortBy(key: SortKey) {
+		if (sortKey === key) {
+			sortDir = sortDir === 'asc' ? 'desc' : 'asc';
+		} else {
+			sortKey = key;
+			sortDir = key === 'count' ? 'desc' : 'asc';
+		}
+	}
+
+	function csvField(value: string): string {
+		if (/[",\n]/.test(value)) return `"${value.replace(/"/g, '""')}"`;
+		return value;
+	}
+
+	function exportCsv() {
+		const headers =
+			category === 'artists' ? ['Rank', 'Name', 'Scrobbles'] : ['Rank', 'Name', 'Artist', 'Scrobbles'];
+		const lines = [headers.join(',')];
+		for (const r of rows) {
+			const cells =
+				category === 'artists'
+					? [String(r.rank), csvField(r.name), String(r.count)]
+					: [String(r.rank), csvField(r.name), csvField(r.artist ?? ''), String(r.count)];
+			lines.push(cells.join(','));
+		}
+		const csv = lines.join('\n');
+		const blob = new Blob([csv], { type: 'text/csv' });
+		const url = URL.createObjectURL(blob);
+		const a = document.createElement('a');
+		a.href = url;
+		a.download = `tourmaline-${category}.csv`;
+		document.body.appendChild(a);
+		a.click();
+		a.remove();
+		URL.revokeObjectURL(url);
+	}
+</script>
+
+{#snippet sortIcon(key: SortKey)}
+	{#if sortKey === key}
+		{#if sortDir === 'asc'}
+			<ArrowUp size={12} />
+		{:else}
+			<ArrowDown size={12} />
+		{/if}
+	{:else}
+		<ArrowUpDown size={12} class="opacity-30" />
+	{/if}
+{/snippet}
+
+<div class="mb-6 overflow-hidden rounded border border-[var(--border)] bg-[var(--surface)] p-3 sm:mb-8 sm:p-4">
+	<div class="mb-3 flex items-start justify-between gap-4 sm:mb-4">
+		<div>
+			<h2 class="text-base font-semibold sm:text-lg">Dataset Explorer</h2>
+			<p class="text-xs text-[var(--text-dim)]">
+				Search, sort, and export your top 50 artists, tracks, and albums
+			</p>
+		</div>
+		<div class="shrink-0 text-[var(--accent)]">
+			<Table2 size={18} />
+		</div>
+	</div>
+
+	<div class="mb-3 flex flex-wrap items-center gap-2 sm:mb-4">
+		<div class="flex flex-wrap gap-2" role="radiogroup" aria-label="Dataset category">
+			{#each CATEGORIES as cat (cat.id)}
+				<button
+					class="rounded-full border px-3 py-1 text-xs font-medium transition-colors {category === cat.id
+						? 'border-[var(--accent)] bg-[var(--accent)]/10 text-[var(--accent)]'
+						: 'border-[var(--border)] text-[var(--text-muted)] hover:border-[var(--accent)]/40 hover:text-[var(--text)]'}"
+					onclick={() => (category = cat.id)}
+					role="radio"
+					aria-checked={category === cat.id}
+				>
+					{cat.label}
+				</button>
+			{/each}
+		</div>
+
+		<div class="relative min-w-[140px] flex-1">
+			<Search size={14} class="pointer-events-none absolute top-1/2 left-2 -translate-y-1/2 text-[var(--text-dim)]" />
+			<input
+				type="text"
+				placeholder="Search {category}..."
+				bind:value={search}
+				class="w-full rounded border border-[var(--border)] bg-[var(--surface-2)] py-1.5 pr-2 pl-7 text-xs text-[var(--text)] placeholder:text-[var(--text-dim)] focus:border-[var(--accent)] focus:outline-none sm:text-sm"
+			/>
+		</div>
+
+		<button
+			onclick={exportCsv}
+			class="flex shrink-0 items-center gap-1.5 rounded border border-[var(--border)] px-2.5 py-1.5 text-xs text-[var(--text-muted)] transition-colors hover:border-[var(--accent)] hover:text-[var(--accent)] sm:text-sm"
+		>
+			<Download size={14} />
+			Export CSV
+		</button>
+	</div>
+
+	<div class="overflow-x-auto">
+		<table class="w-full text-left text-xs sm:text-sm">
+			<thead>
+				<tr class="border-b border-[var(--border)] text-[var(--text-dim)]">
+					<th class="cursor-pointer py-1.5 pr-2 font-medium select-none">
+						<button class="inline-flex items-center gap-1" onclick={() => sortBy('rank')}>
+							#{@render sortIcon('rank')}
+						</button>
+					</th>
+					<th class="cursor-pointer py-1.5 pr-2 font-medium select-none">
+						<button class="inline-flex items-center gap-1" onclick={() => sortBy('name')}>
+							Name{@render sortIcon('name')}
+						</button>
+					</th>
+					{#if category !== 'artists'}
+						<th class="cursor-pointer py-1.5 pr-2 font-medium select-none">
+							<button class="inline-flex items-center gap-1" onclick={() => sortBy('artist')}>
+								Artist{@render sortIcon('artist')}
+							</button>
+						</th>
+					{/if}
+					<th class="cursor-pointer py-1.5 text-right font-medium select-none">
+						<button class="inline-flex items-center gap-1" onclick={() => sortBy('count')}>
+							Scrobbles{@render sortIcon('count')}
+						</button>
+					</th>
+				</tr>
+			</thead>
+			<tbody>
+				{#each rows as row (category + row.rank + row.name)}
+					<tr
+						class="cursor-pointer border-b border-[var(--border-subtle)] transition-colors hover:bg-[var(--surface-2)]"
+						onclick={() => (selected = row)}
+					>
+						<td class="py-1.5 pr-2 text-[var(--text-muted)]">{row.rank}</td>
+						<td class="max-w-[220px] truncate py-1.5 pr-2">{row.name}</td>
+						{#if category !== 'artists'}
+							<td class="max-w-[180px] truncate py-1.5 pr-2 text-[var(--text-muted)]">{row.artist}</td>
+						{/if}
+						<td class="py-1.5 text-right font-mono text-[var(--text-muted)]">{row.count.toLocaleString()}</td>
+					</tr>
+				{/each}
+				{#if rows.length === 0}
+					<tr>
+						<td colspan={category === 'artists' ? 3 : 4} class="py-4 text-center text-[var(--text-dim)]">
+							No matches
+						</td>
+					</tr>
+				{/if}
+			</tbody>
+		</table>
+	</div>
+</div>
+
+{#if selected}
+	<DatasetItemModal
+		row={selected}
+		{category}
+		{artistRankHistory}
+		{topArtistsByWeeksActive}
+		{monthlyArtistPlays}
+		onClose={() => (selected = null)}
+	/>
+{/if}
diff --git a/packages/tourmaline/src/routes/profile/[did]/DatasetItemModal.svelte b/packages/tourmaline/src/routes/profile/[did]/DatasetItemModal.svelte
new file mode 100644
index 0000000..de98034
--- /dev/null
+++ b/packages/tourmaline/src/routes/profile/[did]/DatasetItemModal.svelte
@@ -0,0 +1,144 @@
+<script lang="ts">
+	/**
+	 * Detail modal for a single row clicked in the dataset explorer
+	 * (Dataset.svelte). Shows animated stat tiles for every category, plus
+	 * an artist-only rank-over-time chart — tracks/albums don't have a
+	 * per-month rank history in this codebase (see rank-history.ts).
+	 */
+	import { X } from '@lucide/svelte';
+	import type { RankSnapshot } from '$lib/analysis/rank-history';
+	import CountUp from './CountUp.svelte';
+	import DatasetRankChart from './DatasetRankChart.svelte';
+
+	export type DatasetCategory = 'artists' | 'tracks' | 'albums';
+	export interface DatasetRow {
+		rank: number;
+		name: string;
+		artist?: string;
+		count: number;
+	}
+
+	let {
+		row,
+		category,
+		artistRankHistory,
+		topArtistsByWeeksActive,
+		monthlyArtistPlays,
+		onClose
+	}: {
+		row: DatasetRow;
+		category: DatasetCategory;
+		artistRankHistory: Array<[string, RankSnapshot[]]>;
+		topArtistsByWeeksActive: Array<{ name: string; weeksActive: number; count: number }>;
+		monthlyArtistPlays: Array<[string, Array<[string, number]>]>;
+		onClose: () => void;
+	} = $props();
+
+	const isArtist = $derived(category === 'artists');
+
+	const history = $derived.by((): RankSnapshot[] => {
+		if (!isArtist) return [];
+		return artistRankHistory.find(([name]) => name === row.name)?.[1] ?? [];
+	});
+
+	const weeksActive = $derived.by((): number | null => {
+		if (!isArtist) return null;
+		return topArtistsByWeeksActive.find((a) => a.name === row.name)?.weeksActive ?? null;
+	});
+
+	const bestRank = $derived(history.length > 0 ? Math.min(...history.map((h) => h.rank)) : null);
+
+	const bestMonth = $derived.by((): number | null => {
+		if (!isArtist) return null;
+		let best = 0;
+		for (const [, artists] of monthlyArtistPlays) {
+			for (const [name, count] of artists) {
+				if (name === row.name && count > best) best = count;
+			}
+		}
+		return best > 0 ? best : null;
+	});
+
+	function handleKeydown(e: KeyboardEvent) {
+		if (e.key === 'Escape') onClose();
+	}
+</script>
+
+<svelte:window onkeydown={handleKeydown} />
+
+<div
+	class="fixed inset-0 z-50 flex items-center justify-center bg-black/60 p-4"
+	onclick={onClose}
+	onkeydown={(e) => e.key === 'Enter' && onClose()}
+	role="button"
+	tabindex="-1"
+>
+	<div
+		class="max-h-[85vh] w-full max-w-lg overflow-y-auto rounded border border-[var(--border)] bg-[var(--surface)] p-4 sm:p-6"
+		onclick={(e) => e.stopPropagation()}
+		onkeydown={(e) => e.stopPropagation()}
+		role="dialog"
+		aria-modal="true"
+		aria-labelledby="dataset-modal-title"
+		tabindex="-1"
+	>
+		<div class="mb-4 flex items-start justify-between gap-4">
+			<div class="min-w-0">
+				<h2 id="dataset-modal-title" class="truncate text-lg font-semibold sm:text-xl">{row.name}</h2>
+				{#if row.artist}
+					<p class="truncate text-sm text-[var(--text-muted)]">{row.artist}</p>
+				{/if}
+			</div>
+			<button
+				onclick={onClose}
+				class="shrink-0 rounded p-1 text-[var(--text-muted)] transition-colors hover:text-[var(--text)]"
+				aria-label="Close"
+			>
+				<X size={20} />
+			</button>
+		</div>
+
+		<div class="mb-4 grid grid-cols-2 gap-3 sm:gap-4">
+			<div class="rounded border border-[var(--border)] bg-[var(--surface-2)] p-3">
+				<p class="text-xs text-[var(--text-dim)]">Total scrobbles</p>
+				<p class="text-xl font-semibold text-[var(--accent)] sm:text-2xl">
+					<CountUp value={row.count} />
+				</p>
+			</div>
+
+			{#if isArtist && weeksActive !== null}
+				<div class="rounded border border-[var(--border)] bg-[var(--surface-2)] p-3">
+					<p class="text-xs text-[var(--text-dim)]">Weeks active</p>
+					<p class="text-xl font-semibold text-[var(--accent)] sm:text-2xl">
+						<CountUp value={weeksActive} />
+					</p>
+				</div>
+			{/if}
+
+			{#if isArtist && bestRank !== null}
+				<div class="rounded border border-[var(--border)] bg-[var(--surface-2)] p-3">
+					<p class="text-xs text-[var(--text-dim)]">Best rank ever</p>
+					<p class="text-xl font-semibold text-[var(--accent)] sm:text-2xl">
+						#<CountUp value={bestRank} />
+					</p>
+				</div>
+			{/if}
+
+			{#if isArtist && bestMonth !== null}
+				<div class="rounded border border-[var(--border)] bg-[var(--surface-2)] p-3">
+					<p class="text-xs text-[var(--text-dim)]">Best month</p>
+					<p class="text-xl font-semibold text-[var(--accent)] sm:text-2xl">
+						<CountUp value={bestMonth} />
+					</p>
+				</div>
+			{/if}
+		</div>
+
+		{#if isArtist && history.length > 0}
+			<div>
+				<h3 class="mb-2 text-sm font-medium text-[var(--text-muted)]">Rank over time</h3>
+				<DatasetRankChart {history} />
+			</div>
+		{/if}
+	</div>
+</div>
diff --git a/packages/tourmaline/src/routes/profile/[did]/DatasetRankChart.svelte b/packages/tourmaline/src/routes/profile/[did]/DatasetRankChart.svelte
new file mode 100644
index 0000000..d4cfd84
--- /dev/null
+++ b/packages/tourmaline/src/routes/profile/[did]/DatasetRankChart.svelte
@@ -0,0 +1,85 @@
+<script lang="ts">
+	/**
+	 * Rank-over-time line chart for one artist, used inside the dataset
+	 * explorer's item detail modal. Y-axis is reversed since a lower rank
+	 * number (#1, #2, ...) is "better".
+	 */
+	import { onDestroy } from 'svelte';
+	import { Chart } from '$lib/chart';
+	import type { RankSnapshot } from '$lib/analysis/rank-history';
+
+	let { history }: { history: RankSnapshot[] } = $props();
+
+	let canvas: HTMLCanvasElement;
+	let chart: Chart | null = null;
+
+	$effect(() => {
+		if (!canvas || history.length === 0) return;
+
+		const sorted = [...history].sort((a, b) => a.month.localeCompare(b.month));
+		const labels = sorted.map((h) => h.month);
+		const data = sorted.map((h) => h.rank);
+
+		if (chart) {
+			chart.data.labels = labels;
+			chart.data.datasets[0].data = data;
+			chart.update('none');
+			return;
+		}
+
+		chart = new Chart(canvas, {
+			type: 'line',
+			data: {
+				labels,
+				datasets: [
+					{
+						data,
+						borderColor: '#4ade80',
+						backgroundColor: 'rgba(74,222,128,0.15)',
+						fill: true,
+						tension: 0.2,
+						pointRadius: 2
+					}
+				]
+			},
+			options: {
+				responsive: true,
+				maintainAspectRatio: false,
+				animation: false,
+				plugins: {
+					legend: { display: false },
+					tooltip: {
+						callbacks: {
+							label(ctx) {
+								return `Rank #${ctx.parsed.y}`;
+							}
+						}
+					}
+				},
+				scales: {
+					x: {
+						ticks: { color: '#9ca3af', font: { size: 10 }, maxRotation: 0 },
+						grid: { display: false }
+					},
+					y: {
+						reverse: true,
+						ticks: { color: '#9ca3af', font: { size: 10 }, precision: 0 },
+						grid: { color: 'rgba(255,255,255,0.05)' },
+						title: {
+							display: true,
+							text: 'Rank (lower is better)',
+							color: '#6b7280',
+							font: { size: 11 }
+						}
+					}
+				}
+			}
+		});
+	});
+
+	onDestroy(() => chart?.destroy());
+</script>
+
+<div class="h-48 sm:h-56">
+	<canvas bind:this={canvas}></canvas>
+</div>
-- 
2.51.2