From 0fd579b19b41819d99c685e7af66fb508c904c09 Mon Sep 17 00:00:00 2001
From: Jean-Luc Makiola <business@jeanlucmakiola.de>
Date: Wed, 1 Jul 2026 11:51:42 +0200
Subject: [PATCH] feat(contacts): drop {age} from default titles, disclaim it
 when added

A FREQ=YEARLY event has one static title, so {age} is only a sync-time snapshot
and can look wrong on far-future occurrences. Keep it out of the default
templates ({name}'s birthday / anniversary), and when a user does add {age} in
the title-format editor, show a short disclaimer about the snapshot behaviour.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../calendula/ui/settings/SettingsScreen.kt            | 10 ++++++++++
 app/src/main/res/values-de/strings.xml                 |  5 +++--
 app/src/main/res/values/strings.xml                    |  5 +++--
 docs/design/contact-special-dates.md                   |  4 +++-
 4 files changed, 19 insertions(+), 5 deletions(-)

diff --git a/app/src/main/java/de/jeanlucmakiola/calendula/ui/settings/SettingsScreen.kt b/app/src/main/java/de/jeanlucmakiola/calendula/ui/settings/SettingsScreen.kt
index 92220c5..9e096fd 100644
--- a/app/src/main/java/de/jeanlucmakiola/calendula/ui/settings/SettingsScreen.kt
+++ b/app/src/main/java/de/jeanlucmakiola/calendula/ui/settings/SettingsScreen.kt
@@ -1251,6 +1251,16 @@ private fun SpecialDatesTemplateDialog(
                     style = MaterialTheme.typography.bodySmall,
                     color = MaterialTheme.colorScheme.onSurfaceVariant,
                 )
+                // Only warn about {age}'s snapshot behaviour once the user has
+                // actually put it in the template.
+                if (text.contains("{age}")) {
+                    Spacer(Modifier.height(8.dp))
+                    Text(
+                        text = stringResource(R.string.settings_special_dates_template_age_note),
+                        style = MaterialTheme.typography.bodySmall,
+                        color = MaterialTheme.colorScheme.tertiary,
+                    )
+                }
             }
         },
         confirmButton = {
diff --git a/app/src/main/res/values-de/strings.xml b/app/src/main/res/values-de/strings.xml
index 9d00942..d8246bb 100644
--- a/app/src/main/res/values-de/strings.xml
+++ b/app/src/main/res/values-de/strings.xml
@@ -415,8 +415,8 @@
     <string name="special_dates_calendar_birthday">Geburtstage</string>
     <string name="special_dates_calendar_anniversary">Jahrestage</string>
     <string name="special_dates_calendar_custom">Besondere Tage</string>
-    <string name="special_dates_default_title_birthday">{name}s Geburtstag ({age})</string>
-    <string name="special_dates_default_title_anniversary">{name}s Jahrestag ({age})</string>
+    <string name="special_dates_default_title_birthday">{name}s Geburtstag</string>
+    <string name="special_dates_default_title_anniversary">{name}s Jahrestag</string>
     <string name="special_dates_default_title_custom">{name}</string>
     <string name="event_edit_managed_hint">Verwaltet von „%1$s“ — Titel, Datum und Wiederholung werden aus deinen Kontakten synchron gehalten. Erinnerungen, Ort und Notizen kannst du selbst bearbeiten.</string>
     <string name="settings_special_dates_subtitle">Geburtstage &amp; Jahrestage aus Kontakten</string>
@@ -428,6 +428,7 @@
     <string name="settings_special_dates_type_custom">Weitere Tage</string>
     <string name="settings_special_dates_template">Titelformat</string>
     <string name="settings_special_dates_template_hint">Verwende {name} für den Kontakt und {age} für das Alter (ausgeblendet, wenn das Jahr unbekannt ist).</string>
+    <string name="settings_special_dates_template_age_note">Hinweis: {age} ist das Alter zum nächsten Termin beim letzten Sync. Da ein jährlicher Termin nur einen Titel hat, kann es bei weit entfernten Terminen unpassend wirken.</string>
     <string name="settings_special_dates_show_age">Alter anzeigen</string>
     <string name="settings_special_dates_show_age_hint">{age} in Titeln anzeigen, wenn das Geburtsjahr bekannt ist</string>
     <string name="settings_special_dates_sync_now">Jetzt synchronisieren</string>
diff --git a/app/src/main/res/values/strings.xml b/app/src/main/res/values/strings.xml
index 1a93edd..b4c8f0c 100644
--- a/app/src/main/res/values/strings.xml
+++ b/app/src/main/res/values/strings.xml
@@ -357,6 +357,7 @@
     <string name="settings_special_dates_type_custom">Other dates</string>
     <string name="settings_special_dates_template">Title format</string>
     <string name="settings_special_dates_template_hint">Use {name} for the contact and {age} for their age (hidden when the year is unknown).</string>
+    <string name="settings_special_dates_template_age_note">Note: {age} is the age at the next date as of the last sync. Because a yearly event has one title, it can look off on occurrences far in the future.</string>
     <string name="settings_special_dates_show_age">Show age</string>
     <string name="settings_special_dates_show_age_hint">Include {age} in titles when the birth year is known</string>
     <string name="settings_special_dates_sync_now">Sync now</string>
@@ -497,7 +498,7 @@
     <string name="special_dates_calendar_birthday">Birthdays</string>
     <string name="special_dates_calendar_anniversary">Anniversaries</string>
     <string name="special_dates_calendar_custom">Special dates</string>
-    <string name="special_dates_default_title_birthday">{name}\'s birthday ({age})</string>
-    <string name="special_dates_default_title_anniversary">{name}\'s anniversary ({age})</string>
+    <string name="special_dates_default_title_birthday">{name}\'s birthday</string>
+    <string name="special_dates_default_title_anniversary">{name}\'s anniversary</string>
     <string name="special_dates_default_title_custom">{name}</string>
 </resources>
diff --git a/docs/design/contact-special-dates.md b/docs/design/contact-special-dates.md
index 6af36a4..2b27c88 100644
--- a/docs/design/contact-special-dates.md
+++ b/docs/design/contact-special-dates.md
@@ -15,7 +15,9 @@ Implementation notes / deviations from this design:
   sync-adapter URI).
 - **Age is a sync-time snapshot.** A `FREQ=YEARLY` row has one static title, so
   `{age}` reflects the upcoming birthday at the last sync (refreshed daily / on
-  foreground), not a per-occurrence value.
+  foreground), not a per-occurrence value. Because of this, `{age}` is **kept out
+  of the default templates**; users can add it, and the title-format editor shows
+  a disclaimer once they do.
 - New managed calendars seed a per-calendar all-day reminder default of
   on-the-day + one week before, so birthdays get lead time out of the box.
 - Title template is user-editable from day one (`{name}`, `{age}`).