fix(ui): show the won't-ask-again hints as a snackbar, not a toast

The App info and Default apps hints were toasts, which Android 12 and
later stop at two lines, and the settings page opened over them at once,
so the end of the instruction was never readable on a narrow phone.

rememberPermissionRequest and rememberRoleRequest now post the hint to a
SnackbarHostState from LocalPermissionHints (MainActivity provides one
for every tab, onboarding passes its own) with an Open App info or Open
Default apps action, and the page opens only when that is tapped.
PermissionHintsHost puts a hint's action on its own line so a large font
can't squeeze the text into a column beside it. With no host, the page
opens straight away as before.

New PermissionHintTest checks both hints at 2x font on a 360dp screen
under native graphics (no overflow, more than two lines, inside the
screen), that no toast shows and nothing opens until the action is
tapped, and the no-host fallback. A control run with the old toast and
open put back fails both hint tests. No existing test changed.

Author: SysAdminDoc

CHANGELOG.md

@@ -4,6 +4,7 @@ All notable changes to CallShield will be documented in this file.
 
 ## Unreleased
 
+- When Android stops asking for a permission or a default app role, CallShield's note about where to turn it on now shows in full at the bottom of the screen, with an Open App info or Open Default apps button. It used to be a toast that Android 12 and later cut off after two lines, and the settings page opened on top of it before you could read the rest.
 - A single Not spam vote no longer keeps a number off the community watch list for 90 days. Reports from people on later days count again, so a number that starts getting reported after someone vouched for it can still show the warning. Reports from the day of the vote, or earlier, still don't count.
 - A Report or Not spam result that came in just as the previous message closed, in Lookup or on a number's screen, could be skipped without showing. It shows now.
 - When GitHub's rate limit stops a report, the report service now passes on how long GitHub asked it to wait, instead of always saying a minute. When GitHub refuses the service's access token, it answers that it's unavailable rather than rate limited, and the app keeps the report and tries again later. This takes effect when the report Worker is next deployed.

README.md

@@ -12,7 +12,7 @@
 <p align="center">
   <a href="https://github.com/SysAdminDoc/CallShield/releases/latest"><img src="https://img.shields.io/github/v/release/SysAdminDoc/CallShield?style=flat-square&color=a6e3a1" alt="Release"></a>
   <img src="https://img.shields.io/badge/Spam%20Numbers-51%2C403-f38ba8?style=flat-square" alt="51,403 Numbers">
-  <img src="https://img.shields.io/badge/JVM%20unit%20tests-2051-94e2d5?style=flat-square" alt="2051 JVM unit tests">
+  <img src="https://img.shields.io/badge/JVM%20unit%20tests-2054-94e2d5?style=flat-square" alt="2054 JVM unit tests">
   <img src="https://img.shields.io/badge/Android-10%2B-89b4fa?style=flat-square" alt="Android 10+">
   <img src="https://img.shields.io/badge/License-MIT-cba6f7?style=flat-square" alt="MIT License">
   <img src="https://img.shields.io/badge/API%20Keys-None-fab387?style=flat-square" alt="No required API keys">
@@ -592,12 +592,12 @@ RELEASE_KEY_PASSWORD=...
 ## Testing
 
 ```bash
-./gradlew testDebugUnitTest   # 2051 tests
+./gradlew testDebugUnitTest   # 2054 tests
 ./gradlew connectedDebugAndroidTest -Pandroid.testInstrumentationRunnerArguments.class=com.sysadmindoc.callshield.platform.TargetSdkBehaviorSmokeTest
 ./gradlew verifyPipelineTests # Cloudflare Worker (node) + data-pipeline and translation checks (python)
 ```
 
-The suite is **2051 total JVM unit tests**, run with Robolectric wherever a screen, a service or the database is involved.
+The suite is **2054 total JVM unit tests**, run with Robolectric wherever a screen, a service or the database is involved.
 
 Two GitHub workflows run without building the app. **Validation** runs the Worker and
 pipeline suites on every push except report-only ones (`run-pipeline-tests.ps1 -CorrectnessOnly`),
@@ -634,8 +634,8 @@ language in [issue #7](https://github.com/SysAdminDoc/CallShield/issues/7).
 | Community API | Cloudflare Workers |
 | URL Safety | Local spam-domain data, with optional PhishTank and OpenPhish |
 | Verification | Local Gradle, lint, and release-artifact checks |
-| Tests | 2051 JVM unit tests (JUnit) |
-| Strings | 1792 string resources and 49 plural groups (translation-ready) |
+| Tests | 2054 JVM unit tests (JUnit) |
+| Strings | 1794 string resources and 49 plural groups (translation-ready) |
 | Accessibility | 100+ content descriptions, 48dp touch targets |
 | Min SDK | 29 (Android 10) |
 | Target SDK | 36 |

app/src/main/java/com/sysadmindoc/callshield/ui/ContactsOnlyPaused.kt

@@ -28,7 +28,7 @@ import com.sysadmindoc.callshield.ui.theme.ShapeMd
 /**
  * Asks for Contacts access and calls [onResult] once Android answers. Android
  * stops showing its dialog after two refusals, so a refusal that leaves no
- * dialog for next time opens App info instead, where the permission lives.
+ * dialog for next time points to App info instead, where the permission lives.
  */
 @Composable
 fun rememberAllowContacts(onResult: () -> Unit = {}): () -> Unit {

app/src/main/java/com/sysadmindoc/callshield/ui/MainActivity.kt

@@ -182,12 +182,17 @@ fun CallShieldRoot(
 
             else -> {
                 rootStateHolder.SaveableStateProvider(ROOT_STATE_APP) {
-                    CallShieldApp(
-                        viewModel = viewModel,
-                        startTab = initialTab,
-                        tabRequestId = launchRequest.id.takeIf { launchRequest.shortcutAction != null },
-                        blockedLogRequestId = launchRequest.blockedLogRequestId(),
-                    )
+                    // Every tab's App info and Default apps hints show here,
+                    // above the navigation bar (CallShieldApp's snackbar slot).
+                    val permissionHints = remember { SnackbarHostState() }
+                    CompositionLocalProvider(LocalPermissionHints provides permissionHints) {
+                        CallShieldApp(
+                            viewModel = viewModel,
+                            startTab = initialTab,
+                            tabRequestId = launchRequest.id.takeIf { launchRequest.shortcutAction != null },
+                            blockedLogRequestId = launchRequest.blockedLogRequestId(),
+                        )
+                    }
                 }
             }
         }
@@ -353,6 +358,7 @@ fun CallShieldApp(
                 }
             }
         },
+        snackbarHost = { LocalPermissionHints.current?.let { PermissionHintsHost(it) } },
         containerColor = Black,
     ) { padding ->
         Box(modifier = Modifier.padding(padding)) {

app/src/main/java/com/sysadmindoc/callshield/ui/PermissionRecovery.kt

@@ -7,18 +7,80 @@ import android.content.Intent
 import android.net.Uri
 import android.os.SystemClock
 import android.provider.Settings
-import android.widget.Toast
 import androidx.activity.compose.rememberLauncherForActivityResult
 import androidx.activity.result.contract.ActivityResultContracts
 import androidx.annotation.StringRes
+import androidx.compose.material3.Snackbar
+import androidx.compose.material3.SnackbarDuration
+import androidx.compose.material3.SnackbarHost
+import androidx.compose.material3.SnackbarHostState
+import androidx.compose.material3.SnackbarResult
+import androidx.compose.material3.SnackbarVisuals
 import androidx.compose.runtime.Composable
 import androidx.compose.runtime.getValue
 import androidx.compose.runtime.mutableLongStateOf
 import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.rememberCoroutineScope
 import androidx.compose.runtime.saveable.rememberSaveable
 import androidx.compose.runtime.setValue
+import androidx.compose.runtime.staticCompositionLocalOf
+import androidx.compose.ui.Modifier
 import androidx.compose.ui.platform.LocalContext
+import androidx.compose.ui.res.stringResource
+import com.sysadmindoc.callshield.R
 import com.sysadmindoc.callshield.util.startActivitySafely
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.launch
+
+/**
+ * Where [rememberPermissionRequest] and [rememberRoleRequest] show their App
+ * info and Default apps hints. A snackbar holds the whole hint; the toast they
+ * used to show stops at two lines on Android 12 and later, and the settings
+ * page it opened covered the rest. With no host the page opens straight away.
+ */
+val LocalPermissionHints = staticCompositionLocalOf<SnackbarHostState?> { null }
+
+private class SettingsHintVisuals(
+    override val message: String,
+    override val actionLabel: String,
+) : SnackbarVisuals {
+    override val withDismissAction get() = false
+    override val duration get() = SnackbarDuration.Long
+}
+
+/**
+ * Shows [hints], putting a settings hint's action on its own line so a large
+ * font can't squeeze the hint into a narrow column beside it.
+ */
+@Composable
+fun PermissionHintsHost(
+    hints: SnackbarHostState,
+    modifier: Modifier = Modifier,
+) {
+    SnackbarHost(hints, modifier) { Snackbar(it, actionOnNewLine = it.visuals is SettingsHintVisuals) }
+}
+
+/**
+ * Shows [hint] in [hints] with an [actionLabel] action that opens [intent],
+ * replacing any message already there. Without [hints] it opens [intent] now.
+ */
+private fun CoroutineScope.showSettingsHint(
+    hints: SnackbarHostState?,
+    hint: String,
+    actionLabel: String,
+    context: Context,
+    intent: Intent,
+) {
+    if (hints == null) {
+        context.startActivitySafely(intent)
+        return
+    }
+    launch {
+        hints.currentSnackbarData?.dismiss()
+        val result = hints.showSnackbar(SettingsHintVisuals(hint, actionLabel))
+        if (result == SnackbarResult.ActionPerformed) context.startActivitySafely(intent)
+    }
+}
 
 /**
  * True when a permission request came back with something still refused and
@@ -56,18 +118,22 @@ internal fun refusalsThatCount(
 /**
  * Returns a function that asks for the permissions it's given and calls
  * [onResult] with Android's answer. When the answer leaves no dialog for next
- * time, it calls [onOpensAppInfo], shows [appInfoHint] and opens App info,
- * where the permission lives. Only refusals of [appInfoFor] count when it's
- * given.
+ * time, it calls [onAppInfoHint] and shows [appInfoHint] in [hints] with an
+ * App info action, since App info is where the permission lives now. Only
+ * refusals of [appInfoFor] count when it's given.
  */
 @Composable
 fun rememberPermissionRequest(
     @StringRes appInfoHint: Int,
     appInfoFor: Collection<String>? = null,
-    onOpensAppInfo: () -> Unit = {},
+    hints: SnackbarHostState? = LocalPermissionHints.current,
+    onAppInfoHint: () -> Unit = {},
     onResult: (Map<String, Boolean>) -> Unit = {},
 ): (List<String>) -> Unit {
     val context = LocalContext.current
+    val scope = rememberCoroutineScope()
+    val hint = stringResource(appInfoHint)
+    val actionLabel = stringResource(R.string.permission_hint_app_info)
     // Saved, since the prompt can outlive the activity (a rotation or a
     // reclaimed process), and the answer is read against them.
     var launchedAt by rememberSaveable { mutableLongStateOf(0L) }
@@ -79,9 +145,12 @@ fun rememberPermissionRequest(
             val stillDenied = refusalsThatCount(grants, appInfoFor)
             val promptShown = SystemClock.elapsedRealtime() - launchedAt >= PROMPT_MIN_MILLIS
             if (opensAppInfoAfterRequest(stillDenied, promptShown, refusedBefore, activity::shouldShowRequestPermissionRationale)) {
-                onOpensAppInfo()
-                Toast.makeText(context, appInfoHint, Toast.LENGTH_LONG).show()
-                context.startActivitySafely(
+                onAppInfoHint()
+                scope.showSettingsHint(
+                    hints,
+                    hint,
+                    actionLabel,
+                    context,
                     Intent(Settings.ACTION_APPLICATION_DETAILS_SETTINGS, Uri.fromParts("package", context.packageName, null)),
                 )
             }
@@ -108,31 +177,35 @@ internal fun opensDefaultAppsAfterRoleRequest(
 /** What a role request came back with. */
 data class RoleRequestResult(
     val held: Boolean,
-    /** Android showed no prompt, so the hint was shown and Default apps opened. */
-    val opensDefaultApps: Boolean,
+    /** Android showed no prompt, so the Default apps hint was shown. */
+    val defaultAppsHintShown: Boolean,
 )
 
 /**
  * Returns a function that starts the role request intent it's given and calls
  * [onResult] with the answer. When the request comes straight back refused,
- * it shows [defaultAppsHint] and opens Default apps, where the role lives.
+ * it shows [defaultAppsHint] in [hints] with a Default apps action, since
+ * Default apps is where the role lives now.
  */
 @Composable
 fun rememberRoleRequest(
     @StringRes defaultAppsHint: Int,
     roleHeld: () -> Boolean,
+    hints: SnackbarHostState? = LocalPermissionHints.current,
     onResult: (RoleRequestResult) -> Unit = {},
 ): (Intent) -> Unit {
     val context = LocalContext.current
+    val scope = rememberCoroutineScope()
+    val hint = stringResource(defaultAppsHint)
+    val actionLabel = stringResource(R.string.permission_hint_default_apps)
     var launchedAt by rememberSaveable { mutableLongStateOf(0L) }
     val launcher =
         rememberLauncherForActivityResult(ActivityResultContracts.StartActivityForResult()) {
             val held = roleHeld()
-            val opensDefaultApps = opensDefaultAppsAfterRoleRequest(held, SystemClock.elapsedRealtime() - launchedAt)
-            onResult(RoleRequestResult(held, opensDefaultApps))
-            if (opensDefaultApps) {
-                Toast.makeText(context, defaultAppsHint, Toast.LENGTH_LONG).show()
-                context.startActivitySafely(Intent(Settings.ACTION_MANAGE_DEFAULT_APPS_SETTINGS))
+            val hintShown = opensDefaultAppsAfterRoleRequest(held, SystemClock.elapsedRealtime() - launchedAt)
+            onResult(RoleRequestResult(held, hintShown))
+            if (hintShown) {
+                scope.showSettingsHint(hints, hint, actionLabel, context, Intent(Settings.ACTION_MANAGE_DEFAULT_APPS_SETTINGS))
             }
         }
     return { intent ->

app/src/main/java/com/sysadmindoc/callshield/ui/screens/main/DashboardScreen.kt

@@ -339,7 +339,7 @@ fun DashboardScreen(
     // Settings, which lands on Basic, and Basic has no overlay control at all.
     // Review permissions still opens Settings, where each missing item has a
     // Grant or Enable button.
-    // These open App info, or Default apps for the role, with a hint once
+    // These point to App info, or Default apps for the role, with a hint once
     // Android has stopped showing its dialog, since the request then comes
     // back at once with nothing on screen.
     val screeningRoleRequest =

app/src/main/java/com/sysadmindoc/callshield/ui/screens/onboarding/OnboardingScreen.kt

@@ -50,7 +50,6 @@ import androidx.compose.material3.Icon
 import androidx.compose.material3.MaterialTheme
 import androidx.compose.material3.RadioButton
 import androidx.compose.material3.SnackbarDuration
-import androidx.compose.material3.SnackbarHost
 import androidx.compose.material3.SnackbarHostState
 import androidx.compose.material3.SnackbarResult
 import androidx.compose.material3.Surface
@@ -95,6 +94,7 @@ import com.sysadmindoc.callshield.permissions.InstallSource
 import com.sysadmindoc.callshield.permissions.InstallSourceKind
 import com.sysadmindoc.callshield.service.FeedTrustNotice
 import com.sysadmindoc.callshield.ui.MainViewModel
+import com.sysadmindoc.callshield.ui.PermissionHintsHost
 import com.sysadmindoc.callshield.ui.rememberPermissionRequest
 import com.sysadmindoc.callshield.ui.rememberRoleRequest
 import com.sysadmindoc.callshield.ui.theme.CatBlue
@@ -172,25 +172,30 @@ fun OnboardingScreen(
     }
 
     // Android answers a request it won't show again at once, with nothing on
-    // screen, so even the first tap after two refusals in an earlier run opens
-    // App info, and the button keeps pointing there.
+    // screen, so even the first tap after two refusals in an earlier run gets
+    // the App info hint, and the button points there from then on.
     val runtimePermissionRequest =
         rememberPermissionRequest(
             R.string.permission_core_in_app_info,
             appInfoFor = CallShieldPermissions.corePermissions,
-            onOpensAppInfo = { runtimePermissionsBlocked = true },
+            hints = snackbarHostState,
+            onAppInfoHint = { runtimePermissionsBlocked = true },
         ) {
             refreshReadiness()
             runtimePermissionsBlocked = false
         }
     val notificationPermissionRequest =
-        rememberPermissionRequest(R.string.permission_notifications_in_app_info) {
+        rememberPermissionRequest(R.string.permission_notifications_in_app_info, hints = snackbarHostState) {
             refreshReadiness()
         }
-    // Opens Default apps with a hint once Android has stopped showing the role
-    // prompt, since the request then comes back at once with nothing on screen.
+    // Points to Default apps with a hint once Android has stopped showing the
+    // role prompt, since the request then comes back at once with nothing on screen.
     val screeningRequest =
-        rememberRoleRequest(R.string.role_call_screening_in_default_apps, roleHeld = { CallShieldPermissions.hasCallScreeningRole(roleManager) }) {
+        rememberRoleRequest(
+            R.string.role_call_screening_in_default_apps,
+            roleHeld = { CallShieldPermissions.hasCallScreeningRole(roleManager) },
+            hints = snackbarHostState,
+        ) {
             refreshReadiness()
         }
 
@@ -490,7 +495,7 @@ internal fun OnboardingScreenContent(
             SetupHint.ReinstallOverThisCopy -> ReinstallHint(installerLabel = installerLabel.orEmpty(), onOpenReleases = onOpenReleases)
             null -> Unit
         }
-        SnackbarHost(snackbarHostState)
+        PermissionHintsHost(snackbarHostState)
         Spacer(Modifier.height(8.dp))
         if (currentPage > 0) {
             TextButton(

app/src/main/java/com/sysadmindoc/callshield/ui/screens/settings/SettingsScreen.kt

@@ -168,7 +168,7 @@ fun SettingsScreen(viewModel: MainViewModel) {
     val setupProgress = requiredSetupProgress(corePermissionsGranted, screenerReadyForCurrentMode)
     val setupReadyCount = setupProgress.done
     val setupTotal = setupProgress.total
-    // Both open App info with a hint once Android has stopped showing its
+    // Both point to App info with a hint once Android has stopped showing its
     // dialog, since the request then returns at once with nothing on screen.
     val corePermissionRequest =
         rememberPermissionRequest(R.string.permission_core_in_app_info) {
@@ -183,7 +183,7 @@ fun SettingsScreen(viewModel: MainViewModel) {
         rememberPermissionRequest(R.string.permission_notifications_in_app_info) {
             notificationsGranted = CallShieldPermissions.hasNotificationPermission(context)
         }
-    // Both open Default apps with a hint once Android has stopped showing the
+    // Both point to Default apps with a hint once Android has stopped showing the
     // role prompt, since the request then comes back at once with nothing on screen.
     val screeningRequest =
         rememberRoleRequest(R.string.role_call_screening_in_default_apps, roleHeld = { CallShieldPermissions.hasCallScreeningRole(roleManager) }) {
@@ -194,7 +194,7 @@ fun SettingsScreen(viewModel: MainViewModel) {
             redirectionRoleHeld = it.held
             if (it.held) {
                 viewModel.setOutgoingCallHold(true)
-            } else if (!it.opensDefaultApps) {
+            } else if (!it.defaultAppsHintShown) {
                 Toast.makeText(context, callHoldNotGranted, Toast.LENGTH_SHORT).show()
             }
         }

app/src/main/res/values-zh-rCN/strings.xml

@@ -485,6 +485,8 @@
     <string name="permission_sms_in_app_info">Android 不会再询问。请在应用信息的“权限”中开启“短信”。</string>
     <string name="permission_phone_in_app_info">Android 不会再询问。请在应用信息的“权限”中开启“电话”和“通话记录”。</string>
     <string name="permission_notifications_in_app_info">Android 不会再询问。请在应用信息中开启“通知”。</string>
+    <string name="permission_hint_app_info">打开应用信息</string>
+    <string name="permission_hint_default_apps">打开默认应用</string>
     <string name="settings_outgoing_risk_warning">拨出高风险电话前提醒</string>
     <string name="settings_outgoing_risk_warning_desc">对垃圾号码库中精确匹配的号码显示本地警告</string>
     <string name="settings_outgoing_risk_warning_overlay_required">允许悬浮窗权限以查看拨出提醒。</string>