improvement(import): improve 'cache error' message

Title: Failed to cache file

**Dialog content:**
oaz: Cello error 2.

This is often caused by a bug in the app you used to select
 the file. Please try the following fixes:

• Try re-importing the file
• Ensure there is sufficient free space on your device
• Ensure you are connected to the internet
• Copy the file to your device and try again
• Open the file using your device's file browser app

'Copy debug info' provides the stack trace, then title + content

Fixes 19616

Author: david-allison

AnkiDroid/src/main/java/com/ichi2/anki/IntentHandler.kt

@@ -226,7 +226,7 @@ class IntentHandler : AbstractIntentHandler() {
             is ImportResult.Failure -> {
                 Timber.i("File import failed")
                 // Don't import the file if it didn't load properly or doesn't have apkg extension
-                showImportUnsuccessfulDialog(this, importResult.humanReadableMessage, true)
+                showImportUnsuccessfulDialog(this, importResult, true)
             }
         }
     }

AnkiDroid/src/main/java/com/ichi2/utils/ImportUtils.kt

@@ -139,7 +139,10 @@ object ImportUtils {
             } catch (e: Exception) {
                 CrashReportService.sendExceptionReport(e, "handleFileImport")
                 Timber.e(e, "failed to handle import intent")
-                ImportResult.Failure(context.getString(R.string.import_error_handle_exception, e.localizedMessage), e)
+                ImportResult.Failure(
+                    humanReadableMessage = context.getString(R.string.import_error_handle_exception, e.localizedMessage),
+                    exception = e,
+                )
             }
         }
 
@@ -234,9 +237,13 @@ object ImportUtils {
             filename = ensureValidLength(filename)
             tempOutDir = Uri.fromFile(File(context.cacheDir, filename)).encodedPath!!
 
-            copyFileToCache(context, importPathUri, tempOutDir).asErrorDetails(context)?.let { details ->
+            copyFileToCache(context, importPathUri, tempOutDir).asErrorDetails()?.let { details ->
                 CrashReportService.sendExceptionReport(details.exceptionForReport, "ImportUtils")
-                return ImportResult.Failure(details.userFacingString, details.userFacingException)
+                return ImportResult.Failure(
+                    title = details.buildTitle(context),
+                    humanReadableMessage = details.buildHumanReadableMessage(context),
+                    exception = details.userFacingException,
+                )
             }
             sendShowImportFileDialogMsg(tempOutDir)
             return ImportResult.Success
@@ -317,7 +324,7 @@ object ImportUtils {
             exitActivity: Boolean,
         ) {
             Timber.d("showImportUnsuccessfulDialog() message %s", failure.humanReadableMessage)
-            val title = activity.resources.getString(R.string.import_title_error)
+            val title = failure.title ?: activity.getString(R.string.import_title_error)
             val dialog =
                 AlertDialog.Builder(activity).show {
                     title(text = title)
@@ -376,28 +383,46 @@ object ImportUtils {
 
             data object ContentProviderCrashed : CacheFileResult()
 
-            fun asErrorDetails(context: Context): ErrorDetails? =
+            fun asErrorDetails(): CacheErrorDetails? =
                 when (this) {
                     is Success -> null
                     is Error ->
-                        ErrorDetails(
+                        CacheErrorDetails(
                             exceptionForReport = exception,
-                            userFacingString = context.getString(R.string.import_error_copy_to_cache),
                             userFacingException = exception,
                         )
                     is ContentProviderCrashed ->
-                        ErrorDetails(
+                        CacheErrorDetails(
                             exceptionForReport = ManuallyReportedException("Content provider crashed"),
-                            userFacingString = context.getString(R.string.import_error_copy_to_cache),
                             userFacingException = null,
                         )
                 }
 
-            data class ErrorDetails(
+            data class CacheErrorDetails(
                 val exceptionForReport: Exception,
-                val userFacingString: String,
                 val userFacingException: Exception?,
-            )
+            ) {
+                fun buildTitle(context: Context) = context.getString(R.string.import_error_copy_to_cache_title)
+
+                fun buildHumanReadableMessage(context: Context) =
+                    buildString {
+                        // "oaz: Cello error 2."
+                        if (userFacingException != null) {
+                            appendLine(userFacingException.message)
+                            appendLine()
+                        }
+
+                        // "This is often caused by the file provider, try these fixes:"
+                        val suggestedFixes =
+                            buildString {
+                                // build a bulleted list of suggested fixes
+                                for (line in context.resources.getStringArray(R.array.import_cache_error_resolutions)) {
+                                    appendLine("\u2022 $line")
+                                }
+                            }
+                        append(context.getString(R.string.import_error_copy_to_cache_explanation, suggestedFixes))
+                    }
+            }
         }
 
         companion object {
@@ -515,13 +540,18 @@ sealed class ImportResult {
     data class Failure(
         val humanReadableMessage: String,
         val exception: Exception? = null,
+        val title: String? = null,
     ) : ImportResult() {
         fun toDebugInfo(): String? {
             if (exception == null) return null
             return buildString {
-                appendLine(humanReadableMessage)
-                appendLine()
                 appendLine(exception.stackTraceToString())
+                if (title != null) {
+                    appendLine()
+                    appendLine(title)
+                }
+                appendLine()
+                appendLine(humanReadableMessage)
             }
         }
     }

AnkiDroid/src/main/res/values/02-strings.xml

@@ -160,7 +160,8 @@
     <string name="import_error_not_apkg_extension">Filename “%s” doesn’t have .apkg or .colpkg extension</string>
     <string name="import_error_load_imported_database">Anki Database (.anki2) replacements are not yet supported. Please see the manual for replacement instructions.</string>
     <string name="import_error_content_provider">The selected file couldn’t be imported automatically by AnkiDroid. Please see the user manual for how to manually import Anki files: \n%s</string>
-    <string name="import_error_copy_to_cache">Failed to cache file (possibly out of storage space)</string>
+    <string name="import_error_copy_to_cache_title">Failed to cache file</string>
+    <string name="import_error_copy_to_cache_explanation" comment="The substitution is a list of suggested fixes in bullet point form">This is often caused by a bug in the app you used to select the file. Please try the following fixes:\n\n%s</string>
     <string name="import_interrupted">Import interrupted: AnkiDroid was closed</string>
     <string name="export_ready_title">Export ready</string>
     <string name="export_send_no_handlers">No applications available to handle apkg. Saving…</string>

AnkiDroid/src/main/res/values/03-dialogs.xml

@@ -268,4 +268,18 @@ also changes the interval of the card"
     <string name="tts_error_dialog_reason_text">The text to speech engine <b>%1$s</b> does not support the following language: <b>%2$s</b></string>
     <string name="tts_error_dialog_change_button_text">Change engine</string>
     <string name="tts_error_dialog_supported_voices_button_text">Voice options</string>
+
+    <string-array name="import_cache_error_resolutions">
+        <item>@string/import_error_resolution_try_again</item>
+        <item>@string/import_error_resolution_free_up_space</item>
+        <item>@string/import_error_resolution_check_internet</item>
+        <item>@string/import_error_resolution_copy_to_device</item>
+        <item>@string/import_error_resolution_select_file</item>
+    </string-array>
+
+    <string name="import_error_resolution_try_again">Try re-importing the file</string>
+    <string name="import_error_resolution_free_up_space">Ensure there is sufficient free space on your device</string>
+    <string name="import_error_resolution_check_internet">Ensure you are connected to the internet</string>
+    <string name="import_error_resolution_copy_to_device">Copy the file to your device and try again</string>
+    <string name="import_error_resolution_select_file">Open the file using your device’s file browser app</string>
 </resources>