From 6382efa65a6eeff36a342e47b64a7111bf6b5076 Mon Sep 17 00:00:00 2001
From: Marcel <marcel@familienarchiv>
Date: Sun, 14 Jun 2026 10:52:55 +0200
Subject: [PATCH] =?UTF-8?q?feat(timeline):=20caption=20the=20density=20str?=
 =?UTF-8?q?ip=20with=20=E2=9C=89=20+=20month=20axis=20(REQ-010/011)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The dense-year strip count now carries the ✉ glyph (aria-hidden + sr-only
"Brief"), and beneath the sparkline a "Monats-Dichte" caption sits between
the two endpoint month labels (Jan/Dez {year}) at the ≥10px micro-axis
floor, localized via the shared month formatter. The ≥44px keyboard-
focusable "Briefe anzeigen" expand toggle is preserved unchanged.

Refs #833
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../src/lib/timeline/YearLetterStrip.svelte   | 27 +++++++++++++---
 .../timeline/YearLetterStrip.svelte.spec.ts   | 31 +++++++++++++++++++
 2 files changed, 54 insertions(+), 4 deletions(-)

diff --git a/frontend/src/lib/timeline/YearLetterStrip.svelte b/frontend/src/lib/timeline/YearLetterStrip.svelte
index 8409734c..81b7dd89 100644
--- a/frontend/src/lib/timeline/YearLetterStrip.svelte
+++ b/frontend/src/lib/timeline/YearLetterStrip.svelte
@@ -1,5 +1,7 @@
 <script lang="ts">
 import * as m from '$lib/paraglide/messages.js';
+import { getLocale } from '$lib/paraglide/runtime.js';
+import { formatTickLabel } from '$lib/shared/utils/monthBuckets';
 import Sparkline from '$lib/shared/primitives/Sparkline.svelte';
 import LetterCard from './LetterCard.svelte';
 import { monthHistogram } from './timelineDensity';
@@ -10,20 +12,28 @@ type TimelineEntryDTO = components['schemas']['TimelineEntryDTO'];
 /**
  * Compact density view for a year with many letters (REQ-012): the letter count
  * plus a 12-month density sparkline, and a ≥44px keyboard-focusable toggle that
- * expands to that year's individual LetterCards.
+ * expands to that year's individual LetterCards. The count carries a ✉ glyph and
+ * the sparkline is captioned with its month-density meaning and Jan/Dez endpoint
+ * labels (REQ-010/011).
  */
 let { letters, year }: { letters: TimelineEntryDTO[]; year: number } = $props();
 
 let expanded = $state(false);
 
 const counts = $derived(monthHistogram(letters, year).map((b) => b.count));
+// Two endpoint month labels only (not one per bar). Pass the Jan/Dez anchors so
+// the locale formatter returns a month (a bare "{year}" returns just the year).
+const janLabel = $derived(formatTickLabel(`${year}-01`, getLocale()));
+const dezLabel = $derived(formatTickLabel(`${year}-12`, getLocale()));
 </script>
 
 <div class="mx-auto max-w-md rounded-sm border border-line bg-surface p-3 shadow-sm">
 	<div class="flex items-center justify-between gap-3">
-		<span class="font-sans text-sm font-bold text-brand-navy"
-			>{m.timeline_letters_count({ count: letters.length })}</span
-		>
+		<span class="font-sans text-sm font-bold text-brand-navy">
+			<span aria-hidden="true">✉</span>
+			<span class="sr-only">{m.timeline_letter_glyph_label()}</span>
+			{m.timeline_letters_count({ count: letters.length })}
+		</span>
 		<button
 			type="button"
 			data-testid="strip-expand"
@@ -42,6 +52,15 @@ const counts = $derived(monthHistogram(letters, year).map((b) => b.count));
 		class="mt-2"
 	/>
 
+	<!-- Two endpoint month labels + the density caption, beneath the sparkline
+	     (REQ-010/011). 10px is the floor for this micro-axis (the spec's 6px is
+	     below this project's legibility floor for the 60+ transcriber audience). -->
+	<div class="mt-1 flex items-center justify-between gap-2 font-sans text-[10px] text-ink-3">
+		<span data-testid="strip-axis-label">{janLabel}</span>
+		<span>{m.timeline_strip_density_caption()}</span>
+		<span data-testid="strip-axis-label">{dezLabel}</span>
+	</div>
+
 	{#if expanded}
 		<ul class="mt-3 space-y-2">
 			{#each letters as letter (letter.documentId)}
diff --git a/frontend/src/lib/timeline/YearLetterStrip.svelte.spec.ts b/frontend/src/lib/timeline/YearLetterStrip.svelte.spec.ts
index 4c78ea0e..9d102576 100644
--- a/frontend/src/lib/timeline/YearLetterStrip.svelte.spec.ts
+++ b/frontend/src/lib/timeline/YearLetterStrip.svelte.spec.ts
@@ -1,6 +1,9 @@
 import { describe, it, expect, afterEach } from 'vitest';
 import { cleanup, render } from 'vitest-browser-svelte';
 import { tick } from 'svelte';
+import * as m from '$lib/paraglide/messages.js';
+import { getLocale } from '$lib/paraglide/runtime.js';
+import { formatTickLabel } from '$lib/shared/utils/monthBuckets';
 import YearLetterStrip from './YearLetterStrip.svelte';
 import { makeEntry } from './test-factories';
 
@@ -39,4 +42,32 @@ describe('YearLetterStrip', () => {
 		await tick();
 		expect(document.querySelectorAll('a').length).toBe(30);
 	});
+
+	it('prefixes the count with an aria-hidden ✉ + sr-only "Brief" and shows the density caption (REQ-010)', () => {
+		render(YearLetterStrip, { letters: denseLetters(1915, 30), year: 1915 });
+		const hidden = document.querySelector('[aria-hidden="true"]');
+		expect(hidden?.textContent).toContain('✉');
+		const srOnly = document.querySelector('.sr-only');
+		expect(srOnly?.textContent).toBe(m.timeline_letter_glyph_label());
+		expect(document.body.textContent).toContain(m.timeline_strip_density_caption());
+	});
+
+	it('keeps the expand toggle and its "Briefe anzeigen" label alongside the new chrome (REQ-010)', () => {
+		render(YearLetterStrip, { letters: denseLetters(1915, 30), year: 1915 });
+		const toggle = document.querySelector('[data-testid="strip-expand"]') as HTMLButtonElement;
+		expect(toggle).not.toBeNull();
+		expect(toggle.textContent).toContain(m.timeline_strip_expand());
+		expect(toggle.getBoundingClientRect().height).toBeGreaterThanOrEqual(44);
+	});
+
+	it('renders exactly two endpoint month-axis labels (Jan/Dez {year}) at ≥10px (REQ-011)', () => {
+		render(YearLetterStrip, { letters: denseLetters(1915, 30), year: 1915 });
+		const labels = document.querySelectorAll('[data-testid="strip-axis-label"]');
+		expect(labels).toHaveLength(2);
+		expect(labels[0].textContent).toContain(formatTickLabel('1915-01', getLocale()));
+		expect(labels[1].textContent).toContain(formatTickLabel('1915-12', getLocale()));
+		for (const label of labels) {
+			expect(parseFloat(getComputedStyle(label).fontSize)).toBeGreaterThanOrEqual(10);
+		}
+	});
 });