Merge pull request #23 from matejsemancik/feature/stats-ahead-behind

matejsemancik · web-flow · commit d2a6fc3869ce · 2025-08-27T15:43:04.000+02:00
Stats: ahead/behind indicators
diff --git a/GEMINI.md b/GEMINI.md
@@ -0,0 +1,25 @@
+# Gemini Guidelines
+
+This file contains guidelines for the Gemini AI assistant to follow when working on this project.
+
+## Architecture
+
+This project follows a Kotlin Multiplatform (KMP) architecture with a `shared` module for the core business logic and a `desktopApp` module for the desktop-specific implementation. The architecture is based on a variant of Clean Architecture, with a clear separation of concerns between the data, domain, and presentation layers.
+
+### Key Technologies
+
+*   **Kotlin Multiplatform:** For sharing code between different platforms.
+*   **Jetpack Compose for Desktop:** For building the UI.
+*   **Koin:** For dependency injection.
+*   **Kotlin Coroutines:** For asynchronous programming.
+*   **Ktorfit:** For type-safe HTTP clients.
+*   **Room:** For local data persistence.
+
+### Modules
+
+*   **`shared`:** Contains the platform-independent code.
+    *   **`commonMain`:** The main source set for the shared module.
+        *   **`data`:** The data layer, including repositories, network services, and the database.
+        *   **`feature`:** The presentation layer, with each feature in its own package.
+        *   **`design`:** The design system, including colors, typography, and custom UI components.
+*   **`desktopApp`:** Contains the desktop-specific implementation.
diff --git a/shared/src/commonMain/composeResources/values/strings.xml b/shared/src/commonMain/composeResources/values/strings.xml
@@ -58,4 +58,7 @@
     <string name="stats_today">Today: </string>
     <string name="stats_weekly">This week: </string>
     <string name="stats_period">Current period: </string>
+    <string name="stats_ahead">+%1$s ahead</string>
+    <string name="stats_behind">-%1$s behind</string>
+    <string name="stats_caught_up">Done for today</string>
 </resources>
diff --git a/shared/src/commonMain/kotlin/dev/matsem/bpm/data/repo/WorklogRepo.kt b/shared/src/commonMain/kotlin/dev/matsem/bpm/data/repo/WorklogRepo.kt
@@ -133,7 +133,8 @@ internal class WorklogRepoImpl(
             start..end
         }
 
-        val workSchedule = tempoApiManager.getUserSchedule(dateRange = currentApprovalPeriod.dateRange)
+        val workSchedule =
+            tempoApiManager.getUserSchedule(dateRange = currentApprovalPeriod.dateRange)
         val allWorklogs = tempoApiManager.getAllWorklogs(
             jiraAccountId = user.accountId,
             dateRange = currentApprovalPeriod.dateRange,
@@ -143,24 +144,33 @@ internal class WorklogRepoImpl(
             type = WorkStats.Type.Today,
             dateRange = dateNow..dateNow,
             workSchedule = workSchedule,
-            worklogs = allWorklogs
+            worklogs = allWorklogs,
+            dateNow = dateNow,
         )
 
         val thisWeekWorkStats = getStatsForDates(
             type = WorkStats.Type.ThisWeek,
             dateRange = currentWeek,
             workSchedule = workSchedule,
-            worklogs = allWorklogs
+            worklogs = allWorklogs,
+            dateNow = dateNow,
         )
 
         val currentPeriodWorkStats = getStatsForDates(
             type = WorkStats.Type.CurrentPeriod,
             dateRange = currentApprovalPeriod.dateRange,
             workSchedule = workSchedule,
-            worklogs = allWorklogs
+            worklogs = allWorklogs,
+            dateNow = dateNow,
         )
 
-        workStats.update { listOf(todayWorkStats, thisWeekWorkStats, currentPeriodWorkStats) }
+        workStats.update {
+            listOf(
+                currentPeriodWorkStats,
+                thisWeekWorkStats,
+                todayWorkStats
+            )
+        }
     }
 
     override fun getWorkStats(): Flow<List<WorkStats>> = workStats.asStateFlow()
@@ -179,6 +189,7 @@ internal class WorklogRepoImpl(
         dateRange: ClosedRange<LocalDate>,
         workSchedule: List<DaySchedule>,
         worklogs: List<Worklog>,
+        dateNow: LocalDate,
     ): WorkStats {
         val requiredDuration = workSchedule
             .filter { it.date in dateRange }
@@ -190,6 +201,13 @@ internal class WorklogRepoImpl(
             .sumOf { it.timeSpentSeconds }
             .seconds
 
-        return WorkStats(type, dateRange, requiredDuration, trackedDuration)
+        val requiredUntilToday = workSchedule
+            .filter { it.date in dateRange && it.date <= dateNow }
+            .sumOf { it.requiredSeconds }
+            .seconds
+
+        val trackingDelta = trackedDuration - requiredUntilToday
+
+        return WorkStats(type, dateRange, requiredDuration, trackedDuration, trackingDelta)
     }
 }
diff --git a/shared/src/commonMain/kotlin/dev/matsem/bpm/data/repo/model/WorkStats.kt b/shared/src/commonMain/kotlin/dev/matsem/bpm/data/repo/model/WorkStats.kt
@@ -11,19 +11,31 @@ import kotlin.time.Duration.Companion.seconds
  * @property dateRange The range of dates the statistics cover.
  * @property requiredDuration The total required duration of work for the specified time range.
  * @property trackedDuration The total duration of work that was tracked within the specified time range.
+ * @property trackingDelta The duration by which the tracked work is ahead (positive) or behind (negative) the required work by end of today.
  */
 data class WorkStats(
     val type: Type,
     val dateRange: ClosedRange<LocalDate>,
     val requiredDuration: Duration,
     val trackedDuration: Duration,
+    val trackingDelta: Duration,
 ) {
+    /**
+     * Represents the type of work statistics.
+     */
     enum class Type {
+        /** Statistics for today. */
         Today,
+        /** Statistics for the current week. */
         ThisWeek,
+        /** Statistics for the current work period. */
         CurrentPeriod
     }
 
+    /**
+     * The percentage of tracked work towards the required work, coerced between 0f and 1f.
+     * Returns 0f if the required duration is zero.
+     */
     val percent: Float
         get() {
             if (requiredDuration.inWholeSeconds == 0L) {
@@ -32,3 +44,4 @@ data class WorkStats(
             return (trackedDuration.inWholeSeconds / requiredDuration.inWholeSeconds.toFloat()).coerceIn(0f..1f)
         }
 }
+
diff --git a/shared/src/commonMain/kotlin/dev/matsem/bpm/design/theme/BpmColors.kt b/shared/src/commonMain/kotlin/dev/matsem/bpm/design/theme/BpmColors.kt
@@ -5,14 +5,17 @@ import androidx.compose.ui.graphics.Color
 data class BpmColors(
     val favourite: Color,
     val success: Color,
+    val negativeTimeDelta: Color,
 )
 
 fun lightBpmColors() = BpmColors(
     favourite = Color(0xfff2b21d),
     success = Color(0xff31994e),
+    negativeTimeDelta = Color(0xff9c6843),
 )
 
 fun darkBpmColors() = BpmColors(
     favourite = Color(0xffd19917),
     success = Color(0xff52cc73),
+    negativeTimeDelta = Color(0xffc99977),
 )
diff --git a/shared/src/commonMain/kotlin/dev/matsem/bpm/feature/stats/ui/StatsWidgetUi.kt b/shared/src/commonMain/kotlin/dev/matsem/bpm/feature/stats/ui/StatsWidgetUi.kt
@@ -8,8 +8,10 @@ import androidx.compose.animation.slideInVertically
 import androidx.compose.animation.slideOutVertically
 import androidx.compose.animation.togetherWith
 import androidx.compose.foundation.clickable
+import androidx.compose.foundation.layout.Arrangement
 import androidx.compose.foundation.layout.Column
 import androidx.compose.foundation.layout.PaddingValues
+import androidx.compose.foundation.layout.Row
 import androidx.compose.foundation.layout.fillMaxWidth
 import androidx.compose.foundation.layout.padding
 import androidx.compose.material3.LinearProgressIndicator
@@ -27,17 +29,22 @@ import androidx.compose.ui.unit.dp
 import androidx.lifecycle.compose.LifecycleResumeEffect
 import androidx.lifecycle.compose.collectAsStateWithLifecycle
 import bpm_tracker.shared.generated.resources.Res
+import bpm_tracker.shared.generated.resources.stats_ahead
+import bpm_tracker.shared.generated.resources.stats_behind
+import bpm_tracker.shared.generated.resources.stats_caught_up
 import bpm_tracker.shared.generated.resources.stats_period
 import bpm_tracker.shared.generated.resources.stats_today
 import bpm_tracker.shared.generated.resources.stats_weekly
 import dev.matsem.bpm.data.repo.model.WorkStats
+import dev.matsem.bpm.data.repo.model.WorkStats.Type
 import dev.matsem.bpm.design.theme.BpmTheme
 import dev.matsem.bpm.design.theme.Grid
 import dev.matsem.bpm.design.tooling.VerticalSpacer
 import dev.matsem.bpm.feature.stats.presentation.StatsWidget
 import dev.matsem.bpm.feature.tracker.formatting.DurationFormatter.formatForWorkStats
 import org.jetbrains.compose.resources.stringResource
 import org.koin.compose.koinInject
+import kotlin.time.Duration
 
 @Composable
 fun StatsWidgetUi(
@@ -71,11 +78,23 @@ fun StatsWidgetUi(
                 )
             )
             Column(Modifier.padding(contentPadding)) {
-                Text(
-                    text = workStats.title,
-                    style = BpmTheme.typography.bodySmall,
-                    color = BpmTheme.colorScheme.onSurface,
-                )
+                Row(
+                    horizontalArrangement = Arrangement.SpaceBetween,
+                    modifier = Modifier.fillMaxWidth()
+                ) {
+                    Text(
+                        text = workStats.title,
+                        style = BpmTheme.typography.bodySmall,
+                        color = BpmTheme.colorScheme.onSurface,
+                    )
+                    workStats.aheadOrBehindText?.let {
+                        Text(
+                            text = it,
+                            style = BpmTheme.typography.bodySmall,
+                            color = BpmTheme.colorScheme.onSurface,
+                        )
+                    }
+                }
                 VerticalSpacer(Grid.d1)
                 LinearProgressIndicator(
                     color = when (workStats.percent) {
@@ -90,13 +109,39 @@ fun StatsWidgetUi(
     }
 }
 
+private val WorkStats.aheadOrBehindText: AnnotatedString?
+    @Composable
+    get() {
+        if (type != Type.CurrentPeriod) {
+            return null
+        }
+
+        val textRes = when {
+            trackingDelta > Duration.ZERO -> Res.string.stats_ahead
+            trackingDelta < Duration.ZERO -> Res.string.stats_behind
+            else -> Res.string.stats_caught_up
+        }
+
+        val style = when {
+            trackingDelta >= Duration.ZERO -> SpanStyle(color = BpmTheme.customColorScheme.success)
+            else -> SpanStyle(color = BpmTheme.customColorScheme.negativeTimeDelta)
+        }
+        val text = stringResource(textRes, trackingDelta.absoluteValue.formatForWorkStats())
+
+        return buildAnnotatedString {
+            withStyle(style) {
+                append(text)
+            }
+        }
+    }
+
 private val WorkStats.title: AnnotatedString
     @Composable
     get() {
         val title = when (this.type) {
-            WorkStats.Type.Today -> stringResource(Res.string.stats_today)
-            WorkStats.Type.ThisWeek -> stringResource(Res.string.stats_weekly)
-            WorkStats.Type.CurrentPeriod -> stringResource(Res.string.stats_period)
+            Type.Today -> stringResource(Res.string.stats_today)
+            Type.ThisWeek -> stringResource(Res.string.stats_weekly)
+            Type.CurrentPeriod -> stringResource(Res.string.stats_period)
         }
         return buildAnnotatedString {
             append(title)
diff --git a/shared/src/commonTest/kotlin/dev/matsem/bpm/data/repo/WorklogRepoTest.kt b/shared/src/commonTest/kotlin/dev/matsem/bpm/data/repo/WorklogRepoTest.kt

Original file line number	Diff line number	Diff line change
`@@ -5,14 +5,17 @@ import androidx.compose.ui.graphics.Color`
`5`	`5`	`data class BpmColors(`
`6`	`6`	`val favourite: Color,`
`7`	`7`	`val success: Color,`
	`8`	`+ val negativeTimeDelta: Color,`
`8`	`9`	`)`
`9`	`10`
`10`	`11`	`fun lightBpmColors() = BpmColors(`
`11`	`12`	`favourite = Color(0xfff2b21d),`
`12`	`13`	`success = Color(0xff31994e),`
	`14`	`+ negativeTimeDelta = Color(0xff9c6843),`
`13`	`15`	`)`
`14`	`16`
`15`	`17`	`fun darkBpmColors() = BpmColors(`
`16`	`18`	`favourite = Color(0xffd19917),`
`17`	`19`	`success = Color(0xff52cc73),`
	`20`	`+ negativeTimeDelta = Color(0xffc99977),`
`18`	`21`	`)`