react-native-alarms 0.0.6 → 0.0.7

package/README.md

@@ -1,6 +1,11 @@
 # React Native Alarms 🔔
 
-A powerful, cross-platform alarm management library for React Native. Schedule, manage, and control alarms on both Android and iOS with a unified API.
+A cross-platform native scheduling, reminder, and wake-up system for React Native. Schedule time-sensitive events on Android and iOS, deliver reminders, and present a registered custom React Native screen when a scheduled event fires—using one unified API.
+
+Although it can power a traditional alarm clock, react-native-alarms is also useful for exact-time reminders, scheduled check-ins, custom lock-screen experiences, and time-based app workflows. Build the experience around your own UI and event data instead of being limited to a standard alarm screen.
+
+> **Platform note:** The operating system controls background delivery and screen presentation. Exact timing, full-screen presentation, and behavior when an app is terminated depend on platform version, permissions, device settings, and the native scheduling mechanism. This library does not provide unrestricted background JavaScript execution.
+
 
 [![npm version](https://badge.fury.io/js/react-native-alarms.svg)](https://badge.fury.io/js/react-native-alarms)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
@@ -65,6 +70,44 @@ AppRegistry.registerComponent('AlarmRing', () => AlarmRingScreen);
 Call `Alarm.stopAlarm(alarmId)` or `Alarm.snoozeAlarm(alarmId, minutes)` from its
 buttons; the screen closes itself.
 
+#### Custom presentation component
+
+You can register **multiple** ring screens and choose which one fires per alarm using the `presentation` field in `AlarmConfig`:
+
+```js
+// index.js
+import { AppRegistry } from 'react-native';
+import { AlarmRingScreen } from './src/AlarmRingScreen';
+import { ReminderScreen } from './src/ReminderScreen';
+
+AppRegistry.registerComponent('AlarmRing', () => AlarmRingScreen);   // default
+AppRegistry.registerComponent('Reminder', () => ReminderScreen);     // custom
+```
+
+```ts
+import { AlarmRegistry, AlarmService } from 'react-native-alarms/service';
+
+// 1. Map your key to the registered component name
+AlarmRegistry.register('reminder', 'Reminder');
+
+// 2. Pass it when scheduling
+await AlarmService.scheduleAlarm({
+  timestamp: Date.now() + 60_000,
+  title: 'Standup',
+  presentation: {
+    type: 'reminder',           // resolves to the 'Reminder' component
+    props: { color: '#6200EE' } // forwarded to the screen as componentProps
+  },
+});
+```
+
+The native layer maps `presentation` to two internal fields:
+
+| Internal field | Type | Default | Description |
+|---|---|---|---|
+| `componentName` | `string` | `"AlarmRing"` | Registered `AppRegistry` component name shown when the alarm rings. |
+| `componentProps` / `componentPropsJSON` | `object` / `string` | `{}` | Key-value props forwarded to the ring screen on **both platforms**. On Android they arrive as top-level bundle extras and a nested `componentProps` map; on iOS as a parsed `[String: Any]` dictionary. |
+
 ### Direct module access
 
 ```ts
@@ -179,9 +222,28 @@ type AlarmConfig = {
   snoozeMinutes?: number;     // Snooze duration in minutes
   repeat?: AlarmRepeat;       // Repeat configuration
   data?: string;              // Custom JSON string payload
+  presentation?: AlarmPresentation; // Custom ring screen & props
+};
+
+type AlarmPresentation = {
+  /** Registered presentation type (key passed to AlarmRegistry.register). */
+  type?: string;
+  /**
+   * Props forwarded to the ring screen component.
+   * Available as `componentProps` on both Android and iOS.
+   */
+  props?: Record<string, unknown>;
 };
 ```
 
+> **How the native layer stores these:** `AlarmConfig.presentation` is resolved by `AlarmService` before being handed off to the native module. The resulting fields stored in the native `AlarmData` model are:
+>
+> | Field | Type | Default | Description |
+> |---|---|---|---|
+> | `componentName` | `string` | `"AlarmRing"` | The `AppRegistry` name of the component shown at ring time. Derived from `AlarmRegistry.resolve(presentation.type)`. |
+> | `componentProps` | `object` | `{}` | Parsed props object (from `presentation.props`). Available on both platforms at ring time as `componentProps`. |
+> | `componentPropsJSON` | `string` | `"{}"` | JSON-serialised representation of `componentProps`, persisted alongside the alarm so props survive a device reboot. |
+
 #### `AlarmRepeat`
 Repeat configuration for recurring alarms.
 
@@ -433,27 +495,99 @@ For issues and questions, please visit:
 
 The library supports completely custom alarm UI screens with custom data payloads.
 
-### Basic Custom Screen Example
+### Using `componentName` and `componentProps`
+
+The `presentation` field lets you choose **which registered component** is displayed and pass **arbitrary props** directly to it — without encoding everything inside a JSON `data` string.
+
+#### 1. Register your screens
+
+```js
+// index.js
+import { AppRegistry } from 'react-native';
+import { AlarmRingScreen }   from './src/AlarmRingScreen';
+import { MeetingAlarmScreen } from './src/MeetingAlarmScreen';
+
+AppRegistry.registerComponent('AlarmRing',    () => AlarmRingScreen);    // default fallback
+AppRegistry.registerComponent('MeetingAlarm', () => MeetingAlarmScreen); // custom
+```
+
+#### 2. Map a key to the component name
+
+```ts
+import { AlarmRegistry } from 'react-native-alarms';
+
+AlarmRegistry.register('meeting', 'MeetingAlarm');
+```
+
+#### 3. Schedule with `presentation`
 
 ```typescript
-import { NativeModules } from 'react-native';
 import { AlarmService } from 'react-native-alarms/service';
 
-export function MyCustomAlarmScreen({ alarmId, title, data }) {
-  const customData = JSON.parse(data || '{}');
+await AlarmService.scheduleAlarm({
+  timestamp: Date.now() + 5 * 60 * 1000,
+  title: 'Team standup',
+  presentation: {
+    type: 'meeting',                    // resolves to 'MeetingAlarm'
+    props: {
+      roomName: 'Zoom Room A',
+      meetingUrl: 'https://zoom.us/j/123',
+      accentColor: '#6200EE',
+    },
+  },
+});
+```
+
+#### 4. Receive `componentProps` in your screen
+
+The props passed via `presentation.props` are forwarded to the ring screen on both platforms:
+
+```typescript
+// MeetingAlarmScreen.tsx
+type Props = {
+  alarmId: string;
+  title: string;
+  snoozeEnabled: boolean;
+  snoozeMinutes: number;
+  data?: string;
+  // componentProps fields arrive as top-level props:
+  roomName?: string;
+  meetingUrl?: string;
+  accentColor?: string;
+};
 
+export function MeetingAlarmScreen({
+  alarmId,
+  title,
+  snoozeEnabled,
+  snoozeMinutes,
+  roomName,
+  meetingUrl,
+  accentColor = '#007AFF',
+}: Props) {
   return (
-    <View style={{ backgroundColor: customData.color }}>
-      <Text>{title}</Text>
+    <View style={{ flex: 1, backgroundColor: accentColor }}>
+      <Text style={{ fontSize: 28, color: '#fff' }}>{title}</Text>
+      <Text style={{ color: '#fff' }}>{roomName}</Text>
+
+      {snoozeEnabled && (
+        <TouchableOpacity onPress={() => AlarmService.snoozeAlarm(alarmId, snoozeMinutes)}>
+          <Text>Snooze {snoozeMinutes} min</Text>
+        </TouchableOpacity>
+      )}
       <TouchableOpacity onPress={() => AlarmService.stopAlarm(alarmId)}>
-        <Text>Stop</Text>
+        <Text>Dismiss</Text>
       </TouchableOpacity>
     </View>
   );
 }
 ```
 
-### Passing Custom Data
+> **Platform behaviour**
+> - **Android**: `componentProps` entries are flattened into the launch `Bundle` alongside standard fields (`alarmId`, `title`, etc.), and also available as a nested `componentProps` bundle. The `AlarmRingActivity` uses `componentName` to resolve which registered React root to display.
+> - **iOS**: `componentProps` (parsed from `componentPropsJSON`) is merged into the surface's initial properties passed to the React component.
+
+### Passing Custom Data (legacy approach)
 
 ```typescript
 await AlarmService.scheduleAlarm({

package/android/app/src/main/java/com/reactnativealarm/alarm/AlarmData.kt

@@ -3,6 +3,7 @@ package com.alarm
 import android.os.Bundle
 import com.facebook.react.bridge.Arguments
 import com.facebook.react.bridge.ReadableMap
+import com.facebook.react.bridge.WritableArray
 import com.facebook.react.bridge.WritableMap
 import org.json.JSONArray
 import org.json.JSONObject
@@ -21,8 +22,29 @@ data class AlarmData(
   val weekdays: List<Int>,
   val intervalMs: Long,
   val data: String,
-  var enabled: Boolean = true
+  var enabled: Boolean = true,
+  val componentName: String = "AlarmRing",
+  val componentPropsJSON: String = "{}"
 ) {
+  val componentProps: Map<String, Any>
+    get() {
+      return try {
+        val obj = JSONObject(componentPropsJSON)
+        val map = mutableMapOf<String, Any>()
+        val keys = obj.keys()
+        while (keys.hasNext()) {
+          val key = keys.next()
+          val value = obj.get(key)
+          if (value != JSONObject.NULL) {
+            map[key] = value
+          }
+        }
+        map
+      } catch (_: Exception) {
+        emptyMap()
+      }
+    }
+
   fun nextTrigger(from: Long = System.currentTimeMillis()): Long {
     if (!enabled) return 0
     return when (repeatType) {
@@ -59,6 +81,8 @@ data class AlarmData(
     put("snoozeMinutes", snoozeMinutes); put("repeatType", repeatType)
     put("weekdays", JSONArray(weekdays)); put("intervalMs", intervalMs)
     put("data", data); put("enabled", enabled)
+    put("componentName", componentName)
+    put("componentPropsJSON", componentPropsJSON)
   }.toString()
 
   fun toWritableMap(): WritableMap = Arguments.createMap().apply {
@@ -78,6 +102,13 @@ data class AlarmData(
     putString("data", data)
     putBoolean("enabled", enabled)
     putDouble("nextTriggerAt", nextTrigger().toDouble())
+    putString("componentName", componentName)
+    putString("componentPropsJSON", componentPropsJSON)
+    try {
+      putMap("componentProps", jsonToWritableMap(JSONObject(componentPropsJSON)))
+    } catch (_: Exception) {
+      putMap("componentProps", Arguments.createMap())
+    }
   }
 
   /** Initial props for the React ring screen hosted by [AlarmRingActivity]. */
@@ -89,19 +120,70 @@ data class AlarmData(
     putBoolean("snoozeEnabled", snoozeEnabled)
     putInt("snoozeMinutes", snoozeMinutes)
     putString("data", data)
+    putString("componentName", componentName)
+    putString("componentPropsJSON", componentPropsJSON)
+    try {
+      val propsObj = JSONObject(componentPropsJSON)
+      val propsBundle = jsonToBundle(propsObj)
+      putBundle("componentProps", propsBundle)
+      for (key in propsBundle.keySet()) {
+        if (!containsKey(key)) {
+          val v = propsBundle.get(key)
+          when (v) {
+            is String -> putString(key, v)
+            is Boolean -> putBoolean(key, v)
+            is Int -> putInt(key, v)
+            is Long -> putLong(key, v)
+            is Double -> putDouble(key, v)
+            is Bundle -> putBundle(key, v)
+          }
+        }
+      }
+    } catch (_: Exception) {}
+  }
+
+  private fun jsonToBundle(jsonObject: JSONObject): Bundle {
+    val bundle = Bundle()
+    val iter = jsonObject.keys()
+    while (iter.hasNext()) {
+      val key = iter.next()
+      when (val value = jsonObject.opt(key)) {
+        is JSONObject -> bundle.putBundle(key, jsonToBundle(value))
+        is JSONArray -> bundle.putString(key, value.toString())
+        is Boolean -> bundle.putBoolean(key, value)
+        is Int -> bundle.putInt(key, value)
+        is Long -> bundle.putLong(key, value)
+        is Double -> bundle.putDouble(key, value)
+        is String -> bundle.putString(key, value)
+        else -> if (value != null && value != JSONObject.NULL) {
+          bundle.putString(key, value.toString())
+        }
+      }
+    }
+    return bundle
   }
 
   companion object {
     fun fromJson(s: String): AlarmData {
       val o = JSONObject(s)
       val wd = o.optJSONArray("weekdays")
+      val compName = o.optString("componentName", "AlarmRing").trim()
       return AlarmData(
-        o.getString("id"), o.getLong("timestamp"), o.optString("title"), o.optString("body"),
-        o.optString("sound", "default"), o.optBoolean("vibrate", true),
-        o.optBoolean("snoozeEnabled", true), o.optInt("snoozeMinutes", 5),
-        o.optString("repeatType", "none"),
-        if (wd == null) emptyList() else (0 until wd.length()).map { wd.getInt(it) },
-        o.optLong("intervalMs", 0), o.optString("data"), o.optBoolean("enabled", true)
+        id = o.getString("id"),
+        timestamp = o.getLong("timestamp"),
+        title = o.optString("title"),
+        body = o.optString("body"),
+        sound = o.optString("sound", "default"),
+        vibrate = o.optBoolean("vibrate", true),
+        snoozeEnabled = o.optBoolean("snoozeEnabled", true),
+        snoozeMinutes = o.optInt("snoozeMinutes", 5),
+        repeatType = o.optString("repeatType", "none"),
+        weekdays = if (wd == null) emptyList() else (0 until wd.length()).map { wd.getInt(it) },
+        intervalMs = o.optLong("intervalMs", 0),
+        data = o.optString("data"),
+        enabled = o.optBoolean("enabled", true),
+        componentName = if (compName.isEmpty()) "AlarmRing" else compName,
+        componentPropsJSON = o.optString("componentPropsJSON", "{}").ifBlank { "{}" }
       )
     }
 
@@ -109,6 +191,24 @@ data class AlarmData(
       val r = if (m.hasKey("repeat") && !m.isNull("repeat")) m.getMap("repeat") else null
       val wd = r?.takeIf { it.hasKey("weekdays") }?.getArray("weekdays")
         ?.let { a -> (0 until a.size()).map { a.getInt(it) } } ?: emptyList()
+
+      val componentPropsStr = when {
+        m.hasKey("componentPropsJSON") && !m.isNull("componentPropsJSON") ->
+          m.getString("componentPropsJSON") ?: "{}"
+        m.hasKey("componentProps") && !m.isNull("componentProps") -> {
+          val propsMap = m.getMap("componentProps")
+          try {
+            val hashMap = propsMap?.toHashMap() ?: emptyMap<String, Any>()
+            JSONObject(hashMap).toString()
+          } catch (_: Exception) {
+            "{}"
+          }
+        }
+        else -> "{}"
+      }
+
+      val compName = m.str("componentName", "AlarmRing").trim()
+
       return AlarmData(
         id = id,
         timestamp = m.getDouble("timestamp").toLong(),
@@ -121,10 +221,56 @@ data class AlarmData(
         repeatType = r?.str("type", "none") ?: "none",
         weekdays = wd,
         intervalMs = if (r != null && r.hasKey("intervalMs")) r.getDouble("intervalMs").toLong() else 0,
-        data = m.str("data")
+        data = m.str("data"),
+        componentName = if (compName.isEmpty()) "AlarmRing" else compName,
+        componentPropsJSON = componentPropsStr
       )
     }
 
+    private fun jsonToWritableMap(jsonObject: JSONObject): WritableMap {
+      val map = Arguments.createMap()
+      val iter = jsonObject.keys()
+      while (iter.hasNext()) {
+        val key = iter.next()
+        when (val value = jsonObject.opt(key)) {
+          is JSONObject -> map.putMap(key, jsonToWritableMap(value))
+          is JSONArray -> map.putArray(key, jsonToWritableArray(value))
+          is Boolean -> map.putBoolean(key, value)
+          is Int -> map.putInt(key, value)
+          is Long -> map.putDouble(key, value.toDouble())
+          is Double -> map.putDouble(key, value)
+          is String -> map.putString(key, value)
+          else -> if (value == null || value == JSONObject.NULL) {
+            map.putNull(key)
+          } else {
+            map.putString(key, value.toString())
+          }
+        }
+      }
+      return map
+    }
+
+    private fun jsonToWritableArray(jsonArray: JSONArray): WritableArray {
+      val array = Arguments.createArray()
+      for (i in 0 until jsonArray.length()) {
+        when (val value = jsonArray.opt(i)) {
+          is JSONObject -> array.pushMap(jsonToWritableMap(value))
+          is JSONArray -> array.pushArray(jsonToWritableArray(value))
+          is Boolean -> array.pushBoolean(value)
+          is Int -> array.pushInt(value)
+          is Long -> array.pushDouble(value.toDouble())
+          is Double -> array.pushDouble(value)
+          is String -> array.pushString(value)
+          else -> if (value == null || value == JSONObject.NULL) {
+            array.pushNull()
+          } else {
+            array.pushString(value.toString())
+          }
+        }
+      }
+      return array
+    }
+
     private fun ReadableMap.str(k: String, d: String = "") =
       if (hasKey(k) && !isNull(k)) getString(k) ?: d else d
 

package/android/app/src/main/java/com/reactnativealarm/alarm/AlarmModule.kt

@@ -31,14 +31,14 @@ class AlarmModule(private val ctx: ReactApplicationContext) : ReactContextBaseJa
   private fun notificationsGranted(): Boolean =
     if (Build.VERSION.SDK_INT >= 33)
       ContextCompat.checkSelfPermission(ctx, Manifest.permission.POST_NOTIFICATIONS) ==
-        PackageManager.PERMISSION_GRANTED
+              PackageManager.PERMISSION_GRANTED
     else NotificationManagerCompat.from(ctx).areNotificationsEnabled()
 
   private fun canDrawOverlays(): Boolean = Settings.canDrawOverlays(ctx)
 
   private fun canUseFullScreenIntent(): Boolean =
     Build.VERSION.SDK_INT < 34 ||
-      ctx.getSystemService(NotificationManager::class.java).canUseFullScreenIntent()
+            ctx.getSystemService(NotificationManager::class.java).canUseFullScreenIntent()
 
   private fun permissionMap(): WritableMap = Arguments.createMap().apply {
     val ok = notificationsGranted()

package/android/app/src/main/java/com/reactnativealarm/alarm/AlarmRingActivity.kt

@@ -18,7 +18,8 @@ import java.lang.ref.WeakReference
  */
 class AlarmRingActivity : ReactActivity() {
 
-  override fun getMainComponentName(): String = COMPONENT_NAME
+  override fun getMainComponentName(): String =
+    AlarmService.current?.componentName?.takeIf { it.isNotBlank() } ?: COMPONENT_NAME
 
   override fun createReactActivityDelegate(): ReactActivityDelegate =
     object : DefaultReactActivityDelegate(this, mainComponentName, fabricEnabled) {
@@ -45,7 +46,7 @@ class AlarmRingActivity : ReactActivity() {
       @Suppress("DEPRECATION")
       window.addFlags(
         WindowManager.LayoutParams.FLAG_SHOW_WHEN_LOCKED or
-          WindowManager.LayoutParams.FLAG_TURN_SCREEN_ON
+                WindowManager.LayoutParams.FLAG_TURN_SCREEN_ON
       )
     }
     window.addFlags(WindowManager.LayoutParams.FLAG_KEEP_SCREEN_ON)

package/android/local.properties

@@ -0,0 +1,8 @@
+## This file must *NOT* be checked into Version Control Systems,
+# as it contains information specific to your local configuration.
+#
+# Location of the SDK. This is only used by Gradle.
+# For customization when using a Version Control System, please read the
+# header note.
+#Fri Oct 23 16:38:30 IST 2026
+sdk.dir=/Users/apple/Library/Android/sdk

package/index.d.ts

@@ -8,13 +8,13 @@ import type { Spec } from './specs/NativeAlarm';
 export type {
   AlarmRepeat,
   AlarmConfig,
-  Alarm,
+  AlarmProp,
   AlarmPermission,
   AlarmEvent,
-  Spec as AlarmModuleSpec,
-} from './specs/NativeAlarm';
+} from './src/types';
 
 export { AlarmService } from './AlarmService';
 
 declare const Alarm: Spec;
+
 export default Alarm;

package/index.ts

@@ -8,13 +8,13 @@
 export type {
   AlarmRepeat,
   AlarmConfig,
-  Alarm,
+  AlarmProp,
   AlarmPermission,
   AlarmEvent,
-  Spec as AlarmModuleSpec,
-} from './specs/NativeAlarm';
+} from './src/types';
 
 export { AlarmService } from './AlarmService';
 
-import NativeAlarm from './specs/NativeAlarm';
-export default NativeAlarm;
+import Alarm from './specs/NativeAlarm';
+
+export default Alarm;

package/ios/alarm/AlarmData.swift

@@ -16,11 +16,25 @@ struct AlarmData: Codable {
   var intervalMs: Double
   var data: String
   var enabled: Bool = true
-
+  var componentName: String = "AlarmRing"
+  var componentPropsJSON: String = "{}"
+  
   static func now() -> Double { Date().timeIntervalSince1970 * 1000 }
-
+  
   var date: Date { Date(timeIntervalSince1970: timestamp / 1000) }
 
+   var componentProps: [String: Any] {
+        guard
+            let jsonData = componentPropsJSON.data(using: .utf8),
+            let object = try? JSONSerialization.jsonObject(with: jsonData),
+            let props = object as? [String: Any]
+        else {
+            return [:]
+        }
+
+        return props
+    }
+  
   /// Next time this alarm should ring, in ms since epoch, or 0 if never.
   func nextTrigger(from: Double = AlarmData.now()) -> Double {
     if !enabled { return 0 }
@@ -37,7 +51,7 @@ struct AlarmData: Codable {
       return timestamp > from ? timestamp : 0
     }
   }
-
+  
   private func nextMatching(from: Double, ok: (Int) -> Bool) -> Double {
     let cal = Calendar.current
     let base = cal.dateComponents([.hour, .minute], from: date)
@@ -55,9 +69,9 @@ struct AlarmData: Codable {
     }
     return 0
   }
-
+  
   // MARK: - JS bridge shape (same keys as Android)
-
+  
   func toDictionary() -> [String: Any] {
     [
       "alarmId": id,
@@ -74,7 +88,7 @@ struct AlarmData: Codable {
       "nextTriggerAt": nextTrigger(),
     ]
   }
-
+  
   /// Parses the `AlarmConfig` object JS passes to `scheduleAlarm` / `updateAlarm`.
   static func from(config m: [String: Any], id: String) -> AlarmData {
     let r = m["repeat"] as? [String: Any]