From ffe617dba83e6e3f6976f0d0a895bf3fcf793d4a Mon Sep 17 00:00:00 2001
From: Marcel <marcel@familienarchiv>
Date: Fri, 8 May 2026 10:52:03 +0200
Subject: [PATCH] docs(documents): note nullable minDate/maxDate on
 DocumentDensityResult (#385)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The empty-result case returns null for both bounds, which the TS
codegen surfaces as optional. Future contributors should not "fix"
the missing @Schema(REQUIRED) — it is deliberate.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .../familienarchiv/document/DocumentDensityResult.java   | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/backend/src/main/java/org/raddatz/familienarchiv/document/DocumentDensityResult.java b/backend/src/main/java/org/raddatz/familienarchiv/document/DocumentDensityResult.java
index 5c246113..521feca5 100644
--- a/backend/src/main/java/org/raddatz/familienarchiv/document/DocumentDensityResult.java
+++ b/backend/src/main/java/org/raddatz/familienarchiv/document/DocumentDensityResult.java
@@ -5,6 +5,15 @@ import io.swagger.v3.oas.annotations.media.Schema;
 import java.time.LocalDate;
 import java.util.List;
 
+/**
+ * Result of the timeline density aggregation.
+ *
+ * <p>{@code minDate} / {@code maxDate} are intentionally not marked
+ * {@code @Schema(requiredMode = REQUIRED)} — the empty-result case (no
+ * documents match the filter) returns them as {@code null}, which surfaces in
+ * the generated TypeScript as {@code minDate?: string | null}. Frontend code
+ * must treat them as optional.
+ */
 public record DocumentDensityResult(
         @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
         List<MonthBucket> buckets,