feat(lesereisen): implement lesereisen

frontend/src/lib/document/DashboardNeedsMetadata.svelte.spec.ts

@@ -52,6 +52,6 @@ describe('DashboardNeedsMetadata', () => {
 	it('uses totalCount in the footer even when topDocs has fewer items', async () => {
 		const docs = [makeDoc('d1', 'Only one')];
 		render(DashboardNeedsMetadata, { topDocs: docs, totalCount: 50 });
-		await expect.element(page.getByRole('link', { name: /50/ })).toBeInTheDocument();
+		await expect.element(page.getByRole('link', { name: /Alle 50/ })).toBeInTheDocument();
 	});
 });

frontend/src/lib/document/DocumentMultiSelect.svelte

@@ -1,21 +1,11 @@
 <script lang="ts">
-import type { components } from '$lib/generated/api';
 import { m } from '$lib/paraglide/messages.js';
 import { clickOutside } from '$lib/shared/actions/clickOutside';
-import { formatDocumentDate, type DatePrecision } from '$lib/shared/utils/documentDate';
-import { getLocale } from '$lib/paraglide/runtime.js';
-
-type DocumentListItem = components['schemas']['DocumentListItem'];
-
-/**
- * Exactly the fields this picker reads — id for selection/dedup, the rest for
- * the honest date label. A full `Document` and a `DocumentListItem` are both
- * structurally assignable, so the search results need no cast.
- */
-type DocumentOption = Pick<
-	DocumentListItem,
-	'id' | 'title' | 'documentDate' | 'metaDatePrecision' | 'metaDateEnd'
->;
+import {
+	createDocumentTypeahead,
+	formatDocumentOption,
+	type DocumentOption
+} from './documentTypeahead';
 
 interface Props {
 	selectedDocuments?: DocumentOption[];
@@ -30,13 +20,16 @@ let {
 }: Props = $props();
 
 let searchTerm = $state('');
-let results: DocumentOption[] = $state([]);
-let showDropdown = $state(false);
-let loading = $state(false);
-let debounceTimer: ReturnType<typeof setTimeout>;
 let inputEl: HTMLInputElement;
 let dropdownStyle = $state('');
 
+const picker = createDocumentTypeahead();
+
+// Filter out already-selected documents from typeahead results.
+const filteredResults = $derived(
+	picker.results.filter((d) => !selectedDocuments.some((s) => s.id === d.id))
+);
+
 function updateDropdownPosition() {
 	if (!inputEl) return;
 	const rect = inputEl.getBoundingClientRect();
@@ -44,57 +37,22 @@ function updateDropdownPosition() {
 }
 
 function handleInput() {
-	showDropdown = true;
-	clearTimeout(debounceTimer);
-	debounceTimer = setTimeout(async () => {
-		if (searchTerm.length < 1) {
-			results = [];
-			return;
-		}
-		loading = true;
-		try {
-			const res = await fetch(`/api/documents/search?q=${encodeURIComponent(searchTerm)}&size=10`);
-			if (res.ok) {
-				const body: { items: DocumentListItem[] } = await res.json();
-				const docs: DocumentOption[] = body.items.map((it) => ({
-					id: it.id,
-					title: it.title,
-					documentDate: it.documentDate,
-					metaDatePrecision: it.metaDatePrecision,
-					metaDateEnd: it.metaDateEnd
-				}));
-				results = docs.filter((d) => !selectedDocuments.some((s) => s.id === d.id));
-			}
-		} catch {
-			results = [];
-		} finally {
-			loading = false;
-		}
-	}, 300);
+	if (searchTerm.trim().length >= 1) {
+		picker.setQuery(searchTerm);
+	} else {
+		picker.close();
+	}
 }
 
 function selectDocument(doc: DocumentOption) {
 	selectedDocuments = [...selectedDocuments, doc];
 	searchTerm = '';
-	showDropdown = false;
-	results = [];
+	picker.close();
 }
 
 function removeDocument(id: string | undefined) {
 	selectedDocuments = selectedDocuments.filter((d) => d.id !== id);
 }
-
-function formatDocLabel(doc: DocumentOption): string {
-	if (!doc.documentDate) return doc.title;
-	const label = formatDocumentDate(
-		doc.documentDate,
-		doc.metaDatePrecision as DatePrecision,
-		doc.metaDateEnd,
-		null,
-		getLocale()
-	);
-	return `${doc.title} · ${label}`;
-}
 </script>
 
 <svelte:window onscroll={updateDropdownPosition} onresize={updateDropdownPosition} />
@@ -103,7 +61,7 @@ function formatDocLabel(doc: DocumentOption): string {
 	<input type="hidden" name={hiddenInputName} value={doc.id} />
 {/each}
 
-<div class="relative" use:clickOutside onclickoutside={() => (showDropdown = false)}>
+<div class="relative" use:clickOutside onclickoutside={() => picker.close()}>
 	<div
 		class="flex min-h-[38px] flex-wrap gap-2 rounded border border-line bg-surface p-2 shadow-sm focus-within:ring-2 focus-within:ring-focus-ring focus-within:outline-none"
 	>
@@ -111,7 +69,7 @@ function formatDocLabel(doc: DocumentOption): string {
 			<span
 				class="inline-flex items-center gap-1 rounded bg-muted px-2 py-1 text-sm font-medium text-ink"
 			>
-				{formatDocLabel(doc)}
+				{formatDocumentOption(doc)}
 				<button
 					type="button"
 					onclick={() => removeDocument(doc.id)}
@@ -136,24 +94,23 @@ function formatDocLabel(doc: DocumentOption): string {
 			autocomplete="off"
 			bind:value={searchTerm}
 			oninput={handleInput}
-			onfocus={() => {
-				updateDropdownPosition();
-				showDropdown = true;
-			}}
+			onfocus={() => updateDropdownPosition()}
 			placeholder={placeholder}
 			class="min-w-[120px] flex-1 border-none bg-transparent p-1 text-sm outline-none focus:ring-0"
 		/>
 	</div>
 
-	{#if showDropdown && (results.length > 0 || loading)}
+	{#if picker.isOpen && (filteredResults.length > 0 || picker.loading || picker.error)}
 		<div
 			style={dropdownStyle}
 			class="ring-opacity-5 z-50 max-h-60 overflow-auto rounded-md bg-surface py-1 text-base shadow-lg ring-1 ring-black sm:text-sm"
 		>
-			{#if loading}
+			{#if picker.loading}
 				<div class="p-2 text-sm text-ink-2">{m.comp_multiselect_loading()}</div>
+			{:else if picker.error}
+				<div role="alert" class="p-2 text-sm text-danger">{m.comp_typeahead_error()}</div>
 			{:else}
-				{#each results as doc (doc.id)}
+				{#each filteredResults as doc (doc.id)}
 					<div
 						class="cursor-pointer py-2 pr-9 pl-3 text-ink select-none hover:bg-muted"
 						onclick={() => selectDocument(doc)}
@@ -161,7 +118,7 @@ function formatDocLabel(doc: DocumentOption): string {
 						role="button"
 						tabindex="0"
 					>
-						{formatDocLabel(doc)}
+						{formatDocumentOption(doc)}
 					</div>
 				{/each}
 			{/if}

frontend/src/lib/document/DocumentMultiSelect.svelte.spec.ts

@@ -2,6 +2,7 @@ import { afterEach, describe, expect, it, vi } from 'vitest';
 import { cleanup, render } from 'vitest-browser-svelte';
 import { page, userEvent } from 'vitest/browser';
 import DocumentMultiSelect from './DocumentMultiSelect.svelte';
+import { m } from '$lib/paraglide/messages.js';
 
 const waitForDebounce = () => new Promise((r) => setTimeout(r, 350));
 
@@ -124,6 +125,28 @@ describe('DocumentMultiSelect — search and select', () => {
 	});
 });
 
+describe('DocumentMultiSelect — search failure', () => {
+	it('shows an error row when the search request fails instead of looking like "no results"', async () => {
+		vi.stubGlobal(
+			'fetch',
+			vi.fn().mockResolvedValue({
+				ok: false,
+				status: 500,
+				json: vi.fn().mockResolvedValue({ code: 'INTERNAL_ERROR' })
+			})
+		);
+
+		render(DocumentMultiSelect);
+
+		await userEvent.fill(page.getByPlaceholder('Dokument suchen…'), 'Eug');
+		await waitForDebounce();
+
+		const alert = page.getByRole('alert');
+		await expect.element(alert).toBeInTheDocument();
+		await expect.element(alert).toHaveTextContent(m.comp_typeahead_error());
+	});
+});
+
 describe('DocumentMultiSelect — remove', () => {
 	it('removes a chip when its × button is clicked', async () => {
 		render(DocumentMultiSelect, {

frontend/src/lib/document/DocumentPickerDropdown.svelte

@@ -0,0 +1,155 @@
+<script lang="ts">
+import { m } from '$lib/paraglide/messages.js';
+import { clickOutside } from '$lib/shared/actions/clickOutside';
+import {
+	createDocumentTypeahead,
+	formatDocumentOption,
+	type DocumentOption
+} from './documentTypeahead';
+
+interface Props {
+	alreadyAddedIds?: Set<string>;
+	placeholder?: string;
+	/** Set when a visible <label for> is wired externally — replaces the aria-label fallback. */
+	inputId?: string;
+	onSelect: (doc: DocumentOption) => void;
+}
+
+let {
+	alreadyAddedIds = new Set(),
+	placeholder = m.journey_add_document(),
+	inputId = undefined,
+	onSelect
+}: Props = $props();
+
+const uid = $props.id();
+const listboxId = `doc-picker-listbox-${uid}`;
+const resolvedInputId = $derived(inputId ?? `doc-picker-input-${uid}`);
+
+const picker = createDocumentTypeahead();
+
+let inputValue = $state('');
+
+const activeOptionId = $derived(
+	picker.isOpen && picker.activeIndex >= 0 && picker.results[picker.activeIndex]
+		? `${listboxId}-option-${picker.activeIndex}`
+		: undefined
+);
+
+function handleInput(e: Event) {
+	const q = (e.currentTarget as HTMLInputElement).value;
+	inputValue = q;
+	picker.setActiveIndex(-1);
+	if (q.trim().length >= 1) {
+		picker.setQuery(q);
+	} else {
+		picker.close();
+	}
+}
+
+function handleSelect(doc: DocumentOption) {
+	if (alreadyAddedIds.has(doc.id!)) return;
+	inputValue = '';
+	picker.close();
+	onSelect(doc);
+}
+
+function handleKeydown(e: KeyboardEvent) {
+	if (!picker.isOpen) return;
+
+	const results = picker.results;
+
+	if (e.key === 'ArrowDown') {
+		e.preventDefault();
+		if (results.length > 0) {
+			picker.setActiveIndex((picker.activeIndex + 1) % results.length);
+		}
+	} else if (e.key === 'ArrowUp') {
+		e.preventDefault();
+		if (results.length > 0) {
+			picker.setActiveIndex((picker.activeIndex - 1 + results.length) % results.length);
+		}
+	} else if (e.key === 'Enter') {
+		e.preventDefault();
+		const active = results[picker.activeIndex];
+		// handleSelect is a no-op for already-added (aria-disabled) options.
+		if (active) handleSelect(active);
+	} else if (e.key === 'Escape') {
+		e.preventDefault();
+		picker.close();
+	}
+}
+</script>
+
+<div use:clickOutside onclickoutside={() => picker.close()} class="relative">
+	<input
+		type="text"
+		role="combobox"
+		autocomplete="off"
+		id={resolvedInputId}
+		aria-label={inputId ? undefined : placeholder}
+		aria-expanded={picker.isOpen}
+		aria-controls={picker.isOpen && !picker.loading && !picker.error && picker.results.length > 0
+			? listboxId
+			: undefined}
+		aria-autocomplete="list"
+		aria-activedescendant={activeOptionId}
+		placeholder={placeholder}
+		value={inputValue}
+		oninput={handleInput}
+		onkeydown={handleKeydown}
+		class="block w-full rounded border border-line bg-surface px-3 py-2 text-sm text-ink placeholder:text-ink-3 focus:outline-none focus-visible:ring-2 focus-visible:ring-focus-ring"
+	/>
+
+	{#if picker.isOpen}
+		{#if picker.loading}
+			<div
+				class="ring-opacity-5 absolute z-50 mt-1 w-full rounded-md bg-surface py-1 text-sm shadow-lg ring-1 ring-black"
+			>
+				<p role="status" class="px-3 py-2 text-ink-2">{m.comp_multiselect_loading()}</p>
+			</div>
+		{:else if picker.error}
+			<div
+				class="ring-opacity-5 absolute z-50 mt-1 w-full rounded-md bg-surface py-1 text-sm shadow-lg ring-1 ring-black"
+			>
+				<p role="alert" class="px-3 py-2 text-danger">{m.comp_typeahead_error()}</p>
+			</div>
+		{:else if picker.results.length === 0}
+			<div
+				class="ring-opacity-5 absolute z-50 mt-1 w-full rounded-md bg-surface py-1 text-sm shadow-lg ring-1 ring-black"
+			>
+				<p role="status" class="px-3 py-2 text-ink-2">{m.comp_typeahead_no_results()}</p>
+			</div>
+		{:else}
+			<ul
+				id={listboxId}
+				role="listbox"
+				class="ring-opacity-5 absolute z-50 mt-1 max-h-60 w-full overflow-auto rounded-md bg-surface py-1 text-sm shadow-lg ring-1 ring-black"
+			>
+				{#each picker.results as doc, i (doc.id)}
+					{@const disabled = alreadyAddedIds.has(doc.id!)}
+					<!-- svelte-ignore a11y_click_events_have_key_events -->
+					<li
+						id={`${listboxId}-option-${i}`}
+						role="option"
+						aria-selected={i === picker.activeIndex}
+						aria-disabled={disabled}
+						onclick={() => handleSelect(doc)}
+						class={[
+							'px-3 py-2 text-ink select-none',
+							i === picker.activeIndex ? 'bg-muted' : '',
+							disabled
+								? 'cursor-default opacity-50'
+								: 'cursor-pointer hover:bg-muted'
+						].join(' ')}
+					>
+						{formatDocumentOption(doc)}
+						{#if disabled}
+							<span class="sr-only">{m.journey_already_added()}</span>
+						{/if}
+					</li>
+				{/each}
+			</ul>
+		{/if}
+	{/if}
+</div>

frontend/src/lib/document/DocumentPickerDropdown.svelte.spec.ts

@@ -0,0 +1,261 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { cleanup, render } from 'vitest-browser-svelte';
+import { page, userEvent } from 'vitest/browser';
+import DocumentPickerDropdown from './DocumentPickerDropdown.svelte';
+import { m } from '$lib/paraglide/messages.js';
+
+const waitForDebounce = () => new Promise((r) => setTimeout(r, 350));
+
+const docFactory = (id: string, title: string) => ({
+	id,
+	title,
+	documentDate: '1880-01-01',
+	metaDatePrecision: 'DAY' as const,
+	metaDateEnd: undefined
+});
+
+function mockSearchResponse(items: ReturnType<typeof docFactory>[]) {
+	vi.stubGlobal(
+		'fetch',
+		vi.fn().mockResolvedValue({
+			ok: true,
+			json: vi.fn().mockResolvedValue({ items })
+		})
+	);
+}
+
+afterEach(() => {
+	cleanup();
+	vi.unstubAllGlobals();
+});
+
+describe('DocumentPickerDropdown — empty query guard', () => {
+	it('does not call fetch on empty query', async () => {
+		const fetchMock = vi.fn();
+		vi.stubGlobal('fetch', fetchMock);
+
+		render(DocumentPickerDropdown, { onSelect: vi.fn() });
+		await userEvent.fill(page.getByRole('combobox'), '');
+		await waitForDebounce();
+
+		expect(fetchMock).not.toHaveBeenCalled();
+	});
+});
+
+describe('DocumentPickerDropdown — already-added indicator', () => {
+	it('shows already-added document as aria-disabled with sr-only hint', async () => {
+		mockSearchResponse([docFactory('d1', 'Brief von Eugenie'), docFactory('d2', 'Brief 2')]);
+
+		render(DocumentPickerDropdown, {
+			alreadyAddedIds: new Set(['d1']),
+			onSelect: vi.fn()
+		});
+
+		await userEvent.fill(page.getByRole('combobox'), 'Brief');
+		await waitForDebounce();
+
+		const disabledItem = page
+			.getByText(/Brief von Eugenie/i)
+			.element()
+			.closest('li')!;
+		expect(disabledItem.getAttribute('aria-disabled')).toBe('true');
+		// Screen-reader text "bereits enthalten" must be present in the item
+		await expect.element(page.getByText(/bereits enthalten/i)).toBeInTheDocument();
+	});
+});
+
+describe('DocumentPickerDropdown — selection', () => {
+	it('calls onSelect with the item when a non-disabled option is clicked', async () => {
+		const onSelect = vi.fn();
+		mockSearchResponse([docFactory('d1', 'Brief von Eugenie')]);
+
+		render(DocumentPickerDropdown, { onSelect });
+
+		await userEvent.fill(page.getByRole('combobox'), 'Brief');
+		await waitForDebounce();
+		await userEvent.click(page.getByText(/Brief von Eugenie/i));
+
+		expect(onSelect).toHaveBeenCalledWith(expect.objectContaining({ id: 'd1' }));
+	});
+
+	it('does not call onSelect when an aria-disabled option is clicked', async () => {
+		const onSelect = vi.fn();
+		mockSearchResponse([docFactory('d1', 'Brief von Eugenie')]);
+
+		render(DocumentPickerDropdown, {
+			alreadyAddedIds: new Set(['d1']),
+			onSelect
+		});
+
+		await userEvent.fill(page.getByRole('combobox'), 'Brief');
+		await waitForDebounce();
+		await page.getByText(/Brief von Eugenie/i).click({ force: true });
+
+		expect(onSelect).not.toHaveBeenCalled();
+	});
+});
+
+describe('DocumentPickerDropdown — keyboard navigation', () => {
+	it('selects the first option via ArrowDown then Enter', async () => {
+		const onSelect = vi.fn();
+		mockSearchResponse([docFactory('d1', 'Brief von Eugenie'), docFactory('d2', 'Brief 2')]);
+
+		render(DocumentPickerDropdown, { onSelect });
+
+		await userEvent.fill(page.getByRole('combobox'), 'Brief');
+		await waitForDebounce();
+		await userEvent.keyboard('{ArrowDown}');
+		await userEvent.keyboard('{Enter}');
+
+		expect(onSelect).toHaveBeenCalledWith(expect.objectContaining({ id: 'd1' }));
+	});
+
+	it('does not select an aria-disabled option on Enter', async () => {
+		const onSelect = vi.fn();
+		mockSearchResponse([docFactory('d1', 'Brief von Eugenie')]);
+
+		render(DocumentPickerDropdown, {
+			alreadyAddedIds: new Set(['d1']),
+			onSelect
+		});
+
+		await userEvent.fill(page.getByRole('combobox'), 'Brief');
+		await waitForDebounce();
+		await userEvent.keyboard('{ArrowDown}');
+		await userEvent.keyboard('{Enter}');
+
+		expect(onSelect).not.toHaveBeenCalled();
+	});
+
+	it('closes the dropdown on Escape', async () => {
+		mockSearchResponse([docFactory('d1', 'Brief von Eugenie')]);
+
+		render(DocumentPickerDropdown, { onSelect: vi.fn() });
+
+		await userEvent.fill(page.getByRole('combobox'), 'Brief');
+		await waitForDebounce();
+		await expect.element(page.getByRole('listbox')).toBeInTheDocument();
+
+		await userEvent.keyboard('{Escape}');
+
+		await expect.element(page.getByRole('listbox')).not.toBeInTheDocument();
+	});
+
+	it('points aria-activedescendant at the active option', async () => {
+		mockSearchResponse([docFactory('d1', 'Brief von Eugenie'), docFactory('d2', 'Brief 2')]);
+
+		render(DocumentPickerDropdown, { onSelect: vi.fn() });
+
+		const input = page.getByRole('combobox');
+		await userEvent.fill(input, 'Brief');
+		await waitForDebounce();
+
+		expect(input.element().getAttribute('aria-activedescendant')).toBeNull();
+
+		await userEvent.keyboard('{ArrowDown}');
+
+		const activeId = input.element().getAttribute('aria-activedescendant');
+		expect(activeId).toMatch(/-option-0$/);
+		const firstOption = page
+			.getByText(/Brief von Eugenie/i)
+			.element()
+			.closest('li')!;
+		expect(firstOption.id).toBe(activeId);
+		expect(firstOption.getAttribute('aria-selected')).toBe('true');
+	});
+});
+
+describe('DocumentPickerDropdown — no results', () => {
+	it('shows a non-interactive no-results row when the search returns zero hits', async () => {
+		mockSearchResponse([]);
+
+		render(DocumentPickerDropdown, { onSelect: vi.fn() });
+
+		await userEvent.fill(page.getByRole('combobox'), 'xyz');
+		await waitForDebounce();
+
+		await expect.element(page.getByText(m.comp_typeahead_no_results())).toBeInTheDocument();
+	});
+});
+
+describe('DocumentPickerDropdown — search failure', () => {
+	it('shows an error message when the search request fails instead of vanishing', async () => {
+		// 500 from /api/documents/search — must surface, not render as "no results"
+		vi.stubGlobal(
+			'fetch',
+			vi.fn().mockResolvedValue({
+				ok: false,
+				status: 500,
+				json: vi.fn().mockResolvedValue({ code: 'INTERNAL_ERROR' })
+			})
+		);
+
+		render(DocumentPickerDropdown, { onSelect: vi.fn() });
+
+		await userEvent.fill(page.getByRole('combobox'), 'Brief');
+		await waitForDebounce();
+
+		await expect.element(page.getByText(m.comp_typeahead_error())).toBeInTheDocument();
+	});
+});
+
+describe('DocumentPickerDropdown — ARIA listbox integrity', () => {
+	it('does not render a listbox when results are empty (no aria-required-children violation)', async () => {
+		mockSearchResponse([]);
+		render(DocumentPickerDropdown, { onSelect: vi.fn() });
+
+		await userEvent.fill(page.getByRole('combobox'), 'xyz');
+		await waitForDebounce();
+
+		// no-results message must be visible, but NOT inside a listbox
+		await expect.element(page.getByText(m.comp_typeahead_no_results())).toBeInTheDocument();
+		expect(document.querySelector('[role="listbox"]')).toBeNull();
+	});
+
+	it('does not render a listbox when loading (no aria-required-children violation)', async () => {
+		let resolveSearch!: (v: unknown) => void;
+		vi.stubGlobal(
+			'fetch',
+			vi.fn().mockReturnValue(new Promise((resolve) => (resolveSearch = resolve)))
+		);
+		render(DocumentPickerDropdown, { onSelect: vi.fn() });
+
+		await userEvent.fill(page.getByRole('combobox'), 'Brief');
+
+		// While in-flight, no listbox should exist
+		expect(document.querySelector('[role="listbox"]')).toBeNull();
+		resolveSearch({ ok: true, json: () => Promise.resolve({ items: [] }) });
+	});
+
+	it('option elements do not have tabindex (combobox pattern: focus stays on input)', async () => {
+		mockSearchResponse([docFactory('d1', 'Brief A'), docFactory('d2', 'Brief B')]);
+		render(DocumentPickerDropdown, { onSelect: vi.fn() });
+
+		await userEvent.fill(page.getByRole('combobox'), 'Brief');
+		await waitForDebounce();
+
+		const options = document.querySelectorAll('[role="listbox"] [role="option"]');
+		expect(options.length).toBeGreaterThan(0);
+		options.forEach((opt) => {
+			expect(opt).not.toHaveAttribute('tabindex');
+		});
+	});
+});
+
+describe('DocumentPickerDropdown — external label wiring (#795)', () => {
+	it('renders a generated default id on the input and keeps the aria-label fallback', async () => {
+		render(DocumentPickerDropdown, { onSelect: vi.fn() });
+
+		const input = page.getByRole('combobox').element() as HTMLInputElement;
+		expect(input.id).toMatch(/^doc-picker-input-/);
+		expect(input.getAttribute('aria-label')).not.toBeNull();
+	});
+
+	it('uses the provided inputId and drops the aria-label so an external label wins', async () => {
+		render(DocumentPickerDropdown, { onSelect: vi.fn(), inputId: 'story-doc-picker' });
+
+		const input = page.getByRole('combobox').element() as HTMLInputElement;
+		expect(input.id).toBe('story-doc-picker');
+		expect(input.getAttribute('aria-label')).toBeNull();
+	});
+});

frontend/src/lib/document/documentTypeahead.ts

@@ -0,0 +1,45 @@
+import type { components } from '$lib/generated/api';
+import { createTypeahead } from '$lib/shared/hooks/useTypeahead.svelte';
+import { formatDocumentDate, type DatePrecision } from '$lib/shared/utils/documentDate';
+import { getLocale } from '$lib/paraglide/runtime.js';
+
+type DocumentListItem = components['schemas']['DocumentListItem'];
+
+export type DocumentOption = Pick<
+	DocumentListItem,
+	'id' | 'title' | 'documentDate' | 'metaDatePrecision' | 'metaDateEnd'
+>;
+
+export function createDocumentTypeahead() {
+	return createTypeahead<DocumentOption>({
+		fetchUrl: (q) =>
+			fetch(`/api/documents/search?q=${encodeURIComponent(q)}&size=10`)
+				.then((r) => {
+					// Without this check a 401/500 parses as JSON without `items` and
+					// renders as "no results" — errors must reach the hook's error state.
+					if (!r.ok) throw new Error(`document search failed: ${r.status}`);
+					return r.json();
+				})
+				.then((b: { items: DocumentListItem[] }) =>
+					b.items.map((it) => ({
+						id: it.id,
+						title: it.title,
+						documentDate: it.documentDate,
+						metaDatePrecision: it.metaDatePrecision,
+						metaDateEnd: it.metaDateEnd
+					}))
+				)
+	});
+}
+
+export function formatDocumentOption(doc: DocumentOption): string {
+	if (!doc.documentDate) return doc.title;
+	const label = formatDocumentDate(
+		doc.documentDate,
+		doc.metaDatePrecision as DatePrecision,
+		doc.metaDateEnd,
+		null,
+		getLocale()
+	);
+	return `${doc.title} · ${label}`;
+}

frontend/src/lib/document/transcription/TranscriptionEditView.svelte

@@ -5,7 +5,7 @@ import OcrTrigger from '$lib/ocr/OcrTrigger.svelte';
 import TranscribeCoachEmptyState from '$lib/shared/help/TranscribeCoachEmptyState.svelte';
 import type { PersonMention, TranscriptionBlockData } from '$lib/shared/types';
 import { createBlockAutoSave } from '$lib/document/transcription/useBlockAutoSave.svelte';
-import { createBlockDragDrop } from '$lib/document/transcription/useBlockDragDrop.svelte';
+import { createBlockDragDrop } from '$lib/shared/hooks/useBlockDragDrop.svelte';
 import { csrfFetch } from '$lib/shared/cookies';
 
 type Props = {

frontend/src/lib/document/transcription/useBlockDragDrop.svelte.test.ts

@@ -1,169 +0,0 @@
-import { describe, it, expect, vi } from 'vitest';
-import { createBlockDragDrop } from './useBlockDragDrop.svelte';
-import type { TranscriptionBlockData } from '$lib/shared/types';
-
-function makeBlock(id: string, sortOrder: number): TranscriptionBlockData {
-	return {
-		id,
-		annotationId: `ann-${id}`,
-		documentId: 'doc-1',
-		text: '',
-		label: null,
-		sortOrder,
-		version: 1,
-		source: 'MANUAL',
-		reviewed: false,
-		mentionedPersons: []
-	};
-}
-
-/**
- * Builds a DOM list, mocks getBoundingClientRect (60px per wrapper),
- * drags `dragId` and drops it so dropTargetIdx === targetIdx, then
- * triggers handlePointerUp. Returns the onReorder spy.
- */
-function simulateDragDrop(
-	dragId: string,
-	targetIdx: number,
-	blocks: TranscriptionBlockData[]
-): ReturnType<typeof vi.fn> {
-	const onReorder = vi.fn();
-	const dd = createBlockDragDrop({ getSortedBlocks: () => blocks, onReorder });
-
-	// Build DOM
-	const listEl = document.createElement('div');
-	const wrappers = blocks.map(() => {
-		const grip = document.createElement('div');
-		grip.setAttribute('data-drag-handle', '');
-		const wrapper = document.createElement('div');
-		wrapper.setAttribute('data-block-wrapper', '');
-		wrapper.appendChild(grip);
-		listEl.appendChild(wrapper);
-		return { grip, wrapper };
-	});
-	document.body.appendChild(listEl);
-	dd.setListElement(listEl);
-
-	// Mock bounding rects: each wrapper is 60px tall starting at y=0
-	wrappers.forEach(({ wrapper }, i) => {
-		vi.spyOn(wrapper, 'getBoundingClientRect').mockReturnValue({
-			top: i * 60,
-			height: 60,
-			bottom: (i + 1) * 60,
-			left: 0,
-			right: 100,
-			width: 100,
-			x: 0,
-			y: i * 60,
-			toJSON: () => ({})
-		} as DOMRect);
-	});
-
-	const dragIdx = blocks.findIndex((b) => b.id === dragId);
-	const { grip, wrapper: dragWrapper } = wrappers[dragIdx];
-	dragWrapper.setPointerCapture = vi.fn();
-
-	// Start drag
-	const downEvent = new PointerEvent('pointerdown', { clientY: dragIdx * 60, cancelable: true });
-	Object.defineProperty(downEvent, 'target', { value: grip });
-	dd.handleGripDown(downEvent as PointerEvent, dragId);
-
-	// Move pointer to achieve the desired targetIdx
-	// midpoint of wrapper[i] = i*60 + 30
-	// clientY just before midpoint[i] → target = i
-	// clientY past last midpoint → target = wrappers.length
-	let clientY: number;
-	if (targetIdx <= 0) {
-		clientY = 5; // before first midpoint (30)
-	} else if (targetIdx >= wrappers.length) {
-		clientY = wrappers.length * 60 + 10; // past all midpoints
-	} else {
-		clientY = targetIdx * 60 + 5; // just past top of wrapper[targetIdx], before its midpoint
-	}
-
-	const moveEvent = new PointerEvent('pointermove', { clientY });
-	dd.handlePointerMove(moveEvent as PointerEvent);
-	dd.handlePointerUp();
-
-	document.body.removeChild(listEl);
-	return onReorder;
-}
-
-describe('createBlockDragDrop', () => {
-	it('initial state — no drag in progress', () => {
-		const dd = createBlockDragDrop({ getSortedBlocks: () => [], onReorder: vi.fn() });
-		expect(dd.draggedBlockId).toBeNull();
-		expect(dd.dropTargetIdx).toBeNull();
-		expect(dd.dragOffsetY).toBe(0);
-	});
-
-	it('handleGripDown sets draggedBlockId when grip is hit', () => {
-		const dd = createBlockDragDrop({ getSortedBlocks: () => [], onReorder: vi.fn() });
-		const grip = document.createElement('div');
-		grip.setAttribute('data-drag-handle', '');
-		const wrapper = document.createElement('div');
-		wrapper.setAttribute('data-block-wrapper', '');
-		wrapper.appendChild(grip);
-		document.body.appendChild(wrapper);
-
-		const e = new PointerEvent('pointerdown', { clientY: 100, cancelable: true, bubbles: true });
-		Object.defineProperty(e, 'target', { value: grip });
-		wrapper.setPointerCapture = vi.fn();
-
-		dd.handleGripDown(e as PointerEvent, 'block-1');
-		expect(dd.draggedBlockId).toBe('block-1');
-
-		document.body.removeChild(wrapper);
-	});
-
-	it('handlePointerUp without active drag is a no-op', () => {
-		const onReorder = vi.fn();
-		const dd = createBlockDragDrop({ getSortedBlocks: () => [], onReorder });
-		dd.handlePointerUp();
-		expect(onReorder).not.toHaveBeenCalled();
-	});
-
-	it('handlePointerUp with null dropTargetIdx does not call onReorder', () => {
-		const onReorder = vi.fn();
-		const blocks = [makeBlock('b1', 0), makeBlock('b2', 1)];
-		const dd = createBlockDragDrop({ getSortedBlocks: () => blocks, onReorder });
-
-		const grip = document.createElement('div');
-		grip.setAttribute('data-drag-handle', '');
-		const wrapper = document.createElement('div');
-		wrapper.setAttribute('data-block-wrapper', '');
-		wrapper.appendChild(grip);
-		document.body.appendChild(wrapper);
-		wrapper.setPointerCapture = vi.fn();
-
-		const downEvent = new PointerEvent('pointerdown', { clientY: 50, cancelable: true });
-		Object.defineProperty(downEvent, 'target', { value: grip });
-		dd.handleGripDown(downEvent as PointerEvent, 'b1');
-
-		// dropTargetIdx is still null (no pointer move happened)
-		dd.handlePointerUp();
-		expect(onReorder).not.toHaveBeenCalled();
-		expect(dd.draggedBlockId).toBeNull();
-
-		document.body.removeChild(wrapper);
-	});
-
-	it('reorder: moves block from index 0 to end', () => {
-		const blocks = [makeBlock('b1', 0), makeBlock('b2', 1), makeBlock('b3', 2)];
-		const onReorder = simulateDragDrop('b1', 3, blocks);
-		expect(onReorder).toHaveBeenCalledWith(['b2', 'b3', 'b1']);
-	});
-
-	it('reorder: moves block from end to index 0', () => {
-		const blocks = [makeBlock('b1', 0), makeBlock('b2', 1), makeBlock('b3', 2)];
-		const onReorder = simulateDragDrop('b3', 0, blocks);
-		expect(onReorder).toHaveBeenCalledWith(['b3', 'b1', 'b2']);
-	});
-
-	it('reorder: moves block down by one position (tests insertAt = dropTargetIdx - 1)', () => {
-		const blocks = [makeBlock('b1', 0), makeBlock('b2', 1), makeBlock('b3', 2)];
-		// dragId=b1 (idx=0), targetIdx=2 → insertAt = 2-1 = 1 → [b2, b1, b3]
-		const onReorder = simulateDragDrop('b1', 2, blocks);
-		expect(onReorder).toHaveBeenCalledWith(['b2', 'b1', 'b3']);
-	});
-});

frontend/src/lib/document/transcription/useBlockDragDrop.svelte.ts

@@ -1,88 +0,0 @@
-import type { TranscriptionBlockData } from '$lib/shared/types';
-
-type Options = {
-	getSortedBlocks: () => TranscriptionBlockData[];
-	onReorder: (blockIds: string[]) => void;
-};
-
-export function createBlockDragDrop({ getSortedBlocks, onReorder }: Options) {
-	let draggedBlockId = $state<string | null>(null);
-	let dropTargetIdx = $state<number | null>(null);
-	let dragOffsetY = $state(0);
-
-	// Internal mutable refs — not reactive
-	let dragStartY = 0;
-	let capturedEl: HTMLElement | null = null;
-	let listEl: HTMLElement | null = null;
-
-	function setListElement(el: HTMLElement | null): void {
-		listEl = el;
-	}
-
-	function handleGripDown(e: PointerEvent, blockId: string): void {
-		if (!(e.target as HTMLElement).closest('[data-drag-handle]')) return;
-		e.preventDefault();
-		draggedBlockId = blockId;
-		dragStartY = e.clientY;
-		dragOffsetY = 0;
-		capturedEl = (e.target as HTMLElement).closest('[data-block-wrapper]') as HTMLElement;
-		capturedEl?.setPointerCapture(e.pointerId);
-	}
-
-	function handlePointerMove(e: PointerEvent): void {
-		if (!draggedBlockId || !listEl) return;
-		dragOffsetY = e.clientY - dragStartY;
-
-		const sortedBlocks = getSortedBlocks();
-		const wrappers = Array.from(listEl.querySelectorAll('[data-block-wrapper]'));
-		const dragIdx = sortedBlocks.findIndex((b) => b.id === draggedBlockId);
-		let target: number | null = null;
-
-		for (let i = 0; i < wrappers.length; i++) {
-			const rect = wrappers[i].getBoundingClientRect();
-			if (e.clientY < rect.top + rect.height / 2) {
-				target = i;
-				break;
-			}
-		}
-		if (target === null) target = wrappers.length;
-		if (target === dragIdx || target === dragIdx + 1) target = null;
-		dropTargetIdx = target;
-	}
-
-	function handlePointerUp(): void {
-		if (!draggedBlockId) return;
-
-		if (dropTargetIdx !== null) {
-			const sorted = [...getSortedBlocks()];
-			const fromIdx = sorted.findIndex((b) => b.id === draggedBlockId);
-			if (fromIdx >= 0) {
-				const [moved] = sorted.splice(fromIdx, 1);
-				const insertAt = dropTargetIdx > fromIdx ? dropTargetIdx - 1 : dropTargetIdx;
-				sorted.splice(insertAt, 0, moved);
-				onReorder(sorted.map((b) => b.id));
-			}
-		}
-
-		draggedBlockId = null;
-		dropTargetIdx = null;
-		dragOffsetY = 0;
-		capturedEl = null;
-	}
-
-	return {
-		get draggedBlockId() {
-			return draggedBlockId;
-		},
-		get dropTargetIdx() {
-			return dropTargetIdx;
-		},
-		get dragOffsetY() {
-			return dragOffsetY;
-		},
-		setListElement,
-		handleGripDown,
-		handlePointerMove,
-		handlePointerUp
-	};
-}