Add confirm dialog for translation source language (#517)

* add confirmation dialog to download translation data

* add DataDownloadViewModel for centralized download state management

* navigate to translation setting on clicking Change language

* remove unused import directive

* use dynamic source language from context for download confirm dialog

* add confirm dialog in select translation language screen

* Standardize spacing of all docstrings - WIP will check punctuation/capitalization

* trigger download state from select language screen

* fix navigation to download screen

* Further updates of comments in the project

* Move file to facilitate rebase

* move DataDownloadScreen

---------

Co-authored-by: Andrew Tavis McAllister <andrew.t.mcallister@gmail.com>

Author: catreedle

app/src/main/java/be/scri/App.kt

@@ -21,6 +21,7 @@ import androidx.compose.runtime.getValue
 import androidx.compose.runtime.rememberCoroutineScope
 import androidx.compose.ui.Modifier
 import androidx.compose.ui.unit.dp
+import androidx.lifecycle.viewmodel.compose.viewModel
 import androidx.navigation.NavHostController
 import androidx.navigation.compose.NavHost
 import androidx.navigation.compose.composable
@@ -30,14 +31,15 @@ import be.scri.navigation.Screen
 import be.scri.ui.common.appcomponents.HintDialog
 import be.scri.ui.common.bottombar.ScribeBottomBar
 import be.scri.ui.screens.DefaultCurrencySymbolScreen
-import be.scri.ui.screens.DownloadDataScreen
 import be.scri.ui.screens.InstallationScreen
 import be.scri.ui.screens.LanguageSettingsScreen
 import be.scri.ui.screens.PrivacyPolicyScreen
 import be.scri.ui.screens.SelectTranslationSourceLanguageScreen
 import be.scri.ui.screens.ThirdPartyScreen
 import be.scri.ui.screens.WikimediaScreen
 import be.scri.ui.screens.about.AboutScreen
+import be.scri.ui.screens.download.DataDownloadViewModel
+import be.scri.ui.screens.download.DownloadDataScreen
 import be.scri.ui.screens.settings.SettingsScreen
 import be.scri.ui.theme.ScribeTheme
 import kotlinx.coroutines.CoroutineScope
@@ -60,7 +62,8 @@ import kotlinx.coroutines.launch
  * @param isDarkTheme Flag to indicate if dark theme is enabled.
  * @param modifier Optional layout modifier for UI customization.
  */
-@SuppressLint("ComposeModifierMissing")
+@Suppress("LongParameterList")
+@SuppressLint("ComposeModifierMissing", "LongParameterList")
 @Composable
 fun ScribeApp(
     pagerState: PagerState,
@@ -72,9 +75,12 @@ fun ScribeApp(
     context: Context,
     isDarkTheme: Boolean,
     modifier: Modifier = Modifier,
+    downloadViewModel: DataDownloadViewModel = viewModel(),
 ) {
     val coroutineScope = rememberCoroutineScope()
     val navBackStackEntry by navController.currentBackStackEntryAsState()
+    val downloadStates = downloadViewModel.downloadStates
+    val onDownloadAction = downloadViewModel::handleDownloadAction
 
     ScribeTheme(
         useDarkTheme = isDarkTheme,
@@ -199,6 +205,13 @@ fun ScribeApp(
                         onBackNavigation = {
                             navController.popBackStack()
                         },
+                        onNavigateToTranslation = { language ->
+                            navController.navigate(
+                                "translation_language_detail/$language",
+                            )
+                        },
+                        downloadStates = downloadStates,
+                        onDownloadAction = onDownloadAction,
                         modifier = Modifier.padding(innerPadding),
                     )
                 }
@@ -229,6 +242,10 @@ fun ScribeApp(
                         onBackNavigation = {
                             navController.popBackStack()
                         },
+                        onNavigateToDownloadData = {
+                            navController.popBackStack()
+                        },
+                        onDownloadAction = onDownloadAction,
                         modifier = Modifier.padding(innerPadding),
                         currentLanguage = language,
                     )

app/src/main/java/be/scri/extensions/CommonsContext.kt

@@ -9,15 +9,15 @@ import be.scri.helpers.PREFS_KEY
 /**
  * Retrieves the shared preferences using the predefined PREFS_KEY.
  *
- * @receiver Context used to access shared preferences
- * @return SharedPreferences instance
+ * @receiver Context used to access shared preferences.
+ * @return SharedPreferences instance.
  */
 fun Context.getSharedPrefs() = getSharedPreferences(PREFS_KEY, Context.MODE_PRIVATE)
 
 /**
  * Provides an instance of BaseConfig associated with the context.
  *
- * @receiver Context used to create BaseConfig instance
- * @return BaseConfig instance
+ * @receiver Context used to create BaseConfig instance.
+ * @return BaseConfig instance.
  */
 val Context.baseConfig: BaseConfig get() = BaseConfig.newInstance(this)

app/src/main/java/be/scri/extensions/ContextStyling.kt

@@ -13,8 +13,8 @@ import be.scri.helpers.DARK_GREY
 /**
  * Retrieves the appropriate text color based on the user's theme settings.
  *
- * @receiver Context used to access resources and configuration
- * @return Int representing the text color
+ * @receiver Context used to access resources and configuration.
+ * @return Int representing the text color.
  */
 fun Context.getProperTextColor() =
     if (baseConfig.isUsingSystemTheme) {
@@ -26,8 +26,8 @@ fun Context.getProperTextColor() =
 /**
  * Retrieves the appropriate key color based on the user's theme settings.
  *
- * @receiver Context used to access resources and configuration
- * @return Int representing the key color
+ * @receiver Context used to access resources and configuration.
+ * @return Int representing the key color.
  */
 
 fun Context.getProperKeyColor() =
@@ -40,8 +40,8 @@ fun Context.getProperKeyColor() =
 /**
  * Retrieves the appropriate background color based on the user's theme settings.
  *
- * @receiver Context used to access resources and configuration
- * @return Int representing the background color
+ * @receiver Context used to access resources and configuration.
+ * @return Int representing the background color.
  */
 fun Context.getProperBackgroundColor() =
     if (baseConfig.isUsingSystemTheme) {
@@ -53,8 +53,8 @@ fun Context.getProperBackgroundColor() =
 /**
  * Retrieves the appropriate primary color based on the user's theme settings.
  *
- * @receiver Context used to access resources and configuration
- * @return Int representing the primary color
+ * @receiver Context used to access resources and configuration.
+ * @return Int representing the primary color.
  */
 fun Context.getProperPrimaryColor() =
     when {
@@ -66,8 +66,8 @@ fun Context.getProperPrimaryColor() =
 /**
  * Determines if the current theme is black and white.
  *
- * @receiver Context used to access configuration
- * @return Boolean indicating if the theme is black and white
+ * @receiver Context used to access configuration.
+ * @return Boolean indicating if the theme is black and white.
  */
 fun Context.isBlackAndWhiteTheme() =
     baseConfig.textColor == Color.WHITE &&
@@ -77,8 +77,8 @@ fun Context.isBlackAndWhiteTheme() =
 /**
  * Determines if the current theme is white.
  *
- * @receiver Context used to access configuration
- * @return Boolean indicating if the theme is white
+ * @receiver Context used to access configuration.
+ * @return Boolean indicating if the theme is white.
  */
 
 fun Context.isWhiteTheme() =
@@ -89,7 +89,7 @@ fun Context.isWhiteTheme() =
 /**
  * Determines if the system is using a dark theme.
  *
- * @receiver Context used to access configuration
- * @return Boolean indicating if the system is using a dark theme
+ * @receiver Context used to access configuration.
+ * @return Boolean indicating if the system is using a dark theme.
  */
 fun Context.isUsingSystemDarkTheme() = resources.configuration.uiMode and Configuration.UI_MODE_NIGHT_YES != 0

app/src/main/java/be/scri/extensions/Drawable.kt

@@ -9,6 +9,7 @@ import android.graphics.drawable.Drawable
  * Applies a color filter to the drawable using the specified color.
  *
  * @param color The color to apply using the SRC_IN mode.
+ *
  * @return The mutated [Drawable] with the color filter applied.
  */
 fun Drawable.applyColorFilter(color: Int) = mutate().setColorFilter(color, PorterDuff.Mode.SRC_IN)

app/src/main/java/be/scri/extensions/Int.kt

@@ -34,6 +34,7 @@ fun Int.getContrastColor(): Int {
  *
  * @receiver Int The color to adjust.
  * @param factor Float The factor to multiply the alpha by (0f = fully transparent, 1f = original alpha).
+ *
  * @return Int The color with modified alpha.
  */
 fun Int.adjustAlpha(factor: Float): Int {
@@ -62,6 +63,7 @@ private const val FACTOR_DIVIDER = 100
  *
  * @receiver Int The original color.
  * @param factor Int The factor to darken the color by (default is 8).
+ *
  * @return Int The darkened color.
  */
 
@@ -87,6 +89,7 @@ fun Int.darkenColor(factor: Int = DEFAULT_DARKEN_FACTOR): Int {
  *
  * @receiver Int The original color.
  * @param factor Int The factor to lighten the color by (default is 8).
+ *
  * @return Int The lightened color.
  */
 
@@ -113,6 +116,7 @@ private const val LIGHTNESS_THRESHOLD = 0.5f
  * Converts a color from HSL to HSV.
  *
  * @param hsl FloatArray The color in HSL format.
+ *
  * @return FloatArray The converted color in HSV format.
  */
 private fun hsl2hsv(hsl: FloatArray): FloatArray {
@@ -127,6 +131,7 @@ private fun hsl2hsv(hsl: FloatArray): FloatArray {
  * Converts a color from HSV to HSL.
  *
  * @param hsv FloatArray The color in HSV format.
+ *
  * @return FloatArray The converted color in HSL format.
  */
 

app/src/main/java/be/scri/helpers/AlphanumericComparator.kt

@@ -16,6 +16,7 @@ class AlphanumericComparator {
      *
      * @param string1 The first string to compare.
      * @param string2 The second string to compare.
+     *
      * @return A negative integer if `string1` comes before `string2`,
      *         a positive integer if `string1` comes after `string2`,
      *         and zero if they are equal.
@@ -67,6 +68,7 @@ class AlphanumericComparator {
      * @param string The input string.
      * @param length The total length of the string.
      * @param marker The current position in the string from where extraction starts.
+     *
      * @return A substring representing a numeric or alphabetic chunk.
      */
     private fun getChunk(
@@ -105,7 +107,8 @@ class AlphanumericComparator {
      * Checks if the given character is a numeric digit.
      *
      * @param ch The character to check.
-     * @return `true` if the character is a digit (0-9), `false` otherwise.
+     *
+     * @return true if the character is a digit (0-9), false otherwise.
      */
     private fun isDigit(ch: Char) = ch in '0'..'9'
 }

app/src/main/java/be/scri/helpers/AnnotationTextUtils.kt

@@ -17,7 +17,9 @@ import be.scri.helpers.LanguageMappingConstants.prepAnnotationConversionDict
 object AnnotationTextUtils {
     /**
      * Maps a case annotation string (e.g., "genitive case") to a displayable text and color.
+     *
      * @param nounType The case annotation string.
+     *
      * @return A pair containing the color resource ID and the display text.
      */
     fun handleTextForCaseAnnotation(
@@ -40,7 +42,9 @@ object AnnotationTextUtils {
 
     /**
      * Maps a noun type string (e.g., "masculine") to a displayable text and color.
+     *
      * @param nounType The noun type or gender string.
+     *
      * @return A pair containing the color resource ID and the display text.
      */
     fun handleColorAndTextForNounType(
@@ -62,8 +66,10 @@ object AnnotationTextUtils {
 
     /**
      * Processes a noun gender abbreviation for display, converting it based on language-specific conventions.
+     *
      * @param language The current keyboard language.
      * @param text The gender abbreviation (e.g., "M", "F", "N").
+     *
      * @return The language-specific display text (e.g., "М" for Russian masculine).
      */
     fun processValueForNouns(
@@ -73,8 +79,10 @@ object AnnotationTextUtils {
 
     /**
      * Processes a preposition case abbreviation for display, converting it based on language-specific conventions.
+     *
      * @param language The current keyboard language.
      * @param text The case abbreviation (e.g., "Acc", "Dat").
+     *
      * @return The language-specific display text (e.g., "Akk" for German accusative).
      */
     fun processValuesForPreposition(

app/src/main/java/be/scri/helpers/BaseConfig.kt

@@ -8,10 +8,8 @@ import be.scri.extensions.getSharedPrefs
 
 /**
  * A configuration helper class for managing app settings.
- * <p>
  * This class provides access to various UI-related preferences such as colors, language settings,
  * and theme preferences. Preferences are stored using `SharedPreferences`.
- * </p>
  *
  * @param context The application context used to retrieve resources and shared preferences.
  */
@@ -28,6 +26,7 @@ open class BaseConfig(
          * Creates a new instance of `BaseConfig`.
          *
          * @param context The application context.
+         *
          * @return A new instance of `BaseConfig`.
          */
         fun newInstance(context: Context) = BaseConfig(context)

app/src/main/java/be/scri/helpers/DatabaseFileManager.kt

@@ -12,6 +12,7 @@ import java.io.IOException
 /**
  * Manages access to all SQLite database files.
  * Ensures DB files are copied from assets and provides read-only connections.
+ *
  * @param context The application context.
  */
 class DatabaseFileManager(
@@ -31,6 +32,7 @@ class DatabaseFileManager(
      * It handles copying the database from assets if it doesn't exist locally.
      *
      * @param language The language code (e.g., "DE", "FR") used to determine the database filename.
+     *
      * @return An open, read-only [SQLiteDatabase] instance, or `null` on failure.
      */
     fun getLanguageDatabase(language: String): SQLiteDatabase? {
@@ -56,6 +58,7 @@ class DatabaseFileManager(
      * @param dbName The filename of the database (e.g., "ENLanguageData.sqlite").
      * @param assetPath The path to the database file within the app's assets folder
      * (e.g., "data/ENLanguageData.sqlite").
+     *
      * @return An open, read-only [SQLiteDatabase], or `null` if copying or opening fails.
      */
     private fun getDatabase(
@@ -85,7 +88,8 @@ class DatabaseFileManager(
      *
      * @param dbFile The destination [File] in the app's database directory.
      * @param assetPath The path to the source file within the assets folder.
-     * @return `true` if the copy was successful, `false` otherwise.
+     *
+     * @return true if the copy was successful, false otherwise.
      */
     private fun copyDatabaseFromAssets(
         dbFile: File,

app/src/main/java/be/scri/helpers/DatabaseManagers.kt

@@ -41,6 +41,7 @@ class DatabaseManagers(
      * It delegates the loading and parsing logic to the [ContractDataLoader].
      *
      * @param language The language code (e.g., "DE", "FR") for which to load the contract.
+     *
      * @return A [DataContract] object containing the language's structural metadata, or `null`
      * if not found or on error.
      */