feat(frontend): add precision-aware document date formatter

Adds formatDocumentDate — a pure, branch-per-precision label function that
renders a document date at exactly the precision the data claims (DAY → full
date, MONTH → "Juni 1916", SEASON → localized season word, YEAR → "1916",
APPROX → "ca. 1916", RANGE with collapse/expand/open-ended, UNKNOWN → "Datum
unbekannt"). Delegates to the existing date.ts helpers (shared T12:00:00
convention) and routes every localized word through Paraglide.

A shared docs/date-label-fixtures.json table is asserted by this spec and will
be asserted by the Java title formatter, as the drift guard requested in
review (Markus/Sara). Adds de/en/es precision/season/edit-form i18n keys.

Assumption: SEASON structured label is localized per locale (Decision 4),
with the verbatim raw cell preserved as a separate secondary line by callers.

Refs #666

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

frontend/src/lib/shared/utils/documentDate.spec.ts

@@ -0,0 +1,105 @@
+import { describe, expect, it } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { formatDocumentDate } from './documentDate';
+import { m } from '$lib/paraglide/messages.js';
+
+// ─── Shared drift-guard fixture ─────────────────────────────────────────────
+// The same table is asserted by the Java DocumentTitleFormatter test so the two
+// label implementations cannot drift. Expected values are the German canonical
+// form (see docs/date-label-fixtures.json).
+type FixtureCase = {
+	name: string;
+	precision: string;
+	anchor: string | null;
+	end: string | null;
+	raw: string | null;
+	expected: string;
+};
+
+const fixtures = JSON.parse(
+	readFileSync(resolve(process.cwd(), '../docs/date-label-fixtures.json'), 'utf-8')
+) as { cases: FixtureCase[] };
+
+describe('formatDocumentDate – shared fixture table (de)', () => {
+	for (const c of fixtures.cases) {
+		it(c.name, () => {
+			expect(
+				formatDocumentDate(
+					c.anchor,
+					c.precision as Parameters<typeof formatDocumentDate>[1],
+					c.end,
+					c.raw,
+					'de'
+				)
+			).toBe(c.expected);
+		});
+	}
+});
+
+// ─── Anti-fabrication: suppressed components never leak ──────────────────────
+
+describe('formatDocumentDate – suppressed precision components', () => {
+	it('YEAR of a June date renders the year only, never the month', () => {
+		const label = formatDocumentDate('1916-06-15', 'YEAR');
+		expect(label).toBe('1916');
+		expect(label).not.toContain('Juni');
+		expect(label).not.toContain('15');
+	});
+
+	it('MONTH never renders the day-of-month', () => {
+		const label = formatDocumentDate('1916-06-01', 'MONTH', null, 'Juni 1916');
+		expect(label).toBe('Juni 1916');
+		expect(label).not.toMatch(/\b1\.\s/);
+	});
+});
+
+// ─── i18n: localized structured label ───────────────────────────────────────
+
+describe('formatDocumentDate – localization', () => {
+	it('localizes the UNKNOWN label per locale', () => {
+		expect(formatDocumentDate(null, 'UNKNOWN', null, '?', 'en')).toBe(
+			m.date_precision_unknown(undefined, { locale: 'en' })
+		);
+	});
+
+	it('localizes the APPROX prefix per locale', () => {
+		expect(formatDocumentDate('1920-01-01', 'APPROX', null, null, 'en')).toBe(
+			`${m.date_precision_approx_prefix(undefined, { locale: 'en' })} 1920`
+		);
+	});
+
+	it('localizes the SEASON word per locale when raw is absent', () => {
+		expect(formatDocumentDate('1916-07-01', 'SEASON', null, null, 'en')).toBe(
+			`${m.date_season_summer(undefined, { locale: 'en' })} 1916`
+		);
+	});
+
+	it('localizes the SEASON word even when the raw cell is verbatim German (Decision 4)', () => {
+		expect(formatDocumentDate('1916-06-01', 'SEASON', null, 'Sommer 1916', 'en')).toBe(
+			`${m.date_season_summer(undefined, { locale: 'en' })} 1916`
+		);
+	});
+});
+
+// ─── Security: untrusted raw must never influence the structured label ───────
+
+describe('formatDocumentDate – security', () => {
+	it('ignores a malicious raw value for the structured label (raw is rendered separately, escaped)', () => {
+		const label = formatDocumentDate(null, 'UNKNOWN', null, '<img src=x onerror=alert(1)>');
+		expect(label).toBe('Datum unbekannt');
+		expect(label).not.toContain('<img');
+	});
+});
+
+// ─── Defensive null handling ─────────────────────────────────────────────────
+
+describe('formatDocumentDate – defensive null handling', () => {
+	it('renders the unknown label when the anchor is null but precision is not UNKNOWN', () => {
+		expect(formatDocumentDate(null, 'DAY')).toBe('Datum unbekannt');
+	});
+
+	it('falls back to start-day only for a RANGE whose end is null', () => {
+		expect(formatDocumentDate('1917-01-10', 'RANGE', null)).toBe('ab 10. Jan. 1917');
+	});
+});

frontend/src/lib/shared/utils/documentDate.ts

@@ -0,0 +1,159 @@
+import { formatDate, formatMCDate } from './date';
+import { m } from '$lib/paraglide/messages.js';
+
+/**
+ * Precision of a document's date — mirrors the backend {@code DatePrecision} enum
+ * and the import normalizer's seven values verbatim.
+ */
+export type DatePrecision = 'DAY' | 'MONTH' | 'SEASON' | 'YEAR' | 'RANGE' | 'APPROX' | 'UNKNOWN';
+
+/**
+ * Renders a document date at exactly the precision the data claims — never finer.
+ *
+ * Delegates to the {@link formatDate}/{@link formatMCDate} helpers (so the
+ * `T12:00:00` UTC-safety convention and the German Intl formatting are shared,
+ * not reimplemented) and routes every localized word through Paraglide.
+ *
+ * The label is the SINGLE SOURCE OF TRUTH shared with the Java
+ * {@code DocumentTitleFormatter}: both are asserted against
+ * `docs/date-label-fixtures.json` so they cannot drift. The untrusted `raw`
+ * cell is only used to derive a season word (a known German season token) — it
+ * is otherwise rendered separately by the caller via Svelte default escaping,
+ * never interpolated into HTML here.
+ *
+ * @param iso the sort/filter anchor day (`YYYY-MM-DD`), nullable for UNKNOWN rows
+ * @param precision descriptive precision metadata
+ * @param end the RANGE end day; null means an open-ended range
+ * @param raw the verbatim spreadsheet cell, used only for the SEASON word
+ * @param locale BCP 47 tag for the localized structured parts (default `de-DE`)
+ */
+export function formatDocumentDate(
+	iso: string | null | undefined,
+	precision: DatePrecision,
+	end?: string | null,
+	raw?: string | null,
+	locale: string = 'de-DE'
+): string {
+	if (precision === 'UNKNOWN' || !iso) {
+		return m.date_precision_unknown(undefined, { locale: messageLocale(locale) });
+	}
+
+	const year = iso.slice(0, 4);
+
+	switch (precision) {
+		case 'DAY':
+			return formatDate(iso, 'long');
+		case 'MONTH':
+			return monthYear(iso, locale);
+		case 'SEASON':
+			return seasonLabel(iso, raw, locale, year);
+		case 'YEAR':
+			return year;
+		case 'APPROX':
+			return `${m.date_precision_approx_prefix(undefined, { locale: messageLocale(locale) })} ${year}`;
+		case 'RANGE':
+			return rangeLabel(iso, end, locale);
+		default:
+			return m.date_precision_unknown(undefined, { locale: messageLocale(locale) });
+	}
+}
+
+// ─── precision branches ──────────────────────────────────────────────────────
+
+function monthYear(iso: string, locale: string): string {
+	return new Intl.DateTimeFormat(locale, { month: 'long', year: 'numeric' }).format(noon(iso));
+}
+
+function seasonLabel(
+	iso: string,
+	raw: string | null | undefined,
+	locale: string,
+	year: string
+): string {
+	const month = Number(iso.slice(5, 7));
+	// Prefer the season named in the raw cell; fall back to deriving it from the
+	// anchor month. Either way the WORD is localized (Decision 4) — the verbatim
+	// German raw cell is preserved separately as the visible secondary line.
+	const season = seasonFromRaw(raw) ?? seasonOfMonth(month);
+	return `${seasonWord(season, locale)} ${year}`;
+}
+
+function rangeLabel(iso: string, end: string | null | undefined, locale: string): string {
+	if (!end) {
+		return `${m.date_range_open_prefix(undefined, { locale: messageLocale(locale) })} ${formatMCDate(iso, locale)}`;
+	}
+	if (end === iso) {
+		return formatMCDate(iso, locale);
+	}
+	const start = noon(iso);
+	const finish = noon(end);
+	if (start.getFullYear() === finish.getFullYear()) {
+		return sameYearRange(end, start, finish, locale);
+	}
+	return `${formatMCDate(iso, locale)} – ${formatMCDate(end, locale)}`;
+}
+
+function sameYearRange(end: string, start: Date, finish: Date, locale: string): string {
+	if (start.getMonth() === finish.getMonth()) {
+		// Collapse the shared month/year: only the end carries "DD. Mon. YYYY".
+		return `${start.getDate()}.–${formatMCDate(end, locale)}`;
+	}
+	const startNoYear = new Intl.DateTimeFormat(locale, { day: 'numeric', month: 'short' }).format(
+		start
+	);
+	return `${startNoYear} – ${formatMCDate(end, locale)}`;
+}
+
+// ─── season helpers ──────────────────────────────────────────────────────────
+
+type Season = 'spring' | 'summer' | 'autumn' | 'winter';
+
+/** Quarter buckets; matches the normalizer's representative months (4/7/10/1). */
+function seasonOfMonth(month: number): Season {
+	if (month >= 3 && month <= 5) return 'spring';
+	if (month >= 6 && month <= 8) return 'summer';
+	if (month >= 9 && month <= 11) return 'autumn';
+	return 'winter';
+}
+
+function seasonWord(season: Season, locale: string): string {
+	const opts = { locale: messageLocale(locale) };
+	switch (season) {
+		case 'spring':
+			return m.date_season_spring(undefined, opts);
+		case 'summer':
+			return m.date_season_summer(undefined, opts);
+		case 'autumn':
+			return m.date_season_autumn(undefined, opts);
+		case 'winter':
+			return m.date_season_winter(undefined, opts);
+	}
+}
+
+/** Maps a German season token at the start of the raw cell to a Season, else null. */
+function seasonFromRaw(raw: string | null | undefined): Season | null {
+	if (!raw) return null;
+	const token = raw.trim().split(/\s+/)[0].toLowerCase();
+	const byToken: Record<string, Season> = {
+		frühling: 'spring',
+		frühjahr: 'spring',
+		sommer: 'summer',
+		herbst: 'autumn',
+		winter: 'winter'
+	};
+	return byToken[token] ?? null;
+}
+
+// ─── shared utilities ────────────────────────────────────────────────────────
+
+function noon(iso: string): Date {
+	return new Date(iso + 'T12:00:00');
+}
+
+/** Paraglide expects a registered locale tag; map `de-DE` → `de` etc. */
+function messageLocale(locale: string): 'de' | 'en' | 'es' {
+	const base = locale.slice(0, 2);
+	if (base === 'en') return 'en';
+	if (base === 'es') return 'es';
+	return 'de';
+}