makiolaj/calendula
1
0
Fork 1
Code Actions Releases 32 Activity

Extend onboarding into a wizard (#163) (#169)

Browse Source 
Reviewed-on: https://codeberg.org/jlmakiola/calendula/pulls/169
This commit is contained in:
Jean-Luc Makiola
2026-08-10 17:46:51 +02:00
parent 342af07e09
commit 9dc83ce15b
34 changed files with 2241 additions and 580 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
app/src/androidTest/java/de/jeanlucmakiola/calendula/ui/permission/PermissionScreenTest.kt → app/src/androidTest/java/de/jeanlucmakiola/calendula/ui/onboarding/PermissionScreenTest.kt
View File

@@ -1,4 +1,4 @@
package de.jeanlucmakiola.calendula.ui.permission
package de.jeanlucmakiola.calendula.ui.onboarding
import androidx.compose.ui.test.assertIsDisplayed
import androidx.compose.ui.test.junit4.createComposeRule

91
app/src/main/java/de/jeanlucmakiola/calendula/data/prefs/SettingsPrefs.kt
View File

@@ -550,8 +550,87 @@ class SettingsPrefs @Inject constructor(
prefs[REMINDER_ONBOARDING_KEY] ?: false
}
suspend fun setReminderOnboardingDone() {
store.edit { it[REMINDER_ONBOARDING_KEY] = true }
/** Cleared, not just set: the wizard's back button re-asks a step (#163). */
suspend fun setReminderOnboardingDone(done: Boolean = true) {
store.edit { it[REMINDER_ONBOARDING_KEY] = done }
}
/**
* Whether this install is a fresh one still owing the wizard's optional
* steps (#163). Armed on any launch that holds the calendar permission and
* has not finished the reminder step, and cleared again by
* [finishOnboardingWizard], so an existing user who revokes and re-grants
* the permission isn't re-onboarded.
*/
val onboardingWizardArmed: Flow<Boolean> = store.data.map { prefs ->
prefs[ONBOARDING_WIZARD_ARMED_KEY] ?: false
}
suspend fun armOnboardingWizard() {
store.edit { prefs ->
if (prefs[REMINDER_ONBOARDING_KEY] != true) prefs[ONBOARDING_WIZARD_ARMED_KEY] = true
}
}
/** Whether the wizard's backup step has been answered (or skipped). */
val onboardingBackupDone: Flow<Boolean> = store.data.map { prefs ->
prefs[ONBOARDING_BACKUP_KEY] ?: false
}
suspend fun setOnboardingBackupDone(done: Boolean = true) {
store.edit { it[ONBOARDING_BACKUP_KEY] = done }
}
/** Whether the wizard's default-view step has been answered (or skipped). */
val onboardingViewDone: Flow<Boolean> = store.data.map { prefs ->
prefs[ONBOARDING_VIEW_KEY] ?: false
}
suspend fun setOnboardingViewDone(done: Boolean = true) {
store.edit { it[ONBOARDING_VIEW_KEY] = done }
}
/** Whether the wizard's month-style step has been answered (or skipped). */
val onboardingMonthStyleDone: Flow<Boolean> = store.data.map { prefs ->
prefs[ONBOARDING_MONTH_STYLE_KEY] ?: false
}
suspend fun setOnboardingMonthStyleDone(done: Boolean = true) {
store.edit { it[ONBOARDING_MONTH_STYLE_KEY] = done }
}
/**
* Whether the wizard's calendar-visibility notice has been read. Separate
* from [CalendarPrefs.visibilityNoticePending], which says whether this
* install has anything to announce at all.
*/
val onboardingVisibilityDone: Flow<Boolean> = store.data.map { prefs ->
prefs[ONBOARDING_VISIBILITY_KEY] ?: false
}
suspend fun setOnboardingVisibilityDone(done: Boolean = true) {
store.edit { it[ONBOARDING_VISIBILITY_KEY] = done }
}
/** Whether the wizard's closing screen has been seen. */
val onboardingDoneShown: Flow<Boolean> = store.data.map { prefs ->
prefs[ONBOARDING_DONE_KEY] ?: false
}
suspend fun setOnboardingDoneShown(shown: Boolean = true) {
store.edit { it[ONBOARDING_DONE_KEY] = shown }
}
/**
* Close the wizard for good: the closing screen has been seen and the
* install stops counting as fresh, so a later revoke-and-re-grant is only
* the permission screen. One edit, so the plan can't see it half-closed.
*/
suspend fun finishOnboardingWizard() {
store.edit { prefs ->
prefs[ONBOARDING_DONE_KEY] = true
prefs[ONBOARDING_WIZARD_ARMED_KEY] = false
}
}
/**
@@ -882,6 +961,14 @@ class SettingsPrefs @Inject constructor(
internal const val MAX_EVENT_DURATION = 1_440
internal val REMINDERS_ENABLED_KEY = booleanPreferencesKey("reminders_enabled")
internal val REMINDER_ONBOARDING_KEY = booleanPreferencesKey("reminder_onboarding_done")
internal val ONBOARDING_WIZARD_ARMED_KEY = booleanPreferencesKey("onboarding_wizard_armed")
internal val ONBOARDING_BACKUP_KEY = booleanPreferencesKey("onboarding_backup_done")
internal val ONBOARDING_VIEW_KEY = booleanPreferencesKey("onboarding_view_done")
internal val ONBOARDING_MONTH_STYLE_KEY =
booleanPreferencesKey("onboarding_month_style_done")
internal val ONBOARDING_VISIBILITY_KEY =
booleanPreferencesKey("onboarding_visibility_done")
internal val ONBOARDING_DONE_KEY = booleanPreferencesKey("onboarding_done_shown")
internal val ALLOW_COLOR_UNSUPPORTED_KEY =
booleanPreferencesKey("allow_color_unsupported_calendars")
internal val DEFAULT_REMINDER_KEY = stringPreferencesKey("default_reminder_minutes")

157
app/src/main/java/de/jeanlucmakiola/calendula/ui/RootScreen.kt
View File

@@ -2,12 +2,15 @@ package de.jeanlucmakiola.calendula.ui
import android.Manifest
import android.content.pm.PackageManager
import androidx.compose.animation.Crossfade
import androidx.compose.material3.ExperimentalMaterial3ExpressiveApi
import androidx.compose.material3.MaterialTheme
import androidx.compose.animation.AnimatedContent
import androidx.compose.animation.fadeIn
import androidx.compose.animation.fadeOut
import androidx.compose.animation.togetherWith
import androidx.compose.runtime.Composable
import androidx.compose.runtime.DisposableEffect
import androidx.compose.runtime.LaunchedEffect
import androidx.compose.runtime.SideEffect
import androidx.compose.runtime.mutableIntStateOf
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.setValue
@@ -22,13 +25,22 @@ import androidx.lifecycle.Lifecycle
import androidx.lifecycle.LifecycleEventObserver
import de.jeanlucmakiola.calendula.data.contacts.SpecialDatesScheduler
import de.jeanlucmakiola.calendula.data.contacts.hasContactsPermission
import de.jeanlucmakiola.calendula.ui.calendars.CalendarVisibilityNoticeDialog
import de.jeanlucmakiola.calendula.ui.calendars.CalendarVisibilityNoticeViewModel
import de.jeanlucmakiola.calendula.ui.permission.PermissionScreen
import de.jeanlucmakiola.calendula.ui.permission.ReminderOnboardingScreen
import de.jeanlucmakiola.calendula.ui.permission.ReminderOnboardingViewModel
import de.jeanlucmakiola.calendula.ui.common.rememberCalendarFadeSpec
import de.jeanlucmakiola.calendula.ui.onboarding.OnboardingStep
import de.jeanlucmakiola.calendula.ui.onboarding.OnboardingSteps
import de.jeanlucmakiola.calendula.ui.onboarding.OnboardingViewModel
import de.jeanlucmakiola.calendula.ui.onboarding.onboardingSlideTransition
import de.jeanlucmakiola.calendula.ui.onboarding.rememberOnboardingSlideSpec
import de.jeanlucmakiola.floret.identity.rememberReduceMotion
/** What the root is showing: a wizard step, the app, or neither yet. */
private sealed interface RootTarget {
/** DataStore has not emitted yet — render nothing rather than the wrong screen. */
data object Loading : RootTarget
data object App : RootTarget
data class Step(val step: OnboardingStep) : RootTarget
}
@OptIn(ExperimentalMaterial3ExpressiveApi::class)
@Composable
fun RootScreen(
modifier: Modifier = Modifier,
@@ -76,58 +88,87 @@ fun RootScreen(
onDispose { lifecycle.removeObserver(obs) }
}
// Cross-fade the one-time onboarding gates so granting permission / finishing
// onboarding eases into the next screen instead of snapping. A fade carries no
// spatial motion, so it stays appropriate under "remove animations" too.
val gateSpec = MaterialTheme.motionScheme.fastEffectsSpec<Float>()
Crossfade(targetState = hasPermission, animationSpec = gateSpec, label = "permissionGate") { granted ->
if (granted) {
// Second onboarding gate (v1.4, one-time): reminder notifications.
// Null until DataStore's first emission — render nothing for that
// frame instead of flashing the wrong screen.
val reminderOnboarding: ReminderOnboardingViewModel = hiltViewModel()
val onboardingDone by reminderOnboarding.onboardingDone.collectAsStateWithLifecycle()
// One-time explainer for the switch to the device's own calendar
// visibility (#75), armed by the reconciler.
val visibilityNotice: CalendarVisibilityNoticeViewModel = hiltViewModel()
val noticePending by visibilityNotice.pending.collectAsStateWithLifecycle()
// Runs on entry however the permission was granted, including via
// Android's app-settings screen (caught by the ON_RESUME above).
LaunchedEffect(Unit) {
visibilityNotice.reconcile()
if (!grantedAtLaunch) reminderOnboarding.rearmAfterGrant()
val onboarding: OnboardingViewModel = hiltViewModel()
val plan by onboarding.plan.collectAsStateWithLifecycle()
// The grant is reported however it was taken, including via Android's
// app-settings screen (caught by the ON_RESUME above); arming the wizard
// hangs off that, not off the in-app callback.
LaunchedEffect(hasPermission) {
onboarding.setHasPermission(hasPermission)
if (hasPermission && !grantedAtLaunch) onboarding.onPermissionGranted()
}
// Arms the one-time explainer for the switch to the device's own calendar
// visibility (#75), which the wizard then carries as a step of its own.
LaunchedEffect(hasPermission) {
if (hasPermission) onboarding.reconcileCalendarVisibility()
}
val current = plan
val target: RootTarget = when {
current == null -> RootTarget.Loading
current.current == null -> RootTarget.App
else -> RootTarget.Step(current.current)
}
// Which way the flow is moving, so a step-back slides back. The app sorts
// after every step, so finishing the wizard reads as one more move forward.
val ordinal = when (target) {
RootTarget.Loading -> Int.MIN_VALUE
RootTarget.App -> Int.MAX_VALUE
is RootTarget.Step -> current?.steps?.indexOf(target.step) ?: 0
}
var lastOrdinal by remember { mutableIntStateOf(ordinal) }
val slideDir = if (ordinal < lastOrdinal) -1 else 1
SideEffect { lastOrdinal = ordinal }
val slideSpec = rememberOnboardingSlideSpec()
val fadeSpec = rememberCalendarFadeSpec()
val reduceMotion = rememberReduceMotion()
AnimatedContent(
targetState = target,
transitionSpec = {
// Coming off the blank first frame is not a step change.
if (initialState == RootTarget.Loading) {
fadeIn(fadeSpec).togetherWith(fadeOut(fadeSpec))
} else {
onboardingSlideTransition(
slideDir = slideDir,
spec = slideSpec,
fadeSpec = fadeSpec,
reduceMotion = reduceMotion,
)
}
if (onboardingDone == true && noticePending) {
CalendarVisibilityNoticeDialog(onDismiss = visibilityNotice::dismiss)
}
Crossfade(targetState = onboardingDone, animationSpec = gateSpec, label = "onboardingGate") { done ->
when (done) {
true -> CalendarHost(
modifier = modifier,
requestedDetailKey = requestedDetailKey,
onDetailKeyConsumed = onDetailKeyConsumed,
widgetNavRequest = widgetNavRequest,
onWidgetNavConsumed = onWidgetNavConsumed,
requestedImportUri = requestedImportUri,
onImportConsumed = onImportConsumed,
requestedInsertForm = requestedInsertForm,
requestedInsertSource = requestedInsertSource,
onInsertConsumed = onInsertConsumed,
requestedEditKey = requestedEditKey,
onEditKeyConsumed = onEditKeyConsumed,
)
false -> ReminderOnboardingScreen(
onFinished = reminderOnboarding::finish,
modifier = modifier,
)
null -> {}
}
}
} else {
PermissionScreen(
onGranted = { hasPermission = true },
},
label = "onboardingGate",
) { shown ->
when (shown) {
RootTarget.Loading -> Unit
RootTarget.App -> CalendarHost(
modifier = modifier,
requestedDetailKey = requestedDetailKey,
onDetailKeyConsumed = onDetailKeyConsumed,
widgetNavRequest = widgetNavRequest,
onWidgetNavConsumed = onWidgetNavConsumed,
requestedImportUri = requestedImportUri,
onImportConsumed = onImportConsumed,
requestedInsertForm = requestedInsertForm,
requestedInsertSource = requestedInsertSource,
onInsertConsumed = onInsertConsumed,
requestedEditKey = requestedEditKey,
onEditKeyConsumed = onEditKeyConsumed,
)
// Both halves of a transition read their position out of the live
// plan; the one the outgoing step was drawn with is already gone.
is RootTarget.Step -> current?.let { plan ->
OnboardingSteps(
step = shown.step,
plan = plan,
viewModel = onboarding,
onPermissionGranted = { hasPermission = true },
modifier = modifier,
)
}
}
}
}

2
app/src/main/java/de/jeanlucmakiola/calendula/ui/agenda/AgendaScreen.kt
View File

@@ -276,7 +276,7 @@ private fun AgendaRangeBanner(
}
@Composable
private fun AgendaContent(
internal fun AgendaContent(
state: AgendaUiState,
pastDisplay: PastEventDisplay,
showToday: Boolean,

64
app/src/main/java/de/jeanlucmakiola/calendula/ui/agenda/AgendaViewPreview.kt Normal file
View File

@@ -0,0 +1,64 @@
package de.jeanlucmakiola.calendula.ui.agenda
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.runtime.Composable
import androidx.compose.runtime.remember
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.Dp
import de.jeanlucmakiola.calendula.data.prefs.PastEventDisplay
import de.jeanlucmakiola.calendula.ui.common.ScaledViewPreview
import de.jeanlucmakiola.calendula.ui.common.sampleAgendaEvents
import kotlinx.datetime.DateTimeUnit
import kotlinx.datetime.LocalDate
import kotlinx.datetime.TimeZone
import kotlinx.datetime.plus
import kotlinx.datetime.toLocalDateTime
import kotlin.time.Clock
/** How far ahead the agenda preview's stand-in window runs. */
private const val PREVIEW_WINDOW_DAYS = 14
/**
* A live, scaled-down Agenda view for the onboarding view chooser. Today and
* the day headers are real; only the events are stand-ins.
*/
@Composable
internal fun AgendaViewPreview(
height: Dp,
modifier: Modifier = Modifier,
) {
val zone = remember { TimeZone.currentSystemDefault() }
val today = remember(zone) { Clock.System.now().toLocalDateTime(zone).date }
val state = remember(today, zone) { sampleAgendaState(today, zone) }
ScaledViewPreview(height = height, modifier = modifier) {
AgendaContent(
state = state,
// Stand-in events are all upcoming, so the past-event preference
// cannot change what the preview shows — keep it at the default.
pastDisplay = PastEventDisplay.SHOW,
showToday = true,
onRetry = {},
onEventClick = {},
onOpenDay = {},
modifier = Modifier.fillMaxSize(),
)
}
}
/** Sample agenda state, grouped through the same helper the live view uses. */
private fun sampleAgendaState(today: LocalDate, zone: TimeZone): AgendaUiState.Success {
val windowEnd = today.plus(PREVIEW_WINDOW_DAYS, DateTimeUnit.DAY)
return AgendaUiState.Success(
anchor = today,
today = today,
days = groupAgendaDays(today, windowEnd, sampleAgendaEvents(today, zone), zone),
range = AgendaRange.Custom(PREVIEW_WINDOW_DAYS),
rangeIsOverride = false,
rangeEnd = windowEnd,
// The range bar belongs to the screen, not the list — the preview shows
// the list only.
showRangeBar = false,
zone = zone,
)
}

71
app/src/main/java/de/jeanlucmakiola/calendula/ui/calendars/CalendarVisibilityNotice.kt
View File

@@ -1,71 +0,0 @@
package de.jeanlucmakiola.calendula.ui.calendars
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.VisibilityOff
import androidx.compose.material3.AlertDialog
import androidx.compose.material3.Icon
import androidx.compose.material3.Text
import androidx.compose.material3.TextButton
import androidx.compose.runtime.Composable
import androidx.compose.ui.res.stringResource
import androidx.lifecycle.ViewModel
import androidx.lifecycle.viewModelScope
import dagger.hilt.android.lifecycle.HiltViewModel
import de.jeanlucmakiola.calendula.R
import de.jeanlucmakiola.calendula.data.calendar.CalendarVisibilityReconciler
import de.jeanlucmakiola.calendula.data.prefs.CalendarPrefs
import kotlinx.coroutines.flow.SharingStarted
import kotlinx.coroutines.flow.StateFlow
import kotlinx.coroutines.flow.map
import kotlinx.coroutines.flow.stateIn
import kotlinx.coroutines.launch
import javax.inject.Inject
/**
* The one-time notice that Calendula now follows the device's per-calendar
* visibility (#75), armed by `CalendarVisibilityReconciler`. The app does not
* switch those calendars back on — that would un-hide them everywhere else too.
*/
@HiltViewModel
class CalendarVisibilityNoticeViewModel @Inject constructor(
private val prefs: CalendarPrefs,
private val reconciler: CalendarVisibilityReconciler,
) : ViewModel() {
/**
* Reconcile whenever the app comes up with the calendar permission held,
* rather than off one grant route: a permission granted on Android's
* app-settings screen never reaches the permission screen's callback.
*/
fun reconcile() {
viewModelScope.launch { reconciler.run() }
}
val pending: StateFlow<Boolean> = prefs.visibilityNoticePending
.map { it == true }
.stateIn(
scope = viewModelScope,
started = SharingStarted.WhileSubscribed(5_000L),
initialValue = false,
)
fun dismiss() {
viewModelScope.launch { prefs.setVisibilityNoticePending(false) }
}
}
/** Plain informational dialog — one acknowledgement, nothing to decide. */
@Composable
fun CalendarVisibilityNoticeDialog(onDismiss: () -> Unit) {
AlertDialog(
onDismissRequest = onDismiss,
icon = { Icon(Icons.Default.VisibilityOff, contentDescription = null) },
title = { Text(stringResource(R.string.calendars_visibility_notice_title)) },
text = { Text(stringResource(R.string.calendars_visibility_notice_message)) },
confirmButton = {
TextButton(onClick = onDismiss) {
Text(stringResource(R.string.dialog_ok))
}
},
)
}

169
app/src/main/java/de/jeanlucmakiola/calendula/ui/common/PreviewSamples.kt Normal file
View File

@@ -0,0 +1,169 @@
package de.jeanlucmakiola.calendula.ui.common
import de.jeanlucmakiola.calendula.domain.EventInstance
import kotlinx.datetime.DateTimeUnit
import kotlinx.datetime.LocalDate
import kotlinx.datetime.TimeZone
import kotlinx.datetime.atTime
import kotlinx.datetime.plus
import kotlinx.datetime.toInstant
import kotlin.time.Duration.Companion.minutes
import kotlin.time.Instant
/**
* Stand-in events for the view previews. A preview has no business querying the
* provider for a thumbnail, so every chooser renders the same invented week.
*
* Colours are raw ARGB on purpose: that is what the provider hands out for an
* event, so a theme token here would misrepresent what the views actually draw.
*/
private val SAMPLE_COLORS = listOf(
0xFF3F7BD4.toInt(),
0xFFCE5B4C.toInt(),
0xFF4E9A6A.toInt(),
0xFF8A63C7.toInt(),
)
private val SAMPLE_TITLES = listOf(
"Standup",
"Lunch",
"Review",
"Gym",
"Call",
"Workshop",
"Dentist",
"Trip",
)
/** Hands out [EventInstance]s with running ids and cycling sample titles/colours. */
private class SampleEvents(private val zone: TimeZone) {
private var id = 0L
fun timed(
day: LocalDate,
hour: Int,
minute: Int = 0,
lengthMinutes: Int,
colorIndex: Int,
): EventInstance {
val start = day.atTime(hour, minute).toInstant(zone)
return build(
start = start,
end = start + lengthMinutes.minutes,
isAllDay = false,
colorIndex = colorIndex,
)
}
fun allDay(from: LocalDate, days: Int, colorIndex: Int): EventInstance = build(
// All-day events sit at UTC midnights with an exclusive end.
start = from.atTime(0, 0).toInstant(TimeZone.UTC),
end = from.plus(days, DateTimeUnit.DAY).atTime(0, 0).toInstant(TimeZone.UTC),
isAllDay = true,
colorIndex = colorIndex,
)
private fun build(
start: Instant,
end: Instant,
isAllDay: Boolean,
colorIndex: Int,
): EventInstance {
val next = ++id
return EventInstance(
instanceId = next,
eventId = next,
calendarId = 1L,
title = SAMPLE_TITLES[(next.toInt() - 1) % SAMPLE_TITLES.size],
start = start,
end = end,
isAllDay = isAllDay,
color = SAMPLE_COLORS[colorIndex % SAMPLE_COLORS.size],
location = null,
)
}
}
/**
* A month's worth of stand-ins, spread so most weeks carry something, with one
* multi-day bar bridging cells and a busy today for the split pane.
*/
internal fun sampleMonthEvents(
firstOfMonth: LocalDate,
today: LocalDate,
zone: TimeZone,
): List<EventInstance> {
val sample = SampleEvents(zone)
return buildList {
add(sample.allDay(firstOfMonth.plus(9, DateTimeUnit.DAY), days = 3, colorIndex = 2))
add(sample.timed(firstOfMonth.plus(1, DateTimeUnit.DAY), 9, lengthMinutes = 60, colorIndex = 0))
add(sample.timed(firstOfMonth.plus(4, DateTimeUnit.DAY), 14, lengthMinutes = 120, colorIndex = 1))
add(sample.timed(firstOfMonth.plus(7, DateTimeUnit.DAY), 11, lengthMinutes = 60, colorIndex = 3))
add(sample.timed(firstOfMonth.plus(15, DateTimeUnit.DAY), 10, lengthMinutes = 60, colorIndex = 0))
add(sample.timed(firstOfMonth.plus(18, DateTimeUnit.DAY), 16, lengthMinutes = 60, colorIndex = 2))
add(sample.timed(firstOfMonth.plus(22, DateTimeUnit.DAY), 8, lengthMinutes = 120, colorIndex = 1))
add(sample.timed(firstOfMonth.plus(25, DateTimeUnit.DAY), 13, lengthMinutes = 60, colorIndex = 3))
// Today, so the split pane's list and the grid's dots both have content.
add(sample.timed(today, 9, lengthMinutes = 60, colorIndex = 0))
add(sample.timed(today, 12, lengthMinutes = 60, colorIndex = 1))
add(sample.timed(today, 15, lengthMinutes = 120, colorIndex = 3))
}
}
/**
* Stand-ins for a timeline preview over [days]. [anchor] — the day the preview
* is centred on — gets the busy set, including one overlapping pair so the
* side-by-side lane layout shows; the rest of the week is sparser. A multi-day
* all-day bar is only added when there is more than one column to span.
*/
internal fun sampleTimelineEvents(
days: List<LocalDate>,
anchor: LocalDate,
zone: TimeZone,
): List<EventInstance> {
val sample = SampleEvents(zone)
return buildList {
if (days.size > 1) {
add(sample.allDay(days[days.size / 2], days = 2, colorIndex = 2))
} else {
add(sample.allDay(anchor, days = 1, colorIndex = 2))
}
// The anchor day: enough to fill the column, with 09:30–11:00 running
// under 09:00–10:00 so the overlap resolves into two lanes.
add(sample.timed(anchor, 9, lengthMinutes = 60, colorIndex = 0))
add(sample.timed(anchor, 9, minute = 30, lengthMinutes = 90, colorIndex = 1))
add(sample.timed(anchor, 13, lengthMinutes = 120, colorIndex = 3))
days.filterNot { it == anchor }.forEachIndexed { index, day ->
// Skip every third day so the week doesn't read as a solid block.
if (index % 3 == 2) return@forEachIndexed
add(
sample.timed(
day = day,
hour = 8 + (index * 3) % 9,
lengthMinutes = if (index % 2 == 0) 60 else 90,
colorIndex = index,
),
)
}
}
}
/**
* Stand-ins for the agenda preview: a forward-looking fortnight where the first
* days are busy and later ones thin out, so the grouped-by-day list shows both
* a full day and the gaps between days.
*/
internal fun sampleAgendaEvents(today: LocalDate, zone: TimeZone): List<EventInstance> {
val sample = SampleEvents(zone)
return buildList {
add(sample.timed(today, 9, lengthMinutes = 60, colorIndex = 0))
add(sample.timed(today, 12, minute = 30, lengthMinutes = 60, colorIndex = 1))
add(sample.timed(today, 16, lengthMinutes = 90, colorIndex = 3))
val tomorrow = today.plus(1, DateTimeUnit.DAY)
add(sample.allDay(tomorrow, days = 2, colorIndex = 2))
add(sample.timed(tomorrow, 10, lengthMinutes = 120, colorIndex = 1))
add(sample.timed(today.plus(3, DateTimeUnit.DAY), 14, lengthMinutes = 60, colorIndex = 0))
add(sample.timed(today.plus(6, DateTimeUnit.DAY), 11, lengthMinutes = 60, colorIndex = 3))
add(sample.timed(today.plus(10, DateTimeUnit.DAY), 18, lengthMinutes = 120, colorIndex = 2))
}
}

145
app/src/main/java/de/jeanlucmakiola/calendula/ui/common/ViewPreview.kt Normal file
View File

@@ -0,0 +1,145 @@
package de.jeanlucmakiola.calendula.ui.common
import androidx.compose.animation.Crossfade
import androidx.compose.animation.core.snap
import androidx.compose.animation.core.tween
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.shape.RoundedCornerShape
import androidx.compose.material3.MaterialTheme
import androidx.compose.runtime.Composable
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.draw.clip
import androidx.compose.ui.draw.clipToBounds
import androidx.compose.ui.graphics.TransformOrigin
import androidx.compose.ui.graphics.graphicsLayer
import androidx.compose.ui.input.pointer.PointerEventPass
import androidx.compose.ui.input.pointer.pointerInput
import androidx.compose.ui.layout.layout
import androidx.compose.ui.platform.LocalConfiguration
import androidx.compose.ui.semantics.clearAndSetSemantics
import androidx.compose.ui.unit.Constraints
import androidx.compose.ui.unit.Dp
import androidx.compose.ui.unit.dp
import de.jeanlucmakiola.floret.components.GroupedListInset
import de.jeanlucmakiola.floret.identity.rememberReduceMotion
import kotlin.math.roundToInt
/**
* The viewport a view preview pretends to be: a phone's width by the height a
* calendar view gets under the top bar. Scaling every preview from one fixed
* height keeps them comparable — each shows the same slice of screen.
*/
internal val PREVIEW_VIEWPORT_HEIGHT = 440.dp
/**
* Renders [content] at a full phone viewport and shrinks the finished layout
* into a box [height] tall, for the settings and onboarding choosers. Callers
* pass the *real* view composables, so a preview cannot drift from what it
* depicts.
*
* The [layout] below ignores the incoming constraints so the view measures at a
* phone viewport, and a [graphicsLayer] scale shrinks the result.
* `Modifier.requiredSize` is the obvious alternative but *centres* content that
* overflows its constraints, leaving only the bottom-right corner in the clip.
*/
@Composable
internal fun ScaledViewPreview(
height: Dp,
modifier: Modifier = Modifier,
content: @Composable () -> Unit,
) {
val screenWidth = LocalConfiguration.current.screenWidthDp.dp
val scale = height.value / PREVIEW_VIEWPORT_HEIGHT.value
Box(
modifier = modifier
.clipToBounds()
.background(MaterialTheme.colorScheme.surface)
// A preview is a picture, not a control: swallow touches before the
// view's own clickables see them, and give screen readers one label
// instead of six weeks of day cells.
.pointerInput(Unit) {
awaitPointerEventScope {
while (true) {
awaitPointerEvent(PointerEventPass.Initial).changes
.forEach { it.consume() }
}
}
}
.clearAndSetSemantics { }
// Measure at a full phone viewport but report the scaled size, so the
// node occupies exactly what it draws.
.layout { measurable, _ ->
val fullWidth = screenWidth.roundToPx()
val fullHeight = PREVIEW_VIEWPORT_HEIGHT.roundToPx()
val placeable = measurable.measure(Constraints.fixed(fullWidth, fullHeight))
layout((fullWidth * scale).roundToInt(), (fullHeight * scale).roundToInt()) {
placeable.place(0, 0)
}
}
.graphicsLayer {
scaleX = scale
scaleY = scale
transformOrigin = TransformOrigin(0f, 0f)
},
) {
Column(Modifier.fillMaxSize()) { content() }
}
}
/**
* The stage every preview picker sets its preview on, cross-fading as [selected]
* changes. A preview draws the app's own surface, so a tonal plate gives it the
* edge it would otherwise lack on a chooser screen; the plate takes the width
* and outer radius of the grouped rows underneath so the two read as one stack.
*
* Only vertical spacing is the caller's to pass — the horizontal inset is the
* rows' own, and the alignment is the point.
*/
@Composable
internal fun <T> ViewPreviewFrame(
selected: T,
label: String,
modifier: Modifier = Modifier,
content: @Composable (T) -> Unit,
) {
val reduceMotion = rememberReduceMotion()
Box(
modifier = modifier
.fillMaxWidth()
.padding(horizontal = GroupedListInset)
.clip(FRAME_SHAPE)
.background(MaterialTheme.colorScheme.surfaceContainerHigh)
.padding(FRAME_INSET),
contentAlignment = Alignment.Center,
) {
Crossfade(
targetState = selected,
animationSpec = if (reduceMotion) snap() else tween(durationMillis = 250),
label = label,
) { shown ->
// Each preview renders the real view at phone size and scales it
// down, so its own corners are square — the plate rounds them.
Box(
modifier = Modifier
.clip(PREVIEW_SHAPE)
.background(MaterialTheme.colorScheme.surface)
.clipToBounds(),
) {
content(shown)
}
}
}
}
private val FRAME_INSET = 8.dp
/** The grouped rows' own outer radius, so the stack shares one silhouette. */
private val FRAME_SHAPE = RoundedCornerShape(22.dp)
private val PREVIEW_SHAPE = RoundedCornerShape(12.dp)

4
app/src/main/java/de/jeanlucmakiola/calendula/ui/day/DayScreen.kt
View File

@@ -131,7 +131,7 @@ private val ALL_DAY_ROW_HEIGHT = 24.dp
private val ALL_DAY_VERTICAL_PADDING = 6.dp
/** Total all-day strip height for the day (0 when there are no all-day events). */
private fun DayUiState.Success.allDayStripHeight(): Dp {
internal fun DayUiState.Success.allDayStripHeight(): Dp {
if (allDay.isEmpty()) return 0.dp
val lanes = allDay.maxOf { it.lane } + 1
return ALL_DAY_ROW_HEIGHT * lanes + ALL_DAY_VERTICAL_PADDING * 2
@@ -366,7 +366,7 @@ private fun DayContent(
}
@Composable
private fun DaySuccess(
internal fun DaySuccess(
state: DayUiState.Success,
topSectionColor: Color,
scrollState: ScrollState,

65
app/src/main/java/de/jeanlucmakiola/calendula/ui/day/DayViewPreview.kt Normal file
View File

@@ -0,0 +1,65 @@
package de.jeanlucmakiola.calendula.ui.day
import androidx.compose.foundation.rememberScrollState
import androidx.compose.material3.MaterialTheme
import androidx.compose.runtime.Composable
import androidx.compose.runtime.LaunchedEffect
import androidx.compose.runtime.remember
import androidx.compose.runtime.snapshotFlow
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.Dp
import de.jeanlucmakiola.calendula.ui.common.ScaledViewPreview
import de.jeanlucmakiola.calendula.ui.common.rememberTimelineDragController
import de.jeanlucmakiola.calendula.ui.common.sampleTimelineEvents
import de.jeanlucmakiola.calendula.ui.week.layoutAllDay
import de.jeanlucmakiola.calendula.ui.week.layoutDay
import kotlinx.coroutines.flow.first
import kotlinx.datetime.LocalDate
import kotlinx.datetime.TimeZone
import kotlinx.datetime.toLocalDateTime
import kotlin.time.Clock
/**
* A live, scaled-down Day view for the onboarding view chooser. Today's date is
* real; only the events are stand-ins.
*/
@Composable
internal fun DayViewPreview(
height: Dp,
modifier: Modifier = Modifier,
) {
val zone = remember { TimeZone.currentSystemDefault() }
val today = remember(zone) { Clock.System.now().toLocalDateTime(zone).date }
val state = remember(today, zone) { sampleDayState(today, zone) }
val scrollState = rememberScrollState()
LaunchedEffect(Unit) {
snapshotFlow { scrollState.maxValue }.first { it > 0 }
// Half the scroll range is noon — the same centring the live view does.
scrollState.scrollTo(scrollState.maxValue / 2)
}
ScaledViewPreview(height = height, modifier = modifier) {
DaySuccess(
state = state,
topSectionColor = MaterialTheme.colorScheme.surface,
scrollState = scrollState,
allDayHeight = state.allDayStripHeight(),
dragController = rememberTimelineDragController(),
onEventClick = {},
onCreateAt = { _, _ -> },
onDrop = {},
)
}
}
/** Sample day state, laid out through the same helpers the live view uses. */
private fun sampleDayState(today: LocalDate, zone: TimeZone): DayUiState.Success {
val days = listOf(today)
val events = sampleTimelineEvents(days, today, zone)
return DayUiState.Success(
date = today,
today = today,
allDay = layoutAllDay(events.filter { it.isAllDay }, days, zone),
timed = layoutDay(events, today, zone),
)
}

248
app/src/main/java/de/jeanlucmakiola/calendula/ui/month/MonthStylePreview.kt
View File

@@ -1,54 +1,31 @@
package de.jeanlucmakiola.calendula.ui.month
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.lazy.rememberLazyListState
import androidx.compose.material3.MaterialTheme
import androidx.compose.runtime.Composable
import androidx.compose.runtime.remember
import androidx.compose.ui.Modifier
import androidx.compose.ui.draw.clipToBounds
import androidx.compose.ui.layout.layout
import androidx.compose.ui.unit.Constraints
import androidx.compose.ui.graphics.TransformOrigin
import androidx.compose.ui.graphics.graphicsLayer
import androidx.compose.ui.input.pointer.PointerEventPass
import androidx.compose.ui.input.pointer.pointerInput
import androidx.compose.ui.platform.LocalConfiguration
import androidx.compose.ui.semantics.clearAndSetSemantics
import androidx.compose.ui.unit.Dp
import androidx.compose.ui.unit.dp
import de.jeanlucmakiola.calendula.domain.EventInstance
import de.jeanlucmakiola.calendula.ui.common.ScaledViewPreview
import de.jeanlucmakiola.calendula.ui.common.sampleMonthEvents
import kotlinx.datetime.DateTimeUnit
import kotlinx.datetime.DayOfWeek
import kotlinx.datetime.LocalDate
import kotlinx.datetime.TimeZone
import kotlinx.datetime.YearMonth
import kotlinx.datetime.atTime
import kotlinx.datetime.plus
import kotlinx.datetime.toInstant
import kotlinx.datetime.toLocalDateTime
import kotlin.time.Clock
import kotlin.math.roundToInt
/**
* A live, scaled-down Month view in a given [MonthViewStyle], for the settings
* chooser.
*
* It renders the *real* grid composables rather than a drawing of them, so the
* preview cannot drift from the thing it depicts: change a cell's shape or an
* event bar's colour and every preview follows automatically. The trick is
* [requiredSize] — it ignores the incoming constraints, so the grid lays itself
* out at a full phone width and a plausible viewport height, and a
* [graphicsLayer] scale shrinks the finished layout into the card.
* and onboarding choosers.
*
* The month, today's position and the week start are all real; only the events
* are stand-ins, since the settings screen has no business querying the
* provider for a thumbnail.
* are stand-ins. See [ScaledViewPreview] for how the real grid composables get
* measured at phone size and shrunk into the card.
*/
@Composable
internal fun MonthStylePreview(
@@ -57,108 +34,61 @@ internal fun MonthStylePreview(
height: Dp,
modifier: Modifier = Modifier,
) {
val screenWidth = LocalConfiguration.current.screenWidthDp.dp
val scale = height.value / VIRTUAL_HEIGHT.value
val zone = remember { TimeZone.currentSystemDefault() }
val today = remember(zone) { Clock.System.now().toLocalDateTime(zone).date }
val sample = remember(today, weekStart, zone) { sampleMonthState(today, weekStart, zone) }
Box(
modifier = modifier
.clipToBounds()
.background(MaterialTheme.colorScheme.surface)
// A preview is a picture, not a control: swallow touches before the
// grid's own clickables see them, and give screen readers one label
// instead of six weeks of day cells.
.pointerInput(Unit) {
awaitPointerEventScope {
while (true) {
awaitPointerEvent(PointerEventPass.Initial).changes
.forEach { it.consume() }
}
}
}
.clearAndSetSemantics { }
// Measure the grid at a full phone viewport but report the scaled
// size, so the node occupies exactly what it draws.
//
// Modifier.requiredSize would be the obvious way to force the larger
// measurement, but it *centres* content that overflows the incoming
// constraints — which pushed the grid to a negative offset and left
// only its bottom-right corner inside the clip.
.layout { measurable, _ ->
val fullWidth = screenWidth.roundToPx()
val fullHeight = VIRTUAL_HEIGHT.roundToPx()
val placeable = measurable.measure(Constraints.fixed(fullWidth, fullHeight))
layout((fullWidth * scale).roundToInt(), (fullHeight * scale).roundToInt()) {
placeable.place(0, 0)
}
}
.graphicsLayer {
scaleX = scale
scaleY = scale
transformOrigin = TransformOrigin(0f, 0f)
},
) {
Column(Modifier.fillMaxSize()) {
WeekdayHeader(weekStart = weekStart, showWeekNumbers = false)
when (style) {
MonthViewStyle.Paged -> MonthGrid(
state = sample.month,
showWeekNumbers = false,
onOpenDay = {},
)
MonthViewStyle.Continuous -> ContinuousMonthGrid(
state = sample.continuous,
listState = rememberLazyListState(
initialFirstVisibleItemIndex = itemIndexForMonth(
monthIndexOf(YearMonth(today.year, today.month)),
),
),
showWeekNumbers = false,
onOpenDay = {},
)
MonthViewStyle.Dense -> DenseMonthGrid(
state = sample.continuous,
listState = rememberLazyListState(
// Start a week above today's, so the preview shows a
// stream running past the viewport rather than one
// beginning at its top edge.
initialFirstVisibleItemIndex =
weekIndexOf(today, weekStart) - 1,
),
showWeekNumbers = false,
onOpenDay = {},
)
MonthViewStyle.Split -> {
SplitMonthGrid(
state = sample.month,
selected = today,
showWeekNumbers = false,
onSelectDay = {},
)
SplitDayPane(
date = today,
today = today,
events = sample.month.instancesByDay[today].orEmpty(),
zone = zone,
onOpenDay = {},
onEventClick = {},
onCreateEvent = {},
modifier = Modifier.fillMaxWidth().height(SPLIT_PANE_HEIGHT),
)
}
}
ScaledViewPreview(height = height, modifier = modifier) {
WeekdayHeader(weekStart = weekStart, showWeekNumbers = false)
when (style) {
MonthViewStyle.Paged -> MonthGrid(
state = sample.month,
showWeekNumbers = false,
onOpenDay = {},
)
MonthViewStyle.Continuous -> ContinuousMonthGrid(
state = sample.continuous,
listState = rememberLazyListState(
initialFirstVisibleItemIndex = itemIndexForMonth(
monthIndexOf(YearMonth(today.year, today.month)),
),
),
showWeekNumbers = false,
onOpenDay = {},
)
MonthViewStyle.Dense -> DenseMonthGrid(
state = sample.continuous,
listState = rememberLazyListState(
// Start a week above today's, so the preview shows a stream
// running past the viewport rather than one beginning at its
// top edge.
initialFirstVisibleItemIndex = weekIndexOf(today, weekStart) - 1,
),
showWeekNumbers = false,
onOpenDay = {},
)
MonthViewStyle.Split -> {
SplitMonthGrid(
state = sample.month,
selected = today,
showWeekNumbers = false,
onSelectDay = {},
)
SplitDayPane(
date = today,
today = today,
events = sample.month.instancesByDay[today].orEmpty(),
zone = zone,
onOpenDay = {},
onEventClick = {},
onCreateEvent = {},
modifier = Modifier.fillMaxWidth().height(SPLIT_PANE_HEIGHT),
)
}
}
}
}
/**
* The viewport the preview pretends to be: a phone's width by the height a
* calendar view gets under the top bar. Scaling from a fixed height keeps the
* three styles comparable — each shows the same slice of screen.
*/
private val VIRTUAL_HEIGHT = 440.dp
private val SPLIT_PANE_HEIGHT = 170.dp
private class SampleMonth(
@@ -170,9 +100,6 @@ private class SampleMonth(
* A month's worth of stand-in events, laid out through the same
* [layoutMonthWeeks] / [clipWeekToMonth] the live views use — so the preview
* exercises the real span, lane and overflow logic rather than approximating it.
*
* Colours are raw ARGB on purpose: that is what the provider hands out for an
* event, so a token here would misrepresent what the grid actually renders.
*/
private fun sampleMonthState(
today: LocalDate,
@@ -181,7 +108,7 @@ private fun sampleMonthState(
): SampleMonth {
val ym = YearMonth(today.year, today.month)
val first = LocalDate(ym.year, ym.month, 1)
val events = sampleEvents(first, today, zone)
val events = sampleMonthEvents(first, today, zone)
val weeks = layoutMonthWeeks(ym, weekStart, events, zone)
val month = MonthUiState.Success(
@@ -213,72 +140,3 @@ private fun sampleMonthState(
)
return SampleMonth(month, continuous)
}
private val SAMPLE_COLORS = listOf(
0xFF3F7BD4.toInt(),
0xFFCE5B4C.toInt(),
0xFF4E9A6A.toInt(),
0xFF8A63C7.toInt(),
)
private fun sampleEvents(
firstOfMonth: LocalDate,
today: LocalDate,
zone: TimeZone,
): List<EventInstance> {
var id = 0L
fun next() = ++id
fun timed(day: LocalDate, hour: Int, length: Int, colorIndex: Int) = EventInstance(
instanceId = next(),
eventId = id,
calendarId = 1L,
title = SAMPLE_TITLES[(id.toInt() - 1) % SAMPLE_TITLES.size],
start = day.atTime(hour, 0).toInstant(zone),
end = day.atTime(hour + length, 0).toInstant(zone),
isAllDay = false,
color = SAMPLE_COLORS[colorIndex % SAMPLE_COLORS.size],
location = null,
)
fun allDay(from: LocalDate, days: Int, colorIndex: Int) = EventInstance(
instanceId = next(),
eventId = id,
calendarId = 1L,
title = SAMPLE_TITLES[(id.toInt() - 1) % SAMPLE_TITLES.size],
// All-day events sit at UTC midnights with an exclusive end.
start = from.atTime(0, 0).toInstant(TimeZone.UTC),
end = from.plus(days, DateTimeUnit.DAY).atTime(0, 0).toInstant(TimeZone.UTC),
isAllDay = true,
color = SAMPLE_COLORS[colorIndex % SAMPLE_COLORS.size],
location = null,
)
// Spread across the month so most weeks carry something, with one multi-day
// bar to show a span bridging cells and a busy today for the split pane.
return buildList {
add(allDay(firstOfMonth.plus(9, DateTimeUnit.DAY), days = 3, colorIndex = 2))
add(timed(firstOfMonth.plus(1, DateTimeUnit.DAY), 9, 1, 0))
add(timed(firstOfMonth.plus(4, DateTimeUnit.DAY), 14, 2, 1))
add(timed(firstOfMonth.plus(7, DateTimeUnit.DAY), 11, 1, 3))
add(timed(firstOfMonth.plus(15, DateTimeUnit.DAY), 10, 1, 0))
add(timed(firstOfMonth.plus(18, DateTimeUnit.DAY), 16, 1, 2))
add(timed(firstOfMonth.plus(22, DateTimeUnit.DAY), 8, 2, 1))
add(timed(firstOfMonth.plus(25, DateTimeUnit.DAY), 13, 1, 3))
// Today, so the split pane's list and the grid's dots both have content.
add(timed(today, 9, 1, 0))
add(timed(today, 12, 1, 1))
add(timed(today, 15, 2, 3))
}
}
private val SAMPLE_TITLES = listOf(
"Standup",
"Lunch",
"Review",
"Gym",
"Call",
"Workshop",
"Dentist",
"Trip",
)

100
app/src/main/java/de/jeanlucmakiola/calendula/ui/onboarding/BackupStep.kt Normal file
View File

@@ -0,0 +1,100 @@
package de.jeanlucmakiola.calendula.ui.onboarding
import android.net.Uri
import androidx.activity.compose.rememberLauncherForActivityResult
import androidx.activity.result.contract.ActivityResultContracts
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.CloudOff
import androidx.compose.material.icons.filled.FolderOpen
import androidx.compose.material.icons.filled.Schedule
import androidx.compose.material3.Button
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Text
import androidx.compose.material3.TextButton
import androidx.compose.runtime.Composable
import androidx.compose.ui.Modifier
import androidx.compose.ui.res.stringResource
import androidx.compose.ui.text.style.TextAlign
import androidx.compose.ui.unit.dp
import de.jeanlucmakiola.calendula.R
import de.jeanlucmakiola.floret.components.BenefitRow
import de.jeanlucmakiola.floret.components.OnboardingScaffold
import de.jeanlucmakiola.floret.components.OnboardingSpace
/**
* Wizard step shown only when everything you write to is a device-only calendar
* (#163): the events exist nowhere but this phone, so losing it loses them.
*
* The primary action picks a folder and switches automatic backup on in one go.
* Everything it sets is a normal Backup setting, adjustable afterwards.
*/
@Composable
internal fun BackupStep(
onEnable: (Uri) -> Unit,
onSkip: () -> Unit,
modifier: Modifier = Modifier,
progress: (@Composable () -> Unit)? = null,
navigationIcon: (@Composable () -> Unit)? = null,
) {
val pickFolder = rememberLauncherForActivityResult(
contract = ActivityResultContracts.OpenDocumentTree(),
) { uri ->
// Cancelling the picker decides nothing and leaves the step open.
uri?.let(onEnable)
}
OnboardingScaffold(
modifier = modifier,
progress = progress,
navigationIcon = navigationIcon,
topSpacing = OnboardingSpace.lg,
hero = { IconHero(Icons.Filled.CloudOff) },
actions = {
Button(
onClick = { runCatching { pickFolder.launch(null) } },
modifier = Modifier.fillMaxWidth().height(56.dp),
) {
Text(
text = stringResource(R.string.onboarding_backup_enable_button),
style = MaterialTheme.typography.titleMedium,
)
}
TextButton(
onClick = onSkip,
modifier = Modifier.fillMaxWidth(),
) {
Text(stringResource(R.string.onboarding_backup_skip_button))
}
},
) {
Text(
text = stringResource(R.string.onboarding_backup_title),
style = MaterialTheme.typography.headlineMedium,
textAlign = TextAlign.Center,
)
Spacer(Modifier.height(12.dp))
Text(
text = stringResource(R.string.onboarding_backup_body),
style = MaterialTheme.typography.bodyLarge,
color = MaterialTheme.colorScheme.onSurfaceVariant,
textAlign = TextAlign.Center,
)
Spacer(Modifier.height(OnboardingSpace.lg))
BenefitRow(
icon = Icons.Filled.FolderOpen,
title = stringResource(R.string.onboarding_backup_benefit_folder_title),
body = stringResource(R.string.onboarding_backup_benefit_folder_body),
)
Spacer(Modifier.height(OnboardingSpace.sm))
BenefitRow(
icon = Icons.Filled.Schedule,
title = stringResource(R.string.onboarding_backup_benefit_daily_title),
body = stringResource(R.string.onboarding_backup_benefit_daily_body),
)
}
}

54
app/src/main/java/de/jeanlucmakiola/calendula/ui/permission/BrandHero.kt → app/src/main/java/de/jeanlucmakiola/calendula/ui/onboarding/BrandHero.kt
View File

@@ -1,4 +1,4 @@
package de.jeanlucmakiola.calendula.ui.permission
package de.jeanlucmakiola.calendula.ui.onboarding
import androidx.compose.foundation.Image
import androidx.compose.foundation.background
@@ -9,6 +9,7 @@ import androidx.compose.foundation.layout.size
import androidx.compose.foundation.shape.CircleShape
import androidx.compose.foundation.shape.RoundedCornerShape
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.Check
import androidx.compose.material.icons.filled.Lock
import androidx.compose.material3.Icon
import androidx.compose.material3.MaterialTheme
@@ -16,20 +17,25 @@ import androidx.compose.runtime.Composable
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.draw.clip
import androidx.compose.ui.graphics.vector.ImageVector
import androidx.compose.ui.res.colorResource
import androidx.compose.ui.res.painterResource
import androidx.compose.ui.res.stringResource
import androidx.compose.ui.unit.dp
import de.jeanlucmakiola.calendula.R
/** What, if anything, the brand mark is wearing in its corner. */
internal enum class HeroBadge { Denied, Done }
/**
* The app's adaptive launcher mark, reconstructed as a large branded squircle —
* the hero of the onboarding screens (floret-kit's OnboardingScaffold supplies
* the shell; the mark stays app-local so each sibling keeps its own identity).
* A lock badge overlays the corner when permission has been [denied].
* A [badge] overlays the corner where the screen has a verdict to give: blocked,
* or finished.
*/
@Composable
internal fun BrandHero(denied: Boolean) {
internal fun BrandHero(badge: HeroBadge? = null) {
Box(contentAlignment = Alignment.Center) {
Box(
modifier = Modifier
@@ -43,24 +49,56 @@ internal fun BrandHero(denied: Boolean) {
modifier = Modifier.fillMaxSize(),
)
}
if (denied) {
// A small lock badge sits over the corner to signal "blocked".
if (badge != null) {
val container = when (badge) {
HeroBadge.Denied -> MaterialTheme.colorScheme.errorContainer
HeroBadge.Done -> MaterialTheme.colorScheme.primaryContainer
}
val onContainer = when (badge) {
HeroBadge.Denied -> MaterialTheme.colorScheme.onErrorContainer
HeroBadge.Done -> MaterialTheme.colorScheme.onPrimaryContainer
}
Box(
modifier = Modifier
.align(Alignment.BottomEnd)
.offset(x = 10.dp, y = 10.dp)
.size(44.dp)
.clip(CircleShape)
.background(MaterialTheme.colorScheme.errorContainer),
.background(container),
contentAlignment = Alignment.Center,
) {
Icon(
imageVector = Icons.Filled.Lock,
imageVector = when (badge) {
HeroBadge.Denied -> Icons.Filled.Lock
HeroBadge.Done -> Icons.Filled.Check
},
contentDescription = null,
tint = MaterialTheme.colorScheme.onErrorContainer,
tint = onContainer,
modifier = Modifier.size(24.dp),
)
}
}
}
}
/**
* A single [icon] in the brand squircle — the same silhouette as [BrandHero],
* for the wizard steps that stand for a feature rather than for the app itself.
*/
@Composable
internal fun IconHero(icon: ImageVector) {
Box(
modifier = Modifier
.size(128.dp)
.clip(RoundedCornerShape(34.dp))
.background(MaterialTheme.colorScheme.primaryContainer),
contentAlignment = Alignment.Center,
) {
Icon(
imageVector = icon,
contentDescription = null,
tint = MaterialTheme.colorScheme.onPrimaryContainer,
modifier = Modifier.size(56.dp),
)
}
}

61
app/src/main/java/de/jeanlucmakiola/calendula/ui/onboarding/DoneStep.kt Normal file
View File

@@ -0,0 +1,61 @@
package de.jeanlucmakiola.calendula.ui.onboarding
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.material3.Button
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.ui.Modifier
import androidx.compose.ui.res.stringResource
import androidx.compose.ui.text.style.TextAlign
import androidx.compose.ui.unit.dp
import de.jeanlucmakiola.calendula.R
import de.jeanlucmakiola.floret.components.OnboardingScaffold
import de.jeanlucmakiola.floret.components.OnboardingSpace
/**
* The wizard's closing screen (#163): the flow ends on a full screen saying so
* rather than dropping into the calendar mid-gesture, and the brand mark wears
* the check that the last step earned.
*/
@Composable
internal fun DoneStep(
onFinished: () -> Unit,
modifier: Modifier = Modifier,
progress: (@Composable () -> Unit)? = null,
navigationIcon: (@Composable () -> Unit)? = null,
) {
OnboardingScaffold(
modifier = modifier,
progress = progress,
navigationIcon = navigationIcon,
topSpacing = OnboardingSpace.lg,
hero = { BrandHero(HeroBadge.Done) },
actions = {
Button(
onClick = onFinished,
modifier = Modifier.fillMaxWidth().height(56.dp),
) {
Text(
text = stringResource(R.string.onboarding_done_button),
style = MaterialTheme.typography.titleMedium,
)
}
},
) {
Text(
text = stringResource(R.string.onboarding_done_title),
style = MaterialTheme.typography.headlineMedium,
textAlign = TextAlign.Center,
)
Spacer(Modifier.height(12.dp))
Text(
text = stringResource(R.string.onboarding_done_body),
style = MaterialTheme.typography.bodyLarge,
color = MaterialTheme.colorScheme.onSurfaceVariant,
textAlign = TextAlign.Center,
)
}
}

58
app/src/main/java/de/jeanlucmakiola/calendula/ui/onboarding/OnboardingMotion.kt Normal file
View File

@@ -0,0 +1,58 @@
package de.jeanlucmakiola.calendula.ui.onboarding
import androidx.compose.animation.ContentTransform
import androidx.compose.animation.SizeTransform
import androidx.compose.animation.core.FiniteAnimationSpec
import androidx.compose.animation.fadeIn
import androidx.compose.animation.fadeOut
import androidx.compose.animation.slideInHorizontally
import androidx.compose.animation.slideOutHorizontally
import androidx.compose.animation.togetherWith
import androidx.compose.material3.ExperimentalMaterial3ExpressiveApi
import androidx.compose.material3.MaterialTheme
import androidx.compose.runtime.Composable
import androidx.compose.ui.unit.IntOffset
/**
* The M3 Expressive spatial spring the wizard's steps travel on. Read in
* composable scope so it can be captured by `AnimatedContent`'s non-composable
* transitionSpec lambda.
*/
@OptIn(ExperimentalMaterial3ExpressiveApi::class)
@Composable
internal fun rememberOnboardingSlideSpec(): FiniteAnimationSpec<IntOffset> =
MaterialTheme.motionScheme.defaultSpatialSpec()
/**
* Moving between wizard steps (#163): the steps sit side by side and the whole
* width swipes across, position on a spring so the arriving step settles with a
* little give rather than stopping dead.
*
* No cross-fade, unlike the calendar's shared-axis paging: two steps have
* nothing in common, so fading one through the other smears. Both are opaque and
* travel in lockstep, showing one screen pushing the other off.
*
* @param slideDir +1 = forward (incoming from the right), -1 = back.
* @param spec spatial spec, typically [rememberOnboardingSlideSpec].
* @param fadeSpec effects spec used for the whole transition under reduced
* motion.
* @param reduceMotion when true, drop the movement and cross-fade alone.
*/
internal fun onboardingSlideTransition(
slideDir: Int,
spec: FiniteAnimationSpec<IntOffset>,
fadeSpec: FiniteAnimationSpec<Float>,
reduceMotion: Boolean,
): ContentTransform {
if (reduceMotion) {
return fadeIn(fadeSpec).togetherWith(fadeOut(fadeSpec))
}
val dir = if (slideDir == 0) 1 else slideDir
return ContentTransform(
targetContentEnter = slideInHorizontally(spec) { w -> dir * w },
initialContentExit = slideOutHorizontally(spec) { w -> -dir * w },
// Clipping to the animating container would shear both steps against the
// viewport edge as they pass; there is no size change here to contain.
sizeTransform = SizeTransform(clip = false),
)
}

116
app/src/main/java/de/jeanlucmakiola/calendula/ui/onboarding/OnboardingPlan.kt Normal file
View File

@@ -0,0 +1,116 @@
package de.jeanlucmakiola.calendula.ui.onboarding
/** One screen of the first-launch wizard (#163), in the order they are shown. */
enum class OnboardingStep {
/** Required: nothing works without the calendar grant. */
Permission,
/** Whether Calendula delivers reminder notifications itself. */
Reminders,
/** Only when nothing you write to is synced anywhere — offers a backup. */
Backup,
/** Which view the app opens on, chosen from a live preview. */
View,
/** How the Month view lays itself out, chosen from a live preview. */
MonthStyle,
/** Only on an install that has calendars the device is hiding (#75). */
Visibility,
/** The closing screen: everything is answered and the app is ready. */
Done,
}
/**
* Which steps this install owes and where it has got to. [steps] is the whole
* flow — completed steps included — so the counter doesn't renumber as steps
* are finished; [current] is null once nothing is left and the app opens.
*/
data class OnboardingPlan(
val steps: List<OnboardingStep>,
val current: OnboardingStep?,
) {
/** 1-based position of [current] in [steps], or 0 when the flow is done. */
val index: Int get() = steps.indexOf(current) + 1
val total: Int get() = steps.size
/** A one-step flow is not a wizard: there is nothing to count down. */
val showsProgress: Boolean get() = total > 1
/** The step before [current], or null at the start (and once finished). */
val previous: OnboardingStep? get() = steps.getOrNull(index - 2).takeIf { current != null }
/**
* Whether the wizard can step back. Everything is re-askable except the
* calendar grant, which belongs to the system — once given there is nothing
* for a back press to return to.
*/
val canGoBack: Boolean get() = previous != null && previous != OnboardingStep.Permission
}
/**
* Work out the flow from what is stored.
*
* The optional steps belong to installs still working through their first run.
* Before the grant that can only be guessed, so one that has not answered the
* reminder step either counts as fresh — the same condition
* [de.jeanlucmakiola.calendula.data.prefs.SettingsPrefs.armOnboardingWizard]
* commits to storage a moment later, and clears again on the closing screen so
* a later re-grant is only the permission step.
*
* [backupApplies] is null until the calendar list can be read, i.e. for the
* whole permission step; the backup step is assumed to apply until proven
* otherwise, so the flow can only ever get shorter — never sprout a step the
* counter had not accounted for.
*
* The month-style step is *not* conditional on Month being the chosen view:
* Month is reachable from the drawer whatever opens first, and a step that came
* and went as the view is picked would move the counter under the user on the
* step right before it.
*
* [visibilityArmed] carries the one-time notice that the device is hiding some
* calendars (#75) — the only optional step an *existing* install can be given,
* which is why it is not gated on `fresh`, and on its own it earns no closing
* screen.
*/
fun onboardingPlan(
hasPermission: Boolean,
remindersDone: Boolean,
wizardArmed: Boolean,
backupDone: Boolean,
viewDone: Boolean,
monthStyleDone: Boolean,
backupApplies: Boolean?,
visibilityArmed: Boolean = false,
visibilityDone: Boolean = false,
doneShown: Boolean = false,
): OnboardingPlan {
val fresh = wizardArmed || (!hasPermission && !remindersDone)
val steps = buildList {
if (!hasPermission || fresh) add(OnboardingStep.Permission)
if (!remindersDone || fresh) add(OnboardingStep.Reminders)
if (fresh && backupApplies != false) add(OnboardingStep.Backup)
if (fresh) {
add(OnboardingStep.View)
add(OnboardingStep.MonthStyle)
}
if (visibilityArmed) add(OnboardingStep.Visibility)
if (fresh) add(OnboardingStep.Done)
}
val current = steps.firstOrNull { step ->
when (step) {
OnboardingStep.Permission -> !hasPermission
OnboardingStep.Reminders -> !remindersDone
OnboardingStep.Backup -> !backupDone
OnboardingStep.View -> !viewDone
OnboardingStep.MonthStyle -> !monthStyleDone
OnboardingStep.Visibility -> !visibilityDone
OnboardingStep.Done -> !doneShown
}
}
return OnboardingPlan(steps, current)
}

118
app/src/main/java/de/jeanlucmakiola/calendula/ui/onboarding/OnboardingSteps.kt Normal file
View File

@@ -0,0 +1,118 @@
package de.jeanlucmakiola.calendula.ui.onboarding
import androidx.activity.compose.BackHandler
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.automirrored.filled.ArrowBack
import androidx.compose.material3.Icon
import androidx.compose.material3.IconButton
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.ui.Modifier
import androidx.compose.ui.res.stringResource
import androidx.lifecycle.compose.collectAsStateWithLifecycle
import de.jeanlucmakiola.calendula.R
import de.jeanlucmakiola.floret.components.OnboardingProgress
/**
* Renders the wizard's current [step] (#163). Each step commits its own answer
* through [viewModel], which then hands the host the next one.
*/
@Composable
fun OnboardingSteps(
step: OnboardingStep,
plan: OnboardingPlan,
viewModel: OnboardingViewModel,
onPermissionGranted: () -> Unit,
modifier: Modifier = Modifier,
) {
// Collected for every step, not just the two that draw a preview: starting
// it when the picker composes would leave that step blank as it slides in.
val choice by viewModel.viewChoice.collectAsStateWithLifecycle()
// Coerced because the outgoing half of a transition may be a step the live
// plan has since dropped — the backup step goes once the calendars say it
// does not apply — and a "Step 0 of 3" flash is worse than a stale number.
val index = (plan.steps.indexOf(step) + 1).coerceAtLeast(1)
val progress: (@Composable () -> Unit)? = if (!plan.showsProgress) {
null
} else {
{
OnboardingProgress(
step = index,
total = plan.total,
label = stringResource(R.string.onboarding_step_counter, index, plan.total),
)
}
}
// The system back gesture does the same thing as the button, and stays off
// on the first step so back still leaves the app.
BackHandler(enabled = plan.canGoBack) { viewModel.goBack() }
val navigationIcon: (@Composable () -> Unit)? = if (!plan.canGoBack) {
null
} else {
{
IconButton(onClick = viewModel::goBack) {
Icon(
imageVector = Icons.AutoMirrored.Filled.ArrowBack,
contentDescription = stringResource(R.string.onboarding_back),
)
}
}
}
when (step) {
OnboardingStep.Permission -> PermissionScreen(
onGranted = onPermissionGranted,
modifier = modifier,
progress = progress,
)
OnboardingStep.Reminders -> ReminderStep(
onFinished = viewModel::finishReminders,
modifier = modifier,
progress = progress,
navigationIcon = navigationIcon,
)
OnboardingStep.Backup -> BackupStep(
onEnable = viewModel::enableAutoBackup,
onSkip = viewModel::skipBackup,
modifier = modifier,
progress = progress,
navigationIcon = navigationIcon,
)
// The choice is null only until DataStore's first emission; rendering
// nothing for that frame beats a preview built on the wrong defaults.
OnboardingStep.View -> choice?.let {
ViewStep(
choice = it,
onSelect = viewModel::setDefaultView,
onFinished = viewModel::finishView,
modifier = modifier,
progress = progress,
navigationIcon = navigationIcon,
)
}
OnboardingStep.MonthStyle -> choice?.let {
MonthStyleStep(
choice = it,
onSelect = viewModel::setMonthViewStyle,
onFinished = viewModel::finishMonthStyle,
modifier = modifier,
progress = progress,
navigationIcon = navigationIcon,
)
}
OnboardingStep.Visibility -> VisibilityStep(
onFinished = viewModel::finishVisibility,
modifier = modifier,
progress = progress,
navigationIcon = navigationIcon,
)
OnboardingStep.Done -> DoneStep(
onFinished = viewModel::finishOnboarding,
modifier = modifier,
progress = progress,
navigationIcon = navigationIcon,
)
}
}

321
app/src/main/java/de/jeanlucmakiola/calendula/ui/onboarding/OnboardingViewModel.kt Normal file
View File

@@ -0,0 +1,321 @@
package de.jeanlucmakiola.calendula.ui.onboarding
import android.content.Context
import android.content.Intent
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.BackupScheduler
import de.jeanlucmakiola.calendula.data.calendar.CalendarRepository
import de.jeanlucmakiola.calendula.data.calendar.CalendarVisibilityReconciler
import de.jeanlucmakiola.calendula.data.di.IoDispatcher
import de.jeanlucmakiola.calendula.data.prefs.CalendarPrefs
import de.jeanlucmakiola.calendula.data.prefs.SettingsPrefs
import de.jeanlucmakiola.calendula.data.prefs.WeekStartPref
import de.jeanlucmakiola.calendula.data.reminders.ReminderScanner
import de.jeanlucmakiola.calendula.domain.CalendarSource
import de.jeanlucmakiola.calendula.ui.common.CalendarView
import de.jeanlucmakiola.calendula.ui.month.MonthViewStyle
import kotlinx.coroutines.CoroutineDispatcher
import kotlinx.coroutines.ExperimentalCoroutinesApi
import kotlinx.coroutines.flow.Flow
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.SharingStarted
import kotlinx.coroutines.flow.StateFlow
import kotlinx.coroutines.flow.catch
import kotlinx.coroutines.flow.combine
import kotlinx.coroutines.flow.first
import kotlinx.coroutines.flow.flatMapLatest
import kotlinx.coroutines.flow.flowOf
import kotlinx.coroutines.flow.flowOn
import kotlinx.coroutines.flow.map
import kotlinx.coroutines.flow.mapLatest
import kotlinx.coroutines.flow.stateIn
import kotlinx.coroutines.launch
import javax.inject.Inject
/**
* Drives the first-launch wizard (#163): decides which steps this install owes
* (see [onboardingPlan]) and commits each answer.
*
* [plan] is null until the first stored emission, so the host renders nothing
* for that frame rather than flashing a step the user has already answered.
*/
@OptIn(ExperimentalCoroutinesApi::class)
@HiltViewModel
class OnboardingViewModel @Inject constructor(
@ApplicationContext private val context: Context,
private val prefs: SettingsPrefs,
private val calendarPrefs: CalendarPrefs,
private val repository: CalendarRepository,
private val scanner: ReminderScanner,
private val visibilityReconciler: CalendarVisibilityReconciler,
@IoDispatcher private val io: CoroutineDispatcher,
) : ViewModel() {
/** Null until the host reports it — assuming either way would flash a screen. */
private val permissionReported = MutableStateFlow<Boolean?>(null)
/**
* The grant as the rest of the flow sees it: published only once the wizard
* has been armed for it, since arming is a stored write and the frames
* before it lands would collapse the plan to its one-step form.
*/
private val hasPermission: StateFlow<Boolean?> = permissionReported
.mapLatest { granted ->
if (granted == true) armWizardIfFresh()
granted
}
.stateIn(
scope = viewModelScope,
started = SharingStarted.Eagerly,
initialValue = null,
)
/**
* Whether the backup step applies: something of yours is worth exporting and
* nothing you write to is synced anywhere. Null while the calendar list
* cannot be read: every frame before the grant, and any read that fails —
* an empty list is also how a null cursor arrives, and guessing false there
* would drop the step for the whole session.
*/
private val backupApplies: Flow<Boolean?> = hasPermission.flatMapLatest { granted ->
if (granted != true) {
flowOf(null)
} else {
repository.calendars()
.map { calendars -> if (calendars.isEmpty()) null else calendars.backupApplies() }
.catch { emit(null) }
.flowOn(io)
}
}
private val flags: Flow<OnboardingFlags> = combine(
prefs.reminderOnboardingDone,
prefs.onboardingWizardArmed,
prefs.onboardingBackupDone,
prefs.onboardingViewDone,
prefs.onboardingMonthStyleDone,
::OnboardingFlags,
)
/** The closing steps' own flags, and whether the notice applies at all. */
private val closingFlags: Flow<ClosingFlags> = combine(
calendarPrefs.visibilityNoticePending.map { it == true },
prefs.onboardingVisibilityDone,
prefs.onboardingDoneShown,
::ClosingFlags,
)
val plan: StateFlow<OnboardingPlan?> =
combine(hasPermission, flags, closingFlags, backupApplies) { granted, stored, closing, backup ->
granted?.let {
onboardingPlan(
hasPermission = it,
remindersDone = stored.remindersDone,
wizardArmed = stored.wizardArmed,
backupDone = stored.backupDone,
viewDone = stored.viewDone,
monthStyleDone = stored.monthStyleDone,
backupApplies = backup,
visibilityArmed = closing.visibilityArmed,
visibilityDone = closing.visibilityDone,
doneShown = closing.doneShown,
)
}
}.stateIn(
scope = viewModelScope,
started = SharingStarted.WhileSubscribed(5_000L),
initialValue = null,
)
/** The current view preferences, for the view step's initial selection. */
val viewChoice: StateFlow<ViewChoice?> = combine(
prefs.defaultView,
prefs.monthViewStyle,
prefs.weekStart,
::ViewChoice,
).stateIn(
scope = viewModelScope,
started = SharingStarted.WhileSubscribed(5_000L),
initialValue = null,
)
fun setHasPermission(granted: Boolean) {
permissionReported.value = granted
}
/**
* Arm the wizard for an install that has yet to answer the reminder step,
* whatever route the grant took. Gating this on the in-app grant would
* strand anyone who granted on Android's own settings screen and came back
* to a restarted process, leaving them the reminder step alone.
*/
private suspend fun armWizardIfFresh() {
if (!prefs.reminderOnboardingDone.first()) prefs.armOnboardingWizard()
}
/**
* Record the in-app grant. The launch scan ran before it and bailed out
* without arming anything, so the first alarm would otherwise wait on the
* daily worker.
*/
fun onPermissionGranted() {
scanner.scanInBackground()
}
/** Close the reminder step, recording whether notifications stay on. */
fun finishReminders(remindersEnabled: Boolean) {
viewModelScope.launch {
prefs.setRemindersEnabled(remindersEnabled)
prefs.setReminderOnboardingDone()
// Nothing else re-arms the scan: turning reminders off cancels the
// alarm (#75).
scanner.scan()
}
}
/**
* Re-ask the step before the current one, by clearing its answer. The plan
* derives the position from those answers, so un-setting one *is* the back
* navigation. The calendar grant belongs to the system and cannot be
* returned to, which [OnboardingPlan.canGoBack] already refuses.
*/
fun goBack() {
viewModelScope.launch {
when (plan.value?.previous) {
OnboardingStep.Reminders -> prefs.setReminderOnboardingDone(false)
OnboardingStep.Backup -> prefs.setOnboardingBackupDone(false)
OnboardingStep.View -> prefs.setOnboardingViewDone(false)
OnboardingStep.MonthStyle -> prefs.setOnboardingMonthStyleDone(false)
OnboardingStep.Visibility -> prefs.setOnboardingVisibilityDone(false)
OnboardingStep.Done -> prefs.setOnboardingDoneShown(false)
OnboardingStep.Permission, null -> Unit
}
}
}
/** Close the backup step without setting anything up. */
fun skipBackup() {
viewModelScope.launch { prefs.setOnboardingBackupDone() }
}
/**
* Turn automatic backup on, writing to the folder the user just picked
* (taking a durable write grant so background runs can keep writing), and
* close the step.
*/
fun enableAutoBackup(folder: Uri) {
viewModelScope.launch {
runCatching {
context.contentResolver.takePersistableUriPermission(
folder,
Intent.FLAG_GRANT_READ_URI_PERMISSION or Intent.FLAG_GRANT_WRITE_URI_PERMISSION,
)
}
prefs.setAutoBackupFolderUri(folder.toString())
prefs.setAutoBackupEnabled(true)
BackupScheduler.apply(
context = context,
enabled = true,
intervalMinutes = prefs.autoBackupIntervalMinutes.first(),
hasFolder = true,
)
// Immediate feedback: the first backup lands while onboarding runs.
BackupScheduler.runNow(context)
prefs.setOnboardingBackupDone()
}
}
fun setDefaultView(view: CalendarView) {
viewModelScope.launch { prefs.setDefaultView(view) }
}
fun setMonthViewStyle(style: MonthViewStyle) {
viewModelScope.launch { prefs.setMonthViewStyle(style) }
}
/** Close a picker step — the choice itself is saved as it is made. */
fun finishView() {
viewModelScope.launch { prefs.setOnboardingViewDone() }
}
fun finishMonthStyle() {
viewModelScope.launch { prefs.setOnboardingMonthStyleDone() }
}
/** Acknowledge the calendar-visibility notice (#75). */
fun finishVisibility() {
viewModelScope.launch {
prefs.setOnboardingVisibilityDone()
// Retiring the notice drops its step, so it waits until nothing
// follows — the count must not fall on the way to a later screen.
if (plan.value?.steps?.last() == OnboardingStep.Visibility) retireVisibilityNotice()
}
}
/** Close the wizard from its last screen. */
fun finishOnboarding() {
viewModelScope.launch {
prefs.finishOnboardingWizard()
retireVisibilityNotice()
}
}
/**
* Put the one-time visibility notice away for good — nothing else clears it
* now that the wizard owns it, and left standing it would keep its step in
* every later plan.
*/
private suspend fun retireVisibilityNotice() {
if (calendarPrefs.visibilityNoticePending.first() == true) {
calendarPrefs.setVisibilityNoticePending(false)
}
}
/**
* Fold the retired app-local calendar visibility into the device's own, and
* arm the notice if this install has anything to announce. Runs whenever the
* app comes up holding the permission, however it was granted — one taken on
* Android's app-settings screen never reaches the permission step's callback.
*/
fun reconcileCalendarVisibility() {
viewModelScope.launch { visibilityReconciler.run() }
}
}
/** The stored answers the plan is derived from. */
private data class OnboardingFlags(
val remindersDone: Boolean,
val wizardArmed: Boolean,
val backupDone: Boolean,
val viewDone: Boolean,
val monthStyleDone: Boolean,
)
/** The tail of the flow: the visibility notice and the closing screen. */
private data class ClosingFlags(
val visibilityArmed: Boolean,
val visibilityDone: Boolean,
val doneShown: Boolean,
)
/** What the view step starts from, and renders its previews with. */
data class ViewChoice(
val defaultView: CalendarView,
val monthViewStyle: MonthViewStyle,
val weekStart: WeekStartPref,
)
/**
* True when this device holds events that live nowhere else: at least one local
* calendar worth exporting, and no writable synced calendar to carry them.
* A read-only subscription is not a backup, so it does not count.
*/
private fun List<CalendarSource>.backupApplies(): Boolean {
val exportable = any { it.isLocal && it.canModifyContents && !it.isManaged }
val syncedTarget = any { !it.isLocal && it.canModifyContents }
return exportable && !syncedTarget
}

64
app/src/main/java/de/jeanlucmakiola/calendula/ui/permission/PermissionScreen.kt → app/src/main/java/de/jeanlucmakiola/calendula/ui/onboarding/PermissionScreen.kt
View File

@@ -1,4 +1,4 @@
package de.jeanlucmakiola.calendula.ui.permission
package de.jeanlucmakiola.calendula.ui.onboarding
import de.jeanlucmakiola.floret.components.BenefitRow
import de.jeanlucmakiola.floret.components.OnboardingScaffold
@@ -10,19 +10,15 @@ import android.net.Uri
import android.provider.Settings
import androidx.activity.compose.rememberLauncherForActivityResult
import androidx.activity.result.contract.ActivityResultContracts
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.size
import androidx.compose.foundation.layout.width
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.automirrored.filled.ArrowForward
import androidx.compose.material.icons.filled.CalendarMonth
import androidx.compose.material.icons.filled.Lock
import androidx.compose.material.icons.filled.VisibilityOff
import androidx.compose.material3.Button
import androidx.compose.material3.ButtonDefaults
import androidx.compose.material3.Icon
@@ -32,13 +28,11 @@ import androidx.compose.material3.TextButton
import androidx.compose.runtime.Composable
import androidx.compose.runtime.LaunchedEffect
import androidx.compose.runtime.getValue
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.platform.LocalContext
import androidx.compose.ui.res.stringResource
import androidx.compose.ui.text.style.TextAlign
import androidx.compose.ui.unit.dp
import androidx.compose.ui.unit.sp
import androidx.hilt.navigation.compose.hiltViewModel
import androidx.lifecycle.compose.collectAsStateWithLifecycle
import de.jeanlucmakiola.calendula.R
@@ -52,6 +46,7 @@ private val CALENDAR_PERMISSIONS = arrayOf(
fun PermissionScreen(
onGranted: () -> Unit,
modifier: Modifier = Modifier,
progress: (@Composable () -> Unit)? = null,
viewModel: PermissionViewModel = hiltViewModel(),
) {
val state by viewModel.state.collectAsStateWithLifecycle()
@@ -76,6 +71,7 @@ fun PermissionScreen(
when (state) {
is PermissionUiState.Rationale -> RationaleContent(
onRequest = { launcher.launch(CALENDAR_PERMISSIONS) },
progress = progress,
modifier = modifier,
)
is PermissionUiState.Denied -> DeniedContent(
@@ -83,6 +79,7 @@ fun PermissionScreen(
viewModel.onRetry()
launcher.launch(CALENDAR_PERMISSIONS)
},
progress = progress,
modifier = modifier,
)
is PermissionUiState.Granted -> {
@@ -94,11 +91,14 @@ fun PermissionScreen(
@Composable
private fun RationaleContent(
onRequest: () -> Unit,
progress: (@Composable () -> Unit)?,
modifier: Modifier = Modifier,
) {
OnboardingScaffold(
modifier = modifier,
hero = { BrandHero(denied = false) },
progress = progress,
topSpacing = OnboardingSpace.lg,
hero = { BrandHero() },
actions = {
Button(
onClick = onRequest,
@@ -116,16 +116,8 @@ private fun RationaleContent(
modifier = Modifier.size(20.dp),
)
}
PrivacyFootnote()
},
) {
Text(
text = stringResource(R.string.app_name).uppercase(),
style = MaterialTheme.typography.labelLarge,
color = MaterialTheme.colorScheme.primary,
letterSpacing = 2.sp,
)
Spacer(Modifier.height(OnboardingSpace.xs))
Text(
text = stringResource(R.string.permission_rationale_title),
style = MaterialTheme.typography.headlineMedium,
@@ -139,14 +131,8 @@ private fun RationaleContent(
textAlign = TextAlign.Center,
)
Spacer(Modifier.height(OnboardingSpace.xl))
Spacer(Modifier.height(OnboardingSpace.lg))
BenefitRow(
icon = Icons.Filled.Lock,
title = stringResource(R.string.permission_benefit_private_title),
body = stringResource(R.string.permission_benefit_private_body),
)
Spacer(Modifier.height(OnboardingSpace.sm))
BenefitRow(
icon = Icons.Filled.CalendarMonth,
title = stringResource(R.string.permission_benefit_sync_title),
@@ -154,9 +140,9 @@ private fun RationaleContent(
)
Spacer(Modifier.height(OnboardingSpace.sm))
BenefitRow(
icon = Icons.Filled.VisibilityOff,
title = stringResource(R.string.permission_benefit_privacy_title),
body = stringResource(R.string.permission_benefit_privacy_body),
icon = Icons.Filled.Lock,
title = stringResource(R.string.permission_benefit_private_title),
body = stringResource(R.string.permission_benefit_private_body),
)
}
}
@@ -164,12 +150,14 @@ private fun RationaleContent(
@Composable
private fun DeniedContent(
onRetry: () -> Unit,
progress: (@Composable () -> Unit)?,
modifier: Modifier = Modifier,
) {
val context = LocalContext.current
OnboardingScaffold(
modifier = modifier,
hero = { BrandHero(denied = true) },
progress = progress,
hero = { BrandHero(HeroBadge.Denied) },
actions = {
Button(
onClick = {
@@ -208,25 +196,3 @@ private fun DeniedContent(
)
}
}
@Composable
private fun PrivacyFootnote() {
Row(
modifier = Modifier.fillMaxWidth().padding(top = 4.dp),
horizontalArrangement = Arrangement.Center,
verticalAlignment = Alignment.CenterVertically,
) {
Icon(
imageVector = Icons.Filled.Lock,
contentDescription = null,
tint = MaterialTheme.colorScheme.onSurfaceVariant,
modifier = Modifier.size(14.dp),
)
Spacer(Modifier.width(6.dp))
Text(
text = stringResource(R.string.permission_privacy_footnote),
style = MaterialTheme.typography.labelMedium,
color = MaterialTheme.colorScheme.onSurfaceVariant,
)
}
}

2
app/src/main/java/de/jeanlucmakiola/calendula/ui/permission/PermissionUiState.kt → app/src/main/java/de/jeanlucmakiola/calendula/ui/onboarding/PermissionUiState.kt
View File

@@ -1,4 +1,4 @@
package de.jeanlucmakiola.calendula.ui.permission
package de.jeanlucmakiola.calendula.ui.onboarding
sealed interface PermissionUiState {
data object Rationale : PermissionUiState

2
app/src/main/java/de/jeanlucmakiola/calendula/ui/permission/PermissionViewModel.kt → app/src/main/java/de/jeanlucmakiola/calendula/ui/onboarding/PermissionViewModel.kt
View File

@@ -1,4 +1,4 @@
package de.jeanlucmakiola.calendula.ui.permission
package de.jeanlucmakiola.calendula.ui.onboarding
import androidx.lifecycle.ViewModel
import dagger.hilt.android.lifecycle.HiltViewModel

56
app/src/main/java/de/jeanlucmakiola/calendula/ui/permission/ReminderOnboardingScreen.kt → app/src/main/java/de/jeanlucmakiola/calendula/ui/onboarding/ReminderStep.kt
View File

@@ -1,4 +1,4 @@
package de.jeanlucmakiola.calendula.ui.permission
package de.jeanlucmakiola.calendula.ui.onboarding
import de.jeanlucmakiola.floret.components.BenefitRow
import de.jeanlucmakiola.floret.components.OnboardingScaffold
@@ -8,34 +8,25 @@ import android.Manifest
import android.os.Build
import androidx.activity.compose.rememberLauncherForActivityResult
import androidx.activity.result.contract.ActivityResultContracts
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.size
import androidx.compose.foundation.shape.RoundedCornerShape
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.NotificationsActive
import androidx.compose.material.icons.filled.ContentCopy
import androidx.compose.material.icons.filled.Tune
import androidx.compose.material3.Button
import androidx.compose.material3.Icon
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Text
import androidx.compose.material3.TextButton
import androidx.compose.runtime.Composable
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.draw.clip
import androidx.compose.ui.res.stringResource
import androidx.compose.ui.text.style.TextAlign
import androidx.compose.ui.unit.dp
import androidx.compose.ui.unit.sp
import de.jeanlucmakiola.calendula.R
/**
* One-time onboarding step after the calendar grant (v1.4): explains that
* Wizard step after the calendar grant (v1.4): explains that
* Calendula delivers reminder notifications itself, warns about duplicates
* when a second calendar app has notifications on, and requests
* `POST_NOTIFICATIONS` (a system dialog on API 33+ only; minSdk is 29).
@@ -45,9 +36,11 @@ import de.jeanlucmakiola.calendula.R
* the Settings toggle re-requests it. "Not now" turns the in-app toggle off.
*/
@Composable
fun ReminderOnboardingScreen(
fun ReminderStep(
onFinished: (remindersEnabled: Boolean) -> Unit,
modifier: Modifier = Modifier,
progress: (@Composable () -> Unit)? = null,
navigationIcon: (@Composable () -> Unit)? = null,
) {
val launcher = rememberLauncherForActivityResult(
contract = ActivityResultContracts.RequestPermission(),
@@ -55,7 +48,10 @@ fun ReminderOnboardingScreen(
OnboardingScaffold(
modifier = modifier,
hero = { BellHero() },
progress = progress,
navigationIcon = navigationIcon,
topSpacing = OnboardingSpace.lg,
hero = { IconHero(Icons.Filled.NotificationsActive) },
actions = {
Button(
onClick = {
@@ -80,13 +76,6 @@ fun ReminderOnboardingScreen(
}
},
) {
Text(
text = stringResource(R.string.app_name).uppercase(),
style = MaterialTheme.typography.labelLarge,
color = MaterialTheme.colorScheme.primary,
letterSpacing = 2.sp,
)
Spacer(Modifier.height(OnboardingSpace.xs))
Text(
text = stringResource(R.string.reminder_onboarding_title),
style = MaterialTheme.typography.headlineMedium,
@@ -100,7 +89,7 @@ fun ReminderOnboardingScreen(
textAlign = TextAlign.Center,
)
Spacer(Modifier.height(OnboardingSpace.xl))
Spacer(Modifier.height(OnboardingSpace.lg))
BenefitRow(
icon = Icons.Filled.NotificationsActive,
@@ -113,30 +102,5 @@ fun ReminderOnboardingScreen(
title = stringResource(R.string.reminder_benefit_duplicates_title),
body = stringResource(R.string.reminder_benefit_duplicates_body),
)
Spacer(Modifier.height(OnboardingSpace.sm))
BenefitRow(
icon = Icons.Filled.Tune,
title = stringResource(R.string.reminder_benefit_reversible_title),
body = stringResource(R.string.reminder_benefit_reversible_body),
)
}
}
/** A bell in the brand squircle — same silhouette as the permission hero. */
@Composable
private fun BellHero() {
Box(
modifier = Modifier
.size(128.dp)
.clip(RoundedCornerShape(34.dp))
.background(MaterialTheme.colorScheme.primaryContainer),
contentAlignment = Alignment.Center,
) {
Icon(
imageVector = Icons.Filled.NotificationsActive,
contentDescription = null,
tint = MaterialTheme.colorScheme.onPrimaryContainer,
modifier = Modifier.size(56.dp),
)
}
}

209
app/src/main/java/de/jeanlucmakiola/calendula/ui/onboarding/ViewStep.kt Normal file
View File

@@ -0,0 +1,209 @@
package de.jeanlucmakiola.calendula.ui.onboarding
import androidx.compose.foundation.layout.ColumnScope
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.material3.Button
import androidx.compose.material3.Icon
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.ui.Modifier
import androidx.compose.ui.res.stringResource
import androidx.compose.ui.unit.Dp
import androidx.compose.ui.unit.dp
import de.jeanlucmakiola.calendula.R
import de.jeanlucmakiola.calendula.data.prefs.resolveFirstDay
import de.jeanlucmakiola.calendula.ui.agenda.AgendaViewPreview
import de.jeanlucmakiola.calendula.ui.common.CalendarView
import de.jeanlucmakiola.calendula.ui.common.IMPLEMENTED_VIEWS
import de.jeanlucmakiola.calendula.ui.common.PickerDescription
import de.jeanlucmakiola.calendula.ui.common.ViewPreviewFrame
import de.jeanlucmakiola.calendula.ui.common.icon
import de.jeanlucmakiola.calendula.ui.common.labelRes
import de.jeanlucmakiola.calendula.ui.day.DayViewPreview
import de.jeanlucmakiola.calendula.ui.month.MonthStylePreview
import de.jeanlucmakiola.calendula.ui.month.MonthViewStyle
import de.jeanlucmakiola.calendula.ui.month.descriptionRes
import de.jeanlucmakiola.calendula.ui.month.labelRes
import de.jeanlucmakiola.calendula.ui.week.WeekViewPreview
import de.jeanlucmakiola.floret.components.GroupedListInset
import de.jeanlucmakiola.floret.components.OnboardingScaffold
import de.jeanlucmakiola.floret.components.OnboardingSpace
import de.jeanlucmakiola.floret.components.GroupedRow
import de.jeanlucmakiola.floret.components.SelectedCheck
import de.jeanlucmakiola.floret.components.positionOf
import de.jeanlucmakiola.floret.locale.currentLocale
/**
* Wizard step: which view the app opens on (#163). Built like the Settings
* picker it mirrors — a live preview over connected grouped rows. Selecting
* applies immediately and leaves the step open; the preview is the confirmation.
*/
@Composable
internal fun ViewStep(
choice: ViewChoice,
onSelect: (CalendarView) -> Unit,
onFinished: () -> Unit,
modifier: Modifier = Modifier,
progress: (@Composable () -> Unit)? = null,
navigationIcon: (@Composable () -> Unit)? = null,
) {
val weekStart = choice.weekStart.resolveFirstDay(currentLocale())
StepPickerScaffold(
title = stringResource(R.string.onboarding_view_title),
onFinished = onFinished,
modifier = modifier,
progress = progress,
navigationIcon = navigationIcon,
) {
StepPreview(selected = choice.defaultView) { view ->
when (view) {
CalendarView.Month -> MonthStylePreview(
style = choice.monthViewStyle,
weekStart = weekStart,
height = PREVIEW_HEIGHT,
)
CalendarView.Week -> WeekViewPreview(weekStart = weekStart, height = PREVIEW_HEIGHT)
CalendarView.Day -> DayViewPreview(height = PREVIEW_HEIGHT)
CalendarView.Agenda -> AgendaViewPreview(height = PREVIEW_HEIGHT)
}
}
IMPLEMENTED_VIEWS.forEachIndexed { index, view ->
val isSelected = view == choice.defaultView
GroupedRow(
title = stringResource(view.labelRes),
position = positionOf(index, IMPLEMENTED_VIEWS.size),
selected = isSelected,
leading = {
Icon(
imageVector = view.icon,
contentDescription = null,
tint = MaterialTheme.colorScheme.onSurfaceVariant,
)
},
trailing = if (isSelected) {
{ SelectedCheck() }
} else {
null
},
onClick = { onSelect(view) },
)
}
}
}
/**
* Wizard step: how the Month view lays itself out (#163). The same shape as
* [ViewStep] and as the Settings chooser this duplicates, down to the selected
* style's own blurb sitting under its preview rather than on every row.
*/
@Composable
internal fun MonthStyleStep(
choice: ViewChoice,
onSelect: (MonthViewStyle) -> Unit,
onFinished: () -> Unit,
modifier: Modifier = Modifier,
progress: (@Composable () -> Unit)? = null,
navigationIcon: (@Composable () -> Unit)? = null,
) {
val weekStart = choice.weekStart.resolveFirstDay(currentLocale())
val options = MonthViewStyle.entries
StepPickerScaffold(
title = stringResource(R.string.onboarding_month_style_title),
onFinished = onFinished,
modifier = modifier,
progress = progress,
navigationIcon = navigationIcon,
) {
StepPreview(selected = choice.monthViewStyle) { style ->
MonthStylePreview(style = style, weekStart = weekStart, height = PREVIEW_HEIGHT)
}
PickerDescription(stringResource(choice.monthViewStyle.descriptionRes))
options.forEachIndexed { index, style ->
val isSelected = style == choice.monthViewStyle
GroupedRow(
title = stringResource(style.labelRes),
position = positionOf(index, options.size),
selected = isSelected,
trailing = if (isSelected) {
{ SelectedCheck() }
} else {
null
},
onClick = { onSelect(style) },
)
}
}
}
/**
* The shell both picker steps share: the wizard chrome around a title and a
* full-bleed column, since grouped rows carry their own inset.
*/
@Composable
private fun StepPickerScaffold(
title: String,
onFinished: () -> Unit,
modifier: Modifier = Modifier,
progress: (@Composable () -> Unit)? = null,
navigationIcon: (@Composable () -> Unit)? = null,
body: @Composable ColumnScope.() -> Unit,
) {
OnboardingScaffold(
modifier = modifier,
progress = progress,
navigationIcon = navigationIcon,
topSpacing = OnboardingSpace.xs,
contentPadding = 0.dp,
// The preview gets the room it needs; Continue scrolls in under the
// options rather than pinning to the bottom.
scrollingActions = true,
hero = {
Text(
text = title,
style = MaterialTheme.typography.headlineSmall,
modifier = Modifier
.fillMaxWidth()
.padding(horizontal = GroupedListInset),
)
},
actions = {
Button(
onClick = onFinished,
// Full-bleed step: the button takes the grouped rows' own inset
// and ends up as wide as the options above it.
modifier = Modifier
.padding(horizontal = GroupedListInset)
.fillMaxWidth()
.height(56.dp),
) {
Text(
text = stringResource(R.string.onboarding_view_continue_button),
style = MaterialTheme.typography.titleMedium,
)
}
},
body = body,
)
}
/**
* The live preview, framed like the picker's. The wider gap below keeps the rows
* reading as a group of their own rather than as the preview's caption.
*/
@Composable
private fun <T> StepPreview(selected: T, content: @Composable (T) -> Unit) {
ViewPreviewFrame(
selected = selected,
label = "step-preview",
modifier = Modifier.padding(top = OnboardingSpace.xs, bottom = OnboardingSpace.md),
content = content,
)
}
/** The same size the Settings chooser gives it. */
private val PREVIEW_HEIGHT: Dp = 280.dp

65
app/src/main/java/de/jeanlucmakiola/calendula/ui/onboarding/VisibilityStep.kt Normal file
View File

@@ -0,0 +1,65 @@
package de.jeanlucmakiola.calendula.ui.onboarding
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.VisibilityOff
import androidx.compose.material3.Button
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.ui.Modifier
import androidx.compose.ui.res.stringResource
import androidx.compose.ui.text.style.TextAlign
import androidx.compose.ui.unit.dp
import de.jeanlucmakiola.calendula.R
import de.jeanlucmakiola.floret.components.OnboardingScaffold
import de.jeanlucmakiola.floret.components.OnboardingSpace
/**
* Wizard step for the one-time notice that Calendula now follows the device's
* own per-calendar visibility and some of yours are switched off (#75, #163).
*
* Nothing to decide here — the app does not switch those calendars back on,
* since that would un-hide them everywhere else too.
*/
@Composable
internal fun VisibilityStep(
onFinished: () -> Unit,
modifier: Modifier = Modifier,
progress: (@Composable () -> Unit)? = null,
navigationIcon: (@Composable () -> Unit)? = null,
) {
OnboardingScaffold(
modifier = modifier,
progress = progress,
navigationIcon = navigationIcon,
topSpacing = OnboardingSpace.lg,
hero = { IconHero(Icons.Filled.VisibilityOff) },
actions = {
Button(
onClick = onFinished,
modifier = Modifier.fillMaxWidth().height(56.dp),
) {
Text(
text = stringResource(R.string.onboarding_visibility_button),
style = MaterialTheme.typography.titleMedium,
)
}
},
) {
Text(
text = stringResource(R.string.calendars_visibility_notice_title),
style = MaterialTheme.typography.headlineMedium,
textAlign = TextAlign.Center,
)
Spacer(Modifier.height(12.dp))
Text(
text = stringResource(R.string.calendars_visibility_notice_message),
style = MaterialTheme.typography.bodyLarge,
color = MaterialTheme.colorScheme.onSurfaceVariant,
textAlign = TextAlign.Center,
)
}
}

53
app/src/main/java/de/jeanlucmakiola/calendula/ui/permission/ReminderOnboardingViewModel.kt
View File

@@ -1,53 +0,0 @@
package de.jeanlucmakiola.calendula.ui.permission
import androidx.lifecycle.ViewModel
import androidx.lifecycle.viewModelScope
import dagger.hilt.android.lifecycle.HiltViewModel
import de.jeanlucmakiola.calendula.data.prefs.SettingsPrefs
import de.jeanlucmakiola.calendula.data.reminders.ReminderScanner
import kotlinx.coroutines.flow.SharingStarted
import kotlinx.coroutines.flow.StateFlow
import kotlinx.coroutines.flow.map
import kotlinx.coroutines.flow.stateIn
import kotlinx.coroutines.launch
import javax.inject.Inject
/**
* Gates the one-time reminder onboarding step (v1.4) shown after the calendar
* grant. [onboardingDone] is null until DataStore's first emission so the
* step neither flashes for users who completed it nor gets skipped.
*/
@HiltViewModel
class ReminderOnboardingViewModel @Inject constructor(
private val prefs: SettingsPrefs,
private val scanner: ReminderScanner,
) : ViewModel() {
val onboardingDone: StateFlow<Boolean?> = prefs.reminderOnboardingDone
.map { done -> done as Boolean? }
.stateIn(
scope = viewModelScope,
started = SharingStarted.WhileSubscribed(5_000L),
initialValue = null,
)
/** Close the step, recording whether reminder notifications stay on. */
fun finish(remindersEnabled: Boolean) {
viewModelScope.launch {
prefs.setRemindersEnabled(remindersEnabled)
prefs.setReminderOnboardingDone()
// Nothing else re-arms the scan: turning reminders off cancels the
// alarm (#75).
scanner.scan()
}
}
/**
* Re-scan after the calendar permission is granted. The launch scan runs
* before the grant and bails out without arming anything, so without this
* the first alarm waits on the daily worker.
*/
fun rearmAfterGrant() {
scanner.scanInBackground()
}
}

53
app/src/main/java/de/jeanlucmakiola/calendula/ui/settings/MonthViewStylePicker.kt
View File

@@ -1,24 +1,13 @@
package de.jeanlucmakiola.calendula.ui.settings
import androidx.compose.animation.Crossfade
import androidx.compose.animation.core.snap
import androidx.compose.animation.core.tween
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.shape.RoundedCornerShape
import androidx.compose.material3.MaterialTheme
import androidx.compose.runtime.Composable
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.draw.clip
import androidx.compose.ui.draw.clipToBounds
import androidx.compose.ui.res.stringResource
import androidx.compose.ui.unit.dp
import de.jeanlucmakiola.calendula.R
import de.jeanlucmakiola.calendula.ui.common.PickerDescription
import de.jeanlucmakiola.calendula.ui.common.ViewPreviewFrame
import de.jeanlucmakiola.calendula.ui.month.MonthStylePreview
import de.jeanlucmakiola.calendula.ui.month.MonthViewStyle
import de.jeanlucmakiola.calendula.ui.month.descriptionRes
@@ -27,7 +16,6 @@ import de.jeanlucmakiola.floret.components.FullScreenPicker
import de.jeanlucmakiola.floret.components.GroupedRow
import de.jeanlucmakiola.floret.components.SelectedCheck
import de.jeanlucmakiola.floret.components.positionOf
import de.jeanlucmakiola.floret.identity.rememberReduceMotion
import kotlinx.datetime.DayOfWeek
/**
@@ -51,39 +39,21 @@ internal fun MonthViewStylePicker(
onDismiss: () -> Unit,
) {
val options = MonthViewStyle.entries
val reduceMotion = rememberReduceMotion()
FullScreenPicker(
title = stringResource(R.string.settings_month_view_style),
onDismiss = onDismiss,
predictiveBack = true,
) {
Box(
modifier = Modifier
.fillMaxWidth()
.padding(horizontal = 12.dp, vertical = 8.dp)
.height(PREVIEW_HEIGHT),
contentAlignment = Alignment.Center,
) {
Crossfade(
targetState = selected,
animationSpec = if (reduceMotion) snap() else tween(durationMillis = 250),
label = "month-style-preview",
) { shown ->
// The preview renders the real grid at phone size and scales it
// down, so its own corners are square — the frame rounds it.
Box(
modifier = Modifier
.clip(PREVIEW_SHAPE)
.background(MaterialTheme.colorScheme.surface)
.clipToBounds(),
) {
MonthStylePreview(
style = shown,
weekStart = weekStart,
height = PREVIEW_HEIGHT,
)
}
}
ViewPreviewFrame(
selected = selected,
label = "month-style-preview",
modifier = Modifier.padding(vertical = 8.dp),
) { shown ->
MonthStylePreview(
style = shown,
weekStart = weekStart,
height = PREVIEW_HEIGHT,
)
}
// The selected style's own blurb lives here, under its preview, rather
// than on every row — the rows stay single-line and dense, and the words
@@ -109,4 +79,3 @@ internal fun MonthViewStylePicker(
}
private val PREVIEW_HEIGHT = 280.dp
private val PREVIEW_SHAPE = RoundedCornerShape(12.dp)

51
app/src/main/java/de/jeanlucmakiola/calendula/ui/settings/WeekStartPicker.kt
View File

@@ -1,33 +1,21 @@
package de.jeanlucmakiola.calendula.ui.settings
import androidx.compose.animation.Crossfade
import androidx.compose.animation.core.snap
import androidx.compose.animation.core.tween
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.shape.RoundedCornerShape
import androidx.compose.material3.MaterialTheme
import androidx.compose.runtime.Composable
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.draw.clip
import androidx.compose.ui.draw.clipToBounds
import androidx.compose.ui.res.stringResource
import androidx.compose.ui.unit.dp
import de.jeanlucmakiola.calendula.R
import de.jeanlucmakiola.calendula.data.prefs.WeekStartPref
import de.jeanlucmakiola.calendula.data.prefs.resolveFirstDay
import de.jeanlucmakiola.calendula.ui.common.PickerDescription
import de.jeanlucmakiola.calendula.ui.common.ViewPreviewFrame
import de.jeanlucmakiola.calendula.ui.month.MonthStylePreview
import de.jeanlucmakiola.calendula.ui.month.MonthViewStyle
import de.jeanlucmakiola.floret.components.FullScreenPicker
import de.jeanlucmakiola.floret.components.GroupedRow
import de.jeanlucmakiola.floret.components.SelectedCheck
import de.jeanlucmakiola.floret.components.positionOf
import de.jeanlucmakiola.floret.identity.rememberReduceMotion
import de.jeanlucmakiola.floret.locale.currentLocale
/**
@@ -46,38 +34,22 @@ internal fun WeekStartPicker(
onDismiss: () -> Unit,
) {
val locale = currentLocale()
val reduceMotion = rememberReduceMotion()
val resolved = selected.resolveFirstDay(locale)
FullScreenPicker(
title = stringResource(R.string.settings_week_start),
onDismiss = onDismiss,
predictiveBack = true,
) {
Box(
modifier = Modifier
.fillMaxWidth()
.padding(horizontal = 12.dp, vertical = 8.dp)
.height(PREVIEW_HEIGHT),
contentAlignment = Alignment.Center,
) {
Crossfade(
targetState = resolved,
animationSpec = if (reduceMotion) snap() else tween(durationMillis = 250),
label = "week-start-preview",
) { day ->
Box(
modifier = Modifier
.clip(PREVIEW_SHAPE)
.background(MaterialTheme.colorScheme.surface)
.clipToBounds(),
) {
MonthStylePreview(
style = monthStyle,
weekStart = day,
height = PREVIEW_HEIGHT,
)
}
}
ViewPreviewFrame(
selected = resolved,
label = "week-start-preview",
modifier = Modifier.padding(vertical = 8.dp),
) { day ->
MonthStylePreview(
style = monthStyle,
weekStart = day,
height = PREVIEW_HEIGHT,
)
}
PickerDescription(stringResource(R.string.settings_week_start_hint))
options.forEachIndexed { index, option ->
@@ -107,4 +79,3 @@ internal fun WeekStartPicker(
/** Short enough to leave the first options on screen under it. */
private val PREVIEW_HEIGHT = 200.dp
private val PREVIEW_SHAPE = RoundedCornerShape(12.dp)

4
app/src/main/java/de/jeanlucmakiola/calendula/ui/week/WeekScreen.kt
View File

@@ -148,7 +148,7 @@ private val ALL_DAY_VERTICAL_PADDING = 6.dp
private val COLUMN_GAP = 2.dp
/** Total all-day strip height for a week (0 when there are no all-day events). */
private fun WeekUiState.Success.allDayStripHeight(): Dp {
internal fun WeekUiState.Success.allDayStripHeight(): Dp {
if (allDaySpans.isEmpty()) return 0.dp
val lanes = allDaySpans.maxOf { it.lane } + 1
return ALL_DAY_ROW_HEIGHT * lanes + ALL_DAY_VERTICAL_PADDING * 2
@@ -402,7 +402,7 @@ private fun WeekContent(
}
@Composable
private fun WeekSuccess(
internal fun WeekSuccess(
state: WeekUiState.Success,
topSectionColor: Color,
scrollState: ScrollState,

78
app/src/main/java/de/jeanlucmakiola/calendula/ui/week/WeekViewPreview.kt Normal file
View File

@@ -0,0 +1,78 @@
package de.jeanlucmakiola.calendula.ui.week
import androidx.compose.foundation.rememberScrollState
import androidx.compose.material3.MaterialTheme
import androidx.compose.runtime.Composable
import androidx.compose.runtime.LaunchedEffect
import androidx.compose.runtime.remember
import androidx.compose.runtime.snapshotFlow
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.Dp
import de.jeanlucmakiola.calendula.ui.common.ScaledViewPreview
import de.jeanlucmakiola.calendula.ui.common.rememberTimelineDragController
import de.jeanlucmakiola.calendula.ui.common.sampleTimelineEvents
import kotlinx.datetime.DateTimeUnit
import kotlinx.datetime.DayOfWeek
import kotlinx.datetime.LocalDate
import kotlinx.datetime.TimeZone
import kotlinx.coroutines.flow.first
import kotlinx.datetime.plus
import kotlinx.datetime.toLocalDateTime
import kotlin.time.Clock
/**
* A live, scaled-down Week view for the onboarding view chooser. The week and
* today's column are real; only the events are stand-ins.
*
* The timeline is scrolled to the working day rather than to midnight — the
* live view centres on noon once it knows its own scroll range, which a preview
* that is never interacted with would otherwise never do.
*/
@Composable
internal fun WeekViewPreview(
weekStart: DayOfWeek,
height: Dp,
modifier: Modifier = Modifier,
) {
val zone = remember { TimeZone.currentSystemDefault() }
val today = remember(zone) { Clock.System.now().toLocalDateTime(zone).date }
val state = remember(today, weekStart, zone) { sampleWeekState(today, weekStart, zone) }
val scrollState = rememberScrollState()
LaunchedEffect(Unit) {
snapshotFlow { scrollState.maxValue }.first { it > 0 }
// Half the scroll range is noon — the same centring the live view does.
scrollState.scrollTo(scrollState.maxValue / 2)
}
ScaledViewPreview(height = height, modifier = modifier) {
WeekSuccess(
state = state,
topSectionColor = MaterialTheme.colorScheme.surface,
scrollState = scrollState,
allDayHeight = state.allDayStripHeight(),
dragController = rememberTimelineDragController(),
onEventClick = {},
onOpenDay = {},
onCreateAt = { _, _ -> },
onDrop = {},
)
}
}
/** Sample week state, laid out through the same helpers the live view uses. */
private fun sampleWeekState(
today: LocalDate,
weekStart: DayOfWeek,
zone: TimeZone,
): WeekUiState.Success {
val start = today.startOfWeek(weekStart)
val days = (0 until 7).map { start.plus(it, DateTimeUnit.DAY) }
val events = sampleTimelineEvents(days, today, zone)
return WeekUiState.Success(
weekStart = start,
today = today,
days = days,
allDaySpans = layoutAllDay(events.filter { it.isAllDay }, days, zone),
timedByDay = days.associateWith { layoutDay(events, it, zone) },
)
}

32
app/src/main/res/values/strings.xml
View File

@@ -18,16 +18,20 @@
<!-- Permission flow (F1) -->
<string name="permission_rationale_title">See all your events, beautifully</string>
<string name="permission_rationale_body">Calendula needs access to your calendar to show and manage your events. That\'s all it asks for up front — and nothing ever leaves your device.</string>
<string name="permission_rationale_body">Calendula needs access to your calendar to show and manage your events.</string>
<string name="permission_request_button">Grant calendar access</string>
<string name="permission_denied_title">Calendar access denied</string>
<string name="permission_denied_body">Calendula cannot show events without calendar access. You can grant it again in the system settings.</string>
<string name="permission_open_settings_button">Open system settings</string>
<string name="permission_retry_button">Try again</string>
<string name="permission_benefit_private_title">Stays on your device</string>
<string name="permission_benefit_private_body">Your calendars are read locally and never leave the phone.</string>
<string name="permission_benefit_private_title">Private by design</string>
<string name="permission_benefit_private_body">No internet permission, no telemetry — nothing ever leaves your phone.</string>
<string name="permission_benefit_sync_title">All your calendars, together</string>
<string name="permission_benefit_sync_body">Google, CalDAV, local — anything synced to the device just appears.</string>
<!-- Unused since the wizard trim (#163) — the privacy point is now
permission_benefit_private_*. Kept until Weblate drops them from the
translations: removing a base key a translation still carries is a
fatal ExtraTranslation. -->
<string name="permission_benefit_privacy_title">No tracking, ever</string>
<string name="permission_benefit_privacy_body">Zero telemetry, zero analytics, no ads.</string>
<string name="permission_privacy_footnote">Stays on your device · no internet permission</string>
@@ -268,6 +272,25 @@
<!-- Shared event strings -->
<string name="event_untitled">(No title)</string>
<!-- First-launch wizard (#163) -->
<string name="onboarding_step_counter">Step %1$d of %2$d</string>
<string name="onboarding_backup_title">Your events live only here</string>
<string name="onboarding_backup_body">Nothing on this phone syncs to an account, so losing it would lose your calendar. Calendula can write a backup for you.</string>
<string name="onboarding_backup_benefit_folder_title">A folder you choose</string>
<string name="onboarding_backup_benefit_folder_body">Backups are plain .ics files — put them somewhere that syncs, or on an SD card.</string>
<string name="onboarding_backup_benefit_daily_title">Once a day, by itself</string>
<string name="onboarding_backup_benefit_daily_body">Calendula exports your local calendars in the background. Change how often in Settings.</string>
<string name="onboarding_backup_enable_button">Choose folder and back up</string>
<string name="onboarding_backup_skip_button">Not now</string>
<string name="onboarding_view_title">What should open first?</string>
<string name="onboarding_month_style_title">How should Month look?</string>
<string name="onboarding_view_continue_button">Continue</string>
<string name="onboarding_back">Back</string>
<string name="onboarding_visibility_button">Got it</string>
<string name="onboarding_done_title">You\'re all set</string>
<string name="onboarding_done_body">Your calendars are ready. Everything you just chose can be changed later in Settings.</string>
<string name="onboarding_done_button">Open my calendar</string>
<!-- Reminder notifications (v1.4) -->
<string name="reminder_channel_name">Event reminders</string>
<string name="reminder_channel_description">Notifications at the reminder times of your events</string>
@@ -277,6 +300,7 @@
<string name="reminder_benefit_delivery_body">Every reminder on your events arrives as a notification, right on time.</string>
<string name="reminder_benefit_duplicates_title">Using a second calendar app?</string>
<string name="reminder_benefit_duplicates_body">If another app also posts reminders, you\'ll see them twice — turn them off there or here.</string>
<!-- Unused since the wizard trim (#163); see the note above. -->
<string name="reminder_benefit_reversible_title">Change it anytime</string>
<string name="reminder_benefit_reversible_body">The switch lives in Settings, under Notifications.</string>
<string name="reminder_onboarding_enable_button">Turn on reminders</string>
@@ -597,7 +621,7 @@
<string name="calendars_visibility_hint">Turn a calendar off to hide it on this device — its events disappear from the app and it stops reminding you. This is the same switch your other calendar apps use, so they hide it too. Nothing is deleted, no other device is affected, and you can turn it back on here anytime.</string>
<string name="calendars_visibility_a11y">Show \"%1$s\"</string>
<string name="calendars_visibility_notice_title">Some calendars are switched off</string>
<string name="calendars_visibility_notice_message">Calendula now shows the calendars that are switched on for this device, so what you see and what reminds you can no longer disagree. Some of yours are currently off — they were switched off here or in another calendar app. Turn any of them back on in Settings → Calendars.</string>
<string name="calendars_visibility_notice_message">Calendula shows the calendars that are switched on for this device, and some of yours are off. To see their events, switch them on under Settings → Calendars.</string>
<!-- Footer row under the event-form and .ics import calendar pickers. -->
<string name="calendar_picker_missing_title">Missing a calendar?</string>
<string name="calendar_picker_missing_summary">It may be switched off, read-only, or filled from your contacts — manage your calendars here.</string>

26
app/src/test/java/de/jeanlucmakiola/calendula/data/prefs/SettingsPrefsTest.kt
View File

@@ -337,6 +337,32 @@ class SettingsPrefsTest {
assertThat(prefs.reminderOnboardingDone.first()).isTrue()
}
@Test
fun `the wizard arms on a first run`(@TempDir tempDir: Path) = runTest {
val prefs = SettingsPrefs(newDataStore(tempDir))
prefs.armOnboardingWizard()
assertThat(prefs.onboardingWizardArmed.first()).isTrue()
}
@Test
fun `the wizard does not arm once the reminder step is answered`(@TempDir tempDir: Path) = runTest {
// An existing install re-granting the permission is not re-onboarded.
val prefs = SettingsPrefs(newDataStore(tempDir))
prefs.setReminderOnboardingDone()
prefs.armOnboardingWizard()
assertThat(prefs.onboardingWizardArmed.first()).isFalse()
}
@Test
fun `closing the wizard disarms it`(@TempDir tempDir: Path) = runTest {
val prefs = SettingsPrefs(newDataStore(tempDir))
prefs.armOnboardingWizard()
prefs.finishOnboardingWizard()
assertThat(prefs.onboardingDoneShown.first()).isTrue()
assertThat(prefs.onboardingWizardArmed.first()).isFalse()
}
@Test
fun `default reminder is empty until set`(@TempDir tempDir: Path) = runTest {
val prefs = SettingsPrefs(newDataStore(tempDir))

246
app/src/test/java/de/jeanlucmakiola/calendula/ui/onboarding/OnboardingPlanTest.kt Normal file
View File

@@ -0,0 +1,246 @@
package de.jeanlucmakiola.calendula.ui.onboarding
import com.google.common.truth.Truth.assertThat
import org.junit.jupiter.api.Test
/**
* The wizard's step plan (#163). Two invariants carry the whole feature: an
* existing install must never be re-onboarded, and the counter must not
* renumber under the user as steps are completed.
*/
class OnboardingPlanTest {
private fun plan(
hasPermission: Boolean = false,
remindersDone: Boolean = false,
wizardArmed: Boolean = false,
backupDone: Boolean = false,
viewDone: Boolean = false,
monthStyleDone: Boolean = false,
backupApplies: Boolean? = null,
visibilityArmed: Boolean = false,
visibilityDone: Boolean = false,
doneShown: Boolean = false,
) = onboardingPlan(
hasPermission = hasPermission,
remindersDone = remindersDone,
wizardArmed = wizardArmed,
backupDone = backupDone,
viewDone = viewDone,
monthStyleDone = monthStyleDone,
backupApplies = backupApplies,
visibilityArmed = visibilityArmed,
visibilityDone = visibilityDone,
doneShown = doneShown,
)
@Test
fun `fresh install starts on the permission step`() {
val fresh = plan()
assertThat(fresh.current).isEqualTo(OnboardingStep.Permission)
assertThat(fresh.index).isEqualTo(1)
assertThat(fresh.showsProgress).isTrue()
}
@Test
fun `granting the permission does not renumber the steps behind it`() {
// The plan keeps completed steps, so the reminder step stays step 2 of
// the same flow rather than becoming step 1 of a shorter one.
val granted = plan(hasPermission = true, wizardArmed = true, backupApplies = true)
assertThat(granted.steps).containsExactly(
OnboardingStep.Permission,
OnboardingStep.Reminders,
OnboardingStep.Backup,
OnboardingStep.View,
OnboardingStep.MonthStyle,
OnboardingStep.Done,
).inOrder()
assertThat(granted.current).isEqualTo(OnboardingStep.Reminders)
assertThat(granted.index).isEqualTo(2)
}
@Test
fun `a synced calendar drops the backup step`() {
val synced = plan(
hasPermission = true,
wizardArmed = true,
remindersDone = true,
backupApplies = false,
)
assertThat(synced.steps).doesNotContain(OnboardingStep.Backup)
assertThat(synced.current).isEqualTo(OnboardingStep.View)
assertThat(synced.total).isEqualTo(5)
}
@Test
fun `the backup step is assumed until the calendars can be read`() {
// Before the grant the answer is unknowable, so the flow is planned at
// its longest — it may shrink afterwards, never grow.
assertThat(plan(backupApplies = null).steps).contains(OnboardingStep.Backup)
}
@Test
fun `an existing install is not re-onboarded`() {
val existing = plan(hasPermission = true, remindersDone = true)
assertThat(existing.steps).isEmpty()
assertThat(existing.current).isNull()
}
@Test
fun `an existing install owing only the reminder step gets no counter`() {
val existing = plan(hasPermission = true)
assertThat(existing.steps).containsExactly(OnboardingStep.Reminders)
assertThat(existing.current).isEqualTo(OnboardingStep.Reminders)
assertThat(existing.showsProgress).isFalse()
}
@Test
fun `re-granting the permission on an onboarded install skips the extra steps`() {
// Revoked and granted again: the reminder step is already answered, so
// this is not a fresh install and only the permission is owed.
val revoked = plan(remindersDone = true)
assertThat(revoked.steps).containsExactly(OnboardingStep.Permission)
assertThat(revoked.showsProgress).isFalse()
}
@Test
fun `re-granting after the wizard itself ran does not re-enter it`() {
// The closing screen clears the armed flag, so someone the wizard did
// onboard ends up where any other revoker does: one screen, no counter.
val revoked = plan(remindersDone = true, wizardArmed = false, doneShown = true)
assertThat(revoked.steps).containsExactly(OnboardingStep.Permission)
assertThat(revoked.showsProgress).isFalse()
}
@Test
fun `a read notice leaves nothing behind in a later plan`() {
// The notice is retired once read, so its step stops padding the count
// on a later re-grant.
val later = plan(remindersDone = true, visibilityArmed = false, visibilityDone = true)
assertThat(later.steps).containsExactly(OnboardingStep.Permission)
assertThat(later.showsProgress).isFalse()
}
@Test
fun `answering every step ends the flow`() {
val done = plan(
hasPermission = true,
remindersDone = true,
wizardArmed = true,
backupDone = true,
viewDone = true,
monthStyleDone = true,
backupApplies = true,
doneShown = true,
)
assertThat(done.current).isNull()
assertThat(done.index).isEqualTo(0)
}
@Test
fun `the month style is asked whatever view was chosen`() {
// Month is reachable from the drawer whatever opens first, and making
// the step conditional would move the counter on the step before it.
val afterView = plan(
hasPermission = true,
wizardArmed = true,
remindersDone = true,
backupDone = true,
viewDone = true,
backupApplies = true,
)
assertThat(afterView.current).isEqualTo(OnboardingStep.MonthStyle)
}
@Test
fun `back steps to the previous answered step`() {
val onView = plan(
hasPermission = true,
wizardArmed = true,
remindersDone = true,
backupDone = true,
backupApplies = true,
)
assertThat(onView.current).isEqualTo(OnboardingStep.View)
assertThat(onView.previous).isEqualTo(OnboardingStep.Backup)
assertThat(onView.canGoBack).isTrue()
}
@Test
fun `back is refused where the previous step is the system grant`() {
// The permission is the system's to give; there is nothing to return to.
val onReminders = plan(hasPermission = true, wizardArmed = true, backupApplies = true)
assertThat(onReminders.previous).isEqualTo(OnboardingStep.Permission)
assertThat(onReminders.canGoBack).isFalse()
}
@Test
fun `back is refused on the first step and once the flow is done`() {
assertThat(plan().canGoBack).isFalse()
val done = plan(
hasPermission = true,
remindersDone = true,
wizardArmed = true,
backupDone = true,
viewDone = true,
monthStyleDone = true,
backupApplies = true,
doneShown = true,
)
assertThat(done.previous).isNull()
assertThat(done.canGoBack).isFalse()
}
@Test
fun `the wizard ends on its closing screen`() {
val lastAnswer = plan(
hasPermission = true,
remindersDone = true,
wizardArmed = true,
backupDone = true,
viewDone = true,
monthStyleDone = true,
backupApplies = true,
)
assertThat(lastAnswer.current).isEqualTo(OnboardingStep.Done)
assertThat(lastAnswer.index).isEqualTo(lastAnswer.total)
}
@Test
fun `the visibility notice is asked before the closing screen`() {
val armed = plan(
hasPermission = true,
remindersDone = true,
wizardArmed = true,
backupDone = true,
viewDone = true,
monthStyleDone = true,
backupApplies = true,
visibilityArmed = true,
)
assertThat(armed.current).isEqualTo(OnboardingStep.Visibility)
assertThat(armed.steps.last()).isEqualTo(OnboardingStep.Done)
}
@Test
fun `an onboarded install owing only the notice gets one screen and no counter`() {
// The notice is the one step an existing install can still be given —
// and on its own it is not a wizard, so there is nothing to conclude.
val notice = plan(hasPermission = true, remindersDone = true, visibilityArmed = true)
assertThat(notice.steps).containsExactly(OnboardingStep.Visibility)
assertThat(notice.current).isEqualTo(OnboardingStep.Visibility)
assertThat(notice.showsProgress).isFalse()
assertThat(notice.canGoBack).isFalse()
}
@Test
fun `reading the notice ends an otherwise onboarded flow`() {
val read = plan(
hasPermission = true,
remindersDone = true,
visibilityArmed = true,
visibilityDone = true,
)
assertThat(read.current).isNull()
}
}

32
docs/ARCHITECTURE.md
View File

@@ -27,7 +27,7 @@ the package list (recurring writes, save conflicts, reminder delivery).
```mermaid
flowchart TD
subgraph UI ["ui/ — Compose screens + ViewModels"]
Screens["Month / Week / Day\nDetail / Edit / Settings\nPermission + Reminder onboarding"]
Screens["Month / Week / Day\nDetail / Edit / Settings\nOnboarding wizard"]
end
subgraph Data ["data/"]
Repo["CalendarRepository\n(interface + impl, Flow-based, io-dispatched)"]
@@ -78,8 +78,8 @@ flowchart TD
## Navigation
There is no navigation library. `MainActivity` hosts `RootScreen`, which
gates on the calendar permission and the one-time reminder onboarding, then
shows `CalendarHost`. `CalendarHost` holds the active view (month/week/day)
gates on the first-launch wizard (`ui/onboarding/`), then shows
`CalendarHost`. `CalendarHost` holds the active view (month/week/day)
plus overlay state for detail, edit, and settings — full-screen overlays
driven by `AnimatedVisibility` with a *held-key* pattern: the last shown
key stays alive through the slide-out so content never flashes empty.
@@ -87,6 +87,32 @@ A tapped reminder notification routes through `MainActivity` (`singleTop` +
`onNewIntent`) as an external detail key that `CalendarHost` consumes
exactly like an event tap.
### First-launch wizard
`ui/onboarding/` is a plan, not a navigation graph: `onboardingPlan()` is a
pure function of the stored answers that returns the whole flow *plus* the
step it is on, and `RootScreen` renders that step. Two rules make it work:
- The plan keeps **completed** steps, so finishing one never renumbers the
counter under the user, and stepping *back* is just clearing the previous
step's answer — there is no separate back stack. The calendar grant is the
one step with nothing to return to, so back stops there.
- The optional steps (backup, view) only exist for an install still on its
first run — `armOnboardingWizard()` arms on any launch holding the calendar
permission but refuses if the reminder step was already answered, and the
closing screen clears the flag again, so revoking and re-granting the
permission later never re-onboards anyone.
Whether the backup step applies (nothing writable is synced anywhere) cannot
be known before the grant, so it is assumed until the calendar list can be
read: the flow may shrink after the grant, never sprout a step the counter
had not accounted for.
The flow closes on an "all set" screen, and the one-time calendar-visibility
notice (#75) is a step in front of it rather than a dialog over the app — it
is the only optional step an *already onboarded* install can be given, which
is why it alone is not gated on the wizard being armed.
## Recurring writes
The provider's invariants drive the design (learned the hard way, verified

2
floret-kit

Submodule floret-kit updated: ea860ed781...05c79f2afc