From 90b640054ab9a1affbba12cc27cdbd7aeb8d54b3 Mon Sep 17 00:00:00 2001 From: Jean-Luc Makiola Date: Fri, 13 Nov 2026 19:39:47 +0100 Subject: [PATCH] feat(#481): export and import settings in Backup & restore --- app/build.gradle.kts | 1 + .../calendula/data/backup/SettingsBackup.kt | 197 ++++++++++++ .../data/backup/SettingsBackupEngine.kt | 181 +++++++++++ .../data/backup/SettingsBackupSchema.kt | 106 +++++++ .../calendula/data/backup/SettingsImport.kt | 193 ++++++++++++ .../calendula/data/prefs/CalendarPrefs.kt | 32 +- .../data/prefs/ReminderStatePrefs.kt | 13 +- .../calendula/ui/calendars/BackupScreen.kt | 22 +- .../ui/calendars/SettingsBackupSection.kt | 208 +++++++++++++ .../ui/calendars/SettingsBackupViewModel.kt | 106 +++++++ app/src/main/res/values/strings.xml | 32 ++ .../data/backup/SettingsBackupSchemaTest.kt | 45 +++ .../data/backup/SettingsBackupTest.kt | 291 ++++++++++++++++++ docs/ARCHITECTURE.md | 11 + docs/SETTINGS_BACKUP.md | 126 ++++++++ floret-kit | 2 +- 16 files changed, 1542 insertions(+), 24 deletions(-) create mode 100644 app/src/main/java/de/jeanlucmakiola/calendula/data/backup/SettingsBackup.kt create mode 100644 app/src/main/java/de/jeanlucmakiola/calendula/data/backup/SettingsBackupEngine.kt create mode 100644 app/src/main/java/de/jeanlucmakiola/calendula/data/backup/SettingsBackupSchema.kt create mode 100644 app/src/main/java/de/jeanlucmakiola/calendula/data/backup/SettingsImport.kt create mode 100644 app/src/main/java/de/jeanlucmakiola/calendula/ui/calendars/SettingsBackupSection.kt create mode 100644 app/src/main/java/de/jeanlucmakiola/calendula/ui/calendars/SettingsBackupViewModel.kt create mode 100644 app/src/test/java/de/jeanlucmakiola/calendula/data/backup/SettingsBackupSchemaTest.kt create mode 100644 app/src/test/java/de/jeanlucmakiola/calendula/data/backup/SettingsBackupTest.kt create mode 100644 docs/SETTINGS_BACKUP.md diff --git a/app/build.gradle.kts b/app/build.gradle.kts index 409adcb7..6285729f 100644 --- a/app/build.gradle.kts +++ b/app/build.gradle.kts @@ -177,6 +177,7 @@ dependencies { implementation("de.jeanlucmakiola.floret:core-crash") implementation("de.jeanlucmakiola.floret:core-di") implementation("de.jeanlucmakiola.floret:core-prefs") + implementation("de.jeanlucmakiola.floret:core-backup") implementation("de.jeanlucmakiola.floret:core-reminders") implementation("de.jeanlucmakiola.floret:core-android") implementation("de.jeanlucmakiola.floret:identity") diff --git a/app/src/main/java/de/jeanlucmakiola/calendula/data/backup/SettingsBackup.kt b/app/src/main/java/de/jeanlucmakiola/calendula/data/backup/SettingsBackup.kt new file mode 100644 index 00000000..77070619 --- /dev/null +++ b/app/src/main/java/de/jeanlucmakiola/calendula/data/backup/SettingsBackup.kt @@ -0,0 +1,197 @@ +package de.jeanlucmakiola.calendula.data.backup + +import androidx.datastore.preferences.core.Preferences +import de.jeanlucmakiola.calendula.data.appname.LauncherName +import de.jeanlucmakiola.calendula.data.calendar.ManagedCalendarRow +import de.jeanlucmakiola.calendula.data.prefs.CalendarPrefKeys +import de.jeanlucmakiola.calendula.data.prefs.SettingsKeys +import de.jeanlucmakiola.calendula.domain.CalendarSource +import de.jeanlucmakiola.calendula.domain.contacts.SpecialDateType +import de.jeanlucmakiola.floret.backup.BackupDocument +import de.jeanlucmakiola.floret.backup.BackupResult +import de.jeanlucmakiola.floret.backup.PrefsSection +import de.jeanlucmakiola.floret.backup.invalidBackup +import de.jeanlucmakiola.floret.backup.optBoolean +import de.jeanlucmakiola.floret.backup.optIntList +import de.jeanlucmakiola.floret.backup.optObject +import de.jeanlucmakiola.floret.backup.optObjectList +import de.jeanlucmakiola.floret.backup.optInt +import de.jeanlucmakiola.floret.backup.optString +import de.jeanlucmakiola.floret.backup.readBackup +import de.jeanlucmakiola.floret.backup.requireString +import de.jeanlucmakiola.floret.prefs.Pref +import de.jeanlucmakiola.floret.prefs.get +import kotlinx.serialization.json.JsonArray +import kotlinx.serialization.json.JsonNull +import kotlinx.serialization.json.JsonObject +import kotlinx.serialization.json.JsonPrimitive +import kotlinx.serialization.json.buildJsonObject + +/** + * A calendar as another device can find it again: provider ids are per + * device, so a calendar is named by its account and display name, and a + * special-dates mirror by the date type it mirrors. + */ +data class CalendarIdentity( + val accountName: String, + val accountType: String, + val displayName: String, + val specialDates: SpecialDateType? = null, +) + +/** The per-calendar settings of one calendar; null fields inherit the global default. */ +data class CalendarSettings( + val calendar: CalendarIdentity, + val hidden: Boolean = false, + val lastUsed: Boolean = false, + val eventDurationMinutes: Int? = null, + /** Timed reminder override; an empty list is "no reminder". */ + val reminders: List? = null, + val allDayReminders: List? = null, +) + +/** The app language a file carries; [tag] null follows the system. */ +data class LanguageChoice(val tag: String?) + +/** Everything a settings backup holds. Null [language]/[launcherName]: the file didn't say. */ +data class SettingsBackup( + val prefs: Map, Any>, + val calendars: List, + val language: LanguageChoice? = null, + val launcherName: LauncherName? = null, +) + +internal val plainSection = PrefsSection(SettingsBackupSchema.plain) + +/** + * The backup of [snapshot]. Per-calendar entries are named through + * [calendars] and [managed]; an id neither knows (a deleted calendar's + * leftover) is dropped. + */ +fun buildSettingsBackup( + snapshot: Preferences, + calendars: List, + managed: List, + language: LanguageChoice?, + launcherName: LauncherName?, +): SettingsBackup { + val hidden = snapshot[CalendarPrefKeys.hiddenCalendarIds] + val lastUsed = snapshot[CalendarPrefKeys.lastUsedCalendarId] + val durations = snapshot[SettingsKeys.perCalendarEventDuration] + val reminders = snapshot[SettingsKeys.perCalendarReminderOverride] + val allDay = snapshot[SettingsKeys.perCalendarAllDayReminderOverride] + val ids = hidden + listOfNotNull(lastUsed) + durations.keys + reminders.keys + allDay.keys + val byId = calendars.associateBy { it.id } + val managedType = managed.associate { it.id to it.type } + val entries = ids.sorted().mapNotNull { id -> + val calendar = byId[id] ?: return@mapNotNull null + CalendarSettings( + calendar = CalendarIdentity( + accountName = calendar.accountName, + accountType = calendar.accountType, + displayName = calendar.displayName, + specialDates = managedType[id], + ), + hidden = id in hidden, + lastUsed = id == lastUsed, + eventDurationMinutes = durations[id], + reminders = reminders[id], + allDayReminders = allDay[id], + ) + } + return SettingsBackup( + prefs = plainSection.snapshot(snapshot), + calendars = entries, + language = language, + launcherName = launcherName, + ) +} + +fun encodeSettingsBackup(backup: SettingsBackup, exportedAtMillis: Long, appVersion: String?): String { + val body = buildJsonObject { + put(KEY_SETTINGS, plainSection.encode(backup.prefs)) + put(KEY_CALENDARS, JsonArray(backup.calendars.map { it.toJson() })) + put( + KEY_APP, + buildJsonObject { + backup.language?.let { put(KEY_LANGUAGE, it.tag?.let(::JsonPrimitive) ?: JsonNull) } + backup.launcherName?.let { put(KEY_LAUNCHER_NAME, JsonPrimitive(it.name)) } + }, + ) + } + val document = BackupDocument( + version = SettingsBackupSchema.format.version, + exportedAtMillis = exportedAtMillis, + appVersion = appVersion, + body = body, + ) + return SettingsBackupSchema.format.encode(document) +} + +/** Validates the whole file before anything is applied; see docs/SETTINGS_BACKUP.md. */ +fun decodeSettingsBackup(text: String): BackupResult { + val document = when (val decoded = SettingsBackupSchema.format.decode(text)) { + is BackupResult.Failure -> return decoded + is BackupResult.Success -> decoded.value + } + return readBackup { + val body = document.body + val app = body.optObject(KEY_APP) + SettingsBackup( + prefs = plainSection.read(body.optObject(KEY_SETTINGS) ?: JsonObject(emptyMap())), + calendars = body.optObjectList(KEY_CALENDARS).orEmpty().map { it.toCalendarSettings() }, + language = app?.takeIf { KEY_LANGUAGE in it }?.let { LanguageChoice(it.optString(KEY_LANGUAGE)) }, + launcherName = app?.optString(KEY_LAUNCHER_NAME) + ?.let { name -> LauncherName.entries.firstOrNull { it.name == name } }, + ) + } +} + +private fun CalendarSettings.toJson(): JsonObject = buildJsonObject { + put(KEY_ACCOUNT_NAME, JsonPrimitive(calendar.accountName)) + put(KEY_ACCOUNT_TYPE, JsonPrimitive(calendar.accountType)) + put(KEY_DISPLAY_NAME, JsonPrimitive(calendar.displayName)) + calendar.specialDates?.let { put(KEY_SPECIAL_DATES, JsonPrimitive(it.name)) } + if (hidden) put(KEY_HIDDEN, JsonPrimitive(true)) + if (lastUsed) put(KEY_LAST_USED, JsonPrimitive(true)) + eventDurationMinutes?.let { put(KEY_EVENT_DURATION, JsonPrimitive(it)) } + reminders?.let { put(KEY_REMINDERS, JsonArray(it.map(::JsonPrimitive))) } + allDayReminders?.let { put(KEY_ALL_DAY_REMINDERS, JsonArray(it.map(::JsonPrimitive))) } +} + +/** + * Strict about what it reads. A special-dates type this build doesn't know + * reads as an ordinary calendar, which then simply finds no match. + */ +private fun JsonObject.toCalendarSettings(): CalendarSettings { + val duration = optInt(KEY_EVENT_DURATION) + if (duration != null && duration <= 0) invalidBackup("$KEY_EVENT_DURATION: $duration") + return CalendarSettings( + calendar = CalendarIdentity( + accountName = requireString(KEY_ACCOUNT_NAME), + accountType = requireString(KEY_ACCOUNT_TYPE), + displayName = requireString(KEY_DISPLAY_NAME), + specialDates = optString(KEY_SPECIAL_DATES)?.let { name -> SpecialDateType.entries.firstOrNull { it.name == name } }, + ), + hidden = optBoolean(KEY_HIDDEN) ?: false, + lastUsed = optBoolean(KEY_LAST_USED) ?: false, + eventDurationMinutes = duration, + reminders = optIntList(KEY_REMINDERS), + allDayReminders = optIntList(KEY_ALL_DAY_REMINDERS), + ) +} + +private const val KEY_SETTINGS = "settings" +private const val KEY_CALENDARS = "calendars" +private const val KEY_APP = "app" +private const val KEY_LANGUAGE = "language" +private const val KEY_LAUNCHER_NAME = "launcher_name" +private const val KEY_ACCOUNT_NAME = "account_name" +private const val KEY_ACCOUNT_TYPE = "account_type" +private const val KEY_DISPLAY_NAME = "display_name" +private const val KEY_SPECIAL_DATES = "special_dates" +private const val KEY_HIDDEN = "hidden" +private const val KEY_LAST_USED = "last_used" +private const val KEY_EVENT_DURATION = "event_duration_minutes" +private const val KEY_REMINDERS = "reminders" +private const val KEY_ALL_DAY_REMINDERS = "all_day_reminders" diff --git a/app/src/main/java/de/jeanlucmakiola/calendula/data/backup/SettingsBackupEngine.kt b/app/src/main/java/de/jeanlucmakiola/calendula/data/backup/SettingsBackupEngine.kt new file mode 100644 index 00000000..15397bca --- /dev/null +++ b/app/src/main/java/de/jeanlucmakiola/calendula/data/backup/SettingsBackupEngine.kt @@ -0,0 +1,181 @@ +package de.jeanlucmakiola.calendula.data.backup + +import android.content.Context +import android.util.Log +import androidx.datastore.core.DataStore +import androidx.datastore.preferences.core.Preferences +import androidx.datastore.preferences.core.edit +import dagger.hilt.android.qualifiers.ApplicationContext +import de.jeanlucmakiola.calendula.BuildConfig +import de.jeanlucmakiola.calendula.R +import de.jeanlucmakiola.calendula.data.appname.LauncherNameManager +import de.jeanlucmakiola.calendula.data.calendar.CalendarDataSource +import de.jeanlucmakiola.calendula.data.contacts.ContactSpecialDatesDataSource +import de.jeanlucmakiola.calendula.data.contacts.SpecialDatesScheduler +import de.jeanlucmakiola.calendula.data.contacts.SpecialDatesSyncEngine +import de.jeanlucmakiola.calendula.data.fonts.CustomFontStore +import de.jeanlucmakiola.calendula.data.prefs.SettingsKeys +import de.jeanlucmakiola.calendula.data.reminders.ReminderScanner +import de.jeanlucmakiola.calendula.domain.FontRole +import de.jeanlucmakiola.calendula.widget.requestWidgetRedraw +import de.jeanlucmakiola.floret.backup.BackupProblem +import de.jeanlucmakiola.floret.backup.BackupResult +import de.jeanlucmakiola.floret.di.IoDispatcher +import de.jeanlucmakiola.floret.locale.AppLanguage +import de.jeanlucmakiola.floret.prefs.get +import de.jeanlucmakiola.floret.reminders.ReminderOverride +import kotlinx.coroutines.CancellationException +import kotlinx.coroutines.CoroutineDispatcher +import kotlinx.coroutines.Dispatchers +import kotlinx.coroutines.NonCancellable +import kotlinx.coroutines.flow.first +import kotlinx.coroutines.withContext +import javax.inject.Inject +import javax.inject.Singleton + +/** + * Exports and imports Calendula's settings (#481). The file format and what + * it holds are [SettingsBackupSchema]'s; the import is planned purely by + * [planSettingsImport], written in one DataStore edit, and then followed by + * the side effects the settings screens would have run themselves. + */ +@Singleton +class SettingsBackupEngine @Inject constructor( + private val store: DataStore, + private val calendars: CalendarDataSource, + private val contacts: ContactSpecialDatesDataSource, + private val specialDates: SpecialDatesSyncEngine, + private val reminderScanner: ReminderScanner, + private val launcherNames: LauncherNameManager, + @ApplicationContext private val context: Context, + @IoDispatcher private val io: CoroutineDispatcher, +) { + + suspend fun export(): String = withContext(io) { + val supported = supportedLanguages() + val backup = buildSettingsBackup( + snapshot = store.data.first(), + calendars = runCatching { calendars.calendars() }.getOrDefault(emptyList()), + managed = runCatching { calendars.findManagedCalendars() }.getOrDefault(emptyList()), + language = LanguageChoice(AppLanguage.currentTag(context, supported)), + launcherName = launcherNames.current(), + ) + encodeSettingsBackup(backup, System.currentTimeMillis(), BuildConfig.VERSION_NAME) + } + + /** Validates [text] in full, then replaces the settings; nothing is written for an invalid file. */ + suspend fun import(text: String): BackupResult = withContext(io) { + val backup = when (val decoded = decodeSettingsBackup(text)) { + is BackupResult.Failure -> return@withContext decoded + is BackupResult.Success -> decoded.value + } + val current = store.data.first() + val plan = planSettingsImport(backup, current, environment(current)) + try { + withContext(NonCancellable) { store.edit { plan.applyTo(it) } } + } catch (e: CancellationException) { + throw e + } catch (e: Exception) { + Log.w(TAG, "Settings import could not be written", e) + return@withContext BackupResult.Failure(BackupProblem.NOT_APPLIED, e.message.orEmpty()) + } + val lateSkips = withContext(NonCancellable) { afterImport(plan, current) } + BackupResult.Success(plan.summary(plan.calendars.size + lateSkips.matched, lateSkips.skipped)) + } + + private class LateMatches(val matched: Int, val skipped: List) + + /** + * Brings what reads the settings outside DataStore in line: the mirror, + * reminder alarms, scheduled backups, the launcher alias and the language. + * Each step stands alone, so one failing never undoes the import. + */ + private suspend fun afterImport(plan: SettingsImportPlan, before: Preferences): LateMatches { + val after = store.data.first() + val wasMirroring = before[SettingsKeys.specialDatesEnabled] + val mirroring = after[SettingsKeys.specialDatesEnabled] + var late = LateMatches(0, plan.pendingSpecialDates.map { it.calendar.skipped() }) + step("special dates") { + if (mirroring) { + SpecialDatesScheduler.apply(context, enabled = true) + specialDates.sync() + late = matchSpecialDates(plan) + } else if (wasMirroring) { + SpecialDatesScheduler.apply(context, enabled = false) + specialDates.teardown() + } + } + step("reminders") { reminderScanner.scan() } + step("auto backup") { + BackupScheduler.apply( + context = context, + enabled = after[SettingsKeys.autoBackupEnabled], + intervalMinutes = after[SettingsKeys.autoBackupIntervalMinutes], + hasFolder = after[SettingsKeys.autoBackupFolderUri] != null, + ) + } + plan.launcherName?.let { name -> + step("launcher name") { if (launcherNames.current() != name) launcherNames.set(name) } + } + plan.language?.let { choice -> + step("language") { + if (AppLanguage.currentTag(context, supportedLanguages()) != choice.tag) { + withContext(Dispatchers.Main) { AppLanguage.apply(context, choice.tag) } + requestWidgetRedraw(context) + } + } + } + return late + } + + /** + * The mirror's calendars exist now, so the entries for them get their ids; + * an all-day reminder goes through the mirror, which rewrites its events. + */ + private suspend fun matchSpecialDates(plan: SettingsImportPlan): LateMatches { + val managed = calendars.findManagedCalendars() + val skipped = mutableListOf() + var matched = 0 + val resolved = plan.pendingSpecialDates.mapNotNull { entry -> + val id = managed.firstOrNull { it.type == entry.calendar.specialDates }?.id + if (id == null) skipped += entry.calendar.skipped() else matched++ + id?.let { it to entry } + } + if (resolved.isNotEmpty()) { + store.edit { prefs -> resolved.forEach { (id, entry) -> prefs.addCalendarSettings(id, entry) } } + } + val mirrorEntries = plan.calendars.values + resolved.map { it.second } + mirrorEntries.forEach { entry -> + val type = entry.calendar.specialDates ?: return@forEach + val minutes = entry.allDayReminders ?: return@forEach + val override = if (minutes.isEmpty()) ReminderOverride.None else ReminderOverride.Minutes(minutes) + specialDates.applyReminders(type, override) + } + return LateMatches(matched, skipped) + } + + private fun environment(current: Preferences): ImportEnvironment = ImportEnvironment( + calendars = runCatching { calendars.calendars() }.getOrDefault(emptyList()), + managed = runCatching { calendars.findManagedCalendars() }.getOrDefault(emptyList()), + contactsPermission = contacts.hasPermission(), + customFonts = FontRole.entries.filter { CustomFontStore.exists(context, it) }.toSet(), + hasBackupFolder = current[SettingsKeys.autoBackupFolderUri] != null, + supportedLanguages = supportedLanguages(), + ) + + private fun supportedLanguages(): List = AppLanguage.supportedTags(context, R.xml.locales_config) + + private suspend fun step(name: String, block: suspend () -> Unit) { + try { + block() + } catch (e: CancellationException) { + throw e + } catch (e: Exception) { + Log.w(TAG, "Settings import: $name could not be refreshed", e) + } + } + + private companion object { + const val TAG = "SettingsBackup" + } +} diff --git a/app/src/main/java/de/jeanlucmakiola/calendula/data/backup/SettingsBackupSchema.kt b/app/src/main/java/de/jeanlucmakiola/calendula/data/backup/SettingsBackupSchema.kt new file mode 100644 index 00000000..80623c05 --- /dev/null +++ b/app/src/main/java/de/jeanlucmakiola/calendula/data/backup/SettingsBackupSchema.kt @@ -0,0 +1,106 @@ +package de.jeanlucmakiola.calendula.data.backup + +import de.jeanlucmakiola.calendula.data.prefs.CalendarPrefKeys +import de.jeanlucmakiola.calendula.data.prefs.ReminderStateKeys +import de.jeanlucmakiola.calendula.data.prefs.SettingsKeys +import de.jeanlucmakiola.floret.backup.BackupFormat +import de.jeanlucmakiola.floret.prefs.Pref + +/** + * Which stored keys a settings backup carries (#481), and how. Every key of + * the settings store is in exactly one of the three lists; a test holds that, + * so a new setting cannot ship without deciding. See docs/SETTINGS_BACKUP.md. + */ +internal object SettingsBackupSchema { + + val format = BackupFormat(name = "calendula-settings", version = 1) + + /** Carried as stored and restored over the current value; an absent key restores the default. */ + val plain: List> = listOf( + SettingsKeys.themeMode, + SettingsKeys.dynamicColor, + SettingsKeys.weekStart, + SettingsKeys.softenCalendarColors, + SettingsKeys.brandFont, + SettingsKeys.plainFont, + SettingsKeys.timeFormat, + SettingsKeys.showHourGrid, + SettingsKeys.pastEventDisplay, + SettingsKeys.dimCompletedEvents, + SettingsKeys.showWeekNumbers, + SettingsKeys.monthShowStartTimes, + SettingsKeys.monthViewStyle, + SettingsKeys.timelineScale, + SettingsKeys.multiDayCount, + SettingsKeys.timelineHoursEnabled, + SettingsKeys.timelineHoursStart, + SettingsKeys.timelineHoursEnd, + SettingsKeys.todayButtonInToolbar, + SettingsKeys.dragToReschedule, + SettingsKeys.tapOpensEditor, + SettingsKeys.agendaScreenRange, + SettingsKeys.agendaShowRangeBar, + SettingsKeys.agendaShowToday, + SettingsKeys.defaultView, + SettingsKeys.quickSwitchConfig, + SettingsKeys.drawerViewOrder, + SettingsKeys.defaultFormFields, + SettingsKeys.autofocusEventTitle, + SettingsKeys.defaultEventDurationMinutes, + SettingsKeys.remindersEnabled, + SettingsKeys.allowColorOnUnsupportedCalendars, + SettingsKeys.defaultReminderMinutes, + SettingsKeys.defaultAllDayReminderMinutes, + SettingsKeys.allDayReminderTimeMinutes, + SettingsKeys.snoozeMinutes, + SettingsKeys.autoBackupEnabled, + SettingsKeys.autoBackupIntervalMinutes, + SettingsKeys.specialDatesEnabled, + SettingsKeys.specialDatesShowYear, + ) + SettingsKeys.specialDateTypeEnabled.values + SettingsKeys.specialDatesTitleTemplate.values + + /** + * Keyed by calendar id on disk, so carried per calendar under a portable + * identity instead ([CalendarSettings]) and re-keyed to this device's ids. + */ + val perCalendar: List> = listOf( + CalendarPrefKeys.hiddenCalendarIds, + CalendarPrefKeys.lastUsedCalendarId, + SettingsKeys.perCalendarEventDuration, + SettingsKeys.perCalendarReminderOverride, + SettingsKeys.perCalendarAllDayReminderOverride, + ) + + /** Never exported: this install's own state, bookkeeping, or meaningless on another device. */ + val excluded: List> = ( + listOf( + // Cache-busting counters for the locally imported font file. + SettingsKeys.brandFontStamp, + SettingsKeys.plainFontStamp, + // Legacy defaults for unconfigured widgets; widget configuration stays out. + SettingsKeys.agendaWidgetRange, + SettingsKeys.widgetSize, + // Usage history, not a setting. + SettingsKeys.recentTimeZones, + // First-run wizard progress of this install. + SettingsKeys.onboardingWizardArmed, + CalendarPrefKeys.visibilityNoticePending, + // A SAF grant, which does not survive a reinstall or another device. + SettingsKeys.autoBackupFolderUri, + // Run status. + SettingsKeys.autoBackupLastRun, + SettingsKeys.autoBackupLastSuccess, + SettingsKeys.autoBackupFailures, + SettingsKeys.specialDatesLastRun, + SettingsKeys.specialDatesStalled, + SettingsKeys.specialDatesLastForegroundSync, + // Switch-offs still owed to the provider on this device. + CalendarPrefKeys.pendingDisabledCalendarIds, + // The reminder delivery watermark. + ReminderStateKeys.lastScanMillis, + ) + + SettingsKeys.onboardingDone.values + + // The mirror re-adopts its calendars by their provider marker. + SettingsKeys.specialDatesCalendarId.values + ).distinct() +} diff --git a/app/src/main/java/de/jeanlucmakiola/calendula/data/backup/SettingsImport.kt b/app/src/main/java/de/jeanlucmakiola/calendula/data/backup/SettingsImport.kt new file mode 100644 index 00000000..73dc0437 --- /dev/null +++ b/app/src/main/java/de/jeanlucmakiola/calendula/data/backup/SettingsImport.kt @@ -0,0 +1,193 @@ +package de.jeanlucmakiola.calendula.data.backup + +import androidx.datastore.preferences.core.MutablePreferences +import androidx.datastore.preferences.core.Preferences +import de.jeanlucmakiola.calendula.data.appname.LauncherName +import de.jeanlucmakiola.calendula.data.calendar.ManagedCalendarRow +import de.jeanlucmakiola.calendula.data.prefs.CalendarPrefKeys +import de.jeanlucmakiola.calendula.data.prefs.SettingsKeys +import de.jeanlucmakiola.calendula.domain.CalendarSource +import de.jeanlucmakiola.calendula.domain.FontRole +import de.jeanlucmakiola.calendula.ui.theme.FONT_CUSTOM_TOKEN +import de.jeanlucmakiola.floret.locale.AppLanguage +import de.jeanlucmakiola.floret.prefs.Pref +import de.jeanlucmakiola.floret.prefs.get +import de.jeanlucmakiola.floret.prefs.rawValue +import de.jeanlucmakiola.floret.prefs.set + +/** What this device can take of a backup, read before planning. */ +data class ImportEnvironment( + val calendars: List, + val managed: List, + val contactsPermission: Boolean, + val customFonts: Set, + val hasBackupFolder: Boolean, + val supportedLanguages: List, +) + +/** Something in the file this device could not take, for the import summary. */ +sealed interface SkippedSetting { + /** No calendar on this device matches the file's (or more than one does). */ + data class Calendar(val displayName: String, val accountName: String) : SkippedSetting + + /** A custom font: the font file itself is not part of the backup. */ + data class CustomFont(val role: FontRole) : SkippedSetting + + /** Contact special dates were on, but this device hasn't granted the contacts permission. */ + data object SpecialDates : SkippedSetting + + /** Automatic backup was on, but its folder has to be chosen again here. */ + data object AutoBackupFolder : SkippedSetting + + /** The file's app language isn't one this build ships. */ + data class Language(val tag: String) : SkippedSetting +} + +data class SettingsImportSummary( + val settingsRestored: Int, + val calendarsMatched: Int, + val skipped: List, +) + +/** + * A validated backup laid onto this device: the stored values to write in one + * edit, the side effects the engine runs after it, and the summary. + * [pendingSpecialDates] are mirror calendars that don't exist yet; the engine + * matches them once the mirror's sync has created them. + */ +data class SettingsImportPlan( + val prefs: Map, Any?>, + val calendars: Map, + val pendingSpecialDates: List, + val language: LanguageChoice?, + val launcherName: LauncherName?, + val settingsRestored: Int, + val skipped: List, +) + +/** Plans an import that replaces every backed-up setting; see docs/SETTINGS_BACKUP.md. */ +fun planSettingsImport( + backup: SettingsBackup, + current: Preferences, + environment: ImportEnvironment, +): SettingsImportPlan { + val skipped = mutableListOf() + val prefs = backup.prefs.toMutableMap, Any?>() + + fun keepCurrent(pref: Pref<*>) { + prefs[pref] = current.rawValue(pref) + } + + FontRole.entries.forEach { role -> + val pref = role.fontPref() + if (prefs[pref] == FONT_CUSTOM_TOKEN && role !in environment.customFonts) { + keepCurrent(pref) + skipped += SkippedSetting.CustomFont(role) + } + } + if (prefs[SettingsKeys.specialDatesEnabled] == true && !environment.contactsPermission) { + keepCurrent(SettingsKeys.specialDatesEnabled) + skipped += SkippedSetting.SpecialDates + } + if (prefs[SettingsKeys.autoBackupEnabled] == true && !environment.hasBackupFolder) { + keepCurrent(SettingsKeys.autoBackupEnabled) + skipped += SkippedSetting.AutoBackupFolder + } + + val language = backup.language?.let { choice -> + val tag = choice.tag ?: return@let choice + val resolved = AppLanguage.resolveTag(tag, environment.supportedLanguages) + if (resolved in environment.supportedLanguages) { + LanguageChoice(resolved) + } else { + skipped += SkippedSetting.Language(tag) + null + } + } + + val calendars = linkedMapOf() + val pending = mutableListOf() + backup.calendars.forEach { entry -> + val type = entry.calendar.specialDates + val id = if (type != null) { + environment.managed.firstOrNull { it.type == type }?.id + } else { + environment.calendars + .filter { !it.isManaged && it.matches(entry.calendar) } + .singleOrNull()?.id + } + when { + id != null -> calendars[id] = entry + type != null -> pending += entry + else -> skipped += entry.calendar.skipped() + } + } + + return SettingsImportPlan( + prefs = prefs, + calendars = calendars, + pendingSpecialDates = pending, + language = language, + launcherName = backup.launcherName, + settingsRestored = backup.prefs.size, + skipped = skipped, + ) +} + +/** Writes the plan's stored values, replacing every backed-up setting and all per-calendar ones. */ +fun SettingsImportPlan.applyTo(target: MutablePreferences) { + plainSection.apply(target, prefs) + target.writeCalendarSettings(calendars) +} + +/** + * Replaces the per-calendar keys with [calendars], by this device's ids. A + * last-used calendar only counts from the first entry claiming it. + */ +fun MutablePreferences.writeCalendarSettings(calendars: Map) { + this[CalendarPrefKeys.hiddenCalendarIds] = calendars.filterValues { it.hidden }.keys + this[CalendarPrefKeys.lastUsedCalendarId] = calendars.entries.firstOrNull { it.value.lastUsed }?.key + this[SettingsKeys.perCalendarEventDuration] = + calendars.mapNotNull { (id, entry) -> entry.eventDurationMinutes?.let { id to it } }.toMap() + this[SettingsKeys.perCalendarReminderOverride] = + calendars.mapNotNull { (id, entry) -> entry.reminders?.let { id to it } }.toMap() + this[SettingsKeys.perCalendarAllDayReminderOverride] = + calendars.mapNotNull { (id, entry) -> entry.allDayReminders?.let { id to it } }.toMap() +} + +/** Adds one late-matched calendar's settings to what [writeCalendarSettings] stored. */ +fun MutablePreferences.addCalendarSettings(id: Long, entry: CalendarSettings) { + if (entry.hidden) this[CalendarPrefKeys.hiddenCalendarIds] = this[CalendarPrefKeys.hiddenCalendarIds] + id + if (entry.lastUsed && this[CalendarPrefKeys.lastUsedCalendarId] == null) { + this[CalendarPrefKeys.lastUsedCalendarId] = id + } + entry.eventDurationMinutes?.let { + this[SettingsKeys.perCalendarEventDuration] = this[SettingsKeys.perCalendarEventDuration] + (id to it) + } + entry.reminders?.let { + this[SettingsKeys.perCalendarReminderOverride] = this[SettingsKeys.perCalendarReminderOverride] + (id to it) + } + entry.allDayReminders?.let { + this[SettingsKeys.perCalendarAllDayReminderOverride] = + this[SettingsKeys.perCalendarAllDayReminderOverride] + (id to it) + } +} + +fun CalendarIdentity.skipped(): SkippedSetting = SkippedSetting.Calendar(displayName, accountName) + +fun SettingsImportPlan.summary(calendarsMatched: Int, more: List = emptyList()) = + SettingsImportSummary( + settingsRestored = settingsRestored, + calendarsMatched = calendarsMatched, + skipped = skipped + more, + ) + +private fun CalendarSource.matches(identity: CalendarIdentity): Boolean = + accountType == identity.accountType && + accountName == identity.accountName && + displayName == identity.displayName + +private fun FontRole.fontPref(): Pref = when (this) { + FontRole.BRAND -> SettingsKeys.brandFont + FontRole.PLAIN -> SettingsKeys.plainFont +} diff --git a/app/src/main/java/de/jeanlucmakiola/calendula/data/prefs/CalendarPrefs.kt b/app/src/main/java/de/jeanlucmakiola/calendula/data/prefs/CalendarPrefs.kt index f75b69a4..f2818e55 100644 --- a/app/src/main/java/de/jeanlucmakiola/calendula/data/prefs/CalendarPrefs.kt +++ b/app/src/main/java/de/jeanlucmakiola/calendula/data/prefs/CalendarPrefs.kt @@ -28,9 +28,9 @@ class CalendarPrefs @Inject constructor( ) { private val prefs = PrefStore(store) - val hiddenCalendarIds: Flow> = prefs.flow(HIDDEN_IDS) + val hiddenCalendarIds: Flow> = prefs.flow(CalendarPrefKeys.hiddenCalendarIds) - suspend fun setHiddenCalendarIds(ids: Set) = prefs.set(HIDDEN_IDS, ids) + suspend fun setHiddenCalendarIds(ids: Set) = prefs.set(CalendarPrefKeys.hiddenCalendarIds, ids) /** * Switch-offs the provider does not know about yet, because writing @@ -41,10 +41,10 @@ class CalendarPrefs @Inject constructor( * second visibility model: `CalendarVisibilityReconciler` drains it entry by * entry as soon as the app may write, and nothing adds to it while it may. */ - val pendingDisabledCalendarIds: Flow> = prefs.flow(DISABLED_IDS) + val pendingDisabledCalendarIds: Flow> = prefs.flow(CalendarPrefKeys.pendingDisabledCalendarIds) suspend fun addPendingDisabledCalendarIds(ids: Collection) { - prefs.update(DISABLED_IDS) { it + ids } + prefs.update(CalendarPrefKeys.pendingDisabledCalendarIds) { it + ids } } /** @@ -52,7 +52,7 @@ class CalendarPrefs @Inject constructor( * them, so a run that fails part-way never re-applies what already landed. */ suspend fun removePendingDisabledCalendarIds(ids: Collection) { - prefs.update(DISABLED_IDS) { it - ids.toSet() } + prefs.update(CalendarPrefKeys.pendingDisabledCalendarIds) { it - ids.toSet() } } /** @@ -60,24 +60,26 @@ class CalendarPrefs @Inject constructor( * owed. Null until the reconciler has evaluated it (which needs the calendar * permission), false once it has been shown or was never needed. */ - val visibilityNoticePending: Flow = prefs.flow(VISIBILITY_NOTICE) + val visibilityNoticePending: Flow = prefs.flow(CalendarPrefKeys.visibilityNoticePending) - suspend fun setVisibilityNoticePending(pending: Boolean) = prefs.set(VISIBILITY_NOTICE, pending) + suspend fun setVisibilityNoticePending(pending: Boolean) = prefs.set(CalendarPrefKeys.visibilityNoticePending, pending) /** * The calendar the user last created an event in; preselected in the * event form. Null until the first event is created. */ - val lastUsedCalendarId: Flow = prefs.flow(LAST_USED_CALENDAR) + val lastUsedCalendarId: Flow = prefs.flow(CalendarPrefKeys.lastUsedCalendarId) - suspend fun setLastUsedCalendarId(id: Long) = prefs.set(LAST_USED_CALENDAR, id) + suspend fun setLastUsedCalendarId(id: Long) = prefs.set(CalendarPrefKeys.lastUsedCalendarId, id) - private companion object { - val HIDDEN_IDS = idSetPref("hidden_calendar_ids") - val DISABLED_IDS = idSetPref("disabled_calendar_ids") - val VISIBILITY_NOTICE = nullableBooleanPref("visibility_notice_pending") - val LAST_USED_CALENDAR = nullableLongPref("last_used_calendar_id") - } +} + +/** Every key [CalendarPrefs] stores; the names are on-disk data. */ +internal object CalendarPrefKeys { + val hiddenCalendarIds: Pref> = idSetPref("hidden_calendar_ids") + val pendingDisabledCalendarIds: Pref> = idSetPref("disabled_calendar_ids") + val visibilityNoticePending: Pref = nullableBooleanPref("visibility_notice_pending") + val lastUsedCalendarId: Pref = nullableLongPref("last_used_calendar_id") } /** A comma-joined id set; non-numeric tokens are dropped, and an empty set removes the key. */ diff --git a/app/src/main/java/de/jeanlucmakiola/calendula/data/prefs/ReminderStatePrefs.kt b/app/src/main/java/de/jeanlucmakiola/calendula/data/prefs/ReminderStatePrefs.kt index 47c008f8..cbaf4581 100644 --- a/app/src/main/java/de/jeanlucmakiola/calendula/data/prefs/ReminderStatePrefs.kt +++ b/app/src/main/java/de/jeanlucmakiola/calendula/data/prefs/ReminderStatePrefs.kt @@ -2,6 +2,7 @@ package de.jeanlucmakiola.calendula.data.prefs import androidx.datastore.core.DataStore import androidx.datastore.preferences.core.Preferences +import de.jeanlucmakiola.floret.prefs.Pref import de.jeanlucmakiola.floret.prefs.PrefStore import de.jeanlucmakiola.floret.prefs.nullableLongPref import javax.inject.Inject @@ -23,11 +24,13 @@ class ReminderStatePrefs @Inject constructor( private val prefs = PrefStore(store) /** The watermark, or `null` before the first scan has ever run. */ - suspend fun lastScanMillis(): Long? = prefs.get(LAST_SCAN) + suspend fun lastScanMillis(): Long? = prefs.get(ReminderStateKeys.lastScanMillis) - suspend fun setLastScanMillis(millis: Long) = prefs.set(LAST_SCAN, millis) + suspend fun setLastScanMillis(millis: Long) = prefs.set(ReminderStateKeys.lastScanMillis, millis) - private companion object { - val LAST_SCAN = nullableLongPref("reminder_last_scan_millis") - } +} + +/** The key [ReminderStatePrefs] stores. */ +internal object ReminderStateKeys { + val lastScanMillis: Pref = nullableLongPref("reminder_last_scan_millis") } diff --git a/app/src/main/java/de/jeanlucmakiola/calendula/ui/calendars/BackupScreen.kt b/app/src/main/java/de/jeanlucmakiola/calendula/ui/calendars/BackupScreen.kt index d319ff0c..5dfc6f0a 100644 --- a/app/src/main/java/de/jeanlucmakiola/calendula/ui/calendars/BackupScreen.kt +++ b/app/src/main/java/de/jeanlucmakiola/calendula/ui/calendars/BackupScreen.kt @@ -76,7 +76,9 @@ private val RESTORE_MIME_TYPES = arrayOf( /** * Backup & restore (#69): `.ics` export and restore for local calendars, with - * optional automatic backup. Shares [CalendarsViewModel] with the manager. + * optional automatic backup, and the app's settings as JSON (#481). Shares + * [CalendarsViewModel] with the manager; the settings block works whatever + * state the calendar list is in. * * A full-screen destination hoisted in `CalendarHost`; [onBack] pops it, * [onImport] hands a picked file to the app's normal .ics import flow. @@ -87,6 +89,7 @@ fun BackupScreen( onImport: (Uri) -> Unit, visible: Boolean = true, viewModel: CalendarsViewModel = hiltViewModel(), + settingsBackup: SettingsBackupViewModel = hiltViewModel(), ) { val state by viewModel.backupState.collectAsStateWithLifecycle() val backupResult by viewModel.backupResult.collectAsStateWithLifecycle() @@ -132,6 +135,8 @@ fun BackupScreen( } } + val settings = rememberSettingsBackupActions(settingsBackup) + CollapsingScaffold( title = stringResource(R.string.settings_section_backup), onBack = onBack, @@ -144,8 +149,14 @@ fun BackupScreen( visible = visible, ) { when (val s = state) { - BackupUiState.Loading -> BackupLoading() - is BackupUiState.Failure -> CalendarFailure(reason = s.reason, onRetry = onBack) + BackupUiState.Loading -> { + Box(Modifier.weight(1f)) { BackupLoading() } + SettingsBackupSection(settings) + } + is BackupUiState.Failure -> { + Box(Modifier.weight(1f)) { CalendarFailure(reason = s.reason, onRetry = onBack) } + SettingsBackupSection(settings) + } is BackupUiState.Ready -> BackupContent( exportable = s.exportable, canImport = s.canImport, @@ -158,6 +169,7 @@ fun BackupScreen( }, onExportPick = { showExportPicker = true }, onEditInterval = { showInterval = true }, + settings = settings, ) } } @@ -173,6 +185,7 @@ fun BackupScreen( ) } } + SettingsBackupDialogs(settings, settingsBackup, snackbarHostState) if (showInterval) { BackupIntervalDialog( currentMinutes = autoBackup.intervalMinutes, @@ -213,6 +226,7 @@ private fun BackupContent( onExportAll: () -> Unit, onExportPick: () -> Unit, onEditInterval: () -> Unit, + settings: SettingsBackupActions, ) { val manageCalendars = LocalManageCalendars.current // Restore never depends on export eligibility, and never disappears: when no @@ -233,6 +247,7 @@ private fun BackupContent( leading = { LeadingAvatar(Icons.Default.FileUpload) }, onClick = onRestoreClick, ) + SettingsBackupSection(settings) return } @@ -277,6 +292,7 @@ private fun BackupContent( ) GroupedHint(backupStatusText(autoBackup.status), style = MaterialTheme.typography.bodySmall) } + SettingsBackupSection(settings) } /** diff --git a/app/src/main/java/de/jeanlucmakiola/calendula/ui/calendars/SettingsBackupSection.kt b/app/src/main/java/de/jeanlucmakiola/calendula/ui/calendars/SettingsBackupSection.kt new file mode 100644 index 00000000..c26a4856 --- /dev/null +++ b/app/src/main/java/de/jeanlucmakiola/calendula/ui/calendars/SettingsBackupSection.kt @@ -0,0 +1,208 @@ +package de.jeanlucmakiola.calendula.ui.calendars + +import androidx.activity.compose.rememberLauncherForActivityResult +import androidx.activity.result.contract.ActivityResultContracts +import androidx.compose.foundation.layout.Arrangement +import androidx.compose.foundation.layout.Column +import androidx.compose.foundation.rememberScrollState +import androidx.compose.foundation.verticalScroll +import androidx.compose.material.icons.Icons +import androidx.compose.material.icons.filled.FileDownload +import androidx.compose.material.icons.filled.FileUpload +import androidx.compose.material3.AlertDialog +import androidx.compose.material3.MaterialTheme +import androidx.compose.material3.SnackbarHostState +import androidx.compose.material3.Text +import androidx.compose.material3.TextButton +import androidx.compose.runtime.Composable +import androidx.compose.runtime.LaunchedEffect +import androidx.compose.runtime.MutableState +import androidx.compose.runtime.getValue +import androidx.compose.runtime.mutableStateOf +import androidx.compose.runtime.saveable.rememberSaveable +import androidx.compose.ui.Modifier +import androidx.compose.ui.res.pluralStringResource +import androidx.compose.ui.res.stringResource +import androidx.compose.ui.unit.dp +import androidx.core.net.toUri +import androidx.lifecycle.compose.collectAsStateWithLifecycle +import de.jeanlucmakiola.calendula.R +import de.jeanlucmakiola.calendula.data.backup.SettingsImportSummary +import de.jeanlucmakiola.calendula.data.backup.SkippedSetting +import de.jeanlucmakiola.calendula.domain.FontRole +import de.jeanlucmakiola.calendula.ui.common.LeadingAvatar +import de.jeanlucmakiola.floret.backup.BackupProblem +import de.jeanlucmakiola.floret.components.GroupedHint +import de.jeanlucmakiola.floret.components.GroupedRow +import de.jeanlucmakiola.floret.components.GroupedSectionHeader +import de.jeanlucmakiola.floret.components.Position +import de.jeanlucmakiola.floret.locale.AppLanguage +import java.time.LocalDate + +// What the import picker accepts: providers label .json inconsistently. +private val SETTINGS_MIME_TYPES = arrayOf("application/json", "text/plain", "application/octet-stream") + +/** The Settings block's pickers and the import waiting for its confirmation. */ +class SettingsBackupActions internal constructor( + val busy: Boolean, + internal val pendingImport: MutableState, + val export: () -> Unit, + val import: () -> Unit, +) + +@Composable +fun rememberSettingsBackupActions(viewModel: SettingsBackupViewModel): SettingsBackupActions { + val busy by viewModel.busy.collectAsStateWithLifecycle() + val pendingImport = rememberSaveable { mutableStateOf(null) } + val createFile = rememberLauncherForActivityResult( + ActivityResultContracts.CreateDocument("application/json"), + ) { uri -> uri?.let(viewModel::export) } + val openFile = rememberLauncherForActivityResult( + ActivityResultContracts.OpenDocument(), + ) { uri -> pendingImport.value = uri?.toString() } + return SettingsBackupActions( + busy = busy, + pendingImport = pendingImport, + export = { runCatching { createFile.launch("calendula-settings-${LocalDate.now()}.json") } }, + import = { runCatching { openFile.launch(SETTINGS_MIME_TYPES) } }, + ) +} + +/** Settings export and import (#481), below the events' backup. */ +@Composable +fun SettingsBackupSection(actions: SettingsBackupActions) { + GroupedSectionHeader(stringResource(R.string.settings_backup_header)) + GroupedHint(stringResource(R.string.settings_backup_hint), style = MaterialTheme.typography.bodySmall) + GroupedRow( + title = stringResource(R.string.settings_backup_export), + summary = stringResource(R.string.settings_backup_export_summary), + position = Position.Top, + leading = { LeadingAvatar(Icons.Default.FileDownload) }, + dimmed = actions.busy, + onClick = { if (!actions.busy) actions.export() }, + ) + GroupedRow( + title = stringResource(R.string.settings_backup_import), + summary = stringResource(R.string.settings_backup_import_summary), + position = Position.Bottom, + leading = { LeadingAvatar(Icons.Default.FileUpload) }, + dimmed = actions.busy, + onClick = { if (!actions.busy) actions.import() }, + ) +} + +/** + * The import's confirmation and summary dialogs, and the snackbars for + * everything else. Plain confirmations, so [AlertDialog]s. + */ +@Composable +fun SettingsBackupDialogs( + actions: SettingsBackupActions, + viewModel: SettingsBackupViewModel, + snackbarHostState: SnackbarHostState, +) { + val result by viewModel.result.collectAsStateWithLifecycle() + val exported = stringResource(R.string.settings_backup_export_done) + val exportFailed = stringResource(R.string.settings_backup_export_failed) + val importFailed = BackupProblem.entries.associateWith { stringResource(it.messageRes()) } + + LaunchedEffect(result) { + val message = when (val r = result) { + SettingsBackupResult.Exported -> exported + SettingsBackupResult.ExportFailed -> exportFailed + is SettingsBackupResult.ImportFailed -> importFailed.getValue(r.problem) + is SettingsBackupResult.Imported, null -> return@LaunchedEffect + } + viewModel.consumeResult() + snackbarHostState.showSnackbar(message) + } + + (result as? SettingsBackupResult.Imported)?.let { imported -> + ImportSummaryDialog(imported.summary, onDismiss = viewModel::consumeResult) + } + + actions.pendingImport.value?.let { uri -> + AlertDialog( + onDismissRequest = { actions.pendingImport.value = null }, + title = { Text(stringResource(R.string.settings_backup_import_confirm_title)) }, + text = { Text(stringResource(R.string.settings_backup_import_confirm_message)) }, + confirmButton = { + TextButton( + onClick = { + actions.pendingImport.value = null + viewModel.import(uri.toUri()) + }, + ) { Text(stringResource(R.string.settings_backup_import_confirm_action)) } + }, + dismissButton = { + TextButton(onClick = { actions.pendingImport.value = null }) { + Text(stringResource(R.string.dialog_cancel)) + } + }, + ) + } +} + +@Composable +private fun ImportSummaryDialog(summary: SettingsImportSummary, onDismiss: () -> Unit) { + AlertDialog( + onDismissRequest = onDismiss, + title = { Text(stringResource(R.string.settings_backup_imported_title)) }, + text = { + Column( + verticalArrangement = Arrangement.spacedBy(8.dp), + modifier = Modifier.verticalScroll(rememberScrollState()), + ) { + Text(stringResource(R.string.settings_backup_imported_body)) + if (summary.calendarsMatched > 0) { + Text( + pluralStringResource( + R.plurals.settings_backup_imported_calendars, + summary.calendarsMatched, + summary.calendarsMatched, + ), + ) + } + if (summary.skipped.isNotEmpty()) { + Text( + stringResource(R.string.settings_backup_imported_skipped), + style = MaterialTheme.typography.titleSmall, + ) + summary.skipped.forEach { skipped -> + Text( + "• " + skipped.label(), + style = MaterialTheme.typography.bodyMedium, + color = MaterialTheme.colorScheme.onSurfaceVariant, + ) + } + } + } + }, + confirmButton = { + TextButton(onClick = onDismiss) { Text(stringResource(R.string.dialog_ok)) } + }, + ) +} + +@Composable +private fun SkippedSetting.label(): String = when (this) { + is SkippedSetting.Calendar -> stringResource(R.string.settings_backup_skipped_calendar, displayName, accountName) + is SkippedSetting.CustomFont -> stringResource( + when (role) { + FontRole.BRAND -> R.string.settings_backup_skipped_font_headings + FontRole.PLAIN -> R.string.settings_backup_skipped_font_body + }, + ) + SkippedSetting.SpecialDates -> stringResource(R.string.settings_backup_skipped_special_dates) + SkippedSetting.AutoBackupFolder -> stringResource(R.string.settings_backup_skipped_auto_backup) + is SkippedSetting.Language -> stringResource(R.string.settings_backup_skipped_language, AppLanguage.displayName(tag)) +} + +private fun BackupProblem.messageRes(): Int = when (this) { + BackupProblem.NOT_A_BACKUP -> R.string.settings_backup_import_failed_not_backup + BackupProblem.NEWER_VERSION -> R.string.settings_backup_import_failed_newer + BackupProblem.INVALID_DATA -> R.string.settings_backup_import_failed_invalid + BackupProblem.TOO_LARGE -> R.string.settings_backup_import_failed_too_large + BackupProblem.UNREADABLE -> R.string.settings_backup_import_failed_unreadable + BackupProblem.NOT_APPLIED -> R.string.settings_backup_import_failed +} diff --git a/app/src/main/java/de/jeanlucmakiola/calendula/ui/calendars/SettingsBackupViewModel.kt b/app/src/main/java/de/jeanlucmakiola/calendula/ui/calendars/SettingsBackupViewModel.kt new file mode 100644 index 00000000..46d1eca2 --- /dev/null +++ b/app/src/main/java/de/jeanlucmakiola/calendula/ui/calendars/SettingsBackupViewModel.kt @@ -0,0 +1,106 @@ +package de.jeanlucmakiola.calendula.ui.calendars + +import android.content.Context +import android.net.Uri +import androidx.lifecycle.ViewModel +import androidx.lifecycle.viewModelScope +import dagger.hilt.android.lifecycle.HiltViewModel +import dagger.hilt.android.qualifiers.ApplicationContext +import de.jeanlucmakiola.calendula.data.backup.SettingsBackupEngine +import de.jeanlucmakiola.calendula.data.backup.SettingsImportSummary +import de.jeanlucmakiola.floret.android.DocumentTooLargeException +import de.jeanlucmakiola.floret.android.readDocumentBytes +import de.jeanlucmakiola.floret.android.writeDocumentBytes +import de.jeanlucmakiola.floret.backup.BackupFormat +import de.jeanlucmakiola.floret.backup.BackupProblem +import de.jeanlucmakiola.floret.backup.BackupResult +import de.jeanlucmakiola.floret.di.IoDispatcher +import kotlinx.coroutines.CancellationException +import kotlinx.coroutines.CoroutineDispatcher +import kotlinx.coroutines.flow.MutableStateFlow +import kotlinx.coroutines.flow.StateFlow +import kotlinx.coroutines.flow.asStateFlow +import kotlinx.coroutines.launch +import kotlinx.coroutines.withContext +import javax.inject.Inject + +/** The outcome of a settings export or import, held until the screen has shown it. */ +sealed interface SettingsBackupResult { + data object Exported : SettingsBackupResult + data object ExportFailed : SettingsBackupResult + data class Imported(val summary: SettingsImportSummary) : SettingsBackupResult + data class ImportFailed(val problem: BackupProblem) : SettingsBackupResult +} + +/** + * Settings export/import on the Backup & restore screen (#481). The file is a + * single SAF document the user picked; the engine knows nothing about it. + * The result is state rather than an event, so an import that changes the + * app language — and recreates the activity — still shows its summary. + */ +@HiltViewModel +class SettingsBackupViewModel @Inject constructor( + private val engine: SettingsBackupEngine, + @ApplicationContext private val context: Context, + @IoDispatcher private val io: CoroutineDispatcher, +) : ViewModel() { + + private val _busy = MutableStateFlow(false) + val busy: StateFlow = _busy.asStateFlow() + + private val _result = MutableStateFlow(null) + val result: StateFlow = _result.asStateFlow() + + fun export(uri: Uri) = launchWork { + try { + val text = engine.export() + withContext(io) { context.contentResolver.writeDocumentBytes(uri, text.toByteArray(Charsets.UTF_8)) } + SettingsBackupResult.Exported + } catch (e: CancellationException) { + throw e + } catch (e: Exception) { + SettingsBackupResult.ExportFailed + } + } + + /** Call only once the user has confirmed replacing their settings. */ + fun import(uri: Uri) = launchWork { + val text = try { + withContext(io) { + context.contentResolver.readDocumentBytes(uri, BackupFormat.DEFAULT_MAX_CHARS).toString(Charsets.UTF_8) + } + } catch (e: CancellationException) { + throw e + } catch (e: DocumentTooLargeException) { + return@launchWork SettingsBackupResult.ImportFailed(BackupProblem.TOO_LARGE) + } catch (e: Exception) { + return@launchWork SettingsBackupResult.ImportFailed(BackupProblem.UNREADABLE) + } + try { + when (val imported = engine.import(text)) { + is BackupResult.Success -> SettingsBackupResult.Imported(imported.value) + is BackupResult.Failure -> SettingsBackupResult.ImportFailed(imported.problem) + } + } catch (e: CancellationException) { + throw e + } catch (e: Exception) { + SettingsBackupResult.ImportFailed(BackupProblem.NOT_APPLIED) + } + } + + fun consumeResult() { + _result.value = null + } + + private fun launchWork(work: suspend () -> SettingsBackupResult) { + if (_busy.value) return + _busy.value = true + viewModelScope.launch { + try { + _result.value = work() + } finally { + _busy.value = false + } + } + } +} diff --git a/app/src/main/res/values/strings.xml b/app/src/main/res/values/strings.xml index 278cc7ca..e89f79b4 100644 --- a/app/src/main/res/values/strings.xml +++ b/app/src/main/res/values/strings.xml @@ -910,6 +910,38 @@ Weeks Couldn\'t export the backup. + Settings + Save Calendula\'s settings to a file and restore them after reinstalling or on a new phone. Events aren\'t part of it. + Export settings + Save every setting to a .json file + Import settings + Replace the current settings with a saved file + Settings exported. + Couldn\'t export the settings. + Replace your settings? + Every setting is replaced with the one in the file. Your events and calendars stay as they are. + Replace + That file isn\'t a Calendula settings backup. + That backup is from a newer Calendula. Update the app to import it. + That settings backup is damaged and wasn\'t imported. + That file is too large to be a settings backup. + Couldn\'t read that file. + Couldn\'t import the settings. + Settings imported + Your settings now match the ones in the file. + + Calendar settings were applied to %d calendar. + Calendar settings were applied to %d calendars. + + Not imported + + %1$s (%2$s): no matching calendar on this phone + Custom headings font: choose the font file again + Custom body font: choose the font file again + Contact special dates: turn them on again to allow access to contacts + Automatic backup: choose the backup folder again + + %1$s isn\'t available in this version Exported %d event. Exported %d events. diff --git a/app/src/test/java/de/jeanlucmakiola/calendula/data/backup/SettingsBackupSchemaTest.kt b/app/src/test/java/de/jeanlucmakiola/calendula/data/backup/SettingsBackupSchemaTest.kt new file mode 100644 index 00000000..6813b72b --- /dev/null +++ b/app/src/test/java/de/jeanlucmakiola/calendula/data/backup/SettingsBackupSchemaTest.kt @@ -0,0 +1,45 @@ +package de.jeanlucmakiola.calendula.data.backup + +import com.google.common.truth.Truth.assertThat +import de.jeanlucmakiola.calendula.data.prefs.CalendarPrefKeys +import de.jeanlucmakiola.calendula.data.prefs.ReminderStateKeys +import de.jeanlucmakiola.calendula.data.prefs.SettingsKeys +import de.jeanlucmakiola.floret.prefs.Pref +import org.junit.jupiter.api.Test + +/** + * Every key of the settings store is either backed up or deliberately left + * out. A new key fails here until [SettingsBackupSchema] says which. + */ +class SettingsBackupSchemaTest { + + private val schema = SettingsBackupSchema + + private fun keysOf(holder: Any): List = holder.javaClass.declaredFields + .filter { java.lang.reflect.Modifier.isStatic(it.modifiers) && it.name != "INSTANCE" } + .flatMap { field -> + field.isAccessible = true + when (val value = field.get(null)) { + is Pref<*> -> listOf(value.name) + is Map<*, *> -> value.values.filterIsInstance>().map { it.name } + else -> emptyList() + } + } + + @Test + fun `every stored key is classified`() { + val stored = (keysOf(SettingsKeys) + keysOf(CalendarPrefKeys) + keysOf(ReminderStateKeys)).toSet() + val classified = (schema.plain + schema.perCalendar + schema.excluded).map { it.name } + + assertThat(stored).isNotEmpty() + assertThat(classified).containsAtLeastElementsIn(stored) + assertThat(stored).containsAtLeastElementsIn(classified) + } + + @Test + fun `no key is classified twice`() { + val classified = (schema.plain + schema.perCalendar + schema.excluded).map { it.name } + + assertThat(classified).containsNoDuplicates() + } +} diff --git a/app/src/test/java/de/jeanlucmakiola/calendula/data/backup/SettingsBackupTest.kt b/app/src/test/java/de/jeanlucmakiola/calendula/data/backup/SettingsBackupTest.kt new file mode 100644 index 00000000..1848d99c --- /dev/null +++ b/app/src/test/java/de/jeanlucmakiola/calendula/data/backup/SettingsBackupTest.kt @@ -0,0 +1,291 @@ +package de.jeanlucmakiola.calendula.data.backup + +import androidx.datastore.preferences.core.MutablePreferences +import androidx.datastore.preferences.core.mutablePreferencesOf +import com.google.common.truth.Truth.assertThat +import de.jeanlucmakiola.calendula.data.appname.LauncherName +import de.jeanlucmakiola.calendula.data.calendar.ManagedCalendarRow +import de.jeanlucmakiola.calendula.data.prefs.CalendarPrefKeys +import de.jeanlucmakiola.calendula.data.prefs.SettingsKeys +import de.jeanlucmakiola.calendula.domain.CalendarSource +import de.jeanlucmakiola.calendula.domain.FontRole +import de.jeanlucmakiola.calendula.domain.contacts.SpecialDateType +import de.jeanlucmakiola.calendula.ui.common.CalendarView +import de.jeanlucmakiola.calendula.ui.theme.FONT_CUSTOM_TOKEN +import de.jeanlucmakiola.floret.backup.BackupProblem +import de.jeanlucmakiola.floret.backup.BackupResult +import de.jeanlucmakiola.floret.prefs.ThemeMode +import de.jeanlucmakiola.floret.prefs.get +import de.jeanlucmakiola.floret.prefs.set +import org.junit.jupiter.api.Test + +class SettingsBackupTest { + + private fun calendar(id: Long, name: String, account: String = "me@example.org", managed: Boolean = false) = + CalendarSource( + id = id, + displayName = name, + accountName = account, + accountType = "com.google", + color = 0, + isVisibleInSystem = true, + isManaged = managed, + ) + + private val work = calendar(1, "Work") + private val home = calendar(2, "Home") + private val birthdays = calendar(3, "Birthdays", account = "Calendula", managed = true) + + private fun environment( + calendars: List = listOf(work, home, birthdays), + managed: List = listOf(ManagedCalendarRow(3, SpecialDateType.Birthday)), + contacts: Boolean = true, + fonts: Set = emptySet(), + folder: Boolean = false, + languages: List = listOf("de", "en-US", "fr"), + ) = ImportEnvironment(calendars, managed, contacts, fonts, folder, languages) + + private fun roundTrip(source: MutablePreferences, calendars: List = listOf(work, home, birthdays)): SettingsBackup { + val backup = buildSettingsBackup( + snapshot = source, + calendars = calendars, + managed = listOf(ManagedCalendarRow(3, SpecialDateType.Birthday)), + language = LanguageChoice("de"), + launcherName = LauncherName.CALENDAR, + ) + val decoded = decodeSettingsBackup(encodeSettingsBackup(backup, 1_700_000_000_000, "2.25.0")) + return (decoded as BackupResult.Success).value + } + + private fun import(backup: SettingsBackup, current: MutablePreferences, env: ImportEnvironment = environment()) = + planSettingsImport(backup, current, env).also { it.applyTo(current) } + + @Test + fun `plain settings survive the round trip`() { + val source = mutablePreferencesOf() + source[SettingsKeys.themeMode] = ThemeMode.BLACK + source[SettingsKeys.multiDayCount] = 5 + source[SettingsKeys.defaultView] = CalendarView.Month + source[SettingsKeys.defaultReminderMinutes] = listOf(10, 60) + + val target = mutablePreferencesOf() + import(roundTrip(source), target) + + assertThat(target[SettingsKeys.themeMode]).isEqualTo(ThemeMode.BLACK) + assertThat(target[SettingsKeys.multiDayCount]).isEqualTo(5) + assertThat(target[SettingsKeys.defaultView]).isEqualTo(CalendarView.Month) + assertThat(target[SettingsKeys.defaultReminderMinutes]).containsExactly(10, 60).inOrder() + } + + @Test + fun `a setting the file leaves at its default resets here`() { + val target = mutablePreferencesOf() + target[SettingsKeys.showWeekNumbers] = true + + import(roundTrip(mutablePreferencesOf()), target) + + assertThat(target[SettingsKeys.showWeekNumbers]).isFalse() + } + + @Test + fun `device state is neither exported nor touched`() { + val source = mutablePreferencesOf() + source[SettingsKeys.autoBackupFolderUri] = "content://tree/backup" + source[SettingsKeys.recentTimeZones] = listOf("Europe/Berlin") + val target = mutablePreferencesOf() + target[SettingsKeys.autoBackupLastRun] = 42L + + val backup = roundTrip(source) + import(backup, target) + + assertThat(backup.prefs.keys.map { it.name }).doesNotContain("auto_backup_folder_uri") + assertThat(target[SettingsKeys.autoBackupFolderUri]).isNull() + assertThat(target[SettingsKeys.autoBackupLastRun]).isEqualTo(42L) + } + + @Test + fun `per-calendar settings follow the calendar to its new id`() { + val source = mutablePreferencesOf() + source[CalendarPrefKeys.hiddenCalendarIds] = setOf(1L) + source[CalendarPrefKeys.lastUsedCalendarId] = 2L + source[SettingsKeys.perCalendarEventDuration] = mapOf(1L to 30) + source[SettingsKeys.perCalendarReminderOverride] = mapOf(2L to emptyList()) + val moved = listOf(calendar(11, "Work"), calendar(12, "Home")) + + val target = mutablePreferencesOf() + val plan = import(roundTrip(source), target, environment(calendars = moved, managed = emptyList())) + + assertThat(target[CalendarPrefKeys.hiddenCalendarIds]).containsExactly(11L) + assertThat(target[CalendarPrefKeys.lastUsedCalendarId]).isEqualTo(12L) + assertThat(target[SettingsKeys.perCalendarEventDuration]).containsExactly(11L, 30) + assertThat(target[SettingsKeys.perCalendarReminderOverride]).containsExactly(12L, emptyList()) + assertThat(plan.summary(plan.calendars.size).calendarsMatched).isEqualTo(2) + } + + @Test + fun `a calendar missing here is reported, and its old id is not reused`() { + val source = mutablePreferencesOf() + source[SettingsKeys.perCalendarEventDuration] = mapOf(1L to 30) + val target = mutablePreferencesOf() + target[SettingsKeys.perCalendarEventDuration] = mapOf(1L to 45) + + val plan = import(roundTrip(source), target, environment(calendars = listOf(calendar(1, "Other")))) + + assertThat(target[SettingsKeys.perCalendarEventDuration]).isEmpty() + assertThat(plan.skipped).containsExactly(SkippedSetting.Calendar("Work", "me@example.org")) + } + + @Test + fun `two calendars with the same name and account match neither`() { + val source = mutablePreferencesOf() + source[CalendarPrefKeys.hiddenCalendarIds] = setOf(1L) + + val target = mutablePreferencesOf() + val plan = import(roundTrip(source), target, environment(calendars = listOf(calendar(5, "Work"), calendar(6, "Work")))) + + assertThat(target[CalendarPrefKeys.hiddenCalendarIds]).isEmpty() + assertThat(plan.skipped).hasSize(1) + } + + @Test + fun `a stale id in the prefs is dropped on export`() { + val source = mutablePreferencesOf() + source[CalendarPrefKeys.hiddenCalendarIds] = setOf(1L, 99L) + + assertThat(roundTrip(source).calendars.map { it.calendar.displayName }).containsExactly("Work") + } + + @Test + fun `a mirror calendar is matched by its date type`() { + val source = mutablePreferencesOf() + source[SettingsKeys.perCalendarAllDayReminderOverride] = mapOf(3L to listOf(0, 10080)) + + val target = mutablePreferencesOf() + val renamed = listOf(calendar(7, "Geburtstage", account = "Calendula", managed = true)) + import(roundTrip(source), target, environment(calendars = renamed, managed = listOf(ManagedCalendarRow(7, SpecialDateType.Birthday)))) + + assertThat(target[SettingsKeys.perCalendarAllDayReminderOverride]).containsExactly(7L, listOf(0, 10080)) + } + + @Test + fun `a mirror calendar that doesn't exist yet waits for the sync`() { + val source = mutablePreferencesOf() + source[SettingsKeys.perCalendarAllDayReminderOverride] = mapOf(3L to listOf(0)) + + val target = mutablePreferencesOf() + val plan = import(roundTrip(source), target, environment(managed = emptyList())) + plan.pendingSpecialDates.forEach { target.addCalendarSettings(8L, it) } + + assertThat(plan.skipped).isEmpty() + assertThat(target[SettingsKeys.perCalendarAllDayReminderOverride]).containsExactly(8L, listOf(0)) + } + + @Test + fun `a custom font without its file keeps the current font`() { + val source = mutablePreferencesOf() + source[SettingsKeys.brandFont] = FONT_CUSTOM_TOKEN + source[SettingsKeys.plainFont] = FONT_CUSTOM_TOKEN + val target = mutablePreferencesOf() + target[SettingsKeys.brandFont] = "lora" + + val plan = import(roundTrip(source), target, environment(fonts = setOf(FontRole.PLAIN))) + + assertThat(target[SettingsKeys.brandFont]).isEqualTo("lora") + assertThat(target[SettingsKeys.plainFont]).isEqualTo(FONT_CUSTOM_TOKEN) + assertThat(plan.skipped).containsExactly(SkippedSetting.CustomFont(FontRole.BRAND)) + } + + @Test + fun `contact dates without the permission stay as they are`() { + val source = mutablePreferencesOf() + source[SettingsKeys.specialDatesEnabled] = true + val target = mutablePreferencesOf() + + val plan = import(roundTrip(source), target, environment(contacts = false)) + + assertThat(target[SettingsKeys.specialDatesEnabled]).isFalse() + assertThat(plan.skipped).contains(SkippedSetting.SpecialDates) + } + + @Test + fun `automatic backup without a folder here stays off, its interval comes along`() { + val source = mutablePreferencesOf() + source[SettingsKeys.autoBackupEnabled] = true + source[SettingsKeys.autoBackupIntervalMinutes] = 120L + val target = mutablePreferencesOf() + + val plan = import(roundTrip(source), target) + + assertThat(target[SettingsKeys.autoBackupEnabled]).isFalse() + assertThat(target[SettingsKeys.autoBackupIntervalMinutes]).isEqualTo(120L) + assertThat(plan.skipped).contains(SkippedSetting.AutoBackupFolder) + } + + @Test + fun `automatic backup keeps going where a folder is already set`() { + val source = mutablePreferencesOf() + source[SettingsKeys.autoBackupEnabled] = true + val target = mutablePreferencesOf() + + import(roundTrip(source), target, environment(folder = true)) + + assertThat(target[SettingsKeys.autoBackupEnabled]).isTrue() + } + + @Test + fun `the language resolves against what this build ships`() { + val backup = roundTrip(mutablePreferencesOf()) + + assertThat(planSettingsImport(backup.copy(language = LanguageChoice("en-US")), mutablePreferencesOf(), environment()).language) + .isEqualTo(LanguageChoice("en-US")) + assertThat(planSettingsImport(backup.copy(language = LanguageChoice(null)), mutablePreferencesOf(), environment()).language) + .isEqualTo(LanguageChoice(null)) + val missing = planSettingsImport(backup.copy(language = LanguageChoice("ja")), mutablePreferencesOf(), environment()) + assertThat(missing.language).isNull() + assertThat(missing.skipped).containsExactly(SkippedSetting.Language("ja")) + } + + @Test + fun `app-level choices travel along`() { + val backup = roundTrip(mutablePreferencesOf()) + + assertThat(backup.language).isEqualTo(LanguageChoice("de")) + assertThat(backup.launcherName).isEqualTo(LauncherName.CALENDAR) + } + + @Test + fun `unknown fields from a later build are ignored`() { + val text = """ + {"format":"calendula-settings","version":1,"exportedAt":1,"future":{"x":1}, + "settings":{"multi_day_count":4,"some_new_key":true}, + "calendars":[{"account_name":"a","account_type":"t","display_name":"d","colour":"red"}], + "app":{"launcher_name":"SOMETHING_NEW"}} + """.trimIndent() + + val backup = (decodeSettingsBackup(text) as BackupResult.Success).value + + assertThat(backup.prefs.values).containsExactly(4) + assertThat(backup.calendars).hasSize(1) + assertThat(backup.launcherName).isNull() + assertThat(backup.language).isNull() + } + + @Test + fun `a malformed known field rejects the whole file`() { + listOf( + """{"format":"calendula-settings","version":1,"exportedAt":1,"settings":{"multi_day_count":"4"}}""", + """{"format":"calendula-settings","version":1,"exportedAt":1,"calendars":[{"account_name":"a"}]}""", + """{"format":"calendula-settings","version":1,"exportedAt":1,"calendars":[{"account_name":"a","account_type":"t","display_name":"d","reminders":["x"]}]}""", + ).forEach { text -> + val result = decodeSettingsBackup(text) as BackupResult.Failure + assertThat(result.problem).isEqualTo(BackupProblem.INVALID_DATA) + } + } + + @Test + fun `a newer schema is refused`() { + val result = decodeSettingsBackup("""{"format":"calendula-settings","version":2,"exportedAt":1}""") + + assertThat((result as BackupResult.Failure).problem).isEqualTo(BackupProblem.NEWER_VERSION) + } +} diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 771d9bd7..13ade37d 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -492,6 +492,17 @@ one the calendar accepts. The single-event review form deliberately keeps no col first question is which calendar to use, and answering it clears the colour anyway. +## Settings backup + +Backup & restore also exports the app's settings as versioned JSON (#481), +with the envelope and the generic preference section from floret-kit's +`core-backup`. Every stored key is either carried or deliberately left out +(`SettingsBackupSchema`, enforced by a test); per-calendar settings travel +under the calendar's account and name, since provider ids are per device. An +import replaces rather than merges, in one DataStore edit, then re-runs what +reads settings outside DataStore. Format and per-key decisions: +docs/SETTINGS_BACKUP.md. + ## Testing JUnit 5 + Truth + Turbine on the JVM. The seams that make it work: diff --git a/docs/SETTINGS_BACKUP.md b/docs/SETTINGS_BACKUP.md new file mode 100644 index 00000000..28e8834c --- /dev/null +++ b/docs/SETTINGS_BACKUP.md @@ -0,0 +1,126 @@ +# Settings backup format + +Backup & restore → Settings exports Calendula's settings to a JSON file and +imports one back (#481). Events are not part of it; they have the `.ics` +backup. This file is the schema's source of truth. The envelope and the +`settings` section come from floret-kit's `core-backup` +(`BackupFormat`, `PrefsSection`); `data/backup/SettingsBackup*.kt` implements +the rest. + +## Top level + +```json +{ + "format": "calendula-settings", + "version": 1, + "exportedAt": 1700000000000, + "appVersion": "2.25.0", + "settings": { … }, + "calendars": [ … ], + "app": { … } +} +``` + +- `format` must be exactly `"calendula-settings"`, or the file is not a + settings backup. +- `version` is `1`. A higher version is refused as "from a newer Calendula"; + a change that an older build could misread bumps it. +- `exportedAt` (epoch ms) and `appVersion` are informational. +- The file is limited to 8 MiB. + +## Parsing rules + +- **Unknown fields are ignored**, at any level, so a file from a later build + imports as far as this one understands it. +- **Known fields are strict.** A known key holding the wrong JSON type rejects + the whole file before anything is written. +- **Values are not range-checked.** They are stored as they are and go through + the same reads every setting already does (clamps, enum fallbacks), so an + out-of-range or unknown value degrades to the nearest valid one or the + default. + +## Import semantics + +An import **replaces** every setting the backup covers; it does not merge. A +backed-up setting the file doesn't carry is reset to its default (that is what +the exporting install had). Everything is written in one DataStore edit. After +that the import refreshes what reads settings outside DataStore: the +contact-dates mirror (turned on and synced, or off and torn down, as the +settings toggle does), the reminder scan, the automatic-backup schedule, the +launcher name and the app language. Theme and widgets follow the stored +values on their own. A summary lists what could not be imported. + +## `settings` + +The settings stored under their own on-disk key names, in their stored form, +e.g. `"theme_mode": "DARK"`, `"multi_day_count": 4`, +`"default_reminder_minutes": "10,60"`. Only keys that have been set are +written. `SettingsBackupSchema.plain` lists them: appearance, fonts, +views, the agenda screen, the event form, reminders, automatic backup +(switch and interval) and contact special dates (switch, types, title +templates, year). + +Three are taken only where this device can honour them, otherwise the current +value stays and the summary says why: + +- `brand_font` / `plain_font` set to `custom`: the font file is not in the + backup, so it is taken only if this install already has one for that role. +- `special_dates_enabled` on: needs the contacts permission here. +- `auto_backup_enabled` on: needs a backup folder chosen on this install. + +## `calendars` + +Per-calendar settings are stored by provider id, which means nothing on +another device. Each calendar with any of them is written with a portable +identity instead: + +| Field | Type | Notes | +|---|---|---| +| `account_name` | String | Required. | +| `account_type` | String | Required. | +| `display_name` | String | Required. | +| `special_dates` | String? | `Birthday`/`Anniversary`/`Custom` for a contact-dates mirror calendar. | +| `hidden` | Boolean | Hidden in the drawer's filter. | +| `last_used` | Boolean | Preselected for new events. | +| `event_duration_minutes` | Int? | Per-calendar default length. | +| `reminders` | Int[]? | Timed reminder override; `[]` is "no reminder". | +| `all_day_reminders` | Int[]? | All-day reminder override. | + +On import an entry matches the one calendar here with the same account name, +account type and display name. No match, or more than one, skips it and the +summary names it. A mirror calendar matches by `special_dates` instead, since +its name is localised; when the mirror has not created it yet, it is matched +after the import's sync, and its all-day reminders are applied through the +mirror so its existing events follow. An id in the prefs whose calendar no +longer exists is left out of the export. + +## `app` + +| Field | Type | Notes | +|---|---|---| +| `language` | String? | The app language tag; `null` follows the system. Absent: left as is. A language this build doesn't ship is skipped. | +| `launcher_name` | String? | `CALENDULA` or `CALENDAR`. Unknown: left as is. | + +## Not exported + +`SettingsBackupSchema.excluded`, each for a reason: this install's own state, +bookkeeping, or meaningless on another device. + +- Font stamps (`*_font_stamp`): cache keys for the local font file. +- `agenda_widget_range`, `widget_size`: legacy defaults for unconfigured + widgets. Widget configuration is not part of the backup at all. +- `recent_time_zones`: usage history. +- Onboarding progress and `visibility_notice_pending`. +- `auto_backup_folder_uri`: a SAF grant does not survive a reinstall or + another device. +- Run status: `auto_backup_last_*`, `auto_backup_failures`, + `special_dates_last_run`, `special_dates_stalled_reason`, + `special_dates_last_foreground_sync`. +- `special_dates_calendar_*`: the mirror re-adopts its calendars by their + provider marker. +- `disabled_calendar_ids`: switch-offs not yet written to this device's + provider. Whether a calendar is switched on lives in the provider. +- `reminder_last_scan_millis`: the reminder delivery watermark. + +`SettingsBackupSchemaTest` fails for any stored key that is in none of the +three lists, so a new setting has to be placed before it ships. diff --git a/floret-kit b/floret-kit index a039ab5b..4ca8aa01 160000 --- a/floret-kit +++ b/floret-kit @@ -1 +1 @@ -Subproject commit a039ab5bd470a548d754f2e8e610dc03bbcea40e +Subproject commit 4ca8aa01be110b85f855464389d765b6167493ee