From 9ff8423da692832e15db26426793ee5b334aed01 Mon Sep 17 00:00:00 2001
From: Marcel <marcel@familienarchiv>
Date: Wed, 15 Apr 2026 20:03:04 +0200
Subject: [PATCH] feat(search): highlight snippet terms and mark
 sender/receiver/tag matches in document list

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 frontend/src/lib/generated/api.ts             |   1 +
 frontend/src/routes/DocumentList.svelte       |  58 +++++-
 .../src/routes/DocumentList.svelte.spec.ts    | 183 +++++++++++++++++-
 3 files changed, 226 insertions(+), 16 deletions(-)

diff --git a/frontend/src/lib/generated/api.ts b/frontend/src/lib/generated/api.ts
index a111e919..e9e24790 100644
--- a/frontend/src/lib/generated/api.ts
+++ b/frontend/src/lib/generated/api.ts
@@ -1607,6 +1607,7 @@ export interface components {
             senderMatched: boolean;
             matchedReceiverIds: string[];
             matchedTagIds: string[];
+            snippetOffsets: components["schemas"]["MatchOffset"][];
         };
         IncompleteDocumentDTO: {
             /** Format: uuid */
diff --git a/frontend/src/routes/DocumentList.svelte b/frontend/src/routes/DocumentList.svelte
index 02fe7467..03bd27dc 100644
--- a/frontend/src/routes/DocumentList.svelte
+++ b/frontend/src/routes/DocumentList.svelte
@@ -22,8 +22,13 @@ let {
 		originalFilename: string;
 		documentDate?: string | null;
 		location?: string | null;
-		sender?: { firstName?: string | null; lastName: string; displayName: string } | null;
-		receivers?: { firstName?: string | null; lastName: string; displayName: string }[];
+		sender?: {
+			id?: string;
+			firstName?: string | null;
+			lastName: string;
+			displayName: string;
+		} | null;
+		receivers?: { id?: string; firstName?: string | null; lastName: string; displayName: string }[];
 		tags?: { id: string; name: string }[];
 	}[];
 	canWrite: boolean;
@@ -80,9 +85,14 @@ const showDividers = $derived(groupedDocuments.length >= 2);
 			<ul class="divide-y divide-line-2">
 				{#each group.documents as doc (doc.id)}
 					{@const titleText = doc.title || doc.originalFilename}
-					{@const titleOffsets = matchData?.[doc.id]?.titleOffsets ?? []}
+					{@const match = matchData?.[doc.id]}
+					{@const titleOffsets = match?.titleOffsets ?? []}
 					{@const titleSegments = applyOffsets(titleText, titleOffsets)}
-					{@const snippet = matchData?.[doc.id]?.transcriptionSnippet}
+					{@const snippet = match?.transcriptionSnippet}
+					{@const snippetSegments = snippet ? applyOffsets(snippet, match?.snippetOffsets ?? []) : null}
+					{@const senderMatched = match?.senderMatched ?? false}
+					{@const matchedReceiverIds = new Set(match?.matchedReceiverIds ?? [])}
+					{@const matchedTagIds = new Set(match?.matchedTagIds ?? [])}
 					<li class="group transition-colors duration-200 hover:bg-muted/50">
 						<a href="/documents/{doc.id}" class="block p-6">
 							<div class="flex flex-col gap-6 sm:flex-row">
@@ -123,12 +133,17 @@ const showDividers = $derived(groupedDocuments.length >= 2);
 										{/if}
 									</div>
 
-									{#if snippet}
+									{#if snippetSegments}
 										<p
 											data-testid="search-snippet"
 											class="mb-4 line-clamp-2 font-sans text-sm text-ink-2 italic"
 										>
-											<span class="sr-only">Fundstelle: </span>{snippet}
+											<span class="sr-only"
+												>Fundstelle:
+											</span>{#each snippetSegments as seg, i (i)}{#if seg.highlight}<mark
+														class="bg-accent/20 text-inherit not-italic group-hover:bg-accent/30"
+														>{seg.text}</mark
+													>{:else}{seg.text}{/if}{/each}
 										</p>
 									{/if}
 
@@ -140,7 +155,15 @@ const showDividers = $derived(groupedDocuments.length >= 2);
 												>{m.docs_list_from()}</span
 											>
 											{#if doc.sender}
-												<span class="text-ink">{doc.sender.displayName}</span>
+												{#if senderMatched}
+													<mark
+														data-testid="sender-match"
+														class="bg-accent/20 text-inherit group-hover:bg-accent/30"
+														>{doc.sender.displayName}</mark
+													>
+												{:else}
+													<span class="text-ink">{doc.sender.displayName}</span>
+												{/if}
 											{:else}
 												<span class="text-ink-3 italic">{m.docs_list_unknown()}</span>
 											{/if}
@@ -152,7 +175,18 @@ const showDividers = $derived(groupedDocuments.length >= 2);
 											>
 											{#if doc.receivers && doc.receivers.length > 0}
 												<span class="text-ink">
-													{doc.receivers.map((p) => p.displayName).join(', ')}
+													{#each doc.receivers as receiver, ri (receiver.id ?? ri)}
+														{#if ri > 0}<span>, </span>{/if}
+														{#if receiver.id && matchedReceiverIds.has(receiver.id)}
+															<mark
+																data-testid="receiver-match"
+																class="bg-accent/20 text-inherit group-hover:bg-accent/30"
+																>{receiver.displayName}</mark
+															>
+														{:else}
+															{receiver.displayName}
+														{/if}
+													{/each}
 												</span>
 											{:else}
 												<span class="text-ink-3 italic">{m.docs_list_unknown()}</span>
@@ -166,14 +200,18 @@ const showDividers = $derived(groupedDocuments.length >= 2);
 											{#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"
+													class="relative z-10 inline-flex cursor-pointer items-center rounded px-2 py-1 text-[10px] font-bold tracking-widest uppercase transition-colors hover:bg-primary hover:text-primary-fg {matchedTagIds.has(tag.id) ? 'bg-accent/20 text-ink' : 'bg-muted text-ink'}"
 													onclick={(e) => {
 														e.preventDefault();
 														e.stopPropagation();
 														goto(`/?tag=${encodeURIComponent(tag.name)}`);
 													}}
 												>
-													{tag.name}
+													{#if matchedTagIds.has(tag.id)}
+														<span data-testid="tag-match">{tag.name}</span>
+													{:else}
+														{tag.name}
+													{/if}
 												</button>
 											{/each}
 										</div>
diff --git a/frontend/src/routes/DocumentList.svelte.spec.ts b/frontend/src/routes/DocumentList.svelte.spec.ts
index f3c1f293..538de391 100644
--- a/frontend/src/routes/DocumentList.svelte.spec.ts
+++ b/frontend/src/routes/DocumentList.svelte.spec.ts
@@ -23,8 +23,9 @@ type DocOverrides = {
 	id?: string;
 	title?: string;
 	documentDate?: string | null;
-	sender?: { firstName?: string | null; lastName: string; displayName: string } | null;
-	receivers?: { firstName?: string | null; lastName: string; displayName: string }[];
+	sender?: { id?: string; firstName?: string | null; lastName: string; displayName: string } | null;
+	receivers?: { id?: string; firstName?: string | null; lastName: string; displayName: string }[];
+	tags?: { id: string; name: string }[];
 };
 
 const makeDoc = (overrides: DocOverrides = {}) => ({
@@ -35,7 +36,12 @@ const makeDoc = (overrides: DocOverrides = {}) => ({
 	documentDate: '2024-03-15',
 	location: null,
 	sender: null,
-	receivers: [] as { firstName?: string | null; lastName: string; displayName: string }[],
+	receivers: [] as {
+		id?: string;
+		firstName?: string | null;
+		lastName: string;
+		displayName: string;
+	}[],
 	tags: [],
 	...overrides
 });
@@ -136,7 +142,8 @@ describe('DocumentList – match snippets and highlights', () => {
 					titleOffsets: [],
 					senderMatched: false,
 					matchedReceiverIds: [],
-					matchedTagIds: []
+					matchedTagIds: [],
+					snippetOffsets: []
 				}
 			}
 		});
@@ -161,7 +168,8 @@ describe('DocumentList – match snippets and highlights', () => {
 					titleOffsets: [{ start: 0, length: 5 }], // "Brief"
 					senderMatched: false,
 					matchedReceiverIds: [],
-					matchedTagIds: []
+					matchedTagIds: [],
+					snippetOffsets: []
 				}
 			}
 		});
@@ -183,11 +191,174 @@ describe('DocumentList – match snippets and highlights', () => {
 					titleOffsets: [],
 					senderMatched: false,
 					matchedReceiverIds: [],
-					matchedTagIds: []
+					matchedTagIds: [],
+					snippetOffsets: []
 				}
 			}
 		});
 		await expect.element(page.getByRole('mark')).not.toBeInTheDocument();
 		await expect.element(page.getByText('Brief an Anna')).toBeInTheDocument();
 	});
+
+	it('renders <mark> inside snippet when snippetOffsets are present', async () => {
+		const doc = makeDoc({ id: 'doc1' });
+		render(DocumentList, {
+			...baseProps,
+			documents: [doc],
+			total: 1,
+			matchData: {
+				doc1: {
+					transcriptionSnippet: 'Er schrieb einen Brief',
+					titleOffsets: [],
+					senderMatched: false,
+					matchedReceiverIds: [],
+					matchedTagIds: [],
+					snippetOffsets: [{ start: 17, length: 5 }] // "Brief"
+				}
+			}
+		});
+		const snippet = page.getByTestId('search-snippet');
+		await expect.element(snippet).toBeInTheDocument();
+		const mark = snippet.getByRole('mark');
+		await expect.element(mark).toBeInTheDocument();
+		await expect.element(mark).toHaveTextContent('Brief');
+	});
+
+	it('renders snippet as plain text when snippetOffsets is empty', async () => {
+		const doc = makeDoc({ id: 'doc1' });
+		render(DocumentList, {
+			...baseProps,
+			documents: [doc],
+			total: 1,
+			matchData: {
+				doc1: {
+					transcriptionSnippet: 'Er schrieb einen Brief',
+					titleOffsets: [],
+					senderMatched: false,
+					matchedReceiverIds: [],
+					matchedTagIds: [],
+					snippetOffsets: []
+				}
+			}
+		});
+		const snippet = page.getByTestId('search-snippet');
+		await expect.element(snippet).toBeInTheDocument();
+		// No mark elements inside the snippet when offsets is empty
+		await expect.element(snippet.getByRole('mark')).not.toBeInTheDocument();
+	});
+
+	it('visually marks sender when senderMatched is true', async () => {
+		const doc = makeDoc({
+			id: 'doc1',
+			sender: {
+				id: 'sender-1',
+				firstName: 'Walter',
+				lastName: 'Raddatz',
+				displayName: 'Walter Raddatz'
+			}
+		});
+		render(DocumentList, {
+			...baseProps,
+			documents: [doc],
+			total: 1,
+			matchData: {
+				doc1: {
+					transcriptionSnippet: undefined,
+					titleOffsets: [],
+					senderMatched: true,
+					matchedReceiverIds: [],
+					matchedTagIds: [],
+					snippetOffsets: []
+				}
+			}
+		});
+		const senderMark = page.getByTestId('sender-match');
+		await expect.element(senderMark).toBeInTheDocument();
+		await expect.element(senderMark).toHaveTextContent('Walter Raddatz');
+	});
+
+	it('does not mark sender when senderMatched is false', async () => {
+		const doc = makeDoc({
+			id: 'doc1',
+			sender: {
+				id: 'sender-1',
+				firstName: 'Walter',
+				lastName: 'Raddatz',
+				displayName: 'Walter Raddatz'
+			}
+		});
+		render(DocumentList, {
+			...baseProps,
+			documents: [doc],
+			total: 1,
+			matchData: {
+				doc1: {
+					transcriptionSnippet: undefined,
+					titleOffsets: [],
+					senderMatched: false,
+					matchedReceiverIds: [],
+					matchedTagIds: [],
+					snippetOffsets: []
+				}
+			}
+		});
+		await expect.element(page.getByTestId('sender-match')).not.toBeInTheDocument();
+	});
+
+	it('visually marks matched receiver when their id is in matchedReceiverIds', async () => {
+		const doc = makeDoc({
+			id: 'doc1',
+			receivers: [
+				{ id: 'p-1', firstName: 'Anna', lastName: 'Schmidt', displayName: 'Anna Schmidt' },
+				{ id: 'p-2', firstName: 'Karl', lastName: 'Bauer', displayName: 'Karl Bauer' }
+			]
+		});
+		render(DocumentList, {
+			...baseProps,
+			documents: [doc],
+			total: 1,
+			matchData: {
+				doc1: {
+					transcriptionSnippet: undefined,
+					titleOffsets: [],
+					senderMatched: false,
+					matchedReceiverIds: ['p-1'],
+					matchedTagIds: [],
+					snippetOffsets: []
+				}
+			}
+		});
+		// Only Anna Schmidt should be marked
+		const receiverMark = page.getByTestId('receiver-match');
+		await expect.element(receiverMark).toBeInTheDocument();
+		await expect.element(receiverMark).toHaveTextContent('Anna Schmidt');
+	});
+
+	it('visually marks matched tag when its id is in matchedTagIds', async () => {
+		const doc = makeDoc({
+			id: 'doc1',
+			tags: [
+				{ id: 'tag-1', name: 'Familiengeschichte' },
+				{ id: 'tag-2', name: 'Reise' }
+			]
+		});
+		render(DocumentList, {
+			...baseProps,
+			documents: [doc],
+			total: 1,
+			matchData: {
+				doc1: {
+					transcriptionSnippet: undefined,
+					titleOffsets: [],
+					senderMatched: false,
+					matchedReceiverIds: [],
+					matchedTagIds: ['tag-1'],
+					snippetOffsets: []
+				}
+			}
+		});
+		const tagMark = page.getByTestId('tag-match');
+		await expect.element(tagMark).toBeInTheDocument();
+		await expect.element(tagMark).toHaveTextContent('Familiengeschichte');
+	});
 });