expo-app-blocker 0.1.47 → 0.1.49

package/README.md

@@ -235,6 +235,57 @@ No special setup required beyond what the config plugin handles automatically.
 | `ios.notification.attachIcon` | `boolean` | `true` | Whether to attach the shield icon as a notification image. Set to `false` to avoid the duplicate-icon look on iOS notification banners (the system app icon is always shown either way). |
 | `android.notificationTitle` | `string` | `"App Blocked"` | Notification title |
 | `android.notificationText` | `string` | `"{appName} is blocked."` | Notification text |
+| `android.overlay.icon` | `string` | — | Path to the brand icon shown above the title in the `SYSTEM_ALERT_WINDOW` overlay. Resolved relative to the project root. PNG with transparent background recommended. Build-time only — not adjustable at runtime. |
+
+### Android Overlay (runtime configurable via `setAndroidConfig`)
+
+The `SYSTEM_ALERT_WINDOW` overlay flashed on top of a blocked app is fully themeable. All fields below are optional — defaults preserve the previous "App Blocked" + grey-on-white look. Pass them as a single object to `ExpoAppBlocker.setAndroidConfig({ ... })` once at app boot:
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `overlayTitle` | `string` | `"App Blocked"` | Bold heading. `{appName}` is replaced with the localized app name (e.g. `"Instagram is blocked"`). |
+| `overlayText` | `string` | `"{appName} is blocked."` | Body line under the title. `{appName}` placeholder supported. |
+| `overlayBackgroundColor` | `string` (hex) | `"#FFFFFF"` | Solid background color for the full-screen overlay. |
+| `overlayTitleColor` | `string` (hex) | `"#111111"` | Title text color. |
+| `overlayTextColor` | `string` (hex) | `"#737373"` | Body text color. |
+| `overlayTitleFontSize` | `number` (sp) | `24` | Title font size. Android `sp` units — scales with system font setting. |
+| `overlayTextFontSize` | `number` (sp) | `16` | Body font size. |
+| `overlayTitleBold` | `boolean` | `true` | Render the title with `Typeface.BOLD`. Set to `false` for a regular weight. |
+| `overlayPadding` | `number` (dp) | `32` | Inner padding on all four sides of the overlay's `LinearLayout`. |
+| `overlayIconSize` | `number` (dp) | `96` | Square icon edge length. Only renders when `android.overlay.icon` was declared in the plugin config (build-time). |
+| `overlayIconBottomMargin` | `number` (dp) | `20` | Vertical gap between the icon and the title. |
+| `overlayTitleBottomMargin` | `number` (dp) | `12` | Vertical gap between the title and the body text. |
+| `overlayShowSpinner` | `boolean` | `false` | Render an indeterminate Material circular spinner below the body text — same shape RN's `<ActivityIndicator>` produces. Useful as a "launching…" cue during the brief gap between intercept and the deep-link landing. |
+| `overlaySpinnerSize` | `number` (dp) | `32` | Spinner edge length (square). Only used when `overlayShowSpinner` is true. |
+| `overlaySpinnerTopMargin` | `number` (dp) | `24` | Vertical gap between the body text and the spinner. |
+| `overlaySpinnerColor` | `string` (hex) | system primary | Tints the spinner. Useful to match your brand color. |
+| `notificationTitle` | `string` | `"App Blocked"` | Foreground-service notification title. |
+| `notificationText` | `string` | `"{appName} is blocked. Tap to manage."` | Foreground-service notification body. |
+
+Example (matches a Hebrew RTL app with brand colors + a logo above the title):
+
+```ts
+import * as ExpoAppBlocker from 'expo-app-blocker';
+
+ExpoAppBlocker.setAndroidConfig({
+  overlayTitle: 'האפליקציה חסומה',
+  overlayText: 'ענה על כמה שאלות כדי להשתמש בה',
+  overlayBackgroundColor: '#f6f6f6',
+  overlayTitleColor: '#111111',
+  overlayTextColor: '#888888',
+  overlayTitleFontSize: 26,
+  overlayTextFontSize: 16,
+  overlayTitleBold: true,
+  overlayPadding: 32,
+  overlayIconSize: 112,
+  overlayIconBottomMargin: 20,
+  overlayTitleBottomMargin: 12,
+  notificationTitle: 'גרנדמייזר',
+  notificationText: 'ענה על השאלות כדי לפתוח את האפליקציה',
+});
+```
+
+**Why two layers?** `android.overlay.icon` is build-time because Android resolves drawable resources by ID, which requires the bitmap to be packed into the APK. Everything else (text, colors, sizes) lives in `SharedPreferences` and can be updated by your JS at any time — no rebuild required.
 
 ### Blur Styles
 

package/android/src/main/java/expo/modules/appblocker/AppBlockerPrefs.kt

@@ -11,6 +11,17 @@ object AppBlockerPrefs {
   private const val KEY_OVERLAY_BG_COLOR = "overlay_bg_color"
   private const val KEY_OVERLAY_TITLE_COLOR = "overlay_title_color"
   private const val KEY_OVERLAY_TEXT_COLOR = "overlay_text_color"
+  private const val KEY_OVERLAY_TITLE_FONT_SIZE = "overlay_title_font_size"
+  private const val KEY_OVERLAY_TEXT_FONT_SIZE = "overlay_text_font_size"
+  private const val KEY_OVERLAY_TITLE_BOLD = "overlay_title_bold"
+  private const val KEY_OVERLAY_PADDING = "overlay_padding"
+  private const val KEY_OVERLAY_ICON_SIZE = "overlay_icon_size"
+  private const val KEY_OVERLAY_ICON_GAP = "overlay_icon_gap"
+  private const val KEY_OVERLAY_TITLE_GAP = "overlay_title_gap"
+  private const val KEY_OVERLAY_SHOW_SPINNER = "overlay_show_spinner"
+  private const val KEY_OVERLAY_SPINNER_SIZE = "overlay_spinner_size"
+  private const val KEY_OVERLAY_SPINNER_GAP = "overlay_spinner_gap"
+  private const val KEY_OVERLAY_SPINNER_COLOR = "overlay_spinner_color"
   private const val KEY_NOTIFICATION_TITLE = "notification_title"
   private const val KEY_NOTIFICATION_TEXT = "notification_text"
 
@@ -26,6 +37,13 @@ object AppBlockerPrefs {
       .apply()
   }
 
+  /**
+   * Push the overlay + notification config from JS into native prefs.
+   *
+   * Numeric `Float?` knobs (font sizes, paddings, icon size) are stored as
+   * floats and read back through [getOverlayFloat]. Pass `null` to keep the
+   * baked-in default; pass an explicit value (e.g. `28f`) to override.
+   */
   fun setAndroidConfig(
     context: Context,
     overlayTitle: String?,
@@ -33,18 +51,48 @@ object AppBlockerPrefs {
     overlayBackgroundColor: String?,
     overlayTitleColor: String?,
     overlayTextColor: String?,
+    overlayTitleFontSize: Float?,
+    overlayTextFontSize: Float?,
+    overlayTitleBold: Boolean?,
+    overlayPadding: Float?,
+    overlayIconSize: Float?,
+    overlayIconBottomMargin: Float?,
+    overlayTitleBottomMargin: Float?,
+    overlayShowSpinner: Boolean?,
+    overlaySpinnerSize: Float?,
+    overlaySpinnerTopMargin: Float?,
+    overlaySpinnerColor: String?,
     notificationTitle: String?,
     notificationText: String?,
   ) {
-    get(context).edit()
+    val editor = get(context).edit()
       .putString(KEY_OVERLAY_TITLE, overlayTitle)
       .putString(KEY_OVERLAY_TEXT, overlayText)
       .putString(KEY_OVERLAY_BG_COLOR, overlayBackgroundColor)
       .putString(KEY_OVERLAY_TITLE_COLOR, overlayTitleColor)
       .putString(KEY_OVERLAY_TEXT_COLOR, overlayTextColor)
+      .putString(KEY_OVERLAY_SPINNER_COLOR, overlaySpinnerColor)
       .putString(KEY_NOTIFICATION_TITLE, notificationTitle)
       .putString(KEY_NOTIFICATION_TEXT, notificationText)
-      .apply()
+    putNullableFloat(editor, KEY_OVERLAY_TITLE_FONT_SIZE, overlayTitleFontSize)
+    putNullableFloat(editor, KEY_OVERLAY_TEXT_FONT_SIZE, overlayTextFontSize)
+    putNullableFloat(editor, KEY_OVERLAY_PADDING, overlayPadding)
+    putNullableFloat(editor, KEY_OVERLAY_ICON_SIZE, overlayIconSize)
+    putNullableFloat(editor, KEY_OVERLAY_ICON_GAP, overlayIconBottomMargin)
+    putNullableFloat(editor, KEY_OVERLAY_TITLE_GAP, overlayTitleBottomMargin)
+    putNullableFloat(editor, KEY_OVERLAY_SPINNER_SIZE, overlaySpinnerSize)
+    putNullableFloat(editor, KEY_OVERLAY_SPINNER_GAP, overlaySpinnerTopMargin)
+    if (overlayTitleBold != null) {
+      editor.putBoolean(KEY_OVERLAY_TITLE_BOLD, overlayTitleBold)
+    } else {
+      editor.remove(KEY_OVERLAY_TITLE_BOLD)
+    }
+    if (overlayShowSpinner != null) {
+      editor.putBoolean(KEY_OVERLAY_SHOW_SPINNER, overlayShowSpinner)
+    } else {
+      editor.remove(KEY_OVERLAY_SHOW_SPINNER)
+    }
+    editor.apply()
   }
 
   fun getOverlayTitle(context: Context): String =
@@ -62,9 +110,49 @@ object AppBlockerPrefs {
   fun getOverlayTextColor(context: Context): String =
     get(context).getString(KEY_OVERLAY_TEXT_COLOR, null) ?: "#737373"
 
+  fun getOverlayTitleFontSize(context: Context): Float =
+    getOverlayFloat(context, KEY_OVERLAY_TITLE_FONT_SIZE, 24f)
+
+  fun getOverlayTextFontSize(context: Context): Float =
+    getOverlayFloat(context, KEY_OVERLAY_TEXT_FONT_SIZE, 16f)
+
+  fun getOverlayTitleBold(context: Context): Boolean =
+    get(context).getBoolean(KEY_OVERLAY_TITLE_BOLD, true)
+
+  fun getOverlayPadding(context: Context): Float =
+    getOverlayFloat(context, KEY_OVERLAY_PADDING, 32f)
+
+  fun getOverlayIconSize(context: Context): Float =
+    getOverlayFloat(context, KEY_OVERLAY_ICON_SIZE, 96f)
+
+  fun getOverlayIconBottomMargin(context: Context): Float =
+    getOverlayFloat(context, KEY_OVERLAY_ICON_GAP, 20f)
+
+  fun getOverlayTitleBottomMargin(context: Context): Float =
+    getOverlayFloat(context, KEY_OVERLAY_TITLE_GAP, 12f)
+
+  fun getOverlayShowSpinner(context: Context): Boolean =
+    get(context).getBoolean(KEY_OVERLAY_SHOW_SPINNER, false)
+
+  fun getOverlaySpinnerSize(context: Context): Float =
+    getOverlayFloat(context, KEY_OVERLAY_SPINNER_SIZE, 32f)
+
+  fun getOverlaySpinnerTopMargin(context: Context): Float =
+    getOverlayFloat(context, KEY_OVERLAY_SPINNER_GAP, 24f)
+
+  fun getOverlaySpinnerColor(context: Context): String? =
+    get(context).getString(KEY_OVERLAY_SPINNER_COLOR, null)
+
   fun getNotificationTitle(context: Context): String =
     get(context).getString(KEY_NOTIFICATION_TITLE, null) ?: "App Blocked"
 
   fun getNotificationText(context: Context): String =
     get(context).getString(KEY_NOTIFICATION_TEXT, null) ?: "{appName} is blocked. Tap to manage."
+
+  private fun putNullableFloat(editor: SharedPreferences.Editor, key: String, value: Float?) {
+    if (value != null) editor.putFloat(key, value) else editor.remove(key)
+  }
+
+  private fun getOverlayFloat(context: Context, key: String, fallback: Float): Float =
+    if (get(context).contains(key)) get(context).getFloat(key, fallback) else fallback
 }

package/android/src/main/java/expo/modules/appblocker/ExpoAppBlockerModule.kt

@@ -66,6 +66,10 @@ class ExpoAppBlockerModule : Module() {
     }
 
     Function("setAndroidConfig") { config: Map<String, Any?> ->
+      // JS sends numbers as Double over the bridge — coerce to Float so prefs
+      // keep a consistent type. Booleans are forwarded as-is.
+      fun numberOrNull(key: String): Float? = (config[key] as? Number)?.toFloat()
+
       AppBlockerPrefs.setAndroidConfig(
         context,
         overlayTitle = config["overlayTitle"] as? String,
@@ -73,6 +77,17 @@ class ExpoAppBlockerModule : Module() {
         overlayBackgroundColor = config["overlayBackgroundColor"] as? String,
         overlayTitleColor = config["overlayTitleColor"] as? String,
         overlayTextColor = config["overlayTextColor"] as? String,
+        overlayTitleFontSize = numberOrNull("overlayTitleFontSize"),
+        overlayTextFontSize = numberOrNull("overlayTextFontSize"),
+        overlayTitleBold = config["overlayTitleBold"] as? Boolean,
+        overlayPadding = numberOrNull("overlayPadding"),
+        overlayIconSize = numberOrNull("overlayIconSize"),
+        overlayIconBottomMargin = numberOrNull("overlayIconBottomMargin"),
+        overlayTitleBottomMargin = numberOrNull("overlayTitleBottomMargin"),
+        overlayShowSpinner = config["overlayShowSpinner"] as? Boolean,
+        overlaySpinnerSize = numberOrNull("overlaySpinnerSize"),
+        overlaySpinnerTopMargin = numberOrNull("overlaySpinnerTopMargin"),
+        overlaySpinnerColor = config["overlaySpinnerColor"] as? String,
         notificationTitle = config["notificationTitle"] as? String,
         notificationText = config["notificationText"] as? String,
       )

package/android/src/main/java/expo/modules/appblocker/OverlayManager.kt

@@ -15,6 +15,7 @@ import android.view.View
 import android.view.WindowManager
 import android.widget.ImageView
 import android.widget.LinearLayout
+import android.widget.ProgressBar
 import android.widget.TextView
 
 class OverlayManager(private val context: Context) {
@@ -117,7 +118,7 @@ class OverlayManager(private val context: Context) {
 
   private fun buildOverlayView(appName: String): View {
     val density = context.resources.displayMetrics.density
-    fun dp(value: Int) = (value * density).toInt()
+    fun dp(value: Float) = (value * density).toInt()
 
     val overlayTitle = AppBlockerPrefs.getOverlayTitle(context)
       .replace("{appName}", appName)
@@ -135,12 +136,19 @@ class OverlayManager(private val context: Context) {
       AppBlockerPrefs.getOverlayTextColor(context),
       Color.parseColor("#737373"),
     )
+    val titleFontSize = AppBlockerPrefs.getOverlayTitleFontSize(context)
+    val textFontSize = AppBlockerPrefs.getOverlayTextFontSize(context)
+    val titleBold = AppBlockerPrefs.getOverlayTitleBold(context)
+    val padding = AppBlockerPrefs.getOverlayPadding(context)
+    val iconSize = AppBlockerPrefs.getOverlayIconSize(context)
+    val iconGap = AppBlockerPrefs.getOverlayIconBottomMargin(context)
+    val titleGap = AppBlockerPrefs.getOverlayTitleBottomMargin(context)
 
     return LinearLayout(context).apply {
       orientation = LinearLayout.VERTICAL
       gravity = Gravity.CENTER
       setBackgroundColor(backgroundColor)
-      setPadding(dp(32), dp(32), dp(32), dp(32))
+      setPadding(dp(padding), dp(padding), dp(padding), dp(padding))
 
       // Optional brand icon — drawable named `expo_app_blocker_overlay_icon`
       // is copied by the config plugin from `pluginConfig.android.overlay.icon`.
@@ -154,9 +162,9 @@ class OverlayManager(private val context: Context) {
         addView(ImageView(context).apply {
           val bitmap = BitmapFactory.decodeResource(context.resources, iconResId)
           if (bitmap != null) setImageBitmap(bitmap)
-          val size = dp(96)
+          val size = dp(iconSize)
           layoutParams = LinearLayout.LayoutParams(size, size).apply {
-            bottomMargin = dp(20)
+            bottomMargin = dp(iconGap)
           }
         })
       }
@@ -164,18 +172,37 @@ class OverlayManager(private val context: Context) {
       addView(TextView(context).apply {
         text = overlayTitle
         setTextColor(titleColor)
-        setTextSize(TypedValue.COMPLEX_UNIT_SP, 24f)
-        setTypeface(typeface, Typeface.BOLD)
+        setTextSize(TypedValue.COMPLEX_UNIT_SP, titleFontSize)
+        if (titleBold) setTypeface(typeface, Typeface.BOLD)
         gravity = Gravity.CENTER
-        setPadding(0, 0, 0, dp(12))
+        setPadding(0, 0, 0, dp(titleGap))
       })
 
       addView(TextView(context).apply {
         text = overlayText
         setTextColor(textColor)
-        setTextSize(TypedValue.COMPLEX_UNIT_SP, 16f)
+        setTextSize(TypedValue.COMPLEX_UNIT_SP, textFontSize)
         gravity = Gravity.CENTER
       })
+
+      // Optional indeterminate spinner — gives the user a visual cue that
+      // the app is launching during the ~150–300ms gap between intercept
+      // detection and the deep-link landing.
+      if (AppBlockerPrefs.getOverlayShowSpinner(context)) {
+        val spinnerSize = dp(AppBlockerPrefs.getOverlaySpinnerSize(context))
+        val spinnerGap = dp(AppBlockerPrefs.getOverlaySpinnerTopMargin(context))
+        addView(ProgressBar(context).apply {
+          isIndeterminate = true
+          val tint = AppBlockerPrefs.getOverlaySpinnerColor(context)
+          if (tint != null) {
+            val parsed = parseColorOrNull(tint)
+            if (parsed != null) indeterminateTintList = android.content.res.ColorStateList.valueOf(parsed)
+          }
+          layoutParams = LinearLayout.LayoutParams(spinnerSize, spinnerSize).apply {
+            topMargin = spinnerGap
+          }
+        })
+      }
     }
   }
 
@@ -185,6 +212,12 @@ class OverlayManager(private val context: Context) {
     fallback
   }
 
+  private fun parseColorOrNull(hex: String): Int? = try {
+    Color.parseColor(hex)
+  } catch (_: IllegalArgumentException) {
+    null
+  }
+
   private fun buildLayoutParams(): WindowManager.LayoutParams {
     @Suppress("DEPRECATION")
     val type = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "expo-app-blocker",
-  "version": "0.1.47",
+  "version": "0.1.49",
   "description": "Expo module for cross-platform app blocking. Android: UsageStatsManager + Overlay. iOS: Screen Time API (FamilyControls + ManagedSettings + DeviceActivity).",
   "main": "src/index.ts",
   "types": "src/index.ts",

package/src/ExpoAppBlocker.types.ts

@@ -159,6 +159,28 @@ export interface AndroidConfig {
   overlayTitleColor?: string;
   /** Hex color (e.g. "#737373") for the overlay body text. Default: "#737373". */
   overlayTextColor?: string;
+  /** Title font size in sp. Default: 24. */
+  overlayTitleFontSize?: number;
+  /** Body font size in sp. Default: 16. */
+  overlayTextFontSize?: number;
+  /** Render the title in bold. Default: true. */
+  overlayTitleBold?: boolean;
+  /** Inner padding (all sides) in dp. Default: 32. */
+  overlayPadding?: number;
+  /** Icon edge length in dp (square). Default: 96. Only used when an overlay icon is configured via the plugin. */
+  overlayIconSize?: number;
+  /** Vertical gap (dp) between the icon and the title. Default: 20. */
+  overlayIconBottomMargin?: number;
+  /** Vertical gap (dp) between the title and the body text. Default: 12. */
+  overlayTitleBottomMargin?: number;
+  /** Show an indeterminate circular spinner under the body text. Useful as a "launching…" cue during the brief gap between intercept and the deep-link landing. Default: false. */
+  overlayShowSpinner?: boolean;
+  /** Spinner edge length in dp (square). Default: 32. */
+  overlaySpinnerSize?: number;
+  /** Vertical gap (dp) between the body text and the spinner. Default: 24. */
+  overlaySpinnerTopMargin?: number;
+  /** Hex color (e.g. "#7cb518") tinting the spinner. Default: system primary. */
+  overlaySpinnerColor?: string;
   /** Notification title when app is blocked. Use {appName} as placeholder. Default: "App Blocked" */
   notificationTitle?: string;
   /** Notification text when app is blocked. Use {appName} as placeholder. */