feat(search): add group headers to DocumentList by sort field

Documents sorted by DATE show year dividers, SENDER/RECEIVER sort
shows person name dividers. Dividers only appear when there are 2+
distinct groups. Multi-receiver docs appear in each receiver group.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

frontend/src/routes/DocumentList.svelte

@@ -2,13 +2,16 @@
 import { goto } from '$app/navigation';
 import { m } from '$lib/paraglide/messages.js';
 import { formatDate } from '$lib/utils/date';
+import { groupDocuments } from '$lib/utils/groupDocuments';
+import GroupDivider from '$lib/components/GroupDivider.svelte';
 
 let {
 	documents,
 	canWrite,
 	error,
 	total = 0,
-	q = ''
+	q = '',
+	sort
 }: {
 	documents: {
 		id: string;
@@ -24,7 +27,14 @@ let {
 	error?: string | null;
 	total?: number;
 	q?: string;
+	sort?: string;
 } = $props();
+
+const fallbackLabel = $derived(sort === 'DATE' ? m.docs_group_undated() : m.docs_group_unknown());
+const groupedDocuments = $derived.by(() =>
+	groupDocuments(documents, sort ?? 'DATE', fallbackLabel)
+);
+const showDividers = $derived(groupedDocuments.length >= 2);
 </script>
 
 <!-- DOCUMENT LIST HEADER -->
@@ -57,107 +67,112 @@ let {
 			{error}
 		</div>
 	{:else if documents.length > 0}
-		<ul class="divide-y divide-line-2">
+		{#each groupedDocuments as group (group.label)}
-			{#each documents as doc (doc.id)}
+			{#if showDividers}
-				<li class="group transition-colors duration-200 hover:bg-muted/50">
+				<GroupDivider label={group.label} />
-					<a href="/documents/{doc.id}" class="block p-6">
+			{/if}
-						<div class="flex flex-col gap-6 sm:flex-row">
+			<ul class="divide-y divide-line-2">
-							<!-- Main Info -->
+				{#each group.documents as doc (doc.id)}
-							<div class="flex-1">
+					<li class="group transition-colors duration-200 hover:bg-muted/50">
-								<div class="mb-2 flex items-baseline justify-between">
+						<a href="/documents/{doc.id}" class="block p-6">
-									<h3 class="font-serif text-xl font-medium text-ink group-hover:underline">
+							<div class="flex flex-col gap-6 sm:flex-row">
-										{doc.title || doc.originalFilename}
+								<!-- Main Info -->
-									</h3>
+								<div class="flex-1">
-								</div>
+									<div class="mb-2 flex items-baseline justify-between">
-
+										<h3 class="font-serif text-xl font-medium text-ink group-hover:underline">
-								<!-- Metadata Row -->
+											{doc.title || doc.originalFilename}
-								<div class="mb-4 flex flex-wrap gap-6 font-sans text-sm text-ink-2">
+										</h3>
-									<div class="flex items-center">
-										<img
-											src="/degruyter-icons/Simple/Medium-24px/SVG/Action/Calendar/Calendar-Add-MD.svg"
-											alt=""
-											aria-hidden="true"
-											class="mr-1.5 h-4 w-4"
-										/>
-										{doc.documentDate ? formatDate(doc.documentDate) : '—'}
 									</div>
-									{#if doc.location}
+
+									<!-- Metadata Row -->
+									<div class="mb-4 flex flex-wrap gap-6 font-sans text-sm text-ink-2">
 										<div class="flex items-center">
 											<img
-												src="/degruyter-icons/Simple/Medium-24px/SVG/Action/Location-MD.svg"
+												src="/degruyter-icons/Simple/Medium-24px/SVG/Action/Calendar/Calendar-Add-MD.svg"
 												alt=""
 												aria-hidden="true"
 												class="mr-1.5 h-4 w-4"
 											/>
-											{doc.location}
+											{doc.documentDate ? formatDate(doc.documentDate) : '—'}
+										</div>
+										{#if doc.location}
+											<div class="flex items-center">
+												<img
+													src="/degruyter-icons/Simple/Medium-24px/SVG/Action/Location-MD.svg"
+													alt=""
+													aria-hidden="true"
+													class="mr-1.5 h-4 w-4"
+												/>
+												{doc.location}
+											</div>
+										{/if}
+									</div>
+
+									<!-- Sender/Receiver Info -->
+									<div class="grid grid-cols-1 gap-4 font-serif text-sm sm:grid-cols-2">
+										<div class="flex items-baseline">
+											<span
+												class="w-10 font-sans text-xs font-bold tracking-wide text-ink-3 uppercase"
+												>{m.docs_list_from()}</span
+											>
+											{#if doc.sender}
+												<span class="text-ink">{doc.sender.displayName}</span>
+											{:else}
+												<span class="text-ink-3 italic">{m.docs_list_unknown()}</span>
+											{/if}
+										</div>
+										<div class="flex items-baseline">
+											<span
+												class="w-10 font-sans text-xs font-bold tracking-wide text-ink-3 uppercase"
+												>{m.docs_list_to()}</span
+											>
+											{#if doc.receivers && doc.receivers.length > 0}
+												<span class="text-ink">
+													{doc.receivers.map((p) => p.displayName).join(', ')}
+												</span>
+											{:else}
+												<span class="text-ink-3 italic">{m.docs_list_unknown()}</span>
+											{/if}
+										</div>
+									</div>
+
+									<!-- Tags Display -->
+									{#if doc.tags && doc.tags.length > 0}
+										<div class="mt-4 flex flex-wrap gap-2 pt-3">
+											{#each doc.tags as tag (tag.id)}
+												<button
+													type="button"
+													class="relative z-10 inline-flex cursor-pointer items-center rounded bg-muted px-2 py-1 text-[10px] font-bold tracking-widest text-ink uppercase transition-colors hover:bg-primary hover:text-primary-fg"
+													onclick={(e) => {
+														e.preventDefault();
+														e.stopPropagation();
+														goto(`/?tag=${encodeURIComponent(tag.name)}`);
+													}}
+												>
+													{tag.name}
+												</button>
+											{/each}
 										</div>
 									{/if}
 								</div>
 
-								<!-- Sender/Receiver Info -->
+								<!-- Arrow Icon -->
-								<div class="grid grid-cols-1 gap-4 font-serif text-sm sm:grid-cols-2">
+								<div
-									<div class="flex items-baseline">
+									class="hidden items-center text-ink-3 transition-colors group-hover:text-accent sm:flex"
-										<span
+								>
-											class="w-10 font-sans text-xs font-bold tracking-wide text-ink-3 uppercase"
+									<img
-											>{m.docs_list_from()}</span
+										src="/degruyter-icons/Simple/Medium-24px/SVG/Action/Arrow/Arrow-Right-MD.svg"
-										>
+										alt=""
-										{#if doc.sender}
+										aria-hidden="true"
-											<span class="text-ink">{doc.sender.displayName}</span>
+										class="h-6 w-6"
-										{:else}
+									/>
-											<span class="text-ink-3 italic">{m.docs_list_unknown()}</span>
-										{/if}
-									</div>
-									<div class="flex items-baseline">
-										<span
-											class="w-10 font-sans text-xs font-bold tracking-wide text-ink-3 uppercase"
-											>{m.docs_list_to()}</span
-										>
-										{#if doc.receivers && doc.receivers.length > 0}
-											<span class="text-ink">
-												{doc.receivers.map((p) => p.displayName).join(', ')}
-											</span>
-										{:else}
-											<span class="text-ink-3 italic">{m.docs_list_unknown()}</span>
-										{/if}
-									</div>
 								</div>
-
-								<!-- Tags Display -->
-								{#if doc.tags && doc.tags.length > 0}
-									<div class="mt-4 flex flex-wrap gap-2 pt-3">
-										{#each doc.tags as tag (tag.id)}
-											<button
-												type="button"
-												class="relative z-10 inline-flex cursor-pointer items-center rounded bg-muted px-2 py-1 text-[10px] font-bold tracking-widest text-ink uppercase transition-colors hover:bg-primary hover:text-primary-fg"
-												onclick={(e) => {
-													e.preventDefault();
-													e.stopPropagation();
-													goto(`/?tag=${encodeURIComponent(tag.name)}`);
-												}}
-											>
-												{tag.name}
-											</button>
-										{/each}
-									</div>
-								{/if}
 							</div>
-
+						</a>
-							<!-- Arrow Icon -->
+					</li>
-							<div
+				{/each}
-								class="hidden items-center text-ink-3 transition-colors group-hover:text-accent sm:flex"
+			</ul>
-							>
+		{/each}
-								<img
-									src="/degruyter-icons/Simple/Medium-24px/SVG/Action/Arrow/Arrow-Right-MD.svg"
-									alt=""
-									aria-hidden="true"
-									class="h-6 w-6"
-								/>
-							</div>
-						</div>
-					</a>
-				</li>
-			{/each}
-		</ul>
 	{:else}
 		<!-- Empty State -->
 		<div class="p-16 text-center">

frontend/src/routes/DocumentList.svelte.spec.ts

@@ -1,10 +1,12 @@
-import { describe, expect, it, vi } from 'vitest';
+import { describe, expect, it, vi, afterEach } from 'vitest';
-import { render } from 'vitest-browser-svelte';
+import { cleanup, render } from 'vitest-browser-svelte';
 import { page } from 'vitest/browser';
 import DocumentList from './DocumentList.svelte';
 
 vi.mock('$app/navigation', () => ({ goto: vi.fn() }));
 
+afterEach(() => cleanup());
+
 const baseProps = {
 	documents: [],
 	canWrite: false,
@@ -13,7 +15,14 @@ const baseProps = {
 	q: ''
 };
 
-const makeDoc = () => ({
+type DocOverrides = {
+	id?: string;
+	documentDate?: string | null;
+	sender?: { firstName?: string | null; lastName: string; displayName: string } | null;
+	receivers?: { firstName?: string | null; lastName: string; displayName: string }[];
+};
+
+const makeDoc = (overrides: DocOverrides = {}) => ({
 	id: '1',
 	title: 'Testbrief',
 	originalFilename: 'testbrief.pdf',
@@ -21,8 +30,9 @@ const makeDoc = () => ({
 	documentDate: '2024-03-15',
 	location: null,
 	sender: null,
-	receivers: [],
+	receivers: [] as { firstName?: string | null; lastName: string; displayName: string }[],
-	tags: []
+	tags: [],
+	...overrides
 });
 
 describe('DocumentList – result count', () => {
@@ -49,3 +59,50 @@ describe('DocumentList – empty state with search term', () => {
 		await expect.element(page.getByText(/"Urlaub"/)).toBeInTheDocument();
 	});
 });
+
+// ─── Group headers ────────────────────────────────────────────────────────────
+
+describe('DocumentList – group headers', () => {
+	it('renders group-divider elements when DATE sort spans multiple years', async () => {
+		const documents = [
+			makeDoc({ id: '1', documentDate: '1923-04-12' }),
+			makeDoc({ id: '2', documentDate: '1965-08-03' })
+		];
+		render(DocumentList, { ...baseProps, documents, total: 2, sort: 'DATE' });
+		await expect.element(page.getByTestId('group-divider').first()).toBeInTheDocument();
+	});
+
+	it('does not render group-divider when DATE sort has only one distinct year', async () => {
+		const documents = [
+			makeDoc({ id: '1', documentDate: '1938-01-01' }),
+			makeDoc({ id: '2', documentDate: '1938-06-15' })
+		];
+		render(DocumentList, { ...baseProps, documents, total: 2, sort: 'DATE' });
+		await expect.element(page.getByTestId('group-divider')).not.toBeInTheDocument();
+	});
+
+	it('does not render group-divider for TITLE sort', async () => {
+		const documents = [
+			makeDoc({ id: '1', documentDate: '1923-04-12' }),
+			makeDoc({ id: '2', documentDate: '1965-08-03' })
+		];
+		render(DocumentList, { ...baseProps, documents, total: 2, sort: 'TITLE' });
+		await expect.element(page.getByTestId('group-divider')).not.toBeInTheDocument();
+	});
+
+	it('a doc with two receivers appears in both receiver groups', async () => {
+		const documents = [
+			makeDoc({
+				id: '1',
+				receivers: [
+					{ firstName: null, lastName: 'Müller', displayName: 'Anna Müller' },
+					{ firstName: null, lastName: 'Bauer', displayName: 'Karl Bauer' }
+				]
+			})
+		];
+		render(DocumentList, { ...baseProps, documents, total: 1, sort: 'RECEIVER' });
+		const links = page.getByRole('link', { name: /Testbrief/ });
+		await expect.element(links.first()).toBeInTheDocument();
+		await expect.element(links.nth(1)).toBeInTheDocument();
+	});
+});