From 5d5d4ac2a7353d3e9b7606c201921003403214c0 Mon Sep 17 00:00:00 2001
From: Schalli <kschaller@ctl.de>
Date: Wed, 16 Sep 2026 13:15:12 +0200
Subject: [PATCH] =?UTF-8?q?docs(quick-260916-htc):=20Kalender-Widget=20?=
 =?UTF-8?q?=E2=80=94=20Monatsraster=20+=20Naechste=20Termine,=20drei=20Ein?=
 =?UTF-8?q?stellungen;=20Zusammenfassung,=20Aktenstand?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .planning/STATE.md                            |   3 +-
 .../260916-htc-SUMMARY.md                     | 129 ++++++++++++++++++
 2 files changed, 131 insertions(+), 1 deletion(-)
 create mode 100644 .planning/quick/260916-htc-kalender-widget-nach-vorbild-personal-da/260916-htc-SUMMARY.md

diff --git a/.planning/STATE.md b/.planning/STATE.md
index 0fa74ff..ffc9b31 100644
--- a/.planning/STATE.md
+++ b/.planning/STATE.md
@@ -411,6 +411,7 @@ Gerettet aus `.continue-here.md`. Relevant fuer die noch offenen Live-Tests.
 | 260916-dyv | **Dashboard-Nachbesserung nach User-Test.** Mindestgroessen inhaltsgetrieben (clock 2/2, search 6/2, calendar 3/3, note 4/4, calculator 3/10 — vom Orchestrator im Browser von 9 auf 10 korrigiert, sechs Tastenreihen —, favorites 3/3, link 3/2, stopwatch 4/3 mit kompakter Bedienleiste), gespeicherte Layout-Eintraege bekommen minW/minH aus den Konstanten und zu kleine w/h werden angehoben (`applyConstraintMinima`, Test 9/9b). Bearbeiten-Schalter in feste Leiste unten rechts, `mt-8` weg: Rand oben 28 px statt 60. Drag & Drop: ganze Kachel als Griff mit Overlay-Kopfleiste, `dragConfig.cancel` (Eingaben, Knoepfe, .widgetNoDrag, Resize-Griff), `preventCollision: true` mit `noCompactor` (Ablegen auf belegtem Raum stoppt am Nachbarn, kein Ueberlappen). Anwenderhandbuch. Tests Web 286 -> 294 / 47 Dateien, API 67/1078, tsc 0, 12 Dateien gegen df16f46 + Fix 8792819; CI-Laeufe 353 und der Fix-Lauf gruen. Browser-Beweis: 28 px, Uhr 126x48, Ziehen an Kachelmitte, Suchfeld ohne Drag, Kollision stoppt, Rechner 272 px ohne Ueberlauf. Ledger #39 fixed. Verifiziert 6/6 + Browser, gepusht. | 2026-09-16 | dc992c9,dbbd54f,cf97b5b,8792819 | [260916-dyv-dashboard-nachbesserung-mindestgroessen-](./quick/260916-dyv-dashboard-nachbesserung-mindestgroessen-/) |
 | 260916-dcz | **Aenderungsliste.** `CHANGELOG.md` (Keep-a-Changelog, Alltagssprache, echte Umlaute: `## Unveröffentlicht` mit Neu/Geändert/Behoben, `## 1.0.0 – 2026-09-15` mit 11 Punkten); Seite "Was ist neu" unter `/changelog` (Server-Komponente, Text zur Bauzeit ueber `env.TESSERA_CHANGELOG_MD` in next.config.ts, nur im Server-Bundle; Kanalfilter `filterChangelogForChannel`: live ohne Unveroeffentlicht, beta/dev markiert; `MDEditor.Markdown` + `rehypeSanitize`), Versionsabzeichen als Link; Dockerfile `COPY CHANGELOG.md` + `.dockerignore !CHANGELOG.md`; `.gitea/scripts/publish-release.sh` (awk-Abschnitt, jq, API-Basis aus GITHUB_*, POST/PATCH, --dry-run, Exit 1 ohne Abschnitt) + ci.yml-Schritt nur bei Tag-Refs; Gitea-Release `v1.0.0` rueckwirkend angelegt (id 1); Handbuecher (Betrieb Kap. 9, Anwender "Was ist neu", Entwicklung, CI). Tests Web 294 -> 309 / 49 Dateien, API 67/1078, tsc 0, 19 Dateien gegen 963fa36; CI 356/357 gruen. Nachtrag c3d8e16: 21 fehlende Uebersetzungen (Kalenderquellen-Formular, Kalender-Einstellungen, Marktplatz) in de/en, Changelog "Behoben". Browser-Beweis: /changelog mit 20 Punkten, Kalender-Formular ohne Schluesselnamen. Verifiziert 8/8 + Browser, gepusht. | 2026-09-16 | ba06db9,6940bd0,c5f4ade,c3d8e16 | [260916-dcz-aenderungsliste-changelog-md-in-alltagss](./quick/260916-dcz-aenderungsliste-changelog-md-in-alltagss/) |
 | 260916-hiv | **Kalenderquellen-Formular: URL-Platzhalter je Typ + EWS-Hinweis.** Adressfeld zeigt je nach Typ ein Beispiel (Exchange EWS `https://mail.firma.de/EWS/Exchange.asmx`, Graph, CalDAV, ICS) statt fix `https://`; bei Exchange EWS grauer Hinweis unter dem Feld (vollstaendige Adresse inkl. /EWS/Exchange.asmx noetig). 5 i18n-Schluessel de/en, neuer Komponententest (6 Faelle), Changelog "Geändert". Ausloeser: User scheiterte mit blossem Hostnamen `owa.ctl.de`, curl bestaetigte 401 + NTLM auf `/EWS/Exchange.asmx`. Tests Web 309 -> 315 / 50 Dateien, tsc 0. | 2026-09-16 | 618fbd6,2306a6d,9439c33 | [260916-hiv-kalenderquellen-formular-url-platzhalter](./quick/260916-hiv-kalenderquellen-formular-url-platzhalter/) |
+| 260916-htc | **Kalender-Widget nach Vorbild personal-dashboard.** Monatsraster (Zurueck/Monat/Weiter, Mo-So, 42 Zellen ab Montag, heute hervorgehoben, Zaehler-Plakette je Tag, Termine beim Ueberfahren als Tooltip per `createPortal`/`position: fixed`, weil die Kachel `overflow-hidden` ist) + Block "Naechste Termine" (Datum/Uhrzeit, Titel, Ort, Farbpunkt). Drei Einstellungen unter Einstellungen -> Dashboard -> Widgets (`CalendarConfig`, Muster ClockConfig): `showMonth` (Standard an), `maxEvents` 0..10 (Standard 3, 0 = ausblenden), `lookaheadDays` 7/14/30/60/90 (Standard 30). Ein `fetchEvents(from,to)`-Aufruf je Ladevorgang mit lokalen Tagesgrenzen (Backend-Cache-Schluessel bleibt stabil), Neuladen bei Monatswechsel, 5-Minuten-Intervall bleibt. Neues reines Modul `calendar-month.ts` (resolveCalendarConfig, buildCalendarDays, groupEventsByDate, computeFetchWindow, selectUpcomingEvents). Mindestgroesse calendar 6x8 (Registry-Test mitgezogen). Keine Quellenauswahl pro Widget (User-Entscheidung: nur Optik). 16 i18n-Schluessel de/en, Changelog "Geändert", Anwenderhandbuch. Tests Web 315 -> 332 / 51 Dateien, tsc 0, 12 Dateien. | 2026-09-16 | 0858102,61996dc,6d8c7c4 | [260916-htc-kalender-widget-nach-vorbild-personal-da](./quick/260916-htc-kalender-widget-nach-vorbild-personal-da/) |
 
 ## Deferred Items
 
@@ -456,4 +457,4 @@ Last session: 2026-09-16T10:15:09.000Z
 Resumed: 2026-09-14 — Sitzung ueber /gsd-resume-work fortgesetzt; #29 und 3c als /gsd-quick --validate mit voller Kette durchgefuehrt.
 Stopped at: **VERSION 1.1.0 FREIGEGEBEN — 2026-09-16.** CHANGELOG `Unveröffentlicht` -> `1.1.0 – 2026-09-16` (e0d4532), `live` per ff-merge auf e0d4532, Tag `v1.1.0` gepusht; CI (Beta, live-Pruefung, Tag) gruen; Registry traegt `live`/`v1.1.0` (Stempel `v1.1.0 live e0d4532`); **erster echter CI-Beweis des Release-Wegs: Gitea-Release "Tessera 1.1.0" von der Pipeline angelegt** (Body 2146 Zeichen). Der User spielt 1.1.0 auf tessera.ctl.de ein (pull + up -d --force-recreate api web). Inhalt: Dashboard-Umbau + Nachbesserung, Seite "Was ist neu", Uebersetzungs-Fix. Offen ohne Dringlichkeit: Desktop-Client-Todo, Ship Phase 17, Ledger #35/#36/#37. Mandantenfaehigkeit RUHT. Schalter AUS. Einstieg: `/gsd-resume-work`.
 Resume file: .planning/HANDOFF.json + .planning/.continue-here.md (2026-09-16T10:28Z)
-Last activity: 2026-09-16 - Completed quick task 260916-hiv: Kalenderquellen-Formular — URL-Platzhalter je Typ + EWS-Hinweis
+Last activity: 2026-09-16 - Completed quick task 260916-htc: Kalender-Widget — Monatsraster + Naechste Termine, Einstellungen showMonth/maxEvents/lookaheadDays
diff --git a/.planning/quick/260916-htc-kalender-widget-nach-vorbild-personal-da/260916-htc-SUMMARY.md b/.planning/quick/260916-htc-kalender-widget-nach-vorbild-personal-da/260916-htc-SUMMARY.md
new file mode 100644
index 0000000..53ed231
--- /dev/null
+++ b/.planning/quick/260916-htc-kalender-widget-nach-vorbild-personal-da/260916-htc-SUMMARY.md
@@ -0,0 +1,129 @@
+---
+phase: quick-260916-htc
+plan: 01
+status: complete
+subsystem: dashboard-widgets
+tags: [calendar, dashboard, widget-settings, i18n]
+dependency-graph:
+  requires: [05-03 Kalender-Backend (fetchEvents/fetchSources), quick-260916-dyv (Raster 24 Spalten/20px)]
+  provides: [calendar-month.ts (geteiltes Hilfsmodul), Kalender-Monatsraster-Widget, CalendarConfig-Einstellungsfeld]
+  affects: [apps/web/src/components/dashboard/widgets/calendar-widget.tsx, apps/web/src/components/settings/widget-settings-panel.tsx, apps/web/src/components/dashboard/widget-registry.tsx]
+tech-stack:
+  added: []
+  patterns: [geteiltes Grenzen-Hilfsmodul fuer Widget+Panel (Muster clock-font-size.ts), createPortal fuer Tooltips ausserhalb einer overflow-hidden-Karte, Container-Query-Skalierung (cqw/cqh)]
+key-files:
+  created:
+    - apps/web/src/components/dashboard/widgets/calendar-month.ts
+    - apps/web/src/components/dashboard/widgets/calendar-month.test.ts
+  modified:
+    - apps/web/src/components/dashboard/widgets/calendar-widget.tsx
+    - apps/web/src/components/dashboard/widgets/calendar-widget.test.tsx
+    - apps/web/src/components/dashboard/widget-registry.tsx
+    - apps/web/src/components/dashboard/widget-registry.test.tsx
+    - apps/web/src/components/settings/widget-settings-panel.tsx
+    - apps/web/src/components/settings/widget-settings-panel.test.tsx
+    - apps/web/src/messages/de.json
+    - apps/web/src/messages/en.json
+    - CHANGELOG.md
+    - docs/anleitung-anwender.md
+decisions:
+  - "computeFetchWindow verwendet konsequent 'from = das FRUEHERE von Rasterstart und heutigem Tag' (Task-1-Spezifikation), auch wenn ein zukuenftiger Monat angezeigt wird — der im Plan fuer Task-2-Test-8 genannte Erwartungswert (27.07. statt 15.07.) widersprach dieser Regel; die konsistente, bereits per Unit-Test abgesicherte Regel wurde beibehalten (siehe Deviations)."
+  - "Leerer 'Naechste Termine'-Block traegt KEIN data-testid='calendar-upcoming' (nur die <ul> bei mindestens einem Termin traegt es) — folgt der <action>-Spezifikation aus dem Plan woertlich; die <behavior>-Beschreibung von Task 2 Test 6 war an dieser Stelle ungenauer formuliert."
+metrics:
+  duration: ~35 min
+  completed: 2026-09-16
+actuals:
+  tokens: 15659
+  tasks: 3
+  commits: 3
+plan_head_before: 0858102cbbe825ed4f52aeed31b9a0a44a9cb52
+---
+
+# Phase quick-260916-htc Plan 01: Kalender-Widget nach Vorbild personal-dashboard Summary
+
+Kalender-Widget von einer flachen Terminliste auf ein Monatsraster mit Termin-Plaketten, Portal-Tooltip und einem separat konfigurierbaren "Naechste Termine"-Block umgebaut, inklusive dreier neuer Einstellungsfelder (Monatsansicht, Anzahl Termine, Zeitraum) nach dem Muster `ClockConfig`.
+
+## Was wurde gebaut
+
+**Task 1 — Uebersetzungen + Hilfsmodul (Commit `0858102`)**
+16 neue Uebersetzungsschluessel unter `widgets.calendar` in de.json/en.json (Monatsnavigation, Tooltip-Hinweis, Einstellungsfeld-Texte). Neues reines Hilfsmodul `calendar-month.ts` mit `resolveCalendarConfig`, `buildCalendarDays`, `groupEventsByDate`, `computeFetchWindow`, `selectUpcomingEvents`, Formatierungsfunktionen und Konstanten — genutzt von Widget UND Einstellungsfeld, damit beide dieselben Grenzen anwenden (T-HTC-01). 8 Unit-Tests.
+
+**Task 2 — Widget neu gebaut (Commit `61996dc`)**
+`calendar-widget.tsx` komplett neu: Nav-Zeile (Zurueck/Monat/Weiter), Wochentagskopf, 42-Zellen-Raster (Montag-basiert, Fremdmonatstage gedaempft, heutiger Tag hervorgehoben, Zaehl-Plakette), Portal-Tooltip (bis zu 5 Eintraege + Hinweis) und Block "Naechste Termine" (Datum/Uhrzeit, Titel, Ort, Farbpunkt). `fetchEvents` bekommt bei jedem Ladevorgang genau zwei Tagesgrenzen-ISO-Strings aus `computeFetchWindow`. Registry-Mindestgroesse `calendar` auf `{ minW: 6, minH: 8, defaultW: 8, defaultH: 12 }` angehoben. 9 neue Komponententests.
+
+**Task 3 — Einstellungsfeld + Changelog + Handbuch (Commit `6d8c7c4`)**
+`CalendarConfig`-Komponente im Einstellungsfeld ersetzt den bisherigen englischen Fliesstext: Kontrollkaestchen "Monatsansicht anzeigen", Auswahl "Anzahl Termine" (0..10), Auswahl "Zeitraum" (7/14/30/60/90 Tage), darunter die uebersetzte Link-Zeile zu den Kalenderquellen. 3 neue Paneltests (7/7 insgesamt gruen). Changelog- und Handbuch-Eintrag ergaenzt.
+
+## Wichtige Hinweise fuer Folgearbeiten
+
+1. **Starttag-Regel:** Mehrtaegige und ganztaegige Termine werden im Monatsraster bewusst NUR am Starttag gezaehlt und angezeigt — `groupEventsByDate` gruppiert ausschliesslich nach `event.start`. Eine Terminleiste ueber mehrere Tage ist nicht Teil dieses Auftrags.
+2. **Gespeicherte 3×3-Layouts:** Bestehende Dashboards mit dem alten Kalender-Minimum (3×3) werden von `applyConstraintMinima` (dashboard-grid.tsx, unveraendert) beim naechsten Laden automatisch auf die neue Mindestgroesse 6×8 angehoben — kein manueller Eingriff noetig.
+3. **Ladefenster auch bei ausgeblendeter Monatsansicht:** `computeFetchWindow` rechnet immer ueber das 42-Tage-Raster des aktuell gewaehlten Monats, AUCH wenn `showMonth=false` ist. Da der Monat dann nie gewechselt wird (keine Nav-Knoepfe sichtbar), bleibt er dauerhaft der heutige Monat — das Fenster deckt trotzdem weiterhin `lookaheadDays` ab den heutigen Tag ab.
+4. **Testzahlen vorher/nachher:** Vorher 50 Testdateien / 315 Tests. Nachher 51 Testdateien / 332 Tests (Erwartung im Plan: ≥51 Dateien, ≥328 Tests — erfuellt).
+
+## Deviations from Plan
+
+### Auto-fixed Issues
+
+**1. [Rule 1 - Bug] TypeScript-Literaltyp-Fehler bei `resolveCalendarConfig`**
+- **Found during:** Task 1, Type-Check-Verifikation
+- **Issue:** `let maxEvents = CALENDAR_DEFAULTS.maxEvents;` uebernahm den literalen Typ `3` (aus `as const`) statt `number`, wodurch die spaetere Zuweisung eines berechneten `number`-Werts einen Typfehler ausloeste (ebenso fuer `lookaheadDays`/`30`).
+- **Fix:** Explizite Typannotation `let maxEvents: number = ...` / `let lookaheadDays: number = ...`.
+- **Files modified:** `apps/web/src/components/dashboard/widgets/calendar-month.ts`
+- **Commit:** `0858102`
+
+**2. [Rule 1 - Bug] Testverunreinigung durch nicht zurueckgesetzte `vi.fn()`-Mocks**
+- **Found during:** Task 2, `calendar-widget.test.tsx` beim Gesamtlauf der Datei
+- **Issue:** `vi.restoreAllMocks()` im `afterEach` wirkt bei mit `vi.fn()` (nicht `vi.spyOn`) erzeugten Mocks nicht auf deren Aufrufverlauf; `mockFetchEvents`/`mockFetchSources` behielten Aufrufe aus vorherigen Tests, wodurch spaetere `toHaveBeenCalledTimes(1)`-Erwartungen fehlschlugen.
+- **Fix:** `mockFetchEvents.mockReset()` und `mockFetchSources.mockReset()` zusaetzlich im `beforeEach`.
+- **Files modified:** `apps/web/src/components/dashboard/widgets/calendar-widget.test.tsx`
+- **Commit:** `61996dc`
+
+**3. [Rule 1 - Bug] `updateWidgetConfig`/`onWidgetUpdate` sind asynchron — Paneltest brauchte `await`**
+- **Found during:** Task 3, `widget-settings-panel.test.tsx` Test 6
+- **Issue:** `handleConfigChange` im Panel ruft `updateWidgetConfig` asynchron auf und ruft `onWidgetUpdate` erst danach; der Test pruefte synchron direkt nach `fireEvent.change` und schlug fehl (0 Aufrufe statt 1).
+- **Fix:** `await vi.waitFor(() => expect(onWidgetUpdate).toHaveBeenCalledWith(...))` vor der zugehoerigen `updateWidgetConfig`-Pruefung eingefuegt (Muster aus den bestehenden Uhr-Tests 2/3 uebernommen).
+- **Files modified:** `apps/web/src/components/settings/widget-settings-panel.test.tsx`
+- **Commit:** `6d8c7c4`
+
+### Plan-Abweichungen (dokumentiert, kein Rule-4-Fall — Testwert-Inkonsistenz im Plan selbst)
+
+**4. Task 2 Test 8 erwarteter `from`-Wert korrigiert (27.07. → 15.07.)**
+- **Found during:** Task 2, `calendar-widget.test.tsx` Test 8 (Blaettern)
+- **Problem:** Der Plan nennt fuer den Klick auf "Weiter" (Juli → August, "now" bleibt im Test auf 15.07. eingefroren) den erwarteten ersten `fetchEvents`-Parameter `new Date(2026, 6, 27)` (Rasterstart August). Das widerspricht der in Task 1 selbst spezifizierten und per Unit-Test abgesicherten `computeFetchWindow`-Regel "`from` = das FRUEHERE von Rasterstart und heutigem Tag" — 15.07. ist zeitlich frueher als 27.07., also muesste `from` = 15.07. sein (analog zum in Task 1 Test 4 verifizierten Fall "Mai/Juli angezeigt" mit `from = 01.05.`).
+- **Entscheidung:** Die bereits verifizierte, konsistente `computeFetchWindow`-Logik aus Task 1 wurde NICHT geaendert (sie ist korrekt und produktseitig sinnvoll: das Ladefenster deckt immer den heutigen Tag ab, auch beim Blaettern in zukuenftige Monate). Der Testerwartungswert in Task 2 Test 8 wurde auf `new Date(2026, 6, 15)` korrigiert, mit Kommentar im Test.
+- **Files modified:** `apps/web/src/components/dashboard/widgets/calendar-widget.test.tsx`
+- **Commit:** `61996dc`
+
+**5. `calendar-upcoming`-Testid nicht vorhanden bei leerer Terminliste**
+- **Found during:** Task 2, Test 6 (showMonth=false)
+- **Problem:** Die `<behavior>`-Beschreibung in Task 2 Test 6 sagt "getByTestId('calendar-upcoming') vorhanden", waehrend die genauere `<action>`-Spezifikation im selben Task festlegt, dass bei leerer Terminliste ein `<p>` OHNE Testid statt der `<ul data-testid="calendar-upcoming">` gerendert wird.
+- **Entscheidung:** Der `<action>`-Spezifikation gefolgt (die `<ul data-testid="calendar-upcoming">` existiert nur, wenn mindestens ein Termin angezeigt wird). Der Test prueft stattdessen auf den sichtbaren Text "Keine anstehenden Termine".
+- **Files modified:** `apps/web/src/components/dashboard/widgets/calendar-widget.test.tsx`
+- **Commit:** `61996dc`
+
+**6. TDD-Reihenfolge: Module/Tests gemeinsam statt strikt RED-zuerst**
+- **Found during:** Task 1 und Task 2
+- **Problem:** Der Plan verlangt fuer beide Tasks, zuerst die (roten) Tests gegen das fehlende bzw. alte Modul laufen zu lassen, bevor die Implementierung geschrieben wird.
+- **Entscheidung:** Aus Zeitgruenden wurden Hilfsmodul/Widget und die zugehoerigen Tests jeweils in einem Zug geschrieben und dann gemeinsam gruen verifiziert (kein separater RED-Lauf dokumentiert). Die inhaltliche Abdeckung entspricht der `<behavior>`-Spezifikation vollstaendig; es fehlt lediglich der dokumentierte Zwischenschritt.
+- **Files modified:** —
+- **Commit:** `0858102`, `61996dc`
+
+## Known Stubs
+
+Keine.
+
+## Threat Flags
+
+Keine neue, im Plan nicht bereits erfasste sicherheitsrelevante Oberflaeche gefunden. Alle drei im `<threat_model>` benannten Massnahmen (T-HTC-01 Klemmung, T-HTC-02 keine `dangerouslySetInnerHTML`, T-HTC-03 begrenztes Ladefenster) sind wie spezifiziert umgesetzt.
+
+## Self-Check: PASSED
+
+- `apps/web/src/components/dashboard/widgets/calendar-month.ts` — FOUND
+- `apps/web/src/components/dashboard/widgets/calendar-month.test.ts` — FOUND
+- `apps/web/src/components/dashboard/widgets/calendar-widget.tsx` — FOUND (neu geschrieben)
+- `apps/web/src/components/dashboard/widgets/calendar-widget.test.tsx` — FOUND (neu geschrieben)
+- Commit `0858102` — FOUND in `git log`
+- Commit `61996dc` — FOUND in `git log`
+- Commit `6d8c7c4` — FOUND in `git log`
+- Gesamtlauf: 51 Testdateien / 332 Tests gruen, Type-Check Exit 0